@volter/twin-standard 1.0.30 → 1.0.32

package/src/clients/slack.ts

@@ -0,0 +1,98 @@
+// Slack's own clients (@slack/web-api, @slack/socket-mode), driving the slack pack as an application does: a workspace
+// made and an app installed through Slack's own pages, then the app's Socket Mode client hearing a person's message in a
+// channel its bot is in, and the app's files.uploadV2 putting a file in a thread (Volter Harness's Chat SDK adapter does
+// both, journeys/demand.json). The expectations are the event and the upload as Slack documents them.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const MESSAGE = 'https://docs.slack.dev/reference/events/message.channels';
+const UPLOADS = 'https://docs.slack.dev/messaging/working-with-files';
+/** A message event's fields as Slack documents them (its example payload, and the fields a message carries). */
+const MESSAGE_FIELDS = new Set(['type', 'subtype', 'channel', 'user', 'text', 'ts', 'event_ts', 'channel_type', 'thread_ts', 'parent_user_id', 'blocks', 'team', 'client_msg_id', 'bot_id', 'app_id', 'bot_profile', 'attachments', 'files', 'edited', 'username', 'icons', 'upload', 'display_as_bot']);
+
+type Installed = { channel: string; botUser: string; botToken: string; appToken: string; person: string };
+
+/** A workspace, a channel, and an app with Socket Mode subscribed to the channel's messages, installed by the workspace's
+ *  owner through Slack's own pages and API, as a team sets one up. */
+async function install(c: ClientContext): Promise<Installed> {
+  const person = 'xoxp-UMAYA';
+  const call = async (url: string, body: unknown, token?: string): Promise<Response> => c.fetch(url, { method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body) });
+  const json = async (r: Response): Promise<Record<string, any>> => (await r.json()) as Record<string, any>;
+  await call('https://slack.com/get-started', { email: 'maya@kiln.studio', name: 'Maya Okafor' }, person);
+  const channel = (await json(await call('https://slack.com/api/conversations.create', { name: 'studio' }, person))).channel?.id as string;
+  const config = /access token is (xoxe\.xoxp-[A-Za-z0-9-]+)/.exec(await (await call('https://api.slack.com/apps', { team: 'T-twin' }, person)).text())?.[1];
+  if (!channel || !config) throw new Error(`the workspace or its app configuration token was not made (channel ${channel}, token ${config})`);
+  const app = await json(await call('https://slack.com/api/apps.manifest.create', { manifest: {
+    display_information: { name: 'Conformance Bot' },
+    features: { bot_user: { display_name: 'conformance_bot' } },
+    oauth_config: { redirect_urls: ['https://bot.example.com/slack/oauth'], scopes: { bot: ['chat:write', 'channels:history', 'files:write'] } },
+    settings: { socket_mode_enabled: true, event_subscriptions: { bot_events: ['message.channels'] } },
+  } }, config));
+  if (!app.ok) throw new Error(`apps.manifest.create: ${JSON.stringify(app).slice(0, 160)}`);
+  const allowed = await call('https://slack.com/oauth/v2/authorize', { client_id: app.credentials.client_id, scope: 'chat:write,channels:history,files:write', redirect_uri: 'https://bot.example.com/slack/oauth', state: 'conform', answer: 'allow' }, person);
+  const code = new URL(allowed.headers.get('location') ?? 'http://x/').searchParams.get('code');
+  if (!code) throw new Error(`the install was not allowed (${allowed.status})`);
+  const access = await json(await call('https://slack.com/api/oauth.v2.access', { client_id: app.credentials.client_id, client_secret: app.credentials.client_secret, code, redirect_uri: 'https://bot.example.com/slack/oauth' }));
+  const appToken = /The token is (xapp-[A-Za-z0-9-]+)/.exec(await (await call(`https://api.slack.com/apps/${app.app_id}/app-level-tokens`, { name: 'conformance', scopes: 'connections:write' }, person)).text())?.[1];
+  if (!access.ok || !appToken) throw new Error(`the bot or app-level token was not issued (${JSON.stringify(access).slice(0, 120)})`);
+  await call('https://slack.com/api/conversations.invite', { channel, users: access.bot_user_id }, person);
+  return { channel, botUser: String(access.bot_user_id), botToken: String(access.access_token), appToken, person };
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'socket-mode-message',
+    asks: "an app's Socket Mode client hears a person's message in its bot's channel as Slack documents the event, with nothing else in it",
+    source: `${MESSAGE} "The semantics for this event"`,
+    async run(c) {
+      const installed = await install(c);
+      const { SocketModeClient } = await import('@slack/socket-mode');
+      const { WebClient, LogLevel } = await import('@slack/web-api');
+      const socket = new SocketModeClient({ appToken: installed.appToken, logLevel: LogLevel.ERROR, clientOptions: { agent: c.agent } });
+      const heard = new Promise<Record<string, unknown> | string>((resolve) => {
+        const timer = setTimeout(() => resolve('no message event in 10 s'), 10_000);
+        socket.on('message', async ({ event, ack }: { event: Record<string, unknown>; ack: () => Promise<void> }) => { await ack(); clearTimeout(timer); resolve(event); });
+      });
+      const started = await socket.start().then(() => undefined, (e: Error) => e.message);
+      if (started) return [`the Socket Mode client did not connect: ${started}`];
+      const person = new WebClient(installed.person, { agent: c.agent, logLevel: LogLevel.ERROR });
+      await person.chat.postMessage({ channel: installed.channel, text: 'The client brief is in.' });
+      const event = await heard;
+      await socket.disconnect().catch(() => undefined);
+      if (typeof event === 'string') return [event];
+      const out: string[] = [];
+      for (const k of ['type', 'channel', 'user', 'text', 'ts', 'event_ts', 'channel_type']) if (event[k] === undefined) out.push(`the event carries no ${k}, which Slack's payload has`);
+      for (const k of Object.keys(event)) if (!MESSAGE_FIELDS.has(k)) out.push(`the event carries ${k}, which no Slack message event has`);
+      if (event.text !== 'The client brief is in.') out.push(`the event's text is ${JSON.stringify(event.text)}`);
+      return out;
+    },
+  },
+  {
+    id: 'files-upload-v2',
+    asks: "an app's files.uploadV2 sends a file's bytes to the upload URL Slack answers and completes the upload into a thread, where the file reads back with its size",
+    source: `${UPLOADS} "Post the contents of your file to the URL returned by the files.getUploadURLExternal API method"`,
+    async run(c) {
+      const installed = await install(c);
+      const { WebClient, LogLevel } = await import('@slack/web-api');
+      const bot = new WebClient(installed.botToken, { agent: c.agent, logLevel: LogLevel.ERROR });
+      const root = await bot.chat.postMessage({ channel: installed.channel, text: 'Render finished' });
+      if (!root.ts) return [`the thread's first message was not posted: ${JSON.stringify(root).slice(0, 160)}`];
+      const bytes = Buffer.from('frame,seconds\n1,0.42\n2,0.40\n');
+      let uploaded: Record<string, any>;
+      try {
+        // as the Chat SDK's Slack adapter calls it: the files in file_uploads, the thread's channel_id and thread_ts
+        uploaded = await bot.files.uploadV2({ channel_id: installed.channel, thread_ts: root.ts, file_uploads: [{ file: bytes, filename: 'timings.csv' }] }) as Record<string, any>;
+      } catch (e) { return [`files.uploadV2 failed: ${(e as Error).message}`]; }
+      const id = uploaded.files?.[0]?.files?.[0]?.id as string | undefined;
+      if (!uploaded.ok || !id) return [`files.uploadV2 answered no file: ${JSON.stringify(uploaded).slice(0, 200)}`];
+      const replies = await bot.conversations.replies({ channel: installed.channel, ts: root.ts });
+      const shared = (replies.messages ?? []).flatMap((m) => (m.files ?? []).map((f) => ({ f, thread: m.thread_ts }))).find((x) => x.f.id === id);
+      const out: string[] = [];
+      if (!shared) out.push(`the thread holds no message carrying file ${id}`);
+      else {
+        if (shared.thread !== root.ts) out.push(`the file's message is in thread ${String(shared.thread)}, not ${root.ts}`);
+        if (shared.f.size !== bytes.length) out.push(`the file's size is ${String(shared.f.size)}, not the ${bytes.length} bytes sent`);
+      }
+      return out;
+    },
+  },
+];

