xoonya 3.1.17 → 3.2.0

package/README.md

@@ -1,111 +1,134 @@
 # xoonya
 
-**Deterministic proof & review engine with post-quantum verification** — for receipts, handoffs,
-governance, and the native **XNYA** machine-evidence format. xoonya is the proof-side half of the
-naxytra machine stack; the runtime/payments half is [xytara](https://naxytra.com/xytara).
+**Verifier for xoonya proofs and naxytra delivery evidence.**
 
-It makes machine evidence **deterministic, portable, minimal, verifiable, and replayable**, and
-verifies it with both classical and **post-quantum** signatures.
+xoonya is the proof side of the naxytra machine stack: a hosted proof engine that emits
+deterministic, portable machine evidence for paid agent work, plus this public verifier that lets
+anyone check that evidence offline with classical and **post-quantum** signatures.
 
-## Proven live on Base mainnet
+> The proof engine and server are a hosted service; this package is the verifier. The engine is
+> not distributed.
 
-Post-quantum proof verification is real and demonstrated: a paid x402 call (gasless USDC on Base)
-routes to xoonya's `/execute`, which verifies a native **XNYA** proof bundle signed with a hybrid
-**Ed25519 + ML-DSA-65 (FIPS-204)** suite and returns a `verified_native_hybrid_signature` verdict.
-Adversarially, downgrade-to-classical and the unsigned `none` algorithm are both rejected.
+- Hosted service: https://xoonya.onrender.com
+- Product page: https://www.naxytra.com/xoonya
+- Agent entry points: https://www.naxytra.com/agents
 
-> Scope: XNYA is **machine-evidence verification** — a portable, deterministic check that a proof is
-> well-formed and cryptographically signed. It is **not** an identity, custody, settlement,
-> transport-security, or chain-finality claim.
+## What this package verifies
 
-## What it does
+- **Native proof bundles** (`proof-bundle/v1`) carrying a canonical event bundle and a receipt:
+  - `xoonya-native-sha256-v1` — replayable digest (integrity, not authorship)
+  - `xoonya-native-signed-v1` — Ed25519 / secp256k1 / P-256 signature bound to the carried public key
+  - `xoonya-native-hybrid-v1` — classical + post-quantum dual signature (Ed25519 + ML-DSA-65, FIPS 204)
+  - `xoonya-native-anchored-v1` — digest binding to declared chain / batch / finality anchor refs
+  - structural acceptance of external envelopes (`detached-assertion`, `jwt-assertion`, `did-vc`,
+    `sd-jwt-vc`, `signed-envelope`, `partner-proof-envelope`) and the compatibility `legacy-opreturn` receipt
+- **Detached signatures and compact JWS** — EdDSA, ES256/384/512, ES256K, RS*/PS*, and
+  ML-DSA-44/65/87 — with an explicit trusted-key fingerprint model
+- **XNYA machine-evidence atoms**, XNYP payload profiles and line-rate frames
 
-The public proof loop is deliberately narrow:
-
-1. **receive** a handoff or canonical event bundle
-2. **review** it
-3. **verify** it
-4. **emit** a durable proof bundle
-
-xoonya owns proof, review, and continuity. It does not own pricing, catalogs, workflow
-orchestration, payment rails, or settlement — those live in [xytara](https://naxytra.com/xytara).
+Everything runs on Node built-ins (`node:crypto`); there are no dependencies.
 
 ## Install
 
 ```bash
-npm install xoonya
+npm install xoonya          # Node 24 or newer
 ```
 
-## Quickstart — CLI
-
-```bash
-xoonya start-here                        # the shortest first-run path
-xoonya first-run --verify-native --pretty
-xoonya conformance --json                # run proof + adversarial vectors
-xoonya review --help
-```
+## Verify a native proof bundle
 
-## Quickstart — SDK
+A proof bundle is what the hosted service (or a counterparty running it) hands back after a paid
+execution. Verification is deterministic and offline:
 
 ```js
 const xoonya = require("xoonya");
-
-// 1. emit a signed receipt for a canonical event
-const receipt = xoonya.emitReceipt(event, { /* receipt options */ });
-
-// 2. build a portable proof bundle
-const bundle = xoonya.buildProofBundle({ ceb: event, receipt });
-
-// 3. verify it anywhere, deterministically
-const result = xoonya.verifyProofBundle(bundle);
-// => { valid: true, verification_method: "xoonya-native-hybrid-v1",
-//      verification_state: "verified_native_hybrid_signature", ... }
+const bundle = JSON.parse(require("fs").readFileSync("proof-bundle.json", "utf8"));
+
+const result = xoonya.verifyNativeBundle(bundle);
+// {
+//   valid: true,
+//   verification_method: "xoonya-native-hybrid-v1",
+//   verification_state: "verified_native_hybrid_signature",
+//   verification_class: "cryptographic",
+//   cryptographically_verified: true,
+//   public_key_ref: "ed25519+ml-dsa-65-hybrid-spki-sha256:...",
+//   classical_public_key_ref: "ed25519-spki-sha256:...",
+//   pq_public_key_ref: "ml-dsa-65-spki-sha256:...",
+//   ...
+// }
 ```
 
-## Verification methods
+A valid result says the bundle is well-formed, bound to the canonical event, and (for signed /
+hybrid methods) really signed by the carried public key. It does not say who controls that key.
+Bind the key to an identity you already trust, and refuse digest-only and structural results, with
+options:
 
-xoonya verifies the **native XNYA** family and common **external** formats for interop:
+```js
+xoonya.verifyNativeBundle(bundle, {
+  strict: true, // only cryptographically verified methods pass
+  trusted_public_key_refs: {
+    "did:xoonya:agent-1": {
+      classical: "ed25519-spki-sha256:...",
+      pq: "ml-dsa-65-spki-sha256:..."
+    }
+  }
+});
+// a bundle signed by any other key => { valid: false, reason: "native_hybrid_public_key_not_trusted" }
+```
 
-- **Native (XNYA):** `xoonya-native-sha256-v1`, `xoonya-native-signed-v1` (Ed25519 / secp256k1 /
-  P-256), `xoonya-native-hybrid-v1` (**classical + post-quantum**: ML-DSA-65 / FIPS-204,
-  SLH-DSA / FIPS-205), `xoonya-native-anchored-v1`.
-- **External:** `signed-envelope`, `detached-assertion`, `jwt-assertion`, `sd-jwt-vc`, `did-vc`,
-  `partner-proof-envelope`, `legacy-opreturn`.
+`verifyNativeProof({ event, receipt, anchors })` does the same for a receipt that is not yet wrapped in
+a bundle. `XOONYA_STRICT_VERIFY=1` turns strict mode on for every call.
 
-Conformance and adversarial vectors ship in `vectors/`; the `XNYA-compatible` mark is defined in
-[`XNYA_CONFORMANCE_MARK.md`](./XNYA_CONFORMANCE_MARK.md).
+## Verify a detached ML-DSA signature
 
-## As a paid service (x402)
+```js
+const result = xoonya.verifyDetachedSignature({
+  material: deliverableBytes,        // Buffer or string that was signed
+  signature: signatureBase64,        // base64 (default), "hex" or "base64url" via signature_encoding
+  public_key: signerSpkiPem,         // SPKI PEM, base64 DER or public JWK; private material is refused
+  algorithm: "ML-DSA-65",            // or "EdDSA", "ES256", "ES256K", "RS256", "PS256", ...
+  expected_key_ref: "ml-dsa-65-spki-sha256:..." // the fingerprint you already trust (optional)
+});
+// result.signature_valid   => the signature verifies under the supplied key
+// result.signing_key_ref   => "ml-dsa-65-spki-sha256:..." fingerprint of that key
+// result.trust_anchored    => signature_valid AND the key matches expected_key_ref
+```
 
-xoonya runs as a verification service you can pay per call. An agent pays
-[xytara](https://naxytra.com/xytara) with x402 for `adapter.xoonya.invoke` (tool
-`proof.verify-signature` / `proof.verify-bundle` / `proof.verify-envelope` / `proof.verify-receipt`);
-xytara routes to xoonya's bearer-authed `/execute`, which runs real verification and returns the
-verdict. It is billed only on a successful verification.
+`verifyJws(compactJws, { trusted_public_key, expected_key_ref })` verifies a compact JWS the same
+way; `alg: "none"`, `crit` extensions and unencoded payloads are rejected.
 
-Run the server yourself:
+## CLI
 
 ```bash
-XOONYA_EXECUTOR_BEARER_TOKEN=... npm start   # exposes the paid /execute lane
+xoonya start-here                          # the shortest verification path
+xoonya first-run --verify-native --pretty  # run the shipped vectors, print a JSON verdict
+xoonya conformance --json                  # conformance + adversarial vectors, full summary
+xoonya verify ./proof-bundle.json --pretty # verify one bundle; add --strict; exit 1 if invalid
 ```
 
-## Configuration
+`xoonya release` and `xoonya review` are operator tooling of the hosted service and are not part
+of this package.
 
-- `XOONYA_STRICT_VERIFY=1` — only cryptographically verified (native signed / hybrid) results pass;
-  digest and structural results are rejected.
-- `XOONYA_ACCEPT_PRIVATE_KEY_MATERIAL=false` — refuse private-key material on shared deployments;
-  sign locally with the SDK/CLI instead.
+## Conformance
 
-See [`.env.example`](./.env.example) for the full list.
+`vectors/` ships the conformance and adversarial vectors the hosted engine is tested against
+(eleven verification methods, fifteen rejection cases, XNYA atom and payload-profile vectors).
+`xoonya.verifyVectors()` runs them in-process and returns the summary. The same vectors are run by
+both the hosted engine and this verifier before every release, and every result must be identical.
 
-## Learn more
+## Honest claims
 
-- Why two packages: [`WHY_XYTARA_XOONYA.md`](./WHY_XYTARA_XOONYA.md)
-- Native proof format: [`XOONYA_NATIVE_PROOF_FORMAT.md`](./XOONYA_NATIVE_PROOF_FORMAT.md) ·
-  atom spec: [`XOONYA_NATIVE_ATOM_SPEC.md`](./XOONYA_NATIVE_ATOM_SPEC.md)
-- Start here: [`START_HERE.md`](./START_HERE.md) · terminology: [`TERMINOLOGY.md`](./TERMINOLOGY.md)
-- Live: https://naxytra.com/xoonya
+- **Post-quantum means machine-evidence verification.** A `verified_native_hybrid_signature`
+  verdict says the proof was signed by the carried Ed25519 and ML-DSA-65 keys. It is not an
+  identity, custody, settlement, transport-security or chain-finality claim.
+- **Proven suites:** Ed25519 and Ed25519 + ML-DSA-65 are exercised by the shipped vectors and by a
+  live paid verification on Base mainnet through the naxytra runtime. secp256k1, P-256 and
+  SLH-DSA are implemented suites but are not covered by shipped vectors.
+- **Digest and anchored methods prove integrity, not authorship.** Anyone can produce a valid
+  digest; anchor refs are bound, not checked against the external chain or provider.
+- **Trust in a signing key is yours to declare.** A key carried inside a proof, or supplied in the
+  same request, is never treated as trusted by itself.
 
 ## License
 
-Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
+The verifier SDK is Apache-2.0 (see `LICENSE` and `NOTICE`). The hosted xoonya proof engine and
+server are proprietary.

package/RELEASE_NOTES.md

@@ -1 +1,7 @@
-`xoonya` 3.1.17 is a synchronized-line release with no change to the proof engine, verification behavior, vectors, routes, or package contents. It is published through npm trusted publishing (GitHub OIDC), with no npm token involved.
+`xoonya` 3.2.0 turns the npm package into a thin verifier. The published tarball now carries only what a third party needs to verify xoonya proofs and naxytra delivery evidence: the standalone native verifier (`lib/native_verify.js`), the detached-signature verifier (`lib/external_proof_verify.js`, Ed25519 / ECDSA / RSA / ML-DSA-44/65/87), the `xoonya` CLI (`start-here`, `first-run --verify-native`, `conformance --json`, `verify <bundle.json>`), the conformance and adversarial vectors, and the release-candidate gate.
+
+The proof engine, server, review, governance, bridge packs, reference implementations and operator tooling are no longer distributed. They run as the hosted xoonya service (https://xoonya.onrender.com) behind the naxytra runtime; `xoonya release` and `xoonya review` now explain this and exit with code 2.
+
+Verification semantics are unchanged. The standalone verifier reproduces the engine's canonicalization, hashing, key-fingerprint and signature-suite rules exactly; the in-repo gate verifies every vector, option variant, freshly emitted bundle and mutation with both the engine and the standalone verifier and requires identical results. All eleven verification methods still pass, including `xoonya-native-hybrid-v1` (Ed25519 + ML-DSA-65).
+
+Package entry is now `verify.js` (`verifyNativeBundle`, `verifyNativeProof`, `verifyDetachedSignature`, `verifyJws`, `verifyExternalProofSignature`, `verifyxoonyaNativeAtom`, `verifyVectors`, `version`, `endpoints`). The verifier SDK stays Apache-2.0; the hosted service is proprietary.

package/START_HERE.md

@@ -1,159 +1,63 @@
 # xoonya Start Here
 
-This is the shortest reliable path for understanding and using the public `xoonya` package in production-facing order.
+`xoonya` on npm is the **verifier** for xoonya proofs and naxytra delivery evidence. The proof
+engine and server are a hosted service (https://xoonya.onrender.com); this package is the
+verifier. The engine is not distributed.
 
-The phase program is now complete, so this file is the right starting point for a closed and release-shaped proof system rather than an in-flight milestone build.
-
-The product-side implementation, proof posture, and bounded hybrid verification work for the widened `3.0.0` finish line are now complete. The remaining step is the synchronized public `3.0.0` release cut, publish, deploy, and verification sequence documented in NAXYTRA_3_0_0_RELEASE_CONTRACT.md and PUBLISH_PLAN.md.
-
-If you are arriving from the broader public discovery layer, the canonical entry points are:
+If you are arriving from the public discovery layer, the canonical entry points are:
 
+- https://www.naxytra.com/xoonya
 - https://www.naxytra.com/agents
-- https://www.naxytra.com/v1/agent-discovery-index
-- https://www.naxytra.com/.well-known/agent.json
-
-## 1. Understand The Role
-
-`xoonya` is the proof-side half of the public stack.
-
-Its job is to let a caller:
+- https://www.naxytra.com/v1/first-run-kit
 
-1. receive the transaction-side handoff from `xytara`
-2. inspect review and run posture
-3. emit proof-native completion artifacts
-4. verify the final proof bundle
+## 1. The role
 
-For the full public quote -> execute -> prove path, start from:
+The public spine is `quote -> pay/credits -> execute -> prove -> verify`. The naxytra runtime
+(`xytara`) owns quotes, payment and execution; the hosted xoonya engine emits the proof; this
+package lets you verify that proof anywhere, offline, deterministically.
 
-```text
-https://www.naxytra.com/v1/first-run-kit
-```
-
-Then run the local proof followthrough:
+## 2. Install and run the shipped vectors
 
 ```bash
+npm install xoonya
+xoonya start-here
 xoonya first-run --verify-native --pretty
+xoonya conformance --json
 ```
 
-If you want the frozen machine-readable proof-truth contract behind that flow, inspect:
-
-```text
-GET /v1/proof-truth
-GET /v1/proof-truth/summary
-```
-
-If you want the frozen machine-readable proof default-path contract behind that flow, inspect:
+`first-run --verify-native` must print `"ok": true` and `"required_native_methods_present": true`.
+The verification methods include `xoonya-native-sha256-v1`, `xoonya-native-signed-v1`,
+`xoonya-native-hybrid-v1` (Ed25519 + ML-DSA-65) and `xoonya-native-anchored-v1`.
 
-```text
-GET /v1/default-path
-GET /v1/default-path/summary
-```
-
-If you want the frozen machine-readable followthrough claim boundary behind that flow, inspect:
-
-```text
-GET /v1/followthrough-truth
-GET /v1/followthrough-truth/summary
-```
-
-## 2. Run The Fastest Real Example
-
-Run:
+## 3. Verify a real bundle
 
 ```bash
-node examples/package_quickstart.js
+xoonya verify ./proof-bundle.json --pretty            # exit 0 if valid, 1 otherwise
+xoonya verify ./proof-bundle.json --strict --pretty   # only cryptographically verified methods pass
 ```
 
-This is the fastest way to see the intended proof-side package story end-to-end.
-
-If you want the clearest cross-repo adoption path instead of the broad package tour, continue with:
+Or in code:
 
-- CARRIED_HANDOFF_DEMO.md
+```js
+const xoonya = require("xoonya");
+const result = xoonya.verifyNativeBundle(bundle, { strict: true, trusted_public_key_refs: { ... } });
+```
 
-If you want the shortest neutral external-adoption bundle, continue with:
+For detached signatures (including ML-DSA) use `xoonya.verifyDetachedSignature(...)`; for compact
+JWS use `xoonya.verifyJws(...)`. See `README.md` for the option model.
 
-- PARTNER_READY_PATH.md
-- PUBLIC_DEMO_SCRIPT.md
-- EXAMPLE_PATHS.md
-- `node examples/partner_proof_walkthrough.js`
+## 4. Read the boundary
 
-## 3. Verify The Whole Package
+- A valid result proves binding and signature validity under the carried key, not identity,
+  custody, settlement or external chain truth.
+- Digest and anchored methods prove integrity and replayability, not authorship.
+- Trust in a signing key is declared by you (`expected_key_ref`, `trusted_public_key_refs`).
 
-Run:
+## 5. Hosted surfaces
 
-```bash
-npm run verify:all
-```
+- https://xoonya.onrender.com/v1/proof-center/native-standard/summary
+- https://xoonya.onrender.com/v1/proof-center/native-conformance-mark/summary
+- https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary
 
-This is the production-confidence check for the published proof package surface.
-
-## 4. Read The Durable Contract
-
-For long-term product understanding, read:
-
-- FINAL_CONTRACT.md
-- SERVICE_CONTRACT.md
-- `GET /openapi.json`
-- `GET /asyncapi.json`
-- `GET /cloudevents.json`
-- `GET /v1/auth-profiles`
-- `GET /v1/identity-interop`
-- `GET /v1/providers`
-- `GET /v1/frameworks`
-- `GET /v1/integration-matrix`
-- `GET /v1/telemetry`
-- `GET /v1/provenance`
-- `GET /v1/artifact-distribution`
-- `GET /v1/shared-signals`
-- `GET /v1/feature-control`
-- `GET /v1/adapter-certification`
-- `GET /v1/trust-portability-boundary`
-- `GET /v1/signed-audit-provenance`
-- `GET /v1/major-rails`
-- `GET /v1/treasury`
-- `GET /v1/erc8004`
-- `GET /v1/proof-bridge`
-- `GET /v1/external-proof-import`
-- `GET /v1/result-package-trust`
-- `GET /v1/event-systems`
-- `GET /v1/integrations`
-- PROGRAM_STATUS.md
-- OPERATOR_START_HERE.md
-- OPERATIONS_RUNBOOK.md
-- PROGRAM_COMPLETE_RELEASE.md
-- WHY_XYTARA_XOONYA.md
-- CARRIED_HANDOFF_DEMO.md
-- PARTNER_READY_PATH.md
-- TERMINOLOGY.md
-
-## 5. If You Are Integrating From Outside
-
-Continue with:
-
-- CROSS_RUNTIME_POSTURE.md
-- integrations/PROOF_INTEGRATION_PROCESS.md
-- PARTNER_READY_PATH.md
-- COMPATIBILITY_NOTE.md
-
-## 6. Production Reading Rule
-
-If you only remember one thing, remember this:
-
-The main public path is no longer "understand every proof helper first."
-
-It is:
-
-receive handoff -> inspect review posture -> confirm run posture -> emit and verify proof
-
-If you want the shortest CLI-first read of the package after install, use:
-
-- `xoonya start-here`
-- `xoonya release --summary`
-- `xoonya review --help`
-
-## 7. If You Are Operating The Closed Program
-
-Use:
-
-- PROGRAM_STATUS.md
-- OPERATOR_START_HERE.md
+`xoonya release` and `xoonya review` belong to the hosted service's operator tooling and are not
+part of this package.

package/bin/xoonya-first-run.js

@@ -29,8 +29,9 @@ function buildLocalGuide() {
     product: "xoonya",
     category: "xoonya-first-run-proof-guide",
     guide_version: "xoonya-first-run-proof-guide-v1",
+    package_role: "verifier",
     public_command_kit_url: DEFAULT_KIT_URL,
-    role: "proof_followthrough_after_xytara_runtime_execution",
+    role: "proof_verification_after_xytara_runtime_execution",
     safe_local_verification_command: "xoonya first-run --verify-native --pretty",
     proof_modes: [
       {
@@ -39,7 +40,11 @@ function buildLocalGuide() {
       },
       {
         method: "xoonya-native-signed-v1",
-        verification: "ed25519_signature"
+        verification: "native_signature_ed25519_secp256k1_p256"
+      },
+      {
+        method: "xoonya-native-hybrid-v1",
+        verification: "classical_plus_pq_signature_ed25519_ml_dsa_65"
       },
       {
         method: "xoonya-native-anchored-v1",
@@ -58,7 +63,8 @@ function buildLocalGuide() {
     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"
+      "xytara_owns_runtime_payment_and_execution_state",
+      "the_proof_engine_is_a_hosted_service_and_is_not_distributed"
     ]
   };
 }
@@ -80,12 +86,12 @@ function printUsage() {
     "Usage: xoonya first-run [options]",
     "",
     "Options:",
-    "  --json             Print the guided proof followthrough object",
+    "  --json             Print the guided proof verification 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"));
+  ].join("\n") + "\n");
 }
 
 function runNativeVerification(args) {
@@ -107,6 +113,7 @@ function runNativeVerification(args) {
     product: "xoonya",
     category: "xoonya-first-run-native-verification",
     verification_version: "xoonya-first-run-native-verification-v1",
+    package_role: "verifier",
     proof_bundle_conformance_passed: summary.ok === true,
     conformance_count: summary.conformance_count,
     adversarial_count: summary.adversarial_count,
@@ -114,6 +121,8 @@ function runNativeVerification(args) {
     native_atom_adversarial_count: summary.native_atom_adversarial_count,
     verification_methods: summary.verification_methods,
     native_atom_error_codes: summary.native_atom_error_codes,
+    external_signature_checks: summary.external_signature_checks,
+    engine_parity: summary.engine_parity,
     required_native_methods_present: [
       "xoonya-native-sha256-v1",
       "xoonya-native-signed-v1",
@@ -158,24 +167,27 @@ async function main() {
   process.stdout.write([
     "xoonya first-run",
     "",
-    "Proof followthrough after xytara execution:",
+    "Local proof verification after xytara execution:",
     "  xoonya first-run --verify-native --pretty",
+    "  xoonya verify ./proof-bundle.json --pretty",
     "",
     "Inspect the public command kit:",
     `  ${DEFAULT_KIT_URL}`,
     "",
-    "Native proof modes checked locally:",
+    "Native proof methods checked locally:",
     "  xoonya-native-sha256-v1",
     "  xoonya-native-signed-v1",
+    "  xoonya-native-hybrid-v1",
     "  xoonya-native-anchored-v1",
     "",
-    "Public proof surfaces:",
+    "Hosted 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"));
+    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external.",
+    "  The proof engine is a hosted service; this package is the verifier."
+  ].join("\n") + "\n");
 }
 
 main().catch((error) => {