@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * @techelusive/nest-auth: reusable authentication for NestJS apps.
+ * Everything an app needs is exported from here.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = exports.ConsoleEmailSender = exports.Msg91SmsSender = exports.SOCIAL_PROVIDER = exports.SIGN_IN_STATUS = exports.SIGN_IN_METHOD = exports.ROUTES = exports.PENDING_VERIFICATION = exports.ORGANIZATION_ROLES = exports.ORGANIZATION_ROLE = exports.AUTH_EVENTS = exports.AUTH_ERRORS = exports.ACCOUNT_STATUSES = exports.ACCOUNT_STATUS = exports.AuthError = exports.DEFAULT_SETTINGS = exports.WebhooksService = exports.SigningKeysService = exports.TwoFactorService = exports.OrganizationsService = exports.ApiKeysService = exports.AuthEventsService = exports.SettingsService = exports.SignInService = exports.SessionService = exports.DataRetentionService = exports.UsersService = exports.EmailChangeAndRetention1792700000000 = exports.CreateAuthTables1792600000000 = exports.AUTH_MIGRATIONS = exports.SYSTEM_REQUEST = exports.CurrentRequest = exports.Roles = exports.Public = exports.CurrentUserId = exports.CurrentUser = exports.CurrentCaller = exports.CheckSession = exports.ApiKeyScopes = exports.AdminOnly = exports.AuthGuard = exports.AuthModule = void 0;
+// The module and its options
+var auth_module_1 = require("./auth.module");
+Object.defineProperty(exports, "AuthModule", { enumerable: true, get: function () { return auth_module_1.AuthModule; } });
+// Protecting routes
+var auth_guard_1 = require("./guards/auth.guard");
+Object.defineProperty(exports, "AuthGuard", { enumerable: true, get: function () { return auth_guard_1.AuthGuard; } });
+var auth_decorators_1 = require("./guards/auth.decorators");
+Object.defineProperty(exports, "AdminOnly", { enumerable: true, get: function () { return auth_decorators_1.AdminOnly; } });
+Object.defineProperty(exports, "ApiKeyScopes", { enumerable: true, get: function () { return auth_decorators_1.ApiKeyScopes; } });
+Object.defineProperty(exports, "CheckSession", { enumerable: true, get: function () { return auth_decorators_1.CheckSession; } });
+Object.defineProperty(exports, "CurrentCaller", { enumerable: true, get: function () { return auth_decorators_1.CurrentCaller; } });
+Object.defineProperty(exports, "CurrentUser", { enumerable: true, get: function () { return auth_decorators_1.CurrentUser; } });
+Object.defineProperty(exports, "CurrentUserId", { enumerable: true, get: function () { return auth_decorators_1.CurrentUserId; } });
+Object.defineProperty(exports, "Public", { enumerable: true, get: function () { return auth_decorators_1.Public; } });
+Object.defineProperty(exports, "Roles", { enumerable: true, get: function () { return auth_decorators_1.Roles; } });
+var request_context_1 = require("./common/request-context");
+Object.defineProperty(exports, "CurrentRequest", { enumerable: true, get: function () { return request_context_1.CurrentRequest; } });
+Object.defineProperty(exports, "SYSTEM_REQUEST", { enumerable: true, get: function () { return request_context_1.SYSTEM_REQUEST; } });
+// Database: add AUTH_ENTITIES to your DataSource and AUTH_MIGRATIONS to its migrations
+__exportStar(require("./database/entities"), exports);
+var create_auth_tables_migration_1 = require("./database/create-auth-tables.migration");
+Object.defineProperty(exports, "AUTH_MIGRATIONS", { enumerable: true, get: function () { return create_auth_tables_migration_1.AUTH_MIGRATIONS; } });
+Object.defineProperty(exports, "CreateAuthTables1792600000000", { enumerable: true, get: function () { return create_auth_tables_migration_1.CreateAuthTables1792600000000; } });
+var email_change_and_retention_migration_1 = require("./database/email-change-and-retention.migration");
+Object.defineProperty(exports, "EmailChangeAndRetention1792700000000", { enumerable: true, get: function () { return email_change_and_retention_migration_1.EmailChangeAndRetention1792700000000; } });
+// Services your app can use
+var users_service_1 = require("./features/users/users.service");
+Object.defineProperty(exports, "UsersService", { enumerable: true, get: function () { return users_service_1.UsersService; } });
+var data_retention_service_1 = require("./features/maintenance/data-retention.service");
+Object.defineProperty(exports, "DataRetentionService", { enumerable: true, get: function () { return data_retention_service_1.DataRetentionService; } });
+var session_service_1 = require("./features/sessions/session.service");
+Object.defineProperty(exports, "SessionService", { enumerable: true, get: function () { return session_service_1.SessionService; } });
+var sign_in_service_1 = require("./features/sign-in/sign-in.service");
+Object.defineProperty(exports, "SignInService", { enumerable: true, get: function () { return sign_in_service_1.SignInService; } });
+var settings_service_1 = require("./features/settings/settings.service");
+Object.defineProperty(exports, "SettingsService", { enumerable: true, get: function () { return settings_service_1.SettingsService; } });
+var auth_events_service_1 = require("./features/events/auth-events.service");
+Object.defineProperty(exports, "AuthEventsService", { enumerable: true, get: function () { return auth_events_service_1.AuthEventsService; } });
+var api_keys_service_1 = require("./features/api-keys/api-keys.service");
+Object.defineProperty(exports, "ApiKeysService", { enumerable: true, get: function () { return api_keys_service_1.ApiKeysService; } });
+var organizations_service_1 = require("./features/organizations/organizations.service");
+Object.defineProperty(exports, "OrganizationsService", { enumerable: true, get: function () { return organizations_service_1.OrganizationsService; } });
+var two_factor_service_1 = require("./features/two-factor/two-factor.service");
+Object.defineProperty(exports, "TwoFactorService", { enumerable: true, get: function () { return two_factor_service_1.TwoFactorService; } });
+var signing_keys_service_1 = require("./features/signing-keys/signing-keys.service");
+Object.defineProperty(exports, "SigningKeysService", { enumerable: true, get: function () { return signing_keys_service_1.SigningKeysService; } });
+var webhooks_service_1 = require("./features/webhooks/webhooks.service");
+Object.defineProperty(exports, "WebhooksService", { enumerable: true, get: function () { return webhooks_service_1.WebhooksService; } });
+var settings_defaults_1 = require("./features/settings/settings.defaults");
+Object.defineProperty(exports, "DEFAULT_SETTINGS", { enumerable: true, get: function () { return settings_defaults_1.DEFAULT_SETTINGS; } });
+// Errors and constants (stable error codes apps can check)
+var auth_error_1 = require("./common/auth-error");
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return auth_error_1.AuthError; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "ACCOUNT_STATUS", { enumerable: true, get: function () { return constants_1.ACCOUNT_STATUS; } });
+Object.defineProperty(exports, "ACCOUNT_STATUSES", { enumerable: true, get: function () { return constants_1.ACCOUNT_STATUSES; } });
+Object.defineProperty(exports, "AUTH_ERRORS", { enumerable: true, get: function () { return constants_1.AUTH_ERRORS; } });
+Object.defineProperty(exports, "AUTH_EVENTS", { enumerable: true, get: function () { return constants_1.AUTH_EVENTS; } });
+Object.defineProperty(exports, "ORGANIZATION_ROLE", { enumerable: true, get: function () { return constants_1.ORGANIZATION_ROLE; } });
+Object.defineProperty(exports, "ORGANIZATION_ROLES", { enumerable: true, get: function () { return constants_1.ORGANIZATION_ROLES; } });
+Object.defineProperty(exports, "PENDING_VERIFICATION", { enumerable: true, get: function () { return constants_1.PENDING_VERIFICATION; } });
+Object.defineProperty(exports, "ROUTES", { enumerable: true, get: function () { return constants_1.ROUTES; } });
+Object.defineProperty(exports, "SIGN_IN_METHOD", { enumerable: true, get: function () { return constants_1.SIGN_IN_METHOD; } });
+Object.defineProperty(exports, "SIGN_IN_STATUS", { enumerable: true, get: function () { return constants_1.SIGN_IN_STATUS; } });
+Object.defineProperty(exports, "SOCIAL_PROVIDER", { enumerable: true, get: function () { return constants_1.SOCIAL_PROVIDER; } });
+// Ready-made senders
+var msg91_sms_sender_1 = require("./integrations/msg91-sms-sender");
+Object.defineProperty(exports, "Msg91SmsSender", { enumerable: true, get: function () { return msg91_sms_sender_1.Msg91SmsSender; } });
+var console_email_sender_1 = require("./integrations/console-email-sender");
+Object.defineProperty(exports, "ConsoleEmailSender", { enumerable: true, get: function () { return console_email_sender_1.ConsoleEmailSender; } });
+// For services that RECEIVE webhooks
+var webhook_signature_1 = require("./features/webhooks/webhook-signature");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_signature_1.verifyWebhookSignature; } });
+//# 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;;;GAGG;;;;;;;;;;;;;;;;;AAEH,6BAA6B;AAC7B,6CAA2C;AAAlC,yGAAA,UAAU,OAAA;AAYnB,oBAAoB;AACpB,kDAAgD;AAAvC,uGAAA,SAAS,OAAA;AAClB,4DASkC;AARhC,4GAAA,SAAS,OAAA;AACT,+GAAA,YAAY,OAAA;AACZ,+GAAA,YAAY,OAAA;AACZ,gHAAA,aAAa,OAAA;AACb,8GAAA,WAAW,OAAA;AACX,gHAAA,aAAa,OAAA;AACb,yGAAA,MAAM,OAAA;AACN,wGAAA,KAAK,OAAA;AAGP,4DAA0E;AAAjE,iHAAA,cAAc,OAAA;AAAE,iHAAA,cAAc,OAAA;AAGvC,uFAAuF;AACvF,sDAAoC;AACpC,wFAAyG;AAAhG,+HAAA,eAAe,OAAA;AAAE,6IAAA,6BAA6B,OAAA;AACvD,wGAAuG;AAA9F,4JAAA,oCAAoC,OAAA;AAE7C,4BAA4B;AAC5B,gEAA8D;AAArD,6GAAA,YAAY,OAAA;AACrB,wFAAqF;AAA5E,8HAAA,oBAAoB,OAAA;AAE7B,uEAAqE;AAA5D,iHAAA,cAAc,OAAA;AACvB,sEAAmE;AAA1D,gHAAA,aAAa,OAAA;AACtB,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AACxB,6EAA0E;AAAjE,wHAAA,iBAAiB,OAAA;AAC1B,yEAAsE;AAA7D,kHAAA,cAAc,OAAA;AACvB,wFAAsF;AAA7E,6HAAA,oBAAoB,OAAA;AAC7B,+EAA4E;AAAnE,sHAAA,gBAAgB,OAAA;AACzB,qFAAkF;AAAzE,0HAAA,kBAAkB,OAAA;AAC3B,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AAOxB,2EAAyE;AAAhE,qHAAA,gBAAgB,OAAA;AAEzB,2DAA2D;AAC3D,kDAAgD;AAAvC,uGAAA,SAAS,OAAA;AAClB,yCAYqB;AAXnB,2GAAA,cAAc,OAAA;AACd,6GAAA,gBAAgB,OAAA;AAChB,wGAAA,WAAW,OAAA;AACX,wGAAA,WAAW,OAAA;AACX,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,iHAAA,oBAAoB,OAAA;AACpB,mGAAA,MAAM,OAAA;AACN,2GAAA,cAAc,OAAA;AACd,2GAAA,cAAc,OAAA;AACd,4GAAA,eAAe,OAAA;AAIjB,qBAAqB;AACrB,oEAAiE;AAAxD,kHAAA,cAAc,OAAA;AAEvB,4EAAyE;AAAhE,0HAAA,kBAAkB,OAAA;AAE3B,qCAAqC;AACrC,2EAA+E;AAAtE,2HAAA,sBAAsB,OAAA"}

