@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/types/identity/index.d.ts

@@ -1,51 +1,189 @@
 import type { AuthUser } from '../types/index.js';
 /**
- * Header contract between the gateway and downstream services.
+ * Gateway identity protocol, version 2.
  *
- * The gateway strips any client-supplied identity headers, then writes these and signs them with
- * `x-gateway-auth` = HMAC-SHA256(secret, canonical string). Services verify the signature and
- * timestamp before trusting anything, so a request that bypasses the gateway on the internal
- * network cannot forge an identity.
+ * The gateway strips every client-supplied identity header, writes the headers below for the
+ * authenticated caller and signs them with `x-gateway-signature: v2=<hex>`. The signature is an
+ * HMAC-SHA256 over an app-chosen domain separator, the HTTP method, the canonical path (no query),
+ * the gateway timestamp and every identity header in a fixed order. A request that bypasses the
+ * gateway, is replayed later, or is replayed against another route cannot carry a forged identity.
+ *
+ * App-specific identity fields (for example a tenant id) travel in their own headers through an
+ * {@link IdentityProtocol} mapping, so this module never names an app concept.
  */
 export declare const IDENTITY_HEADERS: {
     readonly USER_ID: "x-user-id";
     readonly USER_EMAIL: "x-user-email";
     readonly USER_ROLES: "x-user-roles";
     readonly USER_PERMISSIONS: "x-user-permissions";
+    readonly SUPER_ADMIN: "x-is-superadmin";
+    readonly OTP_VERIFIED: "x-otp-verified";
+    readonly STEP_UP_AT: "x-step-up-at";
+    readonly SESSION_ID: "x-session-id";
     readonly USER_SCOPES: "x-user-scopes";
     readonly USER_ATTRS: "x-user-attrs";
-    readonly SESSION_ID: "x-session-id";
     readonly TIMESTAMP: "x-gateway-ts";
-    readonly SIGNATURE: "x-gateway-auth";
+    readonly SIGNATURE: "x-gateway-signature";
 };
+/** Non-identity request headers shared by the gateway and services (correlation, client hints, internal auth). */
 export declare const CONTEXT_HEADERS: {
     readonly CORRELATION_ID: "x-correlation-id";
     readonly ANON_ID: "x-anon-id";
     readonly TIMEZONE: "x-timezone";
     readonly CLIENT_IP: "x-client-ip";
     readonly INTERNAL_SECRET: "x-internal-service-secret";
-    readonly CALLER_SERVICE: "x-caller-service";
+    readonly INTERNAL_SERVICE_NAME: "x-internal-service-name";
+    readonly IDEMPOTENCY_KEY: "idempotency-key";
 };
