@agenticprimitives/agent-account 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @agenticprimitives/agent-account
+
+ERC-4337 Smart Agent substrate — **canonical identity owner**.
+
+Every person, org, service, or treasury agent is anchored by its Smart Agent
+address (`0x…` / CAIP-10 `eip155:<chainId>:<address>`). This package deploys
+that account, derives its address, builds UserOps, and verifies ERC-1271
+signatures. Names, profiles, and passkeys are **facets** handled by sibling
+packages.
+
+> **Layer:** Core — the canonical identity **anchor**.
+> **Canonical key:** Smart Agent address (CAIP-10 `eip155:<chainId>:<address>`). Names / profiles / edges point AT it; they never *are* the identity.
+
+## Use This When
+
+- You need counterfactual or deployed Smart Agent addresses (CREATE2 factory).
+- You need `createAccount`, `isDeployed`, `buildUserOp`, or ERC-1271 verify paths.
+- You need bundler helpers (`BundlerClient`, packed UserOp gas fields).
+- You need quorum / admin payload hashing for custody-gated account actions.
+
+## Do Not Use This For
+
+- Passkey ceremonies, SIWE, OAuth, or JWT sessions → `connect-auth`.
+- `.agent` name registration or resolution → `agent-naming`.
+- AgentCard profiles or endpoint verification → `agent-profile`.
+- Custodian enrollment, credential recovery, or quorum scheduling → `account-custody`.
+- Delegation tokens or session authority → `delegation`.
+
+## Install
+
+Workspace-internal; not yet published.
+
+```bash
+pnpm add @agenticprimitives/agent-account
+```
+
+## 60-Second Quickstart
+
+```ts
+import { AgentAccountClient } from '@agenticprimitives/agent-account';
+import { deriveSaltFromEmail } from '@agenticprimitives/connect-auth';
+import type { Signer } from '@agenticprimitives/connect-auth';
+
+const account = new AgentAccountClient({
+  rpcUrl: process.env.RPC_URL!,
+  chainId: 84532,
+  entryPoint: process.env.ENTRYPOINT_ADDRESS as `0x${string}`,
+  factory: process.env.AGENT_FACTORY_ADDRESS as `0x${string}`,
+});
+
+// Salt from auth scope — NOT from a .agent name (ADR-0010).
+const salt = deriveSaltFromEmail(user.email, 0);
+const address = await account.getAddress(bootstrapSigner.address, salt);
+
+if (!(await account.isDeployed(address))) {
+  await account.createAccount(
+    { owner: bootstrapSigner.address, salt },
+    bootstrapSigner as Signer,
+  );
+}
+```
+
+## Main Concepts
+
+- **Smart Agent address**: the canonical identifier; stable across credential
+  rotation ([ADR-0011](../../docs/architecture/decisions/0011-credential-recovery-and-re-association.md)).
+- **CREATE2 salt**: from auth methods + user scope only — never from `.agent`
+  names ([spec 220](../../specs/220-agent-identity-bootstrap.md)).
+- **Signer**: pluggable interface from `connect-auth`; this package consumes it.
+- **UserOperation**: ERC-4337 v0.8 UserOp build path via `buildUserOp`.
+
+See [`docs/concepts.md`](docs/concepts.md).
+
+## Common Recipes
+
+```ts
+import { buildExecuteCallData, type ContractCall } from '@agenticprimitives/agent-account';
+
+const calls: ContractCall[] = [
+  { to: target, value: 0n, data: calldata },
+];
+const executeData = buildExecuteCallData(calls);
+```
+
+```ts
+import { encodeWebAuthnSignature, SIG_TYPE_WEBAUTHN } from '@agenticprimitives/agent-account';
+// WebAuthn ceremony output is produced by connect-auth; on-chain wire format here.
+```
+
+## Runtime Support
+
+Node and browser via `viem`. Requires RPC URL for chain reads and transaction
+submission.
+
+## Security Invariants
+
+- Salt derives from stable keccak inputs; no raw user-supplied salt bytes.
+- EntryPoint version is explicit in client config.
+- Bootstrap signer is distinct from day-to-day custodian signers.
+
+See [`docs/security.md`](docs/security.md) and [`AUDIT.md`](AUDIT.md).
+
+## Documentation Map
+
+- [`docs/concepts.md`](docs/concepts.md) — canonical identity vs facets.
+- [`docs/api.md`](docs/api.md) — public API guide.
+- [`docs/security.md`](docs/security.md) — invariants and trust boundaries.
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — common errors.
+- [`docs/migration.md`](docs/migration.md) — migration notes.
+- [`CLAUDE.md`](CLAUDE.md) — agent routing.
+- [`spec.md`](spec.md) — spec pointer.
+
+## Validation
+
+```bash
+pnpm check:agent-account
+pnpm check:forbidden-terms
+```
+
+## License
+
+UNLICENSED.

package/dist/abis.d.ts

