@chttp/auth 0.0.0-stage → 0.2.0

package/dist/esm/session.js

@@ -0,0 +1,94 @@
+// 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.js";
+import { b64urlEncode, toHex } from "./encoding.js";
+const DEFAULT_TTL_SECONDS = 30 * 24 * 60 * 60;
+export function generateSessionToken() {
+    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) {
+    return toHex(createHash("sha256").update(token).digest());
+}
+function optsOr(opts) {
+    if (opts === undefined || opts === null) {
+        return {};
+    }
+    return opts;
+}
+function ttlOf(opts) {
+    if (opts.ttlSeconds === undefined) {
+        return DEFAULT_TTL_SECONDS;
+    }
+    return opts.ttlSeconds;
+}
+function nowOf(opts) {
+    if (opts.nowMs === undefined) {
+        return Date.now();
+    }
+    return opts.nowMs;
+}
+export async function createSession(store, token, userId, attributes, opts) {
+    const o = optsOr(opts);
+    const ttl = ttlOf(o);
+    if (!(ttl > 0)) {
+        throw authError("E_BAD_PARAMS", "ttlSeconds must be positive");
+    }
+    const rec = {
+        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, token, opts) {
+    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)));
+    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, token) {
+    await store.delete(hashToken(token));
+}
+export async function invalidateAllUserSessions(store, userId) {
+    await store.deleteAllForUser(userId);
+}

package/dist/esm/totp.d.ts

@@ -0,0 +1,13 @@
+export declare function generateTotpSecret(): string;
+export interface TotpUriOpts {
+    digits?: number;
+    stepSeconds?: number;
+}
+export declare function totpAuthUri(secret: string, accountName: string, issuer: string, opts?: TotpUriOpts): string;
+export interface VerifyTotpOpts {
+    window?: number;
+    stepSeconds?: number;
+    digits?: number;
+    nowMs?: number;
+}
+export declare function verifyTotp(code: string, secret: string, opts?: VerifyTotpOpts): boolean;

package/dist/esm/totp.js

