@simple-auth-kit/cli 1.0.0

package/registry/core/test/password-reset.test.ts

@@ -0,0 +1,77 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { hashToken } from "../crypto.js";
+import { requestPasswordReset, resetPassword, PasswordResetStoreDeps } from "../password-reset.js";
+import { AuditEvent, PasswordResetTokenInvalidError } from "../types.js";
+
+interface FakeTokenRow {
+  userId: string;
+  tokenHash: string;
+  expiresAt: string;
+  consumedAt: string | null;
+}
+
+function fakeStore() {
+  const tokens = new Map<string, FakeTokenRow>();
+  const passwordHashes = new Map<string, string>();
+  const auditLog: AuditEvent[] = [];
+
+  const deps: PasswordResetStoreDeps = {
+    saveResetToken: async ({ userId, tokenHash, expiresAt }) => {
+      tokens.set(tokenHash, { userId, tokenHash, expiresAt, consumedAt: null });
+    },
+    findValidResetToken: async (tokenHash) => tokens.get(tokenHash) ?? null,
+    consumeResetToken: async (tokenHash) => {
+      const row = tokens.get(tokenHash);
+      if (row) row.consumedAt = new Date().toISOString();
+    },
+    setPasswordHash: async (userId, passwordHash) => {
+      passwordHashes.set(userId, passwordHash);
+    },
+    appendAuditEvent: async (event) => {
+      auditLog.push(event);
+    },
+  };
+
+  return { deps, tokens, passwordHashes, auditLog };
+}
+
+describe("password-reset", () => {
+  let store: ReturnType<typeof fakeStore>;
+
+  beforeEach(() => {
+    store = fakeStore();
+  });
+
+  it("issues a reset token and records an audit event", async () => {
+    const { token } = await requestPasswordReset(store.deps, "user-1");
+    expect(token).toHaveLength(64); // 32 bytes hex
+    expect(store.tokens.get(hashToken(token))?.userId).toBe("user-1");
+    expect(store.auditLog).toContainEqual({ type: "password_reset_requested", userId: "user-1" });
+  });
+
+  it("resets the password on a valid token and consumes it", async () => {
+    const { token } = await requestPasswordReset(store.deps, "user-1");
+    const { userId } = await resetPassword(store.deps, token, "new-correct-horse-battery-staple");
+
+    expect(userId).toBe("user-1");
+    expect(store.passwordHashes.get("user-1")).toBeDefined();
+    expect(store.tokens.get(hashToken(token))?.consumedAt).not.toBeNull();
+    expect(store.auditLog).toContainEqual({ type: "password_reset_completed", userId: "user-1" });
+  });
+
+  it("rejects an unknown token", async () => {
+    await expect(resetPassword(store.deps, "not-a-real-token", "new-pass")).rejects.toBeInstanceOf(PasswordResetTokenInvalidError);
+  });
+
+  it("rejects a token that has already been consumed", async () => {
+    const { token } = await requestPasswordReset(store.deps, "user-1");
+    await resetPassword(store.deps, token, "first-reset-password");
+
+    await expect(resetPassword(store.deps, token, "second-reset-password")).rejects.toBeInstanceOf(PasswordResetTokenInvalidError);
+  });
+
+  it("rejects an expired token", async () => {
+    const { token } = await requestPasswordReset(store.deps, "user-1", { ttlSeconds: -1 });
+    await expect(resetPassword(store.deps, token, "new-pass")).rejects.toBeInstanceOf(PasswordResetTokenInvalidError);
+  });
+});

