@volter/twin-openai 0.1.0

package/src/openai-types.ts

@@ -0,0 +1,126 @@
+// Shared wire-shape types for the OpenAI API surface. These mirror the real vendor JSON
+// shapes (not the SDK's internal types — the twin never imports the SDK at runtime; the SDK
+// is exercised only in *.test.ts). Kept minimal but faithful.
+
+// ── Chat Completions ────────────────────────────────────────────────────────────────────
+/** A chat message param as the caller sends it (content is a string OR a content-part array). */
+export type ChatMessageParam = {
+  role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';
+  content?: string | Array<Record<string, unknown>> | null;
+  name?: string;
+  tool_calls?: ChatToolCall[];
+  tool_call_id?: string;
+};
+
+/** A function tool_call inside an assistant message (faithful shape). */
+export type ChatToolCall = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/** The chat.completion `usage` object — deterministic token counts. */
+export type ChatUsage = {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  completion_tokens_details?: { accepted_prediction_tokens: number; rejected_prediction_tokens: number };
+};
+
+/** A per-token logprob entry (faithful `choices[].logprobs.content[]` shape). */
+export type ChatLogprobToken = {
+  token: string;
+  logprob: number;
+  bytes: number[];
+  top_logprobs: Array<{ token: string; logprob: number; bytes: number[] }>;
+};
+
+/** An audio output object on an assistant message (when `modalities` includes 'audio'). The twin
+ *  can't synthesize speech, so `data` is a clearly-labeled stub base64 string; the SHAPE
+ *  (id/data/transcript/expires_at) is vendor-faithful. */
+export type ChatAudioOutput = { id: string; data: string; transcript: string; expires_at: number };
+
+export type ChatChoice = {
+  index: number;
+  message: { role: 'assistant'; content: string | null; tool_calls?: ChatToolCall[]; refusal?: null; audio?: ChatAudioOutput };
+  logprobs: { content: ChatLogprobToken[] } | null;
+  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+/** The unary chat.completion response envelope (faithful shape). */
+export type ChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: ChatChoice[];
+  usage: ChatUsage;
+  system_fingerprint: string;
+  metadata?: Record<string, unknown> | null;
+};
+
+// ── Responses API ───────────────────────────────────────────────────────────────────────
+/** A message output item (the assistant's text turn). */
+export type ResponseMessageItem = {
+  type: 'message';
+  id: string;
+  status: 'completed';
+  role: 'assistant';
+  content: Array<{ type: 'output_text'; text: string; annotations: unknown[] }>;
+};
+/** A reasoning output item (emitted for reasoning models / when `reasoning.effort` is set). The
+ *  twin can't run the model, so the reasoning `summary` is a clearly-labeled stub; the item SHAPE
+ *  (type/id/summary[]) is vendor-faithful. */
+export type ResponseReasoningItem = {
+  type: 'reasoning';
+  id: string;
+  summary: Array<{ type: 'summary_text'; text: string }>;
+};
+export type ResponseOutputItem = ResponseMessageItem | ResponseReasoningItem;
+
+/** The Responses API usage object — `output_tokens_details.reasoning_tokens` reports tokens spent
+ *  on the (stubbed) reasoning item, faithful to the vendor shape. */
+export type ResponseUsage = {
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+  output_tokens_details?: { reasoning_tokens: number };
+};
+
+/** The Responses API response envelope (faithful shape). */
+export type OpenAIResponse = {
+  id: string;
+  object: 'response';
+  created_at: number;
+  status: 'completed';
+  model: string;
+  output: ResponseOutputItem[];
+  output_text?: string;
+  usage: ResponseUsage;
+  reasoning?: { effort: string; summary: string | null };
+  previous_response_id?: string;
+};
+
+// ── Embeddings ──────────────────────────────────────────────────────────────────────────
+export type Embedding = { object: 'embedding'; index: number; embedding: number[] };
+export type EmbeddingResponse = {
+  object: 'list';
+  data: Embedding[];
+  model: string;
+  usage: { prompt_tokens: number; total_tokens: number };
+};
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/** A vendor-shaped error envelope: { error: { message, type, param, code } }. */
+export type OpenAIError = {
+  error: { message: string; type: string; param: string | null; code: string | null };
+};
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = { data?: Record<string, unknown>; done?: boolean };
+
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/src/openai-webhooks.ts

