@nage-api/auth 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,176 @@
+# @nage-api/auth
+
+Authentication and authorization (PLAN.md §15). Opt-in, engine-agnostic, and
+**globally enforced**: importing the module protects every route, and opening
+one is a decision you have to write down.
+
+The legacy framework wired guards per controller, so a new file started life
+unauthenticated. Here `NageAuthModule.forRoot` registers `AuthGuard` and
+`AuthorizationGuard` as `APP_GUARD`s, and `@Public()` is the only way out.
+
+## What it provides
+
+| Area           | Export                                                | Notes                                                        |
+| -------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| Access tokens  | `JoseTokenSigner`, `buildClaims`, `parseClaims`       | RS256, algorithm pinned, issuer and audience checked         |
+| Sessions       | `SessionService`                                      | Opaque refresh token, HMAC-stored, rotated, reuse-detected   |
+| Passwords      | `Argon2PasswordHasher`, `assertPasswordPolicy`        | argon2id (19 MiB, t=2) with a pepper; opportunistic re-hash  |
+| One-time codes | `OtpService`                                          | CSPRNG, HMAC-stored, TTL + attempt ceiling + resend cooldown |
+| API keys       | `ApiKeyService`                                       | `nage_<prefix>_<secret>`, hashed, scoped, opt-in per route   |
+| Lockout        | `LockoutService`                                      | Per-identity failure counting, temporary lock                |
+| Authorization  | `@Roles`, `@Permissions`, `@Policy`, `PolicyRegistry` | RBAC by default, ABAC when you want it                       |
+| Principal      | `PrincipalResolver`                                   | Roles from the store, not the token; revocation is immediate |
+| Audit          | `AuthAuditSink`                                       | Typed security events, never containing a credential         |
+
+## Endpoints
+
+The legacy surface is retained, so existing clients keep working:
+
+```
+POST /auth/local             email + password        → token pair
+POST /auth/token             refresh token           → rotated token pair
+POST /auth/logout            refresh token           → 204
+POST /auth/password/forgot   email                   → 202, always
+POST /auth/password/reset    email + code + password → 204
+POST /auth/otp/send          email                   → 202, always
+POST /auth/otp/verify        email + code            → token pair
+POST /auth/user              admin impersonation     → token pair
+```
+
+## Wiring it up
+
+```ts
+import { NageAuthModule, ownershipPolicy } from '@nage-api/auth';
+import type { AuthUserStore, SessionStore } from '@nage-api/auth';
+import type { NodeEnvironment } from '@nage-api/contracts';
+
+// Validated by `@nage-api/config` at boot. None of the peppers has a default: a
+// default secret is the same defect as the `admin@admin.com` seed user (§12).
+declare const env: {
+  NODE_ENV: NodeEnvironment;
+  JWT_PRIVATE_KEY: string;
+  JWT_PUBLIC_KEY: string;
+  PASSWORD_PEPPER: string;
+  SESSION_PEPPER: string;
+  OTP_PEPPER: string;
+};
+
+// Your implementations, bound to whichever driver the application uses.
+declare const users: AuthUserStore;
+declare const sessions: SessionStore;
+
+export const authModule = NageAuthModule.forRoot({
+  environment: env.NODE_ENV,
+  auth: {
+    jwt: { issuer: 'https://auth.example.com', audience: 'https://api.example.com' },
+  },
+  roles: {
+    admin: ['user:read', 'user:write', 'order:read', 'order:write'],
+    editor: ['order:read', 'order:write'],
+  },
+  policies: { 'owns-order': ownershipPolicy('id') },
+  secrets: {
+    jwtPrivateKey: env.JWT_PRIVATE_KEY,
+    jwtPublicKey: env.JWT_PUBLIC_KEY,
+    passwordPepper: env.PASSWORD_PEPPER,
+    sessionPepper: env.SESSION_PEPPER,
+    otpPepper: env.OTP_PEPPER,
+  },
+  users,
+  sessions,
+  // …otpStore, otpChannel, lockout
+});
+```
+
+Feature packages may not import each other (§7.2), so auth declares narrow
+ports — `AuthUserStore`, `SessionStore`, `OtpStore`, `OtpChannel`,
+`ApiKeyStore`, `LockoutStore` — and an application binds them to its own
+driver. Each has an in-memory implementation with real semantics, so the module
+works before a database exists and the ports have an executable specification.
+
+_Defaulting_ to the in-memory stores in production or staging is refused at
+boot, for the four that hold state a restart must not lose (`users`,
+`sessions`, `otpStore`, `lockout`): they are per-process, so otherwise the
+mistake surfaces months later as "users are randomly logged out". Passing one
+explicitly is still allowed — the check is against forgetting, not against
+deliberate choice.
+
+## The four decisions worth knowing
+
+**Refresh tokens rotate, and replay revokes the family.** Every refresh issues
+a new token and marks the old one spent. A spent token coming back means
+someone replayed a token the real client already used — and there is no way to
+tell which party it was — so the whole session family is revoked. A silent
+theft becomes a visible re-login.
+
+**Claims are identity, not authority.** A signed token proves _who_ you are; it
+does not prove what you may still do. `PrincipalResolver` reads roles and
+permissions from the store on every request, so a demotion or a disabled
+account takes effect immediately rather than whenever the access token happens
+to expire. A token carrying `roles: ["admin"]` that the store does not back
+grants nothing.
+
+**Revocation is immediate.** The access token carries the session _family_ id,
+and a revoked family is refused, so a logout logs you out instead of leaving a
+15-minute window. Both lookups sit behind a short TTL cache — the default is 5
+seconds, and the tests run with it at 0.
+
+**Everything fails closed.** An unknown policy name denies. A route marked both
+`@Public()` and `@Roles()` is refused rather than opened. An API key works only
+where a route has `@AllowApiKey()`. Nothing here resolves an ambiguity towards
+access.
+
+## Enumeration and timing
+
+Whether an email is registered is not something an unauthenticated caller may
+learn:
+
+- a login against an unknown address still performs a hash verification, so it
+  takes the same time as a wrong password;
+- wrong password, unknown address and disabled account all raise
+  `AUTH_INVALID_CREDENTIALS`;
+- `password/forgot` and `otp/send` answer 202 either way;
+- an authorization failure never names the role or permission that was missing.
+
+Peppers are required, not optional: passwords, refresh tokens, OTP codes and
+API keys are all stored under a key held outside the database, so a dumped
+table is useless on its own.
+
+## Testing against it
+
+```ts
+import { Argon2PasswordHasher, MemoryAuthUserStore, MemorySessionStore } from '@nage-api/auth';
+
+// Sixteen characters minimum, checked in the constructor: anything shorter
+// cannot carry enough entropy to be a pepper.
+const pepper = 'pepper-for-passwords-0123456789';
+
+// argon2id at its cheapest — the algorithm is real, the work factor is not.
+const hasher = new Argon2PasswordHasher({ pepper, memoryCost: 8, timeCost: 1, parallelism: 1 });
+
+const users = new MemoryAuthUserStore([
+  {
+    id: 'u1',
+    email: 'ada@example.test',
+    roles: ['viewer'],
+    passwordHash: await hasher.hash('Correct-Horse-9'),
+  },
+]);
+const sessions = new MemorySessionStore();
+```
+
+Inject a `Clock` to drive expiry and lockout windows without waiting, and a
+`MemoryOtpChannel` to read the code a flow just sent. `docs/packages/auth.md`
+walks through the whole graph.
+
+## Not yet implemented
+
+- OAuth / external providers (Google, Apple, Facebook, Firebase) — §15.1 lists
+  them as opt-in adapters; the `AuthUserStore` port is where they will attach.
+- Redis-backed revocation lists; today revocation is a `SessionStore` query
+  behind the resolver's cache.
+- `nage add auth` adds the dependency and records the feature in the workspace
+  manifest, and prints what to do next. It writes neither the config block, the
+  environment variables (only `nage create --auth jwt` extends the env schema
+  with the key pair and the peppers) nor the store implementations, which depend
+  on the project's own user model.

