okengine 0.15.2 → 0.17.0

package/site/content/docs/reference/client.mdx

@@ -172,7 +172,7 @@ const { data } = await api.auth.signInEmail({ email, password });
 if (data) session.set(data);
 ```
 
-React: `useSession(api, session)` from `okengine/client-react`.
+React: `useSession(api, session)` and `useLive(api, signal, input?)` from `okengine/client-react`.
 
 | Step                   | What happens                                                     |
 | ---------------------- | ---------------------------------------------------------------- |
@@ -180,6 +180,9 @@ React: `useSession(api, session)` from `okengine/client-react`.
 | HTTP **401**           | `refresh()` runs **once**, then the same call retries            |
 | HTTP **403** / **429** | No refresh — decode the failure envelope as usual                |
 
+`getToken` may return a session access token or an API key secret — both are Bearer.
+See [Gate](/docs/elements/gate#api-keys). `refresh` applies to sessions only.
+
 **Consequence:** `refresh` must mutate whatever `getToken` reads. Returning a new string alone does
 nothing if storage was not updated.
 
@@ -201,6 +204,7 @@ A 401 with no `{ data, error }` body becomes `TransportError` with `data.status:
 | `memorySession`             | `okengine/client/auth`  | In-memory access/refresh bag for `auth.getToken` |
 | `AUTH_ERROR_CODES`          | `okengine/client/auth`  | Common auth Flow / gate codes                    |
 | `useSession(api, session?)` | `okengine/client-react` | React status + `auth.me`                         |
+| `useLive(api, signal, …)`   | `okengine/client-react` | React `events` / `latest` / `isConnected`        |
 
 Core `okengine/client` stays under the size budget — helpers are separate exports. Not in
 core today: cookie jars or plugin `.client()` decorations. Browser apps: also see
