witnora 0.19.2 → 0.20.2

package/dist/cli.js

@@ -158,6 +158,7 @@ else if (command === "onboard") {
         name: readFlag("--name"),
         repository: readFlag("--repo") ?? process.cwd(),
         template: readFlag("--template") ? parseAgentTemplate(readFlag("--template")) : undefined,
+        actionTransport: readActionTransport(readFlag("--action-transport")),
         openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
     });
 }
@@ -906,6 +907,13 @@ else {
   witnora schema validate --schema evidence-bundle --file .witnora/latest/agentcert-evidence.json
 `);
 }
+function readActionTransport(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "http" || value === "mcp")
+        return value;
+    throw new Error("--action-transport must be http or mcp.");
+}
 async function loadConfig(path) {
     if (!path) {
         return undefined;

package/dist/command-help.js

@@ -41,11 +41,13 @@ Options:
         return `Usage:
   witnora onboard --project <project-id>
   witnora onboard --project <project-id> --template <browser|coding|mcp|workflow|data>
+  witnora onboard --project <project-id> --action-transport <http|mcp>
 
 Opens one browser authorization, saves a restricted project credential, detects the repository,
 writes missing starter files, starts a customer-owned Gateway in the background, and records an
 isolated synthetic self-test receipt. The self-test does not create assurance evidence or establish
-CURRENT status.
+CURRENT status. When --action-transport is selected, Witnora validates that exact local transport
+without proposing or executing an Action and reports the bounded result to Hosted.
 
 Options:
   --server <url>          Hosted server (default: https://witnora.com)
@@ -53,6 +55,7 @@ Options:
   --name <name>           Saved connection name (default: repository name)
   --repo <directory>      Repository to configure (default: current directory)
   --template <type>       Override automatic repository detection
+  --action-transport <t>  Test HTTP or MCP against the exact generated sandbox Action path
   --no-browser            Print the approval URL without opening it
 `;
     if (command === "mcp")

package/dist/mcp.js

@@ -1,4 +1,6 @@
 import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -52,6 +54,29 @@ export async function runWitnoraMcpStdioServer(options = {}) {
     const { server } = await createWitnoraMcpServerFromRepository(options);
     await server.connect(new StdioServerTransport());
 }
+export async function testWitnoraMcpConnection(options = {}) {
+    const { server, actionTool, action } = await createWitnoraMcpServerFromRepository(options);
+    const client = new Client({ name: "witnora-onboarding-connection-test", version: "1.0.0" });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    try {
+        await server.connect(serverTransport);
+        await client.connect(clientTransport);
+        const listed = await client.listTools();
+        const tools = listed.tools.map((tool) => tool.name).sort();
+        const expected = [actionTool, "witnora_get_action"].sort();
+        if (JSON.stringify(tools) !== JSON.stringify(expected)) {
+            throw new Error("Witnora MCP connection test found an unexpected tool surface.");
+        }
+        if (tools.some((tool) => /approve|execute|verify/i.test(tool))) {
+            throw new Error("Witnora MCP connection test found a forbidden authority-bearing tool.");
+        }
+        return { actionId: action.id, actionTool, tools };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+    }
+}
 export function witnoraMcpActionToolName(actionId) {
     const normalized = actionId.toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "action";
     const candidate = `witnora_${normalized}`;

package/dist/onboard.js

@@ -8,7 +8,7 @@ import { verifyControlPlaneConnection } from "./control-plane.js";
 import { inferPrivateCapabilities, runPrivateCapabilityDiscovery } from "./private-discovery.js";
 import { parseAgentTemplate, starterAdapter, starterProfile, starterTripwireConfig } from "./onboarding-templates.js";
 import { writeTryEvidence } from "./try.js";
-import { doctorCustomerGateway, activateManagedWorkflowHarness, configureCustomerHttpAction, ensureCustomerGatewayPortAvailable, initializeCustomerGateway, inspectLocalRuntimeBinding, inspectCustomerGatewayFiles, startManagedCustomerGateway, statusManagedCustomerGateway, stopManagedCustomerGateway, upgradeCustomerGatewayRuntime, RuntimeSetupNotReadyError, } from "./gateway.js";
+import { doctorCustomerGateway, activateManagedWorkflowHarness, configureCustomerHttpAction, ensureCustomerGatewayPortAvailable, initializeCustomerGateway, inspectLocalRuntimeBinding, inspectCustomerGatewayFiles, loadCustomerMcpActionBinding, startManagedCustomerGateway, statusManagedCustomerGateway, stopManagedCustomerGateway, upgradeCustomerGatewayRuntime, RuntimeSetupNotReadyError, } from "./gateway.js";
 import { discoverRuntimeReferences, planRuntimeSandboxModules } from "./runtime-sandbox-kit.js";
 import { automaticRuntimeReferencesUsable, bootstrapLocalRuntime, verifyAutomaticRuntimeProbe } from "./runtime-bootstrap.js";
 import { activateRealPathIntegrations } from "./real-path-activation.js";
@@ -294,6 +294,19 @@ export async function runOnboard(options) {
         const runtimeReadiness = doctor.overall === "READY_FOR_RUNTIME" && runtimeBinding
             ? { state: "LOCAL_SANDBOX_READY", checkedAt: new Date().toISOString(), limitations: [] }
             : { state: "RECORDED_ONLY", checkedAt: new Date().toISOString(), limitations: [runtimeLimitation ?? "The local sandbox Runtime worker has not established exact adapter, probe, source-key, identity, mandate, and readiness bindings."] };
+        const actionTransportTest = options.actionTransport
+            ? await runActionTransportTest({
+                transport: options.actionTransport,
+                repository: repositoryPath,
+                server,
+                projectId: token.projectId,
+                apiKey: token.apiKey,
+                repositoryIdentity: repository,
+                httpActionReady: httpActionSetup?.state === "READY" && Boolean(httpActionSetup.action),
+                fetch: requestFetch,
+                generatedFiles,
+            })
+            : undefined;
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
             status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), runtimeReadiness,
             connectedAgent: agentIdentity,
@@ -316,11 +329,20 @@ export async function runOnboard(options) {
         if (httpActionSetup?.state === "READY" && httpActionSetup.action) {
             output(`HTTP Action: READY. POST ${managedGateway.baseUrl}${httpActionSetup.action.path}; copy the action-scoped token and request example from .witnora/gateway/HTTP_ACTION.md.\n`);
         }
-        output("Connected. Nora is monitoring this Agent. Run it normally whenever it is ready; the first source-signed activity will appear automatically without blocking setup.\n");
+        if (actionTransportTest?.state === "PASSED") {
+            output(`Action transport: ${actionTransportTest.transport.toUpperCase()} connection test PASSED at the customer-owned Gateway. No Action was proposed or executed.\n`);
+        }
+        else if (actionTransportTest) {
+            output(`Action transport: ${actionTransportTest.transport.toUpperCase()} is waiting for one exact sandbox Task/action path. ${actionTransportTest.limitation}\n`);
+        }
+        output(actionTransportTest?.state === "WAITING_FOR_ACTION_PATH"
+            ? `Base Gateway connected, but ${actionTransportTest.transport.toUpperCase()} Action is not verified yet. Go to Overview, run the Agent once, confirm one exact sandbox Business Task/action path, then rerun this same command.\n`
+            : "Connected. Nora is monitoring this Agent. Run it normally whenever it is ready; the first source-signed activity will appear automatically without blocking setup.\n");
         return { projectId: token.projectId, connectionName: token.connectionName, credentialsPath, template: repository.template,
             repositoryKind: repository.kind, generatedFiles, receiptPath, discovery, setupPlanId: setupPlan.id,
             gatewayDirectory: join(repositoryPath, ".witnora", "gateway"), gatewayArchiveDirectory: gatewayMigration?.archiveDirectory,
             gateway: managedGateway, runtimeReadiness, assuranceHarnessReadiness, continuousService,
+            actionTransportTest,
             ...(httpActionSetup?.state === "READY" && httpActionSetup.action ? { httpAction: {
                     state: "READY",
                     method: "POST",
@@ -346,6 +368,58 @@ export async function runOnboard(options) {
         throw new Error(`Witnora Setup Autopilot rolled back this install attempt: ${diagnosis}`);
     }
 }
+async function runActionTransportTest(options) {
+    if (!options.httpActionReady)
+        return {
+            state: "WAITING_FOR_ACTION_PATH",
+            transport: options.transport,
+            limitation: "Define and approve one exact sandbox Task/action Harness, then rerun this same onboarding command.",
+        };
+    const binding = await loadCustomerMcpActionBinding({ repository: options.repository });
+    const checkedAt = new Date().toISOString();
+    const passed = options.transport === "http"
+        ? {
+            state: "PASSED",
+            transport: "http",
+            checkedAt,
+            actionId: binding.action.id,
+            endpoint: `${binding.baseUrl}${binding.action.path}`,
+        }
+        : await import("./mcp.js").then(async ({ testWitnoraMcpConnection }) => {
+            const result = await testWitnoraMcpConnection({ repository: options.repository, fetch: options.fetch });
+            return {
+                state: "PASSED",
+                transport: "mcp",
+                checkedAt,
+                actionId: result.actionId,
+                actionTool: result.actionTool,
+            };
+        });
+    const report = {
+        transport: passed.transport,
+        actionId: passed.actionId,
+        ...(passed.transport === "http" ? { endpoint: passed.endpoint } : { actionTool: passed.actionTool }),
+    };
+    const receipt = await jsonRequest(options.fetch, `${options.server}/v1/projects/${encodeURIComponent(options.projectId)}/onboarding/self-test`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${options.apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify({
+            template: options.repositoryIdentity.template,
+            repository: {
+                kind: options.repositoryIdentity.kind,
+                name: options.repositoryIdentity.name,
+                fingerprintSha256: options.repositoryIdentity.fingerprintSha256,
+                actionTransportTest: report,
+            },
+            bundleSha256: createHash("sha256").update(JSON.stringify(report)).digest("hex"),
+        }),
+    });
+    const receiptPath = join(options.repository, ".witnora", "onboarding", "receipts", `action-transport-${passed.transport}-${Date.now()}.json`);
+    await mkdir(dirname(receiptPath), { recursive: true });
+    await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+    options.generatedFiles.push(receiptPath);
+    return { ...passed, receiptPath };
+}
 async function waitForInstalledGatewayService(options) {
     const pause = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
     const deadline = Date.now() + (options.timeoutMs ?? 12_000);

package/dist/real-path-activation.js

@@ -84,9 +84,7 @@ export async function activateRealPathIntegrations(options) {
 }
 async function providerPreflight(request, env, plan, now, postgresClientFactory) {
     if (plan.generated.providerPackId === "STRIPE_REFUND") {
-        const secret = env.STRIPE_SECRET_KEY;
-        if (!secret?.startsWith("sk_test_") || secret.length < 12)
-            throw new Error("Stripe test-mode activation requires STRIPE_SECRET_KEY to reference an sk_test_ credential in the customer environment.");
+        const secret = stripeTestCredential(env);
         return stripePreflight(request, secret, plan, now);
     }
     if (plan.generated.providerPackId === "SHOPIFY_DISPUTE")
@@ -252,7 +250,7 @@ import {join} from "node:path";
 const contracts=${JSON.stringify(contracts)};
 const sha=(value)=>createHash("sha256").update(typeof value==="string"?value:JSON.stringify(value)).digest("hex");
 const request=async(url,key)=>{const response=await fetch(url,{method:"GET",headers:{accept:"application/json",authorization:"Bearer "+key},redirect:"error",signal:AbortSignal.timeout(5000)});if(!response.ok)throw new Error("Provider read-only observation failed ("+response.status+").");return response.json();};
-const observe=async(contract,resourceId,repository)=>{if(contract.sandboxObservation)return structuredClone(contract.sandboxObservation);const key=(await readFile(join(repository,contract.credentialHandle),"utf8")).trim();if(!key)throw new Error("The local read-only Provider credential is unavailable.");if(contract.providerPackId==="STRIPE_REFUND"){if(!key.startsWith("sk_test_"))throw new Error("Stripe test-mode credential is unavailable.");return request("https://api.stripe.com/v1/refunds/"+encodeURIComponent(resourceId),key);}if(contract.providerPackId==="SHOPIFY_DISPUTE"){const response=await fetch(contract.providerConfiguration.origin+"/admin/api/2025-07/shopify_payments/disputes/"+encodeURIComponent(resourceId)+".json",{method:"GET",headers:{accept:"application/json","x-shopify-access-token":key},redirect:"error",signal:AbortSignal.timeout(5000)});if(!response.ok)throw new Error("Provider read-only observation failed ("+response.status+").");return (await response.json()).dispute;}if(contract.providerPackId==="ZENDESK_TICKET")return (await request(contract.providerConfiguration.origin+"/api/v2/tickets/"+encodeURIComponent(resourceId)+".json",key)).ticket;if(contract.providerPackId==="SALESFORCE_RECORD")return request(contract.providerConfiguration.origin+"/services/data/v61.0/sobjects/"+encodeURIComponent(contract.providerConfiguration.resourceType)+"/"+encodeURIComponent(resourceId),key);if(contract.providerPackId==="HUBSPOT_CRM_RECORD")return (await request("https://api.hubapi.com/crm/v3/objects/"+encodeURIComponent(contract.providerConfiguration.resourceType)+"/"+encodeURIComponent(resourceId)+"?properties="+encodeURIComponent(contract.criterion.field),key)).properties;if(contract.providerPackId==="POSTGRES_RECORD"){for(const name of [contract.providerConfiguration.viewName,contract.providerConfiguration.idColumn,contract.criterion.field])if(!/^[A-Za-z][A-Za-z0-9_]{0,99}$/.test(name))throw new Error("PostgreSQL identifier is invalid.");const {Client}=await import("pg");const client=new Client({connectionString:key,application_name:"witnora-read-only-probe"});await client.connect();try{await client.query("BEGIN READ ONLY");const result=await client.query({name:"witnora-provider-observe",text:'SELECT "'+contract.criterion.field+'" FROM "'+contract.providerConfiguration.viewName+'" WHERE "'+contract.providerConfiguration.idColumn+'" = $1 LIMIT 1',values:[resourceId]});await client.query("ROLLBACK");return result.rows[0]??{};}catch(error){await client.query("ROLLBACK").catch(()=>{});throw error;}finally{await client.end();}}throw new Error("Provider Harness contract is unsupported.");};
+const observe=async(contract,resourceId,repository)=>{if(contract.sandboxObservation)return structuredClone(contract.sandboxObservation);const key=(await readFile(join(repository,contract.credentialHandle),"utf8")).trim();if(!key)throw new Error("The local read-only Provider credential is unavailable.");if(contract.providerPackId==="STRIPE_REFUND"){if(!key.startsWith("rk_test_")&&!key.startsWith("sk_test_"))throw new Error("Stripe test-mode credential is unavailable.");return request("https://api.stripe.com/v1/refunds/"+encodeURIComponent(resourceId),key);}if(contract.providerPackId==="SHOPIFY_DISPUTE"){const response=await fetch(contract.providerConfiguration.origin+"/admin/api/2025-07/shopify_payments/disputes/"+encodeURIComponent(resourceId)+".json",{method:"GET",headers:{accept:"application/json","x-shopify-access-token":key},redirect:"error",signal:AbortSignal.timeout(5000)});if(!response.ok)throw new Error("Provider read-only observation failed ("+response.status+").");return (await response.json()).dispute;}if(contract.providerPackId==="ZENDESK_TICKET")return (await request(contract.providerConfiguration.origin+"/api/v2/tickets/"+encodeURIComponent(resourceId)+".json",key)).ticket;if(contract.providerPackId==="SALESFORCE_RECORD")return request(contract.providerConfiguration.origin+"/services/data/v61.0/sobjects/"+encodeURIComponent(contract.providerConfiguration.resourceType)+"/"+encodeURIComponent(resourceId),key);if(contract.providerPackId==="HUBSPOT_CRM_RECORD")return (await request("https://api.hubapi.com/crm/v3/objects/"+encodeURIComponent(contract.providerConfiguration.resourceType)+"/"+encodeURIComponent(resourceId)+"?properties="+encodeURIComponent(contract.criterion.field),key)).properties;if(contract.providerPackId==="POSTGRES_RECORD"){for(const name of [contract.providerConfiguration.viewName,contract.providerConfiguration.idColumn,contract.criterion.field])if(!/^[A-Za-z][A-Za-z0-9_]{0,99}$/.test(name))throw new Error("PostgreSQL identifier is invalid.");const {Client}=await import("pg");const client=new Client({connectionString:key,application_name:"witnora-read-only-probe"});await client.connect();try{await client.query("BEGIN READ ONLY");const result=await client.query({name:"witnora-provider-observe",text:'SELECT "'+contract.criterion.field+'" FROM "'+contract.providerConfiguration.viewName+'" WHERE "'+contract.providerConfiguration.idColumn+'" = $1 LIMIT 1',values:[resourceId]});await client.query("ROLLBACK");return result.rows[0]??{};}catch(error){await client.query("ROLLBACK").catch(()=>{});throw error;}finally{await client.end();}}throw new Error("Provider Harness contract is unsupported.");};
 export function createWitnoraBusinessTaskEvaluatorOptions(context){return {
 loadShadowObservations:async(task)=>{const contract=contracts.find((item)=>item.taskContractId===task.id);if(!contract)throw new Error("No exact real-path contract.");const path=join(context.repository,".witnora","scenarios",task.id+".json");const value=JSON.parse(await readFile(path,"utf8"));if(!Array.isArray(value)||value.length>100)throw new Error("Local scenario file is invalid.");return value.map((item)=>({...item,source:"LIVE_SHADOW"}));},
 evaluateShadowCandidate:async(candidate,task)=>{const contract=contracts.find((item)=>item.taskContractId===task.id);if(!contract)throw new Error("No exact real-path contract.");const resourceId=String(candidate.input?.resourceId??"");if(!/^[A-Za-z0-9._:-]{1,200}$/.test(resourceId))throw new Error("Provider resourceId is invalid.");for(const pathId of contract.actionPathIds)candidate.propose({pathId,parametersDigestSha256:sha(resourceId)});const raw=await observe(contract,resourceId,context.repository);const actual=raw?.[contract.criterion.field];const observed=actual===undefined?{}:{[contract.criterion.field]:actual};return {resultDigestSha256:sha(observed),criteria:[{id:contract.criterion.id,passed:actual===contract.criterion.expected}]};}
@@ -265,11 +263,14 @@ async function persistProviderCredential(repository, plan, environment) {
         return;
     if (plan.generated.providerPackId === "QUEUE_JOB" && plan.environment === "sandbox")
         return;
-    const name = providerCredentialEnvironmentName(plan.generated.providerPackId);
-    const value = environment[name];
     const directory = join(repository, ".witnora", "provider-credentials");
     const target = join(directory, `${plan.id}.secret`);
     const current = await readFile(target, "utf8").catch((error) => error.code === "ENOENT" ? undefined : Promise.reject(error));
+    const name = providerCredentialEnvironmentName(plan.generated.providerPackId);
+    const stripeCredentialSupplied = Boolean(environment.STRIPE_RESTRICTED_TEST_KEY?.trim() || environment.STRIPE_SECRET_KEY?.trim());
+    const value = plan.generated.providerPackId === "STRIPE_REFUND"
+        ? stripeCredentialSupplied ? stripeTestCredential(environment) : undefined
+        : environment[name];
     if (!value) {
         if (current !== undefined)
             return;
@@ -294,7 +295,7 @@ function sameActivationPlans(plans, activations) {
 }
 function providerCredentialEnvironmentName(packId) {
     if (packId === "STRIPE_REFUND")
-        return "STRIPE_SECRET_KEY";
+        return "STRIPE_RESTRICTED_TEST_KEY";
     if (packId === "SHOPIFY_DISPUTE")
         return "SHOPIFY_READ_ACCESS_TOKEN";
     if (packId === "ZENDESK_TICKET")
@@ -307,6 +308,18 @@ function providerCredentialEnvironmentName(packId) {
         return "WITNORA_POSTGRES_READ_URL";
     throw new Error(`Provider credential mapping is not supported for ${packId}.`);
 }
+function stripeTestCredential(environment) {
+    const restricted = environment.STRIPE_RESTRICTED_TEST_KEY?.trim();
+    if (restricted) {
+        if (!restricted.startsWith("rk_test_") || restricted.length < 12)
+            throw new Error("Stripe sandbox activation requires STRIPE_RESTRICTED_TEST_KEY to contain an rk_test_ restricted test key.");
+        return restricted;
+    }
+    const legacy = environment.STRIPE_SECRET_KEY?.trim();
+    if (!legacy?.startsWith("sk_test_") || legacy.length < 12)
+        throw new Error("Stripe sandbox activation requires a read-only rk_test_ key in STRIPE_RESTRICTED_TEST_KEY. STRIPE_SECRET_KEY remains a legacy sk_test_ fallback only.");
+    return legacy;
+}
 function parsePlan(value) { if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("Real-path integration response is invalid."); const plan = value; if (plan.schemaVersion !== "witnora.real_path_integration.v0.1" || !plan.id || !plan.taskContractId || !plan.subject?.agentId || !plan.subject.agentVersion || !plan.generated || plan.generated.boundaries?.rawPayloadUpload !== false || plan.generated.boundaries.rawCredentialUpload !== false || plan.generated.boundaries.evaluatorWrites !== false || plan.generated.boundaries.firstAcceptanceProductionWrites !== 0 || !digest(plan.digestSha256) || !digest(plan.taskContractDigestSha256) || !digest(plan.generated.providerContractDigestSha256))
     throw new Error("Real-path integration response failed its safety contract."); return plan; }

package/mcp.d.ts

@@ -39,4 +39,13 @@ export function runWitnoraMcpStdioServer(options?: {
   fetch?: typeof fetch;
 }): Promise<void>;
 
+export function testWitnoraMcpConnection(options?: {
+  repository?: string;
+  dir?: string;
+  fetch?: typeof fetch;
+}): Promise<{
+  actionTool: string;
+  tools: string[];
+}>;
+
 export function witnoraMcpActionToolName(actionId: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.19.2",
+  "version": "0.20.2",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",