witnora 0.10.4 → 0.12.0

package/README.md

@@ -13,18 +13,21 @@ outcome. It writes portable reports and accumulates a local failure corpus.
 
 ## 5-minute hosted path
 
-Create a Hosted project, open a terminal in the agent repository, and run the
-one command shown by Witnora:
+Create a Hosted project. The Setup Wizard pre-fills a metadata-only plan and
+asks for two decisions: **Confirm plan** and **Authorize install**. Then open a
+terminal in the agent repository and run the one command shown by Witnora:
 
 ```bash
 npx witnora@latest onboard --project your-project-id
 ```
 
-The browser approval creates a restricted project credential without exposing
-it in Hosted, then the CLI saves it outside the repository, detects the agent
-boundary, writes only missing configuration, and verifies the local evidence
-path. `.witnora/onboarding/receipt.json` is synthetic: it cannot create a run,
-evidence object, release decision, or `CURRENT` assurance.
+The browser approval creates one restricted project credential, then the CLI
+saves it outside the repository, detects capability groups, and installs only
+missing Gateway, outcome-probe, CI, policy, review, configuration, and boundary
+files. It verifies each component and reports progress to Hosted. A failed
+attempt removes only files created by that attempt. The onboarding receipt is
+synthetic: it cannot create a run, evidence object, release decision, or
+`CURRENT` assurance.
 
 Onboarding also performs the default private capability discovery locally. It
 does not read source-file contents or upload source code, prompt text,
@@ -40,12 +43,42 @@ Customers that do not permit repository metadata inspection can choose
 runtime-only discovery in Hosted. Source-assisted analysis is a separate,
 explicit GitHub authorization and is never enabled implicitly.
 
+### Customer-owned Gateway
+
+The default Setup Wizard installs a durable customer-owned Gateway beside the
+Agent automatically. Start it, then run the Agent's normal sandbox workflow:
+
+```bash
+npx witnora@latest gateway run
+```
+
+Initialization writes a reusable `.witnora/gateway/client.mjs`. Import its
+`witnoraGateway.start`, `event`, and `complete` methods at one existing sandbox
+workflow boundary. The generated README contains the exact code and privacy
+boundary; no Hosted key or source-signing key is written into the repository.
+
+The browser approval issues one bounded credential for setup, evidence, the
+customer-owned recorder, and covered runtime actions. It has no team,
+retention, administrative, target-system, or customer-data permissions. The
+Hosted key is stored in the user's Witnora credential directory; the repository
+contains only metadata-only config plus ignored local secrets and queue data.
+This reference path establishes **RECORDED** evidence.
+It does not claim **ENFORCED** until target write credentials are placed behind a
+controlled execution adapter, or **OUTCOME VERIFIED** until an independent
+read-only probe checks the target state.
+
+Enterprises that require self-hosted or manual component control can use the
+individual `gateway init`, `gateway doctor`, policy, probe, CI, and review
+commands under Hosted **Advanced**. They are not part of the default customer
+journey.
+
 After the connection self-test, Hosted shows one template-specific next step.
-Place the generated boundary in one meaningful sandbox workflow and run it
-normally. The generated local adapter reuses the saved restricted connection;
-CI and production should use the same project-scoped values from a secret
-manager. The first non-synthetic run completes onboarding, but remains
-`reported` evidence and does not establish a release decision or `CURRENT`.
+Place the generated Gateway client at one meaningful sandbox boundary and run
+it normally. The Gateway reuses the saved restricted connection; CI and
+production should use the same project-scoped values from a secret manager.
+Only a source-signed Gateway run whose journal is reconciled by Hosted completes
+onboarding. A direct run is still visible, but cannot verify the Gateway or
+establish a release decision or `CURRENT` assurance.
 
 Without an agent repository, run `npx witnora@latest try --template workflow`
 for an offline-only sample.

package/dist/cli.js

@@ -38,6 +38,7 @@ import { runDesignPartnerCommand } from "./design-partner-v02.js";
 import { runOnboard } from "./onboard.js";
 import { inspectRepository } from "./onboard.js";
 import { runPrivateCapabilityDiscovery } from "./private-discovery.js";
+import { doctorCustomerGateway, initializeCustomerGateway, renderGatewayDoctor, runCustomerGateway } from "./gateway.js";
 import { verifyEvidencePacketV02 } from "./evidence-v02.js";
 process.on("uncaughtException", reportFatalError);
 process.on("unhandledRejection", reportFatalError);
@@ -157,6 +158,35 @@ else if (command === "onboard") {
         openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
     });
 }