package/registry/core/test/rate-limit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { checkRateLimit, RateLimitDeps } from "../rate-limit.js";
+
+function fakeCounter(): RateLimitDeps & { counts: Map<string, number> } {
+  const counts = new Map<string, number>();
+  return {
+    counts,
+    increment: async (key) => {
+      const next = (counts.get(key) ?? 0) + 1;
+      counts.set(key, next);
+      return next;
+    },
+  };
+}
+
+describe("rate-limit", () => {
+  it("allows requests under the max", async () => {
+    const deps = fakeCounter();
+    for (let i = 0; i < 5; i++) {
+      const result = await checkRateLimit(deps, "login", "user-1");
+      expect(result.allowed).toBe(true);
+    }
+  });
+
+  it("blocks requests over the max", async () => {
+    const deps = fakeCounter();
+    for (let i = 0; i < 5; i++) await checkRateLimit(deps, "login", "user-1");
+    const sixth = await checkRateLimit(deps, "login", "user-1");
+    expect(sixth.allowed).toBe(false);
+    expect(sixth.remaining).toBe(0);
+  });
+
+  it("scopes counters independently per identifier and scope", async () => {
+    const deps = fakeCounter();
+    for (let i = 0; i < 5; i++) await checkRateLimit(deps, "login", "user-1");
+    const otherUser = await checkRateLimit(deps, "login", "user-2");
+    const otherScope = await checkRateLimit(deps, "signup", "user-1");
+    expect(otherUser.allowed).toBe(true);
+    expect(otherScope.allowed).toBe(true);
+  });
+});

package/registry/core/test/rbac.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { resolvePermissions } from "../rbac.js";
+
+describe("rbac: resolvePermissions", () => {
+  it("unions role-derived and direct permissions", () => {
+    expect(resolvePermissions(["users:read", "users:block"], ["billing:manage"])).toEqual([
+      "billing:manage",
+      "users:block",
+      "users:read",
+    ]);
+  });
+
+  it("dedupes a permission granted both by role and directly", () => {
+    expect(resolvePermissions(["users:read"], ["users:read"])).toEqual(["users:read"]);
+  });
+
+  it("returns an empty array when the user has no permissions at all", () => {
+    expect(resolvePermissions([], [])).toEqual([]);
+  });
+});

package/registry/core/test/session-policy.test.ts

