@7h3/protocol 0.5.4 → 0.6.0

package/bin/7h3.js

@@ -1,21 +1,29 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { createServer } from 'node:http';
-import { writeFileSync } from 'node:fs';
+import { writeFileSync, readFileSync } from 'node:fs';
 const USAGE = `
 7h3 — Protocol CLI (wire version 7h3/0.1)
 
 Usage:
   7h3 keygen [--output <file>]
   7h3 sign   --private-key <key> --sender <id> [--recipient <id>] [--payload <str>] [--ttl <ms>]
+             (or --private-key-file <path>, or env P7H3_PRIVATE_KEY)
   7h3 verify --public-key <key> --envelope <json>
   7h3 inspect --envelope <json>
   7h3 gateway --upstream <url> [--port <n>] [--public-key <key>] [--require ed25519|none]
               [--sign-responses] [--private-key <key>] [--sender <id>] [--metrics-port <n>]
+              [--allow-unverified]
+              (private key: --private-key-file <path>, or env GATEWAY_PRIVATE_KEY)
   7h3 keys serve [--public-key <key>] [--key-id <id>] [--port <n>]
   7h3 add --framework <name> [--sender <id>] [--output <dir>]
   7h3 help
 
+Secrets:
+  --private-key on 'sign'/'gateway' is visible in shell history and process
+  listings. Prefer --private-key-file <path> or the P7H3_PRIVATE_KEY /
+  GATEWAY_PRIVATE_KEY environment variables.
+
 Commands:
   keygen     Generate an Ed25519 keypair (PKCS8/SPKI, base64url-encoded)
   sign       Create and sign a 7h3 envelope
@@ -30,6 +38,28 @@ function die(msg) {
     process.stderr.write(`Error: ${msg}\n`);
     process.exit(1);
 }
+// A private key passed as a bare CLI argument lands in shell history and is
+// visible to any other local user via `ps`/`/proc` for the life of the
+// process — resolveSecretArg() prefers a file (never touches argv or the
+// environment table other tools can dump) or an env var, and only falls
+// back to the raw flag with an explicit warning so the risk is visible
+// rather than silent.
+function resolveSecretArg(flagName, flagValue, fileValue, envVarName) {
+    if (fileValue) {
+        try {
+            return readFileSync(fileValue, 'utf8').trim();
+        }
+        catch (err) {
+            die(`failed to read --${flagName}-file ${fileValue}: ${String(err)}`);
+        }
+    }
+    if (flagValue) {
+        process.stderr.write(`[7h3] Warning: --${flagName} is visible in shell history and process listings. ` +
+            `Prefer --${flagName}-file <path> or the ${envVarName} environment variable.\n`);
+        return flagValue;
+    }
+    return process.env[envVarName] || undefined;
+}
 async function cmdKeygen(argv) {
     const { values } = parseArgs({
         args: argv,
@@ -65,6 +95,7 @@ async function cmdSign(argv) {
         args: argv,
         options: {
             'private-key': { type: 'string' },
+            'private-key-file': { type: 'string' },
             sender: { type: 'string' },
             recipient: { type: 'string' },
             payload: { type: 'string' },
@@ -72,10 +103,10 @@ async function cmdSign(argv) {
         },
         strict: false,
     });
-    const privateKey = values['private-key'];
+    const privateKey = resolveSecretArg('private-key', values['private-key'], values['private-key-file'], 'P7H3_PRIVATE_KEY');
     const sender = values['sender'];
     if (!privateKey)
-        die('--private-key is required');
+        die('--private-key (or --private-key-file / P7H3_PRIVATE_KEY) is required');
     if (!sender)
         die('--sender is required');
     const { createEnvelope, signEnvelopeEd25519 } = await import('@7h3/protocol');
@@ -194,8 +225,10 @@ async function cmdGateway(argv) {
             require: { type: 'string' },
             'sign-responses': { type: 'boolean' },
             'private-key': { type: 'string' },
+            'private-key-file': { type: 'string' },
             sender: { type: 'string' },
             'metrics-port': { type: 'string' },
+            'allow-unverified': { type: 'boolean' },
         },
         strict: false,
     });
@@ -206,16 +239,53 @@ async function cmdGateway(argv) {
     const publicKey = values['public-key'];
     const requireMode = values['require'] ?? (publicKey ? 'ed25519' : 'none');
     const signResponses = !!(values['sign-responses']);
-    const privateKey = values['private-key'];
+    const privateKey = resolveSecretArg('private-key', values['private-key'], values['private-key-file'], 'GATEWAY_PRIVATE_KEY');
     const sender = values['sender'];
     const metricsPortRaw = values['metrics-port'];
     const metricsPort = metricsPortRaw ? parseInt(metricsPortRaw, 10) : undefined;
+    // `7h3 gateway --upstream <url>` with no other flags used to silently start
+    // a fully unverified passthrough proxy — the exact opposite of what the
+    // command's own usage text ("a verifying HTTP proxy gateway") promises.
+    // Require an explicit, positive choice: either real verification material
+    // or an explicit acknowledgment that this instance is intentionally open.
+    if (requireMode === 'none' && !values['allow-unverified']) {
+        die('refusing to start an unverified passthrough gateway. Pass --public-key/--require to ' +
+            'verify requests, or --allow-unverified to explicitly run without verification.');
+    }
     const { createGateway } = await import('@7h3/protocol/gateway');
     const { createStaticKeyRegistry } = await import('@7h3/protocol/key-registry');
     const keys = {};
     if (publicKey && sender)
         keys[sender] = publicKey;
     const keyRegistry = createStaticKeyRegistry(keys);
+    // No --replay-store flag exists (there's no CLI-friendly way to configure
+    // a shared backing store), but shipping with no replay protection at all
+    // when signatures ARE required silently drops one of the two guarantees
+    // this whole command exists to provide. A minimal in-memory ReplayStore is
+    // still only good for this single process — it won't survive a restart or
+    // a second instance — which is why this only applies to the local
+    // single-process CLI gateway, never the library default.
+    class InMemoryCliReplayStore {
+        seen = new Map();
+        async check(key, ttlMs) {
+            const nowMs = Date.now();
+            for (const [k, expiresAt] of this.seen) {
+                if (expiresAt <= nowMs)
+                    this.seen.delete(k);
+            }
+            const existing = this.seen.get(key);
+            if (existing !== undefined && existing > nowMs)
+                return true; // replay
+            this.seen.set(key, nowMs + ttlMs);
+            return false;
+        }
+    }
+    let replayStore;
+    if (requireMode !== 'none') {
+        replayStore = new InMemoryCliReplayStore();
+        process.stderr.write('[7h3] Replay protection is in-memory for this process only — it will not survive a ' +
+            'restart or a second instance. For production, use the library directly with a shared replayStore.\n');
+    }
     const gateway = createGateway({
         upstream: upstream,
         keyRegistry,
@@ -223,6 +293,7 @@ async function cmdGateway(argv) {
         privateKey,
         sender,
         defaultPolicy: requireMode === 'none' ? 'allow' : 'deny',
+        replayStore,
     });
     const server = createServer(async (req, res) => {
         const chunks = [];
@@ -252,6 +323,10 @@ async function cmdGateway(argv) {
             }
         });
     });
+    // Without this, a plain EADDRINUSE (an easy real-world mistake — the port
+    // is already in use) throws as an uncaught exception: a raw Node stack
+    // trace instead of this CLI's own clean `Error: ...` convention.
+    server.on('error', (err) => die(`gateway server: ${String(err)}`));
     server.listen(port, () => {
         process.stderr.write(`7h3 gateway listening on port ${port}\n`);
         process.stderr.write(`  upstream      : ${upstream}\n`);
@@ -274,6 +349,7 @@ async function cmdGateway(argv) {
                 res.end('Not Found');
             }
         });
+        metricsServer.on('error', (err) => die(`metrics server: ${String(err)}`));
         metricsServer.listen(metricsPort, () => {
             process.stderr.write(`7h3 metrics listening on :${metricsPort}/metrics\n`);
         });
@@ -318,6 +394,7 @@ async function cmdKeysServe(argv) {
             res.end('Not Found');
         }
     });
+    server.on('error', (err) => die(`key server: ${String(err)}`));
     server.listen(port, () => {
         process.stderr.write(`7h3 key server listening on port ${port}\n`);
         process.stderr.write(`  GET /.well-known/7h3-keys\n`);
@@ -328,8 +405,81 @@ async function cmdKeysServe(argv) {
     });
 }
 // ─── 7h3 add ───────────────────────────────────────────────────────────────────
-const ADD_FRAMEWORKS = ['cloudflare-worker', 'nextjs', 'express', 'hono', 'fastify', 'claude-code', 'opencode', 'codex', 'grok'];
+const ADD_FRAMEWORKS = ['webmcp', 'cloudflare-worker', 'nextjs', 'express', 'hono', 'fastify', 'claude-code', 'opencode', 'codex', 'grok'];
 const FRAMEWORK_SNIPPETS = {
+    webmcp: (sender) => `// 7h3 — signed, capability-scoped WebMCP tools
+// Install: npm install @7h3/protocol-webmcp @7h3/protocol
+//
+// WebMCP requires a secure context (HTTPS) and tools must be registered in the
+// TOP-LEVEL page — tools inside an iframe are not discoverable by agents.
+
+import { guard, isWebMcpSupported } from '@7h3/protocol-webmcp'
+import { generateEd25519KeypairBase64Url } from '@7h3/protocol'
+
+if (isWebMcpSupported()) {
+  // Per-session key: fine for signing this visitor's grants and receipts. The
+  // manifest is signed separately, at deploy time, by a key the browser never sees.
+  const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+
+  const g = guard({
+    origin: ${JSON.stringify(sender)},
+    privateKey,
+    publicKey,
+    onConfirm: async (tool, input) =>
+      window.confirm(\`Allow \${tool.name}?\\n\\n\${JSON.stringify(input, null, 2)}\`),
+  })
+
+  // An unguarded read: no scope, so no grant is required.
+  await g.registerTool({
+    name: 'search_items',
+    description: 'Search the catalog',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+    execute: async ({ query }) => searchItems(String(query)),
+  })
+
+  // A guarded write. \`scope\` gates it behind a capability; \`limit\` is a ceiling
+  // this site will never exceed, whatever a grant says.
+  await g.registerTool({
+    name: 'place_order',
+    description: 'Place an order for the current cart',
+    inputSchema: {
+      type: 'object',
+      properties: { cartId: { type: 'string' }, amountCents: { type: 'number' } },
+      required: ['cartId', 'amountCents'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true },
+    scope: 'orders/place',
+    limit: { field: 'amountCents', max: 500_00 },
+    confirm: true,
+    execute: async ({ cartId }) => placeOrder(String(cartId)),
+  })
+
+  // Wire this to a consent control in your own UI — never grant automatically.
+  // The token is held page-side, so it never passes through the agent.
+  document.querySelector('#allow-agent')?.addEventListener('click', async () => {
+    await g.grant({
+      subject: 'browser-agent',
+      scopes: ['orders/place'],
+      caps: { amountCents: 100_00 },  // bound inside the signed token
+      ttlMs: 10 * 60_000,             // authority lapses on its own
+    })
+  })
+
+  // Every call — allowed and refused — lands on a hash-chained signed log.
+  g.on((event) => {
+    if (event.type === 'call') {
+      console.log(event.receipt.outcome, event.receipt.tool, event.receipt.reason ?? '')
+    }
+  })
+}
+`,
     'cloudflare-worker': (sender) => `// cloudflare/src/worker.ts — 7h3 Gateway Worker
 // Install: npm install @7h3/protocol
 // See: cloudflare/DEPLOY.md for full setup

package/cborCodec.d.ts

@@ -21,11 +21,24 @@ export declare class CborEncoder {
     private _encodeHeadBytes;
     private _concat;
 }
+/**
+ * Maximum nesting depth accepted while decoding.
+ *
+ * RFC 8949 §10 calls this out explicitly: a decoder that recurses per nesting
+ * level turns a handful of attacker bytes into a stack overflow. `0x81` is
+ * "array of 1", so 50 KB of repeated `0x81` nests 50 000 deep and blows the
+ * stack — and CBOR arrives straight off the wire through the HTTP binding.
+ * 64 is far beyond any real envelope, which nests a handful of levels at most.
+ */
+export declare const MAX_CBOR_DEPTH = 64;
 export declare class CborDecoder {
     private data;
     private offset;
+    private depth;
     decode(data: Uint8Array): unknown;
+    /** Depth-counting wrapper around the recursive decode body. */
     private _decode;
+    private _decodeItem;
     private _decodeUint;
     private _readByte;
     private _readBytes;

package/gateway.d.ts

@@ -46,13 +46,31 @@ export type GatewayVerifyOutcome = {
     envelopeId?: string;
 } | {
     ok: false;
-    status: 401 | 403 | 429;
+    status: 400 | 401 | 403 | 429;
     reason: string;
 };
+/**
+ * Normalize a request path before it's used for both policy matching and
+ * upstream forwarding. Without this, a path like `/public/../admin/secret`
+ * matches a permissive `/public/**` policy (or no policy at all, under
+ * `defaultPolicy: 'allow'`) as a literal string, is forwarded unverified,
+ * and then gets collapsed by the URL parser inside `fetch()` on the way out
+ * — landing on `/admin/secret` at the upstream with zero verification ever
+ * having been performed against the path that's actually reached. Matching
+ * and forwarding must both operate on the same fully-normalized path so
+ * there's no gap between what was checked and what was sent.
+ *
+ * Returns null for anything that isn't a clean absolute path — including a
+ * `..` that would escape above the root, or percent-encoding that doesn't
+ * settle after a bounded number of decode passes (double-encoding is a
+ * classic way to smuggle a traversal past a single decode).
+ */
+export declare function normalizeGatewayPath(rawPath: string): string | null;
 declare class Protocol7h3Gateway {
     private config;
     private rateLimiter;
     constructor(config: GatewayConfig);
+    private checkSenderAndRateLimit;
     verify(req: GatewayRequest): Promise<GatewayVerifyOutcome>;
     handle(req: GatewayRequest): Promise<GatewayResponse>;
     getRateLimiter(): SlidingWindowRateLimiter;