@jshookmcp/jshook 0.2.5 → 0.2.6

package/workflows/auth-surface-mapper/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/auth-surface-mapper/workflow.ts

@@ -0,0 +1,104 @@
+import {
+  createWorkflow,
+  type WorkflowExecutionContext,
+  SequenceNodeBuilder,
+} from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.auth-surface-mapper.v1';
+
+export default createWorkflow(workflowId, 'Auth Surface Mapper')
+  .description(
+    'Enumerates all authentication surfaces on a page: cookies, localStorage tokens, sessionStorage, authorization headers, JWT payloads, CSRF tokens, OAuth parameters, and API keys — producing a unified auth surface report with confidence scores.',
+  )
+  .tags(['reverse', 'auth', 'token', 'cookie', 'credential', 'jwt', 'csrf', 'mission'])
+  .timeoutMs(6 * 60_000)
+  .defaultMaxConcurrency(5)
+  .buildGraph((ctx: WorkflowExecutionContext) => {
+    const prefix = 'workflows.authSurfaceMapper';
+    const url = String(ctx.getConfig(`${prefix}.url`, 'https://example.com'));
+    const waitUntil = String(ctx.getConfig(`${prefix}.waitUntil`, 'networkidle0'));
+    const requestTail = Number(ctx.getConfig(`${prefix}.requestTail`, 50));
+    const minConfidence = Number(ctx.getConfig(`${prefix}.minConfidence`, 0.2));
+    const maxConcurrency = Number(ctx.getConfig(`${prefix}.parallel.maxConcurrency`, 5));
+    const triggerActions = Boolean(ctx.getConfig(`${prefix}.triggerActions`, false));
+
+    const root = new SequenceNodeBuilder('auth-surface-mapper-root');
+
+    // Phase 1: Network & Navigation
+    root
+      .tool('enable-network', 'network_enable', { input: { enableExceptions: true } })
+      .tool('navigate', 'page_navigate', { input: { url, waitUntil } })
+
+      // Phase 2: Parallel Surface Collection
+      .parallel('collect-auth-surfaces', (p: any) => {
+        p.maxConcurrency(maxConcurrency)
+          .failFast(false)
+          .tool('get-cookies', 'page_get_cookies')
+          .tool('get-local-storage', 'page_get_local_storage')
+          .tool('get-requests', 'network_get_requests', { input: { tail: requestTail } })
+          .tool('extract-auth', 'network_extract_auth', { input: { minConfidence } })
+          .tool('search-auth-patterns', 'search_in_scripts', {
+            input: { query: 'authorization,bearer,jwt,token,csrf,x-csrf,api-key,apikey,secret', matchType: 'any' },
+          })
+          .tool('detect-crypto', 'detect_crypto', { input: {} });
+      })
+
+      // Phase 3: Token Deep Analysis
+      .tool('evaluate-auth-state', 'page_evaluate', {
+        input: {
+          expression: `(function() {
+            const result = {};
+            try { result.localStorage = Object.keys(localStorage).filter(k => /token|auth|jwt|session|csrf|key|secret/i.test(k)); } catch(e) {}
+            try { result.sessionStorage = Object.keys(sessionStorage).filter(k => /token|auth|jwt|session|csrf|key|secret/i.test(k)); } catch(e) {}
+            result.metaTags = [...document.querySelectorAll('meta[name*=csrf], meta[name*=token], meta[name*=auth]')].map(m => ({name:m.name,content:m.content?.slice(0,50)}));
+            result.hiddenInputs = [...document.querySelectorAll('input[type=hidden]')].filter(i => /token|csrf|auth|nonce/i.test(i.name)).map(i => ({name:i.name,value:i.value?.slice(0,50)}));
+            return result;
+          })()`,
+        },
+      });
+
+    // Phase 4: Optional Login Trigger
+    if (triggerActions) {
+      root
+        .tool('find-login-buttons', 'dom_find_clickable', { input: {} })
+        .tool('get-forms', 'dom_query_all', { input: { selector: 'form[action]' } });
+    }
+
+    // Phase 5: Evidence Recording
+    root
+      .tool('create-evidence-session', 'instrumentation_session_create', {
+        input: {
+          name: `auth-surface-${new Date().toISOString().slice(0, 10)}`,
+          metadata: { url, workflowId },
+        },
+      })
+      .tool('record-summary', 'console_execute', {
+        input: {
+          expression: `(${JSON.stringify({ status: 'auth_surface_recorded', url, minConfidence })})`,
+        },
+      })
+
+      // Phase 6: Session Insight
+      .tool('emit-insight', 'append_session_insight', {
+        input: {
+          insight: JSON.stringify({
+            status: 'auth_surface_mapper_complete',
+            workflowId,
+            url,
+            minConfidence,
+          }),
+        },
+      });
+
+    return root;
+  })
+  .onStart((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId, mission: 'auth_surface_mapper', stage: 'start' });
+  })
+  .onFinish((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId, mission: 'auth_surface_mapper', stage: 'finish' });
+  })
+  .onError((ctx, error) => {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', { workflowId, mission: 'auth_surface_mapper', stage: 'error', error: error.name });
+  })
+  .build();

package/workflows/batch-register/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "batch-register",
+  "id": "workflow.batch-register.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_batch_register",
+    "ref": "main",
+    "commit": "6d57ba1",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/batch-register/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vmoranv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/workflows/batch-register/README.md