@@ -0,0 +1,209 @@
+import { randomUUID } from "node:crypto";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  blockUser,
+  createSession,
+  revokeAllSessionsForUser,
+  revokeOtherSessionsForUser,
+  revokeSession,
+  rotateRefreshToken,
+  SessionStoreDeps,
+} from "../session-policy.js";
+import { AuditEvent, RefreshInvalidError, RefreshReuseDetectedError, SessionRecord } from "../types.js";
+
+/** What a store would read from config. Long enough that no test trips over it by accident. */
+const SESSION_TTL_MS = 60 * 60 * 1000;
+
+function fakeStore() {
+  const sessions = new Map<string, SessionRecord>();
+  const denylist = new Set<string>();
+  const auditLog: AuditEvent[] = [];
+
+  const deps: SessionStoreDeps = {
+    findSession: async (id) => sessions.get(id) ?? null,
+    saveSession: async (session) => {
+      sessions.set(session.id, session);
+    },
+    createSession: async ({ userId, userAgent, ip, provider }) => {
+      const session: SessionRecord = {
+        id: randomUUID(),
+        userId,
+        sessionVersion: 0,
+        currentRefreshJti: randomUUID(),
+        provider,
+        expiresAt: new Date(Date.now() + SESSION_TTL_MS).toISOString(),
+        revokedAt: null,
+        createdAt: new Date().toISOString(),
+        userAgent,
+        ip,
+      };
+      sessions.set(session.id, session);
+      return session;
+    },
+    revokeAllByUser: async (userId, revoker) => {
+      for (const session of sessions.values()) {
+        if (session.userId === userId) {
+          session.sessionVersion += 1;
+          session.revokedAt = new Date().toISOString();
+          session.revokedBy = revoker?.userId;
+          session.revokedByIp = revoker?.ip;
+        }
+      }
+    },
+    revokeAllByUserExcept: async (userId, keepSessionId, revoker) => {
+      for (const session of sessions.values()) {
+        if (session.userId === userId && session.id !== keepSessionId) {
+          session.sessionVersion += 1;
+          session.revokedAt = new Date().toISOString();
+          session.revokedBy = revoker?.userId;
+          session.revokedByIp = revoker?.ip;
+        }
+      }
+    },
+    denylistJti: async (jti) => {
+      denylist.add(jti);
+    },
+    isDenylisted: async (jti) => denylist.has(jti),
+    appendAuditEvent: async (event) => {
+      auditLog.push(event);
+    },
+  };
+
+  return { deps, sessions, denylist, auditLog };
+}
+
+describe("session-policy", () => {
+  let store: ReturnType<typeof fakeStore>;
+
+  beforeEach(() => {
+    store = fakeStore();
+  });
+
+  it("creates a session and records an audit event", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    expect(session.sessionVersion).toBe(0);
+    expect(session.revokedAt).toBeNull();
+    expect(store.auditLog).toContainEqual({ type: "session_created", sessionId: session.id, userId: "user-1" });
+  });
+
+  it("rotates a refresh token on legitimate use, issuing a new jti", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    const { session: rotated, nextJti } = await rotateRefreshToken(store.deps, {
+      sub: "user-1",
+      sessionId: session.id,
+      sv: session.sessionVersion,
+      jti: session.currentRefreshJti,
+    });
+
+    expect(nextJti).not.toBe(session.currentRefreshJti);
+    expect(rotated.currentRefreshJti).toBe(nextJti);
+  });
+
+  it("detects reuse of an already-rotated refresh token and kills the whole session family", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    const staleJti = session.currentRefreshJti;
+
+    await rotateRefreshToken(store.deps, { sub: "user-1", sessionId: session.id, sv: session.sessionVersion, jti: staleJti });
+
+    await expect(
+      rotateRefreshToken(store.deps, { sub: "user-1", sessionId: session.id, sv: session.sessionVersion, jti: staleJti }),
+    ).rejects.toBeInstanceOf(RefreshReuseDetectedError);
+
+    const updated = await store.deps.findSession(session.id);
+    expect(updated?.revokedAt).not.toBeNull();
+    expect(store.auditLog.some((e) => e.type === "refresh_reuse_detected")).toBe(true);
+  });
+
+  it("rejects a refresh token whose sv is stale (session was revoked)", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    await revokeSession(store.deps, session.id);
+
+    await expect(
+      rotateRefreshToken(store.deps, {
+        sub: "user-1",
+        sessionId: session.id,
+        sv: 0, // the sv the client had before revoke bumped it
+        jti: session.currentRefreshJti,
+      }),
+    ).rejects.toBeInstanceOf(RefreshInvalidError);
+  });
+
+  it("revokeAllSessionsForUser kills every session for that user only", async () => {
+    const a = await createSession(store.deps, { userId: "user-1" });
+    const b = await createSession(store.deps, { userId: "user-1" });
+    const other = await createSession(store.deps, { userId: "user-2" });
+
+    await revokeAllSessionsForUser(store.deps, "user-1");
+
+    expect((await store.deps.findSession(a.id))?.revokedAt).not.toBeNull();
+    expect((await store.deps.findSession(b.id))?.revokedAt).not.toBeNull();
+    expect((await store.deps.findSession(other.id))?.revokedAt).toBeNull();
+  });
+
+  it("revokeOtherSessionsForUser keeps the current session alive and kills the rest", async () => {
+    const current = await createSession(store.deps, { userId: "user-1" });
+    const other = await createSession(store.deps, { userId: "user-1" });
+
+    await revokeOtherSessionsForUser(store.deps, "user-1", current.id);
+
+    expect((await store.deps.findSession(current.id))?.revokedAt).toBeNull();
+    expect((await store.deps.findSession(other.id))?.revokedAt).not.toBeNull();
+    expect(store.auditLog.some((e) => e.type === "other_sessions_revoked")).toBe(true);
+  });
+
+  it("blockUser revokes every session immediately, not just future logins", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    await blockUser(store.deps, "user-1");
+
+    expect((await store.deps.findSession(session.id))?.revokedAt).not.toBeNull();
+    expect(store.auditLog.some((e) => e.type === "user_blocked")).toBe(true);
+  });
+
+  it("records who revoked a session, and from where", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    await revokeSession(store.deps, session.id, { userId: "user-1", ip: "10.0.0.9" });
+
+    const revoked = await store.deps.findSession(session.id);
+    expect(revoked?.revokedBy).toBe("user-1");
+    expect(revoked?.revokedByIp).toBe("10.0.0.9");
+  });
+
+  it("blockUser records the administrator as the revoker, not the blocked user", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    await blockUser(store.deps, "user-1", { userId: "admin-1", ip: "10.0.0.1" });
+
+    // The distinction the column exists for: afterwards the row says an administrator ended this,
+    // not merely that it ended.
+    const revoked = await store.deps.findSession(session.id);
+    expect(revoked?.userId).toBe("user-1");
+    expect(revoked?.revokedBy).toBe("admin-1");
+  });
+
+  it("a refresh-reuse kill records no revoker — nobody did it", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    const staleJti = session.currentRefreshJti;
+    await rotateRefreshToken(store.deps, { sub: "user-1", sessionId: session.id, sv: session.sessionVersion, jti: staleJti });
+
+    await expect(
+      rotateRefreshToken(store.deps, { sub: "user-1", sessionId: session.id, sv: session.sessionVersion, jti: staleJti }),
+    ).rejects.toBeInstanceOf(RefreshReuseDetectedError);
+
+    expect((await store.deps.findSession(session.id))?.revokedBy).toBeUndefined();
+  });
+
+  it("refuses to rotate a session past its own expiry, however valid the token is", async () => {
+    const session = await createSession(store.deps, { userId: "user-1" });
+    // Everything about the presented token stays correct — only the wall clock has moved on.
+    store.sessions.set(session.id, { ...session, expiresAt: new Date(Date.now() - 1000).toISOString() });
+
+    await expect(
+      rotateRefreshToken(store.deps, { sub: "user-1", sessionId: session.id, sv: session.sessionVersion, jti: session.currentRefreshJti }),
+    ).rejects.toBeInstanceOf(RefreshInvalidError);
+  });
+
+  it("carries the login provider onto the session", async () => {
+    const session = await createSession(store.deps, { userId: "user-1", provider: "google" });
+    expect(session.provider).toBe("google");
+    expect((await createSession(store.deps, { userId: "user-1" })).provider).toBeUndefined();
+  });
+});

