hedera-curb 0.4.1 → 0.4.3

package/README.md

@@ -1,8 +1,12 @@
 # hedera-curb
 
-**Verifiable spend-control for Hedera AI agents.** Drop-in [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit-js) hooks that govern every payment your agent makes — per-task & rolling-24h budgets, a counterparty allowlist, and single-use human approval — and write every decision immutably to the Hedera Consensus Service.
+**Verifiable spend-control for Hedera AI agents.** Drop-in [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit-js) hooks that govern every payment your agent makes — per-task & rolling-24h **budgets**, a counterparty **allowlist**, and single-use **human approval** — and write every decision immutably to the **Hedera Consensus Service**.
 
-> ProveAI proves the model; Curb proves the spend.
+> Agents can pay now. `hedera-curb` makes sure they can't overspend, pay a stranger, or move money without a record.
+
+**[🌐 Live demo](https://hedera-curb.vercel.app)  ·  [📖 Docs](https://hedera-curb.vercel.app/docs)  ·  [📚 API reference](https://hedera-curb.vercel.app/docs#api)  ·  [💻 GitHub](https://github.com/Madhav-Gupta-28/Curb)**
+
+---
 
 ## Install
 
@@ -15,38 +19,93 @@ npm i hedera-curb @hashgraph/hedera-agent-kit @hiero-ledger/sdk
 ```ts
 import { createCurb } from 'hedera-curb';
 
-const curb = await createCurb({ client, agentAccountId }); // auto-creates audit + HCS-2 policy topics
+const curb = await createCurb({ client, agentAccountId });
 new HederaAIToolkit({ client, configuration: { context: { hooks: curb.hooks } } });
 ```
 
-`createCurb` defaults the store to in-memory, auto-provisions the audit topic and an HCS-2 policy registry (owner-only writes), publishes the starting policy, and returns `{ hooks, config, store, auditTopicId, policyTopicId }`. Override anything:
+That's it — every governed transfer your agent attempts now passes the budget, allowlist, and approval policies **before** it executes, and every decision lands on your Hedera audit topic.
+
+```
+agent tries to pay
+        │
+        ▼
+  ┌─────────────────────────────────────────────┐
+  │  curb.hooks                                  │
+  │   1. allowlist      → not vetted?   ✗ block  │
+  │   2. spend limits   → over a cap?   ✗ block  │
+  │   3. approval tier  → large?        ⏸ human  │
+  └─────────────────────────────────────────────┘
+        │                         │
+   ✓ allowed                 every decision
+        ▼                         ▼
+   payment executes        📜 HCS audit topic
+```
+
+## `createCurb(opts)`
+
+The one-call setup. It auto-provisions the audit topic + an HCS-2 policy registry, defaults the store, publishes your starting policy, and returns ready-to-use hooks.
+
+**What you pass:**
+
+| Option | Type | Default | |
+| --- | --- | --- | --- |
+| `client` | `Client` | **required** | A `@hiero-ledger/sdk` operator client |
+| `agentAccountId` | `string` | **required** | The account the agent pays from |
+| `perTask` | `number` | `10` | Max value of a single payment |
+| `perDay` | `number` | `25` | Rolling-24h cap |
+| `autoUnder` | `number` | `3` | Below this, payments auto-approve |
+| `approveUnder` | `number` | `10` | At/above this, an approval is flagged high-value |
+| `currency` | `'HBAR' \| 'USDC'` | `'HBAR'` | Display currency |
+| `store` | `CurbStore` | in-memory | Bring your own (Redis/Postgres) for production |
+| `auditTopicId` | `string` | auto-created | Reuse an existing HCS topic |
+| `policyTopicId` | `string \| false` | auto-created | Reuse a registry, or `false` to skip versioning |
+
+**What you get back:**
 
 ```ts
-await createCurb({ client, agentAccountId, perDay: 25, store: myRedisStore, auditTopicId, allowlist });
+const { hooks, config, store, auditTopicId, policyTopicId } = curb;
+//      └ drop into the kit   └ resolved caps   └ for /verify   └ HCS-2 registry
 ```
 
-### Or provision from the terminal (no code)
+Override anything inline:
+
+```ts
+await createCurb({ client, agentAccountId, perDay: 25, autoUnder: 3, store: myRedisStore });
+```
+
+## Provision from the terminal (no code)
+
+Creates the topics and prints your `.env` — handy for CI or a one-time setup:
 
 ```bash
 npx hedera-curb init --network testnet
-# ✓ Audit topic: 0.0.x   ✓ Policy topic: 0.0.y (HCS-2, owner-only)
+# ✓ Audit topic:  0.0.x
+# ✓ Policy topic: 0.0.y   (HCS-2, owner-only writes)
 ```
 
-### Advanced: wire it yourself
+## Advanced — wire it yourself
+
+Prefer to assemble the pieces? `buildCurbHooks` returns the ordered policy + audit stack:
 
 ```ts
 import { buildCurbHooks, InMemoryCurbStore } from 'hedera-curb';
+
 const store = new InMemoryCurbStore();
 store.allowAccount(AGENT_ID, PROVIDER_ID);
-const cfg = { agentAccountId: AGENT_ID, auditTopicId: TOPIC_ID, currency: 'HBAR' as const, perTask: 10, perDay: 25, autoUnder: 3, approveUnder: 10 };
-// context: { hooks: buildCurbHooks({ cfg, store }) }
-```
 
-Now every governed transfer passes the budget, allowlist, and approval policies **before** it executes, and every decision lands on your HCS audit topic.
+const cfg = {
+  agentAccountId: AGENT_ID,
+  auditTopicId: TOPIC_ID,
+  currency: 'HBAR' as const,
+  perTask: 10, perDay: 25, autoUnder: 3, approveUnder: 10,
+};
+
+// configuration: { context: { hooks: buildCurbHooks({ cfg, store }) } }
+```
 
 ## Production storage
 
-`InMemoryCurbStore` is for tests / single-instance apps. For production, implement the `CurbStore` interface against Redis, Postgres, etc. Spend is a rolling-24h window split into **committed** (executed) and short-lived **holds** (atomic reservations) so two concurrent payments can't both slip under the cap:
+`InMemoryCurbStore` is perfect for tests and single-instance apps. For production (multi-instance / serverless), implement the `CurbStore` interface against Redis, Postgres, etc. Spend is a rolling-24h window split into **committed** (executed) spend and short-lived **holds** (atomic reservations), so two concurrent payments can't both slip under the cap:
 
 ```ts
 interface CurbStore {
@@ -61,17 +120,22 @@ interface CurbStore {
 }
 ```
 
-## Beyond budgets
+## Exports
 
-The [full project](https://github.com/Madhav-Gupta-28/Curb) is a trust ladder: off-chain hooks (this package) → HCS audit + an HCS-2 **versioned policy registry** → an on-chain **`CurbVault`** contract that enforces caps + allowlist *in Hedera consensus* → non-custodial allowance / scheduled-transaction approvals. Pick how much to trust the server.
+| | |
+| --- | --- |
+| `createCurb(opts)` | One-call setup — topics, store, hooks |
+| `buildCurbHooks(deps)` | The ordered policy + audit stack for `context.hooks` |
+| `SpendLimitPolicy`, `CounterpartyAllowlistPolicy`, `ApprovalTierPolicy`, `CurbAuditHook` | The individual policies, composable on their own |
+| `createAuditTopic`, `createPolicyRegistry`, `publishPolicyVersion`, `readPolicyVersions`, `currentPolicy` | HCS-2 policy versioning |
+| `InMemoryCurbStore`, `extractPayment`, `paymentKey`, `writeRecord` | Store + helpers |
+| `CurbStore`, `CurbConfig`, `CurbRecord`, `PolicyVersion`, … | Types |
 
-## Exports
+**Every export is documented with parameters, types, and examples → [hedera-curb.vercel.app/docs](https://hedera-curb.vercel.app/docs)**
+
+## Beyond budgets — the trust ladder
 
-- `createCurb(opts)` — one-call setup (topics, store, hooks).
-- `buildCurbHooks(deps)` — the ordered policy + audit stack for `context.hooks`.
-- `SpendLimitPolicy`, `CounterpartyAllowlistPolicy`, `ApprovalTierPolicy`, `CurbAuditHook`.
-- `createAuditTopic`, `createPolicyRegistry`, `publishPolicyVersion`, `readPolicyVersions`, `currentPolicy` — HCS-2 policy versioning.
-- `CurbStore` + `InMemoryCurbStore`, `extractPayment`, `paymentKey`, `writeRecord`, and the `CurbConfig` / `CurbRecord` types.
+This package is **L0** of a [larger trust ladder](https://github.com/Madhav-Gupta-28/Curb): off-chain hooks (here) → **L1** an HCS-2 versioned policy registry + a `/verify` that recomputes spend from the on-chain log → **L2** an on-chain **`CurbVault`** contract that enforces the caps + allowlist *in Hedera consensus*, so even a fully-compromised agent key can't overspend. Plus fully non-custodial flows (HIP-336 allowances + HIP-423 scheduled approvals). Pick how much to trust the server.
 
 ## License
 

package/dist/cli.js

@@ -6,9 +6,24 @@ import { createAuditTopic } from './audit.js';
 import { createPolicyRegistry, publishPolicyVersion } from './policy-registry.js';
 import { DEFAULT_CONFIG } from './config.js';
 const flag = (name) => {
-    const i = process.argv.indexOf(`--${name}`);
+    const eq = process.argv.find((a) => a.startsWith(`--${name}=`)); // support --name=value
+    if (eq)
+        return eq.slice(name.length + 3);
+    const i = process.argv.indexOf(`--${name}`); // and --name value
     return i >= 0 ? process.argv[i + 1] : undefined;
 };
+// a numeric flag must parse to a positive, finite number — otherwise we'd publish a garbage policy (NaN caps).
+const num = (name, def) => {
+    const raw = flag(name);
+    if (raw === undefined)
+        return def;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        console.error(`Invalid --${name}: "${raw}" (expected a positive number).`);
+        process.exit(1);
+    }
+    return n;
+};
 function parseKey(s) {
     for (const parse of [PrivateKey.fromStringECDSA, PrivateKey.fromStringED25519, PrivateKey.fromStringDer]) {
         try {
@@ -29,6 +44,9 @@ async function init() {
         console.error('Missing credentials. Pass --account and --key, or set HEDERA_OPERATOR_ID / HEDERA_OPERATOR_KEY.');
         process.exit(1);
     }
+    // validate all input (flags + key) BEFORE any on-chain work, so bad input never creates topics
+    const perTask = num('per-task', DEFAULT_CONFIG.perTask);
+    const perDay = num('per-day', DEFAULT_CONFIG.perDay);
     console.log(`Provisioning Curb on ${network}…`);
     const client = Client.forName(network).setOperator(account, parseKey(key));
     const auditTopicId = await createAuditTopic(client);
@@ -37,8 +55,8 @@ async function init() {
         agentAccountId: agent,
         auditTopicId,
         ...DEFAULT_CONFIG,
-        perTask: Number(flag('per-task') ?? DEFAULT_CONFIG.perTask),
-        perDay: Number(flag('per-day') ?? DEFAULT_CONFIG.perDay),
+        perTask,
+        perDay,
     };
     await publishPolicyVersion(client, config, policyTopicId, 'initial policy').catch(() => { });
     console.log(`\n✓ Audit topic:  ${auditTopicId}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hedera-curb",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Verifiable spend-control policies for Hedera AI agents — drop-in Hedera Agent Kit hooks for budgets, allowlists, human approval, and an immutable HCS audit trail.",
   "license": "MIT",
   "type": "module",