Refactor verify endpoint timeout handling and improve fetch robustness

.github/workflows/ci.yml

@@ -2,7 +2,9 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
+    branches: [main]
 
 jobs:
   checks:
@@ -20,6 +22,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+
       - name: Syntax check
         run: npm run check
 

.gitignore

@@ -1,2 +1 @@
 node_modules/
-*.json

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Greg Soucy (commandlayer.eth)
+
+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.

SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, email: **security@commandlayer.org**
+
+Please include:
+- A description of the vulnerability
+- Steps to reproduce the issue
+- Potential impact assessment
+- Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and provide a detailed response within 7 days.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | Yes       |
+
+## Security Considerations
+
+This runtime handles cryptographic signing and verification. Operators should:
+
+1. **Protect signing keys** -- never expose `RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64` in logs or client responses.
+2. **Gate debug routes** -- set `DEBUG_ROUTES_ENABLED=0` (default) in production, or protect with `DEBUG_BEARER_TOKEN`.
+3. **Restrict CORS** -- configure `CORS_ALLOW_ORIGINS` to specific origins; never use `*` in production.
+4. **Enable SSRF guard** -- keep `ENABLE_SSRF_GUARD=1` (default) and use `ALLOW_FETCH_HOSTS` to restrict outbound domains.
+5. **Use HTTPS** -- always deploy behind TLS termination in production.
+6. **Pin dependencies** -- use `npm ci` with the lockfile for reproducible builds.

docs/REVIEW.md

@@ -1,6 +1,6 @@
 # Engineering Review (Senior-level Scrutiny)
 
-Scope reviewed: `server.mjs`, packaging metadata, and top-level docs.
+Scope reviewed: `server.mjs`, packaging metadata, CI, and top-level docs.
 
 ## Executive summary
 
@@ -9,9 +9,7 @@ The runtime has strong foundational choices for a reference implementation:
 - signed receipts with canonicalized payload hashing,
 - bounded verification and schema compilation,
 - practical SSRF controls,
-- observability-oriented debug endpoints.
-
-Main gaps are operational/documentation maturity (now improved in this update), plus a few production hardening opportunities that should be addressed next.
+- observability-oriented debug endpoints (gated behind auth).
 
 ## What is strong
 
@@ -29,54 +27,50 @@ Main gaps are operational/documentation maturity (now improved in this update),
    - Timeout budgets on handler execution and verify endpoint.
    - Byte caps and SSRF checks on outbound fetch.
    - Verb allow/deny achieved via `ENABLED_VERBS`.
+   - Verify endpoint uses a `responded` guard to prevent double-response races.
 
 4. **Trace metadata model is sensible**
    - Distinguishes runtime execution `trace_id` from upstream `parent_trace_id`.
    - Supports legacy and modern parent-trace pass-through patterns.
 
-## Risks and recommendations
+5. **Security posture**
+   - CORS is configurable via `CORS_ALLOW_ORIGINS` (deny by default when unset).
+   - Debug routes gated behind `DEBUG_ROUTES_ENABLED` + optional `DEBUG_BEARER_TOKEN`.
+   - Request schema validation available via `REQUEST_SCHEMA_VALIDATION=1`.
 
-### High priority
+## Resolved issues
 
-1. **CORS is globally permissive (`*`)**
-   - Risk: browser-origin abuse if deployed on public endpoints.
-   - Recommendation: make allowed origins configurable; default deny in production.
+The following items from the prior review have been addressed:
 
-2. **Debug endpoints are publicly routable**
-   - `/debug/env` leaks detailed runtime config and posture.
-   - Recommendation: gate debug routes behind auth or environment flag; disable by default.
+| Issue | Resolution |
+|-------|-----------|
+| CORS globally permissive (`*`) | `CORS_ALLOW_ORIGINS` now configurable; empty = deny browser origins |
+| Debug endpoints publicly routable | Gated behind `DEBUG_ROUTES_ENABLED` (default off) + bearer token |
+| No request schema validation | `REQUEST_SCHEMA_VALIDATION` toggle added |
+| Stale `dev:commercial` script | Removed |
+| Missing LICENSE | MIT license added |
+| Missing SECURITY.md | Added |
+| `.gitignore` blocks `*.json` | Fixed to only ignore `node_modules/` |
+| npm audit vulnerability (qs) | Patched via `npm audit fix` |
+| Verify endpoint double-response race | Rewritten with `responded` guard |
+| `doFetch` body double-consumption | Fixed reader/fallback logic |
 
-3. **`fetch` response headers are reflected into receipt**
-   - Could include sensitive metadata from upstream resources.
-   - Recommendation: optionally redact/allowlist stored headers.
+## Remaining considerations
 
 ### Medium priority
 
-4. **No explicit request schema validation for verb inputs**
-   - Current behavior depends on handler-level checks.
-   - Recommendation: optionally validate request payloads with published request schemas.
+1. **`fetch` response headers are reflected into receipt**
+   - Could include sensitive metadata from upstream resources.
+   - Consider: optionally redact/allowlist stored headers.
 
-5. **Single-process in-memory caches**
+2. **Single-process in-memory caches**
    - Functional but inconsistent across replicas.
-   - Recommendation: keep as-is for reference runtime, but document multi-replica prewarm requirement (added).
-
-6. **Package script references non-existent file**
-   - `dev:commercial` points to `commercial.server.mjs` which is not present.
-   - Recommendation: remove or correct script to avoid CI/developer confusion.
-
-## Suggested next backlog (ordered)
-
-1. Add `DEBUG_ROUTES_ENABLED` + optional bearer token for `/debug/*`.
-2. Add `CORS_ALLOW_ORIGINS` with explicit production defaults.
-3. Add request schema validation toggle (`REQUEST_SCHEMA_VALIDATION=1`).
-4. Add minimal automated smoke tests for:
-   - signer readiness,
-   - one verb execution,
-   - verify hash/signature pass/fail paths.
-5. Clean package scripts and add CI lint/check workflow.
+   - Documented in OPERATIONS.md (warm each replica independently).
 
-## Documentation changes delivered in this update
+## Documentation delivered
 
-- Rewrote README for onboarding, API surface, verification semantics, and production context.
-- Added dedicated configuration reference.
-- Added operations runbook for deploy/troubleshooting/prewarm workflows.
+- README: onboarding, API surface, verification semantics, production context.
+- `docs/CONFIGURATION.md`: full environment variable reference.
+- `docs/OPERATIONS.md`: deploy checklist, troubleshooting, prewarm workflows.
+- `SECURITY.md`: vulnerability reporting and hardening guidance.
+- `LICENSE`: MIT (matches protocol-commons).

package.json

@@ -1,8 +1,17 @@
 {
   "name": "@commandlayer/runtime",
   "version": "1.0.0",
+  "description": "Reference Node.js runtime for CommandLayer Commons verbs — deterministic execution, Ed25519-signed receipts, and ENS-based verification.",
   "private": true,
   "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commandlayer/runtime.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
     "start": "node server.mjs",
     "check": "node --check server.mjs",