ethagent 1.1.2 → 2.0.0

package/src/identity/hub/effects/restore/auth.ts

@@ -0,0 +1,159 @@
+import { getAddress, type Address } from 'viem'
+import {
+  ContinuitySnapshotOwnerMismatchError,
+  ContinuitySnapshotRestoreSlotMissingError,
+  findRestorableAddressForSnapshot,
+  isWalletContinuitySnapshotEnvelope,
+  walletContinuitySnapshotSlotForAddress,
+  type ContinuitySnapshotEnvelope,
+} from '../../../continuity/envelope.js'
+import { assertAgentStateBackupOwner } from '../../../crypto/backupEnvelope.js'
+import type { Erc8004AgentCandidate } from '../../../registry/erc8004.js'
+import { requestBrowserWalletAccount, type WalletPurpose } from '../../../wallet/browserWallet.js'
+import type { Step } from '../../identityHubReducer.js'
+import type { EffectCallbacks } from '../types.js'
+import { isContinuitySnapshotEnvelope, parseRestorableEnvelope } from './envelopes.js'
+import {
+  isAuthorizedOperatorAddress,
+  isTransferContinuitySnapshot,
+  ownerCandidateAddresses,
+  requesterAddressFromHandle,
+  restoreTransferSlotForRequester,
+} from './shared.js'
+
+export async function runRestoreConnectWallet(
+  step: Extract<Step, { kind: 'restore-wallet' }>,
+  callbacks: EffectCallbacks,
+): Promise<void> {
+  const wallet = await requestBrowserWalletAccount({
+    onReady: callbacks.onWalletReady,
+    purpose: 'connect-operator-wallet',
+  })
+  callbacks.onStep({ kind: 'restore-network', ownerHandle: wallet.account, purpose: step.purpose })
+}
+
+export function restoreSignatureRequestForStep(
+  step: Extract<Step, { kind: 'restore-authorizing' }>,
+): {
+  expectedAccount: Address
+  message: string
+  purpose: WalletPurpose
+  role: 'owner-wallet' | 'operator-wallet'
+} {
+  if (isContinuitySnapshotEnvelope(step.envelope)) {
+    const requesterAddress = step.requesterAddress ? requesterAddressFromHandle(step.requesterAddress) : undefined
+    if (requesterAddress && isWalletContinuitySnapshotEnvelope(step.envelope)) {
+      const slot = walletContinuitySnapshotSlotForAddress(step.envelope, requesterAddress)
+      if (slot) {
+        const ownerAddress = getAddress(step.envelope.ownerAddress)
+        const requesterIsOwner = requesterAddress.toLowerCase() === ownerAddress.toLowerCase()
+        return {
+          expectedAccount: requesterAddress,
+          message: slot.challenge,
+          purpose: requesterIsOwner ? 'restore-owner-wallet' : 'restore-operator-wallet',
+          role: requesterIsOwner ? 'owner-wallet' : 'operator-wallet',
+        }
+      }
+      if (isAuthorizedOperatorAddress(step.candidate, requesterAddress)) {
+        throw new Error('Restore Slot Missing: re-save this agent once with the owner wallet.')
+      }
+    }
+    if (requesterAddress && isTransferContinuitySnapshot(step.envelope)) {
+      const transferSlot = restoreTransferSlotForRequester(step.envelope, requesterAddress)
+      if (transferSlot) {
+        const ownerAddress = getAddress(step.envelope.ownerAddress)
+        const requesterIsOwner = requesterAddress.toLowerCase() === ownerAddress.toLowerCase()
+        return {
+          expectedAccount: requesterAddress,
+          message: transferSlot.challenge,
+          purpose: requesterIsOwner ? 'restore-owner-wallet' : 'restore-operator-wallet',
+          role: requesterIsOwner ? 'owner-wallet' : 'operator-wallet',
+        }
+      }
+    }
+    const ownerCandidates = ownerCandidateAddresses(step.candidate)
+    if (requesterAddress
+      && !ownerCandidates.some(addr => addr.toLowerCase() === requesterAddress.toLowerCase())
+      && isAuthorizedOperatorAddress(step.candidate, requesterAddress)) {
+      throw new Error('Restore Slot Missing: re-save this agent once with the owner wallet.')
+    }
+    if (isWalletContinuitySnapshotEnvelope(step.envelope)) {
+      for (const candidateAddress of ownerCandidates) {
+        const slot = walletContinuitySnapshotSlotForAddress(step.envelope, candidateAddress)
+        if (slot) {
+          return {
+            expectedAccount: candidateAddress,
+            message: slot.challenge,
+            purpose: 'restore-owner-wallet',
+            role: 'owner-wallet',
+          }
+        }
+      }
+      throw new Error('Restore Slot Missing: re-save this agent once with the owner wallet.')
+    }
+    return {
+      expectedAccount: ownerCandidates[0] ?? getAddress(step.candidate.ownerAddress),
+      message: step.envelope.challenge,
+      purpose: 'restore-owner-wallet',
+      role: 'owner-wallet',
+    }
+  }
+  return {
+    expectedAccount: getAddress(step.candidate.ownerAddress),
+    message: step.envelope.challenge,
+    purpose: 'restore-owner-wallet',
+    role: 'owner-wallet',
+  }
+}
+
+export function restoreMessageForWallet(envelope: ContinuitySnapshotEnvelope, address: Address): string {
+  if (isWalletContinuitySnapshotEnvelope(envelope)) {
+    const slot = walletContinuitySnapshotSlotForAddress(envelope, address)
+    if (!slot) throw new Error('Restore Slot Missing: re-save this agent once with the owner wallet.')
+    return slot.challenge
+  }
+  if (isTransferContinuitySnapshot(envelope)) {
+    const slot = restoreTransferSlotForRequester(envelope, address)
+    if (!slot) throw new Error('Restore Slot Missing: re-save this agent once with the owner wallet.')
+    return slot.challenge
+  }
+  return envelope.challenge
+}
+
+export function assertCandidateCanReadEnvelope(
+  candidate: Erc8004AgentCandidate,
+  requesterHandle: string | undefined,
+  envelope: ReturnType<typeof parseRestorableEnvelope>,
+): void {
+  const requester = requesterHandle ? requesterAddressFromHandle(requesterHandle) : undefined
+  const candidateAddresses: string[] = []
+  const seen = new Set<string>()
+  const add = (addr: string | undefined): void => {
+    if (!addr) return
+    const lower = addr.toLowerCase()
+    if (seen.has(lower)) return
+    seen.add(lower)
+    candidateAddresses.push(addr)
+  }
+  add(candidate.ownerAddress)
+  add(requester)
+  if (candidate.operators?.activeOperatorAddress) add(candidate.operators.activeOperatorAddress)
+  for (const record of candidate.operators?.approvedOperatorWallets ?? []) add(record.address)
+
+  if (isContinuitySnapshotEnvelope(envelope)) {
+    if (findRestorableAddressForSnapshot(envelope, candidateAddresses)) return
+    if (isWalletContinuitySnapshotEnvelope(envelope)) {
+      throw new ContinuitySnapshotRestoreSlotMissingError(requester ?? candidate.ownerAddress)
+    }
+    const snapshotOwner = (envelope as { ownerAddress?: string }).ownerAddress ?? ''
+    throw new ContinuitySnapshotOwnerMismatchError(snapshotOwner, requester ?? candidate.ownerAddress)
+  }
+  for (const addr of candidateAddresses) {
+    try {
+      assertAgentStateBackupOwner(envelope, addr)
+      return
+    } catch {
+    }
+  }
+  assertAgentStateBackupOwner(envelope, candidate.ownerAddress)
+}

