@0xsequence/wallet-wdk 0.0.0-20250520201059

package/src/sequence/sessions.ts

@@ -0,0 +1,238 @@
+import { Signers as CoreSigners, Envelope } from '@0xsequence/wallet-core'
+import {
+  Attestation,
+  Config,
+  Constants,
+  GenericTree,
+  Payload,
+  Signature as SequenceSignature,
+  SessionConfig,
+} from '@0xsequence/wallet-primitives'
+import { Address, Bytes, Hash, Hex } from 'ox'
+import { IdentityType } from '@0xsequence/identity-instrument'
+import { AuthCodePkceHandler } from './handlers/authcode-pkce.js'
+import { IdentityHandler, identityTypeToHex } from './handlers/identity.js'
+import { ManagerOptionsDefaults, Shared } from './manager.js'
+import { Actions } from './types/signature-request.js'
+
+export type AuthorizeImplicitSessionArgs = {
+  target: string
+  applicationData?: Hex.Hex
+}
+
+const DefaultSessionManagerAddresses = [Constants.DefaultSessionManager]
+
+export class Sessions {
+  constructor(
+    private readonly shared: Shared,
+    private readonly sessionManagerAddresses: Address.Address[] = DefaultSessionManagerAddresses,
+  ) {}
+
+  async getSessionTopology(walletAddress: Address.Address): Promise<SessionConfig.SessionsTopology> {
+    const { modules } = await this.shared.modules.wallets.getConfigurationParts(walletAddress)
+    const managerLeaf = modules.find((leaf) =>
+      this.sessionManagerAddresses.some((addr) => Address.isEqual(addr, leaf.address)),
+    )
+    if (!managerLeaf) {
+      throw new Error('Session manager not found')
+    }
+    const imageHash = managerLeaf.imageHash
+    const tree = await this.shared.sequence.stateProvider.getTree(imageHash)
+    if (!tree) {
+      throw new Error('Session topology not found')
+    }
+    return SessionConfig.configurationTreeToSessionsTopology(tree)
+  }
+
+  async prepareAuthorizeImplicitSession(
+    walletAddress: Address.Address,
+    sessionAddress: Address.Address,
+    args: AuthorizeImplicitSessionArgs,
+  ): Promise<string> {
+    const topology = await this.getSessionTopology(walletAddress)
+    const identitySignerAddress = SessionConfig.getIdentitySigner(topology)
+    if (!identitySignerAddress) {
+      throw new Error('No identity signer address found')
+    }
+    const identityKind = await this.shared.modules.signers.kindOf(walletAddress, identitySignerAddress)
+    if (!identityKind) {
+      throw new Error('No identity handler kind found')
+    }
+    const handler = this.shared.handlers.get(identityKind)
+    if (!handler) {
+      throw new Error('No identity handler found')
+    }
+
+    // Create the attestation to sign
+    let identityType: IdentityType | undefined
+    let issuerHash: Hex.Hex = '0x'
+    let audienceHash: Hex.Hex = '0x'
+    if (handler instanceof IdentityHandler) {
+      identityType = handler.identityType
+      if (handler instanceof AuthCodePkceHandler) {
+        issuerHash = Hash.keccak256(Hex.fromString(handler.issuer))
+        audienceHash = Hash.keccak256(Hex.fromString(handler.audience))
+      }
+    }
+    const attestation: Attestation.Attestation = {
+      approvedSigner: sessionAddress,
+      identityType: Bytes.fromHex(identityTypeToHex(identityType), { size: 4 }),
+      issuerHash: Bytes.fromHex(issuerHash, { size: 32 }),
+      audienceHash: Bytes.fromHex(audienceHash, { size: 32 }),
+      applicationData: Bytes.fromHex(args.applicationData ?? '0x'),
+      authData: {
+        redirectUrl: args.target,
+      },
+    }
+    // Fake the configuration with the single required signer
+    const configuration: Config.Config = {
+      threshold: 1n,
+      checkpoint: 0n,
+      topology: {
+        type: 'signer',
+        address: identitySignerAddress,
+        weight: 1n,
+      },
+    }
+    const envelope: Envelope.Envelope<Payload.SessionImplicitAuthorize> = {
+      payload: {
+        type: 'session-implicit-authorize',
+        sessionAddress,
+        attestation,
+      },
+      wallet: walletAddress,
+      chainId: 0n,
+      configuration,
+    }
+
+    // Request the signature from the identity handler
+    return this.shared.modules.signatures.request(envelope, 'session-implicit-authorize', {
+      origin: args.target,
+    })
+  }
+
+  async completeAuthorizeImplicitSession(requestId: string): Promise<{
+    attestation: Attestation.Attestation
+    signature: SequenceSignature.RSY
+  }> {
+    // Get the updated signature request
+    const signatureRequest = await this.shared.modules.signatures.get(requestId)
+    if (
+      signatureRequest.action !== 'session-implicit-authorize' ||
+      !Payload.isSessionImplicitAuthorize(signatureRequest.envelope.payload)
+    ) {
+      throw new Error('Invalid action')
+    }
+
+    if (!Envelope.isSigned(signatureRequest.envelope) || !Envelope.reachedThreshold(signatureRequest.envelope)) {
+      throw new Error('Envelope not signed or threshold not reached')
+    }
+
+    // Find any valid signature
+    const signature = signatureRequest.envelope.signatures[0]
+    if (!signature || !Envelope.isSignature(signature)) {
+      throw new Error('No valid signature found')
+    }
+    if (signature.signature.type !== 'hash') {
+      // Should never happen
+      throw new Error('Unsupported signature type')
+    }
+
+    return {
+      attestation: signatureRequest.envelope.payload.attestation,
+      signature: signature.signature,
+    }
+  }
+
+  async addExplicitSession(
+    walletAddress: Address.Address,
+    sessionAddress: Address.Address,
+    permissions: CoreSigners.Session.ExplicitParams,
+    origin?: string,
+  ): Promise<string> {
+    const topology = await this.getSessionTopology(walletAddress)
+    const newTopology = SessionConfig.addExplicitSession(topology, {
+      ...permissions,
+      signer: sessionAddress,
+    })
+    return this.prepareSessionUpdate(walletAddress, newTopology, origin)
+  }
+
+  async removeExplicitSession(
+    walletAddress: Address.Address,
+    sessionAddress: Address.Address,
+    origin?: string,
+  ): Promise<string> {
+    const topology = await this.getSessionTopology(walletAddress)
+    const newTopology = SessionConfig.removeExplicitSession(topology, sessionAddress)
+    if (!newTopology) {
+      throw new Error('Session not found')
+    }
+    return this.prepareSessionUpdate(walletAddress, newTopology, origin)
+  }
+
+  async addBlacklistAddress(
+    walletAddress: Address.Address,
+    address: Address.Address,
+    origin?: string,
+  ): Promise<string> {
+    const topology = await this.getSessionTopology(walletAddress)
+    const newTopology = SessionConfig.addToImplicitBlacklist(topology, address)
+    return this.prepareSessionUpdate(walletAddress, newTopology, origin)
+  }
+
+  async removeBlacklistAddress(
+    walletAddress: Address.Address,
+    address: Address.Address,
+    origin?: string,
+  ): Promise<string> {
+    const topology = await this.getSessionTopology(walletAddress)
+    const newTopology = SessionConfig.removeFromImplicitBlacklist(topology, address)
+    return this.prepareSessionUpdate(walletAddress, newTopology, origin)
+  }
+
+  private async prepareSessionUpdate(
+    walletAddress: Address.Address,
+    topology: SessionConfig.SessionsTopology,
+    origin: string = 'wallet-webapp',
+  ): Promise<string> {
+    // Store the new configuration
+    const tree = SessionConfig.sessionsTopologyToConfigurationTree(topology)
+    await this.shared.sequence.stateProvider.saveTree(tree)
+    const newImageHash = GenericTree.hash(tree)
+
+    // Find the session manager in the old configuration
+    const { modules } = await this.shared.modules.wallets.getConfigurationParts(walletAddress)
+    const managerLeaf = modules.find((leaf) =>
+      this.sessionManagerAddresses.some((addr) => Address.isEqual(addr, leaf.address)),
+    )
+    if (!managerLeaf) {
+      // Missing. Add it
+      modules.push({
+        ...ManagerOptionsDefaults.defaultSessionsTopology,
+        imageHash: newImageHash,
+      })
+    } else {
+      // Update the configuration to use the new session manager image hash
+      managerLeaf.imageHash = newImageHash
+    }
+
+    return this.shared.modules.wallets.requestConfigurationUpdate(
+      walletAddress,
+      {
+        modules,
+      },
+      Actions.SessionUpdate,
+      origin,
+    )
+  }
+
+  async completeSessionUpdate(requestId: string) {
+    const sigRequest = await this.shared.modules.signatures.get(requestId)
+    if (sigRequest.action !== 'session-update' || !Payload.isConfigUpdate(sigRequest.envelope.payload)) {
+      throw new Error('Invalid action')
+    }
+
+    return this.shared.modules.wallets.completeConfigurationUpdate(requestId)
+  }
+}