package/src/clients/stripe.ts

@@ -0,0 +1,129 @@
+// Stripe's own client (stripe-node), driving the stripe pack as its applications do (Cal.com, Dub, Postiz, Rallly and
+// Twenty call it): an endpoint registered through the API and the event Stripe sends it verified by constructEvent, as an
+// application's webhook handler verifies it; a customer list read page by page by the client's auto-pagination; a retry
+// sent with its idempotency key; the error a missing object raises; and the customer portal a billing page opens.
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const SIGNATURE = 'https://docs.stripe.com/webhooks/signature';
+const EVENT = 'https://docs.stripe.com/api/events/object';
+const PAGINATION = 'https://docs.stripe.com/api/pagination/auto';
+const IDEMPOTENCY = 'https://docs.stripe.com/api/idempotent_requests';
+const ERRORS = 'https://docs.stripe.com/api/errors/handling';
+const PORTAL = 'https://docs.stripe.com/api/customer_portal/sessions/object';
+
+const failed = (what: string) => (e: unknown): Error => new Error(`${what} failed: ${(e as Error).name}: ${(e as Error).message}`);
+
+async function stripe(c: ClientContext) {
+  const { default: Stripe } = await import('stripe');
+  return new Stripe(c.env.STRIPE_SECRET_KEY ?? '', { httpAgent: c.agent, maxNetworkRetries: 0, timeout: 10_000 });
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'webhook-event-verified',
+    asks: "the event Stripe sends an endpoint is verified by its secret, and its data.object is the customer as the API answers it",
+    source: `${SIGNATURE} "use the Stripe-Signature header and call the constructEvent() function"; ${EVENT} "Object containing the API resource relevant to the event."`,
+    async run(c) {
+      // the application's endpoint: a server of this process, as an application's own
+      const received: Array<{ body: string; signature: string }> = [];
+      const receiver = createServer((req, res) => {
+        let body = '';
+        req.on('data', (d: Buffer) => { body += d; });
+        req.on('end', () => { received.push({ body, signature: String(req.headers['stripe-signature'] ?? '') }); res.end('{}'); });
+      });
+      await new Promise<void>((r) => receiver.listen(0, '127.0.0.1', () => r()));
+      const port = (receiver.address() as AddressInfo).port;
+      try {
+        const client = await stripe(c);
+        const endpoint = await client.webhookEndpoints.create({ url: `http://127.0.0.1:${port}/stripe`, enabled_events: ['customer.created'] });
+        const customer = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' });
+        for (let i = 0; i < 50 && !received.length; i++) await new Promise((r) => setTimeout(r, 100));
+        const delivery = received[0];
+        if (!delivery) return ['no event reached the endpoint in 5 s'];
+        let event;
+        try { event = client.webhooks.constructEvent(delivery.body, delivery.signature, String(endpoint.secret)); } catch (e) { return [`constructEvent refused the delivery: ${(e as Error).message}`]; }
+        const out: string[] = [];
+        if (event.type !== 'customer.created') out.push(`the event is ${event.type}`);
+        const object = event.data.object as unknown as Record<string, unknown>;
+        if (object.id !== customer.id) out.push(`data.object is ${String(object.id)}, not the customer made (${customer.id})`);
+        const answered = await client.customers.retrieve(customer.id) as unknown as Record<string, unknown>;
+        for (const k of Object.keys(object)) if (!(k in answered)) out.push(`data.object carries ${k}, which the API's customer does not`);
+        return out;
+      } finally { receiver.close(); }
+    },
+  },
+  {
+    id: 'customers-auto-paginated',
+    asks: 'a list read with the client\'s auto-pagination, two to a page, holds every customer of the email, newest first, across its pages',
+    source: `${PAGINATION} "This feature allows you to easily iterate through large lists of resources without having to manually perform the requests to fetch subsequent pages."`,
+    async run(c) {
+      try {
+        const client = await stripe(c);
+        const made: string[] = [];
+        for (const name of ['Ada Lovelace', 'Grace Hopper', 'Katherine Johnson']) {
+          made.push((await client.customers.create({ email: 'team@analytical.example', name }).catch((e: unknown) => { throw failed('customers.create')(e); })).id);
+        }
+        const listed = await client.customers.list({ email: 'team@analytical.example', limit: 2 }).autoPagingToArray({ limit: 10 }).catch((e: unknown) => { throw failed('customers.list auto-pagination')(e); });
+        const ids = listed.map((x) => x.id);
+        const expected = [...made].reverse();
+        return ids.join(',') === expected.join(',') ? [] : [`auto-pagination read ${ids.join(', ') || 'nothing'}, not the three customers newest first (${expected.join(', ')})`];
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'idempotent-retry',
+    asks: 'a create retried with its idempotency key answers the first create\'s customer, and the key sent with other parameters is refused',
+    source: `${IDEMPOTENCY} "Subsequent requests with the same key return the same result"; ${IDEMPOTENCY} "The idempotency layer compares incoming parameters to those of the original request and errors if they’re not the same to prevent accidental misuse."`,
+    async run(c) {
+      try {
+        const client = await stripe(c);
+        const key = 'client-case-signup-ada';
+        const first = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' }, { idempotencyKey: key }).catch((e: unknown) => { throw failed('customers.create')(e); });
+        const retried = await client.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' }, { idempotencyKey: key }).catch((e: unknown) => { throw failed('customers.create, retried')(e); });
+        const out: string[] = [];
+        if (retried.id !== first.id) out.push(`the retry made ${retried.id}, not the first create's ${first.id}`);
+        const misuse = await client.customers.create({ email: 'grace@example.com', name: 'Grace Hopper' }, { idempotencyKey: key }).then(() => undefined, (e: unknown) => e as { type?: string; statusCode?: number });
+        if (!misuse) out.push('the key sent with other parameters made a customer');
+        else if (misuse.type !== 'StripeIdempotencyError') out.push(`the key sent with other parameters raised ${String(misuse.type)}, not StripeIdempotencyError`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'missing-object-error',
+    asks: 'retrieving a customer that does not exist raises the client\'s invalid-request error, 404, code resource_missing',
+    source: `${ERRORS} "Our client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability."`,
+    async run(c) {
+      try {
+        const client = await stripe(c);
+        const raised = await client.customers.retrieve('cus_never_made').then(() => undefined, (e: unknown) => e as { type?: string; statusCode?: number; code?: string });
+        if (!raised) return ['retrieving a customer that does not exist answered one'];
+        const out: string[] = [];
+        if (raised.type !== 'StripeInvalidRequestError') out.push(`it raised ${String(raised.type)}, not StripeInvalidRequestError`);
+        if (raised.statusCode !== 404) out.push(`its status is ${String(raised.statusCode)}, not 404`);
+        if (raised.code !== 'resource_missing') out.push(`its code is ${String(raised.code)}, not resource_missing`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'portal-session-opens',
+    asks: 'a portal session made for a customer answers its return_url and a url on billing.stripe.com, and that url opens the customer portal',
+    source: `${PORTAL} "The short-lived URL of the session that gives customers access to the customer portal."`,
+    async run(c) {
+      try {
+        const client = await stripe(c);
+        const customer = await client.customers.create({ email: 'billing@analytical.example', name: 'Analytical Engines' }).catch((e: unknown) => { throw failed('customers.create')(e); });
+        const session = await client.billingPortal.sessions.create({ customer: customer.id, return_url: 'https://app.analytical.example/billing' }).catch((e: unknown) => { throw failed('billingPortal.sessions.create')(e); });
+        const out: string[] = [];
+        if (session.return_url !== 'https://app.analytical.example/billing') out.push(`the session's return_url is ${String(session.return_url)}`);
+        if (!session.url.startsWith('https://billing.stripe.com/')) { out.push(`the session's url is ${session.url}, not on billing.stripe.com`); return out; }
+        const page = await c.fetch(session.url);
+        if (page.status !== 200) out.push(`the portal page answered ${page.status}`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+];

package/src/clients/tinybird.ts

@@ -0,0 +1,69 @@
+// Tinybird's official API wrapper, unmodified, with the World credential and routed fetch.
+// The pinned package names Forward; its decoupled API wrapper uses the Classic /v0 APIs.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const SDK = 'https://unpkg.com/@tinybirdco/sdk@0.0.84/src/api/api.ts';
+
+async function client(c: ClientContext, fetch: typeof globalThis.fetch = c.fetch) {
+  const { createTinybirdApi } = await import('@tinybirdco/sdk/api');
+  return createTinybirdApi({ baseUrl: `https://${c.host}`, token: c.env.TINYBIRD_API_KEY ?? c.env.TINYBIRD_TOKEN ?? '', fetch });
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'request-token-override-and-typed-error',
+    asks: 'a request token override is used instead of the Workspace token, and its refusal retains the status and JSON error in TinybirdApiError',
+    source: `${SDK} "Error thrown by TinybirdApi when a response is not OK"`,
+    async run(c) {
+      const { TinybirdApiError } = await import('@tinybirdco/sdk/api');
+      const api = await client(c);
+      try {
+        await api.ingest('client_case_events', { label: 'refused' }, { token: 'throwaway-invalid-token' });
+        return ['the invalid request token was accepted'];
+      } catch (error) {
+        if (!(error instanceof TinybirdApiError)) return [`the refusal is not TinybirdApiError: ${String(error)}`];
+        const failures: string[] = [];
+        if (error.statusCode !== 403) failures.push(`the invalid token answered ${error.statusCode}, not 403`);
+        if (!error.response?.error || error.message !== error.response.error) failures.push('the vendor error message did not survive SDK decoding');
+        if (!error.responseBody || JSON.stringify(JSON.parse(error.responseBody)) !== JSON.stringify(error.response)) failures.push('the parsed error does not retain the raw vendor response');
+        return failures;
+      }
+    },
+  },
+  {
+    id: 'date-rejection-and-ndjson-batch',
+    asks: 'Date objects are refused locally, then two valid event records are serialized as NDJSON without losing quoted text or line breaks',
+    source: `${SDK} "Date values are not supported in ingest payloads."`,
+    async run(c) {
+      let calls = 0;
+      const routed = ((input: RequestInfo | URL, init?: RequestInit) => { calls++; return c.fetch(input, init); }) as typeof fetch;
+      const api = await client(c, routed);
+      try {
+        await api.ingest('client_case_events', { timestamp: new Date('2024-01-15T10:30:00Z') });
+        return ['a Date object was accepted for ingestion'];
+      } catch (error) {
+        if (!(error instanceof Error) || !error.message.includes('Date values are not supported in ingest payloads.')) return [`the Date refusal was ${String(error)}`];
+        if (calls !== 0) return ['the SDK sent a request before refusing the Date object'];
+      }
+      await api.requestJson('/v0/datasources', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ name: 'client_case_events', schema: 'label String, timestamp DateTime' }).toString() });
+      const rows = [{ label: 'a "quoted" value', timestamp: '2024-01-15 10:30:00' }, { label: 'two\nlines', timestamp: '2024-01-15 10:31:00' }];
+      const ingested = await api.ingestBatch('client_case_events', rows, { wait: true });
+      const result = await api.sql('SELECT label, timestamp FROM client_case_events ORDER BY timestamp');
+      return ingested.successful_rows === 2 && ingested.quarantined_rows === 0 && JSON.stringify(result.data) === JSON.stringify(rows)
+        ? [] : [`NDJSON batch/read-back differs: ${JSON.stringify({ ingested, rows: result.data })}`];
+    },
+  },
+  {
+    id: 'json-query-parameter-serialization',
+    asks: 'an object query parameter becomes JSON and the Endpoint uses its value rather than the object string representation',
+    source: `${SDK} "Plain objects (e.g. p.json() params) become JSON strings; Dates are rejected;"`,
+    async run(c) {
+      const api = await client(c);
+      await api.requestJson('/v0/datasources', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ name: 'client_json_rows', schema: 'name String' }).toString() });
+      await api.ingestBatch('client_json_rows', [{ name: 'selected' }, { name: 'excluded' }], { wait: true });
+      await api.requestJson('/v0/pipes', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: 'client_json_filter', nodes: [{ name: 'endpoint', type: 'endpoint', sql: "%\nSELECT name FROM client_json_rows WHERE name = {{JSON(filters, '{\"name\":\"selected\"}').get('name')}}" }] }) });
+      const result = await api.query('client_json_filter', { filters: { name: 'excluded' } });
+      return JSON.stringify(result.data) === JSON.stringify([{ name: 'excluded' }]) ? [] : [`the JSON parameter selected ${JSON.stringify(result.data)}`];
+    },
+  },
+];

package/src/clients/tunnel.ts

@@ -0,0 +1,79 @@
+// The relay's unmodified client forwards a local application's HTTP responses through the control socket.
+// Expectations are the pinned protocol and relay reference, never the pack author's scripted frames.
+import { Agent } from 'node:https';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { ClientCase } from './harness.ts';
+
+export const cases: ClientCase[] = [{
+  id: 'local-http-relay',
+  asks: 'createTunnel preserves visitor method/body/public host and streams local responses, including HEAD, 204 and 304',
+  source: 'https://github.com/volter-ai/volter-tunnel/blob/c14b6e36722b20cbb3ee7245c7f555b5c12b376e/packages/core/src/protocol.ts "An inbound HTTP request to forward to the local server."',
+  async run(c) {
+    const failures: string[] = [];
+    const local = createServer(async (request, response) => {
+      const chunks: Buffer[] = [];
+      for await (const chunk of request) chunks.push(Buffer.from(chunk));
+      const path = request.url ?? '';
+      if (path === '/empty') { response.writeHead(204); response.end(); return; }
+      if (path === '/cached') { response.writeHead(304); response.end(); return; }
+      if (request.method === 'HEAD') { response.writeHead(200, { 'x-local-head': 'present' }); response.end(); return; }
+      response.writeHead(200, { 'content-type': 'application/json', 'x-frame-options': 'DENY', 'content-security-policy': "default-src 'self'; frame-ancestors 'none'" });
+      response.write(JSON.stringify({ method: request.method, path, host: request.headers['x-forwarded-host'], appHeader: request.headers['x-volter-app'], body: Buffer.concat(chunks).toString() }));
+      response.end();
+    });
+    await new Promise<void>((resolve) => local.listen(0, '127.0.0.1', resolve));
+    // The SDK owns its HTTPS agent. Route that agent's TCP connection as a World's injector does,
+    // retaining its secure relay URL and Host; local-origin connections retain their ordinary agent.
+    const original = Agent.prototype.createConnection;
+    Agent.prototype.createConnection = function (options: any, callback: any): any {
+      if ((options.hostname ?? options.host) === c.host) return c.connect();
+      return original.call(this, options, callback);
+    };
+    let tunnel: { url: string; close(): void } | undefined;
+    try {
+      const { createTunnel } = await import('@volter/tunnel/client');
+      tunnel = await createTunnel({ host: `https://${c.host}`, port: (local.address() as AddressInfo).port,
+        tunnelId: 'conform-harness', secret: c.env.TUNNEL_SECRET, authRequired: false,
+        logger: { info() {}, warn() {}, debug() {} },
+      });
+      if (tunnel.url !== 'https://conform-harness.voltertest.xyz') failures.push('registered URL differs from the requested tunnel');
+      const answer = await c.fetch(`${tunnel.url}/command?view=demo`, { method: 'POST',
+        headers: { 'content-type': 'text/plain', 'x-volter-app': 'custom', origin: 'https://viewer.example' }, body: 'run demo' });
+      const body = await answer.json() as Record<string, unknown>;
+      for (const [key, expected] of Object.entries({ method: 'POST', path: '/command?view=demo', host: 'conform-harness.voltertest.xyz', appHeader: 'custom', body: 'run demo' })) {
+        if (body[key] !== expected) failures.push(`local request ${key}: ${JSON.stringify(body[key])}`);
+      }
+      // Node fetch injection rewrites the URL to the listener and carries the original vendor host.
+      const injected = await c.fetch('http://127.0.0.1/injected', { headers: {
+        'x-volter-twin-original-host': 'conform-harness.voltertest.xyz', 'x-volter-app': 'injected',
+      } });
+      if (injected.status !== 200) failures.push('World-injected visitor did not reach its registered tunnel');
+      else {
+        const body = await injected.json() as Record<string, unknown>;
+        if (body.host !== 'conform-harness.voltertest.xyz' || body.path !== '/injected' || body.appHeader !== 'injected') {
+          failures.push('World-injected visitor lost its public host or application headers');
+        }
+      }
+      if (answer.headers.get('access-control-allow-origin') !== 'https://viewer.example') failures.push('CORS origin not reflected');
+      if (answer.headers.has('x-frame-options') || answer.headers.get('content-security-policy')?.includes('frame-ancestors')) failures.push('embedding restrictions not stripped');
+      if (answer.headers.get('cache-control') !== 'private, no-store, max-age=0') failures.push('dynamic response cache policy missing');
+      for (const [path, method, status] of [['/empty', 'GET', 204], ['/cached', 'GET', 304], ['/head', 'HEAD', 200]] as const) {
+        const response = await c.fetch(`${tunnel.url}${path}`, { method });
+        if (response.status !== status || (await response.text()) !== '') failures.push(`${method} ${path} is not bodyless ${status}`);
+      }
+      const preflight = await c.fetch(`${tunnel.url}/command`, { method: 'OPTIONS', headers: {
+        origin: 'https://viewer.example', 'access-control-request-headers': 'X-Demo',
+      } });
+      if (preflight.status !== 204 || preflight.headers.get('access-control-allow-headers') !== 'X-Demo') failures.push('preflight does not reflect requested headers');
+      const tooLarge = await c.fetch(`${tunnel.url}/upload`, { method: 'POST', body: 'x'.repeat(750_001) });
+      if (tooLarge.status !== 413) failures.push('oversized request was forwarded');
+    } finally {
+      tunnel?.close();
+      Agent.prototype.createConnection = original;
+      local.closeAllConnections();
+      await new Promise<void>((resolve) => local.close(() => resolve()));
+    }
+    return failures;
+  },
+}];

package/src/clients/upstash.ts

@@ -0,0 +1,137 @@
+// Upstash's own clients, at the versions Dub pins (@upstash/redis 1.38.2, @upstash/ratelimit 2.0.6, @upstash/qstash
+// 2.11.0), driving the upstash pack as Dub does, with the credentials the pack's credential door issued
+// (UPSTASH_REDIS_REST_URL and _TOKEN, QSTASH_TOKEN and the two signing keys): the Redis client auto-pipelines the commands
+// it is given and decodes base64 answers into the values it was given; the rate limiter runs its sliding window's script
+// by SHA, then by EVAL, and refuses past its limit; QStash's client publishes, a duplicate deduplication id answering the
+// first message, and each delivery carries a signature its Receiver verifies with the account's signing keys.
+//
+// The clients take no fetch of their own: they call the global one, which a World's injector routes, so each case routes
+// it as the World does while it runs.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const AUTO_PIPELINE = 'https://upstash.com/docs/redis/sdks/ts/pipelining/auto-pipeline';
+const ALGORITHMS = 'https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms';
+const SIGNATURE = 'https://upstash.com/docs/qstash/howto/signature';
+const DEDUPLICATION = 'https://upstash.com/docs/qstash/features/deduplication';
+/** The QStash the credential door opens is in eu-central-1, whose URL is qstash.upstash.io (the pack's api lane). */
+const QSTASH_URL = 'https://qstash.upstash.io';
+
+async function routed<T>(c: ClientContext, run: () => Promise<T>): Promise<T> {
+  const held = globalThis.fetch;
+  globalThis.fetch = c.fetch;
+  try { return await run(); } finally { globalThis.fetch = held; }
+}
+
+type Redis = {
+  set: (key: string, value: unknown, opts?: Record<string, unknown>) => Promise<unknown>;
+  get: <T>(key: string) => Promise<T | null>;
+  incr: (key: string) => Promise<number>;
+  hset: (key: string, fields: Record<string, unknown>) => Promise<number>;
+  hgetall: <T>(key: string) => Promise<T | null>;
+};
+
+/** A client as Dub's lib/upstash/redis.ts makes one: `new Redis({ url, token })`. */
+async function redis(c: ClientContext): Promise<Redis> {
+  const { Redis } = (await import('@upstash/redis')) as unknown as { Redis: new (config: { url: string; token: string }) => Redis };
+  return new Redis({ url: c.env.UPSTASH_REDIS_REST_URL!, token: c.env.UPSTASH_REDIS_REST_TOKEN! });
+}
+
+type Publish = { messageId: string; deduplicated?: boolean };
+type QStash = { publishJSON: (request: Record<string, unknown>) => Promise<Publish> };
+type Receiver = new (keys: { currentSigningKey: string; nextSigningKey: string }) => { verify: (r: { signature: string; body: string; url?: string }) => Promise<boolean> };
+export const cases: ClientCase[] = [
+  {
+    id: 'redis-auto-pipeline',
+    asks: 'commands given at once are sent as one pipeline and each answers its own value, decoded from base64 into what was given: an object set is read back as that object, a counter as a number, a hash as an object',
+    source: `${AUTO_PIPELINE} "Auto pipelining allows you to use the Redis client as usual"; ${AUTO_PIPELINE} "the client will accumulate commands in a pipeline"`,
+    async run(c) {
+      if (!c.env.UPSTASH_REDIS_REST_URL || !c.env.UPSTASH_REDIS_REST_TOKEN) return ['the credential door issued no UPSTASH_REDIS_REST_URL and token'];
+      try {
+        return await routed(c, async () => {
+          const r = await redis(c);
+          const link = { url: 'https://trailmark.io/pricing', clicks: 0, tags: ['launch'] };
+          const [set, count, fields] = await Promise.all([r.set('link:go.trailmark.io:pricing', link, { ex: 3600 }), r.incr('clicks:pricing'), r.hset('checkout:cs_1', { amount: 4900, currency: 'usd' })]);
+          const out: string[] = [];
+          if (set !== 'OK') out.push(`SET answered ${JSON.stringify(set)}, not OK`);
+          if (count !== 1) out.push(`INCR answered ${JSON.stringify(count)}, not 1`);
+          if (fields !== 2) out.push(`HSET answered ${JSON.stringify(fields)}, not 2`);
+          const [read, hash] = await Promise.all([r.get<typeof link>('link:go.trailmark.io:pricing'), r.hgetall<Record<string, unknown>>('checkout:cs_1')]);
+          if (JSON.stringify(read) !== JSON.stringify(link)) out.push(`the link read back as ${JSON.stringify(read)}`);
+          if (JSON.stringify(hash) !== JSON.stringify({ amount: 4900, currency: 'usd' })) out.push(`the hash read back as ${JSON.stringify(hash)}`);
+          return out;
+        });
+      } catch (e) { return [`the client's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'ratelimit-sliding-window',
+    asks: "a sliding window of 3 requests per 10 seconds, as Dub's ratelimit() makes one (prefix dub, analytics on), allows three requests and rejects the fourth; its script is run by SHA, and by EVAL when the database does not hold it",
+    source: `${ALGORITHMS} "the request is rejected"; ${ALGORITHMS} "Create a new ratelimiter, that allows 10 requests per 10 seconds."`,
+    async run(c) {
+      if (!c.env.UPSTASH_REDIS_REST_URL || !c.env.UPSTASH_REDIS_REST_TOKEN) return ['the credential door issued no UPSTASH_REDIS_REST_URL and token'];
+      try {
+        return await routed(c, async () => {
+          const { Ratelimit } = (await import('@upstash/ratelimit')) as unknown as { Ratelimit: { new (config: Record<string, unknown>): { limit: (id: string) => Promise<{ success: boolean; remaining: number; pending: Promise<unknown> }> }; slidingWindow: (tokens: number, window: string) => unknown } };
+          const limiter = new Ratelimit({ redis: await redis(c), limiter: Ratelimit.slidingWindow(3, '10 s'), analytics: true, prefix: 'dub', timeout: 1000 });
+          const seen: boolean[] = [];
+          for (let i = 0; i < 4; i += 1) {
+            const res = await limiter.limit('unsplash:203.0.113.7');
+            await res.pending;
+            seen.push(res.success);
+          }
+          return JSON.stringify(seen) === JSON.stringify([true, true, true, false]) ? [] : [`four requests in the window answered ${JSON.stringify(seen)}, not three allowed and the fourth rejected`];
+        });
+      } catch (e) { return [`the limiter's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'qstash-deduplicated-publish',
+    asks: 'a message published again with the same deduplication id is accepted and answers the existing message\'s id',
+    source: `${DEDUPLICATION} "we will accept the request and return the messageID of the existing message"`,
+    async run(c) {
+      if (!c.env.QSTASH_TOKEN) return ['the credential door issued no QSTASH_TOKEN'];
+      try {
+        return await routed(c, async () => {
+          const { Client } = (await import('@upstash/qstash')) as unknown as { Client: new (config: { baseUrl: string; token: string }) => QStash };
+          const client = new Client({ baseUrl: QSTASH_URL, token: c.env.QSTASH_TOKEN! });
+          const request = { url: 'https://app.trailmark.io/api/cron/payouts/send-stripe-payout', body: { payoutId: 'po_1' }, deduplicationId: 'po_1', delay: 3600 };
+          const first = await client.publishJSON(request);
+          const again = await client.publishJSON(request);
+          const out: string[] = [];
+          if (!first.messageId) out.push('the first publish answered no messageId');
+          if (again.messageId !== first.messageId) out.push(`the duplicate answered ${JSON.stringify(again.messageId)}, not the first message's ${JSON.stringify(first.messageId)}`);
+          return out;
+        });
+      } catch (e) { return [`the client's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'qstash-signed-delivery',
+    asks: "a published message's delivery carries Upstash-Signature, a JWT the Receiver verifies with the account's current and next signing keys against the body and the destination",
+    source: `${SIGNATURE} "We send a JWT with each request. This JWT is signed by your individual secret signing key and sent in the Upstash-Signature HTTP header."`,
+    async run(c) {
+      if (!c.env.QSTASH_TOKEN || !c.env.QSTASH_CURRENT_SIGNING_KEY || !c.env.QSTASH_NEXT_SIGNING_KEY) return ['the credential door issued no QSTASH_TOKEN and signing keys'];
+      try {
+        return await routed(c, async () => {
+          const { Client, Receiver } = (await import('@upstash/qstash')) as unknown as { Client: new (config: { baseUrl: string; token: string }) => QStash; Receiver: Receiver };
+          const client = new Client({ baseUrl: QSTASH_URL, token: c.env.QSTASH_TOKEN! });
+          const url = 'https://app.trailmark.io/api/jobs/process/welcome-user-job';
+          await client.publishJSON({ url, body: { name: 'welcome-user-job', userId: 'user_1' } });
+          // the World's stand-in for the destination: what QStash sent there (the pack's deliveries door)
+          let delivery: { headers: Record<string, string>; body: string } | undefined;
+          for (let i = 0; i < 20 && !delivery; i += 1) {
+            const seen = (await (await c.fetch(`${QSTASH_URL}/_twin/deliveries?to=${encodeURIComponent(url)}`)).json()) as { deliveries?: Array<{ headers: Record<string, string>; body: string }> };
+            delivery = seen.deliveries?.[0];
+            if (!delivery) await new Promise((r) => setTimeout(r, 100));
+          }
+          if (!delivery) return ['QStash made no delivery of the message'];
+          const signature = delivery.headers['upstash-signature'];
+          if (!signature) return ['the delivery carries no Upstash-Signature'];
+          const receiver = new Receiver({ currentSigningKey: c.env.QSTASH_CURRENT_SIGNING_KEY!, nextSigningKey: c.env.QSTASH_NEXT_SIGNING_KEY! });
+          const valid = await receiver.verify({ signature, body: delivery.body, url }).catch((e: Error) => e);
+          return valid === true ? [] : [`the Receiver refused the delivery's signature: ${valid instanceof Error ? valid.message : String(valid)}`];
+        });
+      } catch (e) { return [`the client's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+];

package/src/clients/volteridentity.ts

@@ -0,0 +1,108 @@
+// @volter/identity 0.4.1, as Volter Harness uses it; discovery and token verification are also the APIs Open Autonomy
+// uses in 0.1.0. These cases are owned by conformance and are not run during pack authoring.
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { digest } from '@volter/world-core';
+import { resolveIdentity, verifyIdentityToken, tokenFor, readSharedSignIn, SHARED_CLIENTS } from '@volter/identity';
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const INDEX = 'https://unpkg.com/@volter/identity@0.4.1/dist/index.js';
+const SHARED = 'https://unpkg.com/@volter/identity@0.4.1/dist/shared.js';
+type Row = Record<string, any>;
+const issuer = (c: ClientContext) => `https://${c.host}`;
+async function send(c: ClientContext, path: string, body?: unknown, headers: Record<string, string> = {}): Promise<Response> {
+  const response = await c.fetch(`${issuer(c)}${path}`, {
+    method: body === undefined ? 'GET' : 'POST', redirect: 'manual',
+    headers: { 'content-type': typeof body === 'string' ? 'application/x-www-form-urlencoded' : 'application/json', ...headers },
+    ...(body === undefined ? {} : { body: typeof body === 'string' ? body : JSON.stringify(body) }),
+  });
+  if (response.status >= 400) throw new Error(`${path}: ${response.status} ${await response.text()}`);
+  return response;
+}
+async function setup(c: ClientContext, name: string, shared = false): Promise<{ tokens: Row; client: string; subject: string }> {
+  const email = `${name}@sdk.example.test`;
+  const person = await (await send(c, '/_twin/users', { email, name })).json() as Row;
+  const login = await send(c, '/login', `email=${encodeURIComponent(email)}&authorize=`);
+  const cookie = login.headers.get('set-cookie')!.split(';')[0]!;
+  const admin = await (await send(c, '/_twin/app-credentials', {})).json() as Row;
+  const operator = { cookie, authorization: `Bearer ${admin.admin_token}` };
+  const callback = 'http://127.0.0.1:53716/callback';
+  const registered = shared
+    ? await (await send(c, '/_twin/shared-client', {})).json() as Row
+    : await (await send(c, '/admin/clients', { client_name: name, redirect_uris: [callback], application_type: 'native', token_endpoint_auth_method: 'client_secret_post', grant_types: ['authorization_code', 'refresh_token'], skip_consent: true }, operator)).json() as Row;
+  if (shared) {
+    await send(c, '/admin/resources', { identifier: 'https://teams.sdk.example', name: 'SDK Teams server' }, operator);
+    await send(c, `/admin/clients/${registered.client_id}/resources`, { resource: 'https://teams.sdk.example' }, operator);
+  }
+  const verifier = 'official-sdk-case-verifier-with-enough-entropy-for-s256';
+  const query = new URLSearchParams({ client_id: registered.client_id, redirect_uri: callback, response_type: 'code', scope: 'openid profile email offline_access', code_challenge: digest('sha256', verifier, 'base64url'), code_challenge_method: 'S256' });
+  const authorized = await send(c, `/api/auth/oauth2/authorize?${query}`, undefined, { cookie });
+  const code = new URL(authorized.headers.get('location')!).searchParams.get('code')!;
+  const form = new URLSearchParams({ client_id: registered.client_id, redirect_uri: callback, grant_type: 'authorization_code', code, code_verifier: verifier, ...(registered.client_secret ? { client_secret: registered.client_secret } : {}) });
+  const tokens = await (await send(c, '/api/auth/oauth2/token', form.toString())).json() as Row;
+  return { tokens, client: registered.client_id, subject: person.id };
+}
+async function withTransport<T>(c: ClientContext, run: () => Promise<T>): Promise<T> {
+  const previous = globalThis.fetch;
+  globalThis.fetch = c.fetch;
+  try { return await run(); } finally { globalThis.fetch = previous; }
+}
+export const cases: ClientCase[] = [
+  {
+    id: 'discovery-cache-and-fresh',
+    asks: 'resolveIdentity normalizes the issuer, caches discovery and refreshes when fresh is requested',
+    source: `${INDEX} "The answer is cached per issuer"`,
+    async run(c) {
+      let requests = 0;
+      const transport = (async (...args: Parameters<typeof fetch>) => { requests++; return c.fetch(...args); }) as typeof fetch;
+      const first = await resolveIdentity(`${issuer(c)}/`, { fresh: true, fetch: transport });
+      const cached = await resolveIdentity(issuer(c), { fetch: transport });
+      const failures: string[] = [];
+      if (!first.available || !cached.available) failures.push('the SDK did not discover the twin');
+      if (first.available && first.metadata.issuer !== issuer(c)) failures.push('the SDK discovered another issuer');
+      if (requests !== 1) failures.push('a cached discovery made another request');
+      await resolveIdentity(issuer(c), { fresh: true, fetch: transport });
+      if (Number(requests) !== 2) failures.push('fresh discovery did not request metadata again');
+      return failures;
+    },
+  },
+  {
+    id: 'verify-signed-identity-and-audience',
+    asks: 'verifyIdentityToken reads the issuer keys, names the real subject and rejects another audience',
+    source: `${INDEX} "the signature, the issuer, the audience (this product's client id, or the resource it serves) and the expiry. Throws on anything else."`,
+    run(c) { return withTransport(c, async () => {
+      const issued = await setup(c, 'verified-person');
+      const who = await verifyIdentityToken(issued.tokens.id_token, { issuer: issuer(c), audience: issued.client, fetch: c.fetch });
+      const failures = who.subject === issued.subject && who.issuer === issuer(c) ? [] : ['the verified token names another subject or issuer'];
+      const wrong = await verifyIdentityToken(issued.tokens.id_token, { issuer: issuer(c), audience: 'another-client', fetch: c.fetch }).then(() => false, () => true);
+      if (!wrong) failures.push('the SDK accepted a token for another audience');
+      const tampered = await verifyIdentityToken(`${issued.tokens.id_token.slice(0, -4)}AAAA`, { issuer: issuer(c), audience: issued.client, fetch: c.fetch }).then(() => false, () => true);
+      if (!tampered) failures.push('the SDK accepted a changed signature');
+      return failures;
+    }); },
+  },
+  {
+    id: 'shared-resource-refresh-rotation',
+    asks: 'tokenFor exchanges the shared refresh for the resource, saves the rotated refresh and uses it next time',
+    source: `${SHARED} "The token is the product's alone"`,
+    run(c) { return withTransport(c, async () => {
+      const issued = await setup(c, 'shared-person', true);
+      const directory = mkdtempSync(join(tmpdir(), 'identity-sdk-case-'));
+      const path = join(directory, 'identity.json');
+      try {
+        writeFileSync(path, JSON.stringify({ issuer: issuer(c), clientId: SHARED_CLIENTS[issuer(c)], refreshToken: issued.tokens.refresh_token, savedAt: Date.now() }), { mode: 0o600 });
+        const resource = 'https://teams.sdk.example';
+        const token = await tokenFor(resource, { path });
+        if (!token) return ['the SDK obtained no resource token'];
+        const who = await verifyIdentityToken(token, { issuer: issuer(c), audience: resource, fetch: c.fetch });
+        const saved = readSharedSignIn(path)!;
+        const failures = who.subject === issued.subject ? [] : ['the resource token names another subject'];
+        if (saved.refreshToken === issued.tokens.refresh_token) failures.push('the SDK did not save the rotated refresh');
+        if (!await tokenFor(resource, { path })) failures.push('the saved refresh did not obtain the next token');
+        if (JSON.parse(readFileSync(path, 'utf8')).refreshToken === saved.refreshToken) failures.push('the second refresh did not rotate again');
+        return failures;
+      } finally { rmSync(directory, { recursive: true, force: true }); }
+    }); },
+  },
+];