@chttp/auth 0.0.0-stage → 0.2.0

package/dist/esm/jwt.js

@@ -0,0 +1,160 @@
+// 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 { authError } from "./errors.js";
+import { b64urlDecode, b64urlEncode } from "./encoding.js";
+import { runSchema } from "./types.js";
+function inferAlg(key) {
+    return typeof key === "string" ? "HS256" : "ES256";
+}
+export function signJwt(payload, key, opts) {
+    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 = {};
+    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, expected) {
+    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, key, opts) {
+    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"));
+        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"));
+        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(token, key, schema, opts) {
+    const claims = verifyJwt(token, key, opts);
+    if (claims === null) {
+        return null;
+    }
+    const out = await runSchema(schema, claims);
+    if (out === null) {
+        return null;
+    }
+    return out;
+}

package/dist/esm/memory-store.d.ts

@@ -0,0 +1,16 @@
+import type { SessionRecordData } from "./session.ts";
+export declare class MemorySessionStoreCore {
+    _records: Map<string, SessionRecordData>;
+    _now: () => number;
+    constructor(now?: () => number);
+    _sweep(key: string, record: SessionRecordData): SessionRecordData | null;
+    get(key: string): SessionRecordData | null;
+    set(record: SessionRecordData): void;
+    updateExpiry(key: string, expiresAt: number): void;
+    delete(key: string): void;
+    deleteAllForUser(userId: string): void;
+    get size(): number;
+}
+export interface MemorySessionStore<_A> extends MemorySessionStoreCore {
+}
+export declare const MemorySessionStore: typeof MemorySessionStoreCore;

package/dist/esm/memory-store.js

@@ -0,0 +1,59 @@
+// 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.
+export class MemorySessionStoreCore {
+    _records;
+    _now;
+    // `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) {
+        this._records = new Map();
+        this._now = now === undefined ? Date.now : now;
+    }
+    _sweep(key, record) {
+        if (this._now() >= record.expiresAt) {
+            this._records.delete(key);
+            return null;
+        }
+        return record;
+    }
+    get(key) {
+        const r = this._records.get(key);
+        if (r === undefined) {
+            return null;
+        }
+        return this._sweep(key, r);
+    }
+    set(record) {
+        this._records.set(record.key, record);
+    }
+    updateExpiry(key, expiresAt) {
+        const r = this._records.get(key);
+        if (r === undefined) {
+            return;
+        }
+        r.expiresAt = expiresAt;
+    }
+    delete(key) {
+        this._records.delete(key);
+    }
+    deleteAllForUser(userId) {
+        const doomed = [];
+        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() {
+        return this._records.size;
+    }
+}
+export const MemorySessionStore = MemorySessionStoreCore;

package/dist/esm/oauth.d.ts

@@ -0,0 +1,42 @@
+import type { StandardSchemaV1 } from "./types.ts";
+export interface OAuthProvider {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    userInfoEndpoint: string | null;
+    scope: string[];
+    usePkce: boolean;
+}
+export declare function generateState(): string;
+export declare function generateCodeVerifier(): string;
+export declare function codeChallenge(verifier: string): string;
+export interface AuthorizeParams {
+    state: string;
+    codeVerifier: string | null;
+    extraQuery?: {
+        [k: string]: string;
+    };
+}
+export declare function createAuthorizationURL(provider: OAuthProvider, clientId: string, redirectURI: string, params: AuthorizeParams): string;
+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;
+    };
+}
+export interface ExchangeParams {
+    code: string;
+    clientId: string;
+    clientSecret: string | null;
+    redirectURI: string;
+    codeVerifier: string | null;
+}
+export declare function exchangeCodeForTokens(provider: OAuthProvider, params: ExchangeParams): Promise<TokenSet | null>;
+export declare function fetchUserInfo(provider: OAuthProvider, accessToken: string): Promise<{
+    [k: string]: unknown;
+} | null>;
+export declare function fetchUserInfoWith<Schema extends StandardSchemaV1>(provider: OAuthProvider, accessToken: string, schema: Schema): Promise<StandardSchemaV1.InferOutput<Schema> | null>;

package/dist/esm/oauth.js

