@clawchatsai/connector 0.0.14 → 0.0.16

package/dist/auth-handler.d.ts

@@ -0,0 +1,58 @@
+/**
+ * auth-handler.ts — DataChannel authentication state machine
+ *
+ * Manages the auth flow for each DataChannel connection:
+ * 1. Send auth-required with nonce
+ * 2. Wait for auth-session (cached JWT) or auth-full (Google + TOTP)
+ * 3. Verify credentials
+ * 4. Issue session token on success
+ * 5. Block all non-auth messages until authenticated
+ *
+ * Spec: datachannel-auth-totp.md §4
+ */
+export interface AuthConfig {
+    userId: string;
+    totp: {
+        secret: string;
+        algorithm: string;
+        digits: number;
+        period: number;
+        enabledAt: string;
+    };
+    google: {
+        clientId: string;
+        authorizedSub: string;
+        authorizedEmail: string;
+    };
+    sessionSecret: string;
+    backupCodeHashes?: string[];
+    /** When true, skip Google ID token verification (accept 'dev-mode-no-google'). */
+    devMode?: boolean;
+}
+export interface DataChannelSend {
+    send: (data: string) => void;
+}
+/**
+ * Initialize auth for a new DataChannel connection.
+ * Sends auth-required and starts the timeout.
+ *
+ * @returns true if auth was initiated, false if connection is blocked
+ */
+export declare function initAuth(dc: DataChannelSend, connectionId: string): boolean;
+/**
+ * Handle an incoming message on an auth-gated DataChannel.
+ *
+ * @returns 'authenticated' if the message was an auth message and auth succeeded,
+ *          'pending' if auth is still in progress,
+ *          'pass' if the connection is already authenticated (message should be processed normally),
+ *          'blocked' if the message was dropped (pre-auth non-auth message)
+ */
+export declare function handleAuthMessage(dc: DataChannelSend, connectionId: string, msg: Record<string, unknown>, config: AuthConfig): Promise<'authenticated' | 'pending' | 'pass' | 'blocked'>;
+/**
+ * Clean up auth state for a disconnected DataChannel.
+ */
+export declare function cleanupAuth(connectionId: string): void;
+/**
+ * Check if a connection is authenticated (no longer in auth sessions).
+ */
+export declare function isAuthenticated(connectionId: string): boolean;

package/dist/auth-handler.js

