okf-attest

Verify an OKF v0.2 Attested Computation receipt. Zero dependencies, no eval.

The OKF ecosystem has good tooling for validating structure — does a bundle have the right files, frontmatter and links. This checks the thing an Attested Computation actually exists for: that a number an agent reported came from the sanctioned formula rather than from its imagination.

The rule in the spec is that an agent may fill the declared parameters and must never author or edit the computation. So verification asks four questions:

1. Is the formula the agent claims it ran the sanctioned one?
2. Are the parameters it bound actually declared?
3. Does the formula read only declared parameters and known functions?
4. Re-evaluated here, does it produce the number the agent reported?

Any one failing means the figure doesn't get used.

Install

npm install okf-attest

Use

import { verify } from "okf-attest";
import { readFileSync } from "node:fs";

const result = verify(readFileSync("computations/job-estimate.md", "utf8"), {
  formula: agentClaimedFormula,   // optional; omit to just recompute
  parameters: { hours: 3, materials_cost: 50, out_of_hours: false, call_out_applies: true },
  result: 294,                     // what the agent told the customer
});

if (!result.ok) refuseToQuote(result.reason);

okf-attest bundles/decorator --params hours=3,out_of_hours=false,call_out_applies=true --result 185

Exits 0 when the receipt verifies and 1 when it doesn't, so it drops into CI unchanged.

What it rejects

| Tampering | Caught by | |---|---| | A swapped rate | formula no longer matches the sanctioned one | | An added term | same | | A dropped max() | same — and the recomputed total differs | | A mutated result | recomputed value doesn't match the claim | | A formula reading an undeclared input | no_undeclared_inputs | | A receipt binding an undeclared parameter | parameters_declared | | An unknown function | only_known_functions | | A required parameter left unbound | required_parameters_present |

Whitespace, comments and letter case are normalised away first, because reformatting isn't tampering.

Why not eval

An attester decides whether an agent-supplied formula is legitimate. Handing that string to a JS engine would mean a mutated formula could execute arbitrary code on the machine doing the checking — the component whose entire job is to be untrickable would be the easiest thing to trick. So it tokenises, parses to an AST and walks it, with a fixed function table (max, min, round, floor, ceil, abs).

Spec version, and what kind of verdict this gives

Targets OKF v0.2. It reads okf_version from a bundle's root index.md and reports it. A version it wasn't written against produces a note, never a refusal — §12 says consumers "SHOULD attempt best-effort consumption rather than refusing the bundle."

Worth being clear about how this sits next to a conformance suite, because they answer different questions and it would be easy to assume they should agree.

§11 makes consumption deliberately permissive: consumers MUST NOT reject a bundle for unknown types, unknown keys or missing optional fields, and MUST tolerate broken links. A conformance checker that fails a bundle for those is wrong.

Attestation is a different verdict. The question isn't "is this bundle well-formed" but "should I repeat this number to a customer", and there the safe default inverts: an unrecognised function, an undeclared input or a result that doesn't reproduce all mean don't use the figure. Failing open would defeat the point of having an attester at all.

So a bundle can be fully conformant and still fail here, and that isn't a contradiction — it's conformance and trust being two separate verdicts.

Required means required

If a parameter is declared required: true, the receipt must bind it, even when the frontmatter also carries a default. Defaults are for optional inputs. "Was this out of hours?" is material to the price, and an agent that never mentioned it hasn't stated its assumptions — quietly substituting false would hide exactly what attestation is meant to surface.

Tests

node --test test/attest.test.js test/bundles.test.js

attest.test.js runs against a fixture. bundles.test.js is a tamper drill against the five real generated bundles, so the verifier and the generator can't drift apart.

Other OKF tools

This checks one narrow thing. For everything else:

• okf-conformance — conformance criteria, an executable validator and test fixtures; tracks v0.2. If you want to know whether a bundle is well-formed, start here rather than with this package.
• okf-skills — Claude Code toolkit to author, maintain, validate and visualise bundles.
• OWOX Model Canvas — visual canvas / ERD editor that imports and exports OKF.
• openknowledge — CLI for managing bundles.

A verifier that only trusts itself isn't worth much, so: if okf-attest disagrees with a conformance suite about a bundle, that's expected — see the verdict note above — but if it disagrees with another attester, one of us has a bug and I'd like to hear about it.

Licence

Apache-2.0. Part of okf-job-sheet.