@gaballahtech/seba 0.0.0-stage → 0.2.0

package/SECURITY.md

@@ -0,0 +1,224 @@
+# SECURITY
+
+## 1. Threat model
+
+| Threat | Assets at risk | Mitigation |
+|---|---|---|
+| Authorization code interception / mix-up | Access + refresh tokens | PKCE S256, random `state`, RFC 9207 `iss` checked against the issuer the request was built for. |
+| ID token forgery or substitution | User identity (`WebID`) | Signature verified with the provider's JWKS; `iss`, `aud`, `azp`, `exp`, `iat`, `nonce` validated; algorithm taken from the key metadata, not the token's preference. |
+| DPoP proof replay | Pod access | A new proof (new `jti`, new signature) for every attempt; no proof cache, no TTL, no reuse option. |
+| Token theft from the browser profile | Refresh token, DPoP key | Only the refresh token and key are persisted (IndexedDB); access token stays in memory; no `localStorage`; no cookies set by the library. |
+| XSS on the application origin | Everything the origin can reach | Out of scope to *prevent*; the library minimises the window (no tokens in DOM, no globals, no logging) and documents the residual risk. |
+| Credential leak via redirects | Access token, DPoP proof | `redirect: "manual"`; cross-origin redirect responses are returned to the caller, never re-issued with credentials. |
+| Duplicate side effects from retries | Application state | Automatic replay is limited to replayable requests (`GET`/`HEAD`/`OPTIONS`, or a re-readable body), at most one nonce retry and one refresh retry. |
+| Malicious/compromised provider metadata | Redirection of tokens | Issuer must match the discovery document exactly; endpoints must be `https` (loopback `http` only); redirect URI must be published verbatim by the Client ID Document. |
+| Secret leakage through logs | Tokens, codes, keys | Debug logging is structured and excludes credentials by construction; errors carry codes and messages, never payloads. |
+| Stolen database copy | Refresh token, key | IndexedDB is origin-bound and not encrypted at rest by SEBA; at-rest protection is the OS/browser profile's job (documented limitation). |
+
+Trust boundaries: (1) the browser page and its origin, (2) the provider's HTTPS endpoints,
+(3) the Solid resource server, (4) the published Client ID Document. Everything crossing
+those boundaries is validated; nothing is trusted because it "looks like" a token.
+
+## 2. Token storage policy
+
+| Value | Where | Lifetime |
+|---|---|---|
+| Access token | A private field in `SebaClient` (memory) | Until refresh, logout, or process end |
+| Refresh token | IndexedDB (`seba`/`session`, record key `current`) or memory | Until logout / rejection |
+| DPoP private key | IndexedDB, structured-cloned `CryptoKey` (non-extractable) or exported JWK fallback | Same as the refresh token |
+| DPoP public JWK + thumbprint | With the session record | Non-secret |
+| `state`, `nonce`, `code_verifier` | `sessionStorage` (browser) / memory (Node), single transaction record | Deleted after the callback, stale after 10 minutes |
+| ID token | Memory, inside the validated token set | Session lifetime in memory |
+| Authorization code | Memory, only between callback parsing and exchange | Seconds |
+
+`PersistedSession` has **no access-token field** — the type makes accidental persistence a
+compile error. `localStorage`, cookies, `window.name` and URL fragments are never used for
+secrets. If IndexedDB is unavailable and `storage` was left at its default, SEBA throws
+`SebaConfigError`; it never silently downgrades to a weaker store.
+
+## 3. DPoP implementation requirements (RFC 9449)
+
+- `typ` is `dpop+jwt`, `alg` is `ES256`; the `jwk` header contains only `kty`, `crv`, `x`,
+  `y` — never `d`.
+- `jti`: 32 bytes from `crypto.getRandomValues`, base64url encoded. Unique per proof.
+- `htm`: uppercase HTTP method actually sent.
+- `htu`: the request URL with query and fragment removed, normalized by `URL`
+  (lowercased scheme/host, default port removed).
+- `iat`: seconds since the epoch, from the local clock at signing time.
+- `ath`: `base64url(SHA-256(ASCII(access_token)))`, **only** on protected-resource requests.
+  Token-endpoint requests carry no `ath` (there is no access token being presented).
+- `nonce`: included only when the server supplied a `DPoP-Nonce`; the nonce is cached per
+  endpoint, the proof is always regenerated.
+- One proof per HTTP attempt. Retries — nonce challenge, token refresh, redirect hop —
+  each call `createDPoPProof()` again.
+
+`createDPoPProof()` is a pure function of `(key, method, url, accessToken?, nonce?)`
+returning a compact JWS. There is no module-level proof state, so no code path can return
+a previously signed proof. `tests/security/dpop-security.test.ts` asserts this directly:
+100 sequential proofs for an identical `(htm, htu)` yield 100 distinct JWTs and 100
+distinct `jti` values, and a recorded proof never reappears.
+
+## 4. Key management
+
+- Keys are generated with `jose.generateKeyPair("ES256", { extractable: false })` and
+  never leave the runtime.
+- `structuredClone(privateKey)` is probed once at login. When it succeeds, the
+  non-extractable `CryptoKey` is stored and the key material is never exportable
+  (`exportKey` throws for the private key). The public JWK is stored alongside it because a
+  non-extractable private key cannot reproduce its public half later.
+- When the engine cannot clone `CryptoKey`s, SEBA generates an extractable key, exports the
+  private JWK and stores it. This is a documented downgrade: the key is readable by
+  same-origin script either way, but it is no longer protected from export. The probe
+  result is not configurable, and index-key persistence is never used as a silent
+  substitute.
+- Only one key pair exists per stored session. A new login replaces the record atomically;
+  logout deletes it. Keys are never logged, never returned from the public API and never
+  included in error messages.
+- The public JWK's SHA-256 thumbprint (`jkt`) is what the ID token's `cnf.jkt` is compared
+  against; the access token is therefore bound to the same key used for its proofs.
+
+## 5. PKCE and OAuth state
+
+- `code_verifier`: 43 characters from the RFC 7636 alphabet, each from `crypto.getRandomValues`
+  (~258 bits of entropy), never shorter than the RFC minimum.
+- `code_challenge`: `base64url(SHA-256(ASCII(verifier)))`, `code_challenge_method=S256`.
+  `plain` is never sent or accepted.
+- `state` and `nonce`: 32 random bytes each, base64url, independent values.
+- All three are stored **before** the navigation and consumed exactly once. A callback
+  without a pending transaction, with a different `state`, or older than 10 minutes is
+  rejected with `SebaAuthError` before the code is exchanged.
+- The authorization response's `iss` (RFC 9207) must equal the issuer the pending
+  transaction was created for; otherwise `SebaAuthError` (mix-up protection).
+- The code is exchanged exactly once. Pending state is removed as soon as the exchange has
+  succeeded, so a replayed callback finds no transaction and fails closed. A response that
+  fails validation *before* the exchange leaves the transaction in place (until the
+  10-minute expiry) so the user can retry; the code itself is never exchanged twice.
+
+## 6. ID token validation
+
+Performed by `validateIdToken()` before any identity value is read:
+
+1. Compact JWS parsed; signature verified with `createRemoteJWKSet(jwksUri)` via `jose`,
+   restricted to asymmetric algorithms (`ES256/384/512`, `RS256/384/512`, `PS256/384/512`).
+2. `iss` must equal the discovered issuer (exact string).
+3. `aud` must contain `client_id`; `azp`, when present, must equal `client_id`; `azp` is
+   required when `aud` has multiple values.
+4. When the provider advertises the `webid` scope, `aud` must also contain `"solid"`.
+5. `exp` must be in the future (60 s clock tolerance), `iat` must not be in the future
+   (60 s tolerance), `nbf` is honoured when present.
+6. `nonce` must equal the pending transaction's nonce (login only).
+7. `sub` is required. `webid`, when present, must be an `https` URL (loopback `http`
+   allowed for development); otherwise `sub` is used when it is an `https` URL.
+8. `cnf.jkt`, when present, must equal the local DPoP key thumbprint, and is **required**
+   when the provider advertises `webid`.
+9. The resulting WebID must equal `options.webId` when the caller supplied one
+   (`SebaAuthError` on mismatch).
+
+Decoding without verification is never used to make a decision. Failed validation is a
+hard `SebaAuthError`; there is no "accept anyway" path.
+
+## 7. Refresh-token handling
+
+- Refresh requests use `grant_type=refresh_token`, `client_id`, the stored refresh token and
+  a freshly signed DPoP proof for the token endpoint (no `ath`).
+- The response must be `token_type: "DPoP"`; anything else is discarded (`SebaAuthError`)
+  and the previous record is left untouched.
+- Rotation: a returned `refresh_token` replaces the stored one in a single IndexedDB
+  `put`. If the provider omits it, the existing token is kept (RFC 6749 §6 allows both).
+- `invalid_grant` / `invalid_token` / `invalid_request` / `unauthorized_client` → storage
+  cleared, then `SebaSessionExpiredError`. The application learns the user must sign in
+  again. Other OAuth errors surface as `SebaAuthError` and the record is kept.
+- Network failures and 5xx responses → `SebaNetworkError`, record **kept**, so a provider
+  outage is never reported as a logout.
+- An ID token returned by a refresh is validated (signature, `iss`, `aud`, lifetime) and
+  its WebID must match the stored one; a nonce is not expected on refresh.
+- Concurrent refreshes are collapsed into one in-flight promise to avoid rotation races.
+
+## 8. Replay protection
+
+- DPoP: see §3 — no cache, no TTL, fresh `jti` per attempt.
+- OAuth: `state` is single-use and removed before the token request; `nonce` is single-use
+  per transaction; PKCE ties the code to this client instance.
+- Retries in `Seba.fetch`: at most one `use_dpop_nonce` retry and at most one
+  refresh-then-retry, never nested unbounded. Each retry signs a new proof.
+- Redirects: at most 5 same-origin hops. `303` switches to `GET`; `301`/`302` on a `POST`
+  switch to `GET`; `307`/`308` keep the method and body; other method/status combinations
+  are only followed when the body is replayable. Cross-origin targets are never followed
+  with credentials; the redirect response is returned instead.
+- Requests with a non-replayable body (`ReadableStream`) are never retried after a 401:
+  the challenge response is returned unchanged.
+
+## 9. Redirect and request security
+
+- The configured `redirectUri` must appear **verbatim** in the Client ID Document's
+  `redirect_uris`; no scheme/host/port/trailing-slash normalization is applied to either
+  side, so `https://app.example/cb` never matches `https://app.example/cb/`.
+- Node.js callback servers bind only to loopback (`127.0.0.1`, `::1`, `localhost`) and only
+  answer the registered path with the expected `state`; anything else gets `404`/`400`. The
+  listener is fully closed before `login()` settles, and after a five-minute timeout.
+- The authorization URL is built from the discovered endpoints only, over `https`.
+- `Authorization`/`DPoP` headers are attached only to requests the caller initiated (plus
+  same-origin redirect hops). They are never attached to a different origin, and token
+  endpoint requests never carry `Authorization`.
+- The provider selection UI validates user input as an `https` URL before use and never
+  collects credentials; there is no password field anywhere in the library.
+
+## 10. Logging restrictions
+
+`debug: true` logs only: operation names, issuer/client identifiers, endpoint URLs
+(without query strings), status codes, retry reasons and error codes. It never logs access
+tokens, refresh tokens, ID tokens, authorization codes, PKCE verifiers/challenges, `state`,
+`nonce`, public or private JWKs, or DPoP proofs. Errors contain codes and human-readable
+messages; `cause` objects are the original network/JOSE errors and contain no credentials.
+
+## 11. Known limitations
+
+1. **XSS defeats browser storage.** Same-origin script can use the stored refresh token and
+   key while the page is open. SEBA reduces exposure but cannot prevent this.
+2. **IndexedDB is not encrypted at rest** by SEBA. Anyone with the browser profile can read
+   the refresh token and (fallback mode) the exported key.
+3. **Opaque browser redirects.** With `redirect: "manual"`, browsers hide `Location` and the
+   status of a redirect, so SEBA returns the redirect response instead of following it.
+4. **No token introspection.** SEBA validates ID tokens and relies on the resource server
+   for access-token validity; revocation is best-effort.
+5. **Clock skew tolerance (60 s)** is fixed; a badly skewed device can fail login and
+   receives an actionable `SebaAuthError`.
+6. **No live-provider verification.** Only the hand-written mock provider and unit-level
+   protocol tests were executed in this environment.
+7. **`cnf.jkt` requirement gated on advertised `webid` scope.** A provider that omits the
+   scope but issues unbound tokens will pass ID token validation; the resource server still
+   rejects unbound tokens.
+8. **IndexedDB at-rest exposure.** Anyone with the browser profile can read the refresh
+   token and — on engines that cannot structured-clone `CryptoKey` — the exported private
+   JWK. Mitigation available **today**: pass `storage: "memory"` to keep the refresh token
+   and key out of IndexedDB for the lifetime of the page; the session then does not survive
+   a reload. No `sessionStorage` session backend is implemented, so it is not offered as a
+   mitigation here.
+
+## 12. External Validation Findings (v0.2.0)
+
+Audit of `src/core/dpop.ts`, `src/core/session.ts` and `src/core/client.ts`, plus the real
+provider run documented in `VALIDATION_REPORT.md`.
+
+| ID | Severity | Finding | Resolution |
+|---|---|---|---|
+| F1 | Medium (interop) | Real providers (solidcommunity.net, solidweb.me, CSS 7.3.0) publish a path-less issuer with a trailing slash. Exact string comparison rejected the discovery document when the caller typed the host without `/`. | **Fixed.** `issuerEquivalent()` accepts only the empty-path canonical variant and keeps the provider's spelling for every later comparison; paths/ports/schemes must still match exactly. Unit-tested. |
+| F2 | Medium | A refresh whose ID token failed validation (e.g. `webid` for a different user) left the unusable grant in storage and threw `SebaAuthError`, so every subsequent restore repeated the failure. | **Fixed, stricter.** `SessionManager` now clears storage and throws `SebaSessionExpiredError` when refresh-time ID token validation fails. Transport/JWKS errors still keep the record. Regression test added. |
+| F3 | Low (accepted) | A callback with a mismatched `state` throws `SebaAuthError` but leaves the pending transaction intact until its 10-minute expiry. | **Accepted.** The code is never exchanged, and the legitimate transaction stays usable. Clearing it would allow a page that can navigate the user to cancel an in-flight login. No token or identity is exposed either way. |
+| F4 | Informational | CSS 7.3.0 issues an ID token with string `aud` (no `"solid"`) and no `cnf`, contrary to Solid-OIDC §8.1. | **Not worked around.** Relaxing the audience or `cnf` requirement would remove Solid-specific audience restriction and proof-of-possession binding. The provider is non-conformant; SEBA refuses the session. |
+
+Audit checks that passed, with the mechanism:
+
+| Check | Result |
+|---|---|
+| New proof for every attempt | `SebaClient.fetch()` calls `createProof()` inside the attempt loop; `requestTokenResponse()` signs again on its nonce retry. No proof object is stored. |
+| `ath` only with an access token | `createDPoPProof` adds `ath` only when `input.accessToken !== undefined`; token-endpoint and revocation proofs omit it. |
+| `jti` uniqueness | 32 bytes from `crypto.getRandomValues` (256 bits), base64url, per proof. |
+| `state` validated before exchange | `parseAuthorizationResponse()` runs before any token request; mismatch throws before the exchange. |
+| `use_dpop_nonce` retry signs fresh | `requestTokenResponse()` loops and calls `signer.createProof({ nonce })` again; no cached proof. |
+| Refresh-token rotation | Returned refresh token overwrites the stored record with one IndexedDB `put`; concurrent refreshes collapse into one in-flight promise. |
+| `restoreSession()` fails closed on identity mismatch | Now clears storage and throws `SebaSessionExpiredError` (F2). |
+| No secrets in logs | `grep -rn "console\." src/` returns only `core/client.ts`'s `console.debug` of caller-supplied diagnostic messages (issuer, endpoint, WebID after success) and doc comments. No tokens, codes, verifiers, keys or proofs are logged. |
+
+Residual risk unchanged: XSS on the application origin can use the stored refresh token and
+key while the page is open; SEBA cannot prevent that.