@@ -0,0 +1,184 @@
+// 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.js";
+import { runSchema } from "./types.js";
+export function generateState() {
+    return b64urlEncode(randomBytes(32));
+}
+// RFC 7636: verifier is 43-128 chars of unreserved; base64url(32 bytes)
+// yields exactly 43.
+export function generateCodeVerifier() {
+    return b64urlEncode(randomBytes(32));
+}
+// S256: base64url(sha256(verifier)), no padding (Node's base64url is
+// already unpadded).
+export function codeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest().toString("base64url");
+}
+export function createAuthorizationURL(provider, clientId, redirectURI, params) {
+    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();
+}
+function strOrNull(v) {
+    return typeof v === "string" ? v : null;
+}
+function numOrNull(v) {
+    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, text) {
+    if (contentType.indexOf("json") >= 0) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    const params = new URLSearchParams(text);
+    const raw = {};
+    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, params) {
+    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 = {};
+    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;
+    try {
+        res = await fetch(provider.tokenEndpoint, {
+            method: "POST",
+            headers: headers,
+            body: body.toString(),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok) {
+        return null;
+    }
+    let text;
+    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 = {
+        access_token: accessToken,
+        token_type: strOrNull(raw["token_type"]) === null ? "" : strOrNull(raw["token_type"]),
+        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, accessToken) {
+    if (provider.userInfoEndpoint === null) {
+        return null;
+    }
+    const headers = {};
+    headers["authorization"] = "Bearer " + accessToken;
+    headers["accept"] = "application/json";
+    let res;
+    try {
+        res = await fetch(provider.userInfoEndpoint, { headers: headers });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok) {
+        return null;
+    }
+    let text;
+    try {
+        text = await res.text();
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        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(provider, accessToken, schema) {
+    const info = await fetchUserInfo(provider, accessToken);
+    if (info === null) {
+        return null;
+    }
+    const out = await runSchema(schema, info);
+    if (out === null) {
+        return null;
+    }
+    return out;
+}

package/dist/esm/password.d.ts

@@ -0,0 +1,7 @@
+export interface PasswordOpts {
+    N?: number;
+    r?: number;
+    p?: number;
+}
+export declare function hashPassword(password: string, opts?: PasswordOpts): string;
+export declare function verifyPassword(password: string, stored: string): boolean;

package/dist/esm/password.js

@@ -0,0 +1,103 @@
+// 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 function hashPassword(password, opts) {
+    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) {
+    scryptSync(password, Buffer.from("cutils-auth-dummy-salt", "utf8"), KEYLEN, {
+        N: DEFAULT_N,
+        r: DEFAULT_R,
+        p: DEFAULT_P,
+        maxmem: MAXMEM,
+    });
+}
+function parseParam(s) {
+    if (!/^[0-9]+$/.test(s)) {
+        return -1;
+    }
+    return Number(s);
+}
+export function verifyPassword(password, stored) {
+    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;
+    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/dist/esm/providers.d.ts

@@ -0,0 +1,4 @@
+import type { OAuthProvider } from "./oauth.ts";
+export declare const googleProvider: OAuthProvider;
+export declare const githubProvider: OAuthProvider;
+export declare const discordProvider: OAuthProvider;

package/dist/esm/providers.js

@@ -0,0 +1,27 @@
+// 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).
+// OIDC: openid email profile; PKCE on.
+export const googleProvider = {
+    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 = {
+    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 = {
+    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,
+};

package/dist/esm/session.d.ts

@@ -0,0 +1,29 @@
+export interface SessionRecordData {
+    key: string;
+    userId: string;
+    expiresAt: number;
+    attributes: unknown;
+}
+export interface SessionRecord<A> extends SessionRecordData {
+    attributes: A | null;
+}
+export interface SessionStoreCore {
+    get(key: string): unknown;
+    set(record: SessionRecordData): unknown;
+    updateExpiry(key: string, expiresAt: number): unknown;
+    delete(key: string): unknown;
+    deleteAllForUser(userId: string): unknown;
+}
+export interface SessionStore<_A> extends SessionStoreCore {
+}
+export interface SessionOpts {
+    ttlSeconds?: number;
+    extensionThresholdSeconds?: number;
+    nowMs?: number;
+}
+export declare function generateSessionToken(): string;
+export declare function hashToken(token: string): string;
+export declare function createSession(store: SessionStoreCore, token: string, userId: string, attributes: unknown, opts?: SessionOpts): Promise<SessionRecordData>;
+export declare function validateSessionToken(store: SessionStoreCore, token: string, opts?: SessionOpts): Promise<SessionRecordData | null>;
+export declare function invalidateSession(store: SessionStoreCore, token: string): Promise<void>;
+export declare function invalidateAllUserSessions(store: SessionStoreCore, userId: string): Promise<void>;