The protocol is portable. The supported implementation is explicit.

Each binding is one complete program that was run against the pinned core before publication, with its real output shown. All five follow the same six steps: install, validate structure against the hosted schemas, sign an origin statement, verify a handoff bundle, refuse a tampered copy, and read the report.

The contract every binding relies on

A binding is thin because the contract is small. Automate on the exit status and the JSON report, never on human-readable output.

0 · allow

Every required check passed under the exact policy and expectations supplied. stdout holds the report.

1 · deny or indeterminate

stdout holds a complete report; primaryError names the boundary that failed.

2 · invalid input

No report. stderr carries one JSON object with errorClass and message.

3 · internal error

No report. Treat it as an outage, never as a verdict.

The report’s shape is published as the verification-report schema, and every diagnostic code is listed by step in the ordered checks.

Command line

The CLI is the shortest route to every protocol operation without binding a pipeline to Python internals. Install it from a reviewed revision:

git clone https://github.com/makoto-project/makoto.git
cd makoto
git checkout 276008eeec0f10d5322c4c627b8c103222fee841
uv sync --locked --dev
uv run makoto --help

makoto key generate

Write an Ed25519 key pair: --private-out at mode 0600 and --public-out.

makoto key inspect

Print the key ID a trust policy uses for a public key.

makoto digest

Print the SHA-256 digest of a file in the form statements use.

makoto attest origin

Sign an origin statement: --subject name=path, --source-kind, --source-uri, optional --source-metadata.

makoto attest transform

Sign a transformation: one --input-binding file per input naming its predecessor envelope, plus --operation-type.

makoto envelope inspect / cosign

Show an envelope’s payload digest and signer key IDs, or add a co-signature without changing statement identity.

makoto handoff create

Package heads, reachable statements, and final artifacts into a bundle signed by an authorized handoff key.

makoto verify bundle

Run the fourteen ordered steps against a receiver policy and independent expectations; --json writes the report.

makoto schema validate

Validate a document against a core schema or a digest-pinned profile.

makoto profile create

Create a profile reference that pins a schema by digest and closure digest.

makoto policy check

Validate a trust policy, including the canonical ordering the verifier requires.

Run the complete local setup · Walk through a full handoff

Python

The Python package is the reference implementation used by the CLI and its tests. It is not advertised as a separately published distribution, and the PyPI name makoto belongs to an unrelated project. Use the command line for the supported boundary. When a long-running service must verify in-process, the Python binding shows the exact VerificationRequest call the CLI makes, pinned to a revision.

Browse the reviewed Python source ↗ · Read the reviewed tests ↗

Platform integrations

For orchestrators, warehouses, and stream processors, one standard-library helper, makoto_boundary.py, wraps signing, handoff, and verification and separates tool failures, signing conflicts, and denials into three exceptions. Read the helper, then pick a platform:

Airflow

TaskFlow DAG with a failing gate task. Executed on Airflow 3.3.1.

Dagster

Signing assets and a blocking asset check. Executed.

Prefect

Signing tasks and a gate that is never retried. Executed.

dbt

A dbtRunner wrapper around an exported model. Executed.

Spark

Driver-side signing after _SUCCESS. Executed.

Kafka

Signed offset windows and verified commits. Executed against a broker.

Snowflake

Pinned unload, signed download, gated load. Stubbed platform calls.

Databricks

Three-task job with a gate task. Stubbed runtime.

Expanso

Edge seal through the command processor. Validated pipeline.

The browser is a useful verifier surface, but not a shortcut around trust.

A future browser library can hash received ArrayBuffer bytes, validate schemas from a pinned catalog, verify Ed25519 signatures, and render a report. It still needs receiver-owned authorization policy, explicit expected heads or manifests, resource limits, and negative test vectors. No CDN import or package name is promised until those constraints are implemented and tested.

This site’s repository keeps an earlier API study in sdk/javascript and sdk/python. It models ergonomics, not the current protocol: its documents are an earlier bill-of-materials format with no signatures over exact payload bytes, no receiver policy, and no handoff, so the verifier on this site cannot check them. Its real interfaces, executed as written, are worth reading for shape:

// sdk/javascript/src: generate(options) and verify(dbom, fileBuffer)
import { readFile } from "node:fs/promises";
import { generate, verify } from "./sdk/javascript/src/index.js"; // needs ajv and ajv-formats

const buffer = await readFile("sales.csv");
const dbom = await generate({ fileBuffer: buffer, fileName: "sales.csv", signer: "github:you" });
const result = await verify(dbom, buffer); // { valid: boolean, errors: string[] }
console.log(result.valid ? "valid" : result.errors); // valid

# sdk/python/makoto: generate(file_path, signer, ...) and verify(...) -> VerifyResult
from pathlib import Path
from makoto import generate, verify  # the study package, not the core implementation

path = str(Path("sales.csv").resolve())
dbom = generate(path, signer="github:you")
print(verify(dbom, file_path=path).valid)  # True
Path(path).write_text(Path(path).read_text() + "3,4\n")
print(verify(dbom, file_path=path).errors)  # ['File hash mismatch: expected 0ae7..., got 4bb0...']

Read, do not deploy. @makoto/sdk was never published to npm, and the Python study is not on PyPI. Its generate also requires an absolute path: a relative one raises ValueError: relative path can't be expressed as a file URI.

Review the JavaScript design source ↗ · Review the earlier Python API study ↗

What every future SDK must preserve

1. Exact bytesDo not parse and silently rewrite signed JSON. DSSE authenticates the payload bytes that were actually signed.
2. Closed core shapesCore statements stay portable and strict. Team-specific fields enter through declared, digest-pinned profiles.
3. Independent policySignature validity and signer authorization are separate results. The receiver supplies trust policy outside the bundle.
4. Graph identityTransformation inputs bind both the predecessor statement digest and the exact subject digest.
5. Canonical orderPolicies, manifests, and catalogs are rejected when arrays are out of canonical order, so two implementations never disagree about identity.
6. Stable failuresImplementations should agree on allow and deny behaviour and on machine-readable diagnostic codes for every conformance fixture.