-/** Every header a client must never be allowed to set. */
-export declare const PROTECTED_HEADERS: readonly string[];
-type HeaderBag = Record<string, string | string[] | undefined>;
-/** Gateway side: headers (including signature) that represent `user`. */
-export declare function signIdentityHeaders(user: AuthUser, secret: string, now?: number): Record<string, string>;
+/** Signature version prefix: `x-gateway-signature: v2=<hex>`. */
+export declare const GATEWAY_SIGNATURE_VERSION = "v2";
+/** Default maximum age of a gateway timestamp (replay window). */
+export declare const DEFAULT_IDENTITY_MAX_AGE_MS = 30000;
+/** Default allowance for a gateway clock that runs ahead of the service clock. */
+export declare const DEFAULT_IDENTITY_MAX_FUTURE_MS = 5000;
+/** Minimum length of the shared gateway signing secret. */
+export declare const MIN_GATEWAY_SECRET_LENGTH = 32;
+/** App binding of the identity protocol: domain separator plus app-specific identity headers. */
+export interface IdentityProtocolInput {
+    /** Domain separator mixed into every signature, e.g. `"<app>-gateway-identity:v2"`. Two apps never verify each other. */
+    domain: string;
+    /** Scope key → header carrying that scope's ids (comma-separated). Signed after the email header, in declaration order. */
+    scopeHeaders?: Readonly<Record<string, string>>;
+    /** Attr key → header carrying that string attribute. Signed after the scope headers, in declaration order. */
+    attrHeaders?: Readonly<Record<string, string>>;
+}
+/** A validated identity protocol. Build it once with {@link defineIdentityProtocol}. */
+export interface IdentityProtocol {
+    readonly domain: string;
+    readonly scopeHeaders: Readonly<Record<string, string>>;
+    readonly attrHeaders: Readonly<Record<string, string>>;
+    /** Every identity header in signing order (excludes the timestamp and signature headers). */
+    readonly headerOrder: readonly string[];
+}
+/**
+ * Validates and freezes an app's identity protocol. Throws at startup on a bad binding so a
+ * misconfiguration can never weaken verification at runtime.
+ *
+ * @param input Domain separator and optional scope/attr header mappings.
+ * @returns The frozen protocol, including the signing order.
+ * @example const protocol = defineIdentityProtocol({ domain: 'shop-gateway-identity:v2', scopeHeaders: { tenant: 'x-tenant-id' } });
+ */
+export declare function defineIdentityProtocol(input: IdentityProtocolInput): IdentityProtocol;
+/**
+ * Every header a client must never be allowed to set, for a given protocol: identity headers, the gateway
+ * timestamp and signature, both internal-service headers and the client IP.
+ *
+ * @param protocol The app's identity protocol.
+ * @returns Lower-case header names.
+ * @example const blocked = new Set(protectedHeaders(protocol));
+ */
+export declare function protectedHeaders(protocol: IdentityProtocol): string[];
+/**
+ * Removes every protected header in place (gateway ingress), so clients can't forge identity or internal auth.
+ *
+ * @param headers Incoming request headers (mutated).
+ * @param protocol The app's identity protocol.
+ * @example stripProtectedHeaders(req.headers, protocol);
+ */
+export declare function stripProtectedHeaders(headers: HeaderBag, protocol: IdentityProtocol): void;
+/** Node-style request headers (lower-case names; repeated headers as arrays). */
+export type HeaderBag = Record<string, string | string[] | undefined>;
+/**
+ * Canonical request path for signing: the path only (query and fragment dropped), always starting with `/`.
+ *
+ * @param path A path or path-plus-query such as `req.originalUrl`.
+ * @returns The path to sign or verify.
+ * @example canonicalPath('/v1/items?page=2') // '/v1/items'
+ */
+export declare function canonicalPath(path: string): string;
+/**
+ * Gateway side: the identity header values (unsigned) that represent `user` under `protocol`.
+ * Mapped scopes and string attrs travel in their own headers; the rest go in the JSON headers.
+ *
+ * @param user The authenticated caller.
+ * @param protocol The app's identity protocol.
+ * @returns Header name → value for every header in `protocol.headerOrder`.
+ * @example const identity = buildIdentityHeaders(user, protocol);
+ */
+export declare function buildIdentityHeaders(user: AuthUser, protocol: IdentityProtocol): Record<string, string>;
+/** Inputs to {@link signGatewayIdentity}. */
+export interface SignGatewayIdentityInput {
+    method: string;
+    /** Path the downstream service will see; any query string is ignored. */
+    path: string;
+    /** Identity header values, e.g. from {@link buildIdentityHeaders}. Missing headers sign as empty. */
+    identity: Record<string, string>;
+    /** Gateway timestamp, epoch milliseconds (sent as `x-gateway-ts`). */
+    ts: number;
+    secret: string;
+    protocol: IdentityProtocol;
+}
+/**
+ * Signs an identity for one request.
+ *
+ * @param input Method, path, identity headers, timestamp, secret and protocol.
+ * @returns The `x-gateway-signature` value, `v2=<hex>`.
+ * @example headers['x-gateway-signature'] = signGatewayIdentity({ method, path, identity, ts, secret, protocol });
+ */
+export declare function signGatewayIdentity(input: SignGatewayIdentityInput): string;
+/** Inputs to {@link signedIdentityHeaders}. */
+export interface SignedIdentityHeadersInput {
+    user: AuthUser;
+    method: string;
+    path: string;
+    secret: string;
+    protocol: IdentityProtocol;
+    /** Epoch milliseconds; defaults to now. */
+    now?: number;
+}
+/**
+ * Gateway side convenience: every identity header plus `x-gateway-ts` and `x-gateway-signature`. Also used by a
+ * service acting for a user to re-sign the identity for one internal call (signatures bind method and path).
+ *
+ * @param input User, method, path, secret, protocol and optional time.
+ * @returns Headers to add to the outgoing request.
+ *
+ * @example Object.assign(proxyHeaders, signedIdentityHeaders({ user, method: req.method, path: upstreamPath, secret, protocol }));
+ */
+export declare function signedIdentityHeaders(input: SignedIdentityHeadersInput): Record<string, string>;
+/** Why {@link verifyGatewayIdentity} rejected an identity (logged and passed to `onRejected`; never header values). */
+export type IdentityRejection = 'missing-signature' | 'bad-version' | 'bad-timestamp' | 'stale' | 'future' | 'bad-signature' | 'bad-payload';
 export type IdentityResult = {
     status: 'anonymous';
 } | {
     status: 'invalid';
-    reason: string;
+    reason: IdentityRejection;
 } | {
     status: 'authenticated';
     user: AuthUser;
 };
