agentcert 0.2.0 → 0.2.2

package/README.md

@@ -34,6 +34,17 @@ Default outputs:
 - `.agentcert/latest/reviewed-failure-dataset.jsonl`
 - `.agentcert/latest/monitor.json`
 
+Push the validated evidence bundle into a hosted AgentCert project:
+
+```bash
+npx agentcert connect --server https://agentcert-control-plane.onrender.com --project your-project-id
+npx agentcert push --evidence .agentcert/latest/agentcert-evidence.json
+```
+
+Add `--push` to `agentcert run` to run locally and upload the resulting bundle
+in one command. Project API keys can create runs, record events, and upload
+evidence, but cannot approve their own runtime actions.
+
 Review/export helpers:
 
 ```bash

package/dist/cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { validateEvidenceArtifacts } from "./artifact-validation.js";
 import { renderAgentCertBadge } from "./badge.js";
 import { buildEvidenceBundle } from "./bundle.js";
 import { recordsFromAgentCertResult, evaluateFailureClassifier, renderCorpusSummary, summarizeCorpus, writeReviewedFailureDataset, } from "./corpus.js";
 import { openCorpusStore, parseCorpusStoreKind } from "./corpus-store.js";
+import { pushEvidenceToControlPlane, verifyControlPlaneConnection } from "./control-plane.js";
+import { DEFAULT_AGENTCERT_SERVER, resolveConnection, saveConnection } from "./credentials.js";
 import { applyFailureReviews, appendFailureReview, createFailureReview, findFailurePattern, parseFailureReviewStatus, parseFailureType, parseReviewConfidence, readFailureReviews, } from "./failure-review.js";
 import { buildMonitorSnapshot, writeMonitorSnapshot } from "./monitor.js";
 import { normalizeMcpBenchResult, normalizeOnegentAuditPacket, normalizeTripwireResult } from "./normalizers.js";
@@ -81,6 +84,33 @@ Next:
      npx agentcert run --tripwire .tripwire/latest/tripwire-result.json --subject ${JSON.stringify(subject)} --fail-on-verdict
 `);
 }
+else if (command === "connect") {
+    if (readBoolFlag("--help")) {
+        process.stdout.write(`Usage:
+  agentcert connect --server https://agentcert-control-plane.onrender.com --project <project-id>
+  agentcert connect --name staging --server https://staging.example.com --project <project-id>
+
+The API key is read from AGENTCERT_API_KEY or requested with hidden input.
+Saved connections are reused by agentcert push and agentcert run --push.
+`);
+    }
+    else {
+        const name = readFlag("--name") ?? "default";
+        const server = readFlag("--server") ?? process.env.AGENTCERT_BASE_URL ?? DEFAULT_AGENTCERT_SERVER;
+        const projectId = readFlag("--project") ?? process.env.AGENTCERT_PROJECT_ID ?? await promptValue("Project ID: ");
+        const apiKey = readFlag("--api-key") ?? process.env.AGENTCERT_API_KEY ?? await promptSecret("Project API key: ");
+        const connection = await resolveConnection({ server, projectId, apiKey, env: {} });
+        const verified = await verifyControlPlaneConnection({
+            baseUrl: connection.server,
+            projectId: connection.projectId,
+            apiKey: connection.apiKey,
+        });
+        const path = await saveConnection(name, connection);
+        process.stdout.write(`Connected ${JSON.stringify(name)} to ${connection.server}\n`);
+        process.stdout.write(`Project: ${verified.projectId} (${verified.runs} runs, ${verified.evidence} evidence objects)\n`);
+        process.stdout.write(`Credentials: ${path}\n`);
+    }
+}
 else if (command === "report") {
     const config = await loadConfig(readFlag("--config"));
     const subject = readFlag("--subject") ?? config?.subject.name ?? "agentcert-subject";
@@ -269,8 +299,27 @@ else if (command === "run") {
         overrides,
     });
     process.stdout.write(renderRunSummary(outcome));
+    if (readBoolFlag("--push")) {
+        await pushHostedEvidence(outcome.bundle, Buffer.from(`${JSON.stringify(outcome.bundle, null, 2)}\n`), "agentcert-evidence.json");
+    }
     process.exitCode = outcome.exitCode;
 }
