@nage-api/auth 1.0.0-beta.2

package/dist/otp.service.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * One-time codes (PLAN.md §12, §15.1).
+ *
+ * Codes are drawn from the CSPRNG (`randomOtp`, which rejects and re-draws
+ * rather than folding a range, so no digit is more likely than another), stored
+ * as an HMAC, compared in constant time, and consumed on first correct use.
+ *
+ * Three limits make a six-digit code defensible: a short TTL, a per-code
+ * attempt ceiling, and a resend cooldown. Without the cooldown, an attacker
+ * requests a fresh code every time the attempt counter runs out and the
+ * ceiling stops mattering.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtpService = void 0;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@nage-api/core");
+const MIN_PEPPER_LENGTH = 16;
+class OtpService {
+    #store;
+    #channel;
+    #config;
+    #pepper;
+    #clock;
+    #audit;
+    constructor(options) {
+        if (options.pepper.length < MIN_PEPPER_LENGTH) {
+            throw new core_1.ConfigurationError({
+                detail: `The OTP pepper must be at least ${String(MIN_PEPPER_LENGTH)} characters`,
+                meta: { setting: 'OTP_PEPPER' },
+            });
+        }
+        this.#store = options.store;
+        this.#channel = options.channel;
+        this.#config = options.config;
+        this.#pepper = options.pepper;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#audit = options.audit;
+    }
+    /**
+     * Issue a code and hand it to the channel.
+     *
+     * Returns `issued: false` while the cooldown is in force rather than
+     * throwing: the caller replies the same way either way, because telling an
+     * unauthenticated client "you already have a code" confirms the account
+     * exists.
+     */
+    async issue(subject, purpose) {
+        const now = this.#clock.now();
+        const active = await this.#store.findActive(subject, purpose);
+        if (active !== undefined) {
+            const elapsed = now - active.issuedAt;
+            const cooldown = this.#config.resendCooldownSeconds * 1000;
+            if (elapsed < cooldown) {
+                return { issued: false, retryAfterSeconds: Math.ceil((cooldown - elapsed) / 1000) };
+            }
+        }
+        // Only one code may be live per subject and purpose; leaving the old one
+        // valid would double the guessing surface for every resend.
+        await this.#store.invalidate(subject, purpose);
+        const code = (0, core_1.randomOtp)(this.#config.length);
+        const record = {
+            id: (0, core_1.randomId)(),
+            subject,
+            purpose,
+            hashedCode: this.#hash(subject, purpose, code),
+            issuedAt: now,
+            expiresAt: now + this.#config.ttlSeconds * 1000,
+            attempts: 0,
+        };
+        await this.#store.create(record);
+        await this.#channel.send({ subject, code, purpose });
+        await this.#audit?.record({ name: 'otp.sent', at: now, meta: { purpose } });
+        return { issued: true };
+    }
+    /**
+     * Verify and consume a code.
+     *
+     * @throws AuthenticationError `AUTH_OTP_INVALID` or `AUTH_OTP_EXPIRED`
+     */
+    async verify(subject, purpose, code) {
+        const now = this.#clock.now();
+        const record = await this.#store.findActive(subject, purpose);
+        if (record === undefined) {
+            await this.#audit?.record({
+                name: 'otp.failed',
+                at: now,
+                meta: { purpose, reason: 'no-code' },
+            });
+            throw new core_1.AuthenticationError('AUTH_OTP_INVALID', {
+                detail: `No active ${purpose} code for this subject`,
+            });
+        }
+        if (record.expiresAt <= now) {
+            await this.#store.consume(record.id, now);
+            throw new core_1.AuthenticationError('AUTH_OTP_EXPIRED', {
+                detail: `The ${purpose} code expired at ${new Date(record.expiresAt).toISOString()}`,
+            });
+        }
+        if (record.attempts >= this.#config.maxAttempts) {
+            // Burn it: an exhausted code must not become guessable again by waiting.
+            await this.#store.consume(record.id, now);
+            await this.#audit?.record({
+                name: 'otp.failed',
+                at: now,
+                meta: { purpose, reason: 'attempts-exhausted' },
+            });
+            throw new core_1.AuthenticationError('AUTH_OTP_INVALID', {
+                detail: `The ${purpose} code was tried ${String(record.attempts)} times and is now void`,
+            });
+        }
+        if (!(0, core_1.secureCompare)(record.hashedCode, this.#hash(subject, purpose, code))) {
+            await this.#store.recordAttempt(record.id, record.attempts + 1);
+            await this.#audit?.record({
+                name: 'otp.failed',
+                at: now,
+                meta: { purpose, reason: 'mismatch' },
+            });
+            throw new core_1.AuthenticationError('AUTH_OTP_INVALID', {
+                detail: `Incorrect ${purpose} code (attempt ${String(record.attempts + 1)})`,
+            });
+        }
+        await this.#store.consume(record.id, now);
+    }
+    /**
+     * The subject and purpose are bound into the HMAC, so a code issued for a
+     * password reset cannot be presented as a login code, and a code for one
+     * mailbox cannot be replayed against another.
+     */
+    #hash(subject, purpose, code) {
+        return (0, node_crypto_1.createHmac)('sha256', this.#pepper)
+            .update(`${purpose}:${subject}:${code}`, 'utf8')
+            .digest('base64url');
+    }
+}
+exports.OtpService = OtpService;
+//# sourceMappingURL=otp.service.js.map