package/dist/api-key.service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * API keys for service-to-service callers (PLAN.md §15.1).
+ *
+ * A key is `nage_<prefix>_<secret>`: the prefix is a non-secret lookup handle,
+ * the secret is 32 CSPRNG bytes stored only as an HMAC. That split is what lets
+ * verification be a single indexed read followed by one constant-time compare,
+ * instead of hashing the candidate against every row.
+ *
+ * The visible prefix also makes keys revocable by eye — it can be shown in a
+ * dashboard, logged, and matched by secret scanners, none of which is safe to
+ * do with the key itself.
+ */
+import type { Id, Permission } from '@nage-api/contracts';
+import type { ApiKeyRecord, ApiKeyStore, AuthAuditSink, Clock } from './ports.js';
+/** Recognisable in a log or a leak report, and greppable by secret scanners. */
+export declare const API_KEY_PREFIX = "nage";
+export interface ApiKeyServiceOptions {
+    readonly store: ApiKeyStore;
+    readonly pepper: string;
+    readonly clock?: Clock;
+    readonly audit?: AuthAuditSink;
+}
+export interface CreateApiKeyInput {
+    readonly name: string;
+    readonly userId?: Id;
+    readonly roles?: readonly string[];
+    readonly permissions?: readonly Permission[];
+    readonly expiresAt?: number;
+}
+export interface CreatedApiKey {
+    readonly record: ApiKeyRecord;
+    /** Shown once, at creation. Not recoverable afterwards. */
+    readonly key: string;
+}
+export declare class ApiKeyService {
+    #private;
+    constructor(options: ApiKeyServiceOptions);
+    create(input: CreateApiKeyInput): Promise<CreatedApiKey>;
+    /**
+     * Verify a presented key.
+     *
+     * Every failure — bad shape, unknown prefix, wrong secret, revoked, expired —
+     * raises the same error, so the response cannot be used to enumerate which
+     * prefixes exist.
+     */
+    verify(presented: string): Promise<ApiKeyRecord>;
+    revoke(id: string): Promise<void>;
+    hashSecret(secret: string): string;
+}
+//# sourceMappingURL=api-key.service.d.ts.map