-/** Service side: verifies and decodes the gateway identity headers. */
-export declare function verifyIdentityHeaders(headers: HeaderBag, secret: string, options?: {
-    maxSkewMs?: number;
+/** Inputs to {@link verifyGatewayIdentity}. */
+export interface VerifyGatewayIdentityInput {
+    headers: HeaderBag;
+    method: string;
+    /** The path as received, e.g. `req.originalUrl`; the query is ignored. */
+    path: string;
+    secret: string;
+    protocol: IdentityProtocol;
     now?: number;
-}): IdentityResult;
-/** Removes every protected header in place (gateway ingress). */
-export declare function stripProtectedHeaders(headers: HeaderBag): void;
-export {};
+    maxAgeMs?: number;
+    maxFutureMs?: number;
+}
+/**
+ * Service side: verifies and decodes the gateway identity. No `x-user-id` → anonymous. Otherwise the
+ * request is rejected unless the signature is present, version `v2`, made for this method, path and
+ * protocol, and the timestamp is at most `maxAgeMs` old (default 30 s) and at most `maxFutureMs` ahead
+ * (default 5 s). The comparison is constant-time.
+ *
+ * @example const result = verifyGatewayIdentity({ headers: req.headers, method: req.method, path: req.originalUrl, secret, protocol });
+ */
+export declare function verifyGatewayIdentity(input: VerifyGatewayIdentityInput): IdentityResult;
+/**
+ * Throws unless `secret` is long enough to sign identities. Call at startup.
+ *
+ * @param secret The shared gateway signing secret (env `GATEWAY_SIGNING_SECRET`).
+ * @returns The secret, unchanged.
+ */
+export declare function assertGatewaySecret(secret: string | undefined): string;
+export * from './step-up.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/identity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/identity/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAqG,CAAC;AAIrJ,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAiC/D,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAapH;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhD,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CA6B5I;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAE9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/identity/index.ts"],"names":[],"mappings":"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"}

package/dist/types/identity/step-up.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Step-up (re-authentication) scopes. The gateway checks the client's step-up proof for the route's
+ * scope and forwards the verified time as the signed `x-step-up-at` header; services only check that
+ * the time is fresh. Scope names and their rules are app values, declared once with
+ * {@link defineStepUpScopes}.
+ */
+/** Rules for one step-up scope. */
+export interface StepUpScopeDefinition {
+    /** The step-up proof may be used for one request only (the gateway consumes it). */
+    singleUse?: boolean;
+    /** Short note for docs and the route registry. */
+    description?: string;
+}
+/** A frozen scope catalogue, keyed by scope name. */
+export type StepUpCatalogue<S extends string = string> = Readonly<Record<S, Readonly<StepUpScopeDefinition>>>;
+/** Default freshness window for a step-up verification. */
+export declare const DEFAULT_STEP_UP_WINDOW_MS: number;
+/** A step-up time this far ahead of the service clock is still accepted (clock skew). */
+export declare const STEP_UP_MAX_FUTURE_MS = 5000;
+/** Error code of the 403 a service returns when a fresh step-up is required. */
+export declare const STEP_UP_REQUIRED_CODE = "STEP_UP_REQUIRED";
+/**
+ * Validates and freezes an app's step-up scope catalogue (kebab-case names). Throws at startup on a bad name.
+ *
+ * @param catalogue Scope name → rules.
+ * @returns The frozen catalogue; its keys type `requireStepUp`'s scope argument.
+ * @example export const stepUpScopes = defineStepUpScopes({ 'refund-large': {}, 'payout-destination': { singleUse: true } });
+ */
+export declare function defineStepUpScopes<S extends string>(catalogue: Record<S, StepUpScopeDefinition>): StepUpCatalogue<S>;
+export type StepUpStatus = 'fresh' | 'missing' | 'stale' | 'future';
+/**
+ * Whether a gateway-verified step-up time is usable now.
+ *
+ * @param stepUpAt Epoch milliseconds of the step-up, or undefined when none was made.
+ * @param windowMs How old the step-up may be.
+ * @param now Current epoch milliseconds.
+ * @returns `fresh` when usable; otherwise why not.
+ * @example stepUpStatus(req.user?.stepUpAt, DEFAULT_STEP_UP_WINDOW_MS) === 'fresh'
+ */
+export declare function stepUpStatus(stepUpAt: number | undefined, windowMs: number, now?: number): StepUpStatus;
+//# sourceMappingURL=step-up.d.ts.map

