@weavetab/mcp 2.5.0-beta.0

package/dist/security/secrets.js

@@ -0,0 +1,365 @@
+/**
+ * Weavetab — security/secrets.ts
+ * Structured secret store with per-key domain scoping and chmod 600 enforcement.
+ * Replaces the old EnvSecretProvider (.env-based) with a JSON secret store.
+ *
+ * Storage locations:
+ *   - Global default:  ~/.weavetab/secrets.json
+ *
+ * File format:
+ *   {
+ *     "version": 1,
+ *     "secrets": {
+ *       "MY_KEY": {
+ *         "value": "s3cr3t",
+ *         "domains": ["github.com", "gitlab.com"],
+ *         "createdAt": "2024-01-01T00:00:00Z",
+ *         "updatedAt": "2024-01-01T00:00:00Z"
+ *       }
+ *     }
+ *   }
+ *
+ * Security guarantees:
+ *   - File created with mode 0o600 (owner-read/write only).
+ *   - On POSIX: startup hard-fails if file exists with wrong permissions.
+ *   - On Windows: warning only (NTFS ACLs, not POSIX mode bits).
+ *   - Resolved value lives in-process only; never returned in any tool_result.
+ *   - `domains: []` means "any domain" — not recommended for sensitive credentials.
+ *
+ * Weavetab by fy2ne
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+// Encryption key derivation for secrets at rest
+const ENCRYPTION_KEY_FILE = path.join(os.homedir(), ".weavetab-system", "secrets-key");
+let encryptionKey = null;
+function getEncryptionKey() {
+    if (encryptionKey)
+        return encryptionKey;
+    try {
+        if (fs.existsSync(ENCRYPTION_KEY_FILE)) {
+            const keyData = fs.readFileSync(ENCRYPTION_KEY_FILE, "utf-8").trim();
+            encryptionKey = Buffer.from(keyData, "hex");
+        }
+        else {
+            // Generate a new encryption key
+            encryptionKey = crypto.randomBytes(32); // 256-bit key
+            const dir = path.dirname(ENCRYPTION_KEY_FILE);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(ENCRYPTION_KEY_FILE, encryptionKey.toString("hex"), { mode: 0o600 });
+        }
+    }
+    catch {
+        // Fallback to a derived key if file operations fail
+        const machineId = os.hostname() + os.platform() + os.arch();
+        encryptionKey = crypto.createHash("sha256").update(machineId).digest();
+    }
+    return encryptionKey;
+}
+function encrypt(plaintext) {
+    const key = getEncryptionKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    let encrypted = cipher.update(plaintext, "utf8", "hex");
+    encrypted += cipher.final("hex");
+    const authTag = cipher.getAuthTag();
+    // Combine IV + authTag + encrypted data
+    return iv.toString("hex") + authTag.toString("hex") + encrypted;
+}
+function decrypt(ciphertext) {
+    const key = getEncryptionKey();
+    // Extract IV (first 32 hex chars = 16 bytes)
+    const iv = Buffer.from(ciphertext.slice(0, 32), "hex");
+    // Extract authTag (next 32 hex chars = 16 bytes)
+    const authTag = Buffer.from(ciphertext.slice(32, 64), "hex");
+    // Extract encrypted data
+    const encrypted = ciphertext.slice(64);
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encrypted, "hex", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+}
+import { GLOBAL_CONFIG_DIR } from "../config/loader.js";
+// ─── Path resolution ──────────────────────────────────────────────────────────
+export const GLOBAL_SECRETS_PATH = path.join(GLOBAL_CONFIG_DIR, "secrets.json");
+function resolveSecretsPath() {
+    return GLOBAL_SECRETS_PATH;
+}
+// ─── Permission guard ─────────────────────────────────────────────────────────
+const IS_WINDOWS = os.platform() === "win32";
+const REQUIRED_MODE = 0o600;
+/**
+ * Enforce chmod 600 on the secrets file.
+ * Hard-fails on POSIX if the file is accessible by anyone other than the owner.
+ * Warns on Windows (NTFS doesn't map cleanly to POSIX mode bits).
+ */
+function enforceFilePermissions(filePath) {
+    if (!fs.existsSync(filePath))
+        return;
+    if (IS_WINDOWS) {
+        try {
+            const { execFileSync } = require('child_process');
+            const username = process.env.USERNAME || '';
+            // Validate username against a strict allowlist pattern, then pass filePath
+            // and the grant argument as separate argv tokens to execFile (no shell
+            // involved) so the username can never be injected into a command string.
+            if (!/^[a-zA-Z0-9._-]+$/.test(username)) {
+                process.stderr.write(`[Weavetab Secrets] ⚠ Refusing to set ACLs: USERNAME contains unsafe characters.\n`);
+                return;
+            }
+            // Pass each argument as a separate element — no shell, no injection possible
+            execFileSync('icacls', [filePath, '/inheritance:r', '/grant:r', `${username}:F`], { stdio: 'ignore' });
+        }
+        catch (e) {
+            process.stderr.write(`[Weavetab Secrets] ⚠ Failed to enforce Windows ACLs on "${filePath}".\n`);
+        }
+        return;
+    }
+    try {
+        const stats = fs.statSync(filePath);
+        const mode = stats.mode & 0o777;
+        if (mode !== REQUIRED_MODE) {
+            throw new Error(`[Weavetab Secrets] ✗ SECURITY ERROR: Secrets file "${filePath}" has unsafe permissions ` +
+                `(${mode.toString(8)}, expected 600). ` +
+                `Fix with: chmod 600 "${filePath}"`);
+        }
+    }
+    catch (e) {
+        if (e.message.includes("SECURITY ERROR"))
+            throw e;
+        // stat failed for some other reason — skip
+    }
+}
+function applyFilePermissions(filePath) {
+    if (IS_WINDOWS) {
+        enforceFilePermissions(filePath);
+        return;
+    }
+    try {
+        fs.chmodSync(filePath, REQUIRED_MODE);
+    }
+    catch { /* ignore — might be on a FS that doesn't support chmod */ }
+}
+// ─── File I/O ─────────────────────────────────────────────────────────────────
+function readSecretsFile(filePath) {
+    enforceFilePermissions(filePath);
+    if (!fs.existsSync(filePath)) {
+        return { version: 1, secrets: {} };
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8").trim();
+        if (!raw)
+            return { version: 1, secrets: {} };
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed.version !== 1 || typeof parsed.secrets !== "object") {
+            throw new Error("Malformed secrets file");
+        }
+        // Decrypt secret values after reading
+        for (const key in parsed.secrets) {
+            if (parsed.secrets[key].value) {
+                try {
+                    parsed.secrets[key].value = decrypt(parsed.secrets[key].value);
+                }
+                catch {
+                    // If decryption fails, assume it's not encrypted (legacy data)
+                    // and leave it as-is
+                }
+            }
+        }
+        return parsed;
+    }
+    catch (e) {
+        throw new Error(`[Weavetab Secrets] ✗ Failed to read secrets file "${filePath}": ${e.message}`);
+    }
+}
+function writeSecretsFile(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Encrypt secret values before writing
+    const encryptedData = {
+        version: data.version,
+        secrets: {}
+    };
+    for (const key in data.secrets) {
+        encryptedData.secrets[key] = {
+            ...data.secrets[key],
+            value: encrypt(data.secrets[key].value)
+        };
+    }
+    const tmp = filePath + `.tmp.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(encryptedData, null, 2), { encoding: "utf-8", mode: REQUIRED_MODE });
+        applyFilePermissions(tmp);
+        fs.renameSync(tmp, filePath);
+        applyFilePermissions(filePath);
+    }
+    catch (e) {
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw e;
+    }
+}
+// ─── JsonSecretStore ──────────────────────────────────────────────────────────
+class JsonSecretStoreImpl {
+    /**
+     * Resolve a secret value by key.
+     * Returns undefined if the key doesn't exist.
+     * Does NOT check domain — use checkDomain() for that before calling this.
+     */
+    async getSecret(key) {
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        const entry = data.secrets[key];
+        return entry?.value;
+    }
+    /**
+     * Check whether the given hostname is allowed for this key.
+     * Returns true if:
+     *   - The key doesn't exist (will fail at getSecret time anyway)
+     *   - The key's domains list is empty (wildcard — any domain)
+     *   - The hostname matches one of the allowed domains (exact or suffix match)
+     */
+    checkDomain(key, hostname) {
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        const entry = data.secrets[key];
+        if (!entry)
+            return false; // key not found
+        if (entry.domains.length === 0)
+            return true; // wildcard
+        const h = hostname.toLowerCase();
+        return entry.domains.some(d => {
+            const allowed = d.toLowerCase();
+            return h === allowed || h.endsWith("." + allowed);
+        });
+    }
+    /**
+     * Get the allowed domains list for a key (for error messages).
+     * Never returns the value.
+     */
+    getDomains(key) {
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        const entry = data.secrets[key];
+        return entry ? entry.domains : null;
+    }
+    /**
+     * Store a secret. Value must be passed in-process — never as a CLI arg.
+     * domains: list of allowed hostnames. Empty = any domain (not recommended).
+     */
+    async setSecret(key, value, domains) {
+        if (!key || !key.trim())
+            throw new Error("Secret key cannot be empty");
+        if (!value)
+            throw new Error("Secret value cannot be empty");
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        const now = new Date().toISOString();
+        const existing = data.secrets[key];
+        data.secrets[key] = {
+            value,
+            domains: domains.map(d => d.toLowerCase().trim()).filter(Boolean),
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        };
+        writeSecretsFile(filePath, data);
+    }
+    /**
+     * List all secrets — returns key names, domains, and timestamps ONLY.
+     * Never returns values.
+     */
+    async listSecrets() {
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        return Object.entries(data.secrets).map(([key, entry]) => ({
+            key,
+            domains: entry.domains,
+            updatedAt: entry.updatedAt,
+        }));
+    }
+    /**
+     * Remove a secret by key. Returns true if the key existed and was removed.
+     */
+    async removeSecret(key) {
+        const filePath = resolveSecretsPath();
+        const data = readSecretsFile(filePath);
+        if (!data.secrets[key])
+            return false;
+        delete data.secrets[key];
+        writeSecretsFile(filePath, data);
+        return true;
+    }
+    /** Returns the active secrets file path for display purposes. */
+    getSecretsFilePath() {
+        return resolveSecretsPath();
+    }
+}
+export const secretStore = new JsonSecretStoreImpl();
+// ─── Legacy shim — kept so other callers don't break ─────────────────────────
+// @deprecated — use secretStore directly
+/** @deprecated Use secretStore instead. */
+export class EnvSecretProvider {
+    async getSecret(key) {
+        process.stderr.write(`[Weavetab Secrets] ⚠ EnvSecretProvider is deprecated. Falling back to JsonSecretStore.\n`);
+        return secretStore.getSecret(key);
+    }
+}
+// ─── SessionSecretTracker ─────────────────────────────────────────────────────
+// Tracks which DOM backendNodeIds contain secrets so cross-tool redaction
+// (walker, AX tree, delta) can redact them at read time without re-querying
+// the secret store.
+class SessionSecretTrackerImpl {
+    /** Maps sessionId (CDP targetId) → Set of backendNodeIds marked as secret. */
+    trackedNodes = new Map();
+    /** Maps sessionId (CDP targetId) → Set of plaintext secret strings injected. */
+    sessionSecrets = new Map();
+    markNodeAsSecret(sessionId, backendNodeId) {
+        let set = this.trackedNodes.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.trackedNodes.set(sessionId, set);
+        }
+        set.add(backendNodeId);
+    }
+    isNodeSecret(sessionId, backendNodeId) {
+        const set = this.trackedNodes.get(sessionId);
+        return set ? set.has(backendNodeId) : false;
+    }
+    registerSecretValue(sessionId, value) {
+        if (!value || value.length < 3)
+            return; // Don't redact tiny strings
+        let set = this.sessionSecrets.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.sessionSecrets.set(sessionId, set);
+        }
+        set.add(value);
+    }
+    redact(sessionId, text) {
+        if (!text || typeof text !== 'string')
+            return text;
+        const set = this.sessionSecrets.get(sessionId);
+        if (!set || set.size === 0)
+            return text;
+        let redacted = text;
+        for (const secret of set) {
+            // Fast path string replace all instances
+            redacted = redacted.split(secret).join('[REDACTED]');
+        }
+        return redacted;
+    }
+    clearSession(sessionId) {
+        this.trackedNodes.delete(sessionId);
+        this.sessionSecrets.delete(sessionId);
+    }
+}
+export const SessionSecretTracker = new SessionSecretTrackerImpl();

package/dist/sensors/actionability.d.ts

@@ -0,0 +1,81 @@
+/**
+ * src/sensors/actionability.ts
+ *
+ * Playwright-Strategy Actionability Engine for WeaveTab
+ * ─────────────────────────────────────────────────────
+ * Implements every correctness principle from playwright-strategy.md:
+ *
+ *  1. RAF-stability gate     — element must not be animating before we touch it
+ *  2. Strict hit-target      — elementsFromPoint at the computed click point must
+ *                              confirm the target is on top (or the target's child).
+ *  3. WeaveTab transparency  — WeaveTab's own UI (data-wt-ignore nodes) is excluded
+ *                              from the hit stack so the tool never blocks itself.
+ *  4. 4-way scroll rotation  — escape sticky headers / overlays by cycling four
+ *                              scrollIntoView alignments before giving up.
+ *  5. Per-action backoff     — [0, 20, 100, 100, 500] ms retry on transient failures.
+ *  6. Rich blocker report    — on permanent occlusion, return the blocking element's
+ *                              description so the model can reason about it.
+ *
+ * Usage:
+ *   import { verifyActionability } from "../sensors/actionability.js";
+ *   const result = await verifyActionability(session, selector);
+ *   if (result.status !== "ACTIONABLE") { ... }
+ */
+import CDP from "chrome-remote-interface";
+export type ActionabilityStatus = "ACTIONABLE" | "NOT_FOUND" | "INVISIBLE" | "UNSTABLE" | "OCCLUDED" | "FINGERPRINT_MISMATCH";
+export interface OccluderInfo {
+    tag: string;
+    id: string;
+    className: string;
+    ariaLabel: string | null;
+    isWeavetabOwned: boolean;
+}
+export interface ActionabilityResult {
+    status: ActionabilityStatus;
+    /** Computed click center in viewport coordinates. */
+    x?: number;
+    y?: number;
+    /** Populated only when status === "OCCLUDED". */
+    occludedBy?: OccluderInfo;
+    /** True if the blocker was WeaveTab's own UI and can be ignored. */
+    blockerIsWeaveTab?: boolean;
+}
+export interface ActionabilityOptions {
+    /**
+     * Maximum time (ms) to wait for stability before giving up.
+     * Default: 600ms.
+     */
+    stabilityTimeoutMs?: number;
+    /**
+     * Optional fingerprint to verify the element hasn't been replaced by
+     * a framework re-render. Checked once before anything else.
+     */
+    fingerprint?: {
+        tag?: string;
+        role?: string;
+    };
+    /**
+     * Total time budget across all retry attempts.
+     * Default: 2000ms.
+     */
+    totalTimeoutMs?: number;
+}
+/**
+ * Full Playwright-strategy actionability verification.
+ *
+ * Runs up to `BACKOFF.length` attempts with 4-way scroll rotation,
+ * RAF stability gating, WeaveTab-transparent hit-target checking,
+ * and per-attempt retry backoff.
+ *
+ * Returns `status: "ACTIONABLE"` with computed (x, y) when safe to dispatch,
+ * or a failure status with an optional `occludedBy` description.
+ */
+export declare function verifyActionability(session: CDP.Client, selector: string, opts?: ActionabilityOptions): Promise<ActionabilityResult>;
+/**
+ * Quick check: is an element at these coords actually blocked by a non-WT overlay?
+ * Used for lightweight pre-dispatch validation inside click.ts.
+ */
+export declare function quickHitCheck(session: CDP.Client, x: number, y: number, selectorOfTarget: string): Promise<{
+    clear: boolean;
+    blockerDescription?: string;
+}>;