agentcert 0.2.1 → 0.2.2

package/README.md

@@ -37,9 +37,7 @@ Default outputs:
 Push the validated evidence bundle into a hosted AgentCert project:
 
 ```bash
-export AGENTCERT_BASE_URL="https://agentcert.example.com"
-export AGENTCERT_PROJECT_ID="your-project-id"
-export AGENTCERT_API_KEY="ac_live_..."
+npx agentcert connect --server https://agentcert-control-plane.onrender.com --project your-project-id
 npx agentcert push --evidence .agentcert/latest/agentcert-evidence.json
 ```
 

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 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 } from "./control-plane.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";
@@ -82,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";
@@ -481,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
@@ -515,16 +545,16 @@ async function loadConfig(path) {
     return (await readJson(path));
 }
 async function pushHostedEvidence(bundle, bytes, fileName) {
-    const baseUrl = readFlag("--server") ?? process.env.AGENTCERT_BASE_URL;
-    const projectId = readFlag("--project") ?? process.env.AGENTCERT_PROJECT_ID;
-    const apiKey = readFlag("--api-key") ?? process.env.AGENTCERT_API_KEY;
-    if (!baseUrl || !projectId || !apiKey) {
-        throw new Error("Hosted push requires AGENTCERT_BASE_URL, AGENTCERT_PROJECT_ID, and AGENTCERT_API_KEY (or --server, --project, and --api-key).");
-    }
+    const connection = await resolveConnection({
+        name: readFlag("--connection"),
+        server: readFlag("--server"),
+        projectId: readFlag("--project"),
+        apiKey: readFlag("--api-key"),
+    });
     const result = await pushEvidenceToControlPlane({
-        baseUrl,
-        projectId,
-        apiKey,
+        baseUrl: connection.server,
+        projectId: connection.projectId,
+        apiKey: connection.apiKey,
         bundle,
         evidenceBytes: bytes,
         fileName,
@@ -532,6 +562,60 @@ async function pushHostedEvidence(bundle, bytes, fileName) {
     });
     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);

package/dist/control-plane.js

@@ -1,3 +1,37 @@
+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) {
@@ -88,7 +122,7 @@ async function requestJson(request, url, init) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`AgentCert control plane request failed: ${message}`);
+        throw new ControlPlaneRequestError(`AgentCert control plane request failed: ${message}`);
     }
     const text = await response.text();
     let value = {};
@@ -98,12 +132,12 @@ async function requestJson(request, url, init) {
         }
         catch {
             if (!response.ok)
-                throw new Error(`AgentCert control plane returned HTTP ${response.status}.`);
-            throw new Error("AgentCert control plane returned invalid JSON.");
+                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 Error(typeof value.error === "string" ? value.error : `AgentCert control plane returned HTTP ${response.status}.`);
+        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

@@ -2,6 +2,7 @@ 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.1",
+  "version": "0.2.2",
   "description": "Assurance release gates, runtime evidence, and regression CI for AI agents.",
   "type": "module",
   "license": "Apache-2.0",