agentcert 0.2.1 → 0.2.3

package/README.md

@@ -37,15 +37,18 @@ 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
 ```
 
 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.
+in one command. By default, both commands also upload local files referenced by
+the bundle. Reads are confined to `--artifact-root` (the current directory by
+default), path and symlink escapes are rejected, and uploads are capped at 25
+files, 10 MiB per file, and 50 MiB total. Skipped references are reported in
+the CLI and hosted run timeline. Pass `--no-artifacts` to upload only the JSON
+bundle. Project API keys can create runs, record events, and upload evidence,
+but cannot approve their own runtime actions.
 
 Review/export helpers:
 

package/dist/artifact-validation.js

@@ -4,21 +4,24 @@ export async function validateEvidenceArtifacts(input, artifactRoot) {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
         return { checked: 0, missing: [] };
     }
-    const paths = collectArtifactPaths(input, artifactRoot);
-    const uniquePaths = dedupeArtifactPathEntries(paths).filter((entry) => !looksLikeUrl(entry.path));
+    const uniquePaths = collectEvidenceArtifactPaths(input, artifactRoot)
+        .filter((entry) => !isRemoteArtifactPath(entry.sourcePath));
     const missing = [];
     for (const entry of uniquePaths) {
-        const fullPath = isAbsolute(entry.path) ? entry.path : resolve(entry.root, entry.path);
+        const fullPath = isAbsolute(entry.sourcePath) ? entry.sourcePath : resolve(entry.root, entry.sourcePath);
         try {
             await access(fullPath);
         }
         catch {
-            missing.push(entry.path);
+            missing.push(entry.sourcePath);
         }
     }
     return { checked: uniquePaths.length, missing };
 }
-function collectArtifactPaths(bundle, artifactRoot) {
+export function collectEvidenceArtifactPaths(input, artifactRoot) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return [];
+    const bundle = input;
     const paths = [];
     const productRoots = productArtifactRoots(bundle, artifactRoot);
     collectStringValues(bundle.artifacts, paths, artifactRoot);
@@ -27,20 +30,25 @@ function collectArtifactPaths(bundle, artifactRoot) {
         if (result && typeof result === "object" && !Array.isArray(result)) {
             const resultRecord = result;
             collectStringValues(resultRecord.artifacts, paths, artifactRoot);
+            const product = typeof resultRecord.product === "string" ? resultRecord.product : undefined;
+            collectEvidencePaths(resultRecord.evidence, paths, product ? (productRoots.get(product) ?? artifactRoot) : artifactRoot);
         }
     }
-    const evidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
+    collectEvidencePaths(bundle.evidence, paths, artifactRoot, productRoots);
+    return dedupeArtifactPathEntries(paths);
+}
+function collectEvidencePaths(input, paths, root, productRoots) {
+    const evidence = Array.isArray(input) ? input : [];
     for (const item of evidence) {
         if (item && typeof item === "object" && !Array.isArray(item)) {
             const itemRecord = item;
             const artifactPath = itemRecord.artifactPath;
             if (typeof artifactPath === "string" && artifactPath.length > 0) {
                 const source = typeof itemRecord.source === "string" ? itemRecord.source : undefined;
-                paths.push({ path: artifactPath, root: source ? (productRoots.get(source) ?? artifactRoot) : artifactRoot });
+                paths.push({ sourcePath: artifactPath, root: source && productRoots ? (productRoots.get(source) ?? root) : root });
             }
         }
     }
-    return paths;
 }
 function productArtifactRoots(bundle, artifactRoot) {
     const roots = new Map();
@@ -71,7 +79,7 @@ function collectStringValues(input, paths, root) {
     }
     for (const value of Object.values(input)) {
         if (typeof value === "string" && value.length > 0) {
-            paths.push({ path: value, root });
+            paths.push({ sourcePath: value, root });
         }
     }
 }
@@ -79,7 +87,7 @@ function dedupeArtifactPathEntries(entries) {
     const seen = new Set();
     const deduped = [];
     for (const entry of entries) {
-        const key = `${entry.root}\0${entry.path}`;
+        const key = `${entry.root}\0${entry.sourcePath}`;
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -87,6 +95,6 @@ function dedupeArtifactPathEntries(entries) {
     }
     return deduped;
 }
-function looksLikeUrl(value) {
+export function isRemoteArtifactPath(value) {
     return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
 }

package/dist/cli.js

@@ -1,12 +1,15 @@
 #!/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 { collectCompanionArtifacts, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS } from "./companion-artifacts.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 +85,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 +511,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
@@ -491,7 +522,7 @@ 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 push --evidence .agentcert/latest/agentcert-evidence.json --server https://agentcert.example.com --project <project-id> [--artifact-root .] [--no-artifacts]
   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
@@ -515,22 +546,90 @@ 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 companions = readBoolFlag("--no-artifacts")
+        ? undefined
+        : await collectCompanionArtifacts(bundle, resolve(readFlag("--artifact-root") ?? process.cwd()));
     const result = await pushEvidenceToControlPlane({
-        baseUrl,
-        projectId,
-        apiKey,
+        baseUrl: connection.server,
+        projectId: connection.projectId,
+        apiKey: connection.apiKey,
         bundle,
         evidenceBytes: bytes,
         fileName,
         externalId: readFlag("--external-id"),
+        companionArtifacts: companions?.artifacts,
+        skippedCompanionArtifacts: companions?.skipped,
     });
     process.stdout.write(`Hosted run: ${result.runId}\nHosted evidence: ${result.evidenceId}\n`);
+    if (companions) {
+        process.stdout.write(`Hosted companion artifacts: ${result.artifactsUploaded} uploaded, ${result.artifactsSkipped} skipped, ${result.artifactBytesUploaded} bytes.\n`);
+        for (const skipped of companions.skipped.slice(0, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS)) {
+            process.stderr.write(`Skipped companion artifact ${skipped.sourcePath}: ${skipped.reason}${skipped.detail ? ` (${skipped.detail})` : ""}.\n`);
+        }
+        if (companions.skipped.length > MAX_REPORTED_COMPANION_ARTIFACT_SKIPS) {
+            process.stderr.write(`${companions.skipped.length - MAX_REPORTED_COMPANION_ARTIFACT_SKIPS} additional skipped artifacts omitted.\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");

