@gaballahtech/seba 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,283 @@
-# Temporary Holding Version
+# SEBA
 
-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.
+Solid-OIDC authentication in four calls: `login`, `restoreSession`, `fetch`, `logout`.
+
+SEBA implements the Solid-OIDC authorization-code flow with PKCE, DPoP-bound tokens and a
+static Client ID Document. It runs in browsers (IndexedDB session storage, redirect-based
+login) and in Node.js (in-memory storage, real loopback callback server). The public API is
+the same in both.
+
+- No dynamic client registration. Your published Client ID Document is the `client_id`.
+- Access tokens live in memory only; the refresh token and DPoP key are the only secrets
+  persisted.
+- A brand-new DPoP proof is signed for every single attempt. There is no proof cache and no
+  option to add one.
+- Every incoming value is validated: `state`, RFC 9207 `iss`, `nonce`, PKCE S256, ID token
+  signature, `iss`, `aud`, `azp`, `exp`/`iat`, and `cnf.jkt` binding.
+
+## Requirements
+
+- Node.js 20 or newer, or any browser with Web Crypto (ES256), `fetch` and IndexedDB.
+- A publicly dereferenceable **Solid Client ID Document** served over HTTPS.
+
+## Install
+
+```bash
+npm install @gaballahtech/seba
+```
+
+## Publish a Client ID Document
+
+Host a JSON-LD document and use its URL as `clientId`. The `client_id` member must equal the
+document URL, and every callback you use must be listed verbatim.
+
+```json
+{
+  "@context": ["https://www.w3.org/ns/solid/oidc-context.jsonld"],
+  "client_id": "https://app.example/client-id.jsonld",
+  "redirect_uris": [
+    "https://app.example/auth/callback",
+    "http://127.0.0.1:3000/auth/callback"
+  ],
+  "client_name": "My Solid App"
+}
+```
+
+No `registration_endpoint` is ever called; `client_secret` is not used.
+
+## Browser
+
+```ts
+import { Seba } from "@gaballahtech/seba";
+
+const seba = new Seba({
+  clientId: "https://app.example/client-id.jsonld",
+  redirectUri: "https://app.example/auth/callback",
+});
+```
+
+Call `login()` on the page that handles the callback, as well as on the page that starts it:
+
+```ts
+// Runs on every load of the callback route.
+const session = await seba.login({ webId: "https://alice.example/profile/card#me" });
+```
+
+- Without an authorization response in the URL, `login()` stores the PKCE verifier in
+  `sessionStorage` and navigates to the provider. **That promise never settles**, because
+  the document is replaced.
+- When the provider redirects back with `?code=…&state=…&iss=…`, the same call validates the
+  response, exchanges the code, stores the refresh token and DPoP key in IndexedDB, keeps the
+  access token in memory, removes the callback parameters from the address bar, and resolves
+  with the session.
+
+On later page loads:
+
+```ts
+const session = (await seba.restoreSession()) ?? (await seba.login());
+```
+
+`login()` with no arguments opens a small built-in dialog asking for a WebID or an identity
+provider URL. Pass `{ webId }` or `{ issuer }` to skip it.
+
+### React
+
+See [`examples/react/App.tsx`](examples/react/App.tsx).
+
+## Node.js
+
+Node has no document, so `login()` starts a temporary HTTP server on the loopback interface
+from `redirectUri` and waits for the provider to redirect back. The redirect URI must use
+plain `http` on `127.0.0.1`, `::1` or `localhost`, and must be published in the Client ID
+Document.
+
+```ts
+import { exec } from "node:child_process";
+import { Seba } from "@gaballahtech/seba/node";
+
+const seba = new Seba({
+  clientId: "https://app.example/client-id.jsonld",
+  redirectUri: "http://127.0.0.1:3000/auth/callback",
+  openAuthorizationUrl(url) {
+    exec(`xdg-open "${url}"`); // or `open` on macOS, `start` on Windows
+  },
+});
+
+const session = (await seba.restoreSession()) ?? (await seba.login({ issuer: "https://idp.example" }));
+const response = await seba.fetch(session.webId);
+console.log(await response.text());
+
+await seba.logout();
+```
+
+Without `openAuthorizationUrl`, `login()` throws `SebaNoUIError` instead of hanging. Node
+storage is in memory, so a process restart requires a new login.
+
+See [`examples/node/index.ts`](examples/node/index.ts).
+
+## API
+
+### `new Seba(config)`
+
+| Option | Required | Description |
+|---|---|---|
+| `clientId` | yes | HTTPS URL of your Client ID Document (loopback `http` allowed in development). |
+| `redirectUri` | yes | Callback URL published verbatim in `redirect_uris`. Node.js: loopback `http` only. |
+| `storage` | no | `"indexeddb"` (browser default) or `"memory"` (Node.js default). |
+| `debug` | no | `true` emits non-sensitive diagnostics through `console.debug`. |
+| `openAuthorizationUrl` | Node.js | Receives the authorization URL; without it interactive login is impossible. |
+
+### `login(options?)`
+
+```ts
+login(options?: { webId?: string; issuer?: string }): Promise<Session>
+```
+
+Starts or completes an interactive login. Prefers `issuer`; otherwise resolves the issuer
+from the WebID profile (`solid:oidcIssuer`); otherwise asks the user in the browser. The
+resulting WebID must match `options.webId` when it was supplied.
+
+### `restoreSession()`
+
+```ts
+restoreSession(): Promise<Session | null>
+```
+
+Loads the stored refresh token and DPoP key, refreshes the access token, and returns the
+session. Returns `null` when nothing is stored. Throws `SebaSessionExpiredError` when the
+provider rejected the grant (local state is cleared) and `SebaNetworkError` when the
+provider is unreachable (local state is kept).
+
+### `fetch(input, init?)`
+
+```ts
+fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+```
+
+A `fetch` with `Authorization: DPoP …` and a fresh DPoP proof. Same-origin redirects are
+followed (up to five, one new proof per hop); cross-origin redirects are returned to the
+caller instead of being followed with credentials. One retry is allowed for a
+`use_dpop_nonce` challenge and one for an expired/rejected access token; a streamed body is
+never resent. The access token is refreshed automatically when it is close to expiry.
+
+### `logout()`
+
+```ts
+logout(): Promise<void>
+```
+
+Clears memory and storage first, then revokes the refresh token if the provider advertises a
+revocation endpoint. Revocation failures never block logout.
+
+### `Session`
+
+```ts
+interface Session {
+  webId: string;
+  isLoggedIn: true;
+  provider: string;
+}
+```
+
+No tokens, no keys, no expiry bookkeeping.
+
+## Errors
+
+All errors extend `SebaError` and carry a stable `code`:
+
+| Class | Meaning |
+|---|---|
+| `SebaConfigError` | Invalid configuration or unsupported environment. |
+| `SebaDiscoveryError` | Issuer, discovery document, WebID profile or Client ID Document could not be validated. |
+| `SebaRedirectMismatchError` | The redirect URI is not published by the Client ID Document. |
+| `SebaAuthError` | Authorization response, token response or ID token failed validation. |
+| `SebaDPoPError` | DPoP key or proof could not be created/verified. |
+| `SebaSessionExpiredError` | The stored grant is no longer valid (state cleared). |
+| `SebaNetworkError` | Transport failure or 5xx response (state kept). |
+| `SebaNoUIError` | Interactive login is impossible in the current runtime (Node.js without a hook). |
+
+## Security defaults
+
+- PKCE S256 only; `state` and `nonce` are 256-bit random values, single-use.
+- RFC 9207 `iss` in the authorization response must equal the issuer the login was started
+  for.
+- ID token signatures are verified against the discovered JWKS; `aud` must contain the
+  client ID and `"solid"` when the provider advertises `webid`; `cnf.jkt` must match the
+  session key (and is required for `webid`).
+- The refresh token and DPoP key are the only persisted secrets; access tokens are held in
+  a private field.
+- Non-extractable `CryptoKey` storage is used when the engine supports structured cloning;
+  otherwise an exported JWK fallback is used (documented in `SECURITY.md`).
+- Refresh-token rotation is atomic, and concurrent refreshes are collapsed into one.
+
+See [`SECURITY.md`](SECURITY.md) for the full threat model and limitations, and
+[`ARCHITECTURE.md`](ARCHITECTURE.md) for module boundaries.
+
+## Provider compatibility
+
+This table is deliberately conservative: "Publicly tested" means the full login → fetch →
+restore → logout cycle was executed against that provider. If it was not, it says so.
+
+| Provider | Protocol support (spec level) | Locally tested | Publicly tested |
+|---|---|---|---|
+| Hand-written fake provider (`tests/integration`) | Solid-OIDC-shaped: array `aud` with `"solid"`, `azp`, `cnf.jkt` | Full cycle in CI (`npm test`) | — |
+| Community Solid Server 7.3.0 | **Not conformant** with Solid-OIDC §8.1: ID token has a string `aud` without `"solid"`, no `cnf` | Discovery, Client ID Document, PKCE/state/nonce, consent, callback, DPoP token exchange all pass; login rejected at ID token validation | No |
+| solidcommunity.net | Discovery and issuer handling verified; issuer is `https://solidcommunity.net/` | Discovery only | **No** — no account was available |
+| solidweb.org | Discovery verified; issuer is `https://solidweb.org` (no trailing slash); no revocation endpoint advertised | Discovery only | **No** — no account was available |
+| solidweb.me | Discovery verified; issuer is `https://solidweb.me/` | Discovery only | **No** — no account was available |
+
+> **⚠️ Community Solid Server 7.3.0**: CSS issues `id_token.aud` as a string instead of `["solid", client_id]` and omits `cnf.jkt`, violating Solid-OIDC §8.1. Seba correctly rejects this token. Track the upstream issue at https://github.com/CommunitySolidServer/CommunitySolidServer/issues/2295. Do not weaken Seba's validation to work around this.
+
+No public provider has completed the full cycle in this release. See
+[`VALIDATION_REPORT.md`](VALIDATION_REPORT.md) for transcripts and blockers, and
+[`CHANGELOG.md`](CHANGELOG.md) for what changed.
+
+SEBA does not support dynamic client registration. The Client ID Document URL is the
+`client_id`, and the provider must be able to dereference it.
+
+## Running the examples
+
+Node (after `npm run build`; requires a provider and a published loopback redirect URI):
+
+```bash
+SEBA_CLIENT_ID=http://localhost:8443/client-id.jsonld \
+SEBA_REDIRECT_URI=http://localhost:3001/auth/callback \
+SEBA_ISSUER=http://localhost:3000 \
+WEBID=http://localhost:3000/alice/profile/card#me \
+  node examples/node/index.ts
+```
+
+React:
+
+```bash
+VITE_SEBA_CLIENT_ID=https://app.example/client-id.jsonld npm run example:react:build
+npx vite preview --config examples/react/vite.config.ts
+```
+
+The React example expects its redirect URI to be `${window.location.origin}/auth/callback`
+and published in the Client ID Document.
+
+## Validation tooling
+
+```bash
+npm run validate:discovery          # discovery against public providers (no login)
+node scripts/validation/css-setup.mjs   # create a local CSS account + pod
+node scripts/validation/css-flow.mjs    # full flow against local CSS (see report)
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+The test suite includes unit tests, DPoP replay tests, and an integration suite that runs the
+full login → fetch → refresh → logout flow against a hand-written OpenID Provider over
+loopback HTTP.
+
+## License
+
+MIT

package/RESEARCH.md

@@ -0,0 +1,180 @@
+# RESEARCH
+
+Bounded research for SEBA. Ten-source budget; sources below were actually fetched and read
+during this project (no blog posts, no secondary summaries).
+
+## Sources inspected
+
+1. **Solid-OIDC specification** (`solid.github.io/solid-oidc`, Solid-OIDC 1.0 draft) —
+   §5 client identification, §6 WebID issuer discovery, §7 authorization code flow + PKCE,
+   §8 callback/`iss` handling, §9 token validation and DPoP binding, §10 refresh,
+   §11 conformance discovery.
+2. **RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP)** — §4 proof JWT
+   construction and validation, §4.2 claims, §4.3 `ath`, §5 token requests, §6 nonce,
+   §7 protected resource access, §8 server-side validation rules.
+3. **RFC 7636 — Proof Key for Code Exchange** — §4.1 verifier generation, §4.2 S256
+   challenge, §4.3/4.4/4.5 exchange rules.
+4. **OpenID Connect Discovery 1.0 (errata set 2)** — §3 metadata values, §4 discovery
+   request/response/validation, §7.1 TLS requirements.
+5. **`jose` 6.2.15 type definitions and exports inspected locally** (`SignJWT`,
+   `jwtVerify`, `createRemoteJWKSet`, `generateKeyPair`, `exportJWK`, `importJWK`,
+   `calculateJwkThumbprint`, `base64url`, `errors.JOSEError`).
+6. **`idb` 8.0.4 type definitions inspected locally** (`openDB`, `IDBPDatabase`, upgrade
+   callbacks, `IDBPDatabase` transaction helpers).
+
+OpenID Connect Core 1.0 §3.1.3.7 (ID token validation steps) was not fetched separately;
+its steps are reproduced here through the explicit requirements Solid-OIDC §9 places on
+the same validations, and each step is implemented and covered by a test in
+`tests/unit/oidc.test.ts`.
+
+## Relevant protocol requirements
+
+### Client identification (Solid-OIDC §5)
+
+- `client_id` is the URL of a dereferenceable **Client ID Document**, served over HTTPS.
+- The document is JSON-LD and carries the Solid-OIDC context
+  `https://www.w3.org/ns/solid/oidc-context.jsonld`.
+- The document's `client_id` member must equal the URL it is served from.
+- `redirect_uris` must list the exact redirect URI used in the authorization request.
+- Dynamic Client Registration is not used, so the client never calls
+  `registration_endpoint` (SEBA ignores that metadata entirely).
+
+### WebID discovery (Solid-OIDC §6)
+
+- Given a WebID `https://host/profile/card#me`, the profile document is
+  `https://host/profile/card` — the fragment identifies the subject, it is not sent to the
+  server.
+- The profile must state `<webID> solid:oidcIssuer <issuer>`.
+- The issuer must be an `https` URL with a host, and no query or fragment. Loopback `http`
+  is accepted for local development only.
+- JSON-LD (`application/ld+json`) and Turtle (`text/turtle`) are the interoperable
+  profile formats; a `Link` header with
+  `rel="http://www.w3.org/ns/solid/terms#oidcIssuer"` is a documented fallback.
+
+### OpenID Provider discovery (OIDC Discovery §3/§4)
+
+- `issuer` in the metadata document must be identical to the requested issuer; a mismatch
+  invalidates the whole document.
+- `authorization_endpoint`, `token_endpoint` and `jwks_uri` are required and must be
+  absolute `https` URLs.
+- `revocation_endpoint` and `dpop_signing_alg_values_supported` are optional.
+- For issuers with a path component, RFC 8414 places the well-known segment between host
+  and path (`https://host/.well-known/openid-configuration/<path>`); OIDC Discovery
+  examples also show `https://host/<path>/.well-known/openid-configuration`. SEBA tries
+  the RFC 8414 form first and falls back to the appended form on 404 (documented
+  compatibility handling).
+
+### Authorization Code Flow + PKCE (RFC 7636, OIDC Core)
+
+- `code_verifier`: 43–128 characters from `[A-Za-z0-9-._~]`.
+- `code_challenge` = `BASE64URL(SHA-256(ASCII(code_verifier)))`, `code_challenge_method=S256`.
+- `state` must be cryptographically random and validated before the code is used.
+- `nonce` must be cryptographically random and must match the ID token's `nonce` claim.
+- The token request repeats `redirect_uri`, `client_id`, `code` and `code_verifier`.
+
+### DPoP (RFC 9449)
+
+- Proof header: `typ=dpop+jwt`, `alg=ES256`, `jwk` = **public** key only.
+- Payload: `jti` (unique), `htm` (uppercase method), `htu` (target URI without query and
+  fragment, syntactically normalized), `iat` (seconds).
+- `ath` = `BASE64URL(SHA-256(ASCII(access_token)))`, included only when an access token is
+  presented (protected-resource requests), never on token-endpoint requests.
+- Proofs are single-use by design: the server tracks `jti`. A new proof is required for
+  every attempt, including retries and authorization-server nonce challenges.
+- The authorization server binds the issued access/refresh token to the proof key via
+  `cnf.jkt` (JWK thumbprint). The client must keep using that key.
+- `DPoP-Nonce` challenges (`use_dpop_nonce`) require a fresh proof carrying the new
+  `nonce`; a nonce may be cached, a signed proof may not.
+
+### Refresh (Solid-OIDC §10, RFC 9449 §5)
+
+- `grant_type=refresh_token` with a fresh DPoP proof bound to the same key.
+- Refresh tokens rotate; the newest refresh token must be persisted atomically.
+- A rotated/deleted refresh token that is rejected invalidates the local session.
+
+## Existing implementation findings
+
+No existing implementation was consulted, by design: `@inrupt/solid-client-authn-*` is
+excluded by the task, and reading a reference client was not necessary once the normative
+text above was available. The only "existing implementation" inspected was the installed
+`jose`/`idb` type surface, to confirm the exact function signatures used here
+(for example `generateKeyPair` returning `{ privateKey, publicKey }` and defaulting to
+non-extractable keys, and `calculateJwkThumbprint` defaulting to SHA-256).
+
+## Security findings that shaped the design
+
+1. **Proof reuse is the primary DPoP failure mode.** Any cache keyed by `(htu, htm)`
+   silently disables replay protection. SEBA therefore has no proof cache, no TTL, and no
+   configuration knob for one; every attempt signs a brand-new JWT with a new `jti`.
+2. **Refresh tokens are bearer-equivalent if the key leaks.** Both the refresh token and
+   the private key live in IndexedDB; an XSS on the application origin can use both. This
+   is inherent to browser-based public clients and is documented, not "solved".
+3. **`redirect: "manual"` makes cross-origin redirects opaque in browsers.** Credentials
+   cannot be re-attached safely, so SEBA never follows cross-origin redirects with
+   `Authorization`/`DPoP` headers, and returns the redirect response to the caller.
+4. **Content negotiation matters.** Solid providers serve WebID profiles as
+   `text/turtle`, `application/ld+json` or HTML with a `Link` header; a parser written for
+   one concrete example is fragile.
+5. **Provider clock skew is real.** A 60-second tolerance is applied to `exp`/`nbf`/`iat`;
+   it is not configurable, so it cannot be widened into a replay window.
+6. **RFC 9207 `iss` is mandatory in Solid-OIDC** and prevents mix-up attacks; SEBA rejects
+   callbacks without it.
+
+## Identified technical limitations
+
+- **Browsers**: `fetch(..., { redirect: "manual" })` yields an opaque response
+  (status `0`) for redirects, so redirected requests are surfaced to the caller instead of
+  being followed. The library never re-sends credentials to another origin.
+- **IndexedDB** is not available in private-mode variants of some older browsers; SEBA
+  fails with `SebaConfigError` rather than falling back to `localStorage`.
+- **Non-extractable keys**: whether a `CryptoKey` survives IndexedDB structured cloning
+  depends on the engine. SEBA probes this at login and, when cloning is impossible, stores
+  an exported JWK instead (documented downgrade, never silent).
+- **Token introspection / revocation semantics** vary per provider; revocation is
+  best-effort and never blocks local logout.
+- **Live provider interoperability was not tested**: there is no network access to any
+  Solid identity provider from the build environment and no test account. Compatibility
+  claims in `README.md` are limited accordingly.
+
+## Unresolved questions (and the conservative decision taken)
+
+1. **Does every provider emit `iss` on the authorization response (RFC 9207)?**
+   Solid-OIDC requires it. Decision: require it, fail closed with `SebaAuthError`, and
+   document the requirement. A silent fallback would re-open mix-up attacks.
+2. **Should `aud` contain `"solid"`?** Solid-OIDC requires the ID token audience to
+   include both the client ID and `solid`. Decision: require `"solid"` **only when the
+   provider advertises the `webid` scope** in `scopes_supported`; this keeps SEBA strict for
+   Solid providers while remaining usable against plain OIDC providers during evaluation.
+   `azp` is required whenever `aud` has more than one value, and must equal `client_id`.
+3. **Is `cnf.jkt` always present on ID tokens?** Not guaranteed by every deployment.
+   Decision: validate `cnf.jkt` whenever present, and require it when the provider
+   advertises `webid`. Access-token binding is enforced by the resource server regardless.
+4. **Turtle breadth.** A full RDF parser is a large dependency. Decision: a documented
+   subset parser (`src/core/identity.ts`) plus JSON-LD and `Link`-header support; exact
+   supported syntax is listed in `README.md` and each construct is unit-tested. Unsupported
+   constructs raise `SebaDiscoveryError` instead of being mis-parsed.
+5. **Issuer with a path.** Decision: try RFC 8414 ordering, then the appended form, and
+   never accept a discovery document whose `issuer` differs from the request.
+
+## Explicit decisions
+
+| Decision | Justification |
+|---|---|
+| Static Client ID Document only; DCR never implemented | Required by the product constraint; removes a whole class of client-registration attacks and provider-specific behaviour. |
+| ES256 / P-256 DPoP keys only | Required by Solid-OIDC; avoids algorithm negotiation bugs. |
+| No proof cache, no TTL, no `trustedZoneTtl` option | RFC 9449 replay protection is per-proof; any reuse optimisation would defeat it. |
+| Access token held in a private field only | The spec forbids persisting access tokens; nothing else in the library exposes them. |
+| Refresh token + key + metadata in IndexedDB, keyed by `client_id` | One origin can host several applications; keying by client ID avoids cross-app overwrite. |
+| `sessionStorage` for `state`/`nonce`/`code_verifier` | Survives the redirect round-trip, dies with the tab, never persisted to disk like `localStorage`. |
+| Node.js uses a real loopback HTTP server on `127.0.0.1`/`localhost` | Only honest way to receive the callback without browser APIs; bound to loopback only, closed in `finally`. |
+| `openAuthorizationUrl` required for Node interactive login | The library must not pretend to open a browser; without the hook it throws `SebaNoUIError`. |
+| ID token validated with `jose` + remote JWKS, `requiredClaims: exp/iat/iss/aud/sub` | Signature and claim validation before any identity value is trusted. |
+| `htu` = `new URL(target)` with search and hash removed | Matches RFC 9449's "URI without query and fragment" plus RFC 3986 syntax normalization. |
+| Errors are typed classes with stable codes | Applications branch on `error.code`; no string matching, no raw string throws. |
+
+## Dependency decision
+
+Runtime dependencies are exactly `jose` (JWS/JWK/JWKS primitives) and `idb` (IndexedDB).
+No RDF library was added: the required WebID assertion is a single triple, and the subset
+parser is ~200 lines, fully tested, with JSON-LD and `Link` fallbacks. No UI framework is
+included; the browser provider selector is vanilla DOM in `src/browser/provider-modal.ts`.