@awesome-lang-auth/node 1.10.1

package/dist/tools/sse-notify.decorator.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseNotifyRegistry = void 0;
+exports.sseNotify = sseNotify;
+/**
+ * Global registry and dispatcher for decorated SSE notifications.
+ */
+class SseNotifyRegistry {
+    /**
+     * Set the active SSE manager used for broadcasts.  Should be called
+     * during application initialization.
+     */
+    static setManager(manager) {
+        this.manager = manager;
+    }
+    /**
+     * Perform a broadcast if a manager is registered.
+     */
+    static notify(topic, event) {
+        if (!this.manager)
+            return;
+        this.manager.broadcast(topic, event);
+    }
+    /**
+     * Internal helper to execute notification logic.
+     * Can be called manually to bypass decorators.
+     */
+    static async executeNotify(options, args, result) {
+        try {
+            const topic = typeof options.topic === 'function' ? options.topic(args, result) : options.topic;
+            const data = options.payload ? options.payload(result, args) : result;
+            const eventType = options.event ?? 'notification';
+            const tenantId = options.tenantId ? options.tenantId(result, args) : undefined;
+            const userId = options.userId ? options.userId(result, args) : undefined;
+            this.notify(topic, {
+                type: eventType,
+                data,
+                tenantId,
+                userId,
+            });
+        }
+        catch (err) {
+            console.error('[SseNotifyRegistry] Error in notification logic:', err);
+        }
+    }
+}
+exports.SseNotifyRegistry = SseNotifyRegistry;
+SseNotifyRegistry.manager = null;
+/**
+ * Method decorator that automatically triggers an SSE broadcast after
+ * successful execution.
+ *
+ * Uses the **TC39 Stage 3** decorator syntax (TypeScript 5.x+).
+ * For legacy environments, use manual notification via `SseNotifyRegistry.notify()`.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @sseNotify({
+ *     topic: (_args, user) => `user:${user.id}`,
+ *     event: 'user.updated',
+ *   })
+ *   async updateProfile(userId: string, data: any) {
+ *     return await db.users.update(userId, data);
+ *   }
+ * }
+ * ```
+ */
+function sseNotify(options) {
+    return function (target, _context) {
+        return async function (...args) {
+            const result = await target.apply(this, args);
+            await SseNotifyRegistry.executeNotify(options, args, result);
+            return result;
+        };
+    };
+}
+//# sourceMappingURL=sse-notify.decorator.js.map

package/dist/tools/sse-notify.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-notify.decorator.js","sourceRoot":"","sources":["../../src/tools/sse-notify.decorator.ts"],"names":[],"mappings":";;;AAmGA,8BAWC;AA7ED;;GAEG;AACH,MAAa,iBAAiB;IAG1B;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,OAA0B;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,KAAa,EAAE,KAAsE;QAC/F,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAyB,EAAE,IAAW,EAAE,MAAW;QAC1E,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;YAChG,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACtE,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;YAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC/E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAEzE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;gBACf,IAAI,EAAE,SAAS;gBACf,IAAI;gBACJ,QAAQ;gBACR,MAAM;aACT,CAAC,CAAC;QACP,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,kDAAkD,EAAE,GAAG,CAAC,CAAC;QAC3E,CAAC;IACL,CAAC;;AAxCL,8CAyCC;AAxCkB,yBAAO,GAAsB,IAAI,CAAC;AA0CrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,SAAS,CAAC,OAAyB;IAC/C,OAAO,UACH,MAA+D,EAC/D,QAAoG;QAEpG,OAAO,KAAK,WAAuB,GAAG,IAAU;YAC5C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC9C,MAAM,iBAAiB,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7D,OAAO,MAAM,CAAC;QAClB,CAAC,CAAC;IACN,CAAC,CAAC;AACN,CAAC"}