@@ -218,7 +222,7 @@ core today: cookie jars or plugin `.client()` decorations. Browser apps: also se
 | [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                           |
 | [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`                 |
 | [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows on `$routes` |
-| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                        |
+| [Signal](/docs/elements/signal)   | Live SSE      | `api.live(signal, input?, { onEvent })` — HTTP GET, callback + unsubscribe                 |
 | [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                              |
 | [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                           |
 | [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                              |
@@ -230,7 +234,7 @@ Mount a resource, adopt the returned ops, then call the five Flows like any othe
 
 ```typescript
 const notesR = store.resource(db, notes, {/* in, out, list */});
-const mounted = on(http.resource("/notes", notesR.all()).public().live());
+const mounted = on(http.resource("/notes", notesR.all()).public());
 // .adopt({ notes: mounted }) →
 const page = await api.notes.list({ limit: 20 });
 const more = await page.next();
@@ -256,24 +260,63 @@ See [Store](/docs/elements/store) for the list query language and schemas. Handw
 `fx.json.withQuery(rows, input)` for the same envelope. Auth posture for HTTP triggers is
 covered under [Gate](/docs/elements/gate).
 
-### Signal and live queries
+### Live signals
+
+`delivery: "live"` is HTTP SSE. Expose with `.live(signal)` on GET (or `http.live(signal)` for
+`GET /_oke/live/{name}`), then subscribe with a callback. `for await` stays on the server.
+
+```typescript
+const stop = api.live(
+  orderStatus,
+  { orderId: "ord_1" },
+  {
+    onEvent: (event) => {
+      /* event: { orderId, status } */
+    },
+    onError: (err) => {
+      /* optional — 4xx, envelope, network drop */
+    },
+    autoResubscribe: false, // default — true reopens after a drop (500ms…30s backoff)
+  },
+);
+stop(); // useEffect cleanup
+```
 
-`delivery: "live"` and `http.get(…).live()` are Manifest / driver flags today. `okengine/client`
-does **not** expose WebSocket, SSE, or `api.*.subscribe`. Until that ships, poll or call an HTTP
-Flow that returns the current state.
+`api.orders.events({ orderId }, { onEvent })` is the same shape on the exposing flow.
+
+The client picks the unique exposure whose `matchKey` fields are a subset of the input, preferring
+the largest match (`{ orderId }` beats firehose). A tie needs `via: "unit.flow"`.
+
+Reconnects send `Last-Event-ID` from the last `id:` the client actually received.
+
+A **410** `LiveResumeGap` (**OKE1014**) means that cursor is gone — `onError` fires, the
+cursor is dropped, and `autoResubscribe` replays the remaining tape after backoff.
+
+```typescript
+import { useLive } from "okengine/client-react";
+
+const { events, latest, error, isConnected } = useLive(
+  api,
+  orderStatus,
+  { orderId: "ord_1" },
+  {
+    autoResubscribe: true,
+  },
+);
+```
 
 ## Exports
 
-| Export                                    | Kind      | Role                                               |
-| ----------------------------------------- | --------- | -------------------------------------------------- |
-| `createClient`                            | function  | Typed proxy `api.unit.flow(input?)`                |
-| `flattenRoutes`                           | function  | `$routes` → flat `unit.flow` REST table            |
-| `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)  |
-| `isOk` / `isFail`                         | function  | Envelope predicates                                |
-| `isErrorCode` / `isTransportError`        | function  | Error narrowing                                    |
-| `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()` |
-| `Register`                                | interface | Module-augmentation slot for ambient App types     |
-| `AppOf`                                   | type      | Brand a bare route map as an App                   |
+| Export                                    | Kind      | Role                                                |
+| ----------------------------------------- | --------- | --------------------------------------------------- |
+| `createClient`                            | function  | Typed proxy `api.unit.flow(input?)` plus `api.live` |
+| `flattenRoutes`                           | function  | `$routes` → flat `unit.flow` REST table             |
+| `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)   |
+| `isOk` / `isFail`                         | function  | Envelope predicates                                 |
+| `isErrorCode` / `isTransportError`        | function  | Error narrowing                                     |
+| `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()`  |
+| `Register`                                | interface | Module-augmentation slot for ambient App types      |
+| `AppOf`                                   | type      | Brand a bare route map as an App                    |
 
 Budget: the `./client` export stays under the measured client-runtime cap (hard gate in CI).
 
@@ -320,6 +363,20 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 
 </Accordion>
 
+<Accordion title="api.live throws Multiple live exposures">
+
+Two routes share the same match shape. Pass `via: "unit.flow"` or call the exposing flow
+(`api.orders.events(input, { onEvent })`).
+
+</Accordion>
+
+<Accordion title="onError sees LiveResumeGap / HTTP 410">
+
+The last `id:` is not on the server tape. The client drops the cursor. With `autoResubscribe: true`
+the next request omits `Last-Event-ID` and replays what remains.
+
+</Accordion>
+
 </Accordions>
 
 ## Learn more
@@ -329,6 +386,7 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 - [Gate](/docs/elements/gate) — policies, `gate.public`, denials
 - [Store](/docs/elements/store) — `store.resource` and list query language
 - [Flow](/docs/elements/flow) — `in` / `out` / `errors` and `fx.fail`
+- [Signal](/docs/elements/signal) — `api.live` for `delivery: "live"` SSE
 - [Errors](/docs/reference/errors) — framework codes vs failure values
 - [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) — browser callers
 - [CLI Reference](/docs/reference/cli) — `oke client add`, `oke dev`

package/site/content/docs/reference/configuration.mdx

@@ -181,10 +181,13 @@ i18n: { locales: ["en"], default: "en" },
 
 ## tenancy
 
-| Option      | Type                              | Meaning                                  |
-| ----------- | --------------------------------- | ---------------------------------------- |
-| `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store   |
-| `resolve`   | string \| function                | Tenant resolver — reads `ctx.auth.orgId` |
+`oke.config.ts` `tenancy` is **isolation posture** (how rows are separated). Identity —
+who the tenant is — is `gate.auth.tenant` on [Gate](/docs/elements/gate#tenants-identity-dimension).
+
+| Option      | Type                              | Meaning                                           |
+| ----------- | --------------------------------- | ------------------------------------------------- |
+| `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store            |
+| `resolve`   | string \| function                | Observational resolver (isolation-only manifests) |
 
 ## privacy
 

package/site/content/docs/reference/errors.mdx

@@ -29,18 +29,25 @@ string. Custom app codes stay message-less until registered.
 
 ## OKE numeric codes
 
-| Code   | Name              | Cause                                           | Fix                                                |
-| ------ | ----------------- | ----------------------------------------------- | -------------------------------------------------- |
-| `1001` | undeclared read   | Flow reads a resource not in `effects.reads`    | Add it to the flow's `effects.reads`               |
-| `1002` | undeclared write  | Flow writes a resource not in `effects.writes`  | Add it to the flow's `effects.writes`              |
-| `1003` | undeclared emit   | Flow emits a signal not in `effects.emits`      | Add it to the flow's `effects.emits`               |
-| `1004` | undeclared send   | Flow sends a template not in `effects.sends`    | Add it to the flow's `effects.sends`               |
-| `1005` | undeclared ask    | Flow asks a prompt not in `effects.asks`        | Add it to the flow's `effects.asks`                |
-| `1006` | undeclared secret | Flow reads a secret not in `effects.secrets`    | Add it to the flow's `effects.secrets`             |
-| `1007` | undeclared call   | Flow calls a flow not in `effects.calls`        | Add it to the flow's `effects.calls`               |
-| `1042` | orphan emit       | Emit with zero subscribers and `optional` false | Add `on(signal, …)` or declare `optional: true`    |
-| `1043` | signal schema     | Emit payload failed the signal's `schema`       | Pass a payload that matches `schema`, or remove it |
-| `1101` | schema missing    | Domain table absent in `prod` — no auto-DDL     | Run `oke db migrate` against this environment      |
+| Code   | Name                 | Cause                                             | Fix                                                  |
+| ------ | -------------------- | ------------------------------------------------- | ---------------------------------------------------- |
+| `1001` | undeclared read      | Flow reads a resource not in `effects.reads`      | Add it to the flow's `effects.reads`                 |
+| `1002` | undeclared write     | Flow writes a resource not in `effects.writes`    | Add it to the flow's `effects.writes`                |
+| `1003` | undeclared emit      | Flow emits a signal not in `effects.emits`        | Add it to the flow's `effects.emits`                 |
+| `1004` | undeclared send      | Flow sends a template not in `effects.sends`      | Add it to the flow's `effects.sends`                 |
+| `1005` | undeclared ask       | Flow asks a prompt not in `effects.asks`          | Add it to the flow's `effects.asks`                  |
+| `1006` | undeclared secret    | Flow reads a secret not in `effects.secrets`      | Add it to the flow's `effects.secrets`               |
+| `1007` | undeclared call      | Flow calls a flow not in `effects.calls`          | Add it to the flow's `effects.calls`                 |
+| `1011` | HTTP route clash     | Two HTTP flows share the same method + path       | Give each flow a unique method + path                |
+| `1012` | HTTP flow unnamed    | Adopted HTTP flow still has no `unit.export`      | Export from `flows/<unit>/` or pass a named `flow`   |
+| `1013` | live exposure dup    | Same signal, gates, and match on two GET routes   | Change the gate or path-param filter                 |
+| `1014` | live resume gap      | `Last-Event-ID` is not on the retained tape       | Reconnect without the cursor; remaining tape replays |
+| `1015` | tenant required      | Tenant-scoped op with no `fx.tenant.id`           | `switchTenant`, signed `tid`, or tenant header       |
+| `1016` | tenant not member    | Client-supplied tenant id is not a membership     | Pick from `listTenants` or add the user as a member  |
+| `1017` | tenant unknown scope | Tenant role used an invented or `console:*` scope | Use a declared application scope                     |
+| `1042` | orphan emit          | Emit with zero subscribers and `optional` false   | Add `on(signal, …)` or declare `optional: true`      |
+| `1043` | signal schema        | Emit payload failed the signal's `schema`         | Pass a payload that matches `schema`, or remove it   |
+| `1101` | schema missing       | Domain table absent in `prod` — no auto-DDL       | Run `oke db migrate` against this environment        |
 
 <Callout title="Effects are usually inferred">
   The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an
@@ -52,11 +59,11 @@ string. Custom app codes stay message-less until registered.
 
 Returned, not thrown — the request never reached `do`:
 
-| Code           | When                                         | Payload          |
-| -------------- | -------------------------------------------- | ---------------- |
-| `Unauthorized` | Policy denied, request not authenticated     | —                |
-| `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` |
-| `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`   |
+| Code           | When                                         | Payload                                                                                    |
+| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `Unauthorized` | Policy denied, request not authenticated     | —                                                                                          |
+| `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` (`tenant_required` · `not_member` · `unknown_scope` · `session_only` · …) |
+| `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`                                                                             |
 
 ## Framework validation failures
 

package/site/content/docs/reference/fx.mdx

@@ -14,11 +14,16 @@ flow("orders.example", {
 });
 ```
 
+<Callout title="Extracted helpers">
+  Type a helper's `fx` parameter as `Fx` (`import type {Fx} from "okengine"`). A narrower structural
+  type will not match `store()` overloads. See [Flow](/docs/elements/flow).
+</Callout>
+
 ## Stores
 
 | Signature                                                           | Records      | Returns                                                                                     |
 | ------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
-| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | rows (`where` · `orderBy` · `limit` · `offset` chainable)                                   |
+| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | inferred rows (`where` · `orderBy` · `limit` · `offset` chainable)                          |
 | `fx.store(sqlDecl).insert(t).values(v)`                             | `write`      | `Promise<void>`                                                                             |
 | `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`      | `Promise<void>`                                                                             |
 | `fx.store(sqlDecl).delete(t).where(…)`                              | `write`      | `Promise<void>`                                                                             |
@@ -37,6 +42,7 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
 | `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                               |
+| `fx.live(signal, { match? })`         | `read` `signal:<name>` | Live tape as SSE. Returns `JsonStreamResult` (object chunks, `id:` on the wire). Cross-signal throws **OKE1001**. Do not wrap with `fx.json.stream`.                                                      |
 
 ## Runs (observability read)
 
@@ -72,20 +78,29 @@ on(
 
 ## Flows
 
-| Signature                    | Records | Returns / notes                                       |
-| ---------------------------- | ------- | ----------------------------------------------------- |
-| `fx.call(flow, input?)`      | `call`  | The callee's `out` — runs through the same pipeline   |
-| `fx.step(name, fn)`          | —       | Durable step: replays from the journal, never re-runs |
-| `fx.all([...thunks])`        | —       | Parallel; first rejection aborts siblings             |
-| `fx.race([...thunks])`       | —       | First settle wins; losers aborted                     |
-| `fx.retry(fn, opts?)`        | —       | Exponential backoff + jitter (plain Promise)          |
-| `fx.using(acq, rel, use)`    | —       | `release` runs once on settle or ambient abort        |
-| `fx.signal`                  | —       | Ambient `AbortSignal` for the current branch          |
-| `fx.fail(code, data, opts?)` | —       | Typed failure value (`opts.message` overrides)        |
-
-`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization). For
-audit/attribution only, read `fx.principal` — it propagates the originating identity without
-copying into `fx.auth`. Gates never consult `fx.principal`.
+| Signature                                                                      | Records                 | Returns / notes                                                                                    |
+| ------------------------------------------------------------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `fx.call(flow, input?)`                                                        | `call`                  | The callee's `out` — runs through the same pipeline                                                |
+| `fx.step(name, fn)`                                                            | —                       | Durable step: replays from the journal, never re-runs                                              |
+| `fx.all([...thunks])`                                                          | —                       | Parallel; first rejection aborts siblings                                                          |
+| `fx.race([...thunks])`                                                         | —                       | First settle wins; losers aborted                                                                  |
+| `fx.retry(fn, opts?)`                                                          | —                       | Exponential backoff + jitter (plain Promise)                                                       |
+| `fx.using(acq, rel, use)`                                                      | —                       | `release` runs once on settle or ambient abort                                                     |
+| `fx.signal`                                                                    | —                       | Ambient `AbortSignal` for the current branch                                                       |
+| `fx.fail(code, data, opts?)`                                                   | —                       | Typed failure value (`opts.message` overrides)                                                     |
+| `fx.auth.createApiKey({ name, scopes, expiresIn?, ipAllowlist?, rateLimit? })` | `write` `auth:api-keys` | Secret once. Creator is live `userId` / `scopes`. Session only. `ipAllowlist` is IPs or hostnames. |
+| `fx.auth.listApiKeys()`                                                        | `read` `auth:api-keys`  | Keys this session minted                                                                           |
+| `fx.auth.revokeApiKey(id)`                                                     | `write` `auth:api-keys` | Owner only                                                                                         |
+| `fx.auth.rotateApiKey(id)`                                                     | `write` `auth:api-keys` | New secret once. Owner only                                                                        |
+| `fx.auth.updateApiKey(id, …)`                                                  | `write` `auth:api-keys` | Name / scopes / expiry / allowlist / rate. Re-attenuates                                           |
+| `fx.auth.listTenants()`                                                        | `read` `auth:tenants`   | Memberships for the live session. Session only                                                     |
+| `fx.auth.switchTenant(id)`                                                     | `write` `auth:tenants`  | New access+refresh, new family, `tid` on both. Never Set-Cookie. Session only                      |
+| `fx.auth.createTenant({ name, slug?, id? })`                                   | `write` `auth:tenants`  | Creator becomes a member. Session only                                                             |
+| `fx.auth.upsertTenantRole({ tenantId, roleName, scopes })`                     | `write` `auth:tenants`  | Application scopes only — `console:*` is unknown_scope                                             |
+
+`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization) and
+propagates `fx.tenant.id`. For audit/attribution only, read `fx.principal` — it propagates the
+originating identity without copying into `fx.auth`. Gates never consult `fx.principal`.
 
 ## Concurrency and retry
 
@@ -204,6 +219,7 @@ keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
 | `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager            |
 | `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST    |
 | `fx.json.stream(chunks)`                  | 200    | `text/event-stream` — JSON `data:` frames, then `data: [DONE]` |
+| `fx.live(signal)`                         | 200    | Same SSE carrier for a live signal (payload frames + `id:`)    |
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control. Pass `fx.stream(...)` into `fx.json.stream` to reach the HTTP client token-by-token.
 
@@ -265,15 +281,16 @@ Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
 
 ## Principals
 
-| Property       | Shape                                                                     |
-| -------------- | ------------------------------------------------------------------------- |
-| `fx.auth`      | `{ userId: string \| null, scopes: Set<string>, verified?: boolean }`     |
-| `fx.operator`  | `{ id: string \| null }` — Console plane                                  |
-| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?` |
-| `fx.tenant`    | `{ id: string \| null }` — active tenant                                  |
+| Property       | Shape                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `fx.auth`      | `{ userId, scopes, verified?, apiKeyId? }` plus key and tenant methods (session only) |
+| `fx.operator`  | `{ id: string \| null }` — Console plane                                              |
+| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?`             |
+| `fx.tenant`    | `{ id: string \| null }` — active tenant (propagates on `fx.call`)                    |
 
 **Consequence:** use `fx.auth` / gates for authorization; use `fx.principal` only when a callee
-must log who started the call chain.
+must log who started the call chain. A key Bearer sets `userId` to the issuer and `apiKeyId`
+to the key — see [Gate](/docs/elements/gate#api-keys).
 
 ## Not on `fx`
 

package/site/content/docs/reference/security.md

@@ -47,7 +47,7 @@ Our path is concrete: a booking name containing "ignore previous instructions an
 - **Store KV performance** (`QUERY /console/store/kv/stats`) is Redis-wire `INFO` / `COMMANDSTATS` / `SLOWLOG` / `LATENCY` — not Store browse. INFO is instance-wide (`StoreKvStatsServerWideGap`). SLOWLOG args are keys and values — collapsed until `revealPii: true`, which writes `console.store.kv.stats.reveal` (operator, ref). Named limitation `StoreKvStatsSlowlogArgsGap`. `memory` returns `KvStatsUnsupported`. This surface does not run `MONITOR` and does not invent a hot-key table.
 - **Runs SQL** (`POST /console/runs/query`, Observability SQL tab) is operator-session, read-only, 5s timeout, 1000-row cap. DuckDB filesystem access is disabled for the statement. Masking is column-key only (`dim_*` and JSON blobs `input` / `output` / `logs` / `dimensions`). Aliases and expressions can leak classified values — named limitation `RunsQueryPiiProjectionGap`. This is **not** the `projectRun` guarantee. `revealPii: true` writes `console.runs.query.reveal`. Flow `fx.runs.query` stays unrestricted app SQL.
 - **Plugin panels** run in a sandboxed iframe without `allow-same-origin`, communicating only over a `postMessage` bridge with their own CSP, no access to the operator session token, and exposure limited to that plugin's declared flows.
-- **Session and framing:** `frame-ancestors 'none'`, `SameSite=Strict`, step-up authentication before destructive actions. An expired operator session redirects to Sign in with `?next=` set to the current `/overview`, `/flows`, `/store`, `/vault`, or `/observability` href (search included); after login the operator returns there. `/monitoring` is rewritten to `/observability`. Any other `next` (including `/units`) is dropped so the gate cannot be used as an open redirect. Unknown Console paths are 404.
+- **Session and framing:** `frame-ancestors 'none'`, `SameSite=Strict`, step-up authentication before destructive actions. An expired operator session redirects to Sign in with `?next=` set to the current `/overview`, `/flows`, `/store`, `/vault`, `/access`, or `/observability` href (search included); after login the operator returns there. `/monitoring` is rewritten to `/observability`. Any other `next` (including `/units`) is dropped so the gate cannot be used as an open redirect. Unknown Console paths are 404.
 - **Secret write path:** TLS required, no autocomplete, never echoed, never logged, not retained in browser memory after submission. Vault set / rotate / rotate-master use typed confirm (`SET` / `ROTATE` / `ROTATE_MASTER`). The Console never accepts a master key in the HTTP body (`OKE_VAULT_MASTER_KEY` only). `GET /console/vault/audit/verify` is read-only (no typed phrase).
 - **The setup claim code** is rate-limited and compared in constant time. It is
   printed on the `oke dev` board (TTY only — never on `GET /console/setup/status`)

package/src/auth/api-key-sql.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { createApiKey, createApiKeyStore } from "./api-keys.ts";
+import { bindApiKeySqlPersist, hydrateApiKeyStore, type ApiKeySqlExec } from "./api-key-sql.ts";
+
+describe("api-key SQL persist", () => {
+  test("hydrate + persist round-trip", async () => {
+    const rows = new Map<string, Record<string, unknown>>();
+    const sql: ApiKeySqlExec = {
+      async execute(_q, params) {
+        const id = String(params[0]);
+        rows.set(id, {
+          id,
+          plane: params[1],
+          hash: params[2],
+          name: params[3],
+          scopes: params[4],
+          expires_at: params[5],
+          rate_limit: params[6],
+          ip_allowlist: params[7],
+          creator_id: params[8],
+          creator_scopes: params[9],
+          created_at: params[10],
+          last_used_at: params[11],
+          revoked_at: params[12],
+        });
+      },
+      async all() {
+        return [...rows.values()];
+      },
+    };
+    const store = createApiKeyStore();
+    bindApiKeySqlPersist(store, sql);
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "sql",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_sql",
+    });
+    const other = createApiKeyStore();
+    await hydrateApiKeyStore(sql, other);
+    expect(other.keys.get("key_sql")?.name).toBe("sql");
+    expect(other.keys.get("key_sql")?.creatorId).toBe("u1");
+    expect(other.keys.get("key_sql")?.hash).toBe(created.row.hash);
+  });
+});