okengine 0.15.2 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

package/site/content/docs/elements/flow.mdx

@@ -104,6 +104,12 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
   [Store](/docs/elements/store#handwritten-http-lists).
 </Callout>
 
+<Callout title="Helpers take the real Fx">
+  Type a helper's `fx` as the exported `Fx` (`import type { Fx } from
+  "okengine"`). A narrower `{ store: … }` will not match `store()` overloads
+  — that is the `as never` trap. See [fx](/docs/reference/fx).
+</Callout>
+
 ## The five triggers
 
 <FlowTriggers />

package/site/content/docs/elements/gate.mdx

@@ -256,6 +256,38 @@ Customize tables, then `oke schema generate` (`.oke/schema/oke.ts`; `--check` in
 sign-in shapes: [Plugins](/docs/plugins). Call auth from
 [createClient](/docs/reference/client) — helpers in `okengine/client/auth`.
 
+## API keys
+
+A key is the **issuer with fewer gates** — not a second permission system.
+Bearer secrets authenticate as the creator; `fx.auth.scopes` shrink to the key.
+
+| Field                               | Session        | API key                 |
+| ----------------------------------- | -------------- | ----------------------- |
+| `fx.auth.userId` / `fx.operator.id` | subject        | creator (`creatorId`)   |
+| `fx.auth.scopes`                    | session scopes | key scopes (attenuated) |
+| `fx.auth.apiKeyId`                  | `null`         | key id                  |
+| WideEvent `principal`               | subject        | issuer                  |
+| `dimensions.api_key`                | absent         | key id                  |
+
+`gate.auth` always creates a shared key store (HMAC-SHA-256 with `gate.auth.secret`).
+Do not pass `apiKeyStore` unless you are injecting a test Map.
+
+<Callout title="Keys live on the app database">
+  With `store.sql()`, boot hydrates public `oke_api_keys` on that connection (`DATABASE_URL`) and
+  write-through persists create / rotate / revoke. Console **Access** attaches this host store — it
+  does not keep a second key database.
+</Callout>
+
+Session Flows manage keys via [fx](/docs/reference/fx) (`createApiKey`, `listApiKeys`,
+`revokeApiKey`, `rotateApiKey`, `updateApiKey`). A key-authenticated caller cannot.
+
+Declare `effects.reads: ["auth:api-keys"]` / `effects.writes: ["auth:api-keys"]` — never
+`sql:oke_api_keys`. Console **Access** (`:6533` → `/access`) mints operator keys as the
+operator, and user-plane keys only as a picked issuer (`creatorUserId`).
+
+Verify rejects expired, revoked, allowlist-miss, and over-rate secrets with `401`
+and no `api_key` dimension.
+
 ## Identity and decisions
 
 Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
@@ -310,6 +342,29 @@ character classes.
 `"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
 Keying an authenticated endpoint by IP punishes shared NAT.
 
+</Accordion>
+<Accordion title="API key Bearer returns 401">
+
+Expired, revoked, allowlist miss, or over the key's `rateLimit`. Check
+`ipAllowlist` against the same X-Forwarded-For hop as `ip-allowlist`.
+Entries are IPs or hostnames — a host resolves at verify time and must
+include the client IP (lookup failure is closed). Rotate if the secret
+was shown once and then lost.
+
+</Accordion>
+<Accordion title="Keys vanish after an app restart">
+
+No SQL store, or a new `gate.auth.secret`. Declare `store.sql()`, keep
+`DATABASE_URL` (or the same PGlite datadir) and the auth secret stable.
+Console does not persist keys in `oke_console`.
+
+</Accordion>
+<Accordion title="Key can call a route the issuer cannot">
+
+That is a bug in the mint. `createApiKey` / `fx.auth.createApiKey` re-run
+`assertAttenuated` against the issuer's live scopes. Custom `gate.policy`
+predicates that ignore scopes still see `verified: true`.
+
 </Accordion>
 </Accordions>
 

package/site/content/docs/elements/store.mdx

@@ -91,22 +91,17 @@ Install reviews the `CREATE EXTENSION` SQL; **Advanced** can set `SCHEMA`,
 When a newer packaged version exists, the name chip shows **Upgrade**
 (`ALTER EXTENSION … UPDATE`). Names link to the project or Postgres docs.
 
-Each SQL table row shows whether Postgres RLS is on (emerald shield)
-or off (muted shield). The resource header repeats that as an **RLS**
-chip before **PII** — **N RLS** when enabled and policies exist. KV,
-files, and index have no badge. Enabling RLS on create flips that
-shield.
-
-**RLS Policies** lists `pg_policies` plus Manifest policies (`declared` /
-`live`). Two-finger click a row to open its sheet (Edit / Save on editable
-columns); two-finger click empty grid to create. Create policy pins
-SQL | Code (`store.schema.policy` + `pgPolicy`); drag the handle to
-resize the preview.
+SQL table rows and the resource header show RLS (emerald / muted shield;
+**N RLS** when policies exist) before **PII**. KV, files, and index have
+no badge — enabling RLS on create flips the shield.
+
+**RLS Policies** lists `pg_policies` plus Manifest `declared` / `live`.
+Two-finger click a row for its sheet, or empty grid to create. Create
+pins SQL | Code (`store.schema.policy` + `pgPolicy`); drag to resize.
+
 **Templates** use `oke.user()` / `oke.gate()` / `oke.has_scope()`.
-Owner cards open a **Column** select of the table fields (guessed
-`creator_email` / `owner_email` when present) with the same PK / FK
-marks as schema cards. Create stays blocked until a real column is
-picked.
+Owner cards pick a **Column** (guess `creator_email` / `owner_email`)
+with PK / FK marks. Create stays blocked until a column is picked.
 
 Create policy picks a Gate posture (Read / Write / Both), or **Policy &
 scope**. Those picks fill `USING` / `WITH CHECK`. `TO` stays `public` —
@@ -296,6 +291,9 @@ await fx.store(db).update(notes).set({ title: input.title }).where(eq(notes.id,
 await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 ```
 
+`select().from(notes)` infers the declared row (`string` / `number` / `null` from
+`field.*`). A `select({ title: notes.title })` projection stays untyped.
+
 <Callout title="One table per call — no relational with:">
   `fx.store` is deliberately **single-table**: Drizzle's relational `findMany({ with: … })` is not
   available through `fx`. Compose joins as separate single-table reads (or `fx.call`) so every

package/site/content/docs/elements/vault.mdx

@@ -201,6 +201,9 @@ The **Console** (`:6533`) **Vault** page (`/vault`) groups **Secrets** and
 **Config**. Secrets are write-only: a salted fingerprint (`sha256:…`), never
 the cleartext. Config rows show the value — that is `vault.config()`.
 
+API keys are principals — mint them on **Access** (`/access`), not Vault.
+See [Gate](/docs/elements/gate#api-keys).
+
 Add (`+`) creates a contract from Console as well as from source. Those rows
 show `console` until you declare the same name in the Manifest.
 

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

@@ -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.
 

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>`                                                                             |
@@ -72,16 +77,21 @@ 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)        |
+| 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.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
@@ -265,15 +275,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 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                                   |
 
 **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);
+  });
+});

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

