@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/types/database/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/database/tables.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,8BAA8B,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAYhK,OAAO,EAAE,oBAAoB,EAAE,8BAA8B,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;AAExI,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AACzD,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE3E,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,IAAI,SAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GActD;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,IAAI,SAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAUzE;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,SAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAarE;AAED,4CAA4C;AAC5C,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAgB,CAAC;AACpC,gDAAgD;AAChD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAyB,CAAC;AACtD,8CAA8C;AAC9C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAuB,CAAC"}

package/dist/types/express/auth.d.ts

@@ -1,4 +1,5 @@
-import type { RequestHandler } from 'express';
+import type { Request, RequestHandler } from 'express';
+import { type IdentityProtocol, type IdentityRejection } from '../identity/index.js';
 import type { AuthUser, Logger } from '../types/index.js';
 declare global {
     namespace Express {
@@ -7,57 +8,72 @@ declare global {
         }
     }
 }
+/** Why a gateway identity was rejected, for the `onRejected` hook. */
+export interface IdentityRejectedEvent {
+    reason: IdentityRejection;
+    method: string;
+    /** Request path without the query string. Never includes header values. */
+    path: string;
+    requestId?: string;
+}
 /** Options for the gateway identity middleware. */
 export interface GatewayAuthOptions {
-    /** HMAC secret shared with the gateway; verifies the signed identity headers. */
-    secret: string;
-    /** Maximum age of the gateway timestamp before the identity counts as stale (replay guard). */
-    maxSkewMs?: number;
-    /** Receives a warning (reason + path, no header values) when a forged or stale identity is rejected. */
+    /** The app's identity protocol (domain separator + header mapping). */
+    protocol: IdentityProtocol;
+    /** Shared HMAC secret; defaults to env `GATEWAY_SIGNING_SECRET`. Must be at least 32 characters (checked at startup). */
+    secret?: string;
+    /** Replay window for `x-gateway-ts` (default 30 s). */
+    maxAgeMs?: number;
+    /** Allowed gateway clock lead (default 5 s). */
+    maxFutureMs?: number;
+    /** Receives a warning (reason + path, no header values) when an identity is rejected. */
     logger?: Logger;
+    /** Called on every rejected identity, e.g. to publish a security event. Errors it throws are logged and ignored. */
+    onRejected?: (event: IdentityRejectedEvent, req: Request) => void | Promise<void>;
 }
 /**
- * Requires a valid gateway-signed identity and sets `req.user`; 401 UNAUTHENTICATED (with `requestId`) otherwise.
+ * Requires a valid gateway-signed (v2) identity and sets `req.user`; 401 UNAUTHENTICATED (with `requestId`)
+ * otherwise. Also fills the request context's `userId` and `scopes` so log lines carry them.
+ * Throws at startup when the secret is missing or shorter than 32 characters.
  *
- * @param options Secret, skew window and logger.
+ * @param options Protocol, secret, replay window, logger and rejection hook.
  * @returns Express middleware.
- * @example router.use(authenticateFromGateway({ secret: config.gatewaySecret, logger }));
+ * @example router.use(authenticateFromGateway({ protocol, logger, onRejected: publishSecurityEvent }));
  */
 export declare function authenticateFromGateway(options: GatewayAuthOptions): RequestHandler;
 /**
- * Attaches `req.user` when a valid identity is present and continues anonymously when none is sent.
- * A forged or stale identity is still rejected with 401, never downgraded to anonymous.
+ * Attaches `req.user` when a valid identity is present and continues anonymously when none is sent,
+ * for public routes that personalise. A forged or stale identity is still rejected with 401, never
+ * downgraded to anonymous.
  *
- * @param options Secret, skew window and logger.
+ * @param options Same as {@link authenticateFromGateway}.
  * @returns Express middleware.
- * @example router.get('/products', optionalAuthFromGateway({ secret }), controller.list);
+ * @example router.get('/items', optionalAuthFromGateway({ protocol }), controller.list);
  */
 export declare function optionalAuthFromGateway(options: GatewayAuthOptions): RequestHandler;
 /**
  * Allows callers holding any of `permissions` (401 without identity, 403 FORBIDDEN otherwise).
+ * A super admin passes every permission guard.
  *
  * @example router.post('/refunds', requirePermission('refunds.create'), controller.create);
  */
 export declare const requirePermission: (...permissions: string[]) => RequestHandler;
 /**
- * Allows callers holding every one of `permissions`.
+ * Allows callers holding every one of `permissions`. Accepts a list or rest arguments.
  *
  * @example router.delete('/x/:id', requireAllPermissions('x.read', 'x.delete'), controller.remove);
  */
