@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/types/messaging/publisher.d.ts.map

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

package/dist/types/messaging/staff-notifier.d.ts

@@ -1,56 +1,87 @@
-import { z } from 'zod';
-import { type DispatchChannel, type DispatchRecipient, type DispatchValue } from '../contracts/notification-dispatch.js';
+/**
+ * Staff alerts (messaging layer helper): stage one notification dispatch per recipient of a
+ * permission through the caller's outbox. App vocabulary (category, channels, command name) is
+ * passed in as options; nothing app-specific is assumed.
+ */
+import { type DispatchValue } from '../contracts/notification-dispatch.js';
 import type { Logger } from '../types/index.js';
 import type { EnvelopeMeta } from './envelope.js';
-/** The slice of a service's outbox the notifier needs; `E` is that service's transaction type. */
+import type { StaffRecipientResolver } from './staff-recipients.js';
+/**
+ * The slice of a service's outbox the notifier needs.
+ *
+ * @typeParam E The service's transaction/executor type.
+ * @example const outbox: CommandOutbox<DbExecutor> = { command: (tx, name, data, meta) => enqueueOutbox(tx, name, data, { ...meta, exchange: 'commands' }).then(() => undefined) };
+ */
 export interface CommandOutbox<E> {
-    command<T>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
+    command<T extends object>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
 }