@@ -0,0 +1,252 @@
+/**
+ * auth-handler.ts — DataChannel authentication state machine
+ *
+ * Manages the auth flow for each DataChannel connection:
+ * 1. Send auth-required with nonce
+ * 2. Wait for auth-session (cached JWT) or auth-full (Google + TOTP)
+ * 3. Verify credentials
+ * 4. Issue session token on success
+ * 5. Block all non-auth messages until authenticated
+ *
+ * Spec: datachannel-auth-totp.md §4
+ */
+import * as crypto from 'node:crypto';
+import { verifyTotp, verifyBackupCode } from './totp.js';
+import { verifyGoogleIdToken, clearJWKSCache } from './google-jwt.js';
+import { issueSessionToken, verifySessionToken } from './session-token.js';
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+/** Tracks per-connection auth state */
+const authSessions = new Map();
+/** Rate limiting: connectionIds blocked after too many failures */
+const blockedConnections = new Map(); // connectionId → unblock timestamp
+/** TOTP replay prevention */
+let lastUsedTotpStep = 0;
+/** Max nonces to prevent memory leaks from connection storms */
+const MAX_PENDING_NONCES = 10;
+const AUTH_TIMEOUT_MS = 30_000;
+const MAX_FAILURES = 5;
+const BLOCK_DURATION_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Initialize auth for a new DataChannel connection.
+ * Sends auth-required and starts the timeout.
+ *
+ * @returns true if auth was initiated, false if connection is blocked
+ */
+export function initAuth(dc, connectionId) {
+    // Check if this connection is rate-limited
+    const blockedUntil = blockedConnections.get(connectionId);
+    if (blockedUntil && Date.now() < blockedUntil) {
+        dc.send(JSON.stringify({
+            type: 'auth-failed',
+            reason: 'rate_limited',
+        }));
+        return false;
+    }
+    blockedConnections.delete(connectionId);
+    // Cap pending nonces to prevent memory leaks
+    if (authSessions.size >= MAX_PENDING_NONCES) {
+        // Evict oldest
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, session] of authSessions) {
+            if (session.createdAt < oldestTime) {
+                oldestTime = session.createdAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            const old = authSessions.get(oldestKey);
+            clearTimeout(old.timeoutHandle);
+            authSessions.delete(oldestKey);
+        }
+    }
+    const nonce = crypto.randomBytes(32).toString('hex');
+    const timeoutHandle = setTimeout(() => {
+        const session = authSessions.get(connectionId);
+        if (session && session.state === 'awaiting-auth') {
+            dc.send(JSON.stringify({
+                type: 'auth-failed',
+                reason: 'auth_timeout',
+            }));
+            authSessions.delete(connectionId);
+        }
+    }, AUTH_TIMEOUT_MS);
+    authSessions.set(connectionId, {
+        state: 'awaiting-auth',
+        nonce,
+        connectionId,
+        failCount: 0,
+        createdAt: Date.now(),
+        timeoutHandle,
+    });
+    dc.send(JSON.stringify({
+        type: 'auth-required',
+        nonce,
+    }));
+    return true;
+}
+/**
+ * Handle an incoming message on an auth-gated DataChannel.
+ *
+ * @returns 'authenticated' if the message was an auth message and auth succeeded,
+ *          'pending' if auth is still in progress,
+ *          'pass' if the connection is already authenticated (message should be processed normally),
+ *          'blocked' if the message was dropped (pre-auth non-auth message)
+ */
+export async function handleAuthMessage(dc, connectionId, msg, config) {
+    const session = authSessions.get(connectionId);
+    // No auth session = already authenticated or unknown connection
+    if (!session) {
+        return 'pass';
+    }
+    // Already authenticated (shouldn't happen, but be safe)
+    if (session.state === 'authenticated') {
+        clearTimeout(session.timeoutHandle);
+        authSessions.delete(connectionId);
+        return 'pass';
+    }
+    // Only accept auth messages pre-auth
+    const msgType = msg['type'];
+    if (msgType !== 'auth-session' && msgType !== 'auth-full') {
+        return 'blocked';
+    }
+    // Handle auth-session (cached JWT)
+    if (msgType === 'auth-session') {
+        const token = msg['sessionToken'];
+        if (!token) {
+            return sendFailure(dc, connectionId, 'invalid_session');
+        }
+        try {
+            verifySessionToken(token, config.sessionSecret, config.userId, config.google.authorizedSub);
+            return authSuccess(dc, connectionId);
+        }
+        catch (e) {
+            const reason = e.message;
+            // On expired session, don't count as failure — just prompt for full auth
+            if (reason === 'expired_session') {
+                dc.send(JSON.stringify({ type: 'auth-failed', reason: 'expired_session' }));
+                return 'pending';
+            }
+            return sendFailure(dc, connectionId, 'invalid_session');
+        }
+    }
+    // Handle auth-full (Google ID token + TOTP)
+    if (msgType === 'auth-full') {
+        const idToken = msg['idToken'];
+        const totp = msg['totp'];
+        const sessionDays = msg['sessionDays'] || 7;
+        const msgNonce = msg['nonce'];
+        // Verify nonce
+        if (msgNonce !== session.nonce) {
+            return sendFailure(dc, connectionId, 'nonce_mismatch');
+        }
+        // Verify Google ID token (skipped in dev mode)
+        if (config.devMode && idToken === 'dev-mode-no-google') {
+            // Dev mode: skip Google verification
+            console.log('[Auth] Dev mode — skipping Google ID token verification');
+        }
+        else {
+            try {
+                await verifyGoogleIdToken(idToken, {
+                    clientId: config.google.clientId,
+                    authorizedSub: config.google.authorizedSub,
+                    authorizedEmail: config.google.authorizedEmail,
+                });
+            }
+            catch (e) {
+                console.error(`[Auth] Google ID token verification failed: ${e.message}`);
+                // Retry with fresh JWKS on first failure (key rotation)
+                clearJWKSCache();
+                try {
+                    await verifyGoogleIdToken(idToken, {
+                        clientId: config.google.clientId,
+                        authorizedSub: config.google.authorizedSub,
+                        authorizedEmail: config.google.authorizedEmail,
+                    });
+                }
+                catch {
+                    return sendFailure(dc, connectionId, 'invalid_id_token');
+                }
+            }
+        }
+        // Verify TOTP or backup code
+        const totpStep = verifyTotp(totp, config.totp.secret, lastUsedTotpStep);
+        if (totpStep >= 0) {
+            lastUsedTotpStep = totpStep;
+        }
+        else {
+            // Try backup code
+            const backupIndex = config.backupCodeHashes
+                ? verifyBackupCode(totp, config.backupCodeHashes)
+                : -1;
+            if (backupIndex >= 0) {
+                // Consume the backup code
+                config.backupCodeHashes.splice(backupIndex, 1);
+                // Caller should persist the updated config
+            }
+            else {
+                return sendFailure(dc, connectionId, 'invalid_totp');
+            }
+        }
+        // Issue session token
+        const sessionToken = issueSessionToken(config.userId, config.google.authorizedSub, sessionDays, config.sessionSecret);
+        const expiresAt = new Date(Date.now() + Math.min(Math.max(sessionDays, 1), 30) * 86400 * 1000).toISOString();
+        clearTimeout(session.timeoutHandle);
+        authSessions.delete(connectionId);
+        dc.send(JSON.stringify({
+            type: 'auth-ok',
+            sessionToken,
+            expiresAt,
+        }));
+        return 'authenticated';
+    }
+    return 'blocked';
+}
+/**
+ * Clean up auth state for a disconnected DataChannel.
+ */
+export function cleanupAuth(connectionId) {
+    const session = authSessions.get(connectionId);
+    if (session) {
+        clearTimeout(session.timeoutHandle);
+        authSessions.delete(connectionId);
+    }
+}
+/**
+ * Check if a connection is authenticated (no longer in auth sessions).
+ */
+export function isAuthenticated(connectionId) {
+    return !authSessions.has(connectionId);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function authSuccess(dc, connectionId) {
+    const session = authSessions.get(connectionId);
+    if (session) {
+        clearTimeout(session.timeoutHandle);
+        authSessions.delete(connectionId);
+    }
+    dc.send(JSON.stringify({ type: 'auth-ok' }));
+    return 'authenticated';
+}
+function sendFailure(dc, connectionId, reason) {
+    const session = authSessions.get(connectionId);
+    if (!session)
+        return 'pending';
+    session.failCount++;
+    if (session.failCount >= MAX_FAILURES) {
+        dc.send(JSON.stringify({ type: 'auth-failed', reason: 'rate_limited' }));
+        clearTimeout(session.timeoutHandle);
+        authSessions.delete(connectionId);
+        blockedConnections.set(connectionId, Date.now() + BLOCK_DURATION_MS);
+        return 'pending';
+    }
+    dc.send(JSON.stringify({ type: 'auth-failed', reason }));
+    return 'pending';
+}

package/dist/gateway-bridge.d.ts

@@ -17,6 +17,20 @@ export interface PluginConfig {
     devicePrivateKey?: string;
     schemaVersion: number;
     installedAt: string;
+    totp?: {
+        secret: string;
+        algorithm: string;
+        digits: number;
+        period: number;
+        enabledAt: string;
+    };
+    google?: {
+        clientId: string;
+        authorizedSub: string;
+        authorizedEmail: string;
+    };
+    sessionSecret?: string;
+    backupCodeHashes?: string[];
 }
 export interface BridgeConfig {
     gatewayToken: string;

package/dist/google-jwt.d.ts

@@ -0,0 +1,34 @@
+/**
+ * google-jwt.ts — Google ID Token verification
+ *
+ * Verifies Google-signed JWTs against Google's public JWKS.
+ * Uses `jose` for cryptographic verification.
+ *
+ * Spec: datachannel-auth-totp.md §5.1
+ */
+export interface GoogleIdTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string;
+    email: string;
+    email_verified: boolean;
+    exp: number;
+    iat: number;
+}
+export interface VerifyGoogleIdTokenOptions {
+    clientId: string;
+    authorizedSub: string;
+    authorizedEmail: string;
+}
+/**
+ * Verify a Google ID token JWT.
+ *
+ * @param idToken  The raw JWT string from the browser
+ * @param options  Expected clientId, sub, and email
+ * @returns        The verified claims, or throws on failure
+ */
+export declare function verifyGoogleIdToken(idToken: string, options: VerifyGoogleIdTokenOptions): Promise<GoogleIdTokenClaims>;
+/**
+ * Invalidate the JWKS cache (e.g., on key rotation failure).
+ */
+export declare function clearJWKSCache(): void;

package/dist/google-jwt.js

@@ -0,0 +1,87 @@
+/**
+ * google-jwt.ts — Google ID Token verification
+ *
+ * Verifies Google-signed JWTs against Google's public JWKS.
+ * Uses `jose` for cryptographic verification.
+ *
+ * Spec: datachannel-auth-totp.md §5.1
+ */
+import * as https from 'node:https';
+// jose is imported dynamically to allow graceful failure if not installed
+let joseModule = null;
+async function getJose() {
+    if (!joseModule) {
+        joseModule = await import('jose');
+    }
+    return joseModule;
+}
+let jwksCache = null;
+const GOOGLE_JWKS_URI = 'https://www.googleapis.com/oauth2/v3/certs';
+const GOOGLE_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+/**
+ * Fetch Google's JWKS, with caching based on Cache-Control header.
+ */
+async function fetchJWKS() {
+    if (jwksCache && Date.now() < jwksCache.expiresAt) {
+        return jwksCache.keys;
+    }
+    const jose = await getJose();
+    return new Promise((resolve, reject) => {
+        https.get(GOOGLE_JWKS_URI, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk; });
+            res.on('end', () => {
+                try {
+                    const keys = JSON.parse(data);
+                    // Parse Cache-Control max-age
+                    const cacheControl = res.headers['cache-control'] || '';
+                    const maxAgeMatch = cacheControl.match(/max-age=(\d+)/);
+                    const maxAge = maxAgeMatch ? parseInt(maxAgeMatch[1], 10) : 3600;
+                    jwksCache = {
+                        keys,
+                        expiresAt: Date.now() + maxAge * 1000,
+                    };
+                    resolve(keys);
+                }
+                catch (e) {
+                    reject(new Error(`Failed to parse Google JWKS: ${e.message}`));
+                }
+            });
+        }).on('error', reject);
+    });
+}
+/**
+ * Verify a Google ID token JWT.
+ *
+ * @param idToken  The raw JWT string from the browser
+ * @param options  Expected clientId, sub, and email
+ * @returns        The verified claims, or throws on failure
+ */
+export async function verifyGoogleIdToken(idToken, options) {
+    const jose = await getJose();
+    // Fetch JWKS
+    const jwksData = await fetchJWKS();
+    const JWKS = jose.createLocalJWKSet(jwksData);
+    // Verify signature and decode
+    const { payload } = await jose.jwtVerify(idToken, JWKS, {
+        issuer: GOOGLE_ISSUERS,
+        audience: options.clientId,
+    });
+    const claims = payload;
+    // Verify sub matches authorized user
+    if (claims.sub !== options.authorizedSub) {
+        throw new Error(`Google account mismatch: expected sub ${options.authorizedSub}, ` +
+            `got ${claims.sub} (${claims.email})`);
+    }
+    // Verify email matches (belt + suspenders)
+    if (claims.email !== options.authorizedEmail) {
+        throw new Error(`Google email mismatch: expected ${options.authorizedEmail}, got ${claims.email}`);
+    }
+    return claims;
+}
+/**
+ * Invalidate the JWKS cache (e.g., on key rotation failure).
+ */
+export function clearJWKSCache() {
+    jwksCache = null;
+}

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  * Spec: specs/multitenant-p2p.md sections 6.1-6.2
  */
 export declare const PLUGIN_ID = "connector";
