ProofSlip

ProofSlip

A public proof that a specific GitHub Actions job ran for a specific commit.

ProofSlip verifies a GitHub Actions OIDC token, records the provider-backed job identity and execution context, and returns a stable public proof URL. No ProofSlip account or API key is required for release proofs.

Live site · Agent Skill · Docs · OpenAPI · Privacy

Install the Agent Skill

npx skills add Johnny-Z13/proofslip --skill proofslip-release-proof

The open-source skill gives Codex, Claude Code, Cursor, and other skills-compatible agents two focused workflows:

• verify an existing ProofSlip URL and report provider facts, ProofSlip observations, submitted context, expiry, and limitations separately;
• prepare the smallest GitHub Actions change in the workflow that actually deploys or releases a project.

The skill inspects before editing, shows the proposed workflow change, and asks for approval. It does not create a synthetic “proof-only” workflow, and it never commits, pushes, or releases without separate authorization.

Example prompts:

Verify this ProofSlip URL and tell me exactly what it proves and does not prove.

Add ProofSlip after the real deploy step in this repository. Show me the patch before changing it.

What a release proof means

Every release-proof/v1 object keeps three evidence sources separate:

| Field | Source | What it establishes | |---|---|---| | issuer | GitHub Actions OIDC, provider-verified | The identity and execution context of the workflow job that requested the token. | | observations | ProofSlip | Optional facts ProofSlip observed at issuance time, such as an HTTP status. | | submitted_context | Workflow input | Caller-supplied labels, explicitly marked unverified. |

A proof does not establish that tests passed, that the entire workflow succeeded, or that a deployment contains the claimed commit.

Manual GitHub Actions quickstart

permissions:
  contents: read
  id-token: write

steps:
  - name: Create ProofSlip release proof
    shell: bash
    run: |
      TOKEN="$(curl -sSf \
        -H "Authorization: bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
        "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https%3A%2F%2Fproofslip.ai" \
        | jq -r .value)"

      BODY="$(jq -n \
        --arg key "${GITHUB_REPOSITORY}:${GITHUB_RUN_ID}:${GITHUB_RUN_ATTEMPT}" \
        '{idempotency_key:$key}')"

      curl --fail-with-body -sS \
        -X POST https://proofslip.ai/v1/proofs/releases/github-actions \
        -H "Authorization: Bearer ${TOKEN}" \
        -H "Content-Type: application/json" \
        --data "${BODY}"

Optional request fields let the workflow ask ProofSlip to observe a public HTTPS endpoint and attach unverified labels:

{
  "idempotency_key": "owner/repo:run_id:attempt",
  "deployment": {
    "url": "https://app.example.com",
    "health_path": "/health"
  },
  "submitted_context": {
    "environment": "production",
    "label": "web release"
  }
}

The response includes a human proof_url and a machine-readable proof_id:

{
  "proof_id": "prf_...",
  "proof_url": "https://proofslip.ai/proof/prf_...",
  "schema_version": "release-proof/v1",
  "is_valid": true,
  "is_expired": false,
  "trust_level": "provider_verified",
  "verification_method": "github_actions_oidc",
  "issuer": {
    "type": "github_actions",
    "repository": "owner/repo",
    "ref": "refs/heads/main",
    "sha": "...",
    "run_id": "...",
    "run_attempt": 1
  },
  "observations": [],
  "submitted_context": null,
  "issued_at": "...",
  "expires_at": "..."
}

Fetch JSON with:

curl https://proofslip.ai/v1/proofs/prf_...

API surface

| Method | Endpoint | Auth | Purpose | |---|---|---|---| | POST | /v1/proofs/releases/github-actions | GitHub Actions OIDC | Create a provider-backed release proof. | | GET | /v1/proofs/:proof_id | None | Fetch public proof JSON. | | GET | /proof/:proof_id | None | View the human evidence page. | | POST | /v1/receipts | ProofSlip API key | Create a legacy workflow receipt. | | GET | /v1/verify/:receipt_id | None | Verify a legacy receipt. | | GET | /v1/receipts/:receipt_id/status | None | Poll legacy receipt status. | | POST | /v1/auth/signup | None | Create an API key for legacy receipts. |

The full contract is available in the human docs, OpenAPI, and docs/specs/release-proof-v1.md.

Public access and retention

Release proof URLs are public, including proofs created from private repositories. The proof can expose repository metadata, workflow identifiers, actor, ref, SHA, and any submitted context.