+else if (command === "push") {
+    const evidencePath = resolve(readFlag("--evidence") ?? ".agentcert/latest/agentcert-evidence.json");
+    const evidenceBytes = await readFile(evidencePath);
+    let bundle;
+    try {
+        bundle = JSON.parse(evidenceBytes.toString("utf8"));
+    }
+    catch {
+        throw new Error(`Evidence file is not valid JSON: ${evidencePath}`);
+    }
+    const validation = validateAgentCertSchema("evidence-bundle", bundle);
+    if (!validation.valid) {
+        throw new Error(`Evidence bundle is invalid:\n${validation.errors.map((error) => `- ${error}`).join("\n")}`);
+    }
+    await pushHostedEvidence(bundle, evidenceBytes, basename(evidencePath));
+}
 else if (command === "release-gate") {
     const overrides = readRunOverrides();
     const profileName = readFlag("--profile");
@@ -461,6 +510,7 @@ else if (command === "validate") {
 else {
     process.stdout.write(`Usage:
   agentcert init --subject my-browser-agent
+  agentcert connect --server https://agentcert-control-plane.onrender.com --project <project-id>
   agentcert init --out agentcert.config.json --tripwire-config tripwire.yml --force
   agentcert init --subject my-browser-agent --github-action
   agentcert report --mcpbench .mcpbench/latest/results.json --tripwire .tripwire/latest/tripwire-result.json --onegent .onegent/procurement/audit-packet.json --out .agentcert/latest --subject my-agent
@@ -471,6 +521,8 @@ else {
   agentcert monitor build --corpus .agentcert/corpus/corpus.jsonl --out .agentcert/latest/monitor.json --subject my-agent
   agentcert monitor build --store sqlite --sqlite .agentcert/corpus/agentcert.sqlite --out .agentcert/latest/monitor.json --subject my-agent
   agentcert run --profile public-demo
+  agentcert push --evidence .agentcert/latest/agentcert-evidence.json --server https://agentcert.example.com --project <project-id>
+  agentcert run --tripwire .tripwire/latest/tripwire-result.json --push
   agentcert run --mcpbench .mcpbench/latest/results.json --tripwire .tripwire/latest/tripwire-result.json --onegent .onegent/procurement/audit-packet.json --out .agentcert/latest --corpus .agentcert/corpus/corpus.jsonl --monitor-out .agentcert/latest/monitor.json --reviewed-dataset-out .agentcert/latest/reviewed-failure-dataset.jsonl
   agentcert release-gate --config agentcert.config.json --strict
   agentcert release-gate --evidence .agentcert/latest/agentcert-evidence.json --baseline .agentcert/baselines/main.json
@@ -492,6 +544,78 @@ async function loadConfig(path) {
     }
     return (await readJson(path));
 }
+async function pushHostedEvidence(bundle, bytes, fileName) {
+    const connection = await resolveConnection({
+        name: readFlag("--connection"),
+        server: readFlag("--server"),
+        projectId: readFlag("--project"),
+        apiKey: readFlag("--api-key"),
+    });
+    const result = await pushEvidenceToControlPlane({
+        baseUrl: connection.server,
+        projectId: connection.projectId,
+        apiKey: connection.apiKey,
+        bundle,
+        evidenceBytes: bytes,
+        fileName,
+        externalId: readFlag("--external-id"),
+    });
+    process.stdout.write(`Hosted run: ${result.runId}\nHosted evidence: ${result.evidenceId}\n`);
+}
+async function promptValue(label) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error(`Missing ${label.trim().replace(/:$/, "").toLowerCase()}. Pass it as a flag or environment variable.`);
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await prompt.question(label)).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function promptSecret(label) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || !process.stdin.setRawMode) {
+        throw new Error("Missing project API key. Set AGENTCERT_API_KEY or pass --api-key in a trusted environment.");
+    }
+    process.stdout.write(label);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    return new Promise((resolveSecret, rejectSecret) => {
+        let value = "";
+        const cleanup = () => {
+            process.stdin.off("data", onData);
+            process.stdin.setRawMode?.(false);
+            process.stdin.pause();
+            process.stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            for (const character of String(chunk)) {
+                if (character === "\u0003") {
+                    cleanup();
+                    rejectSecret(new Error("AgentCert connection cancelled."));
+                    return;
+                }
+                if (character === "\r" || character === "\n") {
+                    cleanup();
+                    resolveSecret(value.trim());
+                    return;
+                }
+                if (character === "\u007f" || character === "\b") {
+                    if (value) {
+                        value = value.slice(0, -1);
+                        process.stdout.write("\b \b");
+                    }
+                    continue;
+                }
+                value += character;
+                process.stdout.write("*");
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
 async function readJson(path) {
     const raw = await readFile(resolve(path), "utf8");
     return JSON.parse(raw);
@@ -683,6 +807,12 @@ function errorHint(message, code) {
     if (message.includes("already exists")) {
         return "Hint: re-run with `--force` to overwrite starter files, or choose a different `--out` path.";
     }
+    if (message.includes("Hosted push requires")) {
+        return "Hint: create a project API key in AgentCert Integrations, then set AGENTCERT_BASE_URL, AGENTCERT_PROJECT_ID, and AGENTCERT_API_KEY.";
+    }
+    if (message.includes("Authentication required") || message.includes("API key")) {
+        return "Hint: check AGENTCERT_API_KEY and confirm the key belongs to AGENTCERT_PROJECT_ID.";
+    }
     return undefined;
 }
 function starterTripwireConfig(subject) {

package/dist/control-plane.js

@@ -0,0 +1,143 @@
+export class ControlPlaneRequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ControlPlaneRequestError";
+    }
+}
+export async function verifyControlPlaneConnection(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    const request = options.fetch ?? fetch;
+    try {
+        const overview = await requestJson(request, `${baseUrl}/v1/projects/${encodeURIComponent(options.projectId)}/overview`, {
+            headers: { authorization: `Bearer ${options.apiKey}` },
+        });
+        return {
+            projectId: overview.projectId,
+            runs: overview.summary.runs ?? 0,
+            evidence: overview.summary.evidence ?? 0,
+        };
+    }
+    catch (error) {
+        if (error instanceof ControlPlaneRequestError && error.status === 401) {
+            throw new Error("AgentCert API key was rejected. Create a new project API key and try again.");
+        }
+        if (error instanceof ControlPlaneRequestError && error.status === 403) {
+            throw new Error(`AgentCert API key cannot access project ${options.projectId}. Check the project ID and key scope.`);
+        }
+        if (error instanceof ControlPlaneRequestError && error.status === 404) {
+            throw new Error(`AgentCert project ${options.projectId} was not found.`);
+        }
+        throw error;
+    }
+}
+export async function pushEvidenceToControlPlane(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, "");
+    if (!baseUrl || !options.projectId || !options.apiKey) {
+        throw new Error("baseUrl, projectId, and apiKey are required to push evidence.");
+    }
+    const request = options.fetch ?? fetch;
+    const projectUrl = `${baseUrl}/v1/projects/${encodeURIComponent(options.projectId)}`;
+    const externalId = options.externalId ?? options.bundle.runId;
+    const kind = hostedRunKind(options.bundle);
+    const headers = { authorization: `Bearer ${options.apiKey}` };
+    const run = await requestJson(request, `${projectUrl}/runs`, {
+        method: "POST",
+        headers: { ...headers, "content-type": "application/json" },
+        body: JSON.stringify({
+            externalId,
+            kind,
+            schemaVersion: options.bundle.schemaVersion,
+            startedAt: options.bundle.generatedAt,
+            metadata: {
+                subject: options.bundle.subject,
+                products: options.bundle.summary.products,
+            },
+        }),
+    });
+    await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/events`, {
+        method: "POST",
+        headers: { ...headers, "content-type": "application/json" },
+        body: JSON.stringify({
+            events: [{
+                    sequence: 0,
+                    type: "agentcert.evidence.created",
+                    actor: "agentcert-cli",
+                    occurredAt: options.bundle.generatedAt,
+                    payload: {
+                        verdict: options.bundle.verdict,
+                        totalEvidence: options.bundle.summary.totalEvidence,
+                        criticalEvidence: options.bundle.summary.criticalEvidence,
+                        highEvidence: options.bundle.summary.highEvidence,
+                    },
+                }],
+        }),
+    });
+    const query = new URLSearchParams({
+        fileName: options.fileName ?? "agentcert-evidence.json",
+        kind: "evidence_bundle",
+        schemaVersion: options.bundle.schemaVersion,
+        runId: run.id,
+    });
+    const evidence = await requestJson(request, `${projectUrl}/evidence?${query}`, {
+        method: "POST",
+        headers: { ...headers, "content-type": "application/json" },
+        body: new Uint8Array(options.evidenceBytes).buffer,
+    });
+    const firstDivergence = options.bundle.evidence.find((item) => item.severity === "critical" || item.severity === "high")?.message;
+    await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/complete`, {
+        method: "POST",
+        headers: { ...headers, "content-type": "application/json" },
+        body: JSON.stringify({
+            status: options.bundle.verdict.passed ? "passed" : "failed",
+            score: options.bundle.verdict.score,
+            summary: `${options.bundle.subject.name}: ${options.bundle.verdict.level}`,
+            firstDivergence,
+            completedAt: options.bundle.generatedAt,
+            metadata: {
+                evidenceId: evidence.id,
+                evidenceSchemaVersion: options.bundle.schemaVersion,
+            },
+        }),
+    });
+    return { runId: run.id, evidenceId: evidence.id, externalId };
+}
+function hostedRunKind(bundle) {
+    const products = new Set(bundle.summary.products);
+    if (products.size > 1)
+        return "release_gate";
+    if (products.has("mcpbench"))
+        return "mcpbench";
+    if (products.has("tripwire-ci"))
+        return "tripwire";
+    if (products.has("onegent-runtime"))
+        return "runtime";
+    return "custom";
+}
+async function requestJson(request, url, init) {
+    let response;
+    try {
+        response = await request(url, { ...init, signal: init.signal ?? AbortSignal.timeout(30_000) });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ControlPlaneRequestError(`AgentCert control plane request failed: ${message}`);
+    }
+    const text = await response.text();
+    let value = {};
+    if (text) {
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            if (!response.ok)
+                throw new ControlPlaneRequestError(`AgentCert control plane returned HTTP ${response.status}.`, response.status);
+            throw new ControlPlaneRequestError("AgentCert control plane returned invalid JSON.", response.status);
+        }
+    }
+    if (!response.ok) {
+        throw new ControlPlaneRequestError(typeof value.error === "string" ? value.error : `AgentCert control plane returned HTTP ${response.status}.`, response.status);
+    }
+    return value;
+}

package/dist/credentials.js

@@ -0,0 +1,115 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const DEFAULT_AGENTCERT_SERVER = "https://agentcert-control-plane.onrender.com";
+export async function saveConnection(name, input, options = {}) {
+    const connectionName = validateConnectionName(name);
+    const connection = validateConnection(input);
+    const path = credentialsPath(options);
+    const current = await readCredentialFile(path);
+    const next = {
+        schemaVersion: "agentcert.credentials.v1",
+        defaultConnection: connectionName,
+        connections: { ...current?.connections, [connectionName]: connection },
+    };
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600).catch(() => undefined);
+    return path;
+}
+export async function loadConnection(name, options = {}) {
+    const file = await readCredentialFile(credentialsPath(options));
+    if (!file)
+        return undefined;
+    const connectionName = name ? validateConnectionName(name) : file.defaultConnection;
+    const connection = file.connections[connectionName];
+    return connection ? validateConnection(connection) : undefined;
+}
+export async function resolveConnection(options = {}) {
+    const env = options.env ?? process.env;
+    const stored = options.server && options.projectId && options.apiKey
+        ? undefined
+        : await loadConnection(options.name, options);
+    const candidate = {
+        server: options.server ?? env.AGENTCERT_BASE_URL ?? stored?.server,
+        projectId: options.projectId ?? env.AGENTCERT_PROJECT_ID ?? stored?.projectId,
+        apiKey: options.apiKey ?? env.AGENTCERT_API_KEY ?? stored?.apiKey,
+    };
+    const missing = Object.entries(candidate).filter(([, value]) => !value).map(([key]) => key);
+    if (missing.length > 0) {
+        throw new Error(`Hosted connection is incomplete (${missing.join(", ")} missing). Run \`npx agentcert connect\` or set AGENTCERT_BASE_URL, AGENTCERT_PROJECT_ID, and AGENTCERT_API_KEY.`);
+    }
+    return validateConnection(candidate);
+}
+export function credentialsPath(options = {}) {
+    const configHome = options.configHome ?? process.env.AGENTCERT_CONFIG_HOME ?? join(homedir(), ".agentcert");
+    return join(configHome, "credentials.json");
+}
+function validateConnection(input) {
+    const projectId = input.projectId.trim();
+    const apiKey = input.apiKey.trim();
+    if (!projectId)
+        throw new Error("AgentCert project ID is required.");
+    if (!apiKey.startsWith("ac_live_"))
+        throw new Error("AgentCert API key must start with ac_live_.");
+    return { server: normalizeServer(input.server), projectId, apiKey };
+}
+function normalizeServer(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw new Error("AgentCert server must be a valid HTTP or HTTPS URL.");
+    }
+    const loopback = new Set(["localhost", "127.0.0.1", "[::1]"]).has(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error("AgentCert server must use HTTPS. Plain HTTP is allowed only for localhost development.");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("AgentCert server URL cannot contain credentials, query parameters, or a fragment.");
+    }
+    return url.toString().replace(/\/$/, "");
+}
+function validateConnectionName(value) {
+    const name = value.trim();
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(name)) {
+        throw new Error("Connection name must contain 1-64 letters, numbers, dots, underscores, or hyphens.");
+    }
+    return name;
+}
+async function readCredentialFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`AgentCert credentials file is not valid JSON: ${path}`);
+    }
+    if (!isCredentialFile(value)) {
+        throw new Error(`AgentCert credentials file has an unsupported format: ${path}`);
+    }
+    return value;
+}
+function isCredentialFile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const file = value;
+    return file.schemaVersion === "agentcert.credentials.v1"
+        && typeof file.defaultConnection === "string"
+        && Boolean(file.connections)
+        && typeof file.connections === "object"
+        && !Array.isArray(file.connections);
+}

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "./bundle.js";
 export * from "./corpus.js";
 export * from "./corpus-store.js";
+export * from "./control-plane.js";
+export * from "./credentials.js";
 export * from "./failure-review.js";
 export * from "./evidence-signing.js";
 export * from "./local-server.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcert",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Assurance release gates, runtime evidence, and regression CI for AI agents.",
   "type": "module",
   "license": "Apache-2.0",