@volter/twin-standard 1.0.30 → 1.0.32

package/dist/src/clients/upstash.js

@@ -0,0 +1,143 @@
+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(c, run) {
+    const held = globalThis.fetch;
+    globalThis.fetch = c.fetch;
+    try {
+        return await run();
+    }
+    finally {
+        globalThis.fetch = held;
+    }
+}
+/** A client as Dub's lib/upstash/redis.ts makes one: `new Redis({ url, token })`. */
+async function redis(c) {
+    const { Redis } = (await import('@upstash/redis'));
+    return new Redis({ url: c.env.UPSTASH_REDIS_REST_URL, token: c.env.UPSTASH_REDIS_REST_TOKEN });
+}
+export const cases = [
+    {
+        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 = [];
+                    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('link:go.trailmark.io:pricing'), r.hgetall('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.name}: ${e.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'));
+                    const limiter = new Ratelimit({ redis: await redis(c), limiter: Ratelimit.slidingWindow(3, '10 s'), analytics: true, prefix: 'dub', timeout: 1000 });
+                    const seen = [];
+                    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.name}: ${e.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'));
+                    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 = [];
+                    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.name}: ${e.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'));
+                    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;
+                    for (let i = 0; i < 20 && !delivery; i += 1) {
+                        const seen = (await (await c.fetch(`${QSTASH_URL}/_twin/deliveries?to=${encodeURIComponent(url)}`)).json());
+                        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) => 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.name}: ${e.message}`];
+            }
+        },
+    },
+];

package/dist/src/clients/volteridentity.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/volteridentity.js

@@ -0,0 +1,128 @@
+// @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';
+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';
+const issuer = (c) => `https://${c.host}`;
+async function send(c, path, body, headers = {}) {
+    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, name, shared = false) {
+    const email = `${name}@sdk.example.test`;
+    const person = await (await send(c, '/_twin/users', { email, name })).json();
+    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();
+    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()
+        : 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();
+    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();
+    return { tokens, client: registered.client_id, subject: person.id };
+}
+async function withTransport(c, run) {
+    const previous = globalThis.fetch;
+    globalThis.fetch = c.fetch;
+    try {
+        return await run();
+    }
+    finally {
+        globalThis.fetch = previous;
+    }
+}
+export const cases = [
+    {
+        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) => { requests++; return c.fetch(...args); });
+            const first = await resolveIdentity(`${issuer(c)}/`, { fresh: true, fetch: transport });
+            const cached = await resolveIdentity(issuer(c), { fetch: transport });
+            const failures = [];
+            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 });
+                }
+            });
+        },
+    },
+];

package/dist/src/clients/xai.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/xai.js

@@ -0,0 +1,23 @@
+import { chatCases, openaiClient } from "./openai-compatible.js";
+const XAI = { key: 'XAI_API_KEY', base: (host) => `https://${host}/v1`, model: 'grok-4.7' };
+export const cases = [
+    ...chatCases(XAI),
+    {
+        id: 'responses-reasoning-stream',
+        asks: "a reasoning turn streamed through the SDK's Responses stream completes with its reasoning item and its message",
+        source: 'https://developers.openai.com/api/reference/resources/responses/streaming-events "response.reasoning_summary_part.added"',
+        async run(c) {
+            c.scenario({ handlers: [{ id: 'reasons', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words', reasoning: 'thinking it through' } }] });
+            const client = await openaiClient(c, XAI);
+            try {
+                const stream = client.responses.stream({ model: XAI.model, input: 'hello', reasoning: { summary: 'auto' } });
+                for await (const _event of stream) { /* the accumulator reads each */ }
+                const types = (await stream.finalResponse()).output.map((o) => o.type);
+                return types.includes('reasoning') && types.includes('message') ? [] : [`the streamed response's output is ${JSON.stringify(types)}`];
+            }
+            catch (e) {
+                return [`the SDK's Responses stream failed: ${e.message}`];
+            }
+        },
+    },
+];

package/dist/src/conformance.d.ts

@@ -0,0 +1,33 @@
+export type ConformanceResult = {
+    id: string;
+    asks: string;
+    failures: string[];
+    note?: string;
+};
+/** The files conformance reads from a unit: its manifest, its spec's record, its vendor's life and its decision table
+ *  (a lane's journeys are its own `journeys/` or else its vendor's). A release publishes each (published()), and a
+ *  pack's standing counts it in the form only when every unit holds them (twin-world's scripts/pack-standing.ts, by
+ *  unitFilesMissing): the one list of both. */
+export declare const UNIT_FILES: readonly ["src/manifest.ts", "spec/SOURCE.md", "journeys/customer-life.json", "journeys/decisions.json"];
+/** The published package must carry every conformance input its units hold, including lanes. */
+export declare function unpublishedUnitFiles(unit: string): string[];
+/** Each of UNIT_FILES a unit lacks where conformance reads it: the manifest of every unit, the life at its vendor's root
+ *  (lifeServed), the spec's record and the decision table of a unit with a spec (decided()). */
+export declare function unitFilesMissing(unit: string): string[];
+type Owners = Record<string, string>;
+type Decision = {
+    operation: string;
+    mechanism: string;
+    demand?: string;
+    lane?: string;
+};
+/** The decision table read against one unit of a vendor (its own API, `''`, or a lane by name), each unit against its
+ *  own owners (a fetch's `ownersByUnit()`): a row decides the operation of the lane it names; a row naming none decides
+ *  the vendor's own API's operation of that id, or, when its own API has none, the one lane's that has it. So an id two
+ *  units share is two decisions, and a lane's operation its root serves stays the lane's gap (Clerk's Backend and
+ *  Frontend APIs both name `ListOrganizationMemberships`). A demanded operation (journeys/demand.json, the vendor's
+ *  backend calls) is the unit's a row naming no lane would decide. */
+export declare function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded?: string[], doors?: string[]): string[];
+/** Every check over the pack at `dir`, in order. */
+export declare function conformance(dir: string): Promise<ConformanceResult[]>;
+export {};