@foir/sdk 0.10.0 → 0.12.0

package/dist/server.js

@@ -117,15 +117,17 @@ async function loadJwks(jwksUrl) {
   return keys;
 }
 function parseSubject(sub) {
-  const parts = sub.split("|");
-  if (parts.length !== 3) {
-    throw new Error(`malformed sub: expected 3 pipe-delimited segments, got ${parts.length}`);
+  const first = sub.indexOf("|");
+  const second = first === -1 ? -1 : sub.indexOf("|", first + 1);
+  if (first === -1 || second === -1) {
+    throw new Error("malformed sub: expected <tenant>|<project>|<app>");
   }
-  const [tenantId, projectId, appName] = parts;
-  if (!tenantId || !projectId || !appName) {
-    throw new Error("malformed sub: empty segment");
+  const tenantId = sub.slice(0, first);
+  const projectId = sub.slice(first + 1, second);
+  if (!tenantId || !projectId) {
+    throw new Error("malformed sub: empty tenant or project");
   }
-  return { tenantId, projectId, appName };
+  return { tenantId, projectId, appName: sub.slice(second + 1) };
 }
 function recordsReadModels(claims) {
   return claims.rrm ?? [];
@@ -134,16 +136,25 @@ function recordsWriteModels(claims) {
   return claims.rwm ?? [];
 }
 async function verifyScopedToken(token, jwksUrl, options) {
+  return verifyWithKeys(token, () => loadJwks(jwksUrl), void 0, options);
+}
+async function verifyWithKeys(token, loadKeys, refetchForUnknownKid, options) {
   const expectedIssuer = options?.expectedIssuer ?? "foir-platform";
   const parts = token.split(".");
   if (parts.length !== 3) throw new Error("malformed token");
   const [rawHeader, rawPayload, rawSig] = parts;
-  const header = JSON.parse(
-    new TextDecoder().decode(base64UrlDecode(rawHeader))
-  );
-  if (header.alg !== "EdDSA") throw new Error(`unexpected alg ${header.alg}`);
-  if (!header.kid) throw new Error("missing kid");
-  const keys = await loadJwks(jwksUrl);
+  let header;
+  try {
+    header = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawHeader)));
+  } catch {
+    throw new Error("unreadable token header");
+  }
+  if (header.alg !== "EdDSA") throw new Error(`unexpected alg ${String(header.alg)}`);
+  if (typeof header.kid !== "string" || !header.kid) throw new Error("missing kid");
+  let keys = await loadKeys();
+  if (!keys.has(header.kid) && refetchForUnknownKid) {
+    keys = await refetchForUnknownKid() ?? keys;
+  }
   const key = keys.get(header.kid);
   if (!key) throw new Error(`unknown kid ${header.kid}`);
   const signingInput = new TextEncoder().encode(`${rawHeader}.${rawPayload}`);
@@ -158,10 +169,13 @@ async function verifyScopedToken(token, jwksUrl, options) {
     )
   );
   if (!ok) throw new Error("signature invalid");
-  const claims = JSON.parse(
-    new TextDecoder().decode(base64UrlDecode(rawPayload))
-  );
-  const now = Math.floor(Date.now() / 1e3);
+  let claims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(base64UrlDecode(rawPayload)));
+  } catch {
+    throw new Error("unreadable token payload");
+  }
+  const now = Math.floor((options?.now?.() ?? Date.now()) / 1e3);
   if (claims.iss !== expectedIssuer) throw new Error(`bad iss ${claims.iss}`);
   if (typeof claims.exp !== "number" || claims.exp < now) {
     throw new Error("token expired");
@@ -183,35 +197,174 @@ function parseContextHeader(raw) {
   }
   return out;
 }