package/dist/companion-artifacts.js

@@ -0,0 +1,180 @@
+import { lstat, open, realpath, stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { collectEvidenceArtifactPaths, isRemoteArtifactPath, } from "./artifact-validation.js";
+export const DEFAULT_COMPANION_ARTIFACT_LIMITS = {
+    maxFiles: 25,
+    maxFileBytes: 10 * 1024 * 1024,
+    maxTotalBytes: 50 * 1024 * 1024,
+};
+export const MAX_REPORTED_COMPANION_ARTIFACT_SKIPS = 50;
+export async function collectCompanionArtifacts(bundle, artifactRoot, limits = DEFAULT_COMPANION_ARTIFACT_LIMITS) {
+    validateLimits(limits);
+    const root = await realpath(resolve(artifactRoot));
+    const artifacts = [];
+    const skipped = [];
+    const uploadedRealPaths = new Set();
+    let totalBytes = 0;
+    for (const entry of collectEvidenceArtifactPaths(bundle, root)) {
+        if (isRemoteArtifactPath(entry.sourcePath)) {
+            skipped.push(skip(entry, "remote_url"));
+            continue;
+        }
+        if (artifacts.length >= limits.maxFiles) {
+            skipped.push(skip(entry, "file_limit", `maximum ${limits.maxFiles} files`));
+            continue;
+        }
+        const candidate = isAbsolute(entry.sourcePath)
+            ? resolve(entry.sourcePath)
+            : resolve(entry.root, entry.sourcePath);
+        if (!isWithinRoot(root, candidate)) {
+            skipped.push(skip(entry, "outside_artifact_root"));
+            continue;
+        }
+        let candidateInfo;
+        try {
+            candidateInfo = await lstat(candidate);
+        }
+        catch (error) {
+            skipped.push(skip(entry, errorCode(error) === "ENOENT" ? "missing" : "unreadable", errorMessage(error)));
+            continue;
+        }
+        if (candidateInfo.isSymbolicLink()) {
+            skipped.push(skip(entry, "symlink"));
+            continue;
+        }
+        let resolvedPath;
+        try {
+            resolvedPath = await realpath(candidate);
+        }
+        catch (error) {
+            skipped.push(skip(entry, errorCode(error) === "ENOENT" ? "missing" : "unreadable", errorMessage(error)));
+            continue;
+        }
+        if (!isWithinRoot(root, resolvedPath)) {
+            skipped.push(skip(entry, "outside_artifact_root"));
+            continue;
+        }
+        if (uploadedRealPaths.has(resolvedPath))
+            continue;
+        let fileInfo;
+        try {
+            fileInfo = await stat(resolvedPath);
+        }
+        catch (error) {
+            skipped.push(skip(entry, errorCode(error) === "ENOENT" ? "missing" : "unreadable", errorMessage(error)));
+            continue;
+        }
+        if (!fileInfo.isFile()) {
+            skipped.push(skip(entry, "not_file"));
+            continue;
+        }
+        if (fileInfo.size > limits.maxFileBytes) {
+            skipped.push(skip(entry, "file_too_large", `${fileInfo.size} bytes exceeds ${limits.maxFileBytes}`));
+            continue;
+        }
+        if (totalBytes + fileInfo.size > limits.maxTotalBytes) {
+            skipped.push(skip(entry, "total_size_limit", `maximum ${limits.maxTotalBytes} bytes`));
+            continue;
+        }
+        const remainingBytes = limits.maxTotalBytes - totalBytes;
+        let readResult;
+        try {
+            readResult = await readBounded(resolvedPath, Math.min(limits.maxFileBytes, remainingBytes));
+        }
+        catch (error) {
+            skipped.push(skip(entry, "unreadable", errorMessage(error)));
+            continue;
+        }
+        if (readResult.exceeded) {
+            const reason = remainingBytes < limits.maxFileBytes ? "total_size_limit" : "file_too_large";
+            skipped.push(skip(entry, reason));
+            continue;
+        }
+        const descriptor = describeArtifact(entry.sourcePath);
+        artifacts.push({
+            sourcePath: normalizeSourcePath(entry.sourcePath),
+            fileName: basename(resolvedPath),
+            kind: descriptor.kind,
+            contentType: descriptor.contentType,
+            bytes: readResult.bytes,
+        });
+        uploadedRealPaths.add(resolvedPath);
+        totalBytes += readResult.bytes.byteLength;
+    }
+    return { artifacts, skipped, totalBytes, limits: { ...limits } };
+}
+function validateLimits(limits) {
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`${name} must be a positive integer.`);
+    }
+}
+function isWithinRoot(root, candidate) {
+    const pathFromRoot = relative(root, candidate);
+    return pathFromRoot === "" || (!pathFromRoot.startsWith(`..${sep}`) && pathFromRoot !== ".." && !isAbsolute(pathFromRoot));
+}
+async function readBounded(path, maxBytes) {
+    const handle = await open(path, "r");
+    const chunks = [];
+    let total = 0;
+    try {
+        while (total <= maxBytes) {
+            const capacity = Math.min(64 * 1024, maxBytes + 1 - total);
+            const chunk = Buffer.allocUnsafe(capacity);
+            const { bytesRead } = await handle.read(chunk, 0, capacity, null);
+            if (bytesRead === 0)
+                return { bytes: Buffer.concat(chunks, total), exceeded: false };
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+        }
+        return { bytes: new Uint8Array(), exceeded: true };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function describeArtifact(path) {
+    const lower = path.toLowerCase();
+    const extension = extname(lower);
+    if ([".png", ".jpg", ".jpeg", ".webp"].includes(extension)) {
+        const imageType = extension === ".jpg" ? "jpeg" : extension.slice(1);
+        return { kind: "screenshot", contentType: `image/${imageType}` };
+    }
+    if (extension === ".svg")
+        return { kind: "report", contentType: "image/svg+xml" };
+    if (extension === ".zip" || lower.includes("trace")) {
+        const contentType = extension === ".zip" ? "application/zip" : extension === ".json" ? "application/json" : "application/octet-stream";
+        return { kind: "trace", contentType };
+    }
+    if ([".html", ".htm"].includes(extension) || lower.includes("dom")) {
+        const contentType = [".html", ".htm"].includes(extension)
+            ? "text/html; charset=utf-8"
+            : extension === ".json"
+                ? "application/json"
+                : "application/octet-stream";
+        return { kind: "dom", contentType };
+    }
+    if (extension === ".json")
+        return { kind: "json", contentType: "application/json" };
+    if (extension === ".jsonl")
+        return { kind: "json", contentType: "application/x-ndjson" };
+    if (extension === ".pdf")
+        return { kind: "report", contentType: "application/pdf" };
+    if (extension === ".md")
+        return { kind: "report", contentType: "text/markdown; charset=utf-8" };
+    if (extension === ".txt")
+        return { kind: "artifact", contentType: "text/plain; charset=utf-8" };
+    return { kind: "artifact", contentType: "application/octet-stream" };
+}
+function normalizeSourcePath(path) {
+    return path.replace(/\\/g, "/").slice(0, 1024);
+}
+function skip(entry, reason, detail) {
+    return { sourcePath: normalizeSourcePath(entry.sourcePath), reason, ...(detail ? { detail } : {}) };
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error ? String(error.code) : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/control-plane.js

@@ -1,3 +1,38 @@
+import { MAX_REPORTED_COMPANION_ARTIFACT_SKIPS, } from "./companion-artifacts.js";
+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) {
@@ -51,6 +86,47 @@ export async function pushEvidenceToControlPlane(options) {
         headers: { ...headers, "content-type": "application/json" },
         body: new Uint8Array(options.evidenceBytes).buffer,
     });
+    const companionArtifacts = options.companionArtifacts ?? [];
+    const skippedArtifacts = options.skippedCompanionArtifacts ?? [];
+    let artifactBytesUploaded = 0;
+    for (const artifact of companionArtifacts) {
+        const artifactQuery = new URLSearchParams({
+            fileName: artifact.fileName,
+            kind: artifact.kind,
+            schemaVersion: options.bundle.schemaVersion,
+            runId: run.id,
+            sourcePath: artifact.sourcePath,
+        });
+        await requestJson(request, `${projectUrl}/evidence?${artifactQuery}`, {
+            method: "POST",
+            headers: { ...headers, "content-type": artifact.contentType },
+            body: new Uint8Array(artifact.bytes).buffer,
+        });
+        artifactBytesUploaded += artifact.bytes.byteLength;
+    }
+    if (companionArtifacts.length > 0 || skippedArtifacts.length > 0) {
+        await requestJson(request, `${projectUrl}/runs/${encodeURIComponent(run.id)}/events`, {
+            method: "POST",
+            headers: { ...headers, "content-type": "application/json" },
+            body: JSON.stringify({
+                events: [{
+                        sequence: 1,
+                        type: "agentcert.companion_artifacts.processed",
+                        actor: "agentcert-cli",
+                        occurredAt: options.bundle.generatedAt,
+                        payload: {
+                            uploadedCount: companionArtifacts.length,
+                            skippedCount: skippedArtifacts.length,
+                            uploadedBytes: artifactBytesUploaded,
+                            skipped: skippedArtifacts
+                                .slice(0, MAX_REPORTED_COMPANION_ARTIFACT_SKIPS)
+                                .map(({ sourcePath, reason }) => ({ sourcePath, reason })),
+                            skippedDetailsTruncated: skippedArtifacts.length > MAX_REPORTED_COMPANION_ARTIFACT_SKIPS,
+                        },
+                    }],
+            }),
+        });
+    }
     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",
@@ -64,10 +140,20 @@ export async function pushEvidenceToControlPlane(options) {
             metadata: {
                 evidenceId: evidence.id,
                 evidenceSchemaVersion: options.bundle.schemaVersion,
+                companionArtifactsUploaded: companionArtifacts.length,
+                companionArtifactsSkipped: skippedArtifacts.length,
+                companionArtifactBytesUploaded: artifactBytesUploaded,
             },
         }),
     });
-    return { runId: run.id, evidenceId: evidence.id, externalId };
+    return {
+        runId: run.id,
+        evidenceId: evidence.id,
+        externalId,
+        artifactsUploaded: companionArtifacts.length,
+        artifactsSkipped: skippedArtifacts.length,
+        artifactBytesUploaded,
+    };
 }
 function hostedRunKind(bundle) {
     const products = new Set(bundle.summary.products);
@@ -88,7 +174,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 +184,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.3",
   "description": "Assurance release gates, runtime evidence, and regression CI for AI agents.",
   "type": "module",
   "license": "Apache-2.0",