aae-protocol 0.0.1 → 0.9.0

package/README.md

@@ -1,8 +1,51 @@
-# aae-protocol (name reservation)
+# @aae/protocol (TypeScript)
 
-Placeholder reserving the `aae-protocol` name for **Accountable Agentic
-Execution** — a protocol for governing what AI agents do.
+TypeScript / JavaScript SDK for the [Accountable Agentic Execution (AAE)](https://github.com/r3moteBee/aae) protocol.
 
-This 0.0.1 release contains no implementation. The real SDK lands at 0.7.0+.
+## Install
 
-Project: https://github.com/r3moteBee/aae
+```bash
+npm install @aae/protocol
+# or
+pnpm add @aae/protocol
+```
+
+## What this provides
+
+- Zod schemas for every AAE protocol type (parse-and-validate at runtime, infer TS types at compile time)
+- Hash chain helpers (RFC 8785 canonicalization via `json-canonicalize`, SHA-256 chain construction, verification)
+- Capability token mint/verify (JWT via `jose`)
+- Reference adapters for policy, audit sink, and approval delivery (TODO)
+
+## Quick example
+
+```ts
+import { ProposalSchema, type Proposal, BlastRadius } from "@aae/protocol";
+import { verifyChain } from "@aae/protocol/hashchain";
+import { ulid } from "ulid";
+
+const proposal: Proposal = ProposalSchema.parse({
+  aae_version: "0.1",
+  proposal_id: ulid(),
+  agent_id: "ops-agent-v3",
+  tenant_id: "default",
+  intent: "restart_test_service",
+  context: { rationale: "QA asked" },
+  steps: [
+    {
+      tool: "ssh_exec",
+      args: { host: "test-01", command: "systemctl restart test" },
+      blast_radius: BlastRadius.SINGLE_SERVICE,
+    },
+  ],
+  submitted_at: new Date().toISOString(),
+});
+```
+
+## Status
+
+v0.1 — early development. APIs may shift before v1.0.
+
+## License
+
+MIT OR Apache-2.0

package/dist/hashchain.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Hash chain helpers: RFC 8785 canonicalization, chain construction, verification.
+ *
+ * Verification semantics match the Python and Rust SDKs; conformance fixtures
+ * in reference-tests/conformance.json validate cross-SDK byte-for-byte equality.
+ */
+import type { AuditEvent } from "./models.js";
+export declare const HASH_PREFIX: "sha256:";
+export declare class ChainError extends Error {
+    readonly eventId?: string | undefined;
+    name: string;
+    constructor(message: string, eventId?: string | undefined);
+}
+/**
+ * Produce the hashing view of an event (normative; mirrors the Python SDK's
+ * `_event_to_canonical_dict`, the single point of truth):
+ *   - `this_event_hash` is excluded.
+ *   - `signature` is excluded when null/undefined (None-valued optional
+ *     fields don't pollute the hash).
+ *   - `prev_event_hash` is INCLUDED even when null (genesis marker is
+ *     structurally significant).
+ */
+export declare function eventForHashing(event: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Compute this_event_hash from an event-shaped object that does NOT include
+ * this_event_hash itself, plus the previous chain tip.
+ */
+export declare function computeEventHash(eventWithoutHash: Record<string, unknown>, prevEventHash: string | null): string;
+/**
+ * Append an event to the chain by computing and assigning this_event_hash.
+ * Returns a new event object; does not mutate the input.
+ */
+export declare function appendEvent(event: AuditEvent, prevEventHash: string | null): AuditEvent;
+/**
+ * Value-based chain production: seal a raw event object onto the chain.
+ * Sets prev_event_hash and this_event_hash on a copy and returns it.
+ * Producers using this path control their serialization byte-for-byte
+ * (C-3: no typed round-trip can alter timestamp precision).
+ */
+export declare function appendEventValue(event: Record<string, unknown>, prevEventHash: string | null): Record<string, unknown>;
+/**
+ * Value-based chain verification for chains produced by other
+ * implementations (C-3-safe: hashes the received JSON as-is). Returns the
+ * tip hash; throws ChainError on any break.
+ */
+export declare function verifyChainValues(events: Record<string, unknown>[]): string;
+/**
+ * Verify a single event's this_event_hash matches its recomputed hash.
+ */
+export declare function verifyEvent(event: AuditEvent): boolean;
+/**
+ * Verify a sequence of events forms a valid hash chain. Returns the tip hash
+ * on success; throws ChainError on the first detected problem.
+ */
+export declare function verifyChain(events: AuditEvent[]): string;
+//# sourceMappingURL=hashchain.d.ts.map

package/dist/hashchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashchain.d.ts","sourceRoot":"","sources":["../src/hashchain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,WAAW,EAAG,SAAkB,CAAC;AAE9C,qBAAa,UAAW,SAAQ,KAAK;aAInB,OAAO,CAAC,EAAE,MAAM;IAHxB,IAAI,SAAgB;gBAE5B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,YAAA;CAIjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,aAAa,EAAE,MAAM,GAAG,IAAI,GAC1B,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,MAAM,GAAG,IAAI,GAC1B,UAAU,CAIZ;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAyB3E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAMtD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAoCxD"}

package/dist/hashchain.js

@@ -0,0 +1,134 @@
+/**
+ * Hash chain helpers: RFC 8785 canonicalization, chain construction, verification.
+ *
+ * Verification semantics match the Python and Rust SDKs; conformance fixtures
+ * in reference-tests/conformance.json validate cross-SDK byte-for-byte equality.
+ */
+import { createHash } from "node:crypto";
+import { canonicalize } from "json-canonicalize";
+export const HASH_PREFIX = "sha256:";
+export class ChainError extends Error {
+    eventId;
+    name = "ChainError";
+    constructor(message, eventId) {
+        super(message);
+        this.eventId = eventId;
+    }
+}
+/**
+ * Produce the hashing view of an event (normative; mirrors the Python SDK's
+ * `_event_to_canonical_dict`, the single point of truth):
+ *   - `this_event_hash` is excluded.
+ *   - `signature` is excluded when null/undefined (None-valued optional
+ *     fields don't pollute the hash).
+ *   - `prev_event_hash` is INCLUDED even when null (genesis marker is
+ *     structurally significant).
+ */
+export function eventForHashing(event) {
+    const { this_event_hash: _omit, signature, ...view } = event;
+    void _omit;
+    if (signature !== null && signature !== undefined) {
+        return { ...view, signature };
+    }
+    return view;
+}
+/**
+ * Compute this_event_hash from an event-shaped object that does NOT include
+ * this_event_hash itself, plus the previous chain tip.
+ */
+export function computeEventHash(eventWithoutHash, prevEventHash) {
+    const canonical = canonicalize(eventWithoutHash);
+    const hasher = createHash("sha256");
+    hasher.update(canonical, "utf8");
+    hasher.update(prevEventHash ?? "", "utf8");
+    return `${HASH_PREFIX}${hasher.digest("hex")}`;
+}
+/**
+ * Append an event to the chain by computing and assigning this_event_hash.
+ * Returns a new event object; does not mutate the input.
+ */
+export function appendEvent(event, prevEventHash) {
+    const withPrev = { ...event, prev_event_hash: prevEventHash };
+    const newHash = computeEventHash(eventForHashing(withPrev), prevEventHash);
+    return { ...withPrev, this_event_hash: newHash };
+}
+/**
+ * Value-based chain production: seal a raw event object onto the chain.
+ * Sets prev_event_hash and this_event_hash on a copy and returns it.
+ * Producers using this path control their serialization byte-for-byte
+ * (C-3: no typed round-trip can alter timestamp precision).
+ */
+export function appendEventValue(event, prevEventHash) {
+    const sealed = {
+        ...event,
+        prev_event_hash: prevEventHash,
+    };
+    const hash = computeEventHash(eventForHashing(sealed), prevEventHash);
+    sealed.this_event_hash = hash;
+    return sealed;
+}
+/**
+ * Value-based chain verification for chains produced by other
+ * implementations (C-3-safe: hashes the received JSON as-is). Returns the
+ * tip hash; throws ChainError on any break.
+ */
+export function verifyChainValues(events) {
+    if (events.length === 0)
+        throw new ChainError("empty chain");
+    const first = events[0];
+    if (first === undefined || first.prev_event_hash !== null) {
+        throw new ChainError("genesis event must have prev_event_hash=null");
+    }
+    let prev = null;
+    for (const ev of events) {
+        if ((ev.prev_event_hash ?? null) !== prev) {
+            throw new ChainError(`prev_event_hash mismatch at ${String(ev.event_id)}`, String(ev.event_id));
+        }
+        const expected = computeEventHash(eventForHashing(ev), prev);
+        if (expected !== ev.this_event_hash) {
+            throw new ChainError(`this_event_hash mismatch at ${String(ev.event_id)}`, String(ev.event_id));
+        }
+        prev = ev.this_event_hash;
+    }
+    if (prev === null)
+        throw new ChainError("empty chain");
+    return prev;
+}
+/**
+ * Verify a single event's this_event_hash matches its recomputed hash.
+ */
+export function verifyEvent(event) {
+    const expected = computeEventHash(eventForHashing(event), event.prev_event_hash);
+    return expected === event.this_event_hash;
+}
+/**
+ * Verify a sequence of events forms a valid hash chain. Returns the tip hash
+ * on success; throws ChainError on the first detected problem.
+ */
+export function verifyChain(events) {
+    if (events.length === 0) {
+        throw new ChainError("empty chain");
+    }
+    const first = events[0];
+    if (first === undefined) {
+        throw new ChainError("empty chain");
+    }
+    if (first.prev_event_hash !== null) {
+        throw new ChainError("genesis event must have prev_event_hash=null", first.event_id);
+    }
+    let prev = null;
+    for (const ev of events) {
+        if (ev.prev_event_hash !== prev) {
+            throw new ChainError(`prev_event_hash mismatch: expected ${prev}, got ${ev.prev_event_hash}`, ev.event_id);
+        }
+        if (!verifyEvent(ev)) {
+            throw new ChainError("this_event_hash does not match recomputed", ev.event_id);
+        }
+        prev = ev.this_event_hash;
+    }
+    if (prev === null) {
+        throw new ChainError("empty chain after iteration");
+    }
+    return prev;
+}
+//# sourceMappingURL=hashchain.js.map

package/dist/hashchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashchain.js","sourceRoot":"","sources":["../src/hashchain.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @aae/protocol — Accountable Agentic Execution protocol SDK for TypeScript.
+ *
+ * See https://github.com/r3moteBee/aae for the protocol specification.
+ */
+export * from "./models.js";
+export * as hashchain from "./hashchain.js";
+export * as signing from "./signing.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aae/protocol — Accountable Agentic Execution protocol SDK for TypeScript.
+ *
+ * See https://github.com/r3moteBee/aae for the protocol specification.
+ */
+export * from "./models.js";
+export * as hashchain from "./hashchain.js";
+export * as signing from "./signing.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC"}