@veraanchor/verifier 0.0.0-stage → 0.1.0

package/docs/verification-semantics.md

@@ -0,0 +1,65 @@
+# Verification semantics
+
+The verifier separates evidence findings, cross-source consistency and relying-party decisions. These layers are related but are not interchangeable.
+
+## Finding outcomes
+
+Every supported verification check has one of five normalized outcomes:
+
+- `pass` — the available evidence satisfies the exact check.
+- `fail` — the verifier demonstrated a contradiction or violation of an explicit requirement.
+- `indeterminate` — the check could not be established because required evidence or an external observation was unavailable.
+- `unsupported` — the requested material or operation is outside the verifier's supported contract or bounded implementation.
+- `skipped` — the check was intentionally not applicable or not requested in the selected workflow.
+
+Missing evidence and service outages are not contradictions and therefore must not be converted into `fail` unless an explicit requirement itself is violated.
+
+## Triangulation
+
+Cross-source relationship states are:
+
+- `consistent` — the compared independently acquired facts agree for all required comparisons;
+- `conflict` — at least one required comparison demonstrates a contradiction;
+- `incomplete` — the relationship cannot be fully established because required observations are missing, indeterminate or unsupported.
+
+Consistency is not factual truth. It means the compared evidence sources agree on the supported facts that were actually checked.
+
+## Policy decisions
+
+Policy decisions are separate from verification findings:
+
+- `allow` — all requirements selected by the relying party are satisfied under the policy.
+- `deny` — a required condition is contradicted or the policy otherwise requires denial.
+- `review` — the evidence is unresolved under a policy that delegates unresolved cases for review.
+
+Verification intent and policy must be controlled by the relying party. An untrusted receipt, bundle, execution record or standards projection cannot define its own sufficient acceptance threshold.
+
+## Assurance in v0.1
+
+The current policy assurance dimension is `mirror_corroboration`. It means the relevant supported fact was independently observed through the SDK's Hedera Mirror resolver path. It does not mean that the SDK authenticated Hedera consensus signatures or established control of an account, DID or publisher key.
+
+The SDK also performs deterministic integrity and binding checks where the underlying contract supports recomputation. Those checks are represented through findings rather than being silently promoted into a broader authentication claim.
+
+## Supported standards interpretation
+
+The v0.1 standards path supports pinned verification behavior for HCS-1, HCS-2, HCS-11, HCS-13, HCS-14 and HCS-26 as exposed by the SDK. Standards registration or profile publication is evidence of the declared record and its supported integrity relationships; it is not evidence that associated software executed, that a publisher currently controls a key, or that a claim is factually true.
+
+HCS-26 verification resolves the selected historical discovery/version path, verifies the canonical manifest, and verifies integrity for the manifest-declared HCS-1 files within the SDK's resource bounds.
+
+## Portable reports
+
+`va.portable-verification-report.v1` is a deterministic, digest-bound representation of a verification result and its supported context. Validating a saved portable report checks its structure and internal digests. It does not recompute the underlying evidence and does not authenticate the report's origin.
+
+Accordingly, a saved report cannot elevate itself into an SDK-authenticated `allow` decision. Fresh verification with independently supplied intent and policy is required when a relying party needs an SDK-computed decision over the underlying evidence.
+
+## Authentication boundary
+
+v0.1 intentionally stops short of stronger authentication claims. In particular, a SHA3-512 match, HCS content checksum, Explorer resolution or Mirror observation does not by itself establish:
+
+- Hedera consensus-signature authentication;
+- DID-controller or publisher-key authentication;
+- historical ownership of an account;
+- factual truth of the verified content;
+- independent cryptographic binding of Explorer-assisted decrypted plaintext to publication ciphertext.
+
+Future authentication capabilities must be represented as additional explicit evidence and assurance, not by changing the meaning of existing v0.1 outcomes.

package/examples/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+These examples use the public `@veraanchor/verifier` package API and are intentionally small.
+
+They treat evidence as untrusted input. Dataset identity, network selection, expected scope and policy must come from the relying party's trusted context.
+
+From a repository checkout, run `npm ci` and `npm run build` first. The package self-reference resolves the same public entry point that consumers import after installation.
+
+## Offline Dataset verification
+
+```sh
+node examples/dataset-offline.mjs \
+  bundle.json \
+  receipt.json \
+  source-file.json \
+  verification_demo/source-file.json \
+  07be0cf7-4cab-40ca-aa70-87840df4d3e7.example.verification.demo.v1 \
+  mainnet
+```
+
+The source path argument is the producer-relative path committed by the Dataset, not merely the local filename.
+
+## Fresh policy decision
+
+```sh
+node examples/dataset-policy.mjs \
+  bundle.json \
+  receipt.json \
+  source-file.json \
+  verification_demo/source-file.json \
+  intent.json \
+  policy.json
+```
+
+The intent and policy files must be supplied independently by the relying party. Do not construct them by copying expectations from the untrusted evidence being verified.

