@kanzo-tech/auth 0.2.0

package/README.md

@@ -0,0 +1,103 @@
+# @kanzo-tech/auth
+
+Authentication over Keycloak: the claim vocabulary read into one session, the role evaluation that
+knows about organizations, and an authenticated `fetch`.
+
+## What it is not
+
+**There is no sign-in screen.** That is the shape of the package rather than a gap in it. A sign-in
+screen is a logo, a legal line, a privacy notice and a button, and every product answers those
+differently — `@kanzo-tech/ui` has the parts to draw one. What is genuinely shared sits underneath,
+and that is what is here.
+
+**There is no protocol in it either.** PKCE, silent renewal, token storage and cross-tab
+coordination are `oidc-client-ts`'s job, behind `./browser`; the confidential client is
+`openid-client`'s, behind `./server`. Writing either by hand is where mistakes turn into
+vulnerabilities, and neither is what this package is for.
+
+What is left after those two subtractions is everything this package is: **Keycloak's claims as one
+`Session`, a role predicate that understands organizations, one `fetch` that stays authenticated,
+and the same session shape across two deployment patterns that otherwise share no code.**
+
+## Why a package, and not `@kanzo-tech/ui`
+
+The [first admission rule](https://kanzo-tech.github.io/ui/docs/philosophy#admission) is *domain-free
+— nothing about RDF / SHACL / fossil / graphs / **auth***. Auth is excluded by name, deliberately:
+`ui` is the generic vocabulary every product shares. The rule was written after a sidebar composite
+shipped a hard-coded log-out flow, confirmation dialog and untranslatable copy included.
+
+## The one rule to read first
+
+**What a client knows about its roles is for drawing, never for deciding.**
+
+The roles in a `Session` are a copy, and a copy is something an attacker controls the moment it
+reaches the browser. `can` hides a button; the resource server, validating the access token it was
+sent, is what refuses the request behind it. A product that gates only in the browser has not gated
+anything.
+
+The same rule one level down: **never read the access token in the client.** It is opaque to a
+client by definition, its format is not guaranteed, and it may be encrypted for the resource —
+depending on its contents is, in Microsoft's words for the same mistake, *"one of the most common
+sources of errors and client logic breakage."* Roles for drawing come from the session, not from
+prising open a token.
+
+## Install
+
+```sh
+pnpm add @kanzo-tech/auth
+```
+
+That is the whole of it for a single-page application: the root barrel carries no engine. The other
+doors each name theirs — `oidc-client-ts` for `./browser`, `openid-client` and `jose` for
+`./server`, `next` for `./next` — and a consumer installs only the one it opens.
+
+## The claims it reads
+
+Nothing here is invented. Every claim is one Keycloak emits without being asked:
+
+| claim | becomes |
+| --- | --- |
+| `sub`, `email`, `name` (or `given_name` + `family_name`), `preferred_username` | `session.user` |
+| `realm_access.roles` ∪ `resource_access.<clientId>.roles` | `session.roles` |
+| `organization` — `{ "acme": { "id": "…", "groups": ["/keasy/owner"] } }` | `session.organizations` |
+| `exp` | `session.expiresAt`, in milliseconds |
+
+A group path's **first segment is the application**: `/keasy/owner` is a role in keasy, `/hub/reader`
+is not, and a single-segment `/owner` is granted across all of them. Without that filtering, a role
+held in one application would authorise its holder in another.
+
+Ask Keycloak for `organization:*` to receive every organization the person belongs to. Plain
+`organization` returns the only one when there is one and prompts for a choice when there are
+several, which is the documented behaviour behind more than one bug report about the claim
+"disappearing".
+
+## Membership is in the session; the active organization is not
+
+```ts
+interface Session {
+  user: AuthUser;
+  roles: readonly string[];
+  organizations: readonly Organization[];
+  expiresAt: number;
+}
+```
+
+There is no active organization on it, and the absence is deliberate. Membership is stable and comes
+from the token; which organization you are *looking at* is a property of the request — the URL — and
+deriving it per request is what lets two tabs sit in two organizations at once. A field here would
+be the single shared value they would fight over.
+
+Roles held inside an organization live on that organization, and are never merged into
+`session.roles`. Being an owner of one organization says nothing about another.
+
+```ts
+can(session, "auditor");           // a realm or client role
+can(session, "owner", "acme");     // a role inside that organization
+```
+
+There is no role hierarchy in the predicate. That `owner` outranks `member` is a fact about a
+product, so a product writes it where it can be seen:
+
+```ts
+const isMember = (org: string) => can(session, "owner", org) || can(session, "member", org);
+```

package/dist/auth-context.d.ts

@@ -0,0 +1,13 @@
+import { Auth, Session } from './types';
+/**
+ * The context, in its own module because two files need it and neither should import the other.
+ * `createContext` is what makes this file client-only.
+ */
+export type AuthStatus = "loading" | "authenticated" | "anonymous";
+export interface AuthContextValue {
+    readonly auth: Auth;
+    readonly session: Session | null;
+    readonly status: AuthStatus;
+}
+export declare const AuthContext: import('react').Context<AuthContextValue | null>;
+//# sourceMappingURL=auth-context.d.ts.map

package/dist/auth-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.d.ts","sourceRoot":"","sources":["../src/auth-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE7C;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,eAAe,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,eAAO,MAAM,WAAW,kDAA+C,CAAC"}

package/dist/auth-context.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext as t } from "react";
+const e = t(null);
+export {
+  e as AuthContext
+};
+//# sourceMappingURL=auth-context.js.map

package/dist/auth-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.js","sources":["../src/auth-context.ts"],"sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport type { Auth, Session } from \"./types\";\n\n/**\n * The context, in its own module because two files need it and neither should import the other.\n * `createContext` is what makes this file client-only.\n */\n\nexport type AuthStatus = \"loading\" | \"authenticated\" | \"anonymous\";\n\nexport interface AuthContextValue {\n  readonly auth: Auth;\n  readonly session: Session | null;\n  readonly status: AuthStatus;\n}\n\nexport const AuthContext = createContext<AuthContextValue | null>(null);\n"],"names":[],"mappings":";;AAkBO;;;;"}

package/dist/auth-fetch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A `fetch` that stays authenticated.
+ *
+ * This is the seam a product already has. keasy's API client is
+ * `createClient({ baseUrl: "/" })` with one middleware; the viewer's trace source takes its
+ * transport as a parameter. Handing either an authenticated `fetch` changes one line and no call
+ * site — which is the point, because the alternative is every call site remembering a header.
+ *
+ * Auth0's SPA SDK ships the same shape for the same reason: `fetchWithAuth`, *"a drop-in replacement
+ * for the Fetch API's `fetch()` method"* that builds the headers and handles the retries.
+ */
+/**
+ * Where a token comes from, and how to ask for a fresh one.
+ *
+ * Both are the implementation's business to make cheap and **single-flight** — see `singleFlight`.
+ * `current` is called on every request, so it must answer from cache until the token is near
+ * expiry. `null` from both is legitimate: it means there is no bearer token to attach.
+ */
+export interface TokenSource {
+    current(): Promise<string | null>;
+    renew(): Promise<string | null>;
+}
+/**
+ * Wrap a `fetch` so every request carries the session, and one stale token does not surface as a
+ * failure the user has to see.
+ *
+ * The retry is **once**, and only on a 401 we sent a token for. Retrying a 403 would be wrong — that
+ * is an answer, not a stale credential — and retrying twice turns an expired session into a loop
+ * against the authorization server.
+ */
+export declare function authFetch(source: TokenSource, base?: typeof globalThis.fetch): typeof globalThis.fetch;
+//# sourceMappingURL=auth-fetch.d.ts.map

package/dist/auth-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-fetch.d.ts","sourceRoot":"","sources":["../src/auth-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACjC;AAgBD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,OAAO,UAAU,CAAC,KAAwB,GAC/C,OAAO,UAAU,CAAC,KAAK,CAuBzB"}

package/dist/auth-fetch.js