package/dist/tools/webhook-action.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @webhookAction decorator and ActionRegistry.
+ *
+ * Developers annotate service methods with `@webhookAction` to expose them
+ * safely inside the `vm` sandbox when an inbound webhook fires.  The admin UI
+ * can then:
+ *   1. Globally enable / disable each action (via `ISettingsStore.enabledWebhookActions`).
+ *   2. Assign a per-webhook subset of those enabled actions to each inbound
+ *      webhook config (`WebhookConfig.allowedActions`).
+ *
+ * The sandbox only receives the **intersection** of both sets, enforcing the
+ * Principle of Least Privilege.
+ *
+ * @example
+ * ```typescript
+ * import { webhookAction } from '@awesome-lang-auth/node';
+ *
+ * class UserService {
+ *   \@webhookAction({
+ *     id: 'user.suspend',
+ *     label: 'Suspend user',
+ *     category: 'Users',
+ *     description: 'Set isActive=false on a user record.',
+ *   })
+ *   async suspendUser(userId: string): Promise<void> { ... }
+ * }
+ *
+ * const svc = new UserService();
+ * ActionRegistry.register({ id: 'user.suspend', ..., fn: svc.suspendUser.bind(svc) });
+ * ```
+ */
+/** Metadata for a single webhook action. */
+export interface WebhookActionMeta {
+    /** Stable machine identifier, e.g. `'user.suspend'`. */
+    id: string;
+    /** Human-readable label shown in the Admin UI. */
+    label: string;
+    /** Grouping category shown in the Admin UI. */
+    category: string;
+    /** Short description shown in the Admin UI. */
+    description: string;
+    /**
+     * Other action IDs that must be globally enabled for this action to be
+     * available.  The UI will disable this action's toggle if any dependency
+     * is not met.
+     */
+    dependsOn?: string[];
+}
+/** Registered action entry (metadata + callable function reference). */
+export interface RegisteredAction extends WebhookActionMeta {
+    fn: (...args: unknown[]) => unknown;
+}
+/**
+ * Registry of all webhook-exposed actions.
+ *
+ * All methods are static so the registry is accessible anywhere without
+ * instantiation.
+ */
+export declare class ActionRegistry {
+    /**
+     * Register an action.  Called automatically by the `@webhookAction`
+     * decorator, but can also be called manually (useful when the action
+     * function is not on a class instance at decoration time).
+     */
+    static register(entry: RegisteredAction): void;
+    /** Return all registered actions (metadata + function). */
+    static getAll(): RegisteredAction[];
+    /** Return metadata for all registered actions (no function references). */
+    static getAllMeta(): WebhookActionMeta[];
+    /**
+     * Look up a single registered action by ID.
+     * Returns `undefined` when not found.
+     */
+    static get(id: string): RegisteredAction | undefined;
+    /**
+     * Build the `actions` context object injected into the `vm` sandbox.
+     *
+     * Only includes actions that satisfy **all three** conditions:
+     *  1. Registered in the registry.
+     *  2. Listed in `enabledIds` (globally enabled by the admin).
+     *  3. Listed in `allowedIds`  (assigned to this specific webhook).
+     *
+     * Additionally, a registered action is excluded if any of its `dependsOn`
+     * entries are not in the effective allowed set.
+     *
+     * @param enabledIds  Globally enabled action IDs (`AuthSettings.enabledWebhookActions`).
+     * @param allowedIds  Per-webhook allowed action IDs (`WebhookConfig.allowedActions`).
+     * @returns           A `Record<id, fn>` object safe to pass as the `actions` sandbox variable.
+     */
+    static buildContext(enabledIds: string[], allowedIds: string[]): Record<string, (...args: unknown[]) => unknown>;
+    /** Remove all entries (useful in tests). */
+    static clear(): void;
+}
+/**
+ * Method decorator that registers the decorated method in the `ActionRegistry`
+ * using the provided metadata.
+ *
+ * Uses the **TC39 Stage 3** decorator syntax (TypeScript 5.x without
+ * `experimentalDecorators`).
+ *
+ * The function reference stored in the registry is the **unbound** method.
+ * For instance methods, pass a bound function when calling
+ * `ActionRegistry.register` at runtime, or bind the instance manually:
+ *
+ * ```typescript
+ * const svc = new BillingService();
+ * ActionRegistry.register({
+ *   id: 'billing.cancelSubscription',
+ *   label: 'Cancel subscription',
+ *   category: 'Billing',
+ *   description: 'Cancel a subscription.',
+ *   fn: svc.cancelSubscription.bind(svc),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class BillingService {
+ *   \@webhookAction({
+ *     id: 'billing.cancelSubscription',
+ *     label: 'Cancel subscription',
+ *     category: 'Billing',
+ *     description: 'Cancel a user subscription in the billing system.',
+ *   })
+ *   async cancelSubscription(subscriptionId: string): Promise<void> { ... }
+ * }
+ * ```
+ */
+export declare function webhookAction(meta: WebhookActionMeta): <This, Args extends unknown[], Return>(value: (this: This, ...args: Args) => Return, _context: ClassMethodDecoratorContext) => (this: This, ...args: Args) => Return;
+//# sourceMappingURL=webhook-action.d.ts.map

