@gaballahtech/seba 0.0.0-stage → 0.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,242 @@
+# ARCHITECTURE
+
+## 1. System overview
+
+SEBA is a single npm package with three entry points over one implementation:
+
+```
+                 ┌──────────────────────────────┐
+   seba          │  src/index.ts  (public API)  │
+                 └──────────────┬───────────────┘
+                    ┌───────────┴────────────┐
+                    │  src/seba.ts  (Seba)   │  4 public methods, lazy runtime binding
+                    └───────────┬────────────┘
+                                │
+                 ┌──────────────▼───────────────┐
+                 │  src/core/client.ts          │  protocol orchestration, platform-agnostic
+                 └──┬────────┬────────┬─────────┘
+        ┌───────────┘        │        └─────────────┐
+┌───────▼──────┐  ┌──────────▼───────┐  ┌──────────▼─────────┐
+│ identity.ts  │  │ discovery.ts     │  │ oidc.ts            │
+│ Client ID    │  │ OP metadata      │  │ PKCE, state, nonce │
+│ WebID        │  │ issuer checks    │  │ callback, tokens   │
+└──────────────┘  └──────────────────┘  └──────────┬─────────┘
+                                                   │
+                                   ┌───────────────▼──────────┐
+                                   │ dpop.ts   session.ts     │
+                                   │ proofs    storage/refresh│
+                                   └───────────────┬──────────┘
+                                                   │ Platform interface
+                        ┌──────────────────────────┴─────────────────────────┐
+              ┌─────────▼──────────┐                            ┌────────────▼─────────┐
+              │ browser/platform   │                            │ node/platform        │
+              │ sessionStorage,    │                            │ memory pending auth, │
+              │ IndexedDB, DOM     │                            │ loopback HTTP server │
+              └────────────────────┘                            └──────────────────────┘
+```
+
+`src/core/client.ts` contains **all** protocol sequencing exactly once. Browser and Node
+differences are confined to the `Platform` interface (`src/types.ts`): how a callback URL
+is obtained, where pending authorization state lives, and which storage backend is the
+default. There is no second code path for "Node login"; the same validation runs for both.
+
+## 2. Core module responsibilities
+
+| Module | Responsibility | Deliberately not responsible for |
+|---|---|---|
+| `core/errors.ts` | Error hierarchy with stable `code` values. | Deciding retry policy. |
+| `core/http.ts` | JSON/text fetching with content-type checks, `SebaNetworkError` mapping, non-2xx handling, timeout. | Auth headers (callers add them). |
+| `core/identity.ts` | Client ID Document fetch/validation, exact redirect-URI membership, WebID URL handling, Turtle-subset + JSON-LD + `Link` issuer extraction. | Trusting any value it parsed (issuer is re-validated). |
+| `core/discovery.ts` | Issuer validation, well-known lookup, OP metadata validation. | Assuming optional metadata exists. |
+| `core/oidc.ts` | PKCE, `state`, `nonce`, authorization URL, callback parsing/validation, code exchange, token-response parsing, ID token validation, WebID extraction. | Storing anything. |
+| `core/dpop.ts` | ES256 key generation/import, proof signing, `jti`, `htu`, `ath`, thumbprints, nonce plumbing. | Caching proofs (forbidden). |
+| `core/session.ts` | The active session record, refresh with rotation, revocation, logout cleanup, restore. | Deciding whether to redirect the user, storage engines. |
+| `core/storage.ts`, `browser/storage.ts` | Memory adapters (Node.js, tests) and IndexedDB/`sessionStorage` adapters (browser). | Protocol decisions. |
+| `core/client.ts` | The four operations, fetch retry/redirect policy, in-memory access token, last-seen DPoP nonce, debug logging. | Any DOM or `node:` API. |
+| `seba.ts` | Public `Seba` class with the four documented methods; binds a runtime platform lazily on first use. | Protocol details. |
+
+## 3. Browser architecture
+
+`src/browser/platform.ts` supplies:
+
+- `currentUrl()` → `new URL(window.location.href)`.
+- `pendingAuth` → one `sessionStorage` record under `seba.pending-authorization`
+  (the record itself carries `clientId` and `redirectUri`, which are re-checked on the
+  callback). The PKCE verifier and expected nonce never leave the tab and never appear in
+  a URL.
+- `beginInteractiveLogin()` → `window.location.assign(authorizationUrl)`; the returned
+  promise intentionally never settles, because the document is being replaced.
+- `selectIdentity()` → the vanilla DOM provider selector in `browser/provider-modal.ts`
+  (focus trap, `Esc` to close, `Enter` to submit, WebID or custom issuer input, no password
+  field, no network calls).
+- `createStorage("indexeddb")` → `idb`-backed adapter; `"memory"` → process memory.
+- `clearCallback()` → `history.replaceState` to remove `code`/`state`/`iss` from the
+  address bar after the callback has been consumed.
+
+Login lifecycle in a browser (documented in `README.md`):
+
+1. Application calls `login()`. There is no callback in the URL, so SEBA discovers the
+   provider, stores pending state in `sessionStorage`, and navigates away.
+2. The provider authenticates the user and redirects to `redirectUri?code=…&state=…&iss=…`.
+3. The application calls `login()` again on that page. SEBA recognises the callback,
+   validates `state`, `iss`, `nonce`, PKCE and the ID token, stores the refresh token and
+   key, keeps the access token in memory, returns the `Session`.
+
+Because step 1 unloads the page, its promise never resolves; this is documented rather
+than papered over with polling or `BroadcastChannel` tricks.
+
+`src/browser/index.ts` is the `@gaballahtech/seba/browser` entry point: it re-exports the public API and
+`createBrowserPlatform`.
+
+## 4. Node.js architecture
+
+`src/node/platform.ts`:
+
+- `currentUrl()` → `null` (no document).
+- `pendingAuth` → an in-process record; no browser storage API is referenced anywhere in
+  `src/node/`.
+- `beginInteractiveLogin()` →
+  1. parse the configured `redirectUri`; require `http:` and a loopback host
+     (`127.0.0.1`, `::1`, `localhost`) — never bind `0.0.0.0`;
+  2. `node:http` server on that host and port, only answering the registered path;
+  3. call `openAuthorizationUrl(authorizationUrl)` (required; otherwise
+     `SebaNoUIError` — thrown *before* the server is started);
+  4. respond with a small HTML page that contains no secrets and close the listener
+     completely before resolving the login promise, so the port is free for the next login
+     and no late request can reach a closed transaction;
+  5. reject after a five-minute timeout and close the listener the same way.
+- `createStorage()` → memory only; `"indexeddb"` throws `SebaConfigError` with an
+  actionable message instead of pretending a browser store exists.
+
+Provider and resource calls use the runtime's global `fetch` through `core/http.ts`, which
+adds an abort-based 10-second timeout and maps transport failures to `SebaNetworkError`.
+`src/node/index.ts` is the `@gaballahtech/seba/node` entry point: it re-exports the public API and
+`createNodePlatform`.
+
+The configured `redirectUri` must still be published by the Client ID Document, so a
+loopback URI must appear in `redirect_uris`; otherwise `SebaRedirectMismatchError` is
+thrown before any listener is opened.
+
+## 5. Authentication flow
+
+```
+login(options)
+  │
+  ├─ callback present & pending state found? ──yes──► completeLogin()
+  │                                                   ├ state exact match
+  │                                                   ├ RFC 9207 `iss` == pending issuer
+  │                                                   ├ error param? → SebaAuthError
+  │                                                   ├ POST token endpoint (fresh DPoP proof, no ath)
+  │                                                   ├ token_type == DPoP
+  │                                                   ├ validate ID token (JWKS, iss, aud, azp, exp, iat, nonce)
+  │                                                   ├ cnf.jkt == our thumbprint (and required for `webid`)
+  │                                                   ├ webId == requested webId (when given)
+  │                                                   ├ persist {refresh_token, key, webId, issuer, clientId}
+  │                                                   └ keep access token in memory → Session
+  │
+  └─ no callback
+       ├ issuer = options.issuer ?? discoverIssuerForWebId(options.webId) ?? platform.selectIdentity()
+       ├ loadClientIdDocument(clientId) → redirect URI must be listed exactly
+       ├ discoverProvider(issuer)
+       ├ create PKCE verifier/challenge, state, nonce → PendingAuthorization
+       ├ build authorization URL (response_type=code, scope=openid webid offline_access,
+       │   code_challenge_method=S256, nonce, state, client_id)
+       ├ platform.beginInteractiveLogin(...)  → browser: navigate away
+       │                                      → node: loopback callback URL
+       └ completeLogin(callbackUrl)
+```
+
+## 6. Session lifecycle
+
+```
+(no session) ──login──► { accessToken (memory), refreshToken (storage), key (storage) }
+                              │
+                    access token expires / 401 invalid_token
+                              ▼
+                     refresh (grant_type=refresh_token, fresh proof)
+                              │ rotation: persist new refresh token atomically
+                              ▼
+                        new access token in memory
+                              │
+                    restoreSession() on reload: load record → refresh → Session
+                              │ record missing → null
+                              │ invalid_grant → clear storage + SebaSessionExpiredError
+                              │ 5xx / offline → SebaNetworkError, record kept
+                              ▼
+                     logout(): clear memory → revoke (best effort) → delete record
+```
+
+The persisted record (`PersistedSession`) is the only durable state:
+`version`, `webId`, `provider`, `clientId`, `refreshToken`, `key`
+(`CryptoKey` + public JWK, or exported JWK), optional `scope`, `createdAt`.
+**No access token field exists in the type**, so it cannot be persisted by accident.
+
+Refresh is serialized through a single in-flight promise in `core/session.ts`, so ten
+concurrent `fetch()` calls that all see an expired token perform one refresh, not ten
+(rotating refresh tokens would otherwise invalidate each other).
+
+## 7. DPoP lifecycle
+
+1. **Generation** at login: ES256/P-256 via `jose.generateKeyPair`. Non-extractable private
+   key when the runtime can structured-clone `CryptoKey` (probed with `structuredClone`);
+   otherwise an extractable key exported to JWK and stored as such (reported in
+   `SECURITY.md`).
+2. **Signing** per attempt: `{typ: "dpop+jwt", alg: "ES256", jwk: publicJwk}` with
+   `{jti, htm, htu, iat}` plus `ath` only when an access token is presented, plus `nonce`
+   when the server supplied one.
+3. **No persistence of proofs.** `createDPoPProof()` is pure: inputs in, one JWT out. It is
+   called once per HTTP attempt, including retries (`nonce` challenge, token refresh,
+   redirect hop).
+4. **Nonce handling**: `core/client.ts` keeps the most recent `DPoP-Nonce` returned by a
+   protected resource and sends it with subsequent proofs. A nonce is server state, not a
+   proof; caching it is explicitly allowed by RFC 9449. Token requests handle their own
+   `use_dpop_nonce` challenge in `core/oidc.ts`.
+5. **Binding**: the key pair stays with the session record; the ID token's `cnf.jkt` and
+   the access token's binding are checked against its thumbprint.
+
+## 8. Storage architecture
+
+| Runtime | Default | Record location | Access token |
+|---|---|---|---|
+| Browser | `indexeddb` | DB `seba`, object store `session`, single record key `current` | memory only |
+| Browser (`storage: "memory"`) | opt-in | module-level map | memory only |
+| Node.js | `memory` | process memory | memory only |
+
+`sessionStorage` holds **only** the pending authorization transaction
+(`state`, `code_verifier`, `nonce`, `issuer`, `clientId`, `redirectUri`, `createdAt`,
+optional `webId`) and is deleted as soon as the callback is processed. `localStorage` is
+never used. IndexedDB writes are whole-record `put`s, which makes refresh-token rotation a
+single atomic overwrite.
+
+## 9. Public API design
+
+```ts
+class Seba {
+  constructor(config: SebaConfig)
+  login(options?: LoginOptions): Promise<Session>
+  restoreSession(): Promise<Session | null>
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+  logout(): Promise<void>
+}
+```
+
+Exactly four public methods. `Session` carries `webId`, `isLoggedIn: true`, `provider` and
+no tokens. Tokens, keys and proofs are never exported from the package root. Configuration
+is validated when the first operation runs (`SebaConfigError`); there are no
+proof-caching or TTL knobs.
+
+`Seba` binds its platform on first use (dynamic import of `browser/platform.js` when
+`window`/`document` exist, otherwise `node/platform.js`), which keeps `node:http` out of
+browser bundles and DOM code out of Node.
+
+## 10. Architectural trade-offs
+
+| Trade-off | Choice | Consequence |
+|---|---|---|
+| Redirect lifecycle vs. promise ergonomics | `login()`'s promise does not settle when navigation happens | Applications must call `login()` again on the callback page; documented with code. |
+| No proof cache | Re-sign every attempt | Slight CPU cost per request (one ECDSA signature); replay protection stays intact. |
+| `redirect: "manual"` everywhere | Never re-attach credentials on redirects | Browsers surface redirects to the app instead of following them. |
+| Custom Turtle subset | ~200 lines instead of an RDF dependency | Documented, tested subset + JSON-LD + `Link` fallback; unsupported syntax fails loudly. |
+| Static client identity | No DCR | One published JSON-LD file must list every redirect URI. |
+| Loopback-only Node login | Real HTTP callback | Requires `openAuthorizationUrl`; impossible flows fail with `SebaNoUIError`. |
+| `cnf.jkt` requirement gated on advertised `webid` scope | Interoperable and strict | Providers that do not advertise `webid` get standard OIDC validation only. |