package/src/identity/hub/effects/restore/discover.ts

@@ -0,0 +1,86 @@
+import type { EthagentConfig } from '../../../../storage/config.js'
+import {
+  DEFAULT_IPFS_API_URL,
+} from '../../../storage/ipfs.js'
+import {
+  discoverOwnedAgentBackups,
+  type Erc8004AgentCandidate,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import type { RestorePurpose, Step } from '../../identityHubReducer.js'
+import type { EffectCallbacks } from '../types.js'
+import { isAbortError, isAuthorizedOperatorAddress, requesterAddressFromHandle } from './shared.js'
+import type { Address } from 'viem'
+
+export async function runRestoreDiscover(
+  step: Extract<Step, { kind: 'restore-discovering' }>,
+  _config: EthagentConfig | undefined,
+  callbacks: EffectCallbacks,
+): Promise<void> {
+  const signal = step.abortSignal
+  let owned: Erc8004AgentCandidate[]
+  try {
+    owned = await discoverOwnedAgentBackups({
+      ...step.registry,
+      ownerHandle: step.ownerHandle,
+      ipfsApiUrl: DEFAULT_IPFS_API_URL,
+      ...(signal ? { signal } : {}),
+    })
+  } catch (err: unknown) {
+    if (signal?.aborted || isAbortError(err)) return
+    callbacks.onStep({
+      kind: 'restore-not-found',
+      ownerHandle: step.ownerHandle,
+      registry: step.registry,
+      requesterAddress: requesterAddressFromHandle(step.ownerHandle),
+      reason: 'search-incomplete',
+      purpose: step.purpose,
+    })
+    return
+  }
+  if (signal?.aborted) return
+  if (owned.length === 0) {
+    callbacks.onStep({
+      kind: 'restore-recovery-input',
+      ownerHandle: step.ownerHandle,
+      registry: step.registry,
+      purpose: step.purpose,
+    })
+    return
+  }
+  callbacks.onStep(restoreTokenSelectionStep({
+    ownerHandle: step.ownerHandle,
+    registry: step.registry,
+    candidates: owned,
+    requesterAddress: requesterAddressFromHandle(step.ownerHandle),
+    purpose: step.purpose,
+  }))
+}
+
+export function restoreTokenSelectionStep(args: {
+  ownerHandle: string
+  registry: Erc8004RegistryConfig
+  candidates: Erc8004AgentCandidate[]
+  requesterAddress?: Address
+  purpose?: RestorePurpose
+}): Extract<Step, { kind: 'restore-select-token' }> {
+  const restorable = args.candidates.filter(candidate => candidate.backup?.cid)
+  if (restorable.length === 0) {
+    throw new Error(args.candidates.length === 0
+      ? 'No agent identities found for that wallet on this network'
+      : 'No matching agent identity has recoverable ethagent state on this network')
+  }
+  return {
+    kind: 'restore-select-token',
+    ownerHandle: args.ownerHandle,
+    registry: args.registry,
+    candidates: restorable,
+    requesterAddress: args.requesterAddress,
+    purpose: args.purpose,
+  }
+}
+
+export function canRestoreCandidate(candidate: Erc8004AgentCandidate, address: Address): boolean {
+  if (candidate.ownerAddress.toLowerCase() === address.toLowerCase()) return true
+  return isAuthorizedOperatorAddress(candidate, address)
+}

package/src/identity/hub/effects/restore/envelopes.ts

@@ -0,0 +1,21 @@
+import { parseAgentStateBackupEnvelope } from '../../../crypto/backupEnvelope.js'
+import {
+  CONTINUITY_SNAPSHOT_ENVELOPE_VERSION,
+  parseContinuitySnapshotEnvelope,
+  type ContinuitySnapshotEnvelope,
+} from '../../../continuity/envelope.js'
+
+export type RestorableEnvelope = ReturnType<typeof parseAgentStateBackupEnvelope> | ContinuitySnapshotEnvelope
+
+export function parseRestorableEnvelope(raw: string | Uint8Array): RestorableEnvelope {
+  const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw)
+  const parsed = JSON.parse(text) as { envelopeVersion?: unknown }
+  if (parsed.envelopeVersion === CONTINUITY_SNAPSHOT_ENVELOPE_VERSION) {
+    return parseContinuitySnapshotEnvelope(text)
+  }
+  return parseAgentStateBackupEnvelope(text)
+}
+
+export function isContinuitySnapshotEnvelope(envelope: RestorableEnvelope): envelope is ContinuitySnapshotEnvelope {
+  return envelope.envelopeVersion === CONTINUITY_SNAPSHOT_ENVELOPE_VERSION
+}

