@9in-io/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.0
+
+- `WebAppAuth` (`@9in-io/sdk/server`): sign-in for server-rendered apps (authorization code +
+  PKCE, with or without a client secret), using only `fetch` and Web Crypto, so it runs on Node,
+  Next.js Edge, Cloudflare Workers, Deno and Bun. `createLogin`, `handleCallback` (state, RFC 9207
+  issuer check and ID token verification), `refresh`, `logoutUrl`, `revoke`, `userInfo`. It's the
+  base of `@9in-io/nextjs`; you keep the transaction and session where you like.
+- `verifyIdToken`: signature, issuer, audience (`azp` with several), expiry and nonce.
+
 ## 0.2.0
 
 Breaking: 9in's wire formats are now snake_case throughout, with ISO 8601 UTC times

package/README.md

@@ -30,6 +30,34 @@ const res = await auth.fetch("https://api.acme.com/orders");
 await auth.logout({ returnTo: location.origin });
 ```
 
+## Sign users in (server-rendered apps)
+
+`WebAppAuth` runs the sign-in on your server: Node, Next.js (also Edge), Cloudflare Workers,
+Deno and Bun. You keep the transaction (between the redirect and the callback) and the session,
+for example in encrypted cookies. With Next.js, `@9in-io/nextjs` does all of that for you.
+
+```ts
+import { WebAppAuth } from "@9in-io/sdk/server";
+
+const auth = new WebAppAuth({
+  issuer: "https://acme.9in.io",
+  clientId: process.env.NINE_CLIENT_ID!,
+  clientSecret: process.env.NINE_CLIENT_SECRET, // confidential apps; leave out for public ones
+  redirectUri: "https://app.acme.com/auth/callback",
+});
+
+// /auth/login
+const { url, transaction } = await auth.createLogin({ returnTo: "/dashboard" });
+// store `transaction` (encrypted, ~15 minutes), then redirect to `url`
+
+// /auth/callback
+const { tokens, claims, returnTo } = await auth.handleCallback(request.url, transaction);
+// claims: the verified ID token (sub, email, name, amr…); tokens: access, refresh, ID token
+
+const fresh = await auth.refresh(tokens.refreshToken!);  // 9in rotates refresh tokens: keep the new one
+const bye = await auth.logoutUrl({ idTokenHint: tokens.idToken, postLogoutRedirectUri: "https://app.acme.com/" });
+```
+
 ## Protect your API (server)
 
 ```ts

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 export { NineError, normalizeIssuer } from "./util.js";
+export { WebAppAuth, type WebAppAuthOptions, type WebLoginOptions, type LoginTransaction, type WebTokenSet, type CallbackResult } from "./web-app.js";
 export interface VerifyOptions {
     /** Your tenant's issuer (exactly as in the token's iss claim). */
     issuer: string;
@@ -39,6 +40,43 @@ export interface AccessTokenClaims {
  * `createTokenVerifier` (hybrid mode) when revocation must take effect at once.
  */
 export declare function verifyAccessToken(token: string | null | undefined, options: VerifyOptions): Promise<AccessTokenClaims>;
+export interface VerifyIdTokenOptions {
+    /** Your tenant's issuer URL. */
+    issuer: string;
+    /** Your application's client ID (the token's audience). */
+    clientId: string;
+    /** The nonce sent with the sign-in request. */
+    nonce?: string | null;
+    /** For tenants whose signing key is a shared (HMAC) secret. */
+    secret?: string;
+    /** Seconds of clock skew allowed (default 30). */
+    clockTolerance?: number;
+    fetch?: typeof fetch;
+    allowInsecureIssuer?: boolean;
+}
+/** Claims of a verified ID token (standard OIDC claims plus your custom profile claims). */
+export interface IdTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    nonce?: string;
+    auth_time?: number;
+    /** How the user signed in, e.g. ["pwd", "mfa", "otp"]. */
+    amr?: string[];
+    sid?: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    [claim: string]: unknown;
+}
+/**
+ * Verifies an ID token from your tenant: signature (JWKS, or the shared secret for HMAC keys),
+ * issuer, audience (your client ID; `azp` when there are several), expiry and nonce.
+ */
+export declare function verifyIdToken(token: string | null | undefined, options: VerifyIdTokenOptions): Promise<IdTokenClaims>;
 export type VerificationMode = "local" | "hybrid" | "introspect";
 export interface TokenVerifierOptions extends Omit<VerifyOptions, "scope"> {
     /**

package/dist/server.js

@@ -1,5 +1,6 @@
 import { NineError, decodeJwt, discover, normalizeIssuer, postForm, toHex, utf8 } from "./util.js";
 export { NineError, normalizeIssuer } from "./util.js";
+export { WebAppAuth } from "./web-app.js";
 /** WebCrypto parameters for each JWS algorithm 9in signs with. */
 const ALGORITHMS = {
     RS256: { import: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, verify: "RSASSA-PKCS1-v1_5" },
@@ -111,6 +112,57 @@ export async function verifyAccessToken(token, options) {
     checkClaims(payload, issuer, options);
     return payload;
 }
+/**
+ * Verifies an ID token from your tenant: signature (JWKS, or the shared secret for HMAC keys),
+ * issuer, audience (your client ID; `azp` when there are several), expiry and nonce.
+ */
+export async function verifyIdToken(token, options) {
+    if (!token)
+        throw new NineError("invalid_token", "missing ID token", 401);
+    const fetcher = options.fetch ?? fetch.bind(globalThis);
+    const issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+    let parts;
+    try {
+        parts = decodeJwt(token);
+    }
+    catch {
+        throw new NineError("invalid_token", "malformed ID token", 401);
+    }
+    const { header, payload, signingInput, signature } = parts;
+    const alg = String(header.alg);
+    // An access token is never accepted as an ID token.
+    if (ACCESS_TOKEN_TYPES.has(String(header.typ ?? "").toLowerCase()))
+        throw new NineError("invalid_token", "not an ID token", 401);
+    let valid;
+    if (HMAC_HASH[alg]) {
+        if (!options.secret)
+            throw new NineError("invalid_token", "HMAC-signed ID token: pass the tenant's shared secret", 401);
+        const key = await crypto.subtle.importKey("raw", utf8(options.secret), { name: "HMAC", hash: HMAC_HASH[alg] }, false, ["verify"]);
+        valid = await crypto.subtle.verify("HMAC", key, signature, utf8(signingInput));
+    }
+    else if (ALGORITHMS[alg]) {
+        const jwk = await findKey(issuer, header.kid, fetcher);
+        if (!jwk)
+            throw new NineError("invalid_token", "unknown signing key", 401);
+        if (jwk.alg && jwk.alg !== alg)
+            throw new NineError("invalid_token", "algorithm does not match the key", 401);
+        valid = await crypto.subtle.verify(ALGORITHMS[alg].verify, await importPublicKey(jwk, alg), signature, utf8(signingInput));
+    }
+    else {
+        throw new NineError("invalid_token", "unsupported algorithm", 401);
+    }
+    if (!valid)
+        throw new NineError("invalid_token", "bad signature", 401);
+    checkClaims(payload, issuer, { issuer, audience: options.clientId, clockTolerance: options.clockTolerance });
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (aud.length > 1 && payload.azp !== options.clientId)
+        throw new NineError("invalid_token", "authorized party mismatch", 401);
+    if (options.nonce !== undefined && options.nonce !== null && payload.nonce !== options.nonce)
+        throw new NineError("invalid_token", "nonce mismatch", 401);
+    if (typeof payload.sub !== "string" || !payload.sub)
+        throw new NineError("invalid_token", "missing subject", 401);
+    return payload;
+}
 function checkClaims(payload, issuer, options) {
     const now = Math.floor(Date.now() / 1000);
     const skew = options.clockTolerance ?? 30;

package/dist/web-app.d.ts

@@ -0,0 +1,96 @@
+import { type IdTokenClaims } from "./server.js";
+/**
+ * Sign-in for server-rendered web apps (authorization code + PKCE, with or without a client
+ * secret), using only `fetch` and Web Crypto: it runs on Node 18+, Next.js (Node and Edge),
+ * Cloudflare Workers, Deno and Bun. Framework packages keep the transaction and the session
+ * (for example in encrypted cookies); this class does the protocol:
+ *
+ *   const { url, transaction } = await auth.createLogin({ returnTo: "/dashboard" });
+ *   // keep `transaction` until the callback, redirect the browser to `url`
+ *   const { tokens, claims, returnTo } = await auth.handleCallback(request.url, transaction);
+ */
+export interface WebAppAuthOptions {
+    /** Your tenant's issuer URL, e.g. https://acme.9in.io. */
+    issuer: string;
+    clientId: string;
+    /** For confidential applications: sent with HTTP Basic. Leave out for public ones (PKCE only). */
+    clientSecret?: string;
+    /** Your callback URL, as registered on the application. */
+    redirectUri: string;
+    /** Default "openid profile email offline_access" (offline_access gives a refresh token). */
+    scope?: string;
+    /** An API identifier, to get access tokens for that API. */
+    audience?: string;
+    /** Only for tenants that sign with a shared (HMAC) key. */
+    idTokenSecret?: string;
+    fetch?: typeof fetch;
+    /** Allows http:// issuers other than localhost (never in production). */
+    allowInsecureIssuer?: boolean;
+}
+export interface WebLoginOptions {
+    /** A path in your app to come back to after sign-in. */
+    returnTo?: string;
+    prompt?: "login" | "consent" | "none" | "select_account" | "create";
+    /** Prefills the identifier on the sign-in page. */
+    loginHint?: string;
+    /** "signup" opens the registration page. */
+    screen?: "login" | "signup";
+    /** Language of the hosted pages (ui_locales), e.g. "de". */
+    locale?: string;
+    /** Extra authorization parameters (they never replace state, nonce or PKCE). */
+    params?: Record<string, string>;
+}
+/** What to keep between the redirect to 9in and the callback (store it encrypted; it's secret). */
+export interface LoginTransaction {
+    state: string;
+    nonce: string;
+    verifier: string;
+    returnTo?: string;
+    /** ms */
+    createdAt: number;
+}
+export interface WebTokenSet {
+    accessToken: string;
+    idToken: string | null;
+    refreshToken: string | null;
+    /** ms */
+    expiresAt: number;
+    scope: string;
+    tokenType: string;
+}
+export interface CallbackResult {
+    tokens: WebTokenSet;
+    /** The verified ID token's claims: the signed-in user. */
+    claims: IdTokenClaims;
+    returnTo?: string;
+}
+export declare class WebAppAuth {
+    private readonly options;
+    private readonly issuer;
+    private readonly fetcher;
+    constructor(options: WebAppAuthOptions);
+    /** The URL to send the browser to, and the transaction to keep until the callback. */
+    createLogin(options?: WebLoginOptions): Promise<{
+        url: string;
+        transaction: LoginTransaction;
+    }>;
+    /**
+     * Finishes sign-in on your callback URL: checks the state against the transaction, exchanges
+     * the code and verifies the ID token (signature, issuer, audience, expiry, nonce).
+     */
+    handleCallback(callbackUrl: string | URL, transaction: LoginTransaction | null | undefined): Promise<CallbackResult>;
+    /** New tokens from a refresh token (9in rotates it: keep the one returned). */
+    refresh(refreshToken: string): Promise<WebTokenSet>;
+    /** The URL that ends the session at 9in and comes back to `postLogoutRedirectUri`. */
+    logoutUrl(options?: {
+        idTokenHint?: string | null;
+        postLogoutRedirectUri?: string;
+        state?: string;
+    }): Promise<string>;
+    /** Revokes a refresh token (ending the session's token family) or an access token. */
+    revoke(token: string, hint?: "refresh_token" | "access_token"): Promise<void>;
+    /** The user's current profile from the userinfo endpoint. */
+    userInfo(accessToken: string): Promise<Record<string, unknown>>;
+    private clientAuth;
+    private tokenRequest;
+}

package/dist/web-app.js

@@ -0,0 +1,138 @@
+import { NineError, base64UrlEncode, discover, normalizeIssuer, postForm, randomString, sha256 } from "./util.js";
+import { verifyIdToken } from "./server.js";
+const TRANSACTION_TTL = 15 * 60_000;
+const RESERVED = new Set(["response_type", "client_id", "redirect_uri", "state", "nonce", "code_challenge", "code_challenge_method", "scope"]);
+export class WebAppAuth {
+    options;
+    issuer;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId)
+            throw new NineError("invalid_options", "clientId is required");
+        if (!options.redirectUri)
+            throw new NineError("invalid_options", "redirectUri is required");
+        this.issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+        this.fetcher = options.fetch ?? fetch.bind(globalThis);
+    }
+    /** The URL to send the browser to, and the transaction to keep until the callback. */
+    async createLogin(options = {}) {
+        const config = await discover(this.issuer, this.fetcher);
+        const transaction = {
+            state: randomString(24),
+            nonce: randomString(24),
+            verifier: randomString(48),
+            createdAt: Date.now(),
+            ...(options.returnTo ? { returnTo: options.returnTo } : {}),
+        };
+        const url = new URL(config.authorization_endpoint);
+        const params = url.searchParams;
+        for (const [key, value] of Object.entries(options.params ?? {}))
+            if (!RESERVED.has(key))
+                params.set(key, value);
+        params.set("response_type", "code");
+        params.set("client_id", this.options.clientId);
+        params.set("redirect_uri", this.options.redirectUri);
+        params.set("scope", this.options.scope ?? "openid profile email offline_access");
+        params.set("state", transaction.state);
+        params.set("nonce", transaction.nonce);
+        params.set("code_challenge", base64UrlEncode(await sha256(transaction.verifier)));
+        params.set("code_challenge_method", "S256");
+        if (this.options.audience)
+            params.set("audience", this.options.audience);
+        const prompt = options.screen === "signup" ? "create" : options.prompt;
+        if (prompt)
+            params.set("prompt", prompt);
+        if (options.loginHint)
+            params.set("login_hint", options.loginHint);
+        if (options.locale)
+            params.set("ui_locales", options.locale);
+        return { url: url.toString(), transaction };
+    }
+    /**
+     * Finishes sign-in on your callback URL: checks the state against the transaction, exchanges
+     * the code and verifies the ID token (signature, issuer, audience, expiry, nonce).
+     */
+    async handleCallback(callbackUrl, transaction) {
+        const url = new URL(callbackUrl);
+        const error = url.searchParams.get("error");
+        if (error)
+            throw new NineError(error, url.searchParams.get("error_description") ?? error, 400);
+        if (!transaction)
+            throw new NineError("invalid_state", "no sign-in in progress (it expired, or started in another browser)", 400);
+        if (Date.now() - transaction.createdAt > TRANSACTION_TTL)
+            throw new NineError("invalid_state", "the sign-in took too long; start again", 400);
+        if (url.searchParams.get("state") !== transaction.state)
+            throw new NineError("invalid_state", "state mismatch", 400);
+        // RFC 9207: when the issuer says who it is, it must be ours.
+        const iss = url.searchParams.get("iss");
+        if (iss && iss.replace(/\/$/, "") !== this.issuer)
+            throw new NineError("invalid_issuer", `unexpected issuer ${iss}`, 400);
+        const code = url.searchParams.get("code");
+        if (!code)
+            throw new NineError("missing_code", "no authorization code in the URL", 400);
+        const tokens = await this.tokenRequest({ grant_type: "authorization_code", code, redirect_uri: this.options.redirectUri, code_verifier: transaction.verifier });
+        const claims = await verifyIdToken(tokens.idToken, {
+            issuer: this.issuer,
+            clientId: this.options.clientId,
+            nonce: transaction.nonce,
+            secret: this.options.idTokenSecret,
+            fetch: this.fetcher,
+            allowInsecureIssuer: this.options.allowInsecureIssuer,
+        });
+        return { tokens, claims, ...(transaction.returnTo ? { returnTo: transaction.returnTo } : {}) };
+    }
+    /** New tokens from a refresh token (9in rotates it: keep the one returned). */
+    async refresh(refreshToken) {
+        const tokens = await this.tokenRequest({ grant_type: "refresh_token", refresh_token: refreshToken });
+        return { ...tokens, refreshToken: tokens.refreshToken ?? refreshToken };
+    }
+    /** The URL that ends the session at 9in and comes back to `postLogoutRedirectUri`. */
+    async logoutUrl(options = {}) {
+        const config = await discover(this.issuer, this.fetcher);
+        const url = new URL(config.end_session_endpoint ?? `${this.issuer}/logout`);
+        url.searchParams.set("client_id", this.options.clientId);
+        if (options.idTokenHint)
+            url.searchParams.set("id_token_hint", options.idTokenHint);
+        if (options.postLogoutRedirectUri)
+            url.searchParams.set("post_logout_redirect_uri", options.postLogoutRedirectUri);
+        if (options.state)
+            url.searchParams.set("state", options.state);
+        return url.toString();
+    }
+    /** Revokes a refresh token (ending the session's token family) or an access token. */
+    async revoke(token, hint = "refresh_token") {
+        const config = await discover(this.issuer, this.fetcher);
+        if (!config.revocation_endpoint)
+            return;
+        const { form, headers } = this.clientAuth({ token, token_type_hint: hint });
+        await postForm(config.revocation_endpoint, form, headers, this.fetcher);
+    }
+    /** The user's current profile from the userinfo endpoint. */
+    async userInfo(accessToken) {
+        const config = await discover(this.issuer, this.fetcher);
+        const res = await this.fetcher(config.userinfo_endpoint, { headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" } });
+        if (!res.ok)
+            throw new NineError(res.status === 401 ? "invalid_token" : "userinfo_failed", `HTTP ${res.status}`, res.status);
+        return (await res.json());
+    }
+    clientAuth(form) {
+        if (!this.options.clientSecret)
+            return { form: { ...form, client_id: this.options.clientId }, headers: {} };
+        const basic = btoa(`${encodeURIComponent(this.options.clientId)}:${encodeURIComponent(this.options.clientSecret)}`);
+        return { form, headers: { Authorization: `Basic ${basic}` } };
+    }
+    async tokenRequest(input) {
+        const config = await discover(this.issuer, this.fetcher);
+        const { form, headers } = this.clientAuth(input);
+        const json = await postForm(config.token_endpoint, form, headers, this.fetcher);
+        return {
+            accessToken: json.access_token,
+            idToken: json.id_token ?? null,
+            refreshToken: json.refresh_token ?? null,
+            expiresAt: Date.now() + (json.expires_in ?? 3600) * 1000,
+            scope: json.scope ?? "",
+            tokenType: json.token_type ?? "Bearer",
+        };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@9in-io/sdk",
-  "version": "0.2.0",
-  "description": "Official 9in SDK: browser sign-in with PKCE, token verification, Management API client and adapter handler. Zero dependencies; runs in browsers, Node 18+, Cloudflare Workers, Deno and Bun.",
+  "version": "0.3.0",
+  "description": "Official 9in SDK: browser and server-side sign-in with PKCE, token verification, Management API client and adapter handler. Zero dependencies; runs in browsers, Node 18+, Cloudflare Workers, Deno and Bun.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,

package/src/server.ts

@@ -1,6 +1,7 @@
 import { NineError, decodeJwt, discover, normalizeIssuer, postForm, toHex, utf8 } from "./util.js";
 
 export { NineError, normalizeIssuer } from "./util.js";
+export { WebAppAuth, type WebAppAuthOptions, type WebLoginOptions, type LoginTransaction, type WebTokenSet, type CallbackResult } from "./web-app.js";
 
 // ---------------------------------------------------------------------------
 // Access token verification
@@ -151,6 +152,80 @@ export async function verifyAccessToken(token: string | null | undefined, option
   return payload as AccessTokenClaims;
 }
 
+export interface VerifyIdTokenOptions {
+  /** Your tenant's issuer URL. */
+  issuer: string;
+  /** Your application's client ID (the token's audience). */
+  clientId: string;
+  /** The nonce sent with the sign-in request. */
+  nonce?: string | null;
+  /** For tenants whose signing key is a shared (HMAC) secret. */
+  secret?: string;
+  /** Seconds of clock skew allowed (default 30). */
+  clockTolerance?: number;
+  fetch?: typeof fetch;
+  allowInsecureIssuer?: boolean;
+}
+
+/** Claims of a verified ID token (standard OIDC claims plus your custom profile claims). */
+export interface IdTokenClaims {
+  iss: string;
+  sub: string;
+  aud: string | string[];
+  exp: number;
+  iat: number;
+  nonce?: string;
+  auth_time?: number;
+  /** How the user signed in, e.g. ["pwd", "mfa", "otp"]. */
+  amr?: string[];
+  sid?: string;
+  email?: string;
+  email_verified?: boolean;
+  name?: string;
+  picture?: string;
+  [claim: string]: unknown;
+}
+
+/**
+ * Verifies an ID token from your tenant: signature (JWKS, or the shared secret for HMAC keys),
+ * issuer, audience (your client ID; `azp` when there are several), expiry and nonce.
+ */
+export async function verifyIdToken(token: string | null | undefined, options: VerifyIdTokenOptions): Promise<IdTokenClaims> {
+  if (!token) throw new NineError("invalid_token", "missing ID token", 401);
+  const fetcher = options.fetch ?? fetch.bind(globalThis);
+  const issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+  let parts;
+  try {
+    parts = decodeJwt(token);
+  } catch {
+    throw new NineError("invalid_token", "malformed ID token", 401);
+  }
+  const { header, payload, signingInput, signature } = parts;
+  const alg = String(header.alg);
+  // An access token is never accepted as an ID token.
+  if (ACCESS_TOKEN_TYPES.has(String(header.typ ?? "").toLowerCase())) throw new NineError("invalid_token", "not an ID token", 401);
+  let valid: boolean;
+  if (HMAC_HASH[alg]) {
+    if (!options.secret) throw new NineError("invalid_token", "HMAC-signed ID token: pass the tenant's shared secret", 401);
+    const key = await crypto.subtle.importKey("raw", utf8(options.secret), { name: "HMAC", hash: HMAC_HASH[alg] }, false, ["verify"]);
+    valid = await crypto.subtle.verify("HMAC", key, signature, utf8(signingInput));
+  } else if (ALGORITHMS[alg]) {
+    const jwk = await findKey(issuer, header.kid, fetcher);
+    if (!jwk) throw new NineError("invalid_token", "unknown signing key", 401);
+    if (jwk.alg && jwk.alg !== alg) throw new NineError("invalid_token", "algorithm does not match the key", 401);
+    valid = await crypto.subtle.verify(ALGORITHMS[alg]!.verify, await importPublicKey(jwk, alg), signature, utf8(signingInput));
+  } else {
+    throw new NineError("invalid_token", "unsupported algorithm", 401);
+  }
+  if (!valid) throw new NineError("invalid_token", "bad signature", 401);
+  checkClaims(payload, issuer, { issuer, audience: options.clientId, clockTolerance: options.clockTolerance });
+  const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+  if (aud.length > 1 && payload.azp !== options.clientId) throw new NineError("invalid_token", "authorized party mismatch", 401);
+  if (options.nonce !== undefined && options.nonce !== null && payload.nonce !== options.nonce) throw new NineError("invalid_token", "nonce mismatch", 401);
+  if (typeof payload.sub !== "string" || !payload.sub) throw new NineError("invalid_token", "missing subject", 401);
+  return payload as IdTokenClaims;
+}
+
 function checkClaims(payload: Record<string, unknown>, issuer: string, options: VerifyOptions): void {
   const now = Math.floor(Date.now() / 1000);
   const skew = options.clockTolerance ?? 30;

package/src/web-app.ts

@@ -0,0 +1,207 @@
+import { NineError, base64UrlEncode, discover, normalizeIssuer, postForm, randomString, sha256 } from "./util.js";
+import { verifyIdToken, type IdTokenClaims } from "./server.js";
+
+/**
+ * Sign-in for server-rendered web apps (authorization code + PKCE, with or without a client
+ * secret), using only `fetch` and Web Crypto: it runs on Node 18+, Next.js (Node and Edge),
+ * Cloudflare Workers, Deno and Bun. Framework packages keep the transaction and the session
+ * (for example in encrypted cookies); this class does the protocol:
+ *
+ *   const { url, transaction } = await auth.createLogin({ returnTo: "/dashboard" });
+ *   // keep `transaction` until the callback, redirect the browser to `url`
+ *   const { tokens, claims, returnTo } = await auth.handleCallback(request.url, transaction);
+ */
+
+export interface WebAppAuthOptions {
+  /** Your tenant's issuer URL, e.g. https://acme.9in.io. */
+  issuer: string;
+  clientId: string;
+  /** For confidential applications: sent with HTTP Basic. Leave out for public ones (PKCE only). */
+  clientSecret?: string;
+  /** Your callback URL, as registered on the application. */
+  redirectUri: string;
+  /** Default "openid profile email offline_access" (offline_access gives a refresh token). */
+  scope?: string;
+  /** An API identifier, to get access tokens for that API. */
+  audience?: string;
+  /** Only for tenants that sign with a shared (HMAC) key. */
+  idTokenSecret?: string;
+  fetch?: typeof fetch;
+  /** Allows http:// issuers other than localhost (never in production). */
+  allowInsecureIssuer?: boolean;
+}
+
+export interface WebLoginOptions {
+  /** A path in your app to come back to after sign-in. */
+  returnTo?: string;
+  prompt?: "login" | "consent" | "none" | "select_account" | "create";
+  /** Prefills the identifier on the sign-in page. */
+  loginHint?: string;
+  /** "signup" opens the registration page. */
+  screen?: "login" | "signup";
+  /** Language of the hosted pages (ui_locales), e.g. "de". */
+  locale?: string;
+  /** Extra authorization parameters (they never replace state, nonce or PKCE). */
+  params?: Record<string, string>;
+}
+
+/** What to keep between the redirect to 9in and the callback (store it encrypted; it's secret). */
+export interface LoginTransaction {
+  state: string;
+  nonce: string;
+  verifier: string;
+  returnTo?: string;
+  /** ms */
+  createdAt: number;
+}
+
+export interface WebTokenSet {
+  accessToken: string;
+  idToken: string | null;
+  refreshToken: string | null;
+  /** ms */
+  expiresAt: number;
+  scope: string;
+  tokenType: string;
+}
+
+export interface CallbackResult {
+  tokens: WebTokenSet;
+  /** The verified ID token's claims: the signed-in user. */
+  claims: IdTokenClaims;
+  returnTo?: string;
+}
+
+const TRANSACTION_TTL = 15 * 60_000;
+const RESERVED = new Set(["response_type", "client_id", "redirect_uri", "state", "nonce", "code_challenge", "code_challenge_method", "scope"]);
+
+interface TokenResponse {
+  access_token: string;
+  id_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+  token_type?: string;
+}
+
+export class WebAppAuth {
+  private readonly issuer: string;
+  private readonly fetcher: typeof fetch;
+
+  constructor(private readonly options: WebAppAuthOptions) {
+    if (!options.clientId) throw new NineError("invalid_options", "clientId is required");
+    if (!options.redirectUri) throw new NineError("invalid_options", "redirectUri is required");
+    this.issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+    this.fetcher = options.fetch ?? fetch.bind(globalThis);
+  }
+
+  /** The URL to send the browser to, and the transaction to keep until the callback. */
+  async createLogin(options: WebLoginOptions = {}): Promise<{ url: string; transaction: LoginTransaction }> {
+    const config = await discover(this.issuer, this.fetcher);
+    const transaction: LoginTransaction = {
+      state: randomString(24),
+      nonce: randomString(24),
+      verifier: randomString(48),
+      createdAt: Date.now(),
+      ...(options.returnTo ? { returnTo: options.returnTo } : {}),
+    };
+    const url = new URL(config.authorization_endpoint);
+    const params = url.searchParams;
+    for (const [key, value] of Object.entries(options.params ?? {})) if (!RESERVED.has(key)) params.set(key, value);
+    params.set("response_type", "code");
+    params.set("client_id", this.options.clientId);
+    params.set("redirect_uri", this.options.redirectUri);
+    params.set("scope", this.options.scope ?? "openid profile email offline_access");
+    params.set("state", transaction.state);
+    params.set("nonce", transaction.nonce);
+    params.set("code_challenge", base64UrlEncode(await sha256(transaction.verifier)));
+    params.set("code_challenge_method", "S256");
+    if (this.options.audience) params.set("audience", this.options.audience);
+    const prompt = options.screen === "signup" ? "create" : options.prompt;
+    if (prompt) params.set("prompt", prompt);
+    if (options.loginHint) params.set("login_hint", options.loginHint);
+    if (options.locale) params.set("ui_locales", options.locale);
+    return { url: url.toString(), transaction };
+  }
+
+  /**
+   * Finishes sign-in on your callback URL: checks the state against the transaction, exchanges
+   * the code and verifies the ID token (signature, issuer, audience, expiry, nonce).
+   */
+  async handleCallback(callbackUrl: string | URL, transaction: LoginTransaction | null | undefined): Promise<CallbackResult> {
+    const url = new URL(callbackUrl);
+    const error = url.searchParams.get("error");
+    if (error) throw new NineError(error, url.searchParams.get("error_description") ?? error, 400);
+    if (!transaction) throw new NineError("invalid_state", "no sign-in in progress (it expired, or started in another browser)", 400);
+    if (Date.now() - transaction.createdAt > TRANSACTION_TTL) throw new NineError("invalid_state", "the sign-in took too long; start again", 400);
+    if (url.searchParams.get("state") !== transaction.state) throw new NineError("invalid_state", "state mismatch", 400);
+    // RFC 9207: when the issuer says who it is, it must be ours.
+    const iss = url.searchParams.get("iss");
+    if (iss && iss.replace(/\/$/, "") !== this.issuer) throw new NineError("invalid_issuer", `unexpected issuer ${iss}`, 400);
+    const code = url.searchParams.get("code");
+    if (!code) throw new NineError("missing_code", "no authorization code in the URL", 400);
+    const tokens = await this.tokenRequest({ grant_type: "authorization_code", code, redirect_uri: this.options.redirectUri, code_verifier: transaction.verifier });
+    const claims = await verifyIdToken(tokens.idToken, {
+      issuer: this.issuer,
+      clientId: this.options.clientId,
+      nonce: transaction.nonce,
+      secret: this.options.idTokenSecret,
+      fetch: this.fetcher,
+      allowInsecureIssuer: this.options.allowInsecureIssuer,
+    });
+    return { tokens, claims, ...(transaction.returnTo ? { returnTo: transaction.returnTo } : {}) };
+  }
+
+  /** New tokens from a refresh token (9in rotates it: keep the one returned). */
+  async refresh(refreshToken: string): Promise<WebTokenSet> {
+    const tokens = await this.tokenRequest({ grant_type: "refresh_token", refresh_token: refreshToken });
+    return { ...tokens, refreshToken: tokens.refreshToken ?? refreshToken };
+  }
+
+  /** The URL that ends the session at 9in and comes back to `postLogoutRedirectUri`. */
+  async logoutUrl(options: { idTokenHint?: string | null; postLogoutRedirectUri?: string; state?: string } = {}): Promise<string> {
+    const config = await discover(this.issuer, this.fetcher);
+    const url = new URL(config.end_session_endpoint ?? `${this.issuer}/logout`);
+    url.searchParams.set("client_id", this.options.clientId);
+    if (options.idTokenHint) url.searchParams.set("id_token_hint", options.idTokenHint);
+    if (options.postLogoutRedirectUri) url.searchParams.set("post_logout_redirect_uri", options.postLogoutRedirectUri);
+    if (options.state) url.searchParams.set("state", options.state);
+    return url.toString();
+  }
+
+  /** Revokes a refresh token (ending the session's token family) or an access token. */
+  async revoke(token: string, hint: "refresh_token" | "access_token" = "refresh_token"): Promise<void> {
+    const config = await discover(this.issuer, this.fetcher);
+    if (!config.revocation_endpoint) return;
+    const { form, headers } = this.clientAuth({ token, token_type_hint: hint });
+    await postForm(config.revocation_endpoint, form, headers, this.fetcher);
+  }
+
+  /** The user's current profile from the userinfo endpoint. */
+  async userInfo(accessToken: string): Promise<Record<string, unknown>> {
+    const config = await discover(this.issuer, this.fetcher);
+    const res = await this.fetcher(config.userinfo_endpoint, { headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" } });
+    if (!res.ok) throw new NineError(res.status === 401 ? "invalid_token" : "userinfo_failed", `HTTP ${res.status}`, res.status);
+    return (await res.json()) as Record<string, unknown>;
+  }
+
+  private clientAuth(form: Record<string, string>): { form: Record<string, string>; headers: Record<string, string> } {
+    if (!this.options.clientSecret) return { form: { ...form, client_id: this.options.clientId }, headers: {} };
+    const basic = btoa(`${encodeURIComponent(this.options.clientId)}:${encodeURIComponent(this.options.clientSecret)}`);
+    return { form, headers: { Authorization: `Basic ${basic}` } };
+  }
+
+  private async tokenRequest(input: Record<string, string>): Promise<WebTokenSet> {
+    const config = await discover(this.issuer, this.fetcher);
+    const { form, headers } = this.clientAuth(input);
+    const json = await postForm<TokenResponse>(config.token_endpoint, form, headers, this.fetcher);
+    return {
+      accessToken: json.access_token,
+      idToken: json.id_token ?? null,
+      refreshToken: json.refresh_token ?? null,
+      expiresAt: Date.now() + (json.expires_in ?? 3600) * 1000,
+      scope: json.scope ?? "",
+      tokenType: json.token_type ?? "Bearer",
+    };
+  }
+}