xoonya 2.4.0 → 2.6.0

package/bin/xoonya-first-run.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const DEFAULT_KIT_URL = "https://www.naxytra.com/v1/first-run-kit";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    index += 1;
+  }
+  return args;
+}
+
+function buildLocalGuide() {
+  return {
+    ok: true,
+    product: "xoonya",
+    category: "xoonya-first-run-proof-guide",
+    guide_version: "xoonya-first-run-proof-guide-v1",
+    public_command_kit_url: DEFAULT_KIT_URL,
+    role: "proof_followthrough_after_xytara_runtime_execution",
+    safe_local_verification_command: "xoonya first-run --verify-native --pretty",
+    proof_modes: [
+      {
+        method: "xoonya-native-sha256-v1",
+        verification: "replayable_digest"
+      },
+      {
+        method: "xoonya-native-signed-v1",
+        verification: "ed25519_signature"
+      },
+      {
+        method: "xoonya-native-anchored-v1",
+        verification: "anchor_binding"
+      },
+      {
+        method: "external_interop_methods",
+        verification: "structure_checked_external_verifier_boundary"
+      }
+    ],
+    public_checks: [
+      "https://xoonya.onrender.com/v1/proof-center/native-standard/summary",
+      "https://xoonya.onrender.com/v1/proof-center/native-atom-conformance/summary",
+      "https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary"
+    ],
+    boundaries: [
+      "xoonya_verifies_proof_bundles_and_native_method_binding",
+      "xoonya_anchor_binding_does_not_claim_external_provider_or_chain_truth",
+      "xytara_owns_runtime_payment_and_execution_state"
+    ]
+  };
+}
+
+async function fetchPublicKit(url) {
+  const response = await fetch(url, { headers: { accept: "application/json" } });
+  if (!response.ok) {
+    throw new Error(`first_run_kit_fetch_failed_${response.status}`);
+  }
+  return response.json();
+}
+
+function writeJson(payload, pretty) {
+  process.stdout.write(`${JSON.stringify(payload, null, pretty ? 2 : 0)}\n`);
+}
+
+function printUsage() {
+  process.stdout.write([
+    "Usage: xoonya first-run [options]",
+    "",
+    "Options:",
+    "  --json             Print the guided proof followthrough object",
+    "  --offline          Do not fetch the public command kit",
+    "  --verify-native    Run local native/conformance verification",
+    "  --pretty           Pretty-print JSON output",
+    "  --help             Show this help message"
+  ].join("\n"));
+}
+
+function runNativeVerification(args) {
+  const scriptPath = path.join(__dirname, "..", "scripts", "verify_vectors.js");
+  const result = spawnSync(process.execPath, [
+    scriptPath,
+    "--json"
+  ], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"]
+  });
+  if (result.status !== 0) {
+    process.exitCode = typeof result.status === "number" ? result.status : 1;
+    return;
+  }
+  const summary = JSON.parse(result.stdout);
+  writeJson({
+    ok: true,
+    product: "xoonya",
+    category: "xoonya-first-run-native-verification",
+    verification_version: "xoonya-first-run-native-verification-v1",
+    proof_bundle_conformance_passed: summary.ok === true,
+    conformance_count: summary.conformance_count,
+    adversarial_count: summary.adversarial_count,
+    native_atom_vector_count: summary.native_atom_vector_count,
+    native_atom_adversarial_count: summary.native_atom_adversarial_count,
+    verification_methods: summary.verification_methods,
+    native_atom_error_codes: summary.native_atom_error_codes,
+    required_native_methods_present: [
+      "xoonya-native-sha256-v1",
+      "xoonya-native-signed-v1",
+      "xoonya-native-anchored-v1"
+    ].every((method) => summary.verification_methods.includes(method)),
+    boundary: "local_conformance_verifies_xoonya_binding_and_vectors_not_external_chain_truth"
+  }, args.pretty);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printUsage();
+    return;
+  }
+  if (args["verify-native"]) {
+    runNativeVerification(args);
+    return;
+  }
+
+  const localGuide = buildLocalGuide();
+  if (args.json) {
+    if (args.offline) {
+      writeJson(localGuide, args.pretty);
+      return;
+    }
+    try {
+      const publicKit = await fetchPublicKit(DEFAULT_KIT_URL);
+      writeJson({
+        ...localGuide,
+        public_command_kit: publicKit
+      }, args.pretty);
+    } catch (error) {
+      writeJson({
+        ...localGuide,
+        public_command_kit_fetch_error: error.message
+      }, args.pretty);
+    }
+    return;
+  }
+
+  process.stdout.write([
+    "xoonya first-run",
+    "",
+    "Proof followthrough after xytara execution:",
+    "  xoonya first-run --verify-native --pretty",
+    "",
+    "Inspect the public command kit:",
+    `  ${DEFAULT_KIT_URL}`,
+    "",
+    "Native proof modes checked locally:",
+    "  xoonya-native-sha256-v1",
+    "  xoonya-native-signed-v1",
+    "  xoonya-native-anchored-v1",
+    "",
+    "Public proof surfaces:",
+    "  https://xoonya.onrender.com/v1/proof-center/native-standard/summary",
+    "  https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary",
+    "",
+    "Boundary:",
+    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external."
+  ].join("\n"));
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/bin/xoonya.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function printUsage() {
+  process.stdout.write([
+    "Usage: xoonya <command> [options]",
+    "",
+    "Commands:",
+    "  release [args]    Open the release/adoption/reporting surface",
+    "  review [args]     Review a carried handoff or proof input",
+    "  conformance       Run proof conformance and adversarial vectors",
+    "  first-run [args]  Guide or run proof followthrough checks",
+    "  start-here        Print the shortest first-run path",
+    "  help              Show this help message",
+    "",
+    "Fastest first run:",
+    "  xoonya start-here",
+    "  xoonya first-run",
+    "  xoonya first-run --verify-native --pretty",
+    "  xoonya release --summary",
+    "  xoonya conformance --json",
+    "  xoonya review --help"
+  ].join("\n"));
+}
+
+function printStartHere() {
+  process.stdout.write([
+    "xoonya start-here",
+    "",
+    "Public first-run spine:",
+    "  quote -> pay/credits -> execute -> prove",
+    "",
+    "1. Open https://www.naxytra.com/v1/first-run-kit",
+    "2. Run the xytara quote-only command first; it needs no wallet secret.",
+    "3. After funded execution, verify the proof side:",
+    "   xoonya first-run --verify-native --pretty",
+    "   node examples/package_quickstart.js",
+    "   xoonya conformance --json",
+    "4. Inspect native proof surfaces:",
+    "   https://xoonya.onrender.com/v1/proof-center/native-standard/summary",
+    "   https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary",
+    "",
+    "Native proof modes:",
+    "  xoonya-native-sha256-v1     replayable digest proof",
+    "  xoonya-native-signed-v1     key-bound authorship proof",
+    "  xoonya-native-anchored-v1   anchor-binding proof",
+    "",
+    "Boundary:",
+    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external"
+  ].join("\n"));
+}
+
+function delegate(scriptName, args) {
+  const scriptPath = path.join(__dirname, scriptName);
+  const result = spawnSync(process.execPath, [scriptPath, ...args], { stdio: "inherit" });
+  process.exitCode = typeof result.status === "number" ? result.status : 1;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  printUsage();
+} else if (command === "start-here" || command === "--start-here") {
+  printStartHere();
+} else if (command === "release") {
+  delegate("xoonya-release.js", rest);
+} else if (command === "review") {
+  delegate("xoonya-review.js", rest);
+} else if (command === "first-run" || command === "firstrun") {
+  delegate("xoonya-first-run.js", rest);
+} else if (command === "conformance" || command === "verify-vectors") {
+  const scriptPath = path.join(__dirname, "..", "scripts", "verify_vectors.js");
+  const result = spawnSync(process.execPath, [scriptPath, ...rest], { stdio: "inherit" });
+  process.exitCode = typeof result.status === "number" ? result.status : 1;
+} else {
+  printUsage();
+  process.exitCode = 1;
+}

