witnora 0.8.1 → 0.9.0

package/dist/command-help.js

@@ -0,0 +1,71 @@
+export function renderCommandHelp(command) {
+    if (command === "sandbox" || command === "browser-adapter")
+        return undefined;
+    if (command === "setup")
+        return `Usage:
+  witnora setup apply --plan witnora-setup-plan.json --repo .
+  witnora setup apply --plan witnora-setup-plan.json --repo . --github-pr
+  witnora setup apply --plan witnora-setup-plan.json --repo . --github-pr --configure-ci
+
+Applies only allowlisted Witnora templates from a typed setup plan. Commands embedded in the plan are never executed.
+--github-pr requires authenticated git and GitHub CLI, creates a reviewable branch, and never writes API keys.
+--configure-ci additionally reads WITNORA_PROJECT_ID and WITNORA_API_KEY from the environment, then stores them through GitHub Variables and Secrets. Legacy AGENTCERT_* names remain supported. The API key is passed to gh on standard input.
+`;
+    if (command === "try")
+        return `Usage:
+  witnora try [--template <browser|coding|mcp|workflow|data>] [--subject <name>]
+  witnora try --template workflow --push
+
+Runs a deterministic local sample without an agent, model key, or external system.
+The output demonstrates the Witnora evidence path only; it is not a customer-agent evaluation.
+
+Options:
+  --template <type>       Sample boundary (default: workflow)
+  --subject <name>        Sample identity (default: witnora-sample-<template>)
+  --out <directory>       Output directory (default: .witnora/try)
+  --push                  Upload after a hosted project has been connected
+  --help, -h              Show this help
+`;
+    if (command === "init")
+        return `Usage:
+  witnora init --template <browser|coding|mcp|workflow|data> [--subject <name>]
+  witnora init --template browser --github-action
+
+Options:
+  --template <type>       External agent boundary (default: browser)
+  --subject <name>        Agent identity (default: my-<template>-agent)
+  --out <path>            Profile output (default: witnora.config.json)
+  --adapter-out <path>    Envelope adapter for coding/workflow/data
+  --github-action         Write the browser Tripwire workflow
+  --force                 Replace existing starter files
+  --help, -h              Show this help without writing files
+`;
+    if (command === "conformance")
+        return `Usage:
+  witnora conformance <evidence.json> --artifact-root <directory> [--implementation <name>] [--out <report.json>]
+
+Checks schema identity, v0.1 compatibility, artifact manifest structure, and exact artifact hashes and sizes.
+`;
+    if (command !== "push")
+        return undefined;
+    return `Usage:
+  witnora push --evidence .witnora/latest/agentcert-evidence.json
+  witnora push --evidence <path> --server <url> --project <project-id> [--api-key <key>]
+
+Options:
+  --evidence <path>       Evidence bundle (default: .witnora/latest/agentcert-evidence.json)
+  --connection <name>    Saved hosted connection
+  --server <url>         Hosted Witnora base URL
+  --project <id>         Hosted project ID
+  --api-key <key>        Project API key (prefer WITNORA_API_KEY in CI)
+  --external-id <id>     Idempotent hosted run ID
+  --assurance-case <id>  Issued assurance case to reconcile
+  --assurance-scope <p>  Declared agent/model/prompt/tools/policy/suite scope JSON
+  --assurance-trigger <t> auto, pull_request, release, or nightly (default: auto)
+  --require-current       Fail unless Hosted confirms authoritative CURRENT and complete evidence
+  --continuous-health-out <path>  Write the redacted Hosted health contract
+  --artifact-root <dir>  Allowed root for companion artifacts (default: current directory)
+  --no-artifacts         Upload only the evidence bundle
+  --help, -h             Show this help
+`;
+}

package/dist/companion-artifacts.js

