ProofGate

ProofGate is a production-grade TypeScript core for building safe, auditable action flows using:

• Intent Envelopes (what is being requested)
• Policies / Invariants (whether it’s allowed)
• Approval Tokens (signed approvals bound to an intent hash)
• Execution (v1: deterministic simulation)
• Receipts (portable proof artifacts, optionally signed)

Current v1 supports a single action: email.send.

Install

npm i proofgate
# or
pnpm add proofgate
# or
yarn add proofgate

• Node: >= 18
• ESM: this package is "type": "module"

Exports (v1)

Core exports you’ll use most:

Intent

• ActionType
• IntentEnvelopeSchema
• IntentEnvelope (type)

Policy / Invariants

• Decision (type)
• SafeSendPolicy (type)
• decideSafeSend(intent, policy)

Execution

• ExecutionResult (type)
• executeIntent(intent)

Receipts

• ProofReceipt (type)
• stableStringify(value)
• mintReceipt(intent, decision, signer?)

Signing (Ed25519)

• ReceiptSignature (type)
• Keypair (type)
• generateEd25519Keypair()
• signEd25519(privateKeyB64, messageUtf8)
• verifyEd25519(publicKeyB64, messageUtf8, signatureB64)

Approval Tokens

• ApprovalTokenPayload (type)
• ApprovalToken (type)
• hashIntent(intent)
• mintApprovalToken({ intent, ttlMs, ed25519PrivateKeyB64 })
• verifyApprovalToken(token)

Inspect the exact runtime export list:

node -e "import('proofgate').then(m=>console.log(Object.keys(m)))"

The v1 flow

Intent → Decide → (Optional Approval) → Execute (simulated) → Receipt

1) Create & validate an intent

Zod defaults apply for cc, bcc, links, requestedScopes, and meta.

import { IntentEnvelopeSchema } from "proofgate";

const intent = IntentEnvelopeSchema.parse({
  intentId: "intent_000001",
  action: "email.send",
  actor: { actorId: "user_123", actorType: "human" },
  payload: {
    to: ["[email protected]"],
    subject: "Quarterly update",
    body: "Hello team...",
    links: ["https://docs.company.com/q1"]
  },
  requestedScopes: ["email.send"],
  meta: { campaign: "q1" }
});

IntentEnvelope fields (v1)

• intentId: string (min 8)

• action: "email.send"

• actor:

  • actorId: string (min 3)
  • actorType: "human" | "model" | "service"

• payload:

  • to: email[] (min 1)
  • cc: email[] (default [])
  • bcc: email[] (default [])
  • subject: 1..200 chars
  • body: 1..20000 chars
  • links: url[] (default [])

• requestedScopes: string[] (default [])

• meta: record<string, unknown> (default {})

2) Decide with SafeSend policy

SafeSend enforces:

• recipient count cap
• recipient domain allowlist
• link domain allowlist
• optional approval requirement for external recipients

import { decideSafeSend } from "proofgate";
import type { SafeSendPolicy } from "proofgate";

const policy: SafeSendPolicy = {
  allowedRecipientDomains: ["company.com"],
  allowedLinkDomains: ["company.com", "docs.company.com"],
  maxRecipients: 10,
  requireApprovalForExternal: true
};

const decision = decideSafeSend(intent, policy);

switch (decision.decision) {
  case "DENY":
    console.error("DENIED:", decision.reason);
    break;

  case "REQUIRE_APPROVAL":
    console.warn("APPROVAL REQUIRED:", decision.reason);
    console.warn("Approval token hint:", decision.approvalToken);
    break;

  case "EXECUTE":
    console.log("OK:", decision.reason);
    break;
}

Decision type

type Decision =
  | { decision: "DENY"; reason: string; requiresApproval: false }
  | { decision: "REQUIRE_APPROVAL"; reason: string; requiresApproval: true; approvalToken: string }
  | { decision: "EXECUTE"; reason: string; requiresApproval: false };

Domain allowlisting behavior

Allowlists support exact match and subdomains:

• allow company.com → also allows docs.company.com, mail.ops.company.com, etc.

