@0xsequence/wallet-wdk 0.0.0-20250520201059

package/src/sequence/handlers/authcode-pkce.ts

@@ -0,0 +1,70 @@
+import { Hex, Address, Bytes } from 'ox'
+import { Handler } from './handler.js'
+import * as Db from '../../dbs/index.js'
+import { Signatures } from '../signatures.js'
+import * as Identity from '@0xsequence/identity-instrument'
+import { IdentitySigner } from '../../identity/signer.js'
+import { AuthCodeHandler } from './authcode.js'
+
+export class AuthCodePkceHandler extends AuthCodeHandler implements Handler {
+  constructor(
+    signupKind: 'google-pkce',
+    issuer: string,
+    audience: string,
+    nitro: Identity.IdentityInstrument,
+    signatures: Signatures,
+    commitments: Db.AuthCommitments,
+    authKeys: Db.AuthKeys,
+  ) {
+    super(signupKind, issuer, audience, nitro, signatures, commitments, authKeys)
+  }
+
+  public async commitAuth(target: string, isSignUp: boolean, state?: string, signer?: string) {
+    let challenge = new Identity.AuthCodePkceChallenge(this.issuer, this.audience, this.redirectUri)
+    if (signer) {
+      challenge = challenge.withSigner(signer)
+    }
+    const { verifier, loginHint, challenge: codeChallenge } = await this.nitroCommitVerifier(challenge)
+    if (!state) {
+      state = Hex.fromBytes(Bytes.random(32))
+    }
+
+    await this.commitments.set({
+      id: state,
+      kind: this.signupKind,
+      verifier,
+      challenge: codeChallenge,
+      target,
+      metadata: {},
+      isSignUp,
+    })
+
+    const searchParams = new URLSearchParams({
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      client_id: this.audience,
+      redirect_uri: this.redirectUri,
+      login_hint: loginHint,
+      response_type: 'code',
+      scope: 'openid profile email',
+      state,
+    })
+
+    const oauthUrl = this.oauthUrl()
+    return `${oauthUrl}?${searchParams.toString()}`
+  }
+
+  public async completeAuth(
+    commitment: Db.AuthCommitment,
+    code: string,
+  ): Promise<[IdentitySigner, { [key: string]: string }]> {
+    const challenge = new Identity.AuthCodePkceChallenge('', '', '')
+    if (!commitment.verifier) {
+      throw new Error('Missing verifier in commitment')
+    }
+    const signer = await this.nitroCompleteAuth(challenge.withAnswer(commitment.verifier, code))
+    await this.commitments.del(commitment.id)
+
+    return [signer, commitment.metadata]
+  }
+}

package/src/sequence/handlers/authcode.ts

