@willyim/idp 0.1.0

package/dist/src/client.js

@@ -0,0 +1,155 @@
+/**
+ * Layer 0 — the OIDC relying party. Everything on the wire lives here: the
+ * discovery document, the authorization-code flow with PKCE, refresh, userinfo,
+ * and RP-initiated logout. No sessions, no cookies, no storage.
+ *
+ * `fetch` + WebCrypto only, so it runs anywhere the platform is web-standard.
+ */
+import { normalizeClaims } from "./claims.js";
+import { randomToken, sha256Base64url } from "./crypto.js";
+export const DEFAULT_SCOPES = ["openid", "profile", "email", "offline_access"];
+export class IdpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "IdpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** A fresh PKCE verifier and its S256 challenge. */
+export async function createPkce() {
+    const codeVerifier = randomToken(32);
+    return { codeVerifier, codeChallenge: await sha256Base64url(codeVerifier) };
+}
+export function createIdpClient(options) {
+    const issuer = options.issuer.replace(/\/+$/, "");
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const defaultScopes = options.scopes ?? DEFAULT_SCOPES;
+    let cached = null;
+    /** The discovery document, fetched at most once per client instance. */
+    function discover() {
+        cached ??= (async () => {
+            const url = `${issuer}/.well-known/openid-configuration`;
+            let response;
+            try {
+                response = await doFetch(url);
+            }
+            catch (cause) {
+                cached = null;
+                throw new IdpError(`discovery request to ${url} failed`, 0, cause);
+            }
+            if (!response.ok) {
+                cached = null;
+                throw new IdpError(`discovery failed (${response.status})`, response.status, await text(response));
+            }
+            return (await response.json());
+        })();
+        return cached;
+    }
+    async function token(body, what) {
+        const { token_endpoint } = await discover();
+        body.set("client_id", options.clientId);
+        body.set("client_secret", options.clientSecret);
+        const response = await doFetch(token_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body,
+        });
+        const json = (await response.json().catch(() => null));
+        if (!response.ok || !json) {
+            throw new IdpError(`${what} failed (${response.status})`, response.status, json);
+        }
+        return {
+            accessToken: String(json.access_token ?? ""),
+            tokenType: String(json.token_type ?? "Bearer"),
+            expiresIn: typeof json.expires_in === "number" ? json.expires_in : null,
+            refreshToken: typeof json.refresh_token === "string" ? json.refresh_token : null,
+            idToken: typeof json.id_token === "string" ? json.id_token : null,
+            scope: typeof json.scope === "string" ? json.scope : null,
+        };
+    }
+    return {
+        discover,
+        /** Where to send the browser to log in. */
+        async authorizationUrl(input) {
+            const { authorization_endpoint } = await discover();
+            const url = new URL(authorization_endpoint);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("client_id", options.clientId);
+            url.searchParams.set("redirect_uri", input.redirectUri);
+            url.searchParams.set("scope", (input.scopes ?? defaultScopes).join(" "));
+            url.searchParams.set("state", input.state);
+            url.searchParams.set("code_challenge", input.codeChallenge);
+            url.searchParams.set("code_challenge_method", "S256");
+            if (input.prompt)
+                url.searchParams.set("prompt", input.prompt);
+            if (input.loginHint)
+                url.searchParams.set("login_hint", input.loginHint);
+            return url.toString();
+        },
+        /** Swap the callback `code` for tokens. The verifier proves we started the flow. */
+        exchangeCode(input) {
+            return token(new URLSearchParams({
+                grant_type: "authorization_code",
+                code: input.code,
+                redirect_uri: input.redirectUri,
+                code_verifier: input.codeVerifier,
+            }), "token exchange");
+        },
+        /** Requires `offline_access` at login. Throws `IdpError` once the grant is gone. */
+        refresh(refreshToken) {
+            return token(new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken }), "refresh");
+        },
+        /**
+         * Live claims for an access token. Unlike the id_token — a login-time
+         * snapshot — this reflects permissions and workspaces as they are *now*,
+         * which is how a revocation at the IdP reaches the app.
+         */
+        async userinfo(accessToken) {
+            const { userinfo_endpoint } = await discover();
+            const response = await doFetch(userinfo_endpoint, {
+                headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+            });
+            if (!response.ok) {
+                throw new IdpError(`userinfo failed (${response.status})`, response.status, await text(response));
+            }
+            return normalizeClaims((await response.json()));
+        },
+        /**
+         * RP-initiated logout, built from the `end_session_endpoint` in discovery —
+         * never a hardcoded path. Returns null when there is nothing usable to
+         * redirect to, which is either of:
+         *
+         *  - the IdP advertises no `end_session_endpoint`, or
+         *  - we have no `id_token` to hint with. The spec makes `id_token_hint`
+         *    optional; this IdP does not — it identifies the client from the hint,
+         *    verifies its signature, and reads `sid` out of it to pick the SSO
+         *    session to kill. Without one the request is rejected.
+         *
+         * Callers must treat null as "log out locally and move on" — see
+         * `createIdp().logout`, which does exactly that.
+         *
+         * Note the IdP-side registration this depends on: the OAuth client needs
+         * `enable_end_session` set (better-auth answers 401 `invalid_client`
+         * otherwise) and `redirectTo` must be listed in its
+         * `post_logout_redirect_uris` (an unlisted URI is silently not redirected
+         * to, leaving the visitor at the IdP).
+         */
+        async logoutUrl(input) {
+            const { end_session_endpoint } = await discover();
+            if (!end_session_endpoint || !input.idToken)
+                return null;
+            const url = new URL(end_session_endpoint);
+            url.searchParams.set("id_token_hint", input.idToken);
+            url.searchParams.set("client_id", options.clientId);
+            if (input.redirectTo)
+                url.searchParams.set("post_logout_redirect_uri", input.redirectTo);
+            return url.toString();
+        },
+    };
+}
+function text(response) {
+    return response.text().catch(() => null);
+}

