@jshookmcp/jshook 0.2.3 → 0.2.6

package/workflows/anti-bot-diagnoser/README.md

@@ -0,0 +1,105 @@
+# jshook_workflow_template
+
+TypeScript-first template repository for building a reusable `jshook` workflow.
+
+This template focuses on one thing:
+
+- codify an existing built-in tool chain into a reusable workflow contract
+- keep TypeScript source in Git and generated JavaScript out of Git
+
+## Included in the template
+
+- `workflow.ts`: workflow source entrypoint
+- `docs/agent-recipes.md`: recipes for orchestration, parallel reads, and subagent-assisted analysis
+- `dist/workflow.js`: generated locally by `pnpm run build` and ignored by Git
+
+## What the MVP workflow demonstrates
+
+The sample workflow runs this shape:
+
+1. `network_enable`
+2. `page_navigate`
+3. parallel surface collection
+   - `page_get_local_storage`
+   - `page_get_cookies`
+   - `network_get_requests`
+   - `page_get_all_links`
+   - optional `console_get_logs`
+4. `network_extract_auth`
+5. `console_execute` summary output
+
+## Dependency model
+
+This template uses the published npm package:
+
+```json
+{
+  "@jshookmcp/extension-sdk": "^0.1.3"
+}
+```
+
+## Install and build
+
+```bash
+pnpm install
+pnpm run build
+pnpm run check
+```
+
+## Loading behavior
+
+`jshook` discovers both `workflow.ts` and `dist/workflow.js`, but when both exist it prefers the generated JavaScript entry.
+
+Recommended workflow:
+
+1. edit `workflow.ts`
+2. run `pnpm run build`
+3. let `jshook` load `dist/workflow.js`
+
+Do **not** commit `dist/`.
+
+## Load the workflow into jshook
+
+Set:
+
+```bash
+MCP_WORKFLOW_ROOTS=<path-to-cloned-jshook_workflow_template>
+```
+
+Then run inside `jshook`:
+
+1. `extensions_reload`
+2. `extensions_list`
+3. `list_extension_workflows`
+4. `run_extension_workflow`
+
+## Configuration prefix
+
+The template uses:
+
+```text
+workflows.templateCapture.*
+```
+
+Rename that prefix early when adapting the template for real use.
+
+## Git hygiene
+
+Keep this repo focused on source and docs.
+Do not commit:
+
+- `dist/`
+- `node_modules/`
+- `.env`
+- runtime artifacts
+- screenshots
+- local sessions
+- host-specific temp output
+
+## What to change first
+
+1. replace `workflowId` and `displayName`
+2. rename the config prefix
+3. keep state-mutating steps serialized
+4. keep read-only collection steps parallel where safe
+5. validate the workflow through `extensions_reload` and `list_extension_workflows`

package/workflows/anti-bot-diagnoser/docs/agent-recipes.md

@@ -0,0 +1,44 @@
+# Agent Recipes for `jshook_workflow_template`
+
+## Core rule
+
+- parallelize reads, not shared page state mutations
+- let the main agent keep the active browser session
+- use subagents for sidecar analysis and report drafting
+
+## Recipe 1: run workflow, then delegate analysis
+
+Recommended split:
+
+- main agent
+  - `run_extension_workflow`
+  - optional `network_get_response_body`
+- subagent
+  - classify endpoints
+  - summarize auth and session artifacts
+  - draft report output
+
+## Recipe 2: main agent navigates, subagent reviews outputs
+
+Recommended split:
+
+- main agent
+  - `page_navigate`
+  - page actions
+  - `network_get_requests`
+- subagent
+  - endpoint matrix
+  - auth header and signature review
+  - next-step probing suggestions
+
+## Recipe 3: when to use parallel tool calls
+
+Good read-only candidates:
+
+- `extensions_list`
+- `search_tools`
+- `page_get_local_storage`
+- `page_get_cookies`
+- `console_get_logs`
+
+Avoid parallelizing any action that changes the current page state.

package/workflows/anti-bot-diagnoser/meta.yaml

@@ -0,0 +1,6 @@
+name: anti-bot-diagnoser
+description: JSHook workflow for anti-bot-diagnoser
+author: vmoranv
+tags:
+  - workflow
+  - anti-bot-diagnoser