package/dist/integrations/console-email-sender.d.ts

@@ -0,0 +1,15 @@
+import { AuthEmail, EmailSender } from '../auth-options.js';
+/**
+ * Development only: prints emails to the console instead of sending them, so you can copy
+ * codes and links while building your app. Use a real sender (SES, Resend, SMTP...) in production.
+ */
+export declare class ConsoleEmailSender implements EmailSender {
+    private readonly logger;
+    /**
+     * Prints the email to the console.
+     *
+     * @param email - The email the library wants to send.
+     * @throws When NODE_ENV is "production", so it can't be shipped by accident.
+     */
+    send(email: AuthEmail): Promise<void>;
+}

package/dist/integrations/console-email-sender.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleEmailSender = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../constants.js");
+/**
+ * Development only: prints emails to the console instead of sending them, so you can copy
+ * codes and links while building your app. Use a real sender (SES, Resend, SMTP...) in production.
+ */
+class ConsoleEmailSender {
+    logger = new common_1.Logger(constants_1.LOG_CONTEXT.consoleEmailSender);
+    /**
+     * Prints the email to the console.
+     *
+     * @param email - The email the library wants to send.
+     * @throws When NODE_ENV is "production", so it can't be shipped by accident.
+     */
+    async send(email) {
+        if (process.env.NODE_ENV === constants_1.PRODUCTION_ENVIRONMENT) {
+            throw new Error('ConsoleEmailSender must not be used in production');
+        }
+        this.logger.log(`[${email.type}] to ${email.to}: ${JSON.stringify(email)}`);
+    }
+}
+exports.ConsoleEmailSender = ConsoleEmailSender;
+//# sourceMappingURL=console-email-sender.js.map

