@nage-api/auth 1.0.0-beta.2

package/dist/auth.module.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * `NageAuthModule` — one `forRoot` that registers both guards globally
+ * (PLAN.md §15.1, §11.1).
+ *
+ * The module owns the composition: an application supplies stores and secrets,
+ * and gets back a protected surface. It deliberately does **not** offer a way
+ * to register the controller without the guards — a package that lets you take
+ * the endpoints and skip the protection is a footgun with a `forRoot`.
+ *
+ * Every store defaults to its in-memory implementation so the module is usable
+ * (and testable) before a database exists; a real deployment passes its own,
+ * and `assertProductionStores` refuses the in-memory ones there.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var NageAuthModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageAuthModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@nage-api/core");
+const api_key_service_js_1 = require("./api-key.service.js");
+const auth_controller_js_1 = require("./auth.controller.js");
+const auth_guard_js_1 = require("./auth.guard.js");
+const auth_service_js_1 = require("./auth.service.js");
+const authorization_guard_js_1 = require("./authorization.guard.js");
+const jwt_js_1 = require("./jwt.js");
+const lockout_service_js_1 = require("./lockout.service.js");
+const otp_service_js_1 = require("./otp.service.js");
+const policy_js_1 = require("./policy.js");
+const principal_resolver_js_1 = require("./principal.resolver.js");
+const session_service_js_1 = require("./session.service.js");
+const password_js_1 = require("./password.js");
+const config_js_1 = require("./config.js");
+const memory_stores_js_1 = require("./memory-stores.js");
+const tokens_js_1 = require("./tokens.js");
+let NageAuthModule = NageAuthModule_1 = class NageAuthModule {
+    static forRoot(options) {
+        const config = (0, config_js_1.resolveAuthConfig)({
+            ...(options.auth === undefined ? {} : { auth: options.auth }),
+            environment: options.environment,
+            ...(options.roles === undefined ? {} : { roles: options.roles }),
+            ...(options.impersonation === undefined ? {} : { impersonation: options.impersonation }),
+        });
+        const stores = {
+            users: options.users ?? new memory_stores_js_1.MemoryAuthUserStore(),
+            sessions: options.sessions ?? new memory_stores_js_1.MemorySessionStore(),
+            otpStore: options.otpStore ?? new memory_stores_js_1.MemoryOtpStore(),
+            otpChannel: options.otpChannel ?? new memory_stores_js_1.MemoryOtpChannel(),
+            apiKeys: options.apiKeys ?? new memory_stores_js_1.MemoryApiKeyStore(),
+            lockout: options.lockout ?? new memory_stores_js_1.MemoryLockoutStore(),
+        };
+        assertProductionStores(config, options, stores);
+        const hasher = options.hasher ?? new password_js_1.Argon2PasswordHasher({ pepper: options.secrets.passwordPepper });
+        const signer = options.signer ??
+            new jwt_js_1.JoseTokenSigner({
+                config,
+                privateKey: options.secrets.jwtPrivateKey,
+                ...(options.secrets.jwtPublicKey === undefined
+                    ? {}
+                    : { publicKey: options.secrets.jwtPublicKey }),
+            });
+        const sessionService = new session_service_js_1.SessionService({
+            store: stores.sessions,
+            config,
+            pepper: options.secrets.sessionPepper,
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+            ...(options.audit === undefined ? {} : { audit: options.audit }),
+        });
+        const lockoutService = new lockout_service_js_1.LockoutService({
+            store: stores.lockout,
+            config: config.lockout,
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+            ...(options.audit === undefined ? {} : { audit: options.audit }),
+        });
+        const otpService = new otp_service_js_1.OtpService({
+            store: stores.otpStore,
+            channel: stores.otpChannel,
+            config: config.otp,
+            pepper: options.secrets.otpPepper,
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+            ...(options.audit === undefined ? {} : { audit: options.audit }),
+        });
+        const authService = new auth_service_js_1.AuthService({
+            config,
+            users: stores.users,
+            sessions: sessionService,
+            hasher,
+            signer,
+            otp: otpService,
+            lockout: lockoutService,
+            ...(options.audit === undefined ? {} : { audit: options.audit }),
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+        });
+        const principals = new principal_resolver_js_1.PrincipalResolver({
+            users: stores.users,
+            sessions: stores.sessions,
+            roles: config.roles,
+            ...(options.principalCacheTtlMs === undefined
+                ? {}
+                : { cacheTtlMs: options.principalCacheTtlMs }),
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+        });
+        const policies = new policy_js_1.PolicyRegistry(options.policies ?? {});
+        const apiKeyService = config.apiKeys.enabled
+            ? new api_key_service_js_1.ApiKeyService({
+                store: stores.apiKeys,
+                pepper: requireApiKeyPepper(options.secrets),
+                ...(options.clock === undefined ? {} : { clock: options.clock }),
+                ...(options.audit === undefined ? {} : { audit: options.audit }),
+            })
+            : undefined;
+        const providers = [
+            { provide: tokens_js_1.NAGE_AUTH_CONFIG, useValue: config },
+            { provide: tokens_js_1.NAGE_AUTH_USER_STORE, useValue: stores.users },
+            { provide: tokens_js_1.NAGE_SESSION_STORE, useValue: stores.sessions },
+            { provide: tokens_js_1.NAGE_OTP_STORE, useValue: stores.otpStore },
+            { provide: tokens_js_1.NAGE_OTP_CHANNEL, useValue: stores.otpChannel },
+            { provide: tokens_js_1.NAGE_API_KEY_STORE, useValue: stores.apiKeys },
+            { provide: tokens_js_1.NAGE_LOCKOUT_STORE, useValue: stores.lockout },
+            { provide: tokens_js_1.NAGE_PASSWORD_HASHER, useValue: hasher },
+            { provide: tokens_js_1.NAGE_TOKEN_SIGNER, useValue: signer },
+            { provide: session_service_js_1.SessionService, useValue: sessionService },
+            { provide: lockout_service_js_1.LockoutService, useValue: lockoutService },
+            { provide: otp_service_js_1.OtpService, useValue: otpService },
+            { provide: auth_service_js_1.AuthService, useValue: authService },
+            { provide: principal_resolver_js_1.PrincipalResolver, useValue: principals },
+            { provide: policy_js_1.PolicyRegistry, useValue: policies },
+            // Order matters: Nest runs global guards in registration order, and
+            // authorization has nothing to authorize until authentication has run.
+            {
+                provide: core_1.APP_GUARD,
+                inject: [core_1.Reflector],
+                useFactory: (reflector) => new auth_guard_js_1.AuthGuard({
+                    signer,
+                    principals,
+                    reflector,
+                    ...(apiKeyService === undefined ? {} : { apiKeys: apiKeyService }),
+                }),
+            },
+            {
+                provide: core_1.APP_GUARD,
+                inject: [core_1.Reflector],
+                useFactory: (reflector) => new authorization_guard_js_1.AuthorizationGuard({ reflector, policies }),
+            },
+        ];
+        if (apiKeyService !== undefined) {
+            providers.push({ provide: api_key_service_js_1.ApiKeyService, useValue: apiKeyService });
+        }
+        if (options.audit !== undefined) {
+            providers.push({ provide: tokens_js_1.NAGE_AUTH_AUDIT, useValue: options.audit });
+        }
+        if (options.clock !== undefined) {
+            providers.push({ provide: tokens_js_1.NAGE_AUTH_CLOCK, useValue: options.clock });
+        }
+        return {
+            module: NageAuthModule_1,
+            controllers: [auth_controller_js_1.AuthController],
+            providers,
+            exports: [
+                auth_service_js_1.AuthService,
+                session_service_js_1.SessionService,
+                otp_service_js_1.OtpService,
+                lockout_service_js_1.LockoutService,
+                principal_resolver_js_1.PrincipalResolver,
+                policy_js_1.PolicyRegistry,
+                tokens_js_1.NAGE_AUTH_CONFIG,
+                tokens_js_1.NAGE_AUTH_USER_STORE,
+                tokens_js_1.NAGE_SESSION_STORE,
+                tokens_js_1.NAGE_PASSWORD_HASHER,
+                tokens_js_1.NAGE_TOKEN_SIGNER,
+                ...(apiKeyService === undefined ? [] : [api_key_service_js_1.ApiKeyService]),
+            ],
+        };
+    }
+};
+exports.NageAuthModule = NageAuthModule;
+exports.NageAuthModule = NageAuthModule = NageAuthModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NageAuthModule);
+/**
+ * Refuse to boot production on the in-memory stores.
+ *
+ * They lose every session on restart and are not shared between instances, so
+ * a deployment that reaches them has a bug that would otherwise present as
+ * "users are randomly logged out" months later.
+ */
+function assertProductionStores(config, options, stores) {
+    if (config.environment !== 'production' && config.environment !== 'staging')
+        return;
+    const defaulted = [
+        options.users === undefined && stores.users instanceof memory_stores_js_1.MemoryAuthUserStore
+            ? 'users'
+            : undefined,
+        options.sessions === undefined && stores.sessions instanceof memory_stores_js_1.MemorySessionStore
+            ? 'sessions'
+            : undefined,
+        options.otpStore === undefined && stores.otpStore instanceof memory_stores_js_1.MemoryOtpStore
+            ? 'otpStore'
+            : undefined,
+        options.lockout === undefined && stores.lockout instanceof memory_stores_js_1.MemoryLockoutStore
+            ? 'lockout'
+            : undefined,
+    ].filter((name) => name !== undefined);
+    if (defaulted.length === 0)
+        return;
+    throw new core_2.ConfigurationError({
+        detail: `NageAuthModule is using in-memory stores in ${config.environment}: ${defaulted.join(', ')}. They are per-process and lost on restart.`,
+        meta: { environment: config.environment, stores: defaulted },
+    });
+}
+function requireApiKeyPepper(secrets) {
+    if (secrets.apiKeyPepper === undefined || secrets.apiKeyPepper === '') {
+        throw new core_2.ConfigurationError({
+            detail: 'auth.apiKeys is enabled but no apiKeyPepper was supplied; set API_KEY_PEPPER',
+            meta: { setting: 'secrets.apiKeyPepper' },
+        });
+    }
+    return secrets.apiKeyPepper;
+}
+//# sourceMappingURL=auth.module.js.map

