@keelcodes/policy 0.1.0

package/dist/evaluate.d.ts

@@ -0,0 +1,32 @@
+import type { Address, Call, Decision, Hex, Policy, PolicyState, RuleUsage } from './types.js';
+/** Usage of a rule that has never been exercised. */
+export declare const ZERO_USAGE: RuleUsage;
+/** Builds a {@link Call}, deriving the selector from `data`. */
+export declare function toCall(input: {
+    target: Address;
+    value?: bigint;
+    data?: Hex;
+}): Call;
+/**
+ * Evaluates a single call against the policy. Validity is checked first, then
+ * a matching rule is looked up in declared order (first match wins), then that
+ * rule's per-tx / daily / count and per-token ceilings are applied.
+ */
+export declare function evaluateCall(policy: Policy, state: PolicyState, call: Call): Decision;
+export interface SimulationResult {
+    readonly allowed: boolean;
+    /** The last decision evaluated: the first denial, or the final allow. */
+    readonly decision: Decision;
+    /** Usage after applying every allowed call; input state is never mutated. */
+    readonly usage: readonly RuleUsage[];
+}
+/**
+ * Dry-runs `calls` in order, accumulating usage so that later calls see the
+ * effect of earlier ones (e.g. a batch that would breach a daily cap only
+ * together). Stops and returns at the first denial.
+ *
+ * `state.usage` is aligned to `policy.rules` by index; callers reset
+ * `dailySpent` / `tokenSpent` themselves when the day window rolls over.
+ */
+export declare function simulateCalls(policy: Policy, state: PolicyState, calls: readonly Call[]): SimulationResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,OAAO,EACP,IAAI,EACJ,QAAQ,EAER,GAAG,EACH,MAAM,EAEN,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAC;AAYpB,qDAAqD;AACrD,eAAO,MAAM,UAAU,EAAE,SAAuD,CAAC;AAEjF,gEAAgE;AAChE,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,IAAI,CAKnF;AAmCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,GAAG,QAAQ,CAsBrF;AAsBD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,gBAAgB,CAa1G"}

package/dist/evaluate.js

