@atp-protocol/spec

Protocol constants, JSON schemas, Ed25519 signing, and replay protection for the Agent Transaction Protocol (ATP) 1.0 — the open specification for autonomous agent action governance.

Install

npm install @atp-protocol/spec

Quick test

After installing, paste this into a .mjs file and run it with node:

import { createHash } from 'node:crypto';
import {
  ATP_PROTOCOL, ATP_VERSION,
  generateSigningKeyPair, signReceipt, verifyReceiptSignature, canonicalBytes
} from '@atp-protocol/spec';

const { publicKey, privateKey } = generateSigningKeyPair();
const snapshot = { action: 'test' };
const now = new Date().toISOString();

const receipt = {
  receipt_id: 'TR-1', intent_id: 'TI-1', decision_id: 'TD-1',
  execution_status: 'executed', schemaVersion: '1.0.0',
  occurred_at: now, received_at: now, sealed_at: now, captured_at: now,
  event_snapshot: snapshot,
  event_snapshot_hash: createHash('sha256').update(canonicalBytes(snapshot)).digest('hex'),
  correlation_id: 'sess-1'
};

const signed = signReceipt(receipt, privateKey, 'my-key');
const { ok } = verifyReceiptSignature(signed, publicKey);

console.log(`${ATP_PROTOCOL} ${ATP_VERSION} — sign + verify: ${ok ? 'PASS' : 'FAIL'}`);
// ATP 1.0 — sign + verify: PASS

Usage

Protocol constants

import { ATP_PROTOCOL, ATP_VERSION, ATP_DECISION_OUTCOMES, ATP_EXECUTION_STATUSES } from '@atp-protocol/spec';

console.log(ATP_PROTOCOL);          // "ATP"
console.log(ATP_VERSION);           // "1.0"
console.log(ATP_DECISION_OUTCOMES); // ["allow", "approve", "deny"]
console.log(ATP_EXECUTION_STATUSES);// ["executed", "blocked", "expired", "error"]

Sign and verify a receipt

import { createHash } from 'node:crypto';
import { generateSigningKeyPair, signReceipt, verifyReceiptSignature, canonicalBytes } from '@atp-protocol/spec';

const { publicKey, privateKey } = generateSigningKeyPair();

const eventSnapshot = { action: 'purchase', item: 'flowers' };
const now = new Date().toISOString();

const receipt = {
  receipt_id: 'TR-123',
  intent_id: 'TI-456',
  decision_id: 'TD-789',
  execution_status: 'executed',
  schemaVersion: '1.0.0',
  occurred_at: now,
  received_at: now,
  sealed_at: now,
  captured_at: now,
  event_snapshot: eventSnapshot,
  event_snapshot_hash: createHash('sha256').update(canonicalBytes(eventSnapshot)).digest('hex'),
  correlation_id: 'sess-1'
};

const signed = signReceipt(receipt, privateKey, 'my-key-id');
const result = verifyReceiptSignature(signed, publicKey);
// result.ok === true

Replay protection

import { ReplayGuard } from '@atp-protocol/spec';

const guard = new ReplayGuard({ windowMs: 300_000, skewMs: 5_000 });
const result = guard.check(signedReceipt);
// result.ok === true (first presentation)
// result.ok === false, result.reason === 'receipt_replay_detected' (duplicate)

JSON schemas

import { getSchemaPath } from '@atp-protocol/spec';

const intentSchema = getSchemaPath('intent');    // absolute path to intent.schema.json
const decisionSchema = getSchemaPath('decision');
const receiptSchema = getSchemaPath('receipt');

Or import the JSON directly:

import intentSchema from '@atp-protocol/spec/schemas/intent' with { type: 'json' };
import decisionSchema from '@atp-protocol/spec/schemas/decision' with { type: 'json' };
import receiptSchema from '@atp-protocol/spec/schemas/receipt' with { type: 'json' };

Exports

| Export | Description | |--------|-------------| | ATP_PROTOCOL | Protocol identifier — "ATP" | | ATP_VERSION | Protocol version — "1.0" | | ATP_DECISION_OUTCOMES | ["allow", "approve", "deny"] | | ATP_EXECUTION_STATUSES | ["executed", "blocked", "expired", "error"] | | ATP_SIGNING_ALGORITHM | "Ed25519" | | generateSigningKeyPair() | Generate an Ed25519 key pair (PEM) | | signReceipt(receipt, privateKey, kid) | Sign a receipt with Ed25519 + RFC8785-JCS | | verifyReceiptSignature(receipt, publicKey) | Verify a signed receipt | | receiptFingerprint(receipt) | SHA-256 fingerprint of a receipt | | canonicalJSONString(obj) | RFC8785-JCS canonical JSON string | | canonicalBytes(obj) | RFC8785-JCS canonical bytes (for hashing) | | exportPublicKeyAsJwk(publicKey, kid) | Export public key as JWK | | buildJwks(keys) | Build a JWKS document | | ReplayGuard | Sliding-window replay protection | | getSchemaPath(name) | Resolve path to a bundled JSON schema |

License

Apache-2.0