@broberg/sso 0.9.0 → 0.10.0

package/dist/hono.d.cts

@@ -139,6 +139,15 @@ interface Discovery {
     userinfo_endpoint?: string;
     end_session_endpoint?: string;
 }
+/** The signed-in user's own profile, as BID's GET /api/app/profile returns it. */
+interface BidProfile {
+    sub: string;
+    name: string | null;
+    picture: string | null;
+    email: string | null;
+    /** BID's own account page — mail, password, passkeys, 2FA and sessions live there. */
+    account_url: string;
+}
 /**
  * What `beginLogin` produces. Every field except `url` must survive the round
  * trip to BID and back — the adapter stores them in a short-lived cookie.
@@ -244,6 +253,21 @@ interface SsoClient {
      * Throws SsoError on anything that is not a valid, sub-only logout token.
      */
     verifyLogoutToken(token: string): Promise<LogoutToken>;
+    /**
+     * F095.2 — the signed-in user's own profile (scope `profile`), with the user's
+     * access token. Throws SsoAppApiError on any refusal.
+     */
+    getProfile(accessToken: string): Promise<BidProfile>;
+    /** F095.2 — change the user's own name (scope `profile:write`). Returns the new profile. */
+    updateProfile(accessToken: string, name: string): Promise<BidProfile>;
+    /**
+     * F095.2 — replace the user's picture (scope `profile:write`). Refuses more than
+     * MAX_AVATAR_BYTES or a type outside AVATAR_TYPES with SsoAvatarRejectedError
+     * BEFORE anything is sent.
+     */
+    uploadAvatar(accessToken: string, bytes: Uint8Array | ArrayBuffer, contentType: string): Promise<BidProfile>;
+    /** F095.2 — remove the user's picture (scope `profile:write`). */
+    removeAvatar(accessToken: string): Promise<BidProfile>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
@@ -428,5 +452,28 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
 type TransactionFailure = "absent" | "expired" | "unreadable";
 /** Read the session a middleware attached. */
 declare function getSession(c: Context): SessionPayload | null;
+/** What accountRoutes needs from ssoRoutes — pass its return value as is. */
+interface AccountRoutesInput {
+    client: Pick<SsoClient, "getProfile" | "updateProfile" | "uploadAvatar" | "removeAvatar">;
+    getAccessToken(c: Context): Promise<string>;
+}
+/**
+ * The signed-in user's own name and picture, for the app's account page.
+ * Mount it on /api/account:
+ *
+ *   const sso = ssoRoutes({ tokenStore });
+ *   app.route("/api/account", accountRoutes(sso));
+ *
+ * GET /profile · POST /profile {name} · POST /profile/avatar (raw image body) ·
+ * POST /profile/avatar/remove. Every answer is JSON, refusals included — it is
+ * an API, so never a login redirect:
+ *   401 {error:"unauthenticated"}            no live session
+ *   401 {error:"reauth"}                     the session's tokens are spent — log in again
+ *   403 {error:"insufficient_scope", scope}  log in again with that scope requested
+ *   413 / 415                                picture too large / not PNG, JPEG or WebP
+ *   4xx {error:<BID's code>}                 BID refused the change (e.g. an invalid name)
+ *   502 {error:"bid_unavailable"}            BID did not answer usably
+ */
+declare function accountRoutes(sso: AccountRoutesInput): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };
+export { type AccountRoutesInput, type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, accountRoutes, getSession, ssoRoutes };

package/dist/hono.d.ts

@@ -139,6 +139,15 @@ interface Discovery {
     userinfo_endpoint?: string;
     end_session_endpoint?: string;
 }
+/** The signed-in user's own profile, as BID's GET /api/app/profile returns it. */
+interface BidProfile {
+    sub: string;
+    name: string | null;
+    picture: string | null;
+    email: string | null;
+    /** BID's own account page — mail, password, passkeys, 2FA and sessions live there. */
+    account_url: string;
+}
 /**
  * What `beginLogin` produces. Every field except `url` must survive the round
  * trip to BID and back — the adapter stores them in a short-lived cookie.
@@ -244,6 +253,21 @@ interface SsoClient {
      * Throws SsoError on anything that is not a valid, sub-only logout token.
      */
     verifyLogoutToken(token: string): Promise<LogoutToken>;
