@wtfalch/keys 0.1.0

package/dist/issued/index.d.ts

@@ -0,0 +1,88 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { SerializedCredential, VerifyKeys, WorkerClient, WorkerErrorCode } from '../worker-contract.js';
+export { ID_PATTERN, SIGNED_PREFIX, type RequestMeta, type SerializedCredential, type SignableRow, type SignedKind, type SignedRow, type SignRowRequest, type SignRowResult, type SignRowSuccess, type VerifyKeys, type WorkerClient, type WorkerError, type WorkerErrorCode, type WorkerFailure, } from '../worker-contract.js';
+export type Db = PgDatabase<PgQueryResultHKT, any, any>;
+export interface AuditEvent {
+    readonly name: 'credential.minted' | 'credential.rotated' | 'credential.revoked';
+    readonly credentialId: string;
+    /** The id sent to the Worker on the same call, when there was one — omitted for `revoke()`, which never calls it. */
+    readonly requestId?: string;
+    readonly at: number;
+}
+export type AuditCallback = (event: AuditEvent) => Promise<void> | void;
+export interface CreateCredentialIssuerOptions<TGrant> {
+    readonly db: Db;
+    /** Only `signRow` is called: `check()` and `revoke()` stay fully local. */
+    readonly worker: Pick<WorkerClient<TGrant>, 'signRow'>;
+    /** This host's own Worker-signed service credential, sent as the bearer on every `signRow` call. */
+    readonly credential: SerializedCredential;
+    /** The Worker's current Ed25519 public key, and its previous one during a Worker key-rotation window. */
+    readonly verifyKeys: VerifyKeys;
+    /** `credential.minted` / `credential.rotated` / `credential.revoked`, for the host's own audit chain. */
+    readonly audit?: AuditCallback;
+    /** This host's split-secret prefix, e.g. `ai_live_`. Fixed per issuer; never inferred from a row. */
+    readonly prefix: string;
+    /** Unix milliseconds. Defaults to `Date.now`; a test passes a fake clock. */
+    readonly now?: () => number;
+}
+export interface IssueRequest<TGrant> {
+    readonly grants: readonly TGrant[];
+    /** The id of the credential minting this one, or `null` for a root mint. */
+    readonly minter: string | null;
+    /** Unix milliseconds. Required: refused when missing or already past, never clamped to the minter's own. */
+    readonly expiresAt: number;
+    readonly idempotencyKey?: string;
+}
+export type IssueRefusalReason = 'expires_at_required' | 'expires_at_past' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
+export type IssueResult = {
+    readonly ok: true;
+    readonly id: string;
+    readonly keyPrefix: string;
+    /** Shown exactly once. `null` on an idempotent replay — only the hash was ever stored. */
+    readonly secret: string | null;
+} | {
+    readonly ok: false;
+    readonly reason: IssueRefusalReason;
+};
+export type CheckRefusalReason = 'not_found' | 'signature_invalid' | 'revoked' | 'expired' | 'secret_mismatch';
+export type CheckResult<TGrant> = {
+    readonly ok: true;
+    readonly id: string;
+    readonly issuedById: string | null;
+    readonly grants: readonly TGrant[];
+} | {
+    readonly ok: false;
+    readonly reason: CheckRefusalReason;
+};
+export type RotateRefusalReason = 'not_found' | 'revoked' | 'minter_not_found' | 'minter_revoked' | 'minter_expired' | WorkerErrorCode;
+export type RotateResult = {
+    readonly ok: true;
+    readonly secret: string;
+} | {
+    readonly ok: false;
+    readonly reason: RotateRefusalReason;
+};
+export interface CredentialLink<TGrant> {
+    readonly id: string;
+    readonly issuedById: string | null;
+    readonly grants: readonly TGrant[];
+    readonly expiresAt: number;
+    readonly revokedAt: number | null;
+}
+export interface CredentialIssuer<TGrant> {
+    /** Calls `worker.signRow`. */
+    issue(request: IssueRequest<TGrant>): Promise<IssueResult>;
+    /** Fully local — never calls `worker`. */
+    check(secret: string): Promise<CheckResult<TGrant>>;
+    /** Calls `worker.signRow`. */
+    rotate(id: string, options: {
+        readonly graceMs: number;
+    }): Promise<RotateResult>;
+    /** Fully local — works during a Worker outage. Cascades by default. */
+    revoke(id: string, options?: {
+        readonly cascade?: boolean;
+    }): Promise<readonly string[]>;
+    /** The chain from `id` to its root, `id` first. Fully local. */
+    lineageOf(id: string): Promise<readonly CredentialLink<TGrant>[]>;
+}
+export declare function createCredentialIssuer<TGrant>(options: CreateCredentialIssuerOptions<TGrant>): CredentialIssuer<TGrant>;

