| 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, soft-persisted access token | The refresh token and key are persisted (IndexedDB). When a provider issues no refresh token, the access token is persisted too by default (persistSessionWithoutRefreshToken: "auto") so a reload can resume the session until it expires; set "never" to keep such sessions in memory only. Refresh-token sessions never store an access token. 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.
| 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.
typisdpop+jwt,algisES256; thejwkheader contains onlykty,crv,x,y— neverd.jti: 32 bytes fromcrypto.getRandomValues, base64url encoded. Unique per proof.htm: uppercase HTTP method actually sent.htu: the request URL with query and fragment removed, normalized byURL(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 noath(there is no access token being presented).nonce: included only when the server supplied aDPoP-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.
- 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-extractableCryptoKeyis stored and the key material is never exportable (exportKeythrows 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
CryptoKeys, 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'scnf.jktis compared against; the access token is therefore bound to the same key used for its proofs.
code_verifier: 43 characters from the RFC 7636 alphabet, each fromcrypto.getRandomValues(~258 bits of entropy), never shorter than the RFC minimum.code_challenge:base64url(SHA-256(ASCII(verifier))),code_challenge_method=S256.plainis never sent or accepted.stateandnonce: 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 withSebaAuthErrorbefore the code is exchanged. - The authorization response's
iss(RFC 9207) must equal the issuer the pending transaction was created for; otherwiseSebaAuthError(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.
Performed by validateIdToken() before any identity value is read:
- Compact JWS parsed; signature verified with
createRemoteJWKSet(jwksUri)viajose, restricted to asymmetric algorithms (ES256/384/512,RS256/384/512,PS256/384/512). issmust equal the discovered issuer (exact string).audmust containclient_id;azp, when present, must equalclient_id;azpis required whenaudhas multiple values.- When the provider advertises the
webidscope,audmust also contain"solid". expmust be in the future (60 s clock tolerance),iatmust not be in the future (60 s tolerance),nbfis honoured when present.noncemust equal the pending transaction's nonce (login only).subis required.webid, when present, must be anhttpsURL (loopbackhttpallowed for development); otherwisesubis used when it is anhttpsURL.cnf.jkt, when present, must equal the local DPoP key thumbprint, and is required when the provider advertiseswebid.- The resulting WebID must equal
options.webIdwhen the caller supplied one (SebaAuthErroron mismatch).
Decoding without verification is never used to make a decision. Failed validation is a
hard SebaAuthError; there is no "accept anyway" path.
- Refresh requests use
grant_type=refresh_token,client_id, the stored refresh token and a freshly signed DPoP proof for the token endpoint (noath). - The response must be
token_type: "DPoP"; anything else is discarded (SebaAuthError) and the previous record is left untouched. - Rotation: a returned
refresh_tokenreplaces the stored one in a single IndexedDBput. 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, thenSebaSessionExpiredError. The application learns the user must sign in again. Other OAuth errors surface asSebaAuthErrorand 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.
- DPoP: see §3 — no cache, no TTL, fresh
jtiper attempt. - OAuth:
stateis single-use and removed before the token request;nonceis single-use per transaction; PKCE ties the code to this client instance. - Retries in
Seba.fetch: at most oneuse_dpop_nonceretry and at most one refresh-then-retry, never nested unbounded. Each retry signs a new proof. - Redirects: at most 5 same-origin hops.
303switches toGET;301/302on aPOSTswitch toGET;307/308keep 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.
- The configured
redirectUrimust appear verbatim in the Client ID Document'sredirect_uris; no scheme/host/port/trailing-slash normalization is applied to either side, sohttps://app.example/cbnever matcheshttps://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 expectedstate; anything else gets404/400. The listener is fully closed beforelogin()settles, and after a five-minute timeout. - The authorization URL is built from the discovered endpoints only, over
https. Authorization/DPoPheaders 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 carryAuthorization.- The provider selection UI validates user input as an
httpsURL before use and never collects credentials; there is no password field anywhere in the library.
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.
- 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.
- IndexedDB is not encrypted at rest by SEBA. Anyone with the browser profile can read the refresh token and (fallback mode) the exported key.
- Opaque browser redirects. With
redirect: "manual", browsers hideLocationand the status of a redirect, so SEBA returns the redirect response instead of following it. - No token introspection. SEBA validates ID tokens and relies on the resource server for access-token validity; revocation is best-effort.
- Clock skew tolerance (60 s) is fixed; a badly skewed device can fail login and
receives an actionable
SebaAuthError. - No live-provider verification. Only the hand-written mock provider and unit-level protocol tests were executed in this environment.
cnf.jktrequirement gated on advertisedwebidscope. A provider that omits the scope but issues unbound tokens will pass ID token validation; the resource server still rejects unbound tokens.- 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: passstorage: "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. NosessionStoragesession backend is implemented, so it is not offered as a mitigation here.
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 | debug: true emits non-sensitive diagnostics (operation names, issuer/client identifiers, endpoint URLs) through core/client.ts's console.debug. No tokens, authorization codes, verifiers, keys, proofs, or WebID/PII 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.
Some Identity Providers are not fully Solid-OIDC compliant. SEBA is strict by default and offers explicit, opt-in relaxations only for documented interoperability cases.
| Option | What it relaxes | What remains enforced | Alternatives |
|---|---|---|---|
allowNonCompliantAudience / tolerances[issuer].allowNonCompliantAudience |
Missing "solid" in ID token aud when the provider advertises webid scope (Solid-OIDC §8.1) |
Signature/JWKS, iss, aud contains clientId (via verification), azp rules, exp/nbf/iat, nonce, cnf.jkt (unless separately tolerated), WebID checks |
Fix the provider; use a conformant IdP |
allowNonCompliantCnf / tolerances[issuer].allowNonCompliantCnf |
Missing cnf.jkt on the ID token when DPoP binding is required by webid context |
DPoP proofs are still required on requests; if cnf.jkt is present it is still checked; signature, iss, exp/iat, nonce, azp, clientId audience |
Fix the provider; ensure ID tokens are DPoP-bound |
Safeguard: enabling any tolerance requires acknowledgeSecurityRelaxations: true or SEBA throws SebaConfigError. Prefer per-issuer tolerances over global flags. Tolerances are logged as warnings when applied; validation can report application via onToleranceApplied callbacks (internal), and the intended session UX is a session-changed event with reason tolerance-applied (see ADR 0003).