@keelcodes/policy 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+export type Address = `0x${string}`;
+export type Hex = `0x${string}`;
+/**
+ * Schema version, mixed into the commitment hash so a future DSL change can
+ * never silently produce a hash collision with an older, semantically
+ * different policy.
+ */
+export declare const POLICY_VERSION = 1;
+/**
+ * Per-token ERC-20 ceiling, as authored. Keyed by the token contract, which is
+ * also the call target: enforcing the cap requires reading the amount out of
+ * the token's own `transfer` / `approve` call data.
+ */
+export interface TokenLimitInput {
+    /** ERC-20 contract the cap applies to. */
+    token: Address;
+    /** Token amount ceiling for a single call; `0`/omitted means unlimited. */
+    maxPerTx?: bigint;
+    /** Token amount ceiling accumulated within a day; `0`/omitted means unlimited. */
+    maxDaily?: bigint;
+}
+/** A rule scoped to one target contract, as authored. */
+export interface PolicyRuleInput {
+    /** Contract the agent may call. */
+    target: Address;
+    /** Allowed 4-byte selectors; omitted or empty means "any method on target". */
+    selectors?: readonly Hex[];
+    /** Native-value ceiling for a single call; `0`/omitted means unlimited. */
+    maxPerTx?: bigint;
+    /** Native-value ceiling accumulated within a day; `0`/omitted means unlimited. */
+    maxDaily?: bigint;
+    /** Maximum number of calls; `0`/omitted means unlimited. */
+    maxCalls?: number;
+    /** ERC-20 ceilings, one per token contract; each token may appear once. */
+    tokenLimits?: readonly TokenLimitInput[];
+}
+/** A policy as authored. */
+export interface PolicyInput {
+    /** Unix seconds before which the policy is not valid; `0`/omitted = immediately. */
+    validAfter?: bigint;
+    /** Unix seconds after which the policy expires; `0`/omitted = never. */
+    validUntil?: bigint;
+    rules: readonly PolicyRuleInput[];
+}
+/** A per-token ERC-20 ceiling with every field populated (post-normalisation). */
+export interface TokenLimit {
+    readonly token: Address;
+    readonly maxPerTx: bigint;
+    readonly maxDaily: bigint;
+}
+/** A rule with every field populated (post-normalisation). */
+export interface PolicyRule {
+    readonly target: Address;
+    readonly selectors: readonly Hex[];
+    readonly maxPerTx: bigint;
+    readonly maxDaily: bigint;
+    readonly maxCalls: number;
+    readonly tokenLimits: readonly TokenLimit[];
+}
+/** A normalised, hash-stable policy. */
+export interface Policy {
+    readonly version: number;
+    readonly validAfter: bigint;
+    readonly validUntil: bigint;
+    readonly rules: readonly PolicyRule[];
+}
+/** A call an agent wants to make. */
+export interface Call {
+    readonly target: Address;
+    /** Native value sent with the call. */
+    readonly value: bigint;
+    /** Call data; `0x` for a plain value transfer. */
+    readonly data: Hex;
+    /** 4-byte selector (first 4 bytes of `data`), or `0x` when there is no data. */
+    readonly selector: Hex;
+}
+/**
+ * Accrued usage for one rule, kept by the caller (off-chain) or by the on-chain
+ * hook's accounting. `dailySpent` / `tokenSpent` must be reset by the caller
+ * when the day window rolls over.
+ */
+export interface RuleUsage {
+    readonly calls: number;
+    /** Native value spent in the current day window. */
+    readonly dailySpent: bigint;
+    /** Per-token amount spent in the current day window, keyed by lower-cased token address. */
+    readonly tokenSpent?: Readonly<Record<string, bigint>>;
+}
+/** Evaluation context: the current time plus per-rule usage, aligned to `policy.rules` by index. */
+export interface PolicyState {
+    /** Current unix time in seconds. */
+    readonly now: bigint;
+    /** Usage aligned to `policy.rules`; absent entries are treated as zero. */
+    readonly usage: readonly RuleUsage[];
+}
+/** Why a call was denied. */
+export type DenyReason = 'not-yet-valid' | 'expired' | 'no-matching-rule' | 'value-per-tx-exceeded' | 'daily-limit-exceeded' | 'call-count-exceeded' | 'token-per-tx-exceeded' | 'token-daily-limit-exceeded' | 'token-transfer-from-blocked' | 'token-amount-unparsable';
+export interface Decision {
+    readonly allowed: boolean;
+    /** Set when `allowed` is false. */
+    readonly reason?: DenyReason;
+    /**
+     * Index of the rule that matched, when one did. On an allowed decision this
+     * is the rule whose usage the caller must advance.
+     */
+    readonly ruleIndex?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,21 @@
+// ============================================================================
+// Keel policy model — account-agnostic authorization for agent accounts.
+//
+// A policy declares what an agent may do with an account: which targets it may
+// call, which methods on them, and the value / frequency ceilings. The model
+// deliberately contains **no account-specific encodings**: it is the same
+// `Policy` whether it is later compiled to an ERC-7579 hook module, a 7710
+// enforcer, or evaluated off-chain for a pre-check. That is what "account
+// agnostic" means here (see docs/KEEL_PLAN.md §4.4 ②).
+//
+// Fields are authored optionally ({@link PolicyInput}) and normalised to a
+// fully-populated {@link Policy} before hashing, so semantically identical
+// policies always produce the same commitment hash.
+// ============================================================================
+/**
+ * Schema version, mixed into the commitment hash so a future DSL change can
+ * never silently produce a hash collision with an older, semantically
+ * different policy.
+ */
+export const POLICY_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yEAAyE;AACzE,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,uDAAuD;AACvD,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,oDAAoD;AACpD,+EAA+E;AAK/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@keelcodes/policy",
+  "version": "0.1.0",
+  "description": "Account-agnostic agent authorization policy: declarative DSL, canonical commitment hash and off-chain pre-check/simulation.",
+  "license": "Apache-2.0",
+  "homepage": "https://keel.codes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keelcodes/keel.git",
+    "directory": "packages/policy"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "erc-4337",
+    "erc-7579",
+    "policy",
+    "session-keys",
+    "agent",
+    "account-abstraction"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}