package/dist/types/identity/step-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../../../src/identity/step-up.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAE9G,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,QAAa,CAAC;AACpD,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAIxD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,EAAE,qBAAqB,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAOpH;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,YAAY,CAInH"}

package/dist/types/index.d.ts

@@ -1,10 +1,17 @@
 export * from './types/index.js';
 export * from './common/index.js';
+export * from './context/index.js';
 export * from './identity/index.js';
 export * from './access/index.js';
 export * from './validation/index.js';
 export * from './logging/index.js';
 export * from './config/index.js';
+export * from './cache/keyspace.js';
+export * from './rate-limit/keys.js';
 export * from './contracts/index.js';
 export * from './alerting/index.js';
+export * from './database/pagination.js';
+export * from './audit/index.js';
+export * from './approvals/index.js';
+export * from './socket/ticket.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/types/knex/columns.d.ts

@@ -0,0 +1,15 @@
+import type { Knex } from 'knex';
+/** Column primitives shared by every migration helper (one definition of ULID and DATETIME(3) columns). */
+/** `id CHAR(26)` primary key for ULIDs. */
+export declare function ulidPrimary(table: Knex.CreateTableBuilder, name?: string): void;
+/** `CHAR(26)` column referencing another ULID (FK constraints only within the same database). */
+export declare function ulidColumn(table: Knex.CreateTableBuilder | Knex.AlterTableBuilder, name: string): Knex.ColumnBuilder;
+/** `created_at` / `updated_at` as `DATETIME(3)` in UTC, maintained by MySQL. */
+export declare function timestamps(table: Knex.CreateTableBuilder, knex: Knex): void;
+/** `created_by` / `updated_by` actor columns (null for system operations). */
+export declare function actorColumns(table: Knex.CreateTableBuilder): void;
+/** Nullable `DATETIME(3)` column. */
+export declare function datetime(table: Knex.CreateTableBuilder | Knex.AlterTableBuilder, name: string): Knex.ColumnBuilder;
+/** `DATETIME(3)` column defaulting to `CURRENT_TIMESTAMP(3)` (insert time, UTC). */
+export declare function createdAtColumn(table: Knex.CreateTableBuilder, knex: Knex, name?: string): Knex.ColumnBuilder;
+//# sourceMappingURL=columns.d.ts.map

package/dist/types/knex/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../../src/knex/columns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC,2GAA2G;AAE3G,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,SAAO,GAAG,IAAI,CAE7E;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAEpH;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAG3E;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAGjE;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAElH;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAe,GAAG,IAAI,CAAC,aAAa,CAEnH"}

package/dist/types/knex/index.d.ts

@@ -1,24 +1,16 @@
 import type { Knex } from 'knex';
+export * from './columns.js';
+export * from './migration-helpers.js';
 /**
  * Migration helpers (usable from CommonJS `.cjs` migrations via `require('@heavybit/shared-lib/knex')`).
  * They keep ID, timestamp and audit column definitions identical across services.
  */
