witnora 0.9.3 → 0.10.2

package/README.md

@@ -9,17 +9,51 @@ outcome. It writes portable reports and accumulates a local failure corpus.
 [Public evidence](https://witnora.com/evidence) |
 [Get started](https://witnora.com/docs) |
 [Private workspace](https://witnora.com/app) |
-[GitHub source](https://github.com/Kakarottoooo/agentcert)
+[GitHub source](https://github.com/Kakarottoooo/witnora)
 
-## 5-minute local path
+## 5-minute hosted path
 
-No agent repository or API key is required for the first run:
+Create a Hosted project, open a terminal in the agent repository, and run the
+one command shown by Witnora:
 
 ```bash
-npx witnora@latest try --template workflow
+npx witnora@latest onboard --project your-project-id
 ```
 
-Inspect `.witnora/try/agentcert-report.html` and
+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.
+
+Without an agent repository, run `npx witnora@latest try --template workflow`
+for an offline-only sample.
+
+To exercise the privacy-preserving high-risk action loop locally, including
+contract compilation, exact-action approval, a single-use grant, controlled
+execution, independent outcome observation, signed evidence, and offline
+verification:
+
+```bash
+npx witnora@latest contract init
+npx witnora@latest contract compile witnora.assurance-contract.json
+npx witnora@latest privacy init
+npx witnora@latest demo assurance-loop
+npx witnora@latest verify --offline .witnora/assurance-loop/witnora-evidence-packet.json \
+  --trust .witnora/assurance-loop/witnora-trust-bundle.json
+```
+
+This reference path is deterministic and local. It uses no real integration or
+credential. See the full [privacy-preserving action loop](https://github.com/Kakarottoooo/witnora/blob/main/docs/how-it-works/privacy-preserving-action-loop.md),
+including attack demonstrations and explicit limitations.
+
+Implementation references:
+
+- [Assurance Contract v0.1](https://github.com/Kakarottoooo/witnora/blob/main/docs/specifications/witnora-assurance-contract-v0.1.md)
+- [Two-hour design-partner quickstart](https://github.com/Kakarottoooo/witnora/blob/main/docs/guides/design-partner-two-hour-quickstart.md)
+- [Threat model and trust boundaries](https://github.com/Kakarottoooo/witnora/blob/main/docs/security/privacy-verifiable-assurance-v1-threat-model.md)
+
+If you use the offline sample, inspect `.witnora/try/agentcert-report.html` and
 `.witnora/try/agentcert-evidence.json`. The output is explicitly synthetic and
 reported-strength: it proves the evidence tooling works, not that a real agent
 is reliable.
@@ -92,13 +126,35 @@ Default outputs:
 - `.witnora/latest/reviewed-failure-dataset.jsonl`
 - `.witnora/latest/monitor.json`
 
-Push the validated evidence bundle into a hosted Witnora project:
+Onboard once, then push the validated evidence bundle into the same project:
 
 ```bash
-npx witnora connect --server https://witnora.com --project your-project-id
-npx witnora push --evidence .witnora/latest/agentcert-evidence.json
+npx witnora@latest onboard --project your-project-id
+npx witnora@latest push --evidence .witnora/latest/agentcert-evidence.json
 ```
 
+### Automatic agent and environment context
+
+`run --push`, `push`, and the generated workflow/coding/data adapter register
+the observed agent automatically. Witnora derives the stable identity and
+version from the command subject, the nearest `package.json`, and the current
+CI commit. It records one canonical environment for every run:
+
+- local, development, and test execution becomes `sandbox`;
+- pull-request and preview execution becomes `staging`;
+- tagged releases and recognized production hosts become `production`.
+
+This context is run evidence, not a project form the customer must keep in
+sync. A later run with the same Agent ID updates the observed version without
+overwriting reviewed permissions. Explicit `WITNORA_AGENT_ID`,
+`WITNORA_AGENT_VERSION`, and `WITNORA_ENVIRONMENT` values take precedence when
+a repository needs a stable identity that differs from its package metadata.
+Unsupported environment values fail closed instead of being guessed.
+
+Useful one-run overrides are `--agent-id`, `--agent-name`, `--agent-version`,
+`--agent-framework`, and `--environment`. Raw prompts, credentials, and tool
+arguments are not needed for this registration.
+
 Bind a release, pull-request, or nightly run to an issued continuous assurance
 case by declaring the exact reviewed scope:
 
@@ -172,7 +228,7 @@ the bundled deterministic adapter contract and writes
 `.witnora/sandbox/sandbox-adapter-conformance.json`. No `@agentcert` scoped
 package is required.
 
-After `agentcert connect`, certify and upload in one command:
+After `witnora onboard`, certify and upload in one command:
 
 ```bash
 npx witnora sandbox push --adapter ./agentcert.sandbox.mjs
@@ -299,3 +355,14 @@ npm --prefix packages/witnora-cli ci
 npm --prefix packages/witnora-cli run build
 node packages/witnora-cli/dist/cli.js run --profile public-demo
 ```
+
+## Design-partner independent assurance v0.2
+
+The sandbox-only reference path separates a write-capable Gateway from a
+customer-operated read-only Probe, binds approval and a single-use grant to one
+declared GitHub pull-request action, reconciles target state after dispatch, and
+produces a packet that TypeScript and Python can verify offline.
+
+Start with the [two-hour design-partner quickstart](../../docs/guides/design-partner-two-hour-quickstart.md).
+The included GitHub target is an emulator. It does not claim live GitHub or
+production acceptance, organizational independence, or external review.

package/dist/assurance-contract.js

@@ -0,0 +1,312 @@
+import { readFile } from "node:fs/promises";
+import { canonicalJson, sha256Canonical, WITNORA_CANONICALIZATION_VERSION } from "./canonical.js";
+export const ASSURANCE_CONTRACT_VERSION = "witnora.assurance_contract.v0.1";
+export const COMPILED_CONTRACT_VERSION = "witnora.compiled_assurance_contract.v0.1";
+export const ASSURANCE_COMPILER_VERSION = "witnora.contract_compiler.v0.1";
+export async function readAssuranceContract(path) {
+    const raw = await readFile(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Contract must be JSON (JSON is valid YAML 1.2). Generated contracts use a .json file to avoid parser ambiguity.");
+    }
+    return validateAssuranceContract(parsed);
+}
+export function validateAssuranceContract(input) {
+    const errors = [];
+    const root = object(input, "$", errors);
+    exactKeys(root, ["kind", "metadata", "subject", "capability", "authority", "preconditions", "effect", "execution", "observation", "privacy", "evidence", "revalidation"], "$", errors);
+    if (root.kind !== ASSURANCE_CONTRACT_VERSION)
+        errors.push(`$.kind must equal ${ASSURANCE_CONTRACT_VERSION}.`);
+    const metadata = object(root.metadata, "$.metadata", errors);
+    exactKeys(metadata, ["id", "version", "description"], "$.metadata", errors);
+    const subject = object(root.subject, "$.subject", errors);
+    exactKeys(subject, ["agentId", "environment"], "$.subject", errors);
+    const capability = object(root.capability, "$.capability", errors);
+    exactKeys(capability, ["id", "action", "sideEffect", "risk"], "$.capability", errors);
+    const authority = object(root.authority, "$.authority", errors);
+    exactKeys(authority, ["mandateRef", "policyRef", "approval", "resourceScope"], "$.authority", errors);
+    const approval = object(authority.approval, "$.authority.approval", errors);
+    exactKeys(approval, ["required"], "$.authority.approval", errors);
+    const resourceScope = object(authority.resourceScope, "$.authority.resourceScope", errors);
+    exactKeys(resourceScope, ["type", "pattern"], "$.authority.resourceScope", errors);
+    const effect = object(root.effect, "$.effect", errors);
+    exactKeys(effect, ["eventuallyWithin", "stableFor", "must", "mustNot"], "$.effect", errors, ["stableFor"]);
+    const execution = object(root.execution, "$.execution", errors);
+    exactKeys(execution, ["atMostOnce", "idempotencyRequired", "retryPolicy"], "$.execution", errors);
+    const retry = object(execution.retryPolicy, "$.execution.retryPolicy", errors);
+    exactKeys(retry, ["maxAttempts"], "$.execution.retryPolicy", errors);
+    const observation = object(root.observation, "$.observation", errors);
+    exactKeys(observation, ["mode", "probeRef", "reconcileWithTargetAuditLog"], "$.observation", errors);
+    const privacy = object(root.privacy, "$.privacy", errors);
+    exactKeys(privacy, ["localOnly", "disclose", "commitOnly"], "$.privacy", errors);
+    const evidence = object(root.evidence, "$.evidence", errors);
+    exactKeys(evidence, ["require"], "$.evidence", errors);
+    const revalidation = object(root.revalidation, "$.revalidation", errors);
+    exactKeys(revalidation, ["triggers"], "$.revalidation", errors);
+    requiredString(metadata.id, "$.metadata.id", errors);
+    positiveInteger(metadata.version, "$.metadata.version", errors);
+    requiredString(metadata.description, "$.metadata.description", errors);
+    requiredString(subject.agentId, "$.subject.agentId", errors);
+    requiredString(subject.environment, "$.subject.environment", errors);
+    requiredString(capability.id, "$.capability.id", errors);
+    oneOf(capability.action, ["SUBMIT", "PAY", "SEND", "UPDATE"], "$.capability.action", errors);
+    bool(capability.sideEffect, "$.capability.sideEffect", errors);
+    oneOf(capability.risk, ["low", "medium", "high", "critical"], "$.capability.risk", errors);
+    requiredString(authority.mandateRef, "$.authority.mandateRef", errors);
+    requiredString(authority.policyRef, "$.authority.policyRef", errors);
+    bool(approval.required, "$.authority.approval.required", errors);
+    requiredString(resourceScope.type, "$.authority.resourceScope.type", errors);
+    requiredString(resourceScope.pattern, "$.authority.resourceScope.pattern", errors);
+    const preconditions = predicates(root.preconditions, "$.preconditions", errors);
+    requiredString(effect.eventuallyWithin, "$.effect.eventuallyWithin", errors);
+    if (typeof effect.eventuallyWithin === "string" && parseContractDurationMs(effect.eventuallyWithin) === undefined)
+        errors.push("$.effect.eventuallyWithin must be a positive duration such as 30s, 5m, or 1h.");
+    if (effect.stableFor !== undefined) {
+        requiredString(effect.stableFor, "$.effect.stableFor", errors);
+        if (typeof effect.stableFor === "string" && parseContractDurationMs(effect.stableFor) === undefined)
+            errors.push("$.effect.stableFor must be a positive duration such as 5s, 1m, or 1h.");
+    }
+    const must = predicates(effect.must, "$.effect.must", errors);
+    const mustNot = predicates(effect.mustNot, "$.effect.mustNot", errors);
+    bool(execution.atMostOnce, "$.execution.atMostOnce", errors);
+    bool(execution.idempotencyRequired, "$.execution.idempotencyRequired", errors);
+    positiveInteger(retry.maxAttempts, "$.execution.retryPolicy.maxAttempts", errors);
+    if (observation.mode !== "independent_read_path")
+        errors.push("$.observation.mode must equal independent_read_path.");
+    requiredString(observation.probeRef, "$.observation.probeRef", errors);
+    bool(observation.reconcileWithTargetAuditLog, "$.observation.reconcileWithTargetAuditLog", errors);
+    const localOnly = strings(privacy.localOnly, "$.privacy.localOnly", errors);
+    const disclose = strings(privacy.disclose, "$.privacy.disclose", errors);
+    const commitOnly = strings(privacy.commitOnly, "$.privacy.commitOnly", errors);
+    const overlap = [...localOnly, ...disclose, ...commitOnly].filter((value, index, all) => all.indexOf(value) !== index);
+    if (overlap.length)
+        errors.push(`$.privacy categories overlap: ${[...new Set(overlap)].join(", ")}.`);
+    const requireEvidence = strings(evidence.require, "$.evidence.require", errors);
+    const triggers = strings(revalidation.triggers, "$.revalidation.triggers", errors);
+    if (capability.sideEffect === true && ["high", "critical"].includes(String(capability.risk)) && approval.required !== true) {
+        errors.push("$.authority.approval.required must be true for a high-risk side effect.");
+    }
+    if (execution.atMostOnce !== true || execution.idempotencyRequired !== true)
+        errors.push("High-risk v0.1 contracts require at-most-once grant use and target idempotency.");
+    if (!must.length)
+        errors.push("$.effect.must must contain at least one independently observable predicate.");
+    if (errors.length)
+        throw new Error(`Invalid Assurance Contract:\n${errors.map((error) => `- ${error}`).join("\n")}`);
+    return structuredClone(input);
+}
+export function compileAssuranceContract(input) {
+    const contract = validateAssuranceContract(input);
+    const sourceContractDigest = sha256Canonical(contract);
+    const artifacts = {
+        capabilityRegistration: contract.capability,
+        runtimePolicyInput: { ...contract.authority, contractDigest: sourceContractDigest },
+        approvalPresentation: { capability: contract.capability.id, action: contract.capability.action, resourceType: contract.authority.resourceScope.type, exactActionDigestRequired: true },
+        executionGrantBindingTemplate: {
+            contractDigest: sourceContractDigest,
+            policyRef: contract.authority.policyRef,
+            mandateRef: contract.authority.mandateRef,
+            agentId: contract.subject.agentId,
+            environment: contract.subject.environment,
+            maxUses: 1,
+        },
+        outcomeProbeSpecification: { ...contract.observation, ...contract.effect },
+        evidenceObligations: [...contract.evidence.require].sort(),
+        privacyObligations: contract.privacy,
+        revalidationFingerprint: sha256Canonical({ triggers: contract.revalidation.triggers, values: revalidationValues(contract) }),
+    };
+    return {
+        schemaVersion: COMPILED_CONTRACT_VERSION,
+        compilerVersion: ASSURANCE_COMPILER_VERSION,
+        canonicalizationVersion: WITNORA_CANONICALIZATION_VERSION,
+        sourceContractDigest,
+        ...artifacts,
+        artifactDigests: Object.fromEntries(Object.entries(artifacts).map(([key, value]) => [key, sha256Canonical(value)])),
+    };
+}
+export function parseContractDurationMs(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value);
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const multiplier = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]];
+    if (multiplier === undefined)
+        return undefined;
+    const result = amount * multiplier;
+    return Number.isFinite(result) && result > 0 ? result : undefined;
+}
+export function diffAssuranceContracts(previousInput, nextInput) {
+    const previous = validateAssuranceContract(previousInput);
+    const next = validateAssuranceContract(nextInput);
+    const changedPaths = changed(previous, next);
+    const reasons = new Set();
+    if (changedPaths.some((path) => path.startsWith("capability")))
+        reasons.add("CAPABILITY_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("authority.resourceScope")))
+        reasons.add("RESOURCE_SCOPE_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("authority.approval")))
+        reasons.add("APPROVAL_REQUIREMENT_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("authority.policyRef")))
+        reasons.add("POLICY_VERSION_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("effect") || path.startsWith("observation")))
+        reasons.add("OUTCOME_SEMANTICS_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("privacy")))
+        reasons.add("PRIVACY_DISCLOSURE_CHANGED");
+    if (changedPaths.some((path) => path.startsWith("subject")))
+        reasons.add("SUBJECT_SCOPE_CHANGED");
+    const authorityExpanded = scopeExpanded(previous, next);
+    if (authorityExpanded)
+        reasons.add("AUTHORITY_EXPANDED");
+    return {
+        schemaVersion: "witnora.assurance_contract_diff.v0.1",
+        revalidationRequired: reasons.size > 0,
+        authorityExpanded,
+        reasons: [...reasons].sort(),
+        changedPaths,
+    };
+}
+export function exampleAssuranceContract() {
+    return {
+        kind: ASSURANCE_CONTRACT_VERSION,
+        metadata: { id: "record-submit", version: 1, description: "Submit one record through a controlled action path." },
+        subject: { agentId: "example-workflow-agent", environment: "sandbox" },
+        capability: { id: "record.submit", action: "SUBMIT", sideEffect: true, risk: "high" },
+        authority: {
+            mandateRef: "mandate:record-submit:v1",
+            policyRef: "policy:high-risk-submit:v1",
+            approval: { required: true },
+            resourceScope: { type: "record", pattern: "sandbox/*" },
+        },
+        preconditions: [{ path: "status", operator: "equals", value: "DRAFT" }],
+        effect: {
+            eventuallyWithin: "30s",
+            must: [{ path: "status", operator: "equals", value: "SUBMITTED" }],
+            mustNot: [{ path: "prohibitedSideEffect", operator: "equals", value: true }],
+        },
+        execution: { atMostOnce: true, idempotencyRequired: true, retryPolicy: { maxAttempts: 1 } },
+        observation: { mode: "independent_read_path", probeRef: "probe:record-status:v1", reconcileWithTargetAuditLog: true },
+        privacy: {
+            localOnly: ["prompt", "agentSource", "credentials", "rawArguments", "rawResult"],
+            disclose: ["actionType", "policyDecision", "outcomeStatus"],
+            commitOnly: ["resourceId", "canonicalAction"],
+        },
+        evidence: { require: ["sourceSignature", "serverReceipt", "grantBinding", "outcomeObservation", "sequenceContinuity"] },
+        revalidation: { triggers: ["agentVersion", "modelVersion", "promptDigest", "toolSchemaDigest", "policyVersion", "probeVersion"] },
+    };
+}
+export function resourceMatchesScope(scope, resourceId) {
+    if (!scope.type || !resourceId)
+        return false;
+    const wildcard = scope.pattern.indexOf("*");
+    if (wildcard < 0)
+        return resourceId === scope.pattern;
+    if (wildcard !== scope.pattern.length - 1 || scope.pattern.indexOf("*", wildcard + 1) >= 0)
+        return false;
+    return resourceId.startsWith(scope.pattern.slice(0, -1));
+}
+export function renderContractExplanation(contract) {
+    const compiled = compileAssuranceContract(contract);
+    return [
+        `Contract valid: ${contract.metadata.id} v${contract.metadata.version}`,
+        `Contract digest: ${compiled.sourceContractDigest}`,
+        `Capability: ${contract.capability.id} (${contract.capability.action}, ${contract.capability.risk} risk)`,
+        `Approval: ${contract.authority.approval.required ? "required and bound to exact action digest" : "not required"}`,
+        `Outcome probe: ${contract.observation.probeRef} via ${contract.observation.mode}`,
+        `Cloud disclosure: ${contract.privacy.disclose.join(", ") || "none"}`,
+        `Commitment only: ${contract.privacy.commitOnly.join(", ") || "none"}`,
+        `Local only: ${contract.privacy.localOnly.join(", ") || "none"}`,
+        `Revalidation triggers: ${contract.revalidation.triggers.join(", ")}`,
+        "Enforcement caveat: this contract covers only dispatches mediated by a credential-isolated Gateway.",
+    ].join("\n") + "\n";
+}
+function revalidationValues(contract) {
+    return {
+        agentId: contract.subject.agentId,
+        environment: contract.subject.environment,
+        capability: contract.capability,
+        authority: contract.authority,
+        effect: contract.effect,
+        observation: contract.observation,
+        privacy: contract.privacy,
+    };
+}
+function scopeExpanded(previous, next) {
+    if (previous.authority.resourceScope.pattern !== next.authority.resourceScope.pattern && next.authority.resourceScope.pattern === "*")
+        return true;
+    if (previous.authority.approval.required && !next.authority.approval.required)
+        return true;
+    if (!previous.capability.sideEffect && next.capability.sideEffect)
+        return true;
+    const rank = { low: 0, medium: 1, high: 2, critical: 3 };
+    return rank[next.capability.risk] > rank[previous.capability.risk];
+}
+function changed(previous, next, path = "") {
+    if (canonicalJson(previous) === canonicalJson(next))
+        return [];
+    if (Array.isArray(previous) || Array.isArray(next) || !previous || !next || typeof previous !== "object" || typeof next !== "object")
+        return [path || "$"];
+    const left = previous;
+    const right = next;
+    return [...new Set([...Object.keys(left), ...Object.keys(right)])].sort().flatMap((key) => changed(left[key], right[key], path ? `${path}.${key}` : key));
+}
+function predicates(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array.`);
+        return [];
+    }
+    return value.map((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        const result = object(item, itemPath, errors);
+        exactKeys(result, ["path", "operator", "value"], itemPath, errors, ["value"]);
+        requiredString(result.path, `${itemPath}.path`, errors);
+        oneOf(result.operator, ["equals", "not_equals", "exists", "not_exists", "contains", "count"], `${itemPath}.operator`, errors);
+        if (!["exists", "not_exists"].includes(String(result.operator)) && result.value === undefined)
+            errors.push(`${itemPath}.value is required for ${String(result.operator)}.`);
+        return result;
+    });
+}
+function object(value, path, errors) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        errors.push(`${path} must be an object.`);
+        return {};
+    }
+    return value;
+}
+function exactKeys(value, allowed, path, errors, optional = []) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            errors.push(`${path}.${key} is not allowed.`);
+    for (const key of allowed)
+        if (!optional.includes(key) && !(key in value))
+            errors.push(`${path}.${key} is required.`);
+}
+function requiredString(value, path, errors) {
+    if (typeof value !== "string" || !value.trim())
+        errors.push(`${path} must be a non-empty string.`);
+}
+function strings(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array.`);
+        return [];
+    }
+    const output = [];
+    value.forEach((item, index) => { requiredString(item, `${path}[${index}]`, errors); if (typeof item === "string")
+        output.push(item); });
+    if (new Set(output).size !== output.length)
+        errors.push(`${path} must not contain duplicates.`);
+    return output;
+}
+function positiveInteger(value, path, errors) {
+    if (!Number.isSafeInteger(value) || Number(value) <= 0)
+        errors.push(`${path} must be a positive safe integer.`);
+}
+function bool(value, path, errors) {
+    if (typeof value !== "boolean")
+        errors.push(`${path} must be Boolean.`);
+}
+function oneOf(value, allowed, path, errors) {
+    if (typeof value !== "string" || !allowed.includes(value))
+        errors.push(`${path} must be one of ${allowed.join(", ")}.`);
+}