@nage-api/auth 1.0.0-beta.2

package/dist/principal.resolver.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalResolver = void 0;
+const core_1 = require("@nage-api/core");
+const config_js_1 = require("./config.js");
+const DEFAULT_CACHE_TTL_MS = 5_000;
+const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
+class PrincipalResolver {
+    #users;
+    #sessions;
+    #roles;
+    #cacheTtlMs;
+    #cacheMaxEntries;
+    #clock;
+    #cache = new Map();
+    #revoked = new Map();
+    constructor(options) {
+        this.#users = options.users;
+        this.#sessions = options.sessions;
+        this.#roles = options.roles;
+        this.#cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.#cacheMaxEntries = options.cacheMaxEntries ?? DEFAULT_CACHE_MAX_ENTRIES;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+    }
+    async resolve(input) {
+        if (await this.#isRevoked(input.sessionId)) {
+            throw new core_1.AuthenticationError('AUTH_SESSION_REVOKED', {
+                detail: `Session family ${input.sessionId} was revoked`,
+                meta: { sessionId: input.sessionId },
+            });
+        }
+        const record = await this.#load(input.userId);
+        if (record === undefined) {
+            // The token is valid but the account is gone. `AUTH_TOKEN_INVALID` rather
+            // than a 404: whether a user id exists is not a caller's business.
+            throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+                detail: `Token subject ${input.userId} does not resolve to a user`,
+            });
+        }
+        if (record.disabled === true) {
+            throw new core_1.AuthenticationError('AUTH_SESSION_REVOKED', {
+                detail: `User ${input.userId} is disabled`,
+            });
+        }
+        return {
+            id: record.id,
+            ...(record.email === '' ? {} : { email: record.email }),
+            roles: record.roles,
+            permissions: (0, config_js_1.resolvePermissions)(this.#roles, record.roles, record.permissions ?? []),
+            sessionId: input.sessionId,
+            ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+            ...(input.impersonatedBy === undefined ? {} : { impersonatedBy: input.impersonatedBy }),
+        };
+    }
+    /** Drop a user's cached record — call after a role or status change. */
+    invalidate(userId) {
+        this.#cache.delete(userId);
+    }
+    /** Drop everything; used by tests and by an administrative refresh. */
+    clear() {
+        this.#cache.clear();
+        this.#revoked.clear();
+    }
+    async #load(userId) {
+        const now = this.#clock.now();
+        if (this.#cacheTtlMs > 0) {
+            const cached = this.#cache.get(userId);
+            if (cached !== undefined && cached.expiresAt > now)
+                return cached.record;
+        }
+        const record = await this.#users.findById(userId);
+        if (record !== undefined && this.#cacheTtlMs > 0) {
+            this.#evictIfFull();
+            this.#cache.set(userId, { record, expiresAt: now + this.#cacheTtlMs });
+        }
+        return record;
+    }
+    async #isRevoked(sessionId) {
+        const now = this.#clock.now();
+        // Only negative answers are cached, and only briefly. A revocation caches
+        // permanently for this process because a family is never un-revoked.
+        const known = this.#revoked.get(sessionId);
+        if (known === Number.POSITIVE_INFINITY)
+            return true;
+        if (known !== undefined && known > now)
+            return false;
+        // An API-key principal has no session family to revoke.
+        if (sessionId.startsWith('api-key:'))
+            return false;
+        const revoked = await this.#sessions.isFamilyRevoked(sessionId);
+        this.#revoked.set(sessionId, revoked ? Number.POSITIVE_INFINITY : now + this.#cacheTtlMs);
+        return revoked;
+    }
+    #evictIfFull() {
+        if (this.#cache.size < this.#cacheMaxEntries)
+            return;
+        // Map preserves insertion order, so the first key is the oldest write.
+        const oldest = this.#cache.keys().next();
+        if (!oldest.done)
+            this.#cache.delete(oldest.value);
+    }
+}
+exports.PrincipalResolver = PrincipalResolver;
+//# sourceMappingURL=principal.resolver.js.map