-export declare const PLUGIN_VERSION = "0.0.13";
+export declare const PLUGIN_VERSION = "0.0.16";
 interface PluginServiceContext {
     stateDir: string;
     logger: {

package/dist/index.js

@@ -16,14 +16,19 @@ import { SignalingClient } from './signaling-client.js';
 import { WebRTCPeerManager } from './webrtc-peer.js';
 import { dispatchRpc } from './shim.js';
 import { checkForUpdates, performUpdate } from './updater.js';
+import { initAuth, handleAuthMessage, cleanupAuth } from './auth-handler.js';
+import { generateTotpSecret, verifyTotp, generateBackupCodes, buildOtpauthUri } from './totp.js';
+import { generateSessionSecret } from './session-token.js';
 // Inline from shared/api-version.ts to avoid rootDir conflict
 const CURRENT_API_VERSION = 1;
 export const PLUGIN_ID = 'connector';
-export const PLUGIN_VERSION = '0.0.13';
+export const PLUGIN_VERSION = '0.0.16';
 /** Max DataChannel message size (~256KB, leave room for envelope) */
 const MAX_DC_MESSAGE_SIZE = 256 * 1024;
 /** Active DataChannel connections: connectionId → send function */
 const connectedClients = new Map();
+/** Reassembly buffers for chunked gateway-msg from browser (large payloads like image attachments). */
+const gatewayMsgChunkBuffers = new Map();
 let app = null;
 let signaling = null;
 let webrtcPeer = null;
@@ -48,6 +53,10 @@ function loadConfig() {
         return null;
     }
 }
+function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
 // ---------------------------------------------------------------------------
 // Service lifecycle
 // ---------------------------------------------------------------------------
@@ -265,35 +274,145 @@ async function stopClawChats(ctx) {
 // DataChannel message handler (spec section 6.4)
 // ---------------------------------------------------------------------------
 function setupDataChannelHandler(dc, connectionId, ctx) {
-    connectedClients.set(connectionId, dc);
-    dc.onMessage(async (data) => {
-        console.log(`[DC:${connectionId}] Received: ${data.substring(0, 200)}`);
-        let msg;
-        try {
-            msg = JSON.parse(data);
-        }
-        catch {
-            dc.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
-            return;
-        }
-        switch (msg['type']) {
-            case 'rpc':
-                await handleRpcMessage(dc, msg, ctx);
-                break;
-            case 'gateway-msg':
-                // Forward to local OpenClaw gateway via createApp's gateway client
-                if (app?.gatewayClient && typeof msg['payload'] === 'string') {
-                    app.gatewayClient.sendToGateway(msg['payload']);
-                }
-                break;
-            default:
-                dc.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
+    // Build auth config from plugin config
+    const config = loadConfig();
+    const isDevMode = process.env.CLAWCHATS_DEV === 'true';
+    const hasGoogle = !!config?.google;
+    const authEnabled = config?.schemaVersion === 2 && config?.totp && config?.sessionSecret
+        && (hasGoogle || isDevMode);
+    if (authEnabled) {
+        // In dev mode without Google identity, use placeholder
+        const google = config.google ?? {
+            clientId: 'dev-placeholder',
+            authorizedSub: 'dev-placeholder',
+            authorizedEmail: 'dev@localhost',
+        };
+        // Auth-gated: don't add to broadcast clients until authenticated
+        const authConfig = {
+            userId: config.userId,
+            totp: config.totp,
+            google,
+            sessionSecret: config.sessionSecret,
+            backupCodeHashes: config.backupCodeHashes,
+            devMode: isDevMode,
+        };
+        const authStarted = initAuth(dc, connectionId);
+        if (!authStarted)
+            return; // rate-limited, DC will be closed
+        dc.onMessage(async (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data);
+            }
+            catch {
+                dc.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+                return;
+            }
+            // Check auth state
+            const authResult = await handleAuthMessage(dc, connectionId, msg, authConfig);
+            switch (authResult) {
+                case 'authenticated':
+                    // Auth succeeded — add to broadcast clients and inform gateway
+                    connectedClients.set(connectionId, dc);
+                    ctx.logger.info(`Browser authenticated: ${connectionId}`);
+                    // Persist backup code changes if any were consumed
+                    if (authConfig.backupCodeHashes && config.backupCodeHashes) {
+                        config.backupCodeHashes = authConfig.backupCodeHashes;
+                        saveConfig(config);
+                    }
+                    return;
+                case 'pending':
+                    // Still waiting for valid auth
+                    return;
+                case 'blocked':
+                    // Pre-auth non-auth message — drop silently
+                    return;
+                case 'pass':
+                    // Already authenticated — process message normally
+                    break;
+            }
+            // Authenticated message processing
+            processAuthenticatedMessage(dc, connectionId, msg, ctx);
+        });
+    }
+    else {
+        // No auth configured (schemaVersion 1 or missing TOTP)
+        if (config && config.schemaVersion !== undefined && config.schemaVersion < 2) {
+            ctx.logger.warn('TOTP not configured — DataChannel access blocked. Run: openclaw clawchats reauth');
+            dc.send(JSON.stringify({
+                type: 'auth-required-setup',
+                message: 'Two-factor authentication is required. Run "openclaw clawchats reauth" on your gateway machine to set it up.',
+            }));
+            return; // Don't process any messages
         }
-    });
+        // Legacy path: no config at all (shouldn't happen in normal flow)
+        connectedClients.set(connectionId, dc);
+        dc.onMessage(async (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data);
+            }
+            catch {
+                dc.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+                return;
+            }
+            processAuthenticatedMessage(dc, connectionId, msg, ctx);
+        });
+    }
     dc.onClosed(() => {
         connectedClients.delete(connectionId);
+        cleanupAuth(connectionId);
     });
 }
