Files
archie/docs/development/state-store.md
T
sam d6e769ab4c feat(egress): intercept OAuth token endpoints and inject stored access tokens
The egress proxy now holds a Kit's OAuth tokens on the host. A refresh
carrying the sentinel refresh token goes upstream with the org's stored
one; a successful response is written to the State Store and returned to
the container with sentinels only. Requests to the Kit's resource hosts
carrying the sentinel access token get the stored one.

The org's token set is read or written only for a run whose credential
carries the service, so a Kit declaring a service never reaches the org
secret by itself. The launcher grants a bound OAuth service without a
config secret, and Register refuses a required OAuth credential when no
harness secret store is wired. A provider that does not rotate refresh
tokens keeps the stored one.

Part of archie-core-egkf.7 (#1208). Credential-file rendering and
per-binding concurrency remain.
2026-09-28 01:52:07 +10:00

66 lines
3.2 KiB
Markdown

# State Store
Authority: `docs/prds/state-store-contract.md` and the State Store section of
`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store
process; nothing else opens the database.
## Adding a column
1. Write the next migration in `internal/infrastructure/postgres/migrations/`
(`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`
that is correct for existing rows.
2. Update the queries in `internal/infrastructure/postgres/queries/` and
regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the
binding selects) does not pick the new one up; `SELECT *` queries do.
3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the
column holds encoded data, the package that owns the type owns the encoding
(`task.EncodeInputs`), and the store and the wire both use it.
4. Carry it over the wire (next section) if any process other than the State
Store reads it.
## Adding a field to a wire message
1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse
a number; retire one with `deprecated = true`.
2. `task proto:generate`, then map it both ways in
`internal/infrastructure/staterpc/values.go`.
3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and
fails on one the mapping forgets. If it cannot fill the field's kind, extend
it. Other messages have no such test, so add a round trip to
`conformance_test.go`.
## Adding an RPC or a store method
1. Put the Go method on the narrow consumer interface in
`internal/domain/storecontract` (keep each at eight methods or fewer) and add
the matching RPC. A Go method without an RPC does not cross the process.
2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`
assertion) and in `staterpc.server`. A missing dependency answers
`codes.Unavailable`, never a fabricated default.
3. Wire the dependency in every composition that serves or consumes it:
`stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's
assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the
dashboard process.
4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on
their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is
added there deliberately.
5. Add it to `conformance_test.go`, which runs every surface over a real gRPC
connection.
## Adding an error sentinel
Add the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and
a case to `error_test.go`. The canonical message is part of the wire contract:
changing it breaks `errors.Is` on the client silently.
## Harness OAuth secrets
`HarnessSecretStore` stores token sets by org and credential service through
admin-only State Store RPCs. The EDA store seals them with the binding cipher's
keyring and a separate `HarnessSecretDomain`. OAuth writes require a configured
binding encryption key; the legacy binding plaintext fallback does not apply.
The daemon's egress proxy (`internal/infrastructure/egress/oauth.go`) is the
only daemon consumer: for a run granted the service it swaps sentinels for the
stored tokens and writes every refresh back. The setup terminal is a separate
harness slice.