@wtfalch/keys 0.1.0

package/dist/issued/tables.d.ts

@@ -0,0 +1,250 @@
+/**
+ * `keys_issued_credentials`, mirrored from `../migrations/0001_keys_issued.sql`,
+ * which is the source of truth: the SQL carries the CHECKs, the self-referencing
+ * foreign key and the partial unique indexes that drizzle-kit does not generate.
+ *
+ * `expiresAt` and `previousValidUntil` are `bigint` in `'number'` mode, not
+ * `timestamp`: both are signed as integer Unix milliseconds
+ * (`../worker-contract.ts`), and a bigint round-trips that exact integer with
+ * no timezone or fractional-second conversion in the way.
+ *
+ * `signature` is `text`, storing the Worker's Ed25519 signature bytes as
+ * base64url (see `codec.ts`) rather than `bytea`, so every driver hands the
+ * same JS string back with no Buffer/Uint8Array translation to get wrong.
+ *
+ * `issuedById` has no `.references()` here: a self-referencing foreign key on
+ * a lazily-declared drizzle table needs an `AnyPgColumn` callback and buys
+ * nothing this package's own tests check, since the constraint that actually
+ * runs is the one in the SQL migration.
+ */
+export declare const keysIssuedCredentials: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "keys_issued_credentials";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        issuedById: import("drizzle-orm/pg-core").PgColumn<{
+            name: "issued_by_id";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        keyPrefix: import("drizzle-orm/pg-core").PgColumn<{
+            name: "key_prefix";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        secretHash: import("drizzle-orm/pg-core").PgColumn<{
+            name: "secret_hash";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        previousSecretHash: import("drizzle-orm/pg-core").PgColumn<{
+            name: "previous_secret_hash";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        previousValidUntil: import("drizzle-orm/pg-core").PgColumn<{
+            name: "previous_valid_until";
+            tableName: "keys_issued_credentials";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        grants: import("drizzle-orm/pg-core").PgColumn<{
+            name: "grants";
+            tableName: "keys_issued_credentials";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "expires_at";
+            tableName: "keys_issued_credentials";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        signature: import("drizzle-orm/pg-core").PgColumn<{
+            name: "signature";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        signingGenerationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "signing_generation_id";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        idempotencyKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "idempotency_key";
+            tableName: "keys_issued_credentials";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "keys_issued_credentials";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        revokedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "revoked_at";
+            tableName: "keys_issued_credentials";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export type KeysIssuedCredentialsTable = typeof keysIssuedCredentials;
+export type KeysIssuedCredentialRow = typeof keysIssuedCredentials.$inferSelect;
+export type KeysIssuedCredentialInsert = typeof keysIssuedCredentials.$inferInsert;

package/dist/issued/tables.js

@@ -0,0 +1,35 @@
+import { bigint, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+/**
+ * `keys_issued_credentials`, mirrored from `../migrations/0001_keys_issued.sql`,
+ * which is the source of truth: the SQL carries the CHECKs, the self-referencing
+ * foreign key and the partial unique indexes that drizzle-kit does not generate.
+ *
+ * `expiresAt` and `previousValidUntil` are `bigint` in `'number'` mode, not
+ * `timestamp`: both are signed as integer Unix milliseconds
+ * (`../worker-contract.ts`), and a bigint round-trips that exact integer with
+ * no timezone or fractional-second conversion in the way.
+ *
+ * `signature` is `text`, storing the Worker's Ed25519 signature bytes as
+ * base64url (see `codec.ts`) rather than `bytea`, so every driver hands the
+ * same JS string back with no Buffer/Uint8Array translation to get wrong.
+ *
+ * `issuedById` has no `.references()` here: a self-referencing foreign key on
+ * a lazily-declared drizzle table needs an `AnyPgColumn` callback and buys
+ * nothing this package's own tests check, since the constraint that actually
+ * runs is the one in the SQL migration.
+ */
+export const keysIssuedCredentials = pgTable('keys_issued_credentials', {
+    id: text('id').primaryKey(),
+    issuedById: text('issued_by_id'),
+    keyPrefix: text('key_prefix').notNull(),
+    secretHash: text('secret_hash').notNull(),
+    previousSecretHash: text('previous_secret_hash'),
+    previousValidUntil: bigint('previous_valid_until', { mode: 'number' }),
+    grants: jsonb('grants').notNull(),
+    expiresAt: bigint('expires_at', { mode: 'number' }).notNull(),
+    signature: text('signature').notNull(),
+    signingGenerationId: text('signing_generation_id').notNull(),
+    idempotencyKey: text('idempotency_key'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+});

package/dist/issued/verify.d.ts

@@ -0,0 +1,8 @@
+import type { SignableRow, VerifyKeys } from '../worker-contract.js';
+/**
+ * Verifies `signature` over `encodeSigned('issued-row', pickSignable(row))`
+ * against `verifyKeys`: `current` first, then `previous` if present. A row
+ * signed under either key checks — that is what lets a Worker signing-key
+ * rotation happen without re-signing every row before `previous` is dropped.
+ */
+export declare function verifyIssuedRowSignature<TGrant>(row: SignableRow<TGrant>, signature: Uint8Array, verifyKeys: VerifyKeys): Promise<boolean>;

package/dist/issued/verify.js

@@ -0,0 +1,31 @@
+import { encodeSigned, pickSignable } from './encoding.js';
+/**
+ * WebCrypto (`crypto.subtle`), not `node:crypto`'s classic API: the same
+ * `verify('Ed25519', …)` shape runs in Node 22 and in a Cloudflare Worker,
+ * and `check()` verifying a row is exactly the code a Worker-side sweep
+ * would want to reuse later.
+ */
+async function importEd25519PublicKey(raw) {
+    return crypto.subtle.importKey('raw', raw, { name: 'Ed25519' }, false, [
+        'verify',
+    ]);
+}
+async function verifyEd25519(publicKey, signature, data) {
+    const key = await importEd25519PublicKey(publicKey);
+    return crypto.subtle.verify({ name: 'Ed25519' }, key, signature, data);
+}
+/**
+ * Verifies `signature` over `encodeSigned('issued-row', pickSignable(row))`
+ * against `verifyKeys`: `current` first, then `previous` if present. A row
+ * signed under either key checks — that is what lets a Worker signing-key
+ * rotation happen without re-signing every row before `previous` is dropped.
+ */
+export async function verifyIssuedRowSignature(row, signature, verifyKeys) {
+    const data = encodeSigned('issued-row', pickSignable(row));
+    const [current, previous] = verifyKeys;
+    if (await verifyEd25519(current, signature, data))
+        return true;
+    if (previous && (await verifyEd25519(previous, signature, data)))
+        return true;
+    return false;
+}

package/dist/migrations/0001_keys_issued.sql

@@ -0,0 +1,80 @@
+-- @wtfalch/keys: the ./issued entry's row store. Mirrors src/issued/tables.ts.
+--
+-- One row per issued credential: the eight SignableRow<TGrant> fields the
+-- Worker signs (id, issued_by_id, key_prefix, secret_hash,
+-- previous_secret_hash, previous_valid_until, grants, expires_at), plus the
+-- Worker's own signature and the signing generation it was signed under, and
+-- three columns this table owns alone: an idempotency key, created_at and
+-- revoked_at. check() re-verifies the signature over exactly those eight
+-- fields on every call (src/issued/encoding.ts's pickSignable), so a column
+-- outside that set carries no authority and this file's shape must match
+-- pickSignable's allowlist exactly.
+--
+-- expires_at and previous_valid_until are bigint, not timestamptz: both are
+-- signed as integer Unix milliseconds (worker-contract.ts's SignableRow), and
+-- a bigint round-trips that exact integer with no timezone conversion or
+-- fractional-second rounding in the way. migration.test.ts proves it.
+--
+-- signature is text, not bytea: stored as base64url so every driver
+-- (postgres.js, PGlite, whatever a future host uses) returns the same JS
+-- string type back, with no driver-specific Buffer/Uint8Array translation to
+-- get wrong.
+--
+-- Applied by the host's own migrate script after the host copies this file
+-- into its own migrations directory as the next number (keys-migrations);
+-- never edited there. Every statement is idempotent.
+--
+-- No shred sweep here: that is #232, over ./held's envelope tables. A revoked
+-- issued credential's row stays — it carries no secret in the clear, only a
+-- hash, and the row itself is what lineageOf and reconciliation read.
+
+create table if not exists keys_issued_credentials (
+  id                     text not null primary key,
+  issued_by_id           text references keys_issued_credentials (id),
+  key_prefix             text not null,
+  secret_hash            text not null,
+  previous_secret_hash   text,
+  previous_valid_until   bigint,
+  grants                 jsonb not null,
+  expires_at             bigint not null,
+  signature              text not null,
+  signing_generation_id  text not null,
+  idempotency_key        text,
+  created_at             timestamptz not null default now(),
+  revoked_at             timestamptz,
+  constraint keys_issued_credentials_id_check
+    check (id ~ '^[A-Za-z0-9_-]{1,128}$'),
+  constraint keys_issued_credentials_issued_by_id_check
+    check (issued_by_id is null or issued_by_id ~ '^[A-Za-z0-9_-]{1,128}$'),
+  constraint keys_issued_credentials_no_self_parent_check
+    check (issued_by_id is distinct from id),
+  constraint keys_issued_credentials_key_prefix_check
+    check (length(key_prefix) between 1 and 64),
+  constraint keys_issued_credentials_secret_hash_check
+    check (secret_hash ~ '^[0-9a-f]{64}$'),
+  constraint keys_issued_credentials_previous_secret_hash_check
+    check (previous_secret_hash is null or previous_secret_hash ~ '^[0-9a-f]{64}$'),
+  -- Signed as a pair: both null outside a rotation, both set during one.
+  constraint keys_issued_credentials_grace_pair_check
+    check ((previous_secret_hash is null) = (previous_valid_until is null)),
+  constraint keys_issued_credentials_grants_check
+    check (jsonb_typeof(grants) = 'array'),
+  constraint keys_issued_credentials_expires_at_check
+    check (expires_at > 0),
+  constraint keys_issued_credentials_signature_check
+    check (length(signature) > 0),
+  constraint keys_issued_credentials_signing_generation_id_check
+    check (length(signing_generation_id) between 1 and 128)
+);
+
+create unique index if not exists keys_issued_credentials_key_prefix_idx
+  on keys_issued_credentials (key_prefix);
+
+-- Cascade revoke walks this column downward via a recursive CTE; index it.
+create index if not exists keys_issued_credentials_issued_by_id_idx
+  on keys_issued_credentials (issued_by_id)
+  where issued_by_id is not null;
+
+create unique index if not exists keys_issued_credentials_idempotency_key_idx
+  on keys_issued_credentials (idempotency_key)
+  where idempotency_key is not null;

package/dist/migrations/0002_keys_held.sql

@@ -0,0 +1,60 @@
+-- @wtfalch/keys ./held: where a host stores the ciphertext half of a held
+-- key. Mirrors src/held/schema.ts.
+--
+-- Applied by the host's own migrate script after this file is copied into
+-- its drizzle/ directory as the next number (keys-migrations); never edited
+-- there. Every statement is idempotent.
+--
+-- keys_held_entries: one row per (tenant, entry) this host holds a secret
+-- for. keys_held_versions: an immutable row per sealed version -- the value's
+-- own ciphertext plus the wrapped data key the Worker returned for it.
+--
+-- wrapped_key is nullable on purpose: a later migration (#232) nulls it,
+-- through a narrowly privileged function, once a version has been eligible
+-- for destruction (retired past its grace window, its entry revoked, or its
+-- tenant archived) for at least the host's shred-delay window. This
+-- migration only creates the column that later change writes to; it adds no
+-- shred function and no guard trigger -- that is #232's migration, not this
+-- one.
+
+create table if not exists keys_held_entries (
+  tenant_id       text not null,
+  entry_id        text not null,
+  current_version integer not null default 0,
+  revoked_at      timestamptz,
+  created_at      timestamptz not null default now(),
+  constraint keys_held_entries_pkey primary key (tenant_id, entry_id),
+  constraint keys_held_entries_tenant_id_check check (tenant_id ~ '^[A-Za-z0-9_-]{1,128}$'),
+  constraint keys_held_entries_entry_id_check check (entry_id ~ '^[A-Za-z0-9_-]{1,128}$'),
+  constraint keys_held_entries_current_version_check check (current_version >= 0)
+);
+
+create table if not exists keys_held_versions (
+  tenant_id   text not null,
+  entry_id    text not null,
+  version     integer not null,
+  -- The Worker keyring generation the data key was wrapped under.
+  -- worker-contract.ts's ID_PATTERN covers "key generation" ids too.
+  kek_id      text not null,
+  -- The data key, wrapped by the Worker under kek_id. NULL once shredded
+  -- (#232); never NULL for a version this migration inserts.
+  wrapped_key bytea,
+  -- 96-bit GCM nonce, fresh per seal.
+  iv          bytea not null,
+  -- GCM ciphertext with its 16-byte authentication tag appended.
+  ciphertext  bytea not null,
+  -- Set by #232's shred sweep. This migration only reserves the column.
+  retired_at  timestamptz,
+  created_at  timestamptz not null default now(),
+  constraint keys_held_versions_pkey primary key (tenant_id, entry_id, version),
+  constraint keys_held_versions_entry_fkey foreign key (tenant_id, entry_id)
+    references keys_held_entries (tenant_id, entry_id),
+  constraint keys_held_versions_version_check check (version >= 1),
+  constraint keys_held_versions_kek_id_check check (kek_id ~ '^[A-Za-z0-9_-]{1,128}$'),
+  constraint keys_held_versions_iv_check check (octet_length(iv) = 12),
+  constraint keys_held_versions_ciphertext_check check (octet_length(ciphertext) >= 16)
+);
+
+-- The rewrap sweep selects every row still under an outgoing kek_id, across
+-- every tenant this host serves (#217: one wrapping key per host).
+create index if not exists keys_held_versions_kek_idx on keys_held_versions (kek_id);