@originals/auth 1.5.0

package/src/server/turnkey-client.ts

@@ -0,0 +1,152 @@
+/**
+ * Server-side Turnkey client utilities
+ */
+
+import { Turnkey } from '@turnkey/sdk-server';
+
+export interface TurnkeyClientConfig {
+  /** Turnkey API base URL (default: https://api.turnkey.com) */
+  apiBaseUrl?: string;
+  /** Turnkey API public key */
+  apiPublicKey: string;
+  /** Turnkey API private key */
+  apiPrivateKey: string;
+  /** Default organization ID */
+  organizationId: string;
+}
+
+/**
+ * Create a Turnkey server client
+ */
+export function createTurnkeyClient(config?: Partial<TurnkeyClientConfig>): Turnkey {
+  const apiPublicKey = config?.apiPublicKey ?? process.env.TURNKEY_API_PUBLIC_KEY;
+  const apiPrivateKey = config?.apiPrivateKey ?? process.env.TURNKEY_API_PRIVATE_KEY;
+  const organizationId = config?.organizationId ?? process.env.TURNKEY_ORGANIZATION_ID;
+
+  if (!apiPublicKey) {
+    throw new Error('TURNKEY_API_PUBLIC_KEY is required');
+  }
+  if (!apiPrivateKey) {
+    throw new Error('TURNKEY_API_PRIVATE_KEY is required');
+  }
+  if (!organizationId) {
+    throw new Error('TURNKEY_ORGANIZATION_ID is required');
+  }
+
+  return new Turnkey({
+    apiBaseUrl: config?.apiBaseUrl ?? 'https://api.turnkey.com',
+    apiPublicKey,
+    apiPrivateKey,
+    defaultOrganizationId: organizationId,
+  });
+}
+
+/**
+ * Get or create a Turnkey sub-organization for a user
+ * Creates sub-org with email-only root user and required wallet accounts
+ */
+export async function getOrCreateTurnkeySubOrg(
+  email: string,
+  turnkeyClient: Turnkey
+): Promise<string> {
+  const organizationId = process.env.TURNKEY_ORGANIZATION_ID;
+  if (!organizationId) {
+    throw new Error('TURNKEY_ORGANIZATION_ID is required');
+  }
+
+  // Generate a consistent base name for lookup
+  const baseSubOrgName = `user-${email.replace(/[^a-z0-9]/gi, '-').toLowerCase()}`;
+
+  console.log(`🔍 Checking for existing sub-organization for ${email}...`);
+
+  try {
+    // Try to get existing sub-organizations by email filter
+    const subOrgs = await turnkeyClient.apiClient().getSubOrgIds({
+      organizationId,
+      filterType: 'EMAIL',
+      filterValue: email,
+    });
+
+    const subOrgIds = subOrgs.organizationIds || [];
+    const existingSubOrgId = subOrgIds.length > 0 ? subOrgIds[0] : null;
+
+    if (existingSubOrgId) {
+      console.log(`✅ Found existing sub-organization: ${existingSubOrgId}`);
+
+      // Check if this sub-org has a wallet
+      try {
+        const walletsCheck = await turnkeyClient.apiClient().getWallets({
+          organizationId: existingSubOrgId,
+        });
+        const walletCount = walletsCheck.wallets?.length || 0;
+
+        if (walletCount > 0) {
+          return existingSubOrgId;
+        }
+
+        console.log(`⚠️ Sub-org has no wallet, creating new sub-org with wallet...`);
+      } catch (walletCheckErr) {
+        console.error('Could not check wallet in sub-org:', walletCheckErr);
+        return existingSubOrgId;
+      }
+    }
+  } catch (lookupError) {
+    console.log(`📝 No existing sub-org found, will create new one`);
+  }
+
+  // Generate a unique name for the new sub-org
+  const subOrgName = `${baseSubOrgName}-${Date.now()}`;
+
+  console.log(`📧 Creating new Turnkey sub-organization for ${email}...`);
+
+  // Create sub-organization with wallet containing required keys
+  const result = await turnkeyClient.apiClient().createSubOrganization({
+    subOrganizationName: subOrgName,
+    rootUsers: [
+      {
+        userName: email,
+        userEmail: email,
+        apiKeys: [],
+        authenticators: [],
+        oauthProviders: [],
+      },
+    ],
+    rootQuorumThreshold: 1,
+    wallet: {
+      walletName: 'default-wallet',
+      accounts: [
+        {
+          curve: 'CURVE_SECP256K1',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: "m/44'/0'/0'/0/0", // Bitcoin path for auth-key
+          addressFormat: 'ADDRESS_FORMAT_ETHEREUM',
+        },
+        {
+          curve: 'CURVE_ED25519',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: "m/44'/501'/0'/0'", // Ed25519 for assertion-key
+          addressFormat: 'ADDRESS_FORMAT_SOLANA',
+        },
+        {
+          curve: 'CURVE_ED25519',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: "m/44'/501'/1'/0'", // Ed25519 for update-key
+          addressFormat: 'ADDRESS_FORMAT_SOLANA',
+        },
+      ],
+    },
+  });
+
+  const subOrgId = result.activity?.result?.createSubOrganizationResultV7?.subOrganizationId;
+
+  if (!subOrgId) {
+    throw new Error('No sub-organization ID returned from Turnkey');
+  }
+
+  console.log(`✅ Created sub-organization: ${subOrgId}`);
+
+  return subOrgId;
+}
+
+
+

