@vaultkeepr/smart-account 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,42 @@
+# @vaultkeepr/smart-account
+
+ERC-4337 account abstraction for VaultKeepR: Kernel smart account with Pimlico paymaster. Universal module for Web, Extension, iOS, and Android.
+
+Identity can be derived from the master password (on-device, no seed phrase exposure) or from an existing signer.
+
+## Install
+
+```bash
+npm install @vaultkeepr/smart-account
+```
+
+Requires `@vaultkeepr/core` and `@vaultkeepr/logger`.
+
+> This package ships as TypeScript source (`main`/`exports` point at `src/index.ts`) — consume it through your bundler.
+
+## Usage
+
+```ts
+import {
+  getIdentityAddress,
+  initIdentityFromPassword,
+  isIdentityConnected,
+} from "@vaultkeepr/smart-account";
+
+await initIdentityFromPassword(password, salt);
+if (isIdentityConnected()) {
+  const address = getIdentityAddress(); // smart account address
+}
+```
+
+Alternative: `initIdentityFromSigner(signer)` when a wallet is already connected; `clearIdentity()` wipes in-memory state.
+
+Modules: `identity.ts` (identity lifecycle), `kernel.ts` (Kernel account), `owner.ts` + `secretKey.ts` (signer derivation).
+
+## Security notes
+
+The chain stores location pointers only — never keys. Signatures for on-chain writes go through the user's smart account.
+
+Repository: [VaultKeepR/vaultkeepr-public](https://github.com/VaultKeepR/vaultkeepr-public) · Site: [vaultkeepr.xyz](https://vaultkeepr.xyz)
+
+MIT licensed.

package/dist/index.d.mts

@@ -19,124 +19,59 @@ declare function getCachedSmartAccountAddress(): Address | null;
 declare function getCachedSmartAccountMode(): VaultSmartAccount["mode"] | null;
 declare function clearSmartAccountCache(): void;
 
-declare function getOwnerFromPassword(password: string, secretKey?: string): Promise<LocalAccount>;
+type VaultIdentityMode = "password" | "passkey" | "biometric";
+interface VaultIdentity {
+    ownerAddress: Address;
+    aaAddress: Address;
+    mode: VaultIdentityMode;
+}
+declare function deriveIdentity(ownerAccount: LocalAccount, mode: VaultIdentityMode): Promise<VaultIdentity>;
+interface VerifyAAAuthParams {
+    signature: string;
+    message: string;
+    claimedOwner?: Address;
+    claimedAA?: Address | null;
+    timestamp: number;
+}
+interface VerifyAAAuthResult {
+    ok: boolean;
+    ownerAddress: Address;
+    aaAddress: Address;
+}
+declare function verifyAAAuth(params: VerifyAAAuthParams): Promise<VerifyAAAuthResult>;
 
-declare const CID_REGISTRY_ABI: readonly [{
-    readonly name: "setCid";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [{
-        readonly name: "cid";
-        readonly type: "string";
-    }];
-    readonly outputs: readonly [];
-}, {
-    readonly name: "deleteCid";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [];
-}, {
-    readonly name: "getCid";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "string";
-    }];
-}, {
-    readonly name: "hasCid";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-}, {
-    readonly name: "getUpdatedAt";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "nextAllowedUpdate";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "account";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "cooldownSeconds";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}];
-declare function isCidRegistryConfigured(): boolean;
-declare function publishCidOnChain(smartAccount: VaultSmartAccount, cid: string): Promise<`0x${string}` | null>;
-declare function readCidOnChain(smartAccountAddress: Address): Promise<string | null>;
+declare function getOwnerFromPassword(password: string, secretKey?: string): Promise<LocalAccount>;
 
 declare function getPimlicoApiKey(): string;
 declare function isSmartAccountConfigured(): boolean;
 declare function getTargetChain(): Chain;
 