@@ -0,0 +1,543 @@
+export declare const agentAccountFactoryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "createAgentAccount";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "mode";
+            readonly type: "uint8";
+        }, {
+            readonly name: "custodians";
+            readonly type: "address[]";
+        }, {
+            readonly name: "trustees";
+            readonly type: "address[]";
+        }, {
+            readonly name: "initialPasskeyCredentialIdDigest";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "initialPasskeyX";
+            readonly type: "uint256";
+        }, {
+            readonly name: "initialPasskeyY";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "timelockOverrides";
+        readonly type: "uint32[7]";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getAddressForAgentAccount";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "mode";
+            readonly type: "uint8";
+        }, {
+            readonly name: "custodians";
+            readonly type: "address[]";
+        }, {
+            readonly name: "trustees";
+            readonly type: "address[]";
+        }, {
+            readonly name: "initialPasskeyCredentialIdDigest";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "initialPasskeyX";
+            readonly type: "uint256";
+        }, {
+            readonly name: "initialPasskeyY";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "accountImplementation";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "bundlerSigner";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "sessionIssuer";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "delegationManager";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "custodyPolicy";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "AgentAccountCreated";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "mode";
+        readonly type: "uint8";
+        readonly indexed: false;
+    }, {
+        readonly name: "nExternalCustodians";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "withPasskey";
+        readonly type: "bool";
+        readonly indexed: false;
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}];
+export declare const agentAccountAbi: readonly [{
+    readonly type: "function";
+    readonly name: "isValidSignature";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes4";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "acceptSessionDelegation";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "sessionDelegationHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "hasAcceptedSessionDelegation";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "sessionDelegationHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isCustodian";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "custodianCount";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "factory";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "delegationManager";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "passkeyIdentity";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [{
+        readonly name: "x";
+        readonly type: "uint256";
+    }, {
+        readonly name: "y";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "hasPasskey";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getPasskey";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "x";
+        readonly type: "uint256";
+    }, {
+        readonly name: "y";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "passkeyCount";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "addPasskey";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "x";
+        readonly type: "uint256";
+    }, {
+        readonly name: "y";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "removePasskey";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "addCustodian";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "removeCustodian";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "execute";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "supportsInterface";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [{
+        readonly name: "interfaceId";
+        readonly type: "bytes4";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isAgenticPrimitivesAgentAccount";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "CustodianAdded";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "CustodianRemoved";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "PasskeyAdded";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "x";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "y";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "PasskeyRemoved";
+    readonly inputs: readonly [{
+        readonly name: "credentialIdDigest";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }];
+}];
+/**
+ * ApprovedHashRegistry (packages/contracts/src/ApprovedHashRegistry.sol).
+ * The v=1 path companion — passkey-only or hardware-wallet signers
+ * pre-approve a hash with one tx instead of producing an off-chain
+ * ECDSA sig. `QuorumEnforcer.beforeHook` (and the
+ * `_verifyQuorum(..., guardianMode=true)` path in AgentAccount) check
+ * `isApproved(signer, hash)` for v=1 slots in the packed blob.
+ */
+export declare const approvedHashRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "approveHash";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "revokeHash";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "isApproved";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+/** ERC-1271 magic value returned by isValidSignature on success. */
+export declare const ERC1271_MAGIC_VALUE: "0x1626ba7e";
+/**
+ * Minimal EntryPoint ABI for our bundler client + UserOp hashing.
+ * Source: account-abstraction/contracts/core/EntryPoint.sol (v0.9).
+ */
+export declare const entryPointAbi: readonly [{
+    readonly type: "function";
+    readonly name: "getUserOpHash";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "userOp";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "sender";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "initCode";
+            readonly type: "bytes";
+        }, {
+            readonly name: "callData";
+            readonly type: "bytes";
+        }, {
+            readonly name: "accountGasLimits";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "preVerificationGas";
+            readonly type: "uint256";
+        }, {
+            readonly name: "gasFees";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "paymasterAndData";
+            readonly type: "bytes";
+        }, {
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "handleOps";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "ops";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "sender";
+            readonly type: "address";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "initCode";
+            readonly type: "bytes";
+        }, {
+            readonly name: "callData";
+            readonly type: "bytes";
+        }, {
+            readonly name: "accountGasLimits";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "preVerificationGas";
+            readonly type: "uint256";
+        }, {
+            readonly name: "gasFees";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "paymasterAndData";
+            readonly type: "bytes";
+        }, {
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+    }, {
+        readonly name: "beneficiary";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "getNonce";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "sender";
+        readonly type: "address";
+    }, {
+        readonly name: "key";
+        readonly type: "uint192";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "FailedOp";
+    readonly inputs: readonly [{
+        readonly name: "opIndex";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reason";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "FailedOpWithRevert";
+    readonly inputs: readonly [{
+        readonly name: "opIndex";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reason";
+        readonly type: "string";
+    }, {
+        readonly name: "inner";
+        readonly type: "bytes";
+    }];
+}];
+//# sourceMappingURL=abis.d.ts.map

package/dist/abis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abis.d.ts","sourceRoot":"","sources":["../src/abis.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyEzB,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgDlB,CAAC;AAKX;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyB1B,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,EAAG,YAAqB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8EhB,CAAC"}