@antasphere/chassis-server 1.0.0

package/dist/jobs/timers.d.ts

@@ -0,0 +1,127 @@
+import type PgBoss from 'pg-boss';
+import type pg from 'pg';
+import type { Logger } from '../logger.js';
+/**
+ * One-off timers (PRDCT-3254): a tool runs a function ONCE at an instant or
+ * after a delay, with a JSON payload, on a queue its `jobs` slot declared.
+ * The runtime is pg-boss, the same durable queue the crons ride: a timer is a
+ * job row with `start_after` in the future, so it lives in the tool's own
+ * Postgres, survives a restart and a redeploy, and is taken by exactly one
+ * worker replica (pg-boss fetches with SKIP LOCKED). Edition-neutral, and an
+ * api-role replica schedules and cancels like any other: neither needs DDL.
+ *
+ * A KEY makes a timer replaceable: at most one PENDING timer per (queue, key).
+ * `schedule` with a key withdraws the pending timer of that key and inserts
+ * the new one in ONE transaction under a per-key advisory lock, so two
+ * replicas re-arming the same thing at once never leave two timers, and
+ * `cancel({ key })` withdraws whatever is pending under it. A timer that is
+ * already RUNNING is neither replaced nor cancelled (its handler is on it;
+ * the handler's own claim decides what it does), so a consumer keeps its
+ * at-most-once guard in the data it writes (meet's claim-before-send stamps),
+ * never in the timer alone. What a replace or a cancel DOES do to a running
+ * timer is take its retries away (`retry_limit = retry_count`): pg-boss's
+ * fail path re-inserts a failed run as a pending `retry` row with the same
+ * key, which would put the withdrawn payload back beside the new one
+ * (verifier round 1, F1). A withdrawn run that throws therefore ends
+ * `failed`, and "one pending per key" holds across the run's failure too.
+ * `cancel` itself runs without the per-key lock: a cancel concurrent with a
+ * replace may answer 0 and leave the replace's fresh timer pending (it ran
+ * first); a consumer that wants "nothing pending" cancels after its last
+ * schedule, as every path does.
+ *
+ * The payload is a plain JSON object (not an array, not a Date, nothing a
+ * `JSON.stringify` refuses): node-postgres serialises anything else into a
+ * value the `jsonb` column refuses with a raw database error, so the check is
+ * made here and answers `invalid_argument` before any statement runs.
+ *
+ * What a timer costs in pg-boss's terms: `keep_until` is `start_after` plus
+ * the queue's retention (fourteen days by default), so a timer months ahead is
+ * not archived before its time; the handler's run is bounded by the queue's
+ * `expireIn` (fifteen minutes by default); a handler that throws fails the
+ * job, retried per `retry` or the queue's own settings (pg-boss's queue
+ * default is two retries with no delay, so a handler that always throws runs
+ * three times back to back), then left `failed`.
+ *
+ * The pending-state SQL reads pg-boss's own `job` table (its schema is
+ * `PGBOSS_SCHEMA`, the column names pg-boss 10's), because pg-boss exposes no
+ * lookup by key; `timers.test.ts` pins the statements against the installed
+ * version. A pg-boss bump re-verifies them.
+ */
+/** The pg-boss schema the chassis installs (`createJobs`). */
+export declare const PGBOSS_SCHEMA = "pgboss";
+/**
+ * Advisory-lock class serializing the replace of a keyed timer, beside the
+ * migration lock (7432001), the last-owner locks (7432002 xact / 7432003
+ * session) and the pg-boss install lock (7432004). Transaction-scoped, two-int
+ * form: the class and `hashtext(queue + US + key)`.
+ */
+export declare const TIMER_KEY_LOCK_CLASS = 7432005;
+/** What a handler learns about the run beside its payload. */
+export interface TimerJob {
+    /** pg-boss's job id, the one `schedule` answered. */
+    id: string;
+    queue: string;
+    /** The dedupe key the timer was scheduled with; null without one, and on a cron's run. */
+    key: string | null;
+}
+/** When the timer fires: an instant, or a delay from now in seconds. Exactly one. */
+export type TimerWhen = {
+    at: Date;
+    inSeconds?: never;
+} | {
+    inSeconds: number;
+    at?: never;
+};
+/** How a failing handler is retried: `limit` more attempts, `delaySeconds` apart (doubled each time with `backoff`). */
+export interface TimerRetry {
+    limit: number;
+    delaySeconds?: number;
+    backoff?: boolean;
+}
+export type TimerOptions = TimerWhen & {
+    /** The dedupe key: at most one pending timer per (queue, key); a new schedule under it replaces the pending one. */
+    key?: string;
+    /** Absent: the queue's own retry settings. */
+    retry?: TimerRetry;
+};
+export type TimerRef = {
+    id: string;
+    key?: never;
+} | {
+    key: string;
+    id?: never;
+};
+export interface Timers {
+    /**
+     * Run the queue's handler once with `data`, at `at` or `inSeconds` from
+     * now. Answers the job id. Throws `TimerError` (`unknown_queue`) when the
+     * queue is not one the tool's `jobs` slot declared, `invalid_argument` on a
+     * malformed call.
+     */
+    schedule<TData extends object>(queue: string, data: TData, options: TimerOptions): Promise<string>;
+    /**
+     * Withdraw a timer that has not run yet, by its id or by its key. Answers
+     * how many pending timers were withdrawn (0 when none was pending: already
+     * run, already withdrawn, running right now, or never scheduled).
+     */
+    cancel(queue: string, ref: TimerRef): Promise<number>;
+}
+export declare class TimerError extends Error {
+    readonly code: 'unknown_queue' | 'invalid_argument';
+    constructor(code: 'unknown_queue' | 'invalid_argument', message: string);
+}
+/** The longest delay a timer takes, in seconds: a hundred years. Postgres refuses an interval written in exponent form. */
+export declare const MAX_IN_SECONDS: number;
+/** The pg-boss `startAfter` for `options`: the Date of `at`, or the delay in seconds. */
+export declare function startAfterOf(options: TimerWhen): Date | number;
+export declare class PgBossTimers implements Timers {
+    private readonly boss;
+    private readonly pool;
+    private readonly logger;
+    constructor(boss: PgBoss, pool: pg.Pool, logger: Logger);
+    schedule<TData extends object>(queue: string, data: TData, options: TimerOptions): Promise<string>;
+    cancel(queue: string, ref: TimerRef): Promise<number>;
+    /** pg-boss answers null for a queue that does not exist (its insert joins the queue row): that is an unknown queue, named. */
+    private insert;
+}
+//# sourceMappingURL=timers.d.ts.map