package/dist/password.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Password hashing and policy (PLAN.md §12, §15.1).
+ *
+ * argon2id with the OWASP-recommended parameters (19 MiB, t=2, p=1), plus a
+ * **pepper**: the password is HMAC'd with a secret held outside the database
+ * before it is hashed. A dumped user table is then useless on its own, because
+ * the attacker is missing a key that never lived in it.
+ *
+ * The pepper is applied by HMAC rather than concatenation so that a password
+ * longer than the hash block size cannot dilute it, and so rotating to a second
+ * pepper is a matter of re-HMAC'ing at next login rather than a schema change.
+ */
+import type { PasswordHasher } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+/** OWASP's second-choice argon2id profile: 19 MiB, two passes, one lane. */
+export declare const ARGON2_PARAMETERS: {
+    readonly memoryCost: 19456;
+    readonly timeCost: 2;
+    readonly parallelism: 1;
+};
+export interface Argon2PasswordHasherOptions {
+    /** Secret held outside the database. Required — a missing one is a config bug. */
+    readonly pepper: string;
+    readonly memoryCost?: number;
+    readonly timeCost?: number;
+    readonly parallelism?: number;
+}
+export declare class Argon2PasswordHasher implements PasswordHasher {
+    #private;
+    constructor(options: Argon2PasswordHasherOptions);
+    hash(password: string): Promise<string>;
+    verify(hashed: string, password: string): Promise<boolean>;
+    needsRehash(hashed: string): boolean;
+}
+export interface Argon2Parameters {
+    readonly algorithm: string;
+    readonly memoryCost: number;
+    readonly timeCost: number;
+    readonly parallelism: number;
+}
+/** Read the cost parameters back out of an encoded hash. */
+export declare function parseArgon2Parameters(hashed: string): Argon2Parameters | undefined;
+/**
+ * Check a candidate password against the configured policy.
+ *
+ * Reported as field-level validation details rather than one opaque failure —
+ * "must contain a number" is actionable; "password is invalid" makes people
+ * pick `Password1!` and move on.
+ */
+export declare function assertPasswordPolicy(password: string, policy: ResolvedAuthConfig['password'], field?: string): void;
+//# sourceMappingURL=password.d.ts.map

