ethagent 1.1.2 → 2.0.0

package/src/identity/crypto/backupEnvelope.ts

@@ -1,58 +1,15 @@
 import crypto from 'node:crypto'
 import { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
-import { addressFromPrivateKey, recoverAddressFromSignature, toChecksumAddress, validatePrivateKey } from './eth.js'
+import { recoverAddressFromSignature, toChecksumAddress } from './eth.js'
 
-export const BACKUP_ENVELOPE_VERSION = 'ethagent-pq-backup-v1'
 export const AGENT_STATE_BACKUP_ENVELOPE_VERSION = 'ethagent-state-backup-v1'
 
-type BackupPayload = {
-  privateKey: string
-  address: string
-  createdAt: string
-}
-
-export type AgentStatePayload = {
+type AgentStatePayload = {
   ownerAddress: string
   createdAt: string
   state: Record<string, unknown>
 }
 
-export type IdentityBackupEnvelope = {
-  version: 1
-  envelopeVersion: typeof BACKUP_ENVELOPE_VERSION
-  address: string
-  ownerAddress?: string
-  createdAt: string
-  challenge: string
-  walletSignature: string
-  crypto: {
-    kem: 'ML-KEM-768'
-    aead: 'AES-256-GCM'
-    kdf: 'HKDF-SHA256'
-    signature: 'EIP-191'
-  }
-  salt: string
-  kemPublicKey: string
-  kemCiphertext: string
-  nonce: string
-  ciphertext: string
-  tag: string
-}
-
-export type CreateIdentityBackupArgs = {
-  privateKey: string
-  recoveryPassphrase: string
-  walletSignature: string
-  createdAt?: string
-  ownerAddress?: string
-}
-
-export type RestoreIdentityBackupArgs = {
-  envelope: IdentityBackupEnvelope
-  recoveryPassphrase: string
-  walletSignature: string
-}
-
 export type AgentStateBackupEnvelope = {
   version: 1
   envelopeVersion: typeof AGENT_STATE_BACKUP_ENVELOPE_VERSION
@@ -73,14 +30,14 @@ export type AgentStateBackupEnvelope = {
   tag: string
 }
 
-export type CreateAgentStateBackupArgs = {
+type CreateAgentStateBackupArgs = {
   ownerAddress: string
   walletSignature: string
   state: Record<string, unknown>
   createdAt?: string
 }
 
-export type RestoreAgentStateBackupArgs = {
+type RestoreAgentStateBackupArgs = {
   envelope: AgentStateBackupEnvelope
   walletSignature: string
 }
@@ -90,121 +47,21 @@ export class AgentStateOwnerMismatchError extends Error {
     readonly backupOwner: string,
     readonly currentOwner: string,
   ) {
-    super('agent backup is encrypted for another wallet')
+    super('Agent backup is encrypted for another wallet')
     this.name = 'AgentStateOwnerMismatchError'
   }
 }
 
-export function createRecoveryChallenge(address: string): string {
-  const checksum = toChecksumAddress(address)
-  return [
-    'ethagent identity recovery v1',
-    `address: ${checksum}`,
-    'purpose: authorize encrypted portable agent backup',
-  ].join('\n')
-}
-
 export function createAgentStateRecoveryChallenge(ownerAddress: string): string {
   const checksum = toChecksumAddress(ownerAddress)
   return [
-    'ethagent encrypted state access',
+    'Encrypted State Access',
     `Owner: ${checksum}`,
     'Action: authorize this wallet to unlock the encrypted agent backup',
     'Version: 1',
   ].join('\n')
 }
 
-export function createIdentityBackupEnvelope(args: CreateIdentityBackupArgs): IdentityBackupEnvelope {
-  if (!validatePrivateKey(args.privateKey)) throw new Error('invalid private key')
-  if (args.recoveryPassphrase.length < 8) throw new Error('recovery passphrase must be at least 8 characters')
-
-  const address = addressFromPrivateKey(args.privateKey)
-  const ownerAddress = args.ownerAddress ? toChecksumAddress(args.ownerAddress) : undefined
-  const signingAddress = ownerAddress ?? address
-  const challenge = createRecoveryChallenge(signingAddress)
-  assertSignatureForAddress(challenge, args.walletSignature, signingAddress)
-
-  const createdAt = args.createdAt ?? new Date().toISOString()
-  const salt = crypto.randomBytes(32)
-  const kemSeed = deriveKemSeed(args.recoveryPassphrase, args.walletSignature, salt, address)
-  const kemKeys = ml_kem768.keygen(kemSeed)
-  const kem = ml_kem768.encapsulate(kemKeys.publicKey)
-  const key = deriveAesKey(args.recoveryPassphrase, args.walletSignature, kem.sharedSecret, salt, address)
-  const nonce = crypto.randomBytes(12)
-  const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce)
-  cipher.setAAD(aadFor(address, createdAt))
-  const plaintext = Buffer.from(JSON.stringify({
-    privateKey: normalizedPrivateKey(args.privateKey),
-    address,
-    createdAt,
-  } satisfies BackupPayload), 'utf8')
-  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()])
-  const tag = cipher.getAuthTag()
-
-  return {
-    version: 1,
-    envelopeVersion: BACKUP_ENVELOPE_VERSION,
-    address,
-    ...(ownerAddress ? { ownerAddress } : {}),
-    createdAt,
-    challenge,
-    walletSignature: args.walletSignature,
-    crypto: {
-      kem: 'ML-KEM-768',
-      aead: 'AES-256-GCM',
-      kdf: 'HKDF-SHA256',
-      signature: 'EIP-191',
-    },
-    salt: toBase64(salt),
-    kemPublicKey: toBase64(kemKeys.publicKey),
-    kemCiphertext: toBase64(kem.cipherText),
-    nonce: toBase64(nonce),
-    ciphertext: toBase64(encrypted),
-    tag: toBase64(tag),
-  }
-}
-
-export function restoreIdentityBackupEnvelope(args: RestoreIdentityBackupArgs): BackupPayload {
-  const envelope = normalizeEnvelope(args.envelope)
-  const signingAddress = envelope.ownerAddress ?? envelope.address
-  assertSignatureForAddress(envelope.challenge, args.walletSignature, signingAddress)
-  assertSignatureForAddress(envelope.challenge, envelope.walletSignature, signingAddress)
-
-  const salt = fromBase64(envelope.salt)
-  const kemSeed = deriveKemSeed(args.recoveryPassphrase, envelope.walletSignature, salt, envelope.address)
-  const kemKeys = ml_kem768.keygen(kemSeed)
-  const expectedPublicKey = toBase64(kemKeys.publicKey)
-  if (expectedPublicKey !== envelope.kemPublicKey) {
-    throw new Error('recovery credentials do not match this backup')
-  }
-
-  const sharedSecret = ml_kem768.decapsulate(fromBase64(envelope.kemCiphertext), kemKeys.secretKey)
-  const key = deriveAesKey(args.recoveryPassphrase, envelope.walletSignature, sharedSecret, salt, envelope.address)
-  const decipher = crypto.createDecipheriv('aes-256-gcm', key, fromBase64(envelope.nonce))
-  decipher.setAAD(aadFor(envelope.address, envelope.createdAt))
-  decipher.setAuthTag(fromBase64(envelope.tag))
-
-  let decoded: unknown
-  try {
-    const plaintext = Buffer.concat([
-      decipher.update(fromBase64(envelope.ciphertext)),
-      decipher.final(),
-    ]).toString('utf8')
-    decoded = JSON.parse(plaintext)
-  } catch {
-    throw new Error('could not decrypt backup with the supplied credentials')
-  }
-
-  if (!isBackupPayload(decoded)) throw new Error('backup payload is invalid')
-  if (decoded.address.toLowerCase() !== envelope.address.toLowerCase()) {
-    throw new Error('backup payload address mismatch')
-  }
-  if (addressFromPrivateKey(decoded.privateKey).toLowerCase() !== envelope.address.toLowerCase()) {
-    throw new Error('backup private key does not match address')
-  }
-  return decoded
-}
-
 export function createAgentStateBackupEnvelope(args: CreateAgentStateBackupArgs): AgentStateBackupEnvelope {
   const ownerAddress = toChecksumAddress(args.ownerAddress)
   const challenge = createAgentStateRecoveryChallenge(ownerAddress)
@@ -257,7 +114,7 @@ export function restoreAgentStateBackupEnvelope(args: RestoreAgentStateBackupArg
   const kemKeys = ml_kem768.keygen(kemSeed)
   const expectedPublicKey = toBase64(kemKeys.publicKey)
   if (expectedPublicKey !== envelope.kemPublicKey) {
-    throw new Error('wallet signature does not match this agent backup')
+    throw new Error('Wallet signature does not match this agent backup')
   }
 
   const sharedSecret = ml_kem768.decapsulate(fromBase64(envelope.kemCiphertext), kemKeys.secretKey)
@@ -274,12 +131,12 @@ export function restoreAgentStateBackupEnvelope(args: RestoreAgentStateBackupArg
     ]).toString('utf8')
     decoded = JSON.parse(plaintext)
   } catch {
-    throw new Error('could not decrypt agent state with the supplied wallet signature')
+    throw new Error('Could not decrypt agent state with the supplied wallet signature')
   }
 
-  if (!isAgentStatePayload(decoded)) throw new Error('agent state backup payload is invalid')
+  if (!isAgentStatePayload(decoded)) throw new Error('Agent state backup payload is invalid')
   if (decoded.ownerAddress.toLowerCase() !== envelope.ownerAddress.toLowerCase()) {
-    throw new Error('agent state backup owner mismatch')
+    throw new Error('Agent state backup owner mismatch')
   }
   return {
     ...decoded,
@@ -295,16 +152,6 @@ export function assertAgentStateBackupOwner(envelope: AgentStateBackupEnvelope,
   }
 }
 
-export function serializeIdentityBackupEnvelope(envelope: IdentityBackupEnvelope): string {
-  return JSON.stringify(normalizeEnvelope(envelope), null, 2)
-}
-
-export function parseIdentityBackupEnvelope(raw: string | Uint8Array): IdentityBackupEnvelope {
-  const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw)
-  const parsed = JSON.parse(text) as unknown
-  return normalizeEnvelope(parsed)
-}
-
 export function serializeAgentStateBackupEnvelope(envelope: AgentStateBackupEnvelope): string {
   return JSON.stringify(normalizeAgentStateEnvelope(envelope), null, 2)
 }