@@ -0,0 +1,20 @@
+function c(r, n) {
+  if (typeof Request < "u" && r instanceof Request && r.body !== null) return !1;
+  const e = n == null ? void 0 : n.body;
+  return e == null ? !0 : !(typeof ReadableStream < "u" && e instanceof ReadableStream);
+}
+function h(r, n = globalThis.fetch) {
+  return async (e, t) => {
+    const u = async (d) => {
+      const l = (t == null ? void 0 : t.headers) ?? (typeof Request < "u" && e instanceof Request ? e.headers : void 0), f = new Headers(l);
+      return d !== null && f.set("Authorization", `Bearer ${d}`), n(e, { ...t, headers: f });
+    }, s = await r.current(), a = await u(s);
+    if (a.status !== 401 || s === null || !c(e, t)) return a;
+    const o = await r.renew();
+    return o === null || o === s ? a : u(o);
+  };
+}
+export {
+  h as authFetch
+};
+//# sourceMappingURL=auth-fetch.js.map

package/dist/auth-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-fetch.js","sources":["../src/auth-fetch.ts"],"sourcesContent":["/**\n * A `fetch` that stays authenticated.\n *\n * This is the seam a product already has. keasy's API client is\n * `createClient({ baseUrl: \"/\" })` with one middleware; the viewer's trace source takes its\n * transport as a parameter. Handing either an authenticated `fetch` changes one line and no call\n * site — which is the point, because the alternative is every call site remembering a header.\n *\n * Auth0's SPA SDK ships the same shape for the same reason: `fetchWithAuth`, *\"a drop-in replacement\n * for the Fetch API's `fetch()` method\"* that builds the headers and handles the retries.\n */\n\n/**\n * Where a token comes from, and how to ask for a fresh one.\n *\n * Both are the implementation's business to make cheap and **single-flight** — see `singleFlight`.\n * `current` is called on every request, so it must answer from cache until the token is near\n * expiry. `null` from both is legitimate: it means there is no bearer token to attach.\n */\nexport interface TokenSource {\n  current(): Promise<string | null>;\n  renew(): Promise<string | null>;\n}\n\n/**\n * Can this request be sent a second time?\n *\n * A body that is a stream can be read once, so a retry would send an empty one — silently, with a\n * misleading error at the far end. Where we cannot prove the body is replayable we do not retry: the\n * 401 reaches the caller, which is honest, rather than a corrupted request reaching the server.\n */\nfunction isReplayable(input: RequestInfo | URL, init?: RequestInit): boolean {\n  if (typeof Request !== \"undefined\" && input instanceof Request && input.body !== null) return false;\n  const body = init?.body;\n  if (body === undefined || body === null) return true;\n  return !(typeof ReadableStream !== \"undefined\" && body instanceof ReadableStream);\n}\n\n/**\n * Wrap a `fetch` so every request carries the session, and one stale token does not surface as a\n * failure the user has to see.\n *\n * The retry is **once**, and only on a 401 we sent a token for. Retrying a 403 would be wrong — that\n * is an answer, not a stale credential — and retrying twice turns an expired session into a loop\n * against the authorization server.\n */\nexport function authFetch(\n  source: TokenSource,\n  base: typeof globalThis.fetch = globalThis.fetch,\n): typeof globalThis.fetch {\n  return async (input, init) => {\n    const send = async (token: string | null): Promise<Response> => {\n      const inherited =\n        init?.headers ??\n        (typeof Request !== \"undefined\" && input instanceof Request ? input.headers : undefined);\n      const headers = new Headers(inherited);\n      if (token !== null) headers.set(\"Authorization\", `Bearer ${token}`);\n      return base(input, { ...init, headers });\n    };\n\n    const token = await source.current();\n    const response = await send(token);\n\n    // Nothing to renew against, or nothing that says the credential was the problem.\n    if (response.status !== 401 || token === null) return response;\n    if (!isReplayable(input, init)) return response;\n\n    const renewed = await source.renew();\n    if (renewed === null || renewed === token) return response;\n\n    return send(renewed);\n  };\n}\n"],"names":["isReplayable","input","init","body","authFetch","source","base","send","token","inherited","headers","response","renewed"],"mappings":"AA+BA,SAASA,EAAaC,GAA0BC,GAA6B;AAC3E,MAAI,OAAO,UAAY,OAAeD,aAAiB,WAAWA,EAAM,SAAS,KAAM,QAAO;AAC9F,QAAME,IAAOD,KAAA,gBAAAA,EAAM;AACnB,SAA0BC,KAAS,OAAa,KACzC,EAAE,OAAO,iBAAmB,OAAeA,aAAgB;AACpE;AAUO,SAASC,EACdC,GACAC,IAAgC,WAAW,OAClB;AACzB,SAAO,OAAOL,GAAOC,MAAS;AAC5B,UAAMK,IAAO,OAAOC,MAA4C;AAC9D,YAAMC,KACJP,KAAA,gBAAAA,EAAM,aACL,OAAO,UAAY,OAAeD,aAAiB,UAAUA,EAAM,UAAU,SAC1ES,IAAU,IAAI,QAAQD,CAAS;AACrC,aAAID,MAAU,QAAME,EAAQ,IAAI,iBAAiB,UAAUF,CAAK,EAAE,GAC3DF,EAAKL,GAAO,EAAE,GAAGC,GAAM,SAAAQ,GAAS;AAAA,IACzC,GAEMF,IAAQ,MAAMH,EAAO,QAAA,GACrBM,IAAW,MAAMJ,EAAKC,CAAK;AAIjC,QADIG,EAAS,WAAW,OAAOH,MAAU,QACrC,CAACR,EAAaC,GAAOC,CAAI,EAAG,QAAOS;AAEvC,UAAMC,IAAU,MAAMP,EAAO,MAAA;AAC7B,WAAIO,MAAY,QAAQA,MAAYJ,IAAcG,IAE3CJ,EAAKK,CAAO;AAAA,EACrB;AACF;"}

package/dist/auth-provider.d.ts

@@ -0,0 +1,12 @@
+import { Auth } from './types';
+/**
+ * Holds the session and keeps it current. One per application, at the root.
+ *
+ * It does not know which pattern is underneath it — `bffAuth` or `browserAuth` both satisfy `Auth`
+ * — which is the whole reason the hooks below it can be written once.
+ */
+export declare function AuthProvider({ auth, children, }: {
+    readonly auth: Auth;
+    readonly children?: React.ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=auth-provider.d.ts.map

package/dist/auth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.d.ts","sourceRoot":"","sources":["../src/auth-provider.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,SAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CACrC,+BA0CA"}

package/dist/auth-provider.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as c } from "react/jsx-runtime";
+import { useState as f, useEffect as l, useMemo as m } from "react";
+import { AuthContext as d } from "./auth-context.js";
+function x({
+  auth: s,
+  children: u
+}) {
+  const [t, o] = f({
+    session: null,
+    status: "loading"
+  });
+  l(() => {
+    let e = !0;
+    const n = () => {
+      s.getSession().then((r) => {
+        e && o({ session: r, status: r ? "authenticated" : "anonymous" });
+      }).catch(() => {
+        e && o({ session: null, status: "anonymous" });
+      });
+    }, a = s.subscribe(n);
+    return n(), () => {
+      e = !1, a();
+    };
+  }, [s]);
+  const i = m(
+    () => ({ auth: s, session: t.session, status: t.status }),
+    [s, t.session, t.status]
+  );
+  return /* @__PURE__ */ c(d.Provider, { value: i, children: u });
+}
+export {
+  x as AuthProvider
+};
+//# sourceMappingURL=auth-provider.js.map

package/dist/auth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.js","sources":["../src/auth-provider.tsx"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useMemo, useState } from \"react\";\nimport { AuthContext, type AuthStatus } from \"./auth-context\";\nimport type { Auth, Session } from \"./types\";\n\n/**\n * Holds the session and keeps it current. One per application, at the root.\n *\n * It does not know which pattern is underneath it — `bffAuth` or `browserAuth` both satisfy `Auth`\n * — which is the whole reason the hooks below it can be written once.\n */\nexport function AuthProvider({\n  auth,\n  children,\n}: {\n  readonly auth: Auth;\n  readonly children?: React.ReactNode;\n}) {\n  const [state, setState] = useState<{ session: Session | null; status: AuthStatus }>({\n    session: null,\n    status: \"loading\",\n  });\n\n  useEffect(() => {\n    // `live` rather than an AbortController: `getSession` may be a cache read with no request to\n    // abort, and what must not happen is a setState after unmount — a resolved promise from the\n    // provider that was just torn down, overwriting the one that replaced it.\n    let live = true;\n\n    const read = () => {\n      void auth\n        .getSession()\n        .then((session) => {\n          if (!live) return;\n          setState({ session, status: session ? \"authenticated\" : \"anonymous\" });\n        })\n        .catch(() => {\n          // A session that cannot be read is a session you do not have. Failing to \"anonymous\"\n          // keeps the tree renderable and sends the person to the IdP, which is recoverable;\n          // holding \"loading\" forever is a spinner nobody can escape.\n          if (live) setState({ session: null, status: \"anonymous\" });\n        });\n    };\n\n    const unsubscribe = auth.subscribe(read);\n    read();\n\n    return () => {\n      live = false;\n      unsubscribe();\n    };\n  }, [auth]);\n\n  const value = useMemo(\n    () => ({ auth, session: state.session, status: state.status }),\n    [auth, state.session, state.status],\n  );\n\n  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;\n}\n"],"names":[],"mappings":";;;;AAYO;AAAsB;AAC3B;AAEF;AAIE;AAAoF;AACzE;AACD;AAGV;AAIE;AAEA;AACE;AAGI;AACqE;AAMrE;AAAyD;AAC1D;AAIL;AAGE;AACA;AACF;AAGF;AAAc;;AAEsB;AAGpC;AACF;;;;"}