package/dist/jobs/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../../src/jobs/timers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE5F,wHAAwH;AACxH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG;IACrC,oHAAoH;IACpH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnG;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,qBAAa,UAAW,SAAQ,KAAK;IAEjC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB;gBAA1C,IAAI,EAAE,eAAe,GAAG,kBAAkB,EACnD,OAAO,EAAE,MAAM;CAKlB;AASD,2HAA2H;AAC3H,eAAO,MAAM,cAAc,QAA2B,CAAC;AAQvD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,CAa9D;AA+ED,qBAAa,YAAa,YAAW,MAAM;IAEvC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,MAAM,EAAE,MAAM;IAG3B,QAAQ,CAAC,KAAK,SAAS,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoClG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3D,8HAA8H;YAChH,MAAM;CAUrB"}

package/dist/jobs/timers.js

@@ -0,0 +1,228 @@
+/**
+ * One-off timers (PRDCT-3254): a tool runs a function ONCE at an instant or
+ * after a delay, with a JSON payload, on a queue its `jobs` slot declared.
+ * The runtime is pg-boss, the same durable queue the crons ride: a timer is a
+ * job row with `start_after` in the future, so it lives in the tool's own
+ * Postgres, survives a restart and a redeploy, and is taken by exactly one
+ * worker replica (pg-boss fetches with SKIP LOCKED). Edition-neutral, and an
+ * api-role replica schedules and cancels like any other: neither needs DDL.
+ *
+ * A KEY makes a timer replaceable: at most one PENDING timer per (queue, key).
+ * `schedule` with a key withdraws the pending timer of that key and inserts
+ * the new one in ONE transaction under a per-key advisory lock, so two
+ * replicas re-arming the same thing at once never leave two timers, and
+ * `cancel({ key })` withdraws whatever is pending under it. A timer that is
+ * already RUNNING is neither replaced nor cancelled (its handler is on it;
+ * the handler's own claim decides what it does), so a consumer keeps its
+ * at-most-once guard in the data it writes (meet's claim-before-send stamps),
+ * never in the timer alone. What a replace or a cancel DOES do to a running
+ * timer is take its retries away (`retry_limit = retry_count`): pg-boss's
+ * fail path re-inserts a failed run as a pending `retry` row with the same
+ * key, which would put the withdrawn payload back beside the new one
+ * (verifier round 1, F1). A withdrawn run that throws therefore ends
+ * `failed`, and "one pending per key" holds across the run's failure too.
+ * `cancel` itself runs without the per-key lock: a cancel concurrent with a
+ * replace may answer 0 and leave the replace's fresh timer pending (it ran
+ * first); a consumer that wants "nothing pending" cancels after its last
+ * schedule, as every path does.
+ *
+ * The payload is a plain JSON object (not an array, not a Date, nothing a
+ * `JSON.stringify` refuses): node-postgres serialises anything else into a
+ * value the `jsonb` column refuses with a raw database error, so the check is
+ * made here and answers `invalid_argument` before any statement runs.
+ *
+ * What a timer costs in pg-boss's terms: `keep_until` is `start_after` plus
+ * the queue's retention (fourteen days by default), so a timer months ahead is
+ * not archived before its time; the handler's run is bounded by the queue's
+ * `expireIn` (fifteen minutes by default); a handler that throws fails the
+ * job, retried per `retry` or the queue's own settings (pg-boss's queue
+ * default is two retries with no delay, so a handler that always throws runs
+ * three times back to back), then left `failed`.
+ *
+ * The pending-state SQL reads pg-boss's own `job` table (its schema is
+ * `PGBOSS_SCHEMA`, the column names pg-boss 10's), because pg-boss exposes no
+ * lookup by key; `timers.test.ts` pins the statements against the installed
+ * version. A pg-boss bump re-verifies them.
+ */
+/** The pg-boss schema the chassis installs (`createJobs`). */
+export const PGBOSS_SCHEMA = 'pgboss';
+/**
+ * Advisory-lock class serializing the replace of a keyed timer, beside the
+ * migration lock (7432001), the last-owner locks (7432002 xact / 7432003
+ * session) and the pg-boss install lock (7432004). Transaction-scoped, two-int
+ * form: the class and `hashtext(queue + US + key)`.
+ */
+export const TIMER_KEY_LOCK_CLASS = 7_432_005;
+export class TimerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TimerError';
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** pg-boss's own rule for a queue name (`Attorney.assertQueueName`), applied before any statement runs. */
+const QUEUE_NAME = /^[\w-]+$/;
+/** Unit separator: joins the queue and the key under one lock hash, and can appear in neither. */
+const US = '\u001f';
+const invalid = (message) => new TimerError('invalid_argument', `timers: ${message}`);
+/** The longest delay a timer takes, in seconds: a hundred years. Postgres refuses an interval written in exponent form. */
+export const MAX_IN_SECONDS = 100 * 365.25 * 24 * 3600;
+function assertQueue(queue) {
+    if (typeof queue !== 'string' || !QUEUE_NAME.test(queue)) {
+        throw invalid('the queue must be a name of letters, digits, underscores and hyphens');
+    }
+}
+/** The pg-boss `startAfter` for `options`: the Date of `at`, or the delay in seconds. */
+export function startAfterOf(options) {
+    const hasAt = options.at !== undefined;
+    const hasIn = options.inSeconds !== undefined;
+    if (hasAt === hasIn)
+        throw invalid('exactly one of `at` and `inSeconds` is required');
+    if (hasAt) {
+        const at = options.at;
+        if (!(at instanceof Date) || !Number.isFinite(at.getTime()))
+            throw invalid('`at` must be a valid Date');
+        return at;
+    }
+    const seconds = options.inSeconds;
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_IN_SECONDS)
+        throw invalid('`inSeconds` must be a finite number, between 0 and a hundred years');
+    return seconds;
+}
+function retryOptionsOf(retry) {
+    if (retry === undefined)
+        return {};
+    if (!Number.isInteger(retry.limit) || retry.limit < 0)
+        throw invalid('`retry.limit` must be an integer, 0 or more');
+    const delay = retry.delaySeconds ?? 0;
+    if (!Number.isInteger(delay) || delay < 0)
+        throw invalid('`retry.delaySeconds` must be an integer, 0 or more');
+    return { retryLimit: retry.limit, retryDelay: delay, retryBackoff: retry.backoff ?? false };
+}
+function assertData(data) {
+    const proto = typeof data === 'object' && data !== null ? Object.getPrototypeOf(data) : undefined;
+    if (proto !== Object.prototype && proto !== null) {
+        throw invalid('the payload must be a plain object');
+    }
+    try {
+        JSON.stringify(data);
+    }
+    catch {
+        throw invalid('the payload must be JSON (no bigint, no circular reference)');
+    }
+}
+function assertKey(key) {
+    if (typeof key !== 'string' || key.length === 0 || key.includes(US)) {
+        throw invalid('the key must be a non-empty string');
+    }
+}
+/** The one statement that withdraws pending timers: created or waiting for a retry, never running. */
+const CANCEL_PENDING = (where) => `
+  UPDATE ${PGBOSS_SCHEMA}.job
+  SET state = 'cancelled', completed_on = now()
+  WHERE name = $1 AND ${where} AND state IN ('created', 'retry')
+`;
+/**
+ * The statement that takes a RUNNING timer's retries away, so that if the
+ * run fails it ends `failed` and never comes back as a pending `retry` row
+ * under the withdrawn key or id (pg-boss retries while
+ * `retry_count < retry_limit`).
+ */
+const DISARM_ACTIVE = (where) => `
+  UPDATE ${PGBOSS_SCHEMA}.job
+  SET retry_limit = retry_count
+  WHERE name = $1 AND ${where} AND state = 'active'
+`;
+/** Withdraw the pending timers `ref` names and disarm a running one; answers the pending count withdrawn. */
+async function cancelPending(client, queue, ref) {
+    let where;
+    let value;
+    if (ref.id !== undefined) {
+        if (!UUID.test(ref.id))
+            throw invalid('the id must be a job id');
+        where = 'id = $2::uuid';
+        value = ref.id;
+    }
+    else {
+        assertKey(ref.key);
+        where = 'singleton_key = $2';
+        value = ref.key;
+    }
+    // The disarm FIRST, then the withdraw (verifier round 2, F7): pg-boss's fail
+    // path deletes the active row and re-inserts it as `retry` under the same
+    // key. Disarm first either takes the row lock before that fail (which then
+    // waits for the commit and computes `failed` on the disarmed row) or runs
+    // after it, and the withdraw, a new statement with a new snapshot, then
+    // sees the re-inserted `retry` row and cancels it. In the other order both
+    // statements could miss the row, one round trip wide. A replace whose
+    // insert then fails rolls the disarm back with it: the old run keeps its
+    // retries, a failed replace changes nothing.
+    await client.query(DISARM_ACTIVE(where), [queue, value]);
+    const res = await client.query(CANCEL_PENDING(where), [queue, value]);
+    return res.rowCount ?? 0;
+}
+export class PgBossTimers {
+    boss;
+    pool;
+    logger;
+    constructor(boss, pool, logger) {
+        this.boss = boss;
+        this.pool = pool;
+        this.logger = logger;
+    }
+    async schedule(queue, data, options) {
+        assertQueue(queue);
+        assertData(data);
+        const send = { startAfter: startAfterOf(options), ...retryOptionsOf(options.retry) };
+        if (options.key === undefined) {
+            return this.insert(queue, data, send);
+        }
+        assertKey(options.key);
+        const key = options.key;
+        // Replace = withdraw + insert in one transaction, serialized per key
+        // across replicas by a transaction-scoped advisory lock on a client of
+        // our own: pg-boss runs the insert through the `db` executor we hand it.
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            await client.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [
+                TIMER_KEY_LOCK_CLASS,
+                queue + US + key
+            ]);
+            const replaced = await cancelPending(client, queue, { key });
+            const id = await this.insert(queue, data, {
+                ...send,
+                singletonKey: key,
+                db: { executeSql: (text, values) => client.query(text, values) }
+            });
+            await client.query('COMMIT');
+            if (replaced > 0)
+                this.logger.debug({ queue, key, replaced }, 'timers: a pending timer was replaced');
+            return id;
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => { });
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async cancel(queue, ref) {
+        assertQueue(queue);
+        if ((ref.id === undefined) === (ref.key === undefined))
+            throw invalid('exactly one of `id` and `key` is required');
+        return cancelPending(this.pool, queue, ref);
+    }
+    /** pg-boss answers null for a queue that does not exist (its insert joins the queue row): that is an unknown queue, named. */
+    async insert(queue, data, send) {
+        const id = await this.boss.send(queue, data, send);
+        if (id === null) {
+            throw new TimerError('unknown_queue', `timers: the queue "${queue}" is not declared by the tool's jobs slot (a timer rides a declared queue)`);
+        }
+        return id;
+    }
+}
+//# sourceMappingURL=timers.js.map