package/dist/src/cookie.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal cookie serialize/parse. `Request`/`Response` give us the headers but
+ * not the codec, and pulling in a cookie library would break the zero-runtime-
+ * dependency rule for a dozen lines.
+ */
+export type CookieOptions = {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+};
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+/** A `Set-Cookie` that expires the cookie immediately. */
+export declare function clearCookie(name: string, options?: CookieOptions): string;
+export declare function parseCookies(header: string | null): Record<string, string>;
+export declare function readCookie(request: Request, name: string): string | null;
+//# sourceMappingURL=cookie.d.ts.map

package/dist/src/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/cookie.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;CACrC,CAAA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAShG;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAE7E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe1E;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExE"}

package/dist/src/cookie.js

@@ -0,0 +1,49 @@
+/**
+ * Minimal cookie serialize/parse. `Request`/`Response` give us the headers but
+ * not the codec, and pulling in a cookie library would break the zero-runtime-
+ * dependency rule for a dozen lines.
+ */
+export function serializeCookie(name, value, options = {}) {
+    const parts = [`${name}=${encodeURIComponent(value)}`];
+    parts.push(`Path=${options.path ?? "/"}`);
+    if (options.domain)
+        parts.push(`Domain=${options.domain}`);
+    if (options.maxAge !== undefined)
+        parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    if (options.httpOnly !== false)
+        parts.push("HttpOnly");
+    if (options.secure !== false)
+        parts.push("Secure");
+    parts.push(`SameSite=${sameSiteLabel(options.sameSite ?? "lax")}`);
+    return parts.join("; ");
+}
+/** A `Set-Cookie` that expires the cookie immediately. */
+export function clearCookie(name, options = {}) {
+    return serializeCookie(name, "", { ...options, maxAge: 0 });
+}
+export function parseCookies(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const pair of header.split(";")) {
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = pair.slice(0, eq).trim();
+        if (!name || name in out)
+            continue;
+        try {
+            out[name] = decodeURIComponent(pair.slice(eq + 1).trim());
+        }
+        catch {
+            // A cookie we can't decode is a cookie we didn't write.
+        }
+    }
+    return out;
+}
+export function readCookie(request, name) {
+    return parseCookies(request.headers.get("cookie"))[name] ?? null;
+}
+function sameSiteLabel(value) {
+    return value === "lax" ? "Lax" : value === "strict" ? "Strict" : "None";
+}

