workrr Trust Certificate — Specification v0.1 (draft)

A workrr certificate is an in-toto Statement v1 inside a DSSE envelope, signed keylessly through Sigstore and recorded in the public Rekor transparency log. This document is the contract every implementation (TypeScript, Go) must follow. Two implementations given the same artifact, policy, and ruleset must produce byte-identical checks.

• Predicate type: https://trust.workrr.ai/certificate/v0.1
• JSON Schema: predicate-v0.1.schema.json
• Design rationale: docs/design.md

1. Artifact digest

The subject digest is always sha256.

• Single file: sha256 of the file's bytes. predicate.artifact.digestAlgorithm = "file-sha256".
• Directory: workrr-dirhash-v1:
  1. Walk the directory recursively. Skip any path segment named .git. Don't follow symlinks. A symlink is hashed as its link-target string.
  2. For each regular file, compute sha256(bytes) as lowercase hex.
  3. Relative paths use / separators and are sorted by UTF-8 byte order.
  4. Build the manifest: one line per file, <hex> <path>\n (two spaces).
  5. The digest is sha256(manifest).

The subject name is the artifact's declared name (SKILL.md name, server.json name) or else the directory/file basename.

2. Artifact type

Detected in this order: SKILL.md present → skill; server.json present → mcp-server; AGENTS.md or CLAUDE.md present → agent-context; else other. A single file named SKILL.md, AGENTS.md, or CLAUDE.md maps the same way.

3. Checks

Every check records exactly what was used, so anyone can re-run it.

Scan wording. A pass means "no known-pattern findings of severity high or critical." It never means safe or injection-free. Findings of severity warn are recorded and don't fail the check.