@@ -0,0 +1,254 @@
+/**
+ * SQL persist / hydrate for {@link ApiKeyRow} on `oke_api_keys`.
+ *
+ * Host path: public schema on the app `store.sql()` connection
+ * (`sharedSqlConn` / `DATABASE_URL`). Console attaches that same
+ * {@link ApiKeyStore} — it does not own a second key table.
+ */
+
+import type { SqlConnection } from "../drivers/types.ts";
+import type { ApiKeyRow } from "./tables.ts";
+import { AUTH_TABLES } from "./tables.ts";
+import type { ApiKeyStore } from "./api-keys.ts";
+
+/** Minimal SQL executor for the auth key table. */
+export interface ApiKeySqlExec {
+  execute(sql: string, params: readonly unknown[]): Promise<void>;
+  all(sql: string): Promise<readonly Record<string, unknown>[]>;
+}
+
+/**
+ * Persist one key row to `oke_api_keys`.
+ *
+ * @param sql - Executor
+ * @param row - Key row
+ * @param table - Physical table (`oke_api_keys` or schema-qualified)
+ */
+export async function persistApiKeyRow(
+  sql: ApiKeySqlExec,
+  row: ApiKeyRow,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await sql.execute(
+    `INSERT INTO ${table} (
+      id, plane, hash, name, scopes, expires_at, rate_limit, ip_allowlist,
+      creator_id, creator_scopes, created_at, last_used_at, revoked_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      hash = excluded.hash,
+      name = excluded.name,
+      scopes = excluded.scopes,
+      expires_at = excluded.expires_at,
+      rate_limit = excluded.rate_limit,
+      ip_allowlist = excluded.ip_allowlist,
+      creator_id = excluded.creator_id,
+      creator_scopes = excluded.creator_scopes,
+      last_used_at = excluded.last_used_at,
+      revoked_at = excluded.revoked_at`,
+    [
+      row.id,
+      row.plane,
+      row.hash,
+      row.name,
+      JSON.stringify(row.scopes),
+      row.expiresAt,
+      row.rateLimit ? JSON.stringify(row.rateLimit) : null,
+      JSON.stringify(row.ipAllowlist),
+      row.creatorId,
+      JSON.stringify(row.creatorScopes),
+      row.createdAt,
+      row.lastUsedAt,
+      row.revokedAt,
+    ],
+  );
+}
+
+/**
+ * Load every key row from `oke_api_keys` into a store.
+ *
+ * @param sql - Executor
+ * @param store - Destination store
+ * @param table - Physical table
+ */
+export async function hydrateApiKeyStore(
+  sql: ApiKeySqlExec,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  const rows = await sql.all(`SELECT * FROM ${table}`);
+  for (const raw of rows) {
+    const row = rowFromSql(raw);
+    if (row) store.keys.set(row.id, row);
+  }
+}
+
+/**
+ * Bind write-through persist on a store.
+ *
+ * @param store - Key store
+ * @param sql - Executor
+ * @param table - Physical table
+ */
+export function bindApiKeySqlPersist(
+  store: ApiKeyStore,
+  sql: ApiKeySqlExec,
+  table: string = AUTH_TABLES.apiKeys,
+): void {
+  store.persist = (row) => persistApiKeyRow(sql, row, table);
+}
+
+/** Runtime that can open the app's shared primary SQL connection. */
+export interface HostApiKeySqlRuntime {
+  primarySql(): Promise<SqlConnection | undefined>;
+}
+
+/**
+ * Adapt a driver connection to {@link ApiKeySqlExec}.
+ *
+ * @param conn - Shared `store.sql()` connection
+ */
+export function apiKeySqlExec(conn: SqlConnection): ApiKeySqlExec {
+  return {
+    execute: async (sql, params) => {
+      await conn.exec(sql, params);
+    },
+    all: async (sql) => conn.query(sql),
+  };
+}
+
+/**
+ * Create public `oke_api_keys` when missing (host schema, not `oke_console`).
+ *
+ * @param conn - Shared SQL connection
+ * @param table - Physical table
+ */
+export async function ensureApiKeyTable(
+  conn: SqlConnection,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await conn.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY NOT NULL,
+      plane TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      name TEXT NOT NULL,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      expires_at BIGINT,
+      rate_limit TEXT,
+      ip_allowlist TEXT NOT NULL DEFAULT '[]',
+      creator_id TEXT NOT NULL,
+      creator_scopes TEXT NOT NULL DEFAULT '[]',
+      created_at BIGINT NOT NULL,
+      last_used_at BIGINT,
+      revoked_at BIGINT
+    )
+  `);
+}
+
+/**
+ * Hydrate and write-through-persist a host {@link ApiKeyStore} on `conn`.
+ *
+ * Leaves an already-bound `persist` hook in place (injected test stores).
+ *
+ * @param conn - App SQL connection (`sharedSqlConn`)
+ * @param store - `gate.auth.apiKeyStore`
+ * @param table - Physical table (`oke_api_keys` in `public`)
+ */
+export async function bindHostApiKeySql(
+  conn: SqlConnection,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await ensureApiKeyTable(conn, table);
+  const exec = apiKeySqlExec(conn);
+  await hydrateApiKeyStore(exec, store, table);
+  if (!store.persist) bindApiKeySqlPersist(store, exec, table);
+}
+
+/**
+ * Bind host key persist through {@link HostApiKeySqlRuntime.primarySql}.
+ *
+ * No-ops when the store runtime has no SQL driver (in-memory-only apps).
+ *
+ * @param runtime - Booted `store` element
+ * @param store - `gate.auth.apiKeyStore`
+ */
+export async function bindHostApiKeySqlFromStore(
+  runtime: HostApiKeySqlRuntime,
+  store: ApiKeyStore,
+): Promise<void> {
+  const conn = await runtime.primarySql();
+  if (!conn) return;
+  await bindHostApiKeySql(conn, store);
+}
+
+function rowFromSql(raw: Record<string, unknown>): ApiKeyRow | null {
+  const id = asString(raw.id ?? raw.ID);
+  const plane = raw.plane === "operator" ? "operator" : "user";
+  const hash = asString(raw.hash);
+  const name = asString(raw.name);
+  const creatorId = asString(raw.creator_id ?? raw.creatorId);
+  if (!id || !hash || !name || !creatorId) return null;
+  return {
+    id,
+    plane,
+    hash,
+    name,
+    scopes: asStringArray(raw.scopes),
+    expiresAt: asNumberOrNull(raw.expires_at ?? raw.expiresAt),
+    rateLimit: asRateLimit(raw.rate_limit ?? raw.rateLimit),
+    ipAllowlist: asStringArray(raw.ip_allowlist ?? raw.ipAllowlist),
+    creatorId,
+    creatorScopes: asStringArray(raw.creator_scopes ?? raw.creatorScopes),
+    createdAt: asNumberOrNull(raw.created_at ?? raw.createdAt) ?? 0,
+    lastUsedAt: asNumberOrNull(raw.last_used_at ?? raw.lastUsedAt),
+    revokedAt: asNumberOrNull(raw.revoked_at ?? raw.revokedAt),
+  };
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asNumberOrNull(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string");
+  if (typeof value === "string" && value.length > 0) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((item): item is string => typeof item === "string");
+      }
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+function asRateLimit(value: unknown): { max: number; per: string } | null {
+  const parsed: unknown =
+    typeof value === "string" && value.length > 0
+      ? (() => {
+          try {
+            return JSON.parse(value) as unknown;
+          } catch {
+            return null;
+          }
+        })()
+      : value;
+  if (!parsed || typeof parsed !== "object") return null;
+  const rec = parsed as { max?: unknown; per?: unknown };
+  if (typeof rec.max === "number" && typeof rec.per === "string") {
+    return { max: rec.max, per: rec.per };
+  }
+  return null;
+}