@@ -315,43 +162,11 @@ export function parseAgentStateBackupEnvelope(raw: string | Uint8Array): AgentSt
   return normalizeAgentStateEnvelope(parsed)
 }
 
-function normalizeEnvelope(input: unknown): IdentityBackupEnvelope {
-  if (!isEnvelope(input)) throw new Error('invalid identity backup envelope')
-  if (input.envelopeVersion !== BACKUP_ENVELOPE_VERSION) throw new Error('unsupported backup envelope version')
-  if (input.crypto.kem !== 'ML-KEM-768' || input.crypto.aead !== 'AES-256-GCM') {
-    throw new Error('unsupported backup crypto suite')
-  }
-  return {
-    ...input,
-    address: toChecksumAddress(input.address),
-    ...(typeof input.ownerAddress === 'string' ? { ownerAddress: toChecksumAddress(input.ownerAddress) } : {}),
-  }
-}
-
-function isEnvelope(input: unknown): input is IdentityBackupEnvelope {
-  if (!input || typeof input !== 'object') return false
-  const obj = input as Partial<IdentityBackupEnvelope>
-  return obj.version === 1
-    && obj.envelopeVersion === BACKUP_ENVELOPE_VERSION
-    && typeof obj.address === 'string'
-    && (obj.ownerAddress === undefined || typeof obj.ownerAddress === 'string')
-    && typeof obj.createdAt === 'string'
-    && typeof obj.challenge === 'string'
-    && typeof obj.walletSignature === 'string'
-    && typeof obj.salt === 'string'
-    && typeof obj.kemPublicKey === 'string'
-    && typeof obj.kemCiphertext === 'string'
-    && typeof obj.nonce === 'string'
-    && typeof obj.ciphertext === 'string'
-    && typeof obj.tag === 'string'
-    && !!obj.crypto
-}
-
 function normalizeAgentStateEnvelope(input: unknown): AgentStateBackupEnvelope {
-  if (!isAgentStateEnvelope(input)) throw new Error('invalid agent state backup envelope')
-  if (input.envelopeVersion !== AGENT_STATE_BACKUP_ENVELOPE_VERSION) throw new Error('unsupported agent state backup envelope version')
+  if (!isAgentStateEnvelope(input)) throw new Error('Invalid agent state backup envelope')
+  if (input.envelopeVersion !== AGENT_STATE_BACKUP_ENVELOPE_VERSION) throw new Error('Unsupported agent state backup envelope version')
   if (input.crypto.kem !== 'ML-KEM-768' || input.crypto.aead !== 'AES-256-GCM') {
-    throw new Error('unsupported backup crypto suite')
+    throw new Error('Unsupported backup crypto suite')
   }
   return {
     ...input,
@@ -377,15 +192,6 @@ function isAgentStateEnvelope(input: unknown): input is AgentStateBackupEnvelope
     && !!obj.crypto
 }
 
-function isBackupPayload(input: unknown): input is BackupPayload {
-  if (!input || typeof input !== 'object') return false
-  const obj = input as Partial<BackupPayload>
-  return typeof obj.privateKey === 'string'
-    && validatePrivateKey(obj.privateKey)
-    && typeof obj.address === 'string'
-    && typeof obj.createdAt === 'string'
-}
-
 function isAgentStatePayload(input: unknown): input is AgentStatePayload {
   if (!input || typeof input !== 'object') return false
   const obj = input as Partial<AgentStatePayload>
@@ -399,40 +205,10 @@ function isAgentStatePayload(input: unknown): input is AgentStatePayload {
 function assertSignatureForAddress(challenge: string, signature: string, address: string): void {
   const recovered = recoverAddressFromSignature(challenge, signature)
   if (recovered.toLowerCase() !== address.toLowerCase()) {
-    throw new Error('wallet signature does not match backup address')
+    throw new Error('Wallet signature does not match backup address')
   }
 }
 
-function deriveKemSeed(passphrase: string, walletSignature: string, salt: Uint8Array, address: string): Uint8Array {
-  return hkdf(
-    Buffer.from(`${walletSignature}\n${passphrase}`, 'utf8'),
-    salt,
-    `ethagent:${BACKUP_ENVELOPE_VERSION}:ml-kem768:${address.toLowerCase()}`,
-    64,
-  )
-}
-
-function deriveAesKey(
-  passphrase: string,
-  walletSignature: string,
-  sharedSecret: Uint8Array,
-  salt: Uint8Array,
-  address: string,
-): Buffer {
-  return Buffer.from(hkdf(
-    Buffer.concat([
-      Buffer.from(walletSignature, 'utf8'),
-      Buffer.from('\n', 'utf8'),
-      Buffer.from(passphrase, 'utf8'),
-      Buffer.from('\n', 'utf8'),
-      Buffer.from(sharedSecret),
-    ]),
-    salt,
-    `ethagent:${BACKUP_ENVELOPE_VERSION}:aes-256-gcm:${address.toLowerCase()}`,
-    32,
-  ))
-}
-
 function deriveStateKemSeed(walletSignature: string, salt: Uint8Array, ownerAddress: string): Uint8Array {
   return hkdf(
     Buffer.from(walletSignature, 'utf8'),
@@ -464,19 +240,10 @@ function hkdf(ikm: Uint8Array, salt: Uint8Array, info: string, length: number):
   return new Uint8Array(crypto.hkdfSync('sha256', ikm, salt, Buffer.from(info, 'utf8'), length))
 }
 
-function aadFor(address: string, createdAt: string): Buffer {
-  return Buffer.from(`${BACKUP_ENVELOPE_VERSION}\n${address.toLowerCase()}\n${createdAt}`, 'utf8')
-}
-
 function stateAadFor(ownerAddress: string, createdAt: string): Buffer {
   return Buffer.from(`${AGENT_STATE_BACKUP_ENVELOPE_VERSION}\n${ownerAddress.toLowerCase()}\n${createdAt}`, 'utf8')
 }
 
-function normalizedPrivateKey(privateKey: string): string {
-  const trimmed = privateKey.trim()
-  return trimmed.startsWith('0x') || trimmed.startsWith('0X') ? `0x${trimmed.slice(2)}` : `0x${trimmed}`
-}
-
 function toBase64(bytes: Uint8Array): string {
   return Buffer.from(bytes).toString('base64')
 }

package/src/identity/crypto/eth.ts

@@ -16,11 +16,11 @@ function stripHex(input: string): string {
 
 function hexToBytes(hex: string): Uint8Array {
   const stripped = stripHex(hex)
-  if (stripped.length % 2 !== 0) throw new Error('hex string has odd length')
+  if (stripped.length % 2 !== 0) throw new Error('Hex string has odd length')
   const out = new Uint8Array(stripped.length / 2)
   for (let i = 0; i < out.length; i += 1) {
     const byte = Number.parseInt(stripped.slice(i * 2, i * 2 + 2), 16)
-    if (Number.isNaN(byte)) throw new Error('invalid hex')
+    if (Number.isNaN(byte)) throw new Error('Invalid hex')
     out[i] = byte
   }
   return out
@@ -82,14 +82,14 @@ export function validatePrivateKey(input: string): boolean {
 }
 
 export function addressFromPrivateKey(input: string): string {
-  if (!validatePrivateKey(input)) throw new Error('invalid private key')
+  if (!validatePrivateKey(input)) throw new Error('Invalid private key')
   const bytes = hexToBytes(stripHex(input.trim()))
   const pub = secp256k1.getPublicKey(bytes, false)
   return addressFromPublicKey(pub)
 }
 
 export function toChecksumAddress(address: string): string {
-  if (!ADDR_RE.test(address)) throw new Error('invalid address')
+  if (!ADDR_RE.test(address)) throw new Error('Invalid address')
   const lower = address.slice(2).toLowerCase()
   const hashHex = bytesToHex(keccak_256(new TextEncoder().encode(lower)))
   let out = '0x'
@@ -105,7 +105,7 @@ export function toChecksumAddress(address: string): string {
 }
 
 export function signMessage(privateKey: string, message: string | Uint8Array): string {
-  if (!validatePrivateKey(privateKey)) throw new Error('invalid private key')
+  if (!validatePrivateKey(privateKey)) throw new Error('Invalid private key')
   const sk = hexToBytes(stripHex(privateKey.trim()))
   const digest = ethereumMessageDigest(message)
   const sig = secp256k1.sign(digest, sk, { prehash: false })
@@ -121,11 +121,11 @@ export function signMessage(privateKey: string, message: string | Uint8Array): s
 }
 
 export function recoverAddressFromSignature(message: string | Uint8Array, signature: string): string {
-  if (!SIG_RE.test(signature)) throw new Error('invalid signature')
+  if (!SIG_RE.test(signature)) throw new Error('Invalid signature')
   const bytes = hexToBytes(stripHex(signature))
   const v = bytes[64]!
   const recovery = v >= 27 ? v - 27 : v
-  if (recovery < 0 || recovery > 3) throw new Error('invalid recovery id')
+  if (recovery < 0 || recovery > 3) throw new Error('Invalid recovery id')
   const recovered = new Uint8Array(65)
   recovered[0] = recovery
   recovered.set(bytes.subarray(0, 64), 1)

package/src/identity/ens/agentRecords.ts

@@ -0,0 +1,96 @@
+export const AGENT_RECORD_KEYS = {
+  token:   'org.ethagent.token',
+  profile: 'org.ethagent.profile',
+} as const
+
+type AgentRecordKey = typeof AGENT_RECORD_KEYS[keyof typeof AGENT_RECORD_KEYS]
+
+export const AGENT_RECORD_KEY_LIST: readonly AgentRecordKey[] = [
+  AGENT_RECORD_KEYS.token,
+  AGENT_RECORD_KEYS.profile,
+] as const
+
+export const AGENT_RECORD_READ_KEY_LIST: readonly string[] = AGENT_RECORD_KEY_LIST
+
+export type AgentEnsRecords = {
+  token?: string
+  profile?: string
+}
+
+export type AgentEnsRecordState = AgentEnsRecords
+
+export type AgentRecordDiff = {
+  key: AgentRecordKey
+  field: keyof AgentEnsRecordState
+  current: string
+  next: string
+  changed: boolean
+}
+
+const FIELD_FOR_KEY: Record<AgentRecordKey, keyof AgentEnsRecords> = {
+  [AGENT_RECORD_KEYS.token]:   'token',
+  [AGENT_RECORD_KEYS.profile]: 'profile',
+}
+
+const LABEL_FOR_FIELD: Record<keyof AgentEnsRecordState, string> = {
+  token:   'Agent token',
+  profile: 'Agent profile',
+}
+
+export function recordsFromTextMap(text: Record<string, string>): AgentEnsRecordState {
+  return {
+    token:   text[AGENT_RECORD_KEYS.token]   ?? '',
+    profile: text[AGENT_RECORD_KEYS.profile] ?? '',
+  }
+}
+
+export function diffRecords(current: AgentEnsRecordState, next: AgentEnsRecords): AgentRecordDiff[] {
+  return AGENT_RECORD_KEY_LIST.map(key => {
+    const field = FIELD_FOR_KEY[key]
+    const currentValue = (current[field] ?? '').trim()
+    const nextValue = (next[field] ?? '').trim()
+    return {
+      key,
+      field,
+      current: currentValue,
+      next: nextValue,
+      changed: currentValue !== nextValue,
+    }
+  })
+}
+
+export function changedRecords(current: AgentEnsRecordState, next: AgentEnsRecords): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const diff of diffRecords(current, next)) {
+    if (diff.changed) out[diff.key] = diff.next
+  }
+  return out
+}
+
+export function recordLabel(field: keyof AgentEnsRecordState): string {
+  return LABEL_FOR_FIELD[field]
+}
+
+export function formatRecordValue(field: keyof AgentEnsRecordState, value: string): string {
+  if (field === 'profile' && value.startsWith('ipfs://')) {
+    const cid = value.slice('ipfs://'.length)
+    return cid.length > 18 ? `ipfs://${cid.slice(0, 10)}...${cid.slice(-6)}` : value
+  }
+  return value
+}
+
+export function buildAgentEnsRecords(args: {
+  chainId: number
+  identityRegistryAddress: string
+  agentId: string | undefined
+  agentCardCid: string | undefined
+}): AgentEnsRecords {
+  const records: AgentEnsRecords = {}
+  if (args.agentId) {
+    records.token = `eip155:${args.chainId}:${args.identityRegistryAddress.toLowerCase()}:${args.agentId}`
+  }
+  if (args.agentCardCid) {
+    records.profile = `ipfs://${args.agentCardCid}`
+  }
+  return records
+}

package/src/identity/ens/ensAutomation/contracts.ts

@@ -0,0 +1,38 @@
+import { parseAbi, type Address } from 'viem'
+
+export const ENS_REGISTRY_ADDRESS_MAINNET = '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e' as Address
+export const ENS_NAME_WRAPPER_ADDRESS_MAINNET = '0xD4416b13d2b3a9aBae7AcD5D6C2BbDBE25686401' as Address
+export const ENS_PUBLIC_RESOLVER_ADDRESS_MAINNET = '0xF29100983E058B709F3D539b0c765937B804AC15' as Address
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as Address
+export const DEFAULT_TTL = 0n
+export const DEFAULT_FUSES = 0
+export const DEFAULT_EXPIRY = 0n
+
+export const ENS_RPC_URLS = [
+  'https://ethereum.publicnode.com',
+  'https://eth.llamarpc.com',
+  'https://rpc.ankr.com/eth',
+] as const
+
+export const ENS_AUTOMATION_REGISTRY_ABI = parseAbi([
+  'function owner(bytes32 node) view returns (address)',
+  'function resolver(bytes32 node) view returns (address)',
+  'function setResolver(bytes32 node, address resolver)',
+  'function setSubnodeRecord(bytes32 node, bytes32 label, address owner, address resolver, uint64 ttl)',
+])
+
+export const ENS_AUTOMATION_RESOLVER_ABI = parseAbi([
+  'function addr(bytes32 node) view returns (address)',
+  'function text(bytes32 node, string key) view returns (string)',
+  'function setAddr(bytes32 node, address addr)',
+  'function setText(bytes32 node, string key, string value)',
+  'function multicall(bytes[] data) returns (bytes[])',
+  'function approve(bytes32 node, address delegate, bool approved)',
+  'function isApprovedFor(address owner, bytes32 node, address delegate) view returns (bool)',
+])
+
+export const ENS_AUTOMATION_NAME_WRAPPER_ABI = parseAbi([
+  'function ownerOf(uint256 id) view returns (address)',
+  'function setResolver(bytes32 node, address resolver)',
+  'function setSubnodeRecord(bytes32 parentNode, string label, address owner, address resolver, uint64 ttl, uint32 fuses, uint64 expiry)',
+])

package/src/identity/ens/ensAutomation/delete.ts

@@ -0,0 +1,80 @@
+import { getAddress, namehash, type Address } from 'viem'
+import { isEthDomain, normalizeEthDomain, splitSubdomainName } from '../ensLookup.js'
+import { ENS_NAME_WRAPPER_ADDRESS_MAINNET } from './contracts.js'
+import {
+  createEnsAutomationClient,
+  isZero,
+  readOwner,
+  readWrappedOwner,
+  sameAddress,
+  shortHex,
+} from './read.js'
+import {
+  encodeDeleteSubnodeRegistry,
+  encodeDeleteSubnodeWrapped,
+} from './transactions.js'
+import type {
+  EnsSubdomainDeletePreflightArgs,
+  EnsSubdomainDeletePreflightResult,
+} from './types.js'
+
+export async function preflightDeleteSubdomain(args: EnsSubdomainDeletePreflightArgs): Promise<EnsSubdomainDeletePreflightResult> {
+  const fullName = normalizeEthDomain(args.fullName)
+  if (!isEthDomain(fullName)) {
+    return { ok: false, reason: 'invalid-name', detail: `${args.fullName} is not a valid .eth name` }
+  }
+  const parts = splitSubdomainName(fullName)
+  if (!parts) {
+    return { ok: false, reason: 'not-a-subdomain', detail: `${fullName} is not a subdomain` }
+  }
+  const expectedOwner = getAddress(args.expectedOwnerAddress)
+  const client = args.ensClient ?? createEnsAutomationClient()
+  const parentNode = namehash(parts.parent)
+  const fullNode = namehash(fullName)
+  let parentOwner: Address
+  try {
+    parentOwner = await readOwner(client, parentNode)
+  } catch (err: unknown) {
+    return { ok: false, reason: 'lookup-failed', detail: err instanceof Error ? err.message : String(err) }
+  }
+  if (isZero(parentOwner)) {
+    return { ok: false, reason: 'parent-not-owned', detail: `${parts.parent} does not have an ENS manager on Ethereum mainnet` }
+  }
+  const parentWrapped = sameAddress(parentOwner, ENS_NAME_WRAPPER_ADDRESS_MAINNET)
+  let parentOwnerAddress: Address
+  try {
+    parentOwnerAddress = parentWrapped ? await readWrappedOwner(client, parentNode) : getAddress(parentOwner)
+  } catch (err: unknown) {
+    return { ok: false, reason: 'lookup-failed', detail: err instanceof Error ? err.message : String(err) }
+  }
+  if (!sameAddress(parentOwnerAddress, expectedOwner)) {
+    return {
+      ok: false,
+      reason: 'parent-owner-mismatch',
+      detail: `${parts.parent} is managed by ${shortHex(parentOwnerAddress)}, not the connected wallet ${shortHex(expectedOwner)}`,
+    }
+  }
+  let childOwner: Address
+  try {
+    childOwner = await readOwner(client, fullNode)
+  } catch (err: unknown) {
+    return { ok: false, reason: 'lookup-failed', detail: err instanceof Error ? err.message : String(err) }
+  }
+  if (isZero(childOwner)) {
+    return { ok: false, reason: 'subdomain-missing', detail: `${fullName} is already cleared on Ethereum mainnet` }
+  }
+  const transaction = parentWrapped
+    ? encodeDeleteSubnodeWrapped(parts.parent, parts.label)
+    : encodeDeleteSubnodeRegistry(parts.parent, parts.label)
+  return {
+    ok: true,
+    plan: {
+      fullName,
+      parentName: parts.parent,
+      label: parts.label,
+      parentWrapped,
+      parentOwnerAddress,
+      transaction,
+    },
+  }
+}

package/src/identity/ens/ensAutomation/names.ts

@@ -0,0 +1,14 @@
+import { isEthDomain, normalizeEthDomain, splitSubdomainName } from '../ensLookup.js'
+
+export function isRootEthName(value: string): boolean {
+  const normalized = normalizeEthDomain(value)
+  return isEthDomain(normalized) && normalized.split('.').length === 2
+}
+
+export function isValidSubdomainLabel(value: string): boolean {
+  return /^[a-z0-9-]+$/.test(value) && !value.startsWith('-') && !value.endsWith('-')
+}
+
+export function hasValidSubdomainParts(fullName: string): boolean {
+  return Boolean(splitSubdomainName(fullName))
+}

package/src/identity/ens/ensAutomation/operators.ts

@@ -0,0 +1,29 @@
+import { getAddress, type Address } from 'viem'
+import type { OperatorSetDiff } from './types.js'
+
+export function compareOperatorSets(args: {
+  metadataOperators: ReadonlyArray<{ address: string }>
+  resolverDelegates: ReadonlyArray<string>
+}): OperatorSetDiff {
+  const metadata = new Map<string, Address>()
+  for (const record of args.metadataOperators) {
+    metadata.set(record.address.toLowerCase(), getAddress(record.address))
+  }
+  const resolver = new Map<string, Address>()
+  for (const raw of args.resolverDelegates) {
+    resolver.set(raw.toLowerCase(), getAddress(raw))
+  }
+  const metadataOnly: Address[] = []
+  for (const [key, addr] of metadata) {
+    if (!resolver.has(key)) metadataOnly.push(addr)
+  }
+  const resolverOnly: Address[] = []
+  for (const [key, addr] of resolver) {
+    if (!metadata.has(key)) resolverOnly.push(addr)
+  }
+  return {
+    inSync: metadataOnly.length === 0 && resolverOnly.length === 0,
+    metadataOnly,
+    resolverOnly,
+  }
+}