-/** `id CHAR(26)` primary key for ULIDs. */
-export declare function ulidPrimary(table: Knex.CreateTableBuilder, name?: string): void;
-/** `CHAR(26)` column referencing another ULID (FK constraints only within the same database). */
-export declare function ulidColumn(table: Knex.CreateTableBuilder | Knex.AlterTableBuilder, name: string): Knex.ColumnBuilder;
-/** `created_at` / `updated_at` as `DATETIME(3)` in UTC, maintained by MySQL. */
-export declare function timestamps(table: Knex.CreateTableBuilder, knex: Knex): void;
-/** `created_by` / `updated_by` actor columns (null for system operations). */
-export declare function actorColumns(table: Knex.CreateTableBuilder): void;
-/** Nullable `DATETIME(3)` column. */
-export declare function datetime(table: Knex.CreateTableBuilder | Knex.AlterTableBuilder, name: string): Knex.ColumnBuilder;
 /**
  * Creates `<parent>_audits`: every parent column (defined again by `columns`) plus `parent_id`
  * and `action`. Audit rows are append-only history, so no unique constraints are copied.
  */
 export declare function createAuditTable(knex: Knex, parentTable: string, columns: (table: Knex.CreateTableBuilder) => void): Promise<void>;
-/** Transactional outbox table used by `OutboxRelay`. */
+/** Transactional outbox table used by `OutboxRelay` (columns from {@link outboxColumns}). */
 export declare function createOutboxTable(knex: Knex, name?: string): Promise<void>;
 /** Standard table options: InnoDB, utf8mb4. Call inside `createTable`. */
 export declare function utf8mb4(table: Knex.CreateTableBuilder): void;

package/dist/types/knex/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC;;;GAGG;AAEH,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,SAAO,GAAG,IAAI,CAE7E;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAEpH;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAG3E;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAGjE;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,CAElH;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxI;AAED,wDAAwD;AACxD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxF;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAI5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AAEvC;;;GAGG;AAEH;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxI;AAED,6FAA6F;AAC7F,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9F;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAI5D"}

package/dist/types/knex/migration-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { Knex } from 'knex';
+/**
+ * Column sets for infrastructure tables, for `.cjs` migrations. Each matches the Drizzle table of
+ * the same purpose in `@heavybit/shared-lib/database` (`outboxTable`, `processedEventsTable`,
+ * `schedulerRunsTable`); a test keeps the two in step.
+ *
+ * @example
+ * await knex.schema.createTable('processed_events', (t) => processedEventsColumns(t, knex));
+ */
+type Builder = Knex.CreateTableBuilder;
+/**
+ * Outbox columns: id, routing_key, exchange, payload, correlation_id, attempts, last_error, created_at,
+ * published_at (+ relay index).
+ */
+export declare function outboxColumns(t: Builder, knex: Knex): void;
+/** Consumer idempotency columns: id, consumer, event_id (unique together), processed_at. */
+export declare function processedEventsColumns(t: Builder, knex: Knex): void;
+/** Scheduler run columns: id, job, run_key (unique together), status, error, started_at, finished_at. */
+export declare function schedulerRunsColumns(t: Builder, knex: Knex): void;
+/**
+ * Index that always leads with the scope column (TEN-4); `columns` follow in order, duplicates of
+ * the scope column are dropped.
+ *
+ * @example scopedIndex(t, 'workspace_id', ['status', 'created_at'])
+ */
+export declare function scopedIndex(t: Builder | Knex.AlterTableBuilder, scopeColumn: string, columns?: string[], indexName?: string): void;
+export {};
+//# sourceMappingURL=migration-helpers.d.ts.map

package/dist/types/knex/migration-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-helpers.d.ts","sourceRoot":"","sources":["../../../src/knex/migration-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAIjC;;;;;;;GAOG;AAEH,KAAK,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC;AAGvC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAW1D;AAED,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAOnE;AAED,yGAAyG;AACzG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAUjE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,EAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAGtI"}

package/dist/types/logging/index.d.ts

@@ -1,14 +1,35 @@
+import type { Writable } from 'node:stream';
 import winston from 'winston';
 import type { Logger } from '../types/index.js';
