Free2PA

Free2PA stops changed or outside-publisher agent control files before they load.

AI agents read plain-text files that behave like code: system prompts, skills, tool manifests, policies, SOUL.md, AGENTS.md, and other startup instructions. If one of those files changes, every later agent action can change with it.

Free2PA puts a signed receipt beside each protected file. At load time, your app asks one question:

May this exact file enter the agent runtime?

The verifier checks four facts:

1. the receipt signature is valid;

2. the current file still matches the signed hash;

3. the signing certificate is current; and

4. the publisher is in this project's local trust store.

All four pass: LOAD.

Anything fails: REJECT with a stable reason code such as CONTENT_CHANGED, UNTRUSTED_ISSUER, INVALID_SIGNATURE, or EXPIRED_CERT.

There is no global registry. Trust lives in the verifier. Add a public certificate to admit a publisher. Remove it to revoke that publisher on the next check.

Judge quick path

Live demo: https://free2pa.org

git clone https://github.com/kilroyblockchain/free2pa-devtool.git
cd free2pa-devtool
npm ci
npm test

Run the three deterministic cases:

node bin/free2pa.js verify public/demo/trusted/SKILL.md --trust-store demo_certs
node bin/free2pa.js verify public/demo/tampered/SKILL.md --trust-store demo_certs
node bin/free2pa.js verify public/demo/outside/SKILL.md --trust-store demo_certs

Expected:

trusted  -> PASS
tampered -> FAIL / CONTENT_CHANGED
outside  -> FAIL / UNTRUSTED_ISSUER

Related MCP server: mcp-heimdall

The integration developers actually use

For a custom Node agent, put the gate exactly where the app currently reads its control file:

import { loadVerifiedFile } from 'free2pa/load-gate';

const instructions = await loadVerifiedFile({
  assetPath: 'agent/SOUL.md',
  trustStore: '.free2pa/trusted-publishers',
});

startAgent({ instructions });

loadVerifiedFile() returns the file content only after every check passes. Otherwise it throws Free2PALoadError before untrusted text reaches the model.

For non-Node apps, use the same verifier through the CLI, HTTP API, MCP server, or CI action.

Basic workflow

1. Create a publisher identity

node bin/free2pa.js keygen \
  --name "Project Publisher" \
  --id project-publisher \
  --days 90 \
  --out-dir .free2pa/private

Keep the .key private. Share only the .crt.

2. Admit the publisher to this project

node bin/free2pa.js trust add \
  .free2pa/private/project-publisher.crt \
  --store .free2pa/trusted-publishers \
  --id project-publisher

The trust store is the group policy.

3. Sign a reviewed control file

node bin/free2pa.js sign agent/SOUL.md \
  --cert .free2pa/private/project-publisher.crt \
  --key .free2pa/private/project-publisher.key \
  --purpose "Agent identity and behavior instructions"

This writes agent/SOUL.md.c2pa.json beside the file.

Commit the control file, the sidecar, and the public trusted certificate. Do not commit the private key.

4. Verify before loading

node bin/free2pa.js verify agent/SOUL.md \
  --trust-store .free2pa/trusted-publishers \
  --json

Exit code 0 means the host may load the file. A nonzero exit means the host must apply its configured failure policy: block, quarantine, guarded repair, alert and continue, or log only.

Interfaces

Start the local verifier:

node bin/free2pa.js serve \
  --trust-store .free2pa/trusted-publishers \
  --skills ./skills \
  --port 4001

MCP endpoint:

POST http://127.0.0.1:4001/mcp

Primary MCP tool:

verify_asset(content, sidecar) -> LOAD | REJECT

Codex retrofit workflow

Install the included Codex skill:

node bin/free2pa.js codex-skill install

Then open another agent repository in Codex and ask:

Use $free2pa-protect-agent.
Find the files this app loads into model context.
Show me the load boundary and current security checks.
Then add a fail-closed Free2PA gate and tests for trusted, changed,
and outside-publisher cases.

Codex should not guess the trust group. The human owner chooses publishers and failure policy. Codex wires the verifier into the real loader and proves the boundary.

Guarded repair

If a trusted file changed after signing, Free2PA can restore the original bytes embedded in the signed receipt:

node bin/free2pa.js repair agent/SOUL.md \
  --trust-store .free2pa/trusted-publishers

Repair is deliberately narrow. It runs only when:

• the receipt signature is valid;

• the certificate is current;

• the publisher is locally trusted; and

• the embedded original hashes to the signed value.

By default, the rejected file is preserved as evidence.

Repair will not bless changed content, expired credentials, invalid sidecars, or outside publishers.

GPT-5.6's role

Cryptography answers:

Who signed this exact file, and does this project trust that publisher?

GPT-5.6 can separately review behavior:

Does the verified instruction ask for risky actions?

Those are intentionally separate. GPT-5.6 can explain prompt injection, secret access, destructive actions, and excessive permissions, but it cannot turn a failed Free2PA gate into LOAD.

Configure an OpenAI or Azure OpenAI account only if you want optional behavioral audits. Signing, verification, trust, repair, load gates, MCP, and CI do not require a model account.

What Free2PA protects

Free2PA is useful for text files that shape an agent before or during runtime:

• system prompts;

• AGENTS.md, SOUL.md, and SKILL.md;

• MCP and tool manifests;

• permission and policy files;

• prompt libraries;

• workflow definitions;

• project-specific agent configuration.

That includes OpenClaw-style projects and other agent apps where local files define identity, tools, skills, or startup behavior.

It detects:

• changed bytes after signing;

• valid files from publishers outside this verifier's trust store;

• expired or not-yet-valid certificates;

• malformed sidecars;

• invalid signatures;

• missing receipts;

• pull requests that introduce unverified control files.

It does not prove that signed instructions are benevolent. Use Free2PA as a load-time provenance gate, then use code review, tests, least privilege, and optional GPT-5.6 audit for behavior.

Scope and no-warranty notice

Free2PA determines two provenance facts about an agent control file:

• the apparent origin of the signed receipt; and

• whether the current file bytes differ from the bytes recorded in that signed receipt.

Free2PA does not certify that a file is safe, correct, complete, legal, non-infringing, secure, authorized for every environment, or suitable for any particular use. A local verifier may decide to trust a publisher certificate, but that trust decision belongs to the verifier operator.

Free2PA is provided under the Apache License 2.0 on an "AS IS" basis, without warranties or conditions of any kind, and with the limitation of liability stated in the license.

C2PA relationship

Free2PA is C2PA-style and C2PA-inspired, not a conforming C2PA implementation. It does not claim interoperability with C2PA Content Credentials and does not make any claim beyond origin and edit detection for the signed file. It uses a sidecar format to carry a signed provenance receipt for text-based agent control files. The goal here is narrower and local: make origin, exact-file integrity, and project-local publisher trust machine-checkable before an agent loads the file.

Development

Prerequisites:

• Node.js 20 or newer

• OpenSSL on PATH

• macOS or Linux

Commands:

npm ci
npm test
npm run check
node bin/free2pa.js --help

Package exports:

import { signSkill } from 'free2pa';
import { verifySkill } from 'free2pa';
import { loadVerifiedFile } from 'free2pa/load-gate';

License: Apache-2.0.