package/src/identity/hub/effects/restore/fetch.ts

@@ -0,0 +1,25 @@
+import { catFromIpfs } from '../../../storage/ipfs.js'
+import type { Step } from '../../identityHubReducer.js'
+import type { EffectCallbacks } from '../types.js'
+import { parseRestorableEnvelope } from './envelopes.js'
+import { assertCandidateCanReadEnvelope, restoreSignatureRequestForStep } from './auth.js'
+
+export async function runRestoreFetch(
+  step: Extract<Step, { kind: 'restore-fetching' }>,
+  callbacks: EffectCallbacks,
+): Promise<void> {
+  const raw = await catFromIpfs(step.apiUrl, step.cid)
+  const envelope = parseRestorableEnvelope(raw)
+  assertCandidateCanReadEnvelope(step.candidate, step.requesterAddress, envelope)
+  const nextStep: Extract<Step, { kind: 'restore-authorizing' }> = {
+    kind: 'restore-authorizing',
+    cid: step.cid,
+    apiUrl: step.apiUrl,
+    envelope,
+    candidate: step.candidate,
+    requesterAddress: step.requesterAddress,
+    purpose: step.purpose,
+  }
+  restoreSignatureRequestForStep(nextStep)
+  callbacks.onStep(nextStep)
+}