-/** Keys whose values are replaced with `[REDACTED]` anywhere in log metadata. */
-export declare const DEFAULT_REDACT_KEYS: string[];
+export { DEFAULT_ALLOW_KEYS, DEFAULT_REDACT_KEYS, REDACTED, createKeyClassifier, maskPhoneForLog, maskPhonesInText, redactValue } from './redact.js';
+export type { KeyClassifier } from './redact.js';
+/** Options for {@link createLogger}. */
 export interface LoggerOptions {
+    /** Minimum level; defaults to `LOG_LEVEL`, else `info` in production and `debug` elsewhere. */
     level?: string;
-    /** `json` for machines (default in production), `pretty` for humans. */
+    /** `json` for machines (default in production), `pretty` for humans. Files and streams are always JSON. */
     format?: 'json' | 'pretty';
+    /** Extra sensitive words, matched like {@link DEFAULT_REDACT_KEYS} (e.g. `nationalId`). */
     redactKeys?: string[];
+    /** Exact keys never redacted; replaces {@link DEFAULT_ALLOW_KEYS}. */
+    allowKeys?: string[];
+    /** Also append JSON lines to this file (e.g. `logs/api.log`). */
+    filePath?: string;
+    /** Also write JSON lines to this stream (log shippers, tests). */
+    stream?: Writable;
 }
-/** Structured logger with secret redaction. JSON to stdout in production, pretty otherwise. */
+/**
+ * Structured logger. Every line carries `service` and, inside a request or {@link runWithContext}, the
+ * context's `correlationId`, `userId` and `scopes`. Secrets are redacted by key word (see
+ * {@link DEFAULT_REDACT_KEYS}) and phone numbers are masked to their last 4 digits, in the message and
+ * at any depth of the metadata. Writes to stdout (JSON in production, pretty otherwise; silent under
+ * `NODE_ENV=test` unless `LOG_IN_TESTS` is set) plus an optional file and stream.
+ *
+ * @param service Service name on every line.
+ * @param options Level, format, extra redact/allow keys, file path, stream.
+ * @returns A winston logger that satisfies {@link Logger}.
+ * @example const logger = createLogger('api', { filePath: 'logs/api.log' });
+ */
 export declare function createLogger(service: string, options?: LoggerOptions): winston.Logger & Logger;
 /** Logger that discards everything — handy default for libraries and tests. */
 export declare const silentLogger: Logger;
@@ -17,6 +38,11 @@ export declare const silentLogger: Logger;
  * meta wins on a key clash. `undefined` context values are dropped so lines never carry empty keys.
  * Works over any {@link Logger} (winston, a test spy, or another child), so handlers can create one
  * per message and pass it down.
+ *
+ * @param logger The logger to write through.
+ * @param context Values added to every line.
+ * @returns A {@link Logger}.
+ * @example const log = childLogger(logger, { jobId });
  */
 export declare function childLogger(logger: Logger, context: Record<string, unknown>): Logger;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/logging/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,UAG/B,CAAC;AA6BF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAiBlG;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY,EAAE,MAA6E,CAAC;AAEzG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKpF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrJ,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2CjD,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAqBlG;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY,EAAE,MAA6E,CAAC;AAEzG;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKpF"}