+    /**
+     * F095.2 — the signed-in user's own profile (scope `profile`), with the user's
+     * access token. Throws SsoAppApiError on any refusal.
+     */
+    getProfile(accessToken: string): Promise<BidProfile>;
+    /** F095.2 — change the user's own name (scope `profile:write`). Returns the new profile. */
+    updateProfile(accessToken: string, name: string): Promise<BidProfile>;
+    /**
+     * F095.2 — replace the user's picture (scope `profile:write`). Refuses more than
+     * MAX_AVATAR_BYTES or a type outside AVATAR_TYPES with SsoAvatarRejectedError
+     * BEFORE anything is sent.
+     */
+    uploadAvatar(accessToken: string, bytes: Uint8Array | ArrayBuffer, contentType: string): Promise<BidProfile>;
+    /** F095.2 — remove the user's picture (scope `profile:write`). */
+    removeAvatar(accessToken: string): Promise<BidProfile>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
@@ -428,5 +452,28 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
 type TransactionFailure = "absent" | "expired" | "unreadable";
 /** Read the session a middleware attached. */
 declare function getSession(c: Context): SessionPayload | null;
+/** What accountRoutes needs from ssoRoutes — pass its return value as is. */
+interface AccountRoutesInput {
+    client: Pick<SsoClient, "getProfile" | "updateProfile" | "uploadAvatar" | "removeAvatar">;
+    getAccessToken(c: Context): Promise<string>;
+}
+/**
+ * The signed-in user's own name and picture, for the app's account page.
+ * Mount it on /api/account:
+ *
+ *   const sso = ssoRoutes({ tokenStore });
+ *   app.route("/api/account", accountRoutes(sso));
+ *
+ * GET /profile · POST /profile {name} · POST /profile/avatar (raw image body) ·
+ * POST /profile/avatar/remove. Every answer is JSON, refusals included — it is
+ * an API, so never a login redirect:
+ *   401 {error:"unauthenticated"}            no live session
+ *   401 {error:"reauth"}                     the session's tokens are spent — log in again
+ *   403 {error:"insufficient_scope", scope}  log in again with that scope requested
+ *   413 / 415                                picture too large / not PNG, JPEG or WebP
+ *   4xx {error:<BID's code>}                 BID refused the change (e.g. an invalid name)
+ *   502 {error:"bid_unavailable"}            BID did not answer usably
+ */
+declare function accountRoutes(sso: AccountRoutesInput): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };
+export { type AccountRoutesInput, type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, accountRoutes, getSession, ssoRoutes };

package/dist/hono.js

@@ -174,6 +174,45 @@ var SsoError = class extends Error {
     this.name = "SsoError";
   }
 };
