@volter/twin-tiktok 0.1.0

package/src/tiktok-store.ts

@@ -0,0 +1,543 @@
+// TikTok twin — STATE. Everything the twin knows lives in the shared kernel action log (D1): the
+// developer app (`oauth_client`), the TikTok accounts it can consent as, the tiktok.com browser
+// session, pending authorize requests, authorization codes, user access/refresh tokens, the
+// app-only client token, the per-(app, user) grant that carries the granted scope set and the
+// user's `open_id`, the videos the Display API serves, and the per-endpoint rate window. There is
+// no parallel store.
+//
+// ID MINTING (ADDING_A_TWIN.md §5): every id is either the vendor's own natural key (a video id,
+// a union id) or MINTED HERE, and every minted one is SERVED — the code rides the callback
+// redirect, the `act.`/`rft.`/`clt.` tokens ride the token reply, the `ar_` handle is rendered
+// into the authorize screen. Runtime contract R9 therefore governs all of them: each is a stable
+// hash of (the world instant + the number of rows of that type the store already holds, tombstones
+// counted + the subject it is issued for), never entropy and never a bare counter.
+//
+// ONE MINT IS DELIBERATELY *NOT* SEEDED BY THE COUNT: `open_id`. TikTok's `open_id` is
+// "the TikTok user's unique identifier" PER APP, while `union_id` is the same human across every
+// app of one developer. So open_id must be STABLE for a (client_key, account) pair across every
+// authorization that pair ever performs — it is derived from those two values alone, and the
+// grant row is where it is recorded.
+//
+// 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';
+import { createHash } from 'node:crypto';
+import { stableHex } from './tiktok-ids.ts';
+
+/** A credential as the log keeps it: its SHA-256 (hex), never the credential. */
+export function secretKey(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export const SERVICE = 'tiktok';
+
+/**
+ * THE CREDENTIAL ROWS ARE BOOKKEEPING, AND THEY NEVER NAME THEIR CREDENTIAL. An authorization code,
+ * an access / refresh / client token and a rate window are the twin's own records: nothing about them
+ * crosses to TikTok, so they are `_`-prefixed (world-core `isTwinBookkeeping`) and never deployed or
+ * pushed. Each is keyed by the SHA-256 of the credential (`secretKey`), never the credential — the
+ * YouTube `_token` pattern — so no event log, resource record or changeset a World keeps holds a
+ * bearer in the clear. A presented credential is hashed and looked up.
+ */
+export const BK_CODE = '_authorization_code';
+export const BK_ACCESS = '_access_token';
+export const BK_REFRESH = '_refresh_token';
+export const BK_CLIENT = '_client_token';
+export const BK_RATE = '_rate_window';
+
+export const RESOURCE_TYPES = [
+  'oauth_client',
+  'account',
+  'session',
+  'auth_request',
+  BK_CODE,
+  BK_ACCESS,
+  BK_REFRESH,
+  BK_CLIENT,
+  'grant',
+  'video',
+  'publish',
+  BK_RATE,
+] 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;
+}
+
+export type WriteOpts = { root?: string; occurredAt?: string };
+/** Seeding also needs the origin the twin was reached on, so the demo app's registered callback
+ *  points 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;
+}
+
+/** 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)!;
+}
+
+// ── vendor-shaped id minting ────────────────────────────────────────────────────────────────────
+
+/** The seed every minted credential draws from. `readType` is unfiltered (soft-deletes counted),
+ *  so a value 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}`;
+}
+
+/**
+ * A TikTok user access token. The vendor's own example is `act.example12345Example12345Example`
+ * (User Access Token Management guide) — a dotted prefix plus an opaque tail, and integrations do
+ * key on the prefix. The twin reproduces the shape; the bytes are not the vendor's.
+ */
+export const mintAccessToken = (root: string | undefined, at: number, subject: string): string =>
+  `act.${stableHex(credentialSeed(root, BK_ACCESS, at, subject), 43)}`;
+
+/** A TikTok refresh token — the docs' `rft.example12345Example12345Example`. */
+export const mintRefreshToken = (root: string | undefined, at: number, subject: string): string =>
+  `rft.${stableHex(credentialSeed(root, BK_REFRESH, at, subject), 43)}`;
+
+/** An app-only client access token — the client-credentials guide's `clt.example12345…`. */
+export const mintClientToken = (root: string | undefined, at: number, subject: string): string =>
+  `clt.${stableHex(credentialSeed(root, BK_CLIENT, at, subject), 43)}`;
+
+/**
+ * An authorization code.
+ *
+ * EXTRAPOLATION, and a deliberate one. The token endpoint's parameter table says the `code` is
+ * "The authorization code from the web, iOS, Android or desktop authorization callback" and the
+ * summary page says it must be "URL decoded" — a note that is only meaningful if the code carries
+ * characters a query string must percent-encode. TikTok's codes are widely reported to end in a
+ * `*!<n>!` marker (`…%2A%211%21` on the wire), so the twin mints that shape: an integration that
+ * forgets to decode the callback parameter then fails HERE, locally, instead of against the real
+ * vendor. The exact live format is pinned by `tiktok.token.code_format` (todo).
+ */
+export const mintAuthorizationCode = (root: string | undefined, at: number, subject: string): string =>
+  `${stableHex(credentialSeed(root, BK_CODE, at, subject), 40)}*!1!`;
+
+/** Decimal digits drawn from ENTROPY. */
+function randomDigits(n: number): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(n));
+  return Array.from(bytes, (b) => String(b % 10)).join('');
+}
+
+// THE CONTENT POSTING IDS ARE DRAWN FROM ENTROPY, not from the instant and a count: a World cloned
+// from another replays the same counts at the same instants, and a count-seeded id would hand the
+// clone the ORIGIN'S publish ids, upload ids and post ids — two different posts under one id when
+// the clone's changes are pushed back (LinkedIn's asset ids, the same rule). Nothing reads them back
+// as replayed content: they are answered once, to the caller that made the post.
+
+/**
+ * A Content Posting `publish_id`, in the two shapes the references print: `v_pub_file~v2-1.123456789`
+ * for a Direct Post and `v_inbox_file~v2.123456789` for an upload to the creator's inbox.
+ */
+export const mintPublishId = (mode: 'direct' | 'inbox'): string =>
+  mode === 'direct' ? `v_pub_file~v2-1.${randomDigits(19)}` : `v_inbox_file~v2.${randomDigits(19)}`;
+
+/** The upload_id in an upload_url's query (the references print `upload_id=67890`). */
+export const mintUploadId = (): string => `7${randomDigits(18)}`;
+
+/** A published post's id — the 19-digit item id the Video Object carries and status/fetch reports in
+ *  `publicaly_available_post_id`. */
+export const mintPostId = (): string => `7${randomDigits(18)}`;
+
+/** A TikTok client key — the developer portal hands out an `aw…` string for a web app. */
+export const mintClientKey = (root: string | undefined, instant: string): string =>
+  `aw${stableHex(credentialSeed(root, 'oauth_client', instant, 'client'), 16)}`;
+
+/**
+ * Format 32 hex characters as a **version-4** UUID — the shape both `open_id` and `union_id` take
+ * in the vendor's own Get User Info example (`723f24d7-e717-40f8-a2b6-cb8464cd23b4`, whose 13th
+ * nibble is `4` and whose 17th is `a`).
+ *
+ * THE VERSION AND VARIANT NIBBLES ARE SET, deliberately: a stable hash sliced into 8-4-4-4-12 is
+ * UUID-SHAPED but not a valid UUID, so an integration that validates the id it stores — a Zod
+ * `.uuid()`, a Postgres `uuid` column, a Java `UUID.fromString` — would accept every real TikTok
+ * open_id and reject every one this twin minted. That is the twin being wrong where the vendor is
+ * right, which is exactly the class of bug a twin exists to remove. The seeded `union_id`s already
+ * follow this rule as literals (`00000000-0000-4000-8000-…`); this applies the same rule to the
+ * derived ids, and `tiktok.token.open_id_is_a_valid_uuid` pins it against the vendor's own example.
+ */
+function asUuid(hex32: string): string {
+  const variant = '89ab'[parseInt(hex32[16] ?? '0', 16) % 4]!;
+  return `${hex32.slice(0, 8)}-${hex32.slice(8, 12)}-4${hex32.slice(13, 16)}-${variant}${hex32.slice(17, 20)}-${hex32.slice(20, 32)}`;
+}
+
+/**
+ * The `open_id` a given app sees a given account as — PER (client_key, account) and STABLE, which
+ * is the whole distinction the vendor draws between `open_id` ("The TikTok user's unique
+ * identifier", app-scoped) and `union_id` (the same human across one developer's apps). No count
+ * and no instant enter this seed: re-authorizing must hand the app back the SAME open_id, and two
+ * different apps must see two different ones.
+ */
+export const openIdFor = (clientKey: string, accountId: string): string =>
+  asUuid(stableHex(`open_id:${clientKey}:${accountId}`, 32));
+
+// ── the authorize screen's handle: DETERMINISTIC, because it is SERVED (R9) ─────────────────────
+
+/** Every authorize parameter an `auth_request` row holds — its stable identity. */
+const AUTH_REQUEST_SIG_KEYS = [
+  'clientKey', '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('
');
+}
+
+/**
+ * Twin-internal handle for an authorize screen in flight (never leaves the twin's own pages) —
+ * `ar_` + 32 hex, 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.
+ */
+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 tiktok.com. TikTok shows the authorization
+// sheet 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 —
+// TikTok's real switcher is the tiktok.com account menu, which is not OAuth surface).
+
+/** The seeded demo app's client key. TikTok web apps are issued an `aw…` key by the developer
+ *  portal; a world running a real integration registers ITS OWN key through `POST /_twin/clients`
+ *  (there is no TikTok API that creates an app, so this is the only honest door). */
+export const DEFAULT_CLIENT_KEY = 'awtwindemoapp00001';
+export const DEFAULT_CLIENT_SECRET = 'twin-demo-client-secret-000000000000';
+
+/** NextAuth's callback path for the TikTok provider — the one most Login Kit guides walk through. */
+const CALLBACK_PATH = '/api/auth/callback/tiktok';
+
+export type SeedAccount = {
+  /** The subject id: the account's `union_id`, which is the vendor's own cross-app user key. */
+  unionId: string;
+  username: string;
+  displayName: string;
+  avatarUrl: string;
+  avatarUrl100: string;
+  avatarLargeUrl: string;
+  bioDescription: string;
+  profileDeepLink: string;
+  isVerified: boolean;
+  followerCount: number;
+  followingCount: number;
+  likesCount: number;
+  videoCount: number;
+};
+
+/**
+ * TikTok `union_id`s are v4-shaped UUIDs. The seeded personas take the ALL-ZERO corner of that
+ * space (`00000000-0000-4000-8000-…`), which a real v4 generator will not produce, so a locally
+ * seeded persona can never collide with a pulled real account (the datadog EVENT_ID_BASE / xidentity
+ * 9e18 precedent: the kernel projects twin-side writes over observations, so a colliding id would
+ * keep serving the local row).
+ */
+export const DEFAULT_ACCOUNTS: SeedAccount[] = [
+  {
+    unionId: '00000000-0000-4000-8000-000000000001',
+    username: 'ada_twin',
+    displayName: 'Ada Lovelace',
+    avatarUrl: 'https://p16-sign.tiktokcdn-us.com/twin/ada~c5_168x168.jpeg',
+    avatarUrl100: 'https://p16-sign.tiktokcdn-us.com/twin/ada~c5_100x100.jpeg',
+    avatarLargeUrl: 'https://p16-sign.tiktokcdn-us.com/twin/ada~c5_1080x1080.jpeg',
+    bioDescription: 'Analyst. Engine programmer. First of her kind.',
+    profileDeepLink: 'https://www.tiktok.com/@ada_twin',
+    isVerified: true,
+    followerCount: 58340,
+    followingCount: 204,
+    likesCount: 910233,
+    videoCount: 2,
+  },
+  {
+    unionId: '00000000-0000-4000-8000-000000000002',
+    username: 'grace_twin',
+    displayName: 'Grace Hopper',
+    avatarUrl: 'https://p16-sign.tiktokcdn-us.com/twin/grace~c5_168x168.jpeg',
+    avatarUrl100: 'https://p16-sign.tiktokcdn-us.com/twin/grace~c5_100x100.jpeg',
+    avatarLargeUrl: 'https://p16-sign.tiktokcdn-us.com/twin/grace~c5_1080x1080.jpeg',
+    bioDescription: 'It is easier to ask forgiveness than permission.',
+    profileDeepLink: 'https://www.tiktok.com/@grace_twin',
+    isVerified: false,
+    followerCount: 1204,
+    followingCount: 88,
+    likesCount: 5210,
+    videoCount: 1,
+  },
+];
+
+export type SeedVideo = {
+  id: string;
+  ownerUnionId: string;
+  title: string;
+  videoDescription: string;
+  /** UTC unix epoch SECONDS — the vendor's own `create_time` unit. */
+  createTime: number;
+  duration: number;
+  height: number;
+  width: number;
+  likeCount: number;
+  commentCount: number;
+  shareCount: number;
+  viewCount: number;
+};
+
+/** TikTok video ids ("also called item_id") are 19-digit numeric strings. The seeded ones start at
+ *  7.0e18, inside the shape but pinned to constants so the Display API reads are deterministic. */
+export const DEFAULT_VIDEOS: SeedVideo[] = [
+  {
+    id: '7000000000000000001',
+    ownerUnionId: '00000000-0000-4000-8000-000000000001',
+    title: 'Difference engine, part 1',
+    videoDescription: 'How the machine carries. #engineering',
+    createTime: 1_700_000_400,
+    duration: 42,
+    height: 1024,
+    width: 576,
+    likeCount: 4821,
+    commentCount: 133,
+    shareCount: 77,
+    viewCount: 190_233,
+  },
+  {
+    id: '7000000000000000002',
+    ownerUnionId: '00000000-0000-4000-8000-000000000001',
+    title: 'Notes on the Analytical Engine',
+    videoDescription: 'Note G, read aloud. #history',
+    createTime: 1_700_086_800,
+    duration: 61,
+    height: 1024,
+    width: 576,
+    likeCount: 9910,
+    commentCount: 402,
+    shareCount: 311,
+    viewCount: 820_114,
+  },
+  {
+    id: '7000000000000000003',
+    ownerUnionId: '00000000-0000-4000-8000-000000000002',
+    title: 'A nanosecond of wire',
+    videoDescription: 'This is how far light travels. #compsci',
+    createTime: 1_700_173_200,
+    duration: 30,
+    height: 1024,
+    width: 576,
+    likeCount: 22_004,
+    commentCount: 806,
+    shareCount: 1204,
+    viewCount: 1_400_500,
+  },
+];
+
+/**
+ * Every spelling of the ORIGIN this twin was reached on that a browser could hand back.
+ *
+ * TikTok matches a callback against the app's registered Redirect URIs ("It must match one of the
+ * redirect URIs you registered"), 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 app registers.
+ *
+ * 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 (`TikTokRequest.origin`, which
+ * tiktok-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 app + accounts + videos + 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 app, account, video 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_KEY)) missing.push({
+        type: 'oauth_client',
+        id: DEFAULT_CLIENT_KEY,
+        fields: {
+          name: 'Twin Demo App',
+          secretSha256: secretKey(DEFAULT_CLIENT_SECRET),
+          redirectUris: defaultRedirectUris(opts.origin),
+          rev: 1,
+        },
+      });
+      for (const account of DEFAULT_ACCOUNTS) {
+        if (has('account', account.unionId)) continue;
+        missing.push({
+          type: 'account',
+          id: account.unionId,
+          fields: {
+            username: account.username,
+            displayName: account.displayName,
+            avatarUrl: account.avatarUrl,
+            avatarUrl100: account.avatarUrl100,
+            avatarLargeUrl: account.avatarLargeUrl,
+            bioDescription: account.bioDescription,
+            profileDeepLink: account.profileDeepLink,
+            isVerified: account.isVerified,
+            followerCount: account.followerCount,
+            followingCount: account.followingCount,
+            likesCount: account.likesCount,
+            videoCount: account.videoCount,
+            rev: 1,
+          },
+        });
+      }
+      for (const video of DEFAULT_VIDEOS) {
+        if (has('video', video.id)) continue;
+        missing.push({
+          type: 'video',
+          id: video.id,
+          fields: {
+            ownerUnionId: video.ownerUnionId,
+            title: video.title,
+            videoDescription: video.videoDescription,
+            createTime: video.createTime,
+            duration: video.duration,
+            height: video.height,
+            width: video.width,
+            likeCount: video.likeCount,
+            commentCount: video.commentCount,
+            shareCount: video.shareCount,
+            viewCount: video.viewCount,
+            rev: 1,
+          },
+        });
+      }
+      if (!has('session', 'current')) missing.push({
+        type: 'session',
+        id: 'current',
+        fields: { accountId: DEFAULT_ACCOUNTS[0]!.unionId, 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 tiktok.com browser session is signed in as (the one the sheet 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` a registered Redirect URI for this app? TikTok's parameter table says the
+ * redirect_uri "must match one of the redirect URIs you registered", so the twin compares exactly.
+ *
+ * EVIDENCE BOUNDARY: the docs do not state whether the comparison is exact or prefix-based, nor
+ * whether TikTok's documented desktop-only allowance for `http://127.0.0.1:*` wildcards extends to
+ * web apps. Exact is the strict reading, and a loosely-matching twin would hide the single most
+ * common Login Kit integration bug; `tiktok.authorize.redirect_uri_matching` (todo) pins the live
+ * rule and `tiktok.authorize.redirect_uri_scheme_rules` pins the scheme/port restrictions.
+ */
+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); refuse it outright
+  // rather than let an exact registration smuggle one through.
+  if (candidate.includes('#')) return false;
+  return registered.includes(candidate);
+}