package/BUILD_REPORT.md

@@ -0,0 +1,195 @@
+# BUILD_REPORT — seba 0.2.0
+
+Date: 2026-11-05
+Environment: Linux container, Node.js v26.12.1, npm 12.2.1, TypeScript 5.9.3, Vitest 5.1.0,
+Vite 8.3.6. Chrome binary present; no Firefox/Safari.
+
+## 1. Gate results (actual, in the required order)
+
+| Gate | Command | Exit | Result |
+|---|---|---|---|
+| Install | `npm install` | 0 | 0 vulnerabilities |
+| Typecheck | `npm run typecheck` = `tsc --noEmit && tsc -p tsconfig.examples.json` | 0 | No errors in `src/`, `tests/` or `examples/` |
+| Tests | `npm test` | 0 | 9 files, **123/123** tests passed |
+| Build | `npm run build` | 0 | `dist/` emitted |
+| Pack | `npm pack --dry-run` | 0 | `seba-0.2.0.tgz`, 86 files, 97.8 kB packed, 373.7 kB unpacked |
+
+Test summary as printed:
+
+```
+ Test Files  9 passed (9)
+      Tests  123 passed (123)
+```
+
+Coverage changed since 0.1.0: discovery gained three issuer-canonicalization tests and the
+session suite's "different WebID on refresh" test now expects the stricter
+`SebaSessionExpiredError` + cleared storage behaviour.
+
+## 2. `npm pack --dry-run` output
+
+Captured from the final gate run (the listing was taken immediately before this report's
+last wording change, so this file's own byte count differs by less than 1 kB; the pack was
+re-run after writing it and again included `BUILD_REPORT.md` and exited 0):
+
+```
+npm notice 📦  seba@0.2.0
+npm notice Tarball Contents
+npm notice 15.6kB ARCHITECTURE.md
+npm notice 6.1kB BUILD_REPORT.md
+npm notice 3.1kB CHANGELOG.md
+npm notice 1.1kB LICENSE
+npm notice 10.7kB README.md
+npm notice 11.7kB RESEARCH.md
+npm notice 16.9kB SECURITY.md
+npm notice 10.1kB VALIDATION_REPORT.md
+npm notice 325B dist/browser/index.d.ts
+npm notice 191B dist/browser/index.d.ts.map
+npm notice 323B dist/browser/index.js
+npm notice 189B dist/browser/index.js.map
+npm notice 517B dist/browser/platform.d.ts
+npm notice 282B dist/browser/platform.d.ts.map
+npm notice 2.8kB dist/browser/platform.js
+npm notice 2.1kB dist/browser/platform.js.map
+npm notice 609B dist/browser/provider-modal.d.ts
+npm notice 255B dist/browser/provider-modal.d.ts.map
+npm notice 5.6kB dist/browser/provider-modal.js
+npm notice 4.1kB dist/browser/provider-modal.js.map
+npm notice 1.4kB dist/browser/storage.d.ts
+npm notice 526B dist/browser/storage.d.ts.map
+npm notice 4.3kB dist/browser/storage.js
+npm notice 3.2kB dist/browser/storage.js.map
+npm notice 2.1kB dist/core/client.d.ts
+npm notice 630B dist/core/client.d.ts.map
+npm notice 15.3kB dist/core/client.js
+npm notice 12.3kB dist/core/client.js.map
+npm notice 3.8kB dist/core/discovery.d.ts
+npm notice 900B dist/core/discovery.d.ts.map
+npm notice 11.5kB dist/core/discovery.js
+npm notice 7.0kB dist/core/discovery.js.map
+npm notice 2.4kB dist/core/dpop.d.ts
+npm notice 979B dist/core/dpop.d.ts.map
+npm notice 5.8kB dist/core/dpop.js
+npm notice 4.7kB dist/core/dpop.js.map
+npm notice 3.5kB dist/core/errors.d.ts
+npm notice 1.5kB dist/core/errors.d.ts.map
+npm notice 3.7kB dist/core/errors.js
+npm notice 2.1kB dist/core/errors.js.map
+npm notice 3.0kB dist/core/http.d.ts
+npm notice 1.1kB dist/core/http.d.ts.map
+npm notice 4.6kB dist/core/http.js
+npm notice 3.0kB dist/core/http.js.map
+npm notice 6.1kB dist/core/identity.d.ts
+npm notice 2.0kB dist/core/identity.d.ts.map
+npm notice 28.3kB dist/core/identity.js
+npm notice 23.5kB dist/core/identity.js.map
+npm notice 6.4kB dist/core/oidc.d.ts
+npm notice 3.1kB dist/core/oidc.d.ts.map
+npm notice 18.3kB dist/core/oidc.js
+npm notice 14.1kB dist/core/oidc.js.map
+npm notice 4.8kB dist/core/session.d.ts
+npm notice 1.9kB dist/core/session.d.ts.map
+npm notice 13.7kB dist/core/session.js
+npm notice 9.7kB dist/core/session.js.map
+npm notice 1.0kB dist/core/storage.d.ts
+npm notice 401B dist/core/storage.d.ts.map
+npm notice 1.4kB dist/core/storage.js
+npm notice 891B dist/core/storage.js.map
+npm notice 706B dist/index.d.ts
+npm notice 443B dist/index.d.ts.map
+npm notice 279B dist/index.js
+npm notice 286B dist/index.js.map
+npm notice 317B dist/node/index.d.ts
+npm notice 188B dist/node/index.d.ts.map
+npm notice 315B dist/node/index.js
+npm notice 186B dist/node/index.js.map
+npm notice 1.2kB dist/node/platform.d.ts
+npm notice 331B dist/node/platform.d.ts.map
+npm notice 7.2kB dist/node/platform.js
+npm notice 4.7kB dist/node/platform.js.map
+npm notice 1.6kB dist/seba.d.ts
+npm notice 542B dist/seba.d.ts.map
+npm notice 2.1kB dist/seba.js
+npm notice 1.2kB dist/seba.js.map
+npm notice 10.8kB dist/types.d.ts
+npm notice 4.3kB dist/types.d.ts.map
+npm notice 274B dist/types.js
+npm notice 115B dist/types.js.map
+npm notice 2.2kB examples/node/index.ts
+npm notice 3.7kB examples/react/App.tsx
+npm notice 299B examples/react/index.html
+npm notice 319B examples/react/main.tsx
+npm notice 644B examples/react/vite.config.ts
+npm notice 1.9kB package.json
+npm notice Tarball Details
+npm notice name: seba
+npm notice version: 0.2.0
+npm notice filename: seba-0.2.0.tgz
+npm notice package size: 97.8 kB
+npm notice unpacked size: 373.7 kB
+npm notice total files: 86
+```
+
+The tarball contains `README.md`, `CHANGELOG.md`, `BUILD_REPORT.md`, `SECURITY.md`,
+`VALIDATION_REPORT.md`, `dist/` and `examples/`. It contains **no** `node_modules`, no test
+files or fixtures, and no `css-data` directory. The generated `examples/react/dist` bundle
+was removed before this run; the React example ships as sources plus its Vite config.
+
+## 2b. v0.2.0 external validation status
+
+> **v0.2.0 external validation status:**
+> - Local CSS 7.3.0: login **fails at ID token validation** due to CSS non-compliance (see CSS_ISSUE.md). Seba's rejection is correct per Solid-OIDC §8.1.
+> - Public providers: discovery tested against `solidcommunity.net`, `solidweb.org`, `solidweb.me`. Full cycle not completed (account creation requires interactive browser). Trailing-slash issuer bug fixed.
+> - Browsers: unit tests for browser storage pass; no real-browser E2E performed.
+> - This release is **not** claimed production-ready. See `VALIDATION_REPORT.md`.
+
+Upstream report: https://github.com/CommunitySolidServer/CommunitySolidServer/issues/2295
+
+## 3. External validation summary
+
+Full transcripts, error messages and blockers are in `VALIDATION_REPORT.md`.
+
+- **Community Solid Server 7.3.0 (real):** discovery, Client ID Document fetch,
+  PKCE/state/nonce, account/WebID/consent interaction, callback, and the DPoP token request
+  all succeeded. The login is rejected at ID token validation because CSS issues
+  `aud` as a string containing only the client ID (no `"solid"`) and no `cnf` claim;
+  Solid-OIDC §8.1 requires an array with `"solid"` and a `cnf` binding. The library was not
+  weakened to accommodate a non-conformant provider.
+- **Public providers:** discovery through SEBA's real code succeeded for
+  `solidcommunity.net` (issuer `https://solidcommunity.net/`), `solidweb.org` (issuer
+  `https://solidweb.org`, no revocation endpoint) and `solidweb.me` (issuer
+  `https://solidweb.me/`). No account could be created, so no public full cycle is claimed.
+- **Browser:** not executed. Chrome is installed but Firefox/Safari are not, and a real
+  provider login is blocked as above. No browser matrix is claimed green.
+- **Examples:** `tsc -p tsconfig.examples.json` and `vite build` succeed; runtime login is
+  blocked by the provider issue.
+
+## 4. Changes made because of validation
+
+1. **Issuer canonicalization** (`src/core/discovery.ts`): accept the empty-path
+   trailing-slash form of a path-less issuer and adopt the provider's exact spelling for
+   all later comparisons. Motivated by real providers (solidcommunity.net, solidweb.me,
+   CSS). Paths, ports, schemes and query strings still require exact equality. Three tests
+   added.
+2. **Refresh identity mismatch is terminal** (`src/core/session.ts`): refresh-time ID token
+   validation failure now clears storage and throws `SebaSessionExpiredError` instead of
+   leaving an unusable grant. Stricter; regression test updated.
+3. **Examples in the typecheck graph** (`tsconfig.examples.json`, package scripts), plus
+   runnable Vite scaffolding for the React example and an env-driven Node example.
+4. Docs reconciled with reality: provider compatibility table, security audit findings,
+   validation report, changelog, version 0.2.0.
+
+## 5. Still unvalidated (explicit)
+
+- Full login → fetch → restore → logout against any public provider (no account).
+- Any real-browser run (no Firefox; no provider login that reaches a session).
+- Safari `CryptoKey` persistence and private-browsing IndexedDB behaviour.
+- IndexedDB quota-exceeded and corrupted-record handling in a real browser (unit-covered,
+  not browser-executed).
+- Real pod resource access with a provider-issued access token (blocked at ID token).
+- No automated accessibility audit of the browser dialog.
+
+## 6. Release notes
+
+Version bumped to `0.2.0`. This is a validation release with one interop fix and one
+security hardening change; it is **not** “production ready” in the sense of having passed
+real-provider and browser gates, and no document here claims that.

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## [0.2.0] — 2026-11-05
+
+External validation and hardening release. This is not a claim of production readiness; the
+gates that could not run are listed explicitly.
+
+### Fixed because of external validation
+
+- **Issuer canonicalization.** Real providers publish path-less issuers with a trailing
+  slash (`https://solidcommunity.net/`, `https://solidweb.me/`, Community Solid Server's
+  `http://localhost:3000/`). SEBA required byte-identical strings and rejected the document
+  when the caller typed the host without the slash. Discovery now accepts that one
+  canonical form and adopts the provider's exact spelling for all later comparisons;
+  paths, ports, schemes and query strings still require exact equality. Verified against
+  solidcommunity.net, solidweb.org, solidweb.me and CSS 7.3.0.
+
+### Fixed from the manual security audit
+
+- A refresh whose ID token fails validation (including a WebID that differs from the stored
+  session) now clears the stored grant and throws `SebaSessionExpiredError`. It previously
+  kept the unusable record and threw `SebaAuthError`, which would repeat the failure on
+  every restore. Stricter, covered by a regression test.
+
+### Added
+
+- `tsconfig.examples.json`; `npm run typecheck` now typechecks `examples/` as well.
+- `npm run typecheck:examples`, `npm run example:react:build`, `npm run validate:discovery`.
+- Runnable React example scaffolding (`examples/react/index.html`, `main.tsx`,
+  `vite.config.ts`) and an env-driven Node example.
+- `scripts/validation/css-setup.mjs` and `css-flow.mjs`: a reproducible real-provider flow
+  against a local Community Solid Server, including the account/pod setup and the browser
+  interaction driven through CSS's JSON API.
+- `scripts/validation/public-discovery.mjs`: discovery checks against public providers.
+- `VALIDATION_REPORT.md`, this changelog, and a "Provider Compatibility" table in README.
+
+### Validated externally
+
+- Community Solid Server 7.3.0: discovery, Client ID Document fetch, PKCE/state/nonce
+  authorization, consent, callback, DPoP token request and token response all succeeded.
+  Login stops at ID token validation because CSS emits a string `aud` without `"solid"` and
+  no `cnf` claim, which Solid-OIDC §8.1 requires.
+- solidcommunity.net, solidweb.org and solidweb.me: discovery and issuer handling verified
+  through SEBA's real discovery code; the first two publish trailing-slash issuers, which
+  exposed the normalization bug fixed above.
+- One real CSS failure was caused by **provider non-compliance**, not by Seba: CSS 7.3.0
+  emits `id_token.aud` as a string without `"solid"` and omits `cnf.jkt`, contrary to
+  Solid-OIDC §8.1. The failure is documented in `CSS_ISSUE.md` and reported upstream.
+
+### Not validated (explicitly)
+
+- No full login → fetch → restore → logout cycle against any public provider: creating an
+  account requires an interactive browser, email and, on some deployments, a CAPTCHA.
+- No browser end-to-end run. Chrome is installed, Firefox/Safari are not. The 5-step browser
+  matrix was not executed.
+- Safari `CryptoKey` persistence and IndexedDB private-browsing behaviour were not executed.
+- IndexedDB quota-exceeded and corrupted-record behaviour in a real browser was not
+  executed; the unit tests cover the adapter and the failure paths.
+- No real pod resource was fetched with a CSS-issued token (blocked by the ID token issue).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SEBA contributors
+
+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.