-declare function scheduleCidOnChainSync(smartAccount: VaultSmartAccount | null, cid: string, debounceMs?: number): void;
-declare function flushCidOnChainSync(): Promise<boolean>;
-declare function getOnChainSyncStatus(): {
-    hasPending: boolean;
-    pendingCid: string | null;
-    lastPublishedCid: string | null;
-    lastPublishTime: number;
-    isPublishing: boolean;
-};
-declare function resetOnChainSync(): void;
-
-interface IdentityState {
+interface IdentityState$1 {
     owner: LocalAccount | null;
     smartAccount: VaultSmartAccount | null;
     mode: "password" | "passkey" | "biometric" | null;
     initialized: boolean;
 }
-type IdentityListener = (state: IdentityState) => void;
+type IdentityListener = (state: IdentityState$1) => void;
 declare function initIdentityFromPassword(password: string, secretKey?: string): Promise<{
     address: Address;
     smartAccountAddress: Address | null;
+    aaAddress: Address | null;
 }>;
 declare function initIdentityFromSigner(signer: LocalAccount, mode?: "passkey" | "biometric"): Promise<{
     address: Address;
     smartAccountAddress: Address | null;
+    aaAddress: Address | null;
 }>;
 declare function clearIdentity(): void;
 declare function getIdentityAddress(): Address | null;
 declare function isIdentityConnected(): boolean;
 declare function getIdentityOwner(): LocalAccount | null;
 declare function getIdentitySmartAccount(): VaultSmartAccount | null;
-declare function getIdentityMode(): IdentityState["mode"];
+declare function getIdentityMode(): IdentityState$1["mode"];
 declare function signMessageWithIdentity(message: string): Promise<`0x${string}`>;
 declare function subscribeIdentity(listener: IdentityListener): () => void;
-declare function getIdentitySnapshot(): IdentityState;
+declare function getIdentitySnapshot(): IdentityState$1;
 
 interface UseIdentityReturn {
     address: Address | null;
@@ -145,9 +80,7 @@ interface UseIdentityReturn {
     smartAccountAddress: Address | null;
     signMessage: (message: string) => Promise<`0x${string}`>;
     disconnect: () => void;
-    notifyOnChainSync: (cid: string) => void;
     cleanupOnLock: () => Promise<void>;
-    flushOnChainSync: () => Promise<void>;
 }
 declare function useIdentity(): UseIdentityReturn;
 
@@ -156,4 +89,170 @@ declare function isValidSecretKey(key: string): boolean;
 declare function formatSecretKeyForDisplay(key: string): string;
 declare function parseSecretKeyInput(input: string): string;
 
-export { CID_REGISTRY_ABI, type CreateSmartAccountParams, type UseIdentityReturn, type VaultSmartAccount, clearIdentity, clearSmartAccountCache, computeSmartAccountAddress, createVaultSmartAccount, flushCidOnChainSync, formatSecretKeyForDisplay, generateSecretKey, getCachedSmartAccountAddress, getCachedSmartAccountMode, getIdentityAddress, getIdentityMode, getIdentityOwner, getIdentitySmartAccount, getIdentitySnapshot, getOnChainSyncStatus, getOwnerFromPassword, getPimlicoApiKey, getTargetChain, initIdentityFromPassword, initIdentityFromSigner, isCidRegistryConfigured, isIdentityConnected, isSmartAccountConfigured, isValidSecretKey, parseSecretKeyInput, publishCidOnChain, readCidOnChain, resetOnChainSync, scheduleCidOnChainSync, signMessageWithIdentity, subscribeIdentity, useIdentity };
+/**
+ * Accounts without a secret key, and their one-time passage to a key.
+ *
+ * Rule: one secret key per account. A key-less account has the password identity as owner.
+ * Passing it to a key is a one-time move, in this order:
+ *   1. create the key as a pending key (this device keeps its identity);
+ *   2. copy the pointer under the key's Smart Account;
+ *   3. mark the legacy pointer as moved to that Smart Account;
+ *   4. activate the pending key on this device.
+ * Nothing is deleted. Devices that do not hold the key become read-only.
+ *
+ * A failure stops the sequence. A retry reuses the same pending key. A device never uses the
+ * new key before the legacy pointer has moved to its Smart Account.
+ *
+ * Pure logic. Network and storage are injected, so the order and the failure behaviour are
+ * tested without a device.
+ */
+/** Server view of the legacy (password identity) pointer. */
+type PointerState = "none" | "active" | "moved";
+type IdentityState = {
+    kind: "ready";
+} | {
+    kind: "pass_to_key";
+} | {
+    kind: "pair_required";
+} | {
+    kind: "join_or_create";
+};
+declare function identityState(input: {
+    hasSecretKey: boolean;
+    pointer: PointerState;
+}): IdentityState;
+/**
+ * Writes are allowed while the account has not moved: a key-less account keeps writing to its
+ * legacy pointer until its passage ("nothing changes"). A moved pointer, or no pointer and no
+ * key, cannot be written from this device.
+ */
+declare function canWritePointer(state: IdentityState): boolean;
+interface LegacyPointer {
+    cid: string | null;
+    moved: boolean;
+    /** Smart Account the pointer moved to, when moved. */
+    movedTo?: string;
+}
+interface PassageIO {
+    /** Reads the legacy (password identity) pointer. */
+    readLegacyPointer(): Promise<LegacyPointer>;
+    /** The pending key left by a passage on this device, or null. Never creates a key. */
+    peekPendingKey(): Promise<string | null>;
+    /** The pending key: created and kept in pending storage if absent. Same key on every retry. Does not change the identity. */
+    getOrCreatePendingKey(): Promise<string>;
+    /** Smart Account of the key's owner. */
+    smartAccountOf(secretKey: string): Promise<string>;
+    /** Writes the copy under the Smart Account, signed with the pending key. Idempotent. */
+    writeSmartAccountPointer(smartAccount: string, cid: string): Promise<void>;
+    /** Marks the legacy pointer as moved to the Smart Account, signed with the legacy owner. Idempotent for the same target. */
+    markLegacyMoved(smartAccount: string): Promise<void>;
+    /** Makes the pending key this device's account key. Called only once the legacy pointer has moved to its Smart Account. */
+    activatePendingKey(): Promise<void>;
+    /** Removes the pending key. Used when the account has moved to another key. */
+    discardPendingKey(): Promise<void>;
+}
+type PassageResult = {
+    status: "moved";
+    smartAccount: string;
+} | {
+    status: "nothing_to_pass";
+} | {
+    status: "already_moved";
+} | {
+    status: "already_keyed";
+};
+declare function runPassage(io: PassageIO, opts: {
+    hasSecretKey: boolean;
+}): Promise<PassageResult>;
+
+/**
+ * Client side of the passage to a key: the requests to the server, with the signatures and the
+ * storage supplied by each app. The order and the failure rules are in keyPassage.ts.
+ *
+ * Off in production: PASSAGE_ENABLED stays false until the server move route and the Smart
+ * Account namespace are deployed.
+ */
+
+/** Off until the server side (move route, Smart Account namespace) is deployed. */
+declare const PASSAGE_ENABLED = false;
+interface PassageEnv {
+    /** API origin, without trailing slash. */
+    apiBase: string;
+    fetch: typeof fetch;
+    /** EOA of the password identity (the legacy owner). */
+    legacyAddress: string;
+    /** Signs a message with the legacy owner. */
+    signLegacy(message: string): Promise<string>;
+    /** Signs a message with the owner of a secret key. */
+    signWithKey(secretKey: string, message: string): Promise<string>;
+    /** Smart Account of a secret key's owner. */
+    smartAccountOf(secretKey: string): Promise<string>;
+    /** The autosave delegation message the server verifies (wallet-messages). */
+    formatDelegation(sessionId: string, expiryTimestamp: number): string;
+    /** A new random secret key (client RNG). */
+    newSecretKey(): string;
+    /** A new random session id. */
+    newSessionId(): string;
+    /** Current time, in milliseconds. */
+    now(): number;
+    /** Pending key storage: encrypted at rest, never logged. */
+    pending: {
+        read(): Promise<string | null>;
+        write(secretKey: string): Promise<void>;
+        clear(): Promise<void>;
+    };
+    /** Stores the committed account key and updates this device's identity. */
+    activate(secretKey: string): Promise<void>;
+}
+declare function createPassageIO(env: PassageEnv): PassageIO;
+/** The account's state on this device, for the UI. Changes nothing. */
+declare function readPassageState(env: PassageEnv, hasSecretKey: boolean): Promise<IdentityState>;
+/** Runs the one-time passage. On a failed step it throws, and the pending key is kept for a retry. */
+declare function runPassageWith(env: PassageEnv, hasSecretKey: boolean): Promise<PassageResult>;
+
+/**
+ * Migration of an account that already has a secret key: its pointer moves from the legacy
+ * namespace (the owner EOA of the key) to the Smart Account namespace (SA of that EOA).
+ *
+ * Steps, with the device key as the owner signer (same routes as the one-time passage):
+ *   1. read the legacy pointer of the owner EOA;
+ *   2. if the SA has no pointer, copy the legacy CID under the SA (the server infers the SA namespace
+ *      from the owner signature);
+ *   3. mark the legacy pointer moved to the SA (the server refuses it without the SA copy);
+ *   4. after the move the legacy pointer is frozen: read it again and make the SA equal to it.
+ *      This closes the race where an old client wrote the legacy pointer between steps 1 and 3.
+ *
+ * Nothing is deleted. A failed step throws; the next unlock runs the same steps again.
+ * A conflict (the SA already holds a different CID) changes nothing: the device keeps the legacy pointer.
+ *
+ * Off until the server side is deployed: KEYED_MIGRATION_ENABLED stays false.
+ */
+/** Off until the Smart Account namespace and the move route are deployed. */
+declare const KEYED_MIGRATION_ENABLED = false;
+interface KeyedMigrationEnv {
+    apiBase: string;
+    fetch: typeof fetch;
+    /** Owner EOA derived from the device secret key. The legacy pointer lives under it. */
+    ownerAddress: string;
+    /** Smart Account of the owner EOA, computed on the device. Never taken from the server. */
+    smartAccount: string;
+    /** Signs with the device key (the owner EOA). */
+    signWithKey(message: string): Promise<string>;
+    formatDelegation(sessionId: string, expiryTimestamp: number): string;
+    newSessionId(): string;
+    now(): number;
+}
+/**
+ * - moved: the legacy pointer is now moved to the SA, and the SA holds its CID.
+ * - already_moved: a previous run (or another device) already moved it to this SA.
+ * - no_pointer: no legacy pointer. Nothing to move: the device keeps the legacy namespace.
+ * - conflict: the SA holds a different CID. Nothing changed; to be reported, not resolved here.
+ */
+type KeyedMigrationStatus = "moved" | "already_moved" | "no_pointer" | "conflict";
+/**
+ * Runs the migration for the device's account. Throws on any failed step: the caller keeps the legacy
+ * namespace and retries at the next unlock. Switches the device to the SA only on moved / already_moved.
+ */
+declare function migrateKeyedPointer(env: KeyedMigrationEnv): Promise<KeyedMigrationStatus>;
+
+export { type CreateSmartAccountParams, type IdentityState, KEYED_MIGRATION_ENABLED, type KeyedMigrationEnv, type KeyedMigrationStatus, type LegacyPointer, PASSAGE_ENABLED, type PassageEnv, type PassageIO, type PassageResult, type PointerState, type UseIdentityReturn, type VaultIdentity, type VaultIdentityMode, type VaultSmartAccount, type VerifyAAAuthParams, type VerifyAAAuthResult, canWritePointer, clearIdentity, clearSmartAccountCache, computeSmartAccountAddress, createPassageIO, createVaultSmartAccount, deriveIdentity, formatSecretKeyForDisplay, generateSecretKey, getCachedSmartAccountAddress, getCachedSmartAccountMode, getIdentityAddress, getIdentityMode, getIdentityOwner, getIdentitySmartAccount, getIdentitySnapshot, getOwnerFromPassword, getPimlicoApiKey, getTargetChain, identityState, initIdentityFromPassword, initIdentityFromSigner, isIdentityConnected, isSmartAccountConfigured, isValidSecretKey, migrateKeyedPointer, parseSecretKeyInput, readPassageState, runPassage, runPassageWith, signMessageWithIdentity, subscribeIdentity, useIdentity, verifyAAAuth };