- Status: Draft
- Version: 0.10
- Related documents: threat-model.md, #5305, #3292, #4065, #5354, #5162, #5155, RFC 6749, RFC 7636, RFC 9396, OpenID Connect Core 1.0, OpenID Connect Back-Channel Logout 1.0, back-channel logout specification
ThunderID publishes client SDKs across four repositories and three ecosystems. Nothing today states what an SDK must implement, so each one is built to the conventions of whoever writes it. Without a stated contract, a developer moving between platforms cannot predict the surface, and a reviewer of a change in one repository has no way to tell whether the sibling repositories need the same change.
This specification is the contract every ThunderID SDK implements. It defines the layering, the operational modes, the configuration keys, the client surface, the error model, the security floor, how each platform packages and builds its SDK, what has to be tested, and the delivery rules that make a change in one SDK visible in the others.
Every SDK change goes through it. That includes writing a new SDK for a platform that has none, adding or changing a capability in an SDK that already exists, and building an integration package. The specification is the reference a contributor works from, the checklist a reviewer works against, and the context an AI coding agent is given before it writes SDK code.
The contract is behavioural rather than literal. An SDK conforms by exhibiting the specified behaviour through the idioms of its own platform, so a Swift signature is expected to look like Swift. Conformance is judged on names, returned concepts, and observable behaviour, not on transliterated signatures.
Scope is the SDK repositories listed in Repository topology and the integration packages that adapt ThunderID into third-party auth frameworks. The ThunderID server, the console, the CLI, and the MCP server are out of scope, as is the documentation site itself beyond the obligations this document places on SDK authors.
A layer is a set of responsibilities, not a package. Every SDK covers at least one layer, and each layer builds on the one below it, inheriting its contract and extending it with capabilities that only make sense at that level.
| Layer | Responsibility | Builds on | Ships UI |
|---|---|---|---|
| Agnostic | The full client surface and all protocol logic: authorization requests, token exchange, JWT handling, flow orchestration, the error model. No platform, browser, or framework dependency. | Nothing | No |
| Platform | Platform capabilities: native secure storage, platform crypto, redirect and callback handling, platform session management. | Agnostic | No |
| Core Lib | A framework's reactive primitives (state, lifecycle, context), and the developer-facing entry point. | Platform | Optional |
| Framework Specific | Thin integration for an opinionated or meta framework: server-side rendering, routing conventions, framework-native initialization. | Core Lib | Optional |
One package usually covers one layer, which is how the JavaScript packages are built. It does not have to: where the lower of two adjacent layers has no consumer that wants it on its own, one package covers both, which is how the Apple and Android packages are built. The two ecosystem sections below show each shape concretely, and the table in Platform packaging and build says which packages cover which layers.
flowchart TD
A["<b>Agnostic</b><br/>Client surface, protocol logic<br/>JWT handling, error model"]
B["<b>Platform</b><br/>Secure storage, crypto<br/>Redirect and callback handling"]
C["<b>Core Lib</b><br/>Reactive state, lifecycle<br/>Developer entry point, UI"]
D["<b>Framework Specific</b><br/>SSR, routing conventions<br/>Framework-native initialization"]
A --> B --> C --> D
One package per layer, all four layers present. @thunderid/javascript holds the protocol with
no platform dependency, and the two Platform packages take it to the browser and to Node.
flowchart TD
JS["@thunderid/javascript<br/><i>Agnostic</i>"]
BR["@thunderid/browser<br/><i>Platform</i>"]
NO["@thunderid/node<br/><i>Platform</i>"]
RE["@thunderid/react<br/><i>Core Lib</i>"]
VU["@thunderid/vue<br/><i>Core Lib</i>"]
NX["@thunderid/nextjs<br/><i>Framework Specific</i>"]
NU["@thunderid/nuxt<br/><i>Framework Specific</i>"]
RR["@thunderid/react-router<br/><i>Framework Specific</i>"]
TR["@thunderid/tanstack-router<br/><i>Framework Specific</i>"]
EX["@thunderid/express<br/><i>Framework Specific</i>"]
JS --> BR
JS --> NO
BR --> RE
BR --> VU
RE --> NX
NO --> NX
VU --> NU
RE --> RR
RE --> TR
NO --> EX
The same layers, packaged differently. Apple and Android collapse Agnostic into Platform: there is no separate language-only SDK, because nothing consumes the protocol implementation without the platform capabilities that go with it. Splitting them would produce a package nobody depends on.
flowchart TD
subgraph Apple ["Apple, one Swift package"]
IOS["ThunderID<br/><i>Agnostic and Platform</i><br/>Protocol, Keychain, ASWebAuthenticationSession"]
SUI["ThunderIDSwiftUI<br/><i>Core Lib</i><br/>Environment, state, views"]
IOS --> SUI
end
subgraph Droid ["Android, one Gradle library"]
AND["dev.thunderid.android<br/><i>Agnostic and Platform</i><br/>Protocol, Keystore, Custom Tabs"]
CMP["dev.thunderid.compose<br/><i>Core Lib</i><br/>Composables, state"]
AND --> CMP
end
Flutter adds no protocol implementation of its own. It sits at Core Lib and bridges to both native Platform SDKs:
flowchart TD
FL["thunderid_flutter<br/><i>Core Lib, bridged</i><br/>Widgets and state in Dart"]
PCI["Platform channel<br/>ThunderIDFlutterPlugin, Swift"]
PCA["Platform channel<br/>ThunderIDFlutterPlugin, Kotlin"]
IOS2["ThunderID<br/><i>Agnostic and Platform</i>"]
AND2["dev.thunderid.android<br/><i>Agnostic and Platform</i>"]
FL --> PCI --> IOS2
FL --> PCA --> AND2
Two shapes depart from the strict chain and are allowed:
- Bridged cross-platform SDKs. A Core Lib SDK may take two parents, one per bridged
platform, as
thunderid_flutterdoes above. A React Native SDK, if built, follows the same pattern over native modules. - Dependency-injection frameworks. A framework whose module or injection system makes an intermediate reactive layer redundant may sit at Framework Specific directly on a Platform SDK. Angular is the expected case.
SDKs no longer live in the product monorepo. Each ecosystem owns a repository, and a repository may contain several packages across several layers.
| Repository | Contents | Registry |
|---|---|---|
thunder-id/javascript-sdks |
All JavaScript and TypeScript packages, all four layers, plus integration packages | npm, scope @thunderid |
thunder-id/ios-sdks |
ThunderID (Agnostic and Platform) and ThunderIDSwiftUI (Core Lib) |
Swift Package Manager and CocoaPods |
thunder-id/android-sdks |
dev.thunderid.android (Agnostic and Platform) and dev.thunderid.compose (Core Lib) |
Maven coordinates under dev.thunderid |
thunder-id/flutter-sdks |
thunderid_flutter (Core Lib, bridged) |
pub.dev |
thunder-id/thunderid |
This specification, the published documentation under docs/, and the minimal use-case samples that ship with the product |
Not applicable |
thunder-id/samples |
Feature demos and showcases, organized by feature area | Not applicable |
The split means a single capability now lands as several pull requests in several repositories with no shared branch, no shared CI run, and no single reviewer who sees all of it. Cross-SDK parity and delivery is the mechanism that holds those pull requests together, and it is the reason this document exists rather than being a page in the contributor guide.
- An SDK MUST declare exactly one parent layer. Two cases take more than one parent package:
a bridged cross-platform SDK, which takes one per bridged platform, and a Framework Specific
SDK for a full-stack framework, which takes a Core Lib parent for its client half and a
Platform parent for its server half.
@thunderid/nextjsis the second case, building on@thunderid/reactin the browser and@thunderid/nodeon the server. Both parents MUST sit at or below the SDK's own layer, and the SDK MUST document which parent serves which half. - Two adjacent layers MAY be collapsed into one package where the lower one has no consumer of its own, as the Apple and Android packages collapse Agnostic into Platform. The package MUST still keep the layers separable in its own structure, and MUST document which layers it covers.
- An SDK MUST NOT skip its immediate parent layer. If a capability is reachable through the parent, the SDK uses the parent rather than reaching past it.
- An SDK MUST NOT reimplement logic already present in its parent, and MUST NOT expose the parent's internal types through its own public surface.
- An SDK MUST declare its parent as a versioned dependency. In JavaScript, a Framework
Specific package MAY express that dependency as a peer dependency where the ecosystem
expects the application to own the version, as
@thunderid/react-routerand@thunderid/tanstack-routerdo today. - A breaking change in a layer requires a major version bump in that layer and in every layer above it that is affected.
- Every SDK MUST record the version of this specification it implements, in its
README.md.
An integration adapts ThunderID into a third-party framework that already owns an auth abstraction, such as Better Auth or Auth.js. An integration implements the target framework's provider or plugin interface instead of the ThunderID client surface, and sits outside the layer hierarchy.
An integration MUST delegate every protocol operation to a ThunderID SDK, MUST NOT implement
OAuth 2.0 or OIDC logic of its own, MUST follow the target framework's conventions for
configuration, errors, and sessions, and MUST document the SDK version and the framework
version it supports. Integrations live alongside SDKs in the ecosystem repository, under
packages/, and are published under the same scope, as @thunderid/better-auth is today.
Each ecosystem packages its SDKs the way that ecosystem expects. An SDK MUST declare its minimum supported platform version, and MUST NOT raise that minimum in a patch or minor release.
| Ecosystem | Unit of distribution | Layers per unit | Minimum platform |
|---|---|---|---|
| JavaScript | One npm package per SDK, in a pnpm workspace built with Turborepo | One layer per package | Stated per package |
| Apple | One Swift package exposing two products, plus a CocoaPods podspec for the Platform product | ThunderID covers Agnostic and Platform, ThunderIDSwiftUI covers Core Lib |
iOS 16, macOS 13, Swift 5.9 |
| Android | One Gradle library, consumed through JitPack | dev.thunderid.android covers Agnostic and Platform, dev.thunderid.compose covers Core Lib |
minSdk 26, compileSdk 34, JVM target 17 |
| Flutter | One pub.dev plugin package declaring an Android and an iOS platform implementation | Core Lib only, bridged | Flutter 3.19, Dart 3.3 |
Rules that follow from this shape:
- An Apple or Android SDK MUST keep the Core Lib product separable from the Platform product, so an application that supplies its own UI can depend on the Platform layer alone.
- A bridged SDK MUST pin the native SDKs it bridges to as versioned dependencies, one per platform, and MUST NOT depend on a floating version. The pins are what make a native change reach the bridged SDK, so each repository MUST have a mechanism that raises them after a native release.
- A bridged SDK MUST NOT implement protocol logic on the Dart or JavaScript side. A capability that is missing from one native SDK is a parity gap in that native SDK, not something to work around in the bridge.
- A platform channel surface MUST mirror the client surface names, so that a capability keeps one name from the native SDK through the bridge to the application.
- Platform capabilities that have no cross-platform equivalent, such as Play Integrity on Android and App Attest on Apple platforms, are declared by the Platform SDK that owns them and exposed through a single bridged name where a bridged SDK supports both.
An SDK supports two modes. The mode is chosen at initialization and applies to every operation for the lifetime of the client.
Redirect mode is the default. The SDK runs the OAuth 2.0 authorization code flow with PKCE, sending the user to the ThunderID authorization endpoint and handling the callback. It is the mode for anything that can safely redirect and receive a callback, and it is the mode that keeps the application away from user credentials entirely.
Embedded mode, also called app-native, drives the ThunderID Flow Execution API directly and
keeps the user inside the application. The SDK posts to /flow/execute with an applicationId
and a flowType, receives an executionId with a flowStatus of INCOMPLETE and a
description of the inputs or actions the step requires, and submits each step back with the
executionId, the chosen action, and the collected inputs. A flowStatus of COMPLETE carries
the assertion; ERROR carries a failureReason the SDK surfaces as an authentication failure.
Multi-factor steps arrive as further INCOMPLETE steps and are surfaced to the application the
same way. It is the mode for native mobile and for any application that renders its own
authentication UI.
The mode is set through the mode configuration key, taking redirect or embedded. An SDK
MAY additionally infer embedded from configuration that only makes sense in that mode, such
as a sign-in path owned by the application, but inference is a convenience and MUST NOT be the
only way to select a mode.
Embedded mode also has a server-side prerequisite: the application has to be configured on the ThunderID server to permit it. Client configuration alone selects the mode, it does not grant it, and an application whose server configuration does not allow embedded flows will be refused at the flow endpoint rather than at initialization.
The mode MUST NOT change the public surface. signIn() is signIn() in both modes; the SDK
resolves the underlying flow internally.
Alongside the two user-facing modes, an SDK MAY support a client_credentials grant type for
machine-to-machine use, in which there is no user and no sign-in step, and getAccessToken()
fetches and refreshes a token for the service itself.
client_credentials is valid only with mode: redirect, which in this combination means only
that no embedded flow is driven. Pairing it with mode: embedded MUST be rejected at
initialization. It is a confidential-client grant, so an SDK that cannot hold a client secret
safely, which is any SDK running in a browser or a mobile application, MUST reject it outright.
The user-facing operations have no meaning without a user. Under client_credentials,
signIn, signUp, signInSilently, handleRedirectCallback, getUser, getUserProfile,
updateUserProfile, and getUserSchema MUST fail with a single stable unsupported-operation
error rather than returning an empty result. isSignedIn reports whether a valid token is
held, and signOut discards it.
Configuration is a single object supplied at initialization. Every SDK MUST implement the required keys and SHOULD implement the optional ones. A key that cannot apply on a platform MUST be documented as unsupported there rather than silently ignored.
Key names are canonical across SDKs, adapted only for the naming convention of the language. An SDK MUST NOT rename a canonical key, and MUST NOT introduce a second name for a concept this table already covers.
Core
| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
baseUrl |
String | Yes | None | Base URL of the ThunderID server. MUST be rejected if the scheme is not HTTPS. A non-HTTPS loopback address MAY be accepted for local development only, and MUST be rejected in embedded mode, where credentials cross the wire. |
clientId |
String | Conditional | None | Required in redirect mode. |
clientSecret |
String | No | None | Confidential clients only. MUST NOT be accepted by a browser or other public client. |
mode |
Enum | No | redirect |
redirect or embedded. |
grantType |
Enum | No | authorization_code |
authorization_code or client_credentials. |
applicationId |
String | Conditional | None | Required in embedded mode and for branding resolution. |
instanceId |
Integer | No | None | Enables independent authentication contexts in one application. Every piece of per-context state MUST be namespaced by it: storage keys, in-flight callback state, refresh deduplication, and token caches. Two contexts MUST NOT be able to read or overwrite each other's tokens. |
Redirection
| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
afterSignInUrl |
String | No | Framework default | Must be pre-registered with the application. |
afterSignOutUrl |
String | No | Framework default | Must match an allowed post-logout URI. |
signInUrl |
String | No | Server-hosted page | Application-owned sign-in page. |
signUpUrl |
String | No | Server-hosted page | Application-owned sign-up page. |
Protocol
| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
scopes |
String or list | No | openid |
Space-separated string or list. |
authorizationDetails |
List | No | None | Authorization details (RFC 9396): a list of objects, each with a string type. Sent JSON-encoded as authorization_details on the authorization request, silent sign-in included, on the CIBA backchannel authentication request, and on the client_credentials token request. A value passed to a single sign-in or CIBA call takes precedence over the configured one. Not sent in embedded mode. A request an SDK does not make, or cannot add it to, is documented as unsupported, as for any key. See Authorization details. |
signInOptions |
Map | No | Empty | Extra parameters on the authorize request. state, code_challenge, code_challenge_method, client_id, and redirect_uri are SDK-owned: a caller value for any of them MUST be ignored, and the SDK's own value used. |
signOutOptions |
Map | No | Empty | Extra parameters on the sign-out request. |
signUpOptions |
Map | No | Empty | Extra parameters on the sign-up request. |
discovery |
Object | No | Enabled | OIDC discovery behaviour. Discovered metadata MUST be fetched over HTTPS, and its issuer MUST match the expected issuer exactly before any endpoint from it is used. |
endpoints |
Object | No | Discovered | Per-endpoint overrides for a server that does not publish discovery. Every override MUST use HTTPS and MUST share the origin of baseUrl, unless the application has explicitly allowed the other origin. |
tokenRequest |
Object | No | Platform default | Token endpoint authentication and request shaping. |
http |
Object | No | None | HTTP options. http.fetcher replaces the transport for management operations only. |
Session and tokens
| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
storage |
Storage adapter | No | Platform default | See Security requirements. |
tokenValidation |
Object | No | Validation on | Clock tolerance, and per-claim switches that MUST be rejected when they would disable a check required by Security requirements against a non-loopback baseUrl. Disabling a mandatory check is a test affordance, not a deployment option. |
tokenLifecycle |
Object | No | Platform default | Refresh timing and lifecycle behaviour. |
allowedExternalUrls |
List | No | Empty | Origins the SDK may attach an access token to when tokens are held in isolated storage. Every entry MUST use HTTPS. See Token attachment for how entries are matched. |
session |
Object | No | Disabled | Browser SDKs only. Behaviour around the server's SSO session. silentSignIn.beforeRedirect (default false) makes signIn try a silent prompt=none sign-in first and continue with the redirect when it fails; it MUST be skipped when the caller sets its own prompt. silentSignIn.timeout (milliseconds, default 10000) bounds how long a silent sign-in waits before reporting the user as signed out, including from signInSilently. Silent sign-in only finds the session when the browser sends the server's session cookie to the iframe, which needs the application on the same site as the server. |
backchannelLogout |
Object | No | Disabled | Server-side SDKs only. For an SDK that mounts the back-channel logout handler itself, turns on back-channel logout handling: enabled, the path of the handler, and the store that records ended sessions. An SDK that exposes the handler for the application to mount takes the store on the handler instead and does not read this key. An SDK that cannot receive the request MUST document the key as unsupported. |
organizationHandle |
String | No | None | Organization identifier, required when a custom domain is configured. |
organizationChain |
Object | No | None | Chained authentication across organization contexts. |
Presentation
| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
preferences |
Object | No | None | Theme, internationalization, and user presentation options. SDKs without bundled UI MAY omit it and MUST say so. |
components |
Object | No | None | Per-component overrides for SDKs with bundled UI. |
extensions |
Object | No | None | Extension points for SDKs with bundled UI. |
Initialization MUST validate the object and fail before any network call when a required key is missing or a value is malformed. Any operation invoked before initialization MUST fail with a distinct, documented error rather than a null dereference.
Every SDK MUST expose the operations below. Names are canonical; the signature is whatever the platform makes idiomatic. Return types are stated as the concept returned, and an SDK MUST NOT return a different concept under the same name.
Lifecycle
| Operation | Contract |
|---|---|
initialize |
Validates configuration and prepares the client. Returns success. |
reInitialize |
Applies a partial configuration change without a full restart. mode, grantType, clientId, applicationId, and instanceId are immutable for the life of a client: a change to any of them MUST be rejected rather than partially applied. Changing one means constructing a new client. |
getConfiguration |
Returns the effective configuration. |
isLoading |
Synchronous. True while initializing or refreshing. |
Authentication and registration
| Operation | Contract |
|---|---|
signIn |
Redirect mode starts the authorization code flow; embedded mode drives one step of the flow. Overloaded, or discriminated by payload, per platform idiom. |
signOut |
Terminates the session. Revokes the refresh token server-side, then clears local state. Succeeds silently when no session exists. When revocation cannot be reached, the SDK MUST still clear local state, and MUST report the failed revocation to the caller rather than reporting a clean sign-out. Leaving the user signed in locally because the network was down is not an option. |
signUp |
Redirect mode sends the user to registration; embedded mode drives the registration flow. |
isSignedIn |
Returns current authentication state. |
handleRedirectCallback |
Completes a redirect flow from the callback URL. Required wherever the SDK does not handle the callback implicitly. |
Tokens and session
| Operation | Contract |
|---|---|
getAccessToken |
Returns a valid access token, refreshing transparently when near expiry. |
exchangeToken |
Performs a token exchange (RFC 8693). |
decodeJwtToken |
Decodes a JWT payload without verifying its signature. MUST be documented as unsafe for authorization decisions. |
setSession, clearSession |
Write and clear stored session state. |
User and profile
| Operation | Contract |
|---|---|
getUser |
Returns the authenticated user. |
getUserProfile |
Returns the user's profile attributes. |
updateUserProfile |
Applies attribute updates server-side. Returns the updated profile. |
getUserSchema |
Returns the attribute schema that describes which profile fields exist, their types, and their mutability. |
Operations beyond this set are permitted where a platform needs them, and are the usual origin of a parity gap. Silent sign-in, CIBA, passkey registration and authentication, platform attestation, flow metadata retrieval, and account recovery all sit here: each is meaningful on some platforms and not on others. An SDK adding an operation in this position MUST follow Cross-SDK parity and delivery.
Organization operations (listing, reading, and switching organizations) are a specification target and are deliberately not part of the required surface yet. An SDK MUST NOT ship a partial implementation of them ahead of a specification update.
Management operations let an application administer ThunderID resources, so that an organization can build its own console, or embed part of one in its product, without calling the management API by hand. They are optional: an SDK MAY ship them, and one that does MUST follow this section.
The initial resources are applications, users, and agents. Each exposes the same five
operations, named for the resource in the platform's idiom (getApplications,
client.applications.list, and so on):
| Operation | Contract |
|---|---|
| List | Returns one page of the resource, with the total count. Accepts limit and offset, and a filter where the server supports one. |
| Get | Returns a single resource by identifier. |
| Create | Creates the resource and returns it as the server stored it. |
| Update | Replaces the resource's mutable fields and returns the updated resource. |
| Delete | Deletes the resource. Returns nothing. |
Requirements:
- Requests are authorized with the signed-in user's access token. The SDK MUST NOT mint, widen, or cache a separate credential for them. Whether a call succeeds is the server's decision, and the token needs the permissions the server requires for that resource.
- The management API can run on a different host from the authorization server. The request
URL for each resource MUST come from, in order: an explicit URL passed to the call, then an
endpointsoverride for that resource's collection (applications,users,agents), thenbaseUrlfollowed by the collection path. A single resource is addressed as the collection URL followed by its identifier. - The transport MUST be replaceable by the application through a
fetcher. Afetcherpassed to a single call takes precedence overhttp.fetchersupplied at initialization, which takes precedence over the SDK's default authenticated transport.http.fetcherapplies to management operations only. Authentication, token, and flow requests MUST keep using the SDK's own transport until this specification says otherwise. - A Core Lib or Framework Specific SDK MAY wrap these operations in its framework's reactive model, such as a hook, an observable object, or a state holder. The wrapper MUST NOT depend on a third-party data fetching or caching library, so an application can use its own.
- The SDK MUST NOT produce a user-visible side effect from a management operation. It does not show a notification, translate a message, or write to the application's log. Success and failure are reported to the caller, who decides what the user sees.
- A resource returned by these operations is a server record, not the signed-in user. It MUST NOT reuse a type name the SDK already uses for the authenticated user.
- HTTP 403 and 404 MUST surface as distinct API error codes, so a caller can tell a missing permission from a missing resource.
Self user attribute verification lets a signed-in user prove control of a contact attribute in their
own profile, such as an email address or mobile number, by entering a code the server sends
to it or by opening a link it sends. It runs a SELF flow named by its handle; the
flow picks the email or mobile path from the attribute's type. It is optional: an SDK MAY ship
it, and one that does MUST follow this section.
| Operation | Contract |
|---|---|
| Verify attribute | Executes one step of a SELF flow, by default default-self-attribute-verification-flow, for a named attribute of the signed-in user. Returns the step; COMPLETE means the server recorded the verification. |
Requirements:
- Every request, the initiating one and each continuation, is sent through the SDK's authenticated transport. The server takes the user from the access token on the initiating request and keeps it for the execution, so the SDK MUST NOT send a user identifier or an application ID.
- The request URL comes from an explicit URL passed to the call, then the
flowExecuteendpoint override, thenbaseUrlfollowed by/flow/execute. - A request that starts a verification sends
flowType: SELF, the flowhandleand the attribute. The handle defaults todefault-self-attribute-verification-flowand an application MAY name another. The SDK MUST reject a new flow without a handle before any network call. - Steps are rendered from the server-described components, as the embedded sign-in, sign-up
and recovery components do, so input and action identifiers are not hard-coded. A rejected
code returns the step again with an error and without the first step's additional data, so
the SDK keeps the masked destination and code length from the step that sent the code.
A
RESENDcomponent submits its own action with no inputs and without client-side validation, so the user can ask for a new code with the code field empty or partly typed.ERRORor an HTTP 4xx is a refusal, reported to the caller without the response body. A step with no input and no action waits for a link the user opens outside the application: the SDK shows where the link went and a Done action that re-reads the profile, and MUST NOT poll. - Verification status comes only from the read-only
verifiedAttributesfield of/users/me. The SDK MUST NOT write it, infer it from another field, or mark an attribute verified locally. AfterCOMPLETEit re-reads the profile. An absentverifiedAttributesmeans the status is unknown: the SDK MUST show neither verified nor unverified and MUST NOT offer the verify action on that basis. - Status is shown for top-level single-valued schema properties of type
emailormobilethat hold a value. The verify action is offered foremailandmobile, and only for a stored value, never one being edited. Saving an email address or mobile number updates the stored value and its reported verification status. The profile MUST wait for an explicit Verify action to start verification. - Starting a verification sends a message, so a component that starts one when shown MUST start it once per showing and MUST NOT retry automatically.
- A UI SDK ships a verify-attribute component with a
Basevariant, and its user profile component shows each eligible attribute's status and, for an unverified email or mobile number, the verify action.
When a session ends at the ThunderID server, the server notifies every application that took part in it and registered a back-channel logout URI, by sending a logout token to that URI (OpenID Connect Back-Channel Logout 1.0; what the server sends is defined in the back-channel logout specification). Handling the notification lets an application end its own session at once, rather than when its tokens next fail. It is optional: an SDK MAY ship it, and one that does MUST follow this section.
It applies only where the SDK runs on a server the ThunderID server can reach, which is the Node Platform SDK and the Framework Specific SDKs built on it. An SDK that runs only in a browser or in a mobile application has nothing that can receive the request. It MUST NOT expose the operation, and it relies on revocation instead: the server revokes the session's tokens, so the next refresh fails.
| Operation | Contract |
|---|---|
handleBackchannelLogout |
Takes the raw logout_token. Validates it per Security requirements, ends every local session it names, and returns the sid, the sub, and the number of sessions ended. Fails with a documented error when the token is not valid. |
A Framework Specific SDK exposes the operation as a request handler in its framework's idiom, such as a middleware factory, a route handler, or a server route, mounted at the path the application registered as its back-channel logout URI.
Requirements:
- The request is a
POSTwith anapplication/x-www-form-urlencodedbody carrying onelogout_tokenparameter. The handler MUST reject any other method or content type and MUST cap the size of the body it reads. It MUST NOT require a session cookie or any other credential: the token's signature is the authentication. - The handler answers
200when the token is valid, including when it names no session the application holds, so that a retried notification is harmless. It answers400when the request or the token is not valid. It answers a5xxonly when it could not record the logout, which tells the server to retry. Every response carriesCache-Control: no-store. - A token with a
sidends the sessions bound to thatsid. A token with only asubends every session of that subject that began before the token was issued, so a user who has already signed in again is not signed out a second time. The cutoff is extended by the clock tolerance the token was validated with, since the clocks may differ by that much and ending a session that began just after the logout is the safer mistake. To make the first possible, the SDK MUST record thesidof the ID token against the session it creates at sign-in. - Ending a session here is local. The SDK MUST NOT call the revocation or end session endpoint, which the server has already dealt with, and MUST NOT redirect.
- Where sessions are held on the server, the SDK removes the session's stored state. Where the session is held in a cookie, which the server cannot delete, the SDK MUST record the logout and refuse every later request that presents a matching session, for at least as long as such a session could remain valid.
- Whatever records the logout, the session store or the list of ended sessions, MUST be replaceable by the application. The default MAY be in memory, and the SDK MUST document that a deployment with more than one instance needs a shared one, because the notification reaches only one of them.
- Ending the SDK's session does not recall an access token the application already handed to a browser or to another service. That token stays usable until it expires, and the SDK MUST document this.
- An SDK that cannot decrypt an encrypted logout token MUST document that back-channel logout is unsupported for a client configured for ID token encryption.
Authorization details (RFC 9396) let an application ask for a specific grant, such as one
payment of a stated amount, rather than a broad scope. The SDK sends the requested details
from authorizationDetails, and surfaces the details the server granted:
- Where an SDK returns a token response to the caller, it carries the granted details as
authorizationDetails, as the server returned them. - The granted details are also readable from the access token's
authorization_detailsclaim, so a caller that holds only the token can read them. The resource server, not the SDK, enforces them. - The server may grant less than was requested, since the user can deny or narrow a detail. The SDK MUST report what was granted, never the request in its place, and MUST NOT treat a difference as an error.
- Detail values can carry personal or financial data, such as an account number, and fall under the personal data rules in Logging.
Consent. Authorization details are decided only in a consent prompt that the authorization server renders. An embedded-mode flow cannot carry them, because in that mode the application that requests a detail would also present it for approval. An SDK whose components render the server's consent step renders each authorization details element:
- The element's summary, and one row per field.
- For a field the user may change, an input that permits only the change the row's
modificationallows, bounded by the value shown, and limited to the row'soptionswhere it carries them. - Approval blocked while a changed field is invalid. Deny is always available.
- One decision per element, carrying the fields the user changed as
modified, keyed by field path, and nothing else.
An SDK that does not render consent needs only the request and response behaviour above.
A Core Lib or Framework Specific SDK MUST integrate into its framework's own composition model, and initialization MUST happen once, at the application root, never inside a child component. Configuration MUST be validated there, before the application renders.
The expected shapes are a provider component in React, a plugin in Vue, an environment modifier in SwiftUI, an inherited widget in Flutter, and a module or standalone provider in a dependency-injection framework.
The SDK MUST provide a single primary entry point that exposes the authentication surface: one hook, one composable, one service, or one environment object. An application MUST NOT need to combine several of them to perform a standard flow. Supplementary entry points for optional concerns such as theming, internationalization, or form state MAY be exported in addition, and MUST NOT be required for authentication.
A Core Lib or Framework Specific SDK that targets a UI platform MUST ship components covering the identity flows, so that an application gets working authentication UI without writing its own.
| Category | Purpose | Components |
|---|---|---|
| Actions | Trigger an operation | Sign-in button, sign-out button, sign-up button |
| Auth flow | Handle the redirect callback | Callback |
| Control | Render conditionally on auth state | Signed-in, signed-out, loading |
| Presentation | Render identity UI | Sign-in, sign-up, recovery, accept invite, invite user, user, user avatar, user dropdown, user profile, verify attribute, language switcher |
Requirements:
- A component MUST work with no configuration beyond what the root provider already has.
- A component with non-trivial layout MUST ship an unstyled variant alongside the styled one,
so an application can replace the presentation without forking the logic. The established
convention is a
Baseprefix. - Components MUST be themeable through
preferences, and MUST support the configured internationalization. - Components MUST meet WCAG 2.1 AA.
- In embedded mode, the sign-in and sign-up components MUST render the server-described flow step rather than a hard-coded form, so that a change to the server flow does not require an SDK release.
A component that renders a server-described flow step MUST tag each element it renders with a stable identifier derived from the server's own response, exposed through the platform's accessibility tree:
| Element | Identifier |
|---|---|
| An input rendered from a flow field | thunderid-field-<field id> |
| A control rendered from a flow action | thunderid-action-<action ref> |
The identifiers track the server's flow definition rather than the SDK's view hierarchy, so they stay stable when the presentation changes and move with the flow when it does. They are what the end-to-end suites use to drive authentication without hard-coding native view structure, and they carry an accessibility benefit on every platform that surfaces them.
Platforms expose this through their own mechanism: an accessibility identifier on Apple
platforms, a test tag or content description on Android, Semantics.identifier in Flutter, and
the element id in the browser. The requirement is on the identifier value, not the mechanism.
An SDK that ships UI MUST ship translations for the strings it renders, and MUST let an application override them without forking a component.
- Strings rendered by SDK components MUST come from a translation bundle, never from a literal in the component.
- The SDK MUST ship a default bundle and MUST resolve to the configured fallback language when the active language has no translation for a key.
- An application MUST be able to supply its own bundles through
preferences.i18n.bundles, merged over the shipped ones rather than replacing them wholesale. - Language selection MUST be persisted through the configured storage strategy, and an SDK that supports a URL parameter override MUST allow it to be disabled.
- Text rendered from a server response, such as a flow field label, is already localized by the server and MUST NOT be translated again by the SDK.
Theming follows the same shape. Components MUST honour the configured mode and direction, MUST accept partial token overrides without requiring a full theme object, and MUST be able to resolve branding from the server where the platform supports it, so that an application picks up organization branding without shipping a new build.
Errors are surfaced through a single hierarchy, so an application catches one type and switches on a code.
| Type | Carries |
|---|---|
| Base error | message, code, origin |
| API error | The base fields, plus HTTP statusCode and statusText |
| Runtime error | The base fields, for a failure that is not an API response |
code is a stable, machine-readable string. origin identifies the package that raised the
error, which is what makes a failure traceable across a layered stack.
Requirements:
- Every SDK MUST use this hierarchy, mapped onto the platform's native error type.
- An error MUST be catchable through the platform's standard mechanism.
- The SDK MUST NOT swallow an error silently.
- An error message MUST NOT contain a credential, a token, or personal data.
- A code, once shipped, MUST NOT change meaning. Codes for the same condition SHOULD match across SDKs, and a new condition SHOULD reuse an existing code rather than coin a synonym.
- Automatic retry MUST NOT be performed. Two bounded exceptions apply: a token refresh, and the single JWKS re-fetch that Security requirements requires after a signature verification failure.
- Input validation MUST fail before any network call is made.
A shared catalogue of codes covering configuration, authentication, registration, recovery, and transport failures is a target this specification does not yet define. Until it does, an SDK MUST document the codes it raises.
These are the floor. An SDK MUST NOT ship below them, and no configuration key may be introduced to weaken one without an accompanying threat model update.
Token storage. Tokens go in the most secure store the platform offers: Keychain on iOS,
EncryptedSharedPreferences backed by the Keystore on Android, in-memory or worker-isolated
storage in a browser, an OS credential store on desktop, and an OS keyring on a server.
Browser localStorage and sessionStorage MUST NOT be the default. Environment variables are
not a token store: they are readable by every child process, land in process listings and crash
dumps, and cannot be rotated in place, so an SDK MUST NOT persist a token in one.
Every SDK MUST accept a caller-supplied storage adapter. That adapter is outside the SDK's control and can be weaker than the platform default, so an SDK MUST document that the secure default applies only when it is the one in use.
Isolated storage and token attachment. Where tokens are held in isolated storage and the
SDK proxies outbound requests, it MUST attach the access token only to a URL that matches
allowedExternalUrls, and MUST reject a request to anything else.
Matching is by parsed origin, comparing scheme, host, and port, with a path prefix that MUST
end at a path boundary. String prefix matching MUST NOT be used: it authorizes
https://example.com.attacker.test from an entry for https://example.com. Every entry MUST
use HTTPS, and an entry that does not MUST be rejected at initialization rather than skipped at
request time.
A redirect moves the request to a new URL, so the SDK MUST re-run the same check against every redirect target before following it, and MUST drop the authorization header rather than carry it to an origin that does not match.
PKCE. Mandatory in redirect mode, regardless of server configuration. The verifier is
cryptographically random, 43 to 128 characters drawn from the RFC 7636 unreserved set
(A-Z, a-z, 0-9, -, ., _, ~), held only in memory, and cleared as soon as the
exchange completes. The challenge method is S256; plain MUST NOT be used.
State. A cryptographically random state on every authorization request, validated on
callback. A mismatch fails authentication.
Federated redirects in embedded mode. A REDIRECTION step carries a redirectURL with a
state the server issued. The SDK opens it in a browser session and resubmits the callback's
code and state to the flow with the step's executionId and challenge token. A browser SDK
MUST accept a callback only from the popup it opened, either posted with the application's
origin or read from the popup's same-origin URL. No SDK may submit a callback that lacks a
code or a state: the server checks the state only when the client sends one, so a callback
submitted without one is checked nowhere. On mobile, the SDK MUST also reject, with
invalidGrant, a callback whose state differs from the state in redirectURL. It MUST
likewise reject every callback to a redirectURL that has no state or an empty one. After a
match, it resubmits the state from redirectURL. On Android any installed app can open the
callback scheme. On iOS, ASWebAuthenticationSession hands the callback straight to the
session, and iOS applies the same rules so the mobile SDKs follow one rule. The server always
issues a state, so neither rule rejects a genuine callback. The response to a submitted callback
MAY be another REDIRECTION, and the SDK MUST follow it the same way, in sign-in and sign-up
alike.
Endpoint trust. Every endpoint the SDK calls has to be one it trusts before it sends
anything to it. Discovery metadata is fetched over HTTPS, and its issuer MUST match the
expected issuer exactly, by string comparison, before any endpoint in the document is used. A
mismatch fails initialization; it MUST NOT fall back to a guessed endpoint. Endpoint overrides
are held to the same bar: HTTPS, and the origin of baseUrl unless the application has
explicitly allowed another. This applies to the token, revocation, JWKS, and flow endpoints
alike, because a substituted one of any of them receives credentials, tokens, or the keys used
to judge them.
Token validation. An ID token is validated for signature against the server JWKS, issuer, audience, expiry, and nonce where one was sent. The issuer MUST match exactly, not by prefix or suffix. JWKS keys are cached, and re-fetched once on a verification failure to tolerate key rotation.
Logout token validation. An SDK that handles back-channel logout accepts a logout token only
when all of these hold: the signature verifies against the server JWKS with an algorithm the SDK
accepts for ID tokens; the typ header is logout+jwt; the issuer matches exactly and the
audience contains the client identifier; iat and exp are within the configured clock
tolerance; the events claim has a http://schemas.openid.net/event/backchannel-logout member;
there is no nonce; and a sid or a sub is present. The typ, events, and nonce checks
are what stop an ID token from being replayed as a logout token, and none of these checks can be
configured off. The endpoint is unauthenticated, so the JWKS re-fetch that a verification failure
allows MUST be bounded in rate: otherwise a token with an unknown key identifier makes the SDK
fetch on every request. A jti seen before SHOULD be refused for the lifetime of its token. The
token MUST NOT be logged.
Credentials. In embedded mode, credentials are submitted immediately and MUST NOT be
retained beyond the call. Transport is HTTPS with no exception: the loopback allowance that
baseUrl carries for local development does not extend to embedded mode, so a client
configured for embedded mode against a non-HTTPS baseUrl MUST be rejected at initialization.
Certificate pinning SHOULD be available as an option on platforms that support it.
Logging. Access tokens masked; refresh tokens, passwords, one-time codes, and authorization codes never logged, nor a callback URL that carries a code; email addresses and phone numbers masked. These rules apply at every log level and before any caller-supplied logger is invoked. Values that are never logged are also kept out of the error messages and crash reports the SDK produces.
Sessions. Access tokens are refreshed ahead of expiry, refresh tokens are rotated on use
with stored tokens updated atomically, concurrent refreshes are deduplicated to a single
in-flight request, and sign-out revokes server-side before clearing local state. An SDK that
handles back-channel logout binds each session to the sid of its ID token, so the session can
be found when the server reports that sid ended.
Threats, trust boundaries, and residual risks are analysed in threat-model.md.
A capability counts as delivered once it exists in every SDK where it applies, or once its absence from an SDK is recorded with a reason. Merging it in one repository is the start of that, not the end.
The delivery rule. A pull request that adds, removes, or changes a capability in the public surface of one SDK MUST either link the corresponding pull requests in the other SDK repositories, or state why they are not needed.
What counts as not needed. A capability may legitimately stop at one platform. Valid reasons include a capability with no meaning on the other platforms (a browser worker storage mode has no mobile equivalent), a platform primitive that does not exist yet, a fix confined to one platform's implementation of shared behaviour, and a change that does not reach the public surface at all. "No time" is a deferral, not a reason: it is recorded as a tracked issue in the repository that lacks the capability, and the issue is linked.
What is exempt. Changes that do not touch the public surface: dependency updates, continuous integration and tooling, documentation, tests, and internal refactors. Exempt means exempt from porting, not from the decision. The decision is still recorded on the pull request, because whether a change reaches the other SDKs is a judgement a person makes, not one a file path can be trusted to make for them.
Enforcement. Every SDK repository carries a required check that blocks a pull request until the parity decision has been made on it. The decision is recorded on the pull request itself, in a form that survives the merge and can be queried across merged pull requests afterwards, since an unanswered decision on a merged pull request is what an audit looks for. A maintainer can record the decision by hand, which is the escape hatch when the check misjudges a change.
How the check reads the decision, and what it records it as, is implementation detail and is not
fixed here. The current implementation is a reusable workflow in this repository,
.github/workflows/sdk-parity-check.yml, called by each SDK repository.
Existing divergences. The rule applies from the point it is adopted. Capabilities that already differ between SDKs are reconciled through the normal issue backlog rather than retroactively through this check, so that adopting the rule does not block unrelated work.
Each SDK repository owns its own pipelines. There is no shared monorepo pipeline any more, so the requirement is on behaviour, not on a specific workflow file.
A repository MUST provide:
- A pull request pipeline that lints, builds, and tests every package the change touches.
- The parity check described above, as a required check.
- A release pipeline that publishes to the ecosystem registry on a version tag, and creates a release scoped to the package.
- A nightly or scheduled end-to-end run against a real server.
Packages within a repository are versioned and published independently, and reference each other through workspace paths in development.
Naming follows each ecosystem rather than a single cross-language pattern: @thunderid/* on
npm, PascalCase module names for Swift Package Manager products, reverse-domain coordinates
under dev.thunderid for Android, and snake_case for Dart packages.
An SDK is authentication code running in someone else's application, so its tests are part of this contract. Three levels are required, using each ecosystem's standard tooling.
| Level | What it covers | Tooling in use |
|---|---|---|
| Unit | Protocol construction and parsing, configuration validation, token and claim handling, error mapping, storage adapters, and the pure logic behind each component | Vitest, XCTest, JUnit, flutter test |
| Component | Rendered behaviour of the UI components, including the server-described flow step and the identifiers it emits | The ecosystem's component testing tool |
| End-to-end | A real sign-in and sign-up against a running ThunderID server, driving the quickstart sample as a user would | Playwright for web, Maestro for mobile |
Unit tests. Every public operation MUST have unit coverage for its success path and for each error it can raise. Security behaviour that this specification makes mandatory MUST be covered by a test that fails if the behaviour is removed: PKCE challenge derivation, state generation and comparison, ID token validation, the storage default, refresh deduplication, revocation ordering on sign-out, and, where the SDK handles back-channel logout, each check in logout token validation. Tests MUST NOT reach the network; server interactions are stubbed at the transport boundary.
Reference parity tests. Where an SDK reimplements behaviour that another SDK already defines, and the output has to match across platforms, the reimplementation MUST be tested against fixtures taken from the reference implementation rather than against its own output. Deterministic rendering such as avatar derivation from a seed is the usual case: the same seed has to produce the same avatar on every platform, and only a shared fixture proves it.
End-to-end tests. Every SDK with a quickstart sample MUST have an end-to-end suite that runs the sample against a real ThunderID server. The suite MUST cover sign-in and sign-out and sign-up as a minimum, MUST start from a clean application state, and MUST drive the UI through the flow element identifiers rather than through view structure or visible text, so that a copy change does not break a test and a flow change does.
The mobile suites share one shape across the three repositories: a Maestro workspace holding
signin.yaml, signup.yaml, and a config.yaml that keeps shared subflows out of the test
set, with reusable subflows for preconditions such as ensuring a signed-out start. A new
mobile SDK MUST follow the same shape, and a flow that exists in one mobile repository SHOULD
exist in the others.
End-to-end runs need a server configured for the SDK under test, so each repository MUST provision one as part of the suite rather than depending on a shared environment. The provisioning MUST live in the repository and MUST be reproducible on a developer machine, not only in CI.
Gating. Unit and component tests MUST run on every pull request. End-to-end suites MUST run at least nightly, and SHOULD be available on demand for a pull request that changes authentication behaviour. A pull request that changes behaviour without changing or adding a test is a review finding.
An SDK without documentation and a runnable sample is not shippable.
Documentation is authored in the product repository under docs/, and published to
thunderid.dev. Every SDK MUST have a quickstart that takes a
developer from nothing to a working sign-in with copy-pasteable code, and a reference covering
every public operation, configuration key, and type.
Samples follow the three-tier split agreed in
#4065: minimal use-case samples
ship with the product repository, each SDK repository owns its own quickstart samples
alongside the SDK, and feature demos live in
thunder-id/samples.
Every SDK at Core Lib or Framework Specific layer MUST ship at least one runnable sample in its own repository. A sample MUST run against a local server using only its documented environment variables, MUST NOT hardcode credentials or server URLs, MUST use only the public SDK surface, and MUST be built in CI.
The minimum a client-side sample demonstrates: an unauthenticated state, a sign-in that completes, an authenticated state showing display name, email, and picture or an initials fallback, and a sign-out returning to the unauthenticated state. For a server-side SDK: a public route that succeeds without credentials, a protected route that rejects a request with no token, and the same protected route returning claims with a valid token.
Writing a new SDK. A new SDK starts here rather than from another SDK's source. In order:
- Decide the layer and the parent, per Layers. If the platform has no protocol implementation, decide whether to write one or to bridge to existing Platform SDKs, per Platform packaging and build.
- Decide whether the thing being built is an SDK or an integration, per Integration packages.
- Implement the configuration object and the client surface, adapting signatures to the platform while keeping the canonical names and returned concepts.
- Implement the error hierarchy and meet the security floor.
- Add UI components if the layer and platform call for them, with translations and flow element identifiers.
- Add unit, component, and end-to-end tests, per Testing.
- Add the pipelines, the quickstart, the reference, and at least one sample.
- Record the specification version in the SDK's
README.md.
A new SDK is proposed through the design discussion process before implementation starts, and lands with the parity rule already applied. Its arrival usually creates gaps in the other direction, and those are tracked as issues rather than left implicit.
Changing an existing SDK. The same document governs a change to an SDK that already exists. Before the pull request is opened:
- Check whether the change touches anything this specification defines. A new operation, a configuration key, an error, a component, or a change to security behaviour all do.
- If the specification does not cover the capability yet, update the specification in the same change set. An SDK MUST NOT be the only record of a contract.
- Answer the parity question on the pull request, per Cross-SDK parity and delivery.
- Add or change the tests that cover the behaviour.
Reviewing. A reviewer checks the change against the requirements in this document rather than against the surrounding code's habits. Where the two disagree, the specification is the one that holds, and the surrounding code is a separate issue.
Requirement: As an SDK implementor, I want one document that defines the layering, configuration, client surface, error model, and security floor, so a new SDK is written against the contract and not copied from whichever SDK was nearest.
Acceptance criteria:
- AC1.1: Given this specification is merged, when an SDK's
README.mdis read, then it names the specification version that SDK implements. - AC1.2: Given a new SDK is proposed, when its design discussion is reviewed, then the proposal states the layer it occupies and the parent SDK it builds on.
- AC1.3: Given an SDK exposes a configuration key covered by Configuration, when its name is compared across SDKs, then the canonical name is used, adapted only for the language's naming convention.
- AC1.4: Given a platform cannot support a specified configuration key, when its documentation is read, then the key is listed as unsupported on that platform.
- AC1.5: Given a change adds a capability this specification does not yet cover, when the change set is reviewed, then it also updates this specification.
Requirement: As a developer moving between ThunderID SDKs, I want the same operation names to mean the same thing everywhere, so knowledge of one SDK transfers to another.
Acceptance criteria:
- AC2.1: Given an SDK implements an operation in Client surface, when its name and returned concept are compared with another SDK's, then both match, allowing for platform naming conventions.
- AC2.2: Given an SDK is configured in either mode, when an application calls
signIn(), then the call site is identical and the SDK resolves the flow internally. - AC2.3: Given an operation is called before
initialize(), when it executes, then it fails with a distinct documented error rather than an undefined-state failure. - AC2.4: Given
signOut()is called with no active session, when it executes, then it succeeds without raising. - AC2.4b: Given revocation cannot be reached, when
signOut()completes, then local state is cleared and the caller is told revocation failed. - AC2.5: Given a UI framework SDK, when an application performs a standard authentication flow, then it needs only the SDK's single primary entry point.
Requirement: As an application developer, I want one error hierarchy with stable codes and an identifiable origin, so failures can be handled and traced without platform-specific branching.
Acceptance criteria:
- AC3.1: Given any SDK operation fails, when the error is inspected, then it carries a message, a code, and the originating package.
- AC3.2: Given the failure came from an API response, when the error is inspected, then it also carries the HTTP status code and status text.
- AC3.3: Given an error is raised, when its message and any log output are inspected, then neither contains a credential, a token, or unmasked personal data.
- AC3.4: Given an SDK release, when its documentation is read, then every code that SDK can raise is listed.
Requirement: As a maintainer, I want the security behaviour of every SDK to be specified and identical, so a platform cannot quietly ship a weaker default.
Acceptance criteria:
- AC4.1: Given an SDK in redirect mode, when it builds an authorization request, then it includes a PKCE challenge derived with S256 from a verifier of 43 to 128 unreserved characters, and a random state, regardless of server or application configuration.
- AC4.1b: Given
signInOptionssuppliesstate,code_challenge,code_challenge_method,client_id, orredirect_uri, when the authorization request is built, then the SDK's own value is used and the caller's is ignored. - AC4.2: Given a callback arrives with a state that does not match the request, when the SDK processes it, then authentication fails and no token is stored.
- AC4.3: Given an SDK stores tokens with no caller-supplied adapter, when the storage
location is inspected, then it is the platform's secure store, and never browser
localStorageorsessionStorage. - AC4.4: Given an ID token is received, when the SDK accepts it, then signature, issuer, audience, expiry, and any nonce have been validated.
- AC4.5: Given sign-out is called with an active session, when it completes, then the refresh token was revoked server-side before local state was cleared.
- AC4.6: Given a
baseUrlthat is not HTTPS and not a loopback address, when initialization runs, then it fails before any network call. - AC4.6b: Given
modeisembeddedandbaseUrlis not HTTPS, when initialization runs, then it fails, loopback included. - AC4.8: Given discovery metadata whose
issuerdoes not match the expected issuer exactly, when the SDK processes it, then it fails and uses no endpoint from that document. - AC4.9: Given an
allowedExternalUrlsentry ofhttps://example.com, when a request is made tohttps://example.com.attacker.test, then no access token is attached and the request is rejected. - AC4.10: Given a request to an allowed origin is redirected to an origin that is not allowed, when the SDK follows the redirect, then the authorization header is not carried to the new origin.
- AC4.11: Given a
tokenValidationsetting that would disable a mandatory check against a non-loopbackbaseUrl, when initialization runs, then it is rejected. - AC4.12: Given two clients configured with different
instanceIdvalues, when one signs in, then the other's stored tokens and session state are unchanged. - AC4.13: Given an embedded flow returns a
REDIRECTIONstep, when its callback lacks acodeor astate, then nothing is submitted to the flow and it reports an error. - AC4.14: Given a mobile SDK and a
REDIRECTIONstep, when a callback arrives whosestatediffers from thestateinredirectURL, or theredirectURLhas nostateor an empty one, then it fails withinvalidGrantand nothing is submitted. - AC4.15: Given a submitted callback whose response is another
REDIRECTION, in sign-in or sign-up, when the SDK handles it, then it opens the newredirectURLrather than rendering an empty step. - AC4.7: Given concurrent calls arrive while a token refresh is in flight, when they are served, then only one refresh request was issued.
Requirement: As a maintainer reviewing a change in one SDK repository, I want the parity question answered on the pull request in front of me, so a capability does not ship in one SDK and go missing in the others unnoticed.
Acceptance criteria:
- AC5.1: Given a pull request in an SDK repository, when no parity decision has been recorded on it, then the check fails and the pull request cannot merge.
- AC5.2: Given the parity decision is then recorded, when the check runs again, then it passes, without requiring a push.
- AC5.3: Given a pull request whose decision is that the change reaches other SDKs, when any sibling repository has no disposition on it, being a linked pull request, a linked tracked issue where the port is deferred, or a stated reason the capability does not apply there, then the check fails and identifies the repositories still unaccounted for. A partial answer is how a gap gets missed, so it fails as no answer does.
- AC5.4: Given a change that does not reach the public surface, when the parity decision is recorded as not applicable, then the check passes on that basis alone.
- AC5.5: Given a set of merged pull requests, when they are queried for their parity decision, then one that merged without a decision recorded is identifiable.
- AC5.6: Given a capability is deferred rather than ported, when the pull request is read, then it links a tracked issue in each repository that lacks the capability.
Requirement: As a developer adopting an SDK, I want a quickstart, a reference, and a sample I can run, so I can reach a working sign-in without reading the SDK's source.
Acceptance criteria:
- AC6.1: Given an SDK release, when the documentation site is checked, then a quickstart for that SDK exists with runnable code.
- AC6.2: Given an SDK release, when the reference is checked, then every public operation, configuration key, and type is covered.
- AC6.3: Given an SDK at Core Lib or Framework Specific layer, when its repository is checked, then it contains at least one runnable sample.
- AC6.4: Given a sample and a local server, when only the documented environment variables are set, then the sample runs and completes the flow in Documentation and samples with no code change.
- AC6.5: Given a sample, when its source is inspected, then it contains no hardcoded credential or server URL and uses only the SDK's public surface.
Requirement: As a maintainer, I want every SDK covered by unit, component, and end-to-end tests, so that a regression in authentication behaviour is caught before a release rather than by an adopter.
Acceptance criteria:
- AC7.1: Given a public operation, when its SDK's test suite is inspected, then the success path and each error it can raise are covered.
- AC7.2: Given a mandatory security behaviour in Security requirements, when that behaviour is removed from the implementation, then at least one unit test fails.
- AC7.3: Given a unit test run with no network available, when the suite executes, then it passes.
- AC7.4: Given an SDK that reimplements deterministic behaviour defined by another SDK, when its tests are inspected, then they assert against fixtures from the reference implementation.
- AC7.5: Given an SDK with a quickstart sample, when its end-to-end suite runs against a real server, then sign-in, sign-out, and sign-up complete from a clean application state.
- AC7.6: Given an end-to-end suite, when its steps are inspected, then elements are selected by the identifiers in Flow element identifiers rather than by visible text or view structure.
- AC7.7: Given a pull request, when its pipeline runs, then unit and component tests for every package it touches have run.
- AC7.8: Given an end-to-end suite, when a contributor runs it on a developer machine, then the server it needs is provisioned from the repository without access to a shared environment.
Requirement: As an application developer, I want each platform's SDK packaged the way that platform expects, and the UI layer separable from the protocol layer, so I can adopt only what I need.
Acceptance criteria:
- AC8.1: Given an SDK, when its package metadata is read, then it declares a minimum supported platform version.
- AC8.2: Given an application that supplies its own UI, when it depends on an Apple or Android SDK, then it can depend on the Platform product without pulling in the Core Lib product.
- AC8.3: Given a bridged SDK, when its native dependencies are inspected, then each is pinned to a specific version rather than a range that floats to the latest release.
- AC8.4: Given a native SDK release, when the bridged SDK's repository is checked, then a mechanism exists that raises the pinned version.
- AC8.5: Given a capability exposed by a bridged SDK, when its name is compared with the native SDK's, then both use the canonical name from Client surface.
- AC8.6: Given a bridged SDK, when its Dart or JavaScript source is inspected, then it contains no OAuth 2.0 or OIDC protocol implementation.
Requirement: As a developer whose application shares a ThunderID session with other applications, I want the SDK to end my application's session when the server reports that the session ended, so a user who signs out elsewhere is not left signed in to my application.
Acceptance criteria:
- AC9.1: Given a valid logout token whose
sidis bound to a live session, when the handler processes it, then that session ends and the next request that presents it is treated as unauthenticated. - AC9.2: Given a valid logout token with a
suband nosid, when the handler processes it, then every session of that subject that began before the token was issued, or within the clock tolerance after it, ends, and a session that began later is unaffected. - AC9.3: Given a valid logout token that names no session the application holds, when the
handler processes it, then it answers
200and nothing changes. - AC9.4: Given a logout token with a signature that does not verify, an issuer or audience
that does not match, or a lifetime outside the clock tolerance, when the handler processes it,
then it answers
400and no session ends. - AC9.5: Given an ID token, or any token without the
logout+jwttype, without the back-channel logout event, or with anonce, when the handler processes it, then it answers400and no session ends. - AC9.6: Given the handler ends a session, when its outbound calls are inspected, then it made no call to the revocation or end session endpoint and sent no redirect.
- AC9.7: Given a stream of tokens with a key identifier the SDK does not hold, when the handler processes them, then the JWKS endpoint is fetched no more often than the bound allows.
- AC9.8: Given an SDK that runs only in a browser or a mobile application, when its public
surface is inspected, then it does not expose
handleBackchannelLogout, and its documentation says why. - AC9.9: Given the handler processes any request, when its log output is inspected, then it contains no logout token.
- AC9.10: Given an SDK that holds the session in a cookie, when a logout is recorded and a later request presents a matching session, then the request is treated as unauthenticated until that session could no longer be valid.
Requirement: As a developer whose users keep their own email address and mobile number, I want the SDK to let a signed-in user verify them, so my application shows the verification the server recorded and nothing else.
Acceptance criteria:
- AC10.1: Given a signed-in user, when a verification starts, then the request carries the
access token,
flowType: SELF, the handle and the attribute, and no user identifier or application ID. - AC10.2: Given no handle, when a new verification is requested, then the SDK rejects it before any network call.
- AC10.3: Given a verify-attribute component, when it is shown, then it starts one verification and does not retry it automatically.
- AC10.4: Given a
COMPLETEstep, when the flow ends, then the SDK re-reads/users/meand shows the status fromverifiedAttributesonly; an absent field shows neither verified nor unverified. - AC10.5: Given any verification step, when the log output is inspected, then it contains no code.
- AC10.6: Given a changed email address or mobile number, when the profile saves it, then it shows the stored value and its reported status and waits for Verify before starting a flow.
| Version | Date | Change |
|---|---|---|
| 0.1 | 2026-09-10 | Initial specification. |
| 0.2 | 2026-09-15 | Cross-SDK parity enforcement stated as an outcome. How a check reads and records the decision is left to the implementation. |
| 0.3 | 2026-09-26 | Management operations for applications, users, and agents added as an optional capability. |
| 0.4 | 2026-10-06 | Back-channel logout handling added as an optional capability for SDKs with a server runtime. |
| 0.5 | 2026-10-15 | syncSession replaced by a session object. The server does not implement OpenID Connect Session Management, so there is no check-session iframe for an SDK to synchronize with. session.silentSignIn configures silent sign-in from the SSO session instead. |
| 0.6 | 2026-10-20 | Federated redirects in embedded mode: a callback without a state is never submitted, mobile SDKs compare it with the request's state, and a chained REDIRECTION is followed (AC4.13 to AC4.15). Authorization codes, and the callback URLs that carry them, are never logged. |
| 0.7 | 2026-10-26 | The backchannelLogout key applies only to an SDK that mounts the handler itself; an SDK that exposes the handler takes the store on it. A sub-only logout token also ends sessions that began within the clock tolerance after it was issued. As reviewed in #5777. |
| 0.8 | 2026-10-26 | authorizationDetails configuration key (RFC 9396), sent on the authorization, silent sign-in, CIBA, and client_credentials requests. Granted details surfaced on the token response and the access token. Consent rendering of authorization details elements for SDKs that render consent, and decisions only in server-rendered consent. |
| 0.9 | 2026-11-03 | Self user attribute verification added as an optional capability (R10). |
| 0.10 | 2026-11-10 | The built-in profile waits for Verify after a contact save instead of starting verification by itself (AC10.6). |