package/dist/auth.service.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The authentication flows (PLAN.md §15.1).
+ *
+ * The legacy endpoint surface is retained — `POST /auth/local`, `/auth/token`,
+ * `/auth/logout`, `/auth/password/forgot`, `/auth/password/reset`,
+ * `/auth/otp/send`, `/auth/otp/verify`, admin `/auth/user` — because breaking
+ * every existing client is not a security improvement. What changes is
+ * everything behind them.
+ *
+ * Two properties run through the whole file:
+ *
+ * **No enumeration.** 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, and forgot-password
+ * answers identically either way.
+ *
+ * **Nothing partial.** A password reset revokes every session; a login records
+ * its own failures; a refresh either rotates or fails. There is no state where
+ * a credential is half-changed.
+ */
+import type { AuthUser, Id, TokenPair } from '@nage-api/contracts';
+import { LockoutService } from './lockout.service.js';
+import type { OtpService } from './otp.service.js';
+import type { SessionContext, SessionService } from './session.service.js';
+import type { ResolvedAuthConfig } from './config.js';
+import type { AuthAuditSink, AuthUserStore, Clock, PasswordHasher, TokenSigner } from './ports.js';
+export interface AuthServiceOptions {
+    readonly config: ResolvedAuthConfig;
+    readonly users: AuthUserStore;
+    readonly sessions: SessionService;
+    readonly hasher: PasswordHasher;
+    readonly signer: TokenSigner;
+    readonly otp: OtpService;
+    readonly lockout: LockoutService;
+    readonly audit?: AuthAuditSink;
+    readonly clock?: Clock;
+}
+export interface LoginInput {
+    readonly email: string;
+    readonly password: string;
+    readonly context?: SessionContext;
+}
+export interface ResetPasswordInput {
+    readonly email: string;
+    readonly code: string;
+    readonly password: string;
+}
+export declare class AuthService {
+    #private;
+    constructor(options: AuthServiceOptions);
+    /** `POST /auth/local` — email and password. */
+    login(input: LoginInput): Promise<TokenPair>;
+    /** `POST /auth/token` — exchange a refresh token, rotating it. */
+    refresh(refreshToken: string, context?: SessionContext): Promise<TokenPair>;
+    /** `POST /auth/logout` — revoke the whole session family. */
+    logout(refreshToken: string): Promise<void>;
+    /**
+     * `POST /auth/password/forgot` — send a reset code.
+     *
+     * Returns nothing and never fails for an unknown address: the response is
+     * identical whether or not the account exists.
+     */
+    forgotPassword(email: string): Promise<void>;
+    /** `POST /auth/password/reset` — consume the code and set a new password. */
+    resetPassword(input: ResetPasswordInput): Promise<void>;
+    /** `POST /auth/otp/send` — a login code. Silent for unknown addresses. */
+    sendLoginOtp(email: string): Promise<void>;
+    /** `POST /auth/otp/verify` — exchange a login code for tokens. */
+    verifyLoginOtp(email: string, code: string, context?: SessionContext): Promise<TokenPair>;
+    /**
+     * Admin impersonation (`POST /auth/user`), retained from the legacy surface.
+     *
+     * The issued token records who is impersonating in an RFC 8693 `act` claim,
+     * so every downstream log line and audit row shows both identities. It is
+     * short-lived and cannot be chained: an impersonated session may not
+     * impersonate again.
+     */
+    impersonate(actor: AuthUser, targetUserId: Id, context?: SessionContext): Promise<TokenPair>;
+}
+/** Emails are compared case-insensitively; storing them normalised is the app's job. */
+export declare function normaliseEmail(email: string): string;
+//# sourceMappingURL=auth.service.d.ts.map