package/dist/integrations/console-email-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-email-sender.js","sourceRoot":"","sources":["../../src/integrations/console-email-sender.ts"],"names":[],"mappings":";;;AAAA,2CAAwC;AAExC,2CAAkE;AAElE;;;GAGG;AACH,MAAa,kBAAkB;IACZ,MAAM,GAAG,IAAI,eAAM,CAAC,uBAAW,CAAC,kBAAkB,CAAC,CAAC;IAErE;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,KAAgB;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,kCAAsB,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,QAAQ,KAAK,CAAC,EAAE,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF;AAfD,gDAeC"}

package/dist/integrations/msg91-sms-sender.d.ts

@@ -0,0 +1,28 @@
+import { SmsSender } from '../auth-options.js';
+export interface Msg91Options {
+    /** Your MSG91 auth key (Dashboard -> API -> Configure). Keep it in an environment variable. */
+    authKey: string;
+    /** The DLT-approved SMS template id from MSG91 (Flow / template id). */
+    templateId: string;
+    /** The variable your template uses for the code, e.g. "otp" for "Your code is ##otp##". Default "otp". */
+    codeVariableName?: string;
+}
+/**
+ * Ready-made SMS sender for MSG91 (cheapest for Indian numbers). Plug it in with:
+ *
+ *   smsSender: new Msg91SmsSender({ authKey: process.env.MSG91_AUTH_KEY!, templateId: '...' })
+ *
+ * For any other provider (Twilio, AWS SNS...), write a class with the same `sendCode` method.
+ */
+export declare class Msg91SmsSender implements SmsSender {
+    private readonly msg91;
+    constructor(msg91: Msg91Options);
+    /**
+     * Sends a one-time code through MSG91's Flow API.
+     *
+     * @param phoneNumber - The E.164 phone number, e.g. "+919876543210".
+     * @param code - The code to send.
+     * @throws When MSG91 refuses the request or doesn't answer in time.
+     */
+    sendCode(phoneNumber: string, code: string): Promise<void>;
+}

