@wtfalch/keys 0.1.0

package/dist/worker-contract.d.ts

@@ -0,0 +1,360 @@
+/**
+ * The contract between `@wtfalch/keys` and the unwrap Worker.
+ *
+ * Types, constants and comments only. `./issued` (#230), `./held` (#231) and
+ * the Worker (#233) build against this one shape. The byte encodings are
+ * specified here and implemented once each: `encodeSigned` in
+ * `src/issued/encoding.ts` (#230) and `encodeAad` in `src/held/aad.ts` (#231).
+ * The Worker imports those two implementations rather than writing its own.
+ *
+ * Who does what:
+ * - The Worker implements every endpoint in `WORKER_HTTP`, holds the Ed25519
+ *   signing keys and each host's wrapping-key keyring, and owns two D1
+ *   tables: the mint/unwrap log and `revoked_credentials`.
+ * - `./issued` calls `signRow` from `issue()` and `rotate()`, `resign` from a
+ *   signing-key rotation sweep, and `recordEviction` from the incident
+ *   procedure after a local cascade `revoke()`. `check()`, `revoke()` and
+ *   `lineageOf()` never call the Worker, so revoking works during an outage.
+ * - `./held` calls `wrap` to seal a new version, `unwrap` on a cache-miss
+ *   `open()`, and `rewrap` from a wrapping-key rotation sweep. Encrypting
+ *   and decrypting the value with the data key, and the 60-second data-key
+ *   cache, are local.
+ *
+ * Sources: `.plans/2026-09-13-keys.md` in app-template, and the revised
+ * answers on app-template #216, #217, #218, #224, #225 and #228.
+ */
+/**
+ * Every id in this contract (host, tenant, entry, credential, row, key
+ * generation) matches this pattern. Both sides refuse anything else before
+ * encoding it, so no id can smuggle a delimiter into signed or
+ * authenticated bytes.
+ */
+export declare const ID_PATTERN: RegExp;
+/**
+ * What a signature is over. The Worker's one Ed25519 key signs two kinds of
+ * message, so every signed message starts with its kind. Without the tag, a
+ * host could ask `signRow` for a row whose bytes also parse as a caller
+ * credential, and use the signature as a fresh, unrevoked credential.
+ */
+export type SignedKind = 'issued-row' | 'caller-credential';
+/**
+ * `encodeSigned(kind, value)` is the UTF-8 bytes of
+ *
+ *   `wtfalch-keys:${kind}:v1\n` + canonicalJson(value)
+ *
+ * where `canonicalJson` is RFC 8785 (JCS): object keys sorted by UTF-16 code
+ * unit, no insignificant whitespace, numbers in their shortest round-trip
+ * form, `undefined` refused. JCS rather than `JSON.stringify` because a host
+ * stores `grants` as `jsonb`, which does not keep key order. `check()`
+ * re-encodes from the stored row, so the bytes must not depend on how the
+ * row came back from Postgres.
+ *
+ * Timestamps inside a signed value are integer Unix milliseconds, never ISO
+ * strings, for the same reason: `timestamptz` does not round-trip an ISO
+ * string byte for byte.
+ */
+export declare const SIGNED_PREFIX: "wtfalch-keys:";
+/** One held-key row and version. */
+export interface KeyBinding {
+    readonly tenantId: string;
+    readonly entryId: string;
+    /** The version's sequence number, an integer from 1. */
+    readonly version: number;
+}
+/**
+ * `encodeAad(binding)` is the UTF-8 bytes of
+ *
+ *   `wtfalch-keys:aad:v1\n` + JSON.stringify([tenantId, entryId, version])
+ *
+ * Ids match `ID_PATTERN` and `version` is an integer, so `JSON.stringify`
+ * is already canonical here. The wrapped data key (checked by the Worker)
+ * and the value's own ciphertext (checked by the host) use the same AAD, so
+ * a row copied to another tenant or relabelled to another version fails the
+ * GCM tag on both layers.
+ *
+ * This is a new format. It is not app-template's tier-1 `keystore.v1|...`
+ * string, whose tables this package does not read.
+ */
+export declare const AAD_PREFIX: "wtfalch-keys:aad:v1\n";
+/** What a caller credential may ask the Worker for. A closed set, not `@wtfalch/authz` scopes. */
+export type CallerGrant = 'wrap' | 'unwrap' | 'rewrap' | 'sign' | 'resign' | 'evict';
+/**
+ * What the Worker signs, as `encodeSigned('caller-credential', …)`, when it
+ * mints a host's service credential. `./issued` and `./held` never parse it:
+ * they read the serialized form from host config and forward it.
+ */
+export interface CallerCredential {
+    readonly id: string;
+    /**
+     * The host this credential belongs to. The Worker resolves every `kekId`
+     * inside this host's keyring only, and records `hostId` on every log row.
+     * A `kekId` from another host's keyring is `unknown_generation`, so a
+     * host holding another host's ciphertext still cannot open it.
+     */
+    readonly hostId: string;
+    readonly grants: readonly CallerGrant[];
+    /** Unix milliseconds. Required; checked on every call. */
+    readonly expiresAt: number;
+}
+/**
+ * `base64url(encodeSigned('caller-credential', credential)) + '.' +
+ * base64url(signature)`. Sent as `Authorization: Bearer <this>`. Opaque to
+ * the package.
+ */
+export type SerializedCredential = string;
+/**
+ * The verify keys a host holds for the Worker's signing key. `check()` tries
+ * `current`, then `previous`; never a network call. Two slots at most:
+ * rotation re-signs every live row, so the tuple never grows (#217, #228).
+ */
+export type VerifyKeys = readonly [current: Uint8Array, previous?: Uint8Array];
+/**
+ * Every field the Worker signs for one issued credential, as
+ * `encodeSigned('issued-row', row)`. A field outside this object is not
+ * protected by the signature, so anything that decides whether a secret
+ * authenticates is in here.
+ *
+ * `check()` builds the value to verify by picking exactly these eight fields
+ * from the stored row, never by passing the database row itself: extra
+ * columns would change the bytes and fail every check, or worse, be ignored
+ * by a lenient encoder.
+ */
+export interface SignableRow<TGrant> {
+    readonly id: string;
+    /** The parent credential's id, or `null` for a root mint. */
+    readonly issuedById: string | null;
+    /** The split-secret public id, stored in the clear and indexed. */
+    readonly keyPrefix: string;
+    /** Hex SHA-256 of the whole secret. Never the secret. */
+    readonly secretHash: string;
+    /**
+     * During a rotation's grace window, the hash of the secret being replaced,
+     * with `previousValidUntil`. Both `null` outside a rotation. Signed,
+     * because an unsigned grace pair would let a database writer add a secret
+     * of their own to a genuinely signed row.
+     */
+    readonly previousSecretHash: string | null;
+    /** Unix milliseconds, or `null`. Must be `null` exactly when `previousSecretHash` is. */
+    readonly previousValidUntil: number | null;
+    /** Opaque to the Worker and to this package; `@wtfalch/authz` interprets it. Must be JSON. */
+    readonly grants: readonly TGrant[];
+    /** Unix milliseconds. Required: a missing expiry is refused, never clamped. */
+    readonly expiresAt: number;
+}
+/** A `SignableRow` plus the Worker's signature over it. What `./issued` stores. */
+export interface SignedRow<TGrant> extends SignableRow<TGrant> {
+    readonly signature: Uint8Array;
+}
+export type WorkerErrorCode = 
+/** The bearer credential does not parse, or its signature does not verify. */
+'credential_invalid'
+/** The bearer credential's `expiresAt` has passed. */
+ | 'credential_expired'
+/** The bearer credential's id is in `revoked_credentials`. */
+ | 'credential_revoked'
+/** The bearer credential lacks the `CallerGrant` this call needs. */
+ | 'grant_missing'
+/** Per-credential rate limit exceeded; see `retryAfterMs`. */
+ | 'rate_limited'
+/** The request body is malformed, or an id fails `ID_PATTERN`. */
+ | 'bad_request'
+/** `unwrap`/`rewrap`: the GCM tag check failed for this binding and wrapped key. */
+ | 'aad_mismatch'
+/** `unwrap`/`rewrap`/`resign`: the named key generation is not in this host's keyring. */
+ | 'unknown_generation'
+/** `signRow`: the minter row's signature does not verify. */
+ | 'bad_minter_signature'
+/** `signRow`: the minter row's `expiresAt` has passed. */
+ | 'minter_expired'
+/** `signRow`: the minter row's id is in `revoked_credentials`. */
+ | 'minter_revoked'
+/**
+ * `signRow`: the candidate's `issuedById` is not the minter row's `id`, a
+ * root mint names a parent, or the minter row was not minted by this host.
+ */
+ | 'lineage_mismatch'
+/** `resign`: `oldSignature` does not verify under `oldGenerationId`. */
+ | 'bad_old_signature'
+/** `resign`: the signature verifies but the sign log has no such mint. Treat as forged: force-revoke, do not retry. */
+ | 'unlogged_row'
+/**
+ * `resign`: the mint log does not record `row.id` as minted under the
+ * calling credential's `hostId`. `recordEviction`: `credentialId` does not
+ * trace back, through the mint log's parent ids, to a root minted under
+ * the calling credential's `hostId`.
+ */
+ | 'not_in_lineage'
+/** Never sent by the Worker. The client reports it for a network failure, a timeout, or a response the Worker did not send. */
+ | 'unreachable';
+export interface WorkerError {
+    readonly code: WorkerErrorCode;
+    /** Only with `rate_limited`; mirrors `Retry-After`, in milliseconds. */
+    readonly retryAfterMs?: number;
+    readonly message?: string;
+}
+export interface WorkerFailure {
+    readonly ok: false;
+    readonly error: WorkerError;
+}
+export interface RequestMeta {
+    /**
+     * One per call, chosen by the caller, matching `ID_PATTERN`. The Worker
+     * writes it on the log row, and the host writes the same id on its own
+     * `key.used` / `credential.minted` row, so reconciliation (#236) can pair
+     * them.
+     */
+    readonly requestId: string;
+    /** Sent as `Authorization: Bearer`, never in the body. */
+    readonly credential: SerializedCredential;
+}
+/**
+ * Seals a new held-key version. The Worker generates a fresh 32-byte data
+ * key, wraps it under the calling host's `current` generation with
+ * `encodeAad(binding)` as associated data, and returns both. The host
+ * encrypts the value locally with `dataKey`, stores `wrappedKey` and
+ * `kekId`, and zeroes `dataKey`. The host never chooses a data key and never
+ * sees a wrapping key.
+ */
+export interface WrapRequest extends RequestMeta {
+    readonly binding: KeyBinding;
+}
+export interface WrapSuccess {
+    readonly ok: true;
+    readonly dataKey: Uint8Array;
+    readonly wrappedKey: Uint8Array;
+    readonly kekId: string;
+}
+export type WrapResult = WrapSuccess | WorkerFailure;
+export interface UnwrapRequest extends RequestMeta {
+    readonly kekId: string;
+    readonly wrappedKey: Uint8Array;
+    readonly binding: KeyBinding;
+}
+export interface UnwrapSuccess {
+    readonly ok: true;
+    /** The raw 32-byte data key. The Worker neither caches nor logs it. */
+    readonly dataKey: Uint8Array;
+}
+export type UnwrapResult = UnwrapSuccess | WorkerFailure;
+export interface RewrapRequest extends RequestMeta {
+    readonly kekIdOld: string;
+    readonly kekIdNew: string;
+    readonly wrappedKey: Uint8Array;
+    readonly binding: KeyBinding;
+}
+export interface RewrapSuccess {
+    readonly ok: true;
+    /** The same data key wrapped under `kekIdNew`. The raw data key never leaves the Worker. */
+    readonly wrappedKey: Uint8Array;
+}
+export type RewrapResult = RewrapSuccess | WorkerFailure;
+export interface SignRowRequest<TGrant> extends RequestMeta {
+    readonly candidate: SignableRow<TGrant>;
+    /**
+     * The minting credential's own signed row, or `null` for a root mint
+     * (then `candidate.issuedById` must be `null`). The Worker checks: the
+     * row's signature verifies, its `expiresAt` has not passed, its id is not
+     * revoked, its id was minted by this host (mint log), and
+     * `candidate.issuedById === minter.row.id`. It does not judge
+     * `candidate.grants`: attenuation runs on the host, through
+     * `@wtfalch/authz`, before `issue()`.
+     */
+    readonly minter: {
+        readonly row: SignableRow<TGrant>;
+        readonly signature: Uint8Array;
+    } | null;
+}
+export interface SignRowSuccess {
+    readonly ok: true;
+    readonly signature: Uint8Array;
+    /** The signing generation used, so a later `resign` can name it. */
+    readonly generationId: string;
+}
+export type SignRowResult = SignRowSuccess | WorkerFailure;
+/**
+ * The Worker checks, in order: `oldGenerationId` is in the calling host's
+ * signing keyring (`unknown_generation`); `oldSignature` verifies under it
+ * (`bad_old_signature`); the mint log records `row.id` as minted under the
+ * calling host (`not_in_lineage`); and that log entry was signed under
+ * `oldGenerationId` (`unlogged_row`). Only then does it sign `row` under the
+ * current generation.
+ */
+export interface ResignRequest<TGrant> extends RequestMeta {
+    readonly row: SignableRow<TGrant>;
+    readonly oldSignature: Uint8Array;
+    readonly oldGenerationId: string;
+}
+export interface ResignSuccess {
+    readonly ok: true;
+    readonly signature: Uint8Array;
+    readonly generationId: string;
+}
+export type ResignResult = ResignSuccess | WorkerFailure;
+export interface RecordEvictionRequest extends RequestMeta {
+    /** A credential id the caller has just cascade-revoked in its own store. */
+    readonly credentialId: string;
+    /** Unix milliseconds. */
+    readonly revokedAt: number;
+}
+export interface RecordEvictionSuccess {
+    readonly ok: true;
+    readonly receiptId: string;
+}
+export type RecordEvictionResult = RecordEvictionSuccess | WorkerFailure;
+/** What `./issued` and `./held` are given. Tests pass a stub; hosts pass the HTTP client. */
+export interface WorkerClient<TGrant = unknown> {
+    wrap(req: WrapRequest): Promise<WrapResult>;
+    unwrap(req: UnwrapRequest): Promise<UnwrapResult>;
+    rewrap(req: RewrapRequest): Promise<RewrapResult>;
+    signRow(req: SignRowRequest<TGrant>): Promise<SignRowResult>;
+    resign(req: ResignRequest<TGrant>): Promise<ResignResult>;
+    recordEviction(req: RecordEvictionRequest): Promise<RecordEvictionResult>;
+}
+/**
+ * One endpoint per call. Bodies are JSON; every `Uint8Array` is base64url on
+ * the wire; `requestId` is in the body; the credential is the bearer token.
+ *
+ * 200 carries the `*Success` body without `ok`. Any other status carries
+ * `{ error: WorkerError }`:
+ * - 400 `bad_request`.
+ * - 401 is about the caller: `credential_invalid`, `credential_expired`,
+ *   `credential_revoked`.
+ * - 403 is about this request: `grant_missing`, `aad_mismatch`,
+ *   `unknown_generation` (also `resign`), `bad_minter_signature`, `minter_expired`,
+ *   `minter_revoked`, `lineage_mismatch`, `bad_old_signature`,
+ *   `unlogged_row`, `not_in_lineage`.
+ * - 429 `rate_limited`, with `Retry-After` in seconds.
+ * Any other status, or none, is reported by the client as `unreachable`.
+ */
+export declare const WORKER_HTTP: {
+    readonly wrap: {
+        readonly method: "POST";
+        readonly path: "/v1/held/wrap";
+        readonly grant: "wrap";
+    };
+    readonly unwrap: {
+        readonly method: "POST";
+        readonly path: "/v1/held/unwrap";
+        readonly grant: "unwrap";
+    };
+    readonly rewrap: {
+        readonly method: "POST";
+        readonly path: "/v1/held/rewrap";
+        readonly grant: "rewrap";
+    };
+    readonly signRow: {
+        readonly method: "POST";
+        readonly path: "/v1/issued/sign";
+        readonly grant: "sign";
+    };
+    readonly resign: {
+        readonly method: "POST";
+        readonly path: "/v1/issued/resign";
+        readonly grant: "resign";
+    };
+    readonly recordEviction: {
+        readonly method: "POST";
+        readonly path: "/v1/issued/evictions";
+        readonly grant: "evict";
+    };
+};