package/dist/jobs/timers.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,17 @@
+import { type Logger } from 'pino';
+import type { Env } from './env.js';
+export type { Logger };
+/**
+ * The single redaction list — secrets never reach the log stream.
+ *
+ * Two rules when adding to it. (1) pino's `*.x` glob matches the key `x` at
+ * depth 1 ONLY, and it is an EXACT key match: `*.secret` does NOT cover
+ * `clientSecret`, `client_secret`, or `apiSecret`, so every camel/snake spelling
+ * a payload can carry needs its own entry. (2) Redaction keys off object
+ * PROPERTIES — it can do nothing about a secret interpolated into a message
+ * string. Never build a log message out of a config payload; log the shape
+ * (`{ length, path }`), never the bytes.
+ */
+export declare const REDACT_PATHS: string[];
+export declare function createLogger(env: Pick<Env, 'LOG_LEVEL' | 'NODE_ENV'>): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,YAAY,EAAE,MAAM,EAAE,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,UAiCxB,CAAC;AAEF,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CAAC,GAAG,MAAM,CAe7E"}

package/dist/logger.js

@@ -0,0 +1,64 @@
+import { pino } from 'pino';
+/**
+ * The single redaction list — secrets never reach the log stream.
+ *
+ * Two rules when adding to it. (1) pino's `*.x` glob matches the key `x` at
+ * depth 1 ONLY, and it is an EXACT key match: `*.secret` does NOT cover
+ * `clientSecret`, `client_secret`, or `apiSecret`, so every camel/snake spelling
+ * a payload can carry needs its own entry. (2) Redaction keys off object
+ * PROPERTIES — it can do nothing about a secret interpolated into a message
+ * string. Never build a log message out of a config payload; log the shape
+ * (`{ length, path }`), never the bytes.
+ */
+export const REDACT_PATHS = [
+    'req.headers.authorization',
+    'req.headers.cookie',
+    '*.password',
+    '*.secret',
+    '*.token',
+    // Exact-key spellings the `*.secret` glob misses — OAuth/hub-federation
+    // payloads carry these verbatim.
+    '*.clientSecret',
+    '*.client_secret',
+    '*.accessToken',
+    '*.access_token',
+    '*.refreshToken',
+    '*.refresh_token',
+    '*.apiKey',
+    '*.api_key',
+    'DATABASE_URL',
+    'AUTH_SECRET',
+    'API_KEY_PEPPERS',
+    'SETUP_TOKEN',
+    'METRICS_TOKEN',
+    'SMTP_URL',
+    'RESEND_API_KEY',
+    'BREVO_API_KEY',
+    'S3_SECRET_ACCESS_KEY',
+    'S3_ACCESS_KEY_ID',
+    // Optional social credential — read in env.ts, so any "here is the parsed
+    // env" line would otherwise carry it.
+    'GOOGLE_CLIENT_SECRET',
+    // Cloud edition: the hub-federation client credential (ADR 015 / user-scoped
+    // federation). It is THIS tool's identity at the Antasphere hub — leaking it
+    // lets anyone impersonate the tool at the authorization server.
+    'HUB_CLIENT_SECRET'
+];
+export function createLogger(env) {
+    const options = {
+        level: env.LOG_LEVEL,
+        redact: { paths: REDACT_PATHS, censor: '[redacted]' }
+    };
+    if (env.NODE_ENV === 'development') {
+        // pino-pretty is a devDependency; if it is absent (e.g. NODE_ENV flipped
+        // on a pruned production image) fall back to JSON instead of crashing.
+        try {
+            return pino({ ...options, transport: { target: 'pino-pretty', options: { colorize: true } } });
+        }
+        catch {
+            // fall through to JSON output
+        }
+    }
+    return pino(options);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,MAAM,CAAC;AAKzC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,2BAA2B;IAC3B,oBAAoB;IACpB,YAAY;IACZ,UAAU;IACV,SAAS;IACT,wEAAwE;IACxE,iCAAiC;IACjC,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,UAAU;IACV,WAAW;IACX,cAAc;IACd,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,eAAe;IACf,UAAU;IACV,gBAAgB;IAChB,eAAe;IACf,sBAAsB;IACtB,kBAAkB;IAClB,0EAA0E;IAC1E,sCAAsC;IACtC,sBAAsB;IACtB,6EAA6E;IAC7E,6EAA6E;IAC7E,gEAAgE;IAChE,mBAAmB;CACpB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,GAAwC;IACnE,MAAM,OAAO,GAAG;QACd,KAAK,EAAE,GAAG,CAAC,SAAS;QACpB,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE;KACtD,CAAC;IACF,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACnC,yEAAyE;QACzE,uEAAuE;QACvE,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACjG,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC"}

package/dist/mcp/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * API error → model-readable hint mapping (the predecessor MCP template's
+ * DOMAIN_HINTS pattern). The API returns `{ error: { code, message } }` on
+ * failure; each domain code can carry an actionable hint so the model
+ * self-corrects instead of retrying blindly. The table below holds the hints of
+ * the chassis' own codes; a tool adds its domain's through
+ * {@link mergeErrorHints} (the `errorHints` of its MCP definition).
+ */
+export type ErrorHints = Readonly<Record<string, string>>;
+/** The chassis hints plus a tool's own: ONE table, the one every lookup reads. */
+export declare function mergeErrorHints(toolHints: ErrorHints): ErrorHints;
+/** Thrown when the in-process API call returns a non-2xx wire-shape response. */
+export declare class ApiToolError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    /** The wire's `error.details`, when the API sent any (a plan refusal's upgrade link rides here). */
+    readonly details: unknown;
+    constructor(status: number, code: string | null, message: string, details?: unknown);
+    toUserFacingText(hints?: ErrorHints): string;
+}
+export interface ToolTextResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: true;
+}
+export declare const jsonText: (result: unknown) => ToolTextResult;
+export declare const deny: (text: string) => ToolTextResult;
+/**
+ * Wrap a tool body so any thrown ApiToolError surfaces as a structured MCP
+ * tool error (`isError: true` + text) rather than a protocol-level exception.
+ * Other errors propagate to the SDK.
+ */
+export declare function wrapToolErrors(fn: () => Promise<ToolTextResult>, hints?: ErrorHints): Promise<ToolTextResult>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/mcp/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/mcp/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAmB1D,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAEjE;AAED,iFAAiF;AACjF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,oGAAoG;IACpG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAQnF,gBAAgB,CAAC,KAAK,GAAE,UAAyB,GAAG,MAAM;CA2B3D;AAED,MAAM,WAAW,cAAc;IAE7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED,eAAO,MAAM,QAAQ,GAAI,QAAQ,OAAO,KAAG,cAEzC,CAAC;AAEH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,KAAG,cAGlC,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,EACjC,KAAK,GAAE,UAAyB,GAC/B,OAAO,CAAC,cAAc,CAAC,CASzB"}