@@ -0,0 +1,128 @@
+// OpenAI webhooks — REAL HMAC-signed delivery, Standard-Webhooks scheme.
+//
+// Real OpenAI delivers asynchronous job-completion notifications (batch / fine-tuning /
+// background responses / evals) to a registered endpoint, signed with the Standard Webhooks
+// scheme (the same scheme svix popularized): the signing secret is `whsec_<base64>`, the HMAC
+// key is the base64-decoded portion, and the delivery carries `webhook-id`, `webhook-timestamp`,
+// and `webhook-signature` headers where the signature is `v1,<base64 HMAC-SHA256(key,
+// `${id}.${timestamp}.${payload}`)>`. The SDK verifies with `client.webhooks.unwrap()`. We
+// reproduce the scheme BYTE-FOR-BYTE so a real consumer (or the SDK's unwrap) verifies twin-
+// delivered webhooks unchanged — the signature is REAL, not a stub.
+//
+// `node:crypto` is required LAZILY (server-only) so this module is browser-bundle safe.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return require('node:crypto') as NodeCrypto;
+}
+
+/** The thin webhook envelope OpenAI POSTs: { object:'event', id, type, created_at, data:{id} }. */
+export type OpenAIWebhookEvent = {
+  object: 'event';
+  id: string;
+  type: string;
+  created_at: number;
+  data: { id: string; [k: string]: unknown };
+};
+
+/** Decode a `whsec_<base64>` signing secret to its raw HMAC key bytes. */
+function secretKeyBytes(secret: string): Buffer {
+  const b64 = secret.startsWith('whsec_') ? secret.slice('whsec_'.length) : secret;
+  return Buffer.from(b64, 'base64');
+}
+
+/**
+ * Compute the `webhook-signature` header value for a delivery: `v1,<base64 sig>` over
+ * `${id}.${timestamp}.${payload}` keyed by the (base64-decoded) signing secret — the Standard
+ * Webhooks scheme. A real Standard-Webhooks / svix verifier accepts this unchanged.
+ */
+export function computeOpenAIWebhookSignature(id: string, timestamp: number, payload: string, secret: string): string {
+  const key = secretKeyBytes(secret);
+  const signed = `${id}.${timestamp}.${payload}`;
+  const sig = nodeCrypto().createHmac('sha256', key).update(signed, 'utf8').digest('base64');
+  return `v1,${sig}`;
+}
+
+export class OpenAIWebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OpenAIWebhookVerificationError';
+  }
+}
+
+/**
+ * Verify a webhook payload + Standard-Webhooks headers against the signing secret and return the
+ * parsed event (mirrors the SDK's `webhooks.unwrap`). Throws on a missing/malformed header, a
+ * signature mismatch, or (when `tolerance` is given) a stale timestamp.
+ */
+export function verifyOpenAIWebhook(payload: string, headers: Record<string, string>, secret: string, opts: { tolerance?: number; now?: number } = {}): OpenAIWebhookEvent {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  const id = lower['webhook-id'];
+  const ts = Number(lower['webhook-timestamp']);
+  const sigHeader = lower['webhook-signature'];
+  if (!id || !sigHeader || !Number.isFinite(ts)) throw new OpenAIWebhookVerificationError('Missing required webhook headers (webhook-id / webhook-timestamp / webhook-signature).');
+  if (opts.tolerance !== undefined) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - ts) > opts.tolerance) throw new OpenAIWebhookVerificationError('Webhook timestamp outside tolerance.');
+  }
+  const expected = computeOpenAIWebhookSignature(id, ts, payload, secret).slice('v1,'.length);
+  const expectedBuf = Buffer.from(expected, 'utf8');
+  // The header may carry multiple space-separated `v<n>,<sig>` pairs.
+  const matched = sigHeader.split(' ').some((part) => {
+    const comma = part.indexOf(',');
+    if (comma === -1) return false;
+    const sig = part.slice(comma + 1);
+    const sigBuf = Buffer.from(sig, 'utf8');
+    return sigBuf.length === expectedBuf.length && nodeCrypto().timingSafeEqual(sigBuf, expectedBuf);
+  });
+  if (!matched) throw new OpenAIWebhookVerificationError('No matching signature found.');
+  return JSON.parse(payload) as OpenAIWebhookEvent;
+}
+
+/** The webhook event types OpenAI emits (a faithful slice of the published set). */
+export const OPENAI_WEBHOOK_EVENT_TYPES = [
+  'response.completed',
+  'response.cancelled',
+  'response.failed',
+  'response.incomplete',
+  'batch.completed',
+  'batch.cancelled',
+  'batch.expired',
+  'batch.failed',
+  'fine_tuning.job.succeeded',
+  'fine_tuning.job.cancelled',
+  'fine_tuning.job.failed',
+  'eval.run.succeeded',
+  'eval.run.canceled',
+  'eval.run.failed',
+] as const;
+
+/**
+ * Build a SIGNED webhook delivery for an async job completion: the thin event envelope + the
+ * Standard-Webhooks headers carrying a REAL HMAC signature. Deterministic + offline.
+ */
+export function buildSignedOpenAIWebhook(args: {
+  type: string;
+  resourceId: string;
+  secret: string;
+  occurredAt: string;
+  webhookId: string;
+  extra?: Record<string, unknown>;
+}): { headers: Record<string, string>; body: string; event: OpenAIWebhookEvent } {
+  const ts = Math.floor(Date.parse(args.occurredAt) / 1000);
+  const event: OpenAIWebhookEvent = {
+    object: 'event',
+    id: args.webhookId,
+    type: args.type,
+    created_at: ts,
+    data: { id: args.resourceId, ...(args.extra ?? {}) },
+  };
+  const body = JSON.stringify(event);
+  const headers = {
+    'webhook-id': args.webhookId,
+    'webhook-timestamp': String(ts),
+    'webhook-signature': computeOpenAIWebhookSignature(args.webhookId, ts, body, args.secret),
+  };
+  return { headers, body, event };
+}

