multicorn-shield 1.9.5 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +87 -523
  3. package/dist/index.cjs +31 -20
  4. package/dist/index.d.cts +14 -6
  5. package/dist/index.d.ts +14 -6
  6. package/dist/index.js +12 -1
  7. package/dist/multicorn-proxy.js +1600 -160
  8. package/dist/multicorn-shield.js +1590 -163
  9. package/dist/proxy.cjs +2 -0
  10. package/dist/proxy.d.cts +3 -0
  11. package/dist/proxy.d.ts +3 -0
  12. package/dist/proxy.js +2 -0
  13. package/dist/shield-extension.js +3 -1
  14. package/package.json +42 -22
  15. package/plugins/cline/hooks/scripts/post-tool-use.cjs +0 -0
  16. package/plugins/cline/hooks/scripts/pre-tool-use.cjs +0 -0
package/README.md CHANGED
@@ -1,158 +1,84 @@
1
- ![Multicorn Shield](https://multicorn.ai/images/og-image-shield.png)
2
-
3
1
  # Multicorn Shield
4
2
 
5
- The permissions and control layer for AI agents. Open source.
3
+ Most AI coding agents inherit direct access to MCP tools, terminals, mail, and spend with no enforced guardrails, and Shield inserts consent workflows, budgets, policy checks, and tamper-evident logging before governed calls execute.
6
4
 
7
- [![CI](https://github.com/Multicorn-AI/multicorn-shield/actions/workflows/ci.yml/badge.svg)](https://github.com/Multicorn-AI/multicorn-shield/actions/workflows/ci.yml)
8
- [![Coverage](https://img.shields.io/badge/coverage-85%25+-brightgreen.svg)](https://github.com/Multicorn-AI/multicorn-shield)
9
- [![npm version](https://img.shields.io/npm/v/multicorn-shield.svg)](https://www.npmjs.com/package/multicorn-shield)
10
- [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
- [![Bundle Size](https://img.shields.io/bundlephobia/minzip/multicorn-shield)](https://bundlephobia.com/package/multicorn-shield)
5
+ - **Permission enforcement** - Policy checks on scoped access so agents can't wander past what you granted.
6
+ - **Consent flows** - Human-in-the-loop approval when the model asks for new or risky actions.
7
+ - **Audit trails** - Structured activity logs with append-only hashing so history is harder to forge.
8
+ - **Spending controls** - Per-session and rolling limits aligned with budgets you set on the dashboard.
9
+ - **Anomaly detection** - Surfaces spikes and outliers in agent behaviour before they become incidents.
12
10
 
13
- ## Demo
11
+ [![npm version](https://img.shields.io/npm/v/multicorn-shield.svg)](https://www.npmjs.com/package/multicorn-shield)
12
+ [![MIT Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
13
+ [![CI](https://github.com/Multicorn-AI/multicorn-shield/actions/workflows/ci.yml/badge.svg)](https://github.com/Multicorn-AI/multicorn-shield/actions/workflows/ci.yml)
14
14
 
15
15
  <p align="center">
16
16
  <img src="https://multicorn.ai/images/demo.gif" alt="Multicorn Shield demo: agent blocked, user approves in dashboard, agent proceeds" width="800" />
17
17
  </p>
18
18
 
19
- ## Why?
20
-
21
- AI agents are getting access to your email, calendar, bank accounts, and code repositories. Today, most agents operate with no permission boundaries: they can read, write, and spend with no oversight. Multicorn Shield gives developers a single SDK to enforce what agents can do, track what they did, and let users stay in control.
22
-
23
- ## Quick Start
24
-
25
- ### Option 1: Wrap your existing agents (no code changes)
26
-
27
- Already using an MCP server with Claude Code, OpenClaw, or another agent? Add Shield as a proxy in front of it. No code changes required: the proxy intercepts every tool call, enforces permissions, and logs activity to your dashboard.
28
-
29
- **Step 1: Install**
30
-
31
- ```bash
32
- npm install -g multicorn-shield
33
- ```
34
-
35
- **Step 2: Set up your API key**
36
-
37
- ```bash
38
- npx multicorn-shield init
39
- ```
40
-
41
- The init wizard supports multiple agents. Run it again to add agents on different platforms (OpenClaw, Claude Code, Cursor) without losing existing config. Use `npx multicorn-shield agents` to see configured agents.
42
-
43
- **Step 3: Wrap your MCP server**
44
-
45
- ```bash
46
- npx multicorn-shield --wrap <your-mcp-server>
47
- ```
48
-
49
- For example, to wrap the MCP filesystem server:
50
-
51
- ```bash
52
- npx multicorn-shield --wrap npx @modelcontextprotocol/server-filesystem /tmp
53
- ```
54
-
55
- That's it. Every tool call now goes through Shield's permission layer, and activity appears in your [Multicorn dashboard](https://app.multicorn.ai) in real time.
56
-
57
- See the [full MCP proxy guide](https://multicorn.ai/docs/mcp-proxy) for Claude Code, OpenClaw, and generic MCP client examples.
58
-
59
- ### Claude Desktop Extension (.mcpb)
60
-
61
- Install Shield without the terminal: download the `.mcpb` bundle (or use **Install** from the Shield product page), open it in Claude Desktop, and enter your API key when prompted. The extension reads your existing MCP servers from `claude_desktop_config.json`, runs them as child processes, merges their tools, and checks every `tools/call` with the Shield API. Activity still shows up in your [Multicorn dashboard](https://app.multicorn.ai).
62
-
63
- **Disable or uninstall recovery:** On each start the extension saves a copy of your `mcpServers` block to `~/.multicorn/extension-backup.json` with restricted file permissions (owner read/write only). If you turn the extension off and need your original Claude Desktop MCP entries back, run:
64
-
65
- ```bash
66
- npx multicorn-shield restore
67
- ```
68
-
69
- Then restart Claude Desktop. That overwrites `mcpServers` in your config with the last backup.
70
-
71
- **Duplicate tool names:** If two MCP servers expose the same tool name, the first server in your config file keeps the name. The duplicate is skipped and a warning is written to the extension logs (stderr). Rename tools on the server side if you need both.
19
+ <p align="center">
20
+ <img src="https://multicorn.ai/images/screenshots/consent-screen.png" alt="Consent screen where users grant agent permissions" width="800" />
21
+ </p>
72
22
 
73
- Build the bundle locally (requires a full `pnpm build` first):
23
+ ## Supported agents
74
24
 
75
- ```bash
76
- pnpm run pack:extension
77
- ```
25
+ `npx multicorn-shield init` recognises every platform listed here (same registry as [`INIT_WIZARD_PLATFORM_REGISTRY`](https://github.com/Multicorn-AI/multicorn-shield/blob/main/src/proxy/config.ts) in source). Integration mode follows the [**Shield threat model**](https://multicorn.ai/shield/threat-model): **native plugins** inspect the whole tool surface exposed by the host; **hosted MCP proxy** governs MCP-shaped traffic routed through Shield.
78
26
 
79
- This runs `mcpb validate` and writes `dist/multicorn-shield.mcpb`.
27
+ | Agent | Mode | Setup on multicorn.ai |
28
+ | ------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
29
+ | [OpenClaw](https://openclaw.ai) | Native plugin | [Setup guide](https://multicorn.ai/docs/mcp-proxy#openclaw) |
30
+ | Claude Code | Native plugin | [Setup guide](https://multicorn.ai/docs/mcp-proxy#claude-code) |
31
+ | Windsurf | Native Cascade hooks (hosted MCP proxy optional) | [Setup guide](https://multicorn.ai/docs/mcp-proxy#quick-start) |
32
+ | Cline | Native hooks | [Setup guide](https://multicorn.ai/docs/mcp-proxy#quick-start) |
33
+ | Gemini CLI | Native hooks | [Setup guide](https://multicorn.ai/docs/mcp-proxy#quick-start) |
34
+ | OpenCode | Native plugin | [Setup guide](https://multicorn.ai/docs/mcp-proxy#quick-start) |
35
+ | Codex CLI | Native hooks | [Setup guide](https://multicorn.ai/docs/mcp-proxy#quick-start) |
36
+ | Cursor | Hosted MCP proxy | [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client) |
37
+ | Claude Desktop | Hosted MCP proxy or `.mcpb` extension | [Setup guide](https://multicorn.ai/shield) |
38
+ | GitHub Copilot | Hosted MCP proxy | [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client) |
39
+ | Kilo Code | Hosted MCP proxy | [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client) |
40
+ | Continue | Hosted MCP proxy | [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client) |
41
+ | Goose | Hosted MCP proxy | [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client) |
80
42
 
81
- ### Option 2: OpenClaw Plugin (native integration)
43
+ For any other MCP client on stdio, pick **Local MCP / Other** in the wizard or open the [Setup guide](https://multicorn.ai/docs/mcp-proxy#generic-mcp-client).
82
44
 
83
- If you're running [OpenClaw](https://openclaw.ai), Shield integrates directly as a plugin. No proxy layer, no code changes. The plugin intercepts every tool call at the infrastructure level before it executes.
45
+ ## Quick start
84
46
 
85
- **Step 1: Install and configure**
47
+ Fastest path to a governed proxy ([full walkthrough](https://multicorn.ai/docs/mcp-proxy)):
86
48
 
87
49
  ```bash
88
50
  npm install -g multicorn-shield
89
51
  npx multicorn-shield init
90
52
  ```
91
53
 
92
- Enter your API key when prompted. This saves your key to `~/.multicorn/config.json` and configures the OpenClaw hook environment.
93
-
94
- **Step 2: Build the plugin**
54
+ The wizard prompts for your API key (`mcs_…` from [app.multicorn.ai](https://app.multicorn.ai)) and merges platform-specific snippets into the right config paths. Run it again any time you add another host agent. Inspect saved agents with:
95
55
 
96
56
  ```bash
97
- cd $(npm root -g)/multicorn-shield
98
- npm run build
57
+ npx multicorn-shield agents
99
58
  ```
100
59
 
101
- **Step 3: Register with OpenClaw**
102
-
103
- Add the plugin path to your `~/.openclaw/openclaw.json`:
104
-
105
- ```json
106
- {
107
- "plugins": {
108
- "load": {
109
- "paths": ["<npm-root>/multicorn-shield/dist/openclaw-plugin/index.js"]
110
- },
111
- "entries": {
112
- "multicorn-shield": {
113
- "enabled": true
114
- }
115
- }
116
- }
117
- }
118
- ```
119
-
120
- Replace `<npm-root>` with the output of `npm root -g`.
121
-
122
- **Step 4: Restart and verify**
60
+ After init, wrap your MCP server when you launch it:
123
61
 
124
62
  ```bash
125
- openclaw gateway restart
126
- openclaw plugins list
63
+ npx multicorn-shield --wrap <your-existing-mcp-command>
127
64
  ```
128
65
 
129
- You should see `multicorn-shield` in the loaded plugins list.
130
-
131
- **How it works**
66
+ Shield bundles an OpenClaw plugin under `dist/openclaw-plugin/` if you prefer native interception over wrapping the MCP process. Claude Desktop users can sidestep manual JSON editing with the downloadable `.mcpb` bundle from [multicorn.ai/shield](https://multicorn.ai/shield). Need the SDK directly? Jump to **[SDK snippet](#sdk-snippet)** and the [getting started tutorial](https://multicorn.ai/docs/getting-started).
132
67
 
133
- 1. Agent tries to use a tool (read files, run commands, send emails)
134
- 2. Shield intercepts via `before_tool_call` and checks permissions
135
- 3. First time: A consent screen opens in your browser so you can authorize the agent
136
- 4. Authorized actions: Proceed immediately
137
- 5. New or elevated actions: Blocked with a link to the dashboard where you approve or reject
138
- 6. Everything is logged to your Multicorn dashboard
68
+ ## Links
139
69
 
140
- The plugin maps OpenClaw tools to Shield permission scopes automatically:
70
+ | Resource | URL |
71
+ | -------------- | ------------------------------------------------ |
72
+ | Docs hub | https://multicorn.ai/shield |
73
+ | Product docs | https://multicorn.ai/docs/getting-started |
74
+ | Live dashboard | https://app.multicorn.ai |
75
+ | Source | https://github.com/Multicorn-AI/multicorn-shield |
141
76
 
142
- | OpenClaw Tool | Shield Scope |
143
- | ------------------- | ---------------- |
144
- | read | filesystem:read |
145
- | write, edit | filesystem:write |
146
- | exec | terminal:execute |
147
- | exec (rm, mv, sudo) | terminal:write |
148
- | browser | browser:execute |
149
- | message | messaging:write |
77
+ Changelog: [CHANGELOG.md](CHANGELOG.md) · Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · Security: [SECURITY.md](SECURITY.md)
150
78
 
151
- Destructive commands (rm, mv, sudo, chmod) are detected automatically and require separate write-level approval.
79
+ ## SDK snippet
152
80
 
153
- ### Option 3: Integrate the SDK
154
-
155
- For full control over consent screens, spending limits, and action logging, use the SDK directly in your application code.
81
+ Install as a dependency when you embed consent screens or bespoke logging paths:
156
82
 
157
83
  ```bash
158
84
  npm install multicorn-shield
@@ -177,355 +103,44 @@ await shield.logAction({
177
103
  });
178
104
  ```
179
105
 
180
- That gives you a consent screen, scoped permissions, and an audit trail.
181
-
182
- ## Dashboard
183
-
184
- Every action, approval, and permission is visible in real time at [app.multicorn.ai](https://app.multicorn.ai).
185
-
186
- **Sign up:** [https://app.multicorn.ai](https://app.multicorn.ai)
187
-
188
- With the dashboard you can:
189
-
190
- - See all agents and their activity
191
- - Approve or reject pending actions
192
- - Configure per-agent permissions (read/write/execute per service)
193
- - Set spending limits
194
- - View the full audit trail with hash-chain integrity
195
-
196
- The dashboard works with both the SDK integration and the MCP proxy. No extra setup needed.
197
-
198
- <p align="center">
199
- <img src="https://multicorn.ai/images/og-image-shield.png" alt="Dashboard overview showing total actions, blocked count, spend, and live activity feed" width="800" />
200
- </p>
201
-
202
- <p align="center">
203
- <img src="https://multicorn.ai/images/screenshots/approvals-card.png" alt="Approval card with one-tap approve/reject and permission duration options" width="800" />
204
- </p>
205
-
206
- <p align="center">
207
- <img src="https://multicorn.ai/images/screenshots/activity-log-list.png" alt="Filterable activity log showing every agent action with status" width="800" />
208
- </p>
209
-
210
- <p align="center">
211
- <img src="https://multicorn.ai/images/screenshots/consent-screen.png" alt="Consent screen where users grant agent permissions" width="800" />
212
- </p>
213
-
214
- <p align="center">
215
- <img src="https://multicorn.ai/images/screenshots/agent-page-with-stats.png" alt="Agent detail page with action stats and budget tracking" width="800" />
216
- </p>
217
-
218
- ## Built with Shield
219
-
220
- Multicorn is developed using AI coding agents. Primarily Cursor for code generation and GitHub Actions as the deployment agent. Every one of those agents runs under Shield.
221
-
222
- We're not just building a trust layer for AI agents. We're depending on it ourselves. If Shield fails to catch something in our own workflow, we feel it directly.
223
-
224
- [Read how we use agents to build Multicorn →](https://multicorn.ai/blog/agents)
225
-
226
- ## Features
227
-
228
- ### Consent Screens
229
-
230
- A drop-in web component (Shadow DOM, framework-agnostic) that lets users review and approve agent permissions before granting access.
231
-
232
- ```typescript
233
- const decision = await shield.requestConsent({
234
- agent: "OpenClaw",
235
- scopes: ["read:gmail", "write:calendar", "execute:payments"],
236
- spendLimit: 500,
237
- agentColor: "#8b5cf6",
238
- });
239
-
240
- // decision.grantedScopes - what the user actually approved
241
- ```
242
-
243
- ### Scopes
244
-
245
- Type-safe permission scopes with built-in services (Gmail, Calendar, Slack, Drive, Payments, GitHub, Jira) and a registry for custom ones.
246
-
247
- ```typescript
248
- import { createScopeRegistry, parseScope } from "multicorn-shield";
249
-
250
- const registry = createScopeRegistry();
251
-
252
- registry.register({
253
- name: "analytics",
254
- description: "Internal analytics platform",
255
- capabilities: ["read", "write"],
256
- });
257
-
258
- const scope = parseScope("read:analytics");
259
- // { service: "analytics", permissionLevel: "read" }
260
- ```
261
-
262
- ### Action Logging
263
-
264
- Structured audit trail of every action an agent takes. Supports immediate and batched delivery.
265
-
266
- ```typescript
267
- await shield.logAction({
268
- agent: "OpenClaw",
269
- service: "gmail",
270
- action: "send_email",
271
- status: "approved",
272
- cost: 0.002,
273
- metadata: { recipient: "user@example.com" },
274
- });
275
- ```
276
-
277
- ### Spending Controls
278
-
279
- Client-side enforcement of per-transaction, daily, and monthly spend limits. Currency-safe integer arithmetic (cents) prevents floating point issues.
280
-
281
- ```typescript
282
- const result = shield.checkSpending("OpenClaw", 849);
283
-
284
- if (!result.allowed) {
285
- // "Action blocked: $849.00 exceeds per-transaction limit of $200.00"
286
- console.error(result.reason);
287
- }
288
- ```
289
-
290
- ### MCP Integration
291
-
292
- Middleware adapter for Model Context Protocol servers. Sits between the agent and MCP tools, enforcing permissions on every tool call.
293
-
294
- ```typescript
295
- import { createMcpAdapter, isBlockedResult } from "multicorn-shield";
296
-
297
- const adapter = createMcpAdapter({
298
- agentId: "inbox-assistant",
299
- grantedScopes: [
300
- { service: "gmail", permissionLevel: "execute" },
301
- { service: "calendar", permissionLevel: "read" },
302
- ],
303
- logger,
304
- });
305
-
306
- const result = await adapter.intercept(
307
- { toolName: "gmail_send_email", arguments: { to: "user@example.com" } },
308
- (call) => mcpServer.callTool(call.toolName, call.arguments),
309
- );
310
-
311
- if (isBlockedResult(result)) {
312
- console.error(result.reason);
313
- }
314
- ```
315
-
316
- ## API Reference
317
-
318
- Full API documentation is generated from source with TypeDoc:
319
-
320
- ```bash
321
- pnpm run docs
322
- ```
323
-
324
- This outputs to `docs/api/`. You can also browse the inline JSDoc on every public export. All interfaces, functions, and types are documented with examples.
325
-
326
- ## Architecture
327
-
328
- Multicorn Shield is the client-side SDK in the Multicorn ecosystem. It runs in the browser or Node.js and communicates with the Multicorn hosted API for persistence and policy enforcement.
329
-
330
- ```
331
- ┌─────────────────────────────────────────────────────┐
332
- │ Your Application │
333
- │ │
334
- │ ┌──────────────────────────────────────────────┐ │
335
- │ │ multicorn-shield (this SDK) │ │
336
- │ │ │ │
337
- │ │ ┌────────────┐ ┌──────────┐ ┌──────────┐ │ │
338
- │ │ │ Consent │ │ Action │ │ Spending │ │ │
339
- │ │ │ Screen │ │ Logger │ │ Checker │ │ │
340
- │ │ └────────────┘ └────┬─────┘ └──────────┘ │ │
341
- │ │ ┌────────────┐ │ │ │
342
- │ │ │ MCP │ │ │ │
343
- │ │ │ Adapter │ │ │ │
344
- │ │ └────────────┘ │ │ │
345
- │ └───────────────────────┼──────────────────────┘ │
346
- │ │ HTTPS │
347
- └──────────────────────────┼──────────────────────────┘
348
- │
349
- ▼
350
- ┌────────────────────────┐
351
- │ Multicorn Service API │
352
- │ (hosted backend) │
353
- └────────────┬───────────┘
354
- │
355
- ▼
356
- ┌────────────────────────┐
357
- │ Multicorn Dashboard │
358
- │ (admin UI) │
359
- └────────────────────────┘
360
- ```
361
-
362
- The SDK handles:
363
-
364
- - **Consent**: renders a Shadow DOM web component for permission approval
365
- - **Scope validation**: parses and validates `"permission:service"` scope strings locally
366
- - **Action logging**: sends structured events to the hosted API over HTTPS
367
- - **Spending checks**: client-side pre-validation (server is the source of truth)
368
- - **MCP adapter**: middleware layer between AI agents and MCP tool servers
369
-
370
- The hosted API handles persistence, policy enforcement, and the audit trail. The SDK never stores credentials locally. API keys are held in memory only.
371
-
372
106
  ## Configuration
373
107
 
374
- ### `MulticornShieldConfig`
375
-
376
- | Option | Type | Default | Description |
377
- | ----------- | ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
378
- | `apiKey` | `string` | - | **Required.** Your Multicorn API key. Must start with `mcs_` and be at least 16 characters. Stored in memory only. |
379
- | `baseUrl` | `string` | `"https://api.multicorn.ai"` | Base URL for the Multicorn API. |
380
- | `timeout` | `number` | `5000` | Request timeout in milliseconds. |
381
- | `batchMode` | `BatchModeConfig` | - | Optional batch mode for action logging. When enabled, actions are queued and flushed periodically. |
382
-
383
- ### `BatchModeConfig`
384
-
385
- | Option | Type | Default | Description |
386
- | ----------------- | --------- | ------- | ----------------------------------------- |
387
- | `enabled` | `boolean` | - | Whether batch mode is active. |
388
- | `maxSize` | `number` | `10` | Maximum actions to queue before flushing. |
389
- | `flushIntervalMs` | `number` | `5000` | Maximum time (ms) between flushes. |
390
-
391
- ### `ConsentOptions`
392
-
393
- | Option | Type | Default | Description |
394
- | ------------ | ---------- | ----------- | ------------------------------------------------------------------------------- |
395
- | `agent` | `string` | - | **Required.** Name of the agent requesting access. Shown on the consent screen. |
396
- | `scopes` | `string[]` | - | **Required.** Permission scopes to request. Format: `"permission:service"`. |
397
- | `spendLimit` | `number` | `0` | Maximum spend per transaction in dollars. `0` disables spending controls. |
398
- | `agentColor` | `string` | `"#8b5cf6"` | Hex colour for the agent icon on the consent screen. |
399
-
400
- ### `McpAdapterConfig`
401
-
402
- | Option | Type | Default | Description |
403
- | ------------------------- | ------------------------------ | ------------------ | --------------------------------------------------------------------------- |
404
- | `agentId` | `string` | - | **Required.** Agent identifier for audit logging. |
405
- | `grantedScopes` | `Scope[]` | - | **Required.** Scopes granted via the consent screen. |
406
- | `logger` | `ActionLogger` | - | Optional logger instance. When omitted, actions are checked but not logged. |
407
- | `requiredPermissionLevel` | `PermissionLevel` | `"execute"` | Permission level required for MCP tool calls. |
408
- | `extractService` | `(toolName: string) => string` | Split on first `_` | Custom function to derive the service name from a tool name. |
409
- | `extractAction` | `(toolName: string) => string` | Split on first `_` | Custom function to derive the action type from a tool name. |
410
-
411
- ## Framework Examples
108
+ The hosted **[getting started guide](https://multicorn.ai/docs/getting-started)** spells out CLI quick starts and SDK bootstrap defaults. MCP adapter knobs, consent payloads, CLI flags for the proxy wrapper, spending helpers, and every public export are covered by TypeDoc emitted with `pnpm docs` into **`docs/api/`**.
412
109
 
413
- > **Using MCP?** If your agent connects to tools via an MCP server, you may not need any of these. See [Option 1](#option-1-wrap-your-existing-agents-no-code-changes) to add Shield with zero code changes.
414
-
415
- ### React
416
-
417
- ```tsx
418
- import { useEffect, useRef } from "react";
419
- import { MulticornShield } from "multicorn-shield";
110
+ ## Architecture
420
111
 
421
- function AgentSetup() {
422
- const shieldRef = useRef<MulticornShield | null>(null);
423
-
424
- useEffect(() => {
425
- shieldRef.current = new MulticornShield({ apiKey: "mcs_your_key_here" });
426
- return () => shieldRef.current?.destroy();
427
- }, []);
428
-
429
- async function handleConnect() {
430
- const decision = await shieldRef.current?.requestConsent({
431
- agent: "OpenClaw",
432
- scopes: ["read:gmail", "write:calendar"],
433
- spendLimit: 200,
434
- });
435
- console.log("Granted:", decision?.grantedScopes);
436
- }
437
-
438
- return <button onClick={handleConnect}>Connect Agent</button>;
439
- }
440
112
  ```
441
-
442
- ### Vue
443
-
444
- ```vue
445
- <script setup lang="ts">
446
- import { ref, onMounted, onUnmounted } from "vue";
447
- import { MulticornShield } from "multicorn-shield";
448
-
449
- const shield = ref<MulticornShield | null>(null);
450
-
451
- onMounted(() => {
452
- shield.value = new MulticornShield({ apiKey: "mcs_your_key_here" });
453
- });
454
-
455
- onUnmounted(() => shield.value?.destroy());
456
-
457
- async function handleConnect() {
458
- const decision = await shield.value?.requestConsent({
459
- agent: "OpenClaw",
460
- scopes: ["read:gmail", "write:calendar"],
461
- spendLimit: 200,
462
- });
463
- console.log("Granted:", decision?.grantedScopes);
464
- }
465
- </script>
466
-
467
- <template>
468
- <button @click="handleConnect">Connect Agent</button>
469
- </template>
113
+ Your agent / Browser
114
+ │
115
+ ▼
116
+ multicorn-shield SDK · CLI · local proxy shim
117
+ │
118
+ HTTPS (see Network behaviour below)
119
+ ▼
120
+ Multicorn hosted API -> Dashboard UI
470
121
  ```
471
122
 
472
- ### Svelte
123
+ For module-level internals (consent renderer, MCP adapter, spending checker, proxies), regenerate TypeDoc locally (`pnpm docs`) and skim `docs/adr/`.
473
124
 
474
- ```svelte
475
- <script lang="ts">
476
- import { onMount, onDestroy } from "svelte";
477
- import { MulticornShield } from "multicorn-shield";
125
+ The SDK validates scopes client-side before calling hosted persistence. MCP proxy setups add localhost-only IPC (`127.0.0.1`) between wrapper and MCP child.
478
126
 
479
- let shield: MulticornShield;
127
+ See **[Network behaviour](#network-behaviour)** for reachable hosts.
480
128
 
481
- onMount(() => {
482
- shield = new MulticornShield({ apiKey: "mcs_your_key_here" });
483
- });
484
-
485
- onDestroy(() => shield?.destroy());
486
-
487
- async function handleConnect() {
488
- const decision = await shield.requestConsent({
489
- agent: "OpenClaw",
490
- scopes: ["read:gmail", "write:calendar"],
491
- spendLimit: 200,
492
- });
493
- console.log("Granted:", decision.grantedScopes);
494
- }
495
- </script>
496
-
497
- <button on:click={handleConnect}>Connect Agent</button>
498
- ```
499
-
500
- ### Vanilla HTML
129
+ ## Network behaviour
501
130
 
502
- ```html
503
- <button id="connect">Connect Agent</button>
131
+ - **`api.multicorn.ai`:** Consent workflows, approvals, auditing, spends. Calls happen only while your code or CLI path runs Shield. There is no import-time network activity.
132
+ - **`localhost`:** Proxy-local IPC during stdio MCP wrapping. Traffic never leaves the machine.
133
+ - **CLI config:** The wizard writes your API key into `~/.multicorn/config.json` on disk. The in-app SDK keeps keys in memory unless you persist them yourself.
504
134
 
505
- <script type="module">
506
- import { MulticornShield } from "multicorn-shield";
135
+ No third-party telemetry.
507
136
 
508
- const shield = new MulticornShield({ apiKey: "mcs_your_key_here" });
137
+ ## Dashboard
509
138
 
510
- document.getElementById("connect").addEventListener("click", async () => {
511
- const decision = await shield.requestConsent({
512
- agent: "OpenClaw",
513
- scopes: ["read:gmail", "write:calendar"],
514
- spendLimit: 200,
515
- });
516
- console.log("Granted:", decision.grantedScopes);
517
- });
518
- </script>
519
- ```
139
+ Approve, reject, revoke, tune budgets, and watch live traffic at [app.multicorn.ai](https://app.multicorn.ai). Works for both MCP proxy setups and bespoke SDK integrations.
520
140
 
521
141
  ## Development
522
142
 
523
- ### Prerequisites
524
-
525
- - Node.js 20+
526
- - pnpm 9+
527
-
528
- ### Setup
143
+ Requires Node.js 20+ and pnpm 9+.
529
144
 
530
145
  ```bash
531
146
  git clone https://github.com/Multicorn-AI/multicorn-shield.git
@@ -535,87 +150,36 @@ pnpm test
535
150
  pnpm build
536
151
  ```
537
152
 
538
- ### Commands
539
-
540
- | Command | Description |
541
- | -------------------- | ------------------------------------------ |
542
- | `pnpm build` | Build ESM and CJS bundles with tsup |
543
- | `pnpm dev` | Build in watch mode |
544
- | `pnpm lint` | Run ESLint and Prettier checks |
545
- | `pnpm lint:fix` | Auto-fix lint and formatting issues |
546
- | `pnpm test` | Run tests with Vitest |
547
- | `pnpm test:watch` | Run tests in watch mode |
548
- | `pnpm test:coverage` | Run tests with Istanbul coverage reporting |
549
- | `pnpm typecheck` | Type-check without emitting |
550
- | `pnpm docs` | Generate API docs with TypeDoc |
153
+ | Script | Meaning |
154
+ | -------------------- | ------------------------------------ |
155
+ | `pnpm build` | Produce ESM+CJS bundles with tsup |
156
+ | `pnpm dev` | tsup watch mode |
157
+ | `pnpm lint` | ESLint + Prettier |
158
+ | `pnpm lint:fix` | ESLint autofix plus Prettier write |
159
+ | `pnpm test` | Vitest unit suite |
160
+ | `pnpm test:coverage` | Vitest plus Istanbul instrumentation |
161
+ | `pnpm typecheck` | `tsc --noEmit` |
162
+ | `pnpm docs` | Typedoc emission into `docs/api/` |
551
163
 
552
- ## Project Structure
164
+ Detailed notes live in **`src/`** headers and **`docs/adr/`**.
553
165
 
554
166
  ```
555
167
  multicorn-shield/
556
- ├── src/
557
- │ ├── index.ts # Package entry point (public API barrel)
558
- │ ├── multicorn-shield.ts # Main SDK class that orchestrates all modules
559
- │ ├── consent/ # Consent screen web component (Lit + Shadow DOM)
560
- │ │ ├── multicorn-consent.ts # <multicorn-consent> custom element
561
- │ │ ├── consent-events.ts # Custom event types and dispatchers
562
- │ │ ├── consent-styles.ts # Scoped styles (no CSS leakage)
563
- │ │ ├── focus-trap.ts # Keyboard focus management
564
- │ │ └── scope-labels.ts # Human-readable scope display names
565
- │ ├── scopes/ # Scope types, parsing, and validation
566
- │ │ ├── scope-definitions.ts # Built-in service registry
567
- │ │ ├── scope-parser.ts # "read:gmail" string parsing
568
- │ │ └── scope-validator.ts # Permission access checks
569
- │ ├── logger/ # Action logging client
570
- │ │ └── action-logger.ts # HTTP client with batch mode and retry
571
- │ ├── spending/ # Client-side spend enforcement
572
- │ │ └── spending-checker.ts # Integer-cents arithmetic, limit checks
573
- │ ├── mcp/ # MCP (Model Context Protocol) adapter
574
- │ │ └── mcp-adapter.ts # Middleware for MCP tool call interception
575
- │ └── types/ # Shared TypeScript types
576
- │ └── index.ts # Interfaces, constants, type aliases
577
- ├── docs/
578
- │ └── adr/ # Architecture Decision Records
579
- ├── examples/ # Runnable HTML examples
580
- ├── dist/ # Built output (ESM + CJS + types)
581
- ├── tsup.config.ts # Bundle configuration
582
- ├── tsconfig.json # TypeScript strict mode configuration
583
- ├── vitest.config.ts # Test runner configuration
584
- └── eslint.config.ts # Linting rules
168
+ ├── src/ # SDK, CLI, MCP adapter, consent web component
169
+ ├── plugins/ # Host-specific hooks (Cline, Codex CLI, Windsurf, OpenCode…)
170
+ ├── bin/ # Executable entry stubs
171
+ ├── docs/adr/ # Architecture decision records
172
+ └── examples/ # Runnable HTML snippets
585
173
  ```
586
174
 
587
175
  ## Publishing & ownership
588
176
 
589
- Releases are published from a single GitHub Actions workflow (.github/workflows/publish.yml). It is manually dispatched (workflow_dispatch) with a patch/minor/major input. Each run installs dependencies, runs lint, typecheck, tests, and build, then bumps the package version with npm version (which creates a version commit and tag locally), publishes to npm with pnpm publish --no-git-checks --access public --provenance, and pushes the commit and tag with git push --follow-tags. After that, the same run may POST to a Vercel deploy hook (repository secret) to refresh the learn site. That hook does not publish to npm. No other workflow publishes this package.
590
-
591
- The npm publish step uses a scoped automation token stored as one repository secret (`NPM_TOKEN`), only for this workflow, with npm provenance enabled on the publish command.
592
-
593
- The npm package has a single publisher account (`multicorn-ai`). If you see a Socket.dev "unstable ownership" warning after an earlier publish-identity change, it often clears as the registry history stabilizes across the next few releases.
594
-
595
- For compromised-package or supply-chain concerns, see [SECURITY.md](SECURITY.md).
596
-
597
- ## Network behaviour
598
-
599
- The SDK and CLI make outbound requests to the following hosts:
600
-
601
- **api.multicorn.ai** (control plane; default)
602
-
603
- - Consent creation and approval polling
604
- - Action audit submission
605
- - Spending checks
606
- - Invoked only when the host application calls SDK or CLI methods, or when the proxy or extension runs its control-plane logic. There is no import-time network activity.
607
-
608
- **127.0.0.1 / localhost** (local proxy, when running in proxy mode)
609
-
610
- - IPC between the CLI wrapper and the local proxy process
611
- - Never leaves the user's machine
612
-
613
- No telemetry, analytics, or phone-home calls. Outbound API URLs use fixed paths under a single configurable base URL: the SDK `baseUrl` option (default `https://api.multicorn.ai`), the `MULTICORN_BASE_URL` environment variable, or `baseUrl` in `~/.multicorn/config.json` for the proxy and related tooling. Hosts and paths are not built from agent tool parameters or request bodies.
177
+ Published by `multicorn-ai` on npm. CI runs lint, types, tests, and build before every release. See [SECURITY.md](SECURITY.md) for supply-chain concerns. Operational detail lives in [CONTRIBUTING.md](CONTRIBUTING.md).
614
178
 
615
179
  ## Contributing
616
180
 
617
- Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
181
+ Patches welcome: read [CONTRIBUTING.md](CONTRIBUTING.md), open issues for platform gaps, attach repro logs whenever hooks mis-fire.
618
182
 
619
- ## License
183
+ ## Licence
620
184
 
621
185
  [MIT](LICENSE) © Multicorn AI Pty Ltd