package/dist/issued/index.js

@@ -0,0 +1,273 @@
+import { and, eq, inArray, isNull } from 'drizzle-orm';
+import { sql } from 'drizzle-orm';
+import { fromBase64Url, toBase64Url } from './codec.js';
+import { keyPrefixOf, mintSecret, rotateSecret, secretMatches } from './secret.js';
+import { keysIssuedCredentials } from './tables.js';
+import { verifyIssuedRowSignature } from './verify.js';
+export { ID_PATTERN, SIGNED_PREFIX, } from '../worker-contract.js';
+function rowsOf(result) {
+    if (Array.isArray(result))
+        return result;
+    return (result.rows ?? []);
+}
+function randomId() {
+    return crypto.randomUUID();
+}
+function toSignableRow(row) {
+    return {
+        id: row.id,
+        issuedById: row.issuedById,
+        keyPrefix: row.keyPrefix,
+        secretHash: row.secretHash,
+        previousSecretHash: row.previousSecretHash,
+        previousValidUntil: row.previousValidUntil,
+        grants: row.grants,
+        expiresAt: row.expiresAt,
+    };
+}
+export function createCredentialIssuer(options) {
+    const { db, worker, credential, verifyKeys, audit, prefix } = options;
+    const now = options.now ?? (() => Date.now());
+    const table = keysIssuedCredentials;
+    async function loadById(id) {
+        const [row] = await db.select().from(table).where(eq(table.id, id)).limit(1);
+        return row;
+    }
+    async function loadByPrefix(keyPrefix) {
+        const [row] = await db.select().from(table).where(eq(table.keyPrefix, keyPrefix)).limit(1);
+        return row;
+    }
+    async function loadByIdempotencyKey(key) {
+        const [row] = await db.select().from(table).where(eq(table.idempotencyKey, key)).limit(1);
+        return row;
+    }
+    /** Every descendant of `id`, `id` itself included. Mirrors valet's `subtreeOf` (`self-service.ts`). */
+    async function subtreeIds(id) {
+        const result = await db.execute(sql `
+      with recursive descendants as (
+        select id from keys_issued_credentials where id = ${id}
+        union
+        select c.id
+          from keys_issued_credentials c
+          join descendants d on c.issued_by_id = d.id
+      )
+      select id from descendants
+    `);
+        return rowsOf(result).map((r) => r.id);
+    }
+    async function emit(event) {
+        await audit?.(event);
+    }
+    async function issue(request) {
+        if (request.idempotencyKey) {
+            const existing = await loadByIdempotencyKey(request.idempotencyKey);
+            if (existing) {
+                return { ok: true, id: existing.id, keyPrefix: existing.keyPrefix, secret: null };
+            }
+        }
+        if (typeof request.expiresAt !== 'number' || !Number.isFinite(request.expiresAt)) {
+            return { ok: false, reason: 'expires_at_required' };
+        }
+        if (request.expiresAt <= now()) {
+            return { ok: false, reason: 'expires_at_past' };
+        }
+        let minterAttestation = null;
+        if (request.minter !== null) {
+            const minterRow = await loadById(request.minter);
+            if (!minterRow)
+                return { ok: false, reason: 'minter_not_found' };
+            // Local and authoritative: revoke() never calls the Worker, so its own
+            // mint log can lag a routine local revoke. The host's own table is the
+            // source of truth for whether a minter is still good.
+            if (minterRow.revokedAt !== null)
+                return { ok: false, reason: 'minter_revoked' };
+            if (minterRow.expiresAt <= now())
+                return { ok: false, reason: 'minter_expired' };
+            minterAttestation = {
+                row: toSignableRow(minterRow),
+                signature: fromBase64Url(minterRow.signature),
+            };
+        }
+        const id = randomId();
+        const minted = mintSecret(prefix);
+        const candidate = {
+            id,
+            issuedById: request.minter,
+            keyPrefix: minted.keyPrefix,
+            secretHash: minted.secretHash,
+            previousSecretHash: null,
+            previousValidUntil: null,
+            grants: request.grants,
+            expiresAt: request.expiresAt,
+        };
+        const requestId = randomId();
+        const result = await worker.signRow({
+            requestId,
+            credential,
+            candidate,
+            minter: minterAttestation,
+        });
+        if (!result.ok)
+            return { ok: false, reason: result.error.code };
+        try {
+            await db.insert(table).values({
+                id,
+                issuedById: candidate.issuedById,
+                keyPrefix: candidate.keyPrefix,
+                secretHash: candidate.secretHash,
+                grants: candidate.grants,
+                expiresAt: candidate.expiresAt,
+                signature: toBase64Url(result.signature),
+                signingGenerationId: result.generationId,
+                idempotencyKey: request.idempotencyKey ?? null,
+            });
+        }
+        catch (err) {
+            // A concurrent issue() with the same idempotencyKey won the race: the
+            // partial unique index refused this insert. Replay rather than throw.
+            if (request.idempotencyKey && isUniqueViolation(err)) {
+                const existing = await loadByIdempotencyKey(request.idempotencyKey);
+                if (existing) {
+                    return { ok: true, id: existing.id, keyPrefix: existing.keyPrefix, secret: null };
+                }
+            }
+            throw err;
+        }
+        await emit({ name: 'credential.minted', credentialId: id, requestId, at: now() });
+        return { ok: true, id, keyPrefix: candidate.keyPrefix, secret: minted.secret };
+    }
+    async function check(secret) {
+        const keyPrefix = keyPrefixOf(secret, prefix);
+        if (keyPrefix === null)
+            return { ok: false, reason: 'not_found' };
+        const row = await loadByPrefix(keyPrefix);
+        if (!row)
+            return { ok: false, reason: 'not_found' };
+        // Verified before anything else is trusted about the row: a signature
+        // check over the row's CURRENT fields refuses a row a raw UPDATE
+        // tampered with, whatever that tamper changed.
+        const signable = toSignableRow(row);
+        const genuine = await verifyIssuedRowSignature(signable, fromBase64Url(row.signature), verifyKeys);
+        if (!genuine)
+            return { ok: false, reason: 'signature_invalid' };
+        if (row.revokedAt !== null)
+            return { ok: false, reason: 'revoked' };
+        if (now() >= row.expiresAt)
+            return { ok: false, reason: 'expired' };
+        if (secretMatches(secret, row.secretHash)) {
+            return {
+                ok: true,
+                id: row.id,
+                issuedById: row.issuedById,
+                grants: row.grants,
+            };
+        }
+        if (row.previousSecretHash !== null &&
+            row.previousValidUntil !== null &&
+            now() < row.previousValidUntil &&
+            secretMatches(secret, row.previousSecretHash)) {
+            return {
+                ok: true,
+                id: row.id,
+                issuedById: row.issuedById,
+                grants: row.grants,
+            };
+        }
+        return { ok: false, reason: 'secret_mismatch' };
+    }
+    async function rotate(id, opts) {
+        const row = await loadById(id);
+        if (!row)
+            return { ok: false, reason: 'not_found' };
+        if (row.revokedAt !== null)
+            return { ok: false, reason: 'revoked' };
+        const minted = rotateSecret(row.keyPrefix);
+        const previousValidUntil = now() + opts.graceMs;
+        const candidate = {
+            id: row.id,
+            issuedById: row.issuedById,
+            keyPrefix: row.keyPrefix,
+            secretHash: minted.secretHash,
+            previousSecretHash: row.secretHash,
+            previousValidUntil,
+            grants: row.grants,
+            expiresAt: row.expiresAt,
+        };
+        let minterAttestation = null;
+        if (row.issuedById !== null) {
+            const parent = await loadById(row.issuedById);
+            if (!parent)
+                return { ok: false, reason: 'minter_not_found' };
+            // Same local, authoritative check as issue() — see the comment there.
+            if (parent.revokedAt !== null)
+                return { ok: false, reason: 'minter_revoked' };
+            if (parent.expiresAt <= now())
+                return { ok: false, reason: 'minter_expired' };
+            minterAttestation = {
+                row: toSignableRow(parent),
+                signature: fromBase64Url(parent.signature),
+            };
+        }
+        const requestId = randomId();
+        const result = await worker.signRow({
+            requestId,
+            credential,
+            candidate,
+            minter: minterAttestation,
+        });
+        if (!result.ok)
+            return { ok: false, reason: result.error.code };
+        await db
+            .update(table)
+            .set({
+            secretHash: candidate.secretHash,
+            previousSecretHash: candidate.previousSecretHash,
+            previousValidUntil: candidate.previousValidUntil,
+            signature: toBase64Url(result.signature),
+            signingGenerationId: result.generationId,
+        })
+            .where(eq(table.id, id));
+        await emit({ name: 'credential.rotated', credentialId: id, requestId, at: now() });
+        return { ok: true, secret: minted.secret };
+    }
+    async function revoke(id, opts = {}) {
+        const cascade = opts.cascade ?? true;
+        const ids = cascade ? await subtreeIds(id) : [id];
+        if (ids.length === 0)
+            return [];
+        const revokedAt = new Date(now());
+        const revokedRows = await db
+            .update(table)
+            .set({ revokedAt })
+            .where(and(inArray(table.id, ids), isNull(table.revokedAt)))
+            .returning({ id: table.id });
+        for (const r of revokedRows) {
+            await emit({ name: 'credential.revoked', credentialId: r.id, at: now() });
+        }
+        return revokedRows.map((r) => r.id);
+    }
+    async function lineageOf(id) {
+        const chain = [];
+        const seen = new Set();
+        let currentId = id;
+        while (currentId !== null && !seen.has(currentId)) {
+            seen.add(currentId);
+            const row = await loadById(currentId);
+            if (!row)
+                break;
+            chain.push({
+                id: row.id,
+                issuedById: row.issuedById,
+                grants: row.grants,
+                expiresAt: row.expiresAt,
+                revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+            });
+            currentId = row.issuedById;
+        }
+        return chain;
+    }
+    return { issue, check, rotate, revoke, lineageOf };
+}
+function isUniqueViolation(err) {
+    return err?.code === '23505';
+}

