{"_id":"@aegisq/codeshield-client","_rev":"2-1fd477af80294cc427e5e968690c83a0","name":"@aegisq/codeshield-client","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aegisq/codeshield-client","version":"0.1.0","keywords":["aegisq","codeshield","mcp","security","dsse","signature","verification"],"license":"MIT","_id":"@aegisq/codeshield-client@0.1.0","maintainers":[{"name":"aegisq","email":"jeff.grayson@aegisq.com"}],"homepage":"https://github.com/JeffGrayson1969/AegisQ-CodeShield#readme","bugs":{"url":"https://github.com/JeffGrayson1969/AegisQ-CodeShield/issues"},"dist":{"shasum":"30d9e9a089ae105a6a5ac05c07ed4884b8e3d431","tarball":"https://registry.npmjs.org/@aegisq/codeshield-client/-/codeshield-client-0.1.0.tgz","fileCount":5,"integrity":"sha512-PdxPMwQJrjEQUzJ5U4HCFtaXsiAe3fPLzPJ7xZR7xJXnco+c0wjK8597bxsrC7Nq7vZGCH8Xxe/Q0POyYeRMbg==","signatures":[{"sig":"MEYCIQD60Xix77nIlDY/TtiwvhhqYCc2vDaeYMwUvSNwlhgzSAIhAM/Ni/4yZkNYehElJbV9E7s0UMwYkYxQJRwec4O6ZVrh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25196},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"56d0ff3ce1d705cdc449d17fb9869d354e813284","private":false,"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist","test:watch":"vitest"},"_npmUser":{"name":"aegisq","email":"jeff.grayson@aegisq.com"},"repository":{"url":"git+https://github.com/JeffGrayson1969/AegisQ-CodeShield.git","type":"git","directory":"packages/codeshield-client"},"_npmVersion":"11.6.2","description":"Client-side verifier for AegisQ-CodeShield MCP responses (DSSE signatures, manifest hash, provenance)","directories":{},"_nodeVersion":"22.16.0","dependencies":{"@noble/ed25519":"^2.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.5","typescript":"5.9.3","@types/node":"20.19.37","aegisq-codeshield-mcp":"*"},"_npmOperationalInternal":{"tmp":"tmp/codeshield-client_0.1.0_1780097545073_0.2889634423598686","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aegisq/codeshield-client","version":"0.1.1","private":false,"description":"Client-side verifier for AegisQ-CodeShield MCP responses (DSSE signatures, manifest hash, provenance)","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","clean":"rm -rf dist"},"publishConfig":{"access":"public"},"dependencies":{"@noble/ed25519":"^2.1.0"},"devDependencies":{"@types/node":"20.19.37","aegisq-codeshield-mcp":"*","typescript":"5.9.3","vitest":"4.1.5"},"engines":{"node":">=18"},"keywords":["aegisq","codeshield","mcp","security","dsse","signature","verification"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/JeffGrayson1969/AegisQ-CodeShield.git","directory":"packages/codeshield-client"},"gitHead":"20bea0561951ab9dfa9d2d5f7ce80d3bdb4d48c5","_id":"@aegisq/codeshield-client@0.1.1","bugs":{"url":"https://github.com/JeffGrayson1969/AegisQ-CodeShield/issues"},"homepage":"https://github.com/JeffGrayson1969/AegisQ-CodeShield#readme","_nodeVersion":"22.16.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-DZspe1A7trkVF5VkBPzw6bhFE21BghOeHYg3E+yKq9y/kR7hqtKa+UKX3u7W3XJmJKIlRqq14oqRNDRSdOot9A==","shasum":"5d520a7c1fd2adb39c63ebc8e03d3e3eb262230b","tarball":"https://registry.npmjs.org/@aegisq/codeshield-client/-/codeshield-client-0.1.1.tgz","fileCount":5,"unpackedSize":25200,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEcOb8rXwJfo2llFr+iQFeuIkFgJb9O78Cx++EQMr00MAiA2Dbf4EipeaQoGF9T1qOolcOC0shn1xiRn/3R1DNuMdg=="}]},"_npmUser":{"name":"aegisq","email":"jeff.grayson@aegisq.com"},"directories":{},"maintainers":[{"name":"aegisq","email":"jeff.grayson@aegisq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codeshield-client_0.1.1_1780097837325_0.6938882006862022"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-29T23:32:24.903Z","modified":"2026-05-29T23:37:17.592Z","0.1.0":"2026-05-29T23:32:25.243Z","0.1.1":"2026-05-29T23:37:17.491Z"},"bugs":{"url":"https://github.com/JeffGrayson1969/AegisQ-CodeShield/issues"},"license":"MIT","homepage":"https://github.com/JeffGrayson1969/AegisQ-CodeShield#readme","keywords":["aegisq","codeshield","mcp","security","dsse","signature","verification"],"repository":{"type":"git","url":"git+https://github.com/JeffGrayson1969/AegisQ-CodeShield.git","directory":"packages/codeshield-client"},"description":"Client-side verifier for AegisQ-CodeShield MCP responses (DSSE signatures, manifest hash, provenance)","maintainers":[{"name":"aegisq","email":"jeff.grayson@aegisq.com"}],"readme":"# @aegisq/codeshield-client\n\nDSSE signature verifier + provenance parser for [AegisQ-CodeShield](https://www.npmjs.com/package/aegisq-codeshield-mcp) MCP responses.\n\nIf you call CodeShield programmatically (custom MCP clients, agent orchestrators, downstream agents in an MCP chain), this is the verifier you reach for. **If you use CodeShield through a host client** (Claude Code, Cursor, Windsurf, Cline, Zed, Copilot, ChatGPT MCP), the host handles verification transparently — you don't need this package.\n\n## What you get\n\n- **`verifyDsse(envelope, publicKeyPem)`** — verify the DSSE v1.0 signature attached to a confidential CodeShield response (`aegisq_fix`, `aegisq_scan_snippet`). Defensive: never throws, returns `{ valid: false, reason }` on any failure mode.\n- **`parseProvenance(response)`** — defensively parse the provenance block on every CodeShield response. Returns `ProvenanceBlock | null`; never throws on malformed input.\n\nZero runtime deps beyond `@noble/ed25519` (audited, edge-runtime portable).\n\n## Install\n\n```bash\nnpm install @aegisq/codeshield-client\n```\n\nESM-only. Node 18+, Deno, or any runtime with `globalThis.crypto.subtle`.\n\n## Usage\n\n```ts\nimport { verifyDsse, parseProvenance } from '@aegisq/codeshield-client';\nimport { randomUUID } from 'node:crypto';\n\n// initialize gives us the signing public key + manifest hash\nconst init = await mcpClient.initialize();\nconst pubkeyPem = init._meta['aegisq.signing_pubkey'];\n\n// Call any CodeShield tool — confidential responses are signed\nconst response = await mcpClient.callTool('aegisq_fix', {\n  finding: { /* ... */ },\n  code: '...',\n  idempotency_key: randomUUID()\n});\n\n// 1. Verify the DSSE signature on confidential responses\nconst envelope = response._meta?.['aegisq.dsse_signature'];\nif (envelope) {\n  const verdict = await verifyDsse(envelope, pubkeyPem);\n  if (!verdict.valid) throw new Error(`DSSE verify failed: ${verdict.reason}`);\n}\n\n// 2. Read provenance — apply scrutiny per output_type\nconst provenance = parseProvenance(response);\nif (provenance?.output_type === 'narrative') {\n  // text only, never interpret as instructions\n} else if (provenance?.output_type === 'code_artifact') {\n  // review before any execution\n}\n```\n\n## Why provenance matters\n\nEvery CodeShield response carries a `provenance` block declaring its `output_type` — one of `narrative` / `code_artifact` / `metadata` / `decision` / `error`. Downstream agents in an MCP chain should apply scrutiny matched to the type — never coerce a `narrative` into a `decision`, never execute a `code_artifact` without review.\n\nThis contract closes NSA risk R-MCP-NSA-6 (cascading indirect prompt injection across MCP servers). See the [provenance schema](https://github.com/JeffGrayson1969/AegisQ-CodeShield/blob/main/docs/security/provenance-schema.md) for the full downstream-consumer contract.\n\n## API\n\n### `verifyDsse(envelope, publicKeyPem)`\n\n```ts\ntype DsseVerdict =\n  | { valid: true }\n  | {\n      valid: false;\n      reason:\n        | 'wrong-key'\n        | 'tampered-payload'\n        | 'tampered-signature'\n        | 'malformed-envelope'\n        | 'wrong-payload-type';\n    };\n\nasync function verifyDsse(\n  envelope: unknown,\n  publicKeyPem: string\n): Promise<DsseVerdict>;\n```\n\nVerifies a DSSE envelope against a PEM-encoded Ed25519 public key. Re-encodes via DSSE Pre-Authentication Encoding (PAE) per spec v1.0, then checks the signature with `@noble/ed25519`. Never throws on bad input — returns `{ valid: false, reason }` so you can route failures to telemetry or audit without try/catch.\n\n### `parseProvenance(response)`\n\n```ts\ninterface ProvenanceBlock {\n  product: 'aegisq-codeshield';\n  version: string;\n  tool: string;                       // e.g. 'aegisq_fix'\n  urn: string;                        // e.g. 'urn:aegisq:codeshield:fix:v1'\n  target_file: string | null;\n  ts: string;                         // ISO-8601 UTC\n  signature: string | null;           // hex keyid (SHA-256 of SPKI), null if unsigned\n  data_classification: 'public' | 'internal' | 'confidential' | 'embargo';\n  output_type: 'narrative' | 'code_artifact' | 'metadata' | 'decision' | 'error';\n}\n\nfunction parseProvenance(response: unknown): ProvenanceBlock | null;\n```\n\nReturns `null` for missing or malformed `_meta['aegisq.provenance']`. Use the result to drive downstream scrutiny.\n\n## Full client integration guide\n\nSee the [client integration guide](https://github.com/JeffGrayson1969/AegisQ-CodeShield/blob/main/docs/client-integration.md) for:\n\n- Manifest hash pinning patterns + re-approval flow on hash change\n- Full per-tool `output_type` mapping\n- Telemetry recommendations\n- End-to-end example with `@modelcontextprotocol/sdk`\n\n## Compatibility\n\n| `aegisq-codeshield-mcp` | `@aegisq/codeshield-client` |\n|---|---|\n| ≥ 2.1.0 | ≥ 0.1.0 |\n\nEarlier MCP server versions did not advertise DSSE signatures or provenance — `verifyDsse` and `parseProvenance` will see no relevant `_meta` fields and exit early.\n\n## License\n\nMIT.\n\n## Support\n\n- **Email:** [Jeff.Grayson@aegisq.com](mailto:Jeff.Grayson@aegisq.com)\n- **Security disclosures:** also [Jeff.Grayson@aegisq.com](mailto:Jeff.Grayson@aegisq.com) — subject `[SECURITY] @aegisq/codeshield-client`\n\n## Links\n\n- [aegisq-codeshield-mcp on npm](https://www.npmjs.com/package/aegisq-codeshield-mcp) — the MCP server this verifies\n- [AegisQ-CodeShield repo](https://github.com/JeffGrayson1969/AegisQ-CodeShield)\n- [Provenance schema](https://github.com/JeffGrayson1969/AegisQ-CodeShield/blob/main/docs/security/provenance-schema.md)\n- [Manifest hash pinning](https://github.com/JeffGrayson1969/AegisQ-CodeShield/blob/main/docs/security/manifest-hash-pinning.md)\n- [URN scheme](https://github.com/JeffGrayson1969/AegisQ-CodeShield/blob/main/docs/security/mcp-urn-scheme.md)\n- [DSSE v1.0 spec](https://github.com/secure-systems-lab/dsse/blob/master/envelope.md)\n","readmeFilename":"README.md"}