package/registry/core/test/test-keys.ts

@@ -0,0 +1,6 @@
+import { randomBytes } from "node:crypto";
+import { JwtSigningKey } from "../types.js";
+
+export function generateTestSigningKey(kid = "test-kid-1"): JwtSigningKey {
+  return { kid, secret: randomBytes(32) };
+}

package/registry/core/test/token-service.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  signAccessToken,
+  signRefreshToken,
+  signTwoFactorChallengeToken,
+  verifyAccessToken,
+  verifyRefreshToken,
+  verifyTwoFactorChallengeToken,
+} from "../token-service.js";
+import { AccessTokenInvalidError, RefreshInvalidError, TwoFactorChallengeInvalidError } from "../types.js";
+import { generateTestSigningKey } from "./test-keys.js";
+
+describe("token-service", () => {
+  it("signs and verifies an access token round-trip", async () => {
+    const key = generateTestSigningKey();
+    const { token, jti } = await signAccessToken(
+      { activeKey: key },
+      { sub: "user-1", sessionId: "session-1", roles: ["member"], permissions: ["users:read"] },
+    );
+
+    const claims = await verifyAccessToken({ secret: key.secret, isDenylisted: async () => false }, token);
+
+    expect(claims).toEqual({
+      sub: "user-1",
+      sessionId: "session-1",
+      roles: ["member"],
+      permissions: ["users:read"],
+      jti,
+    });
+  });
+
+  it("rejects a denylisted access token even if signature is valid", async () => {
+    const key = generateTestSigningKey();
+    const { token, jti } = await signAccessToken({ activeKey: key }, { sub: "u", sessionId: "s", roles: [], permissions: [] });
+
+    await expect(
+      verifyAccessToken({ secret: key.secret, isDenylisted: async (candidate) => candidate === jti }, token),
+    ).rejects.toBeInstanceOf(AccessTokenInvalidError);
+  });
+
+  it("rejects an access token verified against a different secret", async () => {
+    const key = generateTestSigningKey();
+    const otherKey = generateTestSigningKey("other-kid");
+    const { token } = await signAccessToken({ activeKey: key }, { sub: "u", sessionId: "s", roles: [], permissions: [] });
+
+    await expect(
+      verifyAccessToken({ secret: otherKey.secret, isDenylisted: async () => false }, token),
+    ).rejects.toBeInstanceOf(AccessTokenInvalidError);
+  });
+
+  it("signs and verifies a refresh token round-trip", async () => {
+    const key = generateTestSigningKey();
+    const { token, jti } = await signRefreshToken({ activeKey: key }, { sub: "user-1", sessionId: "session-1", sv: 3 });
+
+    const claims = await verifyRefreshToken({ secret: key.secret }, token);
+    expect(claims).toEqual({ sub: "user-1", sessionId: "session-1", sv: 3, jti });
+  });
+
+  it("rejects a refresh token verified against a different secret", async () => {
+    const key = generateTestSigningKey();
+    const otherKey = generateTestSigningKey("other-kid");
+    const { token } = await signRefreshToken({ activeKey: key }, { sub: "u", sessionId: "s", sv: 1 });
+
+    await expect(verifyRefreshToken({ secret: otherKey.secret }, token)).rejects.toBeInstanceOf(RefreshInvalidError);
+  });
+
+  it("signs and verifies a two-factor challenge token round-trip", async () => {
+    const key = generateTestSigningKey();
+    const { token } = await signTwoFactorChallengeToken({ activeKey: key }, "user-1");
+
+    const claims = await verifyTwoFactorChallengeToken({ secret: key.secret }, token);
+    expect(claims).toEqual({ sub: "user-1" });
+  });
+
+  it("rejects an access token presented in place of a two-factor challenge token", async () => {
+    const key = generateTestSigningKey();
+    const { token } = await signAccessToken({ activeKey: key }, { sub: "u", sessionId: "s", roles: [], permissions: [] });
+
+    await expect(verifyTwoFactorChallengeToken({ secret: key.secret }, token)).rejects.toBeInstanceOf(TwoFactorChallengeInvalidError);
+  });
+});