package/dist/password.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Password hashing and policy (PLAN.md §12, §15.1).
+ *
+ * argon2id with the OWASP-recommended parameters (19 MiB, t=2, p=1), plus a
+ * **pepper**: the password is HMAC'd with a secret held outside the database
+ * before it is hashed. A dumped user table is then useless on its own, because
+ * the attacker is missing a key that never lived in it.
+ *
+ * The pepper is applied by HMAC rather than concatenation so that a password
+ * longer than the hash block size cannot dilute it, and so rotating to a second
+ * pepper is a matter of re-HMAC'ing at next login rather than a schema change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Argon2PasswordHasher = exports.ARGON2_PARAMETERS = void 0;
+exports.parseArgon2Parameters = parseArgon2Parameters;
+exports.assertPasswordPolicy = assertPasswordPolicy;
+const node_crypto_1 = require("node:crypto");
+const argon2_1 = require("@node-rs/argon2");
+const core_1 = require("@nage-api/core");
+/**
+ * `Algorithm.Argon2id` from `@node-rs/argon2` is an ambient `const enum`, which
+ * `isolatedModules` cannot read across a module boundary. The numeric value is
+ * part of the library's published API, so it is spelled out here rather than
+ * relaxing a compiler flag for the whole package.
+ */
+const ARGON2ID = 2;
+/** OWASP's second-choice argon2id profile: 19 MiB, two passes, one lane. */
+exports.ARGON2_PARAMETERS = {
+    memoryCost: 19_456,
+    timeCost: 2,
+    parallelism: 1,
+};
+/** Anything shorter than this cannot carry enough entropy to be a pepper. */
+const MIN_PEPPER_LENGTH = 16;
+class Argon2PasswordHasher {
+    #pepper;
+    #memoryCost;
+    #timeCost;
+    #parallelism;
+    constructor(options) {
+        if (options.pepper.length < MIN_PEPPER_LENGTH) {
+            throw new core_1.ConfigurationError({
+                detail: `The password pepper must be at least ${String(MIN_PEPPER_LENGTH)} characters; it is the secret that makes a stolen user table useless`,
+                meta: { setting: 'PASSWORD_PEPPER', length: options.pepper.length },
+            });
+        }
+        this.#pepper = options.pepper;
+        this.#memoryCost = options.memoryCost ?? exports.ARGON2_PARAMETERS.memoryCost;
+        this.#timeCost = options.timeCost ?? exports.ARGON2_PARAMETERS.timeCost;
+        this.#parallelism = options.parallelism ?? exports.ARGON2_PARAMETERS.parallelism;
+    }
+    async hash(password) {
+        return (0, argon2_1.hash)(this.#peppered(password), {
+            algorithm: ARGON2ID,
+            memoryCost: this.#memoryCost,
+            timeCost: this.#timeCost,
+            parallelism: this.#parallelism,
+        });
+    }
+    async verify(hashed, password) {
+        try {
+            return await (0, argon2_1.verify)(hashed, this.#peppered(password));
+        }
+        catch {
+            // A malformed or foreign hash is a failed verification, not a 500: it is
+            // what a row written by another system looks like.
+            return false;
+        }
+    }
+    needsRehash(hashed) {
+        const parameters = parseArgon2Parameters(hashed);
+        if (parameters === undefined)
+            return true;
+        return (parameters.algorithm !== 'argon2id' ||
+            parameters.memoryCost < this.#memoryCost ||
+            parameters.timeCost < this.#timeCost);
+    }
+    #peppered(password) {
+        return (0, node_crypto_1.createHmac)('sha256', this.#pepper).update(password, 'utf8').digest('base64');
+    }
+}
+exports.Argon2PasswordHasher = Argon2PasswordHasher;
+/** Read the cost parameters back out of an encoded hash. */
+function parseArgon2Parameters(hashed) {
+    const match = /^\$(argon2(?:id|i|d))\$v=\d+\$m=(\d+),t=(\d+),p=(\d+)\$/.exec(hashed);
+    if (match === null)
+        return undefined;
+    return {
+        algorithm: match[1] ?? '',
+        memoryCost: Number(match[2]),
+        timeCost: Number(match[3]),
+        parallelism: Number(match[4]),
+    };
+}
+/**
+ * Check a candidate password against the configured policy.
+ *
+ * Reported as field-level validation details rather than one opaque failure —
+ * "must contain a number" is actionable; "password is invalid" makes people
+ * pick `Password1!` and move on.
+ */
+function assertPasswordPolicy(password, policy, field = 'password') {
+    const failures = {};
+    if (password.length < policy.minLength) {
+        failures['minLength'] = `Must be at least ${String(policy.minLength)} characters.`;
+    }
+    if (policy.requireMixedCase && !(/[a-z]/.test(password) && /[A-Z]/.test(password))) {
+        failures['mixedCase'] = 'Must contain both upper and lower case letters.';
+    }
+    if (policy.requireNumber && !/\d/.test(password)) {
+        failures['number'] = 'Must contain a number.';
+    }
+    if (policy.requireSymbol && !/[^\p{L}\p{N}]/u.test(password)) {
+        failures['symbol'] = 'Must contain a symbol.';
+    }
+    if (Object.keys(failures).length > 0) {
+        const details = [{ field, constraints: failures }];
+        throw new core_1.ValidationError({ message: 'The password does not meet the policy.', details });
+    }
+}
+//# sourceMappingURL=password.js.map

package/dist/policy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Policies — the opt-in ABAC layer over RBAC (PLAN.md §15.2).
+ *
+ * RBAC answers "may an editor publish?"; a policy answers "may *this* editor
+ * publish *this* article?". Rather than pulling in a rules engine, a policy is
+ * a named function of the principal and the request, registered at module
+ * setup. That keeps the decision auditable — every policy has a name that
+ * appears in the denial's log line — and typed.
+ */
+import type { AuthUser } from '@nage-api/contracts';
+import type { PolicyDecision } from '@nage-api/contracts';
+/** What a policy is given. Deliberately not the raw Nest request object. */
+export interface PolicyContext {
+    readonly user: AuthUser;
+    readonly method: string;
+    readonly path: string;
+    readonly params: Readonly<Record<string, string>>;
+    readonly query: Readonly<Record<string, unknown>>;
+    readonly body: unknown;
+}
+export type PolicyFunction = (context: PolicyContext) => PolicyDecision | Promise<PolicyDecision>;
+/**
+ * The registered policies.
+ *
+ * An unknown policy name **denies**. A typo in `@Policy('article:pubish')`
+ * must not open a route; failing closed is the only safe reading of "I could
+ * not find the rule".
+ */
+export declare class PolicyRegistry {
+    #private;
+    constructor(policies?: Readonly<Record<string, PolicyFunction>>);
+    register(name: string, policy: PolicyFunction): this;
+    has(name: string): boolean;
+    evaluate(name: string, context: PolicyContext): Promise<PolicyDecision>;
+}
+/**
+ * A policy that allows a request only when the principal owns the resource.
+ *
+ * The retained ownership-scoping pattern from `docs/service.md`, expressed as a
+ * first-class helper: `ownershipPolicy('id')` compares the route parameter with
+ * the caller's own id.
+ */
+export declare function ownershipPolicy(parameter?: string): PolicyFunction;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Policies — the opt-in ABAC layer over RBAC (PLAN.md §15.2).
+ *
+ * RBAC answers "may an editor publish?"; a policy answers "may *this* editor
+ * publish *this* article?". Rather than pulling in a rules engine, a policy is
+ * a named function of the principal and the request, registered at module
+ * setup. That keeps the decision auditable — every policy has a name that
+ * appears in the denial's log line — and typed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyRegistry = void 0;
+exports.ownershipPolicy = ownershipPolicy;
+/**
+ * The registered policies.
+ *
+ * An unknown policy name **denies**. A typo in `@Policy('article:pubish')`
+ * must not open a route; failing closed is the only safe reading of "I could
+ * not find the rule".
+ */
+class PolicyRegistry {
+    #policies = new Map();
+    constructor(policies = {}) {
+        for (const [name, policy] of Object.entries(policies))
+            this.register(name, policy);
+    }
+    register(name, policy) {
+        this.#policies.set(name, policy);
+        return this;
+    }
+    has(name) {
+        return this.#policies.has(name);
+    }
+    async evaluate(name, context) {
+        const policy = this.#policies.get(name);
+        if (policy === undefined) {
+            return { allowed: false, reason: `No policy named "${name}" is registered` };
+        }
+        return policy(context);
+    }
+}
+exports.PolicyRegistry = PolicyRegistry;
+/**
+ * A policy that allows a request only when the principal owns the resource.
+ *
+ * The retained ownership-scoping pattern from `docs/service.md`, expressed as a
+ * first-class helper: `ownershipPolicy('id')` compares the route parameter with
+ * the caller's own id.
+ */
+function ownershipPolicy(parameter = 'id') {
+    return ({ user, params }) => {
+        const target = params[parameter];
+        if (target === undefined) {
+            return { allowed: false, reason: `Route has no :${parameter} to check ownership against` };
+        }
+        return target === String(user.id)
+            ? { allowed: true }
+            : { allowed: false, reason: 'The resource belongs to another user' };
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/ports.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The ports `@nage-api/auth` needs and does not implement (PLAN.md §15.1).
+ *
+ * A feature package may not import another feature package (§7.2), so auth
+ * cannot reach for `@nage-api/data` to persist sessions. Instead it declares the
+ * narrow stores it needs; a generated app binds them to its own driver in one
+ * `forRoot` call, and the in-memory reference implementations in this package
+ * make that binding testable before any database exists.
+ *
+ * Every port is deliberately small: a store that only knows how to find, insert
+ * and revoke cannot be the place a subtle authorization bug hides.
+ */
+import type { AuthUser, Id, Permission, RoleName, SessionRecord } from '@nage-api/contracts';
+/** What the framework needs to know about a user in order to authenticate one. */
+export interface AuthUserRecord<TRole extends string = RoleName> {
+    readonly id: Id;
+    readonly email: string;
+    /** Encoded hash, including its parameters. Never a plaintext password. */
+    readonly passwordHash?: string;
+    readonly roles: readonly TRole[];
+    /** Granted directly, on top of whatever the roles imply. */
+    readonly permissions?: readonly Permission[];
+    /** A disabled account authenticates as nobody, whatever its credentials. */
+    readonly disabled?: boolean;
+    readonly tenantId?: Id;
+}
+/**
+ * Lookup of the principal. Read-only except for the password, because auth owns
+ * credentials and the application owns everything else about a user.
+ */
+export interface AuthUserStore<TRole extends string = RoleName> {
+    findById(id: Id): Promise<AuthUserRecord<TRole> | undefined>;
+    /** Case-insensitive by convention; the caller normalises before storing. */
+    findByEmail(email: string): Promise<AuthUserRecord<TRole> | undefined>;
+    setPasswordHash(id: Id, hash: string): Promise<void>;
+}
+/**
+ * Refresh-session persistence.
+ *
+ * Sessions are looked up **by token hash**, never by a client-supplied id: the
+ * hash is the only thing that proves possession, and a lookup by id would let a
+ * caller name a session they do not hold.
+ */
+export interface SessionStore {
+    create(session: SessionRecord): Promise<void>;
+    findByHashedToken(hashedToken: string): Promise<SessionRecord | undefined>;
+    /** Mark a session rotated and point at its successor. */
+    markRotated(id: string, rotatedAt: number): Promise<void>;
+    revoke(id: string, revokedAt: number): Promise<void>;
+    /** Revoke every session in a family — the reuse-detection response. */
+    revokeFamily(familyId: string, revokedAt: number): Promise<number>;
+    /**
+     * Whether a family has been revoked.
+     *
+     * The access token carries the **family** id, so this is what makes a logout
+     * take effect immediately instead of at the end of the access token's life.
+     */
+    isFamilyRevoked(familyId: string): Promise<boolean>;
+    /** Revoke everything a user holds, e.g. after a password reset. */
+    revokeAllForUser(userId: Id, revokedAt: number): Promise<number>;
+    /** Housekeeping; expired rows are useless and grow forever without it. */
+    deleteExpired(now: number): Promise<number>;
+}
+/** A one-time code, stored hashed and consumed on first correct use. */
+export interface OtpRecord {
+    readonly id: string;
+    readonly subject: string;
+    readonly purpose: OtpPurpose;
+    readonly hashedCode: string;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly attempts: number;
+    readonly consumedAt?: number;
+}
+export type OtpPurpose = 'login' | 'password-reset' | 'verify-contact';
+export interface OtpStore {
+    create(record: OtpRecord): Promise<void>;
+    /** The newest unconsumed code for this subject and purpose. */
+    findActive(subject: string, purpose: OtpPurpose): Promise<OtpRecord | undefined>;
+    recordAttempt(id: string, attempts: number): Promise<void>;
+    consume(id: string, consumedAt: number): Promise<void>;
+    /** Invalidate outstanding codes when a new one is issued. */
+    invalidate(subject: string, purpose: OtpPurpose): Promise<number>;
+}
+/** A hashed, scoped machine credential (PLAN.md §15.1). */
+export interface ApiKeyRecord {
+    readonly id: string;
+    /** Public, non-secret prefix used to find the row before verifying it. */
+    readonly prefix: string;
+    readonly hashedKey: string;
+    readonly name: string;
+    /** Acts as this user; a key with no user is a service principal. */
+    readonly userId?: Id;
+    readonly roles: readonly string[];
+    readonly permissions: readonly Permission[];
+    readonly createdAt: number;
+    readonly expiresAt?: number;
+    readonly revokedAt?: number;
+    readonly lastUsedAt?: number;
+}
+export interface ApiKeyStore {
+    create(record: ApiKeyRecord): Promise<void>;
+    findByPrefix(prefix: string): Promise<ApiKeyRecord | undefined>;
+    touch(id: string, usedAt: number): Promise<void>;
+    revoke(id: string, revokedAt: number): Promise<void>;
+}
+/** Failed-attempt counting behind login and OTP lockout. */
+export interface LockoutRecord {
+    readonly key: string;
+    readonly failures: number;
+    readonly firstFailureAt: number;
+    readonly lockedUntil?: number;
+}
+export interface LockoutStore {
+    get(key: string): Promise<LockoutRecord | undefined>;
+    set(record: LockoutRecord): Promise<void>;
+    clear(key: string): Promise<void>;
+}
+/**
+ * Where OTPs actually go.
+ *
+ * Auth generates and verifies codes; it does not know how to send an email.
+ * `@nage-api/notify` binds this in Phase 8; until then an application supplies its
+ * own, and the in-memory one makes the flow testable.
+ */
+export interface OtpChannel {
+    send(input: {
+        subject: string;
+        code: string;
+        purpose: OtpPurpose;
+    }): Promise<void>;
+}
+/** Password hashing, so the algorithm is a swap rather than a rewrite. */
+export interface PasswordHasher {
+    hash(password: string): Promise<string>;
+    /** Constant-time by contract; implementations must not short-circuit. */
+    verify(hash: string, password: string): Promise<boolean>;
+    /** True when the stored hash used weaker parameters than the current policy. */
+    needsRehash(hash: string): boolean;
+}
+/** Signing and verification of access tokens. */
+export interface TokenSigner {
+    sign(claims: Record<string, unknown>, options: {
+        expiresInSeconds: number;
+    }): Promise<string>;
+    /** Rejects on expiry, bad signature, wrong issuer or wrong audience. */
+    verify(token: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Auth events worth keeping (PLAN.md §15.1).
+ *
+ * A sink rather than a logger call: a login failure is a security event that
+ * many deployments route to a SIEM, and it should not be discoverable only by
+ * grepping stdout.
+ */
+export type AuthEventName = 'login.succeeded' | 'login.failed' | 'login.locked' | 'token.refreshed' | 'token.reuse-detected' | 'session.revoked' | 'password.reset' | 'otp.sent' | 'otp.failed' | 'api-key.used' | 'impersonation.started';
+export interface AuthEvent {
+    readonly name: AuthEventName;
+    readonly at: number;
+    readonly userId?: Id;
+    readonly sessionId?: string;
+    /** Never contains a credential, a token or a code. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+export interface AuthAuditSink {
+    record(event: AuthEvent): void | Promise<void>;
+}
+/** Injected so token expiry and lockout windows are testable without waiting. */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+/** Resolved principal, as the guards put it into the request context. */
+export type ResolvedPrincipal<TRole extends string = RoleName> = AuthUser<TRole>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The ports `@nage-api/auth` needs and does not implement (PLAN.md §15.1).
+ *
+ * A feature package may not import another feature package (§7.2), so auth
+ * cannot reach for `@nage-api/data` to persist sessions. Instead it declares the
+ * narrow stores it needs; a generated app binds them to its own driver in one
+ * `forRoot` call, and the in-memory reference implementations in this package
+ * make that binding testable before any database exists.
+ *
+ * Every port is deliberately small: a store that only knows how to find, insert
+ * and revoke cannot be the place a subtle authorization bug hides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.systemClock = { now: () => Date.now() };
+//# sourceMappingURL=ports.js.map

package/dist/principal.resolver.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Turning a verified token into the principal the request runs as
+ * (PLAN.md §15.1).
+ *
+ * Two decisions worth stating, because both are places auth packages commonly
+ * go wrong:
+ *
+ * **Roles come from the store, not from the token.** A signed token proves who
+ * the caller is; it does not prove what they may still do. Trusting its `roles`
+ * claim means a demotion or a disabled account keeps working until the token
+ * expires. Claims are carried for observability and compared, not obeyed.
+ *
+ * **A revoked session stops working at once.** The token carries the session
+ * *family* id, and a revoked family is refused — so logging out actually logs
+ * you out, rather than leaving a 15-minute window in which the access token
+ * still works.
+ *
+ * Both cost a lookup per request, so both are memoised behind a short TTL. The
+ * TTL is the tunable: a few seconds of staleness in exchange for not hitting
+ * the database on every call.
+ */
+import type { AuthUser, Permission, RoleMatrix } from '@nage-api/contracts';
+import type { AuthUserStore, Clock, SessionStore } from './ports.js';
+export interface PrincipalResolverOptions {
+    readonly users: AuthUserStore;
+    readonly sessions: SessionStore;
+    readonly roles: RoleMatrix;
+    /** How long a resolved principal may be reused. 0 disables caching. */
+    readonly cacheTtlMs?: number;
+    /** Bound on the cache, so a token flood cannot grow it without limit. */
+    readonly cacheMaxEntries?: number;
+    readonly clock?: Clock;
+}
+export interface ResolveInput {
+    readonly userId: string;
+    /** Session family id, taken from the token's `sid` claim. */
+    readonly sessionId: string;
+    readonly claimedRoles: readonly string[];
+    readonly claimedPermissions: readonly Permission[];
+    readonly tenantId?: string;
+    readonly impersonatedBy?: string;
+}
+export declare class PrincipalResolver {
+    #private;
+    constructor(options: PrincipalResolverOptions);
+    resolve(input: ResolveInput): Promise<AuthUser>;
+    /** Drop a user's cached record — call after a role or status change. */
+    invalidate(userId: string): void;
+    /** Drop everything; used by tests and by an administrative refresh. */
+    clear(): void;
+}
+//# sourceMappingURL=principal.resolver.d.ts.map