@nage-api/auth 1.0.0-beta.2

package/dist/authorization.guard.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * 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.
+ */
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthorizationGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+const decorators_js_1 = require("./decorators.js");
+let AuthorizationGuard = class AuthorizationGuard {
+    #reflector;
+    #policies;
+    constructor(options) {
+        this.#reflector = options.reflector;
+        this.#policies = options.policies;
+    }
+    async canActivate(context) {
+        if (context.getType() !== 'http')
+            return true;
+        const rules = (0, decorators_js_1.readAuthorizationRules)(this.#reflector, context);
+        const unrestricted = rules.roles.length === 0 && rules.permissions.length === 0 && rules.policy === undefined;
+        if (unrestricted)
+            return true;
+        // A route carrying authorization rules is not public, whatever `@Public()`
+        // says — the combination is a mistake, and resolving it towards "open"
+        // would silently unguard the route.
+        if ((0, core_1.isPublicRoute)(this.#reflector, context)) {
+            throw new core_1.AuthorizationError('FORBIDDEN', {
+                detail: 'Route is marked @Public() but also carries authorization rules; remove one',
+            });
+        }
+        const user = (0, core_1.getActiveContext)()?.user;
+        if (user === undefined) {
+            throw new core_1.AuthenticationError('AUTH_REQUIRED', {
+                detail: 'Authorization rules were evaluated without an authenticated principal',
+            });
+        }
+        this.#assertRoles(user, rules.roles);
+        this.#assertPermissions(user, rules.permissions);
+        if (rules.policy !== undefined) {
+            await this.#assertPolicy(user, rules.policy, context);
+        }
+        return true;
+    }
+    #assertRoles(user, required) {
+        if (required.length === 0)
+            return;
+        if (required.some((role) => user.roles.includes(role)))
+            return;
+        throw new core_1.AuthorizationError('INSUFFICIENT_ROLE', {
+            // The requirement is logged, never returned: telling a caller which role
+            // they lack maps out the permission model for them.
+            detail: `Principal ${String(user.id)} has [${user.roles.join(', ')}] but the route needs one of [${required.join(', ')}]`,
+            meta: { required, held: user.roles },
+        });
+    }
+    #assertPermissions(user, required) {
+        const missing = required.filter((permission) => !user.permissions.includes(permission));
+        if (missing.length === 0)
+            return;
+        throw new core_1.AuthorizationError('INSUFFICIENT_PERMISSION', {
+            detail: `Principal ${String(user.id)} is missing [${missing.join(', ')}]`,
+            meta: { required, missing },
+        });
+    }
+    async #assertPolicy(user, name, context) {
+        const request = context.switchToHttp().getRequest();
+        const policyContext = {
+            user,
+            method: request.method ?? 'GET',
+            path: request.originalUrl ?? request.url ?? '',
+            params: request.params ?? {},
+            query: request.query ?? {},
+            body: request.body,
+        };
+        const decision = await this.#policies.evaluate(name, policyContext);
+        if (decision.allowed)
+            return;
+        throw new core_1.AuthorizationError('POLICY_DENIED', {
+            detail: `Policy "${name}" denied ${String(user.id)}: ${decision.reason ?? 'no reason given'}`,
+            meta: { policy: name, reason: decision.reason },
+        });
+    }
+};
+exports.AuthorizationGuard = AuthorizationGuard;
+exports.AuthorizationGuard = AuthorizationGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], AuthorizationGuard);
+//# sourceMappingURL=authorization.guard.js.map

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Resolving `AuthConfig` into the settled values the services use
+ * (PLAN.md §11.1, §15).
+ *
+ * Two rules shape this file. Defaults are the **secure** ones, so an
+ * application that configures nothing still gets RS256, 15-minute access
+ * tokens, rotation and reuse detection. And every departure is validated here
+ * rather than discovered at the first login: a 24-hour access token or an
+ * HS256 signing key is a configuration error, not a runtime surprise.
+ */
+import type { AuthConfig, NodeEnvironment, Permission, RoleMatrix } from '@nage-api/contracts';
+/** Every value the auth services read, with nothing left optional. */
+export interface ResolvedAuthConfig {
+    readonly environment: NodeEnvironment;
+    readonly jwt: {
+        readonly algorithm: 'RS256' | 'RS512' | 'ES256' | 'HS256';
+        readonly accessTtlSeconds: number;
+        readonly issuer: string;
+        readonly audience: string | readonly string[];
+        readonly keyId?: string;
+        /** Tolerated clock difference when verifying, in seconds. */
+        readonly clockToleranceSeconds: number;
+    };
+    readonly refresh: {
+        readonly ttlSeconds: number;
+        readonly rotate: boolean;
+        readonly reuseDetection: boolean;
+    };
+    readonly password: {
+        readonly minLength: number;
+        readonly requireMixedCase: boolean;
+        readonly requireNumber: boolean;
+        readonly requireSymbol: boolean;
+    };
+    readonly otp: {
+        readonly length: number;
+        readonly ttlSeconds: number;
+        readonly maxAttempts: number;
+        readonly resendCooldownSeconds: number;
+    };
+    readonly lockout: {
+        readonly maxAttempts: number;
+        readonly windowSeconds: number;
+        readonly durationSeconds: number;
+    };
+    readonly apiKeys: {
+        readonly enabled: boolean;
+    };
+    /** Role → permissions. Empty means permissions are granted per user only. */
+    readonly roles: RoleMatrix;
+    /** Roles allowed to impersonate another user via `POST /auth/user`. */
+    readonly impersonation: {
+        readonly enabled: boolean;
+        readonly allowedRoles: readonly string[];
+        readonly ttlSeconds: number;
+    };
+}
+export interface ResolveAuthConfigInput {
+    readonly auth?: AuthConfig;
+    readonly environment: NodeEnvironment;
+    readonly roles?: RoleMatrix;
+    readonly impersonation?: {
+        readonly enabled?: boolean;
+        readonly allowedRoles?: readonly string[];
+        readonly ttl?: string;
+    };
+}
+export declare function resolveAuthConfig(input: ResolveAuthConfigInput): ResolvedAuthConfig;
+/** Permissions a set of roles grants, plus whatever was granted directly. */
+export declare function resolvePermissions(matrix: RoleMatrix, roles: readonly string[], direct?: readonly Permission[]): readonly Permission[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Resolving `AuthConfig` into the settled values the services use
+ * (PLAN.md §11.1, §15).
+ *
+ * Two rules shape this file. Defaults are the **secure** ones, so an
+ * application that configures nothing still gets RS256, 15-minute access
+ * tokens, rotation and reuse detection. And every departure is validated here
+ * rather than discovered at the first login: a 24-hour access token or an
+ * HS256 signing key is a configuration error, not a runtime surprise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAuthConfig = resolveAuthConfig;
+exports.resolvePermissions = resolvePermissions;
+const core_1 = require("@nage-api/core");
+const DEFAULTS = {
+    accessTtl: '15m',
+    refreshTtl: '30d',
+    otpTtl: '5m',
+    resendCooldown: '60s',
+    lockoutWindow: '15m',
+    lockoutDuration: '15m',
+    impersonationTtl: '15m',
+};
+/** Above this, a stolen access token stays useful long enough to matter (§12). */
+const MAX_SAFE_ACCESS_TTL_SECONDS = 60 * 60;
+function resolveAuthConfig(input) {
+    const auth = input.auth ?? {};
+    const jwt = auth.jwt;
+    if (jwt?.issuer === undefined || jwt.issuer.trim() === '') {
+        // Without an issuer, a token minted by any other service that shares the
+        // key verifies here too.
+        throw new core_1.ConfigurationError({
+            detail: 'auth.jwt.issuer must be set; it is what scopes a token to this deployment',
+            meta: { setting: 'auth.jwt.issuer' },
+        });
+    }
+    const algorithm = jwt.algorithm ?? 'RS256';
+    const production = input.environment === 'production' || input.environment === 'staging';
+    if (algorithm === 'HS256' && production) {
+        // Symmetric signing means every verifier can also mint tokens.
+        throw new core_1.ConfigurationError({
+            detail: 'auth.jwt.algorithm HS256 is not allowed in a deployed environment; use RS256',
+            meta: { setting: 'auth.jwt.algorithm', algorithm, environment: input.environment },
+        });
+    }
+    const accessTtlSeconds = seconds(jwt.accessTtl ?? DEFAULTS.accessTtl, 'auth.jwt.accessTtl');
+    if (production && accessTtlSeconds > MAX_SAFE_ACCESS_TTL_SECONDS) {
+        throw new core_1.ConfigurationError({
+            detail: `auth.jwt.accessTtl of ${jwt.accessTtl ?? ''} exceeds the one-hour ceiling`,
+            meta: { setting: 'auth.jwt.accessTtl', seconds: accessTtlSeconds },
+        });
+    }
+    const refresh = auth.refresh ?? {};
+    const rotate = refresh.rotate ?? true;
+    if (!rotate && (refresh.reuseDetection ?? true)) {
+        // Reuse detection is defined as "a rotated token came back"; without
+        // rotation there is nothing to detect, and claiming otherwise is worse than
+        // admitting it is off.
+        throw new core_1.ConfigurationError({
+            detail: 'auth.refresh.reuseDetection requires auth.refresh.rotate; a token that is never rotated cannot be replayed detectably',
+            meta: { setting: 'auth.refresh.rotate' },
+        });
+    }
+    const password = auth.password ?? {};
+    if (password.algorithm !== undefined && password.algorithm !== 'argon2id') {
+        throw new core_1.ConfigurationError({
+            detail: `auth.password.algorithm "${password.algorithm}" is not supported; this package hashes with argon2id`,
+            meta: { setting: 'auth.password.algorithm', algorithm: password.algorithm },
+        });
+    }
+    const otp = auth.otp ?? {};
+    const otpLength = otp.length ?? 6;
+    if (otpLength < 6) {
+        // A 4-digit code is 10 000 possibilities; with any resend at all that is
+        // brute-forceable regardless of the attempt limit.
+        throw new core_1.ConfigurationError({
+            detail: `auth.otp.length of ${String(otpLength)} is too short; use at least 6 digits`,
+            meta: { setting: 'auth.otp.length', length: otpLength },
+        });
+    }
+    const lockout = auth.lockout ?? {};
+    const impersonation = input.impersonation ?? {};
+    return {
+        environment: input.environment,
+        jwt: {
+            algorithm,
+            accessTtlSeconds,
+            issuer: jwt.issuer,
+            audience: jwt.audience ?? jwt.issuer,
+            ...(jwt.keyId === undefined ? {} : { keyId: jwt.keyId }),
+            clockToleranceSeconds: 5,
+        },
+        refresh: {
+            ttlSeconds: seconds(refresh.ttl ?? DEFAULTS.refreshTtl, 'auth.refresh.ttl'),
+            rotate,
+            reuseDetection: rotate && (refresh.reuseDetection ?? true),
+        },
+        password: {
+            minLength: password.minLength ?? 12,
+            requireMixedCase: password.requireMixedCase ?? true,
+            requireNumber: password.requireNumber ?? true,
+            requireSymbol: password.requireSymbol ?? false,
+        },
+        otp: {
+            length: otpLength,
+            ttlSeconds: seconds(otp.ttl ?? DEFAULTS.otpTtl, 'auth.otp.ttl'),
+            maxAttempts: otp.maxAttempts ?? 5,
+            resendCooldownSeconds: seconds(otp.resendCooldown ?? DEFAULTS.resendCooldown, 'auth.otp.resendCooldown'),
+        },
+        lockout: {
+            maxAttempts: lockout.maxAttempts ?? 5,
+            windowSeconds: seconds(lockout.window ?? DEFAULTS.lockoutWindow, 'auth.lockout.window'),
+            durationSeconds: seconds(lockout.duration ?? DEFAULTS.lockoutDuration, 'auth.lockout.duration'),
+        },
+        apiKeys: { enabled: auth.apiKeys?.enabled ?? false },
+        roles: input.roles ?? {},
+        impersonation: {
+            enabled: impersonation.enabled ?? false,
+            allowedRoles: impersonation.allowedRoles ?? ['admin'],
+            ttlSeconds: seconds(impersonation.ttl ?? DEFAULTS.impersonationTtl, 'auth.impersonation.ttl'),
+        },
+    };
+}
+/** Permissions a set of roles grants, plus whatever was granted directly. */
+function resolvePermissions(matrix, roles, direct = []) {
+    const granted = new Set(direct);
+    for (const role of roles) {
+        // `Object.hasOwn` rather than a bare lookup: role names arrive from the users
+        // table, and `matrix['constructor']` reaches `Object.prototype` and yields a
+        // function. Iterating that threw a raw `TypeError` out of the auth guard, so
+        // one row with a role named `constructor` or `toString` turned every request
+        // that user made into a 500.
+        if (!Object.hasOwn(matrix, role))
+            continue;
+        for (const permission of matrix[role] ?? [])
+            granted.add(permission);
+    }
+    return [...granted].sort();
+}
+function seconds(duration, setting) {
+    const milliseconds = (0, core_1.parseDurationMs)(duration);
+    if (milliseconds <= 0) {
+        throw new core_1.ConfigurationError({
+            detail: `${setting} is not a duration ("${duration}"); use forms like 15m, 24h, 30d`,
+            meta: { setting, value: duration },
+        });
+    }
+    return Math.floor(milliseconds / 1000);
+}
+//# sourceMappingURL=config.js.map

package/dist/decorators.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Authorization decorators (PLAN.md §15.2).
+ *
+ * `@Roles` is the coarse gate, `@Permissions` the fine one, `@Policy` the
+ * resource-aware one. They compose: a handler may require a role *and* a
+ * permission *and* a policy, and all three must pass.
+ *
+ * Reading them is centralised in `readAuthorizationRules` so the guard cannot
+ * accidentally check the handler while ignoring the controller, which is the
+ * classic way an `@Roles('admin')` on a class stops applying.
+ */
+import { type CustomDecorator, type ExecutionContext } from '@nestjs/common';
+import type { Reflector } from '@nestjs/core';
+import type { Permission } from '@nage-api/contracts';
+export declare const AUTH_METADATA_KEYS: {
+    readonly roles: "nage:auth:roles";
+    readonly permissions: "nage:auth:permissions";
+    readonly policy: "nage:auth:policy";
+    readonly apiKeyAllowed: "nage:auth:api-key-allowed";
+};
+/** Require **any** of these roles. */
+export declare const Roles: (...roles: readonly string[]) => CustomDecorator;
+/** Require **every** one of these permissions. */
+export declare const Permissions: (...permissions: readonly Permission[]) => CustomDecorator;
+/** Require a registered policy to allow the request (opt-in ABAC). */
+export declare const Policy: (name: string) => CustomDecorator;
+/**
+ * Allow a machine credential on this route.
+ *
+ * Opt-in per route rather than global: an API key is a long-lived bearer
+ * secret, and letting one reach `POST /auth/password/reset` because it works
+ * everywhere else is how a scoped key becomes a full account takeover.
+ */
+export declare const AllowApiKey: () => CustomDecorator;
+export interface AuthorizationRules {
+    readonly roles: readonly string[];
+    readonly permissions: readonly Permission[];
+    readonly policy?: string;
+}
+/**
+ * Merge the handler's rules with its controller's.
+ *
+ * Union rather than override: a controller-level `@Roles('admin')` and a
+ * handler-level `@Permissions('user:write')` both apply. `getAllAndOverride`
+ * would silently drop the class-level rule, which loosens access — the wrong
+ * direction for a default.
+ */
+export declare function readAuthorizationRules(reflector: Reflector, context: ExecutionContext): AuthorizationRules;
+/** Whether an API key may be used on this route. */
+export declare function isApiKeyAllowed(reflector: Reflector, context: ExecutionContext): boolean;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Authorization decorators (PLAN.md §15.2).
+ *
+ * `@Roles` is the coarse gate, `@Permissions` the fine one, `@Policy` the
+ * resource-aware one. They compose: a handler may require a role *and* a
+ * permission *and* a policy, and all three must pass.
+ *
+ * Reading them is centralised in `readAuthorizationRules` so the guard cannot
+ * accidentally check the handler while ignoring the controller, which is the
+ * classic way an `@Roles('admin')` on a class stops applying.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AllowApiKey = exports.Policy = exports.Permissions = exports.Roles = exports.AUTH_METADATA_KEYS = void 0;
+exports.readAuthorizationRules = readAuthorizationRules;
+exports.isApiKeyAllowed = isApiKeyAllowed;
+const common_1 = require("@nestjs/common");
+exports.AUTH_METADATA_KEYS = {
+    roles: 'nage:auth:roles',
+    permissions: 'nage:auth:permissions',
+    policy: 'nage:auth:policy',
+    apiKeyAllowed: 'nage:auth:api-key-allowed',
+};
+/** Require **any** of these roles. */
+const Roles = (...roles) => (0, common_1.SetMetadata)(exports.AUTH_METADATA_KEYS.roles, roles);
+exports.Roles = Roles;
+/** Require **every** one of these permissions. */
+const Permissions = (...permissions) => (0, common_1.SetMetadata)(exports.AUTH_METADATA_KEYS.permissions, permissions);
+exports.Permissions = Permissions;
+/** Require a registered policy to allow the request (opt-in ABAC). */
+const Policy = (name) => (0, common_1.SetMetadata)(exports.AUTH_METADATA_KEYS.policy, name);
+exports.Policy = Policy;
+/**
+ * Allow a machine credential on this route.
+ *
+ * Opt-in per route rather than global: an API key is a long-lived bearer
+ * secret, and letting one reach `POST /auth/password/reset` because it works
+ * everywhere else is how a scoped key becomes a full account takeover.
+ */
+const AllowApiKey = () => (0, common_1.SetMetadata)(exports.AUTH_METADATA_KEYS.apiKeyAllowed, true);
+exports.AllowApiKey = AllowApiKey;
+/**
+ * Merge the handler's rules with its controller's.
+ *
+ * Union rather than override: a controller-level `@Roles('admin')` and a
+ * handler-level `@Permissions('user:write')` both apply. `getAllAndOverride`
+ * would silently drop the class-level rule, which loosens access — the wrong
+ * direction for a default.
+ */
+function readAuthorizationRules(reflector, context) {
+    const targets = [context.getHandler(), context.getClass()];
+    // `getAllAndMerge` concatenates the array each decorator stored, so this is
+    // already a flat list of role names rather than a list of lists.
+    const roles = new Set(reflector.getAllAndMerge(exports.AUTH_METADATA_KEYS.roles, targets));
+    const permissions = new Set(reflector.getAllAndMerge(exports.AUTH_METADATA_KEYS.permissions, targets));
+    const policy = reflector.getAllAndOverride(exports.AUTH_METADATA_KEYS.policy, targets);
+    return {
+        roles: [...roles],
+        permissions: [...permissions],
+        ...(policy === undefined ? {} : { policy }),
+    };
+}
+/** Whether an API key may be used on this route. */
+function isApiKeyAllowed(reflector, context) {
+    return (reflector.getAllAndOverride(exports.AUTH_METADATA_KEYS.apiKeyAllowed, [
+        context.getHandler(),
+        context.getClass(),
+    ]) === true);
+}
+//# sourceMappingURL=decorators.js.map

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@nage-api/auth` — authentication and authorization (PLAN.md §15).
+ *
+ * Opt-in and engine-agnostic: the package owns credentials, tokens, sessions
+ * and access decisions, and knows nothing about how they are stored. An
+ * application binds the ports in `NageAuthModule.forRoot` and gets a globally
+ * protected surface, with the legacy endpoint paths retained.
+ */
+export type * from '@nage-api/contracts';
+export { NageAuthModule, type AuthSecrets, type NageAuthModuleOptions } from './auth.module.js';
+export { resolveAuthConfig, resolvePermissions, type ResolveAuthConfigInput, type ResolvedAuthConfig, } from './config.js';
+export type { ApiKeyRecord, ApiKeyStore, AuthAuditSink, AuthEvent, AuthEventName, AuthUserRecord, AuthUserStore, Clock, LockoutRecord, LockoutStore, OtpChannel, OtpPurpose, OtpRecord, OtpStore, PasswordHasher, ResolvedPrincipal, SessionStore, TokenSigner, } from './ports.js';
+export { systemClock } from './ports.js';
+export { NAGE_API_KEY_STORE, NAGE_AUTH_AUDIT, NAGE_AUTH_CLOCK, NAGE_AUTH_CONFIG, NAGE_AUTH_USER_STORE, NAGE_LOCKOUT_STORE, NAGE_OTP_CHANNEL, NAGE_OTP_STORE, NAGE_PASSWORD_HASHER, NAGE_SESSION_STORE, NAGE_TOKEN_SIGNER, } from './tokens.js';
+export { AuthService, normaliseEmail, type AuthServiceOptions, type LoginInput, type ResetPasswordInput, } from './auth.service.js';
+export { SessionService, type IssuedSession, type SessionContext, type SessionServiceOptions, } from './session.service.js';
+export { OtpService, type OtpIssueResult, type OtpServiceOptions } from './otp.service.js';
+export { LockoutService, type LockoutStatus, type LockoutServiceOptions, } from './lockout.service.js';
+export { ApiKeyService, API_KEY_PREFIX, type ApiKeyServiceOptions, type CreateApiKeyInput, type CreatedApiKey, } from './api-key.service.js';
+export { PrincipalResolver, type PrincipalResolverOptions, type ResolveInput, } from './principal.resolver.js';
+export { Argon2PasswordHasher, ARGON2_PARAMETERS, assertPasswordPolicy, parseArgon2Parameters, type Argon2Parameters, type Argon2PasswordHasherOptions, } from './password.js';
+export { JoseTokenSigner, actorId, buildClaims, parseClaims, type AccessTokenInput, type JoseTokenSignerOptions, } from './jwt.js';
+export { AllowApiKey, AUTH_METADATA_KEYS, Permissions, Policy, Roles, isApiKeyAllowed, readAuthorizationRules, type AuthorizationRules, } from './decorators.js';
+export { PolicyRegistry, ownershipPolicy, type PolicyContext, type PolicyFunction, } from './policy.js';
+export { AuthGuard, type AuthGuardOptions } from './auth.guard.js';
+export { AuthorizationGuard, type AuthorizationGuardOptions } from './authorization.guard.js';
+export { AuthController } from './auth.controller.js';
+export { ForgotPasswordDto, ImpersonateDto, LoginDto, RefreshTokenDto, ResetPasswordDto, SendOtpDto, VerifyOtpDto, } from './auth.dto.js';
+export { MemoryApiKeyStore, MemoryAuthAuditSink, MemoryAuthUserStore, MemoryLockoutStore, MemoryOtpChannel, MemoryOtpStore, MemorySessionStore, } from './memory-stores.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * `@nage-api/auth` — authentication and authorization (PLAN.md §15).
+ *
+ * Opt-in and engine-agnostic: the package owns credentials, tokens, sessions
+ * and access decisions, and knows nothing about how they are stored. An
+ * application binds the ports in `NageAuthModule.forRoot` and gets a globally
+ * protected surface, with the legacy endpoint paths retained.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyOtpDto = exports.SendOtpDto = exports.ResetPasswordDto = exports.RefreshTokenDto = exports.LoginDto = exports.ImpersonateDto = exports.ForgotPasswordDto = exports.AuthController = exports.AuthorizationGuard = exports.AuthGuard = exports.ownershipPolicy = exports.PolicyRegistry = exports.readAuthorizationRules = exports.isApiKeyAllowed = exports.Roles = exports.Policy = exports.Permissions = exports.AUTH_METADATA_KEYS = exports.AllowApiKey = exports.parseClaims = exports.buildClaims = exports.actorId = exports.JoseTokenSigner = exports.parseArgon2Parameters = exports.assertPasswordPolicy = exports.ARGON2_PARAMETERS = exports.Argon2PasswordHasher = exports.PrincipalResolver = exports.API_KEY_PREFIX = exports.ApiKeyService = exports.LockoutService = exports.OtpService = exports.SessionService = exports.normaliseEmail = exports.AuthService = exports.NAGE_TOKEN_SIGNER = exports.NAGE_SESSION_STORE = exports.NAGE_PASSWORD_HASHER = exports.NAGE_OTP_STORE = exports.NAGE_OTP_CHANNEL = exports.NAGE_LOCKOUT_STORE = exports.NAGE_AUTH_USER_STORE = exports.NAGE_AUTH_CONFIG = exports.NAGE_AUTH_CLOCK = exports.NAGE_AUTH_AUDIT = exports.NAGE_API_KEY_STORE = exports.systemClock = exports.resolvePermissions = exports.resolveAuthConfig = exports.NageAuthModule = void 0;
+exports.MemorySessionStore = exports.MemoryOtpStore = exports.MemoryOtpChannel = exports.MemoryLockoutStore = exports.MemoryAuthUserStore = exports.MemoryAuthAuditSink = exports.MemoryApiKeyStore = void 0;
+// Composition.
+var auth_module_js_1 = require("./auth.module.js");
+Object.defineProperty(exports, "NageAuthModule", { enumerable: true, get: function () { return auth_module_js_1.NageAuthModule; } });
+// Configuration.
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "resolveAuthConfig", { enumerable: true, get: function () { return config_js_1.resolveAuthConfig; } });
+Object.defineProperty(exports, "resolvePermissions", { enumerable: true, get: function () { return config_js_1.resolvePermissions; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return ports_js_1.systemClock; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_API_KEY_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_API_KEY_STORE; } });
+Object.defineProperty(exports, "NAGE_AUTH_AUDIT", { enumerable: true, get: function () { return tokens_js_1.NAGE_AUTH_AUDIT; } });
+Object.defineProperty(exports, "NAGE_AUTH_CLOCK", { enumerable: true, get: function () { return tokens_js_1.NAGE_AUTH_CLOCK; } });
+Object.defineProperty(exports, "NAGE_AUTH_CONFIG", { enumerable: true, get: function () { return tokens_js_1.NAGE_AUTH_CONFIG; } });
+Object.defineProperty(exports, "NAGE_AUTH_USER_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_AUTH_USER_STORE; } });
+Object.defineProperty(exports, "NAGE_LOCKOUT_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_LOCKOUT_STORE; } });
+Object.defineProperty(exports, "NAGE_OTP_CHANNEL", { enumerable: true, get: function () { return tokens_js_1.NAGE_OTP_CHANNEL; } });
+Object.defineProperty(exports, "NAGE_OTP_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_OTP_STORE; } });
+Object.defineProperty(exports, "NAGE_PASSWORD_HASHER", { enumerable: true, get: function () { return tokens_js_1.NAGE_PASSWORD_HASHER; } });
+Object.defineProperty(exports, "NAGE_SESSION_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_SESSION_STORE; } });
+Object.defineProperty(exports, "NAGE_TOKEN_SIGNER", { enumerable: true, get: function () { return tokens_js_1.NAGE_TOKEN_SIGNER; } });
+// Services.
+var auth_service_js_1 = require("./auth.service.js");
+Object.defineProperty(exports, "AuthService", { enumerable: true, get: function () { return auth_service_js_1.AuthService; } });
+Object.defineProperty(exports, "normaliseEmail", { enumerable: true, get: function () { return auth_service_js_1.normaliseEmail; } });
+var session_service_js_1 = require("./session.service.js");
+Object.defineProperty(exports, "SessionService", { enumerable: true, get: function () { return session_service_js_1.SessionService; } });
+var otp_service_js_1 = require("./otp.service.js");
+Object.defineProperty(exports, "OtpService", { enumerable: true, get: function () { return otp_service_js_1.OtpService; } });
+var lockout_service_js_1 = require("./lockout.service.js");
+Object.defineProperty(exports, "LockoutService", { enumerable: true, get: function () { return lockout_service_js_1.LockoutService; } });
+var api_key_service_js_1 = require("./api-key.service.js");
+Object.defineProperty(exports, "ApiKeyService", { enumerable: true, get: function () { return api_key_service_js_1.ApiKeyService; } });
+Object.defineProperty(exports, "API_KEY_PREFIX", { enumerable: true, get: function () { return api_key_service_js_1.API_KEY_PREFIX; } });
+var principal_resolver_js_1 = require("./principal.resolver.js");
+Object.defineProperty(exports, "PrincipalResolver", { enumerable: true, get: function () { return principal_resolver_js_1.PrincipalResolver; } });
+// Credentials.
+var password_js_1 = require("./password.js");
+Object.defineProperty(exports, "Argon2PasswordHasher", { enumerable: true, get: function () { return password_js_1.Argon2PasswordHasher; } });
+Object.defineProperty(exports, "ARGON2_PARAMETERS", { enumerable: true, get: function () { return password_js_1.ARGON2_PARAMETERS; } });
+Object.defineProperty(exports, "assertPasswordPolicy", { enumerable: true, get: function () { return password_js_1.assertPasswordPolicy; } });
+Object.defineProperty(exports, "parseArgon2Parameters", { enumerable: true, get: function () { return password_js_1.parseArgon2Parameters; } });
+var jwt_js_1 = require("./jwt.js");
+Object.defineProperty(exports, "JoseTokenSigner", { enumerable: true, get: function () { return jwt_js_1.JoseTokenSigner; } });
+Object.defineProperty(exports, "actorId", { enumerable: true, get: function () { return jwt_js_1.actorId; } });
+Object.defineProperty(exports, "buildClaims", { enumerable: true, get: function () { return jwt_js_1.buildClaims; } });
+Object.defineProperty(exports, "parseClaims", { enumerable: true, get: function () { return jwt_js_1.parseClaims; } });
+// Authorization.
+var decorators_js_1 = require("./decorators.js");
+Object.defineProperty(exports, "AllowApiKey", { enumerable: true, get: function () { return decorators_js_1.AllowApiKey; } });
+Object.defineProperty(exports, "AUTH_METADATA_KEYS", { enumerable: true, get: function () { return decorators_js_1.AUTH_METADATA_KEYS; } });
+Object.defineProperty(exports, "Permissions", { enumerable: true, get: function () { return decorators_js_1.Permissions; } });
+Object.defineProperty(exports, "Policy", { enumerable: true, get: function () { return decorators_js_1.Policy; } });
+Object.defineProperty(exports, "Roles", { enumerable: true, get: function () { return decorators_js_1.Roles; } });
+Object.defineProperty(exports, "isApiKeyAllowed", { enumerable: true, get: function () { return decorators_js_1.isApiKeyAllowed; } });
+Object.defineProperty(exports, "readAuthorizationRules", { enumerable: true, get: function () { return decorators_js_1.readAuthorizationRules; } });
+var policy_js_1 = require("./policy.js");
+Object.defineProperty(exports, "PolicyRegistry", { enumerable: true, get: function () { return policy_js_1.PolicyRegistry; } });
+Object.defineProperty(exports, "ownershipPolicy", { enumerable: true, get: function () { return policy_js_1.ownershipPolicy; } });
+var auth_guard_js_1 = require("./auth.guard.js");
+Object.defineProperty(exports, "AuthGuard", { enumerable: true, get: function () { return auth_guard_js_1.AuthGuard; } });
+var authorization_guard_js_1 = require("./authorization.guard.js");
+Object.defineProperty(exports, "AuthorizationGuard", { enumerable: true, get: function () { return authorization_guard_js_1.AuthorizationGuard; } });
+// HTTP surface.
+var auth_controller_js_1 = require("./auth.controller.js");
+Object.defineProperty(exports, "AuthController", { enumerable: true, get: function () { return auth_controller_js_1.AuthController; } });
+var auth_dto_js_1 = require("./auth.dto.js");
+Object.defineProperty(exports, "ForgotPasswordDto", { enumerable: true, get: function () { return auth_dto_js_1.ForgotPasswordDto; } });
+Object.defineProperty(exports, "ImpersonateDto", { enumerable: true, get: function () { return auth_dto_js_1.ImpersonateDto; } });
+Object.defineProperty(exports, "LoginDto", { enumerable: true, get: function () { return auth_dto_js_1.LoginDto; } });
+Object.defineProperty(exports, "RefreshTokenDto", { enumerable: true, get: function () { return auth_dto_js_1.RefreshTokenDto; } });
+Object.defineProperty(exports, "ResetPasswordDto", { enumerable: true, get: function () { return auth_dto_js_1.ResetPasswordDto; } });
+Object.defineProperty(exports, "SendOtpDto", { enumerable: true, get: function () { return auth_dto_js_1.SendOtpDto; } });
+Object.defineProperty(exports, "VerifyOtpDto", { enumerable: true, get: function () { return auth_dto_js_1.VerifyOtpDto; } });
+// Reference implementations — real behaviour, usable as test doubles (§19).
+var memory_stores_js_1 = require("./memory-stores.js");
+Object.defineProperty(exports, "MemoryApiKeyStore", { enumerable: true, get: function () { return memory_stores_js_1.MemoryApiKeyStore; } });
+Object.defineProperty(exports, "MemoryAuthAuditSink", { enumerable: true, get: function () { return memory_stores_js_1.MemoryAuthAuditSink; } });
+Object.defineProperty(exports, "MemoryAuthUserStore", { enumerable: true, get: function () { return memory_stores_js_1.MemoryAuthUserStore; } });
+Object.defineProperty(exports, "MemoryLockoutStore", { enumerable: true, get: function () { return memory_stores_js_1.MemoryLockoutStore; } });
+Object.defineProperty(exports, "MemoryOtpChannel", { enumerable: true, get: function () { return memory_stores_js_1.MemoryOtpChannel; } });
+Object.defineProperty(exports, "MemoryOtpStore", { enumerable: true, get: function () { return memory_stores_js_1.MemoryOtpStore; } });
+Object.defineProperty(exports, "MemorySessionStore", { enumerable: true, get: function () { return memory_stores_js_1.MemorySessionStore; } });
+//# sourceMappingURL=index.js.map

package/dist/jwt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Access-token signing and verification (PLAN.md §12, §15.1).
+ *
+ * RS256 by default: verifiers hold only the public key, so a compromised API
+ * gateway or a downstream service cannot mint tokens. `jose` does the crypto;
+ * this file is about the parts that get security reviews wrong — that the
+ * algorithm is pinned rather than read from the token header, that issuer and
+ * audience are actually checked, and that a verification failure is mapped to a
+ * typed error instead of leaking a library message to the caller.
+ */
+import type { JwtClaims, Permission } from '@nage-api/contracts';
+import type { TokenSigner } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+export interface JoseTokenSignerOptions {
+    readonly config: ResolvedAuthConfig;
+    /** PEM private key, or the shared secret when the algorithm is HS256. */
+    readonly privateKey: string;
+    /** PEM public key. Omitted for HS256, where the secret verifies as well. */
+    readonly publicKey?: string;
+}
+export declare class JoseTokenSigner implements TokenSigner {
+    #private;
+    constructor(options: JoseTokenSignerOptions);
+    sign(claims: Record<string, unknown>, options: {
+        expiresInSeconds: number;
+    }): Promise<string>;
+    verify(token: string): Promise<Record<string, unknown>>;
+}
+/** Claims minted for an authenticated principal. */
+export interface AccessTokenInput {
+    readonly userId: string;
+    readonly sessionId: string;
+    readonly roles: readonly string[];
+    readonly permissions: readonly Permission[];
+    readonly tenantId?: string;
+    readonly impersonatedBy?: string;
+}
+/** The claim set, kept in one place so signing and parsing cannot disagree. */
+export declare function buildClaims(input: AccessTokenInput): Record<string, unknown>;
+/**
+ * Read a verified payload back into typed claims.
+ *
+ * The payload is verified but still **untrusted in shape**: a token minted by
+ * an older version of this service, or by a deliberately odd one, can carry a
+ * `roles` that is not an array. Anything malformed is dropped rather than cast.
+ */
+export declare function parseClaims(payload: Record<string, unknown>): JwtClaims;
+/** The impersonator's id, when the token carries an `act` claim (RFC 8693). */
+export declare function actorId(payload: Record<string, unknown>): string | undefined;
+//# sourceMappingURL=jwt.d.ts.map