# iamgodofall/capkit architecture

> Architecture diagram of the GitHub repository iamgodofall/capkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamgodofall/capkit
- Repository: https://github.com/iamgodofall/capkit

## Overview

CapKit is a local-first TypeScript library for issuing scoped, expiring HMAC-signed capabilities, checking YAML policies, verifying tokens, and producing signed audit receipts. The demo shows an agent authorization workflow; it simulates the protected action rather than integrating with an external platform. Source excerpts support the demo’s direct API calls and the policy loader’s file/YAML reads; no persistent audit store or external service is shown.

Main entry points: [`demo/agent-example.ts`](https://github.com/iamgodofall/capkit/blob/main/demo/agent-example.ts) (Demo workflow), [`src/policy.ts`](https://github.com/iamgodofall/capkit/blob/main/src/policy.ts) (Policy load and check), [`src/index.ts`](https://github.com/iamgodofall/capkit/blob/main/src/index.ts) (Library exports), [`src/capability.ts`](https://github.com/iamgodofall/capkit/blob/main/src/capability.ts) (Capability issue and verify)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api_entry["Library exports<br/>[index.ts]"]
end

subgraph group_authorization["Authorization"]
  node_capability["Capability issue and verify<br/>[capability.ts]"]
  node_policy["Policy load and check<br/>[policy.ts]"]
end

subgraph group_audit["Audit"]
  node_audit["Signed audit receipt<br/>[capability.ts]"]
end

node_agent(("AI agent"))
node_demo["Demo workflow<br/>[agent-example.ts]"]
node_policy_file["Demo policy<br/>[policy.yaml]"]
node_fs["Node filesystem"]
node_yaml["js-yaml parser"]
node_crypto["Node crypto"]

node_agent -->|"requests authorization"| node_demo
node_demo -->|"invokes API"| node_api_entry
node_api_entry -->|"exports"| node_capability
node_api_entry -->|"exports"| node_policy
node_demo -->|"loads and checks"| node_policy
node_policy -->|"reads file"| node_fs
node_policy -->|"parses YAML"| node_yaml
node_policy -->|"reads policy"| node_policy_file
node_demo -->|"issues and verifies"| node_capability
node_capability -->|"signs and verifies"| node_crypto
node_demo -->|"requests receipt"| node_audit
node_audit -->|"signs receipt"| node_crypto

click node_demo "https://github.com/iamgodofall/capkit/blob/main/demo/agent-example.ts"
click node_api_entry "https://github.com/iamgodofall/capkit/blob/main/src/index.ts"
click node_capability "https://github.com/iamgodofall/capkit/blob/main/src/capability.ts"
click node_policy "https://github.com/iamgodofall/capkit/blob/main/src/policy.ts"
click node_policy_file "https://github.com/iamgodofall/capkit/blob/main/demo/policy.yaml"
click node_audit "https://github.com/iamgodofall/capkit/blob/main/src/capability.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_entry toneBlue
class node_capability,node_policy toneAmber
class node_audit toneMint
class node_agent,node_fs,node_yaml,node_crypto toneIndigo
class node_demo,node_policy_file toneTeal
```

## Components

### Public API

- [Library exports](https://github.com/iamgodofall/capkit/blob/main/src/index.ts): `src/index.ts`

### Authorization

- [Capability issue and verify](https://github.com/iamgodofall/capkit/blob/main/src/capability.ts): `src/capability.ts`
- [Policy load and check](https://github.com/iamgodofall/capkit/blob/main/src/policy.ts): `src/policy.ts`

### Audit

- [Signed audit receipt](https://github.com/iamgodofall/capkit/blob/main/src/capability.ts): `src/capability.ts`

### Other components

- **AI agent**
- [Demo workflow](https://github.com/iamgodofall/capkit/blob/main/demo/agent-example.ts): `demo/agent-example.ts`
- [Demo policy](https://github.com/iamgodofall/capkit/blob/main/demo/policy.yaml): `demo/policy.yaml`
- **Node filesystem**
- **js-yaml parser**
- **Node crypto**

## Connections

- AI agent → Demo workflow: requests authorization
- Demo workflow → Library exports: invokes API
- Library exports → Capability issue and verify: exports
- Library exports → Policy load and check: exports
- Demo workflow → Policy load and check: loads and checks
- Policy load and check → Node filesystem: reads file
- Policy load and check → js-yaml parser: parses YAML
- Policy load and check → Demo policy: reads policy
- Demo workflow → Capability issue and verify: issues and verifies
- Capability issue and verify → Node crypto: signs and verifies
- Demo workflow → Signed audit receipt: requests receipt
- Signed audit receipt → Node crypto: signs receipt