@antasphere/chassis-server 1.0.0

package/dist/apikeys/peppers.js

@@ -0,0 +1,97 @@
+/**
+ * Versioned API-key peppers — the seam that lets API keys survive an
+ * AUTH_SECRET rotation (ADR 008).
+ *
+ * Version 1 is ALWAYS the pepper that hashed keys before versioning existed:
+ * the resolved auth secret, used verbatim as `sha256(secret + pepper)`. With
+ * no `API_KEY_PEPPERS` set the registry is exactly `{ 1: authSecret }` and
+ * new keys mint at version 1 — byte-identical to the pre-versioning
+ * behaviour, nothing to migrate.
+ *
+ * `API_KEY_PEPPERS` supplies additional versions as `<version>:<secret>`
+ * entries joined by `;` (e.g. `1:<old secret>;2:<new pepper>`). Entries
+ * override the defaults, so pinning `1:<value>` freezes version 1
+ * independently of the live AUTH_SECRET — the first step of the rotation
+ * runbook in internal/security-runbooks.md. LOUD RULE: whenever version 1 is pinned, its
+ * value MUST be the historical AUTH_SECRET-derived pepper (the secret that
+ * was live when the version-1 keys were minted), or every existing key stops
+ * resolving. New keys always mint under the HIGHEST version in the registry.
+ *
+ * Resolution looks up the pepper by the key row's stored `pepper_version`
+ * and FAILS CLOSED on a version the registry does not contain — same 401 as
+ * a revoked key, never a fallback to another pepper.
+ */
+/** `pepper_version` is a Postgres smallint. */
+export const MAX_PEPPER_VERSION = 32767;
+/** Peppers hold the same bar as AUTH_SECRET. */
+const MIN_PEPPER_LENGTH = 32;
+/**
+ * Parse the `API_KEY_PEPPERS` value into a version→secret map. Throws a
+ * readable Error on any malformed entry — surfaced by the env schema, so a
+ * bad value refuses boot instead of silently mis-hashing keys.
+ */
+export function parseApiKeyPeppers(raw) {
+    const map = new Map();
+    // Trailing/duplicated separators are operator noise, not errors.
+    const entries = raw
+        .split(';')
+        .map((e) => e.trim())
+        .filter((e) => e.length > 0);
+    if (entries.length === 0) {
+        throw new Error('API_KEY_PEPPERS is set but contains no <version>:<secret> entries');
+    }
+    for (const entry of entries) {
+        // Split at the FIRST colon only — the secret itself may contain colons.
+        const colon = entry.indexOf(':');
+        if (colon <= 0) {
+            throw new Error(`API_KEY_PEPPERS entry "${describeEntry(entry)}" is not <version>:<secret>`);
+        }
+        const versionPart = entry.slice(0, colon).trim();
+        const secret = entry.slice(colon + 1);
+        if (!/^[0-9]+$/.test(versionPart)) {
+            // A reversed `<secret>:<version>` entry makes versionPart the whole
+            // secret — truncate so a misconfiguration doesn't echo it to stderr.
+            throw new Error(`API_KEY_PEPPERS version "${describeEntry(versionPart)}" is not a positive integer`);
+        }
+        const version = Number(versionPart);
+        if (version < 1 || version > MAX_PEPPER_VERSION) {
+            throw new Error(`API_KEY_PEPPERS version ${version} is out of range (1..${MAX_PEPPER_VERSION})`);
+        }
+        if (map.has(version)) {
+            throw new Error(`API_KEY_PEPPERS defines version ${version} twice`);
+        }
+        if (secret.length < MIN_PEPPER_LENGTH) {
+            throw new Error(`API_KEY_PEPPERS version ${version} secret is shorter than ${MIN_PEPPER_LENGTH} characters`);
+        }
+        map.set(version, secret);
+    }
+    return map;
+}
+/** Error context that never echoes a possible secret: version side only. */
+function describeEntry(entry) {
+    const head = entry.slice(0, Math.min(8, entry.length));
+    return entry.length > 8 ? `${head}…` : head;
+}
+/**
+ * Build the registry from the resolved auth secret plus the optional
+ * `API_KEY_PEPPERS` value (already format-validated by the env schema; this
+ * re-parses so direct callers get the same guarantees).
+ */
+export function buildPepperRegistry(authSecret, apiKeyPeppers) {
+    const peppers = new Map([[1, authSecret]]);
+    let v1Pinned = false;
+    if (apiKeyPeppers !== undefined) {
+        const parsed = parseApiKeyPeppers(apiKeyPeppers);
+        v1Pinned = parsed.has(1);
+        for (const [version, secret] of parsed)
+            peppers.set(version, secret);
+    }
+    const current = Math.max(...peppers.keys());
+    return {
+        current,
+        v1Pinned,
+        get: (version) => peppers.get(version),
+        versions: [...peppers.keys()].sort((a, b) => a - b)
+    };
+}
+//# sourceMappingURL=peppers.js.map

