witnora 0.18.2 → 0.18.4

package/dist/gateway-service.js

@@ -18,7 +18,13 @@ export async function installGatewayService(input) {
 export async function installCurrentGatewayService(options) {
     const planInput = currentPlanInput(options);
     return installGatewayService({ ...planInput,
-        writeDefinition: async (path, value) => { await mkdir(dirname(path), { recursive: true }); await writeFile(path, value, { encoding: "utf8", mode: 0o600 }); },
+        writeDefinition: async (path, value) => {
+            await mkdir(dirname(path), { recursive: true });
+            const contents = planInput.platform === "win32"
+                ? Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(value, "utf16le")])
+                : Buffer.from(value, "utf8");
+            await writeFile(path, contents, { mode: 0o600 });
+        },
         run: options.run ?? runCommand,
     });
 }
@@ -53,7 +59,7 @@ export function createGatewayServicePlan(input) {
 function windowsPlan(input, id, args) {
     const definitionPath = `${input.serviceHome}\\${id}.xml`;
     const argumentsValue = args.map(windowsArgument).join(" ");
-    const definition = `<?xml version="1.0" encoding="UTF-8"?>
+    const definition = `<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${xml(input.userId)}</UserId></LogonTrigger></Triggers>
   <Principals><Principal id="Author"><UserId>${xml(input.userId)}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>

package/dist/gateway.js

@@ -2,6 +2,7 @@ import { createHash, createPrivateKey, createPublicKey, randomBytes } from "node
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
 import { access, chmod, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { createServer as createNetServer } from "node:net";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { loadConnection } from "./credentials.js";
@@ -196,6 +197,44 @@ export async function upgradeCustomerGatewayRuntime(options) {
     }
     return { config: next, generatedFiles: [configPath, clientPath, readmePath, ...created, ...(replacingGeneratedRuntime ? [join(directory, runtimeKit.config.adapterModulePath), join(directory, runtimeKit.config.probeModulePath)] : [])], changed: true, rollback: restore };
 }
+export async function ensureCustomerGatewayPortAvailable(options) {
+    const directory = resolve(options.repository, options.dir ?? ".witnora/gateway");
+    const configPath = join(directory, "gateway.json");
+    const clientPath = join(directory, "client.mjs");
+    const readmePath = join(directory, "README.md");
+    const [configRaw, clientRaw, readmeRaw] = await Promise.all([
+        readFile(configPath, "utf8"), readFile(clientPath, "utf8"), readFile(readmePath, "utf8"),
+    ]);
+    const current = parseConfig(configRaw);
+    const health = await localCollector(current.host, current.port, options.fetch ?? fetch);
+    if (health === current.collectorId || (!health && await canListen(current.host, current.port))) {
+        return { changed: false, port: current.port };
+    }
+    if (clientRaw !== gatewayClient(current) || readmeRaw !== gatewayReadme(current)) {
+        throw new Error(`Gateway port ${current.port} is occupied, and generated Gateway files were modified; refusing to rewrite customer files.`);
+    }
+    const excluded = new Set([current.port]);
+    if (current.runtimeWorker?.sandboxOrigin)
+        excluded.add(Number(new URL(current.runtimeWorker.sandboxOrigin).port));
+    const port = await nextAvailablePort(current.host, current.port, excluded);
+    const next = { ...current, port };
+    if (next.runtimeWorker)
+        next.runtimeWorker = { ...next.runtimeWorker, configDigestSha256: undefined };
+    if (next.runtimeWorker)
+        next.runtimeWorker.configDigestSha256 = gatewayConfigDigest(next);
+    try {
+        await atomicWrite(configPath, `${JSON.stringify(next, null, 2)}\n`, 0o644);
+        await atomicWrite(clientPath, gatewayClient(next), 0o644);
+        await atomicWrite(readmePath, gatewayReadme(next), 0o644);
+    }
+    catch (error) {
+        await Promise.all([
+            atomicWrite(configPath, configRaw, 0o644), atomicWrite(clientPath, clientRaw, 0o644), atomicWrite(readmePath, readmeRaw, 0o644),
+        ]).catch(() => undefined);
+        throw error;
+    }
+    return { changed: true, port };
+}
 function sameRuntimeGeneration(left, right) {
     return JSON.stringify({ ...left, configDigestSha256: undefined }) === JSON.stringify({ ...right, configDigestSha256: undefined });
 }
@@ -1412,6 +1451,33 @@ async function atomicWrite(path, content, mode) {
     await rename(temporary, path);
     await chmod(path, mode).catch(() => undefined);
 }
+async function localCollector(host, port, requestFetch) {
+    try {
+        const response = await requestFetch(`http://${host}:${port}/healthz`, { signal: AbortSignal.timeout(750) });
+        if (!response.ok)
+            return "occupied";
+        const value = await response.json();
+        return typeof value.collectorId === "string" ? value.collectorId : "occupied";
+    }
+    catch {
+        return undefined;
+    }
+}
+async function canListen(host, port) {
+    const server = createNetServer();
+    return new Promise((resolvePromise) => {
+        server.once("error", () => resolvePromise(false));
+        server.listen(port, host, () => server.close(() => resolvePromise(true)));
+    });
+}
+async function nextAvailablePort(host, preferred, excluded) {
+    for (let offset = 1; offset <= 1_000; offset += 1) {
+        const candidate = 1_024 + ((preferred - 1_024 + offset) % (65_535 - 1_024));
+        if (!excluded.has(candidate) && await canListen(host, candidate))
+            return candidate;
+    }
+    throw new Error("No available localhost port was found for the customer-owned Gateway.");
+}
 async function exists(path) {
     try {
         await access(path);

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, initializeCustomerGateway, inspectLocalRuntimeBinding, inspectCustomerGatewayFiles, startManagedCustomerGateway, stopManagedCustomerGateway, upgradeCustomerGatewayRuntime, RuntimeSetupNotReadyError, } from "./gateway.js";
+import { doctorCustomerGateway, activateManagedWorkflowHarness, ensureCustomerGatewayPortAvailable, initializeCustomerGateway, inspectLocalRuntimeBinding, inspectCustomerGatewayFiles, startManagedCustomerGateway, 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";
@@ -217,6 +217,9 @@ export async function runOnboard(options) {
                 throw new Error("The prior managed Gateway process did not stop before Assurance Harness activation.");
         }
         if (!options.gatewayLifecycle) {
+            const port = await ensureCustomerGatewayPortAvailable({ repository: repositoryPath });
+            if (port.changed)
+                output(`Rebound this repository's generated Gateway to available localhost port ${port.port}; another project remains untouched.\n`);
             const installed = await installCurrentGatewayService({ repository: repositoryPath, cliEntry: fileURLToPath(new URL("./cli.js", import.meta.url)) });
             continuousService = { state: "INSTALLED", kind: installed.plan.kind, id: installed.plan.id };
         }

package/dist/private-discovery.js

@@ -31,7 +31,7 @@ export async function runPrivateCapabilityDiscovery(input) {
             localRedactionApplied: true,
         },
         capabilities: input.repository.capabilities,
-        unknownCapabilityCount: input.repository.capabilities.length,
+        unknownCapabilityCount: input.repository.capabilities.filter((item) => item.disposition === "pending").length,
     };
     const payloadSha256 = sha256(canonicalJson(payload));
     const privateKey = createPrivateKey(identity.privateKeyPem);
@@ -62,12 +62,13 @@ export async function runPrivateCapabilityDiscovery(input) {
 export function inferPrivateCapabilities(input) {
     const searchable = [...input.dependencyNames, ...input.topLevelNames].join(" ").toLowerCase();
     const detected = new Map();
-    const add = (key, observedName, transport) => detected.set(key, {
+    const add = (key, observedName, transport, capabilityId, disposition = "pending") => detected.set(key, {
         key,
         observedName,
         transport,
-        disposition: "pending",
-        schemaSha256: sha256(canonicalJson({ key, observedName, transport, source: "repository_metadata" })),
+        ...(capabilityId ? { capabilityId } : {}),
+        disposition,
+        schemaSha256: sha256(canonicalJson({ key, observedName, transport, capabilityId, disposition, source: "repository_metadata" })),
         source: "repository_metadata",
     });
     add("workflow:orchestration", "Workflow orchestration", "workflow");
@@ -84,7 +85,7 @@ export function inferPrivateCapabilities(input) {
     if (/slack|discord|twilio|resend|sendgrid|postmark|nodemailer|email/.test(searchable))
         add("messaging:external", "External messaging", "messaging");
     for (const capability of repositoryManifestCapabilities(input.manifest))
-        add(capability.key, capability.observedName, capability.transport);
+        add(capability.key, capability.observedName, capability.transport, capability.capabilityId, capability.disposition);
     return [...detected.values()].sort((left, right) => left.key.localeCompare(right.key));
 }
 function repositoryManifestCapabilities(value) {
@@ -101,13 +102,21 @@ function repositoryManifestCapabilities(value) {
         if (!item || typeof item !== "object" || Array.isArray(item))
             throw new Error(`Repository discovery manifest capability ${index} is invalid.`);
         const capability = item;
-        if (Object.keys(capability).some((key) => key !== "key" && key !== "observedName" && key !== "transport")
+        if (Object.keys(capability).some((key) => !["key", "observedName", "transport", "capabilityId", "disposition"].includes(key))
             || typeof capability.key !== "string" || !/^[A-Za-z0-9._:-]{1,120}$/.test(capability.key)
             || typeof capability.observedName !== "string" || !/^[A-Za-z0-9._:-]{1,120}$/.test(capability.observedName)
-            || !transports.has(capability.transport)) {
+            || !transports.has(capability.transport)
+            || capability.capabilityId !== undefined && (typeof capability.capabilityId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(capability.capabilityId))
+            || capability.disposition !== undefined && !["allowed", "approval_required", "denied", "pending"].includes(String(capability.disposition))) {
             throw new Error(`Repository discovery manifest capability ${index} failed its bounded contract.`);
         }
-        return { key: capability.key, observedName: capability.observedName, transport: capability.transport };
+        return {
+            key: capability.key,
+            observedName: capability.observedName,
+            transport: capability.transport,
+            ...(capability.capabilityId ? { capabilityId: capability.capabilityId } : {}),
+            disposition: capability.disposition ?? "pending",
+        };
     });
 }
 function discoveryIdentityPath(projectId, configHome) {

package/dist/real-path-activation.js

@@ -84,6 +84,8 @@ async function providerPreflight(request, env, plan, now, postgresClientFactory)
     throw new Error(`${plan.generated.providerPackId} activation is not implemented by this CLI version.`);
 }
 async function shopifyDisputePreflight(request, env, plan, now) {
+    if (plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined)
+        return shopifySandboxFixturePreflight(plan, now);
     const token = env.SHOPIFY_READ_ACCESS_TOKEN;
     if (!token || token.length < 8)
         throw new Error("Shopify activation requires the read-only SHOPIFY_READ_ACCESS_TOKEN in the customer environment.");
@@ -103,6 +105,12 @@ async function shopifyDisputePreflight(request, env, plan, now) {
     assertCriterion(plan, observation);
     return preflightResult(plan, now, "shopify", id, observation);
 }
+function shopifySandboxFixturePreflight(plan, now) {
+    const resourceId = `sellershield-dispute-${sha(plan.taskContractDigestSha256).slice(0, 16)}`;
+    const observation = { status: plan.generated.criterion.expected };
+    const resultDigest = sha(canonical(observation));
+    return { acceptance: { kind: "READ_ONLY_PROVIDER_PREFLIGHT", passedAt: now.toISOString(), productionWrites: 0, observationDigestSha256: resultDigest }, scenario: { id: `shopify-sandbox:${sha(resourceId).slice(0, 16)}`, source: "SANDBOX_FIXTURE", sanitized: true, input: { resourceId }, inputDigestSha256: sha(canonical({ resourceId })), baseline: { resultDigestSha256: resultDigest, actionIntents: plan.generated.actionPathBindings.map((item) => ({ pathId: item.actionPathId, parametersDigestSha256: sha(resourceId) })) } } };
+}
 async function stripePreflight(request, secret, plan, now) {
     const response = await request("https://api.stripe.com/v1/refunds?limit=1", { headers: { authorization: `Bearer ${secret}` }, redirect: "error", signal: AbortSignal.timeout(5_000) });
     if (!response.ok)
@@ -214,14 +222,14 @@ async function postgresPreflight(env, plan, now, clientFactory) {
 }
 async function defaultPostgresClient(connectionString) { const imported = await import("pg"); return new imported.Client({ connectionString, application_name: "witnora-read-only-preflight" }); }
 function generatedProviderHarness(plans) {
-    const contracts = plans.map((plan) => ({ taskContractId: plan.taskContractId, providerPackId: plan.generated.providerPackId, providerConfiguration: plan.generated.providerConfiguration ?? {}, credentialHandle: `.witnora/provider-credentials/${plan.id}.secret`, criterion: plan.generated.criterion, actionPathIds: plan.generated.actionPathBindings.map((item) => item.actionPathId) }));
+    const contracts = plans.map((plan) => ({ taskContractId: plan.taskContractId, providerPackId: plan.generated.providerPackId, providerConfiguration: plan.generated.providerConfiguration ?? {}, credentialHandle: `.witnora/provider-credentials/${plan.id}.secret`, criterion: plan.generated.criterion, actionPathIds: plan.generated.actionPathBindings.map((item) => item.actionPathId), ...(plan.generated.providerPackId === "SHOPIFY_DISPUTE" && plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined ? { sandboxObservation: { [plan.generated.criterion.field]: plan.generated.criterion.expected } } : {}) }));
     return `import {createHash} from "node:crypto";
 import {readFile} from "node:fs/promises";
 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)=>{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("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;},
 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}]};}
@@ -230,6 +238,8 @@ export async function checkWitnoraProviderHealth(context){for(const contract of
 `;
 }
 async function persistProviderCredential(repository, plan, environment) {
+    if (plan.generated.providerPackId === "SHOPIFY_DISPUTE" && plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined)
+        return;
     const name = providerCredentialEnvironmentName(plan.generated.providerPackId);
     const value = environment[name];
     if (!value)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "Apache-2.0",