@@ -0,0 +1,39 @@
+# batch-register workflow
+
+Declarative example workflow for batch account registration.
+
+## Entry File
+
+- `workflow.ts`
+
+## Workflow ID
+
+- `workflow.batch-register.v1`
+
+## Structure
+
+This workflow demonstrates all core node types:
+
+- `ToolNode`: precheck and summary steps
+- `ParallelNode`: concurrent account registration
+- `BranchNode`: success-rate-based branching
+- `SequenceNode`: end-to-end orchestration
+
+## Tools Used
+
+- `web_api_capture_session` (precheck)
+- `register_account_flow` (parallel tasks)
+- `console_execute` (summary output)
+
+## Config
+
+- `workflows.batchRegister.maxConcurrency` (default: `3`)
+
+## Local Validation
+
+1. Load extension roots in `jshookmcp`.
+2. Run `extensions_reload`.
+3. Confirm workflow is listed in `extensions_list`.
+4. Trigger the workflow via your workflow runner and verify:
+   - parallel execution occurs
+   - summary branch step emits result

package/workflows/batch-register/meta.yaml

@@ -0,0 +1,4 @@
+name: batch-register
+description: Declarative workflow for parallel account registration with retry and branch summary.
+author: vmoranv
+source_repo: https://github.com/vmoranv/jshook_workflow_batch_register

package/workflows/batch-register/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jshookmcpextension/workflow-batch-register",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+"@jshookmcp/extension-sdk": "^0.3.0"
+  },
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "private": true,
+  "packageManager": "pnpm@10.28.2"
+}

package/workflows/batch-register/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["workflow.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/workflows/batch-register/workflow.ts

@@ -0,0 +1,67 @@
+/**
+ * Example workflow: Batch Account Registration.
+ * Demonstrates SequenceNode, ToolNode, ParallelNode, and BranchNode.
+ * Declarative — executed by a WorkflowEngine.
+ */
+import type { WorkflowContract } from '@jshookmcp/extension-sdk/workflow';
+import { toolNode, sequenceNode, parallelNode, branchNode } from '@jshookmcp/extension-sdk/workflow';
+
+const batchRegisterWorkflow: WorkflowContract = {
+  kind: 'workflow-contract',
+  version: 1,
+  id: 'workflow.batch-register.v1',
+  displayName: 'Batch Register Accounts',
+  description:
+    'Run register_account_flow for multiple accounts with concurrency controls, ' +
+    'retry policies, and success rate gating.',
+  tags: ['workflow', 'registration', 'batch', 'automation'],
+  timeoutMs: 15 * 60_000,
+  defaultMaxConcurrency: 3,
+
+  build(ctx) {
+    const maxConcurrency = ctx.getConfig<number>('workflows.batchRegister.maxConcurrency', 3);
+
+    return sequenceNode('batch-register-root')
+      .step(toolNode('precheck', 'web_api_capture_session').input({
+        url: 'about:blank', exportHar: false, exportReport: false,
+      }))
+      .step(parallelNode('register-parallel')
+        .maxConcurrency(maxConcurrency)
+        .failFast(false)
+        .step(toolNode('register-account-1', 'register_account_flow')
+          .input({
+            registerUrl: 'https://example.com/register',
+            fields: { username: 'user1', email: 'user1@temp.mail', password: '{{PLACEHOLDER}}' },
+          })
+          .retry({ maxAttempts: 2, backoffMs: 1000, multiplier: 2 }))
+        .step(toolNode('register-account-2', 'register_account_flow')
+          .input({
+            registerUrl: 'https://example.com/register',
+            fields: { username: 'user2', email: 'user2@temp.mail', password: '{{PLACEHOLDER}}' },
+          })
+          .retry({ maxAttempts: 2, backoffMs: 1000, multiplier: 2 })))
+      .step(branchNode('summary-branch', 'batch_success_rate_gte_80')
+        .predicateFn(() => true)
+        .whenTrue(toolNode('success-summary', 'console_execute').input({
+          expression: '({ status: "batch_complete", successRate: ">=80%" })',
+        }))
+        .whenFalse(toolNode('failure-summary', 'console_execute').input({
+          expression: '({ status: "needs_retry", successRate: "<80%", suggestion: "Check captcha provider or increase timeout" })',
+        })))
+      .build();
+  },
+
+  onStart(ctx) {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId: 'workflow.batch-register.v1', stage: 'start' });
+  },
+
+  onFinish(ctx) {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId: 'workflow.batch-register.v1', stage: 'finish' });
+  },
+
+  onError(ctx, error) {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', { workflowId: 'workflow.batch-register.v1', error: error.name });
+  },
+};
+
+export default batchRegisterWorkflow;

package/workflows/bundle-recovery/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "bundle-recovery",
+  "id": "workflow.bundle-recovery.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_bundle_recovery",
+    "ref": "main",
+    "commit": "0dd0e8d12c89c5deb8bacd8c158a3daaeeda3023",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/bundle-recovery/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vmoranv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/workflows/bundle-recovery/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/bundle-recovery/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/bundle-recovery/meta.yaml

@@ -0,0 +1,6 @@
+name: bundle-recovery
+description: JSHook workflow for bundle-recovery
+author: vmoranv
+tags:
+  - workflow
+  - bundle-recovery

package/workflows/bundle-recovery/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/bundle-recovery/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"]
+}