package/examples/dataset-offline.mjs

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+
+import { verifyDatasetV1WithIntent } from "@veraanchor/verifier";
+
+const [bundlePath, receiptPath, sourcePath, pathRel, datasetKey, network] =
+  process.argv.slice(2);
+
+if (
+  !bundlePath ||
+  !receiptPath ||
+  !sourcePath ||
+  !pathRel ||
+  !datasetKey ||
+  (network !== "mainnet" && network !== "testnet")
+) {
+  console.error(
+    "Usage: node examples/dataset-offline.mjs " +
+      "<bundle.json> <receipt.json> <source-file> <producer-relative-path> " +
+      "<dataset-key> <mainnet|testnet>",
+  );
+  process.exit(64);
+}
+
+async function readJson(path) {
+  const text = (await readFile(path, "utf8")).replace(/^\uFEFF/, "");
+  return JSON.parse(text);
+}
+
+const [bundle, receipt, sourceBytes] = await Promise.all([
+  readJson(bundlePath),
+  readJson(receiptPath),
+  readFile(sourcePath),
+]);
+
+const report = await verifyDatasetV1WithIntent({
+  bundle,
+  receipt,
+  intent: {
+    subject: {
+      kind: "dataset",
+      id: datasetKey,
+      hedera_network: network,
+    },
+    expected: [],
+  },
+  files: [
+    {
+      path_rel: pathRel,
+      source: [sourceBytes],
+    },
+  ],
+});
+
+console.log(JSON.stringify(report, null, 2));
+
+if (report.findings.some((finding) => finding.outcome === "fail")) {
+  process.exitCode = 1;
+}

package/examples/dataset-policy.mjs

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+
+import { verifyDatasetWithPolicyV1 } from "@veraanchor/verifier";
+
+const [bundlePath, receiptPath, sourcePath, pathRel, intentPath, policyPath] =
+  process.argv.slice(2);
+
+if (
+  !bundlePath ||
+  !receiptPath ||
+  !sourcePath ||
+  !pathRel ||
+  !intentPath ||
+  !policyPath
+) {
+  console.error(
+    "Usage: node examples/dataset-policy.mjs " +
+      "<bundle.json> <receipt.json> <source-file> <producer-relative-path> " +
+      "<intent.json> <policy.json>",
+  );
+  process.exit(64);
+}
+
+async function readJson(path) {
+  const text = (await readFile(path, "utf8")).replace(/^\uFEFF/, "");
+  return JSON.parse(text);
+}
+
+const [bundle, receipt, sourceBytes, intent, policy] = await Promise.all([
+  readJson(bundlePath),
+  readJson(receiptPath),
+  readFile(sourcePath),
+  readJson(intentPath),
+  readJson(policyPath),
+]);
+
+const result = await verifyDatasetWithPolicyV1(
+  {
+    bundle,
+    receipt,
+    intent,
+    files: [
+      {
+        path_rel: pathRel,
+        source: [sourceBytes],
+      },
+    ],
+  },
+  policy,
+);
+
+console.log(JSON.stringify(result, null, 2));
+
+process.exitCode =
+  result.policy.decision === "allow"
+    ? 0
+    : result.policy.decision === "review"
+      ? 2
+      : 1;

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@veraanchor/verifier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Independent, read-only verification of Vera Anchor evidence and supported HCS records",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "vera-anchor": "./dist/cli.js"
+  },
+  "engines": {
+    "node": "^22.15.0 || ^24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VeraAnchor/vera-anchor-verifier.git"
+  },
+  "homepage": "https://github.com/VeraAnchor/vera-anchor-verifier#readme",
+  "bugs": {
+    "url": "https://github.com/VeraAnchor/vera-anchor-verifier/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@mongodb-js/zstd": "2.0.1",
+    "@types/node": "22.20.5",
+    "typescript": "6.0.3",
+    "vitest": "5.0.0"
+  },
+  "keywords": [
+    "vera-anchor",
+    "verification",
+    "digital-evidence",
+    "hedera",
+    "hcs",
+    "provenance"
+  ]
+}