package/src/identity/hub/effects/restore/index.ts

@@ -0,0 +1,22 @@
+export {
+  runRestoreAuthorize,
+} from './apply.js'
+export {
+  restoreSignatureRequestForStep,
+  runRestoreConnectWallet,
+} from './auth.js'
+export {
+  canRestoreCandidate,
+  restoreTokenSelectionStep,
+  runRestoreDiscover,
+} from './discover.js'
+export {
+  runRestoreFetch,
+} from './fetch.js'
+export {
+  runRecoveryRefetch,
+} from './recovery.js'
+export {
+  resolveAgentEnsToCandidate,
+  resolveAgentTokenIdToCandidate,
+} from './resolve.js'

package/src/identity/hub/effects/restore/recovery.ts

@@ -0,0 +1,135 @@
+import { getAddress, type Address } from 'viem'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+import {
+  assertContinuitySnapshotOwner,
+  isWalletContinuitySnapshotEnvelope,
+  restoreContinuitySnapshotEnvelope,
+  transferSnapshotMetadataFromEnvelope,
+} from '../../../continuity/envelope.js'
+import { ensureIdentityMarkdownScaffold, localContinuitySnapshotContentHashes, writeContinuityFiles } from '../../../continuity/storage.js'
+import { recordPublishedContinuitySnapshot, updatePublishedContinuitySnapshotContentHashes } from '../../../continuity/snapshots.js'
+import { catFromIpfs, DEFAULT_IPFS_API_URL } from '../../../storage/ipfs.js'
+import {
+  discoverOwnedAgentBackupByTokenId,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import { requestBrowserWalletSignature } from '../../../wallet/browserWallet.js'
+import { setOperatorVaultAddressField } from '../../../identityCompat.js'
+import type { EffectCallbacks } from '../types.js'
+import { isContinuitySnapshotEnvelope, parseRestorableEnvelope } from './envelopes.js'
+import { restoreMessageForWallet } from './auth.js'
+import { type BackupMetadata, operatorStateFromCandidate, restorePublishedPublicSkills } from './shared.js'
+
+export async function runRecoveryRefetch(
+  identity: EthagentIdentity,
+  registry: Erc8004RegistryConfig,
+  callbacks: EffectCallbacks,
+): Promise<void> {
+  if (!identity.agentId) throw new Error('Cannot refetch: identity is missing an agent token ID')
+  const ownerAddress = getAddress(identity.ownerAddress ?? identity.address)
+  const candidate = await discoverOwnedAgentBackupByTokenId({
+    ...registry,
+    ownerHandle: ownerAddress,
+    tokenId: BigInt(identity.agentId),
+    ipfsApiUrl: identity.backup?.ipfsApiUrl ?? DEFAULT_IPFS_API_URL,
+  })
+  if (!candidate.backup?.cid) {
+    throw new Error('The published agent does not have a recoverable encrypted snapshot')
+  }
+  const apiUrl = identity.backup?.ipfsApiUrl ?? DEFAULT_IPFS_API_URL
+  const raw = await catFromIpfs(apiUrl, candidate.backup.cid)
+  const envelope = parseRestorableEnvelope(raw)
+  if (!isContinuitySnapshotEnvelope(envelope)) {
+    throw new Error('This snapshot is in an unsupported envelope format and cannot be refetched here; use Load Agent')
+  }
+  const eligibleAddresses: Address[] = [ownerAddress]
+  if (isWalletContinuitySnapshotEnvelope(envelope)) {
+    for (const slot of envelope.slots) {
+      const slotAddress = getAddress(slot.address)
+      if (!eligibleAddresses.some(a => a.toLowerCase() === slotAddress.toLowerCase())) {
+        eligibleAddresses.push(slotAddress)
+      }
+    }
+  } else {
+    assertContinuitySnapshotOwner(envelope, ownerAddress)
+  }
+  const wallet = await requestBrowserWalletSignature({
+    chainId: candidate.chainId,
+    purpose: 'refetch-snapshot',
+    messageForAccount: account => {
+      const matched = eligibleAddresses.find(a => a.toLowerCase() === account.toLowerCase())
+      if (!matched) {
+        throw new Error(`Operator Wallet Required: ${account} is not authorized for this agent. Connect the owner wallet or an authorized operator wallet.`)
+      }
+      return restoreMessageForWallet(envelope, matched)
+    },
+    onReady: callbacks.onWalletReady,
+  })
+  callbacks.onWalletReady(null)
+  callbacks.onRestoreProgress?.({ phase: 'decrypting', label: 'signature received, decrypting onchain snapshot...' })
+  const payload = restoreContinuitySnapshotEnvelope({
+    envelope,
+    walletSignature: wallet.signature,
+    currentOwnerAddress: getAddress(wallet.account),
+  })
+  callbacks.onRestoreProgress?.({ phase: 'writing', label: 'restoring SOUL.md, MEMORY.md, and skills.json...' })
+  const transferSnapshot = transferSnapshotMetadataFromEnvelope(envelope)
+  const refreshedBackup: BackupMetadata = {
+    cid: candidate.backup.cid,
+    createdAt: envelope.createdAt,
+    envelopeVersion: envelope.envelopeVersion,
+    ipfsApiUrl: apiUrl,
+    status: 'restored',
+    ownerAddress,
+    chainId: candidate.chainId,
+    rpcUrl: candidate.rpcUrl,
+    identityRegistryAddress: candidate.identityRegistryAddress,
+    agentId: candidate.agentId.toString(),
+    agentUri: candidate.agentUri,
+    metadataCid: candidate.metadataCid,
+    ...(transferSnapshot ? { transferSnapshot } : {}),
+  }
+  const refreshedState: Record<string, unknown> = {
+    ...payload.state,
+    ...(candidate.name ? { name: candidate.name } : {}),
+    ...(candidate.description ? { description: candidate.description } : {}),
+    ...(candidate.imageUrl ? { imageUrl: candidate.imageUrl } : {}),
+    ...operatorStateFromCandidate(candidate),
+  }
+  const tokenOwnerAddress = candidate.tokenOwnerAddress ?? candidate.ownerAddress
+  if (tokenOwnerAddress.toLowerCase() !== candidate.ownerAddress.toLowerCase()) {
+    setOperatorVaultAddressField(refreshedState, getAddress(tokenOwnerAddress))
+  }
+  const nextIdentity: EthagentIdentity = {
+    ...identity,
+    source: 'erc8004',
+    address: ownerAddress,
+    ownerAddress,
+    chainId: candidate.chainId,
+    rpcUrl: candidate.rpcUrl,
+    identityRegistryAddress: candidate.identityRegistryAddress,
+    agentId: candidate.agentId.toString(),
+    agentUri: candidate.agentUri,
+    metadataCid: candidate.metadataCid,
+    state: refreshedState,
+    backup: refreshedBackup,
+    ...(candidate.publicDiscovery ? {
+      publicSkills: {
+        ...(candidate.publicDiscovery.skillsCid ? { cid: candidate.publicDiscovery.skillsCid } : {}),
+        ...(candidate.publicDiscovery.agentCardCid ? { agentCardCid: candidate.publicDiscovery.agentCardCid } : {}),
+        ...(candidate.publicDiscovery.updatedAt ? { updatedAt: candidate.publicDiscovery.updatedAt } : {}),
+        status: 'pinned',
+      },
+    } : {}),
+  }
+  await writeContinuityFiles(nextIdentity, payload.files)
+  callbacks.onRestoreProgress?.({ phase: 'finishing', label: 'finalizing refreshed identity...' })
+  const publicSkillsRestored = await restorePublishedPublicSkills(nextIdentity, apiUrl, candidate.publicDiscovery?.skillsCid)
+  await ensureIdentityMarkdownScaffold(nextIdentity)
+  await recordPublishedContinuitySnapshot({ identity: nextIdentity, label: 'Refetched Latest Snapshot From Chain' }).catch(() => null)
+  if (publicSkillsRestored) {
+    const contentHashes = await localContinuitySnapshotContentHashes(nextIdentity)
+    await updatePublishedContinuitySnapshotContentHashes(nextIdentity, candidate.backup.cid, contentHashes).catch(() => null)
+  }
+  await callbacks.onIdentityComplete(nextIdentity, 'Latest Published Snapshot Restored From Chain', 'update')
+}

package/src/identity/hub/effects/restore/resolve.ts

@@ -0,0 +1,102 @@
+import { type Address } from 'viem'
+import { DEFAULT_IPFS_API_URL } from '../../../storage/ipfs.js'
+import {
+  createErc8004PublicClient,
+  discoverOwnedAgentBackupByTokenId,
+  type Erc8004AgentCandidate,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import { parseAgentTokenReference, readEthagentTextRecords } from '../../../ens/ensLookup.js'
+import { AGENT_RECORD_KEYS } from '../../../ens/agentRecords.js'
+
+const ETH_NAME_PATTERN = /^([a-z0-9-]+\.)+eth$/i
+
+type AgentEnsResolution =
+  | { ok: true; candidate: Erc8004AgentCandidate }
+  | { ok: false; message: string }
+
+export async function resolveAgentEnsToCandidate(
+  ensName: string,
+  registry: Erc8004RegistryConfig,
+): Promise<AgentEnsResolution> {
+  const trimmed = ensName.trim()
+  if (!trimmed) return { ok: false, message: 'Enter an agent ENS name (e.g. agent.example.eth).' }
+  if (!ETH_NAME_PATTERN.test(trimmed)) return { ok: false, message: 'Enter a valid .eth name.' }
+  let records: Record<string, string>
+  try {
+    records = await readEthagentTextRecords(trimmed, [AGENT_RECORD_KEYS.token])
+  } catch (err: unknown) {
+    return { ok: false, message: `Could not reach Ethereum mainnet to resolve ${trimmed}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+  const tokenValue = records[AGENT_RECORD_KEYS.token]
+  if (!tokenValue) return { ok: false, message: `${trimmed} has no org.ethagent.token record. Use the full agent subdomain (e.g. agent.${trimmed}).` }
+  const tokenRef = parseAgentTokenReference(tokenValue)
+  if (!tokenRef) return { ok: false, message: `${trimmed}'s org.ethagent.token record is not a valid eip155 reference.` }
+  if (tokenRef.chainId !== registry.chainId) {
+    return { ok: false, message: `${trimmed}'s agent token is onchain ${tokenRef.chainId}, not the network you selected.` }
+  }
+  const finalRegistry: Erc8004RegistryConfig = registry.identityRegistryAddress.toLowerCase() === tokenRef.identityRegistryAddress.toLowerCase()
+    ? registry
+    : { ...registry, identityRegistryAddress: tokenRef.identityRegistryAddress }
+  let owner: Address
+  try {
+    const publicClient = createErc8004PublicClient(finalRegistry)
+    owner = await publicClient.readContract({
+      address: finalRegistry.identityRegistryAddress,
+      abi: [{ inputs: [{ name: 'tokenId', type: 'uint256' }], name: 'ownerOf', outputs: [{ name: '', type: 'address' }], stateMutability: 'view', type: 'function' }] as const,
+      functionName: 'ownerOf',
+      args: [tokenRef.agentId],
+    }) as Address
+  } catch (err: unknown) {
+    return { ok: false, message: `Could not read ownerOf(token #${tokenRef.agentId.toString()}): ${err instanceof Error ? err.message : String(err)}` }
+  }
+  try {
+    const candidate = await discoverOwnedAgentBackupByTokenId({
+      ...finalRegistry,
+      ownerHandle: owner,
+      ipfsApiUrl: DEFAULT_IPFS_API_URL,
+      tokenId: tokenRef.agentId,
+    })
+    return { ok: true, candidate }
+  } catch (err: unknown) {
+    return { ok: false, message: `Could not load agent token #${tokenRef.agentId.toString()}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}
+
+export async function resolveAgentTokenIdToCandidate(
+  rawTokenId: string,
+  registry: Erc8004RegistryConfig,
+): Promise<AgentEnsResolution> {
+  const trimmed = rawTokenId.trim()
+  if (!trimmed) return { ok: false, message: 'Enter the agent token ID (e.g. 45744).' }
+  if (!/^\d+$/.test(trimmed)) return { ok: false, message: 'Token ID must be a positive integer (e.g. 45744).' }
+  let tokenId: bigint
+  try {
+    tokenId = BigInt(trimmed)
+  } catch {
+    return { ok: false, message: 'Token ID must be a positive integer (e.g. 45744).' }
+  }
+  let owner: Address
+  try {
+    const publicClient = createErc8004PublicClient(registry)
+    owner = await publicClient.readContract({
+      address: registry.identityRegistryAddress,
+      abi: [{ inputs: [{ name: 'tokenId', type: 'uint256' }], name: 'ownerOf', outputs: [{ name: '', type: 'address' }], stateMutability: 'view', type: 'function' }] as const,
+      functionName: 'ownerOf',
+      args: [tokenId],
+    }) as Address
+  } catch (err: unknown) {
+    return { ok: false, message: `Token #${trimmed} not found on this network: ${err instanceof Error ? err.message : String(err)}` }
+  }
+  try {
+    const candidate = await discoverOwnedAgentBackupByTokenId({
+      ...registry,
+      ownerHandle: owner,
+      ipfsApiUrl: DEFAULT_IPFS_API_URL,
+      tokenId,
+    })
+    return { ok: true, candidate }
+  } catch (err: unknown) {
+    return { ok: false, message: `Could not load agent token #${trimmed}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}

package/src/identity/hub/effects/restore/restoreEffects.ts

@@ -0,0 +1,22 @@
+export {
+  canRestoreCandidate,
+  restoreTokenSelectionStep,
+  runRestoreDiscover,
+} from './discover.js'
+export {
+  resolveAgentEnsToCandidate,
+  resolveAgentTokenIdToCandidate,
+} from './resolve.js'
+export {
+  restoreSignatureRequestForStep,
+  runRestoreConnectWallet,
+} from './auth.js'
+export {
+  runRestoreFetch,
+} from './fetch.js'
+export {
+  runRestoreAuthorize,
+} from './apply.js'
+export {
+  runRecoveryRefetch,
+} from './recovery.js'

package/src/identity/hub/effects/restore/shared.ts

@@ -0,0 +1,91 @@
+import { getAddress, isAddress, type Address } from 'viem'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+import {
+  type ContinuitySnapshotEnvelope,
+  type TransferContinuitySnapshotEnvelope,
+} from '../../../continuity/envelope.js'
+import { catFromIpfs } from '../../../storage/ipfs.js'
+import type { Erc8004AgentCandidate } from '../../../registry/erc8004.js'
+import { writePublicSkillsFile } from '../../../continuity/storage.js'
+import { normalizeApprovedOperatorWallets } from '../../operatorWallets.js'
+
+export type BackupMetadata = NonNullable<EthagentIdentity['backup']>
+
+export function isAbortError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false
+  const name = (err as { name?: unknown }).name
+  return name === 'AbortError'
+}
+
+export function requesterAddressFromHandle(handle: string): Address | undefined {
+  return isAddress(handle, { strict: false }) ? getAddress(handle) : undefined
+}
+
+export function isTransferContinuitySnapshot(
+  envelope: ContinuitySnapshotEnvelope,
+): envelope is TransferContinuitySnapshotEnvelope {
+  return (envelope as TransferContinuitySnapshotEnvelope).crypto?.decryptsWith === 'transfer-signature-slot'
+    && typeof (envelope as TransferContinuitySnapshotEnvelope).targetAddress === 'string'
+    && !!(envelope as TransferContinuitySnapshotEnvelope).slots
+}
+
+export function restoreTransferSlotForRequester(
+  envelope: TransferContinuitySnapshotEnvelope,
+  requesterAddress: Address,
+): TransferContinuitySnapshotEnvelope['slots']['owner'] | null {
+  if (requesterAddress.toLowerCase() === getAddress(envelope.ownerAddress).toLowerCase()) {
+    return envelope.slots.owner
+  }
+  if (requesterAddress.toLowerCase() === getAddress(envelope.targetAddress).toLowerCase()) {
+    return envelope.slots.target
+  }
+  return null
+}
+
+export function isAuthorizedOperatorAddress(candidate: Erc8004AgentCandidate, address: Address): boolean {
+  const target = address.toLowerCase()
+  if (candidate.operators?.activeOperatorAddress?.toLowerCase() === target) return true
+  return candidate.operators?.approvedOperatorWallets.some(record => record.address.toLowerCase() === target) ?? false
+}
+
+export function ownerCandidateAddresses(candidate: Erc8004AgentCandidate): Address[] {
+  const out: Address[] = []
+  const seen = new Set<string>()
+  const push = (addr: Address | undefined): void => {
+    if (!addr) return
+    const lower = addr.toLowerCase()
+    if (seen.has(lower)) return
+    seen.add(lower)
+    out.push(getAddress(addr))
+  }
+  push(candidate.ownerAddress)
+  return out
+}
+
+export function operatorStateFromCandidate(candidate: Erc8004AgentCandidate): Record<string, unknown> {
+  const operators = candidate.operators
+  if (!operators) return {}
+  return {
+    approvedOperatorWallets: normalizeApprovedOperatorWallets(operators.approvedOperatorWallets),
+    ...(operators.activeOperatorAddress ? { activeOperatorAddress: operators.activeOperatorAddress } : {}),
+    ...(operators.ownerAddress ? { ownerAddress: operators.ownerAddress } : {}),
+    ...(operators.ensName ? { ensName: operators.ensName } : {}),
+    ...(operators.restoreAccessEpoch ? { restoreAccessEpoch: operators.restoreAccessEpoch } : {}),
+    ...(operators.ownerRestoreAccessKey ? { ownerRestoreAccessKey: operators.ownerRestoreAccessKey } : {}),
+  }
+}
+
+export async function restorePublishedPublicSkills(
+  identity: EthagentIdentity,
+  apiUrl: string,
+  cid: string | undefined,
+): Promise<boolean> {
+  if (!cid) return false
+  try {
+    const raw = await catFromIpfs(apiUrl, cid)
+    await writePublicSkillsFile(identity, new TextDecoder().decode(raw))
+    return true
+  } catch {
+    return false
+  }
+}