package/dist/api-key.service.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * API keys for service-to-service callers (PLAN.md §15.1).
+ *
+ * A key is `nage_<prefix>_<secret>`: the prefix is a non-secret lookup handle,
+ * the secret is 32 CSPRNG bytes stored only as an HMAC. That split is what lets
+ * verification be a single indexed read followed by one constant-time compare,
+ * instead of hashing the candidate against every row.
+ *
+ * The visible prefix also makes keys revocable by eye — it can be shown in a
+ * dashboard, logged, and matched by secret scanners, none of which is safe to
+ * do with the key itself.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiKeyService = exports.API_KEY_PREFIX = void 0;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@nage-api/core");
+/** Recognisable in a log or a leak report, and greppable by secret scanners. */
+exports.API_KEY_PREFIX = 'nage';
+const MIN_PEPPER_LENGTH = 16;
+const PREFIX_LENGTH = 8;
+class ApiKeyService {
+    #store;
+    #pepper;
+    #clock;
+    #audit;
+    constructor(options) {
+        if (options.pepper.length < MIN_PEPPER_LENGTH) {
+            throw new core_1.ConfigurationError({
+                detail: `The API-key pepper must be at least ${String(MIN_PEPPER_LENGTH)} characters`,
+                meta: { setting: 'API_KEY_PEPPER' },
+            });
+        }
+        this.#store = options.store;
+        this.#pepper = options.pepper;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#audit = options.audit;
+    }
+    async create(input) {
+        const prefix = (0, core_1.randomString)(PREFIX_LENGTH).toLowerCase();
+        const secret = (0, core_1.randomToken)(32);
+        const record = {
+            id: (0, core_1.randomId)(),
+            prefix,
+            hashedKey: this.hashSecret(secret),
+            name: input.name,
+            ...(input.userId === undefined ? {} : { userId: input.userId }),
+            roles: input.roles ?? [],
+            permissions: input.permissions ?? [],
+            createdAt: this.#clock.now(),
+            ...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),
+        };
+        await this.#store.create(record);
+        return { record, key: `${exports.API_KEY_PREFIX}_${prefix}_${secret}` };
+    }
+    /**
+     * Verify a presented key.
+     *
+     * Every failure — bad shape, unknown prefix, wrong secret, revoked, expired —
+     * raises the same error, so the response cannot be used to enumerate which
+     * prefixes exist.
+     */
+    async verify(presented) {
+        // Matched rather than split: the secret is base64url, whose alphabet
+        // includes the `_` separator, so splitting would reject a valid key
+        // whenever the random half happened to contain one.
+        const match = new RegExp(`^${exports.API_KEY_PREFIX}_([a-z0-9]+)_(.+)$`).exec(presented);
+        const prefix = match?.[1];
+        const secret = match?.[2];
+        if (prefix === undefined || secret === undefined) {
+            throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', { detail: 'Malformed API key' });
+        }
+        const record = await this.#store.findByPrefix(prefix);
+        if (record === undefined) {
+            throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+                detail: `No API key with prefix ${prefix}`,
+            });
+        }
+        if (!(0, core_1.secureCompare)(record.hashedKey, this.hashSecret(secret))) {
+            throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+                detail: `API key ${prefix} presented an incorrect secret`,
+            });
+        }
+        const now = this.#clock.now();
+        if (record.revokedAt !== undefined) {
+            throw new core_1.AuthenticationError('AUTH_SESSION_REVOKED', {
+                detail: `API key ${prefix} was revoked`,
+            });
+        }
+        if (record.expiresAt !== undefined && record.expiresAt <= now) {
+            throw new core_1.AuthenticationError('AUTH_TOKEN_EXPIRED', { detail: `API key ${prefix} expired` });
+        }
+        await this.#store.touch(record.id, now);
+        await this.#audit?.record({
+            name: 'api-key.used',
+            at: now,
+            ...(record.userId === undefined ? {} : { userId: record.userId }),
+            meta: { prefix, name: record.name },
+        });
+        return record;
+    }
+    async revoke(id) {
+        await this.#store.revoke(id, this.#clock.now());
+    }
+    hashSecret(secret) {
+        return (0, node_crypto_1.createHmac)('sha256', this.#pepper).update(secret, 'utf8').digest('base64url');
+    }
+}
+exports.ApiKeyService = ApiKeyService;
+//# sourceMappingURL=api-key.service.js.map