Canonical JSON. Object keys sorted lexicographically, no whitespace, UTF-8. Precisely: keys sorted by UTF-8 byte order; strings and numbers serialized as ECMAScript JSON.stringify does (only ", \ and U+0000–U+001F are escaped; 1e+21, 1e-7, -0 → 0); absent optional fields are omitted, never null.

Determinism rules. Gold compares checks byte for byte, so these are part of the contract, not implementation details:

• Scan input. Files containing a NUL byte are skipped. Other files are decoded as UTF-8 with WHATWG replacement (one U+FFFD per maximal invalid subpart; a BOM is kept). Symlinks are read through to their target; unreadable files are skipped.
• Scan patterns are ECMAScript regular expressions, run with their flags plus m. Without u, they operate on UTF-16 code units. A finding's line is 1 + the number of \n before the match start; each rule reports at most one finding per line.
• Findings order: file (UTF-8 byte order), then line, then rule id.
• SKILL.md frontmatter is the YAML between a leading --- line (an optional leading UTF-8 BOM U+FEFF is ignored) and the next --- line, parsed with the YAML 1.2 core schema (no merge keys; duplicate keys are a parse error). A frontmatter field counts only if it is a non-blank string.
• Symlinks inside an artifact directory must resolve within the artifact root; any symlink whose target escapes the artifact directory fails the policy check and is not read by the scanner.

Cross-implementation test vectors live in test-vectors/; every implementation must pass them.

4. Level

Display names say how much scrutiny each level means: Scanned (scanned), Signed (banded), Tested (silver), Reproduced (gold). The wire values below are what certificates carry.

Trust bands (A–E). When level is banded, the certifier computes a deterministic A–E grade over four intrinsic signals (1 point each; 4 → A, 3 → B, 2 → C, 1 → D, 0 → E), unless overridden by external outcome evidence:

1. Zero scan warnings: scan.findings has no warn-severity findings.
2. Scoped tools: SKILL.md declares allowed-tools or the policy pins allowedTools.
3. Structured instructions: for a skill, description states when to trigger (use when) and the body has a Markdown heading or numbered step (1. ); for other types, a top-level README or README.md is present.
4. Declared license: a top-level LICENSE/LICENCE/COPYING file or a non-blank license frontmatter field is present.

5. Signing and logging

• Certificates are signed keylessly with Sigstore Fulcio from the certifier's CI OIDC identity, and recorded in public Rekor.
• On GitHub the identity is the reusable workflow https://github.com/workrr-trust/certify/.github/workflows/certify.yml@<ref>, with Build Signer Digest (OID 1.3.6.1.4.1.57264.1.10) = job_workflow_sha. For an annotated tag that is the tag object, not the peeled commit.
• The built-in trust policy accepts only certify.yml@refs/tags/v0.1.0 (digest 9fbe3e453cbd80bef0301f08db79408bb12c7d64) and certify.yml@refs/tags/v0.1.1 (digest 78d8c1a98c929b7b1c1b532c25256582a84887b1). refs/heads/main is not accepted. No GitLab signer is listed.

6. Verification

A verifier must:

1. Recompute the artifact digest (§1) and match it to the Statement subject.
2. Check predicateType is a supported version.
3. Verify the Sigstore bundle: certificate chain, signature, and Rekor inclusion.
4. Match the signer identity (SAN, issuer, Build Signer Digest) against the trust policy. A SAN of refs/heads/main, an unlisted tag, or a digest other than the one pinned for that tag is rejected. The policy embedded in this build lists the certify.yml release tags and the scan.yml observer tag (src/trust-policy.ts).
5. Cross-check source.uri and source.commit in the predicate against the signing certificate's Fulcio SourceRepositoryURI (1.3.6.1.4.1.57264.1.12) and SourceRepositoryDigest (1.3.6.1.4.1.57264.1.13) extensions when present, and derive the certified level (silver or banded) directly from the signed checks results rather than trusting predicate.level alone. Observer signers (trust policy "role": "observer", the public-scan workflow) are the exception: their Fulcio SourceRepositoryURI must be https://github.com/workrr-trust/certify, predicate.level must be scanned and checks.tests.result must be none. The predicate's source is then the observed repository and is not cross-checked against Fulcio. Such a bundle is reported as scanned only when no publisher bundle verifies, and it never counts toward gold. A publisher signer's certificate that claims scanned is rejected.
6. Read checks.policy.policyName and checks.policy.policyDigest and report both. The name workrr-baseline-v0.1 is reserved: that name with any other digest is rejected. Any other digest is not a baseline result, and the verifier must not report silver, gold, or banded for it. A signed trust policy's baselinePolicyDigests map is an additional allow-list when that document is in use; it does not relax this rule.
7. If the caller passes a source repository, it must match source.uri after normalizing .git, embedded credentials, and git@host:org/repo. owner/repo and host/owner/repo match that URL. A mismatch is a failed verification and is not reported at a baseline level.
8. Check the certificate isn't revoked (§7). --offline skips this and must say so.
9. For gold: repeat 1–7 for a second bundle from a different forge, require both policies to be the known baseline, and compare checks byte-for-byte as canonical JSON. The built-in policy has no second forge, so it does not award gold.

7. Signed trust policy and revocation

The trust policy is a versioned JSON document. Verifiers fetch it, check its signature, and cache it. The service that hosts it is not a trust anchor.

7.1 Policy document

Media type of the signed bytes: application/vnd.workrr.trust-policy+json. The bytes are canonical JSON (§3) with no trailing newline.

sequence only goes up. An older signed document is a rollback:

ROLLBACK: trust policy sequence 1 is older than 3

The same rule applies to a revocation checkpoint sequence the client has already verified.

7.2 Signature

The on-wire envelope is application/vnd.workrr.signed-blob+json;version=1:

{
  "mediaType": "application/vnd.workrr.signed-blob+json;version=1",
  "payloadType": "application/vnd.workrr.trust-policy+json",
  "payload": "<standard base64 of the canonical document>",
  "signature": { "algorithm": "sigstore", "bundle": { } }
}

payload is standard base64 (with padding) of the exact bytes that were signed. Those bytes must be canonical JSON. The signature is over those bytes, not over the envelope.

Production signatures are Sigstore bundles from cosign sign-blob --bundle, made by a release-tag run of:

• .github/workflows/trust-policy.yml for a policy
• .github/workflows/revoke.yml for a revocation entry or checkpoint

Both identities use issuer https://token.actions.githubusercontent.com and a SAN of

https://github.com/workrr-trust/certify/.github/workflows/<workflow>.yml@refs/tags/vX.Y.Z

refs/heads/main is not accepted. On a revocation entry or checkpoint the document's signer field must equal that certificate SAN.

The shared test vectors sign with ed25519 instead, so both implementations can check tamper and rollback without Fulcio. Production verifiers do not accept that key.

7.3 Revocation entry

Payload type application/vnd.workrr.revocation-entry+json. Schema workrr-revocation-v1.

A checkpoint (application/vnd.workrr.revocation-checkpoint+json, schema workrr-revocation-checkpoint-v1) has sequence, head (sha256 of the entry at that sequence), timestamp, and signer. It is signed the same way.

A client that loads a policy with watermark w and head h fetches <revocationFeed>/since/<w> and requires:

• every entry and the checkpoint to verify;
• entry sequences w+1, w+2, … with prev chaining from h;
• the checkpoint sequence and head to match the last entry;
• the checkpoint sequence not to go backwards.

A match fails that bundle with REVOKED: <reason>. If every otherwise-valid bundle is revoked, the result status is REVOKED.

A feed that answers but does not verify fails closed. A feed that cannot be reached does not. The client adds revocation was not checked.

7.4 Fetch, cache, offline

• GET <trust-api>/v1/policy, then the revocation feed above.
• A verified policy is cached for one hour. Revocations are fetched on each verification.
• If the policy cannot be fetched and a previously verified cache entry exists, the cache is used even past the TTL, with trust policy fetch failed; using cached trust policy.
• If there is no cache, the policy embedded in the binary is used, with trust policy fetch failed; using the embedded trust policy. The embedded policy's sequence is the floor. It starts at 0 until a release sets it.
• A policy whose signature does not verify is not used. The embedded policy is used, with trust policy signature invalid; using the embedded trust policy.
• --offline does not contact the trust API. It uses the embedded policy, does not check revocation, and prints:

offline: using the embedded trust policy; revocation was not checked

A revoked certificate can still verify under --offline. Passing --trust-policy a legacy {version, signers} file is a local override; the signature is not checked and the command says so. A signed blob passed that way is verified.

The host (https://trust-api.workrr.ai, or WORKRR_TRUST_API) is transport. Replacing it changes availability, not who can sign.

8. Findings

A public scan that fails a high or critical scan rule, or the policy's forbidden file type or escaping symlink rules, signs an in-toto Statement with predicate type https://trust.workrr.ai/finding/v0.1. Its predicate carries artifact, source and checks as in §3 (tests always none), plus kind (concealment when any failing rule is WT002, WT003, WT007 or WT008; otherwise check), findings (one item per failure: check, rule, severity, file, line where applicable, detail), certifier and scannedAt.

A finding is valid only from an observer signer whose Fulcio source repository is workrr-trust/certify. To accept one, a verifier checks the signature and Rekor inclusion as in §6, then reproduces it: it runs the same checks on the named commit and requires identical findings and kind under the same ruleset and policy digests. Certificate verifiers reject this predicate type. Format and policy: docs/findings.md.

Versioning

Breaking changes bump the predicate type URI. Verifiers must reject unknown predicate types.