3) Approval tokens (signed)

SafeSend currently returns a placeholder approvalToken string (appr_${intentId}) when it wants approval. For cryptographic approvals you can mint/verify real approval tokens using approval_token.

Mint an approval token

Approval tokens are bound to the hash of the canonical intent JSON.

import { generateEd25519Keypair, mintApprovalToken } from "proofgate";

const kp = generateEd25519Keypair();

const { token, payload } = mintApprovalToken({
  intent,
  ttlMs: 5 * 60 * 1000,
  ed25519PrivateKeyB64: kp.privateKeyB64
});

console.log("token:", token);
console.log("payload:", payload);

Payload fields:

• v: 1
• intentHash: sha256(canonical intent JSON)
• exp: unix ms expiry
• nonce: random hex

Verify an approval token + bind to intent

import { verifyApprovalToken, hashIntent } from "proofgate";

const v = verifyApprovalToken(token);
if (!v.ok) throw new Error(v.error);

// Ensure the approval token is for THIS exact intent:
const expected = hashIntent(intent);
if (v.payload.intentHash !== expected) {
  throw new Error("Approval token does not match intent");
}

Verification checks:

• token decodes (base64url JSON)
• payload parses + fields are valid
• Ed25519 signature is valid
• token is not expired

v1 embeds the public key in the token (pubB64) so verifiers can validate without extra config.

4) Execute (v1 simulation)

executeIntent is deliberately side-effect free in v1. For email.send, it returns a deterministic summary and never echoes the full body.

import { executeIntent } from "proofgate";

const result = await executeIntent(intent);

if (result.status === "SIMULATED") {
  console.log(result.message);
  console.log(result.output);
} else {
  console.error("EXECUTION FAILED:", result.message, result.error);
}

For email.send, output includes:

• provider: "simulated"
• toCount, ccCount, bccCount
• subject
• bodyBytes (UTF-8 byte length)

5) Mint a ProofReceipt (decision receipt)

Receipts are portable proof artifacts that include:

• canonical intent hash
• deterministic receipt id
• the decision + reason
• requested scopes trace
• optional Ed25519 signature

import { mintReceipt, generateEd25519Keypair } from "proofgate";

const kp = generateEd25519Keypair();

const receipt = mintReceipt(intent, decision, {
  ed25519PrivateKeyB64: kp.privateKeyB64
});

console.log(receipt.receiptId);
console.log(receipt.hashes.intentHash);
console.log(receipt.signature?.alg); // "Ed25519"

Receipt fields:

• receiptId — sha256(canonical receipt payload)
• issuedAt — ISO timestamp
• intentId, action
• decision, reason
• trace.requestedScopes
• hashes.intentHash
• optional signature { alg, publicKeyB64, signatureB64 }

Canonical JSON (stableStringify)

ProofGate hashes and signs canonical JSON produced by stableStringify:

• sorts object keys recursively
• preserves array order
• throws on cycles

import { stableStringify } from "proofgate";

const canon = stableStringify(intent);

Hashes used in v1:

• intentHash = sha256(stableStringify(intent))
• receiptId = sha256(stableStringify(receiptPayload))

Ed25519 signing helpers

import { generateEd25519Keypair, signEd25519, verifyEd25519 } from "proofgate";

const kp = generateEd25519Keypair();

const msg = "hello";
const sig = signEd25519(kp.privateKeyB64, msg);

const ok = verifyEd25519(sig.publicKeyB64, msg, sig.signatureB64);
console.log(ok); // true

Key encoding:

• public key: SPKI DER → base64
• private key: PKCS8 DER → base64

Security notes (v1)

• executeIntent is simulation-only: it does not actually send email.

• SafeSend returns a placeholder approval token string in REQUIRE_APPROVAL mode.

  • Use mintApprovalToken / verifyApprovalToken for cryptographic approvals.

• For approvals, always verify:

  • signature validity
  • expiry
  • intentHash matches the exact intent being approved

Build

pnpm build

Outputs:

• dist/index.js
• dist/index.d.ts

License

MIT License

Copyright (c) 2026 BJ K℞ Klock

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.