package/dist/auth.controller.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The retained auth endpoint surface (PLAN.md §15.1).
+ *
+ * Same paths as the legacy framework so existing clients keep working; the
+ * hardening is behind them. Three things are worth noticing here:
+ *
+ * - the login and OTP routes are `@Public()` **and** rate-limited harder than
+ *   the global default, because they are the ones worth brute-forcing;
+ * - `forgot` and `send` always answer 202, whatever the address;
+ * - nothing in this file touches a password, a hash or a code — it parses a
+ *   body, calls a service and returns a token pair.
+ */
+import type { AuthUser, TokenPair } from '@nage-api/contracts';
+import { AuthService } from './auth.service.js';
+import { ForgotPasswordDto, ImpersonateDto, LoginDto, RefreshTokenDto, ResetPasswordDto, SendOtpDto, VerifyOtpDto } from './auth.dto.js';
+interface RequestLike {
+    headers?: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+export declare class AuthController {
+    private readonly auth;
+    constructor(auth: AuthService);
+    login(body: LoginDto, request: RequestLike): Promise<TokenPair>;
+    refresh(body: RefreshTokenDto, request: RequestLike): Promise<TokenPair>;
+    /**
+     * Public because a caller whose access token has already expired must still
+     * be able to log out; the refresh token in the body is the credential.
+     */
+    logout(body: RefreshTokenDto): Promise<void>;
+    forgotPassword(body: ForgotPasswordDto): Promise<void>;
+    resetPassword(body: ResetPasswordDto): Promise<void>;
+    sendOtp(body: SendOtpDto): Promise<void>;
+    verifyOtp(body: VerifyOtpDto, request: RequestLike): Promise<TokenPair>;
+    /**
+     * Administrative impersonation, retained from the legacy `/auth/user`.
+     *
+     * Not decorated with `@Roles`: which roles may impersonate is configuration
+     * (`auth.impersonation.allowedRoles`), and the service enforces it. Putting
+     * the role list in a decorator here would freeze one deployment's answer into
+     * the framework.
+     */
+    impersonate(body: ImpersonateDto, actor: AuthUser, request: RequestLike): Promise<TokenPair>;
+}
+export {};
+//# sourceMappingURL=auth.controller.d.ts.map