The non-React entry @sempods/app-sdk exports createBrowserRuntime.
It coordinates browser login, durable connections, bound Context views and independent Pod readers.
Portable OAuth steps belong to @sempods/client-sdk/oauth; only the client
executor sends and resends data operations. Importing either package starts
neither requests nor storage.
The runtime uses createPod from @sempods/client-sdk by default. Applications
configure their identity and scope requirements; they do not assemble an HTTP
executor. podFactory remains an optional trusted composition seam for advanced
hosts. Both deterministic runtime tests and the packed browser consumer use the
production client; only transport/server behavior is simulated.
import { createBrowserRuntime } from '@sempods/app-sdk';
const runtime = createBrowserRuntime({
identity: {
kind: 'dynamic',
name: 'My tasks',
redirectUri: 'https://app.example/oauth/callback',
},
returnTo: '/',
});
const report = await runtime.initialize();
// Call from the host's sign-in button after startup.
async function signIn(podUrl: string) {
if (report.storage === 'busy') {
throw new Error('Close the other active tab, then reload this page.');
}
if (report.storage === 'unavailable') {
throw new Error('Restore browser storage access, then reload this page.');
}
const connection = await runtime.connect(podUrl);
await runtime.beginAuthorization(connection.id);
}Ordinary data access uses context grants; no feature scopes are needed for this
example. Add scopes: { required, optional } only for documented capabilities
supported by your Pod. The host renders startup feedback and action failures;
React apps can use AppAccess for that presentation.
A deployed identity instead supplies
{ kind: 'did-web', clientId: 'did:web:app.example', redirectUri: '…' }.
The Pod checks the identifier locally against the callback's host, port and
path; a conforming Pod fetches no DID document and requires no registration
(SPS-AUTH-003…007). Some Pods
require a DID document anyway.
The runtime never silently falls back to dynamic registration. For explicit
local HTTP fixtures use development: 'loopback-http'; production configuration
requires HTTPS.
Call initialize() once at startup, including on the callback route. Repeated
calls share one promise and one report. The runtime scrubs callback parameters
and restores the return location stored with the sign-in. The host router decides
what to render; the runtime does not render login or recovery UI.
returnTo names that location: a same-origin path with optional query and hash,
never the callback path, // or OAuth response parameters. A string is checked
when the runtime is created and used for every sign-in. To keep deep links, pass
a function instead: it is called each time a sign-in or re-authorization starts,
and its result is checked the same way.
// A person on /items/add?list=groceries signs in and returns there.
returnTo: () => location.pathname + location.search + location.hash,An unsafe result rejects that sign-in with a configuration error before any
request. A callback without a matching attempt returns to the string, or to /
for a function. The app's router then shows the page, for example opening an
add dialog for /items/add; Context selection and drafts follow the usual rules.
The report separates interaction (none, completed, cancelled, failed)
from storage (durable, unavailable, busy). Interaction describes the
returning sign-in only: without a callback it stays none, also when storage
or coordination fails or the runtime was already disposed. A rejected callback
can coexist with other restored active connections.
When the provider answers the stored attempt with an OAuth error, the runtime
consumes that attempt, ends its connection with the classified
OAuthProblem (denied reports
interaction cancelled) and retires its record. The connection stays listed
until the next reload, also after a transient provider-unavailable. A forged
or malformed callback leaves the attempt untouched. After any failed or
cancelled callback that matched a stored attempt, attemptConnectionId names
that connection, also when discovery failed before the attempt was claimed.
A re-authorization of a signed-in connection keeps the earlier session beside its stored attempt. Two outcomes resume it, if its credential is still usable (unexpired, or renewable with its refresh token) and fresh discovery confirms its binding:
| Outcome of the re-authorization | Result |
|---|---|
The provider answers access_denied for this attempt |
Earlier session resumes; report cancelled with resumed: true |
| The person returns without a callback (back navigation, abandoned attempt) | Earlier session resumes (restoring → active); interaction none |
| Any other provider error, a lost code answer, a binding or client mismatch | Connection ends as above; the earlier session is dropped |
| An expired earlier credential without a refresh token, or a disconnect | Connection ends; nothing resumes |
| A successful answer | The new grant replaces the earlier one, also when narrower; never a merge |
Resuming sends no token request and consumes the attempt: a replayed callback
then fails with attempt while the session stays. A denied first sign-in ends
its connection with denied, as above. A resume that cannot be stored keeps the attempt, and the next
start resumes it. A refresh claimed before the re-authorization began is not
kept, so its refresh token is not sent again. Records written by SDK 0.5 have
no earlier session and end as before; records written by 0.6 are not supported
by older SDKs.
unreadable identifies corrupt or unsupported records without deleting them
or hiding other valid records.
Startup never waits for the discovery of saved Pods, on the callback route or
otherwise. Saved connections report session.kind: 'restoring' until their own
validated discovery succeeds or fails; subscribe to snapshots for their
outcomes. They cannot dispatch data while restoring. A slow or offline Pod
therefore cannot delay the startup report, another Pod's restoration, or a
callback's code claim and exchange, nor keep callback parameters in the address
bar. Disconnect/dispose still prevent late restoration from publishing
credentials.
Discovery only reads the Pod's metadata, so the runtime bounds it: a Pod whose
discovery has not answered after 15 seconds counts as unreachable
(problem: 'network'), also when its fetch ignores the abort signal. This
applies to every discovery: restoration, resuming an abandoned
re-authorization, the discovery before a refresh claim (which then spends
nothing and stays signed in), rediscovery for a
lost renewal answer, connect(url) (rejects),
beginAuthorization(id) (rejects, nothing reset) and a callback's code claim
(fails before the attempt is claimed). A late answer is dropped: it publishes
nothing and installs no credentials, also after a disconnect or dispose, which
stop the wait at once (disconnected); a pending connect(url) belongs to no
connection yet, so dispose stops it. A timeout reports no failure detail.
Token requests and client registration are not covered by this deadline, and no
refresh or code exchange is replayed.
A saved credential that is due when it is restored (past its expiry, or within
the minute before it, with a refresh token) is renewed as part of restoration:
the connection stays restoring until the token endpoint answers, so an
expired grant ends there (ended, retired like at a first request) instead of
after the app saw it active. That token request has its own 20-second
deadline. A lost answer gets the one rediscovery and resend of a
lost renewal answer, still restoring; offline it is
ended with restorable: true at once. Storage that cannot record the refresh
claim leaves it restorable too, with nothing spent. An expired credential
without a refresh token ends as expired. A valid credential becomes active
without a token request. Restoration therefore settles within 15 seconds when
a Pod does not answer its discovery, within 35 seconds for a due credential,
and within about 70 seconds when that answer is lost once while online.
A restoration that cannot reach its Pod (offline, 5xx, 408, 429 or no
answer within the deadline during discovery) is not a sign-out: the connection ends with that problem and
restorable: true, and the saved session is kept. The runtime restores it again
when the browser fires online, and retryRestore(id) tries at once; both go
through restoring to active without a token request or a new sign-in. Any
other restoration failure, such as a changed binding, ends the session. A
renewal whose answer was lost while the browser is offline is restorable the
same way, but only within the grace period (see
lost renewal answers).
One connection's restoration never holds another back. While a connection is
restoring, the runtime accepts connect(url), and for every other
connection beginAuthorization, disconnect, forget, selectContext,
loadContexts and reads through its views. On the restoring connection itself,
disconnect(id) and forget(id) sign out at once and beginAuthorization(id)
prepares a new sign-in; each wins over the pending restoration, which then
publishes nothing. Which controls an app offers meanwhile is the app's and the
SDK components' policy
(custom layouts), not a
runtime restriction.
Configured callback URLs may retain application query parameters, but may not
contain authorization-response keys (code, state, iss, error,
error_description, error_uri, response).
Application query keys must be unique, including after percent decoding. Invalid
configuration is rejected before registration/navigation.
Runtime actions reject with RuntimeError.problem or portable OAuthError;
use structured facts for localized UI, not diagnostic error messages.
Add a preset to the same runtime configuration as identity and scopes:
const runtime = createBrowserRuntime({
identity: {
kind: 'did-web',
clientId: 'did:web:tasks.example.org',
redirectUri: 'https://tasks.example.org/callback',
},
preset: {
podUrl: 'https://pods.example/alice',
// Optional: omit this to let the person choose a readable context.
contextIri: 'https://pods.example/alice/_system/contexts/tasks',
},
// Optional feature requirements; data access itself uses context grants.
scopes: { required: [], optional: [] },
});runtime.preset and useAppState().preset expose this frozen configuration
as PodPreset | undefined. PodPreset is exported by @sempods/app-sdk.
The runtime validates and copies the preset at construction. An invalid Pod URL
throws the client's SdkError with reason.code: 'invalid-pod-url'; an invalid
exact context throws RuntimeError with problem: 'configuration'. Noncanonical
Pod URLs (including a trailing slash) and wrong-Pod/noncanonical context IRIs are
rejected before any request. Configure it once for that runtime lifetime; changing
props does not change an existing runtime. A host that replaces a runtime must
first settle its drafts and unresolved operations, dispose it, and initialize its
replacement.
runtime.connect() uses the preset URL. Both it and connect(url) reuse an
existing connection at that exact URL, preferring a session over an address-only
record. Concurrent connects to the same URL share discovery. If that connection is being
disconnected, connect waits for retirement and checks the current entries again.
A failed durable retirement keeps the connection locally blocked: disconnect
returns blocked-locally and waiting connects reject with RuntimeError('storage').
Offer an explicit disconnect retry; do not claim the saved session was removed.
Disposing the runtime while a connect waits makes it reject with
RuntimeError('disconnected'), without starting new discovery.
Connecting alone does not sign in:
once startup storage is durable and the connection has finished restoring, call
beginAuthorization(connection.id) to sign in, or
beginAuthorization(connection.id, { intent: 'change-sharing' }) when the
person asks to change what the app may access: only then does the Pod show its
consent page although it could reuse the grant (prompt=consent). The request
is not stored, so a later sign-in or startup never inherits it; see
changing sharing. React and
headless authoring use the guarded app.connect(), which connects and signs in, and prefers
an already active matching connection. PodChooser relies on this reuse to
add another Pod while signed in
(adding another Pod).
Without a preset or a sole allowed Pod,
connect() needs a URL; omitting it is a configuration error. A failed
preparation leaves the connection reusable, so a retry creates no duplicate.
Startup removes redundant disconnected records left by older SDKs, within the app identity's namespace and only after their revision-checked deletion succeeds. One remembered address remains unless a session or authorization attempt already represents it. Live sessions and attempts are never merged. Failed cleanup keeps the address visible and forgettable; the next startup can try again. Pod URLs are compared exactly, never by their display label or by normalizing identities.
An exact configured context takes precedence over a remembered choice for that
Pod. A fresh successful catalogue must list it as readable before a view can be
bound. An absent/unreadable configured context leaves selection empty, never
chooses another context, and exposes the ordinary catalogue/access facts.
Required feature scopes still gate the view separately. Read-only contexts need
no write permission. Once selected, access loss retains that same target and its
drafts through the existing view/operation guards. Choosing another context for
that preset Pod is rejected; omit contextIri when people should choose freely.
Automatic selection does not write the configured context into user preferences.
This is a UI default, not an allowed-Pod policy: connect(otherUrl) remains
possible, foreign stored connections restore normally, and a completed foreign
callback still selects its connection. On an ordinary reload, the app controller
prefers a restored preset connection; if none exists, it leaves the active Pod
empty instead of silently using a foreign one. People can explicitly select
another restored Pod. Identity alone continues to determine the storage/lease
namespace; changing the preset never deletes or migrates sessions. Required and
optional scopes remain runtime-wide, including for explicitly connected other
Pods. To restrict which Pods can be used, add the separate policy below. Per-Pod
scope policies remain outside this contract.
Add allowedPods alongside identity and scopes when an app should use only
specific Pods:
const runtime = createBrowserRuntime({
identity: {
kind: 'did-web',
clientId: 'did:web:tasks.example.org',
redirectUri: 'https://tasks.example.org/callback',
},
allowedPods: ['https://pods.example/alice', 'https://team.example/shared'],
// Optional default; it must be in allowedPods.
preset: { podUrl: 'https://pods.example/alice' },
});One entry also supplies the default for runtime.connect() and guarded
useApp().connect() without a preset. It uses the same reuse/disconnect-waiting
behavior as a preset. With several entries and no preset, pass the chosen URL
explicitly. Omitting allowedPods keeps unrestricted behavior; an empty list,
duplicates or an outside-list preset throw RuntimeError('configuration') at
construction. URLs use the client's canonical validation, including the explicit
development: 'loopback-http' exception; matching is exact, not by origin or
prefix. The list is copied and frozen, and exposed through runtime.allowedPods
and useAppState().allowedPods. No new public export is needed.
An outside-list connection is rejected before discovery. Stored records from other Pods stay untouched but are excluded from snapshots, restoration and all connection-ID actions, so they cannot be selected or bound. Widening the policy in a replacement runtime makes those records eligible again. Required scopes and fresh context evidence still gate every permitted target; a Pod restriction is app configuration, not server authorization.
A callback for an excluded Pod reports interaction: 'failed' with
problem: 'configuration'. It makes no discovery or token request for that Pod,
does not claim the code, and scrubs the URL to the stored safe return location.
Its attempt remains untouched and expires normally; do not retry the callback
automatically. Other permitted sessions restore independently. The identity-based
storage namespace and single-tab lease remain unchanged when the policy changes.
AppAccess presents one/set/free Pod configuration directly, including the
finite picker. See sign-in composition.
Custom controls can read useAppState().allowedPods too.
Configure the policy once outside rendering and use the existing guarded actions
for Pod/context switches; replacing the runtime first requires settling drafts
and unresolved operations, as with presets.
A deployed app in front of one Pod, where people usually have a session at that Pod already (single sign-on), can skip the first click on Sign in:
const runtime = createBrowserRuntime({
identity: {
kind: 'did-web',
clientId: 'did:web:chat.example.org',
redirectUri: 'https://chat.example.org/callback',
},
preset: { podUrl: 'https://pods.example/team' },
firstSignIn: 'silent',
});When nothing is stored for the app on this device (no session, no remembered
Pod, no unreadable record, also none of a Pod that allowedPods now
excludes), initialize() connects the default Pod and
navigates to its provider once with prompt=none, instead of resolving. The
Pod answers at once, without showing anything:
| The Pod's answer | Result |
|---|---|
| A code: the person has a session there and a grant for this app | interaction: 'completed', signed in without a click |
login_required, consent_required or interaction_required |
interaction: 'none'; the connection is signed-out as one never signed in to, nothing is remembered, and StartupReport.firstSignIn names the cause and the Pod's link |
Anything else, such as server_error |
interaction: 'failed', as for a clicked sign-in |
firstSignIn.providerLink is the Pod's error_uri, for example its own login
page, kept only on the issuer's origin; the Pod's error_description is never
kept. The access prompts carry it as AccessPrompt.providerLink while the
connection stays signed out, and AppAccess shows it beside Sign in as a
link that opens in a new tab.
The attempt runs at most once per tab. The runtime notes it in
sessionStorage before the redirect, so a reload, a sign-out, coming back from
the Pod without an answer or a failed answer never starts it again; tabStorage
replaces that storage in tests, and without one nothing is tried. A preparation
that fails (an unreachable Pod) leaves the person signed out without an error.
A tab that started with something stored, or returned from a sign-in, never
tries, also after a sign-out deletes the records. A new tab with nothing stored
tries again. After a sign-out the default rememberPods: true keeps the Pod's
address, so no tab on that device signs in silently any more; with
rememberPods: false a new tab does, because signing out of the app does not
sign out of the Pod.
silent needs a did:web identity and a default Pod (a preset or a single
allowedPods entry); otherwise construction throws
RuntimeError('configuration'). A Pod answers prompt=none with a code only
when it remembers the person, the client is not dynamically registered, and the
app's grant still stands
(SPS-AUTH-040).
Until the person has granted the app once, on any device, the answer is
consent_required. The flow is runtime
policy, not public API: an app that needs another one (another time, another
Pod) builds it from prepareAuthorization(…, { prompt: 'none' }) and
OAuthFailure.providerLink in @sempods/client-sdk/oauth.
Some apps show a Pod's public data: a recipe collection linked to one Pod, or
a catalogue that people read first and sign in to only to see more or to
change something. The signIn option declares what the app needs:
const runtime = createBrowserRuntime({
identity: {
kind: 'did-web',
clientId: 'did:web:recipes.example.org',
redirectUri: 'https://recipes.example.org/callback',
},
signIn: 'optional',
preset: { podUrl: 'https://pods.example/alice' },
});
await runtime.initialize();
// The preset's Pod, read without a token until the person signs in.
const pod = runtime.getSnapshot().find((c) => c.reading === 'anonymous');
if (pod) await runtime.loadContexts(pod.id);required(the default) is the behaviour described above: a connection reads only with a session.optional: a connection without a session reads the Pod's public Contexts without a token. Startup connects the default Pod (thepreset, or the sole allowed Pod), andconnect(url)adds another Pod without discovery or sign-in.beginAuthorization(id)signs in when the person asks for it; only then is the Pod discovered and the client resolved. A session that ends, or signing out, returns to reading without a token.none: only an anonymous connection to the default Pod, which is required. No session store and no Web Lock are used, so several tabs and an installed PWA beside a browser tab work.identitymay be omitted;beginAuthorization,disconnectandforgetreject withRuntimeError('configuration').initialize()reportsstorage: 'unavailable', which here is no failure.
Connection.reading says how a connection sends requests:
reading |
Requests | When |
|---|---|---|
session |
with its token | active or renewing |
anonymous |
without a credential | signed-out, or ended without restorable, under optional or none |
null |
none | restoring, leaving for a sign-in, restorable, signing out, or no session under required |
There is no session state of its own: a connection that reads without a token
is signed-out (or, in the page where its session ended, ended with that
cause), and the runtime publishes reading so the UI derives nothing.
A Pod answers a request without a token with its public Contexts only
(SPS-GRANT-031).
Its catalogue lists them as readable, never as writable
(SPS-CTX-034),
so a bound view reports write: false and every write returns not-sent
before dispatch. bind, bindContext, bindPod, loadContexts and
loadContextLabels work as for a session. Their handles are keyed with the
subject null; signing in, a session that ends and signing out replace them
and invalidate pending reads, and the catalogue is loaded again with the new
access. A Pod that has no public Context answers with an empty catalogue.
A token the Pod rejects is never followed by the same request without it: the Pod does not fall back to anonymous access (SPS-CORE-015), and neither does the runtime. A refused renewal ends the session as before; only after that does the connection read without a token, with new handles.
Under optional, signing in requests public-read as an optional scope
(added if the app does not list it), so a session that receives it still reads
the public Contexts the app showed before. scopes.required is a
configuration error there, as an app that works without a session cannot
require what only a session grants. Under none, any scopes are one.
A signed-out connection keeps reading without a token under optional, also
with rememberPods: false, which then only keeps the address from the next
start. forget(id) removes the connection; a forgotten default Pod is listed
again as a new connection that was never signed in. The other-tab lease still
applies under optional: a second tab reports storage: 'busy'.
The SDK reads public data with plain requests without a token. It does not use
the anonymous scope=public-read&prompt=none token some Pods offer
(SPS-AUTH-042):
it reads nothing more, needs a redirect and a client identity, and expires
without a refresh token. In React, see
apps without sign-in.
const unsubscribe = runtime.subscribe(() => {
renderConnections(runtime.getSnapshot()); // application-specific UI
});
const contexts = await runtime.loadContexts(connectionId);
if (contexts.kind === 'ok') {
const writable = contexts.body.find((c) => c.readable && c.writable);
if (writable) {
runtime.selectContext(connectionId, writable.iri);
const tasks = runtime.bind(connectionId);
const read = await tasks.subjects.get(taskIri);
if (read.kind === 'ok') {
// Pass tasks and the resource evidence to domain/editor code.
console.log(read.body, read.etag);
}
}
}Subscription listeners run independently. A thrown listener error is rethrown in a microtask for the host to report; it does not interrupt other listeners or turn a session transition into a failure.
Snapshots contain session, feature-scope and catalogue facts, never credentials.
requestedScopes, grantedScopes and missingRequiredScopes remain distinct.
Missing required features block bound operations; a missing optional feature
does not. The catalogue supplies context rights separately from token scopes.
There is no automatic consent redirect after a refusal.
The runtime reads a registry description automatically only for the selected,
validated Context (explicit, preset or remembered) and publishes its rdfs:label
in catalogue.labels, keyed by exact IRI (SPS-CTX-032). Other picker entries
show the IRI or a derived name at once; no catalogue size triggers more reads. To
name other Contexts, for example in a list menu, call
loadContextLabels(id, iris): up to 20 IRIs per call (more reject with
RuntimeError('configuration') before any request). Only Contexts the ready
catalogue lists as readable are read, four at a time. The call resolves once its
reads settle or are dropped; labels arrive through the snapshot. Labels are
display text only, never identities or grants, and never block selection or data
reads. Concurrent requests for one Context share one read. Every result (label,
absence, failure) is cached for the connection's access lifetime: unchanged
catalogue reloads and reselection reuse it, and failures keep the fallback
without automatic retry. A selection change drops only the previous selection's
own pending read, not reads that loadContextLabels started or joined. Changed
rights for a Context drop its label; changed grants, session end or a new
authorization clear the cache. An unchanged credential renewal does not refresh
labels.
Select one readable context explicitly. Empty selection does not mean all or a default context. A writable target is an application requirement derived from catalogue facts, not a second login implementation. Read-only Pod queries use the separate reader below.
A BoundView exposes client subject/query operations without tokens. Its
key stays stable through refresh and same-target access changes. Switching
A → B → A creates a new lifetime; the old A view cannot become valid again.
Write observation is per Context, not per handle, so the old and the new A
handles share it: a save that was already under way through an editor on the
old handle still refreshes lists on the new one when it is confirmed.
Pending reads resolve promptly as invalidated after target/access changes;
caller cancellation is cancelled. The shared loader (createViewLoader,
used by useLoad, useList and usePodLoad) owns the bounded silent retry. Writes preserve their original client result, including
an already confirmed refused 401 or applied result after a target change.
A bound 403 triggers one shared catalogue reload for concurrent refusals. Successful revalidation publishes current rights. Loading or failed catalogues retain last-known facts; a network failure is not proof of revocation. UI consumers clear server data when read permission is lost, and retain readable data while disabling actions when only write permission is lost. This runtime does not own a screen's data cache or local drafts. Revalidation invalidates a view's pending reads only when its own Context's access facts change; unchanged rights, unrelated-context changes and failed reloads retain eligible reads. A caller can cancel its wait for a write-triggered revalidation; the already confirmed write result still returns, and the shared catalogue operation may finish separately.
// The Context a Pod-overview row's GRAPH binding names.
const notes = runtime.bindContext(connectionId, rowContextIri);
if (notes.getSnapshot().read) {
const read = await notes.subjects.get(rowSubject);
// Edit with the read's ETag, as with the selected Context's view.
}bindContext returns a BoundView for one explicit Context without changing
or remembering the connection's selection, and loads no label. It is always its
own handle, also when the IRI is the selected Context, and repeated calls return
the same handle for one authorization lifetime (connection, generation and
subject). Selection changes, including A → B → A, neither invalidate its
pending reads nor change its target.
- Preconditions. It needs an eligible signed-in connection, or one that
reads without a token, and throws
RuntimeError('disconnected')otherwise. It throwsRuntimeError('configuration')for an IRI that is not a Context of that connection's Pod (isContextIri), or for another Context than an exact presetcontextIrion the preset's Pod; connections to other Pods are unaffected. Creating the handle sends no request and needs no catalogue. - Access. Like the selected view, it follows the last confirmed catalogue
evidence for its Context. Without that evidence, or once a successful
catalogue removes the permission, requests are not dispatched. A failed
refresh keeps the retained evidence. A Context
403uses the shared catalogue revalidation. - Invalidation. Each explicit Context has its own read domain. A
permission change for that Context cancels its pending reads, including a
late answer after access was lost and regained, and leaves explicit views of
other Contexts and the selected view unaffected. Connection-wide events
(changed grants, session end, a new authorization, disconnect or disposal)
invalidate all of the connection's bindings, explicit and selected alike.
Writes keep their actual result, as for every
BoundView. Within one runtime a renewal never changes the subject: a token for another person fails refresh continuity and ends the session. A new sign-in completes on the callback page, so the new identity's handles belong to a new runtime and never meet the old ones. - Write observation. Handles for the same Context of one authorization
lifetime share their write events and write-start counts. A confirmed write
made through the SDK's editors and hooks (
bindResourceEditororuseResourceEditor,useCreation,useFieldUpdate) on an explicit view refreshes auseListon the selected view of that Context, and its start retires success feedback across those handles. Directsubjectswrites on a view emit no write event. Nothing is shared across Contexts, connections, subjects or generations, and this is no server subscription.
const reader = runtime.bindPod(connectionId);
if (reader.getSnapshot().read) {
const result = await reader.sparql.select(
'SELECT ?subject WHERE { ?subject ?predicate ?object }',
);
if (result.kind === 'ok') {
for (const row of result.body.rows) {
if (row.subject?.type === 'iri') console.log(row.subject.value);
}
}
}Binding and dispatch require no selected Context or catalogue and initiate no
discovery. bindPod requires an eligible signed-in connection, or one that
reads without a token; it throws RuntimeError('disconnected') during
restoration or after session end under signIn: 'required'. A handle may be current with read: false
when required scopes are missing; dispatch rechecks eligibility and returns
invalidated without sending. Readability means permission to attempt the read,
not that readable data exists. The server authorizes its dataset.
The cached BoundPod.key identifies connection, subject, Pod and authorization
generation. It exposes only select, construct and find, and a stable immutable snapshot
with current, read and revision. Subscriptions have no initial callback and
notify only changes to those reader facts. Context selection (including A → B → A),
catalogue loading/failure/permission updates and labels neither cancel pending
Pod reads nor change their snapshot. Session end, disconnect, disposal, changed
subject/generation and changed granted scopes invalidate pending results. A new
generation gets a new handle; an old handle never revives. Changed scopes within
a renewal advance the read revision, while unchanged grants preserve it.
Caller cancellation returns cancelled; invalidation returns invalidated,
including when a late transport answer would otherwise succeed.
Cancellation does not require the newer AbortSignal.any browser API.
Pod reads share the runtime credential owner and the production client's executor
implementation. A bound client guard and the captured lifetime signal apply on
initial dispatch and authentication resend. The existing bounded 401 renewal
remains shared across readers. A Pod 403 returns refused without catalogue
revalidation, automatic renewal or inferred global session/access changes.
Context-view 403 recovery retains its existing behavior.
createAppController(runtime).getSnapshot().pod exposes the active connection's
Pod reader whenever its session is signed in, also while startup still settles.
It is null without an active connection, or unless that connection's session is
active or renewing (so also while it restores, is leaving, is signed out or
has ended). The snapshot's Context view, by contrast, stays null
until startup or startupError is set: on a callback page, saved sessions
restore while the returning sign-in is still being redeemed, and no Context
screen may start on a connection that sign-in is about to replace. Changing the
active Pod exposes its handle; another connection's reader retains its own
lifetime.
Controller startup defaults to automatic catalogues (contextSelection: 'required').
Use createAppController(runtime, { contextSelection: 'on-demand' }) for a
catalogue-free Pod overview. Neither startup/restore, preset/remembered Contexts
nor Pod read/recovery initiates catalogue or description requests in this mode.
The controller still restores all eligible sessions independently. A headless UI
explicitly calls runtime.loadContexts(id) before selecting/binding a Context;
fresh readable catalogue evidence validates the configured/remembered selection.
The full catalogue remains one response, without per-Context reads or fetches.
createViewLoader(reader, read) works with BoundPod and PodRead<T> as well as
Context handles, retaining cancellation, obsolete-result retirement and at most
one recovery retry per cycle. See React Pod overviews.
reader.find(text, options) is the client's
Find through the same
handle. It has the same lifetime, invalidated and cancelled results as
select, waits for a podReadLimit slot, and takes priority: 'current'. A
connection that reads without a token searches only the Pod's public Contexts.
Each Pod answers on its own; to search several, use one loader per Pod as in
reads per connection.
An app that mounts many Pod loaders at once, such as a graph explorer with hundreds of nodes across Pods, bounds them on the runtime instead of queueing reads itself:
const runtime = createBrowserRuntime({
// identity and other options as usual
podReadLimit: { perPod: 4, total: 8 },
});
// For what the person looks at now, such as the selected graph node. A
// changed value reprioritizes the loader's waiting reads; it restarts nothing.
usePodLoad(reader, read, {
key: iri,
priority: selected ? 'current' : undefined,
});
// A single read that is always current:
await reader.sparql.select(query, { signal, priority: 'current' });Without podReadLimit, every read starts at once, as before. With it, an
explicit Pod read (BoundPod.sparql.select/construct or find, also through
usePodLoad and createViewLoader) beyond a limit waits for a slot:
perPodcounts the requests in flight to one Pod URL, across its connections and authorization generations;totalcounts them across all Pods. Each value is a positive integer.- Pods with waiting reads take turns, so 200 reads for one Pod never hold
back another. Within a Pod, normal reads start in order, and a
priority: 'current'read goes before them. After three priority reads in a row on a Pod, its waiting normal read is next on that Pod; after three in a row across all Pods, a waiting normal read of any Pod is next. Priority never exceeds a limit or stops a running read. - When the current resource changes, change the priority, not the read:
usePodLoad'spriorityoption, orsetPriorityof acreateViewLoader(pod, …)loader. A waiting read of that loader then goes first or back to normal in place: it keeps its arrival order, is not restarted and is sent once. A read already admitted keeps its request and signal; the loader's later reads (a second query in the same callback, areload(), a recovery) start with the priority set then. A disposed loader ignores it, and it never reaches another loader's reads. Only reads that receive the loader'ssignalunchanged follow it; a read's ownpriority: 'current'stays. Do not restart a read to change its priority:loadingcovers both waiting and running reads, and a restart aborts a running request, whose slot an abort-ignoring transport keeps. - A waiting read that is cancelled (
signal,cancel(), unmount, areload()that supersedes it) or invalidated (changed grants, sign-out, disconnect) leaves the queue at once and is never sent. - A slot is held until the request settles, also when the caller stopped
waiting earlier. A cancelled or invalidated read returns at once, but a
transport that ignores the abort keeps its slot until it answers or fails.
Old requests therefore still count after changed grants, and the reads of
the new grants wait for them. There is no timeout: a request that never
settles keeps its slot; the browser's
fetchsettles when it is aborted. - Waiting spends no recovery retry: a loader whose read only waits restarts
on the current grants when they change, however often. Once its request
was sent, the loader's one recovery per cycle applies as before. Pass the
loader's
signalto the read unchanged; a read that passes another signal counts as sent. - The one resend after a Bearer
401stays in the read's slot, so the limit holds for every request to the Pod. The credential renewal it may wait for goes to the authorization server and is not counted. - Context reads (
BoundView), discovery, catalogue, labels and writes are not counted and never wait for Pod reads.
IndexedDB stores versioned validated records with compare-and-swap revisions.
Web Locks permit one active runtime per application configuration on an origin.
The storage/lock namespace is the identity kind plus the did:web clientId, or
for dynamic identities the redirectUri. Display name, object property order and
scope policy do not affect it. Restored grants are evaluated against the current
required scopes; the original requested scopes remain continuity evidence.
A did:web app may move its callback route within its identity (same host and
DID path prefix). Signed-in sessions, refresh claims and disconnected records
follow the move: they restore, and the next durable write records the new
route. An outstanding authorization attempt (or a code claim) keeps its exact
redirect, because its code can only be redeemed with it; after a move it is
reported in unreadable and left untouched, so that person signs in again. A
route outside the identity is never followed. Moving a dynamic client's callback
changes its namespace, so it starts without saved sessions.
A second tab reports busy; lack of durable storage or coordination (no Web
Locks, locks: null) does not silently fall back to memory and leaves stored
records untouched, so a later start with coordination restores them. The runtime
requests its lock only if available and never steals it from another tab: the
holder keeps working until it is closed or disposed. The
runtime never retries a busy startup: after closing the holder, reload the busy
page to create a fresh runtime and acquire the lease. A store closed by a newer
database version (versionchange, e.g. after an upgrade in another tab) stays
closed for this runtime; renewals then end the session with storage. Call
dispose() on application shutdown to release the lease. See React/headless authoring for lifecycle integration.
The runtime persists an attempt before navigation, consumes it once before code
exchange, and publishes credentials only after validation and durable acceptance.
Identity, requested/granted scopes and continuity evidence survive redirect and
reload. Context rights are reloaded rather than persisted as grants. The last
explicitly chosen context of each connection is remembered as a preference
(preferences, localStorage by default; null disables it) and reselected when
the fresh catalogue lists it as readable. It is never replaced by another
context, it is kept for a remembered Pod and forgotten
with it, and storage failures only disable it. The same preference storage keeps the
connection the app last worked with, for the
startup choice with several Pods.
Connecting a second Pod preserves the first session.
Discovery retains authorization_response_iss_parameter_supported. When true,
every success or error callback must carry the exact issuer. An empty, duplicate
or foreign iss is rejected. When the server does not announce support, an absent
iss is accepted for compatibility; a present one is still checked. This
compatibility case keeps a residual mix-up risk (RFC 9207). sempods-kotlin
announces support, so its callbacks use the strict path. The announcement is also
part of the saved discovery binding, preventing silent changes on resume.
A first sign-in left without a callback, an abandoned re-authorization whose
earlier session cannot resume, and interrupted code claims (and refresh claims
of SDK 0.7) are retained with an explicit interrupted session problem; an
expired authorization reports expired.
Neither is dispatched or silently retried on startup. A refresh the earlier
page left is resent once instead (see
lost renewal answers). Call beginAuthorization(id)
for an explicit new attempt, or disconnect(id) to durably remove its secret
material; the Pod then stays a remembered Pod until
forget(id). Until one of those actions, a retained
authorizing record still contains its verifier. There is no automatic expiry
cleanup. Corrupt/future-version records remain untouched and
are reported separately through StartupReport.unreadable.
The runtime renews a credential before dispatch once it is within a minute of
its own expiry (half its lifetime for shorter tokens), so a session survives
token expiry without relying on the Pod's 401. While the credential is still
valid, requests keep using it until the renewal completes; once it has expired,
they wait for the renewal. A credential without a refresh
token is sent until it expires by this device's clock; the next request then ends the session as
expired. Renewal remains reactive as well: after a validated 401 with a
Bearer challenge, the client requests renewal and may resend once. A 401
without a challenge does not trigger renewal or a resend, because
SPS-CORE-015
requires a Bearer challenge for a rejected token; such a Pod still works as long
as it honours the advertised token lifetime. If it refuses an unexpired token
without a challenge, for example after revocation or a restart that lost its
tokens, the session stays active and requests return refused 401 until the
renewal near the credential's own expiry, or until the session ends as
expired without a refresh token. beginAuthorization(id) recovers sooner
(Change sharing in the SDK components passes intent: 'change-sharing'). Pods should answer an expired token
with 401 and WWW-Authenticate: Bearer error="invalid_token", and expose that
header to cross-origin apps.
The runtime shares one refresh across callers; cancelling one waiter does not
cancel another. Immutable credential objects retain their identity until an
accepted replacement. A delayed refusal of the old credential reuses that
replacement. The client alone decides whether one resend is still allowed.
A refresh token is claimed durably before dispatch, and removed from memory;
only the claim keeps it, for one resend after a lost answer. Subject/issuer/client
changes, widening scopes or a result that returns the sent refresh token are rejected. Scopes are
unordered sets; duplicates and mismatches are rejected.
A transient failure before a committed refresh claim (unreachable Pod, failing
discovery with a 5xx/408/429 answer, a write the open store could not complete)
spends nothing: the connection stays signed in with its unspent refresh token
and the durable ready record, the request keeps its answer (for example a
refused 401), and the next due or refused request tries the renewal again,
without a reload. A permanent
one (a changed token endpoint, issuer, client or refresh support, unsupported or
invalid metadata, a store closed by a newer database version) ends the session
visibly with its problem and needs a new sign-in; the unspent record is kept but
restores to the same end. Once claimed, a refused or invalid answer retires the
consumed session; a lost one is resent once, as below.
A token request whose answer is lost no longer signs people out. The refresh
claim keeps the sent refresh token, the granted scopes and when it was first
sent. The outcome is unknown when the token endpoint gives no complete answer
(no connection, no answer within 20 seconds, a body cut off), or one that is
neither a token response (2xx) nor an OAuth error answer (400, 401), such
as a gateway or proxy failure (5xx, 403, 404, 408, 429). The Pod may
have rotated the token, so the runtime sends the same token once more while it
was first sent less than refreshGracePeriod ago (60 seconds by default, the
sempods server's default rotation grace period). It first rediscovers the Pod:
that read probes the network, so a connection that lost the answer does not
lose the one resend too. The probe ends with the grace period (a probe still
unanswered then ends as interrupted), and the grace period is checked again
right before the resend is recorded and when it is sent:
| After a lost answer | Result |
|---|---|
| Online, within the grace period | Rediscovered, then resent; renewing until it settles, then active |
| Offline or Pod unreachable, within the grace period | ended { problem: 'network', restorable: true }; resent on online or retryRestore(id) |
| Offline beyond the grace period | ended { problem: 'interrupted' }; nothing is sent |
| The resend loses its answer too | ended { problem: 'interrupted' } |
The resend is refused (reuse detection, invalid_grant) |
ended with the server's problem (exchange), as before |
| A page left during the request (reload, suspended tab) | The next start resends once within the grace period (restoring → active) |
The resend is recorded durably before it is sent, so a reload never sends it a
third time. A session that ends this way keeps its Pod address: it is listed as
a remembered Pod with signed-out { problem: 'interrupted' }
from the next start on, and signing in again is one action. While restorable,
nothing is dispatched: bound handles stay current but report read and
write as false, and pending reads resolve invalidated. The resend restores
their access. Of the token endpoint's outcomes, only an OAuth error
answer (for example invalid_grant or invalid_client) or an outcome still
unknown beyond the grace period ends the session, besides an expired access token without a
refresh token; an answer that does not continue the session (claims) and
local failures (storage) end it as before.
A Pod without a grace period treats the resend as reuse and refuses it, so the
session ends as before; with one (sempods-kotlin#447) it survives.
refreshGracePeriod: 0 never resends. The grace period is measured on this
device's clock from the first send; a clock set back extends it on the client
only, and the Pod still refuses a late resend. Should a page close before an ended
session's claim is retired, the next start within the grace period may send
that claim's token once more; its result passes the same continuity checks.
Besides fixture tests, these outcomes have
live evidence
for 0.8.0 against a deployed Pod with the 60-second grace period. The lost
answers were simulated in the page, so a real network loss and the online
resend are covered by fixture tests only.
A code exchange is never resent.
beginAuthorization() prepares first (discovery, client resolution, the stored
attempt) while the current session keeps working; the app controller reports
changing meanwhile. Only after the attempt is stored does it retire the
connection's handles and navigate; a failed preparation leaves the connection
exactly as it was. Between the stored attempt and the page unloading, the
connection reports session.kind: 'leaving' (with the earlier subject for a
re-authorization) and keeps its catalogue, selection and grants for display:
no request of the earlier session is dispatched, bind, bindContext and
bindPod throw disconnected, and the SDK components show a status instead of a sign-in. A
page restored from the back/forward cache with its runtime still alive resumes
the earlier session as above; a host that disposes the runtime on pagehide
recreates it, and its startup resumes it. After the session ended (for example a failed
refresh), it prepares under a fresh lifetime in the same runtime, which a
disconnect or dispose during preparation still cancels without navigating. A
Pod that advertises no registration endpoint (optional, RFC 8414) still serves
did:web clients; dynamic clients
need one and are refused with invalid-config.
A lost answer to a code exchange requires explicit login; its code is never
redeemed again.
Startup/session failures preserve safe structured protocol failure facts for
presentation alongside problem (network, discovery, state, etc.). Neither
raw error causes nor credential-bearing responses enter snapshots.
JWT payload checks enforce issuer, client, subject, expiry and scope continuity. They are not JWT signature verification: token receipt is bound to the validated token endpoint and TLS. Reloaded data is structurally checked and rediscovered; same-origin script access is not a separate trust boundary.
disconnect() blocks locally immediately and retires the saved session: the
record keeps only the Pod address and why the session ended, without token or
verifier (see remembered Pods).
If that write fails, it returns blocked-locally and retains
session: { kind: 'ended', problem: 'disconnected', saved: false } on the
connection. The fact survives UI remounts and remains during explicit retries;
a successful retry signs out. It is not persisted across reloads:
the saved session may still restore. Offer Sign out again, not a reload.
A late exchange cannot resurrect the locally blocked connection. forget(id)
reports a failed deletion the same way.
AppAccess shows this failure with Try again in
EN/DE (controls.disconnectFailed): in its gate for the active connection, as a
prompt for another one (access, reason sign-out-failed). The ordinary hint notes that sign-out applies
only to this device: it neither revokes sharing on the Pod, deletes Pod data nor
signs out at the Pod's provider. dispose() releases memory/locks while
retaining durable sessions.
A Pod address outlives its session, so people do not type it again on their
own device. Signing out (disconnect(id)) and a session that ends (a refused
renewal, an expired token without a refresh token, a failed sign-in) keep the
connection's record with only its address (the Pod binding) and why the
session ended: no token and no verifier. The connection stays in the snapshot,
and the next start lists it again, as
{ kind: 'signed-out', problem?: RuntimeProblem }with its podUrl and its remembered Context choice. problem is
disconnected after a sign-out, otherwise how the session ended, for example
expired. A connection that was never signed in has none, nor has a Pod
whose first sign-in failed, as no session ended. Records written by SDK 0.7,
which did not keep the reason, have none either: after an upgrade, those Pods
are listed as signed out too. A reason this SDK cannot read (from a newer
SDK) is left out; the address stays. Within the page where it happened, an
ended session keeps reporting ended with its cause; it reads as signed-out
from the next start on.
- Signing in again is one action.
beginAuthorization(id)(the guardeduseApp().authorize(id)) uses the remembered address and reselects the remembered Context once the fresh catalogue confirms it. With a valid sign-in cookie at the Pod and a remembered consent, the Pod answers without interaction.connect(url)reuses a matching connection; without a URL it uses the preset or sole allowed Pod. - Forgetting is separate.
forget(id)signs out if needed, deletes the record and the remembered Context choice, and removes the connection from the snapshot. It works for any connection. While it runs, and after a failed deletion (blocked-locally, as fordisconnect), the connection reportsended { problem: 'disconnected', forget: true }, withsaved: falseafter the failure; a retry withforget(id), or withdisconnect(id), forgets it, so the address is never kept against the person's choice. - Opt out with
rememberPods: false, for shared devices or privacy-sensitive apps. Sign-out then forgets the address and the remembered Context at once and removes the connection; an ended session stays listed only until the page unloads; startup deletes records an earlier start (or SDK 0.7) remembered for the permitted Pods. Records of Pods outsideallowedPodsstay untouched. - Each Pod keeps its own state. One ended session or sign-out never changes another connection.
The app controller does not make a remembered Pod active while another
connection has a session (signed in, restoring or ended), and when the active
connection signs out it gives way to such a connection, as a removed one did.
A remembered Pod the person selects stays active, ready to sign in.
AppAccess offers remembered Pods in an editable address chooser with one
main action. Manage saved Pods, in its dropdown, separates removal from sign-in,
and controls.sessionEnded notes an ended session. Connected management also
lists other Pods under Connect another Pod. Failed retirement offers its
failure and retry, never sign-in to that connection, even when it is not the
active Pod. Controller connect and authorize reject with
RuntimeError('storage') while that connection has ended.saved === false;
retry disconnect or forget first. The low-level runtime's
beginAuthorization(id) remains an explicit escape hatch: a durably saved new
attempt replaces the old record and cancels the failed forget intent. Ordinary
apps should use the controller's retry flow. The React guide
describes the default presentation and its customization.
A custom SessionStore (openStore) implements remove(id, expectedRevision)
for this: an atomic delete at the expected revision, conflict otherwise.
With several saved Pods, the app controller (createAppController, and so
SempodsProvider and AppAccess) makes the connection active that the app
last worked with. It remembers that connection per app identity in
preferences once it works: signed in (reading: 'session') with every
required scope. Without it, or once it is merely remembered (signed-out) or
forgotten, the first connection with a session in the session store's order
is active, as before. With a preset, only the preset Pod's connections count.
Until the startup choice closes, an active connection that cannot work gives way to one that works:
| The remembered (active) connection at startup | Other permitted connections | Result |
|---|---|---|
| Restores and works | Any | Stays active |
| Ends (not a chosen sign-out), is unreachable, or lacks a required scope | One works | That one becomes active; the other shows as an action prompt (signed-out, unreachable, missing-scopes) |
| Cannot work, as in the row above | Others still restore | access.pending until one works (it becomes active) or none can |
| Ends or lacks a required scope | None works | Its gate (signed-out, missing-scopes), as without other Pods |
| Is unreachable | None works | Its unreachable prompt, as without other Pods |
| Still restores after 5 seconds | One works | That one becomes active; the remembered one keeps restoring and prompts only if it then cannot work |
| Still restores after 5 seconds | None works yet | Keeps waiting; the first that works becomes active, possibly the remembered one |
A connection that took over is not remembered, so a Pod that was only slow is
preferred again on the next start, and the controller never switches back to
the remembered one by itself. The startup choice closes once the active
connection works, the person starts a guarded action (navigation, a Context
selection or a connection action), or the active connection's gate or prompt
shows. A returning sign-in's connection (also a failed one, whose cause shows
there) and a connection the person selects never give way. No switch happens
while a registered guard holds work (a draft, a pending or unconfirmed write);
the gate then blocks as before. A Pod outside the preset is never used, and
allowedPods keeps foreign records out of the snapshot.
The 5-second grace period is a starting value: a healthy discovery answers
well within a second. With a single Pod, startup lasts as long as its
restoration (see the bounds above). While the choice is open,
AppSnapshot.starting stays true, so AppAccess shows its
startup screen, not a
gate.
Client ./oauth accepts an OAuthBinding: discovered Pod facts, a client identity
and requested scopes. It creates a portable AuthorizationAttempt with state and
PKCE verifier, validates callbacks and exchanges tokens. Preparation and exchanges
capture detached protocol inputs before awaiting; caller mutations cannot change
the binding used to validate an answer. Its ./oauth/host entry provides
validateOAuthBinding (checks structure and returns an immutable copy; it does
not rediscover a Pod or establish freshness) and the portable token/claim
evidence validation parseStoredCredentials that this runtime builds on.
App-sdk owns SessionBinding and its storage envelope: configuration and connection
IDs, generation, record version, attempt timestamps, the ten-minute authorization
lifetime and the same-origin return location. Its session parser validates that
envelope before claiming an attempt. These types/parsers are internal; neither
client consumers nor ordinary browser apps need them.
A client context or runtime BoundView can be passed directly to
createResourceEditor from @sempods/client-sdk/edit. The consuming UI owns target
changes, access updates and bounded silent recovery; the editor does not select
another target automatically. The edit-source boundary preserves invalidated reads as unavailable;
integration tests exercise it with the runtime-bound editor.
In the SDK repository, pnpm test covers persistence, callback, refresh and
invalidation races with deterministic transports and the production client.
pnpm test:runtime installs packed SDKs outside
the workspace and runs Chromium with real redirects, PKCE exchanges, IndexedDB and
Web Locks against a loopback server. It checks sequential multi-Pod, reload,
did:web without DCR, reactive refresh, renewal of expired short-lived tokens
before dispatch (for Pods refusing them with or without a challenge), cookie omission, Context-scoped and bound Pod queries,
and editor saves with strong If-Match, conflicts and unknown write outcomes.
The unknown-outcome scenario applies the request on the server and deliberately
withholds its answer at the test network boundary. The SDK does not resend it;
this is not a guarantee against retries inside a browser's HTTP stack.
Chromium 153 resends a request on its own when a reused keep-alive connection
closes without an answer, also after the Pod applied it; on a fresh connection
it reports a network error instead. The write conditions turn such a resend into
a 412, so nothing is applied twice, but the SDK sees the 412 instead of a lost
answer. A creation therefore reports every failed create-only condition as
unconfirmed and keeps its IRI; desiredObserved tells whether the IRI holds
its body. An update reports a conflict. Its comparison usually shows that the
Pod already holds the change, but it cannot prove it: the read may fail, or
another writer may have changed the fields since. A resent deletion finds the resource gone: a Pod answering 412
yields a conflict, one answering 404 yields not-removed with reason
not-found. Neither tells whether this deletion or another writer removed it.
Supported environments: current browsers with IndexedDB and Web Locks in a normal browser tab; automated checks run in Chromium. Installed PWAs are experimental: desktop Chromium and Android are expected to work, iOS/iPadOS home-screen apps are unverified. Sign-in returns to the app in the same window, so the callback must land in the storage that holds the attempt; the runtime never transfers attempts or tokens between storage containers. See supported environments.
Sign-in against a deployed Kotlin Pod in Chrome is recorded as live evidence for
a dynamic client on a loopback origin; a deployed did:web origin is not.
React AppAccess and localized
recovery are covered by the authoring guide and packed TODO
checks. Multi-tab concurrent operation and revocation are not implemented
here. Apps without sign-in have
live evidence
for 0.8.0: a deployed Pod's public data read from another origin, signing in
and out under optional, and two tabs under none. A session that ends through
a refused renewal is covered by fixture tests only.