package/dist/mcp/errors.js

@@ -0,0 +1,77 @@
+const DOMAIN_HINTS = {
+    insufficient_scope: 'Reconnect the MCP server and approve the permission on the consent screen ' +
+        '(or mint an API key that includes the scope).',
+    endpoint_not_allowed: 'This endpoint is not opened to machine credentials — a human must do this in the dashboard.',
+    invalid_token: 'The OAuth token expired or was revoked. Reconnect the MCP server.',
+    unauthenticated: 'No valid credential reached the API. Reconnect the MCP server.',
+    rate_limited: 'Rate limited — wait before retrying.',
+    plan_required: 'The workspace\u2019s plan does not allow this — the upgrade link in this message is where a human raises it.',
+    // The same code on both editions: the cloud's credit refusal (402, with the
+    // top-up link) and a self-hosted instance's cap (413, no details).
+    entitlement_denied: 'The instance refused this action: on the cloud the organization lacks the credits and the top-up link in this message is where a human adds them, or the quantity is beyond what can be priced and no top-up covers it (no link then); on a self-hosted instance the request exceeds the operator’s cap.'
+};
+/** The chassis hints plus a tool's own: ONE table, the one every lookup reads. */
+export function mergeErrorHints(toolHints) {
+    return { ...DOMAIN_HINTS, ...toolHints };
+}
+/** Thrown when the in-process API call returns a non-2xx wire-shape response. */
+export class ApiToolError extends Error {
+    status;
+    code;
+    /** The wire's `error.details`, when the API sent any (a plan refusal's upgrade link rides here). */
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = 'ApiToolError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+    toUserFacingText(hints = DOMAIN_HINTS) {
+        const hint = this.code ? hints[this.code] : undefined;
+        const codePart = this.code ? `, code: ${this.code}` : '';
+        // A plan refusal carries its upgrade link (the billing rail, §7): the
+        // agent relays it, a human follows it. Text, never a structured field.
+        const upgradeUrl = this.details?.upgradeUrl;
+        const upgrade = typeof upgradeUrl === 'string' && upgradeUrl ? ` Upgrade: ${upgradeUrl}` : '';
+        // A credit refusal (402 `entitlement_denied`, PRDCT-2664) carries its
+        // top-up link, the price and the balance: the same, as text. The
+        // self-hosted cap's 413 has no details, so no top-up sentence.
+        const { topUpUrl, credits, balance } = (this.details ?? {});
+        let topUp = '';
+        // The gate's message already carries the link, the price and the balance;
+        // the sentence is added only for a message that does not (verifier
+        // round 1: the URL was printed twice).
+        if (typeof topUpUrl === 'string' && topUpUrl && !this.message.includes(topUpUrl)) {
+            const needs = typeof credits === 'number' ? [`this needs ${credits} credits`] : [];
+            const holds = typeof balance === 'number' ? [`the organization holds ${balance}`] : [];
+            const numbers = [...needs, ...holds].join(', ');
+            topUp = ` Top up: ${topUpUrl}${numbers ? ` (${numbers}).` : ''}`;
+        }
+        return `API error (HTTP ${this.status}${codePart}): ${this.message}${hint ? ` — Next: ${hint}` : ''}${upgrade}${topUp}`;
+    }
+}
+export const jsonText = (result) => ({
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+});
+export const deny = (text) => ({
+    content: [{ type: 'text', text }],
+    isError: true
+});
+/**
+ * Wrap a tool body so any thrown ApiToolError surfaces as a structured MCP
+ * tool error (`isError: true` + text) rather than a protocol-level exception.
+ * Other errors propagate to the SDK.
+ */
+export async function wrapToolErrors(fn, hints = DOMAIN_HINTS) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof ApiToolError) {
+            return { content: [{ type: 'text', text: err.toUserFacingText(hints) }], isError: true };
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/mcp/errors.js.map

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

package/dist/mcp/http.d.ts

@@ -0,0 +1,35 @@
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+import type { Principal } from '@antasphere/chassis-contract';
+import { type McpIdentity, type McpToolDefinition } from './server.js';
+/**
+ * The bundled /mcp endpoint (streamable HTTP, STATELESS — see ADR 002).
+ *
+ * Auth gate first: a valid OAuth bearer (token this instance minted) or an
+ * API key — both machine principals, resolved through the same machinery as
+ * /api/v1. Anything else gets the RFC 9728 401 challenge whose
+ * `resource_metadata` URL drives the whole client OAuth dance.
+ *
+ * Stateless transport: a fresh McpServer + transport per request, no session
+ * ids, no in-process stream state — the platform's statelessness invariant
+ * applies to MCP too (any replica can serve any request).
+ */
+export interface McpHttpDeps {
+    publicBaseUrl: string;
+    version: string;
+    /** In-process fetch against the root app; tools forward the caller's bearer. */
+    fetchApi: (path: string, init?: RequestInit) => Promise<Response>;
+    resolveOauthJwt: (token: string) => Promise<Principal | null>;
+    resolveApiKey: (token: string) => Promise<Principal | null>;
+    isApiKeyToken: (token: string) => boolean;
+    /** Instance display name for the server instructions (cached by the caller). */
+    instanceName: () => Promise<string>;
+    /** Per-IP rate limit, applied before the auth gate (floods rejected cheaply). */
+    limiter: MiddlewareHandler;
+    /** The tool's MCP definition: its tools, instructions, error hints and scope names. */
+    tool: McpToolDefinition;
+    /** The server's name and the tool names' prefix (`identity.mcp`). */
+    identity: McpIdentity;
+}
+export declare function mcpRoutes(deps: McpHttpDeps): Hono;
+//# sourceMappingURL=http.d.ts.map

package/dist/mcp/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAI9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC9D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC5D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,gFAAgF;IAChF,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,iFAAiF;IACjF,OAAO,EAAE,iBAAiB,CAAC;IAC3B,uFAAuF;IACvF,IAAI,EAAE,iBAAiB,CAAC;IACxB,qEAAqE;IACrE,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAyFjD"}