@trust-proto/auth-node 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -0,0 +1,424 @@
+import { SecureContextOptions } from 'tls';
+
+/**
+ * Blockchain configuration constants
+ * Supports production and development environments
+ */
+/** Environment type */
+type Environment = 'production' | 'development';
+/** Network configuration interface */
+interface NetworkConfig {
+    RPC_ENDPOINT: string;
+    USER_CONTRACT_ADDRESS: string;
+    IPFS_GATEWAY: string;
+    TRUST_GATE_URL: string;
+}
+/**
+ * Get network configuration for specified environment
+ * @param env - Environment ('production' | 'development'), default: 'production'
+ * @returns Network configuration object
+ */
+declare function getNetworkConfig(env?: Environment): NetworkConfig;
+/** User contract ABI (minimal for tokenURI) */
+declare const USER_CONTRACT_ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "tokenId";
+        readonly type: "address";
+    }];
+    readonly name: "tokenURI";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+
+/**
+ * Liberion Auth Backend SDK Types
+ */
+
+/**
+ * Logger interface for dependency injection
+ */
+interface ILogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * User SNFT token structure from IPFS
+ */
+interface UserToken {
+    /** ML-DSA-87 public key (base64 encoded, 2592 bytes decoded) */
+    publicKeySign: string;
+    /** ML-KEM-1024 public key (base64 encoded, 1568 bytes decoded) */
+    publicKeyEncrypt: string;
+    /** Optional KYC assets */
+    assets?: Record<string, unknown>;
+    /** Additional token properties */
+    [key: string]: unknown;
+}
+/**
+ * SSL/TLS credentials for HTTPS server
+ * Accepts all options from Node.js tls.SecureContextOptions
+ * @see https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
+ */
+type SSLCredentials = SecureContextOptions;
+/**
+ * Decline reason categories
+ */
+type DeclineReason = 'user_declined' | 'timeout' | 'error' | 'unknown';
+/**
+ * Information about declined authorization
+ */
+interface DeclineInfo {
+    /** User wallet address (null if declined before activation) */
+    address: string | null;
+    /** Standardized decline reason */
+    reason: DeclineReason;
+    /** Detailed message */
+    message: string;
+    /** Who initiated the decline */
+    declinedBy: 'wallet' | 'browser';
+    /** Session identifier */
+    sessionId: string;
+}
+/**
+ * Payload received on successful authorization
+ */
+interface AuthPayload {
+    /** User wallet address */
+    address: string;
+    /** KYC fields provided by user */
+    fields: Record<string, unknown>;
+}
+/**
+ * Result returned from onSuccess callback
+ */
+interface AuthResult {
+    /** JWT token for authenticated user */
+    token?: string;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Main configuration for LiberionAuth
+ */
+interface LiberionAuthConfig {
+    /** Project UUID from Liberion dashboard */
+    projectId: string;
+    /** Secret code for AES-256-CBC encryption */
+    secretCode: string;
+    /** WebSocket server port (default: 31313) */
+    port?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** SSL credentials for HTTPS (default: undefined, use HTTP) */
+    ssl?: SSLCredentials;
+    /** Environment: 'production' or 'development' (default: 'production') */
+    environment?: Environment;
+    /** Logger instance (default: NoOpLogger) */
+    logger?: ILogger;
+    /**
+     * Called when wallet activates (scans QR)
+     * @param address - User wallet address
+     * @returns true if user is registered, false otherwise
+     */
+    onHello?: (address: string) => Promise<boolean>;
+    /**
+     * Called on successful authorization
+     * @param payload - Contains address and KYC fields
+     * @returns Object with token or error
+     */
+    onSuccess?: (payload: AuthPayload) => Promise<AuthResult>;
+    /**
+     * Called when authorization is declined
+     * @param info - Decline details including reason and who declined
+     */
+    onDecline?: (info: DeclineInfo) => Promise<void>;
+}
+/**
+ * Session data stored for each connected client
+ */
+interface Session {
+    /** WebSocket client reference */
+    client: unknown;
+    /** Session UUID (for browser-wallet linking) */
+    sessionId: string | null;
+    /** User wallet address (set after activation) */
+    address: string | null;
+    /** Client session ID (for wallet auth) */
+    clientSessionId: string | null;
+    /** True if this is a browser session */
+    isBrowserSession: boolean;
+    /** Stored auth result for reconnect scenario */
+    authResult?: {
+        token: string;
+    };
+    /** Stored decline result for reconnect scenario */
+    declineResult?: {
+        message: string;
+    };
+    /** Authorization timeout handle */
+    timeout?: NodeJS.Timeout;
+}
+/**
+ * Crypto instance for signature verification
+ */
+interface CryptoInstance {
+    /** ML-DSA-87 public key */
+    dsaPublicKey: Uint8Array;
+    /** ML-KEM-1024 public key (optional) */
+    kemPublicKey: Uint8Array | null;
+    /** Algorithm identifier */
+    algorithm: string;
+    /** Original user token */
+    userToken: UserToken;
+    /**
+     * Verify ML-DSA-87 signature
+     * @param msg - Message that was signed
+     * @param signature - ML-DSA-87 signature
+     * @returns true if signature is valid
+     */
+    verifySignature: (msg: Buffer | Uint8Array, sig: Buffer | Uint8Array) => boolean;
+}
+
+/**
+ * LiberionAuth - Main SDK class for Liberion authentication
+ * Creates a WebSocket server that handles browser and wallet connections
+ */
+
+declare class LiberionAuth {
+    private logger;
+    private projectId;
+    private secretCode;
+    private networkConfig;
+    private sessions;
+    private interval;
+    private onHello?;
+    private onSuccess?;
+    private onDecline?;
+    static readonly COMMAND_AUTH = "auth";
+    static readonly COMMAND_READY = "ready";
+    constructor(config: LiberionAuthConfig);
+    private encode;
+    private decode;
+    private request;
+    private send;
+    private readMessage;
+    private newClient;
+    private handleClose;
+    private responseInit;
+    private responseActivate;
+    private responseAuth;
+    private responseDeclined;
+    private responseReconnect;
+    private responseFailed;
+    private errorResponse;
+    private finalResponse;
+    private finalizeSession;
+    private closeClient;
+    private findSession;
+}
+
+/**
+ * Logger adapters for dependency injection
+ */
+
+/**
+ * No-operation logger - default when no logger provided
+ * Silently ignores all log calls
+ */
+declare class NoOpLogger implements ILogger {
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+/**
+ * Console logger for development/debugging
+ * Outputs to stdout/stderr with timestamps
+ */
+declare class ConsoleLogger implements ILogger {
+    private readonly prefix;
+    constructor(prefix?: string);
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Create a logger adapter from Winston logger instance
+ * @param winston - Winston logger instance
+ * @returns ILogger compatible adapter
+ *
+ * @example
+ * ```typescript
+ * import { createWinstonAdapter } from '@trust-proto/auth-node';
+ * import { logger } from './my-winston-logger';
+ *
+ * const auth = new LiberionAuth({
+ *   logger: createWinstonAdapter(logger),
+ *   // ...
+ * });
+ * ```
+ */
+declare function createWinstonAdapter(winston: {
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+}): ILogger;
+/**
+ * Shorten blockchain address for logging (privacy protection)
+ * @param address - Full blockchain address
+ * @returns Shortened address like "0x1234...abcd"
+ */
+declare function shortenAddress(address: string | null | undefined): string;
+
+/**
+ * AES-256-CBC encryption utilities
+ */
+/**
+ * Encrypt buffer using AES-256-CBC
+ * @param buffer - Data to encrypt
+ * @param key - Encryption key (will be hashed to 32 bytes)
+ * @returns Encrypted buffer with IV prepended (16 bytes IV + encrypted data)
+ */
+declare function encryptBuffer(buffer: Buffer, key: string): Buffer;
+/**
+ * Decrypt buffer using AES-256-CBC
+ * @param data - Encrypted data (16 bytes IV + encrypted data)
+ * @param key - Decryption key (will be hashed to 32 bytes)
+ * @returns Decrypted buffer
+ */
+declare function decryptBuffer(data: Buffer, key: string): Buffer;
+
+/**
+ * Post-Quantum Cryptography utility class
+ * Implements hybrid encryption: ML-KEM-1024 + XChaCha20-Poly1305 + ML-DSA-87
+ */
+
+/**
+ * Post-Quantum Cryptography utility class
+ * Used by Trust Gate to:
+ * 1. Generate temporary session keys
+ * 2. Encrypt data for Wallet using user's public keys
+ * 3. Sign KEM ciphertext for authenticity
+ *
+ * Format matches client (cipher.js):
+ * version (1) + header (4) + sigLen (4) + signature + cipherText + nonce (24) + ct
+ */
+declare class PQCrypto {
+    private logger;
+    private _kemPrivateKey;
+    private kemPublicKey;
+    private dsaPrivateKey;
+    private dsaPublicKey;
+    private peerKEMPublicKey;
+    private peerDSAPublicKey;
+    constructor(logger?: ILogger);
+    /**
+     * Generate Trust Gate session keys from cryptographic seed
+     * @param seed - Random seed (at least 96 bytes: 64 for ML-KEM + 32 for ML-DSA)
+     */
+    generateKeysFromSeed(seed: Uint8Array): Promise<void>;
+    /**
+     * Import peer's (user) public keys for encryption and verification
+     * @param kemPublicKey - ML-KEM-1024 public key (1568 bytes)
+     * @param dsaPublicKey - ML-DSA-87 public key (2592 bytes)
+     */
+    importPeerPublicKeys(kemPublicKey: Uint8Array | Buffer, dsaPublicKey: Uint8Array | Buffer): void;
+    /**
+     * Hybrid encryption: ML-KEM + XChaCha20-Poly1305 + ML-DSA signature
+     * Matches client format: version + header + sigLen + signature + cipherText + nonce + ct
+     * @param message - Data to encrypt
+     * @returns Encrypted package in client-compatible format
+     */
+    encrypt(message: ArrayBuffer | Uint8Array | Buffer): Promise<Buffer>;
+    /**
+     * Check if keys have been generated
+     */
+    hasKeys(): boolean;
+    /**
+     * Export Trust Gate public keys (for sending to client)
+     * @returns Object with publicKeyEncrypt and publicKeySign as Buffers
+     */
+    exportKeys(): {
+        publicKeyEncrypt: Buffer;
+        publicKeySign: Buffer;
+    };
+}
+
+/**
+ * ML-DSA-87 signature verification utilities
+ */
+
+/**
+ * Initialize user crypto instance from SNFT token
+ * Parses ML-DSA-87 and ML-KEM-1024 public keys from base64-encoded token
+ *
+ * @param userToken - SNFT token with publicKeySign and publicKeyEncrypt (base64)
+ * @param logger - Optional logger instance
+ * @returns Crypto instance for signature verification
+ */
+declare function initUserCrypto(userToken: UserToken, logger?: ILogger): CryptoInstance;
+/**
+ * Verify ML-DSA-87 signature of data
+ *
+ * @param crypto - Crypto instance from initUserCrypto
+ * @param data - Data that was signed
+ * @param signature - ML-DSA-87 signature (~4595 bytes)
+ * @param logger - Optional logger instance
+ * @returns true if signature is valid
+ * @throws Error if verification fails
+ */
+declare function checkSignature(crypto: CryptoInstance, data: Buffer | Uint8Array | ArrayBuffer | string, signature: Buffer | Uint8Array | ArrayBuffer | string, logger?: ILogger): boolean;
+
+/**
+ * Token Provider - Fetches user SNFT tokens from blockchain and IPFS
+ */
+
+/**
+ * Extract IPFS hash from tokenURI
+ * Handles multiple formats:
+ * - ipfs://QmHash...
+ * - https://gateway.pinata.cloud/ipfs/QmHash...
+ * - https://secure.liberion.com/QmHash...
+ * - QmHash... (raw hash)
+ */
+declare function extractIpfsHash(tokenURI: string): string;
+/**
+ * Get SNFT token from IPFS by user address
+ *
+ * @param address - User blockchain address
+ * @param logger - Optional logger instance
+ * @param networkConfig - Optional network configuration (defaults to production)
+ * @returns SNFT token object from IPFS
+ */
+declare function getTokenFromIPFS(address: string, logger?: ILogger, networkConfig?: NetworkConfig): Promise<UserToken>;
+/**
+ * Clear the token cache (for testing or manual invalidation)
+ */
+declare function clearTokenCache(): void;
+
+declare const COMMAND_READY = "ready";
+declare const COMMAND_AUTH = "auth";
+declare const COMMAND_AUTH_RESULT = "auth_result";
+declare const COMMAND_ACTIVATED = "activated";
+declare const COMMAND_AUTH_DECLINED = "declined";
+declare const COMMAND_AUTH_TIMEOUT = "timeout";
+declare const COMMAND_ERROR = "error";
+declare const DEFAULT_PORT = 31313;
+declare const STATUS: {
+    readonly OK: "ok";
+    readonly FAILED: "error";
+};
+declare const DECLINE_REASON: {
+    readonly USER: "user_declined";
+    readonly TIMEOUT: "timeout";
+    readonly ERROR: "error";
+    readonly UNKNOWN: "unknown";
+};
+
+export { type AuthPayload, type AuthResult, COMMAND_ACTIVATED, COMMAND_AUTH, COMMAND_AUTH_DECLINED, COMMAND_AUTH_RESULT, COMMAND_AUTH_TIMEOUT, COMMAND_ERROR, COMMAND_READY, ConsoleLogger, type CryptoInstance, DECLINE_REASON, DEFAULT_PORT, type DeclineInfo, type DeclineReason, type Environment, type ILogger, LiberionAuth, type LiberionAuthConfig, type NetworkConfig, NoOpLogger, PQCrypto, type SSLCredentials, STATUS, type Session, USER_CONTRACT_ABI, type UserToken, checkSignature, clearTokenCache, createWinstonAdapter, decryptBuffer, encryptBuffer, extractIpfsHash, getNetworkConfig, getTokenFromIPFS, initUserCrypto, shortenAddress };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { SecureContextOptions } from 'tls';
+
 /**
  * Blockchain configuration constants
  * Supports production and development environments
@@ -60,12 +62,11 @@ interface UserToken {
     [key: string]: unknown;
 }
 /**
- * SSL credentials for HTTPS server
+ * SSL/TLS credentials for HTTPS server
+ * Accepts all options from Node.js tls.SecureContextOptions
+ * @see https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
  */
-interface SSLCredentials {
-    key: string;
-    cert: string;
-}
+type SSLCredentials = SecureContextOptions;
 /**
  * Decline reason categories
  */

package/dist/index.js

@@ -1152,6 +1152,7 @@ var PQCrypto = class {
         sharedSecretSize: sharedSecret.length
         // 32 bytes
       });
+      const sharedSecretBuffer = Uint8Array.from(sharedSecret);
       const secretKeyRaw = await subtle.deriveBits(
         {
           name: "HKDF",
@@ -1159,12 +1160,13 @@ var PQCrypto = class {
           salt: PROTOCOL_AAD,
           info: PROTOCOL_AAD
         },
-        await subtle.importKey("raw", sharedSecret, { name: "HKDF" }, false, [
+        await subtle.importKey("raw", sharedSecretBuffer, { name: "HKDF" }, false, [
           "deriveBits"
         ]),
         256
       );
       sharedSecret.fill(0);
+      sharedSecretBuffer.fill(0);
       const versionBuf = new Uint8Array([1]);
       const header = new Uint8Array(4);
       new DataView(header.buffer).setUint32(0, kemCiphertext.length, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trust-proto/auth-node",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Liberion Auth Backend SDK with post-quantum cryptography",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -41,7 +42,7 @@
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.2",
-    "@noble/post-quantum": "^0.5.2",
+    "@noble/post-quantum": "^0.5.4",
     "ethers": "^6.16.0",
     "libsodium-wrappers": "^0.7.15",
     "uuid": "^13.0.0",
@@ -49,19 +50,19 @@
   },
   "devDependencies": {
     "@types/libsodium-wrappers": "^0.7.14",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.3",
     "@types/ws": "^8.5.0",
-    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/coverage-v8": "^4.0.16",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.16"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "test": "vitest --run",
     "test:watch": "vitest",
     "test:coverage": "vitest --run --coverage",