package/dist/integrations/msg91-sms-sender.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Msg91SmsSender = void 0;
+const constants_1 = require("../constants.js");
+/**
+ * Ready-made SMS sender for MSG91 (cheapest for Indian numbers). Plug it in with:
+ *
+ *   smsSender: new Msg91SmsSender({ authKey: process.env.MSG91_AUTH_KEY!, templateId: '...' })
+ *
+ * For any other provider (Twilio, AWS SNS...), write a class with the same `sendCode` method.
+ */
+class Msg91SmsSender {
+    msg91;
+    constructor(msg91) {
+        this.msg91 = msg91;
+    }
+    /**
+     * Sends a one-time code through MSG91's Flow API.
+     *
+     * @param phoneNumber - The E.164 phone number, e.g. "+919876543210".
+     * @param code - The code to send.
+     * @throws When MSG91 refuses the request or doesn't answer in time.
+     */
+    async sendCode(phoneNumber, code) {
+        const response = await fetch(constants_1.MSG91_FLOW_API_URL, {
+            method: constants_1.HTTP_METHOD.post,
+            signal: AbortSignal.timeout(constants_1.MSG91_REQUEST_TIMEOUT_MS),
+            headers: {
+                [constants_1.MSG91_API.authKeyHeader]: this.msg91.authKey,
+                [constants_1.HTTP_HEADER.contentType]: constants_1.JSON_CONTENT_TYPE,
+                [constants_1.HTTP_HEADER.accept]: constants_1.JSON_CONTENT_TYPE,
+            },
+            body: JSON.stringify({
+                template_id: this.msg91.templateId,
+                // MSG91 wants the number with country code but without "+", e.g. 919876543210.
+                recipients: [{ mobiles: phoneNumber.replace(constants_1.LEADING_PLUS_PATTERN, ''), [this.msg91.codeVariableName ?? constants_1.MSG91_API.defaultCodeVariableName]: code }],
+            }),
+        });
+        const result = (await response.json().catch(() => ({})));
+        if (!response.ok || result.type === constants_1.MSG91_API.errorResponseType) {
+            throw new Error(`MSG91 refused the SMS: ${result.message ?? `HTTP ${response.status}`}`);
+        }
+    }
+}
+exports.Msg91SmsSender = Msg91SmsSender;
+//# sourceMappingURL=msg91-sms-sender.js.map

package/dist/integrations/msg91-sms-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msg91-sms-sender.js","sourceRoot":"","sources":["../../src/integrations/msg91-sms-sender.ts"],"names":[],"mappings":";;;AACA,2CAQqB;AAWrB;;;;;;GAMG;AACH,MAAa,cAAc;IACI;IAA7B,YAA6B,KAAmB;QAAnB,UAAK,GAAL,KAAK,CAAc;IAAG,CAAC;IAEpD;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,WAAmB,EAAE,IAAY;QAC9C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,8BAAkB,EAAE;YAC/C,MAAM,EAAE,uBAAW,CAAC,IAAI;YACxB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,oCAAwB,CAAC;YACrD,OAAO,EAAE;gBACP,CAAC,qBAAS,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO;gBAC7C,CAAC,uBAAW,CAAC,WAAW,CAAC,EAAE,6BAAiB;gBAC5C,CAAC,uBAAW,CAAC,MAAM,CAAC,EAAE,6BAAiB;aACxC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU;gBAClC,+EAA+E;gBAC/E,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,gCAAoB,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,qBAAS,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,CAAC;aACnJ,CAAC;SACH,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAwC,CAAC;QAChG,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,KAAK,qBAAS,CAAC,iBAAiB,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,OAAO,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;CACF;AA9BD,wCA8BC"}

package/docs/README.md

