From 3cb11d743307664470b2d4ecdb3cda85722ce03e Mon Sep 17 00:00:00 2001 From: Matt Venables Date: Sat, 14 Feb 2026 18:20:46 -0500 Subject: [PATCH] docs: add per-package AGENTS.md and refactor root instructions Rewrite root AGENTS.md with dependency graph, build pipeline details, dual validation schema pattern, and code style conventions. Add package-level AGENTS.md files with internal dependencies, subpath exports, key types, and source layout for each of the 8 packages. Remove .cursor/rules symlink to AGENTS.md. --- .cursor/rules/project-overview.mdc | 1 - AGENTS.md | 157 ++++++++++++++++------------ packages/ack-id/AGENTS.md | 32 ++++++ packages/ack-id/CLAUDE.md | 1 + packages/ack-pay/AGENTS.md | 45 ++++++++ packages/ack-pay/CLAUDE.md | 1 + packages/agentcommercekit/AGENTS.md | 25 +++++ packages/agentcommercekit/CLAUDE.md | 1 + packages/caip/AGENTS.md | 28 +++++ packages/caip/CLAUDE.md | 1 + packages/did/AGENTS.md | 34 ++++++ packages/did/CLAUDE.md | 1 + packages/jwt/AGENTS.md | 22 ++++ packages/jwt/CLAUDE.md | 1 + packages/keys/AGENTS.md | 37 +++++++ packages/keys/CLAUDE.md | 1 + packages/vc/AGENTS.md | 38 +++++++ packages/vc/CLAUDE.md | 1 + tools/eslint-config/base.js | 3 + 19 files changed, 362 insertions(+), 68 deletions(-) delete mode 120000 .cursor/rules/project-overview.mdc create mode 100644 packages/ack-id/AGENTS.md create mode 100644 packages/ack-id/CLAUDE.md create mode 100644 packages/ack-pay/AGENTS.md create mode 100644 packages/ack-pay/CLAUDE.md create mode 100644 packages/agentcommercekit/AGENTS.md create mode 100644 packages/agentcommercekit/CLAUDE.md create mode 100644 packages/caip/AGENTS.md create mode 100644 packages/caip/CLAUDE.md create mode 100644 packages/did/AGENTS.md create mode 100644 packages/did/CLAUDE.md create mode 100644 packages/jwt/AGENTS.md create mode 100644 packages/jwt/CLAUDE.md create mode 100644 packages/keys/AGENTS.md create mode 100644 packages/keys/CLAUDE.md create mode 100644 packages/vc/AGENTS.md create mode 100644 packages/vc/CLAUDE.md diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc deleted file mode 120000 index b7e6491..0000000 --- a/.cursor/rules/project-overview.mdc +++ /dev/null @@ -1 +0,0 @@ -../../AGENTS.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 846e897..1c6874c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,97 +1,120 @@ # Agent Commerce Kit (ACK) -## Project Overview +TypeScript monorepo providing verifiable AI identity (ACK-ID) and automated payment processing (ACK-Pay) protocols built on W3C DIDs and Verifiable Credentials. -**Agent Commerce Kit (ACK)** is an open-source TypeScript framework enabling AI agents to participate in commerce through two core protocols: +## Commands -1. **ACK-ID**: Verifiable AI identities with compliance controls using W3C DIDs and Verifiable Credentials -2. **ACK-Pay**: Secure, automated payment processing with auditable receipt verification +```bash +pnpm run setup # Install deps + build (safe to re-run) +pnpm run build # Build all packages +pnpm run check # Full CI: format + types + lint + test +pnpm run test # All tests +pnpm run fix # lint:fix + format +pnpm --filter ./packages/[name] test # Single package test +pnpm --filter ./packages/[name] build # Single package build +``` -The project is structured as a **pnpm monorepo** with Turbo build orchestration, requiring Node.js 22+ and pnpm 10+. +## Package Dependency Graph -## Essential Commands +``` +agentcommercekit (umbrella re-export) +├── ack-id → did, jwt, keys, vc +├── ack-pay → did, jwt, keys, vc +├── vc → did, jwt, keys +├── did → caip, keys +├── jwt → keys +├── caip (leaf) +└── keys (leaf) +``` -### Setup & Development +Changes to a leaf package require rebuilding everything above it. Turbo handles this via `"dependsOn": ["^build"]`. Demos and examples import from built `dist/` output, not source. -```bash -pnpm run setup # Initialize repository (install deps, build packages) -pnpm run build # Build all packages -pnpm run dev:examples # Run all example services -pnpm run dev:docs # Run documentation site locally -``` +## Architecture -### Quality Assurance +### Directory Layout -```bash -pnpm run check # Run comprehensive checks (format, types, lint, test) -pnpm run test # Run all tests -pnpm run lint # Run ESLint -pnpm run check:types # TypeScript type checking -pnpm run format # Format code with Prettier -``` +- **`packages/`** - Core NPM-published packages (8 packages, see dependency graph above) +- **`demos/`** - Interactive protocol demonstrations (each runnable independently) +- **`examples/`** - Standalone services: credential issuer, verifier, local DID host +- **`tools/`** - Internal workspace packages (not published): + - `api-utils` - Hono API helpers, middleware, JWT validation + - `cli-tools` - Demo CLI utilities + - `eslint-config` - Shared ESLint flat config + - `typescript-config` - Shared tsconfig bases +- **`docs/`** - Mintlify documentation site (`pnpm dev:docs`) -### Demos +### Build Pipeline -```bash -pnpm demo:identity # ACK-ID protocol demonstration -pnpm demo:identity-a2a # ACK-ID with Google A2A protocol -pnpm demo:payments # ACK-Pay protocol demonstration -pnpm demo:e2e # End-to-end demo (ACK-ID + ACK-Pay) -pnpm demo:skyfire-kya # Skyfire KYA token demonstration +Each package uses **tsdown** (not tsc) for building: + +- Config: `tsdown.config.ts` per package with multiple entry points +- Output: `dist/` with ESM (.js) + TypeScript declarations (.d.ts) +- TypeScript target: ES2022, module: ESNext, bundler resolution +- All packages are ESM-only (`"type": "module"`) + +### Dual Validation Schema Pattern + +Most packages export validation schemas through **three files** with **four export paths**: + +``` +src/schemas/ +├── valibot.ts → ./schemas/valibot +└── zod/ + ├── v3.ts → ./schemas/zod/v3 AND ./schemas/zod (alias) + └── v4.ts → ./schemas/zod/v4 ``` -### Testing +Valibot is the primary validation library (a runtime dependency in most packages, optional peer in `caip` and `jwt`). Zod is an optional peer dependency everywhere. -- Run individual package tests: `pnpm --filter ./packages/[package-name] test` -- All tests use **Vitest** framework with assertive testing patterns (`it('requires...')`, `it('throws...')`, `it('returns...')`) -- Test configuration: individual `vitest.config.ts` files per package +When adding new types, you must: -## Architecture +1. Add the schema to all three files (`valibot.ts`, `zod/v3.ts`, `zod/v4.ts`) +2. Add entry points to `package.json` exports +3. Add entry points to `tsdown.config.ts` entry array + +Exception: `keys` package has no schema exports (exports curve-specific files and encoding instead). -### Core Packages (`/packages/` - Published to NPM) +### Dependency Management -- **`agentcommercekit/`** - Main SDK package (exports everything) -- **`ack-id/`** - Identity protocol implementation -- **`ack-pay/`** - Payment protocol implementation -- **`caip/`** - CAIP (Chain Agnostic Improvement Proposal) utilities for CAIP-2, CAIP-10, and CAIP-19 -- **`did/`** - Decentralized Identifier utilities -- **`jwt/`** - JWT creation/verification utilities -- **`keys/`** - Cryptographic key management (Ed25519, secp256k1, secp256r1) -- **`vc/`** - Verifiable Credentials utilities +- Exact versions enforced by `.npmrc` (`save-exact=true`) +- Shared versions via pnpm catalog in `pnpm-workspace.yaml` +- Workspace dependencies use `workspace:*` +- Catalog dependencies use `catalog:` +- Peer dependencies use semver ranges -### Demonstrations (`/demos/`) +## Testing -Interactive demos showcasing protocol functionality - each can be run independently. +Vitest with individual `vitest.config.ts` per package. -### Example Services (`/examples/`) +- Test files co-located with source as `*.test.ts` +- Assertive test names: `it("creates...")`, `it("throws...")`, `it("requires...")`, `it("returns...")` +- Partial mocks: `vi.mock()` with `vi.importActual()` to preserve real implementations -Standalone service implementations including credential issuer, verifier, and local DID host. +## Code Style -### Build System +### Formatting (Prettier) -- **Turbo**: Orchestrates builds across packages with dependency graph -- **tsdown**: TypeScript compiler/bundler -- **Output**: `dist/` directories with ESM and TypeScript definitions -- **Dependency Management**: Exact versions for dependencies (enforced via `.npmrc`), ranges for peer dependencies +- No semicolons +- Double quotes +- Trailing commas +- 2-space indentation -### Key Technical Patterns +### Imports -- **ESM-only**: All packages use `"type": "module"` -- **Multi-curve Cryptography**: Ed25519, secp256k1, secp256r1 support -- **Dual Validation**: Both Valibot (primary) and Zod (peer dependency) support -- **Standards Compliance**: W3C DIDs and Verifiable Credentials -- **Modular Design**: Protocols can be used independently +- Sorting handled by `@ianvs/prettier-plugin-sort-imports` (via Prettier, not ESLint) +- Enforced `import type { ... }` via ESLint `consistent-type-imports` rule -### Development Workflow +### Linting -1. Changes to core packages require rebuilding: `pnpm run build` -2. Use `pnpm --filter ./packages/[name]` to work on specific packages -3. Run comprehensive checks before commits: `pnpm run check` -4. Demos and examples depend on built packages +- Unused vars: warning with `^_` prefix ignore pattern +- CSpell spell checking integrated into ESLint (config: `cspell.config.yaml`) -### Key Dependencies +## Demos -- **@noble/curves**: Elliptic curve cryptography -- **multiformats**: Multiformat encoding/decoding -- **valibot**: Runtime validation (primary choice) -- **zod**: Alternative validation (peer dependency) +```bash +pnpm demo:identity # ACK-ID protocol demo +pnpm demo:identity-a2a # ACK-ID with Google A2A protocol +pnpm demo:payments # ACK-Pay protocol demo +pnpm demo:e2e # End-to-end (ACK-ID + ACK-Pay) +pnpm demo:skyfire-kya # Skyfire KYA token demo +``` diff --git a/packages/ack-id/AGENTS.md b/packages/ack-id/AGENTS.md new file mode 100644 index 0000000..19406de --- /dev/null +++ b/packages/ack-id/AGENTS.md @@ -0,0 +1,32 @@ +# @agentcommercekit/ack-id + +ACK Identity protocol. Controller credentials for proving ownership chains, plus optional A2A (Agent-to-Agent) authentication support. + +## Internal Dependencies + +`did`, `jwt`, `keys`, `vc` + +## Subpath Exports + +| Export | Description | +| ----------------- | ---------------------------------------------------- | +| `.` | Controller credentials and claim verifier | +| `./a2a` | A2A message signing, verification, service endpoints | +| `./schemas/*` | Standard schema exports | +| `./a2a/schemas/*` | A2A-specific schema exports | + +The `/a2a` subpath is separate because it depends on the optional `@a2a-js/sdk` peer dependency. + +## Source Layout + +- `src/controller-credential.ts` - Create controller credentials +- `src/controller-claim-verifier.ts` - Verify controller claims via DID resolution +- `src/a2a/` - A2A protocol integration: + - `sign-message.ts` - JWT-based message signatures + - `verify.ts` - Challenge-response verification + - `service-endpoints.ts` - Service endpoint helpers + - Separate schema exports for A2A types + +## Key Pattern + +Controller credentials prove an ownership chain: a subject DID is controlled by a controller DID. Verification resolves both DIDs and checks the relationship. diff --git a/packages/ack-id/CLAUDE.md b/packages/ack-id/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/ack-id/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/ack-pay/AGENTS.md b/packages/ack-pay/AGENTS.md new file mode 100644 index 0000000..f2e6039 --- /dev/null +++ b/packages/ack-pay/AGENTS.md @@ -0,0 +1,45 @@ +# @agentcommercekit/ack-pay + +ACK Payment protocol. Payment requests (as signed JWTs), payment receipts (as Verifiable Credentials), and verification for both. + +## Internal Dependencies + +`did`, `jwt`, `keys`, `vc` + +## Key Types + +```typescript +type PaymentRequest = { + id: string + description?: string + serviceCallback?: string + expiresAt?: string + paymentOptions: PaymentOption[] +} + +type PaymentOption = { + id: string + amount: number | string + decimals: number + currency: string + recipient: string + network?: string + paymentService?: string | DidUri + receiptService?: string | DidUri +} +``` + +## Source Layout + +- `src/payment-request.ts` - Payment request types +- `src/create-payment-request-token.ts` / `verify-payment-request-token.ts` - JWT-based request tokens +- `src/create-payment-receipt.ts` / `verify-payment-receipt.ts` - VC-based receipts +- `src/receipt-claim-verifier.ts` - ClaimVerifier implementation for payment receipts +- Standard schema exports + +## Key Patterns + +- Payment requests are signed JWTs (designed for HTTP 402 responses) +- A single request can offer multiple payment options (different currencies/networks) +- Payment receipts are W3C Verifiable Credentials that prove payment was made +- Receipt verification uses the vc package's ClaimVerifier strategy diff --git a/packages/ack-pay/CLAUDE.md b/packages/ack-pay/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/ack-pay/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/agentcommercekit/AGENTS.md b/packages/agentcommercekit/AGENTS.md new file mode 100644 index 0000000..b90ac25 --- /dev/null +++ b/packages/agentcommercekit/AGENTS.md @@ -0,0 +1,25 @@ +# agentcommercekit + +Umbrella package that re-exports all ACK sub-packages. Contains no original code. + +## Internal Dependencies + +All 7 other packages. + +## Subpath Exports + +| Export | Description | +| ----------------- | -------------------------------------------------------------------- | +| `.` | Re-exports: ack-id, ack-pay, caip, did, jwt, keys, keys/encoding, vc | +| `./a2a` | Re-exports from ack-id/a2a | +| `./schemas/*` | Aggregated schemas from all sub-packages | +| `./a2a/schemas/*` | A2A-specific schemas | + +## When Editing + +This package only contains re-exports. If you need to add new functionality, add it to the appropriate sub-package, then ensure it's re-exported through the barrel files here: + +- `src/index.ts` - Main re-exports +- `src/schemas/valibot.ts` - Aggregated valibot schemas +- `src/schemas/zod/v3.ts` / `v4.ts` - Aggregated zod schemas +- `src/a2a/` - A2A re-exports diff --git a/packages/agentcommercekit/CLAUDE.md b/packages/agentcommercekit/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/agentcommercekit/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/caip/AGENTS.md b/packages/caip/AGENTS.md new file mode 100644 index 0000000..6ae381e --- /dev/null +++ b/packages/caip/AGENTS.md @@ -0,0 +1,28 @@ +# @agentcommercekit/caip + +Chain Agnostic Improvement Proposal utilities: CAIP-2 (chain IDs), CAIP-10 (account IDs), and CAIP-19 (asset IDs). Zero runtime dependencies. + +## Internal Dependencies + +None (leaf package). + +## Subpath Exports + +Standard schema exports (`./schemas/valibot`, `./schemas/zod/v3`, `./schemas/zod/v4`). + +Note: unlike most packages, `caip` does **not** have the `./schemas/zod` alias. + +## Key Types + +```typescript +type Caip2ChainId = `${string}:${string}` +type Caip10AccountId = string +type Caip19AssetId = string +``` + +Predefined chain IDs available via `caip2ChainIds` (ethereumMainnet, solanaMainnet, etc.). + +## Source Layout + +- `src/caips/` - One file per CAIP standard (caip-2.ts, caip-10.ts, caip-19.ts) +- `src/schemas/` - Dual validation schemas (valibot + zod v3/v4) diff --git a/packages/caip/CLAUDE.md b/packages/caip/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/caip/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/did/AGENTS.md b/packages/did/AGENTS.md new file mode 100644 index 0000000..c8b5a7c --- /dev/null +++ b/packages/did/AGENTS.md @@ -0,0 +1,34 @@ +# @agentcommercekit/did + +Decentralized Identifier utilities. Type-safe DID URIs using template literal types. Method modules for did:key, did:pkh, and did:web. Resolution support for did:jwks via `jwks-did-resolver` (no method module — resolver-level only). + +## Internal Dependencies + +`caip`, `keys` + +## Key Types + +```typescript +type DidUri< + TMethod extends string = string, + TIdentifier extends string = string, +> = `did:${TMethod}:${TIdentifier}` + +type DidKeyUri = DidUri<"key", `z${string}`> +type DidPkhUri = DidUri<"pkh", Caip10AccountId> +type DidWebUri = DidUri<"web", string> +``` + +## Source Layout + +- `src/methods/` - One file per DID method (did-key.ts, did-pkh.ts, did-web.ts) +- `src/did-resolvers/` - Pluggable resolver with `getDidResolver()` factory +- `src/errors.ts` - `DidDocumentNotFoundError`, `InvalidDidUriError`, `UnsupportedDidMethodError` +- Standard schema exports + +## Key Patterns + +- did:key uses varint-encoded multicodec prefixes (0xe7=secp256k1, 0xed=Ed25519, 0x1200=secp256r1) +- did:web converts URLs to DID format (slashes become colons) +- did:pkh integrates with CAIP-10 for blockchain account identifiers +- `resolveDidWithController()` handles hierarchical DID resolution diff --git a/packages/did/CLAUDE.md b/packages/did/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/did/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/jwt/AGENTS.md b/packages/jwt/AGENTS.md new file mode 100644 index 0000000..e18de43 --- /dev/null +++ b/packages/jwt/AGENTS.md @@ -0,0 +1,22 @@ +# @agentcommercekit/jwt + +JWT creation and verification. Maps cryptographic curves to JWT algorithms and provides signing/verification using did-jwt. + +## Internal Dependencies + +`keys` + +## Key Types + +```typescript +type JwtAlgorithm = "ES256" | "ES256K" | "EdDSA" + +// Mapping: secp256r1→ES256, secp256k1→ES256K, Ed25519→EdDSA +``` + +## Source Layout + +- `jwt-algorithm.ts` - Curve-to-algorithm mapping +- `create-jwt.ts` / `verify.ts` - JWT operations +- `signer.ts` - Signer factory wrapping did-jwt signers +- Standard schema exports diff --git a/packages/jwt/CLAUDE.md b/packages/jwt/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/jwt/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/keys/AGENTS.md b/packages/keys/AGENTS.md new file mode 100644 index 0000000..b6e23a5 --- /dev/null +++ b/packages/keys/AGENTS.md @@ -0,0 +1,37 @@ +# @agentcommercekit/keys + +Cryptographic foundation layer. Keypair generation, public key encoding, and curve-specific operations for Ed25519, secp256k1, and secp256r1. No internal ACK dependencies. + +## Internal Dependencies + +None (leaf package). + +## Subpath Exports + +| Export | Description | +| ------------- | ----------------------------------------------------- | +| `.` | Main API: `Keypair`, `KeyCurve`, public key utilities | +| `./encoding` | Base58, base64url, hex, JWK, multibase conversions | +| `./ed25519` | Ed25519 curve operations | +| `./secp256k1` | secp256k1 curve operations | +| `./secp256r1` | secp256r1 curve operations | + +No schema exports (unlike other packages). + +## Key Types + +```typescript +type KeyCurve = "secp256k1" | "secp256r1" | "Ed25519" + +interface Keypair { + publicKey: Uint8Array + privateKey: Uint8Array + curve: KeyCurve +} +``` + +## Source Layout + +- `src/curves/` - One file per curve (ed25519.ts, secp256k1.ts, secp256r1.ts) +- `src/encoding/` - One file per format (base58.ts, base64.ts, hex.ts, jwk.ts, multibase.ts) +- Uses `@noble/curves` for all cryptographic operations diff --git a/packages/keys/CLAUDE.md b/packages/keys/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/keys/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/vc/AGENTS.md b/packages/vc/AGENTS.md new file mode 100644 index 0000000..8e2b937 --- /dev/null +++ b/packages/vc/AGENTS.md @@ -0,0 +1,38 @@ +# @agentcommercekit/vc + +W3C Verifiable Credentials: creation, signing, verification, and revocation. + +## Internal Dependencies + +`did`, `jwt`, `keys` + +## Verification Chain + +``` +verifyParsedCredential() → verifyProof() → check expiry → check revocation → verify trusted issuer → verify claims +``` + +Claims are verified via the `ClaimVerifier` strategy interface: + +```typescript +type ClaimVerifier = { + accepts(type: string[]): boolean + verify( + credentialSubject: CredentialSubject, + resolver: Resolvable, + ): Promise +} +``` + +## Source Layout + +- `src/signing/` - Credential and presentation signing +- `src/verification/` - Proof verification, expiration, revocation checks, claim verification +- `src/revocation/` - W3C Bitstring Status List implementation (`makeRevocable()`, `createStatusListCredential()`) +- Standard schema exports + +## Key Patterns + +- JWT-based proofs (JwtProof2020) +- Revocation via Bitstring Status Lists +- Re-exports `verifyPresentation` from did-jwt-vc diff --git a/packages/vc/CLAUDE.md b/packages/vc/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/packages/vc/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/tools/eslint-config/base.js b/tools/eslint-config/base.js index 351050e..56b985c 100644 --- a/tools/eslint-config/base.js +++ b/tools/eslint-config/base.js @@ -42,6 +42,9 @@ export function config({ root }) { extends: [markdown.configs.recommended], files: ["**/*.md"], language: "markdown/gfm", + rules: { + "markdown/fenced-code-language": "off", + }, }, /**