package/dist/issued/secret.d.ts

@@ -0,0 +1,30 @@
+export interface MintedSecret {
+    /** Shown to the caller exactly once. Never stored. */
+    readonly secret: string;
+    /** Stored in the clear; the indexed lookup key. */
+    readonly keyPrefix: string;
+    /** Hex SHA-256 of the whole secret. Stored instead of the secret. */
+    readonly secretHash: string;
+}
+export declare function hashSecret(secret: string): string;
+/** A fresh public id and a fresh tail: a brand-new credential. */
+export declare function mintSecret(prefix: string): MintedSecret;
+/** A fresh tail under an EXISTING `keyPrefix`: what rotate() calls, so the row keeps its indexed identity. */
+export declare function rotateSecret(keyPrefix: string): MintedSecret;
+/**
+ * The indexed half of a presented secret, or null if it is not shaped like
+ * one under this host's `prefix`.
+ *
+ * Returning null rather than throwing keeps the caller's refusal uniform: a
+ * malformed secret and an unknown one must be indistinguishable, or refusal
+ * becomes an oracle for which prefixes exist.
+ */
+export declare function keyPrefixOf(presented: string, prefix: string): string | null;
+/**
+ * Constant-time comparison of a presented secret against a stored hex hash.
+ *
+ * `timingSafeEqual` throws on length mismatch, which would itself leak, so
+ * lengths are checked first. Both sides are fixed-length hex here (SHA-256),
+ * so that branch means corrupt data rather than an attack.
+ */
+export declare function secretMatches(presented: string, storedHashHex: string): boolean;

