@volter/twin-openai 0.1.2 → 2.0.0

package/dist/src/openai-types.d.ts

@@ -0,0 +1,194 @@
+/** 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;
+    prompt_tokens_details?: {
+        cached_tokens: number;
+        audio_tokens: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens: number;
+        audio_tokens: number;
+        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;
+        annotations?: unknown[];
+        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;
+    service_tier?: string;
+    metadata?: Record<string, unknown> | null;
+};
+/** 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[];
+        logprobs?: 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;
+    }>;
+};
+/** A function-call output item: the model asking for a tool, as the Responses API shapes it
+ *  (`call_id` pairs with the caller's later `function_call_output` input item; `arguments` is JSON text). */
+export type ResponseFunctionCallItem = {
+    type: 'function_call';
+    id: string;
+    status: 'completed';
+    call_id: string;
+    name: string;
+    arguments: string;
+};
+/** A built-in tool OpenAI ran for the response: a web search or a file search (the spec's WebSearchToolCall, FileSearchToolCall). */
+export type ResponseBuiltInCallItem = {
+    type: 'web_search_call';
+    id: string;
+    status: 'completed';
+    action: {
+        type: 'search';
+        query: string;
+    };
+} | {
+    type: 'file_search_call';
+    id: string;
+    status: 'completed';
+    queries: string[];
+    results: null;
+};
+export type ResponseOutputItem = ResponseMessageItem | ResponseReasoningItem | ResponseFunctionCallItem | ResponseBuiltInCallItem;
+/** 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;
+    input_tokens_details?: {
+        cached_tokens: number;
+        cache_write_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;
+    completed_at?: number | null;
+    reasoning?: {
+        effort: string | null;
+        summary: string | null;
+    };
+    previous_response_id?: string | null;
+};
+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;
+    };
+};
+/** A vendor-shaped error envelope: { error: { message, type, param, code } }. */
+export type OpenAIError = {
+    error: {
+        message: string;
+        type: string;
+        param: string | null;
+        code: string | null;
+    };
+};
+/** 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/dist/src/openai-types.js

@@ -0,0 +1,4 @@
+// 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.
+export {};

package/dist/src/openai-webhooks.d.ts

@@ -0,0 +1,47 @@
+/** 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;
+    };
+};
+/**
+ * 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 declare function computeOpenAIWebhookSignature(id: string, timestamp: number, payload: string, secret: string): string;
+export declare class OpenAIWebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function verifyOpenAIWebhook(payload: string, headers: Record<string, string>, secret: string, opts?: {
+    tolerance?: number;
+    now?: number;
+}): OpenAIWebhookEvent;
+/** The webhook event types OpenAI emits (a faithful slice of the published set). */
+export declare const OPENAI_WEBHOOK_EVENT_TYPES: readonly ["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"];
+/**
+ * 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 declare 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;
+};

package/dist/src/openai-webhooks.js

@@ -0,0 +1,99 @@
+import { nodeBuiltin } from '@volter/world-core';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+/** Decode a `whsec_<base64>` signing secret to its raw HMAC key bytes. */
+function secretKeyBytes(secret) {
+    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, timestamp, payload, secret) {
+    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) {
+        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, headers, secret, opts = {}) {
+    const lower = {};
+    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);
+}
+/** 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',
+];
+/**
+ * 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) {
+    const ts = Math.floor(Date.parse(args.occurredAt) / 1000);
+    const event = {
+        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/dist/src/screens/api-keys.d.ts

@@ -0,0 +1,16 @@
+/** A request that presents one of the organization's project keys uses it: the key's `last_used_at` is that instant
+ *  (https://platform.openai.com/docs/api-reference/project-api-keys/object, "The Unix timestamp (in seconds) of when the
+ *  API key was last used."). A key that has stopped working is refused: one revoked on the keys page or deleted through the
+ *  Admin API, and one of an archived project ("Archived projects cannot be used or updated",
+ *  https://platform.openai.com/docs/api-reference/projects/archive). The refusal is OpenAI's incorrect-key answer (the
+ *  manifest's `auth.invalid`), as OpenAI documents no other for them; the answer is that refusal, or nothing to let the
+ *  request on. */
+export declare function projectKeyUse(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;
+/** platform.openai.com/settings/{project}/api-keys, or undefined for any other request. */
+export declare function openaiApiKeysScreen(scope: {
+    root?: string;
+    clock?: () => string;
+}): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/api-keys.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// OPENAI'S API KEYS PAGE — a workspace screen (docs/contributing/architecture.md, "Screens"): a project's secret keys
+// are made on platform.openai.com, never through the API (docs: platform.openai.com/docs/api-reference/project-api-keys
+// lists, retrieves and deletes them; creating one is the dashboard's "Create new secret key"). The page lists the
+// project's keys, makes a new one from its name and permissions and shows its secret once, and revokes a key. The
+// Admin API then reads and deletes what the page made. Authored from @volter/world-ui's portal piece under OpenAI's
+// skin; nothing of OpenAI's page is copied.
+//
+// The page acts for the person signed in to the dashboard (./session.tsx), never on an API key: a key is for the API,
+// and a request whose session names nobody is sent to log in. A key the page makes is that person's: its owner is
+// their user (https://platform.openai.com/docs/api-reference/project-api-keys/object, owner.user: id, email, name,
+// created_at, role).
+//
+// Where the documentation stops and the twin decides: a key's secret is derived from its id, and shown once, as the
+// dashboard does; any person of the organization may make and revoke a project's keys.
+import { createHash } from 'node:crypto';
+import { semanticsContext, vendorError } from '@volter/world-core';
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { epoch } from "../semantics/shared.js";
+import { signedIn, toLogIn } from "./session.js";
+const KEY = 'ProjectApiKey';
+const OPERATION = surface.operations.find((o) => o.id === 'list-project-api-keys');
+// a key's owner as the spec's ProjectApiKeyOwnerUser gives it: the person's user, created_at being when they joined, and
+// role their role in the project, "owner" or "member" (https://platform.openai.com/docs/api-reference/project-users/object).
+// The twin keeps no project members: the organization's owner owns every project, and anyone else who makes a key there
+// is a member of it.
+const ownerOf = (person) => ({ id: person.id, email: person.email, name: person.name, created_at: person.added_at, role: person.role === 'owner' ? 'owner' : 'member' });
+const PERMISSIONS = [{ value: 'all', label: 'All' }, { value: 'restricted', label: 'Restricted' }, { value: 'read_only', label: 'Read only' }];
+const OPENAI_SKIN = `
+body { background: #ffffff; color: #0d0d0d; font-family: "Söhne", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.portal-side { background: #f9f9f9; border-right: 1px solid #ececec; }
+.portal-section h2 { border-color: #ececec; color: #5d5d5d; }
+.portal-notice { background: #f0fdf4; border: 1px solid #bbf7d0; }
+.portal-detail, .portal-note { color: #5d5d5d; }
+.portal-button { border-color: #d9d9d9; color: #0d0d0d; }
+.portal-primary { background: #0d0d0d; border-color: #0d0d0d; color: #ffffff; }
+.portal-danger { color: #d00e17; border-color: #f3b4b7; }
+.portal-field input, .portal-field select { border-color: #d9d9d9; }
+`;
+const css = [PORTAL_CSS, OPENAI_SKIN];
+const secretOf = (id) => `sk-proj-${createHash('sha256').update(`project-key:${id}`).digest('hex').slice(0, 48)}`;
+const redacted = (secret) => `${secret.slice(0, 11)}...${secret.slice(-4)}`;
+/** The fields a submission carries: the page's form, as a browser posts it. */
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+function page(ctx, project, notice, status = 200) {
+    const id = String(project.id);
+    const keys = ctx.rowsRaw(KEY).filter((k) => k._project_id === id).sort((a, b) => Number(b.created_at) - Number(a.created_at));
+    const action = `/settings/${id}/api-keys`;
+    return flowPage({
+        title: 'API keys - OpenAI API',
+        status,
+        css,
+        body: (_jsx(Portal, { merchant: "OpenAI Platform", back: { href: '/settings/organization/general', label: String(project.name) }, ...(notice ? { notice } : {}), sections: [{
+                    heading: 'API keys',
+                    empty: 'This project has no API keys yet.',
+                    items: keys.map((k) => ({
+                        title: String(k.name),
+                        detail: String(k.redacted_value),
+                        note: `Created ${new Date(Number(k.created_at) * 1000).toISOString().slice(0, 10)} by ${String(k.owner?.user?.name ?? '')}`,
+                        actions: [{ label: 'Revoke key', action, fields: { revoke: String(k.id) }, tone: 'danger' }],
+                    })),
+                }], forms: [{
+                    heading: 'Create new secret key',
+                    action,
+                    fields: [
+                        { id: 'name', label: 'Name', placeholder: 'My Test Key' },
+                        { id: 'permissions', label: 'Permissions', options: PERMISSIONS, value: 'all' },
+                    ],
+                    submit: { label: 'Create secret key' },
+                }] })),
+    });
+}
+/** A request that presents one of the organization's project keys uses it: the key's `last_used_at` is that instant
+ *  (https://platform.openai.com/docs/api-reference/project-api-keys/object, "The Unix timestamp (in seconds) of when the
+ *  API key was last used."). A key that has stopped working is refused: one revoked on the keys page or deleted through the
+ *  Admin API, and one of an archived project ("Archived projects cannot be used or updated",
+ *  https://platform.openai.com/docs/api-reference/projects/archive). The refusal is OpenAI's incorrect-key answer (the
+ *  manifest's `auth.invalid`), as OpenAI documents no other for them; the answer is that refusal, or nothing to let the
+ *  request on. */
+export function projectKeyUse(scope) {
+    return async (request) => {
+        const bearer = /^Bearer\s+(sk-proj-\S+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
+        if (!bearer)
+            return undefined;
+        const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), OPERATION, scope);
+        const key = ctx.rowsRaw(KEY, { withDeleted: true }).find((k) => secretOf(String(k.id)) === bearer);
+        const archived = key ? ctx.row('Project', String(key._project_id))?.status === 'archived' : false;
+        if (key?.deleted === true || archived)
+            return vendorError(manifest, manifest.auth.invalid);
+        if (key)
+            await ctx.write(KEY, String(key.id), { last_used_at: epoch(ctx) }, 'api_key.update');
+        return undefined;
+    };
+}
+/** platform.openai.com/settings/{project}/api-keys, or undefined for any other request. */
+export function openaiApiKeysScreen(scope) {
+    return async (request) => {
+        const m = /^\/settings\/(proj[-_][A-Za-z0-9_-]+)\/api-keys\/?$/.exec(new URL(request.url).pathname);
+        if (!m || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+        const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+        const person = signedIn(request, ctx);
+        if (!person)
+            return toLogIn(request);
+        const project = ctx.get('Project', m[1]);
+        if (!project)
+            return flowPage({ title: 'OpenAI Platform', status: 404, css, body: _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "Project not found" }) }) });
+        if (request.method === 'GET')
+            return page(ctx, project);
+        if (form.revoke) {
+            const key = ctx.row(KEY, form.revoke);
+            if (!key || key._project_id !== project.id)
+                return page(ctx, project, 'That key no longer exists.', 404);
+            await ctx.write(KEY, form.revoke, { deleted: true }, 'api_key.delete');
+            return page(ctx, project, `Revoked ${String(key.name)}. Requests using it will now fail.`);
+        }
+        const name = (form.name ?? '').trim() || 'Secret key';
+        const id = ctx.mint(KEY);
+        const secret = secretOf(id);
+        await ctx.write(KEY, id, {
+            object: 'organization.project.api_key', name, redacted_value: redacted(secret), created_at: epoch(ctx), last_used_at: null,
+            _project_id: project.id, owner: { type: 'user', user: ownerOf(person) }, owner_project_access: 'active', _permissions: PERMISSIONS.some((p) => p.value === form.permissions) ? form.permissions : 'all',
+        }, 'api_key.create');
+        return page(ctx, project, `Save your key: ${secret}. You won't be able to view it again.`, 201);
+    };
+}

