@kanzo-tech/auth 0.29.1 → 0.30.1

package/dist/store.d.ts

@@ -25,6 +25,14 @@ import { Session } from './types';
  */
 export interface SessionRecord {
     readonly session: Session;
+    /**
+     * The IdP's session id, the ID token's `sid`, kept across refreshes.
+     *
+     * It is what a back-channel logout names when one browser session ends at Keycloak rather than
+     * every session the person holds, and {@link ticketStore} writes it into the ticket for that
+     * reason. Absent on a realm that does not emit it, and then a logout can only end them all.
+     */
+    readonly sid?: string;
     /**
      * The credential for a resource server, and the reason this field exists.
      *
@@ -39,9 +47,8 @@ export interface SessionRecord {
      * Epoch milliseconds, from the token response's `expires_in` rather than from opening the token.
      *
      * The access token is opaque to us by contract — it is the resource server's to read — so its
-     * lifetime comes from the envelope it arrived in. {@link Session.expiresAt} is the *ID token's*
-     * expiry and is a different number on a realm that gives the two different lifetimes; renewing
-     * against the wrong one is how a request goes out with a credential that died a minute ago.
+     * lifetime comes from the envelope it arrived in, and {@link Session.expiresAt} is this same
+     * number: the moment the next renewal is due.
      */
     readonly accessTokenExpiresAt?: number;
     /** Rotated on every use, per RFC 10017. The stored one is always the newest issued. */
@@ -49,28 +56,73 @@ export interface SessionRecord {
     /** Kept for `id_token_hint` at the end-session endpoint; without it the IdP asks who is leaving. */
     readonly idToken?: string;
 }
+/**
+ * Who a back-channel logout names: a person, and optionally one of their IdP sessions.
+ *
+ * The shape of OpenID Connect Back-Channel Logout 1.0's own claims, `sub` and `sid`.
+ */
+export interface SessionSubject {
+    readonly sub: string;
+    readonly sid?: string;
+}
+/**
+ * Where sessions live between requests. A stable ticket, updated in place — Duende BFF's server-side
+ * session — rather than a new ticket per renewal.
+ *
+ * The ticket is issued **once, at sign-in**, which is the session-fixation defence: whatever cookie
+ * a browser arrived at the callback with, it leaves with a ticket nobody has seen before. After
+ * that the ticket names the session for its whole life, and a renewal changes what the row holds
+ * rather than which row it is. That is what lets a renewal that happens in the proxy leave the
+ * cookie alone, and what lets two tabs renewing at once agree on the session they share.
+ */
 export interface SessionStore {
     /**
-     * Store a record and return the ticket that identifies it.
+     * Store a record from a sign-in and return the ticket that identifies it.
      *
      * The ticket is what the cookie carries — sealed, so it never travels in the clear. **A store
      * that enforces one live session per person does it here**, by dropping that person's previous
      * ticket as it issues this one.
      */
     put(record: SessionRecord): Promise<string>;
+    /**
+     * Replace the record behind `ticket` after a renewal, and return the ticket to carry from now on
+     * — or `null` when there is no longer a session to replace.
+     *
+     * A store with server state answers `ticket` itself and the cookie does not change. A store whose
+     * ticket *is* the record — {@link statelessStore} — has no row to update and answers a new
+     * ticket, which is the cookie being re-sealed.
+     *
+     * **The write is conditional.** A back-channel logout may delete the row while a renewal is in
+     * flight; an unconditional write would bring the ended session back. `null` is the renewal
+     * learning it lost that race, and the session ends instead.
+     */
+    update(ticket: string, record: SessionRecord): Promise<string | null>;
     /** The record, or `null` when the ticket is unknown, expired, or has been revoked. */
     get(ticket: string): Promise<SessionRecord | null>;
     /** Forget it. Sign-out, and the immediate invalidation a self-contained cookie cannot do. */
     drop(ticket: string): Promise<void>;
+    /**
+     * Forget every session of `sub`, or only the one Keycloak calls `sid` — a back-channel logout.
+     *
+     * A store that cannot find a person's sessions rejects with `AuthError` `session/irrevocable`
+     * rather than answering as though it had: a logout that ends nothing must not report success to
+     * the identity provider.
+     */
+    dropAll(subject: SessionSubject): Promise<void>;
 }
 /**
  * The default: no server state at all. The ticket *is* the record.
  *
- * What it cannot do, stated plainly rather than discovered later: **`drop` does nothing.** Signing
- * out clears the cookie, which is enough for the person holding the browser and is not enough for
- * anyone else — a copy of that cookie taken beforehand keeps working until it expires. A session
- * lifetime is therefore a real security parameter under this store, and "sign out everywhere" is
- * not implementable on top of it. Give `relyingParty` a {@link ticketStore} when either matters.
+ * What it cannot do, stated plainly rather than discovered later: **`drop` does nothing**, and
+ * **`dropAll` refuses** with `session/irrevocable`. Signing out clears the cookie, which is enough
+ * for the person holding the browser and is not enough for anyone else — a copy of that cookie
+ * taken beforehand keeps working until it expires. A session lifetime is therefore a real security
+ * parameter under this store, and neither "sign out everywhere" nor a back-channel logout is
+ * implementable on top of it — Auth0's SDK requires a session store for back-channel logout for
+ * the same reason. Give `relyingParty` a {@link ticketStore} when either matters.
+ *
+ * `update` re-seals: the record changed, so the ticket that *is* the record changes with it, and
+ * the cookie carrying it is reissued.
  *
  * ## It does not fit a record that carries an access token, and the numbers are the argument
  *
@@ -86,7 +138,8 @@ export interface SessionStore {
  */
 export declare function statelessStore(): SessionStore;
 /**
- * The two functions and a delete that a store needs from a deployment's own database.
+ * What a store needs from a deployment's own database — read, write, a conditional replace and a
+ * delete — and a fifth that only a back-channel logout needs.
  *
  * Keys and opaque strings, because that is the intersection of Redis, a SQL table, a KV namespace
  * and a file on disk — anything narrower would name one of them. **An adapter does not bound its
@@ -111,7 +164,24 @@ export interface TicketAdapter {
      * sessions, because the sealed cookie carrying the ticket expires on its own schedule.
      */
     write(key: string, value: string, ttl: number): Promise<void>;
+    /**
+     * Overwrite `key` only if it still exists, and say whether it did — Redis `SET … XX`, SQL
+     * `UPDATE … WHERE key = ?` and its row count.
+     *
+     * One atomic step, because the check and the write must not have a gap between them: that gap
+     * is where a back-channel logout's delete lands and a renewal's write undoes it.
+     */
+    replace(key: string, value: string, ttl: number): Promise<boolean>;
     delete(key: string): Promise<void>;
+    /**
+     * Every key that begins with `prefix` — Redis `SCAN MATCH <prefix>*`, SQL `LIKE '<prefix>%'`.
+     *
+     * Optional, because only `dropAll` uses it; without it a back-channel logout answers that it
+     * cannot end anything. The prefix never contains a glob metacharacter — see
+     * {@link ticketStore} — so the Redis pattern is literal as written. A SQL adapter still escapes
+     * `%` and `_`, which percent-encoding produces.
+     */
+    keys?(prefix: string): AsyncIterable<string>;
 }
 export interface TicketStoreConfig {
     /**
@@ -125,14 +195,19 @@ export interface TicketStoreConfig {
  * database — which is what makes a sign-out a sign-out.
  *
  * ```ts
- * relyingParty({
+ * kanzoAuth(() => ({
  *   …,
  *   store: ticketStore({
  *     read: (key) => redis.get(key),
  *     write: (key, value, ttl) => redis.set(key, value, { EX: ttl }),
+ *     replace: async (key, value, ttl) => (await redis.set(key, value, { XX: true, EX: ttl })) === "OK",
  *     delete: (key) => redis.del(key),
+ *     // node-redis 5 yields a batch of keys per SCAN step
+ *     async *keys(prefix) {
+ *       for await (const batch of redis.scanIterator({ MATCH: `${prefix}*` })) yield* batch;
+ *     },
  *   }),
- * });
+ * }));
  * ```
  *
  * ## What this buys that the cookie cannot
@@ -150,15 +225,22 @@ export interface TicketStoreConfig {
  * The library makes the wait, so the library bounds it: a deployment that forgot to race its
  * Redis client would otherwise hang a page on a store that stopped answering.
  *
- * ## The key carries the subject, and that is deliberate
+ * ## The key carries the subject and the IdP session, and that is deliberate
+ *
+ * A ticket is `<sub>:<sid>:<random>`, each part percent-encoded. The random part is the whole of
+ * the security — the subject and session id are not secrets and are not trusted on the way back
+ * in, because the record they name is read from the row and never from the key. What the prefix
+ * buys is the one operation a flat random key makes impossible: *every session belonging to this
+ * person*, or *the one Keycloak just ended*. That is `dropAll`, which a back-channel logout calls,
+ * and it is a prefix scan through the adapter's `keys` — the same `SCAN sub:*` a deployment could
+ * write by hand for "sign out on every device".
+ *
+ * ## `update` keeps the ticket
  *
- * A ticket is `<subject>:<random>`. The random half is the whole of the security — the subject is
- * not a secret and is not trusted on the way back in, because the record it names is read from the
- * row and never from the key. What the prefix buys is the one operation a flat random key makes
- * impossible: *every session belonging to this person*. `SCAN sub:*` or `DELETE … WHERE key LIKE
- * 'sub:%'` is then a query a deployment can write, and "sign out on every device" and "one live
- * session per person" — which `put` is the place for — stop being features this package has to
- * grow an API for.
+ * A renewal rewrites the row under the same key, so the cookie that names it is untouched. It goes
+ * through `replace`, never `write`, so a row a back-channel logout deleted stays deleted. It also
+ * restarts the row's `ttl`, which can then outlive the cookie by up to one `ttl`; that is a row the
+ * adapter forgets later, never a session, because nothing can present the expired cookie.
  */
 export declare function ticketStore(adapter: TicketAdapter, config?: TicketStoreConfig): SessionStore;
 //# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oGAAoG;IACpG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,sFAAsF;IACtF,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACnD,6FAA6F;IAC7F,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAgB7C;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,GAAE,iBAAsB,GAAG,YAAY,CA8BhG"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oGAAoG;IACpG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,sFAAsF;IACtF,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACnD,6FAA6F;IAC7F,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAyB7C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,GAAE,iBAAsB,GAAG,YAAY,CAgDhG"}

package/dist/store.js

@@ -1,34 +1,57 @@
-import { deadline as c } from "./deadline.js";
-function l() {
+import { deadline as y } from "./deadline.js";
+import { AuthError as u } from "./types.js";
+function w() {
   return {
-    async put(t) {
-      return JSON.stringify(t);
+    async put(e) {
+      return JSON.stringify(e);
     },
-    async get(t) {
+    async update(e, r) {
+      return JSON.stringify(r);
+    },
+    async get(e) {
       try {
-        return JSON.parse(t);
+        return JSON.parse(e);
       } catch {
         return null;
       }
     },
     async drop() {
+    },
+    async dropAll() {
+      throw new u(
+        "session/irrevocable",
+        "a stateless session lives in the cookie, so no server can end it: give relyingParty a ticketStore"
+      );
     }
   };
 }
-const a = 480 * 60;
-function u() {
-  const t = crypto.getRandomValues(new Uint8Array(32));
-  return btoa(String.fromCharCode(...t)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const d = 480 * 60;
+function a(e) {
+  return encodeURIComponent(e).replace(
+    /[!'()*]/g,
+    (r) => `%${r.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+function c(e) {
+  const r = `${a(e.sub)}:`;
+  return e.sid === void 0 ? r : `${r}${a(e.sid)}:`;
 }
-function y(t, s = {}) {
-  const o = s.ttl ?? a, r = (e) => c("session/silent", e);
+function p() {
+  const e = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...e)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function S(e, r = {}) {
+  const i = r.ttl ?? d, s = (t) => y("session/silent", t);
   return {
-    async put(e) {
-      const n = `${encodeURIComponent(e.session.user.id)}:${u()}`;
-      return await r(() => t.write(n, JSON.stringify(e), o)), n;
+    async put(t) {
+      const n = `${c({ sub: t.session.user.id, sid: t.sid ?? "" })}${p()}`;
+      return await s(() => e.write(n, JSON.stringify(t), i)), n;
     },
-    async get(e) {
-      const n = await r(() => t.read(e));
+    async update(t, n) {
+      return await s(() => e.replace(t, JSON.stringify(n), i)) ? t : null;
+    },
+    async get(t) {
+      const n = await s(() => e.read(t));
       if (n === null) return null;
       try {
         return JSON.parse(n);
@@ -36,13 +59,25 @@ function y(t, s = {}) {
         return null;
       }
     },
-    async drop(e) {
-      await r(() => t.delete(e));
+    async drop(t) {
+      await s(() => e.delete(t));
+    },
+    async dropAll(t) {
+      var o;
+      const n = (o = e.keys) == null ? void 0 : o.bind(e);
+      if (n === void 0)
+        throw new u(
+          "session/irrevocable",
+          "the ticket adapter has no `keys`, so a person's sessions cannot be found to end them"
+        );
+      await s(async () => {
+        for await (const l of n(c(t))) await e.delete(l);
+      });
     }
   };
 }
 export {
-  l as statelessStore,
-  y as ticketStore
+  w as statelessStore,
+  S as ticketStore
 };
 //# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sources":["../src/store.ts"],"sourcesContent":["import { deadline } from \"./deadline\";\nimport type { Session } from \"./types\";\n\n/**\n * Where the server keeps what it knows about a signed-in person.\n *\n * The default is a cookie and nothing else: the record is sealed into it, and the deployment needs\n * no database to hold a session. That is the right default and it is not sufficient for everyone —\n * a product that enforces **one live session per user** and wants a sign-out\n * to take effect immediately, and a self-contained cookie can do neither. Both are the same\n * missing ability: a cookie already in someone's hands cannot be taken back.\n *\n * So: one interface, two implementations, and no catalogue. {@link statelessStore} is the cookie;\n * {@link ticketStore} is an opaque ticket over **a key-value adapter the deployment supplies**, so\n * plugging in Redis or a table is two functions rather than a reimplementation of the ticket. No\n * backend ships here — a driver is a dependency and a deployment decision, and neither is this\n * package's to make on its way past — but the *shape* does, because without it every product that\n * wants a real sign-out writes its own sealing, and a logout that invalidates nothing is the\n * thing they all ship instead.\n */\n\n/**\n * What the server holds, and the browser never sees.\n *\n * The tokens are here rather than on {@link Session} because {@link Session} is the shape the\n * browser is given. Under the BFF pattern the whole point is that the refresh token stops at the\n * server, and a type that carried both would make the leak a typo away.\n */\nexport interface SessionRecord {\n  readonly session: Session;\n  /**\n   * The credential for a resource server, and the reason this field exists.\n   *\n   * Without it a token-mediating backend has nothing `typ: \"Bearer\"` to forward, and what it\n   * reaches for instead is the ID token — which works on a realm that happens to put the same\n   * audience in both and stops working the day the resource server checks the type, as it should.\n   * An ID token says *who signed in*; it was never a key to an API. It is also what\n   * `/token/introspect` and `/revoke` take, neither of which is reachable holding the other one.\n   */\n  readonly accessToken?: string;\n  /**\n   * Epoch milliseconds, from the token response's `expires_in` rather than from opening the token.\n   *\n   * The access token is opaque to us by contract — it is the resource server's to read — so its\n   * lifetime comes from the envelope it arrived in. {@link Session.expiresAt} is the *ID token's*\n   * expiry and is a different number on a realm that gives the two different lifetimes; renewing\n   * against the wrong one is how a request goes out with a credential that died a minute ago.\n   */\n  readonly accessTokenExpiresAt?: number;\n  /** Rotated on every use, per RFC 10017. The stored one is always the newest issued. */\n  readonly refreshToken?: string;\n  /** Kept for `id_token_hint` at the end-session endpoint; without it the IdP asks who is leaving. */\n  readonly idToken?: string;\n}\n\nexport interface SessionStore {\n  /**\n   * Store a record and return the ticket that identifies it.\n   *\n   * The ticket is what the cookie carries — sealed, so it never travels in the clear. **A store\n   * that enforces one live session per person does it here**, by dropping that person's previous\n   * ticket as it issues this one.\n   */\n  put(record: SessionRecord): Promise<string>;\n  /** The record, or `null` when the ticket is unknown, expired, or has been revoked. */\n  get(ticket: string): Promise<SessionRecord | null>;\n  /** Forget it. Sign-out, and the immediate invalidation a self-contained cookie cannot do. */\n  drop(ticket: string): Promise<void>;\n}\n\n/**\n * The default: no server state at all. The ticket *is* the record.\n *\n * What it cannot do, stated plainly rather than discovered later: **`drop` does nothing.** Signing\n * out clears the cookie, which is enough for the person holding the browser and is not enough for\n * anyone else — a copy of that cookie taken beforehand keeps working until it expires. A session\n * lifetime is therefore a real security parameter under this store, and \"sign out everywhere\" is\n * not implementable on top of it. Give `relyingParty` a {@link ticketStore} when either matters.\n *\n * ## It does not fit a record that carries an access token, and the numbers are the argument\n *\n * A browser is only required to keep 4096 bytes of cookie. Sealed with the three tokens a\n * token-mediating backend holds, a realistic Keycloak record — two organizations, the roles that\n * come with them — measures **6407 bytes**, and it measured **4068** before the access token\n * joined it, which is 28 bytes of margin and not a design. `store.test.ts` holds both figures.\n *\n * So this store is for a product that reads identity and calls no resource server. The moment\n * there is an API to call, the cookie carries a ticket instead of the tokens — which is\n * {@link ticketStore}, and the sealing throws with the byte count rather than letting a browser\n * drop the cookie in silence.\n */\nexport function statelessStore(): SessionStore {\n  return {\n    async put(record) {\n      return JSON.stringify(record);\n    },\n    async get(ticket) {\n      try {\n        return JSON.parse(ticket) as SessionRecord;\n      } catch {\n        return null;\n      }\n    },\n    async drop() {\n      /* Nothing to forget: see above, and mean it. */\n    },\n  };\n}\n\n/**\n * The two functions and a delete that a store needs from a deployment's own database.\n *\n * Keys and opaque strings, because that is the intersection of Redis, a SQL table, a KV namespace\n * and a file on disk — anything narrower would name one of them. **An adapter does not bound its\n * own waits**: {@link ticketStore} races every call against the package's deadline, so a driver\n * call is all an adapter is. What it still owns is the driver's own configuration — a connect\n * timeout, no offline queue — which is what makes a store that is down refuse at once rather than\n * hang until the deadline.\n *\n * The value is already serialized and it is **not encrypted**: it lives inside the deployment's own trust boundary, and a key held\n * by the same process that reads the rows protects against a stolen dump and nothing else. Encrypt\n * the storage, not the row.\n */\nexport interface TicketAdapter {\n  /** The value written under `key`, or `null` when it is unknown or has expired. */\n  read(key: string): Promise<string | null>;\n  /**\n   * Write `value` under `key`, to be forgotten after `ttl` seconds.\n   *\n   * **Honouring `ttl` is the adapter's job**, because every store that could hold this already has\n   * an expiry of its own — `EX` on Redis, a column and a sweep on SQL — and a timer here would be\n   * one that dies with the process. An adapter that ignores it leaks rows; it does not leak\n   * sessions, because the sealed cookie carrying the ticket expires on its own schedule.\n   */\n  write(key: string, value: string, ttl: number): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface TicketStoreConfig {\n  /**\n   * Seconds a record is kept. Default eight hours — **set it to the `maxAge` you gave\n   * `relyingParty`**, which is the lifetime of the cookie that carries the ticket.\n   */\n  readonly ttl?: number;\n}\n\n/** Eight hours, the same working day `relyingParty` defaults its cookie to. */\nconst DEFAULT_TTL = 8 * 60 * 60;\n\n/**\n * 256 bits from the CSPRNG, base64url. The ticket is a bearer credential in everything but name —\n * it is sealed in the cookie, and it still must not be guessable from another one.\n */\nfunction opaqueTicket(): string {\n  const bytes = crypto.getRandomValues(new Uint8Array(32));\n  return btoa(String.fromCharCode(...bytes)).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/**\n * A store where the cookie carries an opaque ticket and the record lives in the deployment's own\n * database — which is what makes a sign-out a sign-out.\n *\n * ```ts\n * relyingParty({\n *   …,\n *   store: ticketStore({\n *     read: (key) => redis.get(key),\n *     write: (key, value, ttl) => redis.set(key, value, { EX: ttl }),\n *     delete: (key) => redis.del(key),\n *   }),\n * });\n * ```\n *\n * ## What this buys that the cookie cannot\n *\n * **`drop` deletes.** Under {@link statelessStore} the ticket is the record, so a copy of the\n * cookie taken before sign-out keeps working until it expires and *sign out everywhere* is not\n * expressible at all. Here the cookie is a name for a row, and deleting the row ends every copy of\n * the cookie at once, immediately.\n *\n * ## Every wait on the adapter is bounded here\n *\n * Each `read`, `write` and `delete` is raced against `DEADLINE` (30 s), and one that has not\n * answered by then rejects as `AuthError` `session/silent` with `{ after }` — which the server\n * reports as `session/unavailable`, with that as its cause, like any other failure of the store.\n * The library makes the wait, so the library bounds it: a deployment that forgot to race its\n * Redis client would otherwise hang a page on a store that stopped answering.\n *\n * ## The key carries the subject, and that is deliberate\n *\n * A ticket is `<subject>:<random>`. The random half is the whole of the security — the subject is\n * not a secret and is not trusted on the way back in, because the record it names is read from the\n * row and never from the key. What the prefix buys is the one operation a flat random key makes\n * impossible: *every session belonging to this person*. `SCAN sub:*` or `DELETE … WHERE key LIKE\n * 'sub:%'` is then a query a deployment can write, and \"sign out on every device\" and \"one live\n * session per person\" — which `put` is the place for — stop being features this package has to\n * grow an API for.\n */\nexport function ticketStore(adapter: TicketAdapter, config: TicketStoreConfig = {}): SessionStore {\n  const ttl = config.ttl ?? DEFAULT_TTL;\n  const bounded = <T>(call: () => Promise<T>) => deadline(\"session/silent\", call);\n\n  return {\n    async put(record) {\n      // `encodeURIComponent` on the subject, not on the whole key: a `sub` is a uuid on every realm\n      // anyone has seen, and on the one that makes it something with a colon in it the prefix must\n      // still be the prefix. The random half needs no encoding — base64url is already key-safe.\n      const ticket = `${encodeURIComponent(record.session.user.id)}:${opaqueTicket()}`;\n      await bounded(() => adapter.write(ticket, JSON.stringify(record), ttl));\n      return ticket;\n    },\n\n    async get(ticket) {\n      const value = await bounded(() => adapter.read(ticket));\n      if (value === null) return null;\n      try {\n        return JSON.parse(value) as SessionRecord;\n      } catch {\n        // A row that is not a record is a row somebody else wrote, or one written by a version\n        // that shaped it differently. Either way it names nobody, which is what `null` says.\n        return null;\n      }\n    },\n\n    async drop(ticket) {\n      await bounded(() => adapter.delete(ticket));\n    },\n  };\n}\n"],"names":["statelessStore","record","ticket","DEFAULT_TTL","opaqueTicket","bytes","ticketStore","adapter","config","ttl","bounded","call","deadline","value"],"mappings":";AA2FO,SAASA,IAA+B;AAC7C,SAAO;AAAA,IACL,MAAM,IAAIC,GAAQ;AAChB,aAAO,KAAK,UAAUA,CAAM;AAAA,IAC9B;AAAA,IACA,MAAM,IAAIC,GAAQ;AAChB,UAAI;AACF,eAAO,KAAK,MAAMA,CAAM;AAAA,MAC1B,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,MAAM,OAAO;AAAA,IAEb;AAAA,EAAA;AAEJ;AAwCA,MAAMC,IAAc,MAAS;AAM7B,SAASC,IAAuB;AAC9B,QAAMC,IAAQ,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AACvD,SAAO,KAAK,OAAO,aAAa,GAAGA,CAAK,CAAC,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AACtG;AA0CO,SAASC,EAAYC,GAAwBC,IAA4B,IAAkB;AAChG,QAAMC,IAAMD,EAAO,OAAOL,GACpBO,IAAU,CAAIC,MAA2BC,EAAS,kBAAkBD,CAAI;AAE9E,SAAO;AAAA,IACL,MAAM,IAAIV,GAAQ;AAIhB,YAAMC,IAAS,GAAG,mBAAmBD,EAAO,QAAQ,KAAK,EAAE,CAAC,IAAIG,EAAA,CAAc;AAC9E,mBAAMM,EAAQ,MAAMH,EAAQ,MAAML,GAAQ,KAAK,UAAUD,CAAM,GAAGQ,CAAG,CAAC,GAC/DP;AAAA,IACT;AAAA,IAEA,MAAM,IAAIA,GAAQ;AAChB,YAAMW,IAAQ,MAAMH,EAAQ,MAAMH,EAAQ,KAAKL,CAAM,CAAC;AACtD,UAAIW,MAAU,KAAM,QAAO;AAC3B,UAAI;AACF,eAAO,KAAK,MAAMA,CAAK;AAAA,MACzB,QAAQ;AAGN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IAEA,MAAM,KAAKX,GAAQ;AACjB,YAAMQ,EAAQ,MAAMH,EAAQ,OAAOL,CAAM,CAAC;AAAA,IAC5C;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"store.js","sources":["../src/store.ts"],"sourcesContent":["import { deadline } from \"./deadline\";\nimport { AuthError, type Session } from \"./types\";\n\n/**\n * Where the server keeps what it knows about a signed-in person.\n *\n * The default is a cookie and nothing else: the record is sealed into it, and the deployment needs\n * no database to hold a session. That is the right default and it is not sufficient for everyone —\n * a product that enforces **one live session per user** and wants a sign-out\n * to take effect immediately, and a self-contained cookie can do neither. Both are the same\n * missing ability: a cookie already in someone's hands cannot be taken back.\n *\n * So: one interface, two implementations, and no catalogue. {@link statelessStore} is the cookie;\n * {@link ticketStore} is an opaque ticket over **a key-value adapter the deployment supplies**, so\n * plugging in Redis or a table is two functions rather than a reimplementation of the ticket. No\n * backend ships here — a driver is a dependency and a deployment decision, and neither is this\n * package's to make on its way past — but the *shape* does, because without it every product that\n * wants a real sign-out writes its own sealing, and a logout that invalidates nothing is the\n * thing they all ship instead.\n */\n\n/**\n * What the server holds, and the browser never sees.\n *\n * The tokens are here rather than on {@link Session} because {@link Session} is the shape the\n * browser is given. Under the BFF pattern the whole point is that the refresh token stops at the\n * server, and a type that carried both would make the leak a typo away.\n */\nexport interface SessionRecord {\n  readonly session: Session;\n  /**\n   * The IdP's session id, the ID token's `sid`, kept across refreshes.\n   *\n   * It is what a back-channel logout names when one browser session ends at Keycloak rather than\n   * every session the person holds, and {@link ticketStore} writes it into the ticket for that\n   * reason. Absent on a realm that does not emit it, and then a logout can only end them all.\n   */\n  readonly sid?: string;\n  /**\n   * The credential for a resource server, and the reason this field exists.\n   *\n   * Without it a token-mediating backend has nothing `typ: \"Bearer\"` to forward, and what it\n   * reaches for instead is the ID token — which works on a realm that happens to put the same\n   * audience in both and stops working the day the resource server checks the type, as it should.\n   * An ID token says *who signed in*; it was never a key to an API. It is also what\n   * `/token/introspect` and `/revoke` take, neither of which is reachable holding the other one.\n   */\n  readonly accessToken?: string;\n  /**\n   * Epoch milliseconds, from the token response's `expires_in` rather than from opening the token.\n   *\n   * The access token is opaque to us by contract — it is the resource server's to read — so its\n   * lifetime comes from the envelope it arrived in, and {@link Session.expiresAt} is this same\n   * number: the moment the next renewal is due.\n   */\n  readonly accessTokenExpiresAt?: number;\n  /** Rotated on every use, per RFC 10017. The stored one is always the newest issued. */\n  readonly refreshToken?: string;\n  /** Kept for `id_token_hint` at the end-session endpoint; without it the IdP asks who is leaving. */\n  readonly idToken?: string;\n}\n\n/**\n * Who a back-channel logout names: a person, and optionally one of their IdP sessions.\n *\n * The shape of OpenID Connect Back-Channel Logout 1.0's own claims, `sub` and `sid`.\n */\nexport interface SessionSubject {\n  readonly sub: string;\n  readonly sid?: string;\n}\n\n/**\n * Where sessions live between requests. A stable ticket, updated in place — Duende BFF's server-side\n * session — rather than a new ticket per renewal.\n *\n * The ticket is issued **once, at sign-in**, which is the session-fixation defence: whatever cookie\n * a browser arrived at the callback with, it leaves with a ticket nobody has seen before. After\n * that the ticket names the session for its whole life, and a renewal changes what the row holds\n * rather than which row it is. That is what lets a renewal that happens in the proxy leave the\n * cookie alone, and what lets two tabs renewing at once agree on the session they share.\n */\nexport interface SessionStore {\n  /**\n   * Store a record from a sign-in and return the ticket that identifies it.\n   *\n   * The ticket is what the cookie carries — sealed, so it never travels in the clear. **A store\n   * that enforces one live session per person does it here**, by dropping that person's previous\n   * ticket as it issues this one.\n   */\n  put(record: SessionRecord): Promise<string>;\n  /**\n   * Replace the record behind `ticket` after a renewal, and return the ticket to carry from now on\n   * — or `null` when there is no longer a session to replace.\n   *\n   * A store with server state answers `ticket` itself and the cookie does not change. A store whose\n   * ticket *is* the record — {@link statelessStore} — has no row to update and answers a new\n   * ticket, which is the cookie being re-sealed.\n   *\n   * **The write is conditional.** A back-channel logout may delete the row while a renewal is in\n   * flight; an unconditional write would bring the ended session back. `null` is the renewal\n   * learning it lost that race, and the session ends instead.\n   */\n  update(ticket: string, record: SessionRecord): Promise<string | null>;\n  /** The record, or `null` when the ticket is unknown, expired, or has been revoked. */\n  get(ticket: string): Promise<SessionRecord | null>;\n  /** Forget it. Sign-out, and the immediate invalidation a self-contained cookie cannot do. */\n  drop(ticket: string): Promise<void>;\n  /**\n   * Forget every session of `sub`, or only the one Keycloak calls `sid` — a back-channel logout.\n   *\n   * A store that cannot find a person's sessions rejects with `AuthError` `session/irrevocable`\n   * rather than answering as though it had: a logout that ends nothing must not report success to\n   * the identity provider.\n   */\n  dropAll(subject: SessionSubject): Promise<void>;\n}\n\n/**\n * The default: no server state at all. The ticket *is* the record.\n *\n * What it cannot do, stated plainly rather than discovered later: **`drop` does nothing**, and\n * **`dropAll` refuses** with `session/irrevocable`. Signing out clears the cookie, which is enough\n * for the person holding the browser and is not enough for anyone else — a copy of that cookie\n * taken beforehand keeps working until it expires. A session lifetime is therefore a real security\n * parameter under this store, and neither \"sign out everywhere\" nor a back-channel logout is\n * implementable on top of it — Auth0's SDK requires a session store for back-channel logout for\n * the same reason. Give `relyingParty` a {@link ticketStore} when either matters.\n *\n * `update` re-seals: the record changed, so the ticket that *is* the record changes with it, and\n * the cookie carrying it is reissued.\n *\n * ## It does not fit a record that carries an access token, and the numbers are the argument\n *\n * A browser is only required to keep 4096 bytes of cookie. Sealed with the three tokens a\n * token-mediating backend holds, a realistic Keycloak record — two organizations, the roles that\n * come with them — measures **6407 bytes**, and it measured **4068** before the access token\n * joined it, which is 28 bytes of margin and not a design. `store.test.ts` holds both figures.\n *\n * So this store is for a product that reads identity and calls no resource server. The moment\n * there is an API to call, the cookie carries a ticket instead of the tokens — which is\n * {@link ticketStore}, and the sealing throws with the byte count rather than letting a browser\n * drop the cookie in silence.\n */\nexport function statelessStore(): SessionStore {\n  return {\n    async put(record) {\n      return JSON.stringify(record);\n    },\n    async update(_ticket, record) {\n      return JSON.stringify(record);\n    },\n    async get(ticket) {\n      try {\n        return JSON.parse(ticket) as SessionRecord;\n      } catch {\n        return null;\n      }\n    },\n    async drop() {\n      /* Nothing to forget: see above, and mean it. */\n    },\n    async dropAll() {\n      throw new AuthError(\n        \"session/irrevocable\",\n        \"a stateless session lives in the cookie, so no server can end it: give relyingParty a ticketStore\",\n      );\n    },\n  };\n}\n\n/**\n * What a store needs from a deployment's own database — read, write, a conditional replace and a\n * delete — and a fifth that only a back-channel logout needs.\n *\n * Keys and opaque strings, because that is the intersection of Redis, a SQL table, a KV namespace\n * and a file on disk — anything narrower would name one of them. **An adapter does not bound its\n * own waits**: {@link ticketStore} races every call against the package's deadline, so a driver\n * call is all an adapter is. What it still owns is the driver's own configuration — a connect\n * timeout, no offline queue — which is what makes a store that is down refuse at once rather than\n * hang until the deadline.\n *\n * The value is already serialized and it is **not encrypted**: it lives inside the deployment's own trust boundary, and a key held\n * by the same process that reads the rows protects against a stolen dump and nothing else. Encrypt\n * the storage, not the row.\n */\nexport interface TicketAdapter {\n  /** The value written under `key`, or `null` when it is unknown or has expired. */\n  read(key: string): Promise<string | null>;\n  /**\n   * Write `value` under `key`, to be forgotten after `ttl` seconds.\n   *\n   * **Honouring `ttl` is the adapter's job**, because every store that could hold this already has\n   * an expiry of its own — `EX` on Redis, a column and a sweep on SQL — and a timer here would be\n   * one that dies with the process. An adapter that ignores it leaks rows; it does not leak\n   * sessions, because the sealed cookie carrying the ticket expires on its own schedule.\n   */\n  write(key: string, value: string, ttl: number): Promise<void>;\n  /**\n   * Overwrite `key` only if it still exists, and say whether it did — Redis `SET … XX`, SQL\n   * `UPDATE … WHERE key = ?` and its row count.\n   *\n   * One atomic step, because the check and the write must not have a gap between them: that gap\n   * is where a back-channel logout's delete lands and a renewal's write undoes it.\n   */\n  replace(key: string, value: string, ttl: number): Promise<boolean>;\n  delete(key: string): Promise<void>;\n  /**\n   * Every key that begins with `prefix` — Redis `SCAN MATCH <prefix>*`, SQL `LIKE '<prefix>%'`.\n   *\n   * Optional, because only `dropAll` uses it; without it a back-channel logout answers that it\n   * cannot end anything. The prefix never contains a glob metacharacter — see\n   * {@link ticketStore} — so the Redis pattern is literal as written. A SQL adapter still escapes\n   * `%` and `_`, which percent-encoding produces.\n   */\n  keys?(prefix: string): AsyncIterable<string>;\n}\n\nexport interface TicketStoreConfig {\n  /**\n   * Seconds a record is kept. Default eight hours — **set it to the `maxAge` you gave\n   * `relyingParty`**, which is the lifetime of the cookie that carries the ticket.\n   */\n  readonly ttl?: number;\n}\n\n/** Eight hours, the same working day `relyingParty` defaults its cookie to. */\nconst DEFAULT_TTL = 8 * 60 * 60;\n\n/**\n * `encodeURIComponent`, and the five characters it leaves alone that a glob or a pattern reads:\n * `!`, `'`, `(`, `)` and `*`. A subject spelled `*` must not become a prefix that matches everyone.\n */\nfunction keySegment(value: string): string {\n  return encodeURIComponent(value).replace(\n    /[!'()*]/g,\n    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,\n  );\n}\n\n/** Where a person's tickets begin, or one IdP session's: `<sub>:` and `<sub>:<sid>:`. */\nfunction prefixOf(subject: SessionSubject): string {\n  const sub = `${keySegment(subject.sub)}:`;\n  return subject.sid === undefined ? sub : `${sub}${keySegment(subject.sid)}:`;\n}\n\n/**\n * 256 bits from the CSPRNG, base64url. The ticket is a bearer credential in everything but name —\n * it is sealed in the cookie, and it still must not be guessable from another one.\n */\nfunction opaqueTicket(): string {\n  const bytes = crypto.getRandomValues(new Uint8Array(32));\n  return btoa(String.fromCharCode(...bytes)).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/**\n * A store where the cookie carries an opaque ticket and the record lives in the deployment's own\n * database — which is what makes a sign-out a sign-out.\n *\n * ```ts\n * kanzoAuth(() => ({\n *   …,\n *   store: ticketStore({\n *     read: (key) => redis.get(key),\n *     write: (key, value, ttl) => redis.set(key, value, { EX: ttl }),\n *     replace: async (key, value, ttl) => (await redis.set(key, value, { XX: true, EX: ttl })) === \"OK\",\n *     delete: (key) => redis.del(key),\n *     // node-redis 5 yields a batch of keys per SCAN step\n *     async *keys(prefix) {\n *       for await (const batch of redis.scanIterator({ MATCH: `${prefix}*` })) yield* batch;\n *     },\n *   }),\n * }));\n * ```\n *\n * ## What this buys that the cookie cannot\n *\n * **`drop` deletes.** Under {@link statelessStore} the ticket is the record, so a copy of the\n * cookie taken before sign-out keeps working until it expires and *sign out everywhere* is not\n * expressible at all. Here the cookie is a name for a row, and deleting the row ends every copy of\n * the cookie at once, immediately.\n *\n * ## Every wait on the adapter is bounded here\n *\n * Each `read`, `write` and `delete` is raced against `DEADLINE` (30 s), and one that has not\n * answered by then rejects as `AuthError` `session/silent` with `{ after }` — which the server\n * reports as `session/unavailable`, with that as its cause, like any other failure of the store.\n * The library makes the wait, so the library bounds it: a deployment that forgot to race its\n * Redis client would otherwise hang a page on a store that stopped answering.\n *\n * ## The key carries the subject and the IdP session, and that is deliberate\n *\n * A ticket is `<sub>:<sid>:<random>`, each part percent-encoded. The random part is the whole of\n * the security — the subject and session id are not secrets and are not trusted on the way back\n * in, because the record they name is read from the row and never from the key. What the prefix\n * buys is the one operation a flat random key makes impossible: *every session belonging to this\n * person*, or *the one Keycloak just ended*. That is `dropAll`, which a back-channel logout calls,\n * and it is a prefix scan through the adapter's `keys` — the same `SCAN sub:*` a deployment could\n * write by hand for \"sign out on every device\".\n *\n * ## `update` keeps the ticket\n *\n * A renewal rewrites the row under the same key, so the cookie that names it is untouched. It goes\n * through `replace`, never `write`, so a row a back-channel logout deleted stays deleted. It also\n * restarts the row's `ttl`, which can then outlive the cookie by up to one `ttl`; that is a row the\n * adapter forgets later, never a session, because nothing can present the expired cookie.\n */\nexport function ticketStore(adapter: TicketAdapter, config: TicketStoreConfig = {}): SessionStore {\n  const ttl = config.ttl ?? DEFAULT_TTL;\n  const bounded = <T>(call: () => Promise<T>) => deadline(\"session/silent\", call);\n\n  return {\n    async put(record) {\n      // Encoded per part, not as a whole key: a `sub` is a uuid on every realm anyone has seen, and\n      // on the one that makes it something with a colon in it the prefix must still be the prefix.\n      // The random part needs no encoding — base64url is already key-safe.\n      const ticket = `${prefixOf({ sub: record.session.user.id, sid: record.sid ?? \"\" })}${opaqueTicket()}`;\n      await bounded(() => adapter.write(ticket, JSON.stringify(record), ttl));\n      return ticket;\n    },\n\n    async update(ticket, record) {\n      const replaced = await bounded(() => adapter.replace(ticket, JSON.stringify(record), ttl));\n      return replaced ? ticket : null;\n    },\n\n    async get(ticket) {\n      const value = await bounded(() => adapter.read(ticket));\n      if (value === null) return null;\n      try {\n        return JSON.parse(value) as SessionRecord;\n      } catch {\n        // A row that is not a record is a row somebody else wrote, or one written by a version\n        // that shaped it differently. Either way it names nobody, which is what `null` says.\n        return null;\n      }\n    },\n\n    async drop(ticket) {\n      await bounded(() => adapter.delete(ticket));\n    },\n\n    async dropAll(subject) {\n      const keys = adapter.keys?.bind(adapter);\n      if (keys === undefined) {\n        throw new AuthError(\n          \"session/irrevocable\",\n          \"the ticket adapter has no `keys`, so a person's sessions cannot be found to end them\",\n        );\n      }\n      await bounded(async () => {\n        for await (const key of keys(prefixOf(subject))) await adapter.delete(key);\n      });\n    },\n  };\n}\n"],"names":["statelessStore","record","_ticket","ticket","AuthError","DEFAULT_TTL","keySegment","value","c","prefixOf","subject","sub","opaqueTicket","bytes","ticketStore","adapter","config","ttl","bounded","call","deadline","keys","_a","key"],"mappings":";;AAgJO,SAASA,IAA+B;AAC7C,SAAO;AAAA,IACL,MAAM,IAAIC,GAAQ;AAChB,aAAO,KAAK,UAAUA,CAAM;AAAA,IAC9B;AAAA,IACA,MAAM,OAAOC,GAASD,GAAQ;AAC5B,aAAO,KAAK,UAAUA,CAAM;AAAA,IAC9B;AAAA,IACA,MAAM,IAAIE,GAAQ;AAChB,UAAI;AACF,eAAO,KAAK,MAAMA,CAAM;AAAA,MAC1B,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,MAAM,OAAO;AAAA,IAEb;AAAA,IACA,MAAM,UAAU;AACd,YAAM,IAAIC;AAAA,QACR;AAAA,QACA;AAAA,MAAA;AAAA,IAEJ;AAAA,EAAA;AAEJ;AA0DA,MAAMC,IAAc,MAAS;AAM7B,SAASC,EAAWC,GAAuB;AACzC,SAAO,mBAAmBA,CAAK,EAAE;AAAA,IAC/B;AAAA,IACA,CAACC,MAAM,IAAIA,EAAE,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,aAAa;AAAA,EAAA;AAEzD;AAGA,SAASC,EAASC,GAAiC;AACjD,QAAMC,IAAM,GAAGL,EAAWI,EAAQ,GAAG,CAAC;AACtC,SAAOA,EAAQ,QAAQ,SAAYC,IAAM,GAAGA,CAAG,GAAGL,EAAWI,EAAQ,GAAG,CAAC;AAC3E;AAMA,SAASE,IAAuB;AAC9B,QAAMC,IAAQ,OAAO,gBAAgB,IAAI,WAAW,EAAE,CAAC;AACvD,SAAO,KAAK,OAAO,aAAa,GAAGA,CAAK,CAAC,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AACtG;AAsDO,SAASC,EAAYC,GAAwBC,IAA4B,IAAkB;AAChG,QAAMC,IAAMD,EAAO,OAAOX,GACpBa,IAAU,CAAIC,MAA2BC,EAAS,kBAAkBD,CAAI;AAE9E,SAAO;AAAA,IACL,MAAM,IAAIlB,GAAQ;AAIhB,YAAME,IAAS,GAAGM,EAAS,EAAE,KAAKR,EAAO,QAAQ,KAAK,IAAI,KAAKA,EAAO,OAAO,GAAA,CAAI,CAAC,GAAGW,GAAc;AACnG,mBAAMM,EAAQ,MAAMH,EAAQ,MAAMZ,GAAQ,KAAK,UAAUF,CAAM,GAAGgB,CAAG,CAAC,GAC/Dd;AAAA,IACT;AAAA,IAEA,MAAM,OAAOA,GAAQF,GAAQ;AAE3B,aADiB,MAAMiB,EAAQ,MAAMH,EAAQ,QAAQZ,GAAQ,KAAK,UAAUF,CAAM,GAAGgB,CAAG,CAAC,IACvEd,IAAS;AAAA,IAC7B;AAAA,IAEA,MAAM,IAAIA,GAAQ;AAChB,YAAMI,IAAQ,MAAMW,EAAQ,MAAMH,EAAQ,KAAKZ,CAAM,CAAC;AACtD,UAAII,MAAU,KAAM,QAAO;AAC3B,UAAI;AACF,eAAO,KAAK,MAAMA,CAAK;AAAA,MACzB,QAAQ;AAGN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IAEA,MAAM,KAAKJ,GAAQ;AACjB,YAAMe,EAAQ,MAAMH,EAAQ,OAAOZ,CAAM,CAAC;AAAA,IAC5C;AAAA,IAEA,MAAM,QAAQO,GAAS;;AACrB,YAAMW,KAAOC,IAAAP,EAAQ,SAAR,gBAAAO,EAAc,KAAKP;AAChC,UAAIM,MAAS;AACX,cAAM,IAAIjB;AAAA,UACR;AAAA,UACA;AAAA,QAAA;AAGJ,YAAMc,EAAQ,YAAY;AACxB,yBAAiBK,KAAOF,EAAKZ,EAASC,CAAO,CAAC,EAAG,OAAMK,EAAQ,OAAOQ,CAAG;AAAA,MAC3E,CAAC;AAAA,IACH;AAAA,EAAA;AAEJ;"}

package/dist/types.d.ts

@@ -25,10 +25,11 @@ export interface Organization {
 /**
  * The whole of what the client knows about who is signed in.
  *
- * **There is no active organization here, and the absence is the design.** 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.
+ * **Membership and the current organization are two different things, and only the first is
+ * stored.** Membership is stable and comes from the token. Which organization a request is *in* is
+ * a property of that request — its host, its path, a cookie — so `organization` is resolved per
+ * request by the product's resolver and never written into the session record. That is what lets
+ * two tabs sit in two organizations at once: there is no shared value for them to fight over.
  *
  * `roles` are the realm and client roles: global to the person. Roles held inside an organization
  * live on that `Organization`. They are kept apart on purpose, because merging them is how a role
@@ -38,7 +39,17 @@ export interface Session {
     readonly user: AuthUser;
     readonly roles: readonly string[];
     readonly organizations: readonly Organization[];
-    /** Epoch milliseconds. The client uses it to refresh early, never to decide access. */
+    /**
+     * The alias of the organization this request addresses, as the product's resolver answered it.
+     *
+     * An address, not a proof of membership: `can` answers `false` for an organization the person
+     * does not belong to, which is how a product tells "not a member here" from "no tenant".
+     */
+    readonly organization?: string;
+    /**
+     * Epoch milliseconds: when the access token expires, which is when the next renewal is due. The
+     * client never uses it to decide access.
+     */
     readonly expiresAt: number;
 }
 /** Where to come back to, and which organization to ask for, when sending someone to the IdP. */
@@ -46,22 +57,19 @@ export interface SignInOptions {
     /** Defaults to the current URL. */
     readonly returnTo?: string;
     /**
-     * Ask Keycloak for one organization's scope rather than every one the person belongs to.
-     * Omitted, a multi-tenant product should request `organization:*` — `DEFAULT_SCOPE` in
-     * `browser.ts` carries why the star is not optional.
+     * Ask Keycloak for one organization's scope in place of `organization:*`, which every sign-in
+     * otherwise requests — plain `organization` would make Keycloak prompt for a choice.
      */
     readonly organization?: string;
 }
 /**
- * What a product holds, and the only seam between the two deployment patterns.
- *
- * RFC 10017 names three architectures for browser applications and this package implements two:
- * a **Backend For Frontend**, where the token never reaches the browser and a cookie carries the
- * session, and a **browser-based OAuth client** with PKCE, for the SPA that has no server to put a
- * confidential client in. `bffAuth` and `browserAuth` are those two, and they are interchangeable
- * here — which is what lets `useSession`, `Gate` and `auth.fetch` be written once.
+ * What a product holds in the browser: the seam between the hooks and the session behind them.
  *
- * A product names its pattern on one line, at startup, and nothing downstream knows which it chose.
+ * RFC 10017 names three architectures for browser applications, and this package implements the
+ * one it recommends for business applications: a **Backend For Frontend**, where the token never
+ * reaches the browser and a cookie carries the session. `bffAuth` is that implementation. The
+ * interface stays an interface so `useSession`, `Gate` and a test double are written against what
+ * a session *does*, not against the transport underneath.
  */
 export interface Auth {
     /** The session now, or `null`. Answers from cache and renews when near expiry. */
@@ -75,10 +83,7 @@ export interface Auth {
     signOut(options?: {
         readonly returnTo?: string;
     }): Promise<void>;
-    /**
-     * A `fetch` that stays authenticated: the bearer token under one pattern, the cookie riding
-     * along by itself under the other, and a single retry after a renewal in both.
-     */
+    /** A `fetch` that stays authenticated: the cookie rides along, and one retry after a renewal. */
     readonly fetch: typeof globalThis.fetch;
 }
 /**
@@ -115,8 +120,6 @@ export type AuthErrorCode =
  * `session/unavailable`.
  */
  | "session/silent"
-/** Signed in, but holds no membership of the organization being addressed. */
- | "organization/not-a-member"
 /**
  * The organization asked for is not an alias, so it was not put into a scope.
  *
@@ -129,8 +132,22 @@ export type AuthErrorCode =
  | "callback/state-mismatch"
 /** The ID token's `nonce` is not the one that was sent — a replay. */
  | "callback/nonce-mismatch"
-/** The token endpoint refused the code or the refresh token, or returned no ID token. */
+/**
+ * The token endpoint refused the authorization code or answered with something unusable — no ID
+ * token, no access token, a client it does not recognise. A deployment fault or a replayed code.
+ */
  | "token/exchange-failed"
+/**
+ * A token was refused and the session is over: the IdP answered `invalid_grant` to the refresh
+ * token (its SSO session went idle, or was ended), or a back-channel logout token did not verify.
+ */
+ | "token/refused"
+/**
+ * The session store cannot end a session from the server: a stateless store keeps the session in
+ * the cookie, and a ticket adapter without `keys` cannot find a person's sessions. A back-channel
+ * logout answers 501 for it.
+ */
+ | "session/irrevocable"
 /** The IdP could not be reached, or answered with something that is not OAuth — a 5xx, a proxy page. */
  | "idp/unreachable"
 /** The IdP did not answer within `data.after` milliseconds. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mGAAmG;AACnG,MAAM,WAAW,QAAQ;IACvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,IAAI;IACnB,kFAAkF;IAClF,UAAU,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa;AACvB,sGAAsG;AACpG,mBAAmB;AACrB,wEAAwE;GACtE,gBAAgB;AAClB;;;GAGG;GACD,qBAAqB;AACvB;;;;GAIG;GACD,gBAAgB;AAClB,8EAA8E;GAC5E,2BAA2B;AAC7B;;;;;;GAMG;GACD,sBAAsB;AACxB,2FAA2F;GACzF,yBAAyB;AAC3B,sEAAsE;GACpE,yBAAyB;AAC3B,yFAAyF;GACvF,uBAAuB;AACzB,wGAAwG;GACtG,iBAAiB;AACnB,+DAA+D;GAC7D,YAAY,CAAC;AAEjB,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,IAAI,EAAE,aAAa;IAE5B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAJtE,SAAkB,IAAI,eAAe;gBAE1B,IAAI,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,EACN,IAAI,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EACzE,OAAO,CAAC,EAAE,YAAY;CAIzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,mGAAmG;AACnG,MAAM,WAAW,QAAQ;IACvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB,kFAAkF;IAClF,UAAU,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa;AACvB,sGAAsG;AACpG,mBAAmB;AACrB,wEAAwE;GACtE,gBAAgB;AAClB;;;GAGG;GACD,qBAAqB;AACvB;;;;GAIG;GACD,gBAAgB;AAClB;;;;;;GAMG;GACD,sBAAsB;AACxB,2FAA2F;GACzF,yBAAyB;AAC3B,sEAAsE;GACpE,yBAAyB;AAC3B;;;GAGG;GACD,uBAAuB;AACzB;;;GAGG;GACD,eAAe;AACjB;;;;GAIG;GACD,qBAAqB;AACvB,wGAAwG;GACtG,iBAAiB;AACnB,+DAA+D;GAC7D,YAAY,CAAC;AAEjB,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,IAAI,EAAE,aAAa;IAE5B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAJtE,SAAkB,IAAI,eAAe;gBAE1B,IAAI,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,EACN,IAAI,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EACzE,OAAO,CAAC,EAAE,YAAY;CAIzB"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["/**\n * What a session is, and nothing else. No React, no fetch, no Keycloak — those are `claims.ts`'s\n * problem and the doors'. A consumer reading one file to learn the model should read this one.\n */\n\n/** The person. Every field but `id` is optional because a realm decides which scopes it grants. */\nexport interface AuthUser {\n  /** The IdP's stable subject (`sub`). Never an email: an email can be reassigned. */\n  readonly id: string;\n  readonly email?: string;\n  readonly name?: string;\n  readonly username?: string;\n}\n\n/**\n * One organization the person belongs to, with the roles they hold *inside it*.\n *\n * `alias` is the addressable name — the one in a hostname and in a Keycloak scope. `id` is the\n * stable uuid, present only when the realm's organization mapper is configured to include it, and\n * is the one to store: an alias can be renamed.\n */\nexport interface Organization {\n  readonly alias: string;\n  readonly id?: string;\n  readonly roles: readonly string[];\n}\n\n/**\n * The whole of what the client knows about who is signed in.\n *\n * **There is no active organization here, and the absence is the design.** Membership is stable and\n * comes from the token; which organization you are *looking at* is a property of the request — the\n * URL — and deriving it per request is what lets two tabs sit in two organizations at once. A field\n * here would be the single shared value they would fight over.\n *\n * `roles` are the realm and client roles: global to the person. Roles held inside an organization\n * live on that `Organization`. They are kept apart on purpose, because merging them is how a role\n * granted in one organization comes to authorise something in another.\n */\nexport interface Session {\n  readonly user: AuthUser;\n  readonly roles: readonly string[];\n  readonly organizations: readonly Organization[];\n  /** Epoch milliseconds. The client uses it to refresh early, never to decide access. */\n  readonly expiresAt: number;\n}\n\n/** Where to come back to, and which organization to ask for, when sending someone to the IdP. */\nexport interface SignInOptions {\n  /** Defaults to the current URL. */\n  readonly returnTo?: string;\n  /**\n   * Ask Keycloak for one organization's scope rather than every one the person belongs to.\n   * Omitted, a multi-tenant product should request `organization:*` — `DEFAULT_SCOPE` in\n   * `browser.ts` carries why the star is not optional.\n   */\n  readonly organization?: string;\n}\n\n/**\n * What a product holds, and the only seam between the two deployment patterns.\n *\n * RFC 10017 names three architectures for browser applications and this package implements two:\n * a **Backend For Frontend**, where the token never reaches the browser and a cookie carries the\n * session, and a **browser-based OAuth client** with PKCE, for the SPA that has no server to put a\n * confidential client in. `bffAuth` and `browserAuth` are those two, and they are interchangeable\n * here — which is what lets `useSession`, `Gate` and `auth.fetch` be written once.\n *\n * A product names its pattern on one line, at startup, and nothing downstream knows which it chose.\n */\nexport interface Auth {\n  /** The session now, or `null`. Answers from cache and renews when near expiry. */\n  getSession(): Promise<Session | null>;\n  /**\n   * Call `onChange` when the session does — signed in, signed out, renewed, or changed in another\n   * tab. Returns the unsubscribe.\n   */\n  subscribe(onChange: () => void): () => void;\n  signIn(options?: SignInOptions): Promise<void>;\n  signOut(options?: { readonly returnTo?: string }): Promise<void>;\n  /**\n   * A `fetch` that stays authenticated: the bearer token under one pattern, the cookie riding\n   * along by itself under the other, and a single retry after a renewal in both.\n   */\n  readonly fetch: typeof globalThis.fetch;\n}\n\n/**\n * Why a credential was refused, or who did not answer when one was asked for, as a code a product\n * can route on.\n *\n * A boolean cannot be acted upon: \"not signed in\" sends the person to the IdP, \"signed in but not a\n * member\" sends them to a page that says so, and \"the IdP did not answer\" sends them nowhere — it is\n * an outage to name, and sending them to sign in is the loop that hides it. The codes are\n * `area/kind`, the grammar one host registry keys fossil's codes, the rest of kanzo-ui's and its own\n * server's in.\n *\n * **A programming or deployment fault is not one**: `useSession` called outside its provider, or a\n * session too large for a cookie, both throw a plain `Error` on purpose. Giving those codes would\n * invite a product to `catch` them beside a refusal and route them to a sign-in page, which is the\n * wrong answer to \"you wired this up wrong\".\n *\n * *What would reverse it:* a product needing to route on one of those programmatically rather than\n * read it in a stack trace. None has; both are faults you fix once, not conditions you handle.\n */\nexport type AuthErrorCode =\n  /** The claims carry no `sub`. Not a session at all — a configuration or IdP fault, never a user's. */\n  | \"claims/no-subject\"\n  /** There is no session. The person has not signed in, or it expired. */\n  | \"session/absent\"\n  /**\n   * The session could not be read: the session store failed, or the BFF's session endpoint answered\n   * something other than a session or a 401. `data.status` is that answer's status.\n   */\n  | \"session/unavailable\"\n  /**\n   * The session did not answer within `data.after` milliseconds: in the browser, the BFF's session\n   * endpoint; on the server, a `ticketStore`'s adapter — reported there as the cause of a\n   * `session/unavailable`.\n   */\n  | \"session/silent\"\n  /** Signed in, but holds no membership of the organization being addressed. */\n  | \"organization/not-a-member\"\n  /**\n   * The organization asked for is not an alias, so it was not put into a scope.\n   *\n   * The value reaches `begin` from a query parameter on every product with an organization\n   * switcher: a space in it is scope injection, and a product wants to answer \"no such\n   * organization\" rather than let an unreadable 400 arrive at someone who typed a link wrong.\n   */\n  | \"organization/invalid\"\n  /** The callback's `state` is absent, different, or has no transaction to match against. */\n  | \"callback/state-mismatch\"\n  /** The ID token's `nonce` is not the one that was sent — a replay. */\n  | \"callback/nonce-mismatch\"\n  /** The token endpoint refused the code or the refresh token, or returned no ID token. */\n  | \"token/exchange-failed\"\n  /** The IdP could not be reached, or answered with something that is not OAuth — a 5xx, a proxy page. */\n  | \"idp/unreachable\"\n  /** The IdP did not answer within `data.after` milliseconds. */\n  | \"idp/silent\";\n\nexport class AuthError extends Error {\n  override readonly name = \"AuthError\";\n  constructor(\n    readonly code: AuthErrorCode,\n    message: string,\n    readonly data: { readonly after?: number; readonly status?: number } = {},\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n  }\n}\n"],"names":["AuthError","code","message","data","options","__publicField"],"mappings":";;;AA8IO,MAAMA,UAAkB,MAAM;AAAA,EAEnC,YACWC,GACTC,GACSC,IAA8D,CAAA,GACvEC,GACA;AACA,UAAMF,GAASE,CAAO;AAPN,IAAAC,EAAA,cAAO;AAEd,SAAA,OAAAJ,GAEA,KAAA,OAAAE;AAAA,EAIX;AACF;"}
+{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["/**\n * What a session is, and nothing else. No React, no fetch, no Keycloak — those are `claims.ts`'s\n * problem and the doors'. A consumer reading one file to learn the model should read this one.\n */\n\n/** The person. Every field but `id` is optional because a realm decides which scopes it grants. */\nexport interface AuthUser {\n  /** The IdP's stable subject (`sub`). Never an email: an email can be reassigned. */\n  readonly id: string;\n  readonly email?: string;\n  readonly name?: string;\n  readonly username?: string;\n}\n\n/**\n * One organization the person belongs to, with the roles they hold *inside it*.\n *\n * `alias` is the addressable name — the one in a hostname and in a Keycloak scope. `id` is the\n * stable uuid, present only when the realm's organization mapper is configured to include it, and\n * is the one to store: an alias can be renamed.\n */\nexport interface Organization {\n  readonly alias: string;\n  readonly id?: string;\n  readonly roles: readonly string[];\n}\n\n/**\n * The whole of what the client knows about who is signed in.\n *\n * **Membership and the current organization are two different things, and only the first is\n * stored.** Membership is stable and comes from the token. Which organization a request is *in* is\n * a property of that request — its host, its path, a cookie — so `organization` is resolved per\n * request by the product's resolver and never written into the session record. That is what lets\n * two tabs sit in two organizations at once: there is no shared value for them to fight over.\n *\n * `roles` are the realm and client roles: global to the person. Roles held inside an organization\n * live on that `Organization`. They are kept apart on purpose, because merging them is how a role\n * granted in one organization comes to authorise something in another.\n */\nexport interface Session {\n  readonly user: AuthUser;\n  readonly roles: readonly string[];\n  readonly organizations: readonly Organization[];\n  /**\n   * The alias of the organization this request addresses, as the product's resolver answered it.\n   *\n   * An address, not a proof of membership: `can` answers `false` for an organization the person\n   * does not belong to, which is how a product tells \"not a member here\" from \"no tenant\".\n   */\n  readonly organization?: string;\n  /**\n   * Epoch milliseconds: when the access token expires, which is when the next renewal is due. The\n   * client never uses it to decide access.\n   */\n  readonly expiresAt: number;\n}\n\n/** Where to come back to, and which organization to ask for, when sending someone to the IdP. */\nexport interface SignInOptions {\n  /** Defaults to the current URL. */\n  readonly returnTo?: string;\n  /**\n   * Ask Keycloak for one organization's scope in place of `organization:*`, which every sign-in\n   * otherwise requests — plain `organization` would make Keycloak prompt for a choice.\n   */\n  readonly organization?: string;\n}\n\n/**\n * What a product holds in the browser: the seam between the hooks and the session behind them.\n *\n * RFC 10017 names three architectures for browser applications, and this package implements the\n * one it recommends for business applications: a **Backend For Frontend**, where the token never\n * reaches the browser and a cookie carries the session. `bffAuth` is that implementation. The\n * interface stays an interface so `useSession`, `Gate` and a test double are written against what\n * a session *does*, not against the transport underneath.\n */\nexport interface Auth {\n  /** The session now, or `null`. Answers from cache and renews when near expiry. */\n  getSession(): Promise<Session | null>;\n  /**\n   * Call `onChange` when the session does — signed in, signed out, renewed, or changed in another\n   * tab. Returns the unsubscribe.\n   */\n  subscribe(onChange: () => void): () => void;\n  signIn(options?: SignInOptions): Promise<void>;\n  signOut(options?: { readonly returnTo?: string }): Promise<void>;\n  /** A `fetch` that stays authenticated: the cookie rides along, and one retry after a renewal. */\n  readonly fetch: typeof globalThis.fetch;\n}\n\n/**\n * Why a credential was refused, or who did not answer when one was asked for, as a code a product\n * can route on.\n *\n * A boolean cannot be acted upon: \"not signed in\" sends the person to the IdP, \"signed in but not a\n * member\" sends them to a page that says so, and \"the IdP did not answer\" sends them nowhere — it is\n * an outage to name, and sending them to sign in is the loop that hides it. The codes are\n * `area/kind`, the grammar one host registry keys fossil's codes, the rest of kanzo-ui's and its own\n * server's in.\n *\n * **A programming or deployment fault is not one**: `useSession` called outside its provider, or a\n * session too large for a cookie, both throw a plain `Error` on purpose. Giving those codes would\n * invite a product to `catch` them beside a refusal and route them to a sign-in page, which is the\n * wrong answer to \"you wired this up wrong\".\n *\n * *What would reverse it:* a product needing to route on one of those programmatically rather than\n * read it in a stack trace. None has; both are faults you fix once, not conditions you handle.\n */\nexport type AuthErrorCode =\n  /** The claims carry no `sub`. Not a session at all — a configuration or IdP fault, never a user's. */\n  | \"claims/no-subject\"\n  /** There is no session. The person has not signed in, or it expired. */\n  | \"session/absent\"\n  /**\n   * The session could not be read: the session store failed, or the BFF's session endpoint answered\n   * something other than a session or a 401. `data.status` is that answer's status.\n   */\n  | \"session/unavailable\"\n  /**\n   * The session did not answer within `data.after` milliseconds: in the browser, the BFF's session\n   * endpoint; on the server, a `ticketStore`'s adapter — reported there as the cause of a\n   * `session/unavailable`.\n   */\n  | \"session/silent\"\n  /**\n   * The organization asked for is not an alias, so it was not put into a scope.\n   *\n   * The value reaches `begin` from a query parameter on every product with an organization\n   * switcher: a space in it is scope injection, and a product wants to answer \"no such\n   * organization\" rather than let an unreadable 400 arrive at someone who typed a link wrong.\n   */\n  | \"organization/invalid\"\n  /** The callback's `state` is absent, different, or has no transaction to match against. */\n  | \"callback/state-mismatch\"\n  /** The ID token's `nonce` is not the one that was sent — a replay. */\n  | \"callback/nonce-mismatch\"\n  /**\n   * The token endpoint refused the authorization code or answered with something unusable — no ID\n   * token, no access token, a client it does not recognise. A deployment fault or a replayed code.\n   */\n  | \"token/exchange-failed\"\n  /**\n   * A token was refused and the session is over: the IdP answered `invalid_grant` to the refresh\n   * token (its SSO session went idle, or was ended), or a back-channel logout token did not verify.\n   */\n  | \"token/refused\"\n  /**\n   * The session store cannot end a session from the server: a stateless store keeps the session in\n   * the cookie, and a ticket adapter without `keys` cannot find a person's sessions. A back-channel\n   * logout answers 501 for it.\n   */\n  | \"session/irrevocable\"\n  /** The IdP could not be reached, or answered with something that is not OAuth — a 5xx, a proxy page. */\n  | \"idp/unreachable\"\n  /** The IdP did not answer within `data.after` milliseconds. */\n  | \"idp/silent\";\n\nexport class AuthError extends Error {\n  override readonly name = \"AuthError\";\n  constructor(\n    readonly code: AuthErrorCode,\n    message: string,\n    readonly data: { readonly after?: number; readonly status?: number } = {},\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n  }\n}\n"],"names":["AuthError","code","message","data","options","__publicField"],"mappings":";;;AA+JO,MAAMA,UAAkB,MAAM;AAAA,EAEnC,YACWC,GACTC,GACSC,IAA8D,CAAA,GACvEC,GACA;AACA,UAAMF,GAASE,CAAO;AAPN,IAAAC,EAAA,cAAO;AAEd,SAAA,OAAAJ,GAEA,KAAA,OAAAE;AAAA,EAIX;AACF;"}

package/dist/use-session.d.ts

@@ -1,14 +1,19 @@
 import { AuthContextValue } from './auth-context';
 /**
- * Who is signed in, and the two things you can do about it.
+ * Who is signed in, the two things you can do about it, and the role question asked here.
  *
  * `status` is the field to branch on, not `session === null`: those are the same answer for
  * "anonymous" and "we have not looked yet", and drawing a sign-in prompt during the second is the
  * flicker every application with a session has shipped at least once. `"failed"` is the session
  * that could not be read, with what was thrown on `error`.
+ *
+ * `can(role, organization?)` is {@link can} bound to this session, so it asks inside the current
+ * tenant unless told which — Clerk's `useAuth().has()`. It decides what to draw, never what to
+ * allow.
  */
 export declare function useSession(): AuthContextValue & {
     readonly signIn: AuthContextValue["auth"]["signIn"];
     readonly signOut: AuthContextValue["auth"]["signOut"];
+    readonly can: (role: string, organization?: string) => boolean;
 };
 //# sourceMappingURL=use-session.d.ts.map

package/dist/use-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-session.d.ts","sourceRoot":"","sources":["../src/use-session.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,GAAG;IAC/C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;CACvD,CAcA"}
+{"version":3,"file":"use-session.d.ts","sourceRoot":"","sources":["../src/use-session.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,GAAG;IAC/C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CAChE,CAeA"}

package/dist/use-session.js

@@ -1,19 +1,21 @@
 "use client";
-import { useContext as e } from "react";
-import { AuthContext as n } from "./auth-context.js";
-function s() {
-  const t = e(n);
+import { useContext as s } from "react";
+import { AuthContext as e } from "./auth-context.js";
+import { can as r } from "./can.js";
+function h() {
+  const t = s(e);
   if (t === null)
     throw new Error(
-      "useSession() was called outside <AuthProvider>. Wrap the application in one, passing the auth it should use — browserAuth() for a SPA, bffAuth() where there is a server."
+      "useSession() was called outside <AuthProvider>. Wrap the application in one, passing the auth it should use — bffAuth() for a product whose server runs kanzoAuth."
     );
   return {
     ...t,
     signIn: t.auth.signIn,
-    signOut: t.auth.signOut
+    signOut: t.auth.signOut,
+    can: (n, o) => r(t.session, n, o)
   };
 }
 export {
-  s as useSession
+  h as useSession
 };
 //# sourceMappingURL=use-session.js.map