@broberg/sso 0.4.0 → 0.5.0

package/dist/hono.d.cts

@@ -204,10 +204,48 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
+     * One result per email. Throws SsoError on anything BID did not clearly say.
+     */
+    inviteUsers(appKey: string, input: InviteUsersInput): Promise<InvitationResult[]>;
+    /**
+     * Where each user is in the move to BID. Throws SsoError on any state it does
+     * not know — never a silent "ready", which would switch off a user's old login
+     * while they cannot get in.
+     */
+    migrationStatus(appKey: string, emails: string[]): Promise<MigrationStatus>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
 type AddressOwnership = "verified" | "unverified" | "not_on_account";
+type InvitationOutcome = "invited" | "already_invited" | "existing" | "invalid" | "too_soon" | "too_many_today" | "send_failed";
+interface InviteUsersInput {
+    customerName: string;
+    appUrl: string;
+    appName?: string;
+    switchDate?: string;
+    users: Array<{
+        email: string;
+        name: string;
+    }>;
+}
+interface InvitationResult {
+    email: string;
+    outcome: InvitationOutcome;
+    mailId?: string;
+    problem?: string;
+}
+type MigrationState = "ready" | "invited" | "expired" | "not_invited";
+interface MigrationStatus {
+    users: Array<{
+        email: string;
+        state: MigrationState;
+        expiresAt?: string;
+    }>;
+    counts: Record<string, number>;
+    complete: boolean;
+}
 
 /**
  * The app's OWN session cookie — signed, not encrypted.

package/dist/hono.d.ts

@@ -204,10 +204,48 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
+     * One result per email. Throws SsoError on anything BID did not clearly say.
+     */
+    inviteUsers(appKey: string, input: InviteUsersInput): Promise<InvitationResult[]>;
+    /**
+     * Where each user is in the move to BID. Throws SsoError on any state it does
+     * not know — never a silent "ready", which would switch off a user's old login
+     * while they cannot get in.
+     */
+    migrationStatus(appKey: string, emails: string[]): Promise<MigrationStatus>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
 type AddressOwnership = "verified" | "unverified" | "not_on_account";
+type InvitationOutcome = "invited" | "already_invited" | "existing" | "invalid" | "too_soon" | "too_many_today" | "send_failed";
+interface InviteUsersInput {
+    customerName: string;
+    appUrl: string;
+    appName?: string;
+    switchDate?: string;
+    users: Array<{
+        email: string;
+        name: string;
+    }>;
+}
+interface InvitationResult {
+    email: string;
+    outcome: InvitationOutcome;
+    mailId?: string;
+    problem?: string;
+}
+type MigrationState = "ready" | "invited" | "expired" | "not_invited";
+interface MigrationStatus {
+    users: Array<{
+        email: string;
+        state: MigrationState;
+        expiresAt?: string;
+    }>;
+    counts: Record<string, number>;
+    complete: boolean;
+}
 
 /**
  * The app's OWN session cookie — signed, not encrypted.

package/dist/hono.js

@@ -185,6 +185,17 @@ 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]");
@@ -219,6 +230,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() {
@@ -385,21 +430,44 @@ function createSsoClient(config, options = {}) {
       return `${doc.end_session_endpoint}?${params}`;
     },
     async addressOwnership(accessToken, address) {
-      const url = new URL("/api/app/address-ownership", config.issuer).toString();
-      const res = await fetchImpl(url, {
-        method: "POST",
-        headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-        body: JSON.stringify({ address })
-      });
-      if (!res.ok) {
-        throw new SsoError(`${url} answered ${res.status} \u2014 address ownership is unknown, not "unverified".`);
-      }
-      const body = await res.json().catch(() => null);
+      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(`${url} returned status ${JSON.stringify(status)} \u2014 expected verified, unverified or not_on_account.`);
+        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;
     }
   };
 }