@atp-protocol/spec 1.0.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@atp-protocol/spec",
+  "version": "1.0.0",
+  "description": "ATP protocol constants and JSON schemas.",
+  "license": "Apache-2.0",
+  "author": "James Everest <james@transientintelligence.com> (https://transientintelligence.com)",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./schemas/intent": "./schemas/intent.schema.json",
+    "./schemas/decision": "./schemas/decision.schema.json",
+    "./schemas/receipt": "./schemas/receipt.schema.json"
+  },
+  "files": [
+    "src",
+    "schemas"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test ./test/smoke.test.mjs"
+  },
+  "dependencies": {
+    "base64-url": "^2.3.3",
+    "canonicalize": "^2.1.0"
+  }
+}

package/schemas/decision.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.transientintelligence.com/atp/decision.schema.json",
+  "title": "ATP Decision",
+  "type": "object",
+  "required": [
+    "decision_id",
+    "intent_id",
+    "outcome",
+    "reason_code",
+    "decided_at"
+  ],
+  "properties": {
+    "decision_id": {
+      "type": "string",
+      "pattern": "^TD-\\d+$"
+    },
+    "intent_id": {
+      "type": "string",
+      "pattern": "^TI-\\d+$"
+    },
+    "outcome": {
+      "type": "string",
+      "enum": ["allow", "approve", "deny"]
+    },
+    "reason_code": {
+      "type": "string",
+      "minLength": 1
+    },
+    "decided_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/intent.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.transientintelligence.com/atp/intent.schema.json",
+  "title": "ATP Intent",
+  "type": "object",
+  "required": [
+    "intent_id",
+    "actor_id",
+    "connector",
+    "action",
+    "action_class",
+    "target",
+    "context",
+    "governance_profile",
+    "requested_at"
+  ],
+  "properties": {
+    "intent_id": {
+      "type": "string",
+      "pattern": "^TI-\\d+$"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "OPTIONAL. Open namespace for implementation-specific intent key-value pairs.",
+      "maxProperties": 20,
+      "additionalProperties": true
+    },
+    "actor_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "connector": {
+      "type": "string",
+      "minLength": 1
+    },
+    "action": {
+      "type": "string",
+      "minLength": 1
+    },
+    "action_class": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target": {
+      "type": "object"
+    },
+    "context": {
+      "type": "object"
+    },
+    "governance_profile": {
+      "type": "string",
+      "minLength": 1
+    },
+    "requested_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/receipt.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.transientintelligence.com/atp/receipt.schema.json",
+  "title": "ATP Receipt",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "receipt_id",
+    "intent_id",
+    "decision_id",
+    "execution_status",
+    "captured_at",
+    "signature",
+    "occurred_at",
+    "received_at",
+    "sealed_at",
+    "event_snapshot",
+    "event_snapshot_hash",
+    "correlation_id",
+    "intent",
+    "decision"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0.0"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "OPTIONAL. Open namespace for implementation-specific, vendor, or domain-extensibility key-value pairs (e.g. trace_id, environment_name, token_counts).",
+      "maxProperties": 20,
+      "additionalProperties": true
+    },
+    "receipt_id": {
+      "type": "string",
+      "pattern": "^TR-\\d+$"
+    },
+    "intent_id": {
+      "type": "string",
+      "pattern": "^TI-\\d+$"
+    },
+    "decision_id": {
+      "type": "string",
+      "pattern": "^TD-\\d+$"
+    },
+    "execution_status": {
+      "type": "string",
+      "enum": ["executed", "blocked", "expired", "error"]
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "signature": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["alg", "kid", "sig", "canonicalization"],
+          "properties": {
+            "alg": { "type": "string", "enum": ["Ed25519"] },
+            "version": { "type": "string" },
+            "kid": { "type": "string", "minLength": 1 },
+            "sig": { "type": "string", "minLength": 1 },
+            "canonicalization": { "const": "RFC8785-JCS" }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Legacy hash-only signature. Implementations SHOULD migrate to Ed25519 object form."
+        }
+      ]
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "received_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "sealed_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "event_snapshot": {
+      "type": "object",
+      "minProperties": 1
+    },
+    "event_snapshot_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "correlation_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "input_hash": {
+      "type": "object",
+      "description": "RECOMMENDED. Hash of canonicalized input payload. Implementations SHOULD use this instead of embedding raw input.",
+      "required": ["alg", "digest"],
+      "properties": {
+        "alg": { "type": "string", "enum": ["sha256"] },
+        "digest": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "output_hash": {
+      "type": "object",
+      "description": "RECOMMENDED. Hash of canonicalized output payload. Implementations SHOULD use this instead of embedding raw output.",
+      "required": ["alg", "digest"],
+      "properties": {
+        "alg": { "type": "string", "enum": ["sha256"] },
+        "digest": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "cost": {
+      "type": "object",
+      "description": "OPTIONAL. Financial or resource cost attributed to this action.",
+      "required": ["amount", "currency"],
+      "properties": {
+        "amount": { "type": "string", "description": "Decimal string to avoid floating-point ambiguity." },
+        "currency": { "type": "string", "description": "ISO 4217 code or protocol-specific token symbol (e.g. USD, EUR, BTC, FLW)." },
+        "unit": { "type": "string" },
+        "payer": { "type": "string", "description": "Actor funding the action." }
+      },
+      "additionalProperties": false
+    },
+    "intent": {
+      "$ref": "https://schemas.transientintelligence.com/atp/intent.schema.json"
+    },
+    "decision": {
+      "$ref": "https://schemas.transientintelligence.com/atp/decision.schema.json"
+    }
+  },
+  "additionalProperties": true
+}

package/src/index.mjs

@@ -0,0 +1,74 @@
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const ATP_PROTOCOL = "ATP";
+export const ATP_VERSION = "1.0";
+
+export const ATP_SIGNING_MODES = Object.freeze({
+  ED25519: "Ed25519",
+  LEGACY_SHA256: "legacy-sha256"
+});
+
+export const ATP_DEPRECATED = Object.freeze({
+  LEGACY_SHA256_SIGNATURE: {
+    code: "receipt_deprecated_legacy_signature",
+    message:
+      "sha256: string signature is deprecated. Implementations MUST migrate to Ed25519 object form. This form will not be accepted in ATP 2.0."
+  }
+});
+
+export const ATP_ID_PATTERNS = Object.freeze({
+  receipt: "^TR-\\d+$",
+  intent: "^TI-\\d+$",
+  decision: "^TD-\\d+$"
+});
+
+export const ATP_DECISION_OUTCOMES = Object.freeze(["allow", "approve", "deny"]);
+export const ATP_EXECUTION_STATUSES = Object.freeze(["executed", "blocked", "expired", "error"]);
+
+export const ATP_RECEIPT_VALIDATION_CODES = Object.freeze({
+  MISSING_REQUIRED_FIELD: "receipt_missing_required_field",
+  MISSING_REQUIRED_OBJECT: "receipt_missing_required_object",
+  INVALID_RECEIPT_ID_FORMAT: "receipt_invalid_id_format",
+  INVALID_INTENT_ID_FORMAT: "intent_invalid_id_format",
+  INVALID_DECISION_ID_FORMAT: "decision_invalid_id_format",
+  INTENT_ID_MISMATCH: "receipt_intent_id_mismatch",
+  DECISION_ID_MISMATCH: "receipt_decision_id_mismatch",
+  INVALID_SCHEMA_VERSION: "receipt_invalid_schema_version",
+  INVALID_SIGNATURE_FORMAT: "receipt_invalid_signature_format",
+  SIGNATURE_VERIFICATION_FAILED: "receipt_signature_verification_failed",
+  INVALID_DATETIME_FORMAT: "receipt_invalid_datetime_format",
+  INVALID_CAPTURED_AT: "receipt_invalid_captured_at",
+  INVALID_EXECUTION_STATUS: "receipt_invalid_execution_status",
+  INVALID_DECISION_OUTCOME: "decision_invalid_outcome",
+  INVALID_SNAPSHOT_HASH: "receipt_invalid_snapshot_hash",
+  INVALID_TIMESTAMP_ORDER: "receipt_invalid_timestamp_order",
+  REPLAY_DETECTED: "receipt_replay_detected",
+  OUTSIDE_WINDOW: "receipt_outside_window",
+  KEY_NOT_FOUND: "receipt_key_not_found"
+});
+
+export {
+  ATP_SIGNING_ALGORITHM,
+  ATP_SIGNING_VERSION,
+  generateSigningKeyPair,
+  signReceipt,
+  verifyReceiptSignature,
+  receiptFingerprint,
+  canonicalJSONString,
+  canonicalBytes,
+  exportPublicKeyAsJwk,
+  buildJwks
+} from "./signing.mjs";
+
+export { ReplayGuard } from "./replay.mjs";
+
+export function getSchemaPath(name) {
+  if (!["intent", "decision", "receipt"].includes(name)) {
+    throw new Error(`Unknown ATP schema '${name}'`);
+  }
+  return resolve(__dirname, `../schemas/${name}.schema.json`);
+}

package/src/replay.mjs

@@ -0,0 +1,70 @@
+const ATP_RECEIPT_VALIDATION_CODES = {
+  MISSING_REQUIRED_FIELD: "receipt_missing_required_field",
+  INVALID_DATETIME_FORMAT: "receipt_invalid_datetime_format",
+  REPLAY_DETECTED: "receipt_replay_detected",
+  OUTSIDE_WINDOW: "receipt_outside_window"
+};
+
+const DEFAULT_WINDOW_MS = 5 * 60 * 1000;
+const DEFAULT_SKEW_MS = 30 * 1000;
+
+export class ReplayGuard {
+  #seen = new Map();
+  #windowMs;
+  #skewMs;
+
+  constructor({ windowMs = DEFAULT_WINDOW_MS, skewMs = DEFAULT_SKEW_MS } = {}) {
+    this.#windowMs = windowMs;
+    this.#skewMs = skewMs;
+  }
+
+  check(receipt) {
+    const now = Date.now();
+    this.#evict(now);
+
+    const receiptId = String(receipt?.receipt_id ?? "");
+    if (!receiptId) {
+      return { ok: false, reason: ATP_RECEIPT_VALIDATION_CODES.MISSING_REQUIRED_FIELD, detail: "receipt_id missing" };
+    }
+
+    const sealedAt = Date.parse(String(receipt?.sealed_at ?? ""));
+    if (!Number.isFinite(sealedAt)) {
+      return {
+        ok: false,
+        reason: ATP_RECEIPT_VALIDATION_CODES.INVALID_DATETIME_FORMAT,
+        detail: `sealed_at ${String(receipt?.sealed_at ?? "")} must be a valid date-time`
+      };
+    }
+    const earliest = now - this.#windowMs;
+    const latest = now + this.#skewMs;
+    if (sealedAt < earliest || sealedAt > latest) {
+      return {
+        ok: false,
+        reason: ATP_RECEIPT_VALIDATION_CODES.OUTSIDE_WINDOW,
+        detail: `sealed_at ${receipt.sealed_at} is outside observation window`
+      };
+    }
+
+    if (this.#seen.has(receiptId)) {
+      return {
+        ok: false,
+        reason: ATP_RECEIPT_VALIDATION_CODES.REPLAY_DETECTED,
+        detail: `receipt_id ${receiptId} already observed`
+      };
+    }
+
+    this.#seen.set(receiptId, now);
+    return { ok: true };
+  }
+
+  #evict(now) {
+    const cutoff = now - this.#windowMs;
+    for (const [id, observedAt] of this.#seen) {
+      if (observedAt < cutoff) this.#seen.delete(id);
+    }
+  }
+
+  get size() {
+    return this.#seen.size;
+  }
+}

package/src/signing.mjs

@@ -0,0 +1,128 @@
+import { sign as cryptoSign, verify as cryptoVerify, generateKeyPairSync, createHash, createPublicKey } from "node:crypto";
+import canonicalize from "canonicalize";
+import base64Url from "base64-url";
+
+export const ATP_SIGNING_ALGORITHM = "Ed25519";
+export const ATP_SIGNING_VERSION = "ATP-ED25519-1";
+
+const BASE64_URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+function encodeBase64Url(buffer) {
+  return base64Url.escape(buffer.toString("base64"));
+}
+
+function decodeBase64Url(value) {
+  if (typeof value !== "string" || value.trim().length === 0 || !BASE64_URL_PATTERN.test(value)) {
+    throw new Error("signature must be base64url (A-Z, a-z, 0-9, -, _)");
+  }
+  return Buffer.from(base64Url.unescape(value), "base64");
+}
+
+export function generateSigningKeyPair() {
+  return generateKeyPairSync("ed25519", {
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" }
+  });
+}
+
+export function canonicalJSONString(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new TypeError("receipt must be a non-null object");
+  }
+  const clone = structuredClone(receipt);
+  delete clone.signature;
+  const canonical = canonicalize(clone);
+  if (typeof canonical !== "string") {
+    throw new TypeError("failed to canonicalize receipt to RFC8785-JCS string");
+  }
+  return canonical;
+}
+
+export function canonicalBytes(receipt) {
+  return Buffer.from(canonicalJSONString(receipt), "utf8");
+}
+
+export function signReceipt(receipt, privateKeyPem, keyId) {
+  const payload = canonicalBytes(receipt);
+  const sigBuffer = cryptoSign(null, payload, privateKeyPem);
+  const sig = encodeBase64Url(sigBuffer);
+  return {
+    ...receipt,
+    signature: {
+      alg: ATP_SIGNING_ALGORITHM,
+      version: ATP_SIGNING_VERSION,
+      kid: keyId,
+      sig,
+      canonicalization: "RFC8785-JCS"
+    }
+  };
+}
+
+export function verifyReceiptSignature(receipt, publicKeyPem, options = {}) {
+  const sig = receipt?.signature;
+  if (!sig || typeof sig !== "object") {
+    return { ok: false, reason: "receipt_invalid_signature", detail: "signature object missing" };
+  }
+  if (typeof publicKeyPem !== "string" || publicKeyPem.trim().length === 0) {
+    return { ok: false, reason: "receipt_invalid_signature", detail: "public key missing or empty" };
+  }
+  if (sig.alg !== ATP_SIGNING_ALGORITHM) {
+    return { ok: false, reason: "receipt_invalid_signature", detail: `unsupported algorithm '${sig.alg}'` };
+  }
+  if (sig.version !== undefined && sig.version !== ATP_SIGNING_VERSION) {
+    return { ok: false, reason: "receipt_invalid_signature", detail: `unsupported signature version '${sig.version}'` };
+  }
+  if (sig.canonicalization !== "RFC8785-JCS") {
+    return {
+      ok: false,
+      reason: "receipt_invalid_signature",
+      detail: "canonicalization must be RFC8785-JCS"
+    };
+  }
+  if (typeof sig.kid !== "string" || sig.kid.trim().length === 0) {
+    return { ok: false, reason: "receipt_invalid_signature", detail: "kid field missing or empty" };
+  }
+  if (typeof options?.expectedKid === "string" && options.expectedKid.trim().length > 0 && sig.kid !== options.expectedKid) {
+    return {
+      ok: false,
+      reason: "receipt_invalid_signature",
+      detail: `kid mismatch expected '${options.expectedKid}' but got '${sig.kid}'`
+    };
+  }
+  if (typeof sig.sig !== "string" || !sig.sig.trim()) {
+    return { ok: false, reason: "receipt_invalid_signature", detail: "sig field missing or empty" };
+  }
+  try {
+    const payload = canonicalBytes(receipt);
+    const sigBuffer = decodeBase64Url(sig.sig);
+    if (sigBuffer.length !== 64) {
+      return { ok: false, reason: "receipt_invalid_signature", detail: "Ed25519 signature must be exactly 64 bytes" };
+    }
+    const valid = cryptoVerify(null, payload, publicKeyPem, sigBuffer);
+    if (!valid) return { ok: false, reason: "receipt_signature_verification_failed", detail: "signature mismatch" };
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: "receipt_signature_verification_failed", detail: String(error?.message ?? error) };
+  }
+}
+
+export function exportPublicKeyAsJwk(publicKeyPem, kid) {
+  const keyObj = createPublicKey(publicKeyPem);
+  const raw = keyObj.export({ format: "jwk" });
+  return {
+    kty: "OKP",
+    crv: "Ed25519",
+    kid,
+    use: "sig",
+    x: raw.x
+  };
+}
+
+export function buildJwks(entries) {
+  return { keys: entries };
+}
+
+export function receiptFingerprint(receipt) {
+  const payload = canonicalBytes(receipt);
+  return createHash("sha256").update(payload).digest("hex");
+}