@chttp/auth 0.0.0-stage → 0.2.0

package/src/jwt.ts

@@ -0,0 +1,200 @@
+// JWT — JWS compact serialization only. ~120 LoC over node:crypto; no JWE,
+// no JWKS machinery, no EdDSA in v1 (follow-up tickets).
+//
+// - alg comes from the key type: string => HS256 secret, KeyObject =>
+//   ES256 P-256 (the spec's v2 path). Overridable via opts.alg; verify
+//   enforces the expected alg, so there is no alg-confusion window and
+//   "none" is hard-rejected.
+// - ES256 IS RECOGNIZED BUT NOT LOWERABLE TODAY: scriptc 0.3.3's static
+//   node:crypto slice covers hashing, randomness and secret KeyObjects —
+//   createSign/createVerify/createPrivateKey/createPublicKey have no
+//   lowering (asymmetric ops need a public-key stack the runtime lacks).
+//   signJwt({ alg: "ES256" }) throws E_BAD_ALG and verifyJwt rejects ES256
+//   tokens with null; the `string | KeyObject` signature stays so the
+//   feature slots in upstream without a breaking change. When it lands it
+//   must sign/verify with dsaEncoding "ieee-p1363" (JWS carries raw R||S,
+//   not DER — the classic interop bug; RFC 7515 A.3 vector is in tests).
+// - Verify is null-on-invalid for ANY failure: bad format, wrong alg, bad
+//   signature, expired/nbf, wrong issuer/audience. Never throws — callers
+//   branch on null instead of try/catching attacker input. Sign throws on
+//   caller bugs (missing/wrong key) because those are programmer errors.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { KeyObject } from "node:crypto";
+import { authError } from "./errors.ts";
+import { b64urlDecode, b64urlEncode } from "./encoding.ts";
+import { runSchema } from "./types.ts";
+import type { StandardSchemaV1 } from "./types.ts";
+
+export interface SignJwtOpts {
+  alg?: "HS256" | "ES256"; // inferred from key type if omitted; ES256 -> E_BAD_ALG
+  expiresInSeconds?: number; // sets exp = iat + this
+  issuer?: string;
+  audience?: string;
+}
+
+export interface VerifyJwtOpts {
+  alg?: "HS256" | "ES256"; // inferred from key type if omitted
+  issuer?: string;
+  audience?: string;
+  clockToleranceSeconds?: number; // default 0; applies to exp and nbf
+}
+
+function inferAlg(key: string | KeyObject): string {
+  return typeof key === "string" ? "HS256" : "ES256";
+}
+
+export function signJwt(
+  payload: { [k: string]: unknown },
+  key: string | KeyObject,
+  opts?: SignJwtOpts,
+): string {
+  const o = opts === undefined || opts === null ? {} : opts;
+  const alg = o.alg === undefined ? inferAlg(key) : o.alg;
+  if (alg === "ES256") {
+    throw authError(
+      "E_BAD_ALG",
+      "ES256 needs node:crypto asymmetric ops, which scriptc 0.3.3 does not lower",
+    );
+  }
+  if (alg !== "HS256") {
+    throw authError("E_BAD_ALG", "signJwt supports HS256 only");
+  }
+  if (typeof key !== "string") {
+    throw authError("E_NO_KEY", "HS256 requires a string secret");
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const claims: { [k: string]: unknown } = {};
+  const keys = Object.keys(payload);
+  for (let i = 0; i < keys.length; i++) {
+    claims[keys[i]] = payload[keys[i]];
+  }
+  claims["iat"] = now;
+  if (o.expiresInSeconds !== undefined) {
+    claims["exp"] = now + o.expiresInSeconds;
+  }
+  if (o.issuer !== undefined) {
+    claims["iss"] = o.issuer;
+  }
+  if (o.audience !== undefined) {
+    claims["aud"] = o.audience;
+  }
+  const header = { alg: alg, typ: "JWT" };
+  const input =
+    b64urlEncode(Buffer.from(JSON.stringify(header), "utf8")) +
+    "." +
+    b64urlEncode(Buffer.from(JSON.stringify(claims), "utf8"));
+  const sig = createHmac("sha256", key).update(input).digest();
+  return input + "." + b64urlEncode(sig);
+}
+
+function audMatches(aud: unknown, expected: string): boolean {
+  if (typeof aud === "string") {
+    return aud === expected;
+  }
+  if (Array.isArray(aud)) {
+    for (let i = 0; i < aud.length; i++) {
+      if (aud[i] === expected) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// null on ANY failure: bad format, wrong alg, bad signature, expired, wrong
+// issuer/audience. alg "none" always rejected. Never throws.
+export function verifyJwt(
+  token: string,
+  key: string | KeyObject,
+  opts?: VerifyJwtOpts,
+): { [k: string]: unknown } | null {
+  const o = opts === undefined || opts === null ? {} : opts;
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+    const expectedAlg = o.alg === undefined ? inferAlg(key) : o.alg;
+    const headerRaw = JSON.parse(b64urlDecode(parts[0]).toString("utf8")) as {
+      [k: string]: unknown;
+    };
+    const alg = headerRaw["alg"];
+    if (alg !== expectedAlg) {
+      // Covers "none", alg-confusion, and any unsupported alg.
+      return null;
+    }
+    if (alg !== "HS256" || typeof key !== "string") {
+      // ES256 (or anything non-HS256) is unverifiable in this build; a
+      // KeyObject key has no usable signing surface either.
+      return null;
+    }
+    const input = parts[0] + "." + parts[1];
+    const sigBytes = b64urlDecode(parts[2]);
+    const expected = createHmac("sha256", key).update(input).digest();
+    // timingSafeEqual throws on length mismatch — length pre-check.
+    if (expected.length !== sigBytes.length) {
+      return null;
+    }
+    if (!timingSafeEqual(expected, sigBytes)) {
+      return null;
+    }
+    const claims = JSON.parse(b64urlDecode(parts[1]).toString("utf8")) as { [k: string]: unknown };
+    if (claims === null || typeof claims !== "object" || Array.isArray(claims)) {
+      return null;
+    }
+    const tol = o.clockToleranceSeconds === undefined ? 0 : o.clockToleranceSeconds;
+    const now = Math.floor(Date.now() / 1000);
+    const exp = claims["exp"];
+    if (exp !== undefined) {
+      if (typeof exp !== "number") {
+        return null;
+      }
+      if (now - tol >= exp) {
+        return null; // expired
+      }
+    }
+    const nbf = claims["nbf"];
+    if (nbf !== undefined) {
+      if (typeof nbf !== "number") {
+        return null;
+      }
+      if (now + tol < nbf) {
+        return null; // not yet valid
+      }
+    }
+    if (o.issuer !== undefined) {
+      if (claims["iss"] !== o.issuer) {
+        return null;
+      }
+    }
+    if (o.audience !== undefined) {
+      if (!audMatches(claims["aud"], o.audience)) {
+        return null;
+      }
+    }
+    return claims;
+  } catch {
+    return null;
+  }
+}
+
+// val-first twin of verifyJwt: verifies, then parses the claims through any
+// StandardSchemaV1 (@chttp/val, valibot, ...). Returns the typed claims or
+// null — the positional-schema convention (`prepare(sql, schema)`).
+export async function verifyJwtWith<Schema extends StandardSchemaV1>(
+  token: string,
+  key: string | KeyObject,
+  schema: Schema,
+  opts?: VerifyJwtOpts,
+): Promise<StandardSchemaV1.InferOutput<Schema> | null> {
+  const claims = verifyJwt(token, key, opts);
+  if (claims === null) {
+    return null;
+  }
+  const out = await runSchema(schema, claims);
+  if (out === null) {
+    return null;
+  }
+  return out as StandardSchemaV1.InferOutput<Schema>;
+}

package/src/memory-store.ts

@@ -0,0 +1,75 @@
+// MemorySessionStore — dev/test SessionStore over a Map (the 0.3.3 probe
+// lifted the Map/Set ban; same exception @chttp/cache uses).
+//
+// NOT for production. Process memory loses sessions on restart and does not
+// share them across replicas — ship a real adapter (the @cutils/sqlite
+// `key TEXT PRIMARY KEY` shape) instead. Dev only.
+
+import type { SessionRecordData } from "./session.ts";
+
+export class MemorySessionStoreCore {
+  _records: Map<string, SessionRecordData>;
+  _now: () => number;
+
+  // `now` is a constructor-only test seam (fake clock), deliberately NOT an
+  // options-record member — function values inside records degrade
+  // instantiation under scriptc.
+  constructor(now?: () => number) {
+    this._records = new Map<string, SessionRecordData>();
+    this._now = now === undefined ? Date.now : now;
+  }
+
+  _sweep(key: string, record: SessionRecordData): SessionRecordData | null {
+    if (this._now() >= record.expiresAt) {
+      this._records.delete(key);
+      return null;
+    }
+    return record;
+  }
+
+  get(key: string): SessionRecordData | null {
+    const r = this._records.get(key);
+    if (r === undefined) {
+      return null;
+    }
+    return this._sweep(key, r);
+  }
+
+  set(record: SessionRecordData): void {
+    this._records.set(record.key, record);
+  }
+
+  updateExpiry(key: string, expiresAt: number): void {
+    const r = this._records.get(key);
+    if (r === undefined) {
+      return;
+    }
+    r.expiresAt = expiresAt;
+  }
+
+  delete(key: string): void {
+    this._records.delete(key);
+  }
+
+  deleteAllForUser(userId: string): void {
+    const doomed: string[] = [];
+    for (const e of this._records.entries()) {
+      if (e[1].userId === userId) {
+        doomed.push(e[0]);
+      }
+    }
+    for (let i = 0; i < doomed.length; i++) {
+      this._records.delete(doomed[i]);
+    }
+  }
+
+  get size(): number {
+    return this._records.size;
+  }
+}
+
+// Phantom-generic alias over the non-generic core class — generic class
+// parameters degrade instances to methodless shells under scriptc 0.3.x
+// (the `Cache<V>`/`CacheCore` pattern).
+export interface MemorySessionStore<_A> extends MemorySessionStoreCore {}
+export const MemorySessionStore = MemorySessionStoreCore;

package/src/oauth.ts

@@ -0,0 +1,238 @@
+// OAuth2 authorization-code + PKCE (RFC 6749 + RFC 7636). Providers are
+// plain records — no registry, no plugin bus; adding one is a 15-LoC record
+// in user code. The token exchange is a POST x-www-form-urlencoded with
+// HTTP-basic client auth; responses parse as JSON OR form-urlencoded (RFC
+// 6749 permits both). Exchange/userinfo return null on non-2xx or missing
+// fields — never throw, never surface provider error bodies as exceptions.
+
+import { createHash, randomBytes } from "node:crypto";
+import { b64urlEncode } from "./encoding.ts";
+import { runSchema } from "./types.ts";
+import type { StandardSchemaV1 } from "./types.ts";
+
+export interface OAuthProvider {
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  userInfoEndpoint: string | null; // GitHub: non-OIDC /user works
+  scope: string[]; // joined with spaces
+  usePkce: boolean;
+}
+
+export function generateState(): string {
+  return b64urlEncode(randomBytes(32));
+}
+
+// RFC 7636: verifier is 43-128 chars of unreserved; base64url(32 bytes)
+// yields exactly 43.
+export function generateCodeVerifier(): string {
+  return b64urlEncode(randomBytes(32));
+}
+
+// S256: base64url(sha256(verifier)), no padding (Node's base64url is
+// already unpadded).
+export function codeChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier).digest().toString("base64url");
+}
+
+export interface AuthorizeParams {
+  state: string;
+  codeVerifier: string | null; // ignored when provider.usePkce is false
+  extraQuery?: { [k: string]: string }; // e.g. { prompt: "consent" }
+}
+
+export function createAuthorizationURL(
+  provider: OAuthProvider,
+  clientId: string,
+  redirectURI: string,
+  params: AuthorizeParams,
+): string {
+  const url = new URL(provider.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectURI);
+  url.searchParams.set("scope", provider.scope.join(" "));
+  url.searchParams.set("state", params.state);
+  if (provider.usePkce && params.codeVerifier !== null) {
+    url.searchParams.set("code_challenge", codeChallenge(params.codeVerifier));
+    url.searchParams.set("code_challenge_method", "S256");
+  }
+  if (params.extraQuery !== undefined && params.extraQuery !== null) {
+    const keys = Object.keys(params.extraQuery);
+    for (let i = 0; i < keys.length; i++) {
+      url.searchParams.set(keys[i], params.extraQuery[keys[i]]);
+    }
+  }
+  return url.toString();
+}
+
+export interface TokenSet {
+  access_token: string;
+  token_type: string;
+  refresh_token: string | null;
+  expires_in: number | null;
+  scope: string | null;
+  id_token: string | null;
+  raw: { [k: string]: unknown }; // full provider response
+}
+
+export interface ExchangeParams {
+  code: string;
+  clientId: string;
+  clientSecret: string | null;
+  redirectURI: string;
+  codeVerifier: string | null;
+}
+
+function strOrNull(v: unknown): string | null {
+  return typeof v === "string" ? v : null;
+}
+
+function numOrNull(v: unknown): number | null {
+  return typeof v === "number" ? v : null;
+}
+
+// Parses a token-endpoint body by content-type: JSON, else
+// x-www-form-urlencoded (RFC 6749 permits both).
+function parseTokenBody(contentType: string, text: string): { [k: string]: unknown } | null {
+  if (contentType.indexOf("json") >= 0) {
+    try {
+      const parsed = JSON.parse(text) as { [k: string]: unknown };
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  const params = new URLSearchParams(text);
+  const raw: { [k: string]: unknown } = {};
+  for (const name of params.keys()) {
+    const v = params.get(name);
+    if (v !== null) {
+      raw[name] = v;
+    }
+  }
+  if (raw["access_token"] === undefined) {
+    return null;
+  }
+  return raw;
+}
+
+export async function exchangeCodeForTokens(
+  provider: OAuthProvider,
+  params: ExchangeParams,
+): Promise<TokenSet | null> {
+  const body = new URLSearchParams();
+  body.set("grant_type", "authorization_code");
+  body.set("code", params.code);
+  body.set("redirect_uri", params.redirectURI);
+  body.set("client_id", params.clientId);
+  if (params.codeVerifier !== null) {
+    body.set("code_verifier", params.codeVerifier);
+  }
+  const headers: { [k: string]: string } = {};
+  headers["content-type"] = "application/x-www-form-urlencoded";
+  headers["accept"] = "application/json";
+  if (params.clientSecret !== null) {
+    // RFC 6749 §2.3.1: client auth via HTTP basic.
+    body.set("client_secret", params.clientSecret);
+    headers["authorization"] =
+      "Basic " +
+      Buffer.from(params.clientId + ":" + params.clientSecret, "utf8").toString("base64");
+  }
+  let res: Response;
+  try {
+    res = await fetch(provider.tokenEndpoint, {
+      method: "POST",
+      headers: headers,
+      body: body.toString(),
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) {
+    return null;
+  }
+  let text: string;
+  let contentType = "";
+  try {
+    const ct = res.headers.get("content-type");
+    contentType = ct === null ? "" : ct;
+    text = await res.text();
+  } catch {
+    return null;
+  }
+  const raw = parseTokenBody(contentType, text);
+  if (raw === null) {
+    return null;
+  }
+  const accessToken = raw["access_token"];
+  if (typeof accessToken !== "string" || accessToken === "") {
+    return null;
+  }
+  const out: TokenSet = {
+    access_token: accessToken,
+    token_type:
+      strOrNull(raw["token_type"]) === null ? "" : (strOrNull(raw["token_type"]) as string),
+    refresh_token: strOrNull(raw["refresh_token"]),
+    expires_in: numOrNull(raw["expires_in"]),
+    scope: strOrNull(raw["scope"]),
+    id_token: strOrNull(raw["id_token"]),
+    raw: raw,
+  };
+  return out;
+}
+
+export async function fetchUserInfo(
+  provider: OAuthProvider,
+  accessToken: string,
+): Promise<{ [k: string]: unknown } | null> {
+  if (provider.userInfoEndpoint === null) {
+    return null;
+  }
+  const headers: { [k: string]: string } = {};
+  headers["authorization"] = "Bearer " + accessToken;
+  headers["accept"] = "application/json";
+  let res: Response;
+  try {
+    res = await fetch(provider.userInfoEndpoint, { headers: headers });
+  } catch {
+    return null;
+  }
+  if (!res.ok) {
+    return null;
+  }
+  let text: string;
+  try {
+    text = await res.text();
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(text) as { [k: string]: unknown };
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Schema-parsed userinfo — same StandardSchemaV1 seam as verifyJwtWith.
+export async function fetchUserInfoWith<Schema extends StandardSchemaV1>(
+  provider: OAuthProvider,
+  accessToken: string,
+  schema: Schema,
+): Promise<StandardSchemaV1.InferOutput<Schema> | null> {
+  const info = await fetchUserInfo(provider, accessToken);
+  if (info === null) {
+    return null;
+  }
+  const out = await runSchema(schema, info);
+  if (out === null) {
+    return null;
+  }
+  return out as StandardSchemaV1.InferOutput<Schema>;
+}

package/src/password.ts

@@ -0,0 +1,116 @@
+// scrypt password hashing, self-describing format:
+//   "scrypt:N:r:p:saltB64:hashB64"
+// verifyPassword reads the parameters from the string, so parameter upgrades
+// don't invalidate old hashes; hashPassword writes today's OWASP defaults
+// (N=2^17, r=8, p=1, 64-byte key, 16-byte salt). The format prefix leaves
+// room for a future memory-hard successor (e.g. argon2) to slot in.
+
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+
+const DEFAULT_N = 131072; // 2^17 — OWASP Password Storage Cheat Sheet
+const DEFAULT_R = 8;
+const DEFAULT_P = 1;
+const KEYLEN = 64;
+const SALT_BYTES = 16;
+// scrypt memory is ~128*N*r bytes: 2^17*8*128 = 128 MiB, past Node's 32 MiB
+// default maxmem — raised explicitly.
+const MAXMEM = 256 * 1024 * 1024;
+
+export interface PasswordOpts {
+  N?: number;
+  r?: number;
+  p?: number;
+}
+
+export function hashPassword(password: string, opts?: PasswordOpts): string {
+  let N = DEFAULT_N;
+  let r = DEFAULT_R;
+  let p = DEFAULT_P;
+  if (opts !== undefined && opts !== null) {
+    if (opts.N !== undefined) {
+      N = opts.N;
+    }
+    if (opts.r !== undefined) {
+      r = opts.r;
+    }
+    if (opts.p !== undefined) {
+      p = opts.p;
+    }
+  }
+  const salt = randomBytes(SALT_BYTES);
+  const hash = scryptSync(password, salt, KEYLEN, {
+    N: N,
+    r: r,
+    p: p,
+    maxmem: MAXMEM,
+  });
+  return (
+    "scrypt:" +
+    N +
+    ":" +
+    r +
+    ":" +
+    p +
+    ":" +
+    salt.toString("base64") +
+    ":" +
+    hash.toString("base64")
+  );
+}
+
+// Burns one scrypt at default parameters so malformed/corrupt stored rows
+// cost the same as a real verify — flattens the oracle between "row doesn't
+// parse" and "password wrong".
+function dummyHash(password: string): void {
+  scryptSync(password, Buffer.from("cutils-auth-dummy-salt", "utf8"), KEYLEN, {
+    N: DEFAULT_N,
+    r: DEFAULT_R,
+    p: DEFAULT_P,
+    maxmem: MAXMEM,
+  });
+}
+
+function parseParam(s: string): number {
+  if (!/^[0-9]+$/.test(s)) {
+    return -1;
+  }
+  return Number(s);
+}
+
+export function verifyPassword(password: string, stored: string): boolean {
+  const parts = stored.split(":");
+  if (parts.length !== 6 || parts[0] !== "scrypt") {
+    dummyHash(password);
+    return false;
+  }
+  const N = parseParam(parts[1]);
+  const r = parseParam(parts[2]);
+  const p = parseParam(parts[3]);
+  if (N <= 0 || r <= 0 || p <= 0) {
+    dummyHash(password);
+    return false;
+  }
+  const salt = Buffer.from(parts[4], "base64");
+  const expected = Buffer.from(parts[5], "base64");
+  if (salt.length === 0 || expected.length === 0) {
+    dummyHash(password);
+    return false;
+  }
+  let hash: Buffer;
+  try {
+    hash = scryptSync(password, salt, expected.length, {
+      N: N,
+      r: r,
+      p: p,
+      maxmem: MAXMEM,
+    });
+  } catch {
+    dummyHash(password);
+    return false;
+  }
+  // timingSafeEqual throws on length mismatch — length pre-check.
+  if (hash.length !== expected.length) {
+    return false;
+  }
+  return timingSafeEqual(hash, expected);
+}

package/src/providers.ts

@@ -0,0 +1,32 @@
+// Provider presets: plain records, ~15 LoC each — google, github, discord,
+// the top three. A new provider is a 15-LoC record in user code; the
+// package deliberately grows no registry (the better-auth trap).
+
+import type { OAuthProvider } from "./oauth.ts";
+
+// OIDC: openid email profile; PKCE on.
+export const googleProvider: OAuthProvider = {
+  authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
+  tokenEndpoint: "https://oauth2.googleapis.com/token",
+  userInfoEndpoint: "https://openidconnect.googleapis.com/v1/userinfo",
+  scope: ["openid", "email", "profile"],
+  usePkce: true,
+};
+
+// Non-OIDC /user endpoint; PKCE is tolerated (ignored) by GitHub.
+export const githubProvider: OAuthProvider = {
+  authorizationEndpoint: "https://github.com/login/oauth/authorize",
+  tokenEndpoint: "https://github.com/login/oauth/access_token",
+  userInfoEndpoint: "https://api.github.com/user",
+  scope: ["read:user", "user:email"],
+  usePkce: true,
+};
+
+// Discord supports PKCE for public clients (clientSecret may be null).
+export const discordProvider: OAuthProvider = {
+  authorizationEndpoint: "https://discord.com/oauth2/authorize",
+  tokenEndpoint: "https://discord.com/api/oauth2/token",
+  userInfoEndpoint: "https://discord.com/api/users/@me",
+  scope: ["identify", "email"],
+  usePkce: true,
+};