package/dist/tools/webhook-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-action.d.ts","sourceRoot":"","sources":["../../src/tools/webhook-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CACrC;AAKD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB;;;;OAIG;IAEH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAG9C,2DAA2D;IAC3D,MAAM,CAAC,MAAM,IAAI,gBAAgB,EAAE;IAInC,2EAA2E;IAC3E,MAAM,CAAC,UAAU,IAAI,iBAAiB,EAAE;IAIxC;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIpD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAWhH,4CAA4C;IAC5C,MAAM,CAAC,KAAK,IAAI,IAAI;CAGrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,IAClC,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACnD,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC5C,UAAU,2BAA2B,KACpC,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAKzC"}

package/dist/tools/webhook-action.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * @webhookAction decorator and ActionRegistry.
+ *
+ * Developers annotate service methods with `@webhookAction` to expose them
+ * safely inside the `vm` sandbox when an inbound webhook fires.  The admin UI
+ * can then:
+ *   1. Globally enable / disable each action (via `ISettingsStore.enabledWebhookActions`).
+ *   2. Assign a per-webhook subset of those enabled actions to each inbound
+ *      webhook config (`WebhookConfig.allowedActions`).
+ *
+ * The sandbox only receives the **intersection** of both sets, enforcing the
+ * Principle of Least Privilege.
+ *
+ * @example
+ * ```typescript
+ * import { webhookAction } from '@awesome-lang-auth/node';
+ *
+ * class UserService {
+ *   \@webhookAction({
+ *     id: 'user.suspend',
+ *     label: 'Suspend user',
+ *     category: 'Users',
+ *     description: 'Set isActive=false on a user record.',
+ *   })
+ *   async suspendUser(userId: string): Promise<void> { ... }
+ * }
+ *
+ * const svc = new UserService();
+ * ActionRegistry.register({ id: 'user.suspend', ..., fn: svc.suspendUser.bind(svc) });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionRegistry = void 0;
+exports.webhookAction = webhookAction;
+// Module-level registry (populated at boot time via `@webhookAction` or manual calls)
+const _registry = new Map();
+/**
+ * Registry of all webhook-exposed actions.
+ *
+ * All methods are static so the registry is accessible anywhere without
+ * instantiation.
+ */
+class ActionRegistry {
+    /**
+     * Register an action.  Called automatically by the `@webhookAction`
+     * decorator, but can also be called manually (useful when the action
+     * function is not on a class instance at decoration time).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static register(entry) {
+        _registry.set(entry.id, entry);
+    }
+    /** Return all registered actions (metadata + function). */
+    static getAll() {
+        return [..._registry.values()];
+    }
+    /** Return metadata for all registered actions (no function references). */
+    static getAllMeta() {
+        return [..._registry.values()].map(({ fn: _fn, ...meta }) => meta);
+    }
+    /**
+     * Look up a single registered action by ID.
+     * Returns `undefined` when not found.
+     */
+    static get(id) {
+        return _registry.get(id);
+    }
+    /**
+     * Build the `actions` context object injected into the `vm` sandbox.
+     *
+     * Only includes actions that satisfy **all three** conditions:
+     *  1. Registered in the registry.
+     *  2. Listed in `enabledIds` (globally enabled by the admin).
+     *  3. Listed in `allowedIds`  (assigned to this specific webhook).
+     *
+     * Additionally, a registered action is excluded if any of its `dependsOn`
+     * entries are not in the effective allowed set.
+     *
+     * @param enabledIds  Globally enabled action IDs (`AuthSettings.enabledWebhookActions`).
+     * @param allowedIds  Per-webhook allowed action IDs (`WebhookConfig.allowedActions`).
+     * @returns           A `Record<id, fn>` object safe to pass as the `actions` sandbox variable.
+     */
+    static buildContext(enabledIds, allowedIds) {
+        const effectiveSet = new Set(allowedIds.filter((id) => enabledIds.includes(id)));
+        const ctx = {};
+        for (const [id, entry] of _registry) {
+            if (!effectiveSet.has(id))
+                continue;
+            const depsOk = (entry.dependsOn ?? []).every((dep) => effectiveSet.has(dep));
+            if (depsOk)
+                ctx[id] = entry.fn;
+        }
+        return ctx;
+    }
+    /** Remove all entries (useful in tests). */
+    static clear() {
+        _registry.clear();
+    }
+}
+exports.ActionRegistry = ActionRegistry;
+/**
+ * Method decorator that registers the decorated method in the `ActionRegistry`
+ * using the provided metadata.
+ *
+ * Uses the **TC39 Stage 3** decorator syntax (TypeScript 5.x without
+ * `experimentalDecorators`).
+ *
+ * The function reference stored in the registry is the **unbound** method.
+ * For instance methods, pass a bound function when calling
+ * `ActionRegistry.register` at runtime, or bind the instance manually:
+ *
+ * ```typescript
+ * const svc = new BillingService();
+ * ActionRegistry.register({
+ *   id: 'billing.cancelSubscription',
+ *   label: 'Cancel subscription',
+ *   category: 'Billing',
+ *   description: 'Cancel a subscription.',
+ *   fn: svc.cancelSubscription.bind(svc),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * class BillingService {
+ *   \@webhookAction({
+ *     id: 'billing.cancelSubscription',
+ *     label: 'Cancel subscription',
+ *     category: 'Billing',
+ *     description: 'Cancel a user subscription in the billing system.',
+ *   })
+ *   async cancelSubscription(subscriptionId: string): Promise<void> { ... }
+ * }
+ * ```
+ */
+function webhookAction(meta) {
+    return function (value, _context) {
+        // Register the unbound method
+        ActionRegistry.register({ ...meta, fn: value });
+        return value;
+    };
+}
+//# sourceMappingURL=webhook-action.js.map

package/dist/tools/webhook-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-action.js","sourceRoot":"","sources":["../../src/tools/webhook-action.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAiIH,sCASC;AAjHD,sFAAsF;AACtF,MAAM,SAAS,GAAG,IAAI,GAAG,EAA4B,CAAC;AAEtD;;;;;GAKG;AACH,MAAa,cAAc;IACzB;;;;OAIG;IACH,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,CAAC,KAAuB;QAAa,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACnF,CAAC;IAED,2DAA2D;IAC3D,MAAM,CAAC,MAAM;QACX,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,MAAM,CAAC,UAAU;QACf,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,EAAU;QACnB,OAAO,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,UAAoB,EAAE,UAAoB;QAC5D,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACjF,MAAM,GAAG,GAAoD,EAAE,CAAC;QAChE,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YACpC,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7E,IAAI,MAAM;gBAAE,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,KAAK;QACV,SAAS,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF;AA1DD,wCA0DC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,SAAgB,aAAa,CAAC,IAAuB;IACnD,OAAO,UACL,KAA4C,EAC5C,QAAqC;QAErC,8BAA8B;QAC9B,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAwC,EAAE,CAAC,CAAC;QACnF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/tools/webhook-sender.d.ts

@@ -0,0 +1,31 @@
+import { WebhookConfig, OutgoingWebhookEvent } from '../interfaces/webhook-store.interface';
+/**
+ * Sends outgoing webhooks with optional HMAC signing and exponential
+ * back-off retry.
+ */
+export declare class WebhookSender {
+    /**
+     * Deliver an event to a single webhook endpoint.
+     * Retries on transient HTTP errors according to the webhook's `maxRetries`
+     * and `retryDelayMs` settings.
+     *
+     * @param config  Webhook configuration (URL, secret, retry policy, …).
+     * @param event   The event payload to deliver.
+     */
+    send(config: WebhookConfig, event: OutgoingWebhookEvent): Promise<void>;
+    /**
+     * Compute an HMAC-SHA256 signature of `body` using `secret`.
+     * The signature is returned as `sha256=<hex>` so receivers can verify it.
+     */
+    sign(body: string, secret: string): string;
+    /**
+     * Verify an inbound webhook signature.
+     * Returns `true` when the `X-Webhook-Signature` header matches the
+     * expected HMAC-SHA256 of the raw request body.
+     *
+     * Use constant-time comparison to prevent timing attacks.
+     */
+    verify(body: string, secret: string, signature: string): boolean;
+    private delay;
+}
+//# sourceMappingURL=webhook-sender.d.ts.map

package/dist/tools/webhook-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-sender.d.ts","sourceRoot":"","sources":["../../src/tools/webhook-sender.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAE5F;;;GAGG;AACH,qBAAa,aAAa;IACxB;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC7E;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAI1C;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAWhE,OAAO,CAAC,KAAK;CAGd"}

package/dist/tools/webhook-sender.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSender = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Sends outgoing webhooks with optional HMAC signing and exponential
+ * back-off retry.
+ */
+class WebhookSender {
+    /**
+     * Deliver an event to a single webhook endpoint.
+     * Retries on transient HTTP errors according to the webhook's `maxRetries`
+     * and `retryDelayMs` settings.
+     *
+     * @param config  Webhook configuration (URL, secret, retry policy, …).
+     * @param event   The event payload to deliver.
+     */
+    async send(config, event) {
+        const maxRetries = config.maxRetries ?? 3;
+        const baseDelayMs = config.retryDelayMs ?? 1000;
+        const body = JSON.stringify(event);
+        let attempt = 0;
+        while (attempt <= maxRetries) {
+            const headers = {
+                'Content-Type': 'application/json',
+                'X-Webhook-Event': event.event,
+                'X-Webhook-Delivery': (0, crypto_1.randomUUID)(),
+                'X-Webhook-Timestamp': event.timestamp,
+            };
+            if (config.secret) {
+                headers['X-Webhook-Signature'] = this.sign(body, config.secret);
+            }
+            try {
+                const res = await fetch(config.url, { method: 'POST', headers, body });
+                if (res.ok)
+                    return;
+                // Non-2xx: retry if attempts remain
+                if (attempt >= maxRetries)
+                    return;
+            }
+            catch {
+                // Network error: retry if attempts remain
+                if (attempt >= maxRetries)
+                    return;
+            }
+            attempt++;
+            await this.delay(baseDelayMs * Math.pow(2, attempt - 1));
+        }
+    }
+    /**
+     * Compute an HMAC-SHA256 signature of `body` using `secret`.
+     * The signature is returned as `sha256=<hex>` so receivers can verify it.
+     */
+    sign(body, secret) {
+        return 'sha256=' + (0, crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+    }
+    /**
+     * Verify an inbound webhook signature.
+     * Returns `true` when the `X-Webhook-Signature` header matches the
+     * expected HMAC-SHA256 of the raw request body.
+     *
+     * Use constant-time comparison to prevent timing attacks.
+     */
+    verify(body, secret, signature) {
+        const expected = this.sign(body, secret);
+        // Constant-time comparison
+        if (expected.length !== signature.length)
+            return false;
+        let diff = 0;
+        for (let i = 0; i < expected.length; i++) {
+            diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+        }
+        return diff === 0;
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.WebhookSender = WebhookSender;
+//# sourceMappingURL=webhook-sender.js.map

package/dist/tools/webhook-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-sender.js","sourceRoot":"","sources":["../../src/tools/webhook-sender.ts"],"names":[],"mappings":";;;AAAA,mCAAgD;AAGhD;;;GAGG;AACH,MAAa,aAAa;IACxB;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,MAAqB,EAAE,KAA2B;QAC3D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;QAC1C,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,IAAI,IAAK,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAEnC,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,OAAO,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,OAAO,GAA2B;gBACtC,cAAc,EAAE,kBAAkB;gBAClC,iBAAiB,EAAE,KAAK,CAAC,KAAK;gBAC9B,oBAAoB,EAAE,IAAA,mBAAU,GAAE;gBAClC,qBAAqB,EAAE,KAAK,CAAC,SAAS;aACvC,CAAC;YAEF,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;YAClE,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;gBACvE,IAAI,GAAG,CAAC,EAAE;oBAAE,OAAO;gBACnB,oCAAoC;gBACpC,IAAI,OAAO,IAAI,UAAU;oBAAE,OAAO;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,0CAA0C;gBAC1C,IAAI,OAAO,IAAI,UAAU;oBAAE,OAAO;YACpC,CAAC;YAED,OAAO,EAAE,CAAC;YACV,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAY,EAAE,MAAc;QAC/B,OAAO,SAAS,GAAG,IAAA,mBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAY,EAAE,MAAc,EAAE,SAAiB;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzC,2BAA2B;QAC3B,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACvD,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,KAAK,CAAC,CAAC;IACpB,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AAvED,sCAuEC"}

package/dist/ui-assets/2fa.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>2FA Verification - Awesome Node Auth</title>
+    <link rel="stylesheet" href="base.css">
+</head>
+
+<body>
+    <div class="auth-container">
+        <img src="" alt="Logo" class="logo hidden">
+        <h1 class="site-name" data-i18n="site_name">Awesome Node Auth</h1>
+        <h2 data-i18n="two_fa_title">Two-Factor Authentication</h2>
+
+        <div id="alert" class="alert alert-error hidden"></div>
+
+        <form id="2fa-form">
+            <div class="form-group">
+                <label for="code" data-i18n="two_fa_code_label">Verification Code</label>
+                <p id="method-text" class="footer-links" style="margin-bottom: 8px; text-align: left; font-size: 12px;">
+                </p>
+                <input type="text" id="code" name="code" required placeholder="000000" data-i18n="two_fa_code_placeholder"
+                    style="text-align: center; letter-spacing: 4px; font-size: 18px;">
+            </div>
+            <button type="submit" id="submit-btn" data-i18n="verify_code_button">Verify Code</button>
+        </form>
+
+        <div id="setup-section" class="hidden">
+            <p class="footer-links" data-i18n="two_fa_setup_instruction">Scan this QR code with your authenticator app:</p>
+            <img id="qr-code" style="display: block; margin: 16px auto; width: 200px; height: 200px;">
+            <p class="footer-links" style="font-size: 12px;">Or enter this code manually: <strong id="secret"></strong>
+            </p>
+        </div>
+
+        <div class="footer-links">
+            <a href="login">Back to login</a>
+        </div>
+    </div>
+
+    <script src="auth.js?v=2"></script>
+    <script>
+        document.addEventListener('DOMContentLoaded', async () => {
+            await AuthService.init();
+
+            const urlParams = new URLSearchParams(window.location.search);
+            const token = urlParams.get('token');
+            const mode = urlParams.get('mode') || 'verify'; // verify or setup
+
+            if (!token && mode !== 'setup') {
+                window.location.href = 'login';
+                return;
+            }
+
+            const form = document.getElementById('2fa-form');
+            const alert = document.getElementById('alert');
+            const submitBtn = document.getElementById('submit-btn');
+            const methodText = document.getElementById('method-text');
+
+            if (mode === 'setup') {
+                document.querySelector('h2').textContent = '2FA Setup';
+                document.getElementById('setup-section').classList.remove('hidden');
+
+                // Fetch setup data
+                const setupData = await AuthService.apiCall('/2fa/setup', 'POST');
+                if (setupData.qrCode) {
+                    document.getElementById('qr-code').src = setupData.qrCode;
+                    document.getElementById('secret').textContent = setupData.secret;
+                } else {
+                    alert.textContent = 'Failed to load 2FA setup';
+                    alert.classList.remove('hidden');
+                }
+            } else {
+                methodText.textContent = 'Enter the code from your Authenticator App or SMS.';
+            }
+
+            form.addEventListener('submit', async (e) => {
+                e.preventDefault();
+                alert.className = 'alert alert-error hidden';
+                submitBtn.disabled = true;
+                submitBtn.textContent = 'Verifying...';
+
+                const code = form.code.value;
+
+                try {
+                    let endpoint = '/2fa/verify';
+                    let payload = { tempToken: token, totpCode: code };
+
+                    if (mode === 'setup') {
+                        endpoint = '/2fa/verify-setup';
+                        payload = { token: code, secret: document.getElementById('secret').textContent };
+                    }
+
+                    const result = await AuthService.apiCall(endpoint, 'POST', payload);
+
+                    if (result.success) {
+                        window.location.href = '/';
+                    } else {
+                        alert.textContent = result.error || 'Verification failed';
+                        alert.classList.remove('hidden');
+                    }
+                } catch (err) {
+                    alert.textContent = 'An unexpected error occurred';
+                    alert.classList.remove('hidden');
+                } finally {
+                    submitBtn.disabled = false;
+                    submitBtn.textContent = mode === 'setup' ? 'Verify Setup' : 'Verify Code';
+                }
+            });
+        });
+    </script>
+</body>
+
+</html>