create_trustatom

Generate cryptographic receipts for AI decisions to enable compliance auditing and verification. Signs actions with Ed25519 encryption and maps to regulatory frameworks like HIPAA and SOX.

Instructions

Sign an AI decision and return a cryptographic receipt. Every AI decision that matters should have a receipt. Signing takes <3ms. Receipt is Ed25519-signed + SHA-256-hashed.

Input Schema

TableJSON Schema

Name	Required	Description
`action`	Yes	The action being decided (e.g., APPROVE_LOAN, TRIAGE_PATIENT, DEPLOY, TRADE_SIGNAL)
`actor`	Yes	The AI agent or system making the decision
`decision`	Yes	The decision outcome
`context`	No	Additional context for the decision (risk factors, confidence scores, etc.)
`compliance_tags`	No	Compliance framework tags (e.g., HIPAA, SOX, NIST:PR, SOC2:CC6.1)
`risk_score`	No	Risk score 0.0-1.0 (auto-computed if not provided)

Implementation Reference

src/server.ts:161-171 (handler)

The MCP tool request handler for 'create_trustatom' in src/server.ts, which delegates the logic to the 'createTrustAtom' function.

case "create_trustatom": {
  const input: TrustAtomInput = {
    action: String(args?.action ?? "UNKNOWN"),
    actor: String(args?.actor ?? "unknown-agent"),
    decision: (args?.decision as "ALLOW" | "DENY") ?? "DENY",
    context: (args?.context as Record<string, unknown>) ?? {},
    compliance_tags: args?.compliance_tags as string[] | undefined,
    risk_score: args?.risk_score as number | undefined,
  };

  const receipt = createTrustAtom(input, keyPair);

src/sign.ts:124-171 (handler)

The core implementation logic for generating a TrustAtom cryptographic receipt in src/sign.ts.

export function createTrustAtom(
  input: TrustAtomInput,
  keyPair: KeyPair,
): TrustAtomReceipt {
  const start = performance.now();
  const ts = Date.now();

  // Canonical JSON (sorted keys, no whitespace) — matches Python implementation
  const canonical = JSON.stringify(input, Object.keys(input).sort());
  const evidenceHash = createHash("sha256").update(canonical).digest("hex");

  // Ed25519 sign the evidence hash
  const sig = nacl.sign.detached(
    naclUtil.decodeUTF8(evidenceHash),
    keyPair.secretKey,
  );
  const sigB64 = naclUtil.encodeBase64(sig);
  const pubB64 = naclUtil.encodeBase64(keyPair.publicKey);

  // Compute risk + compliance from action
  const risk = input.risk_score ?? RISK_MAP[input.action] ?? 0.5;
  const tags =
    input.compliance_tags ?? COMPLIANCE_MAP[input.action] ?? ["NIST:PR"];

  const signingTime = performance.now() - start;

  return {
    id: `ta_${evidenceHash.slice(0, 12)}`,
    action: input.action,
    actor: input.actor,
    decision: input.decision,
    context: input.context,
    evidence_hash: evidenceHash,
    signature_b64: sigB64,
    public_key_b64: pubB64,
    timestamp_iso: new Date(ts).toISOString(),
    timestamp_ms: ts,
    dct: {
      env: "SANDBOX",
      compliance_tags: tags,
      risk_score: risk,
      ttl_ms: 0,
    },
    tenant_id: input.tenant_id ?? "demo-tenant",
    resource_id: input.resource_id ?? "default",
    signing_time_ms: Math.round(signingTime * 100) / 100,
  };
}

src/server.ts:31-72 (schema)

The MCP tool definition (schema) for 'create_trustatom' in src/server.ts.

{
  name: "create_trustatom",
  description:
    "Sign an AI decision and return a cryptographic receipt. " +
    "Every AI decision that matters should have a receipt. " +
    "Signing takes <3ms. Receipt is Ed25519-signed + SHA-256-hashed.",
  inputSchema: {
    type: "object" as const,
    properties: {
      action: {
        type: "string",
        description:
          "The action being decided (e.g., APPROVE_LOAN, TRIAGE_PATIENT, DEPLOY, TRADE_SIGNAL)",
      },
      actor: {
        type: "string",
        description: "The AI agent or system making the decision",
      },
      decision: {
        type: "string",
        enum: ["ALLOW", "DENY"],
        description: "The decision outcome",
      },
      context: {
        type: "object",
        description:
          "Additional context for the decision (risk factors, confidence scores, etc.)",
      },
      compliance_tags: {
        type: "array",
        items: { type: "string" },
        description:
          "Compliance framework tags (e.g., HIPAA, SOX, NIST:PR, SOC2:CC6.1)",
      },
      risk_score: {
        type: "number",
        description: "Risk score 0.0-1.0 (auto-computed if not provided)",
      },
    },
    required: ["action", "actor", "decision"],
  },
},

TrustAtom MCP Server