@zocomputer/system-api 0.0.0-stage → 0.1.1

package/dist/core/transport.js

@@ -0,0 +1,367 @@
+/**
+ * Fetch transport for the single `/invoke` route.
+ *
+ * Browser-safe: uses `fetch` only, no Node built-ins. Invoke is never retried
+ * automatically — a disconnect, deadline, or malformed result after a mutation
+ * may mean the effect happened, so uncertainty is surfaced rather than replayed.
+ * The request is serialized, size-checked, and the token obtained and validated
+ * BEFORE any network call, so a pre-flight failure reports `outcome:
+ * "not_started"`; `network` is used solely for a `fetch` rejection. Response
+ * bodies are read under a byte cap before parsing, and redirects are refused so
+ * a bearer credential is never replayed to a redirected origin.
+ */
+import { isErrorBody, parseSuccess, readRequestId, } from "./envelope.js";
+import { SystemAPIError } from "./errors.js";
+import { isJsonObject } from "./json.js";
+/**
+ * The closed error wire is `{request_id, error:{code, message, details}}`, so a
+ * lifecycle outcome, when the server sends one, lives at `error.details.outcome`.
+ * Copy it onto the error only when it is exactly one of the two wire values;
+ * an absent, malformed, or unrecognized outcome stays unset. The HTTP status is
+ * never used to infer it — a status does not tell us whether the action ran.
+ */
+function outcomeFromDetails(details) {
+    if (!isJsonObject(details))
+        return undefined;
+    const outcome = details["outcome"];
+    return outcome === "not_started" || outcome === "unknown"
+        ? outcome
+        : undefined;
+}
+export const DEFAULT_BASE_URL = "https://api.zo.computer/zo-system-api/v1";
+/** Plan inline ceiling for a result payload: 1 MiB. */
+const MAX_INLINE_BYTES = 1024 * 1024;
+/**
+ * Total serialized request-body cap: 5 MiB. Inline file content may be up to
+ * 4 MiB of UTF-8, but the whole body as sent must fit here: JSON escaping
+ * (quotes, backslashes, control characters) counts, so heavily escaped
+ * content may need a prepared upload.
+ */
+export const MAX_REQUEST_BYTES = 5 * 1024 * 1024;
+/**
+ * The response may carry a full 1 MiB inline result plus envelope framing
+ * (request_id, action, options, JSON punctuation), so its cap reserves overhead
+ * above the inline ceiling — otherwise a valid near-limit result is rejected.
+ */
+const FRAMING_OVERHEAD_BYTES = 64 * 1024;
+export const MAX_RESPONSE_BYTES = MAX_INLINE_BYTES + FRAMING_OVERHEAD_BYTES;
+/** Upper bound on an honored `Retry-After`, so a hostile header can't stall a caller. */
+const MAX_RETRY_AFTER_SECONDS = 3600;
+/** Header-safe token characters are visible ASCII, 0x21 ('!') to 0x7e ('~'). */
+const MIN_VISIBLE_ASCII = 0x21;
+const MAX_VISIBLE_ASCII = 0x7e;
+function byteLength(text) {
+    return new TextEncoder().encode(text).byteLength;
+}
+function normalizeBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new SystemAPIError({
+            code: "invalid_envelope",
+            message: `invalid baseUrl: ${baseUrl}`,
+            outcome: "not_started",
+        });
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new SystemAPIError({
+            code: "invalid_envelope",
+            message: `unsupported baseUrl protocol: ${parsed.protocol}`,
+            outcome: "not_started",
+        });
+    }
+    return parsed.href.replace(/\/+$/, "");
+}
+/**
+ * Validate a bearer token before it reaches a header. The runtime type is
+ * checked (a provider may return a non-string through untyped JavaScript), and
+ * the token must be non-empty header-safe visible ASCII — control, whitespace
+ * (ASCII or Unicode such as U+00A0/U+0085), and any character a header builder
+ * could reject are refused here, before any request is sent, so they surface as
+ * `unauthenticated`/`not_started` rather than a raw error or a misfiled network
+ * failure.
+ */
+function validateToken(token) {
+    if (typeof token !== "string") {
+        throw new SystemAPIError({
+            code: "unauthenticated",
+            message: "the access token provider did not return a string",
+            outcome: "not_started",
+        });
+    }
+    if (token.length === 0) {
+        throw new SystemAPIError({
+            code: "unauthenticated",
+            message: "access token is empty",
+            outcome: "not_started",
+        });
+    }
+    for (let i = 0; i < token.length; i++) {
+        const code = token.charCodeAt(i);
+        if (code < MIN_VISIBLE_ASCII || code > MAX_VISIBLE_ASCII) {
+            throw new SystemAPIError({
+                code: "unauthenticated",
+                message: "access token contains characters that are not header-safe",
+                outcome: "not_started",
+            });
+        }
+    }
+    return token;
+}
+function parseRetryAfter(header) {
+    if (header === null)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Math.min(Number(trimmed), MAX_RETRY_AFTER_SECONDS);
+    }
+    const when = Date.parse(trimmed);
+    if (Number.isNaN(when))
+        return undefined;
+    const seconds = Math.ceil((when - Date.now()) / 1000);
+    if (seconds <= 0)
+        return 0;
+    return Math.min(seconds, MAX_RETRY_AFTER_SECONDS);
+}
+async function readBoundedText(response, maxBytes) {
+    const stream = response.body;
+    if (stream === null) {
+        // An injected fetch (tests) may not expose a stream; fall back to text().
+        const text = await response.text();
+        if (byteLength(text) > maxBytes)
+            throwOversized(response.status);
+        return text;
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throwOversized(response.status);
+        }
+        chunks.push(value);
+    }
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    // Strict UTF-8: invalid bytes are rejected (parity with Python's strict
+    // decode), never silently replaced with U+FFFD. This is the single place the
+    // response body is decoded, so an optional validator sees the exact same text.
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(joined);
+    }
+    catch (cause) {
+        throw new SystemAPIError({
+            code: "invalid_response",
+            message: "response body was not valid UTF-8",
+            httpStatus: response.status,
+            outcome: "unknown",
+            cause,
+        });
+    }
+}
+function throwOversized(httpStatus) {
+    // Client-side protective cap: the response exceeded the inline result budget,
+    // so we could not read it. The request was sent, so the effect is uncertain;
+    // the HTTP response did arrive, so its status is carried on the error.
+    throw new SystemAPIError({
+        code: "output_limit_exceeded",
+        message: "response exceeded the inline result size limit",
+        httpStatus,
+        outcome: "unknown",
+    });
+}
+export function createTransport(config) {
+    const validator = config.validator;
+    const doFetch = config.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new SystemAPIError({
+            code: "invalid_envelope",
+            message: "no fetch implementation available",
+            outcome: "not_started",
+        });
+    }
+    const baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+    const workspaceId = config.workspaceId;
+    if (workspaceId !== undefined &&
+        (typeof workspaceId !== "string" ||
+            !/^[\x21-\x7e]{1,200}$/.test(workspaceId))) {
+        throw new SystemAPIError({
+            code: "invalid_envelope",
+            message: "workspaceId must contain 1 to 200 header-safe characters",
+            outcome: "not_started",
+        });
+    }
+    async function invokeText(requestBody, sent, target, decodeBody = JSON.parse) {
+        if (byteLength(requestBody) > MAX_REQUEST_BYTES) {
+            throw new SystemAPIError({
+                code: "payload_too_large",
+                message: "request body exceeds the inline size limit",
+                outcome: "not_started",
+            });
+        }
+        // Obtain and validate the token before fetch; a failure here never sent.
+        let rawToken;
+        try {
+            rawToken = await config.accessToken();
+        }
+        catch (cause) {
+            throw new SystemAPIError({
+                code: "unauthenticated",
+                message: "the access token provider failed",
+                outcome: "not_started",
+                cause,
+            });
+        }
+        const token = validateToken(rawToken);
+        // Optional request validation on the EXACT bytes about to be sent, still
+        // before any network call. A throw here — including a SystemAPIError with
+        // misreported lifecycle fields — is normalized: the request was not sent,
+        // so core sets not_started with no httpStatus and keeps the throw as cause.
+        if (validator !== undefined) {
+            try {
+                validator.validateRequestBody(target, requestBody);
+            }
+            catch (cause) {
+                throw new SystemAPIError({
+                    code: "invalid_input",
+                    message: "request body failed client validation before sending",
+                    outcome: "not_started",
+                    cause,
+                });
+            }
+        }
+        let response;
+        try {
+            response = await doFetch(`${baseUrl}/invoke`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${token}`,
+                    ...(workspaceId !== undefined
+                        ? { "Zo-Workspace-Id": workspaceId }
+                        : {}),
+                },
+                body: requestBody,
+                // Refuse redirects: never replay the bearer token to a redirected origin.
+                redirect: "error",
+            });
+        }
+        catch (cause) {
+            // No HTTP response was produced. httpStatus is absent; the effect is
+            // uncertain because we cannot know whether the request reached the server.
+            throw new SystemAPIError({
+                code: "network",
+                message: "request failed before a response was received",
+                outcome: "unknown",
+                cause,
+            });
+        }
+        let text;
+        try {
+            text = await readBoundedText(response, MAX_RESPONSE_BYTES);
+        }
+        catch (cause) {
+            // Our own protective cap re-throws as SystemAPIError; anything else is a
+            // failed body read after a response arrived — a malformed protocol result.
+            if (cause instanceof SystemAPIError)
+                throw cause;
+            throw new SystemAPIError({
+                code: "invalid_response",
+                message: "response body could not be read",
+                httpStatus: response.status,
+                outcome: "unknown",
+                cause,
+            });
+        }
+        let body;
+        try {
+            body = text.length === 0 ? undefined : decodeBody(text);
+        }
+        catch {
+            throw new SystemAPIError({
+                code: "invalid_response",
+                message: "response body was not valid JSON",
+                httpStatus: response.status,
+                outcome: "unknown",
+            });
+        }
+        if (!response.ok) {
+            const retryAfterSeconds = parseRetryAfter(response.headers.get("retry-after"));
+            if (isErrorBody(body)) {
+                // Preserve the server's well-formed error code verbatim, including
+                // custom action-declared failures we do not enumerate.
+                throw new SystemAPIError({
+                    code: body.error.code,
+                    message: body.error.message,
+                    requestId: body.request_id,
+                    httpStatus: response.status,
+                    details: body.error.details,
+                    outcome: outcomeFromDetails(body.error.details),
+                    retryAfterSeconds,
+                });
+            }
+            // Non-2xx without a well-formed error envelope: malformed protocol response.
+            throw new SystemAPIError({
+                code: "invalid_response",
+                message: `received status ${response.status} without a valid error envelope`,
+                requestId: readRequestId(body),
+                httpStatus: response.status,
+                retryAfterSeconds,
+                outcome: "unknown",
+            });
+        }
+        // Validate and correlate the success envelope FIRST: a malformed or
+        // miscorrelated 2xx envelope must surface as invalid_response, never as a
+        // schema error. Only a trusted InvocationSuccess reaches output validation.
+        const success = parseSuccess(body, sent, response.status);
+        // Optional output validation on the exact response text plus the validated
+        // envelope. The action already executed, so a throw — again including a
+        // SystemAPIError with wrong lifecycle fields — is normalized to unknown
+        // with the response status and NO retry; the throw is kept as cause.
+        if (validator !== undefined) {
+            try {
+                validator.validateSuccessBody(target, text, success);
+            }
+            catch (cause) {
+                throw new SystemAPIError({
+                    code: "invalid_response",
+                    message: "response body failed client validation",
+                    requestId: success.request_id,
+                    httpStatus: response.status,
+                    outcome: "unknown",
+                    cause,
+                });
+            }
+        }
+        return { success, text, httpStatus: response.status };
+    }
+    return {
+        invokeText,
+        async invoke(envelope, target) {
+            let requestBody;
+            try {
+                requestBody = JSON.stringify(envelope);
+            }
+            catch (cause) {
+                throw new SystemAPIError({
+                    code: "invalid_envelope",
+                    message: "request envelope could not be serialized",
+                    outcome: "not_started",
+                    cause,
+                });
+            }
+            return (await invokeText(requestBody, envelope, target)).success;
+        },
+    };
+}

package/dist/core/validator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The optional validation seam.
+ *
+ * `createClient` accepts an optional, structural `InvocationValidator`. When one
+ * is injected, the single transport calls its two synchronous hooks on the exact
+ * request/response bytes — the core owns serialize / size / token / fetch /
+ * bounded fatal decode / `parseSuccess` exactly once, and the hooks import
+ * nothing from a validator's heavy dependencies. A typed-only consumer that
+ * injects no validator bundles none of that.
+ *
+ * These are TYPES ONLY. The heavy factory that implements this interface
+ * (`createSchemaValidator`) lives behind the separate `@zocomputer/system-api/validation`
+ * entry so it never enters a typed-only bundle.
+ */
+import type { InvocationSuccess } from "./envelope.ts";
+/**
+ * What the client already resolved for a call: the action, its concrete integer
+ * `version` (matching `InvocationOptions.version`), and that version's catalog
+ * `VersionEntry.digest`. A validator resolves its schema bundle by this exact
+ * contract, so a payload is never validated against a schema whose digest
+ * disagrees with the pinned catalog entry.
+ */
+export interface InvocationTarget {
+    readonly action: string;
+    readonly version: number;
+    readonly digest: string;
+}
+/**
+ * An optional structural validator. Both hooks are synchronous and signal a
+ * failure by throwing; the transport normalizes every throw (see
+ * `createTransport`) into a `SystemAPIError` whose lifecycle fields
+ * (`code`/`httpStatus`/`outcome`/`retryAfterSeconds`) are always set by the
+ * transport, never trusted from the hook — the original throw is preserved only
+ * as `cause`. A hook that returns normally accepts the payload.
+ */
+export interface InvocationValidator {
+    /**
+     * Validate the exact request body bytes before they are sent. `exactBody` is
+     * the precise string the transport will send (never a re-serialization).
+     * Throwing here fails the call before any network request.
+     */
+    validateRequestBody(target: InvocationTarget, exactBody: string): void;
+    /**
+     * Validate the exact response text after the transport has already validated
+     * and correlated the success envelope. `rawText` is the exact fatal-decoded
+     * response body; `success` is the validated envelope `parseSuccess` returned.
+     * Its query metadata uses ordinary JS numbers, including for `callJson`.
+     * Use `rawText` for comparisons that require exact decimal values.
+     * Throwing here fails a call whose action already executed.
+     */
+    validateSuccessBody(target: InvocationTarget, rawText: string, success: InvocationSuccess): void;
+}

package/dist/core/validator.js

@@ -0,0 +1 @@
+export {};

package/dist/generate/cli.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { rename } from "node:fs/promises";
+interface GenerateArgs {
+    out: string;
+    baseUrl?: string;
+    workspace?: string;
+    catalog?: string;
+    from?: string;
+    check: boolean;
+}
+declare function parseArgs(argv: readonly string[]): GenerateArgs;
+/**
+ * Validate the base URL as a credential-bearing endpoint: HTTPS, or explicit
+ * loopback HTTP for local/integration use. Reject any other scheme, non-loopback
+ * HTTP, and any userinfo, query, or fragment — a bearer token must never be able
+ * to ride along in the URL, and the endpoint must not carry hidden state.
+ */
+declare function validateBaseUrl(raw: string): URL;
+/** Read the access token from the environment, falling back to stdin. */
+declare function readToken(): Promise<string>;
+/**
+ * Fetch the raw catalog export bytes from the service. The service requires
+ * `workspace_id` and accepts `catalog` as query parameters. Redirects are
+ * refused (a redirect could send the bearer token to another origin), the
+ * request is bounded by an explicit deadline, and the response body is counted
+ * against {@link MAX_EXPORT_BYTES} while streaming.
+ */
+/** Bounds on the export request, overridable in tests for fast, focused cases. */
+interface FetchExportOptions {
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+}
+declare function fetchExport(baseUrl: URL, workspace: string, catalog: string | undefined, token: string, options?: FetchExportOptions): Promise<Uint8Array>;
+/**
+ * Write the bundle into `outDir`, replacing it atomically at the directory
+ * boundary: stage every file in a sibling temp directory, then swap it into
+ * place, so a reader never sees a half-written mix of old and new files.
+ */
+declare function writeBundleAtomically(outDir: string, files: Record<string, string | Uint8Array>, deps?: {
+    rename: typeof rename;
+    restore?: typeof rename;
+}): Promise<void>;
+declare function main(argv: readonly string[]): Promise<number>;
+export { fetchExport, main, parseArgs, readToken, validateBaseUrl, writeBundleAtomically, };