@7h3/protocol 0.5.4 → 0.5.6

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`);

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;