@stwrd/workers 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+The format is based on Keep a Changelog 1.1.0, and this package adheres to Semantic Versioning (SemVer).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Added
+
+- `stwrdFor(env, options)` and `StwrdWorkers`: the `/auth/*` routes as a `Request` to `Response` handler for Cloudflare Workers.
+- Guards: `requireAuth`, `requireRole`, `requirePermission`, `requireOrg`, `protect` and `resolve`.
+- `StwrdSessionObject`, a SQLite-backed Durable Object that keeps one session and its refresh lease, and `DurableObjectSessionStore`, which seals sessions as JWE with `STWRD_SESSION_KEYS`.
+- Key rotation for `STWRD_SESSION_KEYS`.
+- Optional `ctx` support: session renewals run under `ctx.waitUntil` so they finish after the request ends.
+- Back-channel logout and webhook routes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stwrd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# @stwrd/workers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+stwrd SDK for Cloudflare Workers (backend-for-frontend profile): the `/auth/*` routes as a `Request` to `Response` handler, guards for your own routes, and a Durable Object that keeps each session on the server.
+
+## What it is
+
+[stwrd](https://stwrd.dev) is a multi-tenant identity provider. In the backend-for-frontend (BFF) profile the server performs the OpenID Connect flow and keeps the tokens; the browser only holds a signed cookie. This package runs that profile inside a Worker. It exposes the same routes, the same `GET /auth/session` JSON and the same `STWRD_*` variables as [`@stwrd/node`](https://www.npmjs.com/package/@stwrd/node) and the Python SDK (`stwrd-auth` on PyPI), so a front end such as [`@stwrd/react`](https://www.npmjs.com/package/@stwrd/react) works unchanged. A person's `user.id` is the `sub` claim of the identity provider: global and stable.
+
+## Installation
+
+```sh
+npm install @stwrd/workers
+```
+
+[`@stwrd/core`](https://www.npmjs.com/package/@stwrd/core) is a dependency, pinned to the exact version that ships with this release. Requirements:
+
+- Node.js 20 or newer for the tooling (`wrangler`).
+- The `nodejs_compat` compatibility flag with a `compatibility_date` of 2024-09-23 or later (any date from 2026-08-04 on enables the flag by itself). Without the flag the Worker does not start, because `node:crypto` cannot be imported. With the flag but an earlier date, `stwrdFor` throws a `ConfigError` because the `Buffer` global is missing.
+- A Durable Object binding named `STWRD_SESSIONS` (below).
+
+The package is ESM only and ships its own TypeScript declarations.
+
+## Minimal example
+
+`wrangler.jsonc`: the flag, the binding of the session object and the migration that creates it as a SQLite-backed class.
+
+```jsonc
+// What an app's wrangler config needs for `@stwrd/workers`: the
+// `nodejs_compat` flag, the Durable Object binding named STWRD_SESSIONS, and
+// the migration that creates the class as SQLite-backed. (Secrets are not
+// here: `wrangler secret put STWRD_COOKIE_SECRET`, ...)
+{
+  "name": "my-worker",
+  "main": "./index.ts",
+  "compatibility_date": "2026-08-22",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": { "bindings": [{ "name": "STWRD_SESSIONS", "class_name": "StwrdSessionObject" }] },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["StwrdSessionObject"] }]
+}
+```
+
+`index.ts`:
+
+```ts
+import { StwrdSessionObject, stwrdFor } from "@stwrd/workers";
+
+// The Durable Object class that wrangler.jsonc binds as STWRD_SESSIONS.
+export { StwrdSessionObject };
+
+export default {
+  async fetch(request: Request, env: object, ctx: ExecutionContext): Promise<Response> {
+    const stwrd = stwrdFor(env);
+
+    // /auth/sign-in, /auth/callback, /auth/sign-out, /auth/session, ...
+    const auth = await stwrd.handle(request, ctx);
+    if (auth) return auth;
+
+    // Your own routes: the person, or the response that stops the request.
+    const guard = await stwrd.requireAuth(request, { ctx });
+    if (!guard.ok) return guard.response;
+    return Response.json({ user: guard.context.user?.id });
+  },
+};
+```
+
+Three details of the configuration matter:
+
+- The binding must be named `STWRD_SESSIONS` and point to the class `StwrdSessionObject`, which your Worker has to export.
+- The migration creates that class with SQLite storage; without it Cloudflare rejects the deploy. Keep the tag `v1`; a future migration gets a new tag.
+- Register `{STWRD_BASE_URL}/auth/callback` as a redirect URI of the application in stwrd.
+
+Run `wrangler dev` to try it locally, and `wrangler deploy --dry-run` to check that the Worker bundles and the binding is in place (it needs no Cloudflare account).
+
+## Configuration
+
+Public values go in `wrangler.jsonc` under `vars` or in the dashboard. Everything secret is set with `wrangler secret put` and never in `vars`: a value in `vars` is in your repository and in the dashboard in the clear.
+
+```sh
+wrangler secret put STWRD_CLIENT_SECRET
+wrangler secret put STWRD_COOKIE_SECRET
+wrangler secret put STWRD_SESSION_KEYS
+```
+
+| Variable | Required | Secret | Description |
+|---|---|---|---|
+| `STWRD_ISSUER` | yes | no | Issuer URL of the tenant. |
+| `STWRD_CLIENT_ID` | yes | no | OIDC client ID of the application. |
+| `STWRD_BASE_URL` | yes | no | Public URL of the Worker, without a trailing slash. |
+| `STWRD_CLIENT_SECRET` | yes | yes | Client secret of the application. |
+| `STWRD_COOKIE_SECRET` | yes | yes | HMAC key of the session cookie, at least 32 random characters. |
+| `STWRD_SESSION_KEYS` | yes | yes | Keys that seal the stored sessions: `id:key` entries separated by commas, each key 32 bytes in base64url. The first entry encrypts; all of them decrypt. |
+| `STWRD_WEBHOOK_SECRET` | no | yes | Without it `/auth/webhook` answers 503. |
+| `STWRD_SCOPE`, `STWRD_PREFIX`, `STWRD_SESSION_TTL_S`, `STWRD_COOKIE_SECURE`, `STWRD_POST_LOGIN_REDIRECT`, `STWRD_POST_LOGOUT_REDIRECT` | no | no | Optional; defaults and meaning as in [`@stwrd/core`](https://www.npmjs.com/package/@stwrd/core). Add `org` to the scope to enable organizations. |
+
+Create the first session key with:
+
+```sh
+node -e "console.log('k1:' + require('crypto').randomBytes(32).toString('base64url'))"
+```
+
+Whoever can read `STWRD_SESSION_KEYS` can read every session; treat it like a password. If any variable is missing or malformed, `stwrdFor` throws a `ConfigError`, so the Worker does not start half configured.
+
+### Rotating keys
+
+- Session keys rotate without signing anyone out. Generate a new key (`k2:...`) and put it first: `STWRD_SESSION_KEYS="k2:<new>,k1:<old>"`. Deploy. After `STWRD_SESSION_TTL_S` seconds (8 hours by default) every session sealed with the old key has expired or has been renewed under the new one; then remove `k1` and deploy again. Removing it earlier makes the people still under `k1` sign in again.
+- The cookie secret does not rotate: there is no window for the previous secret, and changing `STWRD_COOKIE_SECRET` signs everybody out.
+- Changing `STWRD_ISSUER` or `STWRD_CLIENT_ID` makes the stored sessions unreadable (everybody signs in again), by design: two apps that share a binding never read each other's sessions.
+
+### Options and hooks
+
+`stwrdFor(env, options?)` builds the instance on the first call for an `env` and returns the same instance afterwards. `options` overrides the environment and can add `onUserRegistered(user)` (runs on every successful sign-in), `onEvent(event)` (runs for each accepted webhook delivery), `fetch`, `sessions` and `backChannel`. A later call that changes a value option (`issuer`, `clientId`, `scope`, ...) throws a `ConfigError`, because it would be ignored. Functions are not compared: those of the first call stay and later ones are ignored without error, so passing a hook inline in `fetch(request, env, ctx)` works on every request:
+
+```ts
+const stwrd = stwrdFor(env, {
+  onUserRegistered: async (user) => {
+    console.log("new person", user.id);
+  },
+});
+```
+
+## API reference
+
+### `StwrdWorkers`
+
+| Member | Description |
+|---|---|
+| `handle(request, ctx?)` | Serves the `/auth/*` routes. Returns `null` for any other path or method, so the rest of your Worker runs as usual. |
+| `requireAuth(request, options?)` | Guard: signed in. |
+| `requireRole(request, role, options?)` | Guard: the role (organization roles when the session has an organization). |
+| `requirePermission(request, permission, options?)` | Guard: the permission. |
+| `requireOrg(request, options?)` | Guard: the session has an organization. Needs the `org` scope (`ConfigError` otherwise). |
+| `protect(request, { public?, api?, ctx? })` | Fail-closed: `null` lets the request through, a `Response` stops it. Everything needs a session except the listed paths (exact, or a prefix ending in `*`) and everything under the auth prefix. |
+| `resolve(request, ctx?)` | The session context for a route that works with or without a person. Check `idpUnavailable` before rendering a "signed out" state. |
+
+Each guard answers `{ ok: true, context }`, with `context.user`, `context.organization`, `context.consents` and `context.session`, or `{ ok: false, response }` with the response that stops the request. In order: identity provider or session store silent gives 503; no person gives a 303 to sign-in for a browser navigation or a 401 JSON (always 401 with `{ api: true }`); a failed rule gives 403. The session is read once per request.
+
+### Other exports
+
+`StwrdSessionObject` (the Durable Object), `DurableObjectSessionStore`, `SESSIONS_BINDING`, `parseSessionKeys`, `Keyring`, `MemoryStore` (tests only), `safeTarget`, `sessionContext`, `sessionResponse`, `hasRole`, `hasPermission`, the errors `ConfigError`, `OidcError`, `IdpUnavailable` and `RefreshUncertain`, and the session types.
+
+### Passing `ctx`
+
+Pass the Worker's `ctx` (`handle(request, ctx)`, `resolve(request, ctx)`, or `{ ctx }` in the options of a guard and of `protect`). It is optional, but without it a person who closes the tab while their session is being renewed can leave that session `uncertain` (see below); with it the renewal runs under `ctx.waitUntil` and finishes anyway. The first call that reads the session in a request is the one whose `ctx` counts. A `ctx` without a `waitUntil` function (typically `env` passed where `ctx` goes) is a `ConfigError`, thrown before the session is read.
+
+## How it differs from the Node SDK
+
+- Sessions live in Durable Objects: one object per session, named after the namespace (`issuer|clientId`) and the local session id. The Worker seals the session (JWE) with `STWRD_SESSION_KEYS`; the object keeps only the envelope and the refresh lease, and never sees a key or a token. The object deletes itself when the session expires.
+- A network failure while renewing makes the session `uncertain`. The runtime does not tell "could not connect" from "cut after sending", so a refresh that may have been processed is never repeated. That session answers 503 until the person signs in again. Only an explicit "not now" from the identity provider (503, 408, 425, 429) releases it. Before a renewal the SDK asks the identity provider for its discovery document (5-second timeout), so a provider that is down costs a retry and not a session.
+- Changing organization takes two steps (retire the old session, install the new one). If the Worker stops between them the person signs in again; there are never two live sessions.
+- Back-channel logout deletes the session in its object and then marks the notice, in that order; if the object does not answer the route answers 503 and the identity provider retries.
+
+## Security
+
+- Tokens never reach the browser: the cookie is HMAC-signed (tamper-evident) and carries only a session identifier. Sessions at rest in the Durable Object are encrypted (JWE `dir` + `A256GCM`) and authenticated against their namespace and id, so a copied envelope is rejected.
+- Secrets (`STWRD_CLIENT_SECRET`, `STWRD_COOKIE_SECRET`, `STWRD_SESSION_KEYS`, `STWRD_WEBHOOK_SECRET`) belong in `wrangler secret put`. Error messages name the variable or the position of an entry, never a key.
+- Sign-out and the organization switch require a CSRF token; redirect targets are confined to relative paths of the app; requests to the identity provider never follow redirects; the redirect URI is built from `STWRD_BASE_URL`, never from the `Host` header. The protocol details are those of `@stwrd/core`.
+- Supported versions and how to report a vulnerability are described in the [security policy](https://github.com/stwrd-dev/sdk-js/security/policy).
+
+## Error handling and troubleshooting
+
+A 503 from `/auth/session` or from a guard means "could not find out", never "signed out". The person keeps their session; show "try again" and not the sign-in page.
+
+| Symptom | Cause | What to do |
+|---|---|---|
+| 503 that goes away by itself | The identity provider or a Durable Object did not answer. | Nothing; the next request tries again. |
+| 503 that stays for one person | The session is `uncertain`: a renewal was cut off after it may have been sent. | The person signs in again; `/auth/sign-in` treats that session as gone. A "Sign in again" button on your 503 page is enough. Pass `ctx` everywhere to make this rare. |
+| Many people `uncertain` at once | The identity provider was down during renewals. | Check the Worker logs for 503 answers. |
+| `ConfigError` at start | A variable is missing or malformed, the binding is missing, or the compatibility flag or date is wrong. | The message names the cause. |
+| The Worker does not start | `nodejs_compat` is missing. | Add the flag and a recent `compatibility_date`. |
+| Everybody signed out after a deploy | `STWRD_COOKIE_SECRET`, `STWRD_ISSUER` or `STWRD_CLIENT_ID` changed. | Expected; see "Rotating keys". |
+
+## Compatibility
+
+- Cloudflare Workers with `nodejs_compat`; Durable Objects with SQLite storage.
+- Node.js 20 or newer for `wrangler` and the build.
+- ESM only; TypeScript declarations included (use `@cloudflare/workers-types` for `ExecutionContext`).
+- The test suite runs on workerd, the Workers runtime, and the example above bundles with `wrangler deploy --dry-run`. Behavior on Cloudflare's network itself is not covered by the tests.
+
+## Versioning
+
+This package follows Semantic Versioning (SemVer). While the version is below 1.0, minor releases may contain breaking changes. `@stwrd/core` is pinned to an exact version, so the two always move together. Changes are listed in `CHANGELOG.md`.
+
+## License
+
+MIT © 2026 stwrd. See `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@stwrd/workers` — the Cloudflare Workers SDK (BFF profile): the `/auth/*`
+ * routes as a `Request → Response` handler, access guards for the app's own
+ * routes, and a Durable Object that keeps each session. Same contract as
+ * `@stwrd/node`: this module's exports are the public surface.
+ */
+export declare const VERSION = "0.1.1";
+export { SESSIONS_BINDING, StwrdWorkers, stwrdFor } from "./stwrd.js";
+export type { GuardOptions, ProtectOptions, WorkersOptions } from "./stwrd.js";
+export { StwrdSessionObject } from "./sessionObject.js";
+export type { ObjectClaim } from "./sessionObject.js";
+export { DurableObjectSessionStore, SESSION_OBJECT_PREFIX, UNNAMED_NOTICE_OBJECT } from "./store.js";
+export type { DurableObjectSessionStoreOptions, SessionObjects } from "./store.js";
+export { SESSION_KEYS_ENV, parseSessionKeys } from "./sessionKeys.js";
+export { ConfigError } from "@stwrd/core/config";
+export { Keyring } from "@stwrd/core/keyring";
+export { IdpUnavailable, OidcError, RefreshUncertain } from "@stwrd/core/oidc";
+export { MemoryStore, contextFromClaims, hasPermission, hasRole, sessionContext, sessionResponse, userFromClaims, } from "@stwrd/core/sessions";
+export { safeTarget } from "@stwrd/core/web/access";
+export type { BackChannelSink } from "@stwrd/core/backchannel";
+export type { FetchLike } from "@stwrd/core/oidc";
+export type { Claims, ConsentState, RefreshClaim, SessionContext, SessionResponse, SessionStore, StwrdOrganization, StwrdSession, StwrdUser, Tokens, } from "@stwrd/core/sessions";
+export type { AccessContext, AccessResult, AccessRule, Resolution } from "@stwrd/core/web/access";
+export type { WebhookEvent } from "@stwrd/core/webhooks";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@stwrd/workers` — the Cloudflare Workers SDK (BFF profile): the `/auth/*`
+ * routes as a `Request → Response` handler, access guards for the app's own
+ * routes, and a Durable Object that keeps each session. Same contract as
+ * `@stwrd/node`: this module's exports are the public surface.
+ */
+export const VERSION = "0.1.1";
+// --- the adapter -------------------------------------------------------------
+export { SESSIONS_BINDING, StwrdWorkers, stwrdFor } from "./stwrd.js";
+// --- sessions: the Durable Object an app exports and binds as `STWRD_SESSIONS` ---
+export { StwrdSessionObject } from "./sessionObject.js";
+export { DurableObjectSessionStore, SESSION_OBJECT_PREFIX, UNNAMED_NOTICE_OBJECT } from "./store.js";
+export { SESSION_KEYS_ENV, parseSessionKeys } from "./sessionKeys.js";
+// --- what an app reads and catches, from the shared core ---------------------
+export { ConfigError } from "@stwrd/core/config";
+export { Keyring } from "@stwrd/core/keyring";
+export { IdpUnavailable, OidcError, RefreshUncertain } from "@stwrd/core/oidc";
+export { MemoryStore, contextFromClaims, hasPermission, hasRole, sessionContext, sessionResponse, userFromClaims, } from "@stwrd/core/sessions";
+export { safeTarget } from "@stwrd/core/web/access";

package/dist/sessionKeys.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `STWRD_SESSION_KEYS` — the keys that seal sessions before they go to a
+ * Durable Object. Only the Workers adapter has it (`@stwrd/node` keeps its
+ * keyring in code, next to its PostgreSQL pool).
+ *
+ * Format: `id:key` entries separated by commas, each key 32 bytes in base64url
+ * (no padding). The FIRST entry encrypts; every entry decrypts, so a key is
+ * rotated by putting the new one first and dropping the old one once no
+ * session is sealed with it. Empty, a repeated id, a malformed entry or a key
+ * of another length: the configuration is not built (a Worker that cannot seal
+ * must not start). Errors name the entry's position, never its key.
+ */
+import { Keyring } from "@stwrd/core/keyring";
+export declare const SESSION_KEYS_ENV = "STWRD_SESSION_KEYS";
+export declare function parseSessionKeys(raw: unknown): Keyring;

package/dist/sessionKeys.js

@@ -0,0 +1,42 @@
+/**
+ * `STWRD_SESSION_KEYS` — the keys that seal sessions before they go to a
+ * Durable Object. Only the Workers adapter has it (`@stwrd/node` keeps its
+ * keyring in code, next to its PostgreSQL pool).
+ *
+ * Format: `id:key` entries separated by commas, each key 32 bytes in base64url
+ * (no padding). The FIRST entry encrypts; every entry decrypts, so a key is
+ * rotated by putting the new one first and dropping the old one once no
+ * session is sealed with it. Empty, a repeated id, a malformed entry or a key
+ * of another length: the configuration is not built (a Worker that cannot seal
+ * must not start). Errors name the entry's position, never its key.
+ */
+import { ConfigError } from "@stwrd/core/config";
+import { Keyring } from "@stwrd/core/keyring";
+export const SESSION_KEYS_ENV = "STWRD_SESSION_KEYS";
+const KEY_ID = /^[A-Za-z0-9._-]{1,64}$/;
+export function parseSessionKeys(raw) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        throw new ConfigError(`${SESSION_KEYS_ENV} is required: id:key entries (32-byte base64url keys) separated by commas.`);
+    }
+    const entries = [];
+    raw.split(",").forEach((part, index) => {
+        const position = `${SESSION_KEYS_ENV} entry ${index + 1}`;
+        const colon = part.indexOf(":");
+        const id = part.slice(0, colon).trim();
+        const encoded = part.slice(colon + 1).trim();
+        if (colon === -1 || !KEY_ID.test(id)) {
+            throw new ConfigError(`${position} must be id:key, with an id of letters, digits, dot, underscore or hyphen (at most 64).`);
+        }
+        if (entries.some(([seen]) => seen === id)) {
+            throw new ConfigError(`${position} repeats the key id "${id}".`);
+        }
+        const key = Buffer.from(encoded, "base64url");
+        // `Buffer` skips what is not base64url and accepts padding: the round trip is the strict check.
+        if (key.toString("base64url") !== encoded || key.length !== 32) {
+            throw new ConfigError(`${position} must be a 32-byte key in base64url (43 characters, no padding).`);
+        }
+        entries.push([id, new Uint8Array(key)]);
+    });
+    // `fromEntries` defines own properties: an id such as `__proto__` stays a key.
+    return new Keyring(Object.fromEntries(entries), entries[0][0]);
+}

package/dist/sessionObject.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `StwrdSessionObject` — the Durable Object that keeps ONE session (the object
+ * is named after the namespace and the local session id) and runs its refresh lease.
+ *
+ * It never sees a session in the clear: the Worker seals the session (JWE, see
+ * `store.ts`) and the object stores the envelope next to the lease columns,
+ * which hold no secret. The lease is the same state machine as the PostgreSQL
+ * and in-memory stores of `@stwrd/node` (`SessionStore` in `@stwrd/core/sessions`
+ * is the contract): `claim` grants the one refresh of a session, and every later
+ * step is a compare-and-set on the fence it handed out.
+ *
+ * **Every method is synchronous.** Awaiting a timer or a `fetch` inside a
+ * method can let another call in between, so the invariants cannot depend on a method being atomic
+ * across an `await`; with no `await` a method runs to the end before any other
+ * call is delivered, and the multi-statement ones are one `transactionSync`.
+ * Only `alarm` is async, at its very end. The lease clock is this object's.
+ *
+ * The object deletes itself: an alarm at the session's expiry removes the
+ * envelope (and with it the stored refresh token) and, when nothing is left,
+ * the whole storage. Storage is only ever created by a write (`set`, `logout`):
+ * reads and lease calls on an object with nothing in it make nothing.
+ */
+import { DurableObject } from "cloudflare:workers";
+/** What `claim` answers: `RefreshClaim` of the core, with the sealed envelope
+ * in place of the session. */
+export type ObjectClaim = {
+    status: "granted";
+    payload: string;
+    fence: number;
+    phase: "acquired" | "hydrating";
+    freshIdToken: boolean;
+} | {
+    status: "busy" | "uncertain" | "gone";
+};
+export declare class StwrdSessionObject extends DurableObject {
+    private ready;
+    /** Whether the storage exists. Only a write creates it (`ensureSchema`), so
+     * a read of an object nobody ever signed in under, or of one whose alarm
+     * emptied it, finds nothing and makes nothing. */
+    private hasSchema;
+    private ensureSchema;
+    private rows;
+    private nowS;
+    /** Strictly increasing, survives `delete`, and anchored to the clock so it
+     * still exceeds every earlier fence after the storage was emptied. */
+    private nextFence;
+    /** The alarm goes off at the earliest thing this object has to forget. */
+    private scheduleAlarm;
+    /** The sealed envelope, or `null`. Expiry is the caller's judgement (the
+     * alarm removes the row some time after it). */
+    get(): string | null;
+    /** Installs a session, clearing any lease and taking a new fence: a stale
+     * owner of an earlier session under this id can no longer write. */
+    set(payload: string, expiresAt: number): void;
+    delete(): void;
+    /** Deletes the session only if it is there; says whether it was. The first
+     * step of an organization switch between two objects. */
+    retire(): boolean;
+    /** Same decision table as the other stores: `gone` with no session; `uncertain`
+     * for good once a sent request has no result; `busy` while another owner's
+     * lease is live; an expired lease in `sent` becomes `uncertain`; otherwise
+     * the caller is granted the lease (`hydrating` is resumed, anything else
+     * starts at `acquired`). */
+    claim(owner: string, leaseS: number): ObjectClaim;
+    /** Written BEFORE the exchange leaves: from this point a lost answer is `uncertain`. */
+    markSent(fence: number): boolean;
+    /** Stores the rotated tokens (the caller re-sealed the envelope) and moves to `hydrating`. */
+    checkpoint(fence: number, payload: string, freshIdToken: boolean): boolean;
+    /** Stores the final session and ends the lease. */
+    complete(fence: number, payload: string, expiresAt: number): boolean;
+    /** `sent: false` clears the lease; `sent: true` in phase `sent` marks the
+     * session `uncertain`, in `hydrating` keeps the checkpoint for a retry. A
+     * session that is already `uncertain` stays so: the owner that sent the
+     * request is gone and nothing it says now can clear that. */
+    release(fence: number, sent: boolean): void;
+    /** Ends the session and remembers the notice's `jti` until `untilS`, in one
+     * step and in this order: the session is deleted FIRST and the `jti` marked
+     * SECOND (`@stwrd/core/backchannel`: the IdP retries a 5xx, and a `jti` marked
+     * before a failed deletion would turn the retry into a "replay"). A `jti`
+     * already seen deletes nothing. */
+    logout(jti: string, untilS: number): "terminated" | "replay";
+    alarm(): Promise<void>;
+}

package/dist/sessionObject.js

@@ -0,0 +1,225 @@
+/**
+ * `StwrdSessionObject` — the Durable Object that keeps ONE session (the object
+ * is named after the namespace and the local session id) and runs its refresh lease.
+ *
+ * It never sees a session in the clear: the Worker seals the session (JWE, see
+ * `store.ts`) and the object stores the envelope next to the lease columns,
+ * which hold no secret. The lease is the same state machine as the PostgreSQL
+ * and in-memory stores of `@stwrd/node` (`SessionStore` in `@stwrd/core/sessions`
+ * is the contract): `claim` grants the one refresh of a session, and every later
+ * step is a compare-and-set on the fence it handed out.
+ *
+ * **Every method is synchronous.** Awaiting a timer or a `fetch` inside a
+ * method can let another call in between, so the invariants cannot depend on a method being atomic
+ * across an `await`; with no `await` a method runs to the end before any other
+ * call is delivered, and the multi-statement ones are one `transactionSync`.
+ * Only `alarm` is async, at its very end. The lease clock is this object's.
+ *
+ * The object deletes itself: an alarm at the session's expiry removes the
+ * envelope (and with it the stored refresh token) and, when nothing is left,
+ * the whole storage. Storage is only ever created by a write (`set`, `logout`):
+ * reads and lease calls on an object with nothing in it make nothing.
+ */
+import { DurableObject } from "cloudflare:workers";
+export class StwrdSessionObject extends DurableObject {
+    ready = false;
+    /** Whether the storage exists. Only a write creates it (`ensureSchema`), so
+     * a read of an object nobody ever signed in under, or of one whose alarm
+     * emptied it, finds nothing and makes nothing. */
+    hasSchema() {
+        if (this.ready)
+            return true;
+        const [row] = this.rows("SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN ('session', 'counter', 'seen')");
+        this.ready = row?.n === 3;
+        return this.ready;
+    }
+    // The storage is created by the first write (and again after the alarm emptied it).
+    ensureSchema() {
+        if (this.ready)
+            return;
+        const sql = this.ctx.storage.sql;
+        sql.exec(`CREATE TABLE IF NOT EXISTS session (
+      slot INTEGER PRIMARY KEY CHECK (slot = 0),
+      payload TEXT NOT NULL,
+      expires_at REAL NOT NULL,
+      fence INTEGER NOT NULL,
+      lease_owner TEXT,
+      lease_phase TEXT CHECK (lease_phase IN ('acquired', 'sent', 'hydrating', 'uncertain')),
+      lease_expires_at REAL,
+      fresh_id_token INTEGER NOT NULL DEFAULT 0,
+      CHECK ((lease_phase IS NULL) = (lease_owner IS NULL))
+    )`);
+        sql.exec("CREATE TABLE IF NOT EXISTS counter (slot INTEGER PRIMARY KEY CHECK (slot = 0), fence INTEGER NOT NULL)");
+        sql.exec("CREATE TABLE IF NOT EXISTS seen (jti TEXT PRIMARY KEY, until_s REAL NOT NULL)");
+        this.ready = true;
+    }
+    rows(query, ...bindings) {
+        return this.ctx.storage.sql.exec(query, ...bindings).toArray();
+    }
+    nowS() {
+        return Date.now() / 1000;
+    }
+    /** Strictly increasing, survives `delete`, and anchored to the clock so it
+     * still exceeds every earlier fence after the storage was emptied. */
+    nextFence() {
+        const [row] = this.rows("SELECT fence FROM counter WHERE slot = 0");
+        const next = Math.max((row?.fence ?? 0) + 1, Date.now() * 1000);
+        this.rows("INSERT INTO counter (slot, fence) VALUES (0, ?) ON CONFLICT (slot) DO UPDATE SET fence = excluded.fence", next);
+        return next;
+    }
+    /** The alarm goes off at the earliest thing this object has to forget. */
+    scheduleAlarm() {
+        const [row] = this.rows(`SELECT min(t) AS next_at FROM (SELECT expires_at AS t FROM session UNION ALL SELECT until_s AS t FROM seen)`);
+        if (row?.next_at !== null && row?.next_at !== undefined) {
+            void this.ctx.storage.setAlarm(Math.ceil(row.next_at * 1000));
+        }
+    }
+    // --- the session -------------------------------------------------------
+    /** The sealed envelope, or `null`. Expiry is the caller's judgement (the
+     * alarm removes the row some time after it). */
+    get() {
+        if (!this.hasSchema())
+            return null;
+        const [row] = this.rows("SELECT payload FROM session WHERE slot = 0");
+        return row ? row.payload : null;
+    }
+    /** Installs a session, clearing any lease and taking a new fence: a stale
+     * owner of an earlier session under this id can no longer write. */
+    set(payload, expiresAt) {
+        this.ensureSchema();
+        this.ctx.storage.transactionSync(() => {
+            const fence = this.nextFence();
+            this.rows(`INSERT INTO session (slot, payload, expires_at, fence) VALUES (0, ?, ?, ?)
+         ON CONFLICT (slot) DO UPDATE SET payload = excluded.payload, expires_at = excluded.expires_at,
+           fence = excluded.fence, lease_owner = NULL, lease_phase = NULL, lease_expires_at = NULL, fresh_id_token = 0`, payload, expiresAt, fence);
+        });
+        this.scheduleAlarm();
+    }
+    delete() {
+        if (!this.hasSchema())
+            return;
+        this.rows("DELETE FROM session");
+        this.scheduleAlarm();
+    }
+    /** Deletes the session only if it is there; says whether it was. The first
+     * step of an organization switch between two objects. */
+    retire() {
+        if (!this.hasSchema())
+            return false;
+        const removed = this.rows("DELETE FROM session RETURNING slot").length > 0;
+        this.scheduleAlarm();
+        return removed;
+    }
+    // --- the refresh lease -------------------------------------------------
+    /** Same decision table as the other stores: `gone` with no session; `uncertain`
+     * for good once a sent request has no result; `busy` while another owner's
+     * lease is live; an expired lease in `sent` becomes `uncertain`; otherwise
+     * the caller is granted the lease (`hydrating` is resumed, anything else
+     * starts at `acquired`). */
+    claim(owner, leaseS) {
+        if (!this.hasSchema())
+            return { status: "gone" };
+        return this.ctx.storage.transactionSync(() => {
+            const [row] = this.rows("SELECT payload, lease_phase, lease_expires_at, fresh_id_token FROM session WHERE slot = 0");
+            if (!row)
+                return { status: "gone" };
+            const now = this.nowS();
+            const phase = row.lease_phase;
+            if (phase === "uncertain")
+                return { status: "uncertain" };
+            if (phase !== null && row.lease_expires_at > now)
+                return { status: "busy" };
+            if (phase === "sent") {
+                this.rows("UPDATE session SET lease_phase = 'uncertain' WHERE slot = 0");
+                return { status: "uncertain" };
+            }
+            const granted = phase === "hydrating" ? "hydrating" : "acquired";
+            const fence = this.nextFence();
+            this.rows("UPDATE session SET fence = ?, lease_owner = ?, lease_phase = ?, lease_expires_at = ? WHERE slot = 0", fence, owner, granted, now + leaseS);
+            return { status: "granted", payload: row.payload, fence, phase: granted, freshIdToken: Boolean(row.fresh_id_token) };
+        });
+    }
+    /** Written BEFORE the exchange leaves: from this point a lost answer is `uncertain`. */
+    markSent(fence) {
+        if (!this.hasSchema())
+            return false;
+        return this.rows("UPDATE session SET lease_phase = 'sent' WHERE fence = ? AND lease_phase = 'acquired' RETURNING slot", fence).length > 0;
+    }
+    /** Stores the rotated tokens (the caller re-sealed the envelope) and moves to `hydrating`. */
+    checkpoint(fence, payload, freshIdToken) {
+        if (!this.hasSchema())
+            return false;
+        return (this.rows("UPDATE session SET payload = ?, lease_phase = 'hydrating', fresh_id_token = ? WHERE fence = ? AND lease_phase = 'sent' RETURNING slot", payload, freshIdToken ? 1 : 0, fence).length > 0);
+    }
+    /** Stores the final session and ends the lease. */
+    complete(fence, payload, expiresAt) {
+        if (!this.hasSchema())
+            return false;
+        const done = this.rows(`UPDATE session SET payload = ?, expires_at = ?, lease_owner = NULL, lease_phase = NULL, lease_expires_at = NULL,
+           fresh_id_token = 0
+         WHERE fence = ? AND lease_phase IS NOT NULL AND lease_phase <> 'uncertain' RETURNING slot`, payload, expiresAt, fence).length > 0;
+        if (done)
+            this.scheduleAlarm();
+        return done;
+    }
+    /** `sent: false` clears the lease; `sent: true` in phase `sent` marks the
+     * session `uncertain`, in `hydrating` keeps the checkpoint for a retry. A
+     * session that is already `uncertain` stays so: the owner that sent the
+     * request is gone and nothing it says now can clear that. */
+    release(fence, sent) {
+        if (!this.hasSchema())
+            return;
+        this.rows(`UPDATE session SET
+         lease_phase = CASE
+           WHEN lease_phase = 'sent' AND ? THEN 'uncertain'
+           WHEN lease_phase = 'hydrating' THEN 'hydrating'
+           ELSE NULL END,
+         lease_owner = CASE
+           WHEN lease_phase = 'hydrating' OR (lease_phase = 'sent' AND ?) THEN lease_owner
+           ELSE NULL END,
+         lease_expires_at = CASE
+           WHEN lease_phase = 'hydrating' THEN ?
+           WHEN lease_phase = 'sent' AND ? THEN lease_expires_at
+           ELSE NULL END
+       WHERE fence = ? AND lease_phase IS NOT NULL AND lease_phase <> 'uncertain'`, sent ? 1 : 0, sent ? 1 : 0, this.nowS(), sent ? 1 : 0, fence);
+    }
+    // --- back-channel logout ---------------------------------------------------
+    /** Ends the session and remembers the notice's `jti` until `untilS`, in one
+     * step and in this order: the session is deleted FIRST and the `jti` marked
+     * SECOND (`@stwrd/core/backchannel`: the IdP retries a 5xx, and a `jti` marked
+     * before a failed deletion would turn the retry into a "replay"). A `jti`
+     * already seen deletes nothing. */
+    logout(jti, untilS) {
+        this.ensureSchema();
+        const outcome = this.ctx.storage.transactionSync(() => {
+            this.rows("DELETE FROM seen WHERE until_s <= ?", this.nowS());
+            if (this.rows("SELECT 1 AS seen FROM seen WHERE jti = ?", jti).length > 0)
+                return "replay";
+            this.rows("DELETE FROM session");
+            this.rows("INSERT INTO seen (jti, until_s) VALUES (?, ?)", jti, untilS);
+            return "terminated";
+        });
+        this.scheduleAlarm();
+        return outcome;
+    }
+    // --- forgetting ---------------------------------------------------------
+    async alarm() {
+        if (!this.hasSchema())
+            return;
+        const now = this.nowS();
+        const left = this.ctx.storage.transactionSync(() => {
+            this.rows("DELETE FROM session WHERE expires_at <= ?", now);
+            this.rows("DELETE FROM seen WHERE until_s <= ?", now);
+            return this.rows("SELECT (SELECT count(*) FROM session) + (SELECT count(*) FROM seen) AS n")[0].n ?? 0;
+        });
+        if (left === 0) {
+            // Nothing left to remember: the storage goes too. The fence restarts from
+            // the clock, which is above every fence handed out before.
+            await this.ctx.storage.deleteAll();
+            this.ready = false;
+        }
+        else {
+            this.scheduleAlarm();
+        }
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `DurableObjectSessionStore` — the `SessionStore` of `@stwrd/workers`: one
+ * Durable Object (`StwrdSessionObject`) per local session, named after the
+ * namespace (tenant/client) and the session id, like the PostgreSQL key
+ * `(namespace, session_id)`, so two clients that share a binding never share
+ * an object, and a login, a refresh and a back-channel notice for different
+ * sessions never queue behind each other and the lease of one session is
+ * decided in one place.
+ *
+ * Sessions are sealed here, in the Worker, with a `Keyring` (JWE `dir` +
+ * `A256GCM`, as `@stwrd/node/postgres` does): the object only ever holds the
+ * envelope, never the key and never a token in the clear. The authenticated
+ * payload carries the namespace (tenant/client), the session id and the
+ * purpose, so an envelope copied to another namespace or another object is
+ * rejected on read. Lease phase, fence and expiry live in plain columns inside
+ * the object because the object decides on them and they hold no secret.
+ *
+ * A store that does not answer is an IdP that does not answer: every failure of
+ * a call to the object is raised as `IdpUnavailable`, so every route and guard answers
+ * 503 and none of them reads it as "no session" (a session lost to a
+ * hiccup of the platform is not a session that ended).
+ *
+ * Back-channel logout goes through the same objects: `backChannelSink()` gives
+ * the sink, built from this store so it cannot name other objects than the
+ * store does (the notice's `sid` names the session's own object, which deletes
+ * the session and THEN marks the `jti`, in one call: `StwrdSessionObject.logout`.
+ * If the object does not answer, nothing was marked: the caller answers 503 and
+ * the IdP retries — it retries a 5xx and never a 4xx, so a `jti` marked before
+ * a failed deletion would turn the retry into a "replay" and leave the session
+ * alive for good).
+ */
+import type { BackChannelSink } from "@stwrd/core/backchannel";
+import type { Keyring } from "@stwrd/core/keyring";
+import { type RefreshClaim, type SessionStore, type StwrdSession, type Tokens } from "@stwrd/core/sessions";
+import type { StwrdSessionObject } from "./sessionObject.js";
+/** The prefix of every object name; the namespace and the session id follow it. */
+export declare const SESSION_OBJECT_PREFIX = "stwrd-session:";
+/** The name of the object that keeps one session: the namespace and the id as
+ * a JSON pair, so no namespace/id split can be read as another (a `|` or a
+ * `:` inside either cannot move the boundary). */
+export declare function sessionObjectName(namespace: string, sessionId: string): string;
+/** Where the `jti` of a notice that names no `sid` (only a `sub`) is kept:
+ * there is no session of ours to end, and the notice must not replay. The
+ * namespace follows it, and the name cannot collide with a session's (those
+ * start with `stwrd-session:`). */
+export declare const UNNAMED_NOTICE_OBJECT = "stwrd-backchannel:unnamed";
+export interface DurableObjectSessionStoreOptions {
+    /** Tenant/client this store serves; bound into every envelope. */
+    namespace: string;
+    keyring: Keyring;
+    /** Called with the reason when an envelope cannot be read (tampered,
+     * relocated, key gone). Default: `console.warn`. */
+    onUnreadable?: (error: unknown) => void;
+}
+export type SessionObjects = DurableObjectNamespace<StwrdSessionObject>;
+export declare class DurableObjectSessionStore implements SessionStore {
+    private readonly objects;
+    private readonly options;
+    constructor(objects: SessionObjects, options: DurableObjectSessionStoreOptions);
+    private get namespace();
+    private objectFor;
+    /** Every call to an object goes through here: whatever goes wrong, the store did not answer. */
+    private call;
+    /** The back-channel logout sink for the objects of THIS store: same
+     * namespace, same objects. There is no way to build one with another namespace. */
+    backChannelSink(): BackChannelSink;
+    private seal;
+    private open;
+    get(sessionId: string): Promise<StwrdSession | null>;
+    set(session: StwrdSession): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    /** Two steps across two objects, not one: the old session is retired first
+     * (and only if it still exists, so a logout in between is never undone) and
+     * the new one installed second. A failure between them leaves no session —
+     * the person signs in again — and never two. */
+    replaceSession(oldId: string, session: StwrdSession): Promise<boolean>;
+    claimRefresh(sessionId: string, owner: string, leaseS: number): Promise<RefreshClaim>;
+    markRefreshSent(sessionId: string, fence: number): Promise<boolean>;
+    checkpointRefresh(sessionId: string, fence: number, tokens: Tokens, freshIdToken: boolean): Promise<boolean>;
+    completeRefresh(sessionId: string, fence: number, session: StwrdSession): Promise<boolean>;
+    releaseRefresh(sessionId: string, fence: number, sent: boolean): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,163 @@
+/**
+ * `DurableObjectSessionStore` — the `SessionStore` of `@stwrd/workers`: one
+ * Durable Object (`StwrdSessionObject`) per local session, named after the
+ * namespace (tenant/client) and the session id, like the PostgreSQL key
+ * `(namespace, session_id)`, so two clients that share a binding never share
+ * an object, and a login, a refresh and a back-channel notice for different
+ * sessions never queue behind each other and the lease of one session is
+ * decided in one place.
+ *
+ * Sessions are sealed here, in the Worker, with a `Keyring` (JWE `dir` +
+ * `A256GCM`, as `@stwrd/node/postgres` does): the object only ever holds the
+ * envelope, never the key and never a token in the clear. The authenticated
+ * payload carries the namespace (tenant/client), the session id and the
+ * purpose, so an envelope copied to another namespace or another object is
+ * rejected on read. Lease phase, fence and expiry live in plain columns inside
+ * the object because the object decides on them and they hold no secret.
+ *
+ * A store that does not answer is an IdP that does not answer: every failure of
+ * a call to the object is raised as `IdpUnavailable`, so every route and guard answers
+ * 503 and none of them reads it as "no session" (a session lost to a
+ * hiccup of the platform is not a session that ended).
+ *
+ * Back-channel logout goes through the same objects: `backChannelSink()` gives
+ * the sink, built from this store so it cannot name other objects than the
+ * store does (the notice's `sid` names the session's own object, which deletes
+ * the session and THEN marks the `jti`, in one call: `StwrdSessionObject.logout`.
+ * If the object does not answer, nothing was marked: the caller answers 503 and
+ * the IdP retries — it retries a 5xx and never a 4xx, so a `jti` marked before
+ * a failed deletion would turn the retry into a "replay" and leave the session
+ * alive for good).
+ */
+import { IdpUnavailable } from "@stwrd/core/oidc";
+import { withoutCapabilities, } from "@stwrd/core/sessions";
+/** The prefix of every object name; the namespace and the session id follow it. */
+export const SESSION_OBJECT_PREFIX = "stwrd-session:";
+/** The name of the object that keeps one session: the namespace and the id as
+ * a JSON pair, so no namespace/id split can be read as another (a `|` or a
+ * `:` inside either cannot move the boundary). */
+export function sessionObjectName(namespace, sessionId) {
+    return SESSION_OBJECT_PREFIX + JSON.stringify([namespace, sessionId]);
+}
+/** Where the `jti` of a notice that names no `sid` (only a `sub`) is kept:
+ * there is no session of ours to end, and the notice must not replay. The
+ * namespace follows it, and the name cannot collide with a session's (those
+ * start with `stwrd-session:`). */
+export const UNNAMED_NOTICE_OBJECT = "stwrd-backchannel:unnamed";
+function defaultUnreadable(error) {
+    console.warn("stwrd: unreadable session envelope", error);
+}
+export class DurableObjectSessionStore {
+    objects;
+    options;
+    constructor(objects, options) {
+        this.objects = objects;
+        this.options = options;
+        if (!options.namespace)
+            throw new Error("A namespace (tenant/client) is required.");
+    }
+    get namespace() {
+        return this.options.namespace;
+    }
+    objectFor(sessionId) {
+        return this.objects.get(this.objects.idFromName(sessionObjectName(this.namespace, sessionId)));
+    }
+    /** Every call to an object goes through here: whatever goes wrong, the store did not answer. */
+    async call(sessionId, run) {
+        try {
+            return await run(this.objectFor(sessionId));
+        }
+        catch (error) {
+            throw Object.assign(new IdpUnavailable("The session store did not respond.", false), { cause: error });
+        }
+    }
+    /** The back-channel logout sink for the objects of THIS store: same
+     * namespace, same objects. There is no way to build one with another namespace. */
+    backChannelSink() {
+        return {
+            terminate: async (sessionId, jti, untilS) => {
+                const name = sessionId === null ? `${UNNAMED_NOTICE_OBJECT}:${this.namespace}` : sessionObjectName(this.namespace, sessionId);
+                try {
+                    return await this.objects.get(this.objects.idFromName(name)).logout(jti, untilS);
+                }
+                catch (error) {
+                    throw Object.assign(new IdpUnavailable("The session store did not respond.", false), { cause: error });
+                }
+            },
+        };
+    }
+    async seal(session) {
+        return this.options.keyring.encrypt(JSON.stringify({ ns: this.namespace, sid: session.id, purpose: "session", session }));
+    }
+    async open(sessionId, payload) {
+        try {
+            const body = JSON.parse(await this.options.keyring.decrypt(payload));
+            if (body.ns !== this.namespace || body.sid !== sessionId || body.purpose !== "session") {
+                throw new Error("Envelope context does not match its location.");
+            }
+            return body.session;
+        }
+        catch (error) {
+            // Fail closed: a tampered, relocated or unreadable envelope is no session.
+            (this.options.onUnreadable ?? defaultUnreadable)(error);
+            return null;
+        }
+    }
+    async get(sessionId) {
+        const payload = await this.call(sessionId, (stub) => stub.get());
+        return payload === null ? null : this.open(sessionId, payload);
+    }
+    async set(session) {
+        const payload = await this.seal(session);
+        await this.call(session.id, (stub) => stub.set(payload, session.expiresAt));
+    }
+    async delete(sessionId) {
+        await this.call(sessionId, (stub) => stub.delete());
+    }
+    /** Two steps across two objects, not one: the old session is retired first
+     * (and only if it still exists, so a logout in between is never undone) and
+     * the new one installed second. A failure between them leaves no session —
+     * the person signs in again — and never two. */
+    async replaceSession(oldId, session) {
+        const retired = await this.call(oldId, (stub) => stub.retire());
+        if (!retired)
+            return false;
+        await this.set(session);
+        return true;
+    }
+    async claimRefresh(sessionId, owner, leaseS) {
+        const claim = await this.call(sessionId, (stub) => stub.claim(owner, leaseS));
+        if (claim.status !== "granted")
+            return { status: claim.status };
+        const session = await this.open(sessionId, claim.payload);
+        if (!session) {
+            // A lease on an envelope nobody can read would only block the session.
+            await this.call(sessionId, (stub) => stub.release(claim.fence, false));
+            return { status: "gone" };
+        }
+        return { status: "granted", session, fence: claim.fence, phase: claim.phase, freshIdToken: claim.freshIdToken };
+    }
+    async markRefreshSent(sessionId, fence) {
+        return this.call(sessionId, (stub) => stub.markSent(fence));
+    }
+    async checkpointRefresh(sessionId, fence, tokens, freshIdToken) {
+        // The object cannot rewrite what it cannot read: the envelope is opened
+        // here, the rotated tokens put in, and the lease (fence and phase) decides
+        // in the object whether this write still counts.
+        const payload = await this.call(sessionId, (stub) => stub.get());
+        const current = payload === null ? null : await this.open(sessionId, payload);
+        if (!current)
+            return false;
+        const sealed = await this.seal({ ...current, claims: withoutCapabilities(current.claims), tokens });
+        return this.call(sessionId, (stub) => stub.checkpoint(fence, sealed, freshIdToken));
+    }
+    async completeRefresh(sessionId, fence, session) {
+        if (session.id !== sessionId)
+            return false;
+        const payload = await this.seal(session);
+        return this.call(sessionId, (stub) => stub.complete(fence, payload, session.expiresAt));
+    }
+    async releaseRefresh(sessionId, fence, sent) {
+        await this.call(sessionId, (stub) => stub.release(fence, sent));
+    }
+}

package/dist/stwrd.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `stwrdFor(env, options)` and `StwrdWorkers` — the object a Worker builds
+ * once from its `env` and uses for the `/auth/*` routes (and, further down,
+ * the guards). Counterpart of `Stwrd` in `@stwrd/node`: everything that is
+ * not about HTTP lives in `StwrdCore`, and the routes are the core's
+ * `Request → Response` handler.
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       const stwrd = stwrdFor(env);
+ *       return (await stwrd.handle(request)) ?? app(request, env);
+ *     },
+ *   };
+ *
+ * Variables are the same as the other SDKs' (`STWRD_ISSUER`, ...), plus
+ * `STWRD_SESSION_KEYS` (see `sessionKeys.ts`); sessions live in the Durable
+ * Object bound as `STWRD_SESSIONS`. `MemoryStore` is only ever used when an app
+ * passes it as `options.sessions` (tests): a Worker has no memory that outlives
+ * a request, so it is not a default.
+ */
+import { type RefreshTuning, StwrdCore, type StwrdOptions } from "@stwrd/core/client";
+import { type AccessResult, type Resolution } from "@stwrd/core/web/access";
+import { type AuthHandlerOptions } from "@stwrd/core/web/authHandler";
+/** The name of the Durable Object binding an app declares in its wrangler config. */
+export declare const SESSIONS_BINDING = "STWRD_SESSIONS";
+/** What differs from Node when a session is renewed.
+ *
+ * workerd gives no proof that an exchange never left (its `fetch` errors carry
+ * no `cause.code`), so a failed exchange sends the session to `uncertain` for
+ * good: the IdP is asked for its discovery document, with a timeout, right
+ * before the exchange is marked as sent, so an IdP that is down costs a retry
+ * and not a session. And every poll for another owner's refresh is a call to
+ * a Durable Object: the wait grows (50, 100, 200, 400, then 800 ms) instead of
+ * polling every 50 ms for ten seconds. */
+export declare const WORKERS_REFRESH_TUNING: RefreshTuning;
+export interface WorkersOptions extends Partial<StwrdOptions>, AuthHandlerOptions {
+}
+/** What a Worker hands the adapter so a renewal outlives the request: its
+ * `ExecutionContext` (only `waitUntil` is used). Optional everywhere; without
+ * it a renewal ends with the request, as in Node. */
+export type WaitUntilContext = Pick<ExecutionContext, "waitUntil">;
+export interface GuardOptions {
+    /** Force a 401 JSON denial even for a browser navigation (the default sends
+     * a navigation, `Accept: text/html`, to the sign-in route instead). */
+    api?: boolean;
+    /** The Worker's `ExecutionContext`: a session renewal it starts is kept
+     * alive with `ctx.waitUntil`, so a person who closes the tab in the middle
+     * of it does not leave the session `uncertain`. */
+    ctx?: WaitUntilContext;
+}
+export interface ProtectOptions extends GuardOptions {
+    /** Paths that need no session: an exact path, or a prefix ending in `*`.
+     * Everything under the auth prefix is public without being listed. */
+    public?: Iterable<string>;
+}
+export declare class StwrdWorkers extends StwrdCore {
+    private readonly handler;
+    private readonly resolutions;
+    constructor(options: StwrdOptions, hooks?: AuthHandlerOptions);
+    /** Serves the `/auth/*` routes. `null` for anything else (another path, or a
+     * method the route does not take): the app routes it. A session store that
+     * does not answer is a 503, like an IdP that does not answer; any other
+     * error is the app's to see. Pass the Worker's `ctx` so a renewal survives
+     * the person closing the tab. */
+    handle(request: Request, ctx?: WaitUntilContext): Promise<Response | null>;
+    /** The request's session context, for a route that works with or without a
+     * person (no denial). `idpUnavailable` is the fact `context.user === null`
+     * cannot carry: the IdP or the session store did not answer, so there is no
+     * user to show — which is not the same as there being none. Render nothing
+     * that says "signed out" when it is set. The first call for a request is the
+     * one that reads the session, so it is the one whose `ctx` keeps a renewal alive. */
+    resolve(request: Request, ctx?: WaitUntilContext): Promise<Resolution>;
+    private guard;
+    /** Every guard answers `{ ok: true, context }` or `{ ok: false, response }`
+     * with the response that stops the request, in this order: IdP or store
+     * silent → 503; no user → 401 JSON (or the 303 to sign-in for a navigation);
+     * user but the rule fails → 403. */
+    requireAuth(request: Request, options?: GuardOptions): Promise<AccessResult>;
+    /** `org_roles` is an open registry: membership, never set equality. */
+    requireRole(request: Request, role: string, options?: GuardOptions): Promise<AccessResult>;
+    requirePermission(request: Request, permission: string, options?: GuardOptions): Promise<AccessResult>;
+    /** Needs the `org` scope in the configuration (`ConfigError` otherwise). */
+    requireOrg(request: Request, options?: GuardOptions): Promise<AccessResult>;
+    /** The opt-in fail-closed guard: `null` lets the request through, a
+     * `Response` stops it. It needs a session on every path that is not declared
+     * public, answering what `requireAuth` answers. */
+    protect(request: Request, options?: ProtectOptions): Promise<Response | null>;
+}
+/** The `StwrdWorkers` of this `env`: built on the first call (the options of
+ * that first call are the ones that count) and reused after. A later call with
+ * no options just gets it; one that changes a value option (issuer, client id,
+ * scope, ...) is a `ConfigError`, because it would be silently ignored. The
+ * callbacks (`onUserRegistered`, `onEvent`, `fetch`) are declared once: those
+ * of the first call stay and those of later calls are ignored, without error,
+ * so `stwrdFor(env, { onUserRegistered })` inside `fetch(req, env, ctx)` works
+ * on every request. Fails closed with a `ConfigError` too when a required
+ * variable, the `STWRD_SESSIONS` binding or `STWRD_SESSION_KEYS` is missing or
+ * invalid. */
+export declare function stwrdFor(env: object, options?: WorkersOptions): StwrdWorkers;

package/dist/stwrd.js

@@ -0,0 +1,198 @@
+/**
+ * `stwrdFor(env, options)` and `StwrdWorkers` — the object a Worker builds
+ * once from its `env` and uses for the `/auth/*` routes (and, further down,
+ * the guards). Counterpart of `Stwrd` in `@stwrd/node`: everything that is
+ * not about HTTP lives in `StwrdCore`, and the routes are the core's
+ * `Request → Response` handler.
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       const stwrd = stwrdFor(env);
+ *       return (await stwrd.handle(request)) ?? app(request, env);
+ *     },
+ *   };
+ *
+ * Variables are the same as the other SDKs' (`STWRD_ISSUER`, ...), plus
+ * `STWRD_SESSION_KEYS` (see `sessionKeys.ts`); sessions live in the Durable
+ * Object bound as `STWRD_SESSIONS`. `MemoryStore` is only ever used when an app
+ * passes it as `options.sessions` (tests): a Worker has no memory that outlives
+ * a request, so it is not a default.
+ */
+import { StwrdCore, stwrdOptionsFromEnv } from "@stwrd/core/client";
+import { ConfigError } from "@stwrd/core/config";
+import { IdpUnavailable } from "@stwrd/core/oidc";
+import { checkAccess, idpSilentResponse, isPublicPath, resolveAccess, } from "@stwrd/core/web/access";
+import { readRequestCookie } from "@stwrd/core/web/cookies";
+import { authHandler } from "@stwrd/core/web/authHandler";
+import { parseSessionKeys } from "./sessionKeys.js";
+import { DurableObjectSessionStore } from "./store.js";
+/** The name of the Durable Object binding an app declares in its wrangler config. */
+export const SESSIONS_BINDING = "STWRD_SESSIONS";
+/** What differs from Node when a session is renewed.
+ *
+ * workerd gives no proof that an exchange never left (its `fetch` errors carry
+ * no `cause.code`), so a failed exchange sends the session to `uncertain` for
+ * good: the IdP is asked for its discovery document, with a timeout, right
+ * before the exchange is marked as sent, so an IdP that is down costs a retry
+ * and not a session. And every poll for another owner's refresh is a call to
+ * a Durable Object: the wait grows (50, 100, 200, 400, then 800 ms) instead of
+ * polling every 50 ms for ten seconds. */
+export const WORKERS_REFRESH_TUNING = Object.freeze({
+    waitS: 10,
+    pollDelayMs: (attempt) => Math.min(50 * 2 ** attempt, 800),
+    probeBeforeExchange: true,
+});
+/** The keep-alive of a `ctx`, or `undefined` for none. A `ctx` that cannot
+ * `waitUntil` is a `ConfigError` before anything is read: the usual cause is
+ * `env` passed where the Worker's `ctx` goes, and the failure would otherwise
+ * show up in the middle of a renewal, after the exchange was marked as sent. */
+function keepAliveOf(ctx) {
+    if (ctx === undefined)
+        return undefined;
+    if (typeof ctx?.waitUntil !== "function") {
+        throw new ConfigError("The ctx you passed has no waitUntil function: pass the ExecutionContext of the Worker (the third argument of fetch), not env.");
+    }
+    return (work) => ctx.waitUntil(work);
+}
+export class StwrdWorkers extends StwrdCore {
+    handler;
+    // One resolution per request object: the session is read (and maybe
+    // renewed) once however many guards and handlers ask.
+    resolutions = new WeakMap();
+    constructor(options, hooks = {}) {
+        super(options, WORKERS_REFRESH_TUNING);
+        this.handler = authHandler(this, hooks);
+    }
+    /** Serves the `/auth/*` routes. `null` for anything else (another path, or a
+     * method the route does not take): the app routes it. A session store that
+     * does not answer is a 503, like an IdP that does not answer; any other
+     * error is the app's to see. Pass the Worker's `ctx` so a renewal survives
+     * the person closing the tab. */
+    async handle(request, ctx) {
+        const keepAlive = keepAliveOf(ctx);
+        try {
+            return await this.handler(request, keepAlive);
+        }
+        catch (exc) {
+            if (exc instanceof IdpUnavailable) {
+                return idpSilentResponse();
+            }
+            throw exc;
+        }
+    }
+    // --- guards ----------------------------------------------------------------
+    /** The request's session context, for a route that works with or without a
+     * person (no denial). `idpUnavailable` is the fact `context.user === null`
+     * cannot carry: the IdP or the session store did not answer, so there is no
+     * user to show — which is not the same as there being none. Render nothing
+     * that says "signed out" when it is set. The first call for a request is the
+     * one that reads the session, so it is the one whose `ctx` keeps a renewal alive. */
+    async resolve(request, ctx) {
+        const keepAlive = keepAliveOf(ctx);
+        let resolution = this.resolutions.get(request);
+        if (!resolution) {
+            resolution = resolveAccess(this, readRequestCookie(request.headers, this.config.sessionCookie), keepAlive);
+            this.resolutions.set(request, resolution);
+        }
+        return resolution;
+    }
+    async guard(request, rule, options) {
+        const url = new URL(request.url);
+        return checkAccess(this, { accept: request.headers.get("accept"), target: url.pathname + url.search, api: options.api, resolved: await this.resolve(request, options.ctx) }, rule);
+    }
+    /** Every guard answers `{ ok: true, context }` or `{ ok: false, response }`
+     * with the response that stops the request, in this order: IdP or store
+     * silent → 503; no user → 401 JSON (or the 303 to sign-in for a navigation);
+     * user but the rule fails → 403. */
+    requireAuth(request, options = {}) {
+        return this.guard(request, { auth: true }, options);
+    }
+    /** `org_roles` is an open registry: membership, never set equality. */
+    requireRole(request, role, options = {}) {
+        return this.guard(request, { role }, options);
+    }
+    requirePermission(request, permission, options = {}) {
+        return this.guard(request, { permission }, options);
+    }
+    /** Needs the `org` scope in the configuration (`ConfigError` otherwise). */
+    requireOrg(request, options = {}) {
+        return this.guard(request, { org: true }, options);
+    }
+    /** The opt-in fail-closed guard: `null` lets the request through, a
+     * `Response` stops it. It needs a session on every path that is not declared
+     * public, answering what `requireAuth` answers. */
+    async protect(request, options = {}) {
+        keepAliveOf(options.ctx);
+        const url = new URL(request.url);
+        if (isPublicPath(url.pathname, [...(options.public ?? [])], this.config.prefix)) {
+            return null;
+        }
+        const result = await this.requireAuth(request, options);
+        return result.ok ? null : result.response;
+    }
+}
+const instances = new WeakMap();
+// What defines the configuration: every option that is set and is not a
+// function. Callbacks (`onUserRegistered`, `onEvent`, `fetch`) are not
+// compared: declared inline in `fetch(req, env, ctx)` they are a new function
+// on every request, and the first call's are the ones that count.
+const present = (options) => Object.entries(options).filter(([, value]) => value !== undefined && typeof value !== "function");
+function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => Object.is(item, b[index]));
+}
+/** The same options: the same keys with the same values (an array by its
+ * items, an object by identity; functions are not compared, see `present`). */
+function sameOptions(a, b) {
+    const left = present(a);
+    const right = present(b);
+    return left.length === right.length && left.every(([key, value]) => key in b && sameValue(value, b[key]));
+}
+function isObjects(value) {
+    const candidate = value;
+    return typeof candidate?.idFromName === "function" && typeof candidate?.get === "function";
+}
+/** The `StwrdWorkers` of this `env`: built on the first call (the options of
+ * that first call are the ones that count) and reused after. A later call with
+ * no options just gets it; one that changes a value option (issuer, client id,
+ * scope, ...) is a `ConfigError`, because it would be silently ignored. The
+ * callbacks (`onUserRegistered`, `onEvent`, `fetch`) are declared once: those
+ * of the first call stay and those of later calls are ignored, without error,
+ * so `stwrdFor(env, { onUserRegistered })` inside `fetch(req, env, ctx)` works
+ * on every request. Fails closed with a `ConfigError` too when a required
+ * variable, the `STWRD_SESSIONS` binding or `STWRD_SESSION_KEYS` is missing or
+ * invalid. */
+export function stwrdFor(env, options = {}) {
+    // The core seals cookies with the `Buffer` global; without `nodejs_compat` it
+    // is missing and the first request would fail somewhere far from the cause.
+    if (typeof Buffer === "undefined") {
+        throw new ConfigError("The Buffer global is missing: turn on the nodejs_compat flag in wrangler.jsonc with a compatibility_date of 2024-09-23 or later (any date from 2026-08-04 on turns it on by itself).");
+    }
+    const cached = instances.get(env);
+    if (cached) {
+        if (present(options).length > 0 && !sameOptions(cached.options, options)) {
+            throw new ConfigError("stwrdFor was already called for this env with other options; they would be ignored. Pass the same options every time, or build the instance once (callbacks are the exception: the first call's stay).");
+        }
+        return cached.instance;
+    }
+    const { onUserRegistered, onEvent, backChannel, ...coreOverrides } = options;
+    const coreOptions = stwrdOptionsFromEnv(env, coreOverrides);
+    let sessions = coreOptions.sessions;
+    let sink = backChannel;
+    if (!sessions) {
+        const objects = env[SESSIONS_BINDING];
+        if (!isObjects(objects)) {
+            throw new ConfigError(`The ${SESSIONS_BINDING} Durable Object binding is missing: declare it in wrangler.jsonc (see the README).`);
+        }
+        const keyring = parseSessionKeys(env.STWRD_SESSION_KEYS);
+        // Sessions sealed for one issuer and client are not readable under another.
+        const namespace = `${coreOptions.issuer}|${coreOptions.clientId}`;
+        const store = new DurableObjectSessionStore(objects, { namespace, keyring });
+        sessions = store;
+        sink ??= store.backChannelSink();
+    }
+    const instance = new StwrdWorkers({ ...coreOptions, sessions }, { onUserRegistered, onEvent, backChannel: sink });
+    instances.set(env, { instance, options });
+    return instance;
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@stwrd/workers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "stwrd SDK for Cloudflare Workers (backend-for-frontend profile): the /auth/* handler, route guards and a Durable Object session store.",
+  "keywords": [
+    "stwrd",
+    "authentication",
+    "oidc",
+    "oauth2",
+    "cloudflare-workers",
+    "durable-objects",
+    "bff",
+    "sessions"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "stwrd",
+    "url": "https://stwrd.dev"
+  },
+  "homepage": "https://stwrd.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stwrd-dev/sdk-js.git",
+    "directory": "packages/workers"
+  },
+  "bugs": {
+    "url": "https://github.com/stwrd-dev/sdk-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -b tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -b tsconfig.json && tsc -p tests/tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@stwrd/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.22.0",
+    "@cloudflare/workers-types": "^5.20261007.1",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10",
+    "wrangler": "4.124.0"
+  }
+}