package/registry/core/test/two-factor.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildTotpProvisioningUri, generateBackupCodes, generateTotpCode, generateTotpSecret, verifyBackupCode, verifyTotpCode } from "../two-factor.js";
+
+// Shared seed from RFC 6238 Appendix B / RFC 4226 Appendix D ("12345678901234567890",
+// base32-encoded) — RFC 4226's own T=0 vector for this seed is the well-known "755224".
+const RFC_SECRET = "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ";
+
+describe("two-factor: TOTP", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("matches the RFC 4226 test vector at T=0 (counter 0, 6 digits)", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(0));
+    expect(verifyTotpCode(RFC_SECRET, "755224")).toBe(true);
+  });
+
+  it("matches the 6-digit truncation of the RFC 6238 T=59 vector (counter 1)", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(59_000));
+    expect(verifyTotpCode(RFC_SECRET, "287082")).toBe(true);
+  });
+
+  it("accepts the adjacent step's code within the default window, rejects it with window 0", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(59_000)); // counter 1; "755224" is counter 0's code
+    expect(verifyTotpCode(RFC_SECRET, "755224")).toBe(true); // default window is 1
+    expect(verifyTotpCode(RFC_SECRET, "755224", { window: 0 })).toBe(false);
+  });
+
+  it("rejects a malformed code without throwing", () => {
+    expect(verifyTotpCode(RFC_SECRET, "not-a-code")).toBe(false);
+    expect(verifyTotpCode(RFC_SECRET, "12345")).toBe(false);
+  });
+
+  it("generateTotpCode round-trips with verifyTotpCode", () => {
+    const secret = generateTotpSecret();
+    expect(verifyTotpCode(secret, generateTotpCode(secret))).toBe(true);
+  });
+
+  it("generateTotpSecret produces a fresh base32 secret each call", () => {
+    const a = generateTotpSecret();
+    const b = generateTotpSecret();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[A-Z2-7]+$/);
+  });
+
+  it("buildTotpProvisioningUri embeds the issuer, account name, and secret", () => {
+    const uri = buildTotpProvisioningUri({ secret: RFC_SECRET, accountName: "alice@example.com", issuer: "simple-auth-kit" });
+    expect(uri).toContain("otpauth://totp/");
+    expect(uri).toContain(`secret=${RFC_SECRET}`);
+    expect(decodeURIComponent(uri)).toContain("simple-auth-kit:alice@example.com");
+  });
+});
+
+describe("two-factor: backup codes", () => {
+  it("generates unique codes with matching hashes that verify correctly", () => {
+    const codes = generateBackupCodes(10);
+    expect(codes).toHaveLength(10);
+    expect(new Set(codes.map((c) => c.code)).size).toBe(10);
+
+    for (const { code, hash } of codes) {
+      expect(verifyBackupCode(code, hash)).toBe(true);
+    }
+  });
+
+  it("rejects an incorrect backup code", () => {
+    const [{ hash }] = generateBackupCodes(1);
+    expect(verifyBackupCode("0000000000", hash)).toBe(false);
+  });
+});