+var SsoReauthError = class extends SsoError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "SsoReauthError";
+  }
+  reason;
+};
+var SsoAppApiError = class extends SsoError {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "SsoAppApiError";
+  }
+  status;
+  code;
+};
+var SsoInsufficientScopeError = class extends SsoAppApiError {
+  constructor(message, scope) {
+    super(message, 403, "insufficient_scope");
+    this.scope = scope;
+    this.name = "SsoInsufficientScopeError";
+  }
+  scope;
+};
+var SsoAvatarRejectedError = class extends SsoError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "SsoAvatarRejectedError";
+  }
+  reason;
+};
+var MAX_AVATAR_BYTES = 2 * 1024 * 1024;
+var AVATAR_TYPES = ["image/png", "image/jpeg", "image/webp"];
+function mediaType(contentType) {
+  return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
 var b64url = (bytes) => {
   const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
   let s = "";
@@ -265,6 +304,68 @@ function createSsoClient(config, options = {}) {
       clearTimeout(timer);
     }
   }
+  async function appRequest(path, bearer, init, what) {
+    const url = new URL(path, config.issuer).toString();
+    const ctrl = new AbortController();
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new SsoAppApiError(`${url} did not answer within ${timeoutMs} ms \u2014 ${what} is unknown.`, null, void 0));
+        ctrl.abort();
+      }, timeoutMs);
+    });
+    const headers = { authorization: `Bearer ${bearer}` };
+    let body;
+    if (init.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.json);
+    } else if (init.bytes !== void 0) {
+      headers["content-type"] = init.contentType ?? "application/octet-stream";
+      body = init.bytes;
+    }
+    try {
+      const res = await Promise.race([
+        fetchImpl(url, { method: init.method, headers, ...body !== void 0 ? { body } : {}, signal: ctrl.signal }),
+        timedOut
+      ]);
+      const raw = await Promise.race([res.text(), timedOut]);
+      let parsed;
+      try {
+        parsed = raw.trim() === "" ? void 0 : JSON.parse(raw);
+      } catch {
+        parsed = void 0;
+      }
+      const fields = parsed && typeof parsed === "object" ? parsed : {};
+      const code = typeof fields.error === "string" ? fields.error : void 0;
+      if (!res.ok) {
+        if (res.status === 403 && code === "insufficient_scope") {
+          const scope = typeof fields.scope === "string" && fields.scope ? fields.scope : init.method === "GET" ? "profile" : "profile:write";
+          throw new SsoInsufficientScopeError(
+            `${url} answered 403 insufficient_scope \u2014 the user's token lacks scope "${scope}"; log in again with it requested.`,
+            scope
+          );
+        }
+        throw new SsoAppApiError(`${url} answered ${res.status}${code ? ` (${code})` : ""} \u2014 ${what} is unknown.`, res.status, code);
+      }
+      if (parsed === void 0) {
+        throw new SsoAppApiError(`${url} answered ${res.status} with a body that is not JSON \u2014 ${what} is unknown.`, res.status, void 0);
+      }
+      return parsed;
+    } catch (e) {
+      if (e instanceof SsoError) throw e;
+      throw new SsoAppApiError(`${url} could not be reached (${e instanceof Error ? e.name : "error"}) \u2014 ${what} is unknown.`, null, void 0);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  function asProfile(body, path) {
+    const b = body ?? {};
+    if (typeof b.sub !== "string" || b.sub === "" || typeof b.account_url !== "string") {
+      throw new SsoAppApiError(`${path} returned no "sub" or "account_url" \u2014 the profile is unknown.`, 200, void 0);
+    }
+    const opt = (v) => typeof v === "string" ? v : null;
+    return { sub: b.sub, name: opt(b.name), picture: opt(b.picture), email: opt(b.email), account_url: b.account_url };
+  }
   let discoveryPromise = null;
   let jwksCache = null;
   async function discovery() {
@@ -508,6 +609,35 @@ function createSsoClient(config, options = {}) {
       return status;
     },
     verifyLogoutToken,
+    async getProfile(accessToken) {
+      const path = "/api/app/profile";
+      return asProfile(await appRequest(path, accessToken, { method: "GET" }, "the profile"), path);
+    },
+    async updateProfile(accessToken, name) {
+      const path = "/api/app/profile";
+      return asProfile(await appRequest(path, accessToken, { method: "POST", json: { name } }, "the new name"), path);
+    },
+    async uploadAvatar(accessToken, bytes, contentType) {
+      const type = mediaType(contentType);
+      if (!AVATAR_TYPES.includes(type)) {
+        throw new SsoAvatarRejectedError(
+          `uploadAvatar: "${type}" is not accepted \u2014 BID takes ${AVATAR_TYPES.join(", ")}.`,
+          "unsupported_type"
+        );
+      }
+      if (bytes.byteLength > MAX_AVATAR_BYTES) {
+        throw new SsoAvatarRejectedError(
+          `uploadAvatar: ${bytes.byteLength} bytes \u2014 BID takes at most ${MAX_AVATAR_BYTES}.`,
+          "too_large"
+        );
+      }
+      const path = "/api/app/profile/avatar";
+      return asProfile(await appRequest(path, accessToken, { method: "POST", bytes, contentType: type }, "the new picture"), path);
+    },
+    async removeAvatar(accessToken) {
+      const path = "/api/app/profile/avatar/remove";
+      return asProfile(await appRequest(path, accessToken, { method: "POST" }, "the removed picture"), path);
+    },
     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.`);
@@ -878,17 +1008,17 @@ function ssoRoutes(options = {}) {
     const live = await liveSession(c);
     if (!live) {
       if (raw?.sid) await tokenStore.delete(raw.sid);
-      throw new SsoError("no live session \u2014 log in again.");
+      throw new SsoReauthError("no live session \u2014 log in again.", "no_session");
     }
     const sid = live.sid;
-    if (!sid) throw new SsoError("this session has no stored tokens (it began before tokenStore was configured) \u2014 log in again.");
+    if (!sid) throw new SsoReauthError("this session has no stored tokens (it began before tokenStore was configured) \u2014 log in again.", "no_tokens");
     const tokens = await tokenStore.get(sid);
-    if (!tokens) throw new SsoError("no tokens stored for this session \u2014 log in again.");
+    if (!tokens) throw new SsoReauthError("no tokens stored for this session \u2014 log in again.", "no_tokens");
     const now = Math.floor(Date.now() / 1e3);
     if (tokens.expiresAt - 30 > now) return tokens.accessToken;
     if (!tokens.refreshToken) {
       await tokenStore.delete(sid);
-      throw new SsoError("the access token has expired and there is no refresh token \u2014 log in again.");
+      throw new SsoReauthError("the access token has expired and there is no refresh token \u2014 log in again.", "expired");
     }
     const inFlight = refreshing.get(sid);
     if (inFlight) return inFlight;
@@ -898,7 +1028,7 @@ function ssoRoutes(options = {}) {
         next = await client.refreshTokens(tokens.refreshToken);
       } catch (e) {
         await tokenStore.delete(sid);
-        throw e instanceof SsoError ? e : new SsoError("token refresh failed");
+        throw new SsoReauthError(e instanceof SsoError ? e.message : "token refresh failed", "refresh_failed");
       }
       await tokenStore.set(sid, {
         sub: tokens.sub,
@@ -935,7 +1065,99 @@ async function parseTransaction(raw, secret) {
 function getSession(c) {
   return c.get(SESSION_KEY) ?? null;
 }
+function errName(e) {
+  return e instanceof Error ? e.name : void 0;
+}
+async function readCapped(c, max) {
+  const stream = c.req.raw.body;
+  if (!stream) return new Uint8Array(0);
+  const reader = stream.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > max) {
+      await reader.cancel().catch(() => {
+      });
+      return null;
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(size);
+  let at = 0;
+  for (const ch of chunks) {
+    out.set(ch, at);
+    at += ch.byteLength;
+  }
+  return out;
+}
+function accountRoutes(sso) {
+  const app = new Hono();
+  const { client } = sso;
+  app.use("*", async (c, next) => {
+    c.header("Cache-Control", "no-store");
+    await next();
+  });
+  app.use("*", async (c, next) => {
+    const site = c.req.header("sec-fetch-site");
+    if (c.req.method !== "GET" && site !== void 0 && site !== "same-origin" && site !== "none") {
+      return c.json({ error: "cross_site" }, 403);
+    }
+    await next();
+  });
+  app.get("/profile", async (c) => c.json(await client.getProfile(await sso.getAccessToken(c))));
+  app.post("/profile", async (c) => {
+    const token = await sso.getAccessToken(c);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body?.name !== "string") {
+      return c.json({ error: "invalid_request", error_description: '"name" must be a string' }, 400);
+    }
+    return c.json(await client.updateProfile(token, body.name));
+  });
+  app.post("/profile/avatar", async (c) => {
+    const token = await sso.getAccessToken(c);
+    const type = mediaType(c.req.header("content-type"));
+    if (!AVATAR_TYPES.includes(type)) {
+      return c.json({ error: "unsupported_type", accepted: AVATAR_TYPES }, 415);
+    }
+    const declared = Number(c.req.header("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_AVATAR_BYTES) {
+      return c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413);
+    }
+    const bytes = await readCapped(c, MAX_AVATAR_BYTES);
+    if (!bytes) return c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413);
+    return c.json(await client.uploadAvatar(token, bytes, type));
+  });
+  app.post("/profile/avatar/remove", async (c) => c.json(await client.removeAvatar(await sso.getAccessToken(c))));
+  app.onError((err, c) => {
+    c.header("Cache-Control", "no-store");
+    const e = err;
+    switch (errName(err)) {
+      case "SsoReauthError":
+        return c.json({ error: e.reason === "no_session" ? "unauthenticated" : "reauth" }, 401);
+      case "SsoInsufficientScopeError":
+        return c.json({ error: "insufficient_scope", scope: e.scope }, 403);
+      case "SsoAvatarRejectedError":
+        return e.reason === "too_large" ? c.json({ error: "too_large", max_bytes: MAX_AVATAR_BYTES }, 413) : c.json({ error: "unsupported_type", accepted: AVATAR_TYPES }, 415);
+      case "SsoAppApiError": {
+        if (e.status === 401) return c.json({ error: "reauth" }, 401);
+        if (typeof e.status === "number" && e.status >= 400 && e.status < 500) {
+          return c.json({ error: e.code ?? "bid_refused" }, e.status);
+        }
+        return c.json({ error: "bid_unavailable" }, 502);
+      }
+      // A plain SsoError here is a setup mistake (e.g. ssoRoutes without tokenStore).
+      case "SsoError":
+        return c.json({ error: "sso_misconfigured" }, 500);
+      default:
+        return c.json({ error: "server_error" }, 500);
+    }
+  });
+  return app;
+}
 
-export { getSession, ssoRoutes };
+export { accountRoutes, getSession, ssoRoutes };
 //# sourceMappingURL=hono.js.map
 //# sourceMappingURL=hono.js.map