-export declare const requireAllPermissions: (...permissions: string[]) => RequestHandler;
+export declare const requireAllPermissions: (...permissions: Array<string | string[]>) => RequestHandler;
 /**
- * Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only.
+ * Allows callers whose session passed the one-time-code (second factor) check; 403 FORBIDDEN otherwise.
  *
- * @example router.use('/ops', requireRole('platform_admin'));
+ * @example router.post('/security/settings', requireOtpVerified(), controller.update);
  */
-export declare const requireRole: (...roles: string[]) => RequestHandler;
+export declare const requireOtpVerified: () => RequestHandler;
 /**
- * Guards `/internal/*` routes: requires the service secret header (constant-time compare);
- * 401 UNAUTHENTICATED with `requestId` otherwise.
+ * Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only.
  *
- * @param secret The expected `x-internal-service-secret`; an empty secret rejects every call (fail closed).
- * @returns Express middleware.
- * @example router.use('/internal', requireInternalServiceSecret(config.internalSecret));
+ * @example router.use('/ops', requireRole('platform_admin'));
  */
-export declare function requireInternalServiceSecret(secret: string): RequestHandler;
+export declare const requireRole: (...roles: string[]) => RequestHandler;
 //# sourceMappingURL=auth.d.ts.map

package/dist/types/express/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/express/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAM/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,QAAQ,CAAC;SACjB;KACF;CACF;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAKnF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAQnF;AAgBD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAgE,CAAC;AAE9H;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAoE,CAAC;AAEtI;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,cAAyE,CAAC;AAE3H;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAM3E"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/express/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAY,MAAM,SAAS,CAAC;AAK/E,OAAO,EACsD,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EACzG,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE,QAAQ,CAAC;SACjB;KACF;CACF;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yHAAyH;IACzH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oHAAoH;IACpH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAMnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAMnF;AAaD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAgE,CAAC;AAE9H;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,GAAG,aAAa,KAAK,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,KAAG,cAGhF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,cAAgG,CAAC;AAEvI;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,cAAyE,CAAC"}

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

@@ -3,4 +3,6 @@ export * from './middleware.js';
 export * from './health.js';
 export * from './security.js';
 export * from './respond.js';
+export * from './step-up.js';
+export * from './internal-caller.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC"}

package/dist/types/express/internal-caller.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Express guard for service-to-service routes.
+ *
+ * Layer: middleware. Key rules:
+ * - Every internal route names the exact callers it accepts: `requireInternalCaller(['alpha-service'])`.
+ * - 401 UNAUTHENTICATED when the caller name or secret is missing, unknown or wrong (constant-time compare);
+ *   403 FORBIDDEN when a correctly authenticated caller is not in the route's list.
+ * - 403 FORBIDDEN for any request outside the app's internal path prefix, so a guard mounted on a public
+ *   router by mistake fails closed instead of exposing a credential-only route.
+ * - Rejections log the reason, caller name and path; never a secret or header value.
+ */
+import type { RequestHandler } from 'express';
+import type { Logger } from '../types/index.js';
+declare global {
+    namespace Express {
+        interface Request {
+            /** The authenticated calling service, set by `requireInternalCaller`. */
+            internalCaller?: string;
+        }
+    }
+}
+/** Settings for {@link createInternalCallerGuards}. */
+export interface InternalCallerGuardOptions {
+    /** The app's internal route prefix, e.g. `/internal`; requests outside it are refused. */
+    pathPrefix: string;
+    /** Caller name → accepted secret; defaults to env `INTERNAL_SERVICE_CREDENTIALS`. */
+    credentials?: Readonly<Record<string, string>>;
+    /** Receives a warning per rejected call. */
+    logger?: Logger;
+}
+/** Guards built by {@link createInternalCallerGuards}. */
+export interface InternalCallerGuards {
+    /**
+     * Allows only the listed callers.
+     *
+     * @param allowed Exact caller service names; must not be empty.
+     * @returns Express middleware that sets `req.internalCaller`.
+     * @throws Error at startup when `allowed` is empty.
+     */
+    requireInternalCaller(allowed: readonly string[]): RequestHandler;
+}
+/**
+ * Builds the internal-caller guard for a service, bound to its internal path prefix and accepted credentials.
+ *
+ * @param options Path prefix, credentials and logger.
+ * @returns `{ requireInternalCaller }`.
+ * @throws Error when the prefix is not an absolute path; ConfigError when env credentials are malformed.
+ * @example
+ * const { requireInternalCaller } = createInternalCallerGuards({ pathPrefix: '/internal', logger });
+ * router.get('/internal/records/:id', requireInternalCaller(['alpha-service']), controller.get);
+ */
+export declare function createInternalCallerGuards(options: InternalCallerGuardOptions): InternalCallerGuards;
+//# sourceMappingURL=internal-caller.d.ts.map