+else if (command === "gateway") {
+    const action = process.argv[3] ?? "help";
+    if (action === "init") {
+        const projectId = readFlag("--project") ?? brandedEnvironment("PROJECT_ID");
+        if (!projectId)
+            throw new Error("--project <project-id> is required.");
+        await initializeCustomerGateway({
+            projectId,
+            server: readFlag("--server") ?? brandedEnvironment("BASE_URL") ?? DEFAULT_WITNORA_SERVER,
+            repository: readFlag("--repo") ?? process.cwd(),
+            outDir: readFlag("--dir"),
+            connectionName: readFlag("--name"),
+            force: readBoolFlag("--force"),
+            openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
+        });
+    }
+    else if (action === "doctor") {
+        const result = await doctorCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+        process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderGatewayDoctor(result));
+        if (result.overall !== "READY_TO_RECORD")
+            process.exitCode = 1;
+    }
+    else if (action === "run") {
+        await runCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+    }
+    else {
+        throw new Error("Use witnora gateway init|doctor|run.");
+    }
+}
 else if (command === "discover") {
     const connectionName = readFlag("--connection");
     const connection = await resolveConnection({

package/dist/command-help.js

@@ -32,6 +32,31 @@ Options:
   --repo <directory>      Repository to configure (default: current directory)
   --template <type>       Override automatic repository detection
   --no-browser            Print the approval URL without opening it
+`;
+    if (command === "gateway")
+        return `Usage:
+  witnora gateway init --project <project-id>
+  witnora gateway doctor
+  witnora gateway run
+
+Initializes and runs a customer-owned, metadata-only collector beside the Agent.
+The browser approval issues a collector-scoped credential; no API key is copied into
+the repository or exposed to the Agent. The local queue and source signing key remain
+under customer control.
+
+The reference Gateway establishes RECORDED evidence only. ENFORCED requires target
+write credentials behind a controlled execution adapter. OUTCOME VERIFIED requires a
+separate read-only probe.
+
+Options:
+  --server <url>          Hosted server (default: https://witnora.com)
+  --project <id>          Project to authorize (required for init)
+  --repo <directory>      Agent repository (default: current directory)
+  --dir <directory>       Gateway directory (default: .witnora/gateway)
+  --name <name>           Saved collector connection name
+  --no-browser            Print the approval URL without opening it
+  --force                 Replace an existing reviewed local setup
+  --json                  JSON doctor output
 `;
     if (command === "design-partner")
         return `Usage:

package/dist/device-authorization.js

@@ -0,0 +1,69 @@
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { DEFAULT_WITNORA_SERVER, saveConnection } from "./credentials.js";
+export async function authorizeProjectConnection(options) {
+    const requestFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolveWait) => setTimeout(resolveWait, milliseconds)));
+    const output = options.output ?? ((message) => process.stdout.write(message));
+    const server = normalizeServer(options.server ?? DEFAULT_WITNORA_SERVER);
+    const codeVerifier = randomBytes(48).toString("base64url");
+    const codeChallengeSha256 = createHash("sha256").update(codeVerifier).digest("hex");
+    const device = await jsonRequest(requestFetch, `${server}/v1/onboarding/device-authorizations`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            projectId: options.projectId,
+            connectionName: options.connectionName,
+            credentialProfile: options.credentialProfile ?? "repository",
+            codeChallengeSha256,
+        }),
+    });
+    output(`Authorize Witnora in your browser:\n  ${device.verificationUriComplete}\nCode: ${device.userCode}\n`);
+    await (options.openBrowser ?? openSystemBrowser)(device.verificationUriComplete);
+    const token = await waitForToken(requestFetch, server, device, codeVerifier, sleep, options.timeoutMs ?? device.expiresIn * 1_000);
+    const credentialsPath = await saveConnection(token.connectionName, {
+        server,
+        projectId: token.projectId,
+        apiKey: token.apiKey,
+    }, { configHome: options.configHome });
+    return { ...token, server, credentialsPath };
+}
+async function waitForToken(requestFetch, server, device, codeVerifier, sleep, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const response = await requestFetch(`${server}/v1/onboarding/device-authorizations/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ deviceCode: device.deviceCode, codeVerifier }),
+        });
+        const body = await response.json().catch(() => ({}));
+        if (response.ok)
+            return body;
+        if (response.status !== 428 || body.code !== "authorization_pending") {
+            throw new Error(String(body.error ?? `Device authorization failed with HTTP ${response.status}.`));
+        }
+        await sleep(Math.max(1, device.interval) * 1_000);
+    }
+    throw new Error("Device authorization timed out. Run the command again to create a new one-time request.");
+}
+async function jsonRequest(requestFetch, url, init) {
+    const response = await requestFetch(url, init);
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(String(body.error ?? `${init.method ?? "GET"} ${url} failed with HTTP ${response.status}.`));
+    return body;
+}
+async function openSystemBrowser(url) {
+    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+}
+function normalizeServer(value) {
+    const url = new URL(value);
+    const loopback = new Set(["localhost", "127.0.0.1", "[::1]"]).has(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error("Witnora server must use HTTPS. Plain HTTP is allowed only for localhost development.");
+    }
+    return url.toString().replace(/\/$/, "");
+}

package/dist/gateway.js

@@ -0,0 +1,256 @@
+import { randomBytes } from "node:crypto";
+import { access, chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { loadConnection } from "./credentials.js";
+import { authorizeProjectConnection } from "./device-authorization.js";
+const CONFIG_SCHEMA = "witnora.customer_gateway_setup.v0.1";
+const SECRETS_SCHEMA = "witnora.customer_gateway_local_secrets.v0.1";
+export async function initializeCustomerGateway(options) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const outDir = resolve(repository, options.outDir ?? ".witnora/gateway");
+    const output = options.output ?? ((message) => process.stdout.write(message));
+    const slug = safeSlug(basename(repository));
+    const connectionName = options.connectionName ?? `${slug}-gateway`;
+    const [configPath, secretsPath, gitignorePath, clientPath, readmePath] = gatewayPaths(outDir);
+    if (!(options.force ?? false)) {
+        const { existing } = await inspectCustomerGatewayFiles({ repository, outDir });
+        if (existing.length > 0) {
+            throw new Error(`Gateway setup already exists at ${existing.join(", ")}. Use --force only after reviewing the existing local setup.`);
+        }
+    }
+    const authorization = options.authorization
+        ? options.authorization
+        : await authorizeProjectConnection({
+            projectId: options.projectId,
+            connectionName,
+            credentialProfile: "customer_gateway",
+            server: options.server,
+            openBrowser: options.openBrowser,
+            fetch: options.fetch,
+            sleep: options.sleep,
+            timeoutMs: options.timeoutMs,
+            output,
+            configHome: options.configHome,
+        });
+    const expectedScopes = ["runs:read", "events:write", "collector:manage"];
+    const missingScopes = expectedScopes.filter((scope) => !authorization.scopes.includes(scope));
+    if (missingScopes.length > 0)
+        throw new Error(`Gateway authorization is missing required scope(s): ${missingScopes.join(", ")}.`);
+    const config = {
+        schemaVersion: CONFIG_SCHEMA,
+        projectId: authorization.projectId,
+        server: authorization.server,
+        connectionName: authorization.connectionName,
+        collectorId: `${slug}-collector`,
+        host: process.env.WITNORA_GATEWAY_HOST?.trim() || "127.0.0.1",
+        port: gatewayPort(process.env.WITNORA_GATEWAY_PORT, 8787),
+        storageDirectory: "data",
+        privacyMode: "metadata_only",
+        coverage: { recorded: "configured", enforced: "not_configured", outcomeVerified: "not_configured" },
+    };
+    const secrets = {
+        schemaVersion: SECRETS_SCHEMA,
+        gatewayToken: randomBytes(32).toString("base64url"),
+    };
+    await mkdir(outDir, { recursive: true });
+    const generatedFiles = [];
+    const force = options.force ?? false;
+    try {
+        for (const [path, content, mode] of [
+            [configPath, `${JSON.stringify(config, null, 2)}\n`, 0o644],
+            [secretsPath, `${JSON.stringify(secrets, null, 2)}\n`, 0o600],
+            [gitignorePath, "secrets.json\ndata/\n", 0o644],
+            [clientPath, gatewayClient(config), 0o644],
+            [readmePath, gatewayReadme(config), 0o644],
+        ]) {
+            await writeExclusive(path, content, force, mode);
+            if (!force)
+                generatedFiles.push(path);
+        }
+    }
+    catch (error) {
+        if (!force) {
+            for (const path of [...generatedFiles].reverse())
+                await rm(path, { force: true }).catch(() => undefined);
+        }
+        throw error;
+    }
+    output("\nCustomer-owned Gateway initialized.\n");
+    output(`Configuration: ${configPath}\nLocal secret: ${secretsPath} (never commit or upload)\n`);
+    output("Next:\n");
+    output("  1. Run: npx witnora@latest gateway doctor\n");
+    output("  2. Run: npx witnora@latest gateway run\n");
+    output("  3. Import .witnora/gateway/client.mjs at one sandbox workflow boundary.\n");
+    output("  4. Run that workflow normally; start, event, and complete are recorded locally.\n");
+    output("This reference path establishes RECORDED evidence only. ENFORCED requires target write credentials behind a controlled execution adapter; OUTCOME VERIFIED requires a separate read-only probe.\n");
+    return { configPath, secretsPath, config, generatedFiles };
+}
+export async function inspectCustomerGatewayFiles(options) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const directory = resolve(repository, options.outDir ?? ".witnora/gateway");
+    const paths = gatewayPaths(directory);
+    const states = await Promise.all(paths.map(async (path) => ({ path, exists: await exists(path) })));
+    const existing = states.filter((item) => item.exists).map((item) => item.path);
+    const missing = states.filter((item) => !item.exists).map((item) => item.path);
+    return {
+        status: existing.length === 0 ? "absent" : missing.length === 0 ? "complete" : "partial",
+        directory,
+        paths,
+        existing,
+        missing,
+    };
+}
+export async function doctorCustomerGateway(options) {
+    const directory = resolve(options.repository ?? process.cwd(), options.dir ?? ".witnora/gateway");
+    const checks = [];
+    let config;
+    let secrets;
+    try {
+        config = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
+        checks.push({ id: "configuration", status: "PASS", message: "Gateway configuration is valid and metadata-only." });
+    }
+    catch (error) {
+        checks.push({ id: "configuration", status: "FAIL", message: message(error) });
+    }
+    try {
+        secrets = parseSecrets(await readFile(join(directory, "secrets.json"), "utf8"));
+        checks.push({ id: "local_auth", status: "PASS", message: "A local Gateway token is present in the ignored customer-owned secret file." });
+    }
+    catch (error) {
+        checks.push({ id: "local_auth", status: "FAIL", message: message(error) });
+    }
+    if (config) {
+        try {
+            const connection = await loadConnection(config.connectionName, { configHome: options.configHome });
+            if (!connection || connection.projectId !== config.projectId || connection.server !== config.server)
+                throw new Error("The saved Gateway credential does not match gateway.json.");
+            checks.push({ id: "hosted_credential", status: "PASS", message: "The collector-scoped Hosted credential is stored outside the repository." });
+        }
+        catch (error) {
+            checks.push({ id: "hosted_credential", status: "FAIL", message: message(error) });
+        }
+        try {
+            const response = await (options.fetch ?? fetch)(`http://${config.host}:${config.port}/healthz`, { signal: AbortSignal.timeout(800) });
+            if (!response.ok)
+                throw new Error(`Gateway health returned HTTP ${response.status}.`);
+            checks.push({ id: "process", status: "PASS", message: `Gateway is listening at http://${config.host}:${config.port}.` });
+        }
+        catch {
+            checks.push({ id: "process", status: "WARN", message: "Gateway is not running yet. Start it with `witnora gateway run`." });
+        }
+    }
+    if (config && secrets) {
+        checks.push({ id: "enforcement", status: "WARN", message: "Write-credential mediation is not configured; current evidence ceiling is RECORDED." });
+        checks.push({ id: "outcome_probe", status: "WARN", message: "An independent read-only outcome probe is not configured." });
+    }
+    const failed = checks.some((check) => check.status === "FAIL");
+    return {
+        schemaVersion: "witnora.customer_gateway_doctor.v0.1",
+        overall: failed ? "SETUP_INCOMPLETE" : "READY_TO_RECORD",
+        checks,
+        evidenceCeiling: "recorded",
+        nextAction: failed ? "Run `witnora gateway init --project <project-id>` again after resolving failed checks." : "Start the Gateway, then send one sandbox run through its local event API.",
+    };
+}
+export async function runCustomerGateway(options) {
+    const { CustomerSourceKeyRing, RemoteCollectorClient, startCustomerOwnedCollectorGateway, } = await import("agentcert-sdk");
+    const directory = resolve(options.repository ?? process.cwd(), options.dir ?? ".witnora/gateway");
+    const config = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
+    const secrets = parseSecrets(await readFile(join(directory, "secrets.json"), "utf8"));
+    const connection = await loadConnection(config.connectionName, { configHome: options.configHome });
+    if (!connection || connection.projectId !== config.projectId || connection.server !== config.server) {
+        throw new Error("The saved Gateway credential does not match gateway.json. Run gateway init again.");
+    }
+    const dataDirectory = resolve(directory, config.storageDirectory);
+    const keyRingPath = join(dataDirectory, "source-keys.json");
+    const keyRing = await (await exists(keyRingPath)
+        ? CustomerSourceKeyRing.open(keyRingPath)
+        : CustomerSourceKeyRing.create(keyRingPath, config.collectorId));
+    const gateway = await startCustomerOwnedCollectorGateway({
+        client: new RemoteCollectorClient({ baseUrl: connection.server, projectId: connection.projectId, apiKey: connection.apiKey }),
+        keyRing,
+        gatewayToken: secrets.gatewayToken,
+        storageDirectory: dataDirectory,
+        host: process.env.WITNORA_GATEWAY_HOST?.trim() || config.host,
+        port: gatewayPort(process.env.WITNORA_GATEWAY_PORT, config.port),
+        environment: "customer-owned",
+    });
+    process.stdout.write(`Witnora customer-owned Gateway listening on ${gateway.baseUrl}\n`);
+    process.stdout.write("Evidence ceiling: RECORDED. No target write credential or outcome-probe credential is loaded by this reference process.\n");
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.once(signal, () => void gateway.close().finally(() => process.exit(0)));
+    }
+}
+export function renderGatewayDoctor(result) {
+    return [
+        `Customer-owned Gateway: ${result.overall}`,
+        ...result.checks.map((check) => `${check.status.padEnd(4)} ${check.id}: ${check.message}`),
+        `Evidence ceiling: ${result.evidenceCeiling.toUpperCase()}`,
+        `Next: ${result.nextAction}`,
+        "",
+    ].join("\n");
+}
+function parseConfig(raw) {
+    const value = JSON.parse(raw);
+    if (value.schemaVersion !== CONFIG_SCHEMA || !value.projectId || !value.server || !value.connectionName || !value.collectorId) {
+        throw new Error("gateway.json is missing required Witnora Gateway fields.");
+    }
+    if (value.privacyMode !== "metadata_only")
+        throw new Error("Gateway privacyMode must remain metadata_only.");
+    if (!value.host || !Number.isSafeInteger(value.port) || Number(value.port) < 1 || Number(value.port) > 65_535)
+        throw new Error("Gateway host and port are invalid.");
+    return value;
+}
+function parseSecrets(raw) {
+    const value = JSON.parse(raw);
+    if (value.schemaVersion !== SECRETS_SCHEMA || typeof value.gatewayToken !== "string" || value.gatewayToken.length < 32) {
+        throw new Error("secrets.json is missing a valid local Gateway token.");
+    }
+    return value;
+}
+function gatewayPort(value, fallback) {
+    if (!value?.trim())
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+        throw new Error("WITNORA_GATEWAY_PORT must be an integer between 1 and 65535.");
+    }
+    return parsed;
+}
+function gatewayReadme(config) {
+    return `# Witnora customer-owned Gateway\n\nThis directory configures a metadata-only Gateway for project \`${config.projectId}\`.\n\n## Start the Gateway\n\n\`\`\`bash\nnpx witnora@latest gateway doctor\nnpx witnora@latest gateway run\n\`\`\`\n\nKeep \`gateway run\` open. In the Agent repository, import the generated client at one meaningful sandbox workflow boundary:\n\n\`\`\`js\nimport { randomUUID } from "node:crypto";\nimport { witnoraGateway } from "./.witnora/gateway/client.mjs";\n\nconst runId = randomUUID();\nawait witnoraGateway.start(runId, { workflow: "sandbox-workflow" });\ntry {\n  // Run the existing customer workflow here. Do not add raw inputs or outputs.\n  await witnoraGateway.event(runId, "workflow.step.completed", { step: "meaningful-boundary" });\n  await witnoraGateway.complete(runId, { status: "completed" });\n} catch (error) {\n  await witnoraGateway.event(runId, "workflow.failed", { errorType: error?.name ?? "Error" });\n  await witnoraGateway.complete(runId, { status: "failed" });\n  throw error;\n}\n\`\`\`\n\nThe generated client reads only the local ignored Gateway token and sends metadata to \`http://${config.host}:${config.port}\`. The Hosted API key and source-signing key stay in the Gateway process. Do not commit \`secrets.json\` or \`data/\`.\n\nThis reference process creates source-signed, durable **RECORDED** evidence. It does not claim complete mediation. **ENFORCED** requires the target write credential to be removed from the Agent and placed behind a controlled execution adapter. **OUTCOME VERIFIED** requires a separate read-only credential and independent probe.\n`;
+}
+function gatewayClient(config) {
+    return `import { readFile } from "node:fs/promises";\n\nconst baseUrl = "http://${config.host}:${config.port}";\nlet gatewayToken;\n\nasync function token() {\n  if (gatewayToken) return gatewayToken;\n  const secrets = JSON.parse(await readFile(new URL("./secrets.json", import.meta.url), "utf8"));\n  if (typeof secrets.gatewayToken !== "string" || secrets.gatewayToken.length < 32) {\n    throw new Error("Witnora local Gateway token is missing or invalid.");\n  }\n  gatewayToken = secrets.gatewayToken;\n  return gatewayToken;\n}\n\nasync function post(runId, operation, body) {\n  if (!/^[A-Za-z0-9._:-]+$/.test(runId)) throw new Error("Witnora runId contains unsupported characters.");\n  const response = await fetch(\`\${baseUrl}/v1/runs/\${encodeURIComponent(runId)}/\${operation}\`, {\n    method: "POST",\n    headers: { authorization: \`Bearer \${await token()}\`, "content-type": "application/json" },\n    body: JSON.stringify(body),\n  });\n  const result = await response.json().catch(() => ({}));\n  if (!response.ok) throw new Error(result.error ?? \`Witnora Gateway returned HTTP \${response.status}.\`);\n  return result;\n}\n\nexport const witnoraGateway = {\n  start(runId, metadata = {}) {\n    return post(runId, "start", { payload: metadata, idempotencyKey: "run-start" });\n  },\n  event(runId, type, metadata = {}, idempotencyKey = \`\${type}-\${crypto.randomUUID()}\`) {\n    return post(runId, "events", { type, payload: metadata, idempotencyKey });\n  },\n  complete(runId, metadata = {}) {\n    return post(runId, "complete", {\n      payload: metadata,\n      evidenceStrength: {\n        schemaVersion: "agentcert.evidence_strength.v0.1",\n        level: "recorded",\n        claims: [],\n        limitations: ["No write-credential mediation or independent outcome probe is configured."],\n      },\n      idempotencyKey: "run-complete",\n    });\n  },\n};\n`;
+}
+async function writeExclusive(path, content, force, mode) {
+    if (!force && await exists(path))
+        throw new Error(`${path} already exists. Use --force only after reviewing the existing local Gateway setup.`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, { encoding: "utf8", mode });
+    await chmod(path, mode).catch(() => undefined);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function gatewayPaths(directory) {
+    return [
+        join(directory, "gateway.json"),
+        join(directory, "secrets.json"),
+        join(directory, ".gitignore"),
+        join(directory, "client.mjs"),
+        join(directory, "README.md"),
+    ];
+}
+function safeSlug(value) {
+    return (value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "agent-repository").slice(0, 48);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/onboard.js

@@ -1,80 +1,152 @@
-import { createHash, randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
-import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { DEFAULT_WITNORA_SERVER, saveConnection } from "./credentials.js";
+import { DEFAULT_WITNORA_SERVER } from "./credentials.js";
+import { authorizeProjectConnection } from "./device-authorization.js";
 import { verifyControlPlaneConnection } from "./control-plane.js";
 import { inferPrivateCapabilities, runPrivateCapabilityDiscovery } from "./private-discovery.js";
-import { parseAgentTemplate, starterAdapter, starterInstructions, starterProfile, starterTripwireConfig } from "./onboarding-templates.js";
+import { parseAgentTemplate, starterAdapter, starterProfile, starterTripwireConfig } from "./onboarding-templates.js";
 import { writeTryEvidence } from "./try.js";
+import { doctorCustomerGateway, initializeCustomerGateway, inspectCustomerGatewayFiles } from "./gateway.js";
 export async function runOnboard(options) {
     const requestFetch = options.fetch ?? fetch;
-    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolveWait) => setTimeout(resolveWait, milliseconds)));
     const output = options.output ?? ((message) => process.stdout.write(message));
     const server = normalizeServer(options.server ?? DEFAULT_WITNORA_SERVER);
     const repositoryPath = resolve(options.repository ?? process.cwd());
     const repository = await inspectRepository(repositoryPath, options.template);
     const connectionName = options.name ?? repository.slug;
-    const codeVerifier = randomBytes(48).toString("base64url");
-    const codeChallengeSha256 = createHash("sha256").update(codeVerifier).digest("hex");
-    const device = await jsonRequest(requestFetch, `${server}/v1/onboarding/device-authorizations`, {
-        method: "POST", headers: { "content-type": "application/json" },
-        body: JSON.stringify({ projectId: options.projectId, connectionName, codeChallengeSha256 }),
+    const token = await authorizeProjectConnection({
+        projectId: options.projectId,
+        connectionName,
+        credentialProfile: "autopilot",
+        server,
+        openBrowser: options.openBrowser,
+        fetch: requestFetch,
+        sleep: options.sleep,
+        timeoutMs: options.timeoutMs,
+        output,
+        configHome: options.configHome,
     });
-    output(`Authorize Witnora in your browser:\n  ${device.verificationUriComplete}\nCode: ${device.userCode}\n`);
-    await (options.openBrowser ?? openSystemBrowser)(device.verificationUriComplete);
-    const token = await waitForToken(requestFetch, server, device, codeVerifier, sleep, options.timeoutMs ?? device.expiresIn * 1_000);
-    const credentialsPath = await saveConnection(token.connectionName, { server, projectId: token.projectId, apiKey: token.apiKey }, { configHome: options.configHome });
+    const credentialsPath = token.credentialsPath;
     await verifyControlPlaneConnection({ baseUrl: server, projectId: token.projectId, apiKey: token.apiKey, fetch: requestFetch });
-    const generatedFiles = await generateRepositoryConfig(repositoryPath, repository.template, repository.name);
-    const selfTest = await writeTryEvidence({
-        template: repository.template,
-        subject: `witnora-onboarding-${repository.slug}`,
-        outDir: join(repositoryPath, ".witnora", "onboarding", "self-test"),
+    const planSnapshot = await jsonRequest(requestFetch, `${server}/v1/projects/${encodeURIComponent(token.projectId)}/setup-plans`, {
+        method: "GET", headers: { authorization: `Bearer ${token.apiKey}` },
     });
-    const bundleBytes = Buffer.from(`${JSON.stringify(selfTest.bundle, null, 2)}\n`);
-    const receipt = await jsonRequest(requestFetch, `${server}/v1/projects/${encodeURIComponent(token.projectId)}/onboarding/self-test`, {
-        method: "POST", headers: { authorization: `Bearer ${token.apiKey}`, "content-type": "application/json" },
-        body: JSON.stringify({
+    const setupPlan = planSnapshot.plan;
+    if (!setupPlan || !setupPlan.authorizedOperations.some((item) => item.kind === "authorize_install")) {
+        throw new Error("Confirm the Setup Plan and authorize installation in the Witnora Workspace before running onboard.");
+    }
+    const attemptId = `install-${Date.now()}-${randomSuffix()}`;
+    const generatedFiles = [];
+    await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, { status: "installing", attemptId });
+    try {
+        generatedFiles.push(...await generateRepositoryConfig(repositoryPath, repository.template, repository.name));
+        const selfTestDir = join(repositoryPath, ".witnora", "onboarding", "self-test", attemptId);
+        const selfTest = await writeTryEvidence({
             template: repository.template,
-            repository: { kind: repository.kind, name: repository.name, fingerprintSha256: repository.fingerprintSha256 },
-            bundleSha256: createHash("sha256").update(bundleBytes).digest("hex"),
-        }),
-    });
-    const receiptPath = join(repositoryPath, ".witnora", "onboarding", "receipt.json");
-    await mkdir(dirname(receiptPath), { recursive: true });
-    await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
-    const discovery = await runPrivateCapabilityDiscovery({
-        connection: { server, projectId: token.projectId, apiKey: token.apiKey },
-        repository,
-        connectionName: token.connectionName,
-        configHome: options.configHome,
-        fetch: requestFetch,
-    });
-    output(`\nConnected ${repository.name} to Witnora.\n`);
-    output(`Project: ${token.projectId}\nTemplate: ${repository.template} (${repository.kind})\n`);
-    output(`Credentials: ${credentialsPath}\nSelf-test receipt: ${receiptPath}\n`);
-    output(`Private discovery: ${discovery.capabilityCount} capability group(s); source code, prompts, credentials, and payloads stayed local.\n`);
-    output("The synthetic self-test verified the local evidence path. It did not create a run, evidence object, release decision, or CURRENT assurance.\n");
-    output(starterInstructions(repository.template, repository.name));
-    return { projectId: token.projectId, connectionName: token.connectionName, credentialsPath, template: repository.template,
-        repositoryKind: repository.kind, generatedFiles, receiptPath, discovery };
-}
-async function waitForToken(requestFetch, server, device, codeVerifier, sleep, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const response = await requestFetch(`${server}/v1/onboarding/device-authorizations/token`, {
-            method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ deviceCode: device.deviceCode, codeVerifier }),
+            subject: `witnora-onboarding-${repository.slug}`,
+            outDir: selfTestDir,
+        });
+        generatedFiles.push(selfTestDir);
+        const bundleBytes = Buffer.from(`${JSON.stringify(selfTest.bundle, null, 2)}\n`);
+        const receipt = await jsonRequest(requestFetch, `${server}/v1/projects/${encodeURIComponent(token.projectId)}/onboarding/self-test`, {
+            method: "POST", headers: { authorization: `Bearer ${token.apiKey}`, "content-type": "application/json" },
+            body: JSON.stringify({
+                template: repository.template,
+                repository: { kind: repository.kind, name: repository.name, fingerprintSha256: repository.fingerprintSha256 },
+                bundleSha256: createHash("sha256").update(bundleBytes).digest("hex"),
+            }),
+        });
+        const receiptPath = join(repositoryPath, ".witnora", "onboarding", "receipts", `${attemptId}.json`);
+        await mkdir(dirname(receiptPath), { recursive: true });
+        await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+        generatedFiles.push(receiptPath);
+        const legacyReceiptPath = join(repositoryPath, ".witnora", "onboarding", "receipt.json");
+        if (!await exists(legacyReceiptPath)) {
+            await writeFile(legacyReceiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+            generatedFiles.push(legacyReceiptPath);
+        }
+        const discovery = await runPrivateCapabilityDiscovery({
+            connection: { server, projectId: token.projectId, apiKey: token.apiKey },
+            repository,
+            connectionName: token.connectionName,
+            configHome: options.configHome,
+            fetch: requestFetch,
+        });
+        const gatewayState = await inspectCustomerGatewayFiles({ repository: repositoryPath });
+        if (gatewayState.status === "partial") {
+            throw new Error(`Existing Gateway setup is incomplete. Preserve the existing files and repair or remove the partial setup in Advanced mode. Missing: ${gatewayState.missing.map((path) => basename(path)).join(", ")}.`);
+        }
+        if (gatewayState.status === "absent") {
+            const gateway = await initializeCustomerGateway({
+                projectId: token.projectId, server, repository: repositoryPath, authorization: token,
+                fetch: requestFetch, configHome: options.configHome, output,
+            });
+            generatedFiles.push(...gateway.generatedFiles);
+        }
+        else {
+            output("\nExisting complete customer-owned Gateway found; verifying and reusing it.\n");
+        }
+        generatedFiles.push(...await generateAutopilotFiles(repositoryPath, repository.name));
+        const doctor = await doctorCustomerGateway({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch });
+        if (doctor.overall !== "READY_TO_RECORD")
+            throw new Error(doctor.checks.filter((check) => check.status === "FAIL").map((check) => check.message).join(" "));
+        await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
+            status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles),
         });
-        const body = await response.json().catch(() => ({}));
-        if (response.ok)
-            return body;
-        if (response.status !== 428 || body.code !== "authorization_pending")
-            throw new Error(String(body.error ?? `Device authorization failed with HTTP ${response.status}.`));
-        await sleep(Math.max(1, device.interval) * 1_000);
+        output(`\nWitnora Setup Autopilot completed for ${repository.name}.\n`);
+        output(`Project: ${token.projectId}\nTemplate: ${repository.template} (${repository.kind})\n`);
+        output(`Credentials: ${credentialsPath}\nSelf-test receipt: ${receiptPath}\n`);
+        output(`Private discovery: ${discovery.capabilityCount} capability group(s); ${discovery.unknownCapabilityCount} pending confirmation.\n`);
+        output("Installed: customer-owned Gateway, default-deny policy, independent-probe contract, review contract, and PR/release/nightly CI.\n");
+        output("The self-test remains isolated. Start the generated Gateway and run the agent normally; the first source-signed, server-reconciled Gateway run completes onboarding.\n");
+        return { projectId: token.projectId, connectionName: token.connectionName, credentialsPath, template: repository.template,
+            repositoryKind: repository.kind, generatedFiles, receiptPath, discovery, setupPlanId: setupPlan.id,
+            gatewayDirectory: join(repositoryPath, ".witnora", "gateway") };
+    }
+    catch (error) {
+        const diagnosis = error instanceof Error ? error.message : String(error);
+        await rollbackGeneratedFiles(generatedFiles);
+        await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
+            status: "failed", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), diagnosis, rolledBack: true,
+        }).catch(() => undefined);
+        throw new Error(`Witnora Setup Autopilot rolled back this install attempt: ${diagnosis}`);
+    }
+}
+async function generateAutopilotFiles(repositoryPath, subject) {
+    const files = new Map([
+        [".witnora/setup/policy.json", `${JSON.stringify({ schemaVersion: "witnora.setup_policy.v0.1", subject, unknownCapabilities: "pending_confirmation", defaultDecision: "deny", environment: "sandbox" }, null, 2)}\n`],
+        [".witnora/setup/outcome-probe.json", `${JSON.stringify({ schemaVersion: "witnora.outcome_probe_contract.v0.1", mode: "independent_read_only", credentialEnv: "WITNORA_OUTCOME_PROBE_CREDENTIAL", status: "awaiting_customer_secret", uploadsCredential: false }, null, 2)}\n`],
+        [".witnora/setup/review.json", `${JSON.stringify({ schemaVersion: "witnora.review_contract.v0.1", independentReviewRequired: true, syntheticEvidenceEligible: false }, null, 2)}\n`],
+        [".github/workflows/witnora-assurance.yml", continuousAssuranceWorkflow()],
+    ]);
+    const written = [];
+    for (const [relativePath, content] of files) {
+        const target = join(repositoryPath, relativePath);
+        if (await exists(target))
+            continue;
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        written.push(target);
     }
-    throw new Error("Device authorization timed out. Run witnora onboard again to create a new one-time request.");
+    return written;
+}
+function continuousAssuranceWorkflow() {
+    return `name: Witnora assurance\non:\n  pull_request:\n  push:\n    tags: [\"v*\"]\n  schedule:\n    - cron: \"17 3 * * *\"\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  assurance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n      - run: npx witnora@latest release-gate --config witnora.config.json --strict\n`;
+}
+async function reportInstall(requestFetch, server, projectId, apiKey, setupPlanId, body) {
+    await jsonRequest(requestFetch, `${server}/v1/projects/${encodeURIComponent(projectId)}/setup-plans/${encodeURIComponent(setupPlanId)}/install-status`, {
+        method: "POST", headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" }, body: JSON.stringify(body),
+    });
 }
