@heavybit/shared-lib 1.3.2 → 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,21 +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 {
-    secret: string;
-    maxSkewMs?: number;
+    /** 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; 401 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 Protocol, secret, replay window, logger and rejection hook.
+ * @returns Express middleware.
+ * @example router.use(authenticateFromGateway({ protocol, logger, onRejected: publishSecurityEvent }));
+ */
 export declare function authenticateFromGateway(options: GatewayAuthOptions): RequestHandler;
-/** Attaches `req.user` when a valid identity is present; continues anonymously otherwise. */
+/**
+ * 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 Same as {@link authenticateFromGateway}.
+ * @returns Express middleware.
+ * @example router.get('/items', optionalAuthFromGateway({ protocol }), controller.list);
+ */
 export declare function optionalAuthFromGateway(options: GatewayAuthOptions): RequestHandler;
-/** Allows callers holding any of `permissions`. */
+/**
+ * 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`. */
-export declare const requireAllPermissions: (...permissions: string[]) => RequestHandler;
-/** Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only. */
+/**
+ * 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: Array<string | string[]>) => RequestHandler;
+/**
+ * Allows callers whose session passed the one-time-code (second factor) check; 403 FORBIDDEN otherwise.
+ *
+ * @example router.post('/security/settings', requireOtpVerified(), controller.update);
+ */
+export declare const requireOtpVerified: () => RequestHandler;
+/**
+ * Allows callers with any of `roles`. Prefer permissions; roles are for coarse gates only.
+ *
+ * @example router.use('/ops', requireRole('platform_admin'));
+ */
 export declare const requireRole: (...roles: string[]) => RequestHandler;
-/** Guards `/internal/*` routes: requires the shared service secret header. */
-export declare function requireInternalServiceSecret(secret: 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;AAK/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,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAKnF;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAQnF;AAgBD,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAgE,CAAC;AAE9H,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,GAAI,GAAG,aAAa,MAAM,EAAE,KAAG,cAAoE,CAAC;AAEtI,+FAA+F;AAC/F,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,cAAyE,CAAC;AAE3H,8EAA8E;AAC9E,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

@@ -2,4 +2,7 @@ export * from './auth.js';
 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"}
+{"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/middleware.d.ts

@@ -1,20 +1,99 @@
 import type { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response } from 'express';
 import type { ZodTypeAny } from 'zod';
 import type { Logger } from '../types/index.js';
-/** Ensures every request carries `x-correlation-id` (reused from the gateway when present). */
-export declare function correlationMiddleware(): RequestHandler;
+/** An incoming correlation id is trusted only if it is 8–64 chars of `[A-Za-z0-9-]` (no log injection). */
+export declare const CORRELATION_ID_PATTERN: RegExp;
+/**
+ * Gives every request one correlation id and runs the rest of the request inside a
+ * {@link RequestContext}. A valid incoming `x-correlation-id` (see {@link CORRELATION_ID_PATTERN}) is
+ * kept; anything else is replaced with a new ULID. The id is echoed on the response, written back to
+ * the request header (so outbound calls forward it) and becomes every error body's `requestId`.
+ * Mount it first: correlation → json → routes → notFoundHandler → errorHandler.
+ *
+ * @param serviceName Recorded in the context (and so in log lines written without a service).
+ * @returns Express middleware.
+ * @example app.use(correlationMiddleware('orders'));
+ */
+export declare function correlationMiddleware(serviceName?: string): RequestHandler;
+/**
+ * The request's correlation id (the source of every error body's `requestId`): the active request
+ * context's id, else the `x-correlation-id` header.
+ *
+ * @param req Express request.
+ * @returns The id, or undefined when neither is present.
+ * @example logger.info('Order placed', { correlationId: correlationId(req) });
+ */
 export declare function correlationId(req: Request): string | undefined;
-/** Real client IP: gateway-forwarded header first, then Express's `req.ip`. */
+/**
+ * Real client IP: gateway-forwarded header first, then Express's `req.ip`.
+ *
+ * @param req Express request.
+ * @returns The IP, or null when unknown.
+ * @example const ip = clientIp(req);
+ */
 export declare function clientIp(req: Request): string | null;
+/**
+ * The caller's IANA time zone as forwarded by the gateway.
+ *
+ * @param req Express request.
+ * @returns e.g. `Europe/Paris`, or null when not sent.
+ * @example formatInTimeZone(date, clientTimezone(req) ?? 'UTC');
+ */
 export declare function clientTimezone(req: Request): string | null;
+/**
+ * The anonymous visitor id forwarded by the gateway (for anonymous visitor state, rate limits and analytics).
+ *
+ * @param req Express request.
+ * @returns The id, or null when not sent.
+ * @example const visitor = req.user?.id ?? anonId(req);
+ */
 export declare function anonId(req: Request): string | null;
 type RequestPart = 'body' | 'query' | 'params';
-/** Validates and replaces `req[part]` with the parsed value; 422 with field errors on failure. */
-export declare function validate(schema: ZodTypeAny, part?: RequestPart): RequestHandler;
-/** Wraps an async handler so rejections reach the error middleware (needed on Express 4). */
+/** Zod schemas for the parts of a request that {@link validate} checks. */
+export type RequestSchemas = Partial<Record<RequestPart, ZodTypeAny>>;
+/**
+ * Validates the request with Zod at the controller boundary. Each given part is parsed and
+ * `req[part]` is replaced with the parsed value, so unknown keys are stripped (or rejected with
+ * `.strict()`) and coercions/defaults apply. Every part is checked before failing, and the combined
+ * field errors are thrown as a 422 {@link ValidationError} for the error handler (body fields keep
+ * their path; params and query fields are prefixed, e.g. `params.id`).
+ *
+ * The older single-schema form `validate(schema, part = 'body')` still works.
+ *
+ * @param schemas `{ params?, query?, body? }`, or one schema.
+ * @param part With a single schema: the part it checks (default `body`).
+ * @returns Express middleware.
+ * @example router.patch('/:id', validate({ params: idParam, body: updateSchema }), controller.update);
+ */
+export declare function validate(schemas: RequestSchemas | ZodTypeAny, part?: RequestPart): RequestHandler;
+/**
+ * Wraps an async handler so rejections reach the error middleware (needed on Express 4; harmless on 5).
+ *
+ * @param fn Async route handler.
+ * @returns A handler that forwards rejections to `next(err)`.
+ * @example router.get('/:id', asyncHandler(controller.get));
+ */
 export declare function asyncHandler<Req extends Request = Request>(fn: (req: Req, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler;
-/** Maps AppErrors to their status; everything else becomes a logged 500 with a generic message. */
+/**
+ * Last error middleware. Every body is `{ success: false, code, message, errors?, requestId }`:
+ * - body-parser failures → 400 BAD_REQUEST / 413 PAYLOAD_TOO_LARGE;
+ * - a thrown ZodError (e.g. from `schema.parse`) → 422 VALIDATION_FAILED with field errors;
+ * - AppError → its status, code and errors; 4xx keep their message, 5xx get a generic one; a
+ *   `retryAfterSeconds` becomes the `Retry-After` header;
+ * - anything else → logged in full, answered 500 INTERNAL_ERROR with a generic message.
+ * `requestId` is the request context's correlation id (set by {@link correlationMiddleware}).
+ *
+ * @param logger Receives 5xx details (message, stack, path, correlation id); never sent to the client.
+ * @returns Express error middleware.
+ * @example app.use(notFoundHandler()); app.use(errorHandler(logger));
+ */
 export declare function errorHandler(logger?: Logger): ErrorRequestHandler;
+/**
+ * Catch-all for unmatched routes: 404 NOT_FOUND with the request id. Mount after every router.
+ *
+ * @returns Express middleware.
+ * @example app.use(notFoundHandler()); app.use(errorHandler(logger));
+ */
 export declare function notFoundHandler(): RequestHandler;
 export {};
 //# sourceMappingURL=middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/express/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAKtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,+FAA+F;AAC/F,wBAAgB,qBAAqB,IAAI,cAAc,CAQtD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG9D;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIpD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlD;AAED,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,WAAoB,GAAG,cAAc,CAWvF;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAIjJ;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAqBjE;AAED,wBAAgB,eAAe,IAAI,cAAc,CAIhD"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/express/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,KAAK,EAAY,UAAU,EAAE,MAAM,KAAK,CAAC;AAMhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,cAAc,CAQ1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK9D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlD;AAED,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AActE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,EAAE,IAAI,GAAE,WAAoB,GAAG,cAAc,CAsBzG;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAIjJ;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CA+BjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAIhD"}

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

@@ -0,0 +1,41 @@
+/**
+ * Success-response helpers for Express controllers (HTTP layer only).
+ * They write the standard envelope `{ success: true, message, data, meta? }`, so controllers never
+ * hand-build bodies. Errors are not sent here: throw an AppError and let `errorHandler` answer.
+ */
+import type { Response } from 'express';
+import type { CursorPage, CursorPageMeta, PaginationMeta } from '../types/index.js';
+/**
+ * 200 with the success envelope.
+ *
+ * @param res Express response.
+ * @param data The payload placed under `data`.
+ * @param message Optional human-readable message (default `Success`).
+ * @param meta Optional list metadata.
+ * @returns The Express response.
+ * @example ok(res, product, 'Product updated');
+ */
+export declare function ok<T>(res: Response, data: T, message?: string, meta?: PaginationMeta | CursorPageMeta): Response;
+/**
+ * 201 with the success envelope, for a newly created resource.
+ *
+ * @param res Express response.
+ * @param data The created resource (or its id).
+ * @param message Optional message (default `Created`).
+ * @returns The Express response.
+ *
+ * @example created(res, { id }, 'Shop created');
+ */
+export declare function created<T>(res: Response, data: T, message?: string): Response;
+/**
+ * 200 with a cursor-paginated list: `data` is the items, `meta` is `{ limit, nextCursor, hasMore }`.
+ *
+ * @param res Express response.
+ * @param page The page from the service (see `buildCursorPageMeta`).
+ * @param message Optional message.
+ * @returns The Express response.
+ *
+ * @example okPage(res, await service.list(scope, { cursor, limit }));
+ */
+export declare function okPage<T>(res: Response, page: CursorPage<T>, message?: string): Response;
+//# sourceMappingURL=respond.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/express/respond.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,QAAQ,CAGhH;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,QAAQ,CAEhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExF"}

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"}