package/lib/artifact_distribution_lane_contract.js

@@ -0,0 +1,54 @@
+"use strict";
+
+function buildArtifactDistributionLanePack() {
+  return {
+    product: "xoonya",
+    category: "proof-artifact-distribution-lane-pack",
+    pack_version: "xoonya-artifact-distribution-lane-pack-v1",
+    lane_state: "first_party_artifact_distribution_lane_present",
+    posture: "oci_style_distribution_for_proof_bundles_and_integration_artifacts",
+    standards: ["oci_artifacts", "oras_style_distribution"],
+    artifact_families: ["proof_bundles", "handoff_bundles", "integration_snapshots", "release_artifacts"],
+    supported_surfaces: {
+      integrations_ref: "/v1/integrations",
+      integrations_snapshot_ref: "/v1/integrations/snapshot",
+      proof_bridge_ref: "/v1/proof-bridge",
+      result_package_trust_ref: "/v1/result-package-trust",
+      release_center_ref: "/v1/release-center"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "proof_artifact_distribution_alignment",
+        recommended_reason: "best path for teams that want portable proof and integration artifacts rather than custom export conventions",
+        sequence: [
+          "inspect_artifact_distribution_lane_summary",
+          "inspect proof_bridge and import surfaces",
+          "treat proof bundles and integration snapshots as distribution-ready artifacts",
+          "publish or transfer them later through standard artifact registries without changing proof semantics"
+        ]
+      }
+    ],
+    guardrails: [
+      "artifact portability should preserve canonical proof bundle and handoff shapes",
+      "distribution posture must not create a second proof model"
+    ]
+  };
+}
+
+function summarizeArtifactDistributionLanePack() {
+  const pack = buildArtifactDistributionLanePack();
+  return {
+    product: "xoonya",
+    category: "proof-artifact-distribution-lane-pack-summary",
+    summary_version: "xoonya-artifact-distribution-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    standard_count: pack.standards.length,
+    artifact_family_count: pack.artifact_families.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildArtifactDistributionLanePack,
+  summarizeArtifactDistributionLanePack
+};

package/lib/asyncapi_contract.js

@@ -0,0 +1,135 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildAsyncApiDocument() {
+  return {
+    asyncapi: "3.0.0",
+    info: {
+      title: "xoonya Event Contract",
+      version: pkg.version,
+      summary: "Proof and review event contract.",
+      description: "This AsyncAPI document describes the stable proof-side canonicalization, receipt, proof-bundle, and bridge event surfaces."
+    },
+    servers: {
+      httpProof: {
+        host: "127.0.0.1:4340",
+        protocol: "http",
+        description: "Local xoonya HTTP proof event entrypoint"
+      }
+    },
+    channels: {
+      "proof/events/canonicalize": {
+        address: "/v1/events/canonicalize",
+        messages: {
+          canonicalizeEventRequest: {
+            name: "canonicalizeEventRequest",
+            title: "Canonicalize event request",
+            summary: "Canonicalize inbound event data before proof construction."
+          }
+        }
+      },
+      "proof/events/hash": {
+        address: "/v1/events/hash",
+        messages: {
+          hashEventRequest: {
+            name: "hashEventRequest",
+            title: "Hash event request",
+            summary: "Hash canonical event data."
+          }
+        }
+      },
+      "proof/receipts/emit": {
+        address: "/v1/receipts/emit",
+        messages: {
+          emitReceiptRequest: {
+            name: "emitReceiptRequest",
+            title: "Emit receipt request",
+            summary: "Emit proof receipt data."
+          }
+        }
+      },
+      "proof/bundles/build": {
+        address: "/v1/proof-bundles/build",
+        messages: {
+          buildProofBundleRequest: {
+            name: "buildProofBundleRequest",
+            title: "Build proof bundle request",
+            summary: "Build a proof bundle from canonical proof inputs."
+          }
+        }
+      },
+      "proof/bridge/economic-handoff": {
+        address: "/v1/proof-center/bridge/economic-handoff",
+        messages: {
+          economicHandoffRequest: {
+            name: "economicHandoffRequest",
+            title: "Economic handoff bridge request",
+            summary: "Bridge bounded economic consequence data into proof review."
+          }
+        }
+      }
+    },
+    operations: {
+      canonicalizeProofEvent: {
+        action: "send",
+        channel: { $ref: "#/channels/proof/events/canonicalize" },
+        summary: "Send canonicalization input into the proof loop."
+      },
+      hashProofEvent: {
+        action: "send",
+        channel: { $ref: "#/channels/proof/events/hash" },
+        summary: "Send event data for proof hash generation."
+      },
+      emitProofReceipt: {
+        action: "send",
+        channel: { $ref: "#/channels/proof/receipts/emit" },
+        summary: "Send receipt emission input into the proof loop."
+      },
+      buildProofBundle: {
+        action: "send",
+        channel: { $ref: "#/channels/proof/bundles/build" },
+        summary: "Send proof-bundle build input into the proof loop."
+      },
+      bridgeEconomicHandoff: {
+        action: "send",
+        channel: { $ref: "#/channels/proof/bridge/economic-handoff" },
+        summary: "Send runtime economic handoff data into proof review."
+      }
+    },
+    "x-naxytra-contract": {
+      product: "xoonya",
+      stability: "stable_public_event_layer",
+      channel_count: 5,
+      linked_docs: [
+        "SERVICE_CONTRACT.md",
+        "FINAL_CONTRACT.md",
+        "START_HERE.md"
+      ]
+    }
+  };
+}
+
+function summarizeAsyncApiDocument() {
+  const document = buildAsyncApiDocument();
+  return {
+    product: "xoonya",
+    category: "proof-asyncapi-contract-summary",
+    summary_version: "xoonya-asyncapi-contract-summary-v1",
+    asyncapi_version: document.asyncapi,
+    info_version: document.info.version,
+    channel_count: Object.keys(document.channels).length,
+    operation_count: Object.keys(document.operations).length,
+    primary_event_lanes: ["canonicalization", "receipts", "proof_bundles", "bridge"],
+    linked_surfaces: {
+      asyncapi_ref: "/asyncapi.json",
+      service_contract_ref: "SERVICE_CONTRACT.md",
+      openapi_ref: "/openapi.json"
+    }
+  };
+}
+
+module.exports = {
+  buildAsyncApiDocument,
+  summarizeAsyncApiDocument
+};

package/lib/auth_interop_contract.js

@@ -0,0 +1,69 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildAuthInteropContract() {
+  return {
+    product: "xoonya",
+    category: "proof-auth-interop-contract",
+    contract_version: "xoonya-auth-interop-contract-v1",
+    service_version: pkg.version,
+    primary_posture: "proof_verification_with_oauth_oidc_and_token_exchange_interop",
+    supported_interop_profiles: [
+      {
+        profile_id: "proof_verifier_client_credentials",
+        standards: ["oauth_2_0", "oidc_optional"],
+        intended_use: "machine verifier access to proof verification surfaces",
+        primary_routes: ["/v1/receipts/verify", "/v1/proof-bundles/verify"]
+      },
+      {
+        profile_id: "runtime_to_proof_handoff_token_exchange",
+        standards: ["oauth_2_0_token_exchange", "jwt_bearer_optional"],
+        intended_use: "map runtime-side bearer posture into bounded proof-side review and bridge intake",
+        primary_routes: ["/v1/proof-center/bridge/economic-handoff"]
+      },
+      {
+        profile_id: "proof_role_governance_interop",
+        standards: ["oauth_2_0", "oidc"],
+        intended_use: "operator and reviewer access to frozen proof-role and governance surfaces",
+        primary_routes: ["/v1/role-freeze", "/v1/role-freeze/package"]
+      }
+    ],
+    native_proof_mapping: {
+      proof_verify: "/v1/proof-bundles/verify",
+      receipt_verify: "/v1/receipts/verify",
+      bridge_economic_handoff: "/v1/proof-center/bridge/economic-handoff",
+      role_freeze_package: "/v1/role-freeze/package"
+    },
+    guardrails: [
+      "proof verification semantics remain canonical inside xoonya rather than inside bearer tokens",
+      "token exchange may convey bounded review posture but must not redefine proof truth",
+      "bridge intake auth must remain subordinate to proof-side review and governance checks"
+    ],
+    linked_surfaces: {
+      openapi_ref: "/openapi.json",
+      asyncapi_ref: "/asyncapi.json",
+      cloudevents_ref: "/cloudevents.json",
+      service_contract_ref: "SERVICE_CONTRACT.md"
+    }
+  };
+}
+
+function summarizeAuthInteropContract() {
+  const contract = buildAuthInteropContract();
+  return {
+    product: "xoonya",
+    category: "proof-auth-interop-contract-summary",
+    summary_version: "xoonya-auth-interop-contract-summary-v1",
+    contract_version: contract.contract_version,
+    profile_count: contract.supported_interop_profiles.length,
+    primary_posture: contract.primary_posture,
+    primary_protocol_lanes: ["proof_verify", "receipt_verify", "bridge"],
+    linked_surfaces: contract.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildAuthInteropContract,
+  summarizeAuthInteropContract
+};

package/lib/cloudevents_contract.js

@@ -0,0 +1,79 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildCloudEventsContract() {
+  return {
+    product: "xoonya",
+    category: "proof-cloudevents-contract",
+    contract_version: "xoonya-cloudevents-contract-v1",
+    specversion: "1.0",
+    service_version: pkg.version,
+    envelope: {
+      required_attributes: ["specversion", "id", "source", "type", "time", "subject", "datacontenttype", "data"],
+      datacontenttype_default: "application/json",
+      source_prefix: "urn:naxytra:xoonya",
+      id_shape: "evt_<opaque_id>",
+      time_format: "RFC3339"
+    },
+    event_families: [
+      {
+        type: "io.naxytra.xoonya.event.canonicalized",
+        source: "urn:naxytra:xoonya:events",
+        subject: "event.canonicalized"
+      },
+      {
+        type: "io.naxytra.xoonya.event.hashed",
+        source: "urn:naxytra:xoonya:events",
+        subject: "event.hashed"
+      },
+      {
+        type: "io.naxytra.xoonya.receipt.emitted",
+        source: "urn:naxytra:xoonya:receipts",
+        subject: "receipt.emitted"
+      },
+      {
+        type: "io.naxytra.xoonya.proof_bundle.built",
+        source: "urn:naxytra:xoonya:proof_bundles",
+        subject: "proof_bundle.built"
+      },
+      {
+        type: "io.naxytra.xoonya.bridge.economic_handoff.accepted",
+        source: "urn:naxytra:xoonya:bridge",
+        subject: "bridge.economic_handoff"
+      }
+    ],
+    stable_http_surfaces: [
+      "/v1/events/canonicalize",
+      "/v1/events/hash",
+      "/v1/receipts/emit",
+      "/v1/proof-bundles/build",
+      "/v1/proof-center/bridge/economic-handoff"
+    ],
+    linked_surfaces: {
+      openapi_ref: "/openapi.json",
+      asyncapi_ref: "/asyncapi.json",
+      service_contract_ref: "SERVICE_CONTRACT.md"
+    }
+  };
+}
+
+function summarizeCloudEventsContract() {
+  const contract = buildCloudEventsContract();
+  return {
+    product: "xoonya",
+    category: "proof-cloudevents-contract-summary",
+    summary_version: "xoonya-cloudevents-contract-summary-v1",
+    specversion: contract.specversion,
+    contract_version: contract.contract_version,
+    event_family_count: contract.event_families.length,
+    stable_surface_count: contract.stable_http_surfaces.length,
+    primary_event_lanes: ["canonicalization", "proof_bundle", "bridge"],
+    linked_surfaces: contract.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildCloudEventsContract,
+  summarizeCloudEventsContract
+};

package/lib/erc8004_proof_lane_contract.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const {
+  buildPhase4Erc8004ProofPack,
+  summarizePhase4Erc8004ProofPack
+} = require("./phase_4_erc8004_proof_pack");
+
+function buildErc8004ProofLanePack() {
+  const phasePack = buildPhase4Erc8004ProofPack();
+  return {
+    product: "xoonya",
+    category: "proof-erc8004-lane-pack",
+    pack_version: "xoonya-erc8004-lane-pack-v1",
+    lane_state: "first_party_erc8004_proof_present",
+    posture: "identity_and_attestation_proof_interop_lane",
+    phase_alignment: {
+      phase_ref: phasePack.phase_ref,
+      phase_proof_pack: phasePack,
+      phase_proof_summary: summarizePhase4Erc8004ProofPack()
+    },
+    supported_surfaces: {
+      phase_proof_ref: "/v1/phases/phase-4/erc8004/proof",
+      phase_proof_summary_ref: "/v1/phases/phase-4/erc8004/proof/summary",
+      identity_interop_ref: "/v1/identity-interop",
+      bridge_summary_ref: "/v1/proof-center/bridge/summary",
+      trust_intelligence_ref: "/v1/trust-intelligence/summary"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "erc8004.attestation_proof_view",
+        recommended_reason: "best first proof-facing trust lane for attestation, subject binding, and policy carry review",
+        sequence: [
+          "inspect_erc8004_proof_lane_summary",
+          "inspect_identity_interop_contract",
+          "inspect_bridge_summary",
+          "inspect_trust_intelligence_summary"
+        ]
+      }
+    ],
+    guardrails: [
+      "erc8004 is an interop lane rather than the canonical source of proof truth",
+      "native proof review and attestation semantics remain canonical inside xoonya",
+      "erc8004 posture should improve external verifier trust without turning xoonya into a generic credential wallet"
+    ]
+  };
+}
+
+function summarizeErc8004ProofLanePack() {
+  const pack = buildErc8004ProofLanePack();
+  return {
+    product: "xoonya",
+    category: "proof-erc8004-lane-pack-summary",
+    summary_version: "xoonya-erc8004-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    posture: pack.posture,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildErc8004ProofLanePack,
+  summarizeErc8004ProofLanePack
+};