package/dist/issued/secret.js

@@ -0,0 +1,69 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/**
+ * The split-secret format, carried over from valet's `src/lib/auth/keys.ts`:
+ *
+ *   <prefix><8-char public id><20-byte secret tail>
+ *
+ * The prefix through the public id is stored in the clear and is what a
+ * lookup indexes on; the tail is never stored, only the SHA-256 hash of the
+ * whole secret. `prefix` is host-supplied here (valet hardcodes `vk_live_`;
+ * a package used by several hosts cannot), everything after it is fixed.
+ *
+ * `node:crypto` rather than WebCrypto: this is a Node-side, host-only
+ * mechanic (unlike encoding.ts, nothing here runs in the Worker), and
+ * `timingSafeEqual` is what makes the comparison constant-time.
+ */
+const PUBLIC_ID_LEN = 8;
+const SECRET_BYTES = 20;
+/** Crockford-ish base32: no padding, no vowels-to-digits confusion in logs. */
+const ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
+function encode(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += ALPHABET[b % ALPHABET.length];
+    return out;
+}
+export function hashSecret(secret) {
+    return createHash('sha256').update(secret, 'utf8').digest('hex');
+}
+/** A fresh public id and a fresh tail: a brand-new credential. */
+export function mintSecret(prefix) {
+    const publicId = encode(randomBytes(PUBLIC_ID_LEN));
+    return rotateSecret(`${prefix}${publicId}`);
+}
+/** A fresh tail under an EXISTING `keyPrefix`: what rotate() calls, so the row keeps its indexed identity. */
+export function rotateSecret(keyPrefix) {
+    const tail = encode(randomBytes(SECRET_BYTES));
+    const secret = `${keyPrefix}${tail}`;
+    return { secret, keyPrefix, secretHash: hashSecret(secret) };
+}
+/**
+ * The indexed half of a presented secret, or null if it is not shaped like
+ * one under this host's `prefix`.
+ *
+ * Returning null rather than throwing keeps the caller's refusal uniform: a
+ * malformed secret and an unknown one must be indistinguishable, or refusal
+ * becomes an oracle for which prefixes exist.
+ */
+export function keyPrefixOf(presented, prefix) {
+    if (!presented.startsWith(prefix))
+        return null;
+    const expected = prefix.length + PUBLIC_ID_LEN + SECRET_BYTES;
+    if (presented.length !== expected)
+        return null;
+    return presented.slice(0, prefix.length + PUBLIC_ID_LEN);
+}
+/**
+ * Constant-time comparison of a presented secret against a stored hex hash.
+ *
+ * `timingSafeEqual` throws on length mismatch, which would itself leak, so
+ * lengths are checked first. Both sides are fixed-length hex here (SHA-256),
+ * so that branch means corrupt data rather than an attack.
+ */
+export function secretMatches(presented, storedHashHex) {
+    const a = Buffer.from(hashSecret(presented), 'hex');
+    const b = Buffer.from(storedHashHex, 'hex');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}