package/dist/apikeys/peppers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peppers.js","sourceRoot":"","sources":["../../src/apikeys/peppers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAExC,gDAAgD;AAChD,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAkB7B;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,iEAAiE;IACjE,MAAM,OAAO,GAAG,GAAG;SAChB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,wEAAwE;QACxE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,aAAa,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAClC,oEAAoE;YACpE,qEAAqE;YACrE,MAAM,IAAI,KAAK,CAAC,4BAA4B,aAAa,CAAC,WAAW,CAAC,6BAA6B,CAAC,CAAC;QACvG,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACpC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,kBAAkB,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,wBAAwB,kBAAkB,GAAG,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,QAAQ,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,2BAA2B,OAAO,2BAA2B,iBAAiB,aAAa,CAC5F,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,4EAA4E;AAC5E,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,aAAsB;IAC5E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAiB,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC3D,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;QACjD,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,MAAM;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,OAAO;QACL,OAAO;QACP,QAAQ;QACR,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACtC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;KACpD,CAAC;AACJ,CAAC"}

package/dist/apikeys/service.d.ts

@@ -0,0 +1,56 @@
+import { type Db } from '@antasphere/chassis-db';
+import type { Principal } from '@antasphere/chassis-contract';
+import { type OnWorkspaceMiss } from '../identity/resolve-membership.js';
+import type { PepperRegistry } from './peppers.js';
+/**
+ * A VALID pinned key presented with an X-Workspace-Id naming a different
+ * workspace — a client bug or a confused-deputy attempt. Distinct from a
+ * plain resolution miss (null → 401) so the middleware can answer the loud
+ * 403 the pinned model always answered.
+ */
+export declare class WorkspaceMismatchError extends Error {
+    constructor();
+}
+export interface MintedKey {
+    id: string;
+    keyId: string;
+    /** The full key — returned once, never stored. */
+    key: string;
+}
+export declare class ApiKeyService {
+    private readonly db;
+    private readonly peppers;
+    /** The tool's key prefix, without the underscore (`identity.apiKeyPrefix`). Required: no chassis default. */
+    private readonly prefix;
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    private readonly onWorkspaceMiss?;
+    private readonly keyRe;
+    constructor(db: Db, peppers: PepperRegistry, 
+    /** The tool's key prefix, without the underscore (`identity.apiKeyPrefix`). Required: no chassis default. */
+    prefix: string, 
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    onWorkspaceMiss?: OnWorkspaceMiss | undefined);
+    /** Distinguishes an API-key credential from other bearers (the shape only, no lookup). */
+    readonly isToken: (token: string) => boolean;
+    mint(opts: {
+        /** Optional workspace PIN — omitted/null mints a user-scoped key. */
+        workspaceId?: string | null;
+        createdBy: string;
+        name: string;
+        scopes: string[];
+        expiresAt?: Date | null;
+    }): Promise<MintedKey>;
+    /**
+     * Resolve a presented key to a live principal, or null. The key dies with
+     * its creator: a live active membership is required (same re-check
+     * discipline as sessions).
+     *
+     * `requested` is the request's X-Workspace-Id (or null). An UNPINNED key
+     * selects with it exactly like a session (fail closed on non-membership);
+     * a PINNED key always resolves its pin and THROWS WorkspaceMismatchError
+     * when `requested` names a different workspace — never silently serves
+     * the pinned one.
+     */
+    resolve(token: string, requested: string | null): Promise<Principal | null>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/apikeys/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/apikeys/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,EAAE,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAiCnD;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAQD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,6GAA6G;IAC7G,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IARnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAGZ,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,cAAc;IACxC,6GAA6G;IAC5F,MAAM,EAAE,MAAM;IAC/B,uEAAuE;IACtD,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS;IAMhE,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,GAAI,OAAO,MAAM,KAAG,OAAO,CAA2B;IAEhE,IAAI,CAAC,IAAI,EAAE;QACf,qEAAqE;QACrE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;KACzB,GAAG,OAAO,CAAC,SAAS,CAAC;IAyBtB;;;;;;;;;;OAUG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CA6FlF"}

package/dist/apikeys/service.js

@@ -0,0 +1,196 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { and, eq, gt, isNull, or, sql } from 'drizzle-orm';
+import { apiKeys } from '@antasphere/chassis-db';
+import { isWorkspaceSelector, resolveMembership } from '../identity/resolve-membership.js';
+/**
+ * API keys: `<prefix>_<keyId8>_<secret>`.
+ *
+ * The prefix is the TOOL's (`identity.apiKeyPrefix`, e.g. a product called
+ * Acme might use `acm`): a constructor value with no default, so the chassis
+ * spells none. The shape is fixed: keyId gives an O(1)
+ * indexed lookup, the secret is stored as sha256(secret + pepper) and
+ * compared constant-time. The pepper defaults to the server auth secret, so
+ * a leaked database alone cannot validate keys — and it is VERSIONED
+ * (peppers.ts, ADR 008): each row records the pepper version that hashed it,
+ * mint uses the registry's current version, and resolution uses the stored
+ * version's pepper or fails closed. Keys are minted by sessions only.
+ *
+ * A key is a USER credential (user-scoped credential model): it acts as its
+ * creator, and the target workspace resolves per request through the shared
+ * resolveMembership rule — the X-Workspace-Id header, else the creator's
+ * default membership. `workspace_id` on the row is an OPTIONAL PIN (least
+ * privilege, and the grandfathered binding of pre-model-change keys): a
+ * pinned key resolves ONLY its pinned workspace, and a request naming a
+ * DIFFERENT one is rejected loudly (WorkspaceMismatchError → 403).
+ */
+const KEY_ID_BYTES = 6; // 8 chars base64url
+const SECRET_BYTES = 32; // 43 chars base64url
+/** The prefix is a literal in the pattern: every RegExp metacharacter in it is escaped. */
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** The key shape for one prefix: `<prefix>_<keyId8>_<secret>`, two capture groups. */
+const keyPattern = (prefix) => new RegExp(`^${escapeRegExp(prefix)}_([A-Za-z0-9_-]{8})_([A-Za-z0-9_-]{20,})$`);
+/**
+ * A VALID pinned key presented with an X-Workspace-Id naming a different
+ * workspace — a client bug or a confused-deputy attempt. Distinct from a
+ * plain resolution miss (null → 401) so the middleware can answer the loud
+ * 403 the pinned model always answered.
+ */
+export class WorkspaceMismatchError extends Error {
+    constructor() {
+        super('This credential is pinned to a different workspace');
+        this.name = 'WorkspaceMismatchError';
+    }
+}
+function hashSecret(secret, pepper) {
+    return createHash('sha256')
+        .update(secret + pepper)
+        .digest('hex');
+}
+export class ApiKeyService {
+    db;
+    peppers;
+    prefix;
+    onWorkspaceMiss;
+    keyRe;
+    constructor(db, peppers, 
+    /** The tool's key prefix, without the underscore (`identity.apiKeyPrefix`). Required: no chassis default. */
+    prefix, 
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    onWorkspaceMiss) {
+        this.db = db;
+        this.peppers = peppers;
+        this.prefix = prefix;
+        this.onWorkspaceMiss = onWorkspaceMiss;
+        if (!prefix)
+            throw new Error('ApiKeyService: the key prefix is required');
+        this.keyRe = keyPattern(prefix);
+    }
+    /** Distinguishes an API-key credential from other bearers (the shape only, no lookup). */
+    isToken = (token) => this.keyRe.test(token);
+    async mint(opts) {
+        const keyId = randomBytes(KEY_ID_BYTES).toString('base64url');
+        const secret = randomBytes(SECRET_BYTES).toString('base64url');
+        // Mint always hashes under the CURRENT pepper version and records which
+        // one, so resolution can keep verifying old keys across pepper rotations.
+        const pepperVersion = this.peppers.current;
+        const pepper = this.peppers.get(pepperVersion);
+        if (pepper === undefined)
+            throw new Error(`pepper registry has no current version ${pepperVersion}`);
+        const [row] = await this.db
+            .insert(apiKeys)
+            .values({
+            workspaceId: opts.workspaceId ?? null,
+            keyId,
+            secretHash: hashSecret(secret, pepper),
+            pepperVersion,
+            name: opts.name,
+            scopes: opts.scopes,
+            createdBy: opts.createdBy,
+            expiresAt: opts.expiresAt ?? null
+        })
+            .returning({ id: apiKeys.id });
+        if (!row)
+            throw new Error('api key insert failed');
+        return { id: row.id, keyId, key: `${this.prefix}_${keyId}_${secret}` };
+    }
+    /**
+     * Resolve a presented key to a live principal, or null. The key dies with
+     * its creator: a live active membership is required (same re-check
+     * discipline as sessions).
+     *
+     * `requested` is the request's X-Workspace-Id (or null). An UNPINNED key
+     * selects with it exactly like a session (fail closed on non-membership);
+     * a PINNED key always resolves its pin and THROWS WorkspaceMismatchError
+     * when `requested` names a different workspace — never silently serves
+     * the pinned one.
+     */
+    async resolve(token, requested) {
+        const match = this.keyRe.exec(token);
+        if (!match)
+            return null;
+        const [, keyId, secret] = match;
+        if (!keyId || !secret)
+            return null;
+        const [row] = await this.db
+            .select({
+            id: apiKeys.id,
+            secretHash: apiKeys.secretHash,
+            pepperVersion: apiKeys.pepperVersion,
+            workspaceId: apiKeys.workspaceId,
+            scopes: apiKeys.scopes,
+            createdBy: apiKeys.createdBy,
+            expiresAt: apiKeys.expiresAt
+        })
+            .from(apiKeys)
+            .where(and(eq(apiKeys.keyId, keyId), isNull(apiKeys.revokedAt), 
+        // Expired = same lookup miss as revoked — one fail-closed 401, no
+        // behavioural fork. DB clock, not app clock.
+        or(isNull(apiKeys.expiresAt), gt(apiKeys.expiresAt, sql `now()`))))
+            .limit(1);
+        if (!row)
+            return null;
+        // Verify under the pepper version THIS row was hashed with — never the
+        // current one, never a fallback. An unknown version (e.g. the operator
+        // dropped a retired pepper from API_KEY_PEPPERS while such keys remain)
+        // FAILS CLOSED: same null → same 401 as a revoked or expired key.
+        const pepper = this.peppers.get(row.pepperVersion);
+        if (pepper === undefined)
+            return null;
+        const presented = Buffer.from(hashSecret(secret, pepper), 'hex');
+        const stored = Buffer.from(row.secretHash, 'hex');
+        if (presented.length !== stored.length || !timingSafeEqual(presented, stored))
+            return null;
+        // Live membership through the shared selection rule. A pinned key's pin
+        // IS the selector (fail-closed on the live membership, as always); an
+        // unpinned key selects like a session. Guest capability limits (D2) bind
+        // machine credentials too — the origin of the LIVE membership rides the
+        // principal, and accountRef carries the projection id the cloud live
+        // gate keys on (internal/federation.md).
+        const selector = row.workspaceId ?? requested;
+        let member = await resolveMembership(this.db, row.createdBy, selector);
+        if (!member && selector && this.onWorkspaceMiss && isWorkspaceSelector(selector)) {
+            // Unknown-workspace retry (cloud): the KEY verified above — the miss
+            // may be a hub org granted since the last reconcile pass. One cached
+            // reconcile, one re-run of the SAME lookup — no recursion. Covers the
+            // pin too: a pinned key into a freshly granted hub org resolves.
+            await this.onWorkspaceMiss(row.createdBy, selector);
+            member = await resolveMembership(this.db, row.createdBy, selector);
+        }
+        if (!member)
+            return null;
+        // A valid PINNED key + a header naming another workspace: reject loudly
+        // (the pre-model-change contract). Checked after the membership resolves
+        // so a dead key/membership stays the uniform 401, exactly as before. The
+        // header may name the pinned workspace by its LOCAL id or by the id of
+        // the hub organization it projects (the resolved row's accountRef,
+        // PRDCT-2947): both are the same workspace, neither is a mismatch.
+        if (row.workspaceId && requested) {
+            const named = requested.toLowerCase();
+            const isPin = named === row.workspaceId.toLowerCase() ||
+                (member.accountRef !== null && named === member.accountRef.toLowerCase());
+            if (!isPin)
+                throw new WorkspaceMismatchError();
+        }
+        // Advisory only — never correctness-load-bearing (statelessness invariant).
+        void this.db
+            .update(apiKeys)
+            .set({ lastUsedAt: sql `now()` })
+            .where(eq(apiKeys.id, row.id))
+            .catch(() => { });
+        return {
+            userId: row.createdBy,
+            email: member.email,
+            name: member.name,
+            workspaceId: member.workspaceId,
+            role: member.role,
+            origin: member.origin,
+            via: 'api_key',
+            scopes: new Set(row.scopes),
+            apiKeyId: row.id,
+            ...(row.expiresAt ? { apiKeyExpiresAt: row.expiresAt.toISOString() } : {}),
+            ...(member.accountRef ? { accountRef: member.accountRef } : {}),
+            ...(row.workspaceId ? { pinned: true } : {})
+        };
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/apikeys/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/apikeys/service.ts"],"names":[],"mappings":"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"}

package/dist/app.d.ts

@@ -0,0 +1,65 @@
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { Logger } from './logger.js';
+import type { RuntimeState } from './util/index.js';
+export interface AppDeps {
+    logger: Logger;
+    state: RuntimeState;
+    /** Directory holding the built dashboard SPA. */
+    publicDir: string;
+    /** The tool's name on the no-dashboard page, title and heading alike (`identity.displayName`). */
+    displayName: string;
+    /** The versioned API, mounted at /api/v1. */
+    api: OpenAPIHono;
+    /** The bundled MCP endpoint, mounted at /mcp (M6). */
+    mcp?: Hono;
+    /** Root-level OAuth discovery documents (/.well-known/*, M6). */
+    wellKnown?: Hono;
+    /**
+     * The tool's public routes (e.g. a public share-link viewer,
+     * /v/{secret}, Phase 4 / ADR 012). Mounted in the public-route slot:
+     * OUTSIDE /api/v1, outside the auth/scope middleware — token recipients
+     * are anonymous, the path secret is the whole credential, and every
+     * user-content response it emits is locked under `CSP: sandbox` (see
+     * viewer/routes.ts in the app).
+     */
+    publicRoutes?: Hono | undefined;
+    /** Observability middlewares + the /metrics route (M5). */
+    metricsMiddleware?: MiddlewareHandler;
+    metricsRoutes?: Hono;
+    otelMiddleware?: MiddlewareHandler;
+    /**
+     * Live readiness probe for the backing store (routes/health.ts). Omitted =
+     * /readyz keeps reporting the boot-time storage result forever.
+     */
+    probeStorage?: () => Promise<void>;
+    /** `Strict-Transport-Security` value (security-headers.ts `hstsValue`); null/absent = no HSTS. */
+    hsts?: string | null;
+    /**
+     * The tool's root middleware, installed after the metrics middleware and
+     * BEFORE every mount. E.g. a tool with VIEWER_BASE_URL (PRDCT-1352): when
+     * present, the host gate (middleware/host-gate.ts in the app) — the viewer
+     * hostname answers only `/v/*`, `/api/v1/viewer/*` and the probes, every
+     * other hostname redirects `/v/*` there. Absent = single-origin behaviour,
+     * gate not installed.
+     */
+    rootMiddleware?: MiddlewareHandler | undefined;
+    /** Extra `frame-src` origins of the dashboard CSP (e.g. a tool's viewer origin, for the preview). */
+    cspFrameSrc?: readonly string[] | undefined;
+    /** Extra `img-src` sources of the dashboard CSP (e.g. `blob:` for a tool whose dashboard shows images it fetched). */
+    cspImgSrc?: readonly string[] | undefined;
+}
+/**
+ * The SQLSTATE of a thrown Postgres error, when it is one. node-postgres puts
+ * it on `.code`; drizzle re-throws the same object untouched.
+ */
+export declare function postgresErrorCode(error: unknown): string | undefined;
+/**
+ * Assemble the single Hono app. Route precedence is load-bearing and fixed:
+ * health → (api, mcp, well-known — mounted here as the platform grows) →
+ * static assets → SPA index fallback LAST. A slot deliberately remains open
+ * before the fallback for products that add public content routes.
+ */
+export declare function createApp({ logger, state, publicDir, displayName, api, mcp, wellKnown, publicRoutes, metricsMiddleware, metricsRoutes, otelMiddleware, probeStorage, hsts, rootMiddleware, cspFrameSrc, cspImgSrc }: AppDeps): Promise<Hono>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKpD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,GAAG,EAAE,WAAW,CAAC;IACjB,sDAAsD;IACtD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,iEAAiE;IACjE,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IAChC,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC/C,qGAAqG;IACrG,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5C,sHAAsH;IACtH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIpE;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,EAC9B,MAAM,EACN,KAAK,EACL,SAAS,EACT,WAAW,EACX,GAAG,EACH,GAAG,EACH,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,IAAI,EACJ,cAAc,EACd,WAAW,EACX,SAAS,EACV,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAqIzB"}

package/dist/app.js

@@ -0,0 +1,142 @@
+import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { requestId } from './middleware/index.js';
+import { buildCsp, inlineScriptHashes, securityHeaders } from './middleware/index.js';
+import { healthRoutes } from './routes/index.js';
+/**
+ * The SQLSTATE of a thrown Postgres error, when it is one. node-postgres puts
+ * it on `.code`; drizzle re-throws the same object untouched.
+ */
+export function postgresErrorCode(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Assemble the single Hono app. Route precedence is load-bearing and fixed:
+ * health → (api, mcp, well-known — mounted here as the platform grows) →
+ * static assets → SPA index fallback LAST. A slot deliberately remains open
+ * before the fallback for products that add public content routes.
+ */
+export async function createApp({ logger, state, publicDir, displayName, api, mcp, wellKnown, publicRoutes, metricsMiddleware, metricsRoutes, otelMiddleware, probeStorage, hsts, rootMiddleware, cspFrameSrc, cspImgSrc }) {
+    const app = new Hono();
+    // The SPA fallback is read first: its inline bootstrap script hashes feed
+    // the CSP that guards every HTML response.
+    let indexHtml = null;
+    try {
+        indexHtml = await readFile(join(publicDir, 'index.html'), 'utf8');
+    }
+    catch {
+        logger.warn({ publicDir }, 'no dashboard build found — serving a placeholder at /');
+    }
+    const csp = buildCsp(indexHtml ? inlineScriptHashes(indexHtml) : [], {
+        frameSrc: [...(cspFrameSrc ?? [])],
+        imgSrc: [...(cspImgSrc ?? [])]
+    });
+    app.use('*', requestId(logger));
+    app.use('*', securityHeaders({ csp, state, hsts: hsts ?? null }));
+    // PRDCT-1809: a fail-closed boot verdict closes the whole surface — the
+    // operator-facing probes stay so the verdict is visible (/readyz carries
+    // the reason) and the process is not restarted into the same state.
+    app.use('*', async (c, next) => {
+        if (state.closed === null)
+            return next();
+        const path = c.req.path;
+        if (path === '/healthz' || path === '/readyz' || path === '/metrics')
+            return next();
+        return c.json({
+            error: {
+                code: 'service_closed',
+                message: 'This instance refuses to serve until an operator resolves a boot verdict; see /readyz'
+            }
+        }, 503);
+    });
+    if (otelMiddleware)
+        app.use('*', otelMiddleware);
+    if (metricsMiddleware)
+        app.use('*', metricsMiddleware);
+    // PRDCT-1352: the viewer-origin host gate, BEFORE every mount below — the
+    // boundary between the two hostnames must be decided before any route
+    // (and any cookie-reading middleware) runs.
+    if (rootMiddleware)
+        app.use('*', rootMiddleware);
+    // Uncaught handler errors: log with the request id, answer the wire shape.
+    app.onError((error, c) => {
+        // Malformed request bodies first: Hono's body validators throw
+        // HTTPException(400) on unparseable JSON ("Malformed JSON in request
+        // body") or broken multipart BEFORE zod runs, so the zod-openapi
+        // defaultHook never sees them — and Hono routes a thrown error straight
+        // here from the throwing handler's own dispatch frame, so an upstream
+        // try/catch middleware never observes it either. This is therefore THE
+        // seam: map the framework's 400s to the wire shape with a stable
+        // machine code instead of amplifying a pre-auth-reachable client
+        // mistake into a 500 + an error-level log. Only hono's validators throw
+        // HTTPException(400) on this app (the MCP sub-app handles its own).
+        if (error instanceof HTTPException && error.status === 400) {
+            const isJson = error.message.includes('JSON');
+            return c.json({
+                error: {
+                    code: isJson ? 'invalid_json' : 'invalid_body',
+                    message: isJson ? 'Request body is not valid JSON' : 'Malformed request body'
+                }
+            }, 400);
+        }
+        // A NUL byte (or any byte the server encoding cannot represent) that
+        // reaches Postgres inside a text value raises 22021 / 22P05. It is a
+        // CLIENT mistake, anonymously drivable on every free-text sink, but the
+        // pg error object carries the offending statement AND its bound
+        // parameters — so left alone it becomes a 500 whose error-level log line
+        // prints the SQL and the values. Contract-level `noNulString` rejects the
+        // known sinks at validation time; this is the backstop for the ones a
+        // product forgets, and it must answer 400 with no log.
+        const pgCode = postgresErrorCode(error);
+        if (pgCode === '22021' || pgCode === '22P05') {
+            return c.json({
+                error: {
+                    code: 'invalid_characters',
+                    message: 'Request contains characters that cannot be stored (e.g. a NUL byte)'
+                }
+            }, 400);
+        }
+        // JSON.stringify is recursive: a deeply nested body blows the V8 stack
+        // (`RangeError`) or exceeds the maximum string length. Both are client
+        // input, not server faults. middleware/json-depth.ts rejects these at the
+        // edge; this is the backstop for anything that builds a deep structure
+        // downstream. Narrow on the two known messages — a RangeError from
+        // anywhere else is a real bug and must stay a 500.
+        if (error instanceof RangeError &&
+            /maximum call stack size exceeded|invalid string length/i.test(error.message)) {
+            return c.json({ error: { code: 'payload_too_deep', message: 'Request payload is nested too deeply' } }, 400);
+        }
+        (c.get('logger') ?? logger).error({ err: error }, 'unhandled error');
+        return c.json({ error: { code: 'internal', message: 'Internal server error' } }, 500);
+    });
+    app.route('/', healthRoutes(state, {
+        ...(probeStorage ? { probeStorage } : {}),
+        onStorageFailure: (err) => logger.error({ err }, 'storage probe failed — reporting not ready')
+    }));
+    if (metricsRoutes)
+        app.route('/', metricsRoutes);
+    app.route('/api/v1', api);
+    if (mcp)
+        app.route('/mcp', mcp);
+    if (wellKnown)
+        app.route('/', wellKnown);
+    // The public-route slot: the share-link viewer lives here — before the
+    // static assets and the SPA fallback, after every credentialed surface.
+    if (publicRoutes)
+        app.route('/', publicRoutes);
+    app.use('*', serveStatic({ root: publicDir }));
+    app.get('*', (c) => {
+        if (indexHtml)
+            return c.html(indexHtml);
+        return c.html(`<!doctype html><title>${displayName}</title><h1>${displayName} API is running</h1>` +
+            '<p>No dashboard build found. API health: <a href="/healthz">/healthz</a></p>');
+    });
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/audit/filters.d.ts

@@ -0,0 +1,38 @@
+import { type SQL } from 'drizzle-orm';
+import { type AuditListQuery, type AuditVia } from '@antasphere/chassis-contract';
+/**
+ * The audit list's WHERE, from the validated query. Every value arrives as
+ * a bound parameter (drizzle's `eq`/`like`/`ilike` never interpolate), and
+ * the free-text ones are escaped as LIKE patterns first, so a `%` or `_` in
+ * what the admin typed matches itself rather than anything.
+ */
+/** A LIKE pattern for "contains this text", the wildcards of the text itself escaped. */
+export declare function escapeLike(value: string): string;
+/**
+ * The `action` list, split and de-duplicated: an item ending in `.` is a
+ * family (a prefix), any other item is one action. The contract has already
+ * bounded the count and the alphabet; empty items are dropped here.
+ */
+export declare function parseActionList(value: string): {
+    exact: string[];
+    families: string[];
+};
+/** The `actorVia` list, split and de-duplicated (the contract pinned the alphabet). */
+export declare function parseViaList(value: string): AuditVia[];
+/**
+ * The cursor, or null when absent, malformed or out of range. Malformed
+ * cursors serve page 1; out-of-range ones are refused the same way, since
+ * Number('99999999999999999999') is finite but past bigint precision, and
+ * sending it to the `lt(id, …)` comparison overflows in Postgres.
+ * Safe-integer is the honest bound for a JS-roundtripped bigserial id.
+ */
+export declare function cursorId(cursor: string | undefined): number | null;
+/**
+ * The filter conditions (the workspace scope and the cursor are the
+ * caller's): one AND-ed list, each member a parameterised comparison.
+ * Returns an empty list when nothing filters.
+ */
+export declare function auditFilterConditions(query: AuditListQuery): SQL[];
+/** The whole WHERE: the scope, the filters, and the keyset cursor when there is one. */
+export declare function auditWhere(scope: SQL, filters: SQL[], cursor: SQL | null): SQL;
+//# sourceMappingURL=filters.d.ts.map

package/dist/audit/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/audit/filters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuD,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAsB,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGtG;;;;;GAKG;AAEH,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAUtF;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAItD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,EAAE,CAqClE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,GAAG,GAAG,CAG9E"}