@trust-proto/auth-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Liberion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @trust-proto/auth-node
+
+Backend SDK for Liberion decentralized authentication system. This package provides a WebSocket server that handles browser-wallet authentication flow.
+
+## Installation
+
+```bash
+npm install @trust-proto/auth-node
+```
+
+## Quick Start
+
+```typescript
+import { LiberionAuth, createWinstonAdapter } from '@trust-proto/auth-node';
+
+const auth = new LiberionAuth({
+  projectId: 'your-project-uuid',
+  secretCode: 'your-secret-code',
+  port: 31313, // optional, default: 31313
+
+  // Check if user exists in your database
+  onHello: async (address) => {
+    return await userExists(address);
+  },
+
+  // Generate JWT token after successful authentication
+  onSuccess: async ({ address, fields }) => {
+    const token = generateJWT(address);
+    return { token };
+  },
+
+  // Handle declined authorization (optional)
+  onDecline: async ({ address, reason, message }) => {
+    console.log(`Auth declined: ${reason}`);
+  },
+});
+```
+
+## Configuration
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `projectId` | `string` | Yes | - | Project UUID from Liberion dashboard |
+| `secretCode` | `string` | Yes | - | Secret code for encryption |
+| `port` | `number` | No | `31313` | WebSocket server port |
+| `ssl` | `{ key: string; cert: string }` | No | - | SSL credentials for HTTPS |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `logger` | `ILogger` | No | `NoOpLogger` | Custom logger instance |
+| `onHello` | `(address: string) => Promise<boolean>` | No | - | Called when wallet activates |
+| `onSuccess` | `(payload: AuthPayload) => Promise<AuthResult>` | No | - | Called on successful auth |
+| `onDecline` | `(info: DeclineInfo) => Promise<void>` | No | - | Called when auth is declined |
+
+## Logger Integration
+
+### Using Winston
+
+```typescript
+import { createWinstonAdapter } from '@trust-proto/auth-node';
+import winston from 'winston';
+
+const logger = winston.createLogger({ /* your config */ });
+
+const auth = new LiberionAuth({
+  projectId: 'your-project-uuid',
+  secretCode: 'your-secret-code',
+  logger: createWinstonAdapter(logger),
+});
+```
+
+### Using Console Logger
+
+```typescript
+import { ConsoleLogger } from '@trust-proto/auth-node';
+
+const auth = new LiberionAuth({
+  projectId: 'your-project-uuid',
+  secretCode: 'your-secret-code',
+  logger: new ConsoleLogger('[MyApp]'),
+});
+```
+
+### Custom Logger
+
+Implement the `ILogger` interface:
+
+```typescript
+const customLogger: ILogger = {
+  info: (message, meta) => { /* ... */ },
+  warn: (message, meta) => { /* ... */ },
+  error: (message, meta) => { /* ... */ },
+};
+```
+
+## Authentication Flow
+
+1. **Browser** connects to WebSocket server and sends `auth_init`
+2. **Server** creates authorization task via Trust Gate
+3. **Server** returns QR code link to browser
+4. **User** scans QR code with Liberion Wallet
+5. **Wallet** sends activation request with encrypted session data
+6. **Server** calls `onHello` callback, sends ACTIVATED to browser
+7. **Wallet** sends signed auth data with KYC fields
+8. **Server** verifies ML-DSA-87 signature, calls `onSuccess`
+9. **Server** sends JWT token to browser, closes connections
+
+## Security Features
+
+- **Post-Quantum Cryptography**: ML-KEM-1024 + ML-DSA-87 (FIPS 203/204)
+- **AES-256-CBC**: Session encryption with project secret
+- **Signature Verification**: All auth data is cryptographically signed
+- **Session Timeout**: 10-minute authorization window
+- **WebSocket Ping/Pong**: Keep-alive with 30-second interval
+
+## Types
+
+```typescript
+interface AuthPayload {
+  address: string;
+  fields: Record<string, unknown>;
+}
+
+interface AuthResult {
+  token?: string;
+  error?: string;
+}
+
+interface DeclineInfo {
+  address: string | null;
+  reason: 'user_declined' | 'timeout' | 'error' | 'unknown';
+  message: string;
+  declinedBy: 'wallet' | 'browser';
+  sessionId: string;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+/**
+ * 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 credentials for HTTPS server
+ */
+interface SSLCredentials {
+    key: string;
+    cert: string;
+}
+/**
+ * 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 };