package/dist/bff-auth.d.ts

@@ -0,0 +1,32 @@
+import { Auth, Session } from './types';
+/**
+ * The Backend-For-Frontend pattern: the token never reaches the browser.
+ *
+ * RFC 10017 calls this one *"strongly recommended for business applications, sensitive
+ * applications, and applications that handle personal data"*. The server holds the confidential
+ * client and the tokens; the browser holds a cookie it cannot read, and asks the server who it is.
+ *
+ * So there is no engine on this path — no PKCE, no storage, no renewal — which is why it lives on
+ * the root barrel beside the hooks rather than behind a subpath. What it needs from the server is
+ * three routes, which `@kanzo-tech/auth/next` provides: a session endpoint, a sign-in and a
+ * sign-out.
+ */
+export interface BffAuthConfig {
+    /** Where the BFF's auth routes are mounted. Default `/api/auth`. */
+    readonly basePath?: string;
+    /** Injectable for tests. Defaults to the global. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Injectable for tests. Defaults to assigning `window.location`. */
+    readonly navigate?: (url: string) => void;
+}
+/**
+ * The session endpoint's answer, checked rather than cast.
+ *
+ * It is our own server on the other end, and it is still **data off the wire**: a cast here would
+ * make a deploy skew or a proxy's error page arrive as a `Session` whose `user` is undefined, and
+ * the failure would surface three components away as a property read on nothing. `null` for
+ * anything unrecognisable is the same answer as "not signed in", which is the safe reading.
+ */
+export declare function readSession(value: unknown): Session | null;
+export declare function bffAuth(config?: BffAuthConfig): Auth;
+//# sourceMappingURL=bff-auth.d.ts.map

package/dist/bff-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bff-auth.d.ts","sourceRoot":"","sources":["../src/bff-auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAgB,OAAO,EAAiB,MAAM,SAAS,CAAC;AAE1E;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAgBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAyB1D;AAED,wBAAgB,OAAO,CAAC,MAAM,GAAE,aAAkB,GAAG,IAAI,CAwExD"}

package/dist/bff-auth.js

@@ -0,0 +1,70 @@
+import { singleFlight as p } from "./single-flight.js";
+function y(e) {
+  if (typeof e != "object" || e === null) return null;
+  const t = e, s = t.alias;
+  return typeof s != "string" || s.length === 0 ? null : {
+    alias: s,
+    id: typeof t.id == "string" ? t.id : void 0,
+    roles: Array.isArray(t.roles) ? t.roles.filter((o) => typeof o == "string") : []
+  };
+}
+function d(e) {
+  if (typeof e != "object" || e === null) return null;
+  const t = e, s = t.user;
+  if (typeof s != "object" || s === null) return null;
+  const o = s.id;
+  if (typeof o != "string" || o.length === 0) return null;
+  const l = s, u = (r) => typeof l[r] == "string" && l[r] !== "" ? l[r] : void 0;
+  return {
+    user: { id: o, email: u("email"), name: u("name"), username: u("username") },
+    roles: Array.isArray(t.roles) ? t.roles.filter((r) => typeof r == "string") : [],
+    organizations: Array.isArray(t.organizations) ? t.organizations.map(y).filter((r) => r !== null) : [],
+    expiresAt: typeof t.expiresAt == "number" ? t.expiresAt : 0
+  };
+}
+function m(e = {}) {
+  const t = (e.basePath ?? "/api/auth").replace(/\/$/, ""), s = e.fetch ?? ((...n) => globalThis.fetch(...n)), o = e.navigate ?? ((n) => void (globalThis.location.href = n)), l = /* @__PURE__ */ new Set(), u = () => {
+    for (const n of l) n();
+  };
+  let r = null, c = !1;
+  const g = p(async () => {
+    const n = await s(`${t}/session`, {
+      headers: { Accept: "application/json" }
+    });
+    return n.status === 401 || !n.ok ? null : d(await n.json().catch(() => null));
+  }), f = async () => {
+    const n = r;
+    return r = await g(), c = !0, (n === null != (r === null) || (n == null ? void 0 : n.user.id) !== (r == null ? void 0 : r.user.id)) && u(), r;
+  };
+  return {
+    async getSession() {
+      return c ? r : f();
+    },
+    subscribe(n) {
+      return l.add(n), () => l.delete(n);
+    },
+    async signIn(n = {}) {
+      var a;
+      const i = new URLSearchParams();
+      i.set("returnTo", n.returnTo ?? ((a = globalThis.location) == null ? void 0 : a.href) ?? "/"), n.organization !== void 0 && i.set("organization", n.organization), o(`${t}/signin?${i.toString()}`);
+    },
+    async signOut(n = {}) {
+      const i = new URLSearchParams();
+      n.returnTo !== void 0 && i.set("returnTo", n.returnTo);
+      const a = i.toString();
+      o(a ? `${t}/signout?${a}` : `${t}/signout`);
+    },
+    // No `Authorization` header, and no retry: the cookie rides along on a same-origin request by
+    // itself, so there is no stale token to renew. A 401 means the session is *gone* rather than
+    // stale, and the useful response to that is to tell the tree — which is what re-reading does.
+    fetch: async (n, i) => {
+      const a = await s(n, i);
+      return a.status === 401 && c && (c = !1, await f()), a;
+    }
+  };
+}
+export {
+  m as bffAuth,
+  d as readSession
+};
+//# sourceMappingURL=bff-auth.js.map