package/src/sequence/signatures.ts

@@ -0,0 +1,263 @@
+import { Envelope } from '@0xsequence/wallet-core'
+import { Config, Payload } from '@0xsequence/wallet-primitives'
+import { Address, Hex } from 'ox'
+import { v7 as uuidv7 } from 'uuid'
+import { Shared } from './manager.js'
+import {
+  Action,
+  ActionToPayload,
+  BaseSignatureRequest,
+  SignatureRequest,
+  SignerBase,
+  SignerSigned,
+  SignerUnavailable,
+} from './types/signature-request.js'
+import { Cron } from './cron.js'
+
+export class Signatures {
+  constructor(private readonly shared: Shared) {}
+
+  initialize() {
+    this.shared.modules.cron.registerJob('prune-signatures', 10 * 60 * 1000, async () => {
+      const prunedSignatures = await this.prune()
+      if (prunedSignatures > 0) {
+        this.shared.modules.logger.log(`Pruned ${prunedSignatures} signatures`)
+      }
+    })
+    this.shared.modules.logger.log('Signatures module initialized and job registered.')
+  }
+
+  private async getBase(requestId: string): Promise<BaseSignatureRequest> {
+    const request = await this.shared.databases.signatures.get(requestId)
+    if (!request) {
+      throw new Error(`Request not found for ${requestId}`)
+    }
+    return request
+  }
+
+  async list(): Promise<SignatureRequest[]> {
+    return this.shared.databases.signatures.list() as any as SignatureRequest[]
+  }
+
+  async get(requestId: string): Promise<SignatureRequest> {
+    const request = await this.getBase(requestId)
+
+    if (request.status !== 'pending' && request.scheduledPruning < Date.now()) {
+      await this.shared.databases.signatures.del(requestId)
+      throw new Error(`Request not found for ${requestId}`)
+    }
+
+    const signers = Config.getSigners(request.envelope.configuration.topology)
+    const signersAndKinds = await Promise.all([
+      ...signers.signers.map(async (signer) => {
+        const kind = await this.shared.modules.signers.kindOf(request.wallet, signer)
+        return {
+          address: signer,
+          imageHash: undefined,
+          kind,
+        }
+      }),
+      ...signers.sapientSigners.map(async (signer) => {
+        const kind = await this.shared.modules.signers.kindOf(
+          request.wallet,
+          signer.address,
+          Hex.from(signer.imageHash),
+        )
+        return {
+          address: signer.address,
+          imageHash: signer.imageHash,
+          kind,
+        }
+      }),
+    ])
+
+    const statuses = await Promise.all(
+      signersAndKinds.map(async (sak) => {
+        const base: SignerBase = {
+          address: sak.address,
+          imageHash: sak.imageHash,
+        }
+
+        // We may have a signature for this signer already
+        const signed = request.envelope.signatures.some((sig) => {
+          if (Envelope.isSapientSignature(sig)) {
+            return Address.isEqual(sig.signature.address, sak.address) && sig.imageHash === sak.imageHash
+          }
+          return Address.isEqual(sig.address, sak.address)
+        })
+
+        if (!sak.kind) {
+          const status: SignerUnavailable = {
+            ...base,
+            handler: undefined,
+            reason: 'unknown-signer-kind',
+            status: 'unavailable',
+          }
+          return status
+        }
+
+        const handler = this.shared.handlers.get(sak.kind)
+        if (signed) {
+          const status: SignerSigned = {
+            ...base,
+            handler,
+            status: 'signed',
+          }
+          return status
+        }
+
+        if (!handler) {
+          const status: SignerUnavailable = {
+            ...base,
+            handler: undefined,
+            reason: 'no-handler',
+            status: 'unavailable',
+          }
+          return status
+        }
+
+        return handler.status(sak.address, sak.imageHash, request)
+      }),
+    )
+
+    const signatureRequest: SignatureRequest = {
+      ...request,
+      ...Envelope.weightOf(request.envelope),
+      signers: statuses,
+    }
+    return signatureRequest
+  }
+
+  onSignatureRequestUpdate(
+    requestId: string,
+    cb: (requests: SignatureRequest) => void,
+    onError?: (error: Error) => void,
+    trigger?: boolean,
+  ) {
+    const undoDbListener = this.shared.databases.signatures.addListener(() => {
+      this.get(requestId)
+        .then((request) => cb(request))
+        .catch((error) => onError?.(error))
+    })
+
+    const undoHandlerListeners = Array.from(this.shared.handlers.values()).map((handler) =>
+      handler.onStatusChange(() => {
+        this.get(requestId)
+          .then((request) => cb(request))
+          .catch((error) => onError?.(error))
+      }),
+    )
+
+    if (trigger) {
+      this.get(requestId)
+        .then((request) => cb(request))
+        .catch((error) => onError?.(error))
+    }
+
+    return () => {
+      undoDbListener()
+      undoHandlerListeners.forEach((undoFn) => undoFn())
+    }
+  }
+
+  onSignatureRequestsUpdate(cb: (requests: BaseSignatureRequest[]) => void, trigger?: boolean) {
+    const undo = this.shared.databases.signatures.addListener(() => {
+      this.list().then((l) => cb(l))
+    })
+
+    if (trigger) {
+      this.list().then((l) => cb(l))
+    }
+
+    return undo
+  }
+
+  async complete(requestId: string) {
+    const request = await this.getBase(requestId)
+
+    if (request?.envelope.payload.type === 'config-update') {
+      // Clear pending config updates for the same wallet with a checkpoint equal or lower than the completed update
+      const pendingRequests = await this.shared.databases.signatures.list()
+      const pendingConfigUpdatesToClear = pendingRequests.filter(
+        (sig) =>
+          Address.isEqual(sig.wallet, request.wallet) &&
+          sig.envelope.payload.type === 'config-update' &&
+          sig.envelope.configuration.checkpoint <= request.envelope.configuration.checkpoint,
+      )
+      // This also deletes the requested id
+      await Promise.all(pendingConfigUpdatesToClear.map((sig) => this.shared.modules.signatures.cancel(sig.id)))
+    }
+
+    await this.shared.databases.signatures.set({
+      ...request,
+      status: 'completed',
+      scheduledPruning: Date.now() + this.shared.databases.pruningInterval,
+    })
+  }
+
+  async request<A extends Action>(
+    envelope: Envelope.Envelope<ActionToPayload[A]>,
+    action: A,
+    options: {
+      origin?: string
+    } = {},
+  ): Promise<string> {
+    // If the action is a config update, we need to remove all signature requests
+    // for the same wallet that also involve configuration updates
+    // as it may cause race conditions
+    // TODO: Eventually we should define a "delta configuration" signature request
+    if (Payload.isConfigUpdate(envelope.payload)) {
+      const pendingRequests = await this.shared.databases.signatures.list()
+      const pendingConfigUpdatesToClear = pendingRequests.filter(
+        (sig) => sig.wallet === envelope.wallet && Payload.isConfigUpdate(sig.envelope.payload),
+      )
+
+      console.warn(
+        'Deleting conflicting configuration updates for wallet',
+        envelope.wallet,
+        pendingConfigUpdatesToClear.map((pc) => pc.id),
+      )
+      await Promise.all(pendingConfigUpdatesToClear.map((sig) => this.shared.modules.signatures.cancel(sig.id)))
+    }
+
+    const id = uuidv7()
+
+    await this.shared.databases.signatures.set({
+      id,
+      wallet: envelope.wallet,
+      envelope: Envelope.toSigned(envelope),
+      origin: options.origin ?? 'unknown',
+      action,
+      createdAt: new Date().toISOString(),
+      status: 'pending',
+    })
+
+    return id
+  }
+
+  async addSignature(requestId: string, signature: Envelope.SapientSignature | Envelope.Signature) {
+    const request = await this.getBase(requestId)
+
+    Envelope.addSignature(request.envelope, signature)
+
+    await this.shared.databases.signatures.set(request)
+  }
+
+  async cancel(requestId: string) {
+    const request = await this.getBase(requestId)
+
+    await this.shared.databases.signatures.set({
+      ...request,
+      status: 'cancelled',
+      scheduledPruning: Date.now() + this.shared.databases.pruningInterval,
+    })
+  }
+
+  async prune() {
+    const now = Date.now()
+    const requests = await this.shared.databases.signatures.list()
+    const toPrune = requests.filter((req) => req.status !== 'pending' && req.scheduledPruning < now)
+    await Promise.all(toPrune.map((req) => this.shared.databases.signatures.del(req.id)))
+    return toPrune.length
+  }
+}

