@volter/twin-xidentity 0.1.0

package/src/xidentity-server.ts

@@ -0,0 +1,97 @@
+// X identity twin HTTP server — one server for the WHOLE vendor surface, because sign-in-with-X is
+// one product spread over two host families. Point `x.com`, `twitter.com`, `api.x.com` and
+// `api.twitter.com` here (the injector's `xidentity` VENDOR_HOSTS entry does exactly that) and an
+// unmodified X client completes a full authorization-code round trip against it.
+//
+// Two things this server does that a JSON-only twin server does not:
+//   • it can answer with HTML and with 302 redirects — the authorize screen and the callback
+//     bounce are the protocol, not decoration, so the handler's `headers` (content-type, location)
+//     pass straight through rather than being flattened into a JSON envelope;
+//   • it serves the authorize page's own assets under the twin-namespaced `/_twin/assets/*`.
+//
+// It also tells the handler its OWN origin, so the consent form's action points BACK AT THE TWIN.
+import { serveHttp } from '@volter/world-core';
+import { CONSENT_CLIENT_CSS, CONSENT_CLIENT_JS, CONSENT_SCRIPT_PATH, CONSENT_STYLE_PATH } from './xidentity-consent-ui.ts';
+import { worldNow, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
+import { handleXIdentityTwinRequest } from './xidentity-twin.ts';
+
+/** Options every X-identity-twin HTTP surface needs, independent of who owns the socket. */
+export interface XIdentityTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12b): a Worker / Durable Object entry has NO
+ * loopback ports, so it must mount a pack's handler IN-PROCESS. `createXIdentityTwinServer` is
+ * nothing but `Bun.serve` wrapped around this closure, so the standalone (R1) and hosted
+ * surfaces are the SAME code — there is no second HTTP adaptation to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): GET /twin is built from constants, and the only clock on
+ * the path is `worldNow()`, the world's frozen instant. The authorize screen's own script and
+ * stylesheet routes serve COMMITTED text (`xidentity-consent-client.gen.ts`, built on the dev
+ * plane by `scripts/consent-clients.ts`) — no build and no disk read on the fetch path.
+ */
+export function createXIdentityTwinFetch(options: XIdentityTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  return async function xIdentityTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({ vendor: 'xidentity', twinOf: 'X (Twitter) identity / OAuth 2.0 + PKCE', stores: 'authorization codes, access/refresh tokens and the authorize-screen round trip' }));
+    }
+
+    if (request.method === 'GET' && url.pathname === CONSENT_SCRIPT_PATH) {
+      return new Response(CONSENT_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+    }
+    if (request.method === 'GET' && url.pathname === CONSENT_STYLE_PATH) {
+      return new Response(CONSENT_CLIENT_CSS, { headers: { 'content-type': 'text/css; charset=utf-8' } });
+    }
+
+    const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+
+    const res = await handleXIdentityTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: worldNow(),
+      origin: twinPublicBase(request),
+      callbackOrigin: url.origin,
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+
+    const out = { ...(res.headers ?? {}) };
+    // A string body is already rendered (HTML, or the empty body of a 302); anything else is the
+    // vendor's JSON.
+    if (typeof res.body === 'string') {
+      if (!out['content-type'] && res.body) out['content-type'] = 'text/html; charset=utf-8';
+      return new Response(res.body, { status: res.status, headers: out });
+    }
+    out['content-type'] = out['content-type'] ?? 'application/json; charset=utf-8';
+    return new Response(JSON.stringify(res.body), { status: res.status, headers: out });
+  };
+}
+
+export async function createXIdentityTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createXIdentityTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/**
+ * The authorize screen is served BY THE TWIN, at the vendor's own path — there is no second
+ * "mirror" server to start. This alias exists so the `world-xidentity mirror` command and the
+ * journey harness have the conventional entry point, and it returns the very same server.
+ */
+export const createXIdentityConsentServer = createXIdentityTwinServer;

package/src/xidentity-store.ts

