@originals/auth 1.5.0

package/src/client/turnkey-client.ts

@@ -0,0 +1,340 @@
+/**
+ * Client-side Turnkey utilities
+ * Handles Turnkey client initialization and authentication flow in the browser
+ */
+
+import { TurnkeyClient, OtpType, WalletAccount } from '@turnkey/core';
+import type { TurnkeyWallet } from '../types';
+
+/**
+ * Session expired error for handling token expiration
+ */
+export class TurnkeySessionExpiredError extends Error {
+  constructor(message: string = 'Your Turnkey session has expired. Please log in again.') {
+    super(message);
+    this.name = 'TurnkeySessionExpiredError';
+  }
+}
+
+/**
+ * Wrapper to handle token expiration errors
+ */
+export async function withTokenExpiration<T>(
+  fn: () => Promise<T>,
+  onExpired?: () => void
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    const errorStr = JSON.stringify(error);
+    if (
+      errorStr.toLowerCase().includes('api_key_expired') ||
+      errorStr.toLowerCase().includes('expired api key') ||
+      errorStr.toLowerCase().includes('"code":16')
+    ) {
+      console.warn('Detected expired API key, calling onExpired');
+      if (onExpired) {
+        onExpired();
+      }
+      throw new TurnkeySessionExpiredError();
+    }
+    throw error;
+  }
+}
+
+/**
+ * Initialize Turnkey client with auth proxy configuration
+ */
+export function initializeTurnkeyClient(): TurnkeyClient {
+  // Access Vite environment variables
+  const env = (import.meta as { env?: Record<string, string | undefined> }).env;
+  const authProxyConfigId = env?.VITE_TURNKEY_AUTH_PROXY_CONFIG_ID;
+  const organizationId = env?.VITE_TURNKEY_ORGANIZATION_ID ?? '';
+
+  if (!authProxyConfigId) {
+    throw new Error('VITE_TURNKEY_AUTH_PROXY_CONFIG_ID environment variable not set');
+  }
+
+  return new TurnkeyClient({
+    authProxyConfigId,
+    organizationId,
+  });
+}
+
+/**
+ * Send OTP code to email
+ */
+export async function initOtp(turnkeyClient: TurnkeyClient, email: string): Promise<string> {
+  try {
+    const response = await turnkeyClient.initOtp({
+      otpType: OtpType.Email,
+      contact: email,
+    });
+
+    if (!response || typeof response !== 'string') {
+      throw new Error('No OTP ID returned from Turnkey');
+    }
+
+    return response;
+  } catch (error) {
+    console.error('Error initializing OTP:', error);
+    throw new Error(
+      `Failed to send OTP: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Complete OTP authentication flow (verifies OTP and logs in/signs up)
+ */
+export async function completeOtp(
+  turnkeyClient: TurnkeyClient,
+  otpId: string,
+  otpCode: string,
+  email: string
+): Promise<{ sessionToken: string; userId: string; action: 'login' | 'signup' }> {
+  try {
+    const response = await turnkeyClient.completeOtp({
+      otpId,
+      otpCode,
+      contact: email,
+      otpType: OtpType.Email,
+    });
+
+    if (!response.sessionToken) {
+      throw new Error('No session token returned from completeOtp');
+    }
+
+    // Fetch user info to get stable identifiers
+    const userInfo = await turnkeyClient.fetchUser();
+
+    return {
+      sessionToken: response.sessionToken,
+      userId: userInfo.userId,
+      action: response.action === 'LOGIN' ? 'login' : 'signup',
+    };
+  } catch (error) {
+    console.error('Error completing OTP:', error);
+    throw new Error(
+      `Failed to complete OTP: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Fetch user information
+ */
+export async function fetchUser(
+  turnkeyClient: TurnkeyClient,
+  onExpired?: () => void
+): Promise<unknown> {
+  return withTokenExpiration(async () => {
+    try {
+      const response = await turnkeyClient.fetchUser();
+      return response;
+    } catch (error) {
+      console.error('Error fetching user:', error);
+      throw new Error(
+        `Failed to fetch user: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }, onExpired);
+}
+
+/**
+ * Fetch user's wallets
+ */
+export async function fetchWallets(
+  turnkeyClient: TurnkeyClient,
+  onExpired?: () => void
+): Promise<TurnkeyWallet[]> {
+  return withTokenExpiration(async () => {
+    try {
+      const response = await turnkeyClient.fetchWallets();
+
+      const wallets: TurnkeyWallet[] = [];
+
+      for (const wallet of response || []) {
+        const accountsResponse = await turnkeyClient.fetchWalletAccounts({
+          wallet: wallet,
+        });
+
+        wallets.push({
+          walletId: wallet.walletId,
+          walletName: wallet.walletName,
+          accounts: accountsResponse.map((acc: WalletAccount) => ({
+            address: acc.address,
+            curve: acc.curve as 'CURVE_SECP256K1' | 'CURVE_ED25519',
+            path: acc.path,
+            addressFormat: acc.addressFormat,
+          })),
+        });
+      }
+
+      return wallets;
+    } catch (error) {
+      console.error('Error fetching wallets:', error);
+      throw new Error(
+        `Failed to fetch wallets: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }, onExpired);
+}
+
+/**
+ * Get key by curve type
+ */
+export function getKeyByCurve(
+  wallets: TurnkeyWallet[],
+  curve: 'CURVE_SECP256K1' | 'CURVE_ED25519'
+): WalletAccount | null {
+  for (const wallet of wallets) {
+    for (const account of wallet.accounts) {
+      if (account.curve === curve) {
+        return account as unknown as WalletAccount;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Create a wallet with the required accounts for DID creation
+ */
+export async function createWalletWithAccounts(
+  turnkeyClient: TurnkeyClient,
+  onExpired?: () => void
+): Promise<TurnkeyWallet> {
+  return withTokenExpiration(async () => {
+    try {
+      const response = await turnkeyClient.createWallet({
+        walletName: 'default-wallet',
+        accounts: [
+          {
+            curve: 'CURVE_SECP256K1',
+            pathFormat: 'PATH_FORMAT_BIP32',
+            path: "m/44'/0'/0'/0/0",
+            addressFormat: 'ADDRESS_FORMAT_BITCOIN_MAINNET_P2TR',
+          },
+          {
+            curve: 'CURVE_ED25519',
+            pathFormat: 'PATH_FORMAT_BIP32',
+            path: "m/44'/501'/0'/0'",
+            addressFormat: 'ADDRESS_FORMAT_SOLANA',
+          },
+          {
+            curve: 'CURVE_ED25519',
+            pathFormat: 'PATH_FORMAT_BIP32',
+            path: "m/44'/501'/1'/0'",
+            addressFormat: 'ADDRESS_FORMAT_SOLANA',
+          },
+        ],
+      });
+
+      let walletId: string;
+      if (typeof response === 'string') {
+        walletId = response;
+      } else {
+        walletId = (response as { walletId?: string })?.walletId ?? '';
+      }
+
+      if (!walletId) {
+        throw new Error('No wallet ID returned from createWallet');
+      }
+
+      // Wait for wallet to be created, then fetch it
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const wallets = await fetchWallets(turnkeyClient, onExpired);
+      const createdWallet = wallets.find((w) => w.walletId === walletId);
+
+      if (!createdWallet) {
+        throw new Error('Failed to fetch created wallet');
+      }
+
+      return createdWallet;
+    } catch (error) {
+      console.error('Error creating wallet:', error);
+      throw new Error(
+        `Failed to create wallet: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }, onExpired);
+}
+
+/**
+ * Ensure user has a wallet with the required accounts for DID creation
+ */
+export async function ensureWalletWithAccounts(
+  turnkeyClient: TurnkeyClient,
+  onExpired?: () => void
+): Promise<TurnkeyWallet[]> {
+  return withTokenExpiration(async () => {
+    try {
+      let wallets = await fetchWallets(turnkeyClient, onExpired);
+
+      if (wallets.length === 0) {
+        console.log('No wallets found, creating new wallet with accounts...');
+        const newWallet = await createWalletWithAccounts(turnkeyClient, onExpired);
+        wallets = [newWallet];
+        return wallets;
+      }
+
+      const defaultWallet = wallets[0];
+      const allAccounts = defaultWallet.accounts;
+      const secp256k1Accounts = allAccounts.filter((acc) => acc.curve === 'CURVE_SECP256K1');
+      const ed25519Accounts = allAccounts.filter((acc) => acc.curve === 'CURVE_ED25519');
+
+      // Check if we need more accounts
+      if (secp256k1Accounts.length >= 1 && ed25519Accounts.length >= 2) {
+        return wallets;
+      }
+
+      // Need to create additional accounts
+      const accountsToCreate: Array<{
+        curve: 'CURVE_SECP256K1' | 'CURVE_ED25519';
+        pathFormat: 'PATH_FORMAT_BIP32';
+        path: string;
+        addressFormat: 'ADDRESS_FORMAT_BITCOIN_MAINNET_P2TR' | 'ADDRESS_FORMAT_SOLANA';
+      }> = [];
+
+      if (secp256k1Accounts.length === 0) {
+        accountsToCreate.push({
+          curve: 'CURVE_SECP256K1',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: "m/44'/0'/0'/0/0",
+          addressFormat: 'ADDRESS_FORMAT_BITCOIN_MAINNET_P2TR',
+        });
+      }
+
+      const ed25519Needed = 2 - ed25519Accounts.length;
+      for (let i = 0; i < ed25519Needed; i++) {
+        const pathIndex = ed25519Accounts.length + i;
+        accountsToCreate.push({
+          curve: 'CURVE_ED25519',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: pathIndex === 0 ? "m/44'/501'/0'/0'" : "m/44'/501'/1'/0'",
+          addressFormat: 'ADDRESS_FORMAT_SOLANA',
+        });
+      }
+
+      if (accountsToCreate.length > 0) {
+        console.log(`Creating ${accountsToCreate.length} missing account(s)...`);
+        await turnkeyClient.createWalletAccounts({
+          walletId: defaultWallet.walletId,
+          accounts: accountsToCreate,
+        });
+
+        wallets = await fetchWallets(turnkeyClient, onExpired);
+      }
+
+      return wallets;
+    } catch (error) {
+      console.error('Error ensuring wallet with accounts:', error);
+      throw new Error(
+        `Failed to ensure wallet with accounts: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }, onExpired);
+}
+

package/src/client/turnkey-did-signer.ts

@@ -0,0 +1,189 @@
+/**
+ * Turnkey DID Signer Adapter
+ * Adapts Turnkey signing to work with didwebvh-ts signer interface
+ */
+
+import { TurnkeyClient, WalletAccount } from '@turnkey/core';
+import { OriginalsSDK, encoding } from '@originals/sdk';
+import { TurnkeySessionExpiredError, withTokenExpiration } from './turnkey-client';
+
+interface SigningInput {
+  document: Record<string, unknown>;
+  proof: Record<string, unknown>;
+}
+
+interface SigningOutput {
+  proofValue: string;
+}
+
+/**
+ * Signer that uses Turnkey for signing DID documents
+ * Compatible with didwebvh-ts signer interface
+ */
+export class TurnkeyDIDSigner {
+  private turnkeyClient: TurnkeyClient;
+  private walletAccount: WalletAccount;
+  private publicKeyMultibase: string;
+  private onExpired?: () => void;
+
+  constructor(
+    turnkeyClient: TurnkeyClient,
+    walletAccount: WalletAccount,
+    publicKeyMultibase: string,
+    onExpired?: () => void
+  ) {
+    this.turnkeyClient = turnkeyClient;
+    this.walletAccount = walletAccount;
+    this.publicKeyMultibase = publicKeyMultibase;
+    this.onExpired = onExpired;
+  }
+
+  /**
+   * Sign the document and proof using Turnkey
+   */
+  async sign(input: SigningInput): Promise<SigningOutput> {
+    return withTokenExpiration(async () => {
+      try {
+        // Use SDK's prepareDIDDataForSigning
+        const dataToSign = await OriginalsSDK.prepareDIDDataForSigning(input.document, input.proof);
+
+        // Sign with Turnkey
+        const response = await this.turnkeyClient.httpClient.signRawPayload({
+          signWith: this.walletAccount.address,
+          payload: Buffer.from(dataToSign).toString('hex'),
+          encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
+          hashFunction: 'HASH_FUNCTION_NOT_APPLICABLE',
+        });
+
+        if (!response.r || !response.s) {
+          throw new Error('Invalid signature response from Turnkey');
+        }
+
+        // For Ed25519, combine r+s only (64 bytes total)
+        const cleanR = response.r.startsWith('0x') ? response.r.slice(2) : response.r;
+        const cleanS = response.s.startsWith('0x') ? response.s.slice(2) : response.s;
+        const combinedHex = cleanR + cleanS;
+
+        const signatureBytes = Buffer.from(combinedHex, 'hex');
+
+        if (signatureBytes.length !== 64) {
+          throw new Error(
+            `Invalid Ed25519 signature length: ${signatureBytes.length} (expected 64 bytes)`
+          );
+        }
+
+        const proofValue = encoding.multibase.encode(signatureBytes, 'base58btc');
+
+        return { proofValue };
+      } catch (error) {
+        console.error('[TurnkeyDIDSigner] Error signing with Turnkey:', error);
+
+        const errorStr = JSON.stringify(error);
+        if (
+          errorStr.toLowerCase().includes('api_key_expired') ||
+          errorStr.toLowerCase().includes('expired api key') ||
+          errorStr.toLowerCase().includes('"code":16')
+        ) {
+          console.warn('Detected expired API key in sign method, calling onExpired');
+          if (this.onExpired) {
+            this.onExpired();
+          }
+          throw new TurnkeySessionExpiredError();
+        }
+
+        throw error;
+      }
+    }, this.onExpired);
+  }
+
+  /**
+   * Get the verification method ID for this signer
+   */
+  getVerificationMethodId(): string {
+    return `did:key:${this.publicKeyMultibase}`;
+  }
+
+  /**
+   * Verify a signature
+   */
+  async verify(
+    signature: Uint8Array,
+    message: Uint8Array,
+    publicKey: Uint8Array
+  ): Promise<boolean> {
+    try {
+      return await OriginalsSDK.verifyDIDSignature(signature, message, publicKey);
+    } catch (error) {
+      console.error('[TurnkeyDIDSigner] Error verifying signature:', error);
+      return false;
+    }
+  }
+}
+
+/**
+ * Create a DID:WebVH using OriginalsSDK.createDIDOriginal() with Turnkey signing
+ */
+export async function createDIDWithTurnkey(params: {
+  turnkeyClient: TurnkeyClient;
+  updateKeyAccount: WalletAccount;
+  authKeyPublic: string;
+  assertionKeyPublic: string;
+  updateKeyPublic: string;
+  domain: string;
+  slug: string;
+  onExpired?: () => void;
+}): Promise<{
+  did: string;
+  didDocument: unknown;
+  didLog: unknown;
+}> {
+  const {
+    turnkeyClient,
+    updateKeyAccount,
+    authKeyPublic,
+    assertionKeyPublic,
+    updateKeyPublic,
+    domain,
+    slug,
+    onExpired,
+  } = params;
+
+  // Create Turnkey signer for the update key
+  const signer = new TurnkeyDIDSigner(turnkeyClient, updateKeyAccount, updateKeyPublic, onExpired);
+
+  // Use SDK's createDIDOriginal
+  const result = await OriginalsSDK.createDIDOriginal({
+    type: 'did',
+    domain,
+    signer,
+    verifier: signer,
+    updateKeys: [signer.getVerificationMethodId()],
+    verificationMethods: [
+      {
+        id: '#key-0',
+        type: 'Multikey',
+        controller: '',
+        publicKeyMultibase: authKeyPublic,
+      },
+      {
+        id: '#key-1',
+        type: 'Multikey',
+        controller: '',
+        publicKeyMultibase: assertionKeyPublic,
+      },
+    ],
+    paths: [slug],
+    portable: false,
+    authentication: ['#key-0'],
+    assertionMethod: ['#key-1'],
+  });
+
+  return {
+    did: result.did,
+    didDocument: result.doc,
+    didLog: result.log,
+  };
+}
+
+
+

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @originals/auth - Turnkey-based authentication for the Originals Protocol
+ *
+ * This package provides authentication utilities for both server and client applications.
+ *
+ * Server-side:
+ * ```typescript
+ * import { createAuthMiddleware, initiateEmailAuth, verifyEmailAuth } from '@originals/auth/server';
+ * ```
+ *
+ * Client-side (pure functions, no React):
+ * ```typescript
+ * import { initializeTurnkeyClient, initOtp, completeOtp, fetchWallets } from '@originals/auth/client';
+ * ```
+ *
+ * Types:
+ * ```typescript
+ * import type { AuthUser, TokenPayload, TurnkeyWallet } from '@originals/auth/types';
+ * ```
+ */
+
+// Re-export types
+export * from './types';
+
+// Re-export server utilities (for convenience, though subpath is preferred)
+export * from './server';
+
+// Note: Client utilities should be imported from '@originals/auth/client'
+// to avoid bundling React in server environments
+
+
+