package/dist/bff-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bff-auth.js","sources":["../src/bff-auth.ts"],"sourcesContent":["import { singleFlight } from \"./single-flight\";\nimport type { Auth, Organization, Session, SignInOptions } from \"./types\";\n\n/**\n * The Backend-For-Frontend pattern: the token never reaches the browser.\n *\n * RFC 10017 calls this one *\"strongly recommended for business applications, sensitive\n * applications, and applications that handle personal data\"*. The server holds the confidential\n * client and the tokens; the browser holds a cookie it cannot read, and asks the server who it is.\n *\n * So there is no engine on this path — no PKCE, no storage, no renewal — which is why it lives on\n * the root barrel beside the hooks rather than behind a subpath. What it needs from the server is\n * three routes, which `@kanzo-tech/auth/next` provides: a session endpoint, a sign-in and a\n * sign-out.\n */\n\nexport interface BffAuthConfig {\n  /** Where the BFF's auth routes are mounted. Default `/api/auth`. */\n  readonly basePath?: string;\n  /** Injectable for tests. Defaults to the global. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** Injectable for tests. Defaults to assigning `window.location`. */\n  readonly navigate?: (url: string) => void;\n}\n\nfunction readOrganization(value: unknown): Organization | null {\n  if (typeof value !== \"object\" || value === null) return null;\n  const org = value as Record<string, unknown>;\n  const alias = org[\"alias\"];\n  if (typeof alias !== \"string\" || alias.length === 0) return null;\n  return {\n    alias,\n    id: typeof org[\"id\"] === \"string\" ? org[\"id\"] : undefined,\n    roles: Array.isArray(org[\"roles\"])\n      ? org[\"roles\"].filter((r): r is string => typeof r === \"string\")\n      : [],\n  };\n}\n\n/**\n * The session endpoint's answer, checked rather than cast.\n *\n * It is our own server on the other end, and it is still **data off the wire**: a cast here would\n * make a deploy skew or a proxy's error page arrive as a `Session` whose `user` is undefined, and\n * the failure would surface three components away as a property read on nothing. `null` for\n * anything unrecognisable is the same answer as \"not signed in\", which is the safe reading.\n */\nexport function readSession(value: unknown): Session | null {\n  if (typeof value !== \"object\" || value === null) return null;\n  const body = value as Record<string, unknown>;\n\n  const user = body[\"user\"];\n  if (typeof user !== \"object\" || user === null) return null;\n  const id = (user as Record<string, unknown>)[\"id\"];\n  if (typeof id !== \"string\" || id.length === 0) return null;\n\n  const person = user as Record<string, unknown>;\n  const str = (key: string) =>\n    typeof person[key] === \"string\" && person[key] !== \"\" ? (person[key] as string) : undefined;\n\n  return {\n    user: { id, email: str(\"email\"), name: str(\"name\"), username: str(\"username\") },\n    roles: Array.isArray(body[\"roles\"])\n      ? body[\"roles\"].filter((r): r is string => typeof r === \"string\")\n      : [],\n    organizations: Array.isArray(body[\"organizations\"])\n      ? body[\"organizations\"]\n          .map(readOrganization)\n          .filter((o): o is Organization => o !== null)\n      : [],\n    expiresAt: typeof body[\"expiresAt\"] === \"number\" ? body[\"expiresAt\"] : 0,\n  };\n}\n\nexport function bffAuth(config: BffAuthConfig = {}): Auth {\n  const base = (config.basePath ?? \"/api/auth\").replace(/\\/$/, \"\");\n  const doFetch = config.fetch ?? ((...args) => globalThis.fetch(...args));\n  const go = config.navigate ?? ((url: string) => void (globalThis.location.href = url));\n\n  const listeners = new Set<() => void>();\n  const announce = () => {\n    for (const listener of listeners) listener();\n  };\n\n  let cached: Session | null = null;\n  let known = false;\n\n  // Single-flight for the same reason the token path needs it: a page that mounts six components\n  // asks six times in one tick, and one answer serves them all. Here it costs a request rather\n  // than a revoked token chain, which is a smaller bill for the same mistake.\n  const read = singleFlight(async (): Promise<Session | null> => {\n    const response = await doFetch(`${base}/session`, {\n      headers: { Accept: \"application/json\" },\n    });\n    // 401 is the documented answer for \"nobody is signed in\", not a failure to report.\n    if (response.status === 401) return null;\n    if (!response.ok) return null;\n    return readSession(await response.json().catch(() => null));\n  });\n\n  const refresh = async (): Promise<Session | null> => {\n    const next = cached;\n    cached = await read();\n    known = true;\n    // Announce only a change, so a poll does not re-render the tree every time.\n    if ((next === null) !== (cached === null) || next?.user.id !== cached?.user.id) announce();\n    return cached;\n  };\n\n  return {\n    async getSession() {\n      if (known) return cached;\n      return refresh();\n    },\n\n    subscribe(onChange) {\n      listeners.add(onChange);\n      return () => listeners.delete(onChange);\n    },\n\n    async signIn(options: SignInOptions = {}) {\n      const params = new URLSearchParams();\n      params.set(\"returnTo\", options.returnTo ?? globalThis.location?.href ?? \"/\");\n      if (options.organization !== undefined) params.set(\"organization\", options.organization);\n      go(`${base}/signin?${params.toString()}`);\n    },\n\n    async signOut(options = {}) {\n      const params = new URLSearchParams();\n      if (options.returnTo !== undefined) params.set(\"returnTo\", options.returnTo);\n      const query = params.toString();\n      go(query ? `${base}/signout?${query}` : `${base}/signout`);\n    },\n\n    // No `Authorization` header, and no retry: the cookie rides along on a same-origin request by\n    // itself, so there is no stale token to renew. A 401 means the session is *gone* rather than\n    // stale, and the useful response to that is to tell the tree — which is what re-reading does.\n    fetch: async (input, init) => {\n      const response = await doFetch(input, init);\n      if (response.status === 401 && known) {\n        known = false;\n        await refresh();\n      }\n      return response;\n    },\n  };\n}\n"],"names":["readOrganization","value","org","alias","r","readSession","body","user","id","person","str","key","o","bffAuth","config","base","doFetch","args","go","url","listeners","announce","listener","cached","known","read","singleFlight","response","refresh","next","onChange","options","params","_a","query","input","init"],"mappings":";AAyBA,SAASA,EAAiBC,GAAqC;AAC7D,MAAI,OAAOA,KAAU,YAAYA,MAAU,KAAM,QAAO;AACxD,QAAMC,IAAMD,GACNE,IAAQD,EAAI;AAClB,SAAI,OAAOC,KAAU,YAAYA,EAAM,WAAW,IAAU,OACrD;AAAA,IACL,OAAAA;AAAA,IACA,IAAI,OAAOD,EAAI,MAAU,WAAWA,EAAI,KAAQ;AAAA,IAChD,OAAO,MAAM,QAAQA,EAAI,KAAQ,IAC7BA,EAAI,MAAS,OAAO,CAACE,MAAmB,OAAOA,KAAM,QAAQ,IAC7D,CAAA;AAAA,EAAC;AAET;AAUO,SAASC,EAAYJ,GAAgC;AAC1D,MAAI,OAAOA,KAAU,YAAYA,MAAU,KAAM,QAAO;AACxD,QAAMK,IAAOL,GAEPM,IAAOD,EAAK;AAClB,MAAI,OAAOC,KAAS,YAAYA,MAAS,KAAM,QAAO;AACtD,QAAMC,IAAMD,EAAiC;AAC7C,MAAI,OAAOC,KAAO,YAAYA,EAAG,WAAW,EAAG,QAAO;AAEtD,QAAMC,IAASF,GACTG,IAAM,CAACC,MACX,OAAOF,EAAOE,CAAG,KAAM,YAAYF,EAAOE,CAAG,MAAM,KAAMF,EAAOE,CAAG,IAAe;AAEpF,SAAO;AAAA,IACL,MAAM,EAAE,IAAAH,GAAI,OAAOE,EAAI,OAAO,GAAG,MAAMA,EAAI,MAAM,GAAG,UAAUA,EAAI,UAAU,EAAA;AAAA,IAC5E,OAAO,MAAM,QAAQJ,EAAK,KAAQ,IAC9BA,EAAK,MAAS,OAAO,CAAC,MAAmB,OAAO,KAAM,QAAQ,IAC9D,CAAA;AAAA,IACJ,eAAe,MAAM,QAAQA,EAAK,aAAgB,IAC9CA,EAAK,cACF,IAAIN,CAAgB,EACpB,OAAO,CAACY,MAAyBA,MAAM,IAAI,IAC9C,CAAA;AAAA,IACJ,WAAW,OAAON,EAAK,aAAiB,WAAWA,EAAK,YAAe;AAAA,EAAA;AAE3E;AAEO,SAASO,EAAQC,IAAwB,IAAU;AACxD,QAAMC,KAAQD,EAAO,YAAY,aAAa,QAAQ,OAAO,EAAE,GACzDE,IAAUF,EAAO,UAAU,IAAIG,MAAS,WAAW,MAAM,GAAGA,CAAI,IAChEC,IAAKJ,EAAO,aAAa,CAACK,MAAgB,MAAM,WAAW,SAAS,OAAOA,KAE3EC,wBAAgB,IAAA,GAChBC,IAAW,MAAM;AACrB,eAAWC,KAAYF,EAAW,CAAAE,EAAA;AAAA,EACpC;AAEA,MAAIC,IAAyB,MACzBC,IAAQ;AAKZ,QAAMC,IAAOC,EAAa,YAAqC;AAC7D,UAAMC,IAAW,MAAMX,EAAQ,GAAGD,CAAI,YAAY;AAAA,MAChD,SAAS,EAAE,QAAQ,mBAAA;AAAA,IAAmB,CACvC;AAGD,WADIY,EAAS,WAAW,OACpB,CAACA,EAAS,KAAW,OAClBtB,EAAY,MAAMsB,EAAS,KAAA,EAAO,MAAM,MAAM,IAAI,CAAC;AAAA,EAC5D,CAAC,GAEKC,IAAU,YAAqC;AACnD,UAAMC,IAAON;AACb,WAAAA,IAAS,MAAME,EAAA,GACfD,IAAQ,KAEHK,MAAS,SAAWN,MAAW,UAASM,KAAA,gBAAAA,EAAM,KAAK,SAAON,KAAA,gBAAAA,EAAQ,KAAK,QAAIF,EAAA,GACzEE;AAAA,EACT;AAEA,SAAO;AAAA,IACL,MAAM,aAAa;AACjB,aAAIC,IAAcD,IACXK,EAAA;AAAA,IACT;AAAA,IAEA,UAAUE,GAAU;AAClB,aAAAV,EAAU,IAAIU,CAAQ,GACf,MAAMV,EAAU,OAAOU,CAAQ;AAAA,IACxC;AAAA,IAEA,MAAM,OAAOC,IAAyB,IAAI;;AACxC,YAAMC,IAAS,IAAI,gBAAA;AACnB,MAAAA,EAAO,IAAI,YAAYD,EAAQ,cAAYE,IAAA,WAAW,aAAX,gBAAAA,EAAqB,SAAQ,GAAG,GACvEF,EAAQ,iBAAiB,YAAkB,IAAI,gBAAgBA,EAAQ,YAAY,GACvFb,EAAG,GAAGH,CAAI,WAAWiB,EAAO,SAAA,CAAU,EAAE;AAAA,IAC1C;AAAA,IAEA,MAAM,QAAQD,IAAU,IAAI;AAC1B,YAAMC,IAAS,IAAI,gBAAA;AACnB,MAAID,EAAQ,aAAa,YAAkB,IAAI,YAAYA,EAAQ,QAAQ;AAC3E,YAAMG,IAAQF,EAAO,SAAA;AACrB,MAAAd,EAAGgB,IAAQ,GAAGnB,CAAI,YAAYmB,CAAK,KAAK,GAAGnB,CAAI,UAAU;AAAA,IAC3D;AAAA;AAAA;AAAA;AAAA,IAKA,OAAO,OAAOoB,GAAOC,MAAS;AAC5B,YAAMT,IAAW,MAAMX,EAAQmB,GAAOC,CAAI;AAC1C,aAAIT,EAAS,WAAW,OAAOH,MAC7BA,IAAQ,IACR,MAAMI,EAAA,IAEDD;AAAA,IACT;AAAA,EAAA;AAEJ;"}