Release proofs have a 90-day validity window. After that window they return HTTP 410 with is_expired: true, but V1 keeps the full record inspectable. Expiration is not automatic deletion. Read the privacy policy before enabling private-repository workflows.

Legacy receipts are different: they expire after at most 24 hours and are deleted by automated cleanup.

Aggregate release-proof event rows contain no tokens, emails, IPs, or payload content and are deleted after at most 90 days.

Security properties

• GitHub OIDC signature verification against GitHub's JWKS.
• Strict issuer, audience, expiry, not-before, issued-at, algorithm, and required-claim checks.
• Raw OIDC tokens are never stored or logged.
• Token IDs are stored only as SHA-256 digests for replay protection.
• Provider claims, ProofSlip observations, and submitted context never share a trust category.
• Release proof records are immutable through the application API.
• Idempotent retries return the existing proof; conflicting retries fail with 409.
• Deployment observations use public HTTPS only, pin the validated DNS address, never follow redirects, and never read response bodies.
• Global request bodies are limited to 16KB.

Legacy receipt integrations

The published integrations currently expose the original short-lived receipt API, not release-proof creation.

MCP

npx -y @proofslip/mcp-server

Tools: create_receipt, verify_receipt, check_status, signup.

LangChain

pip install langchain-proofslip

Tools: create receipt, verify receipt, and check status, plus a toolkit wrapper.

Machine discovery

| Endpoint | Format | Purpose | |---|---|---| | /llms.txt | Text | Compact agent context. | | /llms-full.txt | Text | Complete agent contract. | | /.well-known/openapi.json | JSON | OpenAPI 3.1. | | /.well-known/agent.json | JSON | Agent discovery. | | /.well-known/mcp.json | JSON | Legacy receipt MCP package. |

Local development

Requirements: Node.js 18+ and PostgreSQL (the production deployment uses Neon).

git clone https://github.com/Johnny-Z13/proofslip.git
cd proofslip
npm install
cp .env.example .env
npm run db:migrate
npm run dev

Important environment variables:

| Variable | Purpose | |---|---| | DATABASE_URL | Application database. Production deployments point this at the production branch. | | TEST_DATABASE_URL | Dedicated test database or Neon branch. It must not resolve to the same target as DATABASE_URL. | | BASE_URL | Public base URL; defaults to https://proofslip.ai. | | CRON_SECRET | Protects cleanup of expired receipts and 90-day aggregate proof events. | | RESEND_API_KEY | Optional transactional signup email. | | PROOFSLIP_API_KEY | Used by production smoke tests for legacy receipts. |

The integration test setup remaps DATABASE_URL to TEST_DATABASE_URL and fails closed if the two targets are identical, including pooled versus direct Neon URLs.

Tests

npm run test:unit      # unit + integration; mutates TEST_DATABASE_URL only
npm run test:smoke     # live production smoke tests
npm run test:packages  # SDK + MCP package tests
npm run test:all       # all four layers, including LangChain pytest

The LangChain layer runs from packages/langchain/.venv when available.

Project structure

src/
├── routes/proofs.ts          # release-proof create/fetch routes
├── routes/receipts.ts        # legacy receipt creation
├── lib/github-oidc.ts        # GitHub OIDC verification
├── lib/observe-deployment.ts # pinned-address HTTPS observation
├── lib/proof-format.ts       # shared public proof representation
└── views/                    # HTML and discovery surfaces
packages/
├── sdk/                      # legacy receipt TypeScript client
├── mcp-server/               # @proofslip/mcp-server
└── langchain/                # langchain-proofslip
tests/
├── lib/
├── routes/
├── smoke/
└── packages/

Context Capsule

ProofSlip and Context Capsule remain separate products with one narrow connection:

• ProofSlip is evidential: “What did the release environment attest, and can the next agent check it?”
• Context Capsule is navigational: “What is the situation, what matters, and what should happen next?”

A coding-handoff/v1 capsule can include release-proof IDs in references.proofslip_ids. The receiving agent still fetches and inspects each proof; a reference alone does not make a handoff claim verified. See Context Capsule.

Status

ProofSlip is live and open source. release-proof/v1 and the backward-compatible receipt API are deployed. The repository-owned release-proof Agent Skill is the primary authoring and verification path under active validation; website and discovery changes should be deployed only after the full local and production checks pass.