package/dist/src/crypto.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The WebCrypto bits the package needs: random ids, the PKCE challenge, and the
+ * HMAC that signs the session cookie. Everything here is web-standard so the
+ * same code runs on Workers, Node ≥20, Bun and the browser.
+ */
+export declare function base64url(bytes: Uint8Array): string;
+export declare function base64urlEncodeString(value: string): string;
+export declare function base64urlDecodeString(value: string): string;
+/** Cryptographically random base64url string — session ids, state, PKCE verifiers. */
+export declare function randomToken(bytes?: number): string;
+/** The S256 PKCE challenge for a verifier. */
+export declare function sha256Base64url(input: string): Promise<string>;
+/**
+ * Length-independent, content-constant-time string comparison. Both arguments
+ * are base64url HMACs of a fixed length in practice, so the early length exit
+ * leaks nothing an attacker doesn't already know.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+export type Signer = {
+    sign(value: string): Promise<string>;
+    /** `value.signature` if the signature checks out, else null. */
+    unsign(signed: string): Promise<string | null>;
+    /** `${value}.${signature}` */
+    pack(value: string): Promise<string>;
+};
+/**
+ * HMAC-SHA256 over a string, with the imported key memoized per signer. Used to
+ * sign the opaque session id so a forged or tampered cookie is rejected before
+ * the session store is ever touched.
+ */
+export declare function createSigner(secret: string): Signer;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/src/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAInD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,KAAK,SAAK,GAAG,MAAM,CAI9C;AAED,8CAA8C;AAC9C,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK7D;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpC,gEAAgE;IAChE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC9C,8BAA8B;IAC9B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA6BnD"}

package/dist/src/crypto.js

@@ -0,0 +1,76 @@
+/**
+ * The WebCrypto bits the package needs: random ids, the PKCE challenge, and the
+ * HMAC that signs the session cookie. Everything here is web-standard so the
+ * same code runs on Workers, Node ≥20, Bun and the browser.
+ */
+const encoder = new TextEncoder();
+export function base64url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function base64urlEncodeString(value) {
+    return base64url(encoder.encode(value));
+}
+export function base64urlDecodeString(value) {
+    const padding = value.length % 4 === 0 ? "" : "=".repeat(4 - (value.length % 4));
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + padding);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+}
+/** Cryptographically random base64url string — session ids, state, PKCE verifiers. */
+export function randomToken(bytes = 32) {
+    const buffer = new Uint8Array(bytes);
+    crypto.getRandomValues(buffer);
+    return base64url(buffer);
+}
+/** The S256 PKCE challenge for a verifier. */
+export async function sha256Base64url(input) {
+    const digest = await crypto.subtle.digest("SHA-256", encoder.encode(input));
+    return base64url(new Uint8Array(digest));
+}
+/**
+ * Length-independent, content-constant-time string comparison. Both arguments
+ * are base64url HMACs of a fixed length in practice, so the early length exit
+ * leaks nothing an attacker doesn't already know.
+ */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * HMAC-SHA256 over a string, with the imported key memoized per signer. Used to
+ * sign the opaque session id so a forged or tampered cookie is rejected before
+ * the session store is ever touched.
+ */
+export function createSigner(secret) {
+    if (!secret)
+        throw new Error("session.secret is required");
+    let key = null;
+    const getKey = () => (key ??= crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]));
+    async function sign(value) {
+        const signature = await crypto.subtle.sign("HMAC", await getKey(), encoder.encode(value));
+        return base64url(new Uint8Array(signature));
+    }
+    return {
+        sign,
+        pack: async (value) => `${value}.${await sign(value)}`,
+        async unsign(signed) {
+            const dot = signed.lastIndexOf(".");
+            if (dot <= 0)
+                return null;
+            const value = signed.slice(0, dot);
+            const signature = signed.slice(dot + 1);
+            if (!signature)
+                return null;
+            return timingSafeEqual(await sign(value), signature) ? value : null;
+        },
+    };
+}