@@ -0,0 +1,170 @@
+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;
+        }
+        const descriptor = describeArtifact(entry.sourcePath);
+        if (!descriptor) {
+            skipped.push(skip(entry, "unsupported_type", "accepted formats: PNG, JPEG, WebP, JSON, JSONL, HTML, PDF, ZIP"));
+            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;
+        }
+        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 === ".zip")
+        return { kind: "trace", contentType: "application/zip" };
+    if ([".html", ".htm"].includes(extension))
+        return { kind: "dom", contentType: "text/html; charset=utf-8" };
+    if (extension === ".json")
+        return { kind: lower.includes("trace") ? "trace" : lower.includes("dom") ? "dom" : "json", contentType: "application/json" };
+    if (extension === ".jsonl")
+        return { kind: lower.includes("trace") ? "trace" : "json", contentType: "application/x-ndjson" };
+    if (extension === ".pdf")
+        return { kind: "report", contentType: "application/pdf" };
+    return undefined;
+}
+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/conformance.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { normalizeManifestPath } from "./artifact-manifest.js";
+import { validateAgentCertSchema } from "./schema-validator.js";
+const SUPPORTED_TOP_LEVEL_FIELDS = new Set([
+    "schemaName", "schemaVersion", "schemaSemver", "kind", "runId", "generatedAt", "subject", "verdict", "summary",
+    "results", "evidence", "artifacts", "artifactManifest", "standards",
+]);
+export async function runEvidenceConformance(input, options) {
+    const checks = [];
+    const schema = validateAgentCertSchema("evidence-bundle", input);
+    checks.push(check("schema", "Evidence bundle satisfies the AgentCert v0.1 semantic contract.", schema.errors));
+    const bundle = object(input);
+    const compatibilityErrors = bundle
+        ? Object.keys(bundle).filter((key) => !SUPPORTED_TOP_LEVEL_FIELDS.has(key)).map((key) => `Unsupported top-level field: ${key}.`)
+        : ["Evidence bundle must be an object."];
+    checks.push(check("compatibility", "Evidence bundle uses only v0.1-compatible top-level fields.", compatibilityErrors));
+    const manifestErrors = [];
+    const entries = parseManifest(bundle?.artifactManifest, manifestErrors);
+    checks.push(check("manifest", "Artifact manifest declares unique normalized paths, SHA-256, byte size, and kind.", manifestErrors));
+    const byteErrors = [];
+    if (manifestErrors.length === 0) {
+        const root = resolve(options.artifactRoot);
+        for (const entry of entries) {
+            const path = resolve(root, entry.path);
+            if (path !== root && !path.startsWith(`${root}\\`) && !path.startsWith(`${root}/`)) {
+                byteErrors.push(`${entry.path}: resolved path escapes artifact root.`);
+                continue;
+            }
+            try {
+                const bytes = await readFile(path);
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                if (bytes.byteLength !== entry.sizeBytes)
+                    byteErrors.push(`${entry.path}: expected ${entry.sizeBytes} bytes, observed ${bytes.byteLength}.`);
+                if (digest !== entry.sha256)
+                    byteErrors.push(`${entry.path}: SHA-256 does not match the declared digest.`);
+            }
+            catch (error) {
+                const code = error && typeof error === "object" && "code" in error ? String(error.code) : "read_failed";
+                byteErrors.push(`${entry.path}: artifact could not be read (${code}).`);
+            }
+        }
+    }
+    else {
+        byteErrors.push("Artifact bytes were not checked because the manifest is invalid.");
+    }
+    checks.push(check("artifact-bytes", "Every declared artifact matches its exact runtime bytes.", byteErrors));
+    const passed = checks.filter((item) => item.status === "passed").length;
+    const failed = checks.length - passed;
+    return {
+        schemaVersion: "agentcert.conformance.v0.1",
+        kind: "agentcert.evidence_conformance_report",
+        implementation: options.implementation?.trim() || "third-party",
+        evidenceFile: resolve(options.evidenceFile),
+        artifactRoot: resolve(options.artifactRoot),
+        generatedAt: (options.now ?? new Date()).toISOString(),
+        valid: failed === 0,
+        summary: { passed, failed },
+        checks,
+    };
+}
+function parseManifest(input, errors) {
+    const manifest = object(input);
+    if (!manifest) {
+        errors.push("artifactManifest is required for conformance.");
+        return [];
+    }
+    if (manifest.schemaVersion !== "agentcert.artifact_manifest.v0.1")
+        errors.push("artifactManifest.schemaVersion must be agentcert.artifact_manifest.v0.1.");
+    if (!Array.isArray(manifest.entries)) {
+        errors.push("artifactManifest.entries must be an array.");
+        return [];
+    }
+    if (manifest.entries.length > 500)
+        errors.push("artifactManifest.entries cannot exceed 500 entries.");
+    const paths = new Set();
+    const entries = [];
+    manifest.entries.forEach((inputEntry, index) => {
+        const entry = object(inputEntry);
+        if (!entry) {
+            errors.push(`artifactManifest.entries[${index}] must be an object.`);
+            return;
+        }
+        let path;
+        try {
+            path = typeof entry.path === "string" ? normalizeManifestPath(entry.path) : undefined;
+        }
+        catch (error) {
+            errors.push(`artifactManifest.entries[${index}].path: ${error.message}`);
+        }
+        if (!path)
+            errors.push(`artifactManifest.entries[${index}].path must be a normalized relative path.`);
+        else if (paths.has(path))
+            errors.push(`artifactManifest contains duplicate path ${path}.`);
+        else
+            paths.add(path);
+        if (typeof entry.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha256))
+            errors.push(`artifactManifest.entries[${index}].sha256 must be 64 lowercase hex characters.`);
+        if (!Number.isInteger(entry.sizeBytes) || entry.sizeBytes < 0)
+            errors.push(`artifactManifest.entries[${index}].sizeBytes must be a non-negative integer.`);
+        if (typeof entry.kind !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(entry.kind))
+            errors.push(`artifactManifest.entries[${index}].kind must be a stable lowercase identifier.`);
+        if (path && typeof entry.sha256 === "string" && Number.isInteger(entry.sizeBytes) && typeof entry.kind === "string") {
+            entries.push({ path, sha256: entry.sha256, sizeBytes: entry.sizeBytes, kind: entry.kind });
+        }
+    });
+    return entries;
+}
+function check(id, message, errors) {
+    return { id, status: errors.length === 0 ? "passed" : "failed", message, errors };
+}
+function object(input) {
+    return input && typeof input === "object" && !Array.isArray(input) ? input : undefined;
+}