@@ -0,0 +1,39 @@
+# Documentation
+
+@techelusive/nest-auth is a NestJS module that gives any backend a complete, secure authentication system: sign-up, sign-in (eight methods), two-factor, sessions, roles, organizations, API keys, webhooks and an admin API. It stores everything in **your app's own PostgreSQL database**, and your apps build their own UI on top of its JSON API.
+
+## Start here
+
+| If you want to... | Read |
+|---|---|
+| Add auth to a NestJS app in 15 minutes | [Getting started](getting-started.md) |
+| See every option and setting | [Configuration](configuration.md) |
+| Build the sign-up / sign-in screens | [Sign-in flows](sign-in-flows.md) and [Client integration](client-integration.md) |
+| See every endpoint's exact request and response JSON | [Endpoints](endpoints/README.md) |
+| Look up an endpoint at a glance | [API reference](api-reference.md) |
+| Handle an error code | [Error codes](error-codes.md) |
+| Protect your own routes | [Protecting routes](protecting-routes.md) |
+| Add teams / workspaces | [Organizations](organizations.md) |
+| Manage users, API keys and webhooks | [Admin, API keys and webhooks](admin-api-keys-webhooks.md) |
+| React to sign-ups and other events | [Events](events.md) |
+| Test every flow by hand (Postman, Swagger, dashboard) | [Manual testing](manual-testing.md) |
+| Learn how the code works, flow by flow (for contributors) | [Code walkthrough](code-walkthrough.md) |
+| Go live | [Production checklist](production-checklist.md) |
+| Understand the security design | [Security](security.md) |
+| Understand the internals or contribute | [Architecture](architecture.md) |
+
+## Concepts in one minute
+
+- **User.** One row per person. Has an email and/or phone number, roles (e.g. `user`, `admin`) and a status (`PENDING_VERIFICATION`, `ACTIVE`, `SUSPENDED`, `DEACTIVATED`, `DELETED`).
+- **Session.** One per signed-in device. Signing out ends the session.
+- **Access token.** A short-lived signed JWT (15 minutes by default) sent as `Authorization: Bearer ...` on every request. Any service can verify it with the public keys at `/.well-known/jwks.json`.
+- **Refresh token.** A long-lived single-use token (`rt_...`). It gets a new access token when the old one expires. Reusing an old one ends the session, because reuse means it was stolen.
+- **Settings.** Which features are on and how they behave. Defaults ship with the library, your code overrides them, and an admin can override both at runtime without a deploy.
+- **Events.** Every important action (sign-up, password change...) is written to the audit log. It is also passed to your `onEvent` handler and sent to any webhooks.
+
+## Requirements
+
+- Node.js 22+
+- NestJS 11 with the Express platform
+- TypeORM 0.3 and PostgreSQL 13+
+- Optional: Redis (recommended with more than one server), AWS KMS (recommended in production)

package/docs/admin-api-keys-webhooks.md