+async function rollbackGeneratedFiles(files) {
+    for (const path of [...files].reverse())
+        await rm(path, { recursive: true, force: true }).catch(() => undefined);
+}
+function relativeGeneratedFiles(repositoryPath, files) {
+    return files.map((file) => file.startsWith(repositoryPath) ? file.slice(repositoryPath.length + 1).replaceAll("\\", "/") : file).filter(Boolean);
+}
+function randomSuffix() { return Math.random().toString(36).slice(2, 10); }
 export async function inspectRepository(repositoryPath, explicitTemplate) {
     const entries = await readdir(repositoryPath, { withFileTypes: true });
     const names = entries.map((entry) => entry.name).sort();
@@ -124,12 +196,6 @@ async function jsonRequest(requestFetch, url, init) {
         throw new Error(String(body.error ?? `${init.method ?? "GET"} ${url} failed with HTTP ${response.status}.`));
     return body;
 }
-async function openSystemBrowser(url) {
-    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
-    child.unref();
-}
 async function optionalJson(path) {
     try {
         return JSON.parse(await readFile(path, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "Apache-2.0",
@@ -66,5 +66,8 @@
   },
   "optionalDependencies": {
     "pg": "^8.16.3"
+  },
+  "dependencies": {
+    "agentcert-sdk": "0.5.0"
   }
 }