@awesome-lang-auth/node 1.10.1

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAdminOpenApiSpec = exports.buildAuthOpenApiSpec = exports.buildSwaggerUiHtml = exports.buildOpenApiSpec = exports.createToolsRouter = exports.sseNotify = exports.SseNotifyRegistry = exports.webhookAction = exports.ActionRegistry = exports.AuthTools = exports.WebhookSender = exports.SseManager = exports.AuthEventNames = exports.AuthEventBus = exports.buildUiRouter = exports.createAdminRouter = exports.buildUiLink = exports.createAuthRouter = exports.createJwksAuthMiddleware = exports.createApiKeyMiddleware = exports.createAuthMiddleware = exports.JwksClient = exports.JwksService = exports.ApiKeyService = exports.NotificationService = exports.MailerService = exports.SmsService = exports.PasswordService = exports.TokenService = exports.ApiKeyStrategy = exports.TotpStrategy = exports.SmsStrategy = exports.MagicLinkStrategy = exports.GenericOAuthStrategy = exports.GithubStrategy = exports.GoogleStrategy = exports.LocalStrategy = exports.BaseOAuthStrategy = exports.BaseAuthStrategy = exports.AuthError = exports.MemoryTemplateStore = exports.fastifyAdapter = exports.expressAdapter = exports.AuthConfigurator = void 0;
+var auth_configurator_1 = require("./auth-configurator");
+Object.defineProperty(exports, "AuthConfigurator", { enumerable: true, get: function () { return auth_configurator_1.AuthConfigurator; } });
+// ---- Framework adapters -------------------------------------------------------
+var express_1 = require("./adapters/express");
+Object.defineProperty(exports, "expressAdapter", { enumerable: true, get: function () { return express_1.expressAdapter; } });
+var fastify_1 = require("./adapters/fastify");
+Object.defineProperty(exports, "fastifyAdapter", { enumerable: true, get: function () { return fastify_1.fastifyAdapter; } });
+var memory_template_store_1 = require("./stores/memory-template.store");
+Object.defineProperty(exports, "MemoryTemplateStore", { enumerable: true, get: function () { return memory_template_store_1.MemoryTemplateStore; } });
+var errors_1 = require("./models/errors");
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_1.AuthError; } });
+var base_auth_strategy_abstract_1 = require("./abstract/base-auth-strategy.abstract");
+Object.defineProperty(exports, "BaseAuthStrategy", { enumerable: true, get: function () { return base_auth_strategy_abstract_1.BaseAuthStrategy; } });
+var base_oauth_strategy_abstract_1 = require("./abstract/base-oauth-strategy.abstract");
+Object.defineProperty(exports, "BaseOAuthStrategy", { enumerable: true, get: function () { return base_oauth_strategy_abstract_1.BaseOAuthStrategy; } });
+var local_strategy_1 = require("./strategies/local/local.strategy");
+Object.defineProperty(exports, "LocalStrategy", { enumerable: true, get: function () { return local_strategy_1.LocalStrategy; } });
+var google_strategy_1 = require("./strategies/oauth/google.strategy");
+Object.defineProperty(exports, "GoogleStrategy", { enumerable: true, get: function () { return google_strategy_1.GoogleStrategy; } });
+var github_strategy_1 = require("./strategies/oauth/github.strategy");
+Object.defineProperty(exports, "GithubStrategy", { enumerable: true, get: function () { return github_strategy_1.GithubStrategy; } });
+var generic_oauth_strategy_1 = require("./strategies/oauth/generic-oauth.strategy");
+Object.defineProperty(exports, "GenericOAuthStrategy", { enumerable: true, get: function () { return generic_oauth_strategy_1.GenericOAuthStrategy; } });
+var magic_link_strategy_1 = require("./strategies/magic-link/magic-link.strategy");
+Object.defineProperty(exports, "MagicLinkStrategy", { enumerable: true, get: function () { return magic_link_strategy_1.MagicLinkStrategy; } });
+var sms_strategy_1 = require("./strategies/sms/sms.strategy");
+Object.defineProperty(exports, "SmsStrategy", { enumerable: true, get: function () { return sms_strategy_1.SmsStrategy; } });
+var totp_strategy_1 = require("./strategies/two-factor/totp.strategy");
+Object.defineProperty(exports, "TotpStrategy", { enumerable: true, get: function () { return totp_strategy_1.TotpStrategy; } });
+var api_key_strategy_1 = require("./strategies/api-key/api-key.strategy");
+Object.defineProperty(exports, "ApiKeyStrategy", { enumerable: true, get: function () { return api_key_strategy_1.ApiKeyStrategy; } });
+var token_service_1 = require("./services/token.service");
+Object.defineProperty(exports, "TokenService", { enumerable: true, get: function () { return token_service_1.TokenService; } });
+var password_service_1 = require("./services/password.service");
+Object.defineProperty(exports, "PasswordService", { enumerable: true, get: function () { return password_service_1.PasswordService; } });
+var sms_service_1 = require("./services/sms.service");
+Object.defineProperty(exports, "SmsService", { enumerable: true, get: function () { return sms_service_1.SmsService; } });
+var mailer_service_1 = require("./services/mailer.service");
+Object.defineProperty(exports, "MailerService", { enumerable: true, get: function () { return mailer_service_1.MailerService; } });
+var notification_service_1 = require("./services/notification.service");
+Object.defineProperty(exports, "NotificationService", { enumerable: true, get: function () { return notification_service_1.NotificationService; } });
+var api_key_service_1 = require("./services/api-key.service");
+Object.defineProperty(exports, "ApiKeyService", { enumerable: true, get: function () { return api_key_service_1.ApiKeyService; } });
+var jwks_service_1 = require("./services/jwks.service");
+Object.defineProperty(exports, "JwksService", { enumerable: true, get: function () { return jwks_service_1.JwksService; } });
+var jwks_service_2 = require("./services/jwks.service");
+Object.defineProperty(exports, "JwksClient", { enumerable: true, get: function () { return jwks_service_2.JwksClient; } });
+var auth_middleware_1 = require("./middleware/auth.middleware");
+Object.defineProperty(exports, "createAuthMiddleware", { enumerable: true, get: function () { return auth_middleware_1.createAuthMiddleware; } });
+var api_key_middleware_1 = require("./middleware/api-key.middleware");
+Object.defineProperty(exports, "createApiKeyMiddleware", { enumerable: true, get: function () { return api_key_middleware_1.createApiKeyMiddleware; } });
+var jwks_auth_middleware_1 = require("./middleware/jwks-auth.middleware");
+Object.defineProperty(exports, "createJwksAuthMiddleware", { enumerable: true, get: function () { return jwks_auth_middleware_1.createJwksAuthMiddleware; } });
+var auth_router_1 = require("./router/auth.router");
+Object.defineProperty(exports, "createAuthRouter", { enumerable: true, get: function () { return auth_router_1.createAuthRouter; } });
+Object.defineProperty(exports, "buildUiLink", { enumerable: true, get: function () { return auth_router_1.buildUiLink; } });
+var admin_router_1 = require("./router/admin.router");
+Object.defineProperty(exports, "createAdminRouter", { enumerable: true, get: function () { return admin_router_1.createAdminRouter; } });
+var ui_router_1 = require("./router/ui.router");
+Object.defineProperty(exports, "buildUiRouter", { enumerable: true, get: function () { return ui_router_1.buildUiRouter; } });
+// ---- Event-driven tools system -------------------------------------------
+var auth_event_bus_1 = require("./events/auth-event-bus");
+Object.defineProperty(exports, "AuthEventBus", { enumerable: true, get: function () { return auth_event_bus_1.AuthEventBus; } });
+var auth_event_names_1 = require("./events/auth-event-names");
+Object.defineProperty(exports, "AuthEventNames", { enumerable: true, get: function () { return auth_event_names_1.AuthEventNames; } });
+var sse_manager_1 = require("./tools/sse-manager");
+Object.defineProperty(exports, "SseManager", { enumerable: true, get: function () { return sse_manager_1.SseManager; } });
+var webhook_sender_1 = require("./tools/webhook-sender");
+Object.defineProperty(exports, "WebhookSender", { enumerable: true, get: function () { return webhook_sender_1.WebhookSender; } });
+var auth_tools_1 = require("./tools/auth-tools");
+Object.defineProperty(exports, "AuthTools", { enumerable: true, get: function () { return auth_tools_1.AuthTools; } });
+var webhook_action_1 = require("./tools/webhook-action");
+Object.defineProperty(exports, "ActionRegistry", { enumerable: true, get: function () { return webhook_action_1.ActionRegistry; } });
+Object.defineProperty(exports, "webhookAction", { enumerable: true, get: function () { return webhook_action_1.webhookAction; } });
+var sse_notify_decorator_1 = require("./tools/sse-notify.decorator");
+Object.defineProperty(exports, "SseNotifyRegistry", { enumerable: true, get: function () { return sse_notify_decorator_1.SseNotifyRegistry; } });
+Object.defineProperty(exports, "sseNotify", { enumerable: true, get: function () { return sse_notify_decorator_1.sseNotify; } });
+var tools_router_1 = require("./router/tools.router");
+Object.defineProperty(exports, "createToolsRouter", { enumerable: true, get: function () { return tools_router_1.createToolsRouter; } });
+var openapi_1 = require("./router/openapi");
+Object.defineProperty(exports, "buildOpenApiSpec", { enumerable: true, get: function () { return openapi_1.buildOpenApiSpec; } });
+Object.defineProperty(exports, "buildSwaggerUiHtml", { enumerable: true, get: function () { return openapi_1.buildSwaggerUiHtml; } });
+Object.defineProperty(exports, "buildAuthOpenApiSpec", { enumerable: true, get: function () { return openapi_1.buildAuthOpenApiSpec; } });
+Object.defineProperty(exports, "buildAdminOpenApiSpec", { enumerable: true, get: function () { return openapi_1.buildAdminOpenApiSpec; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA;AAMzB,kFAAkF;AAClF,8CAAoD;AAA3C,yGAAA,cAAc,OAAA;AACvB,8CAAoD;AAA3C,yGAAA,cAAc,OAAA;AAevB,wEAAqE;AAA5D,4HAAA,mBAAmB,OAAA;AAO5B,0CAA4C;AAAnC,mGAAA,SAAS,OAAA;AAGlB,sFAA0E;AAAjE,+HAAA,gBAAgB,OAAA;AACzB,wFAA4E;AAAnE,iIAAA,iBAAiB,OAAA;AAE1B,oEAAkE;AAAzD,+GAAA,aAAa,OAAA;AACtB,sEAAoE;AAA3D,iHAAA,cAAc,OAAA;AACvB,sEAAoE;AAA3D,iHAAA,cAAc,OAAA;AACvB,oFAAiF;AAAxE,8HAAA,oBAAoB,OAAA;AAE7B,mFAAgF;AAAvE,wHAAA,iBAAiB,OAAA;AAC1B,8DAA4D;AAAnD,2GAAA,WAAW,OAAA;AACpB,uEAAqE;AAA5D,6GAAA,YAAY,OAAA;AACrB,0EAAuE;AAA9D,kHAAA,cAAc,OAAA;AAGvB,0DAAwD;AAA/C,6GAAA,YAAY,OAAA;AACrB,gEAA8D;AAArD,mHAAA,eAAe,OAAA;AACxB,sDAAoD;AAA3C,yGAAA,UAAU,OAAA;AACnB,4DAA0D;AAAjD,+GAAA,aAAa,OAAA;AACtB,wEAAsE;AAA7D,2HAAA,mBAAmB,OAAA;AAG5B,8DAA2D;AAAlD,gHAAA,aAAa,OAAA;AAEtB,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AAEpB,wDAAqD;AAA5C,0GAAA,UAAU,OAAA;AAGnB,gEAAoE;AAA3D,uHAAA,oBAAoB,OAAA;AAC7B,sEAAyE;AAAhE,4HAAA,sBAAsB,OAAA;AAC/B,0EAA6E;AAApE,gIAAA,wBAAwB,OAAA;AACjC,oDAAqE;AAA5D,+GAAA,gBAAgB,OAAA;AAAE,0GAAA,WAAW,OAAA;AAEtC,sDAA0D;AAAjD,iHAAA,iBAAiB,OAAA;AAE1B,gDAAmD;AAA1C,0GAAA,aAAa,OAAA;AAGtB,6EAA6E;AAC7E,0DAAuD;AAA9C,8GAAA,YAAY,OAAA;AAErB,8DAA2D;AAAlD,kHAAA,cAAc,OAAA;AAIvB,mDAAiD;AAAxC,yGAAA,UAAU,OAAA;AAGnB,yDAAuD;AAA9C,+GAAA,aAAa,OAAA;AACtB,iDAA+C;AAAtC,uGAAA,SAAS,OAAA;AAElB,yDAAuE;AAA9D,gHAAA,cAAc,OAAA;AAAE,+GAAA,aAAa,OAAA;AAEtC,qEAA4E;AAAnE,yHAAA,iBAAiB,OAAA;AAAE,iHAAA,SAAS,OAAA;AAErC,sDAA0D;AAAjD,iHAAA,iBAAiB,OAAA;AAE1B,4CAAqH;AAA5G,2GAAA,gBAAgB,OAAA;AAAE,6GAAA,kBAAkB,OAAA;AAAE,+GAAA,oBAAoB,OAAA;AAAE,gHAAA,qBAAqB,OAAA"}

package/dist/interfaces/api-key-store.interface.d.ts

@@ -0,0 +1,94 @@
+import { ApiKey } from '../models/api-key.model';
+/**
+ * Pluggable persistence interface for API Keys / Service Tokens.
+ *
+ * Implement this interface and pass the instance to `ApiKeyStrategy` and
+ * `ApiKeyService`.  All methods are optional except for `findByPrefix` and
+ * `findById` — only the features your application actually needs have to be
+ * implemented.
+ *
+ * @example
+ * ```ts
+ * import { IApiKeyStore } from '@awesome-lang-auth/node';
+ *
+ * export class MyApiKeyStore implements IApiKeyStore {
+ *   async save(key: ApiKey) {
+ *     await db('api_keys').insert(key);
+ *   }
+ *   async findByPrefix(prefix: string) {
+ *     return db('api_keys').where({ keyPrefix: prefix, isActive: true }).first() ?? null;
+ *   }
+ *   async findById(id: string) {
+ *     return db('api_keys').where({ id }).first() ?? null;
+ *   }
+ *   async revoke(id: string) {
+ *     await db('api_keys').where({ id }).update({ isActive: false });
+ *   }
+ *   async updateLastUsed(id: string) {
+ *     await db('api_keys').where({ id }).update({ lastUsedAt: new Date() });
+ *   }
+ * }
+ * ```
+ */
+export interface IApiKeyStore {
+    /**
+     * Persist a newly created API key record.
+     */
+    save(key: ApiKey): Promise<void>;
+    /**
+     * Look up an active key candidate by its prefix.
+     *
+     * Because bcrypt comparison is expensive, the prefix is used as a fast
+     * lookup index.  The caller will then verify the raw key against the hash.
+     *
+     * Only return records where `isActive = true`.
+     */
+    findByPrefix(prefix: string): Promise<ApiKey | null>;
+    /**
+     * Retrieve a key record by its unique ID.
+     * Used for revocation, rotation, and admin management.
+     */
+    findById(id: string): Promise<ApiKey | null>;
+    /**
+     * Mark a key as inactive (revoke it).
+     * After revocation all subsequent requests using this key must be rejected.
+     */
+    revoke(id: string): Promise<void>;
+    /**
+     * Update the `lastUsedAt` timestamp after a successful authentication.
+     * Also used for audit purposes.
+     */
+    updateLastUsed(id: string, at?: Date): Promise<void>;
+    /**
+     * Return all keys belonging to a given service identity.
+     * Optional — only needed if you expose a key-listing UI.
+     */
+    listByServiceId?(serviceId: string): Promise<ApiKey[]>;
+    /**
+     * Return all key records (paginated).
+     * Optional — only needed for admin management screens.
+     */
+    listAll?(limit: number, offset: number): Promise<ApiKey[]>;
+    /**
+     * Permanently delete a key record.
+     * Optional — prefer `revoke` for audit-trail preservation.
+     */
+    delete?(id: string): Promise<void>;
+    /**
+     * Append a usage audit-log entry for the given key.
+     * Optional — implement when you need per-key access logs.
+     */
+    logUsage?(entry: ApiKeyAuditEntry): Promise<void>;
+}
+/** A single usage audit record for an API key. */
+export interface ApiKeyAuditEntry {
+    keyId: string;
+    timestamp: Date;
+    ip?: string;
+    userAgent?: string;
+    path?: string;
+    method?: string;
+    success: boolean;
+    failureReason?: string;
+}
+//# sourceMappingURL=api-key-store.interface.d.ts.map

package/dist/interfaces/api-key-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/api-key-store.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAErD;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD;;;OAGG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvD;;;OAGG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE3D;;;OAGG;IACH,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/interfaces/api-key-store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api-key-store.interface.js.map

package/dist/interfaces/api-key-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/api-key-store.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/auth-strategy.interface.d.ts

@@ -0,0 +1,6 @@
+import { AuthConfig } from '../models/auth-config.model';
+export interface IAuthStrategy<TInput = unknown, TOutput = unknown> {
+    name: string;
+    authenticate(input: TInput, config: AuthConfig): Promise<TOutput>;
+}
+//# sourceMappingURL=auth-strategy.interface.d.ts.map

package/dist/interfaces/auth-strategy.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/auth-strategy.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,aAAa,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE"}

package/dist/interfaces/auth-strategy.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=auth-strategy.interface.js.map

package/dist/interfaces/auth-strategy.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy.interface.js","sourceRoot":"","sources":["../../src/interfaces/auth-strategy.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/linked-accounts-store.interface.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Represents an OAuth account linked to a user.
+ */
+export interface LinkedAccount {
+    /** Provider name, e.g. `'google'`, `'github'`. */
+    provider: string;
+    /** Unique user identifier returned by the provider. */
+    providerAccountId: string;
+    /** Email address returned by the provider (optional). */
+    email?: string;
+    /** Display name returned by the provider (optional). */
+    name?: string;
+    /** Profile picture URL returned by the provider (optional). */
+    picture?: string;
+    /** When the account was linked (optional). */
+    linkedAt?: Date;
+}
+/**
+ * Store for managing multiple OAuth provider accounts linked to a single user.
+ *
+ * Implement this interface to support flexible account linking, where a single
+ * user can have multiple OAuth providers linked to their account and can
+ * selectively unlink individual providers.
+ *
+ * When provided to `createAuthRouter` via `RouterOptions.linkedAccountsStore`,
+ * the following endpoints become available:
+ * - `GET  /auth/linked-accounts`                              — list linked accounts (authenticated)
+ * - `DELETE /auth/linked-accounts/:provider/:providerAccountId` — unlink an account (authenticated)
+ *
+ * @example
+ * ```typescript
+ * import { ILinkedAccountsStore, LinkedAccount } from '@awesome-lang-auth/node';
+ *
+ * export class MyLinkedAccountsStore implements ILinkedAccountsStore {
+ *   async getLinkedAccounts(userId: string): Promise<LinkedAccount[]> {
+ *     return db('linked_accounts').where({ userId });
+ *   }
+ *   async linkAccount(userId: string, account: LinkedAccount): Promise<void> {
+ *     await db('linked_accounts').insert({ userId, ...account });
+ *   }
+ *   async unlinkAccount(userId: string, provider: string, providerAccountId: string): Promise<void> {
+ *     await db('linked_accounts').where({ userId, provider, providerAccountId }).delete();
+ *   }
+ *   async findUserByProviderAccount(provider: string, providerAccountId: string): Promise<{ userId: string } | null> {
+ *     const row = await db('linked_accounts').where({ provider, providerAccountId }).first();
+ *     return row ? { userId: row.userId } : null;
+ *   }
+ * }
+ * ```
+ */
+export interface ILinkedAccountsStore {
+    /**
+     * Return all OAuth accounts linked to the given user.
+     */
+    getLinkedAccounts(userId: string): Promise<LinkedAccount[]>;
+    /**
+     * Persist a new linked account for the given user.
+     * Implementations should be idempotent: re-linking the same
+     * `(provider, providerAccountId)` pair should not create a duplicate.
+     */
+    linkAccount(userId: string, account: LinkedAccount): Promise<void>;
+    /**
+     * Remove the link between the given user and the specified provider account.
+     */
+    unlinkAccount(userId: string, provider: string, providerAccountId: string): Promise<void>;
+    /**
+     * Look up the user ID that has the given provider account linked.
+     * Returns `null` if no match is found.
+     */
+    findUserByProviderAccount(provider: string, providerAccountId: string): Promise<{
+        userId: string;
+    } | null>;
+}
+//# sourceMappingURL=linked-accounts-store.interface.d.ts.map

package/dist/interfaces/linked-accounts-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-accounts-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/linked-accounts-store.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAE5D;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1F;;;OAGG;IACH,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5G"}

package/dist/interfaces/linked-accounts-store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=linked-accounts-store.interface.js.map

package/dist/interfaces/linked-accounts-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-accounts-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/linked-accounts-store.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/pending-link-store.interface.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Base interface for a pending OAuth account-link document stored in a
+ * database.  Use this as the foundation for Mongoose schemas or other ORM
+ * models so that the exact document shape is known at compile time.
+ *
+ * @example
+ * ```typescript
+ * // Mongoose example
+ * import { IPendingLink } from '@awesome-lang-auth/node';
+ * import { Schema, model, Document } from 'mongoose';
+ *
+ * interface IPendingLinkDoc extends IPendingLink, Document {}
+ *
+ * const pendingLinkSchema = new Schema<IPendingLinkDoc>({
+ *   email:             { type: String, required: true, index: true },
+ *   provider:          { type: String, required: true },
+ *   providerAccountId: { type: String, required: true },
+ *   createdAt:         { type: Date,   default: Date.now },
+ * });
+ * ```
+ */
+export interface IPendingLink {
+    email: string;
+    provider: string;
+    providerAccountId: string;
+    createdAt: Date;
+}
+/**
+ * Store for temporarily persisting OAuth account-link data for unauthenticated
+ * users who encountered an `OAUTH_ACCOUNT_CONFLICT`.
+ *
+ * Implement this interface and pass it as `pendingLinkStore` in `RouterOptions`
+ * to enable native unauthenticated account linking.  When present, the library
+ * will automatically stash the conflicting provider details and include the
+ * `email` and `provider` query parameters in the `/auth/account-conflict`
+ * redirect so the front-end can drive the verification flow without any
+ * custom server-side routes.
+ *
+ * @example
+ * ```typescript
+ * import { IPendingLinkStore } from '@awesome-lang-auth/node';
+ *
+ * export class InMemoryPendingLinkStore implements IPendingLinkStore {
+ *   private store = new Map<string, { providerAccountId: string }>();
+ *
+ *   private key(email: string, provider: string) { return `${email}::${provider}`; }
+ *
+ *   async stash(email: string, provider: string, providerAccountId: string) {
+ *     this.store.set(this.key(email, provider), { providerAccountId });
+ *   }
+ *   async retrieve(email: string, provider: string) {
+ *     return this.store.get(this.key(email, provider)) ?? null;
+ *   }
+ *   async remove(email: string, provider: string) {
+ *     this.store.delete(this.key(email, provider));
+ *   }
+ * }
+ * ```
+ */
+export interface IPendingLinkStore {
+    /**
+     * Persist a pending link so it can be retrieved later during `/link-verify`.
+     */
+    stash(email: string, provider: string, providerAccountId: string): Promise<void>;
+    /**
+     * Retrieve the stashed `providerAccountId` for the given `email`/`provider`
+     * pair, or `null` if no pending link exists.
+     */
+    retrieve(email: string, provider: string): Promise<{
+        providerAccountId: string;
+    } | null>;
+    /**
+     * Remove a stashed entry after it has been consumed or invalidated.
+     */
+    remove(email: string, provider: string): Promise<void>;
+}
+//# sourceMappingURL=pending-link-store.interface.d.ts.map

package/dist/interfaces/pending-link-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-link-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/pending-link-store.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjF;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAEzF;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD"}

package/dist/interfaces/pending-link-store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=pending-link-store.interface.js.map

package/dist/interfaces/pending-link-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-link-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/pending-link-store.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/roles-permissions-store.interface.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Base interface for a role document stored in a database.
+ * Use this as the foundation for Mongoose schemas or other ORM models.
+ *
+ * @example
+ * ```typescript
+ * // Mongoose example
+ * import { IRoleDocument } from '@awesome-lang-auth/node';
+ * import { Schema, model, Document } from 'mongoose';
+ *
+ * interface IRoleDoc extends IRoleDocument, Document {}
+ *
+ * const roleSchema = new Schema<IRoleDoc>({
+ *   name:        { type: String, required: true, unique: true },
+ *   permissions: [{ type: String }],
+ * });
+ * ```
+ */
+export interface IRoleDocument {
+    name: string;
+    permissions: string[];
+}
+/**
+ * Base interface for a user-role assignment document stored in a database.
+ * Supports both single-tenant and multi-tenant role assignments via the
+ * optional `tenantId` field.
+ *
+ * @example
+ * ```typescript
+ * // Mongoose example
+ * import { IRoleUserDocument } from '@awesome-lang-auth/node';
+ * import { Schema, model, Document } from 'mongoose';
+ *
+ * interface IRoleUserDoc extends IRoleUserDocument, Document {}
+ *
+ * const roleUserSchema = new Schema<IRoleUserDoc>({
+ *   userId:   { type: String, required: true, index: true },
+ *   role:     { type: String, required: true, index: true },
+ *   tenantId: { type: String, index: true },
+ * });
+ * ```
+ */
+export interface IRoleUserDocument {
+    userId: string;
+    role: string;
+    tenantId?: string;
+}
+/**
+ * Optional store for role-based access control (RBAC).
+ *
+ * Implement this interface to assign roles to users, attach fine-grained
+ * permissions to roles, and perform permission checks.  All tenant-aware
+ * methods accept an optional `tenantId` parameter so the same interface
+ * works for both single-tenant and multi-tenant applications.
+ *
+ * @example
+ * ```typescript
+ * import { IRolesPermissionsStore } from '@awesome-lang-auth/node';
+ *
+ * export class MyRbacStore implements IRolesPermissionsStore {
+ *   async addRoleToUser(userId, role, tenantId?) { ... }
+ *   async removeRoleFromUser(userId, role, tenantId?) { ... }
+ *   async getRolesForUser(userId, tenantId?) { ... }
+ *   async createRole(role, permissions?) { ... }
+ *   async deleteRole(role) { ... }
+ *   async addPermissionToRole(role, permission) { ... }
+ *   async removePermissionFromRole(role, permission) { ... }
+ *   async getPermissionsForRole(role) { ... }
+ *   async getPermissionsForUser(userId, tenantId?) { ... }
+ *   async userHasPermission(userId, permission, tenantId?) { ... }
+ * }
+ * ```
+ */
+export interface IRolesPermissionsStore {
+    /**
+     * Assign `role` to the given user.
+     * When `tenantId` is provided the assignment is scoped to that tenant.
+     */
+    addRoleToUser(userId: string, role: string, tenantId?: string): Promise<void>;
+    /**
+     * Remove `role` from the given user.
+     * When `tenantId` is provided only the tenant-scoped assignment is removed.
+     */
+    removeRoleFromUser(userId: string, role: string, tenantId?: string): Promise<void>;
+    /**
+     * Return the list of roles assigned to the given user.
+     * When `tenantId` is provided only roles scoped to that tenant are returned.
+     */
+    getRolesForUser(userId: string, tenantId?: string): Promise<string[]>;
+    /**
+     * Create a new role, optionally pre-loading it with a set of permissions.
+     * Idempotent — calling it on an existing role should not throw.
+     */
+    createRole(role: string, permissions?: string[]): Promise<void>;
+    /**
+     * Delete a role and all its permission assignments.
+     * User ↔ role assignments for this role should also be removed.
+     */
+    deleteRole(role: string): Promise<void>;
+    /**
+     * Add `permission` to `role`.
+     * Idempotent — adding an already-assigned permission should not throw.
+     */
+    addPermissionToRole(role: string, permission: string): Promise<void>;
+    /**
+     * Remove `permission` from `role`.
+     */
+    removePermissionFromRole(role: string, permission: string): Promise<void>;
+    /**
+     * Return all permissions assigned to `role`.
+     */
+    getPermissionsForRole(role: string): Promise<string[]>;
+    /**
+     * Return all permissions the user has, aggregated across all their roles.
+     * When `tenantId` is provided only roles scoped to that tenant are considered.
+     */
+    getPermissionsForUser(userId: string, tenantId?: string): Promise<string[]>;
+    /**
+     * Check whether the user has a specific permission (across any of their roles).
+     * When `tenantId` is provided only roles scoped to that tenant are checked.
+     */
+    userHasPermission(userId: string, permission: string, tenantId?: string): Promise<boolean>;
+    /**
+     * Return all role names defined in the store.
+     * Used by the optional admin router to display the roles & permissions table.
+     */
+    getAllRoles?(): Promise<string[]>;
+}
+//# sourceMappingURL=roles-permissions-store.interface.d.ts.map

package/dist/interfaces/roles-permissions-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-permissions-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/roles-permissions-store.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,sBAAsB;IAKrC;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAMtE;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMxC;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;OAEG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAMvD;;;OAGG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5E;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3F;;;OAGG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnC"}

package/dist/interfaces/roles-permissions-store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=roles-permissions-store.interface.js.map

package/dist/interfaces/roles-permissions-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-permissions-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/roles-permissions-store.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/session-store.interface.d.ts

@@ -0,0 +1,92 @@
+import { SessionInfo } from '../models/session.model';
+/**
+ * Optional store for device-aware session management.
+ *
+ * Implement this interface when you need to give users visibility into
+ * (and control over) their active sessions — similar to "Manage devices"
+ * screens in modern applications.
+ *
+ * Each session is identified by an opaque `sessionHandle` (e.g. a UUID or a
+ * hex token) that is independent of the JWT.  This lets you list, inspect,
+ * and revoke individual sessions without invalidating all tokens at once.
+ *
+ * @example
+ * ```typescript
+ * import { ISessionStore } from '@awesome-lang-auth/node';
+ *
+ * export class MySessionStore implements ISessionStore {
+ *   async createSession(info) {
+ *     const handle = crypto.randomUUID();
+ *     await db('sessions').insert({ handle, ...info });
+ *     return { sessionHandle: handle, ...info };
+ *   }
+ *   async getSession(handle) {
+ *     return db('sessions').where({ handle }).first() ?? null;
+ *   }
+ *   async getSessionsForUser(userId) {
+ *     return db('sessions').where({ userId });
+ *   }
+ *   async updateSessionLastActive(handle) {
+ *     await db('sessions').where({ handle }).update({ lastActiveAt: new Date() });
+ *   }
+ *   async revokeSession(handle) {
+ *     await db('sessions').where({ handle }).delete();
+ *   }
+ *   async revokeAllSessionsForUser(userId) {
+ *     await db('sessions').where({ userId }).delete();
+ *   }
+ * }
+ * ```
+ */
+export interface ISessionStore {
+    /**
+     * Persist a new session and return it with the generated `sessionHandle`.
+     */
+    createSession(info: Omit<SessionInfo, 'sessionHandle'>): Promise<SessionInfo>;
+    /**
+     * Retrieve a session by its handle.
+     * Returns `null` when the session does not exist or has expired.
+     */
+    getSession(sessionHandle: string): Promise<SessionInfo | null>;
+    /**
+     * Return all active sessions for the given user.
+     * When `tenantId` is provided only sessions belonging to that tenant are
+     * returned.
+     */
+    getSessionsForUser(userId: string, tenantId?: string): Promise<SessionInfo[]>;
+    /**
+     * Bump the `lastActiveAt` timestamp for the given session.
+     * Call this on every authenticated request to keep session activity up to date.
+     */
+    updateSessionLastActive(sessionHandle: string): Promise<void>;
+    /**
+     * Invalidate (delete) a single session.
+     *
+     * If `AuthConfig.session.checkOn` is set to `'allcalls'`, access is revoked
+     * immediately. If set to `'refresh'`, access is revoked at the next token
+     * rotation.
+     */
+    revokeSession(sessionHandle: string): Promise<void>;
+    /**
+     * Invalidate all sessions for the given user (e.g. "log out everywhere").
+     * When `tenantId` is provided only sessions for that tenant are revoked.
+     */
+    revokeAllSessionsForUser(userId: string, tenantId?: string): Promise<void>;
+    /**
+     * Return all active sessions across all users.
+     * Used by the optional admin router to display the sessions table.
+     *
+     * @param limit  Maximum number of records to return.
+     * @param offset Zero-based offset for pagination.
+     */
+    getAllSessions?(limit: number, offset: number): Promise<SessionInfo[]>;
+    /**
+     * Delete all sessions whose `expiresAt` timestamp is in the past.
+     * Intended to be called periodically (e.g. from a cron job) via the
+     * `POST /auth/sessions/cleanup` endpoint.
+     *
+     * @returns The number of sessions that were deleted.
+     */
+    deleteExpiredSessions?(): Promise<number>;
+}
+//# sourceMappingURL=session-store.interface.d.ts.map

package/dist/interfaces/session-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/session-store.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,aAAa,CACX,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,GACvC,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE/D;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9E;;;OAGG;IACH,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;OAMG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;OAGG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C"}