package/dist/worker-contract.js

@@ -0,0 +1,94 @@
+/**
+ * The contract between `@wtfalch/keys` and the unwrap Worker.
+ *
+ * Types, constants and comments only. `./issued` (#230), `./held` (#231) and
+ * the Worker (#233) build against this one shape. The byte encodings are
+ * specified here and implemented once each: `encodeSigned` in
+ * `src/issued/encoding.ts` (#230) and `encodeAad` in `src/held/aad.ts` (#231).
+ * The Worker imports those two implementations rather than writing its own.
+ *
+ * Who does what:
+ * - The Worker implements every endpoint in `WORKER_HTTP`, holds the Ed25519
+ *   signing keys and each host's wrapping-key keyring, and owns two D1
+ *   tables: the mint/unwrap log and `revoked_credentials`.
+ * - `./issued` calls `signRow` from `issue()` and `rotate()`, `resign` from a
+ *   signing-key rotation sweep, and `recordEviction` from the incident
+ *   procedure after a local cascade `revoke()`. `check()`, `revoke()` and
+ *   `lineageOf()` never call the Worker, so revoking works during an outage.
+ * - `./held` calls `wrap` to seal a new version, `unwrap` on a cache-miss
+ *   `open()`, and `rewrap` from a wrapping-key rotation sweep. Encrypting
+ *   and decrypting the value with the data key, and the 60-second data-key
+ *   cache, are local.
+ *
+ * Sources: `.plans/2026-09-13-keys.md` in app-template, and the revised
+ * answers on app-template #216, #217, #218, #224, #225 and #228.
+ */
+// ---------------------------------------------------------------------------
+// Identifiers
+// ---------------------------------------------------------------------------
+/**
+ * Every id in this contract (host, tenant, entry, credential, row, key
+ * generation) matches this pattern. Both sides refuse anything else before
+ * encoding it, so no id can smuggle a delimiter into signed or
+ * authenticated bytes.
+ */
+export const ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/**
+ * `encodeSigned(kind, value)` is the UTF-8 bytes of
+ *
+ *   `wtfalch-keys:${kind}:v1\n` + canonicalJson(value)
+ *
+ * where `canonicalJson` is RFC 8785 (JCS): object keys sorted by UTF-16 code
+ * unit, no insignificant whitespace, numbers in their shortest round-trip
+ * form, `undefined` refused. JCS rather than `JSON.stringify` because a host
+ * stores `grants` as `jsonb`, which does not keep key order. `check()`
+ * re-encodes from the stored row, so the bytes must not depend on how the
+ * row came back from Postgres.
+ *
+ * Timestamps inside a signed value are integer Unix milliseconds, never ISO
+ * strings, for the same reason: `timestamptz` does not round-trip an ISO
+ * string byte for byte.
+ */
+export const SIGNED_PREFIX = 'wtfalch-keys:';
+/**
+ * `encodeAad(binding)` is the UTF-8 bytes of
+ *
+ *   `wtfalch-keys:aad:v1\n` + JSON.stringify([tenantId, entryId, version])
+ *
+ * Ids match `ID_PATTERN` and `version` is an integer, so `JSON.stringify`
+ * is already canonical here. The wrapped data key (checked by the Worker)
+ * and the value's own ciphertext (checked by the host) use the same AAD, so
+ * a row copied to another tenant or relabelled to another version fails the
+ * GCM tag on both layers.
+ *
+ * This is a new format. It is not app-template's tier-1 `keystore.v1|...`
+ * string, whose tables this package does not read.
+ */
+export const AAD_PREFIX = 'wtfalch-keys:aad:v1\n';
+// ---------------------------------------------------------------------------
+// HTTP mapping
+// ---------------------------------------------------------------------------
+/**
+ * One endpoint per call. Bodies are JSON; every `Uint8Array` is base64url on
+ * the wire; `requestId` is in the body; the credential is the bearer token.
+ *
+ * 200 carries the `*Success` body without `ok`. Any other status carries
+ * `{ error: WorkerError }`:
+ * - 400 `bad_request`.
+ * - 401 is about the caller: `credential_invalid`, `credential_expired`,
+ *   `credential_revoked`.
+ * - 403 is about this request: `grant_missing`, `aad_mismatch`,
+ *   `unknown_generation` (also `resign`), `bad_minter_signature`, `minter_expired`,
+ *   `minter_revoked`, `lineage_mismatch`, `bad_old_signature`,
+ *   `unlogged_row`, `not_in_lineage`.
+ * - 429 `rate_limited`, with `Retry-After` in seconds.
+ * Any other status, or none, is reported by the client as `unreachable`.
+ */
+export const WORKER_HTTP = {
+    wrap: { method: 'POST', path: '/v1/held/wrap', grant: 'wrap' },
+    unwrap: { method: 'POST', path: '/v1/held/unwrap', grant: 'unwrap' },
+    rewrap: { method: 'POST', path: '/v1/held/rewrap', grant: 'rewrap' },
+    signRow: { method: 'POST', path: '/v1/issued/sign', grant: 'sign' },
+    resign: { method: 'POST', path: '/v1/issued/resign', grant: 'resign' },
+    recordEviction: { method: 'POST', path: '/v1/issued/evictions', grant: 'evict' },
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wtfalch/keys",
+  "version": "0.1.0",
+  "description": "The estate's own bearer keys, issued to callers and held on their behalf: two entries, issued and held, nothing stored in common.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfalch/keys",
+    "directory": "packages/keys"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist"],
+  "bin": {
+    "keys-migrations": "dist/bin/migrations.js"
+  },
+  "exports": {
+    "./issued": {
+      "types": "./dist/issued/index.d.ts",
+      "default": "./dist/issued/index.js"
+    },
+    "./held": {
+      "types": "./dist/held/index.d.ts",
+      "default": "./dist/held/index.js"
+    },
+    "./migrations/*.sql": "./dist/migrations/*.sql",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/migrations && find src/migrations -maxdepth 1 -name '*.sql' -exec cp {} dist/migrations/ \\;",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.39.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@types/node": "^22",
+    "drizzle-orm": "^0.39.3",
+    "postgres": "^3.4.5",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6"
+  }
+}