@chttp/auth 0.0.0-stage → 0.2.0

package/src/session.ts

@@ -0,0 +1,154 @@
+// Sessions, after the Lucia pattern: a random bearer token, a SHA-256 store
+// key (the only thing persisted), sliding expiry. ~150 LoC because the
+// package refuses to own state — the caller's store holds everything.
+//
+// Token layout: base64url(16-byte id) + "." + base64url(32-byte secret) —
+// 384 bits of entropy, never stored whole. hashToken() produces the lookup
+// key; a leaked store yields nothing replayable.
+//
+// Store contract is sync-or-async: stores may return values or Promises and
+// the lifecycle functions `await` unconditionally (one microtask on sync
+// stores — documented in the README; the SHA-256 dominates). We never sniff
+// `.then` (SC2009). Interface members return `unknown` for that reason —
+// a `T | Promise<T>` union arm is SC2009.
+//
+// `SessionStore<A>` / `SessionRecord<A>` are phantom-generic aliases: the
+// generic parameter documents intended attribute type, but no method
+// signature references it (a member that mentions the type param refuses
+// to lower at the call site — SC1090, same finding as @chttp/cache).
+
+import { createHash, randomBytes } from "node:crypto";
+import { authError } from "./errors.ts";
+import { b64urlEncode, toHex } from "./encoding.ts";
+
+export interface SessionRecordData {
+  key: string; // hashToken(token) — the store key
+  userId: string;
+  expiresAt: number; // epoch ms
+  attributes: unknown; // app data (role, display name, ...)
+}
+
+// Generic-typed surface: `SessionRecord<A>` is SessionRecordData with the
+// attributes member re-typed. No functions hold records of this shape by
+// generic signature — see the phantom-alias note above.
+export interface SessionRecord<A> extends SessionRecordData {
+  attributes: A | null;
+}
+
+export interface SessionStoreCore {
+  // Each member may return the value OR a Promise of it; `unknown` keeps the
+  // union SC2009-free. Implementations return the concrete shapes below.
+  get(key: string): unknown; // SessionRecordData | null | Promise<...>
+  set(record: SessionRecordData): unknown; // void | Promise<void>
+  updateExpiry(key: string, expiresAt: number): unknown; // void | Promise<void>
+  delete(key: string): unknown; // void | Promise<void>
+  deleteAllForUser(userId: string): unknown; // void | Promise<void>
+}
+
+// Phantom generic: `SessionStore<A>` types the intended attribute record
+// while every method lowers identically to SessionStoreCore.
+export interface SessionStore<_A> extends SessionStoreCore {}
+
+export interface SessionOpts {
+  ttlSeconds?: number; // default: 30 days
+  // extend when less than this remains; default: half the TTL
+  extensionThresholdSeconds?: number;
+  // deterministic clock seam for tests/ELF (default Date.now())
+  nowMs?: number;
+}
+
+const DEFAULT_TTL_SECONDS = 30 * 24 * 60 * 60;
+
+export function generateSessionToken(): string {
+  return b64urlEncode(randomBytes(16)) + "." + b64urlEncode(randomBytes(32));
+}
+
+// SHA-256 hex of the full token. This is the store key and the only thing
+// persisted; exported so store adapters key consistently.
+export function hashToken(token: string): string {
+  return toHex(createHash("sha256").update(token).digest());
+}
+
+function optsOr(opts: SessionOpts | undefined): SessionOpts {
+  if (opts === undefined || opts === null) {
+    return {};
+  }
+  return opts;
+}
+
+function ttlOf(opts: SessionOpts): number {
+  if (opts.ttlSeconds === undefined) {
+    return DEFAULT_TTL_SECONDS;
+  }
+  return opts.ttlSeconds;
+}
+
+function nowOf(opts: SessionOpts): number {
+  if (opts.nowMs === undefined) {
+    return Date.now();
+  }
+  return opts.nowMs;
+}
+
+export async function createSession(
+  store: SessionStoreCore,
+  token: string,
+  userId: string,
+  attributes: unknown,
+  opts?: SessionOpts,
+): Promise<SessionRecordData> {
+  const o = optsOr(opts);
+  const ttl = ttlOf(o);
+  if (!(ttl > 0)) {
+    throw authError("E_BAD_PARAMS", "ttlSeconds must be positive");
+  }
+  const rec: SessionRecordData = {
+    key: hashToken(token),
+    userId: userId,
+    expiresAt: nowOf(o) + ttl * 1000,
+    attributes: attributes,
+  };
+  await store.set(rec);
+  return rec;
+}
+
+// Sliding expiry: a valid session past the extension threshold gets
+// expiresAt bumped and written back. Returns null for unknown, expired, or
+// malformed tokens. Never throws.
+export async function validateSessionToken(
+  store: SessionStoreCore,
+  token: string,
+  opts?: SessionOpts,
+): Promise<SessionRecordData | null> {
+  const o = optsOr(opts);
+  const ttl = ttlOf(o);
+  let threshold = Math.floor(ttl / 2);
+  if (o.extensionThresholdSeconds !== undefined) {
+    threshold = o.extensionThresholdSeconds;
+  }
+  const now = nowOf(o);
+  const rec = (await store.get(hashToken(token))) as SessionRecordData | null;
+  if (rec === null || rec === undefined) {
+    return null;
+  }
+  if (now >= rec.expiresAt) {
+    await store.delete(rec.key);
+    return null;
+  }
+  if (rec.expiresAt - now < threshold * 1000) {
+    rec.expiresAt = now + ttl * 1000;
+    await store.updateExpiry(rec.key, rec.expiresAt);
+  }
+  return rec;
+}
+
+export async function invalidateSession(store: SessionStoreCore, token: string): Promise<void> {
+  await store.delete(hashToken(token));
+}
+
+export async function invalidateAllUserSessions(
+  store: SessionStoreCore,
+  userId: string,
+): Promise<void> {
+  await store.deleteAllForUser(userId);
+}