+var ScopedTokenUnavailableError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "ScopedTokenUnavailableError";
+    if (options?.cause !== void 0) this.cause = options.cause;
+  }
+};
+var VERIFIER_TTL_MS = 60 * 60 * 1e3;
+var VERIFIER_TIMEOUT_MS = 5e3;
+var KID_MISS_COOLDOWN_MS = 6e4;
+var FAILURE_COOLDOWN_MS = 6e4;
+function createScopedTokenVerifier(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? VERIFIER_TIMEOUT_MS;
+  const ttlMs = options.ttlMs ?? VERIFIER_TTL_MS;
+  let cache;
+  let inFlight;
+  let lastKidMissRefetch = 0;
+  let nextAttemptAt = 0;
+  let staleServes = 0;
+  let refetchFailures = 0;
+  let notModified = 0;
+  async function fetchKeys(held) {
+    try {
+      const headers = { accept: "application/json" };
+      if (held?.etag) headers["if-none-match"] = held.etag;
+      const res = await doFetch(options.jwksUrl, {
+        ...options.requestInit,
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (res.status === 304 && held) {
+        notModified += 1;
+        nextAttemptAt = 0;
+        cache = { ...held, fetchedAt: now() };
+        return cache;
+      }
+      if (!res.ok) throw new Error(`jwks fetch ${res.status}`);
+      const doc = await res.json();
+      const keys2 = /* @__PURE__ */ new Map();
+      for (const jwk of doc.keys ?? []) {
+        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.kid || !jwk.x) continue;
+        const raw = base64UrlDecode(jwk.x);
+        keys2.set(
+          jwk.kid,
+          await crypto.subtle.importKey(
+            "raw",
+            raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength),
+            { name: "Ed25519" },
+            false,
+            ["verify"]
+          )
+        );
+      }
+      if (keys2.size === 0) throw new Error("jwks carried no Ed25519 keys");
+      nextAttemptAt = 0;
+      cache = { keys: keys2, fetchedAt: now(), etag: res.headers.get("etag") ?? void 0 };
+      return cache;
+    } catch (error) {
+      refetchFailures += 1;
+      nextAttemptAt = now() + FAILURE_COOLDOWN_MS;
+      if (held) {
+        staleServes += 1;
+        try {
+          options.onStale?.({ error, ageMs: now() - held.fetchedAt, staleServes });
+        } catch {
+        }
+        return held;
+      }
+      throw new ScopedTokenUnavailableError(
+        `the JWKS could not be read and no keys are held: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  function keys(force) {
+    const held = cache;
+    const at = now();
+    if (!force && held && at - held.fetchedAt < ttlMs) return Promise.resolve(held);
+    if (at < nextAttemptAt && !inFlight) {
+      if (held) {
+        staleServes += 1;
+        return Promise.resolve(held);
+      }
+      return Promise.reject(
+        new ScopedTokenUnavailableError(
+          `the JWKS could not be read and no keys are held; the next attempt is in ${Math.ceil((nextAttemptAt - at) / 1e3)}s`
+        )
+      );
+    }
+    inFlight ??= fetchKeys(held).finally(() => {
+      inFlight = void 0;
+    });
+    return inFlight;
+  }
+  return {
+    verify(token) {
+      return verifyWithKeys(
+        token,
+        async () => (await keys(false)).keys,
+        async () => {
+          const at = now();
+          if (at - lastKidMissRefetch < KID_MISS_COOLDOWN_MS) return null;
+          lastKidMissRefetch = at;
+          return (await keys(true)).keys;
+        },
+        { expectedIssuer: options.expectedIssuer, now }
+      );
+    },
+    async warm() {
+      try {
+        await keys(false);
+      } catch {
+      }
+    },
+    stats() {
+      return {
+        keyCount: cache?.keys.size ?? 0,
+        ageMs: cache ? now() - cache.fetchedAt : null,
+        staleServes,
+        refetchFailures,
+        notModified
+      };
+    }
+  };
+}
 
 // src/server/require-scoped-token.ts
-var TOKEN_HEADER = "X-Foir-Token";
-var CONTEXT_HEADER = "X-Foir-Context";
+var FOIR_TOKEN_HEADER = "X-Foir-Token";
+var FOIR_CONTEXT_HEADER = "X-Foir-Context";
+var TOKEN_HEADER = FOIR_TOKEN_HEADER;
+var CONTEXT_HEADER = FOIR_CONTEXT_HEADER;
 var DEFAULT_JWKS_URL = "https://api.foir.dev/.well-known/jwks.json";
 var ScopedTokenError = class extends Error {
   status;
-  constructor(message, status) {
+  /**
+   * Why, for a route that answers the cases differently: `missing` (the
+   * request carried no token at all, so it did not come from the platform),
+   * `invalid` (a token that does not verify), `forbidden` (a valid token for
+   * another tenant or project) and `unavailable` (the token could not be
+   * checked).
+   */
+  reason;
+  constructor(message, status, reason) {
     super(message);
     this.name = "ScopedTokenError";
     this.status = status;
+    this.reason = reason ?? (status === 403 ? "forbidden" : status === 503 ? "unavailable" : "invalid");
   }
 };
+var LEVEL_CLAIM = "org_id";
 async function requireScopedToken(request, options) {
   const token = request.headers.get(TOKEN_HEADER);
   if (!token) {
     throw new ScopedTokenError(
       `missing ${TOKEN_HEADER} header \u2014 this route only accepts platform-dispatched requests`,
-      401
+      401,
+      "missing"
     );
   }
   let claims;
   try {
-    claims = await verifyScopedToken(
-      token,
-      options?.jwksUrl ?? DEFAULT_JWKS_URL,
-      options
-    );
+    claims = options?.verifier ? await options.verifier.verify(token) : await verifyScopedToken(token, options?.jwksUrl ?? DEFAULT_JWKS_URL, options);
   } catch (err) {
+    if (err instanceof ScopedTokenUnavailableError) {
+      throw new ScopedTokenError(`the scoped token could not be checked: ${err.message}`, 503);
+    }
     throw new ScopedTokenError(
       `invalid scoped token: ${err instanceof Error ? err.message : String(err)}`,
       401
@@ -238,111 +391,126 @@ async function requireScopedToken(request, options) {
       403
     );
   }
+  const rawContext = request.headers.get(CONTEXT_HEADER);
+  const level = claims.ctx?.[LEVEL_CLAIM];
   return {
     claims,
     subject,
-    context: parseContextHeader(request.headers.get(CONTEXT_HEADER))
+    context: parseContextHeader(rawContext),
+    // The token handed over is the one verified above, not a fresh read of the
+    // header, so the client presents exactly what this guard accepted.
+    dispatch: { token: () => token, context: rawContext },
+    orgId: typeof level === "string" ? level : null,
+    ...typeof claims.cid === "string" && claims.cid !== "" ? { customerId: claims.cid } : {},
+    expiresAt: new Date(claims.exp * 1e3),
+    tokenId: claims.jti
   };
 }
 
-// src/server/callback-client.ts
-function createCallbackClient(callback, opts) {
-  const { executionId, signingSecret } = opts;
-  const fetchImpl = opts.fetch ?? globalThis.fetch;
-  if (!fetchImpl) {
-    throw new Error(
-      "createCallbackClient: no fetch available; pass opts.fetch on runtimes without a global fetch"
+// src/server/read-dispatch.ts
+var OperationPayloadError = class extends Error {
+  status;
+  constructor(message) {
+    super(message);
+    this.name = "OperationPayloadError";
+    this.status = 400;
+  }
+};
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function refuse(message) {
+  throw new OperationPayloadError(`[foir] not an operation dispatch body: ${message}`);
+}
+function requireString(from, key, where, allowEmpty = false) {
+  const value = from[key];
+  if (typeof value !== "string" || !allowEmpty && value === "") {
+    refuse(`${where}.${key} is ${describe(value)}, expected a${allowEmpty ? "" : " non-empty"} string`);
+  }
+  return value;
+}
+function describe(value) {
+  if (value === void 0) return "missing";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+async function readDispatch(request) {
+  let text;
+  try {
+    text = await request.text();
+  } catch (err) {
+    throw new OperationPayloadError(
+      `[foir] could not read the dispatch body (has something already consumed it?): ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  if (!executionId) throw new Error("createCallbackClient: executionId is required");
-  if (!signingSecret) throw new Error("createCallbackClient: signingSecret is required");
-  if (!callback?.token || !callback?.gqlEndpoint || !callback?.mutations) {
-    throw new Error("createCallbackClient: callback block is missing required fields");
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    refuse("the body is not JSON");
   }
-  const post = async (mutationName, fields, variables) => {
-    const query = `mutation ${mutationName}Mutation($id: String!${fieldArgsForMutation(mutationName, variables)}) { ${mutationName}(id: $id${fieldArgsCallSite(mutationName, variables)}) { ${fields} } }`;
-    const body = JSON.stringify({
-      query,
-      variables: { id: executionId, ...variables }
-    });
-    const signature = await hmacSha256Hex(signingSecret, body);
-    const resp = await fetchImpl(callback.gqlEndpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${callback.token}`,
-        "X-Foir-Signature": `sha256=${signature}`
-      },
-      body
-    });
-    if (!resp.ok) {
-      throw new Error(`callback ${mutationName} failed with HTTP ${resp.status}: ${await resp.text()}`);
-    }
-    const json = await resp.json();
-    if (json.errors?.length) {
-      throw new Error(`callback ${mutationName} GraphQL error: ${json.errors[0].message}`);
+  if (!isObject(body)) refuse(`the body is ${describe(body)}, expected a JSON object`);
+  if (typeof body.executionId !== "string" || typeof body.operationKey !== "string") {
+    refuse(
+      "it has no executionId and operationKey. The platform sends the run, not the input: the caller's input is under `input`"
+    );
+  }
+  requireString(body, "executionId", "body");
+  requireString(body, "operationKey", "body");
+  const trigger = body.trigger;
+  if (!isObject(trigger)) refuse(`body.trigger is ${describe(trigger)}, expected an object`);
+  requireString(trigger, "type", "body.trigger");
+  const context = body.context;
+  if (!isObject(context)) refuse(`body.context is ${describe(context)}, expected an object`);
+  requireString(context, "tenantId", "body.context");
+  requireString(context, "projectId", "body.context");
+  requireString(context, "userId", "body.context", true);
+  requireString(context, "timestamp", "body.context");
+  if (context.customerId !== void 0) requireString(context, "customerId", "body.context");
+  const input = body.input;
+  if (input !== null && !isObject(input)) {
+    refuse(`body.input is ${describe(input)}, expected an object`);
+  }
+  const payload = { ...body, input: input ?? {} };
+  for (const block of ["content", "record", "triggerContext", "callback", "continuation"]) {
+    const value = payload[block];
+    if (value === void 0) continue;
+    if (value === null) {
+      delete payload[block];
+      continue;
     }
-    const out = json.data?.[mutationName];
-    if (!out) {
-      throw new Error(`callback ${mutationName} returned no data`);
+    if (!isObject(value)) refuse(`body.${block} is ${describe(value)}, expected an object`);
+  }
+  if (isObject(payload.continuation)) {
+    requireString(payload.continuation, "cursor", "body.continuation");
+    if (typeof payload.continuation.slice !== "number") {
+      refuse(`body.continuation.slice is ${describe(payload.continuation.slice)}, expected a number`);
     }
-    return out;
-  };
-  return {
-    complete: (result) => post(callback.mutations.complete, "status cancelled", { result }),
-    fail: (code, message, options = {}) => post(callback.mutations.fail, "status cancelled", {
-      code,
-      message,
-      retryable: options.retryable,
-      details: options.details
-    }),
-    progress: (update) => post(callback.mutations.progress, "status cancelled applied", {
-      pct: update.pct,
-      message: update.message,
-      metadata: update.metadata
-    }),
-    cancel: () => post(callback.mutations.cancel, "status cancelled", {})
-  };
-}
-function fieldArgsForMutation(mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, $${key}: ${graphQLTypeFor(mutationName, key)}`);
   }
-  return parts.join("");
+  return payload;
 }
-function fieldArgsCallSite(_mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, ${key}: $${key}`);
+
+// src/server/continue-run.ts
+var CONTINUATION_MEDIA_TYPE = "application/vnd.foir.continuation+json";
+var MAX_CONTINUATION_CURSOR_BYTES = 16 * 1024;
+var MAX_CONTINUATION_DELAY_MS = 15 * 60 * 1e3;
+function continueRun(continuation) {
+  const { cursor, delayMs, progressPct } = continuation;
+  if (typeof cursor !== "string" || cursor === "") {
+    throw new TypeError("continueRun: a continuation carries the cursor the next slice resumes from");
   }
-  return parts.join("");
-}
-function graphQLTypeFor(mutationName, key) {
-  if (key === "code" || key === "message") return "String!";
-  if (key === "pct") return "Int";
-  if (key === "retryable") return "Boolean";
-  if (key === "details" || key === "metadata") return "JSON";
-  if (key === "result") {
-    const base = mutationName.replace(/^complete/, "").replace(/Execution$/, "");
-    return `${base}ExecutionResultInput!`;
+  if (new TextEncoder().encode(cursor).length > MAX_CONTINUATION_CURSOR_BYTES) {
+    throw new RangeError(`continueRun: a cursor is at most ${MAX_CONTINUATION_CURSOR_BYTES} bytes`);
   }
-  if (key === "message") return "String";
-  return "String";
-}
-async function hmacSha256Hex(secret, body) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
-  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (delayMs !== void 0 && !(Number.isInteger(delayMs) && delayMs >= 0 && delayMs <= MAX_CONTINUATION_DELAY_MS)) {
+    throw new RangeError(`continueRun: delayMs is a whole number of milliseconds from 0 to ${MAX_CONTINUATION_DELAY_MS}`);
+  }
+  if (progressPct !== void 0 && !(Number.isInteger(progressPct) && progressPct >= 0 && progressPct <= 100)) {
+    throw new RangeError("continueRun: progressPct is a whole percentage from 0 to 100");
+  }
+  return new Response(JSON.stringify(continuation), {
+    status: 200,
+    headers: { "Content-Type": CONTINUATION_MEDIA_TYPE }
+  });
 }
 
 // src/transport/foir-http.ts
@@ -398,7 +566,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
     if (this.status === 429 || this.code === "RATE_LIMITED") return true;
     if (this.status >= 500) return true;
     return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
@@ -428,19 +601,50 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
 }
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -456,13 +660,226 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
+
+// src/transport/retry.ts
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 2e4;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function foirRetryDelayMs(error, attempt, policy = {}) {
+  if (!(error instanceof FoirRequestError) || !error.retryable) return null;
+  const max = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const stated = error.retryAfterMs;
+  if (stated !== void 0) return Math.min(stated, max);
+  const base = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  return Math.min(base * 2 ** (attempt - 1), max);
+}
+async function withFoirRetry(fn, policy = {}) {
+  const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+  const sleep = policy.sleep ?? defaultSleep;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      const delayMs = attempt >= attempts ? null : foirRetryDelayMs(error, attempt, policy);
+      if (delayMs === null) throw error;
+      policy.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs);
+    }
+  }
+}
+
+// src/server/callback-client.ts
+function createCallbackClient(callback, opts) {
+  const { executionId } = opts;
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error(
+      "createCallbackClient: no fetch available; pass opts.fetch on runtimes without a global fetch"
+    );
+  }
+  if (!executionId) throw new Error("createCallbackClient: executionId is required");
+  if (!callback?.token || !callback?.mutations) {
+    throw new Error("createCallbackClient: callback block is missing required fields");
+  }
+  if (!callback.gqlEndpoint && !opts.apiUrl) {
+    throw new Error(
+      "createCallbackClient: nowhere to report to. The dispatch named no callback.gqlEndpoint and no apiUrl was passed."
+    );
+  }
+  const endpoint = callback.gqlEndpoint || foirApiEndpoint(opts.apiUrl ?? "", "/graphql");
+  const signingSecret = opts.signingSecret || callback.signingKey;
+  if (!signingSecret) {
+    throw new Error(
+      "createCallbackClient: nothing to sign with. The dispatch carried no callback.signingKey and no signingSecret was passed."
+    );
+  }
+  const post = async (mutationName, fields, variables) => {
+    const query = `mutation ${mutationName}Mutation($id: String!${fieldArgsForMutation(mutationName, variables)}) { ${mutationName}(id: $id${fieldArgsCallSite(mutationName, variables)}) { ${fields} } }`;
+    const body = JSON.stringify({
+      query,
+      variables: { id: executionId, ...variables }
+    });
+    const signature = await hmacSha256Hex(signingSecret, body);
+    return withFoirRetry(async () => {
+      let resp;
+      try {
+        resp = await fetchImpl(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${callback.token}`,
+            "X-Foir-Signature": `sha256=${signature}`
+          },
+          body,
+          ...opts.signal ? { signal: opts.signal } : {}
+        });
+      } catch (err) {
+        if (opts.signal?.aborted) throw err;
+        throw new FoirRequestError(`callback ${mutationName} got no answer`, { cause: err });
+      }
+      if (!resp.ok) {
+        throw new FoirRequestError(
+          `callback ${mutationName} failed with HTTP ${resp.status}: ${await resp.text()}`,
+          { status: resp.status }
+        );
+      }
+      const json = await resp.json();
+      if (json.errors?.length) {
+        throw new FoirRequestError(`callback ${mutationName} GraphQL error: ${json.errors[0].message}`, {
+          status: resp.status,
+          graphQLErrors: json.errors
+        });
+      }
+      const out = json.data?.[mutationName];
+      if (!out) {
+        throw new FoirRequestError(`callback ${mutationName} returned no data`, { status: resp.status });
+      }
+      return out;
+    }, opts.retry);
+  };
+  return {
+    complete: (result) => post(callback.mutations.complete, "status cancelled", { result }),
+    fail: (code, message, options = {}) => post(callback.mutations.fail, "status cancelled", {
+      code,
+      message,
+      retryable: options.retryable,
+      details: options.details
+    }),
+    progress: (update) => post(callback.mutations.progress, "status cancelled applied", {
+      pct: update.pct,
+      message: update.message,
+      metadata: update.metadata
+    }),
+    cancel: () => post(callback.mutations.cancel, "status cancelled", {})
+  };
+}
+function fieldArgsForMutation(mutationName, vars) {
+  const parts = [];
+  for (const key of Object.keys(vars)) {
+    if (vars[key] === void 0) continue;
+    parts.push(`, $${key}: ${graphQLTypeFor(mutationName, key)}`);
+  }
+  return parts.join("");
+}
+function fieldArgsCallSite(_mutationName, vars) {
+  const parts = [];
+  for (const key of Object.keys(vars)) {
+    if (vars[key] === void 0) continue;
+    parts.push(`, ${key}: $${key}`);
+  }
+  return parts.join("");
+}
+function graphQLTypeFor(mutationName, key) {
+  if (key === "code" || key === "message") return "String!";
+  if (key === "pct") return "Int";
+  if (key === "retryable") return "Boolean";
+  if (key === "details" || key === "metadata") return "JSON";
+  if (key === "result") {
+    const base = mutationName.replace(/^complete/, "").replace(/Execution$/, "");
+    return `${base}ExecutionResultInput!`;
+  }
+  if (key === "message") return "String";
+  return "String";
+}
+async function hmacSha256Hex(secret, body) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 
 // src/data/transport.ts
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 
 // src/data/ws-transport.ts
 var GQL = {
@@ -500,6 +917,11 @@ var FoirSocketTransport = class {
   keepAlive = null;
   retryTimer = null;
   constructor(config) {
+    if (config.dispatch !== void 0) {
+      throw new FoirRequestError(
+        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, an admin token or a customer bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
+      );
+    }
     this.config = config;
     this.policy = { ...DEFAULT_RECONNECT, ...config.reconnect ?? {} };
   }
@@ -571,13 +993,7 @@ var FoirSocketTransport = class {
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const headers = buildFoirHeaders({
-        apiKey: this.config.apiKey,
-        draftChannel: this.config.channel === "draft",
-        bearerToken: await resolveBearerToken(this.config),
-        orgId: this.config.orgId,
-        extra: this.config.headers
-      });
+      const { headers } = await resolveFoirAuth(this.config);
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -684,7 +1100,7 @@ var FoirSocketTransport = class {
         return;
       }
       case GQL.error: {
-        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`, {
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe2(message.payload)}`, {
           graphQLErrors: graphQLErrorItems(message.payload)
         });
         if (!message.id) {
@@ -805,17 +1221,17 @@ function graphQLErrorItems(payload) {
     const { message, path, extensions } = entry;
     if (extensions === void 0 && path === void 0) continue;
     items.push({
-      message: typeof message === "string" ? message : describe(entry),
+      message: typeof message === "string" ? message : describe2(entry),
       ...Array.isArray(path) ? { path } : {},
       ...typeof extensions === "object" && extensions !== null ? { extensions } : {}
     });
   }
   return items.length > 0 ? items : void 0;
 }
-function describe(payload) {
+function describe2(payload) {
   if (payload == null) return "no reason given";
   if (typeof payload === "string") return payload;
-  if (Array.isArray(payload)) return payload.map(describe).join("; ");
+  if (Array.isArray(payload)) return payload.map(describe2).join("; ");
   if (typeof payload === "object") {
     const message = payload.message;
     if (typeof message === "string") return message;
@@ -1084,15 +1500,26 @@ function asEventsSocketError(error, requestedCursor) {
   return error;
 }
 export {
+  CONTINUATION_MEDIA_TYPE,
+  FOIR_CONTEXT_HEADER,
   FOIR_EVENTS_PATH,
   FOIR_EVENTS_RETENTION_DAYS,
   FOIR_EVENTS_SCOPE,
+  FOIR_TOKEN_HEADER,
+  FoirAuthDowngradedError,
   FoirEventCursorExpiredError,
   FoirRequestError,
+  FoirSessionExpiredError,
+  MAX_CONTINUATION_CURSOR_BYTES,
+  MAX_CONTINUATION_DELAY_MS,
+  OperationPayloadError,
   ScopedTokenError,
+  ScopedTokenUnavailableError,
   ServerClientError,
+  continueRun,
   createCallbackClient,
   createEventsClient,
+  createScopedTokenVerifier,
   createServerClient,
   isFoirEventCursorExpired,
   isFoirForbidden,
@@ -1101,6 +1528,7 @@ export {
   isFoirUnauthenticated,
   parseContextHeader,
   parseSubject,
+  readDispatch,
   recordsReadModels,
   recordsWriteModels,
   requireScopedToken,