package/workflows/anti-bot-diagnoser/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "jshook-workflow-template",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Standalone template repository for building jshook workflows.",
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@jshookmcp/extension-sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/workflows/anti-bot-diagnoser/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["workflow.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/workflows/anti-bot-diagnoser/workflow.ts

@@ -0,0 +1,224 @@
+import {
+  createWorkflow,
+  type WorkflowExecutionContext,
+  SequenceNodeBuilder,
+} from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.anti-bot-diagnoser.v1';
+
+/**
+ * Anti-Bot Diagnoser — Reverse Mission Workflow
+ *
+ * Differential analysis to detect bot-detection mechanisms:
+ *   1. Creates a baseline fingerprint (normal browser context)
+ *   2. Creates a stealth fingerprint (stealth executor)
+ *   3. Compares both against known detection probes
+ *   4. Identifies specific detection points (webdriver, CDP, timing, canvas, etc.)
+ *   5. Produces a detection map and remediation hints
+ *   6. Records evidence for the diagnostic session
+ */
+export default createWorkflow(workflowId, 'Anti-Bot Diagnoser')
+  .description(
+    'Compares normal vs stealth browser fingerprints, identifies bot-detection triggers (webdriver, CDP, canvas, WebRTC, timing), and produces a detection report with remediation hints.',
+  )
+  .tags([
+    'reverse',
+    'antibot',
+    'stealth',
+    'fingerprint',
+    'detection',
+    'webdriver',
+    'mission',
+  ])
+  .timeoutMs(12 * 60_000)
+  .defaultMaxConcurrency(2)
+  .buildGraph((ctx: WorkflowExecutionContext) => {
+    const prefix = 'workflows.antiBotDiagnoser';
+
+    // ── Config ──────────────────────────────────────────────────────
+    const url = String(ctx.getConfig(`${prefix}.url`, 'https://example.com'));
+    const waitUntil = String(ctx.getConfig(`${prefix}.waitUntil`, 'networkidle0'));
+    const probeCategories = String(
+      ctx.getConfig(
+        `${prefix}.probeCategories`,
+        'webdriver,navigator,timing,canvas,webgl,webrtc,audio,fonts,plugins,permissions',
+      ),
+    );
+    const maxConcurrency = Number(ctx.getConfig(`${prefix}.parallel.maxConcurrency`, 2));
+    const stealthMode = String(ctx.getConfig(`${prefix}.stealthMode`, 'patchright'));
+
+    const root = new SequenceNodeBuilder('anti-bot-diagnoser-root');
+
+    root
+      // ── Phase 1: Enable Network & Navigate ────────────────────────
+      .tool('enable-network', 'network_enable', {
+        input: { enableExceptions: true },
+      })
+      .tool('navigate', 'page_navigate', {
+        input: { url, waitUntil },
+      })
+
+      // ── Phase 2: Baseline Fingerprint (Normal) ────────────────────
+      .tool('fingerprint-baseline', 'page_evaluate', {
+        input: {
+          expression: `
+            (function() {
+              const probes = {};
+              // webdriver
+              probes.webdriver = navigator.webdriver;
+              probes.webdriverDefined = 'webdriver' in navigator;
+              // navigator properties
+              probes.userAgent = navigator.userAgent;
+              probes.platform = navigator.platform;
+              probes.languages = navigator.languages;
+              probes.hardwareConcurrency = navigator.hardwareConcurrency;
+              probes.deviceMemory = navigator.deviceMemory;
+              // timing
+              probes.timingResolution = (() => {
+                const t0 = performance.now();
+                for (let i = 0; i < 1000; i++) performance.now();
+                return performance.now() - t0;
+              })();
+              // canvas
+              probes.canvasFingerprint = (() => {
+                const c = document.createElement('canvas');
+                c.width = 200; c.height = 50;
+                const ctx = c.getContext('2d');
+                if (!ctx) return null;
+                ctx.textBaseline = 'top';
+                ctx.font = '14px Arial';
+                ctx.fillText('probe', 2, 2);
+                return c.toDataURL().slice(0, 100);
+              })();
+              // chrome
+              probes.chromeRuntime = typeof chrome !== 'undefined' && !!chrome.runtime;
+              // permissions
+              probes.permissionsQuery = typeof navigator.permissions !== 'undefined';
+              // plugins
+              probes.pluginCount = navigator.plugins ? navigator.plugins.length : -1;
+              return probes;
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 3: Parallel Detection Checks ────────────────────────
+      .parallel('detection-checks', (p) => {
+        p.maxConcurrency(maxConcurrency)
+          .failFast(false)
+          // Check CDP leak
+          .tool('check-cdp-leak', 'stealth_check_cdp_leak', {
+            input: {},
+          })
+          // Check webdriver property
+          .tool('check-webdriver', 'stealth_check_webdriver', {
+            input: {},
+          })
+          // Check automation flags
+          .tool('check-automation-flags', 'stealth_check_automation', {
+            input: {},
+          })
+          // Run all stealth probes
+          .tool('run-stealth-probes', 'stealth_run_probes', {
+            input: { categories: probeCategories },
+          });
+      })
+
+      // ── Phase 4: Stealth Mode Fingerprint ─────────────────────────
+      .tool('switch-stealth', 'browser_set_stealth_mode', {
+        input: { mode: stealthMode },
+      })
+      .tool('navigate-stealth', 'page_navigate', {
+        input: { url, waitUntil },
+      })
+      .tool('fingerprint-stealth', 'page_evaluate', {
+        input: {
+          expression: `
+            (function() {
+              const probes = {};
+              probes.webdriver = navigator.webdriver;
+              probes.webdriverDefined = 'webdriver' in navigator;
+              probes.userAgent = navigator.userAgent;
+              probes.platform = navigator.platform;
+              probes.chromeRuntime = typeof chrome !== 'undefined' && !!chrome.runtime;
+              probes.pluginCount = navigator.plugins ? navigator.plugins.length : -1;
+              return probes;
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 5: Differential Analysis ────────────────────────────
+      .tool('compute-diff', 'console_execute', {
+        input: {
+          expression: `
+            (function() {
+              return {
+                analysis: 'differential_fingerprint_complete',
+                hint: 'Compare baseline vs stealth results in evidence graph',
+              };
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 6: Detection Report ─────────────────────────────────
+      .tool('generate-report', 'stealth_generate_report', {
+        input: {
+          includeRemediation: true,
+        },
+      })
+
+      // ── Phase 7: Evidence Recording ───────────────────────────────
+      .tool('create-evidence-session', 'instrumentation_session_create', {
+        input: {
+          name: `antibot-diagnosis-${new Date().toISOString().slice(0, 10)}`,
+          metadata: { url, workflowId, stealthMode },
+        },
+      })
+      .tool('record-artifact', 'instrumentation_artifact_record', {
+        input: {
+          type: 'antibot_report',
+          label: `Anti-bot diagnosis for ${url}`,
+          metadata: { url, probeCategories, stealthMode },
+        },
+      })
+
+      // ── Phase 8: Session Insight ──────────────────────────────────
+      .tool('emit-insight', 'append_session_insight', {
+        input: {
+          insight: JSON.stringify({
+            status: 'anti_bot_diagnoser_complete',
+            workflowId,
+            url,
+            probeCategories,
+            stealthMode,
+          }),
+        },
+      });
+
+    return root;
+  })
+  .onStart((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'start',
+    });
+  })
+  .onFinish((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'finish',
+    });
+  })
+  .onError((ctx, error) => {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'error',
+      error: error.name,
+    });
+  })
+  .build();

package/workflows/api-openapi-probe/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "api-openapi-probe",
+  "id": "workflow.api-openapi-probe.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_api_openapi_probe",
+    "ref": "main",
+    "commit": "94e1573fef500945d2da18f1cadda68b9187f22f",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/api-openapi-probe/meta.yaml

@@ -0,0 +1,6 @@
+name: api-openapi-probe
+description: JSHook workflow for api-openapi-probe
+author: vmoranv
+tags:
+  - workflow
+  - api-openapi-probe

package/workflows/api-openapi-probe/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "jshook-workflow-api-openapi-probe",
+  "private": true,
+  "version": "0.1.0",
+  "description": "jshookmcp workflow: api-openapi-probe",
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@jshookmcp/extension-sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}