package/src/server/turnkey-signer.ts

@@ -0,0 +1,170 @@
+/**
+ * Turnkey Signer - Integration between Turnkey key management and Originals SDK
+ *
+ * Provides an ExternalSigner implementation that works with Turnkey-managed
+ * keys for use with the Originals SDK's DID creation and signing operations.
+ */
+
+import { Turnkey } from '@turnkey/sdk-server';
+import { ExternalSigner, ExternalVerifier, multikey, OriginalsSDK } from '@originals/sdk';
+import { sha512 } from '@noble/hashes/sha2.js';
+import { concatBytes, bytesToHex } from '@noble/hashes/utils.js';
+import * as ed25519 from '@noble/ed25519';
+
+// Configure @noble/ed25519 with required SHA-512 function
+const sha512Fn = (...msgs: Uint8Array[]): Uint8Array => sha512(concatBytes(...msgs));
+
+// Initialize Ed25519 configuration
+try {
+  const ed25519Module = ed25519 as unknown as {
+    utils?: { sha512Sync?: typeof sha512Fn };
+    etc?: { sha512Sync?: typeof sha512Fn };
+  };
+  if (ed25519Module.utils) {
+    ed25519Module.utils.sha512Sync = sha512Fn;
+  }
+  if (ed25519Module.etc) {
+    ed25519Module.etc.sha512Sync = sha512Fn;
+  }
+} catch (error) {
+  console.warn('Failed to configure ed25519 utils:', error);
+}
+
+/**
+ * Turnkey-based signer for use with Originals SDK
+ * Implements the ExternalSigner and ExternalVerifier interfaces
+ */
+export class TurnkeyWebVHSigner implements ExternalSigner, ExternalVerifier {
+  private subOrgId: string;
+  private keyId: string;
+  private publicKeyMultibase: string;
+  private turnkeyClient: Turnkey;
+  private verificationMethodId: string;
+
+  constructor(
+    subOrgId: string,
+    keyId: string,
+    publicKeyMultibase: string,
+    turnkeyClient: Turnkey,
+    verificationMethodId: string
+  ) {
+    this.subOrgId = subOrgId;
+    this.keyId = keyId;
+    this.publicKeyMultibase = publicKeyMultibase;
+    this.turnkeyClient = turnkeyClient;
+    this.verificationMethodId = verificationMethodId;
+  }
+
+  /**
+   * Sign data using Turnkey's API
+   */
+  async sign(input: {
+    document: Record<string, unknown>;
+    proof: Record<string, unknown>;
+  }): Promise<{ proofValue: string }> {
+    try {
+      // Prepare the data for signing using the SDK's canonical approach
+      const dataToSign = await OriginalsSDK.prepareDIDDataForSigning(input.document, input.proof);
+
+      // Convert canonical data to hex format for Turnkey's sign API
+      const dataHex = `0x${bytesToHex(dataToSign)}`;
+
+      // Sign using Turnkey's API
+      const result = await this.turnkeyClient.apiClient().signRawPayload({
+        organizationId: this.subOrgId,
+        signWith: this.keyId,
+        payload: dataHex,
+        encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
+        hashFunction: 'HASH_FUNCTION_NO_OP',
+      });
+
+      const signRawResult = result.activity?.result?.signRawPayloadResult;
+      if (!signRawResult?.r || !signRawResult?.s) {
+        throw new Error('No signature returned from Turnkey');
+      }
+
+      const signature = signRawResult.r + signRawResult.s;
+
+      // Convert signature to bytes
+      const cleanSig = signature.startsWith('0x') ? signature.slice(2) : signature;
+      let signatureBytes = Buffer.from(cleanSig, 'hex');
+
+      // Ed25519 signatures should be exactly 64 bytes
+      if (signatureBytes.length === 65) {
+        signatureBytes = signatureBytes.slice(0, 64);
+      } else if (signatureBytes.length !== 64) {
+        throw new Error(
+          `Invalid Ed25519 signature length: ${signatureBytes.length} (expected 64 bytes)`
+        );
+      }
+
+      // Encode signature as multibase
+      const proofValue = multikey.encodeMultibase(signatureBytes);
+      return { proofValue };
+    } catch (error) {
+      console.error('Error signing with Turnkey:', error);
+      throw new Error(
+        `Failed to sign with Turnkey: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Verify a signature
+   */
+  async verify(
+    signature: Uint8Array,
+    message: Uint8Array,
+    publicKey: Uint8Array
+  ): Promise<boolean> {
+    try {
+      // Ed25519 public keys must be exactly 32 bytes
+      let ed25519PublicKey = publicKey;
+      if (publicKey.length === 33) {
+        ed25519PublicKey = publicKey.slice(1);
+      } else if (publicKey.length !== 32) {
+        return false;
+      }
+
+      const ed25519Module = ed25519 as unknown as {
+        utils?: { sha512Sync?: typeof sha512Fn };
+      };
+      if (typeof ed25519Module.utils?.sha512Sync !== 'function') {
+        ed25519Module.utils!.sha512Sync = sha512Fn;
+      }
+
+      return await ed25519.verify(signature, message, ed25519PublicKey);
+    } catch (error) {
+      console.error('Error verifying signature:', error);
+      return false;
+    }
+  }
+
+  getVerificationMethodId(): string {
+    return this.verificationMethodId;
+  }
+
+  getPublicKeyMultibase(): string {
+    return this.publicKeyMultibase;
+  }
+}
+
+/**
+ * Create a Turnkey signer for use with the Originals SDK
+ */
+export async function createTurnkeySigner(
+  subOrgId: string,
+  keyId: string,
+  turnkeyClient: Turnkey,
+  verificationMethodId: string,
+  publicKeyMultibase: string
+): Promise<TurnkeyWebVHSigner> {
+  return new TurnkeyWebVHSigner(
+    subOrgId,
+    keyId,
+    publicKeyMultibase,
+    turnkeyClient,
+    verificationMethodId
+  );
+}
+

package/src/types.ts

@@ -0,0 +1,168 @@
+/**
+ * Shared types for @originals/auth
+ */
+
+/**
+ * Authenticated user information
+ */
+export interface AuthUser {
+  /** Database user ID */
+  id: string;
+  /** User's email address */
+  email: string;
+  /** User's DID identifier */
+  did: string;
+  /** Turnkey sub-organization ID */
+  turnkeySubOrgId: string;
+}
+
+/**
+ * JWT token payload structure
+ */
+export interface TokenPayload {
+  /** Subject - Turnkey sub-organization ID (stable identifier) */
+  sub: string;
+  /** User email (metadata) */
+  email: string;
+  /** Optional Turnkey session token for user authentication */
+  sessionToken?: string;
+  /** Issued at timestamp */
+  iat: number;
+  /** Expiration timestamp */
+  exp: number;
+}
+
+/**
+ * Options for creating auth middleware
+ */
+export interface AuthMiddlewareOptions {
+  /** Function to look up user by Turnkey sub-org ID */
+  getUserByTurnkeyId: (turnkeyId: string) => Promise<AuthUser | null>;
+  /** Optional function to create user on first auth */
+  createUser?: (turnkeyId: string, email: string, temporaryDid: string) => Promise<AuthUser>;
+  /** Cookie name for JWT token (default: 'auth_token') */
+  cookieName?: string;
+  /** JWT secret (default: process.env.JWT_SECRET) */
+  jwtSecret?: string;
+}
+
+/**
+ * Email authentication session
+ */
+export interface EmailAuthSession {
+  /** User's email address */
+  email: string;
+  /** Turnkey sub-organization ID */
+  subOrgId?: string;
+  /** Turnkey OTP ID */
+  otpId?: string;
+  /** Session creation timestamp */
+  timestamp: number;
+  /** Whether the session has been verified */
+  verified: boolean;
+}
+
+/**
+ * Result of initiating email authentication
+ */
+export interface InitiateAuthResult {
+  /** Session ID for verification step */
+  sessionId: string;
+  /** User-friendly message */
+  message: string;
+}
+
+/**
+ * Result of verifying email authentication
+ */
+export interface VerifyAuthResult {
+  /** Whether verification was successful */
+  verified: boolean;
+  /** User's email address */
+  email: string;
+  /** Turnkey sub-organization ID */
+  subOrgId: string;
+}
+
+/**
+ * Cookie configuration for auth tokens
+ */
+export interface AuthCookieConfig {
+  /** Cookie name */
+  name: string;
+  /** Cookie value (JWT token) */
+  value: string;
+  /** Cookie options */
+  options: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: 'strict' | 'lax' | 'none';
+    maxAge: number;
+    path: string;
+  };
+}
+
+/**
+ * Turnkey wallet information
+ */
+export interface TurnkeyWallet {
+  /** Wallet ID */
+  walletId: string;
+  /** Wallet name */
+  walletName: string;
+  /** Wallet accounts */
+  accounts: TurnkeyWalletAccount[];
+}
+
+/**
+ * Turnkey wallet account
+ */
+export interface TurnkeyWalletAccount {
+  /** Account address */
+  address: string;
+  /** Cryptographic curve */
+  curve: 'CURVE_SECP256K1' | 'CURVE_ED25519';
+  /** Derivation path */
+  path: string;
+  /** Address format */
+  addressFormat: string;
+}
+
+/**
+ * Client-side Turnkey authentication state
+ */
+export interface TurnkeyAuthState {
+  /** Whether the user is authenticated */
+  isAuthenticated: boolean;
+  /** Whether an auth operation is in progress */
+  isLoading: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** User's email address */
+  email: string | null;
+  /** User's wallets */
+  wallets: TurnkeyWallet[];
+  /** OTP ID for verification step */
+  otpId: string | null;
+}
+
+/**
+ * Request context with authenticated user
+ */
+export interface AuthenticatedRequest {
+  user: {
+    /** Database user ID */
+    id: string;
+    /** Turnkey sub-organization ID */
+    turnkeySubOrgId: string;
+    /** User's email */
+    email: string;
+    /** User's DID */
+    did: string;
+    /** Turnkey session token (if available) */
+    sessionToken?: string;
+  };
+}
+
+
+

package/tests/index.test.ts

@@ -0,0 +1,25 @@
+import { describe, test, expect } from 'bun:test';
+
+describe('@originals/auth', () => {
+  test('package exports are defined', async () => {
+    // Test that the main exports are accessible
+    const auth = await import('../src/index');
+    expect(auth).toBeDefined();
+  });
+
+  test('server exports are defined', async () => {
+    const server = await import('../src/server/index');
+    expect(server).toBeDefined();
+  });
+
+  test('client exports are defined', async () => {
+    const client = await import('../src/client/index');
+    expect(client).toBeDefined();
+  });
+
+  test('types are defined', async () => {
+    const types = await import('../src/types');
+    expect(types).toBeDefined();
+  });
+});
+

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "lib": ["ES2022", "DOM"],
+    "types": ["bun-types"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+
+
+