@0xsequence/wallet-wdk 3.0.3 → 3.0.5

package/src/sequence/wallets.ts

@@ -8,7 +8,7 @@ import { MnemonicHandler } from './handlers/mnemonic.js'
 import { OtpHandler } from './handlers/otp.js'
 import { Shared } from './manager.js'
 import { Device } from './types/device.js'
-import { Action, Module } from './types/index.js'
+import { Action, Actions, Module } from './types/index.js'
 import { Kinds, SignerWithKind, WitnessExtraSignerKind } from './types/signer.js'
 import { Wallet, WalletSelectionUiHandler } from './types/wallet.js'
 import { PasskeysHandler } from './handlers/passkeys.js'
@@ -28,13 +28,19 @@ function getSignerKindForSignup(kind: SignupArgs['kind'] | AuthCommitment['kind'
   if (kind === 'google-id-token' || kind === 'google-pkce') {
     return Kinds.LoginGoogle
   }
+  if (kind === 'apple-id-token' || kind === 'apple') {
+    return Kinds.LoginApple
+  }
   if (kind.startsWith('custom-')) {
     return kind
   }
   return ('login-' + kind) as string
 }
 
-function getIdTokenSignupHandler(shared: Shared, kind: typeof Kinds.LoginGoogle | `custom-${string}`): IdTokenHandler {
+function getIdTokenSignupHandler(
+  shared: Shared,
+  kind: typeof Kinds.LoginGoogle | typeof Kinds.LoginApple | `custom-${string}`,
+): IdTokenHandler {
   const handler = shared.handlers.get(kind)
   if (!handler) {
     throw new Error('handler-not-registered')
@@ -51,6 +57,12 @@ export type StartSignUpWithRedirectArgs = {
   metadata: { [key: string]: string }
 }
 
+export type StartAddLoginSignerWithRedirectArgs = {
+  wallet: Address.Address
+  kind: 'google-pkce' | 'apple' | `custom-${string}`
+  target: string
+}
+
 export type SignupStatus =
   | { type: 'login-signer-created'; address: Address.Address }
   | { type: 'device-signer-created'; address: Address.Address }
@@ -82,7 +94,7 @@ export type EmailOtpSignupArgs = CommonSignupArgs & {
 }
 
 export type IdTokenSignupArgs = CommonSignupArgs & {
-  kind: 'google-id-token' | `custom-${string}`
+  kind: 'google-id-token' | 'apple-id-token' | `custom-${string}`
   idToken: string
 }
 
@@ -106,6 +118,19 @@ export type SignupArgs =
   | IdTokenSignupArgs
   | AuthCodeSignupArgs
 
+export type AddLoginSignerArgs = {
+  wallet: Address.Address
+} & (
+  | { kind: 'mnemonic'; mnemonic: string }
+  | { kind: 'email-otp'; email: string }
+  | { kind: 'google-id-token' | 'apple-id-token' | `custom-${string}`; idToken: string }
+)
+
+export type RemoveLoginSignerArgs = {
+  wallet: Address.Address
+  signerAddress: Address.Address
+}
+
 export type LoginToWalletArgs = {
   wallet: Address.Address
 }
@@ -222,7 +247,7 @@ export interface WalletsInterface {
    *   - `kind: 'mnemonic'`: Uses a mnemonic phrase as the login credential.
    *   - `kind: 'passkey'`: Prompts the user to create a WebAuthn passkey.
    *   - `kind: 'email-otp'`: Initiates an OTP flow to the user's email.
-   *   - `kind: 'google-id-token'`: Completes an OIDC ID token flow when Google is configured with `authMethod: 'id-token'`.
+   *   - `kind: 'google-id-token' | 'apple-id-token'`: Completes an OIDC ID token flow when the provider is configured with `authMethod: 'id-token'`.
    *   - `kind: 'google-pkce' | 'apple'`: Completes an OAuth redirect flow.
    *   Common options like `noGuard` or `noRecovery` can customize the wallet's security features.
    * @returns A promise that resolves to the address of the newly created wallet, or `undefined` if the sign-up was aborted.
@@ -286,6 +311,66 @@ export interface WalletsInterface {
    */
   completeLogin(requestId: string): Promise<void>
 
+  /**
+   * Adds a new login signer to an existing wallet, enabling account federation.
+   *
+   * This allows a user to link a new login method (e.g., Google, email OTP, mnemonic) to a wallet
+   * that was originally created with a different credential. After federation, the wallet can be
+   * discovered and accessed via any of its linked login methods.
+   *
+   * @param args The arguments specifying the wallet and the new login credential to add.
+   * @returns A promise that resolves to a `requestId` for the configuration update signature request.
+   * @see {completeAddLoginSigner}
+   */
+  addLoginSigner(args: AddLoginSignerArgs): Promise<string>
+
+  /**
+   * Completes the add-login-signer process after the configuration update has been signed.
+   *
+   * @param requestId The ID of the completed signature request returned by `addLoginSigner`.
+   * @returns A promise that resolves when the configuration update has been submitted.
+   */
+  completeAddLoginSigner(requestId: string): Promise<void>
+
+  /**
+   * Initiates an add-login-signer process that involves an OAuth redirect.
+   *
+   * This is the first step for adding a social login signer (e.g., Google, Apple) to an existing wallet
+   * via a redirect-based OAuth flow. It validates the wallet, generates the necessary challenges and state,
+   * stores them locally, and returns a URL. Your application should redirect the user to this URL.
+   *
+   * After the redirect callback, call `completeRedirect` with the returned state and code. This will
+   * create a pending `AddLoginSigner` signature request internally. The caller can then discover
+   * the pending request through the signatures module and call `completeAddLoginSigner` with the requestId
+   * once it has been signed.
+   *
+   * @param args Arguments specifying the wallet, provider (`kind`), and the `target` URL for the redirect callback.
+   * @returns A promise that resolves to the full OAuth URL to which the user should be redirected.
+   * @see {completeRedirect} for the second step of this flow.
+   * @see {completeAddLoginSigner} to finalize after signing.
+   */
+  startAddLoginSignerWithRedirect(args: StartAddLoginSignerWithRedirectArgs): Promise<string>
+
+  /**
+   * Removes a login signer from an existing wallet, enabling account defederation.
+   *
+   * This allows a user to unlink a login method from a wallet. A safety guard ensures
+   * at least one login signer always remains.
+   *
+   * @param args The arguments specifying the wallet and the signer address to remove.
+   * @returns A promise that resolves to a `requestId` for the configuration update signature request.
+   * @see {completeRemoveLoginSigner}
+   */
+  removeLoginSigner(args: RemoveLoginSignerArgs): Promise<string>
+
+  /**
+   * Completes the remove-login-signer process after the configuration update has been signed.
+   *
+   * @param requestId The ID of the completed signature request returned by `removeLoginSigner`.
+   * @returns A promise that resolves when the configuration update has been submitted.
+   */
+  completeRemoveLoginSigner(requestId: string): Promise<void>
+
   /**
    * Logs out from a given wallet, ending the current session.
    *
@@ -411,6 +496,20 @@ export function isIdTokenArgs(args: SignupArgs): args is IdTokenSignupArgs {
   return 'idToken' in args
 }
 
+function addLoginSignerToSignupArgs(args: AddLoginSignerArgs): SignupArgs {
+  switch (args.kind) {
+    case 'mnemonic':
+      return { kind: 'mnemonic', mnemonic: args.mnemonic }
+    case 'email-otp':
+      return { kind: 'email-otp', email: args.email }
+    default: {
+      // google-id-token, apple-id-token, custom-*
+      const _args = args as { kind: string; idToken: string }
+      return { kind: _args.kind as IdTokenSignupArgs['kind'], idToken: _args.idToken }
+    }
+  }
+}
+
 function buildCappedTree(members: { address: Address.Address; imageHash?: Hex.Hex }[]): Config.Topology {
   const loginMemberWeight = 1n
 
@@ -721,8 +820,12 @@ export class Wallets implements WalletsInterface {
         }
       }
 
-      case 'google-id-token': {
-        const handler = getIdTokenSignupHandler(this.shared, Kinds.LoginGoogle)
+      case 'google-id-token':
+      case 'apple-id-token': {
+        const handler = getIdTokenSignupHandler(
+          this.shared,
+          args.kind === 'google-id-token' ? Kinds.LoginGoogle : Kinds.LoginApple,
+        )
         const [signer, metadata] = await handler.completeAuth(args.idToken)
         const loginEmail = metadata.email
         this.shared.modules.logger.log('Created new id token signer:', signer.address)
@@ -730,7 +833,7 @@ export class Wallets implements WalletsInterface {
         return {
           signer,
           extra: {
-            signerKind: Kinds.LoginGoogle,
+            signerKind: getSignerKindForSignup(args.kind),
           },
           loginEmail,
         }
@@ -797,7 +900,27 @@ export class Wallets implements WalletsInterface {
     if (!(handler instanceof AuthCodeHandler)) {
       throw new Error('handler-does-not-support-redirect')
     }
-    return handler.commitAuth(args.target, true)
+    return handler.commitAuth(args.target, { type: 'auth' })
+  }
+
+  async startAddLoginSignerWithRedirect(args: StartAddLoginSignerWithRedirectArgs) {
+    const walletEntry = await this.get(args.wallet)
+    if (!walletEntry) {
+      throw new Error('wallet-not-found')
+    }
+    if (walletEntry.status !== 'ready') {
+      throw new Error('wallet-not-ready')
+    }
+
+    const kind = getSignupHandlerKey(args.kind)
+    const handler = this.shared.handlers.get(kind)
+    if (!handler) {
+      throw new Error('handler-not-registered')
+    }
+    if (!(handler instanceof AuthCodeHandler)) {
+      throw new Error('handler-does-not-support-redirect')
+    }
+    return handler.commitAuth(args.target, { type: 'add-signer', wallet: args.wallet })
   }
 
   async completeRedirect(args: CompleteRedirectArgs): Promise<string> {
@@ -806,28 +929,62 @@ export class Wallets implements WalletsInterface {
       throw new Error('invalid-state')
     }
 
-    // commitment.isSignUp and signUp also mean 'signIn' from wallet's perspective
-    if (commitment.isSignUp) {
-      await this.signUp({
-        kind: commitment.kind,
-        commitment,
-        code: args.code,
-        noGuard: args.noGuard,
-        target: commitment.target,
-        isRedirect: true,
-        use4337: args.use4337,
-      })
-    } else {
-      const handlerKind = getSignupHandlerKey(commitment.kind)
-      const handler = this.shared.handlers.get(handlerKind)
-      if (!handler) {
-        throw new Error('handler-not-registered')
+    switch (commitment.type) {
+      case 'add-signer': {
+        const handlerKind = getSignupHandlerKey(commitment.kind)
+        const handler = this.shared.handlers.get(handlerKind)
+        if (!handler) {
+          throw new Error('handler-not-registered')
+        }
+        if (!(handler instanceof AuthCodeHandler)) {
+          throw new Error('handler-does-not-support-redirect')
+        }
+
+        const walletAddress = commitment.wallet as Address.Address
+        const walletEntry = await this.get(walletAddress)
+        if (!walletEntry) {
+          throw new Error('wallet-not-found')
+        }
+        if (walletEntry.status !== 'ready') {
+          throw new Error('wallet-not-ready')
+        }
+
+        const [signer] = await handler.completeAuth(commitment, args.code)
+        const signerKind = getSignerKindForSignup(commitment.kind)
+
+        await this.addLoginSignerFromPrepared(walletAddress, {
+          signer,
+          extra: { signerKind },
+        })
+        break
       }
-      if (!(handler instanceof AuthCodeHandler)) {
-        throw new Error('handler-does-not-support-redirect')
+
+      case 'auth': {
+        await this.signUp({
+          kind: commitment.kind,
+          commitment,
+          code: args.code,
+          noGuard: args.noGuard,
+          target: commitment.target,
+          isRedirect: true,
+          use4337: args.use4337,
+        })
+        break
       }
 
-      await handler.completeAuth(commitment, args.code)
+      case 'reauth': {
+        const handlerKind = getSignupHandlerKey(commitment.kind)
+        const handler = this.shared.handlers.get(handlerKind)
+        if (!handler) {
+          throw new Error('handler-not-registered')
+        }
+        if (!(handler instanceof AuthCodeHandler)) {
+          throw new Error('handler-does-not-support-redirect')
+        }
+
+        await handler.completeAuth(commitment, args.code)
+        break
+      }
     }
 
     if (!commitment.target) {
@@ -1263,6 +1420,87 @@ export class Wallets implements WalletsInterface {
     })
   }
 
+  async addLoginSigner(args: AddLoginSignerArgs): Promise<string> {
+    const walletEntry = await this.get(args.wallet)
+    if (!walletEntry) {
+      throw new Error('wallet-not-found')
+    }
+    if (walletEntry.status !== 'ready') {
+      throw new Error('wallet-not-ready')
+    }
+
+    const signupArgs = addLoginSignerToSignupArgs(args)
+    const loginSigner = await this.prepareSignUp(signupArgs)
+    return this.addLoginSignerFromPrepared(args.wallet, loginSigner)
+  }
+
+  async completeAddLoginSigner(requestId: string): Promise<void> {
+    const request = await this.shared.modules.signatures.get(requestId)
+    if (request.action !== Actions.AddLoginSigner) {
+      throw new Error('invalid-request-action')
+    }
+    await this.completeConfigurationUpdate(requestId)
+  }
+
+  async removeLoginSigner(args: RemoveLoginSignerArgs): Promise<string> {
+    const walletEntry = await this.get(args.wallet)
+    if (!walletEntry) {
+      throw new Error('wallet-not-found')
+    }
+    if (walletEntry.status !== 'ready') {
+      throw new Error('wallet-not-ready')
+    }
+
+    const { loginTopology, modules } = await this.getConfigurationParts(args.wallet)
+
+    const existingSigners = Config.getSigners(loginTopology)
+    const allExistingAddresses = [...existingSigners.signers, ...existingSigners.sapientSigners.map((s) => s.address)]
+
+    if (!allExistingAddresses.some((addr) => Address.isEqual(addr, args.signerAddress))) {
+      throw new Error('signer-not-found')
+    }
+
+    const remainingMembers = [
+      ...existingSigners.signers
+        .filter((x) => x !== Constants.ZeroAddress && !Address.isEqual(x, args.signerAddress))
+        .map((x) => ({ address: x })),
+      ...existingSigners.sapientSigners
+        .filter((x) => !Address.isEqual(x.address, args.signerAddress))
+        .map((x) => ({ address: x.address, imageHash: x.imageHash })),
+    ]
+
+    if (remainingMembers.length < 1) {
+      throw new Error('cannot-remove-last-login-signer')
+    }
+
+    const nextLoginTopology = buildCappedTree(remainingMembers)
+
+    if (this.shared.modules.sessions.hasSessionModule(modules)) {
+      await this.shared.modules.sessions.removeIdentitySignerFromModules(modules, args.signerAddress)
+    }
+
+    if (this.shared.modules.recovery.hasRecoveryModule(modules)) {
+      await this.shared.modules.recovery.removeRecoverySignerFromModules(modules, args.signerAddress)
+    }
+
+    const requestId = await this.requestConfigurationUpdate(
+      args.wallet,
+      { loginTopology: nextLoginTopology, modules },
+      Actions.RemoveLoginSigner,
+      'wallet-webapp',
+    )
+
+    return requestId
+  }
+
+  async completeRemoveLoginSigner(requestId: string): Promise<void> {
+    const request = await this.shared.modules.signatures.get(requestId)
+    if (request.action !== Actions.RemoveLoginSigner) {
+      throw new Error('invalid-request-action')
+    }
+    await this.completeConfigurationUpdate(requestId)
+  }
+
   async logout<T extends { skipRemoveDevice?: boolean } | undefined = undefined>(
     wallet: Address.Address,
     options?: T,
@@ -1493,4 +1731,54 @@ export class Wallets implements WalletsInterface {
 
     return requestId
   }
+
+  private async addLoginSignerFromPrepared(
+    wallet: Address.Address,
+    loginSigner: {
+      signer: (Signers.Signer | Signers.SapientSigner) & Signers.Witnessable
+      extra: WitnessExtraSignerKind
+    },
+  ): Promise<string> {
+    const newSignerAddress = await loginSigner.signer.address
+
+    const { loginTopology, modules } = await this.getConfigurationParts(wallet)
+
+    // Check for duplicate signer
+    const existingSigners = Config.getSigners(loginTopology)
+    const allExistingAddresses = [...existingSigners.signers, ...existingSigners.sapientSigners.map((s) => s.address)]
+    if (allExistingAddresses.some((addr) => Address.isEqual(addr, newSignerAddress))) {
+      throw new Error('signer-already-exists')
+    }
+
+    // Build new login topology with the additional signer
+    const existingMembers = [
+      ...existingSigners.signers.filter((x) => x !== Constants.ZeroAddress).map((x) => ({ address: x })),
+      ...existingSigners.sapientSigners.map((x) => ({ address: x.address, imageHash: x.imageHash })),
+    ]
+    const newMember = {
+      address: newSignerAddress,
+      imageHash: Signers.isSapientSigner(loginSigner.signer) ? await loginSigner.signer.imageHash : undefined,
+    }
+    const nextLoginTopology = buildCappedTree([...existingMembers, newMember])
+
+    // Add non-sapient login signer to sessions module identity signers
+    if (!Signers.isSapientSigner(loginSigner.signer) && this.shared.modules.sessions.hasSessionModule(modules)) {
+      await this.shared.modules.sessions.addIdentitySignerToModules(modules, newSignerAddress)
+    }
+
+    // Add to recovery module if present
+    if (this.shared.modules.recovery.hasRecoveryModule(modules)) {
+      await this.shared.modules.recovery.addRecoverySignerToModules(modules, newSignerAddress)
+    }
+
+    // Witness so the wallet becomes discoverable via the new credential
+    await loginSigner.signer.witness(this.shared.sequence.stateProvider, wallet, loginSigner.extra)
+
+    return this.requestConfigurationUpdate(
+      wallet,
+      { loginTopology: nextLoginTopology, modules },
+      Actions.AddLoginSigner,
+      'wallet-webapp',
+    )
+  }
 }

package/test/authcode-pkce.test.ts

@@ -90,9 +90,8 @@ describe('AuthCodePkceHandler', () => {
   describe('commitAuth', () => {
     it('Should create Google PKCE auth commitment and return OAuth URL', async () => {
       const target = 'https://example.com/success'
-      const isSignUp = true
 
-      const result = await handler.commitAuth(target, isSignUp)
+      const result = await handler.commitAuth(target, { type: 'auth' })
 
       // Verify nitroCommitVerifier was called with correct challenge
       expect(handler['nitroCommitVerifier']).toHaveBeenCalledWith(
@@ -110,7 +109,7 @@ describe('AuthCodePkceHandler', () => {
         challenge: 'mock-challenge-hash',
         target,
         metadata: {},
-        isSignUp,
+        type: 'auth',
       })
 
       // Verify OAuth URL is constructed correctly
@@ -127,10 +126,13 @@ describe('AuthCodePkceHandler', () => {
 
     it('Should use provided state instead of generating random one', async () => {
       const target = 'https://example.com/success'
-      const isSignUp = false
       const customState = 'custom-state-123'
 
-      const result = await handler.commitAuth(target, isSignUp, customState)
+      const result = await handler.commitAuth(target, {
+        type: 'reauth',
+        state: customState,
+        signer: '0x1234567890123456789012345678901234567890',
+      })
 
       // Verify commitment was saved with custom state
       expect(mockCommitments.set).toHaveBeenCalledWith({
@@ -140,7 +142,8 @@ describe('AuthCodePkceHandler', () => {
         challenge: 'mock-challenge-hash',
         target,
         metadata: {},
-        isSignUp,
+        type: 'reauth',
+        signer: '0x1234567890123456789012345678901234567890',
       })
 
       // Verify URL contains custom state
@@ -149,10 +152,9 @@ describe('AuthCodePkceHandler', () => {
 
     it('Should include signer in challenge when provided', async () => {
       const target = 'https://example.com/success'
-      const isSignUp = true
       const signer = '0x9876543210987654321098765432109876543210'
 
-      await handler.commitAuth(target, isSignUp, undefined, signer)
+      await handler.commitAuth(target, { type: 'reauth', state: 'test-state', signer })
 
       // Verify nitroCommitVerifier was called with signer in challenge
       expect(handler['nitroCommitVerifier']).toHaveBeenCalledWith(
@@ -164,9 +166,8 @@ describe('AuthCodePkceHandler', () => {
 
     it('Should generate random state when not provided', async () => {
       const target = 'https://example.com/success'
-      const isSignUp = true
 
-      const result = await handler.commitAuth(target, isSignUp)
+      const result = await handler.commitAuth(target, { type: 'auth' })
 
       // Verify that a state parameter is present and looks like a hex string
       expect(result).toMatch(/state=0x[a-f0-9]+/)
@@ -181,18 +182,22 @@ describe('AuthCodePkceHandler', () => {
       const target = 'https://example.com/success'
 
       // Test signup
-      await handler.commitAuth(target, true)
+      await handler.commitAuth(target, { type: 'auth' })
       expect(mockCommitments.set).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          isSignUp: true,
+          type: 'auth',
         }),
       )
 
       // Test login
-      await handler.commitAuth(target, false)
+      await handler.commitAuth(target, {
+        type: 'reauth',
+        state: 'test-state',
+        signer: '0x1234567890123456789012345678901234567890',
+      })
       expect(mockCommitments.set).toHaveBeenLastCalledWith(
         expect.objectContaining({
-          isSignUp: false,
+          type: 'reauth',
         }),
       )
     })
@@ -200,13 +205,17 @@ describe('AuthCodePkceHandler', () => {
     it('Should handle errors from nitroCommitVerifier', async () => {
       vi.spyOn(handler as any, 'nitroCommitVerifier').mockRejectedValue(new Error('Nitro service unavailable'))
 
-      await expect(handler.commitAuth('https://example.com/success', true)).rejects.toThrow('Nitro service unavailable')
+      await expect(handler.commitAuth('https://example.com/success', { type: 'auth' })).rejects.toThrow(
+        'Nitro service unavailable',
+      )
     })
 
     it('Should handle database errors during commitment storage', async () => {
       vi.mocked(mockCommitments.set).mockRejectedValue(new Error('Database write failed'))
 
-      await expect(handler.commitAuth('https://example.com/success', true)).rejects.toThrow('Database write failed')
+      await expect(handler.commitAuth('https://example.com/success', { type: 'auth' })).rejects.toThrow(
+        'Database write failed',
+      )
     })
   })
 
@@ -221,7 +230,7 @@ describe('AuthCodePkceHandler', () => {
         challenge: 'test-challenge-hash',
         target: 'https://example.com/success',
         metadata: { scope: 'openid profile email' },
-        isSignUp: true,
+        type: 'auth',
       }
     })
 
@@ -333,7 +342,7 @@ describe('AuthCodePkceHandler', () => {
       const newRedirectUri = 'https://newdomain.com/callback'
       handler.setRedirectUri(newRedirectUri)
 
-      return handler.commitAuth('https://example.com/success', true).then((result) => {
+      return handler.commitAuth('https://example.com/success', { type: 'auth' }).then((result) => {
         expect(result).toContain(`redirect_uri=${encodeURIComponent(newRedirectUri)}`)
       })
     })