@private.me/xbind 1.2.17 → 1.3.0

package/dist-standalone/cli/setup.js

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * @module cli/setup
+ * xBind setup command - creates deployment identity.
+ *
+ * Flow:
+ * 1. Check if identity exists (~/.xbind/identity.json)
+ * 2. Prompt for service name and email
+ * 3. Generate DID (did:key format, Ed25519)
+ * 4. Generate DeploymentID (DEP-YYYYMM-XXXXXXXXXX)
+ * 5. Create account on server (POST /auth/signup)
+ * 6. Send email verification code (6-digit)
+ * 7. Prompt user to enter code
+ * 8. Verify code on server
+ * 9. Store identity locally
+ * 10. Display success message
+ *
+ * @example
+ * ```bash
+ * npx xbind setup --name my-service
+ * # → Prompts for email
+ * # → Generates DID + DeploymentID
+ * # → Creates server account
+ * # → Sends verification email
+ * # → Prompts for 6-digit code
+ * # → Saves to ~/.xbind/identity.json
+ * ```
+ */
+import { parseArgs } from 'node:util';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { randomBytes } from 'node:crypto';
+import { ExitCode, Colors } from './types.js';
+/**
+ * Get identity storage path.
+ */
+function getIdentityPath() {
+    return path.join(os.homedir(), '.xbind', 'identity.json');
+}
+/**
+ * Ensure .xbind directory exists.
+ */
+async function ensureXBindDir() {
+    const xbindDir = path.join(os.homedir(), '.xbind');
+    try {
+        await fs.promises.mkdir(xbindDir, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Cannot create .xbind directory: ${err.message}`);
+    }
+}
+/**
+ * Check if identity exists.
+ */
+async function identityExists() {
+    try {
+        await fs.promises.access(getIdentityPath(), fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read existing identity.
+ */
+async function readIdentity() {
+    try {
+        const data = await fs.promises.readFile(getIdentityPath(), 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write identity to disk.
+ */
+async function writeIdentity(identity) {
+    await ensureXBindDir();
+    await fs.promises.writeFile(getIdentityPath(), JSON.stringify(identity, null, 2), { mode: 0o600 });
+}
+/**
+ * Spinner for progress indication.
+ */
+class Spinner {
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    currentFrame = 0;
+    intervalId;
+    message;
+    useColors;
+    constructor(message, useColors = true) {
+        this.message = message;
+        this.useColors = useColors && process.stdout.isTTY;
+    }
+    start() {
+        this.intervalId = setInterval(() => {
+            const frame = this.frames[this.currentFrame];
+            process.stdout.write(`\r${frame} ${this.message}`);
+            this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+        }, 80);
+    }
+    succeed(message) {
+        this.stop();
+        const check = this.useColors ? `${Colors.GREEN}✅${Colors.RESET}` : '✅';
+        process.stdout.write(`\r${check} ${message ?? this.message}\n`);
+    }
+    fail(message) {
+        this.stop();
+        const cross = this.useColors ? `${Colors.RED}❌${Colors.RESET}` : '❌';
+        process.stdout.write(`\r${cross} ${message ?? this.message}\n`);
+    }
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = undefined;
+        }
+    }
+}
+/**
+ * Prompt user for input.
+ */
+async function prompt(question, defaultValue) {
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question(defaultValue ? `${question} (${defaultValue}): ` : `${question}: `);
+    rl.close();
+    return answer.trim() || defaultValue || '';
+}
+/**
+ * Validate email format.
+ */
+function isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+/**
+ * Validate service name.
+ */
+function isValidServiceName(name) {
+    return /^[a-zA-Z][a-zA-Z0-9-]{2,63}$/.test(name);
+}
+/**
+ * Generate DID (did:key format with Ed25519).
+ * Uses xBind identity module's generateIdentity.
+ */
+async function generateDID() {
+    // Import identity module
+    const { generateIdentity } = await import('../identity.js');
+    const identityResult = await generateIdentity();
+    if (!identityResult.ok) {
+        throw new Error('Failed to generate identity');
+    }
+    const identity = identityResult.value;
+    // Export keys to raw bytes then convert to base64 for storage
+    const publicKeyRaw = new Uint8Array(await crypto.subtle.exportKey('raw', identity.publicKey));
+    const privateKeyJwk = await crypto.subtle.exportKey('jwk', identity.privateKey);
+    // For Ed25519, the private key in JWK format contains 'd' which is the 32-byte seed
+    if (!privateKeyJwk.d) {
+        throw new Error('Failed to export private key');
+    }
+    const publicKeyBase64 = Buffer.from(publicKeyRaw).toString('base64');
+    const privateKeyBase64 = privateKeyJwk.d; // Already base64url encoded
+    return {
+        did: identity.did,
+        publicKey: publicKeyBase64,
+        privateKey: privateKeyBase64,
+    };
+}
+/**
+ * Generate DeploymentID (DEP-YYYYMM-XXXXXXXXXX format).
+ */
+function generateDeploymentID() {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    // 10 hex digits for collision resistance (40 bits entropy)
+    const randomHex = randomBytes(5).toString('hex').toUpperCase();
+    return `DEP-${year}${month}-${randomHex}`;
+}
+/**
+ * Create account on server.
+ */
+async function createServerAccount(did, deploymentId, email, apiUrl) {
+    const url = `${apiUrl}/auth/signup`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ did, deploymentId, email, method: 'code' }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({
+                code: 'UNKNOWN',
+                message: `Server returned ${response.status}`,
+            }));
+            return { success: false, error };
+        }
+        const data = await response.json();
+        return { success: true, account: data.account };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: error instanceof Error ? error.message : 'Network request failed',
+                hint: 'Check that the server is running and accessible',
+            },
+        };
+    }
+}
+/**
+ * Send email verification code.
+ */
+async function sendVerificationCode(email, apiUrl) {
+    const url = `${apiUrl}/auth/send-verification-code`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: `HTTP ${response.status}` }));
+            return { success: false, error: error.message };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Network error',
+        };
+    }
+}
+/**
+ * Verify email code on server.
+ */
+async function verifyEmailCode(email, code, apiUrl) {
+    const url = `${apiUrl}/auth/verify-email-code`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email, code }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: `HTTP ${response.status}` }));
+            return { success: false, error: error.message };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Network error',
+        };
+    }
+}
+/**
+ * Output success message (human-readable).
+ */
+function outputSuccess(identity, useColors) {
+    const green = useColors ? Colors.GREEN : '';
+    const gray = useColors ? Colors.GRAY : '';
+    const blue = useColors ? Colors.BLUE : '';
+    const reset = useColors ? Colors.RESET : '';
+    console.log(`${green}✅ Identity created successfully${reset}\n`);
+    console.log(`Service Name: ${identity.name}`);
+    console.log(`DID:          ${green}${identity.did}${reset}`);
+    console.log(`DeploymentID: ${identity.deploymentId}`);
+    console.log(`Email:        ${identity.email} ${identity.emailVerified ? green + '(verified)' + reset : gray + '(unverified)' + reset}`);
+    console.log(`Storage:      ${gray}${getIdentityPath()}${reset}\n`);
+    console.log(`${blue}ℹ️  Next steps:${reset}`);
+    console.log(`  1. Connect to a service:    xbind connect <service-name>`);
+    console.log(`  2. Generate an invite:      xbind invite <service-name>`);
+    console.log(`  3. Check connection status: xbind status`);
+}
+/**
+ * Output success message (JSON).
+ */
+function outputSuccessJSON(identity) {
+    console.log(JSON.stringify({
+        status: 'initialized',
+        did: identity.did,
+        deploymentId: identity.deploymentId,
+        name: identity.name,
+        email: identity.email,
+        emailVerified: identity.emailVerified,
+        storagePath: getIdentityPath(),
+        createdAt: identity.createdAt,
+    }));
+}
+/**
+ * Output error message.
+ */
+function outputError(message, details, hint, useColors = true) {
+    const red = useColors ? Colors.RED : '';
+    const gray = useColors ? Colors.GRAY : '';
+    const blue = useColors ? Colors.BLUE : '';
+    const reset = useColors ? Colors.RESET : '';
+    console.error(`${red}❌ Error: ${message}${reset}`);
+    if (details) {
+        console.error(`\n${details}`);
+    }
+    if (hint) {
+        console.error(`\n${blue}ℹ️  ${hint}${reset}`);
+    }
+}
+/**
+ * Main setup command.
+ */
+export async function setupCommand(options = {}) {
+    const useColors = !options['no-color'] && process.stdout.isTTY;
+    const apiUrl = options['api-url'] || process.env.XBIND_API_URL || 'http://localhost:3001';
+    // Step 1: Check if identity exists
+    if (!options.force && (await identityExists())) {
+        const existing = await readIdentity();
+        outputError('Identity already exists', `An xBind identity is already configured for this device.\n\nStorage: ${getIdentityPath()}\nDID:     ${existing?.did || 'unknown'}`, 'To create a new identity, use:\n    xbind setup --force', useColors);
+        process.exit(ExitCode.USER_ERROR);
+    }
+    // Step 2: Prompt for service name
+    let serviceName = options.name;
+    if (!serviceName) {
+        const defaultName = `xbind-${Date.now()}`;
+        serviceName = await prompt('Service name', defaultName);
+    }
+    if (!isValidServiceName(serviceName)) {
+        outputError('Invalid service name', `Service names must:\n  • Start with a letter\n  • Contain only letters, numbers, hyphens\n  • Be 3-64 characters long\n\nExample: billing-service, api-v2, payments-prod`, undefined, useColors);
+        process.exit(ExitCode.USER_ERROR);
+    }
+    // Step 3: Prompt for email
+    let email = options.email;
+    if (!email) {
+        email = await prompt('Email address');
+    }
+    if (!isValidEmail(email)) {
+        outputError('Invalid email format', 'Email must be a valid email address.\n\nExample: user@example.com', undefined, useColors);
+        process.exit(ExitCode.USER_ERROR);
+    }
+    // Step 4: Generate DID
+    const spinner1 = new Spinner('Generating DID...', useColors);
+    if (!options.json)
+        spinner1.start();
+    let didInfo;
+    try {
+        didInfo = await generateDID();
+        if (!options.json)
+            spinner1.succeed('DID generated');
+    }
+    catch (error) {
+        if (!options.json)
+            spinner1.fail('Failed to generate DID');
+        outputError('DID generation failed', error instanceof Error ? error.message : 'Unknown error', 'Ensure crypto dependencies are installed', useColors);
+        process.exit(ExitCode.SYSTEM_ERROR);
+    }
+    // Step 5: Generate DeploymentID
+    const deploymentId = generateDeploymentID();
+    // Step 6: Create server account
+    const spinner2 = new Spinner('Creating account on server...', useColors);
+    if (!options.json)
+        spinner2.start();
+    const accountResult = await createServerAccount(didInfo.did, deploymentId, email, apiUrl);
+    if (!accountResult.success) {
+        if (!options.json)
+            spinner2.fail('Failed to create account');
+        outputError(accountResult.error?.code || 'Account creation failed', accountResult.error?.message, accountResult.error?.hint || `Check server at ${apiUrl}`, useColors);
+        process.exit(ExitCode.SYSTEM_ERROR);
+    }
+    if (!options.json)
+        spinner2.succeed('Account created on server');
+    // Step 7: Send verification email
+    const spinner3 = new Spinner('Sending verification email...', useColors);
+    if (!options.json)
+        spinner3.start();
+    const sendResult = await sendVerificationCode(email, apiUrl);
+    if (!sendResult.success) {
+        if (!options.json)
+            spinner3.fail('Failed to send verification email');
+        outputError('Email verification failed', sendResult.error, 'You can verify later using: xbind verify-email', useColors);
+        // Continue anyway - email verification not required for basic setup
+    }
+    else {
+        if (!options.json)
+            spinner3.succeed('Verification email sent');
+        // Step 8: Prompt for verification code
+        if (!options.json) {
+            const cyan = useColors ? Colors.CYAN : '';
+            const reset = useColors ? Colors.RESET : '';
+            console.log(`\n${cyan}→ Check your email for a 6-digit verification code${reset}`);
+        }
+        const code = await prompt('Enter verification code (or press Enter to skip)');
+        if (code) {
+            const spinner4 = new Spinner('Verifying code...', useColors);
+            if (!options.json)
+                spinner4.start();
+            const verifyResult = await verifyEmailCode(email, code, apiUrl);
+            if (!verifyResult.success) {
+                if (!options.json)
+                    spinner4.fail('Verification failed');
+                outputError('Invalid verification code', verifyResult.error, 'You can verify later using: xbind verify-email', useColors);
+                // Continue anyway - save identity with emailVerified: false
+            }
+            else {
+                if (!options.json)
+                    spinner4.succeed('Email verified');
+            }
+        }
+    }
+    // Step 9: Save identity locally
+    const identity = {
+        did: didInfo.did,
+        deploymentId,
+        name: serviceName,
+        email,
+        emailVerified: accountResult.account?.emailVerified || false,
+        publicKey: didInfo.publicKey,
+        privateKey: didInfo.privateKey,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    try {
+        await writeIdentity(identity);
+    }
+    catch (error) {
+        outputError('Failed to save identity', error instanceof Error ? error.message : 'Unknown error', `Check permissions on ${getIdentityPath()}`, useColors);
+        process.exit(ExitCode.SYSTEM_ERROR);
+    }
+    // Step 10: Output success
+    if (options.json) {
+        outputSuccessJSON(identity);
+    }
+    else {
+        console.log(''); // blank line
+        outputSuccess(identity, useColors);
+    }
+}
+/**
+ * CLI entry point.
+ */
+export async function main(argv = process.argv.slice(2)) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            name: { type: 'string', short: 'n' },
+            email: { type: 'string', short: 'e' },
+            pair: { type: 'boolean', short: 'p' },
+            force: { type: 'boolean', short: 'f' },
+            'api-url': { type: 'string' },
+            json: { type: 'boolean' },
+            'no-color': { type: 'boolean' },
+            debug: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        console.log(`
+xBind Setup - Create Deployment Identity
+
+Usage:
+  xbind setup [options]
+
+Options:
+  -n, --name <string>      Service name (default: xbind-<timestamp>)
+  -e, --email <email>      Email address for account
+  -p, --pair               Display QR code for mobile pairing
+  -f, --force              Overwrite existing identity
+  --api-url <url>          Server API URL (default: http://localhost:3001)
+  --json                   Output JSON only (no human-readable text)
+  --no-color               Disable colored output
+  --debug                  Show detailed error information
+  -h, --help               Show this help message
+
+Examples:
+  xbind setup --name billing-service
+  xbind setup --name my-app --email user@example.com
+  xbind setup --force
+    `.trim());
+        return;
+    }
+    try {
+        await setupCommand({
+            name: values.name,
+            email: values.email,
+            pair: values.pair,
+            force: values.force,
+            'api-url': values['api-url'],
+            json: values.json,
+            'no-color': values['no-color'],
+            debug: values.debug,
+        });
+    }
+    catch (error) {
+        const useColors = !values['no-color'] && process.stderr.isTTY;
+        const red = useColors ? Colors.RED : '';
+        const reset = useColors ? Colors.RESET : '';
+        console.error(`${red}❌ Fatal error: ${error instanceof Error ? error.message : String(error)}${reset}`);
+        if (values.debug && error instanceof Error && error.stack) {
+            console.error(error.stack);
+        }
+        process.exit(ExitCode.SYSTEM_ERROR);
+    }
+}
+// Auto-run if executed directly
+const isDirectRun = process.argv[1]?.endsWith('setup.ts') || process.argv[1]?.endsWith('setup.js');
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error('Fatal:', error instanceof Error ? error.message : String(error));
+        process.exitCode = ExitCode.SYSTEM_ERROR;
+    });
+}

package/dist-standalone/cli/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @module cli/types
+ * Shared types for xBind CLI commands.
+ */
+/**
+ * Common CLI options across all commands.
+ */
+export interface GlobalOptions {
+    /** Output JSON only (no human-readable text) */
+    json?: boolean;
+    /** Disable colored output */
+    'no-color'?: boolean;
+    /** Show detailed error information */
+    debug?: boolean;
+}
+/**
+ * Local identity stored in ~/.xbind/identity.json
+ */
+export interface LocalIdentity {
+    /** DID (did:key format) */
+    did: string;
+    /** DeploymentID (DEP-YYYYMM-XXXXXXXXXX format) */
+    deploymentId: string;
+    /** Service/device name */
+    name: string;
+    /** Email address (verified or unverified) */
+    email: string;
+    /** Email verification status */
+    emailVerified: boolean;
+    /** Private key (Ed25519, base64-encoded) */
+    privateKey: string;
+    /** Public key (Ed25519, base64-encoded) */
+    publicKey: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last updated timestamp */
+    updatedAt: string;
+}
+/**
+ * Server account response from /auth/signup
+ */
+export interface ServerAccountResponse {
+    success: boolean;
+    account?: {
+        did: string;
+        deploymentId: string;
+        email: string;
+        emailVerified: boolean;
+        tier: 'free' | 'pro' | 'vip';
+    };
+    error?: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+}
+/**
+ * Exit codes for CLI commands.
+ */
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly USER_ERROR: 1;
+    readonly SYSTEM_ERROR: 2;
+    readonly AUTH_ERROR: 3;
+    readonly BILLING_ERROR: 4;
+    readonly USER_CANCELED: 130;
+};
+/**
+ * ANSI color codes (only used if TTY detected).
+ */
+export declare const Colors: {
+    readonly RED: "\u001B[31m";
+    readonly GREEN: "\u001B[32m";
+    readonly YELLOW: "\u001B[33m";
+    readonly BLUE: "\u001B[34m";
+    readonly CYAN: "\u001B[36m";
+    readonly GRAY: "\u001B[90m";
+    readonly RESET: "\u001B[0m";
+};

package/dist-standalone/cli/types.js

@@ -0,0 +1,27 @@
+/**
+ * @module cli/types
+ * Shared types for xBind CLI commands.
+ */
+/**
+ * Exit codes for CLI commands.
+ */
+export const ExitCode = {
+    SUCCESS: 0,
+    USER_ERROR: 1,
+    SYSTEM_ERROR: 2,
+    AUTH_ERROR: 3,
+    BILLING_ERROR: 4,
+    USER_CANCELED: 130,
+};
+/**
+ * ANSI color codes (only used if TTY detected).
+ */
+export const Colors = {
+    RED: '\x1b[31m',
+    GREEN: '\x1b[32m',
+    YELLOW: '\x1b[33m',
+    BLUE: '\x1b[34m',
+    CYAN: '\x1b[36m',
+    GRAY: '\x1b[90m',
+    RESET: '\x1b[0m',
+};

package/dist-standalone/cli/xbind.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @module cli/xbind
+ * Main xBind CLI router - dispatches to subcommands.
+ *
+ * Supports 12 commands (v2.0.0 spec):
+ * 1. setup     - Create deployment identity
+ * 2. connect   - Connect to a service (TODO)
+ * 3. invite    - Generate invite link (TODO)
+ * 4. list      - List connections (TODO)
+ * 5. status    - Display connection status (TODO)
+ * 6. migrate   - Scan for API keys (TODO)
+ * 7. trial     - Activate free trial (TODO)
+ * 8. deploy    - Deploy algorithms (TODO)
+ * 9. server    - Start relay server (TODO)
+ * 10. revoke   - Revoke connection (TODO)
+ * 11. backup   - Export/import identity (TODO)
+ * 12. debug    - Diagnostics (TODO)
+ */
+export {};