@tyvm/knowhow 0.0.83 → 0.0.84

package/src/worker.ts

@@ -4,6 +4,9 @@ import { createTunnelHandler, TunnelHandler } from "@tyvm/knowhow-tunnel";
 import { includedTools } from "./agents/tools/list";
 import { loadJwt } from "./login";
 import { services } from "./services";
+import { PasskeySetupService } from "./workers/auth/PasskeySetup";
+import { WorkerPasskeyAuthService } from "./workers/auth/WorkerPasskeyAuth";
+import { makeUnlockTool, makeLockTool } from "./workers/tools";
 import { McpServerService } from "./services/Mcp";
 import * as allTools from "./agents/tools";
 import workerTools from "./workers/tools";
@@ -85,9 +88,33 @@ export async function worker(options?: {
   unshare?: boolean;
   sandbox?: boolean;
   noSandbox?: boolean;
+  passkey?: boolean;
+  passkeyReset?: boolean;
 }) {
   const config = await getConfig();
 
+  // Handle --passkey-reset: remove passkey from config
+  if (options?.passkeyReset) {
+    const passkeySetup = new PasskeySetupService();
+    await passkeySetup.reset();
+    return;
+  }
+
+  // Handle --passkey: run browser-based passkey registration flow
+  if (options?.passkey) {
+    let jwt: string;
+    try {
+      jwt = await loadJwt();
+    } catch {
+      console.error("❌ You must be logged in to set up a passkey.");
+      console.error("   Run 'knowhow login' first.");
+      process.exit(1);
+    }
+    const passkeySetup = new PasskeySetupService();
+    await passkeySetup.setup(jwt);
+    return;
+  }
+
   // Check if we're already running inside a Docker container
   const isInsideDocker = process.env.KNOWHOW_DOCKER === "true";
 
@@ -158,6 +185,24 @@ export async function worker(options?: {
   const clientName = "knowhow-worker";
   const clientVersion = "1.1.1";
 
+  // ---------------------------------------------------------------------------
+  // Passkey auth gating
+  // ---------------------------------------------------------------------------
+  let authService: WorkerPasskeyAuthService | null = null;
+  const passkeyConfig = config.worker?.auth?.passkey;
+
+  if (passkeyConfig?.publicKey && passkeyConfig?.credentialId) {
+    authService = new WorkerPasskeyAuthService(
+      {
+        publicKey: passkeyConfig.publicKey,
+        credentialId: passkeyConfig.credentialId,
+        algorithm: -7, // ES256
+      },
+      config.worker?.auth?.sessionDurationHours ?? 3
+    );
+    console.log("🔒 Passkey auth enabled — worker starts locked");
+  }
+
   if (!shouldUseSandbox) {
     console.log(`🖥️  Using host mode (${sandboxSource})`);
   }
@@ -172,7 +217,6 @@ export async function worker(options?: {
       ...config.worker,
       allowedTools: Tools.getToolNames(),
     };
-
     await updateConfig(config);
     return;
   }
@@ -183,7 +227,41 @@ export async function worker(options?: {
     return;
   }
 
-  const toolsToUse = Tools.getToolsByNames(config.worker.allowedTools);
+  let toolsToUse = Tools.getToolsByNames(config.worker.allowedTools);
+
+  // If passkey auth is enabled, wrap all tool functions to check locked state
+  // and register the unlock/lock auth tools
+  if (authService) {
+    const _authService = authService;
+
+    // Wrap every configured tool to gate on locked state
+    for (const tool of toolsToUse) {
+      const toolName = tool.function.name;
+      const originalFn = Tools.getFunction(toolName);
+      Tools.addFunctions({
+        [toolName]: async (...args: any[]) => {
+          if (_authService.isLocked()) {
+            return {
+              error: "WORKER_LOCKED",
+              message:
+                "Worker is locked. Call the `unlock` tool with your passkey assertion to unlock it first.",
+            };
+          }
+          return originalFn(...args);
+        },
+      });
+    }
+
+    // Build and register the auth tools
+    const { unlock, unlockDefinition } = makeUnlockTool(_authService);
+    const { lock, lockDefinition } = makeLockTool(_authService);
+
+    Tools.addFunctions({ unlock, lock });
+    toolsToUse = [unlockDefinition, lockDefinition, ...toolsToUse];
+
+    console.log("🔑 Auth tools registered: unlock, lock");
+  }
+
   mcpServer.createServer(clientName, clientVersion).withTools(toolsToUse);
 
   let connected = false;

package/src/workers/auth/PasskeySetup.ts

@@ -0,0 +1,185 @@
+import axios from "axios";
+import { KNOWHOW_API_URL } from "../../services/KnowhowClient";
+import { openBrowser } from "../../auth/browserLogin";
+import { Spinner } from "../../auth/spinner";
+import { getConfig, updateConfig } from "../../config";
+import { PasskeySetupSession, PasskeySetupStatus, PasskeyCredential } from "./types";
+
+/**
+ * Service that handles the CLI-side passkey setup flow.
+ *
+ * Flow:
+ *  1. POST /api/worker/passkey/setup/session  → get sessionId + browserUrl
+ *  2. Open browser to browserUrl
+ *  3. Poll /api/worker/passkey/setup/status/:sessionId until status === 'complete'
+ *  4. Save the returned credential to local config
+ */
+export class PasskeySetupService {
+  private baseUrl: string;
+
+  constructor(baseUrl: string = KNOWHOW_API_URL) {
+    if (!baseUrl) {
+      throw new Error("KNOWHOW_API_URL environment variable not set");
+    }
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Run the full passkey setup flow.
+   */
+  async setup(jwt: string): Promise<void> {
+    const spinner = new Spinner();
+
+    try {
+      spinner.start("Creating passkey setup session");
+      const session = await this.createSetupSession(jwt);
+      spinner.stop();
+
+      await openBrowser(session.browserUrl);
+      console.log(
+        `\nIf the browser didn't open automatically, please visit:\n  ${session.browserUrl}\n`
+      );
+
+      spinner.start("Waiting for passkey registration in browser…");
+
+      const credential = await this.pollForCompletion(session.sessionId, spinner);
+
+      spinner.stop();
+      spinner.start("Saving passkey credential to config");
+
+      await this.saveCredential(credential);
+
+      spinner.stop();
+      console.log("✅ Passkey registered successfully!");
+      console.log(
+        "   Worker will now require passkey authentication for new connections."
+      );
+    } catch (error) {
+      spinner.stop();
+      throw error;
+    }
+  }
+
+  /**
+   * Remove passkey requirement from config.
+   */
+  async reset(): Promise<void> {
+    const config = await getConfig();
+
+    if (!config.worker?.auth?.passkey) {
+      console.log("ℹ️  No passkey configured for this worker.");
+      return;
+    }
+
+    const updatedConfig = {
+      ...config,
+      worker: {
+        ...config.worker,
+        auth: {
+          ...config.worker.auth,
+          required: false,
+          passkey: undefined,
+        },
+      },
+    };
+
+    await updateConfig(updatedConfig);
+    console.log("✅ Passkey requirement removed from config.");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private async createSetupSession(jwt: string): Promise<PasskeySetupSession> {
+    try {
+      const response = await axios.post<PasskeySetupSession>(
+        `${this.baseUrl}/api/worker/passkey/setup/session`,
+        {},
+        {
+          headers: { Authorization: `Bearer ${jwt}` },
+          timeout: 10000,
+        }
+      );
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        throw new Error(
+          `Failed to create passkey setup session: ${
+            error.response?.data?.message || error.message
+          }`
+        );
+      }
+      throw error;
+    }
+  }
+
+  private async pollForCompletion(
+    sessionId: string,
+    spinner: Spinner
+  ): Promise<PasskeyCredential> {
+    const maxAttempts = 60; // 5 minutes at 5-second intervals
+    let attempt = 0;
+
+    while (attempt < maxAttempts) {
+      attempt++;
+
+      try {
+        const response = await axios.get<PasskeySetupStatus>(
+          `${this.baseUrl}/api/worker/passkey/setup/status/${sessionId}`,
+          { timeout: 10000 }
+        );
+
+        const { status, credential } = response.data;
+
+        if (status === "complete" && credential) {
+          return credential;
+        } else if (status === "expired") {
+          throw new Error(
+            "Passkey setup session expired. Please run 'knowhow worker --passkey' again."
+          );
+        }
+      } catch (error) {
+        if (axios.isAxiosError(error) && error.code === "ECONNABORTED") {
+          // Timeout — keep polling
+        } else if (!(error instanceof Error && error.message.includes("expired"))) {
+          // Re-throw non-timeout, non-expected errors
+          throw error;
+        } else {
+          throw error;
+        }
+      }
+
+      await this.sleep(5000);
+    }
+
+    throw new Error("Passkey setup timed out. Please try again.");
+  }
+
+  private async saveCredential(credential: PasskeyCredential): Promise<void> {
+    const config = await getConfig();
+
+    const updatedConfig = {
+      ...config,
+      worker: {
+        ...config.worker,
+        auth: {
+          ...config.worker?.auth,
+          required: true,
+          passkey: {
+            publicKey: credential.publicKey,
+            credentialId: credential.credentialId,
+            algorithm: credential.algorithm,
+          },
+          sessionDurationHours: config.worker?.auth?.sessionDurationHours ?? 3,
+        },
+      },
+    };
+
+    await updateConfig(updatedConfig);
+  }
+
+  private async sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/workers/auth/WorkerPasskeyAuth.ts

@@ -0,0 +1,190 @@
+import crypto from "crypto";
+import { verifyAuthenticationResponse } from "@simplewebauthn/server";
+
+/**
+ * Manages the locked/unlocked state of the worker's passkey auth.
+ * When the worker has passkey configured, it starts locked.
+ * The user must call `unlock` with a valid WebAuthn assertion to unlock.
+ * The worker verifies the signature locally using the stored public key.
+ */
+
+export interface PasskeyConfig {
+  publicKey: string;    // base64url-encoded COSE public key
+  credentialId: string; // base64url-encoded credential ID
+  algorithm: number;    // e.g. -7 for ES256
+}
+
+export interface UnlockParams {
+  /** base64url-encoded signature from WebAuthn assertion */
+  signature: string;
+  /** base64url-encoded credential ID */
+  credentialId: string;
+  /** base64url-encoded authenticatorData */
+  authenticatorData: string;
+  /** base64url-encoded clientDataJSON */
+  clientDataJSON: string;
+  /** The challenge that was signed (base64url) */
+  challenge: string;
+}
+
+export class WorkerPasskeyAuthService {
+  private locked = true;
+  private sessionExpiry: number | null = null;
+  private sessionDurationMs: number;
+  // Pending challenge: base64url
+  private pendingChallenge: string | null = null;
+  private pendingChallengeExpiry: number | null = null;
+  private readonly CHALLENGE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+  constructor(
+    private passkeyConfig: PasskeyConfig,
+    sessionDurationHours: number = 3
+  ) {
+    this.sessionDurationMs = sessionDurationHours * 60 * 60 * 1000;
+  }
+
+  isLocked(): boolean {
+    if (!this.locked) {
+      // Check if session has expired
+      if (this.sessionExpiry && Date.now() > this.sessionExpiry) {
+        console.log("🔒 Passkey session expired, locking worker");
+        this.locked = true;
+        this.sessionExpiry = null;
+      }
+    }
+    return this.locked;
+  }
+
+  /**
+   * Generate a new challenge for the client to sign.
+   * Returns base64url-encoded challenge bytes.
+   */
+  generateChallenge(): string {
+    const challengeBytes = crypto.randomBytes(32);
+    const challenge = challengeBytes.toString("base64url");
+    this.pendingChallenge = challenge;
+    this.pendingChallengeExpiry = Date.now() + this.CHALLENGE_TTL_MS;
+    return challenge;
+  }
+
+  /**
+   * Attempt to unlock the worker by verifying a WebAuthn assertion.
+   * Returns true if the signature is valid and the worker is now unlocked.
+   */
+  async unlock(params: UnlockParams): Promise<{ success: boolean; reason?: string }> {
+    // Verify the challenge matches what we issued
+    if (!this.pendingChallenge) {
+      return { success: false, reason: "No pending challenge. Call getChallenge first." };
+    }
+    if (this.pendingChallengeExpiry && Date.now() > this.pendingChallengeExpiry) {
+      this.pendingChallenge = null;
+      this.pendingChallengeExpiry = null;
+      return { success: false, reason: "Challenge expired. Please request a new challenge." };
+    }
+
+    // Verify the challenge in clientDataJSON matches our pending challenge
+    let clientData: { type: string; challenge: string; origin: string };
+    try {
+      const clientDataBytes = Buffer.from(params.clientDataJSON, "base64url");
+      clientData = JSON.parse(clientDataBytes.toString("utf8"));
+    } catch {
+      return { success: false, reason: "Invalid clientDataJSON" };
+    }
+
+    // The challenge in clientDataJSON is base64url-encoded
+    if (clientData.challenge !== this.pendingChallenge) {
+      return { success: false, reason: "Challenge mismatch" };
+    }
+
+    if (clientData.type !== "webauthn.get") {
+      return { success: false, reason: "Invalid clientData type" };
+    }
+
+    // Verify credential ID matches our stored credential
+    if (params.credentialId !== this.passkeyConfig.credentialId) {
+      return { success: false, reason: "Unknown credential" };
+    }
+
+    // Verify the signature using @simplewebauthn/server
+    const valid = await this.verifySignature(params, clientData.origin);
+    if (!valid) {
+      return { success: false, reason: "Invalid signature" };
+    }
+
+    // Unlock!
+    this.locked = false;
+    this.sessionExpiry = Date.now() + this.sessionDurationMs;
+    this.pendingChallenge = null;
+    this.pendingChallengeExpiry = null;
+
+    const expiresAt = new Date(this.sessionExpiry).toISOString();
+    console.log(`🔓 Worker unlocked! Session expires at ${expiresAt}`);
+    return { success: true };
+  }
+
+  lock(): void {
+    this.locked = true;
+    this.sessionExpiry = null;
+    this.pendingChallenge = null;
+    this.pendingChallengeExpiry = null;
+    console.log("🔒 Worker locked");
+  }
+
+  getSessionInfo() {
+    if (this.locked || !this.sessionExpiry) {
+      return { locked: true, expiresAt: null };
+    }
+    return {
+      locked: false,
+      expiresAt: new Date(this.sessionExpiry).toISOString(),
+    };
+  }
+
+  /**
+   * Returns the credential ID stored in the passkey config.
+   */
+  getCredentialId(): string {
+    return this.passkeyConfig.credentialId;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Signature verification via @simplewebauthn/server
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Verify a WebAuthn assertion using @simplewebauthn/server's verifyAuthenticationResponse.
+   * This handles all COSE key format complexity automatically.
+   */
+  private async verifySignature(params: UnlockParams, origin: string): Promise<boolean> {
+    try {
+      const { verified } = await verifyAuthenticationResponse({
+        response: {
+          id: params.credentialId,
+          rawId: params.credentialId,
+          response: {
+            authenticatorData: params.authenticatorData,
+            clientDataJSON: params.clientDataJSON,
+            signature: params.signature,
+          },
+          type: "public-key",
+          clientExtensionResults: {},
+        },
+        expectedChallenge: this.pendingChallenge!,
+        expectedOrigin: origin,
+        expectedRPID: new URL(origin).hostname,
+        credential: {
+          id: this.passkeyConfig.credentialId,
+          publicKey: Buffer.from(this.passkeyConfig.publicKey, "base64url"),
+          counter: 0,
+          transports: undefined,
+        },
+        requireUserVerification: false,
+      });
+
+      return verified;
+    } catch (err) {
+      console.error("Signature verification error:", err);
+      return false;
+    }
+  }
+}

package/src/workers/auth/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Auth message types for the worker WebSocket authentication protocol.
+ */
+
+// Worker → Client: challenge
+export interface AuthChallengeMessage {
+  type: "auth:challenge";
+  challenge: string;   // base64-encoded 32 random bytes
+  timestamp: number;   // epoch seconds
+}
+
+// Client → Worker: response
+export interface AuthResponseMessage {
+  type: "auth:response";
+  challenge: string;            // echo back
+  signature: string;            // base64-encoded WebAuthn assertion signature
+  credentialId: string;         // base64-encoded credential ID
+  authenticatorData: string;    // base64-encoded authenticator data
+  clientDataJSON: string;       // base64-encoded client data JSON
+}
+
+// Worker → Client: success
+export interface AuthSuccessMessage {
+  type: "auth:success";
+  token: string;       // opaque session token
+  expiresAt: number;   // epoch seconds
+}
+
+// Worker → Client: failure
+export interface AuthFailureMessage {
+  type: "auth:failure";
+  reason: "invalid_signature" | "expired" | "unknown_credential";
+}
+
+export type AuthMessage =
+  | AuthChallengeMessage
+  | AuthResponseMessage
+  | AuthSuccessMessage
+  | AuthFailureMessage;
+
+// Passkey credential stored in config
+export interface PasskeyCredential {
+  publicKey: string;     // base64-encoded public key
+  credentialId: string;  // base64-encoded credential ID
+  algorithm: string;     // e.g. "ES256"
+}
+
+// Setup session returned by knowhow-web
+export interface PasskeySetupSession {
+  sessionId: string;
+  browserUrl: string;
+}
+
+// Status of a passkey setup session
+export interface PasskeySetupStatus {
+  status: "pending" | "complete" | "expired";
+  credential?: PasskeyCredential;
+}

package/src/workers/tools/getChallenge.ts

@@ -0,0 +1,33 @@
+import { Tool } from "../../clients/types";
+import { WorkerPasskeyAuthService } from "../auth/WorkerPasskeyAuth";
+
+/**
+ * Returns a challenge for the client to sign with their passkey.
+ * The challenge must be signed and passed to the `unlock` tool.
+ */
+export function makeGetChallengeTool(authService: WorkerPasskeyAuthService) {
+  async function getChallenge(): Promise<{ challenge: string; message: string }> {
+    const challenge = authService.generateChallenge();
+    return {
+      challenge,
+      message:
+        "Sign this challenge with your passkey and call the `unlock` tool with the assertion data.",
+    };
+  }
+
+  const getChallengeDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "getChallenge",
+      description:
+        "Get a challenge string to sign with your passkey. Required before calling `unlock`. Returns a base64url-encoded challenge.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  };
+
+  return { getChallenge, getChallengeDefinition };
+}

package/src/workers/tools/index.ts

@@ -1,9 +1,17 @@
 export * from "./listAllowedPorts";
+export * from "./getChallenge";
+export * from "./unlock";
+export * from "./lock";
+
 import {
   listAllowedPorts,
   listAllowedPortsDefinition,
 } from "./listAllowedPorts";
 
+export { makeGetChallengeTool } from "./getChallenge";
+export { makeUnlockTool } from "./unlock";
+export { makeLockTool } from "./lock";
+
 export default {
   tools: { listAllowedPorts },
   definitions: [listAllowedPortsDefinition],

package/src/workers/tools/lock.ts

@@ -0,0 +1,31 @@
+import { Tool } from "../../clients/types";
+import { WorkerPasskeyAuthService } from "../auth/WorkerPasskeyAuth";
+
+/**
+ * Re-locks the worker, requiring passkey authentication again for further tool access.
+ */
+export function makeLockTool(authService: WorkerPasskeyAuthService) {
+  async function lock(): Promise<{ success: boolean; message: string }> {
+    authService.lock();
+    return {
+      success: true,
+      message: "Worker locked. Call getChallenge and unlock to regain access.",
+    };
+  }
+
+  const lockDefinition: Tool = {
+    type: "function" as const,
+    function: {
+      name: "lock",
+      description:
+        "Lock the worker. After locking, only getChallenge, unlock, and lock tools will be accessible until the worker is unlocked again with a valid passkey assertion.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  };
+
+  return { lock, lockDefinition };
+}