@@ -0,0 +1,419 @@
+// X identity twin — STATE. Everything the twin knows lives in the shared kernel action log (D1):
+// OAuth clients, X accounts, the browser session (which account is "logged in" at x.com), pending
+// authorization requests, authorization codes, access/refresh tokens, the per-(client, user) grant
+// record and the per-user rate window. There is no parallel store.
+//
+// ID MINTING (ADDING_A_TWIN.md §5): every id is either the vendor's own natural key (an account
+// id) or MINTED HERE. The minted ones used to be ENTROPIC (`randomUUID`) — never a module counter
+// and never a row count. Every one of them is also SERVED: the `ar_` authorize handle is rendered
+// into the screen, the `…:ac:1` code rides the callback redirect, the `…:at:1`/`…:rt:1` tokens
+// ride the /2/oauth2/token reply, a minted client id rides the twin door's reply. Runtime contract
+// R9 (a served response is a pure function of (request, stored state) — no clock and no randomness
+// in served content) therefore governs all of them, and entropy is exactly the defect it names, so
+// they are ALL minted the resend way now: a stable hash of the world instant + the number of rows
+// of that type the store already holds (soft-deleted rows counted, so a value can never recur) +
+// the subject it is issued for.
+//
+// §5's count-mint hazard — a pulled vendor id sitting in a GAP above the row count, which local
+// creates then walk into and clobber — cannot arise here: these types are twin-internal or
+// twin-issued, no connector pulls one, and the count is a hash SEED rather than the id itself.
+// What §5's entropy bought (two writes at one instant never colliding) the count buys instead: it
+// advances on every mint.
+//
+// The `ar_` handle carries one extra rule the credentials do not: an authorize request whose
+// parameters already name an UNSETTLED pending row reuses that row's id, so re-serving the same
+// authorize screen is byte-identical (and a reload does not pile up a second pending request).
+//
+// The mutable-in-place rows (a code being consumed, a token being revoked, a grant re-granted, a
+// rate window advancing) carry a per-subject `rev` ordinal (the upstash precedent) so a
+// genuine write can never be mistaken for a replay.
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources, type TwinResource } from '@volter/world-core';
+
+export const SERVICE = 'xidentity';
+
+export const RESOURCE_TYPES = [
+  'oauth_client',
+  'account',
+  'session',
+  'auth_request',
+  'authorization_code',
+  'access_token',
+  'refresh_token',
+  'grant',
+  'rate_window',
+] as const;
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+
+export type Row = TwinResource & Record<string, any>;
+
+export function readAll(root: string | undefined): Row[] {
+  return projectResources(SERVICE, root) as Row[];
+}
+export function readType(root: string | undefined, type: ResourceType): Row[] {
+  return readAll(root).filter((r) => r.type === type);
+}
+export function readOne(root: string | undefined, type: ResourceType, id: string): Row | undefined {
+  return readAll(root).find((r) => r.type === type && r.id === id);
+}
+
+/** The next `rev` for a subject that is being rewritten in place (survives deletes/tombstones). */
+export function nextRev(root: string | undefined, type: ResourceType, id: string): number {
+  const existing = readOne(root, type, id);
+  return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+
+/** The next revision from a snapshot already held under the kernel projection lock. */
+export function nextRevIn(resources: readonly TwinResource[], type: ResourceType, id: string): number {
+  const existing = resources.find((r) => r.type === type && r.id === id) as Row | undefined;
+  return (typeof existing?.rev === 'number' ? existing.rev : 0) + 1;
+}
+
+/** A state-dependent one-row update whose read/revision/write decision is one kernel transaction. */
+export async function writeAtomic(
+  type: ResourceType,
+  id: string,
+  operation: string,
+  fields: (resources: readonly TwinResource[]) => Record<string, unknown>,
+  opts: WriteOpts,
+): Promise<Row> {
+  await applyTwinWriteAtomic(
+    SERVICE,
+    (resources) => ({
+      kind: 'write',
+      value: undefined,
+      write: {
+        operation,
+        subjectType: type,
+        subjectId: id,
+        fields: { ...fields(resources), rev: nextRevIn(resources, type, id) },
+        ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+        actor: { kind: 'agent' },
+      },
+    }),
+    opts.root,
+  );
+  return readOne(opts.root, type, id)!;
+}
+
+export type WriteOpts = { root?: string; occurredAt?: string };
+/** Seeding also needs the origin the twin was reached on, so the demo clients' registered
+ *  callbacks point back at THIS twin rather than at a baked-in port (runtime contract R7). */
+export type SeedOpts = WriteOpts & { origin?: string };
+
+export async function write(
+  type: ResourceType,
+  id: string,
+  operation: string,
+  fields: Record<string, unknown>,
+  opts: WriteOpts,
+): Promise<Row> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    {
+      operation,
+      subjectType: type,
+      subjectId: id,
+      fields,
+      ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+      actor: { kind: 'agent' },
+    },
+    opts.root,
+  );
+  return resource as Row;
+}
+
+// ── vendor-shaped id minting ────────────────────────────────────────────────────────────────────
+// X's OAuth 2.0 artefacts are base64url blobs with an internal structure the vendor's own docs
+// examples expose when decoded (docs.x.com user-access-token guide, fetched 2026-08-21):
+//
+//   client_id     M1M5R3BMVy13QmpScXkzTUt5OE46MTpjaQ                → "<21 alnum>:1:ci"
+//   auth code     VGNibzFWSWRE…RchOXlMd2dxOjE2MjIxNjA4MjU4MjU6MToxOmFjOjE
+//                                                                   → "<opaque>:<unix ms>:1:1:ac:1"
+//   access token  Q0Mzb0VhZ0V5…U3NZQnZQYjoxNjIyMTQ3NzQzOTE0OjE6MTphdDox
+//                                                                   → "<opaque>:<unix ms>:1:1:at:1"
+//   refresh token bWRWa3gzdnk3…QVdxbm06MTYyMjE0Nzc0MzkxNDoxOjE6cnQ6MQ
+//                                                                   → "<opaque>:<unix ms>:1:1:rt:1"
+//
+// The twin reproduces the SHAPE (an integrator's code may key on it); the bytes are not the
+// vendor's.
+//
+// Those bytes used to be `randomUUID()` entropy, and every one of them is SERVED (the code rides
+// the callback redirect, the tokens ride the /2/oauth2/token reply), so R9 governs them exactly as
+// it governs the `ar_` handle below. They are the resend pattern now: `stableHex` over (type, the
+// world instant, the rows of that type held BEFORE the insert, the subject being issued for),
+// occupying the same 21/45 characters of the same hex alphabet the entropic version did — the
+// shape is byte-for-byte what it was.
+//
+// A twin's credentials are stand-ins, not secrets: determinism is the contract, and predictability
+// from public state is not a threat model a twin has. UNIQUENESS is, and the seed carries it: the
+// row COUNT advances on every mint, so two credentials of one type at one instant differ even when
+// the subject is identical, and the SUBJECT is the credential being exchanged — the consent screen
+// for a code, the code or spent refresh token for a token — so concurrent exchanges never meet.
+// `xidentity.refresh.rotation` (a rotation must hand back a refresh token the caller did not send)
+// holds by construction: the spent row is already in the store when the replacement is seeded.
+
+const b64url = (s: string) => Buffer.from(s, 'utf8').toString('base64url');
+/** The seed every credential is minted from. `readType` is unfiltered (soft-deletes counted), so a
+ *  count — and therefore a credential — can never recur for one (type, instant, subject). */
+function credentialSeed(root: string | undefined, type: ResourceType, instant: string | number, subject: string): string {
+  return `${type}:${instant}:${readType(root, type).length}:${subject}`;
+}
+
+/** An X OAuth 2.0 client id: base64url of `<opaque>:1:ci`. */
+export const mintClientId = (root: string | undefined, instant: string): string =>
+  b64url(`${stableHex(credentialSeed(root, 'oauth_client', instant, 'client'), 21)}:1:ci`);
+/** An X OAuth 2.0 authorization code (`…:ac:1`). `subject` is the authorize screen it settles. */
+export const mintAuthorizationCode = (root: string | undefined, at: number, subject: string): string =>
+  b64url(`${stableHex(credentialSeed(root, 'authorization_code', at, subject), 45)}:${at}:1:1:ac:1`);
+/** An X OAuth 2.0 user access token (`…:at:1`). `subject` is the credential exchanged for it. */
+export const mintAccessToken = (root: string | undefined, at: number, subject: string): string =>
+  b64url(`${stableHex(credentialSeed(root, 'access_token', at, subject), 45)}:${at}:1:1:at:1`);
+/** An X OAuth 2.0 refresh token (`…:rt:1`). `subject` is the credential exchanged for it. */
+export const mintRefreshToken = (root: string | undefined, at: number, subject: string): string =>
+  b64url(`${stableHex(credentialSeed(root, 'refresh_token', at, subject), 45)}:${at}:1:1:rt:1`);
+// ── the authorize screen's handle: DETERMINISTIC, because it is SERVED (R9) ─────────────────────
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+function stableHex(seed: string, n: number): string {
+  let out = '';
+  for (let round = 0; out.length < n; round += 1) {
+    let h = 0x811c9dc5;
+    const s = `${round}:${seed}`;
+    for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+    out += h.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, n);
+}
+
+/** Every authorize parameter an `auth_request` row holds — its stable identity. Read off the
+ *  fields being written OR off a projected row (the key set is the same on both). */
+const AUTH_REQUEST_SIG_KEYS = [
+  'clientId', 'redirectUri', 'scope', 'state', 'codeChallenge', 'codeChallengeMethod', 'accountId',
+] as const;
+function authRequestSignature(fields: Record<string, unknown>): string {
+  return AUTH_REQUEST_SIG_KEYS.map((k) => `${k}=${String(fields[k] ?? '')}`).join('\u0001');
+}
+
+/**
+ * Twin-internal handle for an authorize screen in flight (never leaves the twin's own pages) —
+ * `ar_` + 32 hex, the shape `randomUUID()` gave it, now a pure function of (request, stored state).
+ *
+ * An authorize request whose parameters ALREADY name an unsettled pending row reuses that row's
+ * id: pressing reload on the authorize screen is the same screen, not a new one. Otherwise the id
+ * is `stableHex(auth_request:<world instant>:<rows already held>)` — two authorize requests at one
+ * instant differ by the count, and two identical worlds mint identical ids.
+ */
+export function authRequestIdFor(root: string | undefined, occurredAt: string, fields: Record<string, unknown>): string {
+  const prior = readType(root, 'auth_request');
+  const signature = authRequestSignature(fields);
+  const reusable = prior.find((r) => r.settled !== true && authRequestSignature(r) === signature);
+  if (reusable) return String(reusable.id);
+  return `ar_${stableHex(`auth_request:${occurredAt}:${prior.length}`, 32)}`;
+}
+
+// ── seeded world ────────────────────────────────────────────────────────────────────────────────
+// The authorize page needs SOMEBODY to be signed in at x.com. X shows the consent screen for the
+// browser's current session; the twin's equivalent is deterministic personas seeded on first use
+// plus a `session` row naming the active one (`POST /_twin/session` switches it — X's real switcher
+// is the x.com account menu, which is not OAuth surface). The default clients mirror the two shapes
+// the X developer portal hands out: a CONFIDENTIAL client (Web App — has a secret, authenticates
+// with HTTP Basic) and a PUBLIC client (Native/SPA — no secret, client_id travels in the body).
+
+export const DEFAULT_CLIENT_ID = 'VHdpbkRlbW9BcHAwMDAwMDAwMDA6MTpjaQ';
+export const DEFAULT_CLIENT_SECRET = 'twin-confidential-secret-0000000000000000000000000';
+export const DEFAULT_PUBLIC_CLIENT_ID = 'VHdpblB1YmxpY0FwcDAwMDAwMDA6MTpjaQ';
+
+export type SeedAccount = {
+  id: string;
+  username: string;
+  name: string;
+  createdAt: string;
+  description: string;
+  location?: string;
+  profileImageUrl?: string;
+  protectedAccount: boolean;
+  verified: boolean;
+  verifiedType: 'none' | 'blue' | 'business' | 'government';
+  publicMetrics: {
+    followers_count: number;
+    following_count: number;
+    tweet_count: number;
+    listed_count: number;
+    like_count: number;
+    media_count: number;
+  };
+  url?: string;
+  confirmedEmail?: string;
+};
+
+/** X user ids are stable numeric strings (the docs' own example user is "2244994945"). The seeded
+ *  ids start at 9e18 — vendor-SHAPED (int64-range numeric) but far ABOVE the live snowflake id
+ *  space (~1.9e18 in 2026), so a locally seeded persona can never collide with a pulled real id
+ *  (the datadog EVENT_ID_BASE precedent; §9 round one). */
+export const DEFAULT_ACCOUNTS: SeedAccount[] = [
+  {
+    id: '9000000000000000001',
+    username: 'ada_twin',
+    name: 'Ada Lovelace',
+    createdAt: '2013-12-14T04:35:55.000Z',
+    description: 'Analyst. Engine programmer. First of her kind.',
+    location: 'London',
+    protectedAccount: false,
+    verified: true,
+    verifiedType: 'blue',
+    publicMetrics: { followers_count: 5834, following_count: 204, tweet_count: 1405, listed_count: 16, like_count: 320, media_count: 12 },
+    url: 'https://ada.example',
+    confirmedEmail: 'ada@twin.example',
+  },
+  {
+    id: '9000000000000000002',
+    username: 'grace_twin',
+    name: 'Grace Hopper',
+    createdAt: '2015-06-01T12:00:00.000Z',
+    description: 'It is easier to ask forgiveness than permission.',
+    protectedAccount: true,
+    verified: false,
+    verifiedType: 'none',
+    publicMetrics: { followers_count: 120, following_count: 88, tweet_count: 5210, listed_count: 3, like_count: 990, media_count: 41 },
+  },
+];
+
+/** NextAuth's callback path for the X provider — the one every X integration guide walks through. */
+const CALLBACK_PATH = '/api/auth/callback/x';
+
+/**
+ * Every spelling of the ORIGIN this twin was reached on that a browser could hand back.
+ *
+ * X matches redirect URIs EXACTLY and documents NO loopback-port exception (see
+ * `redirectUriAllowed` below), so `localhost` and the loopback IP are two different
+ * registrations — while a local app is reachable as both on the same port. A demo registration
+ * naming only one of them would fail half the time for a reason the developer cannot see.
+ */
+function originSpellings(origin?: string): string[] {
+  const base = (origin ?? '').trim().replace(/\/+$/, '');
+  if (!base) return [];
+  let u: URL;
+  try { u = new URL(base); } catch { return [base]; }
+  if (u.protocol !== 'http:') return [base];
+  const port = u.port ? `:${u.port}` : '';
+  if (u.hostname === 'localhost') return [base, `http://127.0.0.1${port}`];
+  if (u.hostname === '127.0.0.1') return [base, `http://localhost${port}`];
+  return [base];
+}
+
+/**
+ * The redirect URIs the seeded demo clients register.
+ *
+ * Runtime contract R7: a twin NEVER bakes a port into served content or config. The callbacks are
+ * DERIVED from the origin the twin was actually reached on (`XIdentityRequest.origin`, which
+ * xidentity-server fills from the URL the request arrived at). A caller that declares no origin —
+ * an in-process call — seeds no callbacks at all and registers its own through the twin door.
+ */
+export function defaultRedirectUris(origin?: string): string[] {
+  return originSpellings(origin).map((base) => `${base}${CALLBACK_PATH}`);
+}
+
+/**
+ * Materialise the default clients + accounts + session once per root. Idempotent by subject id:
+ * re-running it over a seeded root writes nothing new, and it NEVER overwrites an
+ * operator-registered client, account or session choice.
+ */
+export async function ensureSeed(opts: SeedOpts): Promise<void> {
+  await applyTwinWriteAtomic(
+    SERVICE,
+    (resources) => {
+      const has = (type: ResourceType, id: string) => resources.some((r) => r.type === type && r.id === id);
+      const missing: Array<{ type: ResourceType; id: string; fields: Record<string, unknown> }> = [];
+      if (!has('oauth_client', DEFAULT_CLIENT_ID)) missing.push({
+        type: 'oauth_client',
+        id: DEFAULT_CLIENT_ID,
+        fields: {
+          name: 'Twin Demo App',
+          secret: DEFAULT_CLIENT_SECRET,
+          clientType: 'confidential',
+          redirectUris: defaultRedirectUris(opts.origin),
+          rev: 1,
+        },
+      });
+      if (!has('oauth_client', DEFAULT_PUBLIC_CLIENT_ID)) missing.push({
+        type: 'oauth_client',
+        id: DEFAULT_PUBLIC_CLIENT_ID,
+        fields: {
+          name: 'Twin Public App',
+          secret: null,
+          clientType: 'public',
+          redirectUris: defaultRedirectUris(opts.origin),
+          rev: 1,
+        },
+      });
+      for (const account of DEFAULT_ACCOUNTS) {
+        if (has('account', account.id)) continue;
+        missing.push({
+          type: 'account',
+          id: account.id,
+          fields: {
+            username: account.username,
+            name: account.name,
+            createdAt: account.createdAt,
+            description: account.description,
+            ...(account.location ? { location: account.location } : {}),
+            ...(account.profileImageUrl ? { profileImageUrl: account.profileImageUrl } : {}),
+            protectedAccount: account.protectedAccount,
+            verified: account.verified,
+            verifiedType: account.verifiedType,
+            publicMetrics: account.publicMetrics,
+            ...(account.url ? { url: account.url } : {}),
+            ...(account.confirmedEmail ? { confirmedEmail: account.confirmedEmail } : {}),
+            rev: 1,
+          },
+        });
+      }
+      if (!has('session', 'current')) missing.push({
+        type: 'session',
+        id: 'current',
+        fields: { accountId: DEFAULT_ACCOUNTS[0]!.id, rev: 1 },
+      });
+      if (missing.length === 0) return { kind: 'skip', value: undefined };
+      const [primary, ...rest] = missing;
+      return {
+        kind: 'write',
+        value: undefined,
+        write: {
+          operation: 'seed.ensure',
+          subjectType: primary!.type,
+          subjectId: primary!.id,
+          fields: primary!.fields,
+          projection: {
+            creates: rest.map((row) => ({ type: row.type, id: row.id, fields: row.fields })),
+          },
+          ...(opts.occurredAt ? { occurredAt: opts.occurredAt } : {}),
+          actor: { kind: 'system' },
+        },
+      };
+    },
+    opts.root,
+  );
+}
+
+/** The account the x.com browser session is signed in as (the one the authorize screen consents). */
+export function sessionAccount(root: string | undefined): Row | undefined {
+  const session = readOne(root, 'session', 'current');
+  const id = typeof session?.accountId === 'string' ? session.accountId : undefined;
+  return id ? readOne(root, 'account', id) : undefined;
+}
+
+/**
+ * Is `candidate` an EXACT registered callback URI for this client? X documents exact-match
+ * validation for OAuth 2.0 callback URLs ("This value must correspond to one of the Callback URLs
+ * defined in your App's settings" — and the legacy official SDK's own docblock spells out "exact
+ * match validation"). No loopback-port exception is documented for X, so none is modelled — a
+ * loosely-matching twin would hide the single most common integration bug.
+ */
+export function redirectUriAllowed(client: Row, candidate: string): boolean {
+  const registered: string[] = Array.isArray(client.redirectUris) ? client.redirectUris : [];
+  // A fragment never legitimately appears in a redirect_uri (RFC 6749 §3.1.2) and exact string
+  // membership would still admit one only if it had been REGISTERED with a fragment — refuse the
+  // candidate outright before comparing.
+  if (candidate.includes('#')) return false;
+  return registered.includes(candidate);
+}