@broberg/sso 0.3.2 → 0.5.0

package/README.md

@@ -248,3 +248,37 @@ match", which sends you looking at the OAuth flow instead of at a cookie flag.
 ## Licence
 
 MIT
+
+## Does this address belong to the user? (since 0.4.0)
+
+```ts
+const answer = await client.addressOwnership(accessToken, "a@example.dk");
+// "verified"        on the user's BID account and verified there
+// "unverified"      on the account, not verified
+// "not_on_account"  not on this user's account
+```
+
+Calls BID's `POST /api/app/address-ownership` with the user's access token. **It throws `SsoError` on anything else** — a non-2xx, a body that is not JSON, a missing or unknown status. Do not catch that into `"unverified"`: an error means *we do not know*, and treating it as "not verified" quietly downgrades a real user.
+
+## Inviting users and tracking the move to BID (since 0.5.0)
+
+Two calls that authenticate with **your app's own key** (`bidk_…`, issued by Broberg ID) — not the client secret, not a user's token.
+
+```ts
+const results = await client.inviteUsers(process.env.BID_APP_KEY!, {
+  customerName: "Sanne Andersen",
+  appUrl: "https://sanneandersen.dk",
+  appName: "CMS",               // optional
+  switchDate: "2026-10-15",     // optional
+  users: [{ email: "sanne@example.dk", name: "Sanne" }],   // max 500 per call
+});
+// [{ email, outcome: "invited" | "already_invited" | "existing" | "invalid"
+//                   | "too_soon" | "too_many_today" | "send_failed", mailId?, problem? }]
+
+const status = await client.migrationStatus(process.env.BID_APP_KEY!, ["sanne@example.dk"]);
+// { users: [{ email, state: "ready" | "invited" | "expired" | "not_invited", expiresAt? }], counts, complete }
+```
+
+**Both throw `SsoError`** on a non-2xx (a refused key says `invalid_app_key`), a body that is not JSON, a missing array, or an outcome/state this client does not know. **Never treat an error as `"ready"`**: switching off a user's old login because BID's answer was unclear is how someone gets locked out.
+
+**Timeout.** `addressOwnership`, `inviteUsers` and `migrationStatus` give up after `timeoutMs` (default 10 000) with `SsoError`, so a hanging BID cannot hang your app: `createSsoClient(config, { timeoutMs: 5_000 })`.

package/dist/hono.cjs

@@ -122,8 +122,13 @@ function createJwksCache(options) {
           `${jwksUri} answered ${res.status} \u2014 cannot verify any token right now`
         );
       }
-      const body = await res.json();
-      if (!Array.isArray(body.keys)) {
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        throw new JwksUnavailableError(`${jwksUri} answered 200 with a body that is not JSON`);
+      }
+      if (!Array.isArray(body?.keys)) {
         throw new JwksUnavailableError(`${jwksUri} returned no "keys" array`);
       }
       keys = body.keys;
@@ -181,6 +186,18 @@ var randomToken = (bytes = 32) => b64url(crypto.getRandomValues(new Uint8Array(b
 async function challengeFor(verifier) {
   return b64url(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([
+  "invited",
+  "already_invited",
+  "existing",
+  "invalid",
+  "too_soon",
+  "too_many_today",
+  "send_failed"
+]);
+var MIGRATION_STATES = /* @__PURE__ */ new Set(["ready", "invited", "expired", "not_invited"]);
+var MAX_INVITATIONS = 500;
 function excerptForLog(raw, clientSecret) {
   let text = raw.replace(/\s+/g, " ").trim();
   if (clientSecret) text = text.split(clientSecret).join("[redacted client_secret]");
@@ -215,6 +232,40 @@ var ALLOWED_ALGS = [
 ];
 function createSsoClient(config, options = {}) {
   const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  async function appPost(path, bearer, payload, what) {
+    const url = new URL(path, config.issuer).toString();
+    const ctrl = new AbortController();
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        ctrl.abort();
+        reject(new SsoError(`${url} did not answer within ${timeoutMs} ms \u2014 ${what} is unknown.`));
+      }, timeoutMs);
+    });
+    try {
+      const res = await Promise.race([
+        fetchImpl(url, {
+          method: "POST",
+          headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json" },
+          body: JSON.stringify(payload),
+          signal: ctrl.signal
+        }),
+        timedOut
+      ]);
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        const hint = detail.includes("invalid_app_key") ? " (invalid_app_key: this app's bidk_ key was refused)" : "";
+        throw new SsoError(`${url} answered ${res.status}${hint} \u2014 ${what} is unknown.`);
+      }
+      return await Promise.race([res.json().catch(() => null), timedOut]);
+    } catch (e) {
+      if (e instanceof SsoError) throw e;
+      throw new SsoError(`${url} could not be reached: ${e instanceof Error ? e.message : String(e)} \u2014 ${what} is unknown.`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   let discoveryPromise = null;
   let jwksCache = null;
   async function discovery() {
@@ -379,6 +430,46 @@ function createSsoClient(config, options = {}) {
       if (post) params.set("post_logout_redirect_uri", post);
       params.set("client_id", config.clientId);
       return `${doc.end_session_endpoint}?${params}`;
+    },
+    async addressOwnership(accessToken, address) {
+      const body = await appPost(
+        "/api/app/address-ownership",
+        accessToken,
+        { address },
+        'address ownership (not "unverified")'
+      );
+      const status = body?.status;
+      if (typeof status !== "string" || !ADDRESS_OWNERSHIP.has(status)) {
+        throw new SsoError(`address-ownership returned status ${JSON.stringify(status)} \u2014 expected verified, unverified or not_on_account.`);
+      }
+      return status;
+    },
+    async inviteUsers(appKey, input) {
+      if (input.users.length > MAX_INVITATIONS) {
+        throw new SsoError(`inviteUsers: ${input.users.length} users, BID accepts at most ${MAX_INVITATIONS} per call.`);
+      }
+      const body = await appPost("/api/app/invitations", appKey, input, "the invitation outcome");
+      if (!Array.isArray(body?.results)) {
+        throw new SsoError(`invitations returned no "results" array \u2014 the invitation outcome is unknown.`);
+      }
+      for (const r of body.results) {
+        if (typeof r?.outcome !== "string" || !INVITATION_OUTCOMES.has(r.outcome)) {
+          throw new SsoError(`invitations returned outcome ${JSON.stringify(r?.outcome)} for ${String(r?.email)} \u2014 not one this client knows.`);
+        }
+      }
+      return body.results;
+    },
+    async migrationStatus(appKey, emails) {
+      const body = await appPost("/api/app/migration-status", appKey, { emails }, "the migration state");
+      if (!Array.isArray(body?.users) || typeof body.complete !== "boolean") {
+        throw new SsoError(`migration-status returned no "users" array or no "complete" flag \u2014 the migration state is unknown.`);
+      }
+      for (const u of body.users) {
+        if (typeof u?.state !== "string" || !MIGRATION_STATES.has(u.state)) {
+          throw new SsoError(`migration-status returned state ${JSON.stringify(u?.state)} for ${String(u?.email)} \u2014 never read as "ready".`);
+        }
+      }
+      return body;
     }
   };
 }