@volter/twin-clerk

Clerk

Version

volter-aiVolter maintainedSelected defaultv1.0.4

Local Clerk users, sessions and organizations for your real SDKs. Sign-in uses synthetic users and credentials; no real account is needed.

Your World stack

Set up these twins together

In your app’s folder, install the exact choices with the current starter tools:

For a new World, select just these vendors and publishers:

Review the generated bindings and keep each source version in agreement with your manifest and lockfile. An existing World keeps its state and configuration; follow the update guide to change it. Check each release’s Node and kernel requirements before installing.

Your choices stay in this browser. Use several twins together

Mirror UI

Local twin screens with synthetic data · @volter/twin-clerk 1.0.4

Clerk twin Users showing Grace Murray Hopper and the stored user ID. — Users

User profile

Clerk twin Sessions section showing the revoked session. — Revoked session

Set up 1.0.4 Use this selected release Source README

Setup gives the current installation instructions for @volter/twin-clerk 1.0.4. Open the published README for credentials, seeds, supported operations and limits.

Unsupported HTTP operations cannot be identified from this record. Check operation support in Evidence.

README shipped with @volter/twin-clerk 1.0.4

These instructions were published with this package. Their tool versions may differ from the current starter cohort. Use Setup to install this version.

A local Clerk instance: the Backend API an application's server calls (@clerk/backend, unmodified, at https://api.clerk.com/v1) and the Frontend API the unmodified @clerk/clerk-js bundle calls from the browser (the instance's own host, twin.clerk.accounts.dev), over one state. A user made through the Backend API signs in through clerk-js; a session clerk-js starts is one the Backend API lists and mints tokens for.

The Frontend API also answers at frontend-api.clerk.dev, the destination of Clerk’s documented same-site proxy and vgauth’s Worker. That host routes directly to the Frontend API lane, with the same instance state and browser credentials.

Use with an existing app

Use Node 22.6 or newer.

Install the exact twin release and World CLI in your app's folder:

npm install --save-dev --save-exact @volter/world@3.0.165 @volter/twin-clerk@1.0.4
./node_modules/.bin/volter world init --name my-app --twins clerk --source clerk=@volter/twin-clerk

Review the selected vendor and generated bindings before starting. The World supplies synthetic credentials; keep your app's real SDK. Read this release's modeled scope below.

./node_modules/.bin/volter world up
./node_modules/.bin/volter world run -- npm test
./node_modules/.bin/volter world log
./node_modules/.bin/volter world down

Replace npm test with your app's usual command. down retains data, and a later up resumes it. Use these installed executables from the same app folder; install there first if they are missing. Bring an existing app explains multi-vendor selection and routing.

A Protocol 3 derived pack (publisher guide, "Protocol 3" and "Creating a pack"): the surface is generated from Clerk's published OpenAPI documents (spec/, fapi/spec/), plain reads, writes and deletes are the derived core's, the state machines are src/semantics/states.ts, and handlers by operationId (src/semantics/<family>.ts) serve only what an operation does beyond them. Every other operation answers Clerk's own 404. The immutable catalog assessment records the declared surface, measured journeys and remaining gaps.

world-clerk serve [--port N] [--root DIR] [--read-only]

A World makes its people through the Backend API's own POST /users. Nothing is signed in.

What it models

