ethagent 3.0.2 → 3.1.0

package/src/identity/continuity/payloadNormalization.ts

@@ -0,0 +1,183 @@
+import { toChecksumAddress } from '../crypto/eth.js'
+import { normalizeContinuitySkills } from './skillsNormalization.js'
+import type {
+  ContinuityAgentSnapshot,
+  ContinuityFiles,
+  ContinuitySnapshotPayload,
+  TransferContinuitySnapshotSlot,
+  WalletContinuityRestoreAccessKey,
+  WalletContinuitySnapshotSlot,
+} from './envelope.js'
+
+type ContinuityTranscriptSummary = {
+  sessionId?: string
+  createdAt?: string
+  summary: string
+}
+
+export function continuityPayloadFromArgs(args: {
+  ownerAddress: string
+  createdAt: string
+  payload: Omit<ContinuitySnapshotPayload, 'version' | 'ownerAddress' | 'createdAt'> & { createdAt?: string }
+}): ContinuitySnapshotPayload {
+  const skills = normalizeContinuitySkills(args.payload.skills)
+  return {
+    version: 1,
+    ownerAddress: args.ownerAddress,
+    createdAt: args.createdAt,
+    ...(args.payload.sequence !== undefined ? { sequence: args.payload.sequence } : {}),
+    agent: normalizeAgentSnapshot(args.payload.agent),
+    files: normalizeContinuityFiles(args.payload.files),
+    ...(skills ? { skills } : {}),
+    transcript: normalizeTranscript(args.payload.transcript),
+    state: normalizeState(args.payload.state),
+  }
+}
+
+export function normalizeContinuityPayload(input: unknown): ContinuitySnapshotPayload {
+  if (!input || typeof input !== 'object') throw new Error('Continuity snapshot payload is invalid')
+  const obj = input as Partial<ContinuitySnapshotPayload>
+  if (obj.version !== 1) throw new Error('Continuity snapshot payload version is invalid')
+  if (typeof obj.ownerAddress !== 'string') throw new Error('Continuity snapshot owner is invalid')
+  if (typeof obj.createdAt !== 'string') throw new Error('Continuity snapshot timestamp is invalid')
+  const skills = normalizeContinuitySkills(obj.skills)
+  return {
+    version: 1,
+    ownerAddress: toChecksumAddress(obj.ownerAddress),
+    createdAt: obj.createdAt,
+    ...(typeof obj.sequence === 'number' && Number.isSafeInteger(obj.sequence) ? { sequence: obj.sequence } : {}),
+    agent: normalizeAgentSnapshot(obj.agent),
+    files: normalizeContinuityFiles(obj.files),
+    ...(skills ? { skills } : {}),
+    transcript: normalizeTranscript(obj.transcript),
+    state: normalizeState(obj.state),
+  }
+}
+
+export function normalizeAgentSnapshot(input: unknown): ContinuityAgentSnapshot {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
+  const obj = input as Record<string, unknown>
+  return {
+    ...(typeof obj.chainId === 'number' && Number.isSafeInteger(obj.chainId) && obj.chainId > 0 ? { chainId: obj.chainId } : {}),
+    ...(typeof obj.identityRegistryAddress === 'string' ? { identityRegistryAddress: obj.identityRegistryAddress } : {}),
+    ...(typeof obj.agentId === 'string' ? { agentId: obj.agentId } : {}),
+    ...(typeof obj.agentUri === 'string' ? { agentUri: obj.agentUri } : {}),
+    ...(typeof obj.metadataCid === 'string' ? { metadataCid: obj.metadataCid } : {}),
+    ...(typeof obj.name === 'string' ? { name: obj.name } : {}),
+    ...(typeof obj.description === 'string' ? { description: obj.description } : {}),
+  }
+}
+
+export function normalizeContinuityFiles(input: unknown): ContinuityFiles {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Continuity snapshot files are invalid')
+  }
+  const obj = input as Partial<ContinuityFiles>
+  if (typeof obj['SOUL.md'] !== 'string') throw new Error('SOUL.md is missing from continuity snapshot')
+  if (typeof obj['MEMORY.md'] !== 'string') throw new Error('MEMORY.md is missing from continuity snapshot')
+  return {
+    'SOUL.md': obj['SOUL.md'],
+    'MEMORY.md': obj['MEMORY.md'],
+  }
+}
+
+export function normalizeTranscript(input: unknown): ContinuityTranscriptSummary[] {
+  if (!Array.isArray(input)) return []
+  return input.flatMap(item => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return []
+    const obj = item as Partial<ContinuityTranscriptSummary>
+    if (typeof obj.summary !== 'string' || !obj.summary.trim()) return []
+    return [{
+      ...(typeof obj.sessionId === 'string' ? { sessionId: obj.sessionId } : {}),
+      ...(typeof obj.createdAt === 'string' ? { createdAt: obj.createdAt } : {}),
+      summary: obj.summary,
+    }]
+  })
+}
+
+export function normalizeState(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
+  return input as Record<string, unknown>
+}
+
+export function normalizeTransferSlot(input: unknown, expectedAddress: string): TransferContinuitySnapshotSlot {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Continuity transfer slot is invalid')
+  }
+  const obj = input as Partial<TransferContinuitySnapshotSlot>
+  if (typeof obj.address !== 'string') throw new Error('Continuity transfer slot address is invalid')
+  const address = toChecksumAddress(obj.address)
+  if (address.toLowerCase() !== expectedAddress.toLowerCase()) {
+    throw new Error('Continuity transfer slot address mismatch')
+  }
+  if (typeof obj.challenge !== 'string') throw new Error('Continuity transfer slot challenge is invalid')
+  if (typeof obj.salt !== 'string') throw new Error('Continuity transfer slot salt is invalid')
+  if (typeof obj.nonce !== 'string') throw new Error('Continuity transfer slot nonce is invalid')
+  if (typeof obj.encryptedKey !== 'string') throw new Error('Continuity transfer slot key is invalid')
+  if (typeof obj.tag !== 'string') throw new Error('Continuity transfer slot tag is invalid')
+  return {
+    address,
+    challenge: obj.challenge,
+    salt: obj.salt,
+    nonce: obj.nonce,
+    encryptedKey: obj.encryptedKey,
+    tag: obj.tag,
+  }
+}
+
+export function normalizeWalletRestoreAccessKeys(input: unknown): WalletContinuityRestoreAccessKey[] {
+  if (!Array.isArray(input)) return []
+  const out: WalletContinuityRestoreAccessKey[] = []
+  const seen = new Set<string>()
+  for (const item of input) {
+    const key = normalizeWalletRestoreAccessKey(item)
+    const dedupe = key.address.toLowerCase()
+    if (seen.has(dedupe)) continue
+    seen.add(dedupe)
+    out.push(key)
+  }
+  return out.sort((a, b) => a.address.toLowerCase().localeCompare(b.address.toLowerCase()))
+}
+
+export function normalizeWalletRestoreAccessKey(input: unknown): WalletContinuityRestoreAccessKey {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Wallet restore access key is invalid')
+  }
+  const obj = input as Partial<WalletContinuityRestoreAccessKey>
+  if (typeof obj.address !== 'string') throw new Error('Wallet restore access address is invalid')
+  if (typeof obj.challenge !== 'string') throw new Error('Wallet restore access challenge is invalid')
+  if (typeof obj.salt !== 'string') throw new Error('Wallet restore access salt is invalid')
+  if (typeof obj.kemPublicKey !== 'string') throw new Error('Wallet restore access public key is invalid')
+  return {
+    address: toChecksumAddress(obj.address),
+    challenge: obj.challenge,
+    salt: obj.salt,
+    kemPublicKey: obj.kemPublicKey,
+    ...(typeof obj.createdAt === 'string' ? { createdAt: obj.createdAt } : {}),
+  }
+}
+
+export function normalizeWalletSlot(input: unknown): WalletContinuitySnapshotSlot {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Continuity wallet slot is invalid')
+  }
+  const obj = input as Partial<WalletContinuitySnapshotSlot>
+  if (typeof obj.address !== 'string') throw new Error('Continuity wallet slot address is invalid')
+  if (typeof obj.challenge !== 'string') throw new Error('Continuity wallet slot challenge is invalid')
+  if (typeof obj.salt !== 'string') throw new Error('Continuity wallet slot salt is invalid')
+  if (typeof obj.kemPublicKey !== 'string') throw new Error('Continuity wallet slot public key is invalid')
+  if (typeof obj.kemCiphertext !== 'string') throw new Error('Continuity wallet slot ciphertext is invalid')
+  if (typeof obj.nonce !== 'string') throw new Error('Continuity wallet slot nonce is invalid')
+  if (typeof obj.encryptedKey !== 'string') throw new Error('Continuity wallet slot key is invalid')
+  if (typeof obj.tag !== 'string') throw new Error('Continuity wallet slot tag is invalid')
+  return {
+    address: toChecksumAddress(obj.address),
+    challenge: obj.challenge,
+    salt: obj.salt,
+    kemPublicKey: obj.kemPublicKey,
+    kemCiphertext: obj.kemCiphertext,
+    nonce: obj.nonce,
+    encryptedKey: obj.encryptedKey,
+    tag: obj.tag,
+  }
+}