package/dist/browser.d.ts

@@ -0,0 +1,61 @@
+import { UserManagerSettings } from 'oidc-client-ts';
+import { Auth } from './types';
+/** What this adapter reads off the library's `User`. The access token is carried, never opened. */
+export interface OidcUser {
+    readonly profile: unknown;
+    readonly access_token: string;
+    readonly expires_at?: number;
+    readonly url_state?: string;
+}
+/**
+ * The slice of `UserManager` this file uses.
+ *
+ * It exists so the manager can be injected, which is what lets everything below be tested with no
+ * network, no IdP and no iframe. It is deliberately structural and deliberately small — and the
+ * default factory returns a real `UserManager`, so the compiler is what keeps the slice honest.
+ */
+export interface OidcUserManager {
+    getUser(): Promise<OidcUser | null>;
+    signinRedirect(args?: {
+        scope?: string;
+        url_state?: string;
+    }): Promise<void>;
+    signinCallback(url?: string): Promise<OidcUser | undefined>;
+    signinSilent(): Promise<OidcUser | null>;
+    signoutRedirect(args?: {
+        post_logout_redirect_uri?: string;
+    }): Promise<void>;
+    readonly events: {
+        addUserLoaded(cb: () => void): () => void;
+        addUserUnloaded(cb: () => void): () => void;
+        addAccessTokenExpired(cb: () => void): () => void;
+        addUserSessionChanged(cb: () => void): () => void;
+    };
+}
+export interface BrowserAuthConfig {
+    /** The realm's issuer, e.g. `https://id.kanzo.tech/realms/kanzo`. */
+    readonly issuer: string;
+    /**
+     * This application's Keycloak client id. It selects the credential and, through {@link claims},
+     * which of the token's roles are this application's.
+     */
+    readonly clientId: string;
+    /** Must be registered with the IdP. Defaults to the current origin. */
+    readonly redirectUri?: string;
+    /** Must be registered with the IdP. Defaults to the current origin. */
+    readonly postLogoutRedirectUri?: string;
+    /** Defaults to `openid profile email organization:*`. */
+    readonly scope?: string;
+    /**
+     * Poll the OP's session state, so a sign-out performed elsewhere reaches this tab.
+     *
+     * Off by default because it cannot be relied on: it runs a hidden cross-site iframe, and a
+     * browser that partitions third-party cookies — which is now most of them — makes it report
+     * nothing rather than fail loudly. It is a knob and not a default for exactly that reason.
+     */
+    readonly monitorSession?: boolean;
+    /** The seam the tests inject through. Defaults to the real `UserManager`. */
+    readonly createManager?: (settings: UserManagerSettings) => OidcUserManager;
+}
+export declare function browserAuth(config: BrowserAuthConfig): Auth;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,IAAI,EAA0B,MAAM,SAAS,CAAC;AAiC5D,mGAAmG;AACnG,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACpC,cAAc,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC5D,YAAY,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACzC,eAAe,CAAC,IAAI,CAAC,EAAE;QAAE,wBAAwB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,QAAQ,CAAC,MAAM,EAAE;QACf,aAAa,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;QAC1C,eAAe,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;QAC5C,qBAAqB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;QAClD,qBAAqB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;KACnD,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,eAAe,CAAC;CAC7E;AAgBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAiK3D"}

package/dist/browser.js