package/src/totp.ts

@@ -0,0 +1,132 @@
+// TOTP (RFC 6238) over HMAC-SHA1 HOTP (RFC 4226), base32 secrets (RFC 4648).
+// Defaults: 6 digits, 30 s step, ±1 window. Code compares are constant-time
+// (length pre-check + timingSafeEqual over the digit strings).
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { base32Decode, base32Encode } from "./encoding.ts";
+
+const DEFAULT_DIGITS = 6;
+const DEFAULT_STEP = 30;
+const DEFAULT_WINDOW = 1;
+const SECRET_BYTES = 20;
+
+export function generateTotpSecret(): string {
+  return base32Encode(randomBytes(SECRET_BYTES));
+}
+
+export interface TotpUriOpts {
+  digits?: number; // default 6
+  stepSeconds?: number; // default 30
+}
+
+// otpauth:// URI for authenticator enrollment (Google Authenticator shape).
+export function totpAuthUri(
+  secret: string,
+  accountName: string,
+  issuer: string,
+  opts?: TotpUriOpts,
+): string {
+  let digits = DEFAULT_DIGITS;
+  let step = DEFAULT_STEP;
+  if (opts !== undefined && opts !== null) {
+    if (opts.digits !== undefined) {
+      digits = opts.digits;
+    }
+    if (opts.stepSeconds !== undefined) {
+      step = opts.stepSeconds;
+    }
+  }
+  const label = encodeURIComponent(issuer + ":" + accountName);
+  return (
+    "otpauth://totp/" +
+    label +
+    "?secret=" +
+    secret +
+    "&issuer=" +
+    encodeURIComponent(issuer) +
+    "&digits=" +
+    digits +
+    "&period=" +
+    step
+  );
+}
+
+// RFC 4226 dynamic truncation: 8-byte big-endian counter -> HMAC-SHA1 ->
+// 4-byte window -> digits.
+function hotpCode(key: Uint8Array, counter: number, digits: number): string {
+  const msg = new Uint8Array(8);
+  let hi = Math.floor(counter / 4294967296);
+  let lo = counter % 4294967296;
+  msg[0] = (hi >>> 24) & 255;
+  msg[1] = (hi >>> 16) & 255;
+  msg[2] = (hi >>> 8) & 255;
+  msg[3] = hi & 255;
+  msg[4] = (lo >>> 24) & 255;
+  msg[5] = (lo >>> 16) & 255;
+  msg[6] = (lo >>> 8) & 255;
+  msg[7] = lo & 255;
+  const mac = createHmac("sha1", key).update(msg).digest();
+  const off = mac[19] & 15;
+  const bin =
+    ((mac[off] & 127) << 24) |
+    ((mac[off + 1] & 255) << 16) |
+    ((mac[off + 2] & 255) << 8) |
+    (mac[off + 3] & 255);
+  const mod = Math.pow(10, digits);
+  let s = "" + (bin % mod);
+  while (s.length < digits) {
+    s = "0" + s;
+  }
+  return s;
+}
+
+export interface VerifyTotpOpts {
+  window?: number; // default ±1 step
+  stepSeconds?: number; // default 30
+  digits?: number; // default 6
+  nowMs?: number; // deterministic clock seam for tests/ELF (default Date.now())
+}
+
+export function verifyTotp(code: string, secret: string, opts?: VerifyTotpOpts): boolean {
+  const key = base32Decode(secret);
+  if (key === null) {
+    return false;
+  }
+  let digits = DEFAULT_DIGITS;
+  let step = DEFAULT_STEP;
+  let win = DEFAULT_WINDOW;
+  let nowMs = Date.now();
+  if (opts !== undefined && opts !== null) {
+    if (opts.digits !== undefined) {
+      digits = opts.digits;
+    }
+    if (opts.stepSeconds !== undefined) {
+      step = opts.stepSeconds;
+    }
+    if (opts.window !== undefined) {
+      win = opts.window;
+    }
+    if (opts.nowMs !== undefined) {
+      nowMs = opts.nowMs;
+    }
+  }
+  if (code.length !== digits) {
+    return false;
+  }
+  const counter = Math.floor(nowMs / 1000 / step);
+  let match = false;
+  // Check the whole window without early exit — timing stays flat.
+  for (let w = -win; w <= win; w++) {
+    const c = counter + w;
+    if (c < 0) {
+      continue;
+    }
+    const expected = hotpCode(key, c, digits);
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(code, "utf8");
+    if (a.length === b.length && timingSafeEqual(a, b)) {
+      match = true;
+    }
+  }
+  return match;
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+// Shared types for @chttp/auth.
+//
+// StandardSchemaV1 below is a structural twin of the interface published by
+// @standard-schema/spec (Standard Schema v1). The npm package is types-only
+// and scriptc refuses even `import type` of it in the compiled module graph
+// (SC2013), so the twin is declared here — same approach as @chttp/mcp's
+// src/types.ts. Structural identity means any real Standard Schema v1
+// validator (@chttp/val, valibot, zod/v4 standard entry) is assignable to
+// this twin and vice versa. The spec text: https://standardschema.dev
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+export namespace StandardSchemaV1 {
+  export interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: Types<Input, Output> | undefined;
+    // `unknown` (not `Result | Promise<Result>`): a Promise union arm is
+    // SC2009 in the subset, and every conforming validator — whose real
+    // signature returns `Result<Output> | Promise<Result<Output>>` — is
+    // still assignable to a function returning `unknown`. runSchema
+    // awaits the value and reads the shape at runtime.
+    readonly validate: (value: unknown) => unknown;
+  }
+  export interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+  export interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  export interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  export interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  export interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"];
+}
+
+export type InferOutput<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+
+// Runs a Standard-Schema validator over untrusted input (JWT claims, OAuth
+// userinfo). Returns the validated value or null — the auth verify-path
+// contract is null-on-invalid, never throw. The validate call may return a
+// Result or a Promise<Result>; awaiting unknown covers both without ever
+// sniffing `.then` (SC2009).
+export async function runSchema(schema: StandardSchemaV1, value: unknown): Promise<unknown | null> {
+  let res: unknown;
+  try {
+    res = await schema["~standard"].validate(value);
+  } catch {
+    return null;
+  }
+  if (res === null || typeof res !== "object") {
+    return null;
+  }
+  const r = res as { [k: string]: unknown };
+  const issues = r["issues"];
+  if (issues !== undefined && issues !== null) {
+    return null;
+  }
+  if (!("value" in r)) {
+    return null;
+  }
+  return r["value"];
+}