package/src/identity/continuity/skills/loadSkills.ts

@@ -6,6 +6,16 @@ import { ensureContinuityVault } from '../storage/files.js'
 import { continuityVaultRef } from '../storage/paths.js'
 import { parseSkillFile } from './frontmatter.js'
 import { defaultSkillScaffold } from './scaffold.js'
+import {
+  isReservedWindowsSegment,
+  isValidFilenameSegment,
+  isValidSegment,
+  isValidSkillEntryKey,
+  isValidSkillFilePath,
+  isWithin,
+  MAX_FOLDER_DEPTH,
+  SKILL_FILE_NAME,
+} from './skillPaths.js'
 import type {
   ContinuitySkillsTree,
   Skill,
@@ -13,18 +23,9 @@ import type {
   SkillVisibility,
 } from './types.js'
 
-const SKILL_FILE_NAME = 'SKILL.md'
-const SEGMENT_RE = /^[A-Za-z0-9._-]+$/
-const FILE_EXT_RE = /\.[A-Za-z0-9]+$/
-const RESERVED_WINDOWS_SEGMENTS = new Set([
-  'con', 'prn', 'aux', 'nul',
-  'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
-  'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
-])
 const MAX_SKILL_ENTRIES = 200
 const MAX_SKILL_FILE_BYTES = 256 * 1024
 const MAX_TREE_FILES = 500
-const MAX_FOLDER_DEPTH = 4
 
 type IdentityKey = Pick<EthagentIdentity, 'chainId' | 'identityRegistryAddress' | 'agentId' | 'address'>
 
@@ -135,13 +136,6 @@ async function walkSkillFileStats(root: string): Promise<SkillFileStat[]> {
   return out
 }
 
-function isValidSegment(name: string): boolean {
-  if (!name) return false
-  if (name.startsWith('.')) return false
-  if (RESERVED_WINDOWS_SEGMENTS.has(name.toLowerCase())) return false
-  return SEGMENT_RE.test(name)
-}
-
 export async function readSkill(identity: EthagentIdentity, name: string): Promise<Skill> {
   const entries = await listSkills(identity)
   const lookup = name.replace(/^.*:/, '').replace(/:SKILL$/i, '')
@@ -444,7 +438,7 @@ async function walkFolderFiles(
   for (const ent of dirents) {
     if (ent.isSymbolicLink()) continue
     if (ent.name.startsWith('.')) continue
-    if (RESERVED_WINDOWS_SEGMENTS.has(ent.name.toLowerCase())) continue
+    if (isReservedWindowsSegment(ent.name)) continue
     if (ent.isDirectory()) {
       if (!isValidSegment(ent.name)) continue
       const nextPrefix = relativePrefix ? `${relativePrefix}/${ent.name}` : ent.name
@@ -465,14 +459,6 @@ async function walkFolderFiles(
   }
 }
 
-function isValidFilenameSegment(name: string): boolean {
-  if (!name) return false
-  if (name.startsWith('.')) return false
-  if (RESERVED_WINDOWS_SEGMENTS.has(name.toLowerCase())) return false
-  if (!SEGMENT_RE.test(name)) return false
-  return FILE_EXT_RE.test(name)
-}
-
 async function statOrNull(file: string): Promise<import('node:fs').Stats | null> {
   try {
     return await fs.stat(file)
@@ -563,47 +549,4 @@ async function loadSkillBody(entry: SkillIndexEntry): Promise<Skill> {
   return { ...entry, body: parsed.body }
 }
 
-export function isValidSkillEntryKey(rel: string): boolean {
-  if (!rel || rel.length > 256) return false
-  if (rel.includes('\0')) return false
-  if (rel.startsWith('/') || rel.startsWith('\\')) return false
-  if (/^[a-zA-Z]:/.test(rel)) return false
-  const segments = rel.split('/')
-  if (segments.length !== 2) return false
-  const [name, filename] = segments
-  if (!name || !filename) return false
-  if (filename !== SKILL_FILE_NAME) return false
-  if (!isValidSegment(name)) return false
-  return true
-}
-
-export function isValidSkillFilePath(rel: string): boolean {
-  if (!rel || rel.length > 256) return false
-  if (rel.includes('\0')) return false
-  if (rel.startsWith('/') || rel.startsWith('\\')) return false
-  if (/^[a-zA-Z]:/.test(rel)) return false
-  const segments = rel.split('/')
-  if (segments.length < 2) return false
-  if (segments.length > MAX_FOLDER_DEPTH + 2) return false
-  const [first, ...rest] = segments
-  if (!first || !isValidSegment(first)) return false
-  for (let i = 0; i < rest.length; i++) {
-    const seg = rest[i]
-    if (!seg) return false
-    if (i === rest.length - 1) {
-      if (seg === SKILL_FILE_NAME) continue
-      if (!isValidFilenameSegment(seg)) return false
-    } else {
-      if (!isValidSegment(seg)) return false
-    }
-  }
-  return true
-}
-
-function isWithin(root: string, target: string): boolean {
-  const rootResolved = path.resolve(root)
-  const targetResolved = path.resolve(target)
-  if (targetResolved === rootResolved) return true
-  const prefix = rootResolved.endsWith(path.sep) ? rootResolved : rootResolved + path.sep
-  return targetResolved.startsWith(prefix)
-}
+export { isValidSkillEntryKey, isValidSkillFilePath } from './skillPaths.js'

package/src/identity/continuity/skills/skillPaths.ts

@@ -0,0 +1,76 @@
+import path from 'node:path'
+
+export const SKILL_FILE_NAME = 'SKILL.md'
+export const MAX_FOLDER_DEPTH = 4
+
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/
+const FILE_EXT_RE = /\.[A-Za-z0-9]+$/
+const RESERVED_WINDOWS_SEGMENTS = new Set([
+  'con', 'prn', 'aux', 'nul',
+  'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
+  'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
+])
+
+export function isReservedWindowsSegment(name: string): boolean {
+  return RESERVED_WINDOWS_SEGMENTS.has(name.toLowerCase())
+}
+
+export function isValidSegment(name: string): boolean {
+  if (!name) return false
+  if (name.startsWith('.')) return false
+  if (isReservedWindowsSegment(name)) return false
+  return SEGMENT_RE.test(name)
+}
+
+export function isValidFilenameSegment(name: string): boolean {
+  if (!name) return false
+  if (name.startsWith('.')) return false
+  if (isReservedWindowsSegment(name)) return false
+  if (!SEGMENT_RE.test(name)) return false
+  return FILE_EXT_RE.test(name)
+}
+
+export function isValidSkillEntryKey(rel: string): boolean {
+  if (!rel || rel.length > 256) return false
+  if (rel.includes('\0')) return false
+  if (rel.startsWith('/') || rel.startsWith('\\')) return false
+  if (/^[a-zA-Z]:/.test(rel)) return false
+  const segments = rel.split('/')
+  if (segments.length !== 2) return false
+  const [name, filename] = segments
+  if (!name || !filename) return false
+  if (filename !== SKILL_FILE_NAME) return false
+  if (!isValidSegment(name)) return false
+  return true
+}
+
+export function isValidSkillFilePath(rel: string): boolean {
+  if (!rel || rel.length > 256) return false
+  if (rel.includes('\0')) return false
+  if (rel.startsWith('/') || rel.startsWith('\\')) return false
+  if (/^[a-zA-Z]:/.test(rel)) return false
+  const segments = rel.split('/')
+  if (segments.length < 2) return false
+  if (segments.length > MAX_FOLDER_DEPTH + 2) return false
+  const [first, ...rest] = segments
+  if (!first || !isValidSegment(first)) return false
+  for (let i = 0; i < rest.length; i++) {
+    const seg = rest[i]
+    if (!seg) return false
+    if (i === rest.length - 1) {
+      if (seg === SKILL_FILE_NAME) continue
+      if (!isValidFilenameSegment(seg)) return false
+    } else {
+      if (!isValidSegment(seg)) return false
+    }
+  }
+  return true
+}
+
+export function isWithin(root: string, target: string): boolean {
+  const rootResolved = path.resolve(root)
+  const targetResolved = path.resolve(target)
+  if (targetResolved === rootResolved) return true
+  const prefix = rootResolved.endsWith(path.sep) ? rootResolved : rootResolved + path.sep
+  return targetResolved.startsWith(prefix)
+}

package/src/identity/continuity/skillsNormalization.ts

@@ -0,0 +1,119 @@
+import type { ContinuitySkillsTree } from './envelope.js'
+
+const PRIVATE_SKILL_FILE_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+$/
+const PRIVATE_SKILL_LAST_SEG_FILE_RE = /^[A-Za-z0-9._-]+\.[A-Za-z0-9]+$/
+const LEGACY_NESTED_SKILL_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/.+$/
+const LEGACY_FLAT_NAME_MD_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\.md$/i
+const MAX_PRIVATE_SKILL_ENTRIES = 500
+const MAX_PRIVATE_SKILL_BODY_BYTES = 256 * 1024
+const MAX_PRIVATE_SKILL_PATH_LEN = 256
+
+export function normalizeContinuitySkills(input: unknown): ContinuitySkillsTree | undefined {
+  if (input === undefined || input === null) return undefined
+  if (typeof input !== 'object' || Array.isArray(input)) return undefined
+  const obj = input as Record<string, unknown>
+  const out: ContinuitySkillsTree = {}
+  let count = 0
+  const tryInsert = (key: string, rawValue: unknown): void => {
+    if (count >= MAX_PRIVATE_SKILL_ENTRIES) return
+    if (typeof rawValue !== 'string') return
+    if (key.length === 0 || key.length > MAX_PRIVATE_SKILL_PATH_LEN) return
+    if (key.includes('\0')) return
+    if (key.includes('..')) return
+    if (key.startsWith('/')) return
+    if (/^[A-Za-z]:/.test(key)) return
+    if (!isAcceptableSkillKey(key)) return
+    if (Buffer.byteLength(rawValue, 'utf8') > MAX_PRIVATE_SKILL_BODY_BYTES) return
+    if (out[key] !== undefined) return
+    out[key] = rawValue
+    count++
+  }
+  const legacyRoots = new Set<string>()
+  const realSkillFolders = new Set<string>()
+  for (const rawKey of Object.keys(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    const segments = key.split('/')
+    if (segments.length === 3 && segments[2] === 'SKILL.md' && segments[0] && segments[1]) {
+      legacyRoots.add(`${segments[0]}/${segments[1]}`)
+    }
+    if (segments.length === 2 && segments[1] === 'SKILL.md' && segments[0]) {
+      realSkillFolders.add(segments[0])
+    }
+  }
+  for (const [rawKey, rawValue] of Object.entries(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    if (!isCanonicalFlatKey(key)) continue
+    if (isUnderLegacyRoot(key, legacyRoots)) continue
+    if (!keyHasRealSkillFolder(key, realSkillFolders)) continue
+    tryInsert(key, rawValue)
+  }
+  for (const [rawKey, rawValue] of Object.entries(obj)) {
+    const key = rawKey.replace(/\\/g, '/')
+    if (
+      isCanonicalFlatKey(key)
+      && !isUnderLegacyRoot(key, legacyRoots)
+      && keyHasRealSkillFolder(key, realSkillFolders)
+    ) continue
+    const upgraded = upgradeLegacySkillKey(key, legacyRoots)
+    if (!upgraded) continue
+    tryInsert(upgraded, rawValue)
+  }
+  return count > 0 ? out : undefined
+}
+
+function isUnderLegacyRoot(key: string, legacyRoots: Set<string>): boolean {
+  for (const root of legacyRoots) {
+    if (key === `${root}/SKILL.md`) return true
+    if (key.startsWith(`${root}/`)) return true
+  }
+  return false
+}
+
+function keyHasRealSkillFolder(key: string, realSkillFolders: Set<string>): boolean {
+  const first = key.split('/')[0]
+  if (!first) return false
+  return realSkillFolders.has(first)
+}
+
+function isCanonicalFlatKey(key: string): boolean {
+  if (!PRIVATE_SKILL_FILE_RE.test(key)) return false
+  const segments = key.split('/')
+  if (segments.length < 2) return false
+  const last = segments[segments.length - 1]!
+  if (last === 'SKILL.md') return segments.length === 2
+  return PRIVATE_SKILL_LAST_SEG_FILE_RE.test(last)
+}
+
+function isAcceptableSkillKey(key: string): boolean {
+  return isCanonicalFlatKey(key)
+}
+
+function upgradeLegacySkillKey(key: string, legacyRoots: Set<string>): string | null {
+  for (const root of legacyRoots) {
+    if (key === `${root}/SKILL.md` || key.startsWith(`${root}/`)) {
+      const [first, second] = root.split('/')
+      if (!first || !second) continue
+      const rest = key.slice(root.length + 1)
+      const flattened = `${first}-${second}/${rest}`
+      return isCanonicalFlatKey(flattened) ? flattened : null
+    }
+  }
+  if (LEGACY_FLAT_NAME_MD_RE.test(key)) {
+    const [category, file] = key.split('/')
+    if (!category || !file) return null
+    const slug = file.replace(/\.md$/i, '')
+    if (!slug) return null
+    const flattened = `${category}-${slug}/SKILL.md`
+    return isCanonicalFlatKey(flattened) ? flattened : null
+  }
+  if (LEGACY_NESTED_SKILL_RE.test(key)) {
+    const segments = key.split('/')
+    if (segments.length < 3) return null
+    const [first, second, ...rest] = segments
+    if (!first || !second || rest.length === 0) return null
+    const flattened = `${first}-${second}/${rest.join('/')}`
+    return isCanonicalFlatKey(flattened) ? flattened : null
+  }
+  if (isCanonicalFlatKey(key)) return key
+  return null
+}

package/src/identity/continuity/snapshotToken.ts

@@ -0,0 +1,28 @@
+import { toChecksumAddress } from '../crypto/eth.js'
+
+export type ContinuitySnapshotToken = {
+  chainId: number
+  identityRegistryAddress: string
+  agentId: string
+}
+
+export function normalizeContinuitySnapshotToken(input: unknown): ContinuitySnapshotToken {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Continuity snapshot token is invalid')
+  }
+  const obj = input as Partial<ContinuitySnapshotToken>
+  if (typeof obj.chainId !== 'number' || !Number.isSafeInteger(obj.chainId) || obj.chainId <= 0) {
+    throw new Error('Continuity snapshot token chain is invalid')
+  }
+  if (typeof obj.identityRegistryAddress !== 'string') {
+    throw new Error('Continuity snapshot token registry is invalid')
+  }
+  if (typeof obj.agentId !== 'string' || !/^\d+$/.test(obj.agentId)) {
+    throw new Error('Continuity snapshot token id is invalid')
+  }
+  return {
+    chainId: obj.chainId,
+    identityRegistryAddress: toChecksumAddress(obj.identityRegistryAddress),
+    agentId: obj.agentId,
+  }
+}

package/src/identity/hub/continuity/completion.ts

@@ -0,0 +1,67 @@
+import type { EthagentIdentity } from '../../../storage/config.js'
+import type { WalletPurpose } from '../../wallet/browserWallet.js'
+import type { ProfileUpdates } from '../identityHubReducer.js'
+import { snapshotSaveWalletRole } from './snapshot.js'
+
+export function rebackupWalletPurpose(
+  identity: EthagentIdentity,
+  profileUpdates: ProfileUpdates | undefined,
+): WalletPurpose {
+  const role = snapshotSaveWalletRole(identity, profileUpdates)
+  const snapshotPurpose = role === 'operator'
+    ? 'update-snapshot-operator' as const
+    : role === 'owner'
+      ? 'update-snapshot-owner' as const
+      : 'update-snapshot-connected' as const
+  const profilePurpose = role === 'operator'
+    ? 'update-profile-operator' as const
+    : role === 'owner'
+      ? 'update-profile-owner' as const
+      : 'update-profile-connected' as const
+  if (!profileUpdates) return snapshotPurpose
+  const baseState = (identity.state ?? {}) as Record<string, unknown>
+  const currentEns = typeof baseState.ensName === 'string' ? baseState.ensName.trim() : ''
+  const ensTouched = typeof profileUpdates.ensName === 'string'
+  const profileFieldsTouched = profileUpdates.name !== undefined
+    || profileUpdates.description !== undefined
+    || profileUpdates.imagePath !== undefined
+  const operatorFieldsTouched = profileUpdates.ownerAddress !== undefined
+    || profileUpdates.approvedOperatorWallets !== undefined
+    || profileUpdates.activeOperatorAddress !== undefined
+    || profileUpdates.restoreAccessEpoch !== undefined
+  if (operatorFieldsTouched && !ensTouched && !profileFieldsTouched) return 'update-operators'
+  if (ensTouched && !profileFieldsTouched) {
+    const next = (profileUpdates.ensName ?? '').trim()
+    if (!next && currentEns) return 'clear-ens'
+    return 'update-ens'
+  }
+  if (profileFieldsTouched) return profilePurpose
+  return snapshotPurpose
+}
+
+export function rebackupCompletionMessage(
+  profileUpdates: ProfileUpdates | undefined,
+  identity: EthagentIdentity,
+  ensOk?: boolean,
+): string {
+  if (!profileUpdates) return 'Backup Saved'
+  const baseState = (identity.state ?? {}) as Record<string, unknown>
+  const currentEns = typeof baseState.ensName === 'string' ? baseState.ensName.trim() : ''
+  const ensTouched = typeof profileUpdates.ensName === 'string'
+  const profileFieldsTouched = profileUpdates.name !== undefined
+    || profileUpdates.description !== undefined
+    || profileUpdates.imagePath !== undefined
+  const operatorFieldsTouched = profileUpdates.ownerAddress !== undefined
+    || profileUpdates.approvedOperatorWallets !== undefined
+    || profileUpdates.activeOperatorAddress !== undefined
+    || profileUpdates.restoreAccessEpoch !== undefined
+  if (operatorFieldsTouched && !ensTouched && !profileFieldsTouched) return 'Operator Wallets Updated'
+  if (ensTouched && !profileFieldsTouched) {
+    const next = (profileUpdates.ensName ?? '').trim()
+    if (!next && currentEns) return 'ENS Unlinked'
+    if (next) return ensOk === false ? 'ENS Issue' : 'ENS Linked'
+    return 'ENS Updated'
+  }
+  if (profileFieldsTouched) return 'Profile Updated'
+  return 'Backup Saved'
+}

package/src/identity/hub/continuity/effects.ts

@@ -77,6 +77,10 @@ import {
   syncVaultOperatorsAfterOwnerSave,
 } from '../shared/effects/sync.js'
 import { runOperatorWalletRebackup } from './vault.js'
+import {
+  rebackupCompletionMessage,
+  rebackupWalletPurpose,
+} from './completion.js'
 
 type BackupMetadata = NonNullable<EthagentIdentity['backup']>
 type PublicSkillsMetadata = NonNullable<EthagentIdentity['publicSkills']>
@@ -418,65 +422,4 @@ export async function runRebackupStorageSubmit(
   callbacks.onStep({ kind: 'rebackup-signing', identity: step.identity, registry: step.registry, pinataJwt, profileUpdates: step.profileUpdates, returnTo: step.returnTo, walletPurpose: step.walletPurpose, vaultAddress: step.vaultAddress })
 }
 
-function rebackupWalletPurpose(
-  identity: EthagentIdentity,
-  profileUpdates: ProfileUpdates | undefined,
-): WalletPurpose {
-  const role = snapshotSaveWalletRole(identity, profileUpdates)
-  const snapshotPurpose = role === 'operator'
-    ? 'update-snapshot-operator' as const
-    : role === 'owner'
-      ? 'update-snapshot-owner' as const
-      : 'update-snapshot-connected' as const
-  const profilePurpose = role === 'operator'
-    ? 'update-profile-operator' as const
-    : role === 'owner'
-      ? 'update-profile-owner' as const
-      : 'update-profile-connected' as const
-  if (!profileUpdates) return snapshotPurpose
-  const baseState = (identity.state ?? {}) as Record<string, unknown>
-  const currentEns = typeof baseState.ensName === 'string' ? baseState.ensName.trim() : ''
-  const ensTouched = typeof profileUpdates.ensName === 'string'
-  const profileFieldsTouched = profileUpdates.name !== undefined
-    || profileUpdates.description !== undefined
-    || profileUpdates.imagePath !== undefined
-  const operatorFieldsTouched = profileUpdates.ownerAddress !== undefined
-    || profileUpdates.approvedOperatorWallets !== undefined
-    || profileUpdates.activeOperatorAddress !== undefined
-    || profileUpdates.restoreAccessEpoch !== undefined
-  if (operatorFieldsTouched && !ensTouched && !profileFieldsTouched) return 'update-operators'
-  if (ensTouched && !profileFieldsTouched) {
-    const next = (profileUpdates.ensName ?? '').trim()
-    if (!next && currentEns) return 'clear-ens'
-    return 'update-ens'
-  }
-  if (profileFieldsTouched) return profilePurpose
-  return snapshotPurpose
-}
-
-export function rebackupCompletionMessage(
-  profileUpdates: ProfileUpdates | undefined,
-  identity: EthagentIdentity,
-  ensOk?: boolean,
-): string {
-  if (!profileUpdates) return 'Backup Saved'
-  const baseState = (identity.state ?? {}) as Record<string, unknown>
-  const currentEns = typeof baseState.ensName === 'string' ? baseState.ensName.trim() : ''
-  const ensTouched = typeof profileUpdates.ensName === 'string'
-  const profileFieldsTouched = profileUpdates.name !== undefined
-    || profileUpdates.description !== undefined
-    || profileUpdates.imagePath !== undefined
-  const operatorFieldsTouched = profileUpdates.ownerAddress !== undefined
-    || profileUpdates.approvedOperatorWallets !== undefined
-    || profileUpdates.activeOperatorAddress !== undefined
-    || profileUpdates.restoreAccessEpoch !== undefined
-  if (operatorFieldsTouched && !ensTouched && !profileFieldsTouched) return 'Operator Wallets Updated'
-  if (ensTouched && !profileFieldsTouched) {
-    const next = (profileUpdates.ensName ?? '').trim()
-    if (!next && currentEns) return 'ENS Unlinked'
-    if (next) return ensOk === false ? 'ENS Issue' : 'ENS Linked'
-    return 'ENS Updated'
-  }
-  if (profileFieldsTouched) return 'Profile Updated'
-  return 'Backup Saved'
-}
+export { rebackupCompletionMessage } from './completion.js'