+/**
+ * Process a message on an authenticated DataChannel.
+ */
+function processAuthenticatedMessage(dc, connectionId, msg, ctx) {
+    switch (msg['type']) {
+        case 'rpc':
+            handleRpcMessage(dc, msg, ctx);
+            break;
+        case 'gateway-msg':
+            if (app?.gatewayClient && typeof msg['payload'] === 'string') {
+                app.gatewayClient.sendToGateway(msg['payload']);
+            }
+            break;
+        case 'gateway-msg-chunk': {
+            const chunkId = msg['id'];
+            const index = msg['index'];
+            const total = msg['total'];
+            const chunkData = msg['data'];
+            if (!chunkId || typeof index !== 'number' || typeof total !== 'number' || !chunkData) {
+                dc.send(JSON.stringify({ type: 'error', message: 'malformed gateway-msg-chunk' }));
+                break;
+            }
+            if (!gatewayMsgChunkBuffers.has(chunkId)) {
+                gatewayMsgChunkBuffers.set(chunkId, {
+                    chunks: new Array(total),
+                    received: 0,
+                    total,
+                    createdAt: Date.now(),
+                });
+                setTimeout(() => gatewayMsgChunkBuffers.delete(chunkId), 30_000);
+            }
+            const buf = gatewayMsgChunkBuffers.get(chunkId);
+            if (!buf.chunks[index]) {
+                buf.chunks[index] = chunkData;
+                buf.received++;
+            }
+            if (buf.received === buf.total) {
+                gatewayMsgChunkBuffers.delete(chunkId);
+                const fullPayload = buf.chunks.join('');
+                if (app?.gatewayClient) {
+                    app.gatewayClient.sendToGateway(fullPayload);
+                }
+            }
+            break;
+        }
+        default:
+            dc.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
+    }
+}
 async function handleRpcMessage(dc, msg, ctx) {
     if (!app) {
         dc.send(JSON.stringify({
@@ -446,12 +565,13 @@ async function handleSetup(token) {
                 apiKey,
             }));
         });
-        ws.on('message', (raw) => {
+        ws.on('message', async (raw) => {
             const msg = JSON.parse(raw.toString());
             if (msg.type === 'setup-complete') {
                 clearTimeout(timeout);
                 console.log(`  User: ${msg.userId}`);
-                // Save config
+                console.log('  Registering gateway... ✅');
+                // Save initial config (schemaVersion 1 — will upgrade to 2 after TOTP enrollment)
                 const config = {
                     userId: msg.userId,
                     serverUrl: tokenData.serverUrl,
@@ -460,16 +580,31 @@ async function handleSetup(token) {
                     schemaVersion: 1,
                     installedAt: new Date().toISOString(),
                 };
+                // Bind Google identity if provided by signaling server
+                if (msg.google) {
+                    config.google = {
+                        clientId: msg.google.clientId,
+                        authorizedSub: msg.google.sub,
+                        authorizedEmail: msg.google.email,
+                    };
+                }
                 fs.mkdirSync(CONFIG_DIR, { recursive: true });
-                fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+                saveConfig(config);
                 // Create data directories
                 const dataDir = path.join(CONFIG_DIR, 'data');
                 const uploadsDir = path.join(CONFIG_DIR, 'uploads');
                 fs.mkdirSync(dataDir, { recursive: true });
                 fs.mkdirSync(uploadsDir, { recursive: true });
+                ws.close();
+                // Enroll TOTP (interactive — requires stdin)
+                const totpOk = await enrollTotp(config);
+                if (!totpOk) {
+                    console.log('');
+                    console.log('  ⚠️  TOTP not configured. You can set it up later with: openclaw clawchats reauth');
+                    console.log('  ClawChats will not allow browser connections until 2FA is enabled.');
+                }
                 console.log('  ClawChats is ready!');
                 console.log('  Open clawchats.ai in your browser to start chatting.');
-                ws.close();
                 resolve();
             }
             else if (msg.type === 'setup-error') {
@@ -489,6 +624,95 @@ async function handleSetup(token) {
         });
     });
 }
+async function enrollTotp(config) {
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    try {
+        // Generate TOTP secret
+        const totpSecret = generateTotpSecret();
+        const email = config.google?.authorizedEmail || config.userId;
+        const otpauthUri = buildOtpauthUri(totpSecret, email);
+        // Format secret with spaces for readability
+        const formatted = totpSecret.match(/.{1,4}/g)?.join(' ') || totpSecret;
+        console.log('');
+        console.log('  🔐 Setting up two-factor authentication');
+        console.log('');
+        console.log('  Open this link to scan the QR code with your authenticator app:');
+        console.log(`  ${config.serverUrl.replace('wss://', 'https://').replace(/\/ws\/?$/, '')}/totp-setup#${totpSecret}`);
+        console.log('');
+        console.log(`  Or enter this code manually: ${formatted}`);
+        console.log('');
+        console.log("  Don't have an authenticator app?");
+        console.log('  Google Authenticator: https://apps.apple.com/app/google-authenticator/id388497605');
+        console.log('                        https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2');
+        console.log('');
+        // Verification loop
+        let verified = false;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const code = await ask('  Enter a code from your app to verify: ');
+            const step = verifyTotp(code.trim(), totpSecret, 0);
+            if (step >= 0) {
+                verified = true;
+                break;
+            }
+            console.log('  ❌ Invalid code. Make sure you scanned the right QR code and try again.');
+        }
+        if (!verified) {
+            console.log('  Too many failed attempts. TOTP setup cancelled.');
+            rl.close();
+            return false;
+        }
+        console.log('  ✅ Two-factor authentication enabled!');
+        // Generate backup codes
+        const { codes, hashes } = generateBackupCodes();
+        console.log('');
+        console.log('  🔑 Backup codes (save these somewhere safe — one-time use):');
+        for (const code of codes) {
+            console.log(`     ${code}`);
+        }
+        console.log('');
+        console.log('  ⚠️  These codes will NOT be shown again.');
+        // Generate session secret
+        const sessionSecret = generateSessionSecret();
+        // Update config
+        config.totp = {
+            secret: totpSecret,
+            algorithm: 'SHA1',
+            digits: 6,
+            period: 30,
+            enabledAt: new Date().toISOString(),
+        };
+        config.sessionSecret = sessionSecret;
+        config.backupCodeHashes = hashes;
+        config.schemaVersion = 2;
+        saveConfig(config);
+        console.log('');
+        rl.close();
+        return true;
+    }
+    catch (e) {
+        rl.close();
+        console.error(`  TOTP setup failed: ${e.message}`);
+        return false;
+    }
+}
+async function handleReauth() {
+    const config = loadConfig();
+    if (!config) {
+        console.error('ClawChats not configured. Run: openclaw clawchats setup <token>');
+        return;
+    }
+    console.log('🔐 Re-initializing ClawChats authentication...');
+    console.log('');
+    console.log('  ⚠️  This will invalidate all existing sessions.');
+    console.log('  All connected browsers will need to re-authenticate.');
+    const success = await enrollTotp(config);
+    if (success) {
+        console.log('  All previous sessions have been invalidated.');
+        console.log('  Restart the gateway for changes to take effect: systemctl --user restart openclaw-gateway');
+    }
+}
 async function handleStatus() {
     // CLI runs in a separate process — module-level vars are null here.
     // Query the live service via the health endpoint instead.
@@ -623,6 +847,9 @@ const plugin = {
             cmd.command('status')
                 .description('Show ClawChats connection status')
                 .action(() => handleStatus());
+            cmd.command('reauth')
+                .description('Reset two-factor authentication (new TOTP secret + invalidate sessions)')
+                .action(() => handleReauth());
             cmd.command('reset')
                 .description('Disconnect and remove all ClawChats data')
                 .action(() => handleReset());

package/dist/session-token.d.ts

@@ -0,0 +1,43 @@
+/**
+ * session-token.ts — Plugin-local session JWT management
+ *
+ * Issues and verifies HS256 JWTs that let returning users skip TOTP.
+ * Signing key is stored in config.json — regenerating it invalidates
+ * all previously issued tokens.
+ *
+ * Spec: datachannel-auth-totp.md §6
+ */
+interface SessionPayload {
+    sub: string;
+    googleSub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+}
+/**
+ * Issue a session token.
+ *
+ * @param userId      The ClawChats user ID
+ * @param googleSub   The Google account sub
+ * @param sessionDays Duration in days (1-30, clamped)
+ * @param secret      The 256-bit hex signing key from config
+ * @returns           The signed JWT string
+ */
+export declare function issueSessionToken(userId: string, googleSub: string, sessionDays: number, secret: string): string;
+/**
+ * Verify a session token.
+ *
+ * @param token       The JWT string from the browser
+ * @param secret      The 256-bit hex signing key from config
+ * @param userId      Expected userId
+ * @param googleSub   Expected Google sub
+ * @returns           The decoded payload if valid
+ * @throws            Error with descriptive message on failure
+ */
+export declare function verifySessionToken(token: string, secret: string, userId: string, googleSub: string): SessionPayload;
+/**
+ * Generate a new 256-bit session secret (hex-encoded).
+ * Call this during initial setup and on `reauth` to invalidate all sessions.
+ */
+export declare function generateSessionSecret(): string;
+export {};

package/dist/session-token.js

@@ -0,0 +1,102 @@
+/**
+ * session-token.ts — Plugin-local session JWT management
+ *
+ * Issues and verifies HS256 JWTs that let returning users skip TOTP.
+ * Signing key is stored in config.json — regenerating it invalidates
+ * all previously issued tokens.
+ *
+ * Spec: datachannel-auth-totp.md §6
+ */
+import * as crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// HS256 JWT implementation (minimal, no dependencies)
+// ---------------------------------------------------------------------------
+function base64urlEncode(data) {
+    const buf = typeof data === 'string' ? Buffer.from(data) : data;
+    return buf.toString('base64url');
+}
+function base64urlDecode(str) {
+    return Buffer.from(str, 'base64url');
+}
+/**
+ * Issue a session token.
+ *
+ * @param userId      The ClawChats user ID
+ * @param googleSub   The Google account sub
+ * @param sessionDays Duration in days (1-30, clamped)
+ * @param secret      The 256-bit hex signing key from config
+ * @returns           The signed JWT string
+ */
+export function issueSessionToken(userId, googleSub, sessionDays, secret) {
+    const days = Math.min(Math.max(Math.round(sessionDays), 1), 30);
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'HS256', typ: 'JWT' };
+    const payload = {
+        sub: userId,
+        googleSub,
+        iat: now,
+        exp: now + days * 86400,
+        jti: crypto.randomUUID(),
+    };
+    const headerB64 = base64urlEncode(JSON.stringify(header));
+    const payloadB64 = base64urlEncode(JSON.stringify(payload));
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const hmac = crypto.createHmac('sha256', Buffer.from(secret, 'hex'));
+    hmac.update(signingInput);
+    const signature = hmac.digest().toString('base64url');
+    return `${signingInput}.${signature}`;
+}
+/**
+ * Verify a session token.
+ *
+ * @param token       The JWT string from the browser
+ * @param secret      The 256-bit hex signing key from config
+ * @param userId      Expected userId
+ * @param googleSub   Expected Google sub
+ * @returns           The decoded payload if valid
+ * @throws            Error with descriptive message on failure
+ */
+export function verifySessionToken(token, secret, userId, googleSub) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        throw new Error('malformed_token');
+    const [headerB64, payloadB64, signatureB64] = parts;
+    // Verify signature
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const hmac = crypto.createHmac('sha256', Buffer.from(secret, 'hex'));
+    hmac.update(signingInput);
+    const expectedSig = hmac.digest();
+    const actualSig = base64urlDecode(signatureB64);
+    if (expectedSig.length !== actualSig.length ||
+        !crypto.timingSafeEqual(expectedSig, actualSig)) {
+        throw new Error('invalid_signature');
+    }
+    // Decode payload
+    let payload;
+    try {
+        payload = JSON.parse(base64urlDecode(payloadB64).toString('utf8'));
+    }
+    catch {
+        throw new Error('malformed_payload');
+    }
+    // Check expiry
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp <= now)
+        throw new Error('expired_session');
+    // Check not issued in the future (clock skew tolerance: 60s)
+    if (payload.iat > now + 60)
+        throw new Error('invalid_iat');
+    // Check identity
+    if (payload.sub !== userId)
+        throw new Error('invalid_user');
+    if (payload.googleSub !== googleSub)
+        throw new Error('invalid_google_sub');
+    return payload;
+}
+/**
+ * Generate a new 256-bit session secret (hex-encoded).
+ * Call this during initial setup and on `reauth` to invalidate all sessions.
+ */
+export function generateSessionSecret() {
+    return crypto.randomBytes(32).toString('hex');
+}

package/dist/totp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * totp.ts — RFC 6238 TOTP implementation
+ *
+ * Generates and verifies 6-digit time-based one-time passwords.
+ * No external dependencies — uses Node.js built-in crypto.
+ *
+ * Spec: datachannel-auth-totp.md §5.2
+ */
+/**
+ * Generate a TOTP code for the current time.
+ */
+export declare function generateTotp(secretBase32: string): string;
+/**
+ * Verify a TOTP code with ±1 time-step window and replay prevention.
+ *
+ * @param code          The 6-digit code from the user
+ * @param secretBase32  The base32-encoded TOTP secret
+ * @param lastUsedStep  The last successfully used time step (for replay prevention)
+ * @returns             The matched time step if valid, or -1 if invalid
+ */
+export declare function verifyTotp(code: string, secretBase32: string, lastUsedStep: number): number;
+/**
+ * Generate a random 20-byte TOTP secret, returned as base32.
+ */
+export declare function generateTotpSecret(): string;
+/**
+ * Build an otpauth:// URI for QR code generation.
+ */
+export declare function buildOtpauthUri(secretBase32: string, email: string): string;
+/**
+ * Generate backup codes — 10 random 8-char alphanumeric codes.
+ * Returns { codes: string[], hashes: string[] }.
+ * Display `codes` to the user once. Store `hashes` in config.
+ */
+export declare function generateBackupCodes(): {
+    codes: string[];
+    hashes: string[];
+};
+/**
+ * Verify a backup code against stored hashes. Returns the index consumed, or -1.
+ */
+export declare function verifyBackupCode(code: string, hashes: string[]): number;

package/dist/totp.js

@@ -0,0 +1,167 @@
+/**
+ * totp.ts — RFC 6238 TOTP implementation
+ *
+ * Generates and verifies 6-digit time-based one-time passwords.
+ * No external dependencies — uses Node.js built-in crypto.
+ *
+ * Spec: datachannel-auth-totp.md §5.2
+ */
+import * as crypto from 'node:crypto';
+const DIGITS = 6;
+const PERIOD = 30;
+const ALGORITHM = 'sha1';
+/**
+ * Generate a TOTP code for a given time step.
+ */
+function generateForStep(secret, step) {
+    // Convert step to 8-byte big-endian buffer
+    const stepBuf = Buffer.alloc(8);
+    stepBuf.writeBigUInt64BE(BigInt(step));
+    // HMAC-SHA1
+    const hmac = crypto.createHmac(ALGORITHM, secret);
+    hmac.update(stepBuf);
+    const hash = hmac.digest();
+    // Dynamic truncation (RFC 4226 §5.4)
+    const offset = hash[hash.length - 1] & 0x0f;
+    const binary = ((hash[offset] & 0x7f) << 24) |
+        ((hash[offset + 1] & 0xff) << 16) |
+        ((hash[offset + 2] & 0xff) << 8) |
+        (hash[offset + 3] & 0xff);
+    const otp = binary % 10 ** DIGITS;
+    return otp.toString().padStart(DIGITS, '0');
+}
+/**
+ * Generate a TOTP code for the current time.
+ */
+export function generateTotp(secretBase32) {
+    const secret = base32Decode(secretBase32);
+    const step = Math.floor(Date.now() / 1000 / PERIOD);
+    return generateForStep(secret, step);
+}
+/**
+ * Verify a TOTP code with ±1 time-step window and replay prevention.
+ *
+ * @param code          The 6-digit code from the user
+ * @param secretBase32  The base32-encoded TOTP secret
+ * @param lastUsedStep  The last successfully used time step (for replay prevention)
+ * @returns             The matched time step if valid, or -1 if invalid
+ */
+export function verifyTotp(code, secretBase32, lastUsedStep) {
+    if (!/^\d{6}$/.test(code))
+        return -1;
+    const secret = base32Decode(secretBase32);
+    const currentStep = Math.floor(Date.now() / 1000 / PERIOD);
+    // Check T-1, T, T+1
+    for (const offset of [-1, 0, 1]) {
+        const step = currentStep + offset;
+        if (step <= lastUsedStep)
+            continue; // replay protection
+        const expected = generateForStep(secret, step);
+        if (timingSafeEqual(code, expected)) {
+            return step; // caller should update lastUsedStep to this value
+        }
+    }
+    return -1;
+}
+/**
+ * Generate a random 20-byte TOTP secret, returned as base32.
+ */
+export function generateTotpSecret() {
+    const secret = crypto.randomBytes(20);
+    return base32Encode(secret);
+}
+/**
+ * Build an otpauth:// URI for QR code generation.
+ */
+export function buildOtpauthUri(secretBase32, email) {
+    const issuer = 'ClawChats';
+    const label = encodeURIComponent(`${issuer}:${email}`);
+    const params = new URLSearchParams({
+        secret: secretBase32,
+        issuer,
+        algorithm: 'SHA1',
+        digits: String(DIGITS),
+        period: String(PERIOD),
+    });
+    return `otpauth://totp/${label}?${params.toString()}`;
+}
+/**
+ * Generate backup codes — 10 random 8-char alphanumeric codes.
+ * Returns { codes: string[], hashes: string[] }.
+ * Display `codes` to the user once. Store `hashes` in config.
+ */
+export function generateBackupCodes() {
+    const codes = [];
+    const hashes = [];
+    const charset = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // no O/0/I/1 ambiguity
+    for (let i = 0; i < 10; i++) {
+        const bytes = crypto.randomBytes(8);
+        let code = '';
+        for (let j = 0; j < 8; j++) {
+            code += charset[bytes[j] % charset.length];
+        }
+        // Format as XXXX-XXXX for readability
+        const formatted = `${code.slice(0, 4)}-${code.slice(4)}`;
+        codes.push(formatted);
+        hashes.push(crypto.createHash('sha256').update(formatted).digest('hex'));
+    }
+    return { codes, hashes };
+}
+/**
+ * Verify a backup code against stored hashes. Returns the index consumed, or -1.
+ */
+export function verifyBackupCode(code, hashes) {
+    const normalized = code.toUpperCase().replace(/\s/g, '');
+    const hash = crypto.createHash('sha256').update(normalized).digest('hex');
+    const index = hashes.indexOf(hash);
+    return index; // caller should remove hashes[index] after use
+}
+// ---------------------------------------------------------------------------
+// Base32 encoding/decoding (RFC 4648)
+// ---------------------------------------------------------------------------
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+function base32Encode(data) {
+    let result = '';
+    let bits = 0;
+    let value = 0;
+    for (const byte of data) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            result += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+        }
+    }
+    if (bits > 0) {
+        result += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return result;
+}
+function base32Decode(encoded) {
+    const cleaned = encoded.toUpperCase().replace(/[^A-Z2-7]/g, '');
+    const bytes = [];
+    let bits = 0;
+    let value = 0;
+    for (const char of cleaned) {
+        const idx = BASE32_ALPHABET.indexOf(char);
+        if (idx === -1)
+            continue;
+        value = (value << 5) | idx;
+        bits += 5;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((value >>> bits) & 0xff);
+        }
+    }
+    return Buffer.from(bytes);
+}
+// ---------------------------------------------------------------------------
+// Timing-safe string comparison
+// ---------------------------------------------------------------------------
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    return crypto.timingSafeEqual(bufA, bufB);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawchatsai/connector",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "description": "ClawChats OpenClaw plugin — P2P tunnel + local API bridge",
   "main": "dist/index.js",
@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "better-sqlite3": ">=9.0.0",
+    "jose": "^5.10.0",
     "werift": "^0.19.9",
     "ws": "^8.0.0"
   },