@starci/auth 0.0.0-stage → 0.2.0

package/dist/testing/index.d.ts

@@ -0,0 +1,52 @@
+import type { AuthOptions, SigningKeyOptions } from "../server/options.js";
+import type { AccountDirectory, AccountStanding, AuthClock, AuthIds, NewSession, RateCounter, RefreshTokenRecord, SessionStore, SessionTransaction } from "../server/ports.js";
+/** A generated Ed25519 key pair as the PEM texts the options take. */
+export interface TestKeyPair {
+    readonly privateKey: string;
+    readonly publicKey: string;
+}
+/** Generates an Ed25519 key pair (PKCS#8 private PEM, SPKI public PEM). */
+export declare const generateTestKeyPair: () => TestKeyPair;
+/** A signing key for the options; `signer: false` makes it a verify-only (retired) key. */
+export declare const testSigningKey: (pair?: TestKeyPair, keyId?: string, signer?: boolean) => SigningKeyOptions;
+/** A clock the test moves by hand. */
+export declare class FakeClock implements AuthClock {
+    #private;
+    constructor(start?: Date | number);
+    now(): Date;
+    /** Moves time forward. */
+    advance(milliseconds: number): void;
+}
+/** Ids that count up, so a spec reads them. */
+export declare const sequentialIds: (prefix?: string) => AuthIds;
+/** An in-memory `SessionStore` with the same rotation semantics the SQL tables give (a transaction applies all or none of its writes). */
+export declare class MemorySessionStore implements SessionStore {
+    #private;
+    readonly sessions: Map<string, NewSession>;
+    readonly tokens: Map<string, RefreshTokenRecord>;
+    transaction<T>(work: (tx: SessionTransaction) => Promise<T>): Promise<T>;
+    findToken(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    touchSession(): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    closeOtherSessions(userId: string, keepSessionId: string): Promise<void>;
+}
+/** An in-memory account directory. */
+export declare class MemoryAccounts implements AccountDirectory {
+    readonly accounts: Map<string, AccountStanding>;
+    /** Adds or replaces an account. */
+    set(account: AccountStanding): this;
+    find(userId: string): Promise<AccountStanding | undefined>;
+}
+/** An in-memory rate counter with fixed windows that the clock moves. */
+export declare class MemoryRateCounter implements RateCounter {
+    #private;
+    constructor(clock: AuthClock);
+    consume(key: string, windowMs: number, limit: number): Promise<boolean>;
+    clear(key: string): Promise<void>;
+}
+/** Options for a spec: one fresh signing key, in-memory stores and a fake clock. Override any field. */
+export declare const testAuthOptions: (overrides?: Partial<Omit<AuthOptions, "clock" | "sessions" | "accounts">>) => AuthOptions & {
+    readonly clock: FakeClock;
+    readonly sessions: MemorySessionStore;
+    readonly accounts: MemoryAccounts;
+};

package/dist/testing/index.js

@@ -0,0 +1,158 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+/** Generates an Ed25519 key pair (PKCS#8 private PEM, SPKI public PEM). */
+export const generateTestKeyPair = () => {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    return {
+        privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+        publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    };
+};
+/** A signing key for the options; `signer: false` makes it a verify-only (retired) key. */
+export const testSigningKey = (pair = generateTestKeyPair(), keyId, signer = true) => ({
+    publicKey: pair.publicKey,
+    ...(signer ? { privateKey: pair.privateKey } : {}),
+    ...(keyId === undefined ? {} : { keyId }),
+});
+/** A clock the test moves by hand. */
+export class FakeClock {
+    #at;
+    constructor(start = Date.UTC(2026, 0, 1)) {
+        this.#at = typeof start === "number" ? start : start.getTime();
+    }
+    now() {
+        return new Date(this.#at);
+    }
+    /** Moves time forward. */
+    advance(milliseconds) {
+        this.#at += milliseconds;
+    }
+}
+/** Ids that count up, so a spec reads them. */
+export const sequentialIds = (prefix = "id") => {
+    let n = 0;
+    return { next: () => `${prefix}-${String(++n)}-${randomUUID().slice(0, 8)}` };
+};
+/** An in-memory `SessionStore` with the same rotation semantics the SQL tables give (a transaction applies all or none of its writes). */
+export class MemorySessionStore {
+    sessions = new Map();
+    tokens = new Map();
+    async transaction(work) {
+        const sessions = new Map(this.sessions);
+        const tokens = new Map(this.tokens);
+        const tx = {
+            openSession: (session) => {
+                this.sessions.set(session.id, session);
+                return Promise.resolve();
+            },
+            insertToken: (token) => {
+                this.tokens.set(token.id, { ...token, usedAt: null });
+                return Promise.resolve();
+            },
+            findTokenForUpdate: (tokenHash) => Promise.resolve(this.#byHash(tokenHash)),
+            markTokenUsed: (tokenId, at) => {
+                const row = this.tokens.get(tokenId);
+                if (row !== undefined)
+                    this.tokens.set(tokenId, { ...row, usedAt: at });
+                return Promise.resolve();
+            },
+            deleteExpiredTokens: (userId, before) => {
+                for (const [id, row] of this.tokens)
+                    if (row.userId === userId && row.expiresAt < before)
+                        this.tokens.delete(id);
+                return Promise.resolve();
+            },
+        };
+        try {
+            return await work(tx);
+        }
+        catch (cause) {
+            this.sessions.clear();
+            this.tokens.clear();
+            for (const [id, row] of sessions)
+                this.sessions.set(id, row);
+            for (const [id, row] of tokens)
+                this.tokens.set(id, row);
+            throw cause;
+        }
+    }
+    findToken(tokenHash) {
+        return Promise.resolve(this.#byHash(tokenHash));
+    }
+    touchSession() {
+        return Promise.resolve();
+    }
+    closeSession(sessionId) {
+        this.sessions.delete(sessionId);
+        for (const [id, row] of this.tokens)
+            if (row.sessionId === sessionId)
+                this.tokens.delete(id);
+        return Promise.resolve();
+    }
+    closeOtherSessions(userId, keepSessionId) {
+        for (const [id, row] of this.sessions)
+            if (row.userId === userId && id !== keepSessionId)
+                void this.closeSession(id);
+        return Promise.resolve();
+    }
+    #byHash(tokenHash) {
+        for (const row of this.tokens.values())
+            if (row.tokenHash === tokenHash)
+                return row;
+        return null;
+    }
+}
+/** An in-memory account directory. */
+export class MemoryAccounts {
+    accounts = new Map();
+    /** Adds or replaces an account. */
+    set(account) {
+        this.accounts.set(account.id, account);
+        return this;
+    }
+    find(userId) {
+        return Promise.resolve(this.accounts.get(userId));
+    }
+}
+/** An in-memory rate counter with fixed windows that the clock moves. */
+export class MemoryRateCounter {
+    #clock;
+    #hits = new Map();
+    constructor(clock) {
+        this.#clock = clock;
+    }
+    consume(key, windowMs, limit) {
+        const at = this.#clock.now().getTime();
+        const current = this.#hits.get(key);
+        const entry = current === undefined || current.resetAt <= at ? { count: 0, resetAt: at + windowMs } : current;
+        entry.count += 1;
+        this.#hits.set(key, entry);
+        return Promise.resolve(entry.count <= limit);
+    }
+    clear(key) {
+        this.#hits.delete(key);
+        return Promise.resolve();
+    }
+}
+/** Options for a spec: one fresh signing key, in-memory stores and a fake clock. Override any field. */
+export const testAuthOptions = (overrides = {}) => {
+    const clock = new FakeClock();
+    const sessions = new MemorySessionStore();
+    const accounts = new MemoryAccounts();
+    return {
+        issuer: "https://api.example.test",
+        keys: [testSigningKey()],
+        accessTtlSeconds: 900,
+        refreshTtlSeconds: 2_592_000,
+        bcryptCost: 4,
+        returnOrigin: "https://app.example.test",
+        google: null,
+        cookie: { name: "auth_refresh" },
+        budget: { loginAttempts: 3, resetAttempts: 2, windowMs: 900_000 },
+        rate: new MemoryRateCounter(clock),
+        ids: sequentialIds(),
+        ...overrides,
+        clock,
+        sessions,
+        accounts,
+    };
+};

package/migrations/identity-sessions.sql

@@ -0,0 +1,58 @@
+-- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
+-- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
+-- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
+-- The app owns auth.users (db/bootstrap.sql) and the role app_be.
+
+create table public.identity_sessions (
+    id uuid primary key,
+    user_id uuid not null references auth.users (id) on delete cascade,
+    created_at timestamptz not null default now(),
+    refreshed_at timestamptz not null default now(),
+    user_agent text,
+    ip text
+);
+
+create index identity_sessions_user_idx on public.identity_sessions (user_id);
+
+create table public.identity_refresh_tokens (
+    id uuid primary key default gen_random_uuid(),
+    session_id uuid not null references public.identity_sessions (id) on delete cascade,
+    user_id uuid not null,
+    token_hash text not null,
+    created_at timestamptz not null default now(),
+    expires_at timestamptz not null,
+    used_at timestamptz,
+    constraint identity_refresh_tokens_hash_key unique (token_hash)
+);
+
+create index identity_refresh_tokens_session_idx on public.identity_refresh_tokens (session_id);
+create index identity_refresh_tokens_expiry_idx on public.identity_refresh_tokens (user_id, expires_at);
+
+create table public.identity_attempts (
+    key varchar(128) primary key,
+    hits integer not null,
+    reset_at timestamptz not null
+);
+
+create index identity_attempts_reset_idx on public.identity_attempts (reset_at);
+
+alter table public.identity_sessions enable row level security;
+alter table public.identity_sessions force row level security;
+alter table public.identity_refresh_tokens enable row level security;
+alter table public.identity_refresh_tokens force row level security;
+alter table public.identity_attempts enable row level security;
+alter table public.identity_attempts force row level security;
+
+revoke all on table public.identity_sessions from public;
+revoke all on table public.identity_refresh_tokens from public;
+revoke all on table public.identity_attempts from public;
+grant select, insert, update, delete on table public.identity_sessions to app_be;
+grant select, insert, update, delete on table public.identity_refresh_tokens to app_be;
+grant select, insert, update, delete on table public.identity_attempts to app_be;
+
+create policy identity_sessions_app_be_all on public.identity_sessions
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+create policy identity_refresh_tokens_app_be_all on public.identity_refresh_tokens
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');
+create policy identity_attempts_app_be_all on public.identity_attempts
+    for all to app_be using (current_user = 'app_be') with check (current_user = 'app_be');

package/package.json

@@ -1,6 +1,128 @@
 {
   "name": "@starci/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The sign-in of a StarCi lite app in one package: a NestJS module (EdDSA access tokens with a multi-key JWKS, bcrypt passwords, Google OAuth with state and PKCE, rotating refresh tokens with a reuse grace window and reuse detection, a failures-only sign-in limit, the refresh cookie), the door contracts, a front-end auth client (access token in memory, one shared refresh, signed out only on 401 or 403) with React bindings, and test doubles.",
+  "keywords": [
+    "auth",
+    "jwt",
+    "jwks",
+    "eddsa",
+    "passport",
+    "google-oauth",
+    "pkce",
+    "refresh-token",
+    "nestjs",
+    "react"
+  ],
+  "license": "MIT",
+  "author": "starci183",
+  "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/auth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starci183/starci-harness.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/starci183/starci-harness/issues"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/contracts/index.js",
+  "types": "./dist/contracts/index.d.ts",
+  "exports": {
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./client/react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts/index.d.ts",
+      "default": "./dist/contracts/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./migrations/*": "./migrations/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*",
+    "migrations",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); for (const f of fs.readdirSync('dist', {recursive: true}).filter((n) => n.endsWith('.d.ts'))) fs.writeFileSync('dist/' + f, fs.readFileSync('dist/' + f, 'utf8').replace(/((?:from |import\\()['\\x22]\\.\\.?\\/[^'\\x22]+)\\.ts(['\\x22])/g, (all, head, quote) => head + '.js' + quote))\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "npm run typecheck && npm run lint && node --test --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-exclude=\"src/**/*.spec.ts\" --test-coverage-lines=90 \"src/**/*.spec.ts\"",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "dependencies": {
+    "@nestjs/passport": "11.0.5",
+    "bcryptjs": "3.0.3",
+    "jose": "6.2.12",
+    "passport": "0.7.0",
+    "passport-google-oauth20": "2.0.0",
+    "passport-local": "1.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "react": ">=18",
+    "reflect-metadata": "^0.1.12 || ^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@nestjs/common": "11.2.5",
+    "@nestjs/core": "11.2.5",
+    "@nestjs/testing": "11.2.5",
+    "@types/express": "4.17.25",
+    "@types/node": "22.20.4",
+    "@types/passport-google-oauth20": "2.0.17",
+    "@types/passport-local": "1.0.38",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "eslint": "10.13.0",
+    "jiti": "2.7.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.72.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}