deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/play-runtime/internal-bootstrap-token.ts

@@ -0,0 +1,1322 @@
+import { WORKFLOW_EXECUTOR_TOKEN_TTL_SECONDS } from './/runtime-constants';
+import {
+  DEFAULT_RUNTIME_EXECUTION_CAPABILITIES,
+  isRuntimeExecutionCapability,
+  normalizeRuntimeExecutionCapabilities,
+  type RuntimeExecutionCapability,
+} from './/execution-capabilities';
+import {
+  validateFixtureBehavior,
+  type FixtureBehavior,
+} from './/fixture-behavior';
+import { normalizeRuntimeSchedulerSchema } from './/runtime-scheduler-topology';
+import { SignJWT, exportJWK, importJWK, jwtVerify, type JWK } from 'jose';
+import {
+  directCompletedTerminalContract,
+  type DirectCompletedTerminalContract,
+} from './/scheduler-backends/terminal-contract';
+
+// Frozen at 1: the content-addressed `kid` is the real rotation mechanism, so
+// this claim never moves and is not a place to encode a token change.
+const INTERNAL_BOOTSTRAP_TOKEN_VERSION = 1 as const;
+const INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS = 60 * 5;
+// Workflow executor token TTL.
+//
+// HISTORY: This used to be 7 days, with a comment that said "HITL workflow
+// steps can legitimately wait days for a human response." That comment was
+// describing an earlier design where a single activity blocked while waiting
+// on a human. It is no longer true.
+//
+// CURRENT DESIGN: HITL pauses happen at the *workflow* level via
+// `workflowSleep` + signal handlers.
+// When a signal fires (or a timer elapses), the workflow schedules a NEW
+// `executePlay` activity, and that activity mints a fresh executor token at
+// start. So the token only needs to outlive a single activity invocation,
+// which is bounded by `PLAY_ACTIVITY_TIMEOUT_SECONDS`. Matching the two
+// constants makes that contract explicit: an executor token cannot outlive
+// the activity it was minted for.
+//
+// CHANGING THIS: If you ever revert to a model where one activity blocks on
+// a long-running external wait, this TTL must grow accordingly — and the
+// activity startToCloseTimeout must grow with it. Do not bump one without
+// the other; the runtime API depends on the token being valid for the entire
+// lifetime of the activity that minted it.
+const INTERNAL_WORKFLOW_TOKEN_TTL_SECONDS = WORKFLOW_EXECUTOR_TOKEN_TTL_SECONDS;
+const INTERNAL_BOOTSTRAP_TOKEN_AUDIENCE =
+  'deepline.ingestion.provider_sync_bootstrap' as const;
+const INTERNAL_BOOTSTRAP_TOKEN_ISSUER = 'deepline.internal' as const;
+const INTERNAL_BOOTSTRAP_BOOTSTRAP_PURPOSE =
+  'ingestion_provider_sync_bootstrap' as const;
+const INTERNAL_BOOTSTRAP_EXECUTION_PURPOSE =
+  'ingestion_subscription_execution' as const;
+const INTERNAL_WORKFLOW_EXECUTION_AUDIENCE =
+  'deepline.workflow.execution' as const;
+const INTERNAL_WORKFLOW_EXECUTION_PURPOSE = 'workflow_run_execution' as const;
+const RUNTIME_RATE_SCOPE_AUDIENCE = 'deepline.runtime.rate_scope' as const;
+const RUNTIME_RATE_SCOPE_PURPOSE = 'runtime_rate_scope' as const;
+// The runner resolves a rate scope once per tool and retains it for the
+// executor activity. Keep this narrower, run-scoped capability valid for the
+// same bounded activity as the executor token that is required to use it.
+const RUNTIME_RATE_SCOPE_TOKEN_TTL_SECONDS =
+  WORKFLOW_EXECUTOR_TOKEN_TTL_SECONDS;
+const PLAY_DEPLOY_AUDIENCE = 'deepline.play.deploy' as const;
+const PLAY_DEPLOY_PURPOSE = 'play_deploy' as const;
+// A deploy token covers one GitHub deploy-on-push build task: tarball fetch,
+// bundling, register, promote, and status reporting. Deliberately its own
+// constant — the workflow executor TTL is contractually tied to a play
+// activity's runtime limits and must not be reused here.
+//
+// Two hours, not build-length: the token is minted at webhook intake and the
+// task may sit behind a queue backlog plus five exponential retries before
+// it runs, and an expired token would leave the deployment stuck in a
+// non-terminal state (the worker cannot even report failure without it).
+// Real revocation is the live-state check in requirePlayDeployAuth
+// (superseded/terminal deployment, disabled project), not this expiry.
+const PLAY_DEPLOY_TOKEN_TTL_SECONDS = 2 * 60 * 60;
+const INTERNAL_OAUTH_REFRESH_AUDIENCE = 'deepline.oauth.token_refresh' as const;
+const INTERNAL_OAUTH_REFRESH_PURPOSE = 'oauth_token_refresh' as const;
+const PRODUCT_NOTIFICATION_DELIVERY_AUDIENCE =
+  'deepline.product_notification.delivery' as const;
+const PRODUCT_NOTIFICATION_DELIVERY_PURPOSE =
+  'product_notification_delivery' as const;
+const PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE =
+  'deepline.product_notification.unsubscribe' as const;
+const PRODUCT_NOTIFICATION_UNSUBSCRIBE_PURPOSE =
+  'product_notification_unsubscribe' as const;
+const MONITOR_FLEET_DISPATCH_AUDIENCE =
+  'deepline.monitor_fleet.dispatch' as const;
+const MONITOR_FLEET_DISPATCH_PURPOSE = 'monitor_fleet_dispatch' as const;
+const INTERNAL_BOOTSTRAP_TOKEN_DERIVATION_LABEL =
+  'deepline:internal-bootstrap-token:v1';
+const WORKFLOW_EXECUTOR_KEY_DERIVATION_LABEL =
+  'deepline:workflow-executor-ed25519:v1';
+const ED25519_PKCS8_SEED_PREFIX = Uint8Array.from([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04,
+  0x22, 0x04, 0x20,
+]);
+
+type IngestionInternalTokenBaseClaims = {
+  aud: typeof INTERNAL_BOOTSTRAP_TOKEN_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  provider: string;
+  sub: string;
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type IngestionProviderSyncBootstrapTokenClaims =
+  IngestionInternalTokenBaseClaims & {
+    purpose: typeof INTERNAL_BOOTSTRAP_BOOTSTRAP_PURPOSE;
+    request_token: string;
+  };
+
+export type IngestionSubscriptionExecutionTokenClaims =
+  IngestionInternalTokenBaseClaims & {
+    purpose: typeof INTERNAL_BOOTSTRAP_EXECUTION_PURPOSE;
+    subscription_id: string;
+  };
+
+export type IngestionInternalTokenClaims =
+  | IngestionProviderSyncBootstrapTokenClaims
+  | IngestionSubscriptionExecutionTokenClaims;
+
+export type OAuthTokenRefreshTokenClaims = {
+  aud: typeof INTERNAL_OAUTH_REFRESH_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  provider: string;
+  purpose: typeof INTERNAL_OAUTH_REFRESH_PURPOSE;
+  sub: string;
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type ProductNotificationDeliveryTokenClaims = {
+  aud: typeof PRODUCT_NOTIFICATION_DELIVERY_AUDIENCE;
+  delivery_id: string;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  purpose: typeof PRODUCT_NOTIFICATION_DELIVERY_PURPOSE;
+  sub: 'product_notification_dispatcher';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type ProductNotificationUnsubscribeTokenClaims = {
+  aud: typeof PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE;
+  group_key: string;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  member_id: string;
+  org_id: string;
+  purpose: typeof PRODUCT_NOTIFICATION_UNSUBSCRIBE_PURPOSE;
+  sub: 'product_notification_recipient';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+/** Capability scoped to one durable Monitor Fleet control-plane operation. */
+export type MonitorFleetDispatchTokenClaims = {
+  aud: typeof MONITOR_FLEET_DISPATCH_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  purpose: typeof MONITOR_FLEET_DISPATCH_PURPOSE;
+  fleet_id?: string;
+  operation: 'dispatch' | 'daily_sync';
+  sub: 'monitor_fleet_dispatcher';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type PlayDeployTokenClaims = {
+  aud: typeof PLAY_DEPLOY_AUDIENCE;
+  deployment_id: string;
+  exp: number;
+  granted_by_user_id: string;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  play_project_id: string;
+  purpose: typeof PLAY_DEPLOY_PURPOSE;
+  sub: 'play_deploy_worker';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+type WorkflowInternalTokenBaseClaims = {
+  aud: typeof INTERNAL_WORKFLOW_EXECUTION_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  sub: string;
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+export type WorkflowRunExecutionTokenClaims =
+  WorkflowInternalTokenBaseClaims & {
+    purpose: typeof INTERNAL_WORKFLOW_EXECUTION_PURPOSE;
+    workflow_id: string;
+    run_id: string;
+    // Billing owner for this execution. Defaults to run_id on older tokens and
+    // root/top-level run id for child play executor tokens.
+    billing_run_id?: string;
+    // Required by the runtime storage endpoint. Do not make this optional:
+    // play/table names are caller-provided in runtime API requests, so the
+    // signed executor token must carry the authoritative play scope.
+    play_name: string;
+    allowed_secrets?: string[];
+    max_credits_per_run?: number;
+    integration_mode?: 'live' | 'eval_stub' | 'fixture';
+    fixture_behavior?: FixtureBehavior;
+    // Marks a run launched by an automated test harness (set in non-prod only).
+    // Carried on the signed token so the terminal runtime callback — which only
+    // sees executor-token auth, not the original CLI request — can suppress SDK
+    // CLI error alerts for intentionally failing test plays. Absent on real runs.
+    synthetic?: true;
+    // Identity of the actor that launched the run, carried on the signed token
+    // for the same reason as `synthetic`: the terminal runtime callback only
+    // sees executor-token auth, so without these claims it cannot attribute the
+    // run and emits "(unknown actor)" alerts. Optional — trigger/cron/system
+    // launches have no human actor, and older tokens predate the claims.
+    actor_user_id?: string;
+    actor_email?: string;
+    /** Durable scheduler topology attested by the launch-time app. */
+    scheduler_schema?: string;
+    /** Scheduler generation that owns durable writes for this execution leg. */
+    run_attempt?: number;
+    /** Opaque scheduler lease nonce bound to this exact execution leg. */
+    run_lease_token?: string;
+    /**
+     * Terminal transition contract declared by the worker release that asked
+     * for this token. Typed as a string, not a union: a token minted by an
+     * older or newer build may carry a value this build does not know, and
+     * that must degrade to the compatibility wake path rather than make an
+     * otherwise valid execution token fail verification.
+     */
+    terminal_contract?: string;
+    /** Explicit allow-list. Tokens without capabilities fail validation. */
+    capabilities: RuntimeExecutionCapability[];
+    /** Trusted deployment origin that issued this run token. */
+    runtime_origin?: string;
+  };
+
+export type RuntimeRateScopeTokenClaims = {
+  aud: typeof RUNTIME_RATE_SCOPE_AUDIENCE;
+  exp: number;
+  iat: number;
+  iss: typeof INTERNAL_BOOTSTRAP_TOKEN_ISSUER;
+  org_id: string;
+  run_id: string;
+  provider: string;
+  bucket_id: string;
+  scope_kind: 'fleet_managed' | 'customer_credential' | 'org';
+  purpose: typeof RUNTIME_RATE_SCOPE_PURPOSE;
+  sub: 'runtime_rate_scope';
+  v: typeof INTERNAL_BOOTSTRAP_TOKEN_VERSION;
+};
+
+function isValidWorkflowIntegrationMode(
+  value: unknown,
+): value is NonNullable<WorkflowRunExecutionTokenClaims['integration_mode']> {
+  return value === 'live' || value === 'eval_stub' || value === 'fixture';
+}
+
+function getRootSecret(): string {
+  const secretFromEnv = process.env.BETTER_AUTH_SECRET;
+  if (!secretFromEnv) {
+    throw new Error('BETTER_AUTH_SECRET is not set.');
+  }
+  return `${secretFromEnv}:${INTERNAL_BOOTSTRAP_TOKEN_DERIVATION_LABEL}`;
+}
+
+let workflowKeyCache: {
+  secret: string;
+  privateKey: CryptoKey;
+  publicJwk: JWK & { kid: string };
+} | null = null;
+
+async function deriveWorkflowExecutorSeed(secret: string): Promise<Uint8Array> {
+  // Convex WebCrypto does not implement HKDF. Implement the RFC 5869
+  // extract/expand operations with HMAC-SHA-256 instead, so this stays
+  // byte-for-byte compatible with the prior HKDF(seed, zero salt, label).
+  const toArrayBuffer = (bytes: Uint8Array): ArrayBuffer => {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+  };
+  const hmac = async (
+    keyMaterial: Uint8Array,
+    message: Uint8Array,
+  ): Promise<Uint8Array> => {
+    const key = await crypto.subtle.importKey(
+      'raw',
+      toArrayBuffer(keyMaterial),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    );
+    return new Uint8Array(
+      await crypto.subtle.sign('HMAC', key, toArrayBuffer(message)),
+    );
+  };
+  const info = new TextEncoder().encode(WORKFLOW_EXECUTOR_KEY_DERIVATION_LABEL);
+  const prk = await hmac(new Uint8Array(32), new TextEncoder().encode(secret));
+  const expandInput = new Uint8Array(info.length + 1);
+  expandInput.set(info);
+  expandInput[info.length] = 1;
+  return await hmac(prk, expandInput);
+}
+
+async function workflowExecutorKeyPair(): Promise<{
+  privateKey: CryptoKey;
+  publicJwk: JWK & { kid: string };
+}> {
+  const secret = process.env.BETTER_AUTH_SECRET?.trim();
+  if (!secret) throw new Error('BETTER_AUTH_SECRET is not set.');
+  if (workflowKeyCache?.secret === secret) return workflowKeyCache;
+  const seed = await deriveWorkflowExecutorSeed(secret);
+  const pkcs8 = new Uint8Array(ED25519_PKCS8_SEED_PREFIX.length + seed.length);
+  pkcs8.set(ED25519_PKCS8_SEED_PREFIX);
+  pkcs8.set(seed, ED25519_PKCS8_SEED_PREFIX.length);
+  const privateKey = await crypto.subtle.importKey(
+    'pkcs8',
+    pkcs8,
+    { name: 'Ed25519' },
+    true,
+    ['sign'],
+  );
+  const exported = await exportJWK(privateKey);
+  const publicJwk = {
+    kty: exported.kty,
+    crv: exported.crv,
+    x: exported.x,
+    use: 'sig',
+    alg: 'EdDSA',
+    kid: `runtime-${String(exported.x).slice(0, 16)}`,
+  } satisfies JWK & { kid: string };
+  workflowKeyCache = { secret, privateKey, publicJwk };
+  return workflowKeyCache;
+}
+
+export async function workflowExecutorPublicJwks(): Promise<{
+  keys: Array<JWK & { kid: string }>;
+}> {
+  const { publicJwk } = await workflowExecutorKeyPair();
+  return { keys: [publicJwk] };
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(value, 'base64'));
+  }
+
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function toBase64Url(bytes: Uint8Array): string {
+  return bytesToBase64(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  const padding =
+    value.length % 4 === 0 ? '' : '='.repeat(4 - (value.length % 4));
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/') + padding;
+  return base64ToBytes(normalized);
+}
+
+function encodeJson(value: unknown): string {
+  return toBase64Url(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+function decodeJson<T>(value: string): T {
+  const decoded = new TextDecoder().decode(fromBase64Url(value));
+  return JSON.parse(decoded) as T;
+}
+
+async function signTokenMaterial(value: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(getRootSecret()),
+    {
+      name: 'HMAC',
+      hash: 'SHA-256',
+    },
+    false,
+    ['sign'],
+  );
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    new TextEncoder().encode(value),
+  );
+  return toBase64Url(new Uint8Array(signature));
+}
+
+function timingSafeEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  let mismatch = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    mismatch |= left[index] ^ right[index];
+  }
+  return mismatch === 0;
+}
+
+function isValidClaimsShape(
+  claims: Record<string, unknown>,
+): claims is IngestionInternalTokenClaims {
+  const hasBaseShape =
+    claims.v === INTERNAL_BOOTSTRAP_TOKEN_VERSION &&
+    claims.iss === INTERNAL_BOOTSTRAP_TOKEN_ISSUER &&
+    claims.aud === INTERNAL_BOOTSTRAP_TOKEN_AUDIENCE &&
+    typeof claims.org_id === 'string' &&
+    claims.org_id.length > 0 &&
+    typeof claims.provider === 'string' &&
+    claims.provider.length > 0 &&
+    typeof claims.sub === 'string' &&
+    claims.sub.length > 0 &&
+    typeof claims.iat === 'number' &&
+    Number.isFinite(claims.iat) &&
+    typeof claims.exp === 'number' &&
+    Number.isFinite(claims.exp);
+
+  if (!hasBaseShape) {
+    return false;
+  }
+
+  if (claims.purpose === INTERNAL_BOOTSTRAP_BOOTSTRAP_PURPOSE) {
+    return (
+      typeof claims.request_token === 'string' &&
+      claims.request_token.length > 0
+    );
+  }
+
+  if (claims.purpose === INTERNAL_BOOTSTRAP_EXECUTION_PURPOSE) {
+    return (
+      typeof claims.subscription_id === 'string' &&
+      claims.subscription_id.length > 0
+    );
+  }
+
+  return false;
+}
+
+function isValidOAuthRefreshClaimsShape(
+  claims: Record<string, unknown>,
+): claims is OAuthTokenRefreshTokenClaims {
+  return (
+    claims.v === INTERNAL_BOOTSTRAP_TOKEN_VERSION &&
+    claims.iss === INTERNAL_BOOTSTRAP_TOKEN_ISSUER &&
+    claims.aud === INTERNAL_OAUTH_REFRESH_AUDIENCE &&
+    claims.purpose === INTERNAL_OAUTH_REFRESH_PURPOSE &&
+    typeof claims.org_id === 'string' &&
+    claims.org_id.length > 0 &&
+    typeof claims.provider === 'string' &&
+    claims.provider.length > 0 &&
+    typeof claims.sub === 'string' &&
+    claims.sub.length > 0 &&
+    typeof claims.iat === 'number' &&
+    Number.isFinite(claims.iat) &&
+    typeof claims.exp === 'number' &&
+    Number.isFinite(claims.exp)
+  );
+}
+
+function isValidRuntimeOrigin(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  try {
+    const url = new URL(value);
+    if (url.origin !== value || url.username || url.password) return false;
+    if (url.protocol === 'https:') return true;
+    return (
+      url.protocol === 'http:' &&
+      (url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '[::1]')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isValidWorkflowClaimsShape(
+  claims: Record<string, unknown>,
+): claims is WorkflowRunExecutionTokenClaims {
+  return (
+    claims.v === INTERNAL_BOOTSTRAP_TOKEN_VERSION &&
+    claims.iss === INTERNAL_BOOTSTRAP_TOKEN_ISSUER &&
+    claims.aud === INTERNAL_WORKFLOW_EXECUTION_AUDIENCE &&
+    claims.purpose === INTERNAL_WORKFLOW_EXECUTION_PURPOSE &&
+    typeof claims.org_id === 'string' &&
+    claims.org_id.length > 0 &&
+    typeof claims.workflow_id === 'string' &&
+    claims.workflow_id.length > 0 &&
+    typeof claims.run_id === 'string' &&
+    claims.run_id.length > 0 &&
+    (claims.billing_run_id === undefined ||
+      (typeof claims.billing_run_id === 'string' &&
+        claims.billing_run_id.length > 0)) &&
+    // Hard cutover invariant: old workflow tokens without play_name are not
+    // accepted. If this is loosened, runtime storage minting can no longer
+    // prove that the requested playName came from the signed run contract.
+    typeof claims.play_name === 'string' &&
+    claims.play_name.length > 0 &&
+    (claims.max_credits_per_run === undefined ||
+      (typeof claims.max_credits_per_run === 'number' &&
+        Number.isFinite(claims.max_credits_per_run) &&
+        claims.max_credits_per_run > 0)) &&
+    (claims.integration_mode === undefined ||
+      isValidWorkflowIntegrationMode(claims.integration_mode)) &&
+    (claims.fixture_behavior === undefined ||
+      (claims.integration_mode === 'fixture' &&
+        validateFixtureBehavior(claims.fixture_behavior).ok)) &&
+    (claims.synthetic === undefined || claims.synthetic === true) &&
+    (claims.actor_user_id === undefined ||
+      typeof claims.actor_user_id === 'string') &&
+    (claims.actor_email === undefined ||
+      typeof claims.actor_email === 'string') &&
+    (claims.scheduler_schema === undefined ||
+      normalizeRuntimeSchedulerSchema(claims.scheduler_schema) !== null) &&
+    (claims.run_attempt === undefined ||
+      (typeof claims.run_attempt === 'number' &&
+        Number.isSafeInteger(claims.run_attempt) &&
+        claims.run_attempt >= 0)) &&
+    (claims.run_lease_token === undefined ||
+      (typeof claims.run_lease_token === 'string' &&
+        claims.run_lease_token.length > 0)) &&
+    (claims.terminal_contract === undefined ||
+      typeof claims.terminal_contract === 'string') &&
+    (claims.runtime_origin === undefined ||
+      isValidRuntimeOrigin(claims.runtime_origin)) &&
+    Array.isArray(claims.capabilities) &&
+    claims.capabilities.length > 0 &&
+    claims.capabilities.every(isRuntimeExecutionCapability) &&
+    typeof claims.sub === 'string' &&
+    claims.sub.length > 0 &&
+    typeof claims.iat === 'number' &&
+    Number.isFinite(claims.iat) &&
+    typeof claims.exp === 'number' &&
+    Number.isFinite(claims.exp)
+  );
+}
+
+export async function mintIngestionProviderSyncBootstrapToken(input: {
+  orgId: string;
+  provider: string;
+  requestToken: string;
+  requestedByUserId: string | null;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: IngestionProviderSyncBootstrapTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: INTERNAL_BOOTSTRAP_TOKEN_AUDIENCE,
+    purpose: INTERNAL_BOOTSTRAP_BOOTSTRAP_PURPOSE,
+    org_id: input.orgId,
+    provider: input.provider,
+    request_token: input.requestToken,
+    sub: input.requestedByUserId ?? 'system',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
+  };
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT',
+  };
+  const encodedHeader = encodeJson(header);
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  const signature = await signTokenMaterial(signingInput);
+  return `${signingInput}.${signature}`;
+}
+
+export async function mintIngestionSubscriptionExecutionToken(input: {
+  orgId: string;
+  provider: string;
+  subscriptionId: string;
+  subject?: string | null;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: IngestionSubscriptionExecutionTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: INTERNAL_BOOTSTRAP_TOKEN_AUDIENCE,
+    purpose: INTERNAL_BOOTSTRAP_EXECUTION_PURPOSE,
+    org_id: input.orgId,
+    provider: input.provider,
+    subscription_id: input.subscriptionId,
+    sub: input.subject ?? 'ingestion_executor',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
+  };
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT',
+  };
+  const encodedHeader = encodeJson(header);
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  const signature = await signTokenMaterial(signingInput);
+  return `${signingInput}.${signature}`;
+}
+
+export async function mintWorkflowRunExecutionToken(input: {
+  orgId: string;
+  workflowId: string;
+  runId: string;
+  billingRunId?: string | null;
+  playName: string;
+  allowedSecrets?: readonly string[] | null;
+  maxCreditsPerRun?: number | null;
+  integrationMode?: 'live' | 'eval_stub' | 'fixture' | null;
+  fixtureBehavior?: FixtureBehavior | null;
+  synthetic?: boolean | null;
+  actorUserId?: string | null;
+  actorEmail?: string | null;
+  schedulerSchema?: string | null;
+  runAttempt?: number | null;
+  runLeaseToken?: string | null;
+  terminalContract?: DirectCompletedTerminalContract | null;
+  capabilities?: readonly RuntimeExecutionCapability[];
+  runtimeOrigin?: string | null;
+  subject?: string | null;
+  nowMs?: number;
+}): Promise<string> {
+  const fixtureBehavior = validateFixtureBehavior(input.fixtureBehavior);
+  if (!fixtureBehavior.ok) throw new Error(fixtureBehavior.error);
+  if (fixtureBehavior.behavior && input.integrationMode !== 'fixture') {
+    throw new Error(
+      'fixtureBehavior requires workflow integration mode "fixture".',
+    );
+  }
+  const actorUserId = input.actorUserId?.trim() || null;
+  const actorEmail = input.actorEmail?.trim() || null;
+  const schedulerSchema = normalizeRuntimeSchedulerSchema(
+    input.schedulerSchema,
+  );
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  // A retired contract value mints no claim; the verifier then selects the wake path.
+  const mintedTerminalContract = directCompletedTerminalContract(
+    input.terminalContract,
+  );
+  const claims: WorkflowRunExecutionTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: INTERNAL_WORKFLOW_EXECUTION_AUDIENCE,
+    purpose: INTERNAL_WORKFLOW_EXECUTION_PURPOSE,
+    org_id: input.orgId,
+    workflow_id: input.workflowId,
+    run_id: input.runId,
+    ...(input.billingRunId?.trim()
+      ? { billing_run_id: input.billingRunId.trim() }
+      : {}),
+    play_name: input.playName,
+    ...(input.allowedSecrets?.length
+      ? {
+          allowed_secrets: [
+            ...new Set(
+              input.allowedSecrets
+                .filter((name): name is string => typeof name === 'string')
+                .map((name) => name.trim().toUpperCase())
+                .filter(Boolean),
+            ),
+          ],
+        }
+      : {}),
+    ...(typeof input.maxCreditsPerRun === 'number' &&
+    Number.isFinite(input.maxCreditsPerRun) &&
+    input.maxCreditsPerRun > 0
+      ? { max_credits_per_run: input.maxCreditsPerRun }
+      : {}),
+    ...(isValidWorkflowIntegrationMode(input.integrationMode)
+      ? { integration_mode: input.integrationMode }
+      : {}),
+    ...(fixtureBehavior.behavior
+      ? { fixture_behavior: fixtureBehavior.behavior }
+      : {}),
+    ...(input.synthetic ? { synthetic: true as const } : {}),
+    ...(actorUserId ? { actor_user_id: actorUserId } : {}),
+    ...(actorEmail ? { actor_email: actorEmail } : {}),
+    ...(schedulerSchema ? { scheduler_schema: schedulerSchema } : {}),
+    ...(typeof input.runAttempt === 'number' &&
+    Number.isSafeInteger(input.runAttempt) &&
+    input.runAttempt >= 0
+      ? { run_attempt: input.runAttempt }
+      : {}),
+    ...(input.runLeaseToken?.trim()
+      ? { run_lease_token: input.runLeaseToken.trim() }
+      : {}),
+    ...(mintedTerminalContract
+      ? { terminal_contract: mintedTerminalContract }
+      : {}),
+    capabilities: normalizeRuntimeExecutionCapabilities(
+      input.capabilities ?? DEFAULT_RUNTIME_EXECUTION_CAPABILITIES,
+    ),
+    ...(input.runtimeOrigin?.trim()
+      ? { runtime_origin: new URL(input.runtimeOrigin).origin }
+      : {}),
+    sub: input.subject ?? 'workflow_executor',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_WORKFLOW_TOKEN_TTL_SECONDS,
+  };
+  const { privateKey, publicJwk } = await workflowExecutorKeyPair();
+  return await new SignJWT(claims)
+    .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT', kid: publicJwk.kid })
+    .sign(privateKey);
+}
+
+export async function mintRuntimeRateScopeToken(input: {
+  orgId: string;
+  runId: string;
+  provider: string;
+  bucketId: string;
+  scopeKind: RuntimeRateScopeTokenClaims['scope_kind'];
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: RuntimeRateScopeTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: RUNTIME_RATE_SCOPE_AUDIENCE,
+    purpose: RUNTIME_RATE_SCOPE_PURPOSE,
+    org_id: input.orgId,
+    run_id: input.runId,
+    provider: input.provider,
+    bucket_id: input.bucketId,
+    scope_kind: input.scopeKind,
+    sub: 'runtime_rate_scope',
+    iat: issuedAt,
+    exp: issuedAt + RUNTIME_RATE_SCOPE_TOKEN_TTL_SECONDS,
+  };
+  const { privateKey, publicJwk } = await workflowExecutorKeyPair();
+  return await new SignJWT(claims)
+    .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT', kid: publicJwk.kid })
+    .sign(privateKey);
+}
+
+export async function verifyRuntimeRateScopeTokenWithJwks(
+  token: string,
+  jwks: { keys: JWK[] },
+  nowMs = Date.now(),
+): Promise<RuntimeRateScopeTokenClaims> {
+  const headerKid = decodeJson<Record<string, unknown>>(
+    token.split('.')[0] ?? '',
+  ).kid;
+  const jwk = jwks.keys.find((candidate) => candidate.kid === headerKid);
+  if (!jwk) throw new Error('Invalid runtime rate-scope token key.');
+  const key = await importJWK(jwk, 'EdDSA');
+  const verified = await jwtVerify(token, key, {
+    algorithms: ['EdDSA'],
+    issuer: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    audience: RUNTIME_RATE_SCOPE_AUDIENCE,
+    currentDate: new Date(nowMs),
+    typ: 'JWT',
+  });
+  const claims = verified.payload as Record<string, unknown>;
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.purpose !== RUNTIME_RATE_SCOPE_PURPOSE ||
+    claims.sub !== 'runtime_rate_scope' ||
+    typeof claims.org_id !== 'string' ||
+    typeof claims.run_id !== 'string' ||
+    typeof claims.provider !== 'string' ||
+    typeof claims.bucket_id !== 'string' ||
+    !['fleet_managed', 'customer_credential', 'org'].includes(
+      String(claims.scope_kind),
+    )
+  ) {
+    throw new Error('Invalid runtime rate-scope token.');
+  }
+  return claims as RuntimeRateScopeTokenClaims;
+}
+
+export async function verifyRuntimeRateScopeToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<RuntimeRateScopeTokenClaims> {
+  const { publicJwk } = await workflowExecutorKeyPair();
+  return await verifyRuntimeRateScopeTokenWithJwks(
+    token,
+    { keys: [publicJwk] },
+    nowMs,
+  );
+}
+
+/**
+ * Deploy tokens authorize exactly one GitHub deploy-on-push deployment. The
+ * control plane mints one at webhook-intake time (the deploy worker holds no
+ * signing material) and only the /api/v2/deployments/* endpoints accept it.
+ * The granting principal is the play project's binding admin; the grant at
+ * bind time is the authorization event.
+ */
+export async function mintPlayDeployToken(input: {
+  orgId: string;
+  playProjectId: string;
+  deploymentId: string;
+  grantedByUserId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: PlayDeployTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: PLAY_DEPLOY_AUDIENCE,
+    purpose: PLAY_DEPLOY_PURPOSE,
+    org_id: input.orgId,
+    play_project_id: input.playProjectId,
+    deployment_id: input.deploymentId,
+    granted_by_user_id: input.grantedByUserId,
+    sub: 'play_deploy_worker',
+    iat: issuedAt,
+    exp: issuedAt + PLAY_DEPLOY_TOKEN_TTL_SECONDS,
+  };
+  const { privateKey, publicJwk } = await workflowExecutorKeyPair();
+  return await new SignJWT(claims)
+    .setProtectedHeader({ alg: 'EdDSA', typ: 'JWT', kid: publicJwk.kid })
+    .sign(privateKey);
+}
+
+/**
+ * Cheap pre-verification discriminator: does this bearer token claim to be a
+ * play deploy token? Decodes without verifying — callers must still verify.
+ */
+export function isPlayDeployTokenCandidate(token: string): boolean {
+  const segments = token.split('.');
+  if (segments.length !== 3) return false;
+  try {
+    const claims = decodeJson<Record<string, unknown>>(segments[1] ?? '');
+    return claims.aud === PLAY_DEPLOY_AUDIENCE;
+  } catch {
+    return false;
+  }
+}
+
+export async function verifyPlayDeployToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<PlayDeployTokenClaims> {
+  const { publicJwk } = await workflowExecutorKeyPair();
+  const headerKid = decodeJson<Record<string, unknown>>(
+    token.split('.')[0] ?? '',
+  ).kid;
+  if (headerKid !== publicJwk.kid) {
+    throw new Error('Invalid play deploy token key.');
+  }
+  const key = await importJWK(publicJwk, 'EdDSA');
+  const verified = await jwtVerify(token, key, {
+    algorithms: ['EdDSA'],
+    issuer: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    audience: PLAY_DEPLOY_AUDIENCE,
+    currentDate: new Date(nowMs),
+    typ: 'JWT',
+  });
+  const claims = verified.payload as Record<string, unknown>;
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.purpose !== PLAY_DEPLOY_PURPOSE ||
+    claims.sub !== 'play_deploy_worker' ||
+    typeof claims.org_id !== 'string' ||
+    !claims.org_id ||
+    typeof claims.play_project_id !== 'string' ||
+    !claims.play_project_id ||
+    typeof claims.deployment_id !== 'string' ||
+    !claims.deployment_id ||
+    typeof claims.granted_by_user_id !== 'string' ||
+    !claims.granted_by_user_id
+  ) {
+    throw new Error('Invalid play deploy token.');
+  }
+  return claims as PlayDeployTokenClaims;
+}
+
+// Server-only authorization for runtime OAuth token-refresh writes. Minted by
+// the server during integration execution (which holds the signing secret) and
+// verified by the Convex refresh mutation, so a member API key can never
+// authorize a connection write — it can only execute, which triggers the
+// server-side refresh that mints this token.
+export async function mintOAuthTokenRefreshToken(input: {
+  orgId: string;
+  provider: string;
+  subject?: string | null;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: OAuthTokenRefreshTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: INTERNAL_OAUTH_REFRESH_AUDIENCE,
+    purpose: INTERNAL_OAUTH_REFRESH_PURPOSE,
+    org_id: input.orgId,
+    provider: input.provider,
+    sub: input.subject ?? 'oauth_token_refresh',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
+  };
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT',
+  };
+  const encodedHeader = encodeJson(header);
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  const signature = await signTokenMaterial(signingInput);
+  return `${signingInput}.${signature}`;
+}
+
+export async function verifyOAuthTokenRefreshToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<OAuthTokenRefreshTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) {
+    throw new Error('Invalid OAuth refresh token.');
+  }
+
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid OAuth refresh token.');
+  }
+
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid OAuth refresh token.');
+  }
+
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (!isValidOAuthRefreshClaimsShape(claims)) {
+    throw new Error('Invalid OAuth refresh token.');
+  }
+
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('OAuth refresh token expired.');
+  }
+
+  return claims;
+}
+
+/**
+ * Mints a short-lived capability for one product-notification delivery. The
+ * delivery id is part of the signed scope so the receiving route cannot use a
+ * valid token to read another org delivery or OAuth connection.
+ */
+export async function mintProductNotificationDeliveryToken(input: {
+  orgId: string;
+  deliveryId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: ProductNotificationDeliveryTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: PRODUCT_NOTIFICATION_DELIVERY_AUDIENCE,
+    purpose: PRODUCT_NOTIFICATION_DELIVERY_PURPOSE,
+    org_id: input.orgId,
+    delivery_id: input.deliveryId,
+    sub: 'product_notification_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
+  };
+  const encodedHeader = encodeJson({ alg: 'HS256', typ: 'JWT' });
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  const signature = await signTokenMaterial(signingInput);
+  return `${signingInput}.${signature}`;
+}
+
+export async function verifyProductNotificationDeliveryToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<ProductNotificationDeliveryTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) {
+    throw new Error('Invalid product notification delivery token.');
+  }
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid product notification delivery token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid product notification delivery token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== PRODUCT_NOTIFICATION_DELIVERY_AUDIENCE ||
+    claims.purpose !== PRODUCT_NOTIFICATION_DELIVERY_PURPOSE ||
+    claims.sub !== 'product_notification_dispatcher' ||
+    typeof claims.org_id !== 'string' ||
+    claims.org_id.length === 0 ||
+    typeof claims.delivery_id !== 'string' ||
+    claims.delivery_id.length === 0 ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp)
+  ) {
+    throw new Error('Invalid product notification delivery token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Product notification delivery token expired.');
+  }
+  return claims as ProductNotificationDeliveryTokenClaims;
+}
+
+/**
+ * Mints a durable, narrowly scoped opt-out command. It never expires because
+ * an old notification must remain usable to stop future email; rotating the
+ * application secret revokes every outstanding link.
+ */
+export async function mintProductNotificationUnsubscribeToken(input: {
+  orgId: string;
+  groupKey: string;
+  memberId: string;
+  nowMs?: number;
+}): Promise<string> {
+  const claims: ProductNotificationUnsubscribeTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE,
+    purpose: PRODUCT_NOTIFICATION_UNSUBSCRIBE_PURPOSE,
+    org_id: input.orgId,
+    group_key: input.groupKey,
+    member_id: input.memberId,
+    sub: 'product_notification_recipient',
+    iat: Math.floor((input.nowMs ?? Date.now()) / 1000),
+  };
+  const encodedHeader = encodeJson({ alg: 'HS256', typ: 'JWT' });
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  return `${signingInput}.${await signTokenMaterial(signingInput)}`;
+}
+
+export async function verifyProductNotificationUnsubscribeToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<ProductNotificationUnsubscribeTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) {
+    throw new Error('Invalid product notification unsubscribe token.');
+  }
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid product notification unsubscribe token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid product notification unsubscribe token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== PRODUCT_NOTIFICATION_UNSUBSCRIBE_AUDIENCE ||
+    claims.purpose !== PRODUCT_NOTIFICATION_UNSUBSCRIBE_PURPOSE ||
+    claims.sub !== 'product_notification_recipient' ||
+    typeof claims.org_id !== 'string' ||
+    !claims.org_id ||
+    typeof claims.group_key !== 'string' ||
+    !claims.group_key ||
+    typeof claims.member_id !== 'string' ||
+    !claims.member_id ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    claims.iat > Math.floor(nowMs / 1000) + 30
+  ) {
+    throw new Error('Invalid product notification unsubscribe token.');
+  }
+  return claims as ProductNotificationUnsubscribeTokenClaims;
+}
+
+export async function mintMonitorFleetDispatchToken(input: {
+  orgId: string;
+  operation: 'dispatch' | 'daily_sync';
+  fleetId?: string;
+  nowMs?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.nowMs ?? Date.now()) / 1000);
+  const claims: MonitorFleetDispatchTokenClaims = {
+    v: INTERNAL_BOOTSTRAP_TOKEN_VERSION,
+    iss: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+    aud: MONITOR_FLEET_DISPATCH_AUDIENCE,
+    purpose: MONITOR_FLEET_DISPATCH_PURPOSE,
+    org_id: input.orgId,
+    operation: input.operation,
+    ...(input.fleetId ? { fleet_id: input.fleetId } : {}),
+    sub: 'monitor_fleet_dispatcher',
+    iat: issuedAt,
+    exp: issuedAt + INTERNAL_BOOTSTRAP_TOKEN_TTL_SECONDS,
+  };
+  const encodedHeader = encodeJson({ alg: 'HS256', typ: 'JWT' });
+  const encodedClaims = encodeJson(claims);
+  const signingInput = `${encodedHeader}.${encodedClaims}`;
+  return `${signingInput}.${await signTokenMaterial(signingInput)}`;
+}
+
+export async function verifyMonitorFleetDispatchToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<MonitorFleetDispatchTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3)
+    throw new Error('Invalid monitor fleet dispatch token.');
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid monitor fleet dispatch token.');
+  }
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid monitor fleet dispatch token.');
+  }
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (
+    claims.v !== INTERNAL_BOOTSTRAP_TOKEN_VERSION ||
+    claims.iss !== INTERNAL_BOOTSTRAP_TOKEN_ISSUER ||
+    claims.aud !== MONITOR_FLEET_DISPATCH_AUDIENCE ||
+    claims.purpose !== MONITOR_FLEET_DISPATCH_PURPOSE ||
+    claims.sub !== 'monitor_fleet_dispatcher' ||
+    typeof claims.org_id !== 'string' ||
+    !claims.org_id ||
+    !['dispatch', 'daily_sync'].includes(String(claims.operation)) ||
+    (claims.fleet_id !== undefined && typeof claims.fleet_id !== 'string') ||
+    typeof claims.iat !== 'number' ||
+    !Number.isFinite(claims.iat) ||
+    typeof claims.exp !== 'number' ||
+    !Number.isFinite(claims.exp)
+  ) {
+    throw new Error('Invalid monitor fleet dispatch token.');
+  }
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Monitor fleet dispatch token expired.');
+  }
+  return claims as MonitorFleetDispatchTokenClaims;
+}
+
+export async function verifyIngestionInternalToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<IngestionInternalTokenClaims> {
+  const segments = token.split('.');
+  if (segments.length !== 3) {
+    throw new Error('Invalid ingestion token.');
+  }
+
+  const [encodedHeader, encodedClaims, signature] = segments;
+  const header = decodeJson<Record<string, unknown>>(encodedHeader);
+  if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+    throw new Error('Invalid ingestion token.');
+  }
+
+  const expectedSignature = await signTokenMaterial(
+    `${encodedHeader}.${encodedClaims}`,
+  );
+  if (
+    !timingSafeEqual(fromBase64Url(signature), fromBase64Url(expectedSignature))
+  ) {
+    throw new Error('Invalid ingestion token.');
+  }
+
+  const claims = decodeJson<Record<string, unknown>>(encodedClaims);
+  if (!isValidClaimsShape(claims)) {
+    throw new Error('Invalid ingestion token.');
+  }
+
+  if (claims.exp <= Math.floor(nowMs / 1000)) {
+    throw new Error('Ingestion token expired.');
+  }
+
+  return claims;
+}
+
+export async function verifyWorkflowInternalToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<WorkflowRunExecutionTokenClaims> {
+  const { publicJwk } = await workflowExecutorKeyPair();
+  return await verifyWorkflowInternalTokenWithJwks(
+    token,
+    { keys: [publicJwk] },
+    nowMs,
+  );
+}
+
+export async function verifyWorkflowInternalTokenWithJwks(
+  token: string,
+  jwks: { keys: JWK[] },
+  nowMs = Date.now(),
+): Promise<WorkflowRunExecutionTokenClaims> {
+  const headerKid = decodeJson<Record<string, unknown>>(
+    token.split('.')[0] ?? '',
+  ).kid;
+  const jwk = jwks.keys.find((candidate) => candidate.kid === headerKid);
+  if (!jwk) throw new Error('Invalid workflow token key.');
+  const key = await importJWK(jwk, 'EdDSA');
+  let claims: Record<string, unknown>;
+  try {
+    const verified = await jwtVerify(token, key, {
+      algorithms: ['EdDSA'],
+      issuer: INTERNAL_BOOTSTRAP_TOKEN_ISSUER,
+      audience: INTERNAL_WORKFLOW_EXECUTION_AUDIENCE,
+      currentDate: new Date(nowMs),
+      typ: 'JWT',
+    });
+    claims = verified.payload as Record<string, unknown>;
+  } catch (error) {
+    if (
+      error &&
+      typeof error === 'object' &&
+      'code' in error &&
+      (error as { code?: unknown }).code === 'ERR_JWT_EXPIRED'
+    ) {
+      throw new Error('Workflow token expired.');
+    }
+    throw error;
+  }
+  if (!isValidWorkflowClaimsShape(claims)) {
+    throw new Error('Invalid workflow token.');
+  }
+
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (claims.exp <= nowSeconds || claims.iat > nowSeconds + 30) {
+    throw new Error('Workflow token expired.');
+  }
+
+  return claims;
+}
+
+export async function verifyIngestionProviderSyncBootstrapToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<IngestionProviderSyncBootstrapTokenClaims> {
+  const claims = await verifyIngestionInternalToken(token, nowMs);
+  if (claims.purpose !== INTERNAL_BOOTSTRAP_BOOTSTRAP_PURPOSE) {
+    throw new Error('Invalid bootstrap token.');
+  }
+  return claims;
+}
+
+export async function verifyIngestionSubscriptionExecutionToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<IngestionSubscriptionExecutionTokenClaims> {
+  const claims = await verifyIngestionInternalToken(token, nowMs);
+  if (claims.purpose !== INTERNAL_BOOTSTRAP_EXECUTION_PURPOSE) {
+    throw new Error('Invalid execution token.');
+  }
+  return claims;
+}
+
+export async function verifyWorkflowRunExecutionToken(
+  token: string,
+  nowMs = Date.now(),
+): Promise<WorkflowRunExecutionTokenClaims> {
+  const claims = await verifyWorkflowInternalToken(token, nowMs);
+  if (claims.purpose !== INTERNAL_WORKFLOW_EXECUTION_PURPOSE) {
+    throw new Error('Invalid workflow execution token.');
+  }
+  return claims;
+}
+
+export async function verifyWorkflowRunExecutionTokenWithJwks(
+  token: string,
+  jwks: { keys: JWK[] },
+  nowMs = Date.now(),
+): Promise<WorkflowRunExecutionTokenClaims> {
+  const claims = await verifyWorkflowInternalTokenWithJwks(token, jwks, nowMs);
+  if (claims.purpose !== INTERNAL_WORKFLOW_EXECUTION_PURPOSE) {
+    throw new Error('Invalid workflow execution token.');
+  }
+  return claims;
+}