@@ -0,0 +1,147 @@
+# Admin, API keys and webhooks
+
+Everything under `/auth/admin` needs a user holding one of `settings.admin.adminRoles` (default `["admin"]`). The session is checked live, so a removed admin loses access at once.
+
+## The first admin
+
+No one is an admin after installation. Make the first one from a one-off script or a database console:
+
+```ts
+// scripts/make-admin.ts
+const users = app.get(UsersService);
+const user = await users.findUserByEmail('founder@myapp.com');
+await users.setRoles(user!.id, [...user!.roles, 'admin'], user!.id, SYSTEM_REQUEST);
+```
+
+```sql
+-- or directly in SQL
+UPDATE auth_users SET roles = array_append(roles, 'admin') WHERE email = 'founder@myapp.com';
+```
+
+The role appears in the user's next access token, so sign in again or wait for a refresh. From then on, admins manage roles through `PUT /auth/admin/users/:id/roles`.
+
+## Managing users
+
+| Task | Request |
+|---|---|
+| Find users | `GET /auth/admin/users?search=asha&status=ACTIVE&role=seller&page=1&pageSize=50` (search matches email, phone and names; deleted users are hidden unless `status=DELETED`) |
+| See one user | `GET /auth/admin/users/:id` returns profile, suspension reason, consent times, sign-in methods and active devices |
+| Change roles | `PUT /auth/admin/users/:id/roles { "roles": ["user", "seller"] }` (replaces the list) |
+| Suspend | `POST /auth/admin/users/:id/suspend { "reason": "Chargeback fraud, ticket 4411" }` signs them out everywhere |
+| Lift suspension | `POST /auth/admin/users/:id/unsuspend` |
+| Verify email by hand | `POST /auth/admin/users/:id/verify-email` |
+| Reset 2FA | `POST /auth/admin/users/:id/reset-2fa`, only after confirming identity through support |
+| Sign out everywhere | `POST /auth/admin/users/:id/logout-all` |
+| Delete | `DELETE /auth/admin/users/:id` wipes personal data, permanently |
+
+Every admin action is written to the audit log with `performedBy: "admin:<adminUserId>"`.
+
+## Audit log
+
+```http
+GET /auth/admin/audit-log?userId=5f0c...&eventName=user.sign_in_failed&page=1
+```
+
+Entries: `eventName`, `userId`, `performedBy`, `ipAddress`, `userAgent`, `details`, `createdAt`. The log never contains passwords, tokens or codes. It records sign-ins, failures (with a reason), password changes, 2FA changes, admin actions, settings changes and refresh-token reuse. See [Events](events.md) for the list.
+
+The table grows forever. Prune it on a schedule that matches your retention policy, for example:
+
+```sql
+DELETE FROM auth_audit_logs WHERE created_at < now() - interval '1 year';
+```
+
+## Runtime settings
+
+```http
+GET    /auth/admin/settings                                     → settings in force
+PATCH  /auth/admin/settings  { "emailOtp": { "enabled": true } } → change some
+DELETE /auth/admin/settings                                     → back to the code settings
+```
+
+See [Configuration](configuration.md#settings) for every setting and its limits.
+
+## Signing keys
+
+Access tokens are signed with an ES256 key that the library creates on first start, encrypts and stores. To rotate (every few months, or immediately if you suspect a leak):
+
+```http
+POST /auth/admin/signing-keys/rotate
+```
+
+New tokens use the new key right away. The old public key stays in `/.well-known/jwks.json` for 2 days, so tokens it signed keep working until they expire. Every server picks up the change within a minute.
+
+## API keys
+
+API keys let other servers call routes marked `@ApiKeyScopes(...)`.
+
+```http
+POST /auth/admin/api-keys
+{ "name": "Partner: QuickBooks sync", "scopes": ["orders:read", "invoices:write"], "expiresAt": "2027-06-30T00:00:00Z" }
+→ { "apiKey": "ak_3Fx9...", "details": { "id": "...", "keyPreview": "ak_3Fx9Lm", ... } }
+```
+
+- **Shown once:** `apiKey` appears only in this response. Store it in the calling server's secret manager. Only its hash is kept.
+- **Scopes:** lowercase, like `orders:read`, `invoices:write` or `admin`. Define your own vocabulary.
+- **`organizationId`** (optional) ties the key to one organization.
+- **Listing and revoking:** `GET /auth/admin/api-keys` lists keys (never the secret). `DELETE /auth/admin/api-keys/:id` revokes immediately.
+- **Usage:** `lastUsedAt` shows recent use (updated at most once a minute).
+
+## Webhooks
+
+Webhooks send auth [events](events.md) to other systems as HTTP POSTs: your CRM, analytics, a Slack bot, a separate service.
+
+### Register
+
+```http
+POST /auth/admin/webhooks
+{ "url": "https://hooks.myapp.com/auth", "eventNames": ["user.created", "user.deleted"], "description": "CRM sync" }
+→ { "webhook": { "id": "..." }, "signingSecret": "whsec_..." }
+```
+
+- **`eventNames`:** an empty list means every event.
+- **`signingSecret`:** shown once. `POST .../rotate-secret` issues a new one, and the old one stops working immediately.
+- **URL rules:** the URL must be **public https**. Addresses on private networks, loopback, link-local (including cloud metadata `169.254.169.254`) and similar are refused, both when saving and before every delivery. In development, `http://localhost` is allowed.
+
+### Delivery
+
+```http
+POST https://hooks.myapp.com/auth
+Content-Type: application/json
+X-Techelusive-Event: user.created
+X-Techelusive-Delivery: 7d0b...
+X-Techelusive-Signature: t=1792600000,v1=5257a869e7ec...
+
+{ "id": "7d0b...", "name": "user.created", "userId": "5f0c...", "data": { "status": "ACTIVE" }, "occurredAt": "2026-10-20T05:00:00.000Z" }
+```
+
+- **Success:** reply with any 2xx status within 10 seconds. Redirects are not followed.
+- **Retries:** other answers and timeouts are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. After that the delivery is marked `failed`.
+- **Duplicates:** deliveries can arrive more than once (e.g. after a timeout), so use the `id` / `X-Techelusive-Delivery` value to ignore duplicates.
+- **Order:** not guaranteed. Use `occurredAt` if order matters.
+
+### Verifying the signature (receiving side)
+
+```ts
+import express from 'express';
+import { verifyWebhookSignature } from '@techelusive/nest-auth';
+
+app.post('/auth', express.raw({ type: 'application/json' }), (req, res) => {
+  const rawBody = req.body.toString('utf8');               // the exact bytes received
+  const isGenuine = verifyWebhookSignature(process.env.WEBHOOK_SECRET!, rawBody, req.header('X-Techelusive-Signature'));
+  if (!isGenuine) return res.status(400).end();
+  const event = JSON.parse(rawBody);
+  // ... handle event ...
+  res.status(204).end();
+});
+```
+
+The check rejects bodies that were changed, the wrong secret, and deliveries older than 5 minutes (replays). In another language, compute `HMAC-SHA256(secret, "<t>.<rawBody>")` in hex, compare it with `v1` in constant time, and check that `t` is recent.
+
+### Debugging
+
+| Request | Purpose |
+|---|---|
+| `POST /auth/admin/webhooks/:id/test` | Queue a `webhook.test` delivery |
+| `GET /auth/admin/webhooks/:id/deliveries` | Recent deliveries with `status`, `attemptCount`, `lastResponseStatus`, `lastError` |
+| `POST /auth/admin/webhooks/:id/deliveries/:deliveryId/retry` | Send again now |
+| `PATCH /auth/admin/webhooks/:id { "isEnabled": false }` | Pause |

package/docs/api-reference.md

@@ -0,0 +1,175 @@
+# API reference
+
+A one-page overview of every endpoint. For the **exact request and response JSON** of each one, see [Endpoints](endpoints/README.md).
+
+## Conventions
+
+- **Base path:** all routes are under `/auth`, except `GET /.well-known/jwks.json`.
+- **Content type:** request and response bodies are JSON. Unknown body fields are **rejected** (`VALIDATION_ERROR`), which stops clients from sneaking in fields such as `roles`.
+- **Success:** every success response has `"success": true`.
+- **Errors:** every error looks like `{ "success": false, "code": "...", "message": "..." }`, sometimes with extra fields. See [Error codes](error-codes.md).
+- **Auth column:**
+  - *Public:* no token needed.
+  - *User:* `Authorization: Bearer <accessToken>`.
+  - *User + live:* also checks in the database that the session is still active (sensitive actions).
+  - *Admin:* a user with a role in `settings.admin.adminRoles`, checked live.
+- **Rate limits:** a limited request returns `429 TOO_MANY_REQUESTS` with `retryAfterSeconds` and a `Retry-After` header.
+- **Sign-in result:** "→ sign-in result" means the response is `signed_in` or `two_factor_required`, see [Sign-in flows](sign-in-flows.md#every-sign-in-ends-the-same-way).
+
+## Email + password
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/auth/register` | Public | `email`, `password`, `firstName?`, `lastName?`, `phoneNumber?`, `acceptTerms?`, `acceptPrivacyPolicy?` | `201` `{ status: "verification_required", message, pendingVerifications }` or sign-in result |
+| POST | `/auth/login` | Public | `email`, `password` | sign-in result |
+| POST | `/auth/email/send-verification` | Public | `email` | `{ message }`, always |
+| POST | `/auth/email/verify` | Public | `token` | `{ message, status, pendingVerifications }` |
+| POST | `/auth/password/forgot` | Public | `email` | `{ message }`, always |
+| POST | `/auth/password/reset` | Public | `token`, `newPassword` | `{ message }` |
+| POST | `/auth/password/change` | User | `currentPassword?`, `newPassword` | `{ message }` |
+
+## Passwordless
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/auth/email/send-otp` | Public | `email` | `{ message }`, always |
+| POST | `/auth/email/verify-otp` | Public | `email`, `code`, sign-up details\* | sign-in result |
+| POST | `/auth/magic-link/send` | Public | `email` | `{ message }`, always |
+| POST | `/auth/magic-link/verify` | Public | `token`, sign-up details\* | sign-in result |
+| POST | `/auth/phone/send-otp` | Public | `phoneNumber` | `{ message }`, always |
+| POST | `/auth/phone/verify-otp` | Public | `phoneNumber`, `code`, sign-up details\* | sign-in result |
+
+\* Sign-up details: `firstName?`, `lastName?`, `acceptTerms?`, `acceptPrivacyPolicy?`. They are only used when the request creates a new account.
+
+## Social
+
+`:provider` is `google`, `apple` or `facebook`.
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/auth/social/:provider` | Public | `token`, `nonce?`, sign-up details\* | sign-in result |
+| POST | `/auth/social/:provider/link` | User + live | `token`, `nonce?` | `{}` |
+| DELETE | `/auth/social/:provider` | User + live | none | `{}` |
+
+## Passkeys
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/auth/passkeys/register/options` | User + live | none | `{ challengeToken, options }` |
+| POST | `/auth/passkeys/register/verify` | User + live | `challengeToken`, `response`, `name?` | `{ passkey }` |
+| POST | `/auth/passkeys/sign-in/options` | Public | none | `{ challengeToken, options }` |
+| POST | `/auth/passkeys/sign-in/verify` | Public | `challengeToken`, `response` | sign-in result |
+| GET | `/auth/passkeys` | User | none | `{ passkeys: [{ id, name, isBackedUp, createdAt, lastUsedAt }] }` |
+| PATCH | `/auth/passkeys/:id` | User | `name` | `{}` |
+| DELETE | `/auth/passkeys/:id` | User + live | none | `{}` |
+
+## Two-factor
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| GET | `/auth/2fa` | User | none | `{ isEnabled, remainingBackupCodes }` |
+| POST | `/auth/2fa/setup` | User + live | none | `{ secret, authenticatorAppUrl }` |
+| POST | `/auth/2fa/enable` | User + live | `code` | `{ backupCodes }` |
+| POST | `/auth/2fa/disable` | User + live | `code` | `{}` |
+| POST | `/auth/2fa/backup-codes` | User + live | `code` | `{ backupCodes }` |
+| POST | `/auth/2fa/verify` | Public | `challengeToken`, `code` | `signed_in` result |
+
+## Account and sessions
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/auth/refresh` | Public | `refreshToken` (omit in cookie mode) | `{ accessToken, expiresIn, refreshToken, refreshTokenExpiresAt, sessionId }` |
+| POST | `/auth/logout` | User | none | `{ message }` |
+| POST | `/auth/logout-all` | User | none | `{ message, endedSessions }` |
+| GET | `/auth/me` | User + live | none | `{ user }` |
+| PATCH | `/auth/me` | User + live | `firstName?`, `lastName?`, `metadata?` | `{ user }` |
+| DELETE | `/auth/me` | User + live | none | `{ message }` |
+| GET | `/auth/me/export` | User + live | none | `{ exportedAt, profile, signInMethods, linkedAccounts, passkeys, devices, organizations, securityHistory }` |
+| POST | `/auth/email/change` | User + live | `newEmail`, `currentPassword?` | `{ message }` |
+| POST | `/auth/email/change/confirm` | Public | `token` | `{ message, user }` |
+| GET | `/auth/health` | Public | none | `{ status, checks: { database, redis } }` (503 when unhealthy) |
+| GET | `/auth/sign-in-methods` | User | none | `{ signInMethods: { hasPassword, canUseEmailCode, canUsePhoneCode, socialAccounts, passkeyCount } }` |
+| GET | `/auth/sessions` | User | none | `{ sessions: [{ id, isCurrentDevice, signInMethod, ipAddress, userAgent, createdAt, lastUsedAt }] }` |
+| DELETE | `/auth/sessions/:id` | User | none | `{}` |
+| POST | `/auth/deactivate` | User + live | none | `{ message }` |
+| POST | `/auth/reactivate` | Public | `reactivationToken` | sign-in result |
+
+### The user object
+
+```jsonc
+{
+  "id": "5f0c...",
+  "email": "asha@example.com",           // null for phone-only users
+  "isEmailVerified": true,
+  "phoneNumber": "+919876543210",        // null if none
+  "isPhoneVerified": false,
+  "firstName": "Asha",
+  "lastName": "Rao",
+  "roles": ["user"],
+  "status": "ACTIVE",                    // PENDING_VERIFICATION | ACTIVE | SUSPENDED | DEACTIVATED | DELETED
+  "pendingVerifications": [],            // ["email"] / ["phone"] when not yet active
+  "onboardingCompleted": false,
+  "isTwoFactorEnabled": false,
+  "metadata": {},                        // your app's own fields
+  "lastSignedInAt": "2026-10-20T05:00:00.000Z",
+  "createdAt": "2026-10-01T09:00:00.000Z"
+}
+```
+
+## Organizations
+
+All need a signed-in user, and roles are checked per organization. See [Organizations](organizations.md).
+
+| Method | Path | Minimum role | Body |
+|---|---|---|---|
+| GET | `/auth/organizations` | none | none |
+| POST | `/auth/organizations` | none | `name`, `slug` |
+| POST | `/auth/organizations/switch` | member | `organizationId` (or `null`) → `{ accessToken, expiresIn, organizationId }` |
+| POST | `/auth/organizations/invitations/accept` | none | `token` |
+| GET | `/auth/organizations/:id` | member | none |
+| PATCH | `/auth/organizations/:id` | admin | `name?`, `slug?`, `metadata?` |
+| DELETE | `/auth/organizations/:id` | owner | none |
+| GET | `/auth/organizations/:id/members` | member | none |
+| PATCH | `/auth/organizations/:id/members/:userId` | admin\*\* | `role` |
+| DELETE | `/auth/organizations/:id/members/:userId` | admin\*\*, or self | none |
+| GET | `/auth/organizations/:id/invitations` | admin | none |
+| POST | `/auth/organizations/:id/invitations` | admin\*\* | `email`, `role` |
+| DELETE | `/auth/organizations/:id/invitations/:invitationId` | admin | none |
+
+\*\* Anything that makes, changes or removes an **owner** needs an owner.
+
+## Admin
+
+All need an admin. See [Admin, API keys and webhooks](admin-api-keys-webhooks.md).
+
+| Method | Path | Body / query |
+|---|---|---|
+| GET | `/auth/admin/users` | `?search=&status=&role=&page=&pageSize=` |
+| GET | `/auth/admin/users/:id` | none |
+| PATCH | `/auth/admin/users/:id` | `firstName?`, `lastName?`, `metadata?` |
+| PUT | `/auth/admin/users/:id/roles` | `roles` |
+| POST | `/auth/admin/users/:id/suspend` | `reason` |
+| POST | `/auth/admin/users/:id/unsuspend` | none |
+| POST | `/auth/admin/users/:id/verify-email` | none |
+| POST | `/auth/admin/users/:id/reset-2fa` | none |
+| POST | `/auth/admin/users/:id/logout-all` | none |
+| DELETE | `/auth/admin/users/:id` | none |
+| GET / PATCH / DELETE | `/auth/admin/settings` | PATCH: partial settings |
+| GET | `/auth/admin/audit-log` | `?userId=&eventName=&page=&pageSize=` |
+| GET | `/auth/admin/stats` | none |
+| POST | `/auth/admin/maintenance/cleanup` | none |
+| POST | `/auth/admin/signing-keys/rotate` | none |
+| GET / POST | `/auth/admin/api-keys` | POST: `name`, `scopes`, `organizationId?`, `expiresAt?` |
+| DELETE | `/auth/admin/api-keys/:id` | none |
+| GET / POST | `/auth/admin/webhooks` | POST: `url`, `eventNames?`, `description?`, `isEnabled?` |
+| PATCH / DELETE | `/auth/admin/webhooks/:id` | PATCH: same fields, all optional |
+| POST | `/auth/admin/webhooks/:id/rotate-secret` | none |
+| POST | `/auth/admin/webhooks/:id/test` | none |
+| GET | `/auth/admin/webhooks/:id/deliveries` | `?page=&pageSize=` |
+| POST | `/auth/admin/webhooks/:id/deliveries/:deliveryId/retry` | none |
+
+## Public keys
+
+| Method | Path | Auth | Response |
+|---|---|---|---|
+| GET | `/.well-known/jwks.json` | Public | `{ keys: [...] }`, the ES256 public keys that verify access tokens. Cached 5 minutes. |