package/test-fixtures/openai-openapi-operations.SOURCE.md

@@ -0,0 +1,19 @@
+# openai-openapi-operations.json — provenance
+
+The operation-inventory denominator for `../openai-spec-census.json`: a scope-filtered subset of
+the vendor's published spec, enumerated by `deriveFromOpenAPI` (`packages/twin/tooling/src/derive.ts`).
+
+- **Upstream:** https://github.com/openai/openai-openapi — `openapi.yaml`, fetched 2026-09-02 from
+  `https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml` at commit
+  `18a43ed13461a01fce5b9cc93c86843c550734a3` (2026-09-01), spec `info.version` 2.3.0.
+- **How it was built:** `bun scripts/spec-census-bootstrap.ts --vendor openai --from-file <openapi.yaml> --scope-paths /assistants,/audio,/batches,/chat/,/containers,/embeddings,/evals,/files,/fine_tuning,/images,/models,/moderations,/organization,/responses,/threads,/uploads,/vector_stores --apply`
+  over a copy of the upstream file fetched 2026-09-02; operation metadata only (operationId, summary, tags,
+  first response), schemas dropped. The gate never fetches — refreshing the fixture is
+  `bun scripts/spec-refresh.ts --vendor openai --from-file <newer spec> --apply` over a newly fetched copy.
+- **Scope (222 of 281 upstream operations):** every operation whose path starts with one of
+  `/assistants`, `/audio`, `/batches`, `/chat/`, `/containers`, `/embeddings`, `/evals`, `/files`, `/fine_tuning`, `/images`, `/models`, `/moderations`, `/organization`, `/responses`, `/threads`, `/uploads`, `/vector_stores`.
+- **Mapping:** 128 operations mapped to capability ids by segment match at birth, then reviewed by
+  hand against the router (`routeOpenAI` in `../src/openai-twin.ts`) and each capability's `verify()`:
+  60 entries were re-ruled, landing at **97 capability / 0 outOfScope / 125 unmapped** (the ratchet
+  baseline). Every later ruling (an `outOfScope` reason, a remap) is an edit to the census, never to
+  this fixture.