@@ -0,0 +1,116 @@
+import { Hex, Address, Bytes } from 'ox'
+import { Handler } from './handler.js'
+import * as Db from '../../dbs/index.js'
+import { Signatures } from '../signatures.js'
+import * as Identity from '@0xsequence/identity-instrument'
+import { SignerUnavailable, SignerReady, SignerActionable, BaseSignatureRequest } from '../types/signature-request.js'
+import { IdentitySigner } from '../../identity/signer.js'
+import { IdentityHandler } from './identity.js'
+
+export class AuthCodeHandler extends IdentityHandler implements Handler {
+  protected redirectUri: string = ''
+
+  constructor(
+    public readonly signupKind: 'apple' | 'google-pkce',
+    public readonly issuer: string,
+    public readonly audience: string,
+    nitro: Identity.IdentityInstrument,
+    signatures: Signatures,
+    protected readonly commitments: Db.AuthCommitments,
+    authKeys: Db.AuthKeys,
+  ) {
+    super(nitro, authKeys, signatures, Identity.IdentityType.OIDC)
+  }
+
+  public get kind() {
+    return 'login-' + this.signupKind
+  }
+
+  public setRedirectUri(redirectUri: string) {
+    this.redirectUri = redirectUri
+  }
+
+  public async commitAuth(target: string, isSignUp: boolean, state?: string, signer?: string) {
+    if (!state) {
+      state = Hex.fromBytes(Bytes.random(32))
+    }
+
+    await this.commitments.set({
+      id: state,
+      kind: this.signupKind,
+      signer,
+      target,
+      metadata: {},
+      isSignUp,
+    })
+
+    const searchParams = new URLSearchParams({
+      client_id: this.audience,
+      redirect_uri: this.redirectUri,
+      response_type: 'code',
+      scope: 'openid',
+      state,
+    })
+
+    const oauthUrl = this.oauthUrl()
+    return `${oauthUrl}?${searchParams.toString()}`
+  }
+
+  public async completeAuth(
+    commitment: Db.AuthCommitment,
+    code: string,
+  ): Promise<[IdentitySigner, { [key: string]: string }]> {
+    let challenge = new Identity.AuthCodeChallenge(this.issuer, this.audience, this.redirectUri, code)
+    if (commitment.signer) {
+      challenge = challenge.withSigner(commitment.signer)
+    }
+    await this.nitroCommitVerifier(challenge)
+    const signer = await this.nitroCompleteAuth(challenge)
+
+    return [signer, {}]
+  }
+
+  async status(
+    address: Address.Address,
+    _imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerUnavailable | SignerReady | SignerActionable> {
+    // Normalize address
+    const normalizedAddress = Address.checksum(address)
+    const signer = await this.getAuthKeySigner(normalizedAddress)
+    if (signer) {
+      return {
+        address: normalizedAddress,
+        handler: this,
+        status: 'ready',
+        handle: async () => {
+          await this.sign(signer, request)
+          return true
+        },
+      }
+    }
+
+    return {
+      address: normalizedAddress,
+      handler: this,
+      status: 'actionable',
+      message: 'request-redirect',
+      handle: async () => {
+        const url = await this.commitAuth(window.location.pathname, false, request.id, normalizedAddress)
+        window.location.href = url
+        return true
+      },
+    }
+  }
+
+  protected oauthUrl() {
+    switch (this.issuer) {
+      case 'https://accounts.google.com':
+        return 'https://accounts.google.com/o/oauth2/v2/auth'
+      case 'https://appleid.apple.com':
+        return 'https://appleid.apple.com/auth/authorize'
+      default:
+        throw new Error('unsupported-issuer')
+    }
+  }
+}

package/src/sequence/handlers/devices.ts

@@ -0,0 +1,53 @@
+import { Kinds } from '../types/signer.js'
+import { Signatures } from '../signatures.js'
+import { Address, Hex } from 'ox'
+import { Devices } from '../devices.js'
+import { Handler } from './handler.js'
+import { SignerReady, SignerUnavailable, BaseSignatureRequest } from '../types/index.js'
+
+export class DevicesHandler implements Handler {
+  kind = Kinds.LocalDevice
+
+  constructor(
+    private readonly signatures: Signatures,
+    private readonly devices: Devices,
+  ) {}
+
+  onStatusChange(cb: () => void): () => void {
+    return () => {}
+  }
+
+  async status(
+    address: Address.Address,
+    _imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerUnavailable | SignerReady> {
+    const signer = await this.devices.get(address)
+    if (!signer) {
+      const status: SignerUnavailable = {
+        address,
+        handler: this,
+        reason: 'not-local-key',
+        status: 'unavailable',
+      }
+      return status
+    }
+
+    const status: SignerReady = {
+      address,
+      handler: this,
+      status: 'ready',
+      handle: async () => {
+        const signature = await signer.sign(request.envelope.wallet, request.envelope.chainId, request.envelope.payload)
+
+        await this.signatures.addSignature(request.id, {
+          address,
+          signature,
+        })
+
+        return true
+      },
+    }
+    return status
+  }
+}

package/src/sequence/handlers/handler.ts

@@ -0,0 +1,14 @@
+import { Address, Hex } from 'ox'
+import { SignerActionable, SignerReady, SignerUnavailable, BaseSignatureRequest } from '../types/index.js'
+
+export interface Handler {
+  kind: string
+
+  onStatusChange(cb: () => void): () => void
+
+  status(
+    address: Address.Address,
+    imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerUnavailable | SignerReady | SignerActionable>
+}

package/src/sequence/handlers/identity.ts

@@ -0,0 +1,101 @@
+import { Hex, Bytes } from 'ox'
+import * as Db from '../../dbs/index.js'
+import * as Identity from '@0xsequence/identity-instrument'
+import { Signatures } from '../signatures.js'
+import { BaseSignatureRequest } from '../types/signature-request.js'
+import { IdentitySigner, toIdentityAuthKey } from '../../identity/signer.js'
+
+export const identityTypeToHex = (identityType?: Identity.IdentityType): Hex.Hex => {
+  // Bytes4
+  switch (identityType) {
+    case Identity.IdentityType.Guest:
+      return '0x00000000'
+    case Identity.IdentityType.Email:
+      return '0x00000001'
+    case Identity.IdentityType.OIDC:
+      return '0x00000002'
+    default:
+      // Unknown identity type
+      return '0xffffffff'
+  }
+}
+
+export class IdentityHandler {
+  constructor(
+    private readonly nitro: Identity.IdentityInstrument,
+    private readonly authKeys: Db.AuthKeys,
+    private readonly signatures: Signatures,
+    public readonly identityType: Identity.IdentityType,
+  ) {}
+
+  public onStatusChange(cb: () => void): () => void {
+    return this.authKeys.addListener(cb)
+  }
+
+  protected async nitroCommitVerifier(challenge: Identity.Challenge) {
+    await this.authKeys.delBySigner('')
+    const authKey = await this.getAuthKey('')
+    if (!authKey) {
+      throw new Error('no-auth-key')
+    }
+
+    const res = await this.nitro.commitVerifier(toIdentityAuthKey(authKey), challenge)
+    return res
+  }
+
+  protected async nitroCompleteAuth(challenge: Identity.Challenge) {
+    const authKey = await this.getAuthKey('')
+    if (!authKey) {
+      throw new Error('no-auth-key')
+    }
+
+    const res = await this.nitro.completeAuth(toIdentityAuthKey(authKey), challenge)
+
+    authKey.identitySigner = res.signer
+    authKey.expiresAt = new Date(Date.now() + 1000 * 60 * 3) // 3 minutes
+    await this.authKeys.delBySigner('')
+    await this.authKeys.set(authKey)
+
+    const signer = new IdentitySigner(this.nitro, authKey)
+    return signer
+  }
+
+  protected async sign(signer: IdentitySigner, request: BaseSignatureRequest) {
+    const signature = await signer.sign(request.envelope.wallet, request.envelope.chainId, request.envelope.payload)
+    await this.signatures.addSignature(request.id, {
+      address: signer.address,
+      signature,
+    })
+  }
+
+  protected async getAuthKeySigner(address: string): Promise<IdentitySigner | undefined> {
+    const authKey = await this.getAuthKey(address)
+    if (!authKey) {
+      return undefined
+    }
+    return new IdentitySigner(this.nitro, authKey)
+  }
+
+  private async getAuthKey(signer: string): Promise<Db.AuthKey | undefined> {
+    let authKey = await this.authKeys.getBySigner(signer)
+    if (!signer && !authKey) {
+      const keyPair = await window.crypto.subtle.generateKey(
+        {
+          name: 'ECDSA',
+          namedCurve: 'P-256',
+        },
+        false,
+        ['sign', 'verify'],
+      )
+      const publicKey = await window.crypto.subtle.exportKey('raw', keyPair.publicKey)
+      authKey = {
+        address: Hex.fromBytes(new Uint8Array(publicKey)),
+        identitySigner: '',
+        expiresAt: new Date(Date.now() + 1000 * 60 * 60), // 1 hour
+        privateKey: keyPair.privateKey,
+      }
+      await this.authKeys.set(authKey)
+    }
+    return authKey
+  }
+}

package/src/sequence/handlers/index.ts

@@ -0,0 +1,6 @@
+export type { Handler } from './handler.js'
+export { DevicesHandler } from './devices.js'
+export { PasskeysHandler } from './passkeys.js'
+export { OtpHandler } from './otp.js'
+export { AuthCodePkceHandler } from './authcode-pkce.js'
+export { MnemonicHandler } from './mnemonic.js'

package/src/sequence/handlers/mnemonic.ts

@@ -0,0 +1,88 @@
+import { Signers } from '@0xsequence/wallet-core'
+import { Address, Hex, Mnemonic } from 'ox'
+import { Handler } from './handler.js'
+import { Signatures } from '../signatures.js'
+import { Kinds } from '../types/signer.js'
+import { SignerReady, SignerUnavailable, BaseSignatureRequest, SignerActionable } from '../types/index.js'
+
+type RespondFn = (mnemonic: string) => Promise<void>
+
+export class MnemonicHandler implements Handler {
+  kind = Kinds.LoginMnemonic
+
+  private onPromptMnemonic: undefined | ((respond: RespondFn) => Promise<void>)
+
+  constructor(private readonly signatures: Signatures) {}
+
+  public registerUI(onPromptMnemonic: (respond: RespondFn) => Promise<void>) {
+    this.onPromptMnemonic = onPromptMnemonic
+    return () => {
+      this.onPromptMnemonic = undefined
+    }
+  }
+
+  public unregisterUI() {
+    this.onPromptMnemonic = undefined
+  }
+
+  onStatusChange(_cb: () => void): () => void {
+    return () => {}
+  }
+
+  public static toSigner(mnemonic: string): Signers.Pk.Pk | undefined {
+    try {
+      const pk = Mnemonic.toPrivateKey(mnemonic)
+      return new Signers.Pk.Pk(Hex.from(pk))
+    } catch {
+      return undefined
+    }
+  }
+
+  async status(
+    address: Address.Address,
+    _imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerUnavailable | SignerActionable> {
+    const onPromptMnemonic = this.onPromptMnemonic
+    if (!onPromptMnemonic) {
+      return {
+        address,
+        handler: this,
+        reason: 'ui-not-registered',
+        status: 'unavailable',
+      }
+    }
+
+    return {
+      address,
+      handler: this,
+      status: 'actionable',
+      message: 'enter-mnemonic',
+      handle: () =>
+        new Promise(async (resolve, reject) => {
+          const respond = async (mnemonic: string) => {
+            const signer = MnemonicHandler.toSigner(mnemonic)
+            if (!signer) {
+              return reject('invalid-mnemonic')
+            }
+
+            if (signer.address !== address) {
+              return reject('wrong-mnemonic')
+            }
+
+            const signature = await signer.sign(
+              request.envelope.wallet,
+              request.envelope.chainId,
+              request.envelope.payload,
+            )
+            await this.signatures.addSignature(request.id, {
+              address,
+              signature,
+            })
+            resolve(true)
+          }
+          await onPromptMnemonic(respond)
+        }),
+    }
+  }
+}

package/src/sequence/handlers/otp.ts

@@ -0,0 +1,107 @@
+import { Hex, Address } from 'ox'
+import { Signers } from '@0xsequence/wallet-core'
+import * as Identity from '@0xsequence/identity-instrument'
+import { Handler } from './handler.js'
+import * as Db from '../../dbs/index.js'
+import { Signatures } from '../signatures.js'
+import { SignerUnavailable, SignerReady, SignerActionable, BaseSignatureRequest } from '../types/signature-request.js'
+import { Kinds } from '../types/signer.js'
+import { IdentityHandler } from './identity.js'
+
+type RespondFn = (otp: string) => Promise<void>
+
+export class OtpHandler extends IdentityHandler implements Handler {
+  kind = Kinds.LoginEmailOtp
+
+  private onPromptOtp: undefined | ((recipient: string, respond: RespondFn) => Promise<void>)
+
+  constructor(nitro: Identity.IdentityInstrument, signatures: Signatures, authKeys: Db.AuthKeys) {
+    super(nitro, authKeys, signatures, Identity.IdentityType.Email)
+  }
+
+  public registerUI(onPromptOtp: (recipient: string, respond: RespondFn) => Promise<void>) {
+    this.onPromptOtp = onPromptOtp
+    return () => {
+      this.onPromptOtp = undefined
+    }
+  }
+
+  public unregisterUI() {
+    this.onPromptOtp = undefined
+  }
+
+  public async getSigner(email: string): Promise<Signers.Signer & Signers.Witnessable> {
+    const onPromptOtp = this.onPromptOtp
+    if (!onPromptOtp) {
+      throw new Error('otp-handler-ui-not-registered')
+    }
+
+    const challenge = Identity.OtpChallenge.fromRecipient(this.identityType, email)
+    const { loginHint, challenge: codeChallenge } = await this.nitroCommitVerifier(challenge)
+
+    return new Promise(async (resolve, reject) => {
+      const respond = async (otp: string) => {
+        try {
+          const signer = await this.nitroCompleteAuth(challenge.withAnswer(codeChallenge, otp))
+          resolve(signer)
+        } catch (e) {
+          reject(e)
+        }
+      }
+      await onPromptOtp(loginHint, respond)
+    })
+  }
+
+  async status(
+    address: Address.Address,
+    _imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerUnavailable | SignerReady | SignerActionable> {
+    const onPromptOtp = this.onPromptOtp
+    if (!onPromptOtp) {
+      return {
+        address,
+        handler: this,
+        reason: 'ui-not-registered',
+        status: 'unavailable',
+      }
+    }
+
+    const signer = await this.getAuthKeySigner(address)
+    if (signer) {
+      return {
+        address,
+        handler: this,
+        status: 'ready',
+        handle: async () => {
+          await this.sign(signer, request)
+          return true
+        },
+      }
+    }
+
+    return {
+      address,
+      handler: this,
+      status: 'actionable',
+      message: 'request-otp',
+      handle: () =>
+        new Promise(async (resolve, reject) => {
+          const challenge = Identity.OtpChallenge.fromSigner(this.identityType, address)
+          const { loginHint, challenge: codeChallenge } = await this.nitroCommitVerifier(challenge)
+
+          const respond = async (otp: string) => {
+            try {
+              await this.nitroCompleteAuth(challenge.withAnswer(codeChallenge, otp))
+              resolve(true)
+            } catch (e) {
+              resolve(false)
+              throw e
+            }
+          }
+
+          await onPromptOtp(loginHint, respond)
+        }),
+    }
+  }
+}

package/src/sequence/handlers/passkeys.ts

@@ -0,0 +1,84 @@
+import { Signers, State } from '@0xsequence/wallet-core'
+import { Address, Hex } from 'ox'
+import { Kinds } from '../types/signer.js'
+import { Signatures } from '../signatures.js'
+import { Extensions } from '@0xsequence/wallet-primitives'
+import { Handler } from './handler.js'
+import { SignerActionable, SignerUnavailable, BaseSignatureRequest } from '../types/index.js'
+
+export class PasskeysHandler implements Handler {
+  kind = Kinds.LoginPasskey
+
+  constructor(
+    private readonly signatures: Signatures,
+    private readonly extensions: Pick<Extensions.Extensions, 'passkeys'>,
+    private readonly stateReader: State.Reader,
+  ) {}
+
+  onStatusChange(cb: () => void): () => void {
+    return () => {}
+  }
+
+  private async loadPasskey(wallet: Address.Address, imageHash: Hex.Hex): Promise<Signers.Passkey.Passkey | undefined> {
+    try {
+      return await Signers.Passkey.Passkey.loadFromWitness(this.stateReader, this.extensions, wallet, imageHash)
+    } catch (e) {
+      console.warn('Failed to load passkey:', e)
+      return undefined
+    }
+  }
+
+  async status(
+    address: Address.Address,
+    imageHash: Hex.Hex | undefined,
+    request: BaseSignatureRequest,
+  ): Promise<SignerActionable | SignerUnavailable> {
+    const base = { address, imageHash, handler: this }
+    if (address !== this.extensions.passkeys) {
+      console.warn(
+        'PasskeySigner: status address does not match passkey module address',
+        address,
+        this.extensions.passkeys,
+      )
+      const status: SignerUnavailable = {
+        ...base,
+        status: 'unavailable',
+        reason: 'unknown-error',
+      }
+      return status
+    }
+
+    const passkey = imageHash && (await this.loadPasskey(request.envelope.wallet, imageHash))
+    if (!passkey) {
+      console.warn('PasskeySigner: status failed to load passkey', address, imageHash)
+      const status: SignerUnavailable = {
+        ...base,
+        status: 'unavailable',
+        reason: 'unknown-error',
+      }
+      return status
+    }
+
+    const status: SignerActionable = {
+      ...base,
+      status: 'actionable',
+      message: 'request-interaction-with-passkey',
+      imageHash: imageHash,
+      handle: async () => {
+        const signature = await passkey.signSapient(
+          request.envelope.wallet,
+          request.envelope.chainId,
+          request.envelope.payload,
+          imageHash,
+        )
+        await this.signatures.addSignature(request.id, {
+          address,
+          imageHash,
+          signature,
+        })
+        return true
+      },
+    }
+    return status
+  }
+}