package/src/sequence/signers.ts

@@ -0,0 +1,88 @@
+import { Payload } from '@0xsequence/wallet-primitives'
+import { Address, Hex } from 'ox'
+import { Shared } from './manager.js'
+import { Kind, Kinds, SignerWithKind, WitnessExtraSignerKind } from './types/signer.js'
+
+export function isWitnessExtraSignerKind(extra: any): extra is WitnessExtraSignerKind {
+  return typeof extra === 'object' && extra !== null && 'signerKind' in extra
+}
+
+function toKnownKind(kind: string): Kind {
+  if (Object.values(Kinds).includes(kind as Kind)) {
+    return kind as Kind
+  }
+
+  console.warn(`Unknown signer kind: ${kind}`)
+
+  return Kinds.Unknown
+}
+
+// Signers is in charge to know (or figure out) the "kind" of each signer
+// i.e., when a signature is requested, we only get address and imageHash (if sapient)
+// this module takes care of figuring out the kind of signer (e.g., device, passkey, recovery, etc.)
+export class Signers {
+  constructor(private readonly shared: Shared) {}
+
+  async kindOf(wallet: Address.Address, address: Address.Address, imageHash?: Hex.Hex): Promise<Kind | undefined> {
+    // // The device may be among the local devices, in that case it is a local device
+    // // TODO: Maybe signers shouldn't be getting in the way of devices, it feels like a
+    // //      different concern
+    // if (await this.devices.has(address)) {
+    //   return Kinds.LocalDevice
+    // }
+
+    // Some signers are known by the configuration of the wallet development kit, specifically
+    // some of the sapient signers, who always share the same address
+    if (Address.isEqual(this.shared.sequence.extensions.recovery, address)) {
+      return Kinds.Recovery
+    }
+
+    // We need to use the state provider (and witness) this will tell us the kind of signer
+    // NOTICE: This looks expensive, but this operation should be cached by the state provider
+    const witness = await (imageHash
+      ? this.shared.sequence.stateProvider.getWitnessForSapient(wallet, address, imageHash)
+      : this.shared.sequence.stateProvider.getWitnessFor(wallet, address))
+
+    if (!witness) {
+      return undefined
+    }
+
+    // Parse the payload, it may have the kind of signer
+    if (!Payload.isMessage(witness.payload)) {
+      return undefined
+    }
+
+    try {
+      const message = JSON.parse(Hex.toString(witness.payload.message))
+      if (isWitnessExtraSignerKind(message)) {
+        return toKnownKind(message.signerKind)
+      }
+    } catch {}
+
+    return undefined
+  }
+
+  async resolveKinds(
+    wallet: Address.Address,
+    signers: (Address.Address | { address: Address.Address; imageHash: Hex.Hex })[],
+  ): Promise<SignerWithKind[]> {
+    return Promise.all(
+      signers.map(async (signer) => {
+        if (typeof signer === 'string') {
+          const kind = await this.kindOf(wallet, signer)
+          return {
+            address: signer,
+            kind,
+          }
+        } else {
+          const kind = await this.kindOf(wallet, signer.address, signer.imageHash)
+          return {
+            address: signer.address,
+            imageHash: signer.imageHash,
+            kind,
+          }
+        }
+      }),
+    )
+  }
+}