package/dist/src/screens/session.d.ts

@@ -0,0 +1,22 @@
+import { type SemanticsContext } from '@volter/world-core';
+type Scope = {
+    root?: string;
+    clock?: () => string;
+};
+/** A person's account: the user object's fields, and the hash of the password the World gave them. */
+export type Account = {
+    id: string;
+    object: 'organization.user';
+    name: string;
+    email: string;
+    role: 'owner' | 'reader';
+    added_at: number;
+    _hash: string;
+};
+/** The account the request's session cookie names, or undefined when nobody is signed in. */
+export declare function signedIn(request: Request, ctx: SemanticsContext): Account | undefined;
+/** Where a dashboard page asked for by nobody signed in sends its visitor: the log-in, returning here after. */
+export declare function toLogIn(request: Request): Response;
+/** The log-in's paths and the World's account door, or undefined for any other request. */
+export declare function openaiSessionFlow(scope: Scope): (request: Request) => Promise<Response | undefined>;
+export {};

package/dist/src/screens/session.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// OPENAI'S LOG-IN — the door before the dashboard's pages (docs/contributing/architecture.md, "Who is on a screen"): the
+// log-in page takes a person's email address and password, the right pair signs them in, and the dashboard's session
+// cookie names them to every page after. A dashboard page asked for by nobody signed in sends its visitor to the log-in
+// with `return_to`, and the log-in returns them there. Built from @volter/world-ui's sign-in piece under OpenAI's skin;
+// nothing of OpenAI's page is copied.
+//
+// A person is an account of the World's organization, as the Admin API's user object gives one
+// (https://platform.openai.com/docs/api-reference/users/object: id, name, email, role "owner" or "reader", added_at).
+//
+// Where OpenAI's documentation stops and the twin decides: an account is made at the World's door
+// (`POST /_twin/accounts`, standing in for OpenAI's sign-up, which is not modelled), and the World keeps its password's
+// hash, never the password; the World has one organization, whose first account is its owner and whose later ones join
+// as readers unless the door names a role; the log-in is one page (OpenAI's asks for the email and the password on two),
+// served on the dashboard's own host at platform.openai.com/login, the address OpenAI's log-in link opens (OpenAI hands it
+// on to auth.openai.com, which the twin does not model as a host of its own), so its session cookie is the dashboard's;
+// the session cookie's name (`platform_session`) is the twin's, as OpenAI documents none; a refused log-in shows the page
+// again with the message, answered 200; and a session does not end: no person of a World logs out yet.
+import { createHash } from 'node:crypto';
+import { semanticsContext } from '@volter/world-core';
+import { cookieOf, flowPage, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { epoch } from "../semantics/shared.js";
+const ACCOUNT = '_account';
+const SESSION = '_session';
+const COOKIE = 'platform_session';
+const OPERATION = surface.operations.find((o) => o.id === 'retrieve-user');
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email, password) => hex(`password:${email.toLowerCase()}:${password}`);
+// OpenAI's skin over the sign-in: its black primary button on white
+const SKIN = `
+body { background: #ffffff; color: #0d0d0d; font-family: "Söhne", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.sign-in-mark { background: #0d0d0d; }
+.sign-in-error { background: #fef2f2; border-color: #fecaca; color: #b91c1c; }
+.sign-in-box { background: #ffffff; border-color: #ececec; }
+.sign-in-box input[type=text], .sign-in-box input[type=password] { border-color: #d9d9d9; }
+.sign-in-submit { background: #0d0d0d; border-color: #0d0d0d; color: #ffffff; }
+`;
+const contextOf = (request, scope) => semanticsContext(manifest, request, OPERATION, scope);
+const accounts = (ctx) => ctx.rowsRaw(ACCOUNT);
+/** The account the request's session cookie names, or undefined when nobody is signed in. */
+export function signedIn(request, ctx) {
+    const token = cookieOf(request, COOKIE);
+    const session = token ? ctx.rowsRaw(SESSION).find((s) => s.token === token) : undefined;
+    return session ? accounts(ctx).find((a) => a.id === session.account) : undefined;
+}
+/** Where a dashboard page asked for by nobody signed in sends its visitor: the log-in, returning here after. */
+export function toLogIn(request) {
+    const url = new URL(request.url);
+    return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(url.pathname + url.search)}` } });
+}
+/** A return_to the log-in follows: a path on the dashboard, never another site. */
+const returnTo = (raw) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+function page(back, email, error) {
+    return flowPage({
+        title: 'Log in - OpenAI',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(SignIn, { heading: "Welcome back", action: "/login", fields: { return_to: back }, account: { name: 'email', label: 'Email address', ...(email ? { value: email } : {}) }, password: { name: 'password', label: 'Password' }, submit: "Continue", ...(error ? { error } : {}) })),
+    });
+}
+async function logIn(request, scope) {
+    const form = Object.fromEntries(new URLSearchParams(await request.clone().text()));
+    const email = (form.email ?? '').trim();
+    const back = returnTo(form.return_to);
+    const ctx = await contextOf(request, scope);
+    const account = accounts(ctx).find((a) => a.email.toLowerCase() === email.toLowerCase());
+    // the log-in names neither which half was wrong
+    if (!account || account._hash !== passwordHash(account.email, form.password ?? ''))
+        return page(back, email, 'Wrong email or password.');
+    const n = ctx.rowsRaw(SESSION).length + 1;
+    const token = hex(`session:${account.id}:${ctx.occurredAt}:${n}`).slice(0, 48);
+    await ctx.record(SESSION, { token, account: account.id, created_at: epoch(ctx) }, `session_${token.slice(0, 16)}`);
+    return new Response(null, { status: 302, headers: { location: back, 'set-cookie': `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax` } });
+}
+/** The World's account door refusing an account it cannot make: one already made for the email, or one missing a field. */
+function badAccount(email, taken) {
+    return Response.json({ error: { message: taken ? `An account for ${email} already exists.` : 'An account needs an email address, a name and a password; a role is "owner" or "reader".', type: 'invalid_request_error' } }, { status: 400 });
+}
+/** POST /_twin/accounts {email, name, password, role?} → 201 the account's user object: a person of the World's
+ *  organization, who logs in with that password. */
+async function makeAccount(request, scope) {
+    let body = {};
+    try {
+        body = await request.clone().json();
+    }
+    catch { /* answered below */ }
+    const email = typeof body.email === 'string' ? body.email.trim() : '';
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    const password = typeof body.password === 'string' ? body.password : '';
+    const ctx = await contextOf(request, scope);
+    const taken = accounts(ctx).some((a) => a.email.toLowerCase() === email.toLowerCase());
+    if (!/^[^@\s]+@[^@\s]+$/.test(email) || !name || !password || taken || (body.role !== undefined && body.role !== 'owner' && body.role !== 'reader'))
+        return badAccount(email, taken);
+    const role = body.role ?? (accounts(ctx).some((a) => a.role === 'owner') ? 'reader' : 'owner');
+    const id = `user-${hex(`account:${email.toLowerCase()}`).slice(0, 24)}`;
+    const account = { id, object: 'organization.user', name, email, role, added_at: epoch(ctx), _hash: passwordHash(email, password) };
+    await ctx.record(ACCOUNT, account, id);
+    const { _hash: _secret, ...user } = account;
+    return Response.json(user, { status: 201 });
+}
+/** The log-in's paths and the World's account door, or undefined for any other request. */
+export function openaiSessionFlow(scope) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const path = url.pathname.replace(/\/+$/, '');
+        if (path === '/login' && request.method === 'GET')
+            return page(returnTo(url.searchParams.get('return_to')));
+        if (path === '/login' && request.method === 'POST')
+            return logIn(request, scope);
+        if (path === '/_twin/accounts' && request.method === 'POST')
+            return makeAccount(request, scope);
+        return undefined;
+    };
+}

package/dist/src/semantics/assistants.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const assistants: Record<string, Semantics>;