@broberg/sso 0.18.3 → 0.19.0

package/README.md

@@ -240,6 +240,31 @@ try {
 - **Needs `SSO_CLIENT_SECRET`** — a public client cannot introspect. Since 0.18.0 (F084.160) that is `SsoConfigError`, thrown before any request (0.17.0 called it `SsoIntrospectionUnavailableError`, which sent callers down the 503-and-retry path for a fault that never goes away). Answer 500 and fix the setup; never retry. A wrong secret is reported as unavailable with "client id/secret was refused" — measured against id.broberg.ai.
 - **Cache** (optional, `cacheMs`): an active answer is reused up to that long and never past the token's `exp`; an inactive answer is never cached. The token itself never appears in an error message.
 
+## Login and signup in YOUR design — `client.embedded` (0.19.0, F084.165)
+
+For an app BID has allowed to draw its own login (BID F084.166 v1.1 + F084.167 — owner's exception,
+Jam first). Runs on YOUR SERVER as a confidential client (`clientSecret` required — BID gets
+`Authorization: Basic client_id:client_secret`). Ends in the SAME `LoginResult` as `completeLogin`,
+so your `signSession` step does not change.
+
+```ts
+const s = await client.embedded.start({ email, endUserIp, intent: "signup", name, termsVersion }); // intent/name/termsVersion only for signup
+if (s.ok) setCookie("bid_flow", await sealEmbeddedFlow(s.flow, cookieSecret), { httpOnly: true, maxAge: EMBEDDED_FLOW_MAX_AGE });
+// later, with the code from the mail:
+const f = await openEmbeddedFlow(getCookie("bid_flow"), cookieSecret);           // { ok, flow } | { ok:false, reason: absent|expired|unreadable }
+const step = f.ok ? await client.embedded.verify(f.flow, code) : null;          // done → step.result is a LoginResult
+// second_factor → client.embedded.sendSms(flow) / verifySecondFactor(flow, "totp"|"sms", code)
+const terms = await client.embedded.terms("da");                                // show terms.text + links VERBATIM at the signup button
+```
+
+- The PKCE verifier and nonce stay server-side in the sealed flow cookie (10 min, same signing as the login
+  transaction); the id_token's `nonce` must match the flow's, or `verify` throws.
+- Errors are data: `invalid_code {attemptsLeft}`, `expired`, `locked {retryAfter}`, `too_many_requests {retryAfter}`,
+  `not_embedded` (403/404 — fall back to the normal redirect login), `signup_not_enabled`, `terms_outdated {version}`
+  (re-fetch `terms()`), `invalid_request`, `unavailable`.
+- A 401 from BID is YOUR configuration (wrong client id/secret) and THROWS `SsoError` — it is never shown to the
+  user as a wrong code.
+
 ## What it will never do
 
 No passwords. No passkey registration. No social-provider keys. No email

package/dist/{chunk-CHRCHUZ3.cjs → chunk-MZE4TPFU.cjs}

@@ -73,6 +73,127 @@ function loadSsoConfig(env = process.env) {
     clientSecret: env.SSO_CLIENT_SECRET?.trim() || void 0
   };
 }