-/** Who holds a permission, as staff alert recipients. Configured lists today; an auth-admin lookup later. */
-export interface StaffRecipientResolver {
-    resolve(permission: string): Promise<DispatchRecipient[]>;
-}
-/** Recipients from configuration (env), keyed by the permission an alert targets. */
-export declare class ConfiguredStaffRecipients implements StaffRecipientResolver {
-    private readonly byPermission;
-    constructor(byPermission: Readonly<Record<string, readonly DispatchRecipient[]>>);
-    resolve(permission: string): Promise<DispatchRecipient[]>;
-}
-export interface StaffAlert {
+/**
+ * One operational alert to the staff who hold a permission.
+ *
+ * @example { template: 'job-failed', permission: 'jobs.manage', data: { reference: 'J-1' } }
+ */
+export interface StaffAlert<Ch extends string = string> {
     /** Seeded notification template slug. */
     template: string;
-    /** The permission its recipients hold (e.g. `newsdesk.policy.manage`). */
+    /** The permission its recipients hold (e.g. `reports.manage`). */
     permission: string;
     /** Template variables. */
     data: Record<string, DispatchValue>;
-    /** Defaults to email: staff addresses have no account, so the in-app feed cannot reach them. */
-    channels?: DispatchChannel[];
+    /** Channels for this alert (at least one); defaults to the notifier's `defaultChannels`. */
+    channels?: [Ch, ...Ch[]];
 }
-/** Tracing for the staged commands; the actor is always the system. */
-export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId' | 'aggregate'>;
 /**
- * Stages one `notification:dispatch` per recipient through the outbox, in the caller's transaction, so an
- * alert is sent if and only if the state change that raised it commits. Never sends email itself.
+ * Tracing for the staged commands; the actor is always the system.
+ *
+ * @example { correlationId: correlationId(req) }
+ */
+export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId'>;
+/**
+ * How the notifier stages commands. All app vocabulary is passed in; nothing is assumed.
+ *
+ * @example { category: 'staff', defaultChannels: ['email'], logger }
+ */
+export interface StaffNotifierOptions<C extends string, Ch extends string> {
+    /** The dispatch category for staff alerts in this app (e.g. `staff`). */
+    category: C;
+    /** Channels used when an alert names none. Staff addresses usually have no account, so typically `['email']`. */
+    defaultChannels: [Ch, ...Ch[]];
+    /** Command name; defaults to {@link NOTIFICATION_DISPATCH}. */
+    command?: string;
+    /** Warns when an alert resolves to no recipients; silent when omitted. */
+    logger?: Logger;
+}
+/**
+ * Stages one dispatch command per recipient through the outbox, in the caller's transaction, so an
+ * alert is sent if and only if the state change that raised it commits. Never sends anything itself.
  * An alert that resolves to nobody is logged as a warning (an unconfigured list must not fail silently).
+ * Staff alerts always bypass recipient preferences and record the target permission.
+ *
+ * @typeParam E The service's transaction/executor type.
+ * @typeParam C The app's dispatch categories.
+ * @typeParam Ch The app's dispatch channels.
+ * @example
+ * const notifier = new StaffNotifier(outbox, new ConfiguredStaffRecipients({ 'jobs.manage': config.opsEmails }),
+ *   { category: 'staff', defaultChannels: ['email'], logger });
+ * await notifier.alert(tx, { template: 'job-failed', permission: 'jobs.manage', data: { reference } }, { correlationId });
  */
-export declare class StaffNotifier<E> {
+export declare class StaffNotifier<E, C extends string = string, Ch extends string = string> {
     private readonly outbox;
     private readonly recipients;
+    private readonly category;
+    private readonly defaultChannels;
+    private readonly command;
     private readonly logger;
-    constructor(outbox: CommandOutbox<E>, recipients: StaffRecipientResolver, logger?: Logger);
-    /** Returns how many commands were staged. */
-    alert(executor: E, alert: StaffAlert, meta?: StaffAlertMeta): Promise<number>;
+    constructor(outbox: CommandOutbox<E>, recipients: StaffRecipientResolver, options: StaffNotifierOptions<C, Ch>);
+    /**
+     * Stage the alert for every recipient of its permission.
+     *
+     * @param executor The caller's open transaction; the commands commit or roll back with it.
+     * @param alert Template, permission, variables and optional channels.
+     * @param meta Correlation id for tracing; the actor is always the system.
+     * @returns How many commands were staged (0 when nobody is configured).
+     */
+    alert(executor: E, alert: StaffAlert<Ch>, meta?: StaffAlertMeta): Promise<number>;
 }
-/**
- * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
- * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
- * instead of dead-lettering in notification-service when the alert finally fires.
- */
-export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
-    email: string;
-    name?: string | undefined;
-    userId?: string | null | undefined;
-    locale?: string | null | undefined;
-    timezone?: string | null | undefined;
-}[], string | undefined>;
 //# sourceMappingURL=staff-notifier.d.ts.map

package/dist/types/messaging/staff-notifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,kGAAkG;AAClG,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF;AAED,6GAA6G;AAC7G,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3D;AAED,qFAAqF;AACrF,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAE3F,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhE;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,WAAW,CAAC,CAAC;AAE/E;;;;GAIG;AACH,qBAAa,aAAa,CAAC,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EAClC,MAAM,GAAE,MAAqB;IAGhD,6CAA6C;IACvC,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoBxF;AAID;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;wBAegD,CAAC"}
+{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtG;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACpD,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM;IACvE,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC;IACZ,iHAAiH;IACjH,eAAe,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IAO/E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EACnD,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,EAAE,CAAC;IAQtC;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoB5F"}

package/dist/types/messaging/staff-recipients.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Staff alert recipients (messaging layer helper): who receives an alert raised for a permission.
+ * Today the lists come from configuration; an app can plug in a lookup (e.g. its auth service)
+ * by implementing {@link StaffRecipientResolver}.
+ */
+import { z } from 'zod';
+import { type DispatchRecipient } from '../contracts/notification-dispatch.js';
+/**
+ * Resolves the recipients who hold a permission.
+ *
+ * @example const resolver: StaffRecipientResolver = { resolve: async (p) => authClient.usersWithPermission(p) };
+ */
+export interface StaffRecipientResolver {
+    /**
+     * @param permission The permission an alert targets.
+     * @returns Recipients (possibly empty).
+     */
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+/**
+ * Recipients from configuration (env), keyed by the permission an alert targets.
+ *
+ * @param byPermission Map of permission → recipients, typically built with {@link staffEmailListSchema}.
+ * @example new ConfiguredStaffRecipients({ 'payouts.manage': env.FINANCE_ALERT_EMAILS })
+ */
+export declare class ConfiguredStaffRecipients implements StaffRecipientResolver {
+    private readonly byPermission;
+    constructor(byPermission: Readonly<Record<string, readonly DispatchRecipient[]>>);
+    /**
+     * @param permission The permission an alert targets.
+     * @returns A copy of the configured recipients, or `[]` when none are configured.
+     */
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+/**
+ * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
+ * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
+ * instead of dead-lettering in the notification-service when the alert finally fires.
+ *
+ * @returns (on parse) `DispatchRecipient[]` with `email` only.
+ * @example const config = z.object({ FINANCE_ALERT_EMAILS: staffEmailListSchema }).parse(process.env);
+ */
+export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
+    email: string;
+    name?: string | undefined;
+    userId?: string | null | undefined;
+    locale?: string | null | undefined;
+    timezone?: string | null | undefined;
+}[], string | undefined>;
+//# sourceMappingURL=staff-recipients.d.ts.map

package/dist/types/messaging/staff-recipients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff-recipients.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-recipients.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3D;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAEjG;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhE;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;wBAegD,CAAC"}

package/dist/types/messaging/topology.d.ts

@@ -1,23 +1,55 @@
 /**
- * Naming for exchanges and queues. Every name carries the environment prefix so two
- * environments that accidentally share a vhost still cannot see each other's traffic.
+ * Naming for exchanges and queues, all derived from the app slug and the environment prefix
+ * (`QUEUE_PREFIX`), so two environments that share a broker or vhost never see each other's traffic.
  *
- *   events exchange   <app>.<prefix>.events     (topic)  domain events: `auth.user.registered`
- *   commands exchange <app>.<prefix>.commands   (direct) work for one owner: `email:send`
- *   queues            <prefix>.<name>                    e.g. `prod.notification-service:auth.events`
+ *   events exchange   {app}.{prefix}.events            (topic)  domain events, e.g. `thing.created`
+ *   commands exchange {app}.{prefix}.commands          (direct) work for one owner, e.g. `mail:send`
+ *   dead-letter exch. {app}.{prefix}.{service}.dlx     (direct) one per service
+ *   service queues    {prefix}.{service}.{purpose}              e.g. `dev.billing.thing-events`
+ *   dead-letter queue {queue}.dlq      retry queues {queue}.retry.{ms}      delay queues {queue}.delay.{ms}
  */
 export interface Topology {
     readonly app: string;
     readonly prefix: string;
     readonly eventsExchange: string;
     readonly commandsExchange: string;
-    /** Physical queue name for a logical name. */
+    /** Physical queue name for a logical name (adds the environment prefix once). */
     queue(name: string): string;
+    /** `{prefix}.{service}.{purpose}` — the name of a service's subscription queue. */
+    queueName(service: string, purpose: string): string;
+    /** `{app}.{prefix}.{service}.dlx` — the service's dead-letter exchange. */
+    deadLetterExchange(service: string): string;
 }
-export declare function createTopology(options: {
+/** Options for {@link createTopology}; values come from config, never literals in shared code. */
+export interface TopologyOptions {
+    /** App slug (lower-case letters, digits, `-`, `_`). */
     app: string;
+    /** Environment prefix, i.e. `QUEUE_PREFIX` (lower-case letters, digits, `-`, `_`). */
     prefix: string;
-}): Topology;
+}
+/**
+ * Builds the naming scheme for one app and environment.
+ *
+ * @param options App slug and environment prefix.
+ * @returns The {@link Topology}.
+ * @throws Error when a segment is empty or has other characters.
+ * @example const topology = createTopology({ app: config.APP_SLUG, prefix: config.QUEUE_PREFIX });
+ */
+export declare function createTopology(options: TopologyOptions): Topology;
+/** Retry queue for one delay: a fixed TTL, dead-lettering back into `queue`. */
 export declare const retryQueueName: (queue: string, delayMs: number) => string;
+/** Dead-letter queue of `queue`. */
 export declare const deadLetterQueueName: (queue: string) => string;
+/** Smallest delay bucket for {@link delayQueueName}. */
+export declare const MIN_DELAY_BUCKET_MS = 1000;
+/**
+ * Delay queue for `scheduleDelayed`: one per power-of-two bucket (1s, 2s, 4s …) at or above `delayMs`.
+ * Per-message TTLs only expire at the head of a queue, so bucketing bounds how long a short delay can
+ * wait behind a longer one (at most its own bucket size).
+ *
+ * @param queue Target queue (physical name).
+ * @param delayMs Requested delay in milliseconds.
+ * @returns `{queue}.delay.{bucketMs}`.
+ */
+export declare function delayQueueName(queue: string, delayMs: number): string;
 //# sourceMappingURL=topology.d.ts.map

package/dist/types/messaging/topology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8CAA8C;IAC9C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAWjF;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,WAAgC,CAAC;AAC9F,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,WAAmB,CAAC"}
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,mFAAmF;IACnF,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,2EAA2E;IAC3E,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7C;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAYjE;AAED,gFAAgF;AAChF,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,WAAgC,CAAC;AAC9F,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,WAAmB,CAAC;AAErE,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrE"}

package/dist/types/rate-limit/index.d.ts

@@ -2,27 +2,63 @@ import type { NextFunction, Request, Response } from 'express';
 import type { Redis } from 'ioredis';
 import { type RateLimiterAbstract } from 'rate-limiter-flexible';
 import type { Logger } from '../types/index.js';
+import { type RedisKeyspace } from '../cache/keyspace.js';
+export * from './keys.js';
+/** Inputs to {@link createLimiter}. */
 export interface RateLimitOptions {
     points: number;
     durationSec: number;
-    /** Unique per limiter, e.g. `rl:auth:login-ip`. */
-    keyPrefix: string;
+    /** The service keyspace; limiter keys read `{prefix}rl:{scope}:{key}`. */
+    keyspace: RedisKeyspace;
+    /** Limit name, unique per limiter (lower-case kebab-case), e.g. `sign-in-ip`. */
+    scope: string;
     redis?: Redis | null;
     /** Lock the key for this long once exhausted (default: none). */
     blockDurationSec?: number;
     logger?: Logger;
 }
-/** Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. */
+/**
+ * Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. Its
+ * keys come from the keyspace; pass already-encoded keys (see {@link limiterKey}) to `consume`.
+ *
+ * @param options Points, window, keyspace and scope.
+ * @returns The limiter.
+ * @example const limiter = createLimiter({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis });
+ */
 export declare function createLimiter(options: RateLimitOptions): RateLimiterAbstract;
+/**
+ * Encodes a raw limiter key (user id, IP …) so it cannot add segments to the limiter's Redis key.
+ *
+ * @param raw Raw identifier.
+ * @returns The encoded key part.
+ * @example limiter.consume(limiterKey(req.ip))
+ */
+export declare const limiterKey: (raw: string) => string;
 /**
  * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
- * For in-service checks such as per-identifier login throttling.
+ * For in-service checks such as per-identifier sign-in throttling.
+ *
+ * @param limiter Limiter from {@link createLimiter}.
+ * @param key Encoded key (see {@link limiterKey}).
+ * @param message Optional public message for the 429.
+ * @throws TooManyRequestsError when the limit is exhausted; rethrows limiter failures.
+ * @example await consumeOrThrow(limiter, limiterKey(userId));
  */
 export declare function consumeOrThrow(limiter: RateLimiterAbstract, key: string, message?: string): Promise<void>;
+/** Inputs to {@link rateLimitMiddleware}: limiter options plus the request → key function. */
 export interface RateLimitMiddlewareOptions extends RateLimitOptions {
     /** Default: authenticated user ID, else client IP. */
     keyOf?: (req: Request) => string;
 }
+/**
+ * Express middleware that consumes one point per request. Sets `X-RateLimit-Limit` and
+ * `X-RateLimit-Remaining`; when exhausted answers 429 `RATE_LIMITED` with `Retry-After` (seconds).
+ * Fails open: a limiter error (not a rejection) is logged and the request continues.
+ *
+ * @param options Limiter options and `keyOf` (default user id, else client IP).
+ * @returns The middleware.
+ * @example router.post('/sessions', rateLimitMiddleware({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis }), handler);
+ */
 export declare function rateLimitMiddleware(options: RateLimitMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 export type { RateLimiterAbstract };
 //# sourceMappingURL=index.d.ts.map

package/dist/types/rate-limit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAuC,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB,CAW5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;AAED,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,sDAAsD;IACtD,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,IAKvD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAuC,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGzE,cAAc,WAAW,CAAC;AAE1B,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,EAAE,aAAa,CAAC;IACxB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB,CAY5E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAA4B,CAAC;AAEtE;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;AAED,8FAA8F;AAC9F,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,sDAAsD;IACtD,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,IAMvD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/types/rate-limit/keys.d.ts

@@ -0,0 +1,52 @@
+import { type RedisKey, type RedisKeyspace } from '../cache/keyspace.js';
+/**
+ * Rate-limit key builder and the sliding-window limiter contract. Dependency-free (exported from the
+ * package root as well as `/rate-limit`); the consuming service implements the sliding window.
+ */
+/** Purpose segment for every rate-limit key: `{prefix}rl:{scope}:…`. */
+export declare const RATE_LIMIT_PURPOSE = "rl";
+/** What a limit counts against. At least one dimension is required; they combine in a fixed order. */
+export interface RateLimitKeyInput {
+    /** Limit name, e.g. `sign-in` (lower-case kebab-case). */
+    scope: string;
+    ip?: string;
+    userId?: string;
+    /** Normalised (trimmed, lower-cased) and always hashed — never stored in clear. */
+    email?: string;
+    /** Request host, lower-cased. */
+    host?: string;
+    /** Route template, e.g. `/sessions` (encoded, so slashes cannot add segments). */
+    route?: string;
+}
+/**
+ * Builds `{prefix}rl:{scope}[:ip:{ip}][:user:{id}][:email:{hash}][:host:{host}][:route:{route}]`.
+ *
+ * @param keyspace The service keyspace.
+ * @param input Scope plus at least one dimension.
+ * @returns The rate-limit key.
+ * @throws ConfigError when no dimension is given or the scope is invalid.
+ * @example rateLimitKey(ks, { scope: 'sign-in', ip: req.ip, email: body.email })
+ */
+export declare function rateLimitKey(keyspace: RedisKeyspace, input: RateLimitKeyInput): RedisKey;
+/** Input to one sliding-window check. */
+export interface SlidingWindowCheck {
+    /** Key from {@link rateLimitKey}. */
+    key: RedisKey;
+    /** Requests allowed per window. */
+    limit: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Clock override for tests (epoch ms). */
+    now?: number;
+}
+/** Outcome of one sliding-window check. */
+export interface SlidingWindowResult {
+    allowed: boolean;
+    /** Requests left in the current window (0 when refused). */
+    remaining: number;
+    /** Milliseconds until the next request would be allowed (0 when allowed). */
+    retryAfterMs: number;
+}
+/** Sliding-window limiter contract; implemented by the consuming service (e.g. over Redis sorted sets). */
+export type SlidingWindowLimiter = (check: SlidingWindowCheck) => Promise<SlidingWindowResult>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/types/rate-limit/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/rate-limit/keys.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,QAAQ,EAAqB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3G;;;GAGG;AAEH,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAeD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAUxF;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,GAAG,EAAE,QAAQ,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,2GAA2G;AAC3G,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC"}

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

@@ -1,6 +1,11 @@
 import type { Server as HttpServer } from 'node:http';
+import type { Redis } from 'ioredis';
 import { Server, type ServerOptions, type Socket } from 'socket.io';
+import type { RedisKeyspace } from '../cache/keyspace.js';
+import { type IdentityProtocol } from '../identity/index.js';
 import type { AuthUser, Logger } from '../types/index.js';
+import { type SocketTicketClaims, type SocketTicketKeyOptions, type SocketTicketRejection } from './ticket.js';
+export * from './ticket.js';
 export interface SocketServerOptions {
     /** Socket.IO path, e.g. `/ws/notifications` (the gateway proxies the same path). */
     path: string;
@@ -23,8 +28,87 @@ export interface SocketEmitter {
     emitToRoom(room: string, event: string, payload: unknown): void;
     close(): Promise<void>;
 }
+/** Name of the private room every connection of `userId` joins. */
 export declare const userRoom: (userId: string) => string;
+/**
+ * Creates a Socket.IO server that authenticates every connection and joins it only to server-derived rooms.
+ * The verified user is in `socket.data.identity`.
+ *
+ * @example const sockets = createSocketServer(httpServer, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
 export declare function createSocketServer(httpServer: HttpServer, options: SocketServerOptions): SocketEmitter;
-/** Trusts the gateway-signed identity headers forwarded on the WebSocket upgrade request. */
-export declare function gatewaySocketAuth(secret: string): (socket: Socket) => AuthUser | null;
+/**
+ * Trusts the gateway-signed (v2) identity headers forwarded on the WebSocket upgrade request. The gateway
+ * signs the upgrade as `GET <handshake path>` (query ignored).
+ *
+ * @param options The shared secret (at least 32 characters) and the app's identity protocol.
+ * @returns An `authenticate` function for {@link createSocketServer}.
+ * @example createSocketServer(server, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
+export declare function gatewaySocketAuth(options: {
+    secret: string;
+    protocol: IdentityProtocol;
+}): (socket: Socket) => AuthUser | null;
+/** Why a ticket handshake was refused: a ticket problem, an origin problem or a replayed ticket. */
+export type SocketRejectionReason = SocketTicketRejection | 'origin_not_allowed' | 'replayed';
+/** Passed to `onRejected` so the service can log it and publish its security event. */
+export interface SocketRejection {
+    reason: SocketRejectionReason;
+    /** Known once the ticket verified (origin and replay rejections). */
+    userId: string | null;
+    /** The Socket.IO path that was refused. */
+    path: string;
+    origin: string | null;
+}
+/** Settings for {@link createTicketHandshake}. */
+export interface TicketHandshakeOptions extends SocketTicketKeyOptions {
+    /** Ticket audience(s) this server accepts. */
+    audience: string | readonly string[];
+    /** Browser origins allowed for this ticket holder (e.g. the app's origins, or a tenant's own domain). */
+    allowedOrigins: (claims: SocketTicketClaims) => readonly string[] | Promise<readonly string[]>;
+    /** Accept handshakes without an `Origin` header (non-browser clients). Default false. */
+    allowMissingOrigin?: boolean;
+    /** Returns false when the ticket id was already used (makes tickets single-use). */
+    isFirstUse?: (claims: SocketTicketClaims) => Promise<boolean>;
+    /** Called for every refused handshake. Must not throw. */
+    onRejected?: (rejection: SocketRejection) => void;
+    /** Socket.IO path, reported in rejections. */
+    path: string;
+}
+/**
+ * The handshake check on its own (testable without a server): verifies the ticket from
+ * `socket.handshake.auth.ticket`, then the browser origin against `allowedOrigins(claims)`, then
+ * single use.
+ *
+ * @param options Ticket keys, audience, origin rule, replay check and rejection hook.
+ * @returns `authenticate(socket)` resolving to the claims, or null when refused.
+ */
+export declare function createTicketHandshake(options: TicketHandshakeOptions): (socket: Pick<Socket, 'handshake'>) => Promise<SocketTicketClaims | null>;
+/** Settings for {@link createTicketSocketServer}. */
+export interface TicketSocketServerOptions extends Omit<TicketHandshakeOptions, 'isFirstUse'> {
+    httpServer: HttpServer;
+    /**
+     * Shared Redis: enables the `@socket.io/redis-adapter` fan-out across replicas (channel prefix from
+     * `keyspace`) and makes tickets single-use (`{keyspace}socket-ticket:{jti}`, TTL = ticket lifetime).
+     * Omit only for a single in-process instance (tests, local tools).
+     */
+    redis?: Redis;
+    /** The service's keyspace; required with `redis`. */
+    keyspace?: RedisKeyspace;
+    /** Extra rooms to join on connect, derived from the verified claims. `user:{userId}` is always joined. */
+    rooms?: (claims: SocketTicketClaims) => string[];
+    serverOptions?: Partial<ServerOptions>;
+    logger?: Logger;
+}
+/**
+ * Creates a Socket.IO server whose clients authenticate with a short-lived ticket
+ * (`io(url, { path, auth: (cb) => getTicket().then((ticket) => cb({ ticket })) })`). Each connection
+ * auto-joins `user:{userId}`; the verified claims are in `socket.data.identity` for later room checks
+ * with `canJoinScopeRoom`.
+ *
+ * @param options HTTP server, path, ticket keys, origin rule, Redis + keyspace, rejection hook.
+ * @returns The emitter.
+ * @example createTicketSocketServer({ httpServer, path: '/ws', secret, domain, audience: 'admin-app', redis, keyspace, allowedOrigins: () => origins, onRejected })
+ */
+export declare function createTicketSocketServer(options: TicketSocketServerOptions): SocketEmitter;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,oFAAoF;IACpF,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7E;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;IACrC,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,WAAqB,CAAC;AAE7D,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAmCtG;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,IACtC,QAAQ,MAAM,KAAG,QAAQ,GAAG,IAAI,CAIzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAA8C,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEzG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEnI,cAAc,aAAa,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,oFAAoF;IACpF,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7E;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;IACrC,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,mEAAmE;AACnE,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,WAAqB,CAAC;AAqD7D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAWtG;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,IAE/E,QAAQ,MAAM,KAAG,QAAQ,GAAG,IAAI,CAMzC;AAED,oGAAoG;AACpG,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,GAAG,oBAAoB,GAAG,UAAU,CAAC;AAE9F,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACrC,yGAAyG;IACzG,cAAc,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC/F,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,0DAA0D;IAC1D,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IAClD,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAiBhJ;AAED,qDAAqD;AACrD,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC;IAC3F,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0GAA0G;IAC1G,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,MAAM,EAAE,CAAC;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,aAAa,CAqB1F"}

package/dist/types/socket/ticket.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Short-lived socket handshake tickets. The browser cannot send its in-memory access token on a
+ * WebSocket upgrade header, so it asks the API for a ticket (≤ 60 s) and passes it in the Socket.IO
+ * `auth` payload. A ticket is `v1.<base64url claims>.<base64url HMAC-SHA256>`, signed over a domain
+ * separator so a ticket minted for another app or purpose never verifies here.
+ *
+ * Dependency-free (no socket.io), so the issuer can sign tickets without the socket stack.
+ */
+/** Longest allowed ticket lifetime (and the default), in seconds. */
+export declare const SOCKET_TICKET_MAX_TTL_SECONDS = 60;
+/** Shortest accepted signing secret. */
+export declare const MIN_SOCKET_TICKET_SECRET_LENGTH = 32;
+/** What the issuer puts in a ticket. */
+export interface SocketTicketInput {
+    userId: string;
+    /** Who the ticket is for (e.g. the front-end app); the server checks it. */
+    aud: string;
+    /** Resource ids the user may act on, keyed by scope name (as in `AuthUser.scopes`). */
+    scopes?: Record<string, string[]>;
+    permissions?: string[];
+    isSuperAdmin?: boolean;
+}
+/** Verified ticket claims. */
+export interface SocketTicketClaims {
+    userId: string;
+    aud: string;
+    scopes: Record<string, string[]>;
+    permissions: string[];
+    isSuperAdmin: boolean;
+    /** Unique id, so a server can make tickets single-use. */
+    jti: string;
+    /** Issued-at and expiry, epoch seconds. */
+    iat: number;
+    exp: number;
+}
+/** Signing and verification settings. */
+export interface SocketTicketKeyOptions {
+    /** Shared HMAC secret (at least 32 characters). */
+    secret: string;
+    /** Domain separator, e.g. `myapp-socket-ticket:v1`. */
+    domain: string;
+    /** Clock (tests). */
+    now?: () => Date;
+}
+/** Why a ticket was refused. */
+export type SocketTicketRejection = 'missing' | 'malformed' | 'bad_signature' | 'expired' | 'wrong_audience';
+/** Result of {@link verifySocketTicket}. */
+export type SocketTicketResult = {
+    ok: true;
+    claims: SocketTicketClaims;
+} | {
+    ok: false;
+    reason: SocketTicketRejection;
+};
+/**
+ * Signs a ticket.
+ *
+ * @param input User, audience, scopes and permissions.
+ * @param options Secret, domain separator and `ttlSeconds` (1–60, default 60).
+ * @returns The ticket string.
+ * @example signSocketTicket({ userId, aud: 'admin-app', scopes: { tenant: [tenantId] }, permissions }, { secret, domain: 'myapp-socket-ticket:v1' })
+ */
+export declare function signSocketTicket(input: SocketTicketInput, options: SocketTicketKeyOptions & {
+    ttlSeconds?: number;
+}): string;
+/**
+ * Verifies a ticket's signature, domain, lifetime and audience. Never throws for a bad ticket.
+ *
+ * @param ticket The string from the handshake.
+ * @param options Secret, domain separator and the accepted audience(s).
+ * @returns The claims, or the rejection reason.
+ * @example const result = verifySocketTicket(socket.handshake.auth.ticket, { secret, domain, audience: 'admin-app' });
+ */
+export declare function verifySocketTicket(ticket: unknown, options: SocketTicketKeyOptions & {
+    audience: string | readonly string[];
+}): SocketTicketResult;
+/** Name of the room for one scope id, e.g. `tenant:01J…`. */
+export declare const scopeRoom: (scope: string, scopeId: string) => string;
+/**
+ * True when the ticket holder may join the room of `scopeId` in `scope`: the id is in the ticket's scope
+ * ids (or the holder is a super admin) and, when given, the holder has `permission`.
+ *
+ * @param claims Verified ticket claims.
+ * @param scope Scope name, e.g. `tenant`.
+ * @param scopeId The id whose room is requested.
+ * @param permission Permission the room needs (optional).
+ * @example canJoinScopeRoom(claims, 'tenant', tenantId, 'widgets.view')
+ */
+export declare function canJoinScopeRoom(claims: SocketTicketClaims, scope: string, scopeId: string, permission?: string): boolean;
+//# sourceMappingURL=ticket.d.ts.map