@hraness/ghostget 0.17.6 → 0.18.2

package/src/control/credential-helper.ts

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { createAuth, loadAuthSnapshotIfPresent, normalizeOAuthScopes, replaceAuthIfUnchanged, saveAuth } from "../auth";
+import { canonicalJson } from "../canonical-json";
+import { OperationDeadline } from "../operation-deadline";
+import { createPinnedHttpsFetchScope, type PinnedHttpsFetch } from "../pinned-https";
+import { bearerHeaders, loadOAuthCredential, loadOAuthToken, ProviderHttpClient, type OAuthTokenAuth } from "../provider-http";
+import { isXAccountSubject } from "../provider-subject";
+import { withReadProjectionAuthAdmission } from "../read-projections";
+import { createPrivateJsonIfAbsent, ghostgetStateHome, removePrivateStateFileIfUnchanged } from "../storage";
+import { GHOSTGET_VERSION } from "../version";
+import type { ControlRequest } from "./protocol";
+import { readInterfaceJson } from "./interface-json";
+import { parseControlRequest } from "./validation";
+import { connectionAccountRevision } from "./account-revision";
+
+export type VaultImportRequest = Extract<ControlRequest, { action: "vault.import" }>;
+export type VaultImportCode = "INVALID_IMPORT" | "ACCOUNT_CHANGED" | "VAULT_UNAVAILABLE" | "TOKEN_UNVERIFIED" | "IMPORT_CANCELLED" | "IMPORT_FAILED" | "IMPORT_UNCERTAIN";
+export type VaultImportResult = { readonly ok: true } | { readonly ok: false; readonly code: VaultImportCode };
+type Environment = Readonly<Record<string, string | undefined>>;
+export const VAULT_IMPORT_TIMEOUT_MS = 120_000;
+const X_IMPORT_SCOPES = new Set(["tweet.read", "tweet.write", "users.read", "dm.read", "dm.write", "bookmark.write"]);
+
+/** The import metadata is declared by the human; only the exact user subject is proved. */
+export function parseVaultImport(value: unknown, now = Date.now()): VaultImportRequest {
+  const request = parseControlRequest(value);
+  if (request.action !== "vault.import" || !/^[a-z][a-z0-9-]{0,47}$/u.test(request.id)
+    || !isXAccountSubject(request.expectedSubject)
+    || request.account.trim() !== request.account || /[\u0000-\u001f\u007f]/u.test(request.account)
+    || !/^op:\/\/[^/\u0000-\u001f\u007f?#\\]+\/[^/\u0000-\u001f\u007f?#\\]+\/(?:[^/\u0000-\u001f\u007f?#\\]+\/)?[^/\u0000-\u001f\u007f?#\\]+$/u.test(request.reference)
+    || /%(?:2f|5c|00|0a|0d)/iu.test(request.reference)) throw new Error("invalid token import");
+  const scopes = normalizeOAuthScopes(request.scopes);
+  if (!scopes.includes("tweet.read") || !scopes.includes("users.read") || scopes.some(scope => !X_IMPORT_SCOPES.has(scope))) throw new Error("unsupported token scopes");
+  if (request.expiresAt !== null && (!Number.isFinite(Date.parse(request.expiresAt)) || new Date(request.expiresAt).toISOString() !== request.expiresAt || Date.parse(request.expiresAt) <= now + 30_000)) throw new Error("invalid declared expiry");
+  return { ...request, scopes };
+}
+
+/** Trusted fixed sink: no registry, supplied URL, dynamic executor, redirect or retry. */
+export async function probeImportedXToken(auth: OAuthTokenAuth, signal: AbortSignal, transport?: PinnedHttpsFetch): Promise<string> {
+  const deadline = new OperationDeadline(15_000, { signal });
+  const scope = transport === undefined ? createPinnedHttpsFetchScope("https://api.x.com") : null;
+  const fetch = transport ?? scope!.fetch;
+  try {
+    const token = loadOAuthToken(auth);
+    const http = new ProviderHttpClient((input, init) => fetch(new URL(String(input)), init ?? {}, 15_000), deadline, 16_384);
+    const response = await http.request("https://api.x.com/2/users/me", { method: "GET", headers: bearerHeaders(token.accessToken, { Accept: "application/json" }), credentials: "omit" }, [200], ["api.x.com"], 16_384, "application/json");
+    const body = response.body as { data?: { id?: unknown }; errors?: unknown } | null;
+    const subject = body?.data?.id;
+    if (typeof subject !== "string" || !isXAccountSubject(subject) || body?.errors !== undefined) throw new Error("unverified account");
+    deadline.throwIfUnavailable("account verification");
+    return subject;
+  } finally { deadline.dispose(); scope?.close(); }
+}
+
+async function resolveDesktopSecret(account: string, reference: string): Promise<string> {
+  const sdk = await import("@1password/sdk");
+  const client = await sdk.createClient({ auth: new sdk.DesktopAuth(account), integrationName: "Ghostget", integrationVersion: GHOSTGET_VERSION });
+  return client.secrets.resolve(reference);
+}
+
+export type CredentialImportDependencies = {
+  readonly resolve?: (account: string, reference: string) => Promise<string>;
+  readonly probe?: (auth: OAuthTokenAuth, signal: AbortSignal) => Promise<string>;
+};
+
+/** Runs only in the credential process. Never returns secret values or raw errors. */
+export async function runCredentialImport(value: unknown, environment: Environment, signal: AbortSignal, dependencies: CredentialImportDependencies = {}): Promise<VaultImportResult> {
+  let request: VaultImportRequest;
+  try { request = parseVaultImport(value); } catch { return { ok: false, code: "INVALID_IMPORT" }; }
+  const deadline = new OperationDeadline(VAULT_IMPORT_TIMEOUT_MS, { signal });
+  let stage: { path: string; contentSha256: string | null } | null = null;
+  let failure: VaultImportCode = "IMPORT_FAILED";
+  try {
+    deadline.throwIfUnavailable("token import");
+    failure = "ACCOUNT_CHANGED";
+    const current = withReadProjectionAuthAdmission(request.id, environment, () => {
+      const snapshot = loadAuthSnapshotIfPresent(request.id, environment);
+      if ((snapshot === null ? null : connectionAccountRevision(snapshot, environment)) !== request.expectedRevision) throw new Error();
+      return snapshot;
+    });
+    failure = "VAULT_UNAVAILABLE";
+    const accessToken = await deadline.run(() => (dependencies.resolve ?? resolveDesktopSecret)(request.account, request.reference), "vault access");
+    if (typeof accessToken !== "string" || accessToken.length < 8 || Buffer.byteLength(accessToken) > 16_384 || !/^[A-Za-z0-9._~+/-]+=*$/u.test(accessToken)) return { ok: false, code: "TOKEN_UNVERIFIED" };
+    deadline.throwIfUnavailable("token import");
+    failure = "IMPORT_FAILED";
+    const path = join(ghostgetStateHome(environment), "auth", "oauth-tokens", `${request.id}-${randomUUID()}.json`);
+    const credential = { schemaVersion: 1, provider: "x", subject: request.expectedSubject, scopes: request.scopes, accessToken, expiresAt: request.expiresAt };
+    const expectedContent = `${canonicalJson(credential)}\n`;
+    stage = { path, contentSha256: null };
+    if (!createPrivateJsonIfAbsent(path, credential, { privateParent: true, environment }).created) { stage = null; throw new Error(); }
+    const auth = createAuth(request.id, { oauthProvider: "x", tokenFile: path, subject: request.expectedSubject, scopes: request.scopes, ownedImport: true });
+    if (auth.kind !== "oauth-token-file") throw new Error();
+    const { contentSha256 } = loadOAuthCredential(auth, { expectedContent });
+    stage = { path, contentSha256 };
+    failure = "TOKEN_UNVERIFIED";
+    const subject = await deadline.run(activeSignal => (dependencies.probe ?? probeImportedXToken)(auth, activeSignal), "account verification");
+    if (subject !== request.expectedSubject) throw new Error();
+    failure = "ACCOUNT_CHANGED";
+    withReadProjectionAuthAdmission(request.id, environment, () => {
+      deadline.throwIfUnavailable("token import");
+      // Validation is repeated after both external ceremonies and before the only commit.
+      parseVaultImport(request);
+      const observed = loadAuthSnapshotIfPresent(request.id, environment);
+      if ((observed === null ? null : connectionAccountRevision(observed, environment)) !== request.expectedRevision) throw new Error();
+      if (loadOAuthCredential(auth, { expectedContent }).contentSha256 !== contentSha256) throw new Error();
+      if (current === null) saveAuth(auth, environment);
+      else if (!replaceAuthIfUnchanged(current, auth, environment).replaced) throw new Error();
+    });
+    stage = null;
+    return { ok: true };
+  } catch {
+    if (stage !== null) {
+      try {
+        const observed = loadAuthSnapshotIfPresent(request.id, environment)?.auth;
+        // A cleanup failure after locator publication must never erase its live token.
+        if (stage.contentSha256 === null || observed?.kind === "oauth-token-file" && observed.path === stage.path) return { ok: false, code: "IMPORT_UNCERTAIN" };
+        if (!removePrivateStateFileIfUnchanged(stage.path, { expectedCurrentContentSha256: stage.contentSha256 }, environment)) return { ok: false, code: "IMPORT_UNCERTAIN" };
+      } catch { return { ok: false, code: "IMPORT_UNCERTAIN" }; }
+    }
+    return { ok: false, code: deadline.signal.aborted ? "IMPORT_CANCELLED" : failure };
+  } finally { deadline.dispose(); }
+}
+
+async function main(): Promise<void> {
+  // Install before the lazy SDK import, including any SDK module-loader output.
+  // Native library stderr is discarded by the parent; malformed stdout is never
+  // surfaced and cannot be accepted as a successful credential receipt.
+  for (const name of Object.getOwnPropertyNames(console)) {
+    const value: unknown = Reflect.get(console, name);
+    if (typeof value === "function") Reflect.set(console, name, () => undefined);
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.on("SIGTERM", abort); process.on("SIGINT", abort);
+  const timer = setTimeout(abort, VAULT_IMPORT_TIMEOUT_MS);
+  let result: VaultImportResult = { ok: false, code: "INVALID_IMPORT" };
+  try {
+    const chunks: Buffer[] = []; let size = 0;
+    for await (const chunk of process.stdin) {
+      const bytes = Buffer.from(chunk); size += bytes.byteLength;
+      if (size > 16_384 || controller.signal.aborted) throw new Error();
+      chunks.push(bytes);
+    }
+    const value = readInterfaceJson(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)), 16_384);
+    result = await runCredentialImport(value, process.env, controller.signal);
+  } catch { /* Categorical output only, including SDK and filesystem failures. */ }
+  finally { clearTimeout(timer); process.off("SIGTERM", abort); process.off("SIGINT", abort); }
+  await Bun.write(Bun.stdout, `${JSON.stringify(result)}\n`);
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (import.meta.main) await main();

package/src/control/helper.ts

@@ -0,0 +1,79 @@
+import { createServer, connect, type Socket } from "node:net";
+import { chmodSync, lstatSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonicalJson, sha256 } from "../canonical-json";
+import { captureProcessOwnerIdentity, processOwnerStatus } from "../process-identity";
+import { createPrivateJsonIfAbsent, ensurePrivateStateDirectory, ghostgetStateHome, readPrivateStateFileIfPresent, removePrivateStateFileIfUnchanged, snapshotPrivateStateDirectory, writePrivateJsonIfUnchanged } from "../storage";
+import { controlSocketPath } from "./approval-client";
+import { CONTROL_PROTOCOL, type ApprovalTarget, type JsonValue } from "./protocol";
+import { controlFailure, ControlService } from "./service";
+import { ControlError, controlResponseLine, digest, identifier, integer, keys, nullable, oneOf, parseControlRequest, record, string } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+function parseTarget(value:unknown):ApprovalTarget {
+  const v=record(value);
+  if(v.kind==="web"){keys(v,["kind","method","url"]);return {kind:"web",method:oneOf(v.method,["GET","HEAD"]),url:string(v.url,8192)};}
+  keys(v,["kind","adapterId","operationId","authId","input","planDigest"]);if(v.kind!=="provider")throw new Error("invalid target");
+  // The kernel's operation input parser is authoritative; bound recursive JSON before calling it.
+  const inspect=(item:unknown,depth:number):void=>{if(depth>24)throw new Error("deep input");if(item===null||typeof item==="boolean"||typeof item==="string"||typeof item==="number"&&Number.isFinite(item))return;if(Array.isArray(item)){if(item.length>1024)throw new Error("large input");for(const child of item)inspect(child,depth+1);return;}const object=record(item);if(Object.keys(object).length>256)throw new Error("large input");for(const child of Object.values(object))inspect(child,depth+1);};inspect(v.input,0);
+  return {kind:"provider",adapterId:identifier(v.adapterId),operationId:identifier(v.operationId),authId:nullable(v.authId,128),input:v.input as JsonValue,planDigest:v.planDigest===null?null:digest(v.planDigest)};
+}
+async function handleAgent(value:unknown,service:ControlService,signal:AbortSignal):Promise<unknown> {
+  const v=record(value);
+  if(v.protocol==="ghostget.web/1") {keys(v,["protocol","action","method","url"]);if(v.action!=="request")throw new Error("invalid action");return await service.gateway.run(oneOf(v.method,["GET","HEAD"]),string(v.url,8192),signal);}
+  if(v.protocol!=="ghostget.approval/1")throw new Error("invalid protocol");
+  if(v.action==="request"){keys(v,["protocol","action","id","target","expectedDigest"]);return await service.approvals.request(identifier(v.id),parseTarget(v.target),digest(v.expectedDigest));}
+  keys(v,["protocol","action","id","digest"]);const id=identifier(v.id);const hash=digest(v.digest);
+  if(v.action==="check")return await service.approvals.check(id,hash);
+  if(v.action==="cancel")return service.approvals.cancel(id,hash);
+  throw new Error("invalid action");
+}
+function socketLive(path:string):Promise<boolean> {
+  return new Promise((resolve,reject)=>{const socket=connect({path});const timer=setTimeout(()=>{socket.destroy();reject(new Error("socket state unknown"));},1000);socket.once("connect",()=>{clearTimeout(timer);socket.destroy();resolve(true);});socket.once("error",error=>{clearTimeout(timer);socket.destroy();if((error as NodeJS.ErrnoException).code==="ECONNREFUSED")resolve(false);else reject(new Error("socket state unknown"));});});
+}
+function acquireOwner(environment:ControlEnvironment):()=>void {
+  const directory=join(ghostgetStateHome(environment),"control");ensurePrivateStateDirectory(directory,environment);
+  const path=join(directory,"owner.json");const previous=readPrivateStateFileIfPresent(path,2048,"control owner",environment);
+  if(previous!==null){const v=record(JSON.parse(previous));keys(v,["schema","pid","bootId","processStartId","generation"]);if(v.schema!==1)throw new Error("invalid owner");const owner={pid:integer(v.pid,1,2**31-1),bootId:digest(v.bootId),processStartId:digest(v.processStartId)};identifier(v.generation);if(processOwnerStatus(owner)!=="different-or-dead")throw new ControlError("CONTROL_ALREADY_RUNNING","Ghostget is already open for this state home, or its previous owner cannot be verified.");}
+  const next={schema:1,...captureProcessOwnerIdentity(process.pid),generation:randomUUID()};
+  const acquired=previous===null?createPrivateJsonIfAbsent(path,next,{environment}).created:writePrivateJsonIfUnchanged(path,next,{expectedCurrentContentSha256:sha256(previous)});
+  if(!acquired)throw new ControlError("CONTROL_ALREADY_RUNNING","Another Ghostget app opened this state home.");
+  const expectedCurrentContentSha256=sha256(`${canonicalJson(next)}\n`);
+  return ()=>{removePrivateStateFileIfUnchanged(path,{expectedCurrentContentSha256},environment);};
+}
+
+/** Private native stdio is the only administrative transport. No TCP listener is created. */
+export async function runControlHelper(environment:ControlEnvironment=process.env):Promise<void> {
+  process.umask(0o077);
+  const releaseOwner=acquireOwner(environment);const socketPath=controlSocketPath(environment);const clients=new Set<Socket>();const active=new Set<Promise<void>>();
+  let service:ControlService|undefined;let ownedSocket:{dev:number;ino:number}|undefined;let closing=false;let controlActive=0;
+  const directory=join(ghostgetStateHome(environment),"control");const directoryIdentity=ensurePrivateStateDirectory(directory,environment);
+  const server=createServer(socket=>{
+    if(closing||clients.size>=16||service===undefined){socket.destroy();return;}
+    clients.add(socket);const controller=new AbortController();let buffer=Buffer.alloc(0);let started=false;
+    socket.setTimeout(150_000,()=>socket.destroy());
+    socket.on("close",()=>{controller.abort();clients.delete(socket);});socket.on("error",()=>controller.abort());
+    socket.on("data",chunk=>{
+      if(started){socket.destroy();return;}buffer=Buffer.concat([buffer,typeof chunk==="string"?Buffer.from(chunk):chunk]);if(buffer.length>262144){socket.destroy();return;}const newline=buffer.indexOf(10);if(newline<0)return;
+      started=true;const work=(async()=>{let response:unknown;try{if(newline!==buffer.length-1)throw new Error();response=await handleAgent(JSON.parse(buffer.subarray(0,newline).toString("utf8")),service!,controller.signal);}catch(error){response=controlFailure(error);}if(!socket.destroyed)socket.end(`${JSON.stringify(response)}\n`);})();active.add(work);void work.then(()=>active.delete(work),()=>{active.delete(work);process.exitCode=1;process.stdin.destroy();});
+    });
+  });
+  const shutdown=async()=>{if(closing)return;closing=true;for(const socket of clients)socket.destroy();service?.beginShutdown();await Promise.allSettled(active);service?.close();if(server.listening)await new Promise<void>(resolve=>server.close(()=>resolve()));if(ownedSocket!==undefined){snapshotPrivateStateDirectory(directory,environment,directoryIdentity);try{const stat=lstatSync(socketPath);if(stat.isSocket()&&stat.dev===ownedSocket.dev&&stat.ino===ownedSocket.ino)unlinkSync(socketPath);}catch(error){if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;}}releaseOwner();};
+  const termination=()=>{process.stdin.destroy();};process.once("SIGTERM",termination);process.once("SIGINT",termination);
+  try {
+    if(Buffer.byteLength(socketPath)>100)throw new ControlError("CONTROL_PATH_TOO_LONG","Choose a shorter Ghostget state-home path for the native app.");
+    let stale:ReturnType<typeof lstatSync>|undefined;try{stale=lstatSync(socketPath);}catch(error){if((error as NodeJS.ErrnoException).code!=="ENOENT")throw error;}
+    if(stale!==undefined){if(!stale.isSocket()||stale.uid!==process.getuid?.()||(Number(stale.mode)&0o777)!==0o600||await socketLive(socketPath))throw new ControlError("CONTROL_ALREADY_RUNNING","The control socket is already in use or unsafe.");snapshotPrivateStateDirectory(directory,environment,directoryIdentity);const current=lstatSync(socketPath);if(current.dev!==stale.dev||current.ino!==stale.ino)throw new Error("socket changed");unlinkSync(socketPath);}
+    await new Promise<void>((resolve,reject)=>{server.once("error",reject);server.listen(socketPath,()=>{server.off("error",reject);resolve();});});chmodSync(socketPath,0o600);const socketStat=lstatSync(socketPath);ownedSocket={dev:socketStat.dev,ino:socketStat.ino};
+    service=new ControlService(environment);
+    let buffer=Buffer.alloc(0);
+    for await(const chunk of process.stdin){if(closing)break;buffer=Buffer.concat([buffer,typeof chunk==="string"?Buffer.from(chunk):chunk]);if(buffer.length>4_194_304)throw new Error("control frame too large");let newline:number;
+      while((newline=buffer.indexOf(10))>=0){const frame=buffer.subarray(0,newline);buffer=buffer.subarray(newline+1);if(controlActive>=8)throw new Error("too many control requests");controlActive++;
+        const work=(async()=>{let id="invalid";let response;try{const v=record(JSON.parse(frame.toString("utf8")));keys(v,["id","protocol","request"]);id=identifier(v.id);if(v.protocol!==CONTROL_PROTOCOL)throw new Error("wrong protocol");response=await service!.request(parseControlRequest(v.request));}catch(error){response=controlFailure(error);}const output=controlResponseLine(id,response);if(!closing)process.stdout.write(output);})().finally(()=>{controlActive--;});active.add(work);void work.then(()=>active.delete(work),()=>{active.delete(work);process.exitCode=1;process.stdin.destroy();});
+      }
+    }
+    if(buffer.length!==0)throw new Error("partial control frame");
+  } finally {process.off("SIGTERM",termination);process.off("SIGINT",termination);await shutdown();}
+}
+if(import.meta.main){try{await runControlHelper();}catch{process.stderr.write("Ghostget control helper stopped safely.\n");process.exitCode=1;}}

package/src/control/interface-cli.ts

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+import { providerPluginRegistry } from "../provider-plugins";
+import { createPortableProviderPluginCatalog } from "../provider-plugin-portable-catalog";
+import { readRegularFile } from "../storage";
+import { exportInterfaces, listInterfaces, saveInterface } from "./interfaces";
+import { ControlError, identifier } from "./validation";
+import type { ControlEnvironment } from "./web-policy";
+
+/** Agent editing ends at an inert draft; activation is an explicit native review. */
+export function runInterfaceCommand(args:readonly string[],environment:ControlEnvironment,output:{stdout:(value:string)=>unknown;stderr:(value:string)=>unknown}):number {
+  try {
+    if(args.length===1||args[1]==="--help"){output.stdout("Usage: ghostget interface list\n       ghostget interface export [adapter]\n       ghostget interface import <openapi.json> [--expected-digest <sha256>]\nImport saves an inert draft. Review and activate it in the native app.\n");return 0;}
+    const context={environment,registry:createPortableProviderPluginCatalog(providerPluginRegistry,environment).registry};
+    if(args[1]==="list"&&args.length===2){output.stdout(`${JSON.stringify({interfaces:listInterfaces(context)})}\n`);return 0;}
+    if(args[1]==="export"&&(args.length===2||args.length===3)){output.stdout(exportInterfaces({adapterId:args[2]===undefined?null:identifier(args[2]),...context}).text);return 0;}
+    if(args[1]==="import"&&(args.length===3||args.length===5&&args[3]==="--expected-digest")){
+      const document=readRegularFile(resolve(args[2]!),524288,"OpenAPI interface");
+      const draft=saveInterface({document,source:"user",expectedDigest:args[4]??null,...context});output.stdout(`${JSON.stringify({draft})}\n`);return 0;
+    }
+    throw new ControlError("INVALID_REQUEST","Run ghostget interface --help for the supported draft commands.");
+  } catch(error){output.stderr(`${JSON.stringify({ok:false,code:error instanceof ControlError?error.code:"INTERFACE_INVALID",message:error instanceof ControlError?error.message:"The OpenAPI document, expected revision, or installed semantic binding is invalid. No interface was activated."})}\n`);return 1;}
+}

package/src/control/interface-json.ts

@@ -0,0 +1,94 @@
+/** A bounded JSON reader that also rejects duplicate keys before they can disappear. */
+export function readInterfaceJson(text: string, maximumBytes: number): unknown {
+  if (typeof text !== "string" || Buffer.byteLength(text) > maximumBytes) {
+    throw new Error("interface JSON exceeds its byte limit");
+  }
+  let cursor = 0;
+  let nodes = 0;
+  const whitespace = () => { while (/^[\t\n\r ]$/u.test(text[cursor] ?? "")) cursor++; };
+  const fail = (): never => { throw new Error("interface JSON is malformed"); };
+  const string = (): string => {
+    if (text[cursor++] !== '"') return fail();
+    const start = cursor - 1;
+    while (cursor < text.length) {
+      const character = text[cursor++];
+      if (character === "\\") { cursor++; continue; }
+      if (character === '"') {
+        try { return JSON.parse(text.slice(start, cursor)) as string; } catch { return fail(); }
+      }
+    }
+    return fail();
+  };
+  const value = (depth: number): unknown => {
+    if (++nodes > 50_000 || depth > 24) throw new Error("interface JSON exceeds its structural limit");
+    whitespace();
+    if (text[cursor] === '"') return string();
+    if (text[cursor] === "{") {
+      cursor++;
+      const result: Record<string, unknown> = {};
+      const keys = new Set<string>();
+      whitespace();
+      if (text[cursor] === "}") { cursor++; return result; }
+      for (;;) {
+        whitespace();
+        const key = string();
+        if (keys.has(key)) throw new Error("interface JSON repeats an object key");
+        if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error("interface JSON contains a reserved object key");
+        if (["$ref", "$dynamicRef", "$id", "$schema"].includes(key)) throw new Error("interface JSON references and schema dialect overrides are unsupported");
+        keys.add(key);
+        whitespace();
+        if (text[cursor++] !== ":") return fail();
+        result[key] = value(depth + 1);
+        whitespace();
+        if (text[cursor] === "}") { cursor++; return result; }
+        if (text[cursor++] !== ",") return fail();
+      }
+    }
+    if (text[cursor] === "[") {
+      cursor++;
+      const result: unknown[] = [];
+      whitespace();
+      if (text[cursor] === "]") { cursor++; return result; }
+      for (;;) {
+        result.push(value(depth + 1));
+        whitespace();
+        if (text[cursor] === "]") { cursor++; return result; }
+        if (text[cursor++] !== ",") return fail();
+      }
+    }
+    const token = /^(?:true|false|null|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)/u.exec(text.slice(cursor))?.[0];
+    if (token === undefined) return fail();
+    cursor += token.length;
+    const parsed: unknown = JSON.parse(token);
+    if (typeof parsed === "number" && !Number.isFinite(parsed)) return fail();
+    return parsed;
+  };
+  const parsed = value(0);
+  whitespace();
+  if (cursor !== text.length) return fail();
+  return parsed;
+}
+
+export function interfaceRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+export function interfaceKeys(value: Record<string, unknown>, required: readonly string[], optional: readonly string[], label: string): void {
+  if (required.some((key) => !Object.hasOwn(value, key)) || Object.keys(value).some((key) => !required.includes(key) && !optional.includes(key))) {
+    throw new Error(`${label} contains missing or unsupported fields`);
+  }
+}
+
+export function interfaceText(value: unknown, label: string, maximum = 512): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > maximum || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)) {
+    throw new Error(`${label} must be bounded text`);
+  }
+  return value;
+}
+
+export function interfaceId(value: unknown): string {
+  const id = interfaceText(value, "interface identifier", 48);
+  if (!/^[a-z][a-z0-9-]*$/u.test(id)) throw new Error("interface identifier must be lowercase kebab-case");
+  return id;
+}

