@veraanchor/verifier 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@veraanchor/verifier` are documented here.
+
+## [0.1.0] - 2026-11-03
+
+Initial public release.
+
+### Added
+
+- Deterministic Dataset and Ingest verification, including source, bundle and receipt checks.
+- Explicit public triangulation through Vera Anchor Explorer and Hedera Mirror observations.
+- SAGE execution verification with caller-controlled execution scope.
+- Pinned HCS-1, HCS-2, HCS-11, HCS-13, HCS-14 and HCS-26 verification.
+- HCS-26 canonical manifest verification and integrity verification of manifest-declared HCS-1 files.
+- Canonical portable verification reports and deterministic report validation.
+- Relying-party policy evaluation with `allow`, `review` and `deny` decisions.
+- `vera-anchor` CLI for offline, public, standards, report and policy workflows.
+
+### Assurance boundary
+
+The v0.1 release provides deterministic integrity verification and supported Mirror corroboration. It does not claim Hedera consensus-signature authentication, DID-controller or publisher-key authentication, historical account ownership, factual truth, or independent cryptographic binding of Explorer-assisted decrypted plaintext to publication ciphertext.

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Contributions that improve correctness, interoperability, security, documentation and developer usability are welcome.
+
+Changes to public schemas, commitment algorithms, verification semantics, reason codes, resolver trust boundaries or policy behavior require explicit review because downstream users may rely on their deterministic meaning.
+
+## Development checks
+
+Before submitting a pull request, run:
+
+```sh
+npm ci
+npm run check
+npm run typecheck
+npm test
+npm run build
+```
+
+Do not commit credentials, private customer evidence, production configuration, proprietary Vera Anchor service code or other material that is not explicitly authorized for public release.
+
+## Verification and cryptographic changes
+
+Changes to cryptographic or verification behavior should include:
+
+- deterministic positive coverage;
+- at least one relevant tampered or negative case;
+- explicit algorithm and contract versions where applicable;
+- clear authority and trust-boundary semantics;
+- reproducible conformance material when the change affects interoperability.
+
+An established historical commitment algorithm must not be changed in place. A behavior change that would alter previously valid commitments requires an explicit new version and migration analysis.
+
+Networked resolver changes must preserve caller-controlled network selection, bounded I/O and the rule that untrusted evidence cannot choose resolver authority.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vera Anchor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,4 @@
+Vera Anchor Verifier SDK
+Copyright 2026 Vera Anchor LLC
+
+This repository is maintained as a standalone, read-only verification project.

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# Vera Anchor Verifier SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@veraanchor/verifier` is an open-source, read-only verifier for Vera Anchor evidence and supported HCS-backed execution references.
+
+The SDK is local-first. Offline workflows recompute commitments from caller-supplied evidence and source material without Vera Anchor credentials. Explicit public workflows can resolve Vera Anchor Explorer records and independently corroborate supported Hedera observations using caller-selected network configuration.
+
+The verifier is designed for relying parties that need deterministic verification results they can evaluate under their own acceptance policy.
+
+## What it verifies
+
+The v0.1 surface includes:
+
+- Dataset and Ingest bundle, receipt, source-binding, and commitment recomputation.
+- Public Dataset and Ingest triangulation across local evidence, Vera Anchor Explorer publication records, and Hedera Mirror observations.
+- SAGE execution verification with independently supplied execution scope and expected program and result constraints.
+- Pinned HCS-1, HCS-2, HCS-11, HCS-13, HCS-14, and HCS-26 verification.
+- HCS-26 historical discovery and version resolution, canonical manifest verification, and integrity verification of manifest-declared HCS-1 files.
+- Canonical portable verification reports with deterministic report digests.
+- Explicit relying-party policies that convert verification findings into `allow`, `review`, or `deny` decisions.
+
+## Assurance boundaries
+
+Verification results are intentionally scoped.
+
+A successful integrity check does not establish factual truth, publisher ownership, or code execution. Hedera Mirror observations provide independent corroboration of supported ledger data; they are not authenticated Hedera consensus proofs.
+
+v0.1 does not claim DID-controller authentication, historical account ownership, consensus-signature authentication, or independent cryptographic binding between Explorer-assisted decrypted plaintext and its publication ciphertext.
+
+Caller-controlled intent is part of the trust boundary. Subject identifiers, expected commitments, Hedera network selection, execution scope, and policy requirements must come from the relying party's trusted context rather than being copied from untrusted evidence.
+
+See [Verification semantics](docs/verification-semantics.md) and the [Threat model](docs/threat-model.md) for the precise distinctions used by the SDK.
+
+## Installation
+
+```sh
+npm install @veraanchor/verifier
+```
+
+The package is ESM-only and has no runtime dependencies.
+
+Node.js 24 is recommended for the full v0.1 feature set. The supported runtime range is defined by the package metadata.
+
+## Library quickstart
+
+Verification primitives are available from the package root:
+
+```js
+import { verifyDatasetV1Bundle } from "@veraanchor/verifier";
+
+const result = verifyDatasetV1Bundle(bundle);
+
+if (!result.ok) {
+  console.error(result.mismatches);
+}
+```
+
+Higher-level APIs add independently supplied verification intent, public resolution, HCS standards verification, portable reporting, and policy evaluation.
+
+Public workflows perform network I/O only when explicitly selected.
+
+## CLI quickstart
+
+The package also exposes the `vera-anchor` CLI.
+
+After installing the package:
+
+```sh
+npm exec -- vera-anchor --help
+```
+
+Offline Dataset verification from original local source bytes:
+
+```sh
+npm exec -- vera-anchor verify dataset \
+  --bundle bundle.json \
+  --sources sources.json \
+  --source-root ./source-files \
+  --intent intent.json \
+  --policy policy.json
+```
+
+Explicit public verification of a Dataset publication and Hedera Mirror evidence:
+
+```sh
+npm exec -- vera-anchor verify dataset \
+  --mode public \
+  --explorer-url https://explorer.veraanchor.com \
+  --bundle bundle.json \
+  --sources sources.json \
+  --source-root ./source-files \
+  --intent public-intent.json \
+  --policy public-policy.json
+```
+
+Offline SAGE execution verification:
+
+```sh
+npm exec -- vera-anchor verify execution \
+  --evidence execution.json \
+  --intent intent.json \
+  --policy policy.json
+```
+
+Independent HCS standards verification:
+
+```sh
+npm exec -- vera-anchor verify standards \
+  --evidence execution.json \
+  --intent intent.json \
+  --policy standards-policy.json
+```
+
+Portable report validation and policy assessment:
+
+```sh
+npm exec -- vera-anchor report validate \
+  --report report.json
+
+npm exec -- vera-anchor policy assess \
+  --report report.json \
+  --policy policy.json
+```
+
+The CLI also supports Ingest verification and explicit public execution verification.
+
+See the [CLI reference](docs/cli-v0.1.md) for command options, JSON inputs, policy examples, and exit codes.
+
+## Verification model
+
+The SDK keeps evidence findings, cross-source consistency, and application decisions separate:
+
+```text
+source and evidence recomputation
+            |
+            v
+public record and HCS resolution when requested
+            |
+            v
+independent Mirror corroboration where supported
+            |
+            v
+verification findings and observations
+            |
+            v
+portable verification report
+            |
+            v
+caller-supplied policy
+            |
+            v
+allow / review / deny
+```
+
+Missing evidence and service outages do not become successful checks. Demonstrated contradictions fail. Unsupported operations remain explicit.
+
+The verifier never silently changes Hedera networks or selects a latest execution result when an exact result is required.
+
+## Offline and public verification
+
+Offline verification performs no resolver network requests. It operates only on caller-supplied evidence, source material, verification intent, and policy.
+
+Public workflows are explicit. Resolver origins are controlled by the caller rather than by untrusted evidence. Supported resolvers use bounded requests, reject redirects, and do not silently fall back to another Hedera network.
+
+Vera Anchor Explorer publication resolution and Hedera Mirror corroboration are distinct observations. An original HCS anchor is not interpreted as a public publication receipt.
+
+## HCS standards verification
+
+The v0.1 standards surface supports pinned verification behavior for:
+
+- HCS-1 content integrity and bounded file reconstruction.
+- HCS-2 historical registry entries.
+- HCS-11 AI-agent profile integrity and supported reference relationships.
+- HCS-13 schema registration and canonical schema integrity.
+- HCS-14 DID-backed UAID structural binding.
+- HCS-26 historical discovery and version registration, canonical skill manifests, and manifest-declared HCS-1 file integrity.
+
+Standards registration establishes only the supported properties of the observed records. It does not establish that associated software executed, that a publisher currently controls a key, or that the underlying claims are factually true.
+
+## SAGE execution verification
+
+The execution verification surface supports deterministic verification of supported SAGE evidence using independently supplied intent.
+
+Public execution workflows can additionally resolve the selected execution record through Vera Anchor Explorer and corroborate supported Hedera observations.
+
+Independent standards verification resolves supported HCS references separately from Explorer-based public execution triangulation. Successful public triangulation does not implicitly complete HCS standards verification, and successful HCS standards resolution does not independently prove that the referenced software executed.
+
+## Portable reports
+
+The SDK can produce `va.portable-verification-report.v1` reports containing deterministic, digest-bound verification results and supported context.
+
+Validating a saved report checks its structure and internal digests. It does not recompute the original evidence or authenticate the report's origin.
+
+Accordingly, a saved report cannot promote itself into a fresh SDK-computed `allow` decision. Decisions requiring verification of the underlying evidence should be produced by rerunning the appropriate workflow with independently supplied intent and policy.
+
+## Policy decisions
+
+Policy evaluation keeps application acceptance separate from verification mechanics:
+
+- `allow` means the requirements selected by the relying party were satisfied.
+- `deny` means a required condition was contradicted or the policy requires denial.
+- `review` means the evidence remains unresolved under a policy that delegates unresolved cases for review.
+
+Verification intent and policy must be supplied independently by the relying party. Untrusted evidence cannot define its own sufficient acceptance threshold.
+
+The current public assurance dimension is `mirror_corroboration`. It must not be interpreted as consensus-signature, account-control, publisher-key, or DID-controller authentication.
+
+## Conformance
+
+The verifier is exercised against deterministic fixtures and live public observations covering supported Dataset, Ingest, SAGE execution, HCS standards, Explorer, Hedera Mirror, network-scope, portable-report, and policy workflows.
+
+Live conformance depends on external public services. Service unavailability is not converted into successful verification.
+
+See [Conformance](docs/conformance.md) for the current coverage and reproducibility requirements.
+
+## Documentation
+
+- [CLI reference](docs/cli-v0.1.md)
+- [Verification semantics](docs/verification-semantics.md)
+- [Threat model](docs/threat-model.md)
+- [Conformance](docs/conformance.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Development
+
+Install the locked development dependencies:
+
+```sh
+npm ci
+```
+
+Run the repository qualification checks:
+
+```sh
+npm run check
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run --json
+```
+
+`npm run format` modifies files and is intended for local formatting work.
+
+Release qualification additionally includes package-content inspection, clean external-consumer installation, CLI and library smoke tests, and live conformance checks.
+
+## Security
+
+Treat all evidence, resolver responses, source material, and references as hostile input.
+
+Do not include credentials, private tenant evidence, customer data, or undisclosed vulnerabilities in public issues.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.
+
+## Contributing
+
+Changes to public schemas, commitment algorithms, verification semantics, reason codes, resolver trust boundaries, or policy behavior require careful review because downstream applications may rely on their deterministic meaning.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution requirements.
+
+## License
+
+Licensed under the MIT License.
+
+See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published release line of `@veraanchor/verifier`. Users should upgrade to the latest available patch release before reporting a security issue that may already have been corrected.
+
+Pre-release branches, unpublished commits and local development builds are not supported release artifacts.
+
+## Reporting a vulnerability
+
+Do not open a public issue containing exploit details, credentials, private evidence, customer data or an undisclosed vulnerability.
+
+Use GitHub private vulnerability reporting for this repository when available. If private reporting is unavailable, contact Vera Anchor through an established, verified organizational channel and provide only the minimum information needed to establish a private reporting path.
+
+Public GitHub issues are appropriate for non-sensitive defects, documentation problems and feature requests that do not disclose security-sensitive information.
+
+## Security scope
+
+The verifier processes untrusted evidence and, in explicitly selected public workflows, untrusted network responses. Security reports involving parser boundaries, resource exhaustion, path handling, resolver origin controls, redirect handling, network-scope enforcement, commitment verification, policy bypass or incorrect verification outcomes are in scope.
+
+A successful integrity or Mirror-corroboration result is not a claim of factual truth, publisher ownership, DID-controller authentication or Hedera consensus-signature authentication. See [docs/verification-semantics.md](docs/verification-semantics.md) for the supported assurance model.

package/dist/cli/commandV1.d.ts

@@ -0,0 +1,5 @@
+type Emitter = (line: string) => void;
+/** CLI adapter only. Never accepts a caller flag claiming a report was SDK-verified. */
+export declare function runVerifierCliV1(argv: readonly string[], emit: Emitter): Promise<number>;
+export {};
+//# sourceMappingURL=commandV1.d.ts.map

package/dist/cli/commandV1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandV1.d.ts","sourceRoot":"","sources":["../../src/cli/commandV1.ts"],"names":[],"mappings":"AAmCA,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAqStC,wFAAwF;AACxF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CA6G9F"}