+
+// src/session.ts
+var enc = new TextEncoder();
+var b64url = (bytes) => {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var fromB64url = (s) => {
+  const pad = s.replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(pad + "=".repeat((4 - pad.length % 4) % 4));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+};
+async function hmacKey(secret) {
+  return crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify"
+  ]);
+}
+async function signValue(value, secret, options = {}) {
+  const payload = b64url(enc.encode(value));
+  const body = options.maxAgeSeconds === void 0 ? payload : `t${Math.floor((options.now ?? Date.now)() / 1e3)}~${payload}`;
+  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(secret), enc.encode(body)));
+  return `${body}.${b64url(sig)}`;
+}
+var STAMPED = /^t(\d+)~(.*)$/s;
+async function verifyValue(token, secret, options = {}) {
+  if (!token) return null;
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  try {
+    const ok = await crypto.subtle.verify(
+      "HMAC",
+      await hmacKey(secret),
+      fromB64url(token.slice(dot + 1)),
+      enc.encode(body)
+    );
+    if (!ok) return null;
+    const stamped = STAMPED.exec(body);
+    if (options.maxAgeSeconds !== void 0) {
+      if (!stamped) return null;
+      const issuedAt = Number(stamped[1]);
+      if ((options.now ?? Date.now)() / 1e3 - issuedAt > options.maxAgeSeconds) return null;
+    }
+    return new TextDecoder().decode(fromB64url(stamped?.[2] ?? body));
+  } catch {
+    return null;
+  }
+}
+async function signSession(payload, secret) {
+  return signValue(JSON.stringify(payload), secret);
+}
+async function verifySession(token, secret, now = Date.now) {
+  const body = await verifyValue(token, secret);
+  if (body === null) return null;
+  try {
+    const payload = JSON.parse(body);
+    if (typeof payload.sub !== "string" || payload.sub === "") return null;
+    if (typeof payload.exp !== "number" || payload.exp * 1e3 <= now()) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function cookieHeader(name, value, opts) {
+  const parts = [
+    `${name}=${value}`,
+    `Path=${opts.path ?? "/"}`,
+    `Max-Age=${opts.maxAge}`,
+    "HttpOnly",
+    // Lax, NOT Strict, and this is load-bearing: the callback from BrobergID
+    // is a top-level GET navigation from another site. Strict withholds the
+    // cookie on exactly that navigation, so the login transaction cookie would
+    // be missing when it is needed and every sign-in would fail with "state
+    // does not match" — a message that sends you looking in the wrong place.
+    `SameSite=${opts.sameSite ?? "Lax"}`
+  ];
+  if (opts.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+function readCookie(header, name) {
+  if (!header) return void 0;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return void 0;
+}
+
+// src/embedded.ts
+var EMBEDDED_FLOW_MAX_AGE = 600;
+function sealEmbeddedFlow(flow, secret, options = {}) {
+  return signValue(JSON.stringify(flow), secret, { maxAgeSeconds: EMBEDDED_FLOW_MAX_AGE, ...options });
+}
+async function openEmbeddedFlow(raw, secret, options = {}) {
+  if (!raw) return { ok: false, reason: "absent" };
+  if (await verifyValue(raw, secret) === null) return { ok: false, reason: "unreadable" };
+  const fresh = await verifyValue(raw, secret, { maxAgeSeconds: EMBEDDED_FLOW_MAX_AGE, ...options });
+  if (fresh === null) return { ok: false, reason: "expired" };
+  try {
+    const f = JSON.parse(fresh);
+    if (typeof f.flowId !== "string" || typeof f.codeVerifier !== "string" || typeof f.nonce !== "string" || typeof f.email !== "string") return { ok: false, reason: "unreadable" };
+    return { ok: true, flow: f };
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+}
+function embeddedError(status, body) {
+  const code = typeof body.error === "string" ? body.error : "";
+  const num = (v) => typeof v === "number" ? v : void 0;
+  if (status === 400 && code === "invalid_code") return { kind: "invalid_code", ...num(body.attempts_left) !== void 0 ? { attemptsLeft: num(body.attempts_left) } : {} };
+  if (status === 400 && code === "expired") return { kind: "expired" };
+  if (status === 400 && code === "terms_outdated") return { kind: "terms_outdated", ...typeof body.version === "string" ? { version: body.version } : {} };
+  if (status === 400) return { kind: "invalid_request" };
+  if (status === 403 && code === "signup_not_enabled") return { kind: "signup_not_enabled" };
+  if (status === 403 || status === 404 || status === 405) return { kind: "not_embedded" };
+  if (status === 429) return { kind: code === "locked" ? "locked" : "too_many_requests", ...num(body.retry_after) !== void 0 ? { retryAfter: num(body.retry_after) } : {} };
+  return { kind: "unavailable", message: `BID answered ${status}${code ? ` (${code})` : ""}` };
+}
 var JwksError = class extends Error {
   constructor(message) {
     super(message);
@@ -226,15 +347,15 @@ var AVATAR_TYPES = ["image/png", "image/jpeg", "image/webp"];
 function mediaType(contentType) {
   return (contentType ?? "").split(";")[0].trim().toLowerCase();
 }
-var b64url = (bytes) => {
+var b64url2 = (bytes) => {
   const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
   let s = "";
   for (const b of view) s += String.fromCharCode(b);
   return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 };
-var randomToken = (bytes = 32) => b64url(crypto.getRandomValues(new Uint8Array(bytes)));
+var randomToken = (bytes = 32) => b64url2(crypto.getRandomValues(new Uint8Array(bytes)));
 async function challengeFor(verifier) {
-  return b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
+  return b64url2(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
 }
 var ADDRESS_OWNERSHIP = /* @__PURE__ */ new Set(["verified", "unverified", "not_on_account"]);
 var INVITATION_OUTCOMES = /* @__PURE__ */ new Set([
@@ -554,9 +675,133 @@ function createSsoClient(config, options = {}) {
     if (options2.cacheMs && options2.cacheMs > 0) introspectCache.set(key, { result, until: Math.min(now() + options2.cacheMs, exp * 1e3) });
     return result;
   }
+  async function exchangeCode(code, codeVerifier, nonce) {
+    const { token_endpoint } = await discovery();
+    const res = await fetchImpl(token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: config.redirectUri,
+        client_id: config.clientId,
+        // ALWAYS sent, secret or not. See SsoConfig.clientSecret: the two
+        // prove different things, so a confidential client keeps PKCE.
+        code_verifier: codeVerifier,
+        ...config.clientSecret ? { client_secret: config.clientSecret } : {}
+      })
+    });
+    const raw = await res.text();
+    let body;
+    try {
+      body = raw.trim() === "" ? {} : JSON.parse(raw);
+    } catch {
+      throw new SsoError(
+        `token exchange failed (${res.status}): the response body is not JSON${res.headers.get("content-type") ? ` (content-type: ${res.headers.get("content-type")})` : ""} \u2014 ${excerptForLog(raw, config.clientSecret)}`
+      );
+    }
+    if (!res.ok || !body.id_token) {
+      throw new SsoError(
+        `token exchange failed (${res.status}): ${body.error ?? "no id_token in response"}` + (body.error_description ? ` \u2014 ${body.error_description}` : "") + invalidClientHint(body.error, config.clientSecret !== void 0)
+      );
+    }
+    const claims = await verifyIdToken(body.id_token, { nonce });
+    const merged = body.access_token ? await withUserInfo(claims, body.access_token) : { claims, unverifiedClaims: [] };
+    return {
+      claims: merged.claims,
+      unverifiedClaims: merged.unverifiedClaims,
+      idToken: body.id_token,
+      ...body.access_token ? { accessToken: body.access_token } : {},
+      ...body.refresh_token ? { refreshToken: body.refresh_token } : {},
+      ...typeof body.expires_in === "number" ? { expiresIn: body.expires_in } : {}
+    };
+  }
+  async function embeddedCall(method, path, body) {
+    if (!config.clientSecret) throw new SsoError("the embedded login runs from the server as a confidential client \u2014 set clientSecret (SSO_CLIENT_SECRET)");
+    const url = new URL(`/embedded${path}`, config.issuer).toString();
+    let res;
+    try {
+      res = await fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Basic ${btoa(`${config.clientId}:${config.clientSecret}`)}`,
+          accept: "application/json",
+          ...body ? { "content-type": "application/json" } : {}
+        },
+        ...body ? { body: JSON.stringify({ client_id: config.clientId, ...body }) } : {}
+      });
+    } catch (e) {
+      return { ok: false, status: 0, body: { error: "network", message: e instanceof Error ? e.message : String(e) } };
+    }
+    const raw = await res.text();
+    let json = {};
+    try {
+      json = raw.trim() ? JSON.parse(raw) : {};
+    } catch {
+    }
+    if (res.status === 401) {
+      throw new SsoError(`BID refused this app's client credentials on /embedded${path} (401 ${typeof json.error === "string" ? json.error : "invalid_client"}) \u2014 check SSO_CLIENT_ID / SSO_CLIENT_SECRET`);
+    }
+    return res.ok ? { ok: true, body: json } : { ok: false, status: res.status, body: json };
+  }
+  const toError = (r) => r.status === 0 ? { kind: "unavailable", message: `BID did not answer: ${String(r.body.message ?? "")}` } : embeddedError(r.status, r.body);
+  async function embeddedNext(r, flow) {
+    if (!r.ok) return { kind: "error", error: toError(r) };
+    if (r.body.next === "done" && typeof r.body.code === "string") {
+      return { kind: "done", result: await exchangeCode(r.body.code, flow.codeVerifier, flow.nonce) };
+    }
+    if (r.body.next === "second_factor") {
+      const methods = (Array.isArray(r.body.methods) ? r.body.methods : []).filter((m) => m === "totp" || m === "sms");
+      return { kind: "second_factor", methods };
+    }
+    return { kind: "error", error: { kind: "unavailable", message: "BID's answer names no next step" } };
+  }
+  const embedded = {
+    async start(input) {
+      const codeVerifier = randomToken();
+      const nonce = randomToken(16);
+      const r = await embeddedCall("POST", "/start", {
+        email: input.email,
+        code_challenge: await challengeFor(codeVerifier),
+        code_challenge_method: "S256",
+        nonce,
+        ...input.intent === "signup" ? { intent: "signup", name: input.name, terms_version: input.termsVersion } : {},
+        ...input.endUserIp ? { end_user_ip: input.endUserIp } : {}
+      });
+      if (!r.ok) return { ok: false, error: toError(r) };
+      if (typeof r.body.flow_id !== "string") return { ok: false, error: { kind: "unavailable", message: "BID's answer has no flow_id" } };
+      return {
+        ok: true,
+        flow: { flowId: r.body.flow_id, codeVerifier, nonce, email: input.email },
+        expiresIn: typeof r.body.expires_in === "number" ? r.body.expires_in : 600
+      };
+    },
+    async verify(flow, code) {
+      return embeddedNext(await embeddedCall("POST", "/verify", { flow_id: flow.flowId, code }), flow);
+    },
+    async sendSms(flow) {
+      const r = await embeddedCall("POST", "/second-factor/sms", { flow_id: flow.flowId });
+      return r.ok ? { ok: true } : { ok: false, error: toError(r) };
+    },
+    async verifySecondFactor(flow, method, code) {
+      return embeddedNext(await embeddedCall("POST", "/second-factor", { flow_id: flow.flowId, method, code }), flow);
+    },
+    async terms(lang) {
+      const r = await embeddedCall("GET", `/terms?lang=${lang}`);
+      const b = r.body;
+      if (!r.ok || typeof b.version !== "string" || typeof b.text !== "string") {
+        throw new SsoError(`BID did not answer the signup terms (${r.ok ? "no version/text" : r.status})`);
+      }
+      const links = (Array.isArray(b.links) ? b.links : []).filter(
+        (l) => typeof l === "object" && l !== null && typeof l.label === "string" && typeof l.url === "string"
+      );
+      return { version: b.version, text: b.text, links: links.map((l) => ({ label: l.label, url: l.url })) };
+    }
+  };
   return {
     discovery,
     introspectToken,
+    embedded,
     get jwks() {
       if (!jwksCache) throw new SsoError("the key cache is created on first verification");
       return jwksCache;
@@ -595,45 +840,7 @@ function createSsoClient(config, options = {}) {
       }
       const code = params.get("code");
       if (!code) throw new SsoError("callback carried neither an error nor a code");
-      const { token_endpoint } = await discovery();
-      const res = await fetchImpl(token_endpoint, {
-        method: "POST",
-        headers: { "content-type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({
-          grant_type: "authorization_code",
-          code,
-          redirect_uri: config.redirectUri,
-          client_id: config.clientId,
-          // ALWAYS sent, secret or not. See SsoConfig.clientSecret: the two
-          // prove different things, so a confidential client keeps PKCE.
-          code_verifier: codeVerifier,
-          ...config.clientSecret ? { client_secret: config.clientSecret } : {}
-        })
-      });
-      const raw = await res.text();
-      let body;
-      try {
-        body = raw.trim() === "" ? {} : JSON.parse(raw);
-      } catch {
-        throw new SsoError(
-          `token exchange failed (${res.status}): the response body is not JSON${res.headers.get("content-type") ? ` (content-type: ${res.headers.get("content-type")})` : ""} \u2014 ${excerptForLog(raw, config.clientSecret)}`
-        );
-      }
-      if (!res.ok || !body.id_token) {
-        throw new SsoError(
-          `token exchange failed (${res.status}): ${body.error ?? "no id_token in response"}` + (body.error_description ? ` \u2014 ${body.error_description}` : "") + invalidClientHint(body.error, config.clientSecret !== void 0)
-        );
-      }
-      const claims = await verifyIdToken(body.id_token, { nonce });
-      const merged = body.access_token ? await withUserInfo(claims, body.access_token) : { claims, unverifiedClaims: [] };
-      return {
-        claims: merged.claims,
-        unverifiedClaims: merged.unverifiedClaims,
-        idToken: body.id_token,
-        ...body.access_token ? { accessToken: body.access_token } : {},
-        ...body.refresh_token ? { refreshToken: body.refresh_token } : {},
-        ...typeof body.expires_in === "number" ? { expiresIn: body.expires_in } : {}
-      };
+      return exchangeCode(code, codeVerifier, nonce);
     },
     async refreshTokens(refreshToken) {
       const { token_endpoint } = await discovery();
@@ -750,96 +957,6 @@ function createSsoClient(config, options = {}) {
   };
 }
 
-// src/session.ts
-var enc = new TextEncoder();
-var b64url2 = (bytes) => {
-  let s = "";
-  for (const b of bytes) s += String.fromCharCode(b);
-  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-};
-var fromB64url = (s) => {
-  const pad = s.replace(/-/g, "+").replace(/_/g, "/");
-  const bin = atob(pad + "=".repeat((4 - pad.length % 4) % 4));
-  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
-};
-async function hmacKey(secret) {
-  return crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
-    "sign",
-    "verify"
-  ]);
-}
-async function signValue(value, secret, options = {}) {
-  const payload = b64url2(enc.encode(value));
-  const body = options.maxAgeSeconds === void 0 ? payload : `t${Math.floor((options.now ?? Date.now)() / 1e3)}~${payload}`;
-  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(secret), enc.encode(body)));
-  return `${body}.${b64url2(sig)}`;
-}
-var STAMPED = /^t(\d+)~(.*)$/s;
-async function verifyValue(token, secret, options = {}) {
-  if (!token) return null;
-  const dot = token.lastIndexOf(".");
-  if (dot <= 0) return null;
-  const body = token.slice(0, dot);
-  try {
-    const ok = await crypto.subtle.verify(
-      "HMAC",
-      await hmacKey(secret),
-      fromB64url(token.slice(dot + 1)),
-      enc.encode(body)
-    );
-    if (!ok) return null;
-    const stamped = STAMPED.exec(body);
-    if (options.maxAgeSeconds !== void 0) {
-      if (!stamped) return null;
-      const issuedAt = Number(stamped[1]);
-      if ((options.now ?? Date.now)() / 1e3 - issuedAt > options.maxAgeSeconds) return null;
-    }
-    return new TextDecoder().decode(fromB64url(stamped?.[2] ?? body));
-  } catch {
-    return null;
-  }
-}
-async function signSession(payload, secret) {
-  return signValue(JSON.stringify(payload), secret);
-}
-async function verifySession(token, secret, now = Date.now) {
-  const body = await verifyValue(token, secret);
-  if (body === null) return null;
-  try {
-    const payload = JSON.parse(body);
-    if (typeof payload.sub !== "string" || payload.sub === "") return null;
-    if (typeof payload.exp !== "number" || payload.exp * 1e3 <= now()) return null;
-    return payload;
-  } catch {
-    return null;
-  }
-}
-function cookieHeader(name, value, opts) {
-  const parts = [
-    `${name}=${value}`,
-    `Path=${opts.path ?? "/"}`,
-    `Max-Age=${opts.maxAge}`,
-    "HttpOnly",
-    // Lax, NOT Strict, and this is load-bearing: the callback from BrobergID
-    // is a top-level GET navigation from another site. Strict withholds the
-    // cookie on exactly that navigation, so the login transaction cookie would
-    // be missing when it is needed and every sign-in would fail with "state
-    // does not match" — a message that sends you looking in the wrong place.
-    `SameSite=${opts.sameSite ?? "Lax"}`
-  ];
-  if (opts.secure) parts.push("Secure");
-  return parts.join("; ");
-}
-function readCookie(header, name) {
-  if (!header) return void 0;
-  for (const part of header.split(";")) {
-    const eq = part.indexOf("=");
-    if (eq === -1) continue;
-    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
-  }
-  return void 0;
-}
-
 // src/tokens.ts
 var warned = false;
 function memoryTokenStore(options = {}) {
@@ -890,6 +1007,7 @@ function newSid() {
 exports.ALLOWED_ALGS = ALLOWED_ALGS;
 exports.AVATAR_TYPES = AVATAR_TYPES;
 exports.DEFAULT_SESSION_MAX_AGE = DEFAULT_SESSION_MAX_AGE;
+exports.EMBEDDED_FLOW_MAX_AGE = EMBEDDED_FLOW_MAX_AGE;
 exports.JwksError = JwksError;
 exports.JwksUnavailableError = JwksUnavailableError;
 exports.JwksUnknownKeyError = JwksUnknownKeyError;
@@ -911,10 +1029,12 @@ exports.loadSsoConfig = loadSsoConfig;
 exports.mediaType = mediaType;
 exports.memoryTokenStore = memoryTokenStore;
 exports.newSid = newSid;
+exports.openEmbeddedFlow = openEmbeddedFlow;
 exports.readCookie = readCookie;
+exports.sealEmbeddedFlow = sealEmbeddedFlow;
 exports.signSession = signSession;
 exports.signValue = signValue;
 exports.verifySession = verifySession;
 exports.verifyValue = verifyValue;
-//# sourceMappingURL=chunk-CHRCHUZ3.cjs.map
-//# sourceMappingURL=chunk-CHRCHUZ3.cjs.map
+//# sourceMappingURL=chunk-MZE4TPFU.cjs.map
+//# sourceMappingURL=chunk-MZE4TPFU.cjs.map