package/dist/session.service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Refresh sessions: issue, rotate, detect reuse, revoke (PLAN.md §12, §15.1).
+ *
+ * The refresh token is opaque and high-entropy (32 CSPRNG bytes), so it is
+ * stored as an HMAC rather than an argon2 hash — stretching adds nothing to a
+ * 256-bit random value, and a lookup by HMAC is a single indexed read instead
+ * of a table scan of candidate hashes.
+ *
+ * Rotation and reuse detection are the point of the design:
+ *
+ *   1. every refresh issues a new token and marks the old one rotated;
+ *   2. a rotated or revoked token coming back means someone replayed a token
+ *      the legitimate client already spent — either the client or the attacker,
+ *      and there is no way to tell which;
+ *   3. so the entire **family** is revoked, which logs both out and turns a
+ *      silent theft into a visible re-login.
+ */
+import type { Id, SessionRecord } from '@nage-api/contracts';
+import type { AuthAuditSink, Clock, SessionStore } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+export interface SessionServiceOptions {
+    readonly store: SessionStore;
+    readonly config: ResolvedAuthConfig;
+    /** Secret that makes a stolen session table unusable for replay. */
+    readonly pepper: string;
+    readonly clock?: Clock;
+    readonly audit?: AuthAuditSink;
+}
+export interface IssuedSession {
+    readonly session: SessionRecord;
+    /** The only moment the plaintext token exists; it is never stored. */
+    readonly refreshToken: string;
+}
+export interface SessionContext {
+    readonly userAgent?: string;
+    readonly ip?: string;
+}
+export declare class SessionService {
+    #private;
+    constructor(options: SessionServiceOptions);
+    /** Start a new session family — one login, one family. */
+    issue(userId: Id, context?: SessionContext): Promise<IssuedSession>;
+    /**
+     * Exchange a refresh token for a new one.
+     *
+     * @throws AuthenticationError `AUTH_TOKEN_REUSED` when the token was already
+     * rotated or revoked — after revoking the whole family.
+     */
+    rotate(refreshToken: string, context?: SessionContext): Promise<IssuedSession>;
+    /** Look up a live session, or `undefined` if it is spent, revoked or expired. */
+    findLive(refreshToken: string): Promise<SessionRecord | undefined>;
+    /**
+     * Log out.
+     *
+     * Revokes the whole family, not just the presented token: a logout that left
+     * the previous, already-rotated sibling usable would not be a logout.
+     */
+    revoke(refreshToken: string): Promise<boolean>;
+    /** Revoke every session a user holds — after a password reset, say. */
+    revokeAllForUser(userId: Id, reason: string): Promise<number>;
+    /** Drop expired rows; wire to a schedule in a long-running deployment. */
+    prune(): Promise<number>;
+    /**
+     * HMAC-SHA256 of the token under the session pepper.
+     *
+     * Public because a store implementation may need it to migrate existing rows,
+     * and because the tests assert that no plaintext token is ever persisted.
+     */
+    hashToken(refreshToken: string): string;
+}
+//# sourceMappingURL=session.service.d.ts.map