package/VALIDATION_REPORT.md

@@ -0,0 +1,187 @@
+# VALIDATION_REPORT — SEBA v0.2.0
+
+Environment: Linux (container), Node.js v26.12.1, npm 12.2.1, Chrome 141 binary present
+(`/usr/bin/google-chrome-stable`), no Firefox/Safari binary. Network access to npm and the
+public Solid providers was available.
+
+This report records what was executed, not what was intended. Where a gate could not run,
+it is marked **BLOCKED** with the concrete reason.
+
+## Phase A — real provider validation
+
+### A.1 Local Community Solid Server 7.3.0
+
+Commands:
+
+```bash
+npx @solid/community-server@7.3.0 -c @css:config/file.json -f ./css-data -p 3000
+node scripts/validation/css-setup.mjs      # account + password login + pod
+CSS_EMAIL=… CSS_PASSWORD=… WEBID=… node scripts/validation/css-flow.mjs
+```
+
+The Client ID Document is served by the validation script at
+`http://localhost:8443/client-id.jsonld` with `redirect_uris:
+["http://localhost:3001/auth/callback"]`. Plain loopback HTTP is used instead of the
+suggested `mkcert` HTTPS endpoint because SEBA's Node callback server intentionally binds
+plain HTTP on loopback only; the document shape is otherwise the requested one (`@context`,
+`client_id`, `redirect_uris`, `client_name`, `scope`, `grant_types`).
+
+What passed:
+
+| Step | Result |
+|---|---|
+| Discovery | `GET /.well-known/openid-configuration` → 200; issuer `http://localhost:3000/` |
+| Client ID Document fetch by CSS | Accepted; authorization request reached the account interaction |
+| PKCE S256, `state`, `nonce` in authorization request | Accepted by CSS |
+| Interactive login / WebID selection / consent (driven through CSS's account JSON API) | Completed; CSS redirected to the callback with `code`, `state`, `iss=http://localhost:3000/` |
+| SEBA callback server | Received the callback, returned HTTP 200 |
+| Token request with DPoP proof | Accepted by CSS (no `invalid_dpop_proof`, no nonce challenge needed) |
+| Token response | `token_type: "DPoP"`, access token, refresh token, ID token |
+
+The ID token CSS actually issued (non-secret claims only, captured by the validation
+script):
+
+```json
+{
+  "iss": "http://localhost:3000/",
+  "aud": "http://localhost:8443/client-id.jsonld",
+  "azp": "http://localhost:8443/client-id.jsonld",
+  "webid": "http://localhost:3000/seba018213/profile/card#me",
+  "sub": "http://localhost:3000/seba018213/profile/card#me"
+}
+```
+
+SEBA then failed the login with:
+
+```
+SebaAuthError: The ID token audience does not include "solid".
+Solid-OIDC requires it when the provider advertises the webid scope.
+```
+
+Root cause: CSS 7.3.0 deviates from [Solid-OIDC §8.1](https://solidproject.org/TR/oidc).
+With the `webid` scope (which CSS itself advertises in `scopes_supported`), the spec
+requires:
+
+- `aud` to be an **array** that includes `azp` and the string `"solid"`;
+- a `cnf` claim with `jkt`.
+
+CSS emits a string `aud` containing only the client ID and emits no `cnf`. The same
+observation was reported to the Solid authentication panel long ago
+(solid/authentication-panel#135 discusses the strict audience requirement), but the current
+normative text has not changed.
+
+Decision: **do not relax the check.** Accepting an ID token without `"solid"` and `cnf`
+would remove the Solid-specific audience restriction and the proof-of-possession binding
+this library exists to enforce. The failure is in the provider, not in SEBA. Gate A.1 is
+therefore **BLOCKED** at the last step (post-token, pre-session) by provider
+non-conformance. Everything up to and including the DPoP token exchange was exercised
+against real CSS.
+
+Transcript files from the run: `/tmp/css-flow.out`, `/tmp/css-flow-noslash.out` (ephemeral,
+environment-local).
+
+### A.2 Public providers
+
+No account could be created on `solidcommunity.net`, `solidweb.org` or `solidweb.me`
+without an interactive browser session, an email address and (on some deployments) a
+CAPTCHA. No credentials were available to this environment, so the full login → fetch →
+restore → logout cycle did **not** run against any public provider. It is not marked as
+tested anywhere in this repository.
+
+What was executed instead, through SEBA's real discovery code
+(`node scripts/validation/public-discovery.mjs`):
+
+| Requested issuer | Discovery | Issuer returned | Revocation endpoint | `webid` advertised |
+|---|---|---|---|---|
+| `https://solidcommunity.net` | 200 | `https://solidcommunity.net/` | yes | yes |
+| `https://solidcommunity.net/` | 200 | `https://solidcommunity.net/` | yes | yes |
+| `https://solidweb.org` | 200 | `https://solidweb.org` | **no** | yes |
+| `https://solidweb.me` | 200 | `https://solidweb.me/` | yes | yes |
+| `http://localhost:3000` | 200 | `http://localhost:3000/` | yes | yes |
+
+This surfaced a real interoperability problem: two of the three providers publish an issuer
+with a trailing slash while users and documentation usually type the host without one, and
+SEBA's exact-string comparison rejected the document. Fixed — see Phase D finding F1.
+
+Gate A.2: **BLOCKED** (no public account; full cycle not executed). Discovery compatibility
+is proven, not authentication.
+
+## Phase B — browser validation
+
+- Chrome is installed, but Firefox and Safari are not present in this environment.
+- A browser end-to-end login against a real provider is blocked by A.1/A.2: the only local
+  real provider (CSS) fails ID token validation, and no public provider account exists.
+- No Playwright/Puppeteer run was performed. The built React example (Vite) and the browser
+  storage adapter (`fake-indexeddb` unit tests) are the only browser-adjacent evidence.
+
+Gate B.1: **BLOCKED** — Chrome + Firefox 5-step matrix not executed. Safari availability
+was never reached.
+
+### B.2 IndexedDB edge cases
+
+Not executed in a real browser. What the code does today, verified by unit tests or
+inspection:
+
+| Case | Behaviour | Evidence |
+|---|---|---|
+| Storage quota exceeded | `storage.save()` rejection is caught in `SessionManager.adopt` and only logged; the in-memory session stays usable. Refresh-rotation save failure is likewise non-fatal. | `tests/unit/session.test.ts` "keeps the session usable when storage fails" |
+| Corrupted pending-authorization JSON | Removed and treated as no pending login (`SebaAuthError` when a callback arrives). | `tests/unit/browser-storage.test.ts` |
+| Stored session from another client/version | Cleared, then `SebaAuthError`. | `tests/unit/session.test.ts` |
+| Unusable stored DPoP key | Cleared, then `SebaSessionExpiredError`. | `tests/unit/session.test.ts` |
+| Private/incognito IndexedDB failure | `openDB` rejection propagates while saving; `adopt` downgrades it to a debug message and keeps the memory session. A later `restoreSession()` sees nothing. No hang, but no typed error is surfaced to the caller because storage failure is intentionally non-fatal. | code inspection; not browser-executed |
+
+Gate B.2: **NOT EXECUTED in a browser**; no crash/hang was found by inspection or unit
+tests, but this gate is not claimed green.
+
+## Phase C — examples
+
+- `tsconfig.examples.json` added; `npm run typecheck` now runs both projects.
+- `npm run typecheck:examples` → 0 errors.
+- `npm run example:react:build` (`vite build`) → success, 79 modules.
+- Node example is env-driven and documented; React example has `index.html`, `main.tsx` and
+  `vite.config.ts`, with `clientId`/`redirectUri` documented in its comments and README.
+- Runtime against CSS remains blocked by A.1.
+
+Gate C.1: **PASS** (typechecked). Gate C.2: **PARTIAL** — build command works; the Node
+example cannot complete a login against CSS for the provider reason above.
+
+## Phase D — security audit
+
+See `SECURITY.md` §12 for the full table and accepted risks. Summary:
+
+- **F1 (real-provider incompatibility, fixed):** issuer with/without trailing slash.
+  `parseProviderConfiguration` now accepts only the empty-path canonical form and adopts the
+  provider's spelling; paths, ports and schemes still require exact equality. Not a
+  security weakening: the exact declared issuer is what is stored and compared afterwards.
+- **F2 (audit finding, fixed, stricter):** a refresh whose ID token fails validation (e.g.
+  different WebID) previously left the unusable grant in storage and threw `SebaAuthError`.
+  It now clears storage and throws `SebaSessionExpiredError`. New regression test added.
+- **F3 (audit finding, accepted):** a callback with a mismatched `state` throws
+  `SebaAuthError` without clearing the pending transaction. The code is never exchanged and
+  the legitimate transaction remains usable until its 10-minute expiry. Clearing it would
+  let any page that can navigate the user cancel an in-flight login; both behaviours fail
+  closed. Documented.
+- No proof reuse, no cached proofs, fresh `jti` per attempt, `ath` only on resource
+  requests, no tokens/keys logged.
+
+Gate D.1: zero unresolved high-severity findings; one medium fixed, one low accepted.
+
+## Phase E — release
+
+See `BUILD_REPORT.md` for the pasted gate output and package contents. Version 0.2.0 is a
+validation-and-hardening release, **not** a claim of production readiness: the public
+provider and browser gates are blocked, and no document in this repository says otherwise.
+
+## Definition-of-done checklist
+
+| Item | Status |
+|---|---|
+| Local CSS full cycle with transcript | **BLOCKED** — every step through DPoP token exchange succeeded; CSS 7.3.0 fails Solid-OIDC §8.1 ID token requirements |
+| At least one public provider full cycle | **BLOCKED** — no account could be created; discovery verified for three providers |
+| Chrome and Firefox 5-step browser check | **BLOCKED** — Firefox absent; real-provider login blocked; no browser automation run |
+| IndexedDB edge cases typed errors | **PARTIAL** — unit-covered; browser execution not performed |
+| Examples typechecked and documented | **PASS** |
+| Manual security audit of `dpop.ts`, `session.ts`, `client.ts` | **PASS** (findings in SECURITY.md §12) |
+| No document claims untested capability | **PASS** |
+| `npm pack --dry-run` output pasted in BUILD_REPORT | **PASS** |
+| `CHANGELOG.md` honest about validation | **PASS** |

package/dist/browser/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser entry point (`seba/browser`).
+ *
+ * Identical to the root entry point; browsers resolve the platform themselves. The
+ * subpath exists so bundlers can target a browser-only module graph.
+ */
+export * from "../index.js";
+export { createBrowserPlatform } from "./platform.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/browser/index.js

@@ -0,0 +1,9 @@
+/**
+ * Browser entry point (`seba/browser`).
+ *
+ * Identical to the root entry point; browsers resolve the platform themselves. The
+ * subpath exists so bundlers can target a browser-only module graph.
+ */
+export * from "../index.js";
+export { createBrowserPlatform } from "./platform.js";
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/browser/platform.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser platform: navigation-based login, IDB session storage, `sessionStorage`
+ * authorization state.
+ */
+import type { LoginOptions, Platform } from "../types.js";
+/**
+ * Create the platform used by `Seba` in browsers.
+ *
+ * @throws {@link SebaConfigError} when no browser `window`/`document` exists.
+ */
+export declare function createBrowserPlatform(): Platform;
+/** Re-exported for {@link Seba} type inference in browser-only builds. */
+export type { LoginOptions };
+//# sourceMappingURL=platform.d.ts.map

package/dist/browser/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/browser/platform.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAA2B,YAAY,EAAE,QAAQ,EAAsC,MAAM,aAAa,CAAC;AAUvH;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAqDhD;AAED,0EAA0E;AAC1E,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/browser/platform.js

@@ -0,0 +1,60 @@
+/**
+ * Browser platform: navigation-based login, IDB session storage, `sessionStorage`
+ * authorization state.
+ */
+import { SebaConfigError } from "../core/errors.js";
+import { memorySessionStorage } from "../core/storage.js";
+import { askForIdentity } from "./provider-modal.js";
+import { createIndexedDbStorage, createSessionStoragePendingAuthStore } from "./storage.js";
+/** Query parameters produced by an authorization response. */
+const CALLBACK_PARAMS = ["code", "state", "iss", "error", "error_description", "error_uri", "session_state"];
+/** How long a browser waits for navigation before reporting that it did not happen. */
+const NAVIGATION_GRACE_MS = 1_500;
+/**
+ * Create the platform used by `Seba` in browsers.
+ *
+ * @throws {@link SebaConfigError} when no browser `window`/`document` exists.
+ */
+export function createBrowserPlatform() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        throw new SebaConfigError("The browser entry point requires a DOM. Import \"seba\" in a browser or \"seba/node\" in Node.js.");
+    }
+    return {
+        kind: "browser",
+        defaultStorage: "indexeddb",
+        fetch: (input, init) => globalThis.fetch(input, init),
+        currentUrl: () => new URL(window.location.href),
+        pendingAuth: createSessionStoragePendingAuthStore(),
+        selectIdentity: () => askForIdentity(),
+        createStorage(kind) {
+            if (kind === "memory") {
+                return memorySessionStorage();
+            }
+            return createIndexedDbStorage();
+        },
+        async beginInteractiveLogin(request) {
+            const target = new URL(request.redirectUri);
+            const before = window.location.href;
+            window.location.assign(request.authorizationUrl);
+            return new Promise((_resolve, reject) => {
+                if (before.startsWith(target.origin) && window.location.href !== before) {
+                    // Navigation already happened; the page is unloading.
+                    return;
+                }
+                window.setTimeout(() => {
+                    reject(new SebaConfigError("The browser did not navigate to the identity provider. " +
+                        "A popup blocker or a sandboxed iframe can prevent navigation; open the page in a top-level tab."));
+                }, NAVIGATION_GRACE_MS);
+            });
+        },
+        clearCallback() {
+            const url = new URL(window.location.href);
+            for (const name of CALLBACK_PARAMS) {
+                url.searchParams.delete(name);
+            }
+            const query = url.searchParams.toString();
+            window.history.replaceState({}, document.title, `${url.pathname}${query === "" ? "" : `?${query}`}${url.hash}`);
+        },
+    };
+}
+//# sourceMappingURL=platform.js.map

package/dist/browser/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/browser/platform.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,oCAAoC,EAAE,MAAM,cAAc,CAAC;AAE5F,8DAA8D;AAC9D,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;AAE7G,uFAAuF;AACvF,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACrE,MAAM,IAAI,eAAe,CACvB,mGAAmG,CACpG,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,cAAc,EAAE,WAAW;QAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC;QACrD,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/C,WAAW,EAAE,oCAAoC,EAAE;QACnD,cAAc,EAAE,GAAG,EAAE,CAAC,cAAc,EAAE;QACtC,aAAa,CAAC,IAAiB;YAC7B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtB,OAAO,oBAAoB,EAAE,CAAC;YAChC,CAAC;YACD,OAAO,sBAAsB,EAAE,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,qBAAqB,CAAC,OAAgC;YAC1D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YACpC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAEjD,OAAO,IAAI,OAAO,CAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;gBAC3C,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBACxE,sDAAsD;oBACtD,OAAO;gBACT,CAAC;gBACD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE;oBACrB,MAAM,CACJ,IAAI,eAAe,CACjB,yDAAyD;wBACvD,iGAAiG,CACpG,CACF,CAAC;gBACJ,CAAC,EAAE,mBAAmB,CAAC,CAAC;YAC1B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,aAAa;YACX,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC1C,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;gBACnC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;YACD,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;YAC1C,MAAM,CAAC,OAAO,CAAC,YAAY,CACzB,EAAE,EACF,QAAQ,CAAC,KAAK,EACd,GAAG,GAAG,CAAC,QAAQ,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,CAC/D,CAAC;QACJ,CAAC;KACiB,CAAC;AACvB,CAAC"}

package/dist/browser/provider-modal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal, dependency-free identity prompt for browsers.
+ *
+ * The dialog asks for a WebID by default and offers an identity-provider URL instead.
+ * It is only a hint: whatever the user enters is validated and discovered by the core.
+ */
+import type { LoginOptions } from "../types.js";
+/**
+ * Ask the user which WebID or identity provider to use.
+ *
+ * @returns Login options collected from the dialog.
+ * @throws {@link SebaAuthError} when the user cancels or the dialog cannot be shown.
+ */
+export declare function askForIdentity(): Promise<LoginOptions>;
+//# sourceMappingURL=provider-modal.d.ts.map

package/dist/browser/provider-modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-modal.d.ts","sourceRoot":"","sources":["../../src/browser/provider-modal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC,CA4HtD"}