package/registry/core/token-service.ts

@@ -0,0 +1,143 @@
+import { SignJWT, jwtVerify } from "jose";
+import { randomUUID } from "node:crypto";
+import {
+  AccessTokenClaims,
+  AccessTokenInput,
+  AccessTokenInvalidError,
+  JwtSigningKey,
+  RefreshInvalidError,
+  RefreshTokenClaims,
+  TwoFactorChallengeInvalidError,
+} from "./types.js";
+
+const ACCESS_TOKEN_TTL_SECONDS_DEFAULT = 900; // 15 min
+const REFRESH_TOKEN_TTL_SECONDS_DEFAULT = 60 * 60 * 24 * 30; // 30 days
+const TWO_FACTOR_CHALLENGE_TTL_SECONDS_DEFAULT = 5 * 60; // 5 min
+const TWO_FACTOR_CHALLENGE_PURPOSE = "2fa-challenge";
+
+export interface SignDeps {
+  activeKey: JwtSigningKey;
+}
+
+export interface VerifyAccessTokenDeps {
+  secret: Uint8Array;
+  isDenylisted: (jti: string) => Promise<boolean>;
+}
+
+export interface VerifyRefreshTokenDeps {
+  secret: Uint8Array;
+}
+
+export async function signAccessToken(
+  deps: SignDeps,
+  claims: AccessTokenInput,
+  opts: { ttlSeconds?: number } = {},
+): Promise<{ token: string; jti: string; expiresAt: Date }> {
+  const jti = randomUUID();
+  const ttl = opts.ttlSeconds ?? ACCESS_TOKEN_TTL_SECONDS_DEFAULT;
+  const now = Math.floor(Date.now() / 1000);
+  const token = await new SignJWT({
+    sessionId: claims.sessionId,
+    // Omitted, not emptied, when the caller passes neither: a token that resolves authorization
+    // server-side must carry no authorization claim at all, so there is nothing to read off it.
+    ...(claims.roles !== undefined ? { roles: claims.roles } : {}),
+    ...(claims.permissions !== undefined ? { permissions: claims.permissions } : {}),
+  })
+    .setProtectedHeader({ alg: "HS256", kid: deps.activeKey.kid })
+    .setSubject(claims.sub)
+    .setJti(jti)
+    .setIssuedAt(now)
+    .setExpirationTime(now + ttl)
+    .sign(deps.activeKey.secret);
+  return { token, jti, expiresAt: new Date((now + ttl) * 1000) };
+}
+
+export async function verifyAccessToken(deps: VerifyAccessTokenDeps, token: string): Promise<AccessTokenClaims> {
+  let payload;
+  try {
+    ({ payload } = await jwtVerify(token, deps.secret, { algorithms: ["HS256"] }));
+  } catch {
+    throw new AccessTokenInvalidError();
+  }
+
+  const jti = payload.jti;
+  if (!jti) throw new AccessTokenInvalidError("missing jti");
+  if (await deps.isDenylisted(jti)) throw new AccessTokenInvalidError("token revoked");
+
+  return {
+    sub: payload.sub as string,
+    sessionId: payload.sessionId as string,
+    roles: (payload.roles as string[]) ?? [],
+    permissions: (payload.permissions as string[]) ?? [],
+    jti,
+  };
+}
+
+export async function signRefreshToken(
+  deps: SignDeps,
+  claims: Omit<RefreshTokenClaims, "jti">,
+  opts: { ttlSeconds?: number; jti?: string } = {},
+): Promise<{ token: string; jti: string }> {
+  const jti = opts.jti ?? randomUUID();
+  const ttl = opts.ttlSeconds ?? REFRESH_TOKEN_TTL_SECONDS_DEFAULT;
+  const now = Math.floor(Date.now() / 1000);
+  const token = await new SignJWT({ sessionId: claims.sessionId, sv: claims.sv })
+    .setProtectedHeader({ alg: "HS256", kid: deps.activeKey.kid })
+    .setSubject(claims.sub)
+    .setJti(jti)
+    .setIssuedAt(now)
+    .setExpirationTime(now + ttl)
+    .sign(deps.activeKey.secret);
+  return { token, jti };
+}
+
+// Short-TTL, purpose-scoped token proving "password already checked" without granting API
+// access — carries no session/roles.
+export async function signTwoFactorChallengeToken(
+  deps: SignDeps,
+  sub: string,
+  opts: { ttlSeconds?: number } = {},
+): Promise<{ token: string; jti: string }> {
+  const jti = randomUUID();
+  const ttl = opts.ttlSeconds ?? TWO_FACTOR_CHALLENGE_TTL_SECONDS_DEFAULT;
+  const now = Math.floor(Date.now() / 1000);
+  const token = await new SignJWT({ purpose: TWO_FACTOR_CHALLENGE_PURPOSE })
+    .setProtectedHeader({ alg: "HS256", kid: deps.activeKey.kid })
+    .setSubject(sub)
+    .setJti(jti)
+    .setIssuedAt(now)
+    .setExpirationTime(now + ttl)
+    .sign(deps.activeKey.secret);
+  return { token, jti };
+}
+
+export async function verifyTwoFactorChallengeToken(deps: VerifyRefreshTokenDeps, token: string): Promise<{ sub: string }> {
+  let payload;
+  try {
+    ({ payload } = await jwtVerify(token, deps.secret, { algorithms: ["HS256"] }));
+  } catch {
+    throw new TwoFactorChallengeInvalidError();
+  }
+
+  if (payload.purpose !== TWO_FACTOR_CHALLENGE_PURPOSE || !payload.sub) throw new TwoFactorChallengeInvalidError("malformed claims");
+  return { sub: payload.sub };
+}
+
+export async function verifyRefreshToken(deps: VerifyRefreshTokenDeps, token: string): Promise<RefreshTokenClaims> {
+  let payload;
+  try {
+    ({ payload } = await jwtVerify(token, deps.secret, { algorithms: ["HS256"] }));
+  } catch {
+    throw new RefreshInvalidError();
+  }
+
+  const jti = payload.jti;
+  if (!jti || payload.sv === undefined || !payload.sessionId) throw new RefreshInvalidError("malformed claims");
+
+  return {
+    sub: payload.sub as string,
+    sessionId: payload.sessionId as string,
+    sv: payload.sv as number,
+    jti,
+  };
+}

package/registry/core/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["*.ts", "test"],
+  "exclude": ["node_modules"]
+}