package/dist/types/express/internal-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-caller.d.ts","sourceRoot":"","sources":["../../../src/express/internal-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAI/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,yEAAyE;YACzE,cAAc,CAAC,EAAE,MAAM,CAAC;SACzB;KACF;CACF;AAED,uDAAuD;AACvD,MAAM,WAAW,0BAA0B;IACzC,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,qBAAqB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAAC;CACnE;AAID;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,0BAA0B,GAAG,oBAAoB,CA+BpG"}

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

@@ -0,0 +1,38 @@
+import type { RequestHandler } from 'express';
+import { type StepUpCatalogue } from '../identity/step-up.js';
+/** One step-up guard a service mounted, as listed by `declaredStepUpRoutes()`. */
+export interface DeclaredStepUpRoute<S extends string = string> {
+    scope: S;
+    singleUse: boolean;
+    /** Route label such as `POST /v1/refunds/:id`, when the caller gave one. */
+    route?: string;
+}
+/** Options for {@link createStepUpGuards}. */
+export interface StepUpGuardOptions<S extends string> {
+    /** The app's scope catalogue from `defineStepUpScopes`. */
+    catalogue: StepUpCatalogue<S>;
+    /** How old a step-up may be (default 5 minutes). */
+    windowMs?: number;
+    /** Clock for tests. */
+    now?: () => number;
+}
+/** The guard factory and its registry, from {@link createStepUpGuards}. */
+export interface StepUpGuards<S extends string> {
+    /** Middleware: 403 STEP_UP_REQUIRED `{ scope }` unless the gateway-verified step-up time is fresh. */
+    requireStepUp(scope: S, route?: string): RequestHandler;
+    /** Every guard created so far, so the service can compare its scopes with the gateway route map. */
+    declaredStepUpRoutes(): ReadonlyArray<DeclaredStepUpRoute<S>>;
+}
+/**
+ * Builds the step-up guard for an app's catalogue. Must run after `authenticateFromGateway`, which sets
+ * `req.user.stepUpAt` only from the signed `x-step-up-at` header. Single-use proofs are consumed by the
+ * gateway; the service sees only the verified time. Throws at startup for an unknown scope or a bad window.
+ *
+ * @param options Catalogue, freshness window and clock.
+ * @returns `requireStepUp(scope, route?)` and `declaredStepUpRoutes()`.
+ * @example
+ * const { requireStepUp } = createStepUpGuards({ catalogue: stepUpScopes });
+ * router.post('/refunds/:id', requirePermission('refunds.create'), requireStepUp('refund-large', 'POST /refunds/:id'), controller.refund);
+ */
+export declare function createStepUpGuards<S extends string>(options: StepUpGuardOptions<S>): StepUpGuards<S>;
+//# sourceMappingURL=step-up.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../../../src/express/step-up.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAC;AAE/E,OAAO,EAC2D,KAAK,eAAe,EACrF,MAAM,wBAAwB,CAAC;AAGhC,kFAAkF;AAClF,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC5D,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM;IAClD,2DAA2D;IAC3D,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC5C,sGAAsG;IACtG,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;IACxD,oGAAoG;IACpG,oBAAoB,IAAI,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAqBpG"}

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

@@ -1,34 +1,6 @@
-import type { Logger } from '../types/index.js';
-export * from './safe-fetch.js';
-export interface ServiceClientOptions {
-    /** e.g. `http://auth-admin-service:4001` */
-    baseUrl: string;
-    /** Sent as `x-internal-service-secret`. */
-    internalSecret: string;
-    callerService: string;
-    timeoutMs?: number;
-    /** Retries for network errors and 502/503/504 on idempotent methods. */
-    retries?: number;
-    logger?: Logger;
-}
-export interface RequestOptions {
-    query?: Record<string, string | number | boolean | undefined>;
-    body?: unknown;
-    headers?: Record<string, string>;
-    correlationId?: string;
-    timeoutMs?: number;
-}
-export interface ServiceClient {
-    get<T>(path: string, options?: RequestOptions): Promise<T>;
-    post<T>(path: string, options?: RequestOptions): Promise<T>;
-    put<T>(path: string, options?: RequestOptions): Promise<T>;
-    patch<T>(path: string, options?: RequestOptions): Promise<T>;
-    delete<T>(path: string, options?: RequestOptions): Promise<T>;
-}
 /**
- * Typed client for `/internal/*` calls between services. Unwraps the `{ success, data }`
- * envelope, maps upstream errors to AppErrors with the same status, and turns network failures
- * and timeouts into 503s.
+ * Outbound HTTP helpers. Service-to-service calls use `createInternalClient` (root export); calls to
+ * tenant-supplied URLs go through the SSRF-guarded {@link createSafeFetcher}.
  */
-export declare function createServiceClient(options: ServiceClientOptions): ServiceClient;
+export * from './safe-fetch.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE7D,cAAc,iBAAiB,CAAC;AAEhC,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/D;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAyDhF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,iBAAiB,CAAC"}

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

@@ -6,6 +6,12 @@ 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,oBAAoB,CAAC;AACnC,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;