@@ -0,0 +1,125 @@
+import { isAddress } from 'viem';
+import { ERC20_SELECTOR, readErc20Amount } from './erc20.js';
+import { PolicyError } from './errors.js';
+// ============================================================================
+// Off-chain pre-check and simulation.
+//
+// These are pure functions over (policy, state, call). They mirror the rules
+// the on-chain hook will enforce, so a caller can dry-run a batch before
+// signing: reject it locally with a precise reason instead of paying for a
+// bundler round-trip that ends in a validation failure. The on-chain module
+// remains the source of truth; this layer never widens what is allowed.
+// ============================================================================
+/** Usage of a rule that has never been exercised. */
+export const ZERO_USAGE = Object.freeze({ calls: 0, dailySpent: 0n });
+/** Builds a {@link Call}, deriving the selector from `data`. */
+export function toCall(input) {
+    if (!isAddress(input.target))
+        throw new PolicyError(`call.target: invalid address "${input.target}"`);
+    const data = (input.data ?? '0x');
+    const selector = (data.length >= 10 ? data.slice(0, 10) : '0x').toLowerCase();
+    return { target: input.target.toLowerCase(), value: input.value ?? 0n, data, selector };
+}
+function matches(rule, call) {
+    if (rule.target !== call.target.toLowerCase())
+        return false;
+    if (rule.selectors.length === 0)
+        return true;
+    return rule.selectors.includes(call.selector.toLowerCase());
+}
+/**
+ * Applies a rule's per-token ceiling, if one is configured for this call's
+ * target. Returns the reason to deny, or `undefined` to allow.
+ *
+ * `transferFrom` is refused outright while a limit is configured: its amount is
+ * readable but bounding a pull from an arbitrary address is ambiguous enough
+ * that the conservative choice (matching the existing infraX module) is to
+ * reject it. Calls to a limited token that are not standard ERC-20 methods are
+ * left to the rule's selector whitelist.
+ */
+function tokenDenial(rule, usage, call) {
+    const limit = rule.tokenLimits.find((entry) => entry.token === call.target.toLowerCase());
+    if (!limit)
+        return undefined;
+    const read = readErc20Amount(call);
+    if (read.kind === 'malformed')
+        return 'token-amount-unparsable';
+    if (read.kind === 'not-erc20')
+        return undefined;
+    if (read.selector === ERC20_SELECTOR.transferFrom)
+        return 'token-transfer-from-blocked';
+    if (limit.maxPerTx > 0n && read.value > limit.maxPerTx)
+        return 'token-per-tx-exceeded';
+    const spent = usage.tokenSpent?.[limit.token] ?? 0n;
+    if (limit.maxDaily > 0n && spent + read.value > limit.maxDaily)
+        return 'token-daily-limit-exceeded';
+    return undefined;
+}
+/**
+ * Evaluates a single call against the policy. Validity is checked first, then
+ * a matching rule is looked up in declared order (first match wins), then that
+ * rule's per-tx / daily / count and per-token ceilings are applied.
+ */
+export function evaluateCall(policy, state, call) {
+    if (policy.validAfter > 0n && state.now < policy.validAfter)
+        return { allowed: false, reason: 'not-yet-valid' };
+    if (policy.validUntil > 0n && state.now > policy.validUntil)
+        return { allowed: false, reason: 'expired' };
+    const ruleIndex = policy.rules.findIndex((rule) => matches(rule, call));
+    if (ruleIndex === -1)
+        return { allowed: false, reason: 'no-matching-rule' };
+    const rule = policy.rules[ruleIndex];
+    const usage = state.usage[ruleIndex] ?? ZERO_USAGE;
+    if (rule.maxPerTx > 0n && call.value > rule.maxPerTx) {
+        return { allowed: false, reason: 'value-per-tx-exceeded', ruleIndex };
+    }
+    const tokenReason = tokenDenial(rule, usage, call);
+    if (tokenReason)
+        return { allowed: false, reason: tokenReason, ruleIndex };
+    if (rule.maxDaily > 0n && usage.dailySpent + call.value > rule.maxDaily) {
+        return { allowed: false, reason: 'daily-limit-exceeded', ruleIndex };
+    }
+    if (rule.maxCalls > 0 && usage.calls + 1 > rule.maxCalls) {
+        return { allowed: false, reason: 'call-count-exceeded', ruleIndex };
+    }
+    return { allowed: true, ruleIndex };
+}
+/** Advances a rule's usage by one allowed call, including any token amount. */
+function advanceUsage(rule, usage, call) {
+    const next = {
+        calls: usage.calls + 1,
+        dailySpent: usage.dailySpent + call.value,
+    };
+    const limit = rule.tokenLimits.find((entry) => entry.token === call.target.toLowerCase());
+    const read = limit ? readErc20Amount(call) : undefined;
+    if (limit && read?.kind === 'amount' && read.selector !== ERC20_SELECTOR.transferFrom) {
+        const tokenSpent = { ...(usage.tokenSpent ?? {}) };
+        tokenSpent[limit.token] = (tokenSpent[limit.token] ?? 0n) + read.value;
+        next.tokenSpent = tokenSpent;
+    }
+    else if (usage.tokenSpent) {
+        next.tokenSpent = usage.tokenSpent;
+    }
+    return next;
+}
+/**
+ * Dry-runs `calls` in order, accumulating usage so that later calls see the
+ * effect of earlier ones (e.g. a batch that would breach a daily cap only
+ * together). Stops and returns at the first denial.
+ *
+ * `state.usage` is aligned to `policy.rules` by index; callers reset
+ * `dailySpent` / `tokenSpent` themselves when the day window rolls over.
+ */
+export function simulateCalls(policy, state, calls) {
+    const usage = policy.rules.map((_, index) => state.usage[index] ?? ZERO_USAGE);
+    let decision = { allowed: true };
+    for (const call of calls) {
+        decision = evaluateCall(policy, { now: state.now, usage }, call);
+        if (!decision.allowed)
+            return { allowed: false, decision, usage };
+        const index = decision.ruleIndex;
+        usage[index] = advanceUsage(policy.rules[index], usage[index] ?? ZERO_USAGE, call);
+    }
+    return { allowed: true, decision, usage };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/evaluate.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @keelcodes/policy
+ *
+ * Account-agnostic authorization policy for agent accounts: a declarative DSL,
+ * a canonical commitment hash and an off-chain pre-check / simulation layer.
+ *
+ * The package is carrier-neutral. Today it is used off-chain to dry-run calls
+ * before signing; the same normalised policy and commitment are what the
+ * on-chain ERC-7579 hook module (Keel's carrier for on-chain enforcement)
+ * recomputes and enforces, so the two layers cannot disagree about what a
+ * policy means.
+ *
+ * @packageDocumentation
+ */
+export { INSTALL_ABI_PARAMETERS, POLICY_ABI_PARAMETERS, encodeInstallData, encodePolicy, policyCommitment, } from './commitment.js';
+export { CAPABILITY_VERSION, EnvelopeStatus, ZERO_ASSET, ZERO_CURSOR, advanceCursor, applyStatus, approvalsSatisfied, assertConservation, attenuate, canDraw, canSetStatus, capabilityCommitment, contestExpired, cursorCommitment, defaultResolution, effectiveStatus, encodeCapability, encodeCursor, envelopeId, isTerminal, normalizeCapability, openContest, remaining, withinCap, } from './bounded.js';
+export { ERC20_SELECTOR, readErc20Amount } from './erc20.js';
+export { ZERO_USAGE, evaluateCall, simulateCalls, toCall } from './evaluate.js';
+export { EnvelopeError, PolicyError, SessionError } from './errors.js';
+export { normalizePolicy } from './normalize.js';
+export { InMemorySessionStore, createSessionId, isSessionActive, issueSession, listSessions, revokeSession, rotateSession, sessionStatus, } from './session.js';
+export type { Erc20Read } from './erc20.js';
+export type { ApprovalInput, Capability, CapabilityInput, ContestWindow, Cursor, DrawContext, DrawDecision, DrawDenyReason, Envelope, EnvelopeRef, TrustTier, } from './bounded.js';
+export type { SimulationResult } from './evaluate.js';
+export type { IssueSessionInput, Rotation, RotateSessionInput, Session, SessionStatus, SessionStore, SessionView, } from './session.js';
+export type { Address, Call, Decision, DenyReason, Hex, Policy, PolicyInput, PolicyRule, PolicyRuleInput, PolicyState, RuleUsage, TokenLimit, TokenLimitInput, } from './types.js';
+export { POLICY_VERSION } from './types.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;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,UAAU,EACV,eAAe,EACf,aAAa,EACb,MAAM,EACN,WAAW,EACX,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,WAAW,EACX,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,YAAY,EACZ,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,GAAG,EACH,MAAM,EACN,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,SAAS,EACT,UAAU,EACV,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @keelcodes/policy
+ *
+ * Account-agnostic authorization policy for agent accounts: a declarative DSL,
+ * a canonical commitment hash and an off-chain pre-check / simulation layer.
+ *
+ * The package is carrier-neutral. Today it is used off-chain to dry-run calls
+ * before signing; the same normalised policy and commitment are what the
+ * on-chain ERC-7579 hook module (Keel's carrier for on-chain enforcement)
+ * recomputes and enforces, so the two layers cannot disagree about what a
+ * policy means.
+ *
+ * @packageDocumentation
+ */
+export { INSTALL_ABI_PARAMETERS, POLICY_ABI_PARAMETERS, encodeInstallData, encodePolicy, policyCommitment, } from './commitment.js';
+export { CAPABILITY_VERSION, EnvelopeStatus, ZERO_ASSET, ZERO_CURSOR, advanceCursor, applyStatus, approvalsSatisfied, assertConservation, attenuate, canDraw, canSetStatus, capabilityCommitment, contestExpired, cursorCommitment, defaultResolution, effectiveStatus, encodeCapability, encodeCursor, envelopeId, isTerminal, normalizeCapability, openContest, remaining, withinCap, } from './bounded.js';
+export { ERC20_SELECTOR, readErc20Amount } from './erc20.js';
+export { ZERO_USAGE, evaluateCall, simulateCalls, toCall } from './evaluate.js';
+export { EnvelopeError, PolicyError, SessionError } from './errors.js';
+export { normalizePolicy } from './normalize.js';
+export { InMemorySessionStore, createSessionId, isSessionActive, issueSession, listSessions, revokeSession, rotateSession, sessionStatus, } from './session.js';
+export { POLICY_VERSION } from './types.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;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,cAAc,CAAC;AAyCtB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/normalize.d.ts

@@ -0,0 +1,10 @@
+import { type Policy, type PolicyInput } from './types.js';
+/**
+ * Validates an authored policy and returns its normalised form.
+ *
+ * Throws {@link PolicyError} rather than returning a partial policy, so a
+ * malformed policy surfaces at definition time instead of as a silent on-chain
+ * mismatch later.
+ */
+export declare function normalizePolicy(input: PolicyInput): Policy;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AA6EpB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAkB1D"}

package/dist/normalize.js

@@ -0,0 +1,92 @@
+import { getAddress, isAddress } from 'viem';
+import { PolicyError } from './errors.js';
+import { POLICY_VERSION, } from './types.js';
+// ============================================================================
+// Authored DSL → normalised Policy.
+//
+// Normalisation fills every optional field with its zero/default so that the
+// commitment hash depends on meaning, not on which fields a caller happened to
+// spell out: `{ maxPerTx: 0n }` and `{}` hash identically. Addresses are
+// lower-cased for the same reason (the ABI encoding already ignores case, but
+// keeping it deterministic makes policies comparable with `===` too).
+// ============================================================================
+const SELECTOR_PATTERN = /^0x[0-9a-fA-F]{8}$/;
+function normalizeAddress(value, field) {
+    if (!isAddress(value))
+        throw new PolicyError(`${field}: invalid address "${value}"`);
+    return getAddress(value).toLowerCase();
+}
+function normalizeSelector(value, field) {
+    if (!SELECTOR_PATTERN.test(value)) {
+        throw new PolicyError(`${field}: selector must be 4 bytes (0x + 8 hex), got "${value}"`);
+    }
+    return value.toLowerCase();
+}
+function normalizeNonNegative(value, field) {
+    if (value < 0n)
+        throw new PolicyError(`${field}: must be >= 0, got ${value}`);
+    return value;
+}
+function normalizeTokenLimit(input, field) {
+    const token = normalizeAddress(input.token, `${field}.token`);
+    return Object.freeze({
+        token,
+        maxPerTx: normalizeNonNegative(input.maxPerTx ?? 0n, `${field}.maxPerTx`),
+        maxDaily: normalizeNonNegative(input.maxDaily ?? 0n, `${field}.maxDaily`),
+    });
+}
+function normalizeRule(input, index) {
+    const at = `rules[${index}]`;
+    const target = normalizeAddress(input.target, `${at}.target`);
+    const selectors = (input.selectors ?? []).map((selector, i) => normalizeSelector(selector, `${at}.selectors[${i}]`));
+    const maxCalls = input.maxCalls ?? 0;
+    if (!Number.isInteger(maxCalls) || maxCalls < 0) {
+        throw new PolicyError(`${at}.maxCalls: must be a non-negative integer, got ${maxCalls}`);
+    }
+    // A token cap can only be enforced on calls made directly to the token, so a
+    // limit for any other address would be dead config — reject it loudly.
+    const tokenLimits = (input.tokenLimits ?? []).map((limit, i) => {
+        const normalized = normalizeTokenLimit(limit, `${at}.tokenLimits[${i}]`);
+        if (normalized.token !== target) {
+            throw new PolicyError(`${at}.tokenLimits[${i}]: token ${normalized.token} must equal the rule target ${target}`);
+        }
+        return normalized;
+    });
+    if (new Set(tokenLimits.map((limit) => limit.token)).size !== tokenLimits.length) {
+        throw new PolicyError(`${at}.tokenLimits: duplicate limit for the same token`);
+    }
+    return Object.freeze({
+        target,
+        selectors: Object.freeze(selectors),
+        maxPerTx: normalizeNonNegative(input.maxPerTx ?? 0n, `${at}.maxPerTx`),
+        maxDaily: normalizeNonNegative(input.maxDaily ?? 0n, `${at}.maxDaily`),
+        maxCalls,
+        tokenLimits: Object.freeze(tokenLimits),
+    });
+}
+/**
+ * Validates an authored policy and returns its normalised form.
+ *
+ * Throws {@link PolicyError} rather than returning a partial policy, so a
+ * malformed policy surfaces at definition time instead of as a silent on-chain
+ * mismatch later.
+ */
+export function normalizePolicy(input) {
+    const rules = input.rules ?? [];
+    if (rules.length === 0)
+        throw new PolicyError('policy must declare at least one rule');
+    const validAfter = normalizeNonNegative(input.validAfter ?? 0n, 'validAfter');
+    const validUntil = normalizeNonNegative(input.validUntil ?? 0n, 'validUntil');
+    // validUntil = 0 is the sentinel for "never expires", so only a non-zero
+    // value has to be strictly after validAfter.
+    if (validUntil !== 0n && validUntil <= validAfter) {
+        throw new PolicyError(`validUntil (${validUntil}) must be greater than validAfter (${validAfter})`);
+    }
+    return Object.freeze({
+        version: POLICY_VERSION,
+        validAfter,
+        validUntil,
+        rules: Object.freeze(rules.map(normalizeRule)),
+    });
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,cAAc,GASf,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,oCAAoC;AACpC,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,8EAA8E;AAC9E,sEAAsE;AACtE,+EAA+E;AAE/E,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAE9C,SAAS,gBAAgB,CAAC,KAAa,EAAE,KAAa;IACpD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,sBAAsB,KAAK,GAAG,CAAC,CAAC;IACrF,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,WAAW,EAAa,CAAC;AACpD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa,EAAE,KAAa;IACrD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,iDAAiD,KAAK,GAAG,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,EAAS,CAAC;AACpC,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,KAAa;IACxD,IAAI,KAAK,GAAG,EAAE;QAAE,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,uBAAuB,KAAK,EAAE,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAsB,EAAE,KAAa;IAChE,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK;QACL,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,KAAK,WAAW,CAAC;QACzE,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,KAAK,WAAW,CAAC;KAC1E,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,KAAsB,EAAE,KAAa;IAC1D,MAAM,EAAE,GAAG,SAAS,KAAK,GAAG,CAAC;IAC7B,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAC5D,iBAAiB,CAAC,QAAQ,EAAE,GAAG,EAAE,cAAc,CAAC,GAAG,CAAC,CACrD,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,WAAW,CAAC,GAAG,EAAE,kDAAkD,QAAQ,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,6EAA6E;IAC7E,uEAAuE;IACvE,MAAM,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC7D,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACzE,IAAI,UAAU,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAChC,MAAM,IAAI,WAAW,CACnB,GAAG,EAAE,gBAAgB,CAAC,YAAY,UAAU,CAAC,KAAK,+BAA+B,MAAM,EAAE,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IACH,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,MAAM,EAAE,CAAC;QACjF,MAAM,IAAI,WAAW,CAAC,GAAG,EAAE,kDAAkD,CAAC,CAAC;IACjF,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM;QACN,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;QACnC,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,EAAE,WAAW,CAAC;QACtE,QAAQ,EAAE,oBAAoB,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,GAAG,EAAE,WAAW,CAAC;QACtE,QAAQ;QACR,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC;KACxC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,uCAAuC,CAAC,CAAC;IAEvF,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;IAC9E,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;IAC9E,yEAAyE;IACzE,6CAA6C;IAC7C,IAAI,UAAU,KAAK,EAAE,IAAI,UAAU,IAAI,UAAU,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC,eAAe,UAAU,sCAAsC,UAAU,GAAG,CAAC,CAAC;IACtG,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,cAAc;QACvB,UAAU;QACV,UAAU;QACV,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;KAC/C,CAAC,CAAC;AACL,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,98 @@
+import type { Address, Hex, Policy, PolicyInput } from './types.js';
+/** Lifecycle state of a session at a given time, derived from its record. */
+export type SessionStatus = 'pending' | 'active' | 'expired' | 'revoked';
+/** One authorization grant on an account. */
+export interface Session {
+    /** Unique bytes32 identifier (random unless supplied at issue time). */
+    readonly id: Hex;
+    /** Smart account the grant applies to (lower-cased). */
+    readonly account: Address;
+    /** The normalised policy this session grants. */
+    readonly policy: Policy;
+    /** `keccak256(encodePolicy(policy))` — the value the on-chain carrier stores. */
+    readonly commitment: Hex;
+    /** Unix seconds the session record was created. */
+    readonly createdAt: bigint;
+    /** Unix seconds the session was revoked; absent while it has not been. */
+    readonly revokedAt?: bigint;
+    /** Id of the session this one replaced, when created by a rotation. */
+    readonly rotatedFrom?: Hex;
+    /** Id of the session that replaced this one, when revoked by a rotation. */
+    readonly rotatedTo?: Hex;
+}
+/** A session together with its status at a given time. */
+export interface SessionView extends Session {
+    readonly status: SessionStatus;
+}
+/**
+ * Persistence port for sessions. Async by design so a database-backed store can
+ * implement it directly; {@link InMemorySessionStore} is the reference.
+ */
+export interface SessionStore {
+    /** Inserts or replaces the record for `session.id`. */
+    save(session: Session): Promise<void>;
+    /** The record for `id`, or `undefined` when unknown. */
+    get(id: Hex): Promise<Session | undefined>;
+    /** Every session of `account`, in store order. */
+    listByAccount(account: Address): Promise<readonly Session[]>;
+}
+/** Minimal in-memory {@link SessionStore}; not durable, intended for tests and single-process use. */
+export declare class InMemorySessionStore implements SessionStore {
+    #private;
+    save(session: Session): Promise<void>;
+    get(id: Hex): Promise<Session | undefined>;
+    listByAccount(account: Address): Promise<readonly Session[]>;
+}
+export interface IssueSessionInput {
+    readonly account: Address;
+    readonly policy: PolicyInput;
+    /** Current unix time in seconds. */
+    readonly now: bigint;
+    /** Explicit bytes32 id; a random one is generated when omitted. */
+    readonly id?: Hex;
+}
+export interface RotateSessionInput {
+    /** Policy for the successor session; usually the same as the previous one. */
+    readonly policy: PolicyInput;
+    /** Current unix time in seconds. */
+    readonly now: bigint;
+    /** Explicit bytes32 id for the successor; a random one is generated when omitted. */
+    readonly id?: Hex;
+}
+/** The pair of records a rotation produces. */
+export interface Rotation {
+    /** The predecessor, now revoked and linked forward. */
+    readonly previous: Session;
+    /** The successor, linked back to the predecessor. */
+    readonly next: Session;
+}
+/** A fresh random bytes32 session id. */
+export declare function createSessionId(): Hex;
+/**
+ * Creates an active session for `input.account`.
+ *
+ * The policy is normalised (so the stored commitment is canonical) and the id
+ * must be unused. Throws {@link SessionError} on a duplicate id or a bad
+ * account, and {@link PolicyError} on a malformed policy.
+ */
+export declare function issueSession(store: SessionStore, input: IssueSessionInput): Promise<Session>;
+/**
+ * Revokes a session. The record is kept (append-only) with `revokedAt` set, so
+ * a revocation is auditable and idempotent failures are explicit. Revoking an
+ * already-revoked or unknown session throws {@link SessionError}.
+ */
+export declare function revokeSession(store: SessionStore, id: Hex, now: bigint): Promise<Session>;
+/**
+ * Rotates a session: issues a successor and revokes the predecessor in one
+ * step, cross-linking the two. This is the off-chain half of the migration
+ * "uninstall old module + invalidate nonce + install new" (docs/KEEL_PLAN.md
+ * §7.5); the successor inherits the predecessor's account.
+ */
+export declare function rotateSession(store: SessionStore, id: Hex, input: RotateSessionInput): Promise<Rotation>;
+/** Derives a session's status from its record at time `now`. */
+export declare function sessionStatus(session: Session, now: bigint): SessionStatus;
+/** Whether the session is usable at time `now` (its status is `active`). */
+export declare function isSessionActive(session: Session, now: bigint): boolean;
+/** Lists an account's sessions with their status at `now`, in store order. */
+export declare function listSessions(store: SessionStore, account: Address, now: bigint): Promise<readonly SessionView[]>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAuBpE,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzE,6CAA6C;AAC7C,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACjB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC1C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,wDAAwD;IACxD,GAAG,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC3C,kDAAkD;IAClD,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;CAC9D;AAED,sGAAsG;AACtG,qBAAa,oBAAqB,YAAW,YAAY;;IAGjD,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,GAAG,CAAC,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAI1C,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC;CAInE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAQD,yCAAyC;AACzC,wBAAgB,eAAe,IAAI,GAAG,CAIrC;AAcD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBlG;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ/F;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,GAAG,EACP,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,QAAQ,CAAC,CA0BnB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAK1E;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,8EAA8E;AAC9E,wBAAsB,YAAY,CAChC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAGjC"}

package/dist/session.js

@@ -0,0 +1,128 @@
+import { bytesToHex, getAddress, isAddress } from 'viem';
+import { policyCommitment } from './commitment.js';
+import { SessionError } from './errors.js';
+import { normalizePolicy } from './normalize.js';
+/** Minimal in-memory {@link SessionStore}; not durable, intended for tests and single-process use. */
+export class InMemorySessionStore {
+    #sessions = new Map();
+    async save(session) {
+        this.#sessions.set(session.id, session);
+    }
+    async get(id) {
+        return this.#sessions.get(id);
+    }
+    async listByAccount(account) {
+        const wanted = account.toLowerCase();
+        return [...this.#sessions.values()].filter((session) => session.account === wanted);
+    }
+}
+const SESSION_ID_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+/** A fresh random bytes32 session id. */
+export function createSessionId() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+}
+function normalizeSessionId(value) {
+    if (!SESSION_ID_PATTERN.test(value)) {
+        throw new SessionError(`id: must be 32 bytes (0x + 64 hex), got "${value}"`);
+    }
+    return value.toLowerCase();
+}
+function normalizeAccount(value) {
+    if (!isAddress(value))
+        throw new SessionError(`account: invalid address "${value}"`);
+    return getAddress(value).toLowerCase();
+}
+/**
+ * Creates an active session for `input.account`.
+ *
+ * The policy is normalised (so the stored commitment is canonical) and the id
+ * must be unused. Throws {@link SessionError} on a duplicate id or a bad
+ * account, and {@link PolicyError} on a malformed policy.
+ */
+export async function issueSession(store, input) {
+    const id = input.id === undefined ? createSessionId() : normalizeSessionId(input.id);
+    if (await store.get(id))
+        throw new SessionError(`session ${id} already exists`);
+    const account = normalizeAccount(input.account);
+    const policy = normalizePolicy(input.policy);
+    const session = Object.freeze({
+        id,
+        account,
+        policy,
+        commitment: policyCommitment(policy),
+        createdAt: input.now,
+    });
+    await store.save(session);
+    return session;
+}
+/**
+ * Revokes a session. The record is kept (append-only) with `revokedAt` set, so
+ * a revocation is auditable and idempotent failures are explicit. Revoking an
+ * already-revoked or unknown session throws {@link SessionError}.
+ */
+export async function revokeSession(store, id, now) {
+    const session = await store.get(id);
+    if (!session)
+        throw new SessionError(`session ${id} not found`);
+    if (session.revokedAt !== undefined)
+        throw new SessionError(`session ${id} is already revoked`);
+    const revoked = Object.freeze({ ...session, revokedAt: now });
+    await store.save(revoked);
+    return revoked;
+}
+/**
+ * Rotates a session: issues a successor and revokes the predecessor in one
+ * step, cross-linking the two. This is the off-chain half of the migration
+ * "uninstall old module + invalidate nonce + install new" (docs/KEEL_PLAN.md
+ * §7.5); the successor inherits the predecessor's account.
+ */
+export async function rotateSession(store, id, input) {
+    const previous = await store.get(id);
+    if (!previous)
+        throw new SessionError(`session ${id} not found`);
+    if (previous.revokedAt !== undefined)
+        throw new SessionError(`session ${id} is already revoked`);
+    const nextId = input.id === undefined ? createSessionId() : normalizeSessionId(input.id);
+    if (nextId === id)
+        throw new SessionError('a rotated session must have a new id');
+    if (await store.get(nextId))
+        throw new SessionError(`session ${nextId} already exists`);
+    const policy = normalizePolicy(input.policy);
+    const next = Object.freeze({
+        id: nextId,
+        account: previous.account,
+        policy,
+        commitment: policyCommitment(policy),
+        createdAt: input.now,
+        rotatedFrom: id,
+    });
+    const revoked = Object.freeze({ ...previous, revokedAt: input.now, rotatedTo: nextId });
+    // Persist the successor first: a crash between the two writes then leaves a
+    // usable successor without a back-link, rather than a revoked original with
+    // no replacement.
+    await store.save(next);
+    await store.save(revoked);
+    return { previous: revoked, next };
+}
+/** Derives a session's status from its record at time `now`. */
+export function sessionStatus(session, now) {
+    if (session.revokedAt !== undefined)
+        return 'revoked';
+    if (now < session.policy.validAfter)
+        return 'pending';
+    if (session.policy.validUntil !== 0n && now > session.policy.validUntil)
+        return 'expired';
+    return 'active';
+}
+/** Whether the session is usable at time `now` (its status is `active`). */
+export function isSessionActive(session, now) {
+    return sessionStatus(session, now) === 'active';
+}
+/** Lists an account's sessions with their status at `now`, in store order. */
+export async function listSessions(store, account, now) {
+    const sessions = await store.listByAccount(normalizeAccount(account));
+    return sessions.map((session) => Object.freeze({ ...session, status: sessionStatus(session, now) }));
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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