@@ -0,0 +1,106 @@
+// 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.js";
+const DEFAULT_DIGITS = 6;
+const DEFAULT_STEP = 30;
+const DEFAULT_WINDOW = 1;
+const SECRET_BYTES = 20;
+export function generateTotpSecret() {
+    return base32Encode(randomBytes(SECRET_BYTES));
+}
+// otpauth:// URI for authenticator enrollment (Google Authenticator shape).
+export function totpAuthUri(secret, accountName, issuer, opts) {
+    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, counter, digits) {
+    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 function verifyTotp(code, secret, opts) {
+    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/dist/esm/types.d.ts

@@ -0,0 +1,34 @@
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly types?: Types<Input, Output> | undefined;
+        readonly validate: (value: unknown) => unknown;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+export type InferOutput<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;
+export declare function runSchema(schema: StandardSchemaV1, value: unknown): Promise<unknown | null>;

package/dist/esm/types.js

@@ -0,0 +1,35 @@
+// 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
+// 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, value) {
+    let res;
+    try {
+        res = await schema["~standard"].validate(value);
+    }
+    catch {
+        return null;
+    }
+    if (res === null || typeof res !== "object") {
+        return null;
+    }
+    const r = res;
+    const issues = r["issues"];
+    if (issues !== undefined && issues !== null) {
+        return null;
+    }
+    if (!("value" in r)) {
+        return null;
+    }
+    return r["value"];
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@chttp/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Session, password, JWT, OAuth2+PKCE, CSRF and TOTP primitives over node:crypto, authored inside the scriptc compilable subset",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sigilco/cutils.git",
+    "directory": "packages/auth"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@chttp/router": "^0.2.1",
+    "@chttp/val": "^0.2.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^24.0.0",
+    "jose": "^6.0.0",
+    "typescript": "^5.9.0",
+    "valibot": "^1.5.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "author": "Joaquin Terrasa & contributors",
+  "keywords": [
+    "auth",
+    "session",
+    "jwt",
+    "oauth2",
+    "pkce",
+    "csrf",
+    "totp",
+    "scrypt",
+    "scriptc",
+    "native"
+  ],
+  "homepage": "https://github.com/sigilco/cutils/tree/main/packages/auth#readme",
+  "bugs": {
+    "url": "https://github.com/sigilco/cutils/issues"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.js test/*.test.mjs && bash test/elf.test.sh"
+  }
 }

package/src/cookie.ts

@@ -0,0 +1,111 @@
+// Set-Cookie serialization + minimal Cookie-header read. Three cookies are
+// set (session, expired-session, csrf) and one is read (session) — 80 LoC
+// beats a jar dependency.
+
+export interface CookieAttrs {
+  maxAge?: number; // seconds
+  path?: string; // default "/"
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+}
+
+export const SESSION_COOKIE_NAME = "session";
+export const CSRF_COOKIE_NAME = "csrf";
+
+function sameSiteAttr(v: string): string {
+  if (v === "strict") {
+    return "Strict";
+  }
+  if (v === "none") {
+    return "None";
+  }
+  return "Lax";
+}
+
+// Full Set-Cookie header value.
+export function serializeCookie(name: string, value: string, attrs: CookieAttrs): string {
+  let out = name + "=" + value;
+  const path = attrs.path === undefined ? "/" : attrs.path;
+  out += "; Path=" + path;
+  if (attrs.maxAge !== undefined) {
+    out += "; Max-Age=" + Math.floor(attrs.maxAge);
+  }
+  if (attrs.httpOnly === true) {
+    out += "; HttpOnly";
+  }
+  if (attrs.secure === true) {
+    out += "; Secure";
+  }
+  if (attrs.sameSite !== undefined) {
+    out += "; SameSite=" + sameSiteAttr(attrs.sameSite);
+  }
+  return out;
+}
+
+// Minimal read of the Cookie request header: returns the raw value for
+// `name`, or null. First match wins; values are returned undecoded (the
+// session/csrf tokens this package sets are base64url, which needs none).
+export function readCookie(cookieHeader: string | null, name: string): string | null {
+  if (cookieHeader === null) {
+    return null;
+  }
+  const prefix = name + "=";
+  const parts = cookieHeader.split(";");
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i].trim();
+    if (p.startsWith(prefix)) {
+      return p.slice(prefix.length);
+    }
+  }
+  return null;
+}
+
+export interface SessionCookieOpts {
+  secure?: boolean; // default true; set false for http://localhost dev
+  ttlSeconds?: number; // default: 30 days — bound to the session TTL
+}
+
+const DEFAULT_COOKIE_TTL = 30 * 24 * 60 * 60;
+
+// Prebuilt session cookie: HttpOnly, SameSite=Lax, Path=/, Secure=true
+// (override for localhost), Max-Age bound to the session TTL.
+export function buildSessionCookie(token: string, opts?: SessionCookieOpts): string {
+  const secure = opts === undefined || opts.secure === undefined ? true : opts.secure;
+  const ttl =
+    opts === undefined || opts.ttlSeconds === undefined ? DEFAULT_COOKIE_TTL : opts.ttlSeconds;
+  return serializeCookie(SESSION_COOKIE_NAME, token, {
+    maxAge: ttl,
+    path: "/",
+    secure: secure,
+    httpOnly: true,
+    sameSite: "lax",
+  });
+}
+
+// Logout: same name, empty value, already expired.
+export function buildExpiredSessionCookie(opts?: SessionCookieOpts): string {
+  const secure = opts === undefined || opts.secure === undefined ? true : opts.secure;
+  return serializeCookie(SESSION_COOKIE_NAME, "", {
+    maxAge: 0,
+    path: "/",
+    secure: secure,
+    httpOnly: true,
+    sameSite: "lax",
+  });
+}
+
+// CSRF double-submit cookie: deliberately NOT HttpOnly — the pattern needs
+// JS (or the page itself) to read the token into a form field/header.
+export function buildCsrfCookie(token: string, opts?: SessionCookieOpts): string {
+  const secure = opts === undefined || opts.secure === undefined ? true : opts.secure;
+  const ttl =
+    opts === undefined || opts.ttlSeconds === undefined ? DEFAULT_COOKIE_TTL : opts.ttlSeconds;
+  return serializeCookie(CSRF_COOKIE_NAME, token, {
+    maxAge: ttl,
+    path: "/",
+    secure: secure,
+    httpOnly: false,
+    sameSite: "lax",
+  });
+}

package/src/csrf.ts

@@ -0,0 +1,46 @@
+// CSRF: double-submit cookie + Origin allowlist — the two halves of the
+// pattern. The token compare is constant-time (length pre-check, then
+// timingSafeEqual); the origin allowlist is a plain string match — Origin
+// is not secret material.
+
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+// base64url(32 random bytes).
+export function generateCsrfToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+// Double-submit: the cookie token and the submitted (form field / header)
+// token must match byte-for-byte under a constant-time compare.
+export function verifyCsrfToken(
+  cookieToken: string | null,
+  submittedToken: string | null,
+): boolean {
+  if (cookieToken === null || submittedToken === null) {
+    return false;
+  }
+  const a = Buffer.from(cookieToken, "utf8");
+  const b = Buffer.from(submittedToken, "utf8");
+  // timingSafeEqual throws on length mismatch — length pre-check.
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+// Origin check for state-changing requests (the other CSRF half): the
+// request's Origin header must appear verbatim in the allowlist.
+export function verifyRequestOrigin(
+  originHeader: string | null,
+  allowedOrigins: string[],
+): boolean {
+  if (originHeader === null) {
+    return false;
+  }
+  for (let i = 0; i < allowedOrigins.length; i++) {
+    if (allowedOrigins[i] === originHeader) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/encoding.ts

@@ -0,0 +1,78 @@
+// Byte <-> text helpers shared across the auth primitives.
+//
+// - Hex goes through a lookup table: `number.toString(16)` is SC2012-fenced
+//   under scriptc (probe finding from the hono/jwt attempt), and
+//   `Buffer.toString("hex")` on variable digests is avoided for the same
+//   class of reason — the table is deterministic.
+// - base64url goes through Buffer (`Buffer.from(bytes).toString("base64url")`
+//   — probe-verified static in scriptc 0.3.3). Output is unpadded, which is
+//   what session tokens, PKCE challenges and JWS all require.
+// - base32 is a 40-LoC RFC 4648 hand-roll (standard alphabet, no padding on
+//   encode, padding/lowercase tolerated on decode). It exists only for TOTP.
+
+const HEX_DIGITS = "0123456789abcdef";
+
+export function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX_DIGITS[b >>> 4] + HEX_DIGITS[b & 15];
+  }
+  return out;
+}
+
+export function b64urlEncode(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function b64urlDecode(text: string): Buffer {
+  return Buffer.from(text, "base64url");
+}
+
+const B32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+// RFC 4648 base32, no padding emitted (otpauth secrets are unpadded).
+export function base32Encode(bytes: Uint8Array): string {
+  let out = "";
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      out += B32_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    out += B32_ALPHABET[(value << (5 - bits)) & 31];
+  }
+  return out;
+}
+
+// Tolerates `=` padding and lowercase input; returns null on any character
+// outside the RFC 4648 alphabet (null-on-invalid — this is attacker input
+// when it comes from a stored secret or a user-typed key).
+export function base32Decode(text: string): Uint8Array | null {
+  const upper = text.toUpperCase();
+  let bits = 0;
+  let value = 0;
+  const out: number[] = [];
+  for (let i = 0; i < upper.length; i++) {
+    const ch = upper[i];
+    if (ch === "=") {
+      break;
+    }
+    const idx = B32_ALPHABET.indexOf(ch);
+    if (idx < 0) {
+      return null;
+    }
+    value = (value << 5) | idx;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 255);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(out);
+}

package/src/errors.ts

@@ -0,0 +1,8 @@
+// Code-string errors for caller bugs on the sign/exchange paths. Verify
+// paths never throw — they return null/false — so these codes only fire for
+// programmer error: missing key material, an alg the package does not sign,
+// or malformed parameters.
+
+export function authError(code: string, detail: string): Error {
+  return new Error(code + ": " + detail);
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// @chttp/auth — public surface. Plain async functions over node:crypto:
+// sessions (Lucia pattern), cookies, scrypt passwords, double-submit CSRF,
+// HS256/ES256 JWT, OAuth2 authorization-code + PKCE, TOTP. Zero runtime
+// dependencies; the schema seam is a local StandardSchemaV1 twin.
+
+export {
+  generateSessionToken,
+  hashToken,
+  createSession,
+  validateSessionToken,
+  invalidateSession,
+  invalidateAllUserSessions,
+} from "./session.ts";
+export type {
+  SessionRecord,
+  SessionRecordData,
+  SessionStore,
+  SessionStoreCore,
+  SessionOpts,
+} from "./session.ts";
+export { MemorySessionStore, MemorySessionStoreCore } from "./memory-store.ts";
+
+export {
+  serializeCookie,
+  readCookie,
+  buildSessionCookie,
+  buildExpiredSessionCookie,
+  buildCsrfCookie,
+  SESSION_COOKIE_NAME,
+  CSRF_COOKIE_NAME,
+} from "./cookie.ts";
+export type { CookieAttrs, SessionCookieOpts } from "./cookie.ts";
+
+export { hashPassword, verifyPassword } from "./password.ts";
+export type { PasswordOpts } from "./password.ts";
+
+export { generateCsrfToken, verifyCsrfToken, verifyRequestOrigin } from "./csrf.ts";
+
+export { signJwt, verifyJwt, verifyJwtWith } from "./jwt.ts";
+export type { SignJwtOpts, VerifyJwtOpts } from "./jwt.ts";
+
+export {
+  generateState,
+  generateCodeVerifier,
+  codeChallenge,
+  createAuthorizationURL,
+  exchangeCodeForTokens,
+  fetchUserInfo,
+  fetchUserInfoWith,
+} from "./oauth.ts";
+export type { OAuthProvider, TokenSet, AuthorizeParams, ExchangeParams } from "./oauth.ts";
+export { googleProvider, githubProvider, discordProvider } from "./providers.ts";
+
+export { generateTotpSecret, totpAuthUri, verifyTotp } from "./totp.ts";
+export type { TotpUriOpts, VerifyTotpOpts } from "./totp.ts";
+
+export { base32Encode, base32Decode, toHex, b64urlEncode, b64urlDecode } from "./encoding.ts";
+
+export { authError } from "./errors.ts";
+export { runSchema } from "./types.ts";
+export type { StandardSchemaV1, InferOutput } from "./types.ts";