package/dist/auth.service.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * The authentication flows (PLAN.md §15.1).
+ *
+ * The legacy endpoint surface is retained — `POST /auth/local`, `/auth/token`,
+ * `/auth/logout`, `/auth/password/forgot`, `/auth/password/reset`,
+ * `/auth/otp/send`, `/auth/otp/verify`, admin `/auth/user` — because breaking
+ * every existing client is not a security improvement. What changes is
+ * everything behind them.
+ *
+ * Two properties run through the whole file:
+ *
+ * **No enumeration.** 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, and forgot-password
+ * answers identically either way.
+ *
+ * **Nothing partial.** A password reset revokes every session; a login records
+ * its own failures; a refresh either rotates or fails. There is no state where
+ * a credential is half-changed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthService = void 0;
+exports.normaliseEmail = normaliseEmail;
+const core_1 = require("@nage-api/core");
+const password_js_1 = require("./password.js");
+const jwt_js_1 = require("./jwt.js");
+const config_js_1 = require("./config.js");
+const lockout_service_js_1 = require("./lockout.service.js");
+class AuthService {
+    #config;
+    #users;
+    #sessions;
+    #hasher;
+    #signer;
+    #otp;
+    #lockout;
+    #audit;
+    #clock;
+    /**
+     * Hash of a value nobody knows, verified against when the account does not
+     * exist. Without it, "unknown email" returns in a millisecond and "wrong
+     * password" in eighty — a timing oracle that enumerates the user table.
+     */
+    #decoyHash;
+    constructor(options) {
+        this.#config = options.config;
+        this.#users = options.users;
+        this.#sessions = options.sessions;
+        this.#hasher = options.hasher;
+        this.#signer = options.signer;
+        this.#otp = options.otp;
+        this.#lockout = options.lockout;
+        this.#audit = options.audit;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    /** `POST /auth/local` — email and password. */
+    async login(input) {
+        const email = normaliseEmail(input.email);
+        const key = lockout_service_js_1.LockoutService.key('login', email);
+        await this.#lockout.assertNotLocked(key);
+        const user = await this.#users.findByEmail(email);
+        const valid = await this.#verifyPassword(user, input.password);
+        if (!valid || user === undefined || user.disabled === true) {
+            const status = await this.#lockout.recordFailure(key, { email });
+            await this.#audit?.record({
+                name: 'login.failed',
+                at: this.#clock.now(),
+                ...(user === undefined ? {} : { userId: user.id }),
+                meta: {
+                    reason: user === undefined ? 'unknown-user' : 'bad-password',
+                    failures: status.failures,
+                },
+            });
+            // One error for every cause: wrong password, unknown address and disabled
+            // account are indistinguishable from outside.
+            throw new core_1.AuthenticationError('AUTH_INVALID_CREDENTIALS', {
+                detail: user === undefined
+                    ? `No user with email ${email}`
+                    : `Password mismatch for user ${String(user.id)}`,
+            });
+        }
+        await this.#lockout.recordSuccess(key);
+        // Upgrading opportunistically: the plaintext is only available here, and a
+        // parameter bump should not require a mass reset.
+        if (user.passwordHash !== undefined && this.#hasher.needsRehash(user.passwordHash)) {
+            await this.#users.setPasswordHash(user.id, await this.#hasher.hash(input.password));
+        }
+        return this.#issue(user, input.context ?? {}, 'login.succeeded');
+    }
+    /** `POST /auth/token` — exchange a refresh token, rotating it. */
+    async refresh(refreshToken, context = {}) {
+        const { session, refreshToken: rotated } = await this.#sessions.rotate(refreshToken, context);
+        const user = await this.#users.findById(session.userId);
+        if (user === undefined || user.disabled === true) {
+            // The account went away between issuing and refreshing; the family should
+            // not outlive it.
+            await this.#sessions.revokeAllForUser(session.userId, 'user-unavailable');
+            throw new core_1.AuthenticationError('AUTH_SESSION_REVOKED', {
+                detail: `Refresh for ${String(session.userId)} rejected: the user is missing or disabled`,
+            });
+        }
+        return this.#tokenPair(user, session.familyId, rotated);
+    }
+    /** `POST /auth/logout` — revoke the whole session family. */
+    async logout(refreshToken) {
+        // Deliberately not reporting whether anything was revoked: a client
+        // logging out twice should see success both times.
+        await this.#sessions.revoke(refreshToken);
+    }
+    /**
+     * `POST /auth/password/forgot` — send a reset code.
+     *
+     * Returns nothing and never fails for an unknown address: the response is
+     * identical whether or not the account exists.
+     */
+    async forgotPassword(email) {
+        const normalised = normaliseEmail(email);
+        const user = await this.#users.findByEmail(normalised);
+        if (user === undefined)
+            return;
+        await this.#otp.issue(normalised, 'password-reset');
+    }
+    /** `POST /auth/password/reset` — consume the code and set a new password. */
+    async resetPassword(input) {
+        const email = normaliseEmail(input.email);
+        const key = lockout_service_js_1.LockoutService.key('otp', email);
+        await this.#lockout.assertNotLocked(key);
+        (0, password_js_1.assertPasswordPolicy)(input.password, this.#config.password);
+        const user = await this.#users.findByEmail(email);
+        if (user === undefined) {
+            // Consume an attempt anyway, so a nonexistent address is not a free
+            // oracle for guessing codes.
+            await this.#lockout.recordFailure(key, { email });
+            throw new core_1.AuthenticationError('AUTH_OTP_INVALID', {
+                detail: `Password reset attempted for unknown email ${email}`,
+            });
+        }
+        try {
+            await this.#otp.verify(email, 'password-reset', input.code);
+        }
+        catch (error) {
+            await this.#lockout.recordFailure(key, { email });
+            throw error;
+        }
+        await this.#lockout.recordSuccess(key);
+        await this.#users.setPasswordHash(user.id, await this.#hasher.hash(input.password));
+        // Everything issued under the old password stops working. A reset is often
+        // a response to a compromise, and leaving live sessions defeats it.
+        await this.#sessions.revokeAllForUser(user.id, 'password-reset');
+        await this.#audit?.record({ name: 'password.reset', at: this.#clock.now(), userId: user.id });
+    }
+    /** `POST /auth/otp/send` — a login code. Silent for unknown addresses. */
+    async sendLoginOtp(email) {
+        const normalised = normaliseEmail(email);
+        const user = await this.#users.findByEmail(normalised);
+        if (user === undefined || user.disabled === true)
+            return;
+        await this.#otp.issue(normalised, 'login');
+    }
+    /** `POST /auth/otp/verify` — exchange a login code for tokens. */
+    async verifyLoginOtp(email, code, context = {}) {
+        const normalised = normaliseEmail(email);
+        const key = lockout_service_js_1.LockoutService.key('otp', normalised);
+        await this.#lockout.assertNotLocked(key);
+        const user = await this.#users.findByEmail(normalised);
+        if (user === undefined || user.disabled === true) {
+            await this.#lockout.recordFailure(key, { email: normalised });
+            throw new core_1.AuthenticationError('AUTH_OTP_INVALID', {
+                detail: `OTP login attempted for unknown or disabled account ${normalised}`,
+            });
+        }
+        try {
+            await this.#otp.verify(normalised, 'login', code);
+        }
+        catch (error) {
+            await this.#lockout.recordFailure(key, { email: normalised });
+            throw error;
+        }
+        await this.#lockout.recordSuccess(key);
+        return this.#issue(user, context, 'login.succeeded');
+    }
+    /**
+     * Admin impersonation (`POST /auth/user`), retained from the legacy surface.
+     *
+     * The issued token records who is impersonating in an RFC 8693 `act` claim,
+     * so every downstream log line and audit row shows both identities. It is
+     * short-lived and cannot be chained: an impersonated session may not
+     * impersonate again.
+     */
+    async impersonate(actor, targetUserId, context = {}) {
+        if (!this.#config.impersonation.enabled) {
+            throw new core_1.AuthorizationError('FORBIDDEN', {
+                detail: 'Impersonation is disabled; enable auth.impersonation to use it',
+            });
+        }
+        if (actor.impersonatedBy !== undefined) {
+            throw new core_1.AuthorizationError('FORBIDDEN', {
+                detail: `Principal ${String(actor.id)} is already impersonating and may not chain`,
+            });
+        }
+        const allowed = this.#config.impersonation.allowedRoles;
+        if (!actor.roles.some((role) => allowed.includes(role))) {
+            throw new core_1.AuthorizationError('INSUFFICIENT_ROLE', {
+                detail: `Impersonation needs one of [${allowed.join(', ')}]; ${String(actor.id)} has [${actor.roles.join(', ')}]`,
+            });
+        }
+        const target = await this.#users.findById(targetUserId);
+        if (target === undefined || target.disabled === true) {
+            throw new core_1.AuthenticationError('AUTH_INVALID_CREDENTIALS', {
+                detail: `Impersonation target ${String(targetUserId)} is missing or disabled`,
+            });
+        }
+        const { session, refreshToken } = await this.#sessions.issue(target.id, context);
+        await this.#audit?.record({
+            name: 'impersonation.started',
+            at: this.#clock.now(),
+            userId: target.id,
+            sessionId: session.familyId,
+            meta: { actorId: actor.id },
+        });
+        return this.#tokenPair(target, session.familyId, refreshToken, {
+            impersonatedBy: String(actor.id),
+            ttlSeconds: this.#config.impersonation.ttlSeconds,
+        });
+    }
+    async #issue(user, context, event) {
+        const { session, refreshToken } = await this.#sessions.issue(user.id, context);
+        await this.#audit?.record({
+            name: event,
+            at: this.#clock.now(),
+            userId: user.id,
+            sessionId: session.familyId,
+        });
+        return this.#tokenPair(user, session.familyId, refreshToken);
+    }
+    async #tokenPair(user, familyId, refreshToken, options = {}) {
+        const expiresIn = options.ttlSeconds ?? this.#config.jwt.accessTtlSeconds;
+        const accessToken = await this.#signer.sign((0, jwt_js_1.buildClaims)({
+            userId: String(user.id),
+            // The **family** id: it is the unit a logout or a reuse detection
+            // revokes, so it is what the access token must be checked against.
+            sessionId: familyId,
+            roles: user.roles,
+            permissions: (0, config_js_1.resolvePermissions)(this.#config.roles, user.roles, user.permissions ?? []),
+            ...(user.tenantId === undefined ? {} : { tenantId: String(user.tenantId) }),
+            ...(options.impersonatedBy === undefined ? {} : { impersonatedBy: options.impersonatedBy }),
+        }), { expiresInSeconds: expiresIn });
+        return { accessToken, refreshToken, expiresIn, tokenType: 'Bearer' };
+    }
+    async #verifyPassword(user, password) {
+        if (user?.passwordHash === undefined) {
+            // Burn the same work on a miss as on a hit.
+            await this.#hasher.verify(await this.#decoy(), password);
+            return false;
+        }
+        return this.#hasher.verify(user.passwordHash, password);
+    }
+    #decoy() {
+        this.#decoyHash ??= this.#hasher.hash((0, core_1.randomToken)(32));
+        return this.#decoyHash;
+    }
+}
+exports.AuthService = AuthService;
+/** Emails are compared case-insensitively; storing them normalised is the app's job. */
+function normaliseEmail(email) {
+    return email.trim().toLowerCase();
+}
+//# sourceMappingURL=auth.service.js.map

package/dist/authorization.guard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The global authorization guard (PLAN.md §15.2).
+ *
+ * Runs after `AuthGuard`, so a principal is already in the context. Three
+ * checks, all of which must pass: any of the required roles, **all** of the
+ * required permissions, and the named policy.
+ *
+ * Permissions are conjunctive on purpose. `@Permissions('order:read',
+ * 'order:write')` on a handler that reads and writes should mean both; an
+ * "any" reading would grant write access to a read-only caller.
+ */
+import { type CanActivate, type ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { PolicyRegistry } from './policy.js';
+export interface AuthorizationGuardOptions {
+    readonly reflector: Reflector;
+    readonly policies: PolicyRegistry;
+}
+export declare class AuthorizationGuard implements CanActivate {
+    #private;
+    constructor(options: AuthorizationGuardOptions);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//# sourceMappingURL=authorization.guard.d.ts.map