package/src/control/interface-schema.ts

@@ -0,0 +1,120 @@
+import { canonicalJson, type InputField, type InputSchema } from "../model";
+import { interfaceKeys, interfaceRecord, interfaceText } from "./interface-json";
+
+type Schema = Record<string, unknown>;
+
+function fieldSchema(field: InputField): Schema {
+  if (field.type === "file") return {
+    type: "object", description: field.description, additionalProperties: false,
+    properties: { kind: { type: "string", const: "file" }, reference: { type: "string", minLength: 1 } },
+    required: ["kind", "reference"],
+    "x-ghostget-file": { maxBytes: field.maxBytes, ...(field.mediaTypes === undefined ? {} : { mediaTypes: field.mediaTypes }) },
+  };
+  if (field.type === "array") return {
+    type: "array", description: field.description, items: fieldSchema(field.items), minItems: field.minItems, maxItems: field.maxItems,
+  };
+  const { format, urlPathPrefixes, ...scalar } = field;
+  return {
+    ...scalar,
+    ...(format === undefined ? {} : { format: format === "url" ? "uri" : "path-segment" }),
+    ...(urlPathPrefixes === undefined ? {} : { "x-ghostget-url-path-prefixes": urlPathPrefixes }),
+  };
+}
+
+export function interfaceInputSchema(input: InputSchema): Schema {
+  return {
+    type: "object", additionalProperties: false,
+    properties: Object.fromEntries(Object.entries(input.properties).sort(([a], [b]) => a.localeCompare(b)).map(([key, field]) => [key, fieldSchema(field)])),
+    required: [...input.required],
+  };
+}
+
+function number(value: unknown, label: string, integer = false): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || (integer && (!Number.isSafeInteger(value) || value < 0))) throw new Error(`${label} must be a bounded number`);
+  return value;
+}
+
+function fieldFromSchema(value: unknown, nested = false): InputField {
+  const field = interfaceRecord(value, "input field schema");
+  const description = interfaceText(field.description, "input field description", 4_096);
+  if (field.type === "object") {
+    interfaceKeys(field, ["type", "description", "additionalProperties", "properties", "required", "x-ghostget-file"], [], "file reference schema");
+    const binding = interfaceRecord(field["x-ghostget-file"], "file reference binding");
+    interfaceKeys(binding, ["maxBytes"], ["mediaTypes"], "file reference binding");
+    const maxBytes = number(binding.maxBytes, "file byte limit", true);
+    let mediaTypes: string[] | undefined;
+    if (binding.mediaTypes !== undefined) {
+      if (!Array.isArray(binding.mediaTypes) || binding.mediaTypes.length > 32) throw new Error("file media types exceed their bound");
+      mediaTypes = binding.mediaTypes.map((entry) => interfaceText(entry, "file media type", 128));
+    }
+    const result: InputField = { type: "file", description, maxBytes, ...(mediaTypes === undefined ? {} : { mediaTypes }) };
+    if (canonicalJson(fieldSchema(result)) !== canonicalJson(field)) throw new Error("file reference schema changed its opaque input contract");
+    return result;
+  }
+  if (field.type === "array") {
+    if (nested) throw new Error("nested input arrays are unsupported");
+    interfaceKeys(field, ["type", "description", "items", "minItems", "maxItems"], [], "array input schema");
+    const items = fieldFromSchema(field.items, true);
+    if (items.type === "array") throw new Error("nested input arrays are unsupported");
+    const minItems = number(field.minItems, "minimum items", true);
+    const maxItems = number(field.maxItems, "maximum items", true);
+    if (minItems > maxItems || maxItems > 10_000) throw new Error("array bounds are invalid");
+    return { type: "array", description, items, minItems, maxItems };
+  }
+  interfaceKeys(field, ["type", "description"], ["minLength", "maxLength", "minimum", "maximum", "enum", "format", "x-ghostget-url-path-prefixes"], "scalar input schema");
+  if (field.type !== "string" && field.type !== "number" && field.type !== "boolean") throw new Error("input field type is unsupported");
+  const result: Record<string, unknown> = { type: field.type, description };
+  for (const key of ["minLength", "maxLength", "minimum", "maximum"] as const) {
+    if (field[key] !== undefined) result[key] = number(field[key], key, key.endsWith("Length"));
+  }
+  if (field.enum !== undefined) {
+    if (!Array.isArray(field.enum) || field.enum.length < 1 || field.enum.length > 256 || field.enum.some((entry) => typeof entry !== field.type)) throw new Error("input enum is invalid");
+    result.enum = field.enum;
+  }
+  if (field.format !== undefined) {
+    if (field.type !== "string" || (field.format !== "uri" && field.format !== "path-segment")) throw new Error("input format is unsupported");
+    result.format = field.format === "uri" ? "url" : "path-segment";
+  }
+  if (field["x-ghostget-url-path-prefixes"] !== undefined) {
+    const prefixes = field["x-ghostget-url-path-prefixes"];
+    if (field.format !== "uri" || !Array.isArray(prefixes) || prefixes.length > 64) throw new Error("URL path prefixes are invalid");
+    result.urlPathPrefixes = prefixes.map((entry) => interfaceText(entry, "URL path prefix", 2_048));
+  }
+  return result as InputField;
+}
+
+export function inputFromInterfaceSchema(value: unknown): InputSchema {
+  const schema = interfaceRecord(value, "operation input schema");
+  interfaceKeys(schema, ["type", "properties", "required", "additionalProperties"], [], "operation input schema");
+  if (schema.type !== "object" || schema.additionalProperties !== false) throw new Error("operation input requires a closed object schema");
+  const properties = interfaceRecord(schema.properties, "input properties");
+  if (Object.keys(properties).length > 128) throw new Error("input properties exceed their bound");
+  if (!Array.isArray(schema.required) || schema.required.length > 128) throw new Error("required inputs exceed their bound");
+  const required = schema.required.map((entry) => interfaceText(entry, "required input", 128));
+  if (new Set(required).size !== required.length || required.some((key) => !Object.hasOwn(properties, key))) throw new Error("required inputs are duplicate or missing");
+  return {
+    properties: Object.fromEntries(Object.entries(properties).map(([key, field]) => {
+      if (!/^[a-z][a-z0-9_]{0,127}$/u.test(key)) throw new Error("input field name is invalid");
+      return [key, fieldFromSchema(field)];
+    })),
+    required,
+  };
+}
+
+/** Generic inert schemas are validated, never resolved or compiled into code. */
+export function validateInertInterfaceSchema(value: unknown): void {
+  const schema = interfaceRecord(value, "OpenAPI schema");
+  interfaceKeys(schema, [], ["type", "description", "properties", "required", "additionalProperties", "items", "enum", "const", "format", "minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems", "x-ghostget-file", "x-ghostget-url-path-prefixes"], "OpenAPI schema");
+  if (schema.type !== undefined && !["object", "array", "string", "number", "integer", "boolean", "null"].includes(String(schema.type))) throw new Error("OpenAPI schema type is unsupported");
+  if (schema.description !== undefined) interfaceText(schema.description, "schema description", 4_096);
+  if (schema.properties !== undefined) {
+    const properties = interfaceRecord(schema.properties, "schema properties");
+    if (Object.keys(properties).length > 128) throw new Error("schema properties exceed their bound");
+    Object.values(properties).forEach(validateInertInterfaceSchema);
+  }
+  if (schema.items !== undefined) validateInertInterfaceSchema(schema.items);
+  if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") throw new Error("schema additionalProperties must be boolean");
+  for (const key of ["minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems"] as const) if (schema[key] !== undefined) number(schema[key], key, !["minimum", "maximum"].includes(key));
+  if (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.length > 128 || schema.required.some((entry) => typeof entry !== "string"))) throw new Error("schema required is invalid");
+  if (schema.enum !== undefined && (!Array.isArray(schema.enum) || schema.enum.length > 256)) throw new Error("schema enum is invalid");
+}