@oxyhq/services 5.16.33 → 5.16.35

package/src/shared/crypto/signature.ts

@@ -0,0 +1,235 @@
+/**
+ * Signature Verification Service
+ * 
+ * Unified signature verification used by both backend (API) and SDK.
+ * Uses platform adapters for crypto operations while keeping message construction shared.
+ */
+
+import { ec as EC } from 'elliptic';
+import { getCryptoAdapter, PlatformDetector } from './platform';
+import {
+  buildAuthMessage,
+  buildRegistrationMessage,
+  buildRequestMessage,
+  isTimestampFresh,
+} from './messageBuilders';
+
+const ec = new EC('secp256k1');
+
+/**
+ * Maximum age for signed messages (5 minutes)
+ */
+export const MAX_SIGNATURE_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * Challenge TTL (5 minutes)
+ */
+export const CHALLENGE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Signature Service
+ * Provides signature verification that works across all platforms
+ */
+export class SignatureService {
+  /**
+   * Verify an ECDSA signature
+   * 
+   * @param message - The original message that was signed
+   * @param signature - The signature in DER format (hex encoded)
+   * @param publicKey - The public key (hex encoded, uncompressed)
+   * @returns true if the signature is valid
+   */
+  static async verify(
+    message: string,
+    signature: string,
+    publicKey: string
+  ): Promise<boolean> {
+    try {
+      const key = ec.keyFromPublic(publicKey, 'hex');
+      const adapter = await getCryptoAdapter();
+      const messageHash = await adapter.sha256(message);
+      return key.verify(messageHash, signature);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Synchronous signature verification (Node.js only)
+   * Uses Node.js crypto module directly for hashing
+   */
+  static verifySync(
+    message: string,
+    signature: string,
+    publicKey: string
+  ): boolean {
+    if (!PlatformDetector.isNode()) {
+      throw new Error(
+        'verifySync should only be used in Node.js. Use verify() in other environments.'
+      );
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-implied-eval
+      const getCrypto = new Function('return require("crypto")');
+      const crypto = getCrypto();
+      const key = ec.keyFromPublic(publicKey, 'hex');
+      const messageHash = crypto.createHash('sha256').update(message).digest('hex');
+      return key.verify(messageHash, signature);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Verify an authentication challenge response
+   * 
+   * @param publicKey - The user's public key
+   * @param challenge - The original challenge string
+   * @param signature - The signature of the auth message
+   * @param timestamp - The timestamp when the signature was created
+   * @param maxAgeMs - Maximum age of the signature in milliseconds
+   * @returns true if the challenge response is valid
+   */
+  static async verifyChallengeResponse(
+    publicKey: string,
+    challenge: string,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = CHALLENGE_TTL_MS
+  ): Promise<boolean> {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildAuthMessage(publicKey, challenge, timestamp);
+    
+    // Verify the signature
+    return this.verify(message, signature, publicKey);
+  }
+
+  /**
+   * Synchronous challenge response verification (Node.js only)
+   */
+  static verifyChallengeResponseSync(
+    publicKey: string,
+    challenge: string,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = CHALLENGE_TTL_MS
+  ): boolean {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildAuthMessage(publicKey, challenge, timestamp);
+    
+    // Verify the signature
+    return this.verifySync(message, signature, publicKey);
+  }
+
+  /**
+   * Verify a registration signature
+   * Signature format: oxy:register:{publicKey}:{timestamp}
+   */
+  static async verifyRegistrationSignature(
+    publicKey: string,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = MAX_SIGNATURE_AGE_MS
+  ): Promise<boolean> {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildRegistrationMessage(publicKey, timestamp);
+    
+    // Verify the signature
+    return this.verify(message, signature, publicKey);
+  }
+
+  /**
+   * Synchronous registration signature verification (Node.js only)
+   */
+  static verifyRegistrationSignatureSync(
+    publicKey: string,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = MAX_SIGNATURE_AGE_MS
+  ): boolean {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildRegistrationMessage(publicKey, timestamp);
+    
+    // Verify the signature
+    return this.verifySync(message, signature, publicKey);
+  }
+
+  /**
+   * Verify a signed request
+   * Used for authenticated API operations
+   */
+  static async verifyRequestSignature(
+    publicKey: string,
+    data: Record<string, unknown>,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = MAX_SIGNATURE_AGE_MS
+  ): Promise<boolean> {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildRequestMessage(publicKey, timestamp, data);
+    
+    // Verify the signature
+    return this.verify(message, signature, publicKey);
+  }
+
+  /**
+   * Synchronous request signature verification (Node.js only)
+   */
+  static verifyRequestSignatureSync(
+    publicKey: string,
+    data: Record<string, unknown>,
+    signature: string,
+    timestamp: number,
+    maxAgeMs: number = MAX_SIGNATURE_AGE_MS
+  ): boolean {
+    // Check timestamp freshness
+    if (!isTimestampFresh(timestamp, maxAgeMs)) {
+      return false;
+    }
+
+    // Build the canonical message
+    const message = buildRequestMessage(publicKey, timestamp, data);
+    
+    // Verify the signature
+    return this.verifySync(message, signature, publicKey);
+  }
+
+  /**
+   * Validate that a string is a valid public key
+   */
+  static isValidPublicKey(publicKey: string): boolean {
+    try {
+      ec.keyFromPublic(publicKey, 'hex');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+

package/src/shared/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @oxyhq/shared
+ * 
+ * Shared utilities, models, and crypto primitives for OxyHQ packages.
+ * 
+ * This package provides:
+ * - Canonical data models (User, Session, ChallengePayload, etc.)
+ * - Unified signature verification across platforms
+ * - Platform-agnostic crypto adapters
+ * - Shared utility functions
+ * - Canonical message builders for signing
+ */
+
+// Models
+export * from './models/index';
+
+// Crypto
+export * from './crypto/signature';
+export * from './crypto/messageBuilders';
+export * from './crypto/platform';
+export { getCryptoAdapter, PlatformDetector } from './crypto/platform';
+
+// Utils
+export * from './utils/index';
+
+// Transport
+export * from './transport/index';
+

package/src/shared/models/index.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared Data Models
+ * 
+ * Canonical TypeScript interfaces used across Accounts, Services SDK, and API packages.
+ * These models eliminate type drift and ensure consistency across the monorepo.
+ */
+
+/**
+ * User Model
+ * 
+ * IMPORTANT: 
+ * - id: MongoDB ObjectId (24 hex characters) - PRIMARY IDENTIFIER for all internal operations
+ * - publicKey: Cryptographic public key (130 hex characters) - LOOKUP KEY for authentication and identity operations
+ * 
+ * Never use publicKey as an ID. Always use id (ObjectId) for:
+ * - Database queries
+ * - Session userId
+ * - Token userId
+ * - Socket room names
+ * - API route parameters (unless explicitly doing publicKey lookup)
+ */
+export interface User {
+  id: string;           // MongoDB ObjectId - PRIMARY IDENTIFIER (always 24 hex chars)
+  publicKey: string;    // Cryptographic public key - LOOKUP KEY (130 hex chars for secp256k1)
+  username: string;
+  email?: string;
+  avatar?: string;      // Avatar file id (asset id)
+  privacySettings?: {
+    [key: string]: unknown;
+  };
+  name?: {
+    first?: string;
+    last?: string;
+    full?: string;      // virtual, not stored in DB, returned by API
+    [key: string]: unknown;
+  };
+  bio?: string;
+  karma?: number;
+  location?: string;
+  website?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  links?: Array<{
+    title?: string;
+    description?: string;
+    image?: string;
+    link: string;
+  }>;
+  _count?: {
+    followers?: number;
+    following?: number;
+  };
+  accountExpiresAfterInactivityDays?: number | null;
+  [key: string]: unknown;
+}
+
+/**
+ * Session Model
+ * Represents an authenticated session on a device
+ */
+export interface Session {
+  sessionId: string;
+  userId: string;       // MongoDB ObjectId - PRIMARY IDENTIFIER
+  deviceId: string;
+  deviceInfo?: {
+    deviceName?: string;
+    deviceType?: string;
+    platform?: string;
+    browser?: string;
+    os?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    location?: string;
+    fingerprint?: string;
+    lastActive?: string | Date;
+  };
+  isActive: boolean;
+  expiresAt: string | Date;
+  lastActive?: string | Date;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+}
+
+/**
+ * Challenge Payload
+ * Used in challenge-response authentication
+ */
+export interface ChallengePayload {
+  challenge: string;
+  publicKey: string;
+  expiresAt: string | Date;
+}
+
+/**
+ * Signed Message
+ * Represents a message with cryptographic signature
+ */
+export interface SignedMessage {
+  message: string;
+  signature: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+/**
+ * Auth Challenge Response
+ * Response to an authentication challenge
+ */
+export interface AuthChallengeResponse {
+  challenge: string;
+  publicKey: string;
+  signature: string;
+  timestamp: number;
+}
+
+/**
+ * Session Auth Response
+ * Response from session authorization (SSO flow)
+ */
+export interface SessionAuthResponse {
+  sessionToken: string;
+  status: 'pending' | 'authorized' | 'expired' | 'cancelled';
+  accessToken?: string;
+  refreshToken?: string;
+  user?: User;
+  expiresAt: string | Date;
+  createdAt?: string | Date;
+}
+
+/**
+ * Registration Request
+ * Used when registering a new identity
+ */
+export interface RegistrationRequest {
+  publicKey: string;
+  signature: string;
+  timestamp: number;
+  username?: string;
+  email?: string;
+}
+
+/**
+ * Login Response
+ * Response from successful authentication
+ */
+export interface LoginResponse {
+  accessToken?: string;
+  refreshToken?: string;
+  token?: string;       // For backwards compatibility
+  user: User;
+  message?: string;
+}
+
+/**
+ * Pagination Info
+ * Standard pagination metadata
+ */
+export interface PaginationInfo {
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+/**
+ * Search Profiles Response
+ * Response from profile search with pagination
+ */
+export interface SearchProfilesResponse {
+  data: User[];
+  pagination: PaginationInfo;
+}
+