package/dist/types/logging/redact.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Secret redaction and phone masking for log lines. Matching is by key *word*, not substring: a key is
+ * split on camelCase and separators (`refresh_token` → `refresh`, `token`; `OTPCode` → `otp`, `code`),
+ * and it is sensitive when a word (or two adjacent words joined, e.g. `api`+`key`) equals a listed term
+ * or its plural. So `accessToken` and `Set-Cookie` are redacted while `pinned` or `spinner` are not.
+ */
+/** Words whose values are always replaced with `[REDACTED]`. Apps add their own via `redactKeys`. */
+export declare const DEFAULT_REDACT_KEYS: readonly string[];
+/** Keys that are never redacted although they contain a listed word (error, status and reference codes). */
+export declare const DEFAULT_ALLOW_KEYS: readonly string[];
+/** The marker that replaces a secret value. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Masks every digit except the last four; the same rule as `maskPhone` in common (one rule for logs and UI).
+ *
+ * @param value A phone number in any format.
+ * @returns e.g. `********5678`; values with fewer than 5 digits are fully masked.
+ * @example maskPhoneForLog('15551234567') // '*******4567'
+ */
+export declare const maskPhoneForLog: (value: string) => string;
+/**
+ * Masks phone-number-looking runs inside free text.
+ *
+ * @param text Any string (a log message or value).
+ * @returns The text with each 9–15 digit run masked to its last 4 digits.
+ * @example maskPhonesInText('OTP sent to 15551234567') // 'OTP sent to *******4567'
+ */
+export declare function maskPhonesInText(text: string): string;
+/** Decides, per key, whether a value is a secret, a phone number or neither. */
+export interface KeyClassifier {
+    isSecret(key: string): boolean;
+    isPhone(key: string): boolean;
+}
+/**
+ * Builds a key classifier from the default terms plus app-specific ones.
+ *
+ * @param extraKeys Extra words (matched like the defaults, case-insensitive).
+ * @param allowKeys Exact keys never treated as secret (defaults to {@link DEFAULT_ALLOW_KEYS}).
+ * @returns The classifier.
+ * @example createKeyClassifier(['nationalId']).isSecret('nationalId') // true
+ */
+export declare function createKeyClassifier(extraKeys?: readonly string[], allowKeys?: readonly string[]): KeyClassifier;
+/**
+ * Returns a copy of `value` with secrets replaced by `[REDACTED]` and phone numbers masked, at any depth
+ * (up to 8 levels; deeper values are dropped as `[TRUNCATED]`). Errors are kept as-is.
+ *
+ * @param value Log metadata (object, array or scalar).
+ * @param classifier From {@link createKeyClassifier}.
+ * @param depth Internal recursion depth; callers omit it.
+ * @returns The redacted copy; the input is not modified.
+ * @example redactValue({ user: { otp: '1234', phone: '15551234567' } }, createKeyClassifier())
+ */
+export declare function redactValue(value: unknown, classifier: KeyClassifier, depth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/types/logging/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAGhD,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAwF,CAAC;AAQzI,+CAA+C;AAC/C,eAAO,MAAM,QAAQ,eAAe,CAAC;AAGrC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAkB,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,EAAE,SAAS,GAAE,SAAS,MAAM,EAAuB,GAAG,aAAa,CAgBvI;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,OAAO,CAYzF"}

package/dist/types/messaging/base-consumer.d.ts

@@ -0,0 +1,33 @@
+import type { InboundMessage, MessageConsumer, SubscriptionOptions } from './consumer.js';
+/** Everything a subscription needs except the handler, which a {@link BaseConsumer} subclass supplies. */
+export type ConsumerDefinition<T, TTx> = Omit<SubscriptionOptions<T, TTx>, 'handler'>;
+/**
+ * Base for a service's queue consumers (one class per queue in `src/consumers/`). The subclass declares
+ * its queue, bindings, payload schema, retry policy, dedupe and scope in the constructor and implements
+ * {@link BaseConsumer.handle}; `worker.ts` registers it. Validation, dedupe, retries, dead-lettering and
+ * context restore are done by {@link MessageConsumer}.
+ *
+ * @typeParam T Validated payload type.
+ * @typeParam TTx Dedupe transaction type (`DbExecutor` with `ProcessedEventsDeduper`).
+ * @example
+ * class ThingCreatedConsumer extends BaseConsumer<ThingCreated, DbExecutor> {
+ *   constructor(private readonly things: ThingService, dedupe: ProcessedEventsDeduper) {
+ *     super({ queue: 'thing-created', bindings: [{ exchange: 'events', routingKey: 'thing.created' }],
+ *       schema: thingCreatedSchema, dedupe, scopeFrom: (d) => ({ tenantId: d.tenantId }) });
+ *   }
+ *   protected handle({ data, tx, scope }: InboundMessage<ThingCreated, DbExecutor>) { return this.things.onCreated(scope!, data, tx!); }
+ * }
+ */
+export declare abstract class BaseConsumer<T, TTx = undefined> {
+    protected readonly definition: ConsumerDefinition<T, TTx>;
+    protected constructor(definition: ConsumerDefinition<T, TTx>);
+    /** Handles one validated, de-duplicated message. Throw to retry (or a non-retryable error to dead-letter). */
+    protected abstract handle(message: InboundMessage<T, TTx>): Promise<void>;
+    /**
+     * Subscribes this consumer.
+     *
+     * @param consumer The service's {@link MessageConsumer}.
+     */
+    register(consumer: MessageConsumer): Promise<void>;
+}
+//# sourceMappingURL=base-consumer.d.ts.map

package/dist/types/messaging/base-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-consumer.d.ts","sourceRoot":"","sources":["../../../src/messaging/base-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE1F,0GAA0G;AAC1G,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,YAAY,CAAC,CAAC,EAAE,GAAG,GAAG,SAAS;IAC7B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC;IAA/E,SAAS,aAAgC,UAAU,EAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC;IAE/E,8GAA8G;IAC9G,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAEzE;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}