package/dist/session.service.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Refresh sessions: issue, rotate, detect reuse, revoke (PLAN.md §12, §15.1).
+ *
+ * The refresh token is opaque and high-entropy (32 CSPRNG bytes), so it is
+ * stored as an HMAC rather than an argon2 hash — stretching adds nothing to a
+ * 256-bit random value, and a lookup by HMAC is a single indexed read instead
+ * of a table scan of candidate hashes.
+ *
+ * Rotation and reuse detection are the point of the design:
+ *
+ *   1. every refresh issues a new token and marks the old one rotated;
+ *   2. a rotated or revoked token coming back means someone replayed a token
+ *      the legitimate client already spent — either the client or the attacker,
+ *      and there is no way to tell which;
+ *   3. so the entire **family** is revoked, which logs both out and turns a
+ *      silent theft into a visible re-login.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionService = void 0;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@nage-api/core");
+const MIN_PEPPER_LENGTH = 16;
+class SessionService {
+    #store;
+    #config;
+    #pepper;
+    #clock;
+    #audit;
+    constructor(options) {
+        if (options.pepper.length < MIN_PEPPER_LENGTH) {
+            throw new core_1.ConfigurationError({
+                detail: `The session pepper must be at least ${String(MIN_PEPPER_LENGTH)} characters`,
+                meta: { setting: 'SESSION_PEPPER', length: options.pepper.length },
+            });
+        }
+        this.#store = options.store;
+        this.#config = options.config;
+        this.#pepper = options.pepper;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        this.#audit = options.audit;
+    }
+    /** Start a new session family — one login, one family. */
+    async issue(userId, context = {}) {
+        return this.#create(userId, (0, core_1.randomId)(), context);
+    }
+    /**
+     * Exchange a refresh token for a new one.
+     *
+     * @throws AuthenticationError `AUTH_TOKEN_REUSED` when the token was already
+     * rotated or revoked — after revoking the whole family.
+     */
+    async rotate(refreshToken, context = {}) {
+        const now = this.#clock.now();
+        const session = await this.#store.findByHashedToken(this.hashToken(refreshToken));
+        if (session === undefined) {
+            // Indistinguishable from a random string: the client learns nothing about
+            // whether the token ever existed.
+            throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+                detail: 'Refresh token does not match any session',
+            });
+        }
+        if (session.revokedAt !== undefined || session.rotatedAt !== undefined) {
+            if (this.#config.refresh.reuseDetection) {
+                const revoked = await this.#store.revokeFamily(session.familyId, now);
+                await this.#audit?.record({
+                    name: 'token.reuse-detected',
+                    at: now,
+                    userId: session.userId,
+                    sessionId: session.id,
+                    meta: { familyId: session.familyId, sessionsRevoked: revoked },
+                });
+            }
+            throw new core_1.AuthenticationError('AUTH_TOKEN_REUSED', {
+                detail: `Refresh token for session ${session.id} was replayed after rotation; family ${session.familyId} revoked`,
+                meta: { sessionId: session.id, familyId: session.familyId },
+            });
+        }
+        if (session.expiresAt <= now) {
+            throw new core_1.AuthenticationError('AUTH_TOKEN_EXPIRED', {
+                detail: `Refresh session ${session.id} expired`,
+            });
+        }
+        if (!this.#config.refresh.rotate) {
+            // Rotation off: the same token stays valid, and no new row is written.
+            return { session, refreshToken };
+        }
+        await this.#store.markRotated(session.id, now);
+        const issued = await this.#create(session.userId, session.familyId, context);
+        await this.#audit?.record({
+            name: 'token.refreshed',
+            at: now,
+            userId: session.userId,
+            sessionId: issued.session.id,
+            meta: { familyId: session.familyId, previousSessionId: session.id },
+        });
+        return issued;
+    }
+    /** Look up a live session, or `undefined` if it is spent, revoked or expired. */
+    async findLive(refreshToken) {
+        const session = await this.#store.findByHashedToken(this.hashToken(refreshToken));
+        if (session === undefined)
+            return undefined;
+        const spent = session.revokedAt !== undefined ||
+            session.rotatedAt !== undefined ||
+            session.expiresAt <= this.#clock.now();
+        return spent ? undefined : session;
+    }
+    /**
+     * Log out.
+     *
+     * Revokes the whole family, not just the presented token: a logout that left
+     * the previous, already-rotated sibling usable would not be a logout.
+     */
+    async revoke(refreshToken) {
+        const now = this.#clock.now();
+        const session = await this.#store.findByHashedToken(this.hashToken(refreshToken));
+        if (session === undefined)
+            return false;
+        await this.#store.revokeFamily(session.familyId, now);
+        await this.#audit?.record({
+            name: 'session.revoked',
+            at: now,
+            userId: session.userId,
+            sessionId: session.id,
+            meta: { familyId: session.familyId, reason: 'logout' },
+        });
+        return true;
+    }
+    /** Revoke every session a user holds — after a password reset, say. */
+    async revokeAllForUser(userId, reason) {
+        const now = this.#clock.now();
+        const revoked = await this.#store.revokeAllForUser(userId, now);
+        if (revoked > 0) {
+            await this.#audit?.record({
+                name: 'session.revoked',
+                at: now,
+                userId,
+                meta: { reason, sessionsRevoked: revoked },
+            });
+        }
+        return revoked;
+    }
+    /** Drop expired rows; wire to a schedule in a long-running deployment. */
+    async prune() {
+        return this.#store.deleteExpired(this.#clock.now());
+    }
+    /**
+     * HMAC-SHA256 of the token under the session pepper.
+     *
+     * Public because a store implementation may need it to migrate existing rows,
+     * and because the tests assert that no plaintext token is ever persisted.
+     */
+    hashToken(refreshToken) {
+        return (0, node_crypto_1.createHmac)('sha256', this.#pepper).update(refreshToken, 'utf8').digest('base64url');
+    }
+    async #create(userId, familyId, context) {
+        const now = this.#clock.now();
+        const refreshToken = (0, core_1.randomToken)(32);
+        const session = {
+            id: (0, core_1.randomId)(),
+            familyId,
+            userId,
+            hashedToken: this.hashToken(refreshToken),
+            issuedAt: now,
+            expiresAt: now + this.#config.refresh.ttlSeconds * 1000,
+            ...(context.userAgent === undefined ? {} : { userAgent: context.userAgent }),
+            ...(context.ip === undefined ? {} : { ip: context.ip }),
+        };
+        await this.#store.create(session);
+        return { session, refreshToken };
+    }
+}
+exports.SessionService = SessionService;
+//# sourceMappingURL=session.service.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DI tokens for the auth ports (PLAN.md §7.3).
+ *
+ * An application binds these once in `NageAuthModule.forRoot`; nothing in this
+ * package imports a store implementation directly, which is what lets the same
+ * guards run against an in-memory store in tests and a SQL one in production.
+ */
+import { type Token } from '@nage-api/core';
+import type { ApiKeyStore, AuthAuditSink, AuthUserStore, Clock, LockoutStore, OtpChannel, OtpStore, PasswordHasher, SessionStore, TokenSigner } from './ports.js';
+import type { ResolvedAuthConfig } from './config.js';
+export declare const NAGE_AUTH_CONFIG: Token<ResolvedAuthConfig>;
+export declare const NAGE_AUTH_USER_STORE: Token<AuthUserStore>;
+export declare const NAGE_SESSION_STORE: Token<SessionStore>;
+export declare const NAGE_OTP_STORE: Token<OtpStore>;
+export declare const NAGE_OTP_CHANNEL: Token<OtpChannel>;
+export declare const NAGE_API_KEY_STORE: Token<ApiKeyStore>;
+export declare const NAGE_LOCKOUT_STORE: Token<LockoutStore>;
+export declare const NAGE_PASSWORD_HASHER: Token<PasswordHasher>;
+export declare const NAGE_TOKEN_SIGNER: Token<TokenSigner>;
+export declare const NAGE_AUTH_AUDIT: Token<AuthAuditSink>;
+export declare const NAGE_AUTH_CLOCK: Token<Clock>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * DI tokens for the auth ports (PLAN.md §7.3).
+ *
+ * An application binds these once in `NageAuthModule.forRoot`; nothing in this
+ * package imports a store implementation directly, which is what lets the same
+ * guards run against an in-memory store in tests and a SQL one in production.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_AUTH_CLOCK = exports.NAGE_AUTH_AUDIT = exports.NAGE_TOKEN_SIGNER = exports.NAGE_PASSWORD_HASHER = exports.NAGE_LOCKOUT_STORE = exports.NAGE_API_KEY_STORE = exports.NAGE_OTP_CHANNEL = exports.NAGE_OTP_STORE = exports.NAGE_SESSION_STORE = exports.NAGE_AUTH_USER_STORE = exports.NAGE_AUTH_CONFIG = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_AUTH_CONFIG = (0, core_1.createToken)('NAGE_AUTH_CONFIG');
+exports.NAGE_AUTH_USER_STORE = (0, core_1.createToken)('NAGE_AUTH_USER_STORE');
+exports.NAGE_SESSION_STORE = (0, core_1.createToken)('NAGE_SESSION_STORE');
+exports.NAGE_OTP_STORE = (0, core_1.createToken)('NAGE_OTP_STORE');
+exports.NAGE_OTP_CHANNEL = (0, core_1.createToken)('NAGE_OTP_CHANNEL');
+exports.NAGE_API_KEY_STORE = (0, core_1.createToken)('NAGE_API_KEY_STORE');
+exports.NAGE_LOCKOUT_STORE = (0, core_1.createToken)('NAGE_LOCKOUT_STORE');
+exports.NAGE_PASSWORD_HASHER = (0, core_1.createToken)('NAGE_PASSWORD_HASHER');
+exports.NAGE_TOKEN_SIGNER = (0, core_1.createToken)('NAGE_TOKEN_SIGNER');
+exports.NAGE_AUTH_AUDIT = (0, core_1.createToken)('NAGE_AUTH_AUDIT');
+exports.NAGE_AUTH_CLOCK = (0, core_1.createToken)('NAGE_AUTH_CLOCK');
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nage-api/auth",
+  "version": "1.0.0-beta.2",
+  "description": "Authentication and authorization for @nage-api — RS256 JWT, rotating refresh with reuse detection, argon2id passwords, OTP, API keys, RBAC",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@node-rs/argon2": "2.1.0",
+    "jose": "6.2.8",
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/platform-express": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@types/supertest": "6.0.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "supertest": "7.1.4",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}