Backend API: users (made, updated, their metadata merged or replaced, listed and counted with Clerk's filters, deleted), sessions (made for a test, listed, revoked, their tokens), sign-in tokens (made, revoked, used once by the Frontend API), an instance's organization settings (Organizations are off until turned on, as on a new Clerk instance), custom permissions and roles beside the system ones, organizations with their memberships and invitations, JWT templates, SAML enterprise configuration and the instance's public keys.
Frontend API (what clerk-js needs to boot and what the applications measured drive through it): the environment, the dev browser, the client and its __client cookie, sign-up by email and password (the address verified by an emailed code) and by an invitation's ticket, sign-in by password, by an emailed code and by ticket, sessions (touched, read and their tokens), an invitation's link, and /.well-known/jwks.json. Clerk's published clerk-js bundle (5.127.2, vendor/clerk-js/, with its SOURCE.md) is served as published at the /npm/@clerk/clerk-js loader path.
Webhooks: user.deleted, Svix-signed, to the instance's webhook endpoints. The payload includes timestamp, instance_id, request event_attributes and the deleted user's external_id. Each delivery is recorded; the Dashboard endpoint is set through POST /_twin/webhook-endpoints.

The OAuth identity-provider flow serves the account worker used by Volter Editor: authorization redirects to sign-in and explicit consent, then a registered callback receives a single-use code bound to S256 PKCE. The worker exchanges it at /oauth/token; refresh grants retain the user and selected organization. Access tokens use the at+jwt header type Clerk's SDK expects; OpenID Connect ID tokens use JWT. Register the public OAuth application with POST /v1/oauth_applications before using it. Codes expire after ten minutes, access and ID tokens after one day, and refresh tokens after ten years in the pinned Frontend API spec.

The Frontend API accepts the documented clerk.<application domain> host family and frontend-api.clerk.dev; proxy calls require a held instance secret key in Clerk-Secret-Key, the full Clerk-Proxy-Url, and X-Forwarded-For.

Organization settings are stored as the Backend API's OrganizationSettings singleton and read back through GET /v1/instance/organization_settings; the Frontend environment renders its domain fields in the Frontend shape. Dashboard-only sign-in configuration remains private bookkeeping. Memberships retain the Backend API's public_user_data.user_id reference, including after refresh. The known-resource scopes read JWT templates, enterprise connections and their SAML children without promising enumeration for those types.

Dashboard workspace

The World operator view opens the Users page at /users (the workspace listed by GET /twin, on dashboard.clerk.com inside the World). It displays the same users and sessions the Backend SDK created: search users, open a user profile, inspect identifiers and public/private/unsafe metadata, read organization memberships, and see session status and timestamps. Saving first and last names uses UpdateUser; revoking an active session uses RevokeSession. These forms return to a fresh stored-row view, and read-only Worlds refuse their writes.

This is an operator workspace authorized by the World. It introduces no Clerk Dashboard account sign-in, team-role permissions, instance switching or frontend application sign-in compatibility. Metadata is read-only in the workspace; device/location, billing, analytics and impersonation controls are outside this screen's scope. The pack's official visual references and limits are in spec/screen-references.json.

Keys

The Backend API takes only the keys the instance holds: the application's, which the World issues when it boots (POST /_twin/app-credentials, the descriptor's credential door, with the publishable key, the CLERK_JWT_KEY a backend verifies session tokens with and the webhook signing secret), and every key the API Keys page's door made. No Authorization header is Clerk's 401 authorization_header_format_invalid, and any other key, whatever its shape, is its 401 clerk_key_invalid. A request with no secret key is never the Backend API's: on a Frontend API path it is the browser's, answered by the Frontend API.

Each World signs with its own key. Session tokens, the tokens of JWT templates without a key of their own, and invitation tickets are signed with an RSA key the World makes once at random (ctx.signingKey), served as the instance's JWKS, so a token verifies only against the World that issued it and no one can mint one from this package. A template with its own signing key signs with that key, in its algorithm (RSA or HMAC, SHA-256 to 512; others are refused).

Doors

The World's hands on the instance, standing in for the Clerk Dashboard (src/semantics/doors.ts); the POST doors are refused on a read-only twin:

POST /_twin/secret-keys {name}: a secret key, as the API Keys page shows it once (sk_test_… on a development instance); the twin keeps its hash.
POST /_twin/webhook-endpoints {url, events, signing_secret?}: a webhook endpoint and its whsec_… signing secret (the one given, when the World's application already holds one).
POST /_twin/instance {…}: the instance's sign-up settings (password on or off, legal consent, organization membership optional or required, the Frontend API host, the Native API on or off).
POST /_twin/native-applications {platform, …}: an iOS app (app_id_prefix, bundle_id) or Android app (package_name) registered on the Native applications page. A native client's request (_is_native=true, its client token in Authorization) is Clerk's 400 native_api_disabled until the Native API is on.
GET /_twin/emails?to=<address>: what Clerk sent an address (verification codes, invitations), oldest first.
GET /_twin/webhook-messages?type=<event>: what was delivered to the webhook endpoints, oldest first.

Not modelled

OAuth device authorization, token exchange, dynamic registration, userinfo and revocation; SSO sign-in (an enterprise connection is configured, never signed in through) and passkeys; multi-factor authentication; phone numbers; application-invitation acceptance and revocation, allowlist and blocklist, actor tokens, redirect URLs, domains, OAuth application updates and deletion, and the webhook endpoints API; uploaded logos and profile images; standalone SAML mutations and enumeration (known connections are readable), permission/role deletion, UserProfile and client session removal, and every Frontend API route clerk-js's organization components drive. Each answers the gap, never a fabricated success.

The first-party account broker’s production share invitation calls Backend API CreateInvitation; the companion stores that application invitation, sends its ticket to the modeled recipient inbox, and exposes ListInvitations for read-back. These operations honor notification, metadata, expiration and duplicate handling. Application-invitation acceptance, revocation and bulk creation remain separate gaps.

Set up this release

Use a Node version matching >=22.3. Install this exact starter cohort in your app folder:

npm install --save-dev --save-exact @volter/world@3.0.165 @volter/world-core@3.0.155 @volter/world-runtime@3.0.163 @volter/world-console@3.0.151 @volter/world-ui@1.0.155 @volter/twin-clerk@1.0.4

In your app’s folder, initialize a World with this implementation:

./node_modules/.bin/volter world init --name my-app --twins clerk --source clerk=@volter/twin-clerk

Review the detected vendor and retain the generated bindings. The clerk service’s source must select this version:

{
  "source": {
    "package": "@volter/twin-clerk",
    "version": "1.0.4"
  }
}

This is the source field, not a complete config. Keep the installed version, lockfile and generated service source in agreement. Use the release README for throwaway SDK credentials, seeds and limits.

The assessment records its own earlier tool versions under Measurements. This setup uses the current starter cohort.

Run your app’s own test command inside the World:

./node_modules/.bin/volter world up
./node_modules/.bin/volter world run -- npm test
./node_modules/.bin/volter world log
./node_modules/.bin/volter world down

down stops compute and retains state.

Bring an existing app Recover a failed call Trial an update

Versions and implementations

Package / version	Publisher	Status	First use
@volter/twin-clerk1.0.4	volter-ai	Selected default	Passed
@volter/twin-clerk1.0.3	volter-ai	live	Passed
@volter/twin-clerk1.0.2	volter-ai	live	Not measured

Evidence for 1.0.4

Unsupported HTTP operations cannot be identified from this record. Consult the release README for limits.

Installed first use · Passed

Installed first use: Passed
Fresh app installation: Verified
Workflow scope: Exact installed artifact; normal CLI initialization, unchanged SDK, result assertions and retained-state read-only resume where applicable
Customer SDK versions: @clerk/backend@2.33.3
CLI, kernel and runtime versions: @volter/world@3.0.165 · @volter/world-core@3.0.155 · @volter/world-runtime@3.0.163
World clock: {"mode":"wall"}
Retained-state readback: Verified
Stopped compute: Verified
Customer journey failures: 0

API coverage, replay and browser measurements

Counts describe the declared HTTP surface, not separate command tables or other protocols. Consult the release README for those workflows.

Assessment scope: packaged-customer-journey; in-process
Declared HTTP surface: 82 served · 381 gaps · 463 declared operations
Exercised HTTP operation coverage: 68 / 463 declared operations (14.7%)
Journey steps: 198 answered / 221 steps
Replay: Equal across 2 runs
Journey failures: 0
Browser target: HTTP customer journey replay through Chromium at each request origin; authored HTTP headers and observed wire responses 153.0.8010.12
HTTP operations exercised through Chromium: 68 / 463 declared operations (14.7%)
Chromium journey replay: Equal across 2 runs
Browser response observation: Transport observes status, headers and body, including redirects and Set-Cookie; these are not JavaScript-visible response claims
Application-origin CORS coverage: Not measured
Native cookie-jar coverage: Not measured
DOM coverage: Not measured
Source code coverage: Not measured
State transition coverage: Not measured

Operations not exercised · measurement only

An operation not exercised by this journey may be served or unsupported. Check the separate declared unsupported operations above.

Conformance results

decided: 0 failures · every served operation is decided with its demand; every demanded and every refreshed operation is served
published: 0 failures · what a release publishes holds every unit: its manifest, its spec and its journeys
cited: 0 failures · every vendor fact cited is recorded as a page that answered, each quote found on it
refresh: 0 failures · every stored resource of a vendor-backed unit declares how it is read back, and a unit that sends events ingests the vendor's
registered: 0 failures · a vendor-backed unit, lane or not, reaches the registered pack's state system
allowance: 0 failures · a rate budget above the fallback rests on the vendor's documented allowance, cited in its manifest
client: 0 failures · driven by the vendor's own client (its official SDK), served as a World runs it, the vendor's documented behaviour holds · 4 case(s) through the vendor's client
life: 0 failures · the life walked over HTTP against the pack served as a World runs it, with its scenario: every check held
standalone: 0 failures · served by its server.ts as a World runs it, the pack answers HTTP and the boot probe, and each declared socket upgrades

Publisher, admission and provenance

Publisher: volter-ai/twin-packs-open
Source commit: b828301d8954cedd90491525860fa03090897081
Catalog record commit: b3760985a33c6575289a1c857845f74cea8898a5
Package integrity: sha512-+FvpxOyeVbJCIr2j5U4OnPNOEqKpBgSfzgWKwvHktDt9Dl9B/fNJzLAi4CaOJEBIZ27NpuryzdpFwTD23YAAUA==
Admission mode: Trusted internal publisher · maintainer merge
Catalog assessment: Bundled report checksum verified
Assessed at: Not recorded
Assessment input head: 9e51be37d9254f1ab35cf35bc113267fd6d258d5
Evidence: Assessment and admission

Read the catalog snapshot

Install this version

npm install --save-dev --save-exact @volter/world@3.0.165 @volter/world-core@3.0.155 @volter/world-runtime@3.0.163 @volter/world-console@3.0.151 @volter/world-ui@1.0.155 @volter/twin-clerk@1.0.4

In your app’s folder. Setup instructions

License: Apache-2.0
Node for this setup: >=22.3
World kernel: ^3.0.155