A supplier-side provenance & verification extension for OKF bundles.
It defines one optional frontmatter key — provenance — plus the canonicalization, signing, and
verification rules needed to make it interoperable. It does not modify base OKF and asks nothing of
the OKF project: it relies solely on OKF's documented rule that producers may add extra keys and
consumers must preserve unknown fields.
- Chain-agnostic core. Signing, hashing, DID resolution, and proof verification work fully offline — no blockchain required. On-chain anchoring is a separate, optional, pluggable backend (later milestone).
- License: Apache-2.0 · Spec:
SPEC.md(Verifiable OKF v0.3)
| Package | Status | Purpose |
|---|---|---|
@verifiable-okf/canon |
✅ M0 | Canonicalization (§5) + JCS (§6) + signing-payload builder. The shared, version-pinned core. |
@verifiable-okf/signer |
✅ M0 | vokf-sign — attaches provenance without mutating any other byte. |
@verifiable-okf/verifier |
✅ M0 | vokf-verify — the §10 verification algorithm (status + reason codes), schema validation, did:web/did:key. |
@verifiable-okf/visualizer |
✅ M1 | Bundle → single offline HTML with per-concept badges. |
@verifiable-okf/attest-zk-groth16 |
✅ M1 | zk-groth16 attestation verifier (Groth16/BN254 via snarkjs, offline); bundles the contains_no_pii demo circuit. |
pnpm install && pnpm build
# A test-only Ed25519 seed (32 bytes hex). NEVER use a real key on the CLI.
SEED=0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
# 1) Sign an unsigned concept → attaches a `provenance` block (only).
node packages/signer/dist/cli.js fixtures/unsigned/ga4-event.md \
--key "$SEED" --valid-from 2026-01-01T00:00:00Z --valid-until 2027-01-01T00:00:00Z \
-o /tmp/signed.md
# 2) Verify it → machine-readable JSON, exit 0 when verified.
node packages/verifier/dist/cli.js /tmp/signed.md
# {"status":"verified","reasons":[],"issuer":"did:key:z6Mkne..."}The signed output is byte-identical to fixtures/signed/ga4-event.md, and tampering with the body,
signature, schema, or issuer yields the corresponding failed reason code (see fixtures/tampered/).
Verification is fully offline for did:key; did:web resolves the issuer over HTTPS.
examples/okf-bundle/ is a small multi-concept OKF bundle (a GA4 analytics mapping). Sign every
concept, verify each, and render an offline report:
pnpm install && pnpm build
examples/sign-and-verify.sh
# add-to-cart-event.md {"status":"verified", ...}
# consent-mode.md {"status":"verified", ...}
# purchase-event.md {"status":"verified", ...}
# report → /tmp/.../report.html (3 concepts, 0 failed)pnpm install
pnpm build
pnpm testAttestations are pluggable, machine-checkable claims carried in provenance.attestations.
@verifiable-okf/attest-zk-groth16 provides an offline Groth16 proof verifier; pass it to the
verifier's policy to turn the §10 attestation path into real ZK checks:
import { verifyConcept } from "@verifiable-okf/verifier";
import { groth16AttestationVerifier } from "@verifiable-okf/attest-zk-groth16";
await verifyConcept(concept, {
policy: { requiredClaims: ["contains_no_pii"] },
attestationVerifiers: { "zk-groth16": groth16AttestationVerifier },
});The contains_no_pii demo circuit (circuits/contains_no_pii/, regenerate with gen.sh) proves a
private field is absent; verification needs only the bundled verification key — no proving key, no
circom, no network. Proof issuance (and metering) is a separate, commercial concern, not part of
this OSS engine.
See CANONICALIZATION.md and SECURITY.md.