@@ -0,0 +1,107 @@
+import { WebStorageStateStore as g, InMemoryWebStorage as b, UserManager as U } from "oidc-client-ts";
+import { authFetch as R } from "./auth-fetch.js";
+import { claims as T } from "./claims.js";
+import { singleFlight as w } from "./single-flight.js";
+const v = "openid profile email organization:*", x = ["code", "state", "session_state", "iss", "error", "error_description"];
+function A(t) {
+  const s = new URLSearchParams(t);
+  return s.has("state") && (s.has("code") || s.has("error"));
+}
+function L(t, s) {
+  return s === void 0 ? t : [...t.split(" ").filter((n) => n.length > 0 && !n.startsWith("organization:")), `organization:${s}`].join(" ");
+}
+function F(t) {
+  var p;
+  const s = ((p = globalThis.location) == null ? void 0 : p.origin) ?? "", a = t.scope ?? v, n = {
+    authority: t.issuer,
+    client_id: t.clientId,
+    redirect_uri: t.redirectUri ?? s,
+    post_logout_redirect_uri: t.postLogoutRedirectUri ?? s,
+    scope: a,
+    response_type: "code",
+    monitorSession: t.monitorSession ?? !1,
+    // **Tokens in memory only.** The library's default is `sessionStorage`, and RFC 10017 is
+    // explicit that under a public client anything script can read is something an XSS can steal;
+    // a token on disk outlives the page that was compromised to get it.
+    //
+    // The cost is real and is the whole of the trade: a full page load starts with nothing, so the
+    // session is re-established by a silent renewal or a redirect rather than read off disk. That
+    // is one round trip on every load, and a signed-out first paint for any application that draws
+    // before `getSession()` settles.
+    userStore: new g({ store: new b() }),
+    // The PKCE verifier, `state` and `nonce` are **not** tokens and cannot be in memory: the page
+    // is unloaded by the navigation to the IdP, and memory goes with it. `sessionStorage` rather
+    // than the library's `localStorage` default — per tab, gone when the tab closes, and never
+    // visible to a second tab racing the same sign-in.
+    stateStore: new g({ store: globalThis.sessionStorage })
+  }, o = (t.createManager ?? ((e) => new U(e)))(n), u = (e) => {
+    const r = new URL(globalThis.location.href);
+    for (const y of x) r.searchParams.delete(y);
+    const i = e === void 0 ? r : new URL(e, r.origin), l = i.origin === r.origin ? i : r;
+    globalThis.history.replaceState(null, "", `${l.pathname}${l.search}${l.hash}`);
+  }, _ = async () => {
+    if (!A(globalThis.location.search)) return null;
+    try {
+      const e = await o.signinCallback(globalThis.location.href) ?? null;
+      return u(e == null ? void 0 : e.url_state), e;
+    } catch {
+      return u(void 0), null;
+    }
+  };
+  let d;
+  const m = w(async () => (d ?? (d = _()), await d ?? o.getUser())), c = w(async () => {
+    try {
+      return await o.signinSilent();
+    } catch {
+      return null;
+    }
+  }), S = (e) => e.expires_at !== void 0 && e.expires_at * 1e3 <= Date.now(), h = async () => {
+    const e = await m();
+    return e === null || S(e) ? c() : e;
+  }, f = (e) => {
+    const r = T(e.profile, { clientId: t.clientId });
+    return e.expires_at === void 0 ? r : { ...r, expiresAt: e.expires_at * 1e3 };
+  };
+  return {
+    async getSession() {
+      const e = await h();
+      return e === null ? null : f(e);
+    },
+    subscribe(e) {
+      const r = [
+        o.events.addUserLoaded(e),
+        o.events.addUserUnloaded(e),
+        o.events.addAccessTokenExpired(e),
+        o.events.addUserSessionChanged(e)
+      ];
+      return () => {
+        for (const i of r) i();
+      };
+    },
+    async signIn(e = {}) {
+      await o.signinRedirect({
+        scope: L(a, e.organization),
+        url_state: e.returnTo ?? globalThis.location.href
+      });
+    },
+    async signOut(e = {}) {
+      await o.signoutRedirect({
+        post_logout_redirect_uri: e.returnTo ?? t.postLogoutRedirectUri
+      });
+    },
+    fetch: R({
+      async current() {
+        var e;
+        return ((e = await h()) == null ? void 0 : e.access_token) ?? null;
+      },
+      async renew() {
+        var e;
+        return ((e = await c()) == null ? void 0 : e.access_token) ?? null;
+      }
+    })
+  };
+}
+export {
+  F as browserAuth
+};
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sources":["../src/browser.ts"],"sourcesContent":["import {\n  InMemoryWebStorage,\n  UserManager,\n  WebStorageStateStore,\n  type UserManagerSettings,\n} from \"oidc-client-ts\";\nimport { authFetch, type TokenSource } from \"./auth-fetch\";\nimport { claims } from \"./claims\";\nimport { singleFlight } from \"./single-flight\";\nimport type { Auth, Session, SignInOptions } from \"./types\";\n\n/**\n * `./browser` — RFC 10017's *browser-based OAuth 2.0 client*: a public client with PKCE, for the\n * SPA that has no server to hold a confidential one. `agents/viewer` and `hub/browser` are both\n * that shape, and for them it is the only architecture available.\n *\n * **This file is an adapter, not an implementation.** PKCE, silent renewal, storage, the callback\n * and RP-initiated logout are `oidc-client-ts`'s; a `UserManager` goes in and our `Auth` comes out.\n * The reference evaluation picked that library precisely so none of the protocol would be written\n * here, because a hand-written flow is where a mistake stops being a bug and becomes a\n * vulnerability. What is genuinely ours is the four things no library can have: Keycloak's claim\n * vocabulary read into one `Session`, the organization scope, the single-flight renewal, and one\n * `Session` across both deployment patterns.\n *\n * There is no `\"use client\"` here, and that is the rule rather than an oversight: nothing in this\n * module is stateful and no browser global is read at module scope. The listeners are registered\n * inside `subscribe`, and `location` inside the factory.\n */\n\n/**\n * `organization:*`, not `organization`.\n *\n * Plain `organization` returns the single organization when there is one and **prompts for a\n * choice** when there are several — which is the documented behaviour behind the reports of the\n * claim \"disappearing\" for multi-organization users. It never disappeared; the selection was\n * missing. A single-tenant product pays nothing for the star: the claim is simply absent.\n */\nconst DEFAULT_SCOPE = \"openid profile email organization:*\";\n\n/** The query parameters an authorization response puts in the URL, and that must not stay there. */\nconst RESPONSE_PARAMS = [\"code\", \"state\", \"session_state\", \"iss\", \"error\", \"error_description\"];\n\n/** What this adapter reads off the library's `User`. The access token is carried, never opened. */\nexport interface OidcUser {\n  readonly profile: unknown;\n  readonly access_token: string;\n  readonly expires_at?: number;\n  readonly url_state?: string;\n}\n\n/**\n * The slice of `UserManager` this file uses.\n *\n * It exists so the manager can be injected, which is what lets everything below be tested with no\n * network, no IdP and no iframe. It is deliberately structural and deliberately small — and the\n * default factory returns a real `UserManager`, so the compiler is what keeps the slice honest.\n */\nexport interface OidcUserManager {\n  getUser(): Promise<OidcUser | null>;\n  signinRedirect(args?: { scope?: string; url_state?: string }): Promise<void>;\n  signinCallback(url?: string): Promise<OidcUser | undefined>;\n  signinSilent(): Promise<OidcUser | null>;\n  signoutRedirect(args?: { post_logout_redirect_uri?: string }): Promise<void>;\n  readonly events: {\n    addUserLoaded(cb: () => void): () => void;\n    addUserUnloaded(cb: () => void): () => void;\n    addAccessTokenExpired(cb: () => void): () => void;\n    addUserSessionChanged(cb: () => void): () => void;\n  };\n}\n\nexport interface BrowserAuthConfig {\n  /** The realm's issuer, e.g. `https://id.kanzo.tech/realms/kanzo`. */\n  readonly issuer: string;\n  /**\n   * This application's Keycloak client id. It selects the credential and, through {@link claims},\n   * which of the token's roles are this application's.\n   */\n  readonly clientId: string;\n  /** Must be registered with the IdP. Defaults to the current origin. */\n  readonly redirectUri?: string;\n  /** Must be registered with the IdP. Defaults to the current origin. */\n  readonly postLogoutRedirectUri?: string;\n  /** Defaults to `openid profile email organization:*`. */\n  readonly scope?: string;\n  /**\n   * Poll the OP's session state, so a sign-out performed elsewhere reaches this tab.\n   *\n   * Off by default because it cannot be relied on: it runs a hidden cross-site iframe, and a\n   * browser that partitions third-party cookies — which is now most of them — makes it report\n   * nothing rather than fail loudly. It is a knob and not a default for exactly that reason.\n   */\n  readonly monitorSession?: boolean;\n  /** The seam the tests inject through. Defaults to the real `UserManager`. */\n  readonly createManager?: (settings: UserManagerSettings) => OidcUserManager;\n}\n\n/** `code` or `error`, together with `state`. Nothing else in a URL is an authorization response. */\nfunction isAuthorizationResponse(search: string): boolean {\n  const params = new URLSearchParams(search);\n  return params.has(\"state\") && (params.has(\"code\") || params.has(\"error\"));\n}\n\nfunction scopeFor(scope: string, organization: string | undefined): string {\n  if (organization === undefined) return scope;\n  // Replace rather than append: `organization:* organization:acme` asks for both, and the point of\n  // naming one is to get one.\n  const rest = scope.split(\" \").filter((s) => s.length > 0 && !s.startsWith(\"organization:\"));\n  return [...rest, `organization:${organization}`].join(\" \");\n}\n\nexport function browserAuth(config: BrowserAuthConfig): Auth {\n  const origin = globalThis.location?.origin ?? \"\";\n  const scope = config.scope ?? DEFAULT_SCOPE;\n\n  const settings: UserManagerSettings = {\n    authority: config.issuer,\n    client_id: config.clientId,\n    redirect_uri: config.redirectUri ?? origin,\n    post_logout_redirect_uri: config.postLogoutRedirectUri ?? origin,\n    scope,\n    response_type: \"code\",\n    monitorSession: config.monitorSession ?? false,\n\n    // **Tokens in memory only.** The library's default is `sessionStorage`, and RFC 10017 is\n    // explicit that under a public client anything script can read is something an XSS can steal;\n    // a token on disk outlives the page that was compromised to get it.\n    //\n    // The cost is real and is the whole of the trade: a full page load starts with nothing, so the\n    // session is re-established by a silent renewal or a redirect rather than read off disk. That\n    // is one round trip on every load, and a signed-out first paint for any application that draws\n    // before `getSession()` settles.\n    userStore: new WebStorageStateStore({ store: new InMemoryWebStorage() }),\n\n    // The PKCE verifier, `state` and `nonce` are **not** tokens and cannot be in memory: the page\n    // is unloaded by the navigation to the IdP, and memory goes with it. `sessionStorage` rather\n    // than the library's `localStorage` default — per tab, gone when the tab closes, and never\n    // visible to a second tab racing the same sign-in.\n    stateStore: new WebStorageStateStore({ store: globalThis.sessionStorage }),\n  };\n\n  const manager = (config.createManager ?? ((s) => new UserManager(s)))(settings);\n\n  /** Take the spent response out of the URL, and honour `returnTo` if it is ours to honour. */\n  const restore = (returnTo: string | undefined): void => {\n    const here = new URL(globalThis.location.href);\n    for (const key of RESPONSE_PARAMS) here.searchParams.delete(key);\n    const wanted = returnTo === undefined ? here : new URL(returnTo, here.origin);\n    // `url_state` round-trips through the IdP, so following it anywhere would make our own callback\n    // the bounce in an open redirect. Same origin, or we stay where we are.\n    const url = wanted.origin === here.origin ? wanted : here;\n    globalThis.history.replaceState(null, \"\", `${url.pathname}${url.search}${url.hash}`);\n  };\n\n  /**\n   * Finish a redirect the IdP has just sent back.\n   *\n   * The URL is cleaned either way. An authorization code is single-use, and one left in the address\n   * bar reaches history, bookmarks and the `Referer` — and replays as an error on the next reload.\n   */\n  const complete = async (): Promise<OidcUser | null> => {\n    if (!isAuthorizationResponse(globalThis.location.search)) return null;\n    try {\n      const user = (await manager.signinCallback(globalThis.location.href)) ?? null;\n      restore(user?.url_state);\n      return user;\n    } catch {\n      // A stale state entry or a reloaded callback URL is \"not signed in\", not an exception for\n      // every caller of `getSession` to handle.\n      restore(undefined);\n      return null;\n    }\n  };\n\n  let completing: Promise<OidcUser | null> | undefined;\n\n  const load = singleFlight(async (): Promise<OidcUser | null> => {\n    completing ??= complete();\n    return (await completing) ?? manager.getUser();\n  });\n\n  /**\n   * One renewal at a time, shared by every caller — the most load-bearing line in this file, and\n   * the failure `singleFlight` exists for: under the rotation RFC 10017 requires, a second renewal\n   * replays a token the first already spent.\n   */\n  const renew = singleFlight(async (): Promise<OidcUser | null> => {\n    try {\n      return await manager.signinSilent();\n    } catch {\n      // A silent renewal fails when the refresh token is gone, rotated out, or the IdP session has\n      // ended. All three mean \"no session\", and the answer is the same one `getUser` gives for it.\n      return null;\n    }\n  });\n\n  const isExpired = (user: OidcUser): boolean =>\n    user.expires_at !== undefined && user.expires_at * 1000 <= Date.now();\n\n  /**\n   * The user — renewed when the token it carries has expired, and **asked for when there is no\n   * user at all**.\n   *\n   * That second case is the whole of what makes memory-only storage liveable, and it was missing:\n   * this returned `null` the moment `load()` did, so every reload signed the person out while the\n   * comment on `userStore` promised a silent renewal would pick them back up. Memory-only is a\n   * defensible trade against XSS *because* the IdP still holds the session and a `prompt=none`\n   * round trip recovers it; without that round trip it is just a session that dies on F5, which no\n   * product would accept and which no amount of XSS resistance would buy back.\n   *\n   * The cost is the one the `userStore` comment already names: an anonymous cold load spends a\n   * failed `prompt=none` too. `renew()` answers `null` for it rather than throwing, so the caller\n   * sees the same \"not signed in\" it saw before — one round trip later.\n   */\n  const fresh = async (): Promise<OidcUser | null> => {\n    const user = await load();\n    if (user === null) return renew();\n    return isExpired(user) ? renew() : user;\n  };\n\n  const toSession = (user: OidcUser): Session => {\n    const session = claims(user.profile, { clientId: config.clientId });\n    if (user.expires_at === undefined) return session;\n    // The access token's expiry comes from the token *response*, not from opening the token —\n    // which stays opaque. It is the credential we attach, so it is the one worth counting down.\n    return { ...session, expiresAt: user.expires_at * 1000 };\n  };\n\n  const source: TokenSource = {\n    async current() {\n      return (await fresh())?.access_token ?? null;\n    },\n    async renew() {\n      return (await renew())?.access_token ?? null;\n    },\n  };\n\n  return {\n    async getSession() {\n      const user = await fresh();\n      return user === null ? null : toSession(user);\n    },\n\n    subscribe(onChange) {\n      const detach = [\n        manager.events.addUserLoaded(onChange),\n        manager.events.addUserUnloaded(onChange),\n        manager.events.addAccessTokenExpired(onChange),\n        manager.events.addUserSessionChanged(onChange),\n      ];\n      return () => {\n        for (const off of detach) off();\n      };\n    },\n\n    async signIn(options: SignInOptions = {}) {\n      await manager.signinRedirect({\n        scope: scopeFor(scope, options.organization),\n        url_state: options.returnTo ?? globalThis.location.href,\n      });\n    },\n\n    async signOut(options = {}) {\n      // RP-initiated logout through the library, which discovers `end_session_endpoint` and sends\n      // the `id_token_hint`. A hand-built URL gets both wrong and neither failure is visible.\n      await manager.signoutRedirect({\n        post_logout_redirect_uri: options.returnTo ?? config.postLogoutRedirectUri,\n      });\n    },\n\n    fetch: authFetch(source),\n  };\n}\n"],"names":["DEFAULT_SCOPE","RESPONSE_PARAMS","isAuthorizationResponse","search","params","scopeFor","scope","organization","s","browserAuth","config","origin","_a","settings","WebStorageStateStore","InMemoryWebStorage","manager","UserManager","restore","returnTo","here","key","wanted","url","complete","user","completing","load","singleFlight","renew","isExpired","fresh","toSession","session","claims","onChange","detach","off","options","authFetch"],"mappings":";;;;AAqCA,MAAMA,IAAgB,uCAGhBC,IAAkB,CAAC,QAAQ,SAAS,iBAAiB,OAAO,SAAS,mBAAmB;AA0D9F,SAASC,EAAwBC,GAAyB;AACxD,QAAMC,IAAS,IAAI,gBAAgBD,CAAM;AACzC,SAAOC,EAAO,IAAI,OAAO,MAAMA,EAAO,IAAI,MAAM,KAAKA,EAAO,IAAI,OAAO;AACzE;AAEA,SAASC,EAASC,GAAeC,GAA0C;AACzE,SAAIA,MAAiB,SAAkBD,IAIhC,CAAC,GADKA,EAAM,MAAM,GAAG,EAAE,OAAO,CAACE,MAAMA,EAAE,SAAS,KAAK,CAACA,EAAE,WAAW,eAAe,CAAC,GACzE,gBAAgBD,CAAY,EAAE,EAAE,KAAK,GAAG;AAC3D;AAEO,SAASE,EAAYC,GAAiC;;AAC3D,QAAMC,MAASC,IAAA,WAAW,aAAX,gBAAAA,EAAqB,WAAU,IACxCN,IAAQI,EAAO,SAASV,GAExBa,IAAgC;AAAA,IACpC,WAAWH,EAAO;AAAA,IAClB,WAAWA,EAAO;AAAA,IAClB,cAAcA,EAAO,eAAeC;AAAA,IACpC,0BAA0BD,EAAO,yBAAyBC;AAAA,IAC1D,OAAAL;AAAA,IACA,eAAe;AAAA,IACf,gBAAgBI,EAAO,kBAAkB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAUzC,WAAW,IAAII,EAAqB,EAAE,OAAO,IAAIC,EAAA,GAAsB;AAAA;AAAA;AAAA;AAAA;AAAA,IAMvE,YAAY,IAAID,EAAqB,EAAE,OAAO,WAAW,gBAAgB;AAAA,EAAA,GAGrEE,KAAWN,EAAO,kBAAkB,CAACF,MAAM,IAAIS,EAAYT,CAAC,IAAIK,CAAQ,GAGxEK,IAAU,CAACC,MAAuC;AACtD,UAAMC,IAAO,IAAI,IAAI,WAAW,SAAS,IAAI;AAC7C,eAAWC,KAAOpB,EAAiB,CAAAmB,EAAK,aAAa,OAAOC,CAAG;AAC/D,UAAMC,IAASH,MAAa,SAAYC,IAAO,IAAI,IAAID,GAAUC,EAAK,MAAM,GAGtEG,IAAMD,EAAO,WAAWF,EAAK,SAASE,IAASF;AACrD,eAAW,QAAQ,aAAa,MAAM,IAAI,GAAGG,EAAI,QAAQ,GAAGA,EAAI,MAAM,GAAGA,EAAI,IAAI,EAAE;AAAA,EACrF,GAQMC,IAAW,YAAsC;AACrD,QAAI,CAACtB,EAAwB,WAAW,SAAS,MAAM,EAAG,QAAO;AACjE,QAAI;AACF,YAAMuB,IAAQ,MAAMT,EAAQ,eAAe,WAAW,SAAS,IAAI,KAAM;AACzE,aAAAE,EAAQO,KAAA,gBAAAA,EAAM,SAAS,GAChBA;AAAA,IACT,QAAQ;AAGN,aAAAP,EAAQ,MAAS,GACV;AAAA,IACT;AAAA,EACF;AAEA,MAAIQ;AAEJ,QAAMC,IAAOC,EAAa,aACxBF,UAAeF,EAAA,IACP,MAAME,KAAeV,EAAQ,QAAA,EACtC,GAOKa,IAAQD,EAAa,YAAsC;AAC/D,QAAI;AACF,aAAO,MAAMZ,EAAQ,aAAA;AAAA,IACvB,QAAQ;AAGN,aAAO;AAAA,IACT;AAAA,EACF,CAAC,GAEKc,IAAY,CAACL,MACjBA,EAAK,eAAe,UAAaA,EAAK,aAAa,OAAQ,KAAK,IAAA,GAiB5DM,IAAQ,YAAsC;AAClD,UAAMN,IAAO,MAAME,EAAA;AACnB,WAAIF,MAAS,QACNK,EAAUL,CAAI,IADKI,EAAA,IACSJ;AAAA,EACrC,GAEMO,IAAY,CAACP,MAA4B;AAC7C,UAAMQ,IAAUC,EAAOT,EAAK,SAAS,EAAE,UAAUf,EAAO,UAAU;AAClE,WAAIe,EAAK,eAAe,SAAkBQ,IAGnC,EAAE,GAAGA,GAAS,WAAWR,EAAK,aAAa,IAAA;AAAA,EACpD;AAWA,SAAO;AAAA,IACL,MAAM,aAAa;AACjB,YAAMA,IAAO,MAAMM,EAAA;AACnB,aAAON,MAAS,OAAO,OAAOO,EAAUP,CAAI;AAAA,IAC9C;AAAA,IAEA,UAAUU,GAAU;AAClB,YAAMC,IAAS;AAAA,QACbpB,EAAQ,OAAO,cAAcmB,CAAQ;AAAA,QACrCnB,EAAQ,OAAO,gBAAgBmB,CAAQ;AAAA,QACvCnB,EAAQ,OAAO,sBAAsBmB,CAAQ;AAAA,QAC7CnB,EAAQ,OAAO,sBAAsBmB,CAAQ;AAAA,MAAA;AAE/C,aAAO,MAAM;AACX,mBAAWE,KAAOD,EAAQ,CAAAC,EAAA;AAAA,MAC5B;AAAA,IACF;AAAA,IAEA,MAAM,OAAOC,IAAyB,IAAI;AACxC,YAAMtB,EAAQ,eAAe;AAAA,QAC3B,OAAOX,EAASC,GAAOgC,EAAQ,YAAY;AAAA,QAC3C,WAAWA,EAAQ,YAAY,WAAW,SAAS;AAAA,MAAA,CACpD;AAAA,IACH;AAAA,IAEA,MAAM,QAAQA,IAAU,IAAI;AAG1B,YAAMtB,EAAQ,gBAAgB;AAAA,QAC5B,0BAA0BsB,EAAQ,YAAY5B,EAAO;AAAA,MAAA,CACtD;AAAA,IACH;AAAA,IAEA,OAAO6B,EA1CmB;AAAA,MAC1B,MAAM,UAAU;;AACd,iBAAQ3B,IAAA,MAAMmB,QAAN,gBAAAnB,EAAgB,iBAAgB;AAAA,MAC1C;AAAA,MACA,MAAM,QAAQ;;AACZ,iBAAQA,IAAA,MAAMiB,QAAN,gBAAAjB,EAAgB,iBAAgB;AAAA,MAC1C;AAAA,IAAA,CAoCuB;AAAA,EAAA;AAE3B;"}

package/dist/can.d.ts

@@ -0,0 +1,25 @@
+import { Organization, Session } from './types';
+/**
+ * The role predicate, and the lookup underneath it.
+ *
+ * **What this decides is what to draw, never what to allow.** The roles a client holds are a copy,
+ * and a copy is something an attacker controls the moment it reaches the browser: `can` hides a
+ * button, and the resource server — validating the access token it was sent — is what actually
+ * refuses the request behind it. A product that gates only here has not gated anything.
+ */
+/** The organization by that alias, or `undefined` for one this person does not belong to. */
+export declare function organizationOf(session: Session | null | undefined, alias: string): Organization | undefined;
+/**
+ * Does this session hold `role`?
+ *
+ * With an `organization`, the question is asked *inside* it — the person's roles there, which is a
+ * different set from their realm and client roles and is deliberately not merged with them. A role
+ * held in one organization says nothing about another, and the day those two sets are unioned for
+ * convenience is the day one organization's owner is every organization's owner.
+ *
+ * Closed by default: no session, or no membership of the named organization, is `false` rather than
+ * an error. There is no hierarchy here either — that `owner` outranks `member` is a fact about a
+ * product, so a product spells it out: `can(s, "owner", org) || can(s, "member", org)`.
+ */
+export declare function can(session: Session | null | undefined, role: string, organization?: string): boolean;
+//# sourceMappingURL=can.d.ts.map