Add dependency-free local API server

Author: Flow Memory Builder

BUILD_REPORT.md

@@ -278,3 +278,8 @@ RC1 validation updates:
 ## Neural Agent Layer v1 build update — 2026-05-23
 
 Added optional neural subsystem, synthetic datasets, tiny dual-stream perception, predictive world model, advisory plan/skill/risk/evaluation scoring, neural memory retrieval, tiny training smoke scripts, V-JEPA 2 / VideoMAE adapter seams, CLI `--neural`, FlowLang neural config, neural examples, neural benchmarks, and documentation. PyTorch remains optional and default tests skip torch-only behavior when absent.
+
+
+## Dependency-free local HTTP API server update — 2026-05-23
+
+Added `src/flow_memory/api/http_server.py` and `scripts/run_local_api_server.py` to expose the internal API router through a standard-library local HTTP server. The gateway covers JSON parsing, API-key checks, optional scope enforcement, local fixed-window rate limiting, request audit events, and structured API errors. Added `tests/test_api_http_server.py` for direct gateway behavior plus an ephemeral localhost request. This remains a local/public-alpha server boundary, not production internet auth or deployment infrastructure.

FLOW_MEMORY_STATUS.md

@@ -47,6 +47,7 @@ It is not production-certified. Contracts are unaudited, sandboxing is not harde
 | API snapshot validation | Implemented and committed as `docs/API_SNAPSHOT.json` |
 | API auth/signed requests | Local API-key and HMAC signed-request seam tested; not production auth |
 | API scopes/errors/rate limits/audit middleware | Functional local prototype; not production auth |
+| Dependency-free local HTTP API server | Implemented local/public-alpha server with API-key, scopes, rate limits, error contracts, and audit events; not production internet auth |
 | Base Sepolia dry run | Implemented no-key/no-funds artifact set and validator |
 | ERC-4337 adapter | UserOperation dry-run schema tested locally |
 | Contract registry validation | Implemented address, required-contract, and zero-address checks |

README.md

@@ -136,3 +136,8 @@ Observed during the public-alpha RC1 preflight build:
 ## Neural Agent Layer v1
 
 Flow Memory now includes an optional Neural Agent Layer v1. The base install still has no PyTorch requirement. Install `flow-memory[ml]` to run tiny CPU-safe PyTorch prototypes for dual-stream perception, appearance-suppressed dorsal motion, tiny JEPA-style world modeling, advisory plan scoring, skill routing, risk scoring, and neural memory retrieval. V-JEPA 2 and VideoMAE are adapter seams that require explicit local checkpoints; Flow Memory never downloads checkpoints automatically. Neural scores never override policy or approval gates.
+
+
+## Local HTTP API server
+
+Flow Memory now includes a dependency-free local HTTP API server for public-alpha operator testing. Run it with `python scripts/run_local_api_server.py --host 127.0.0.1 --port 8765`. Add `--api-key dev-local-only --require-scopes` to exercise local API-key and scope gates. This is not production internet authentication; it is a local server boundary for smoke tests, demos, and preflight tools.

docs/API.md

@@ -1,6 +1,6 @@
 # Flow Memory API
 
-Flow Memory has a dependency-free internal router plus optional server seams.
+Flow Memory has a dependency-free internal router, a dependency-free local HTTP server, and optional server seams.
 
 ## Local router
 
@@ -60,16 +60,32 @@ python scripts/export_api_snapshot.py --write docs/API_SNAPSHOT.json
 
 Use `validate_api_snapshot()` in release checks to detect accidental endpoint drift.
 
+## Dependency-free local HTTP server
+
+`src/flow_memory/api/http_server.py` wraps the internal router with JSON parsing, local API-key checks, optional scope enforcement, rate limiting, audit events, and the standard API error contract.
+
+Run it locally:
+
+```bash
+python scripts/run_local_api_server.py --host 127.0.0.1 --port 8765
+```
+
+With local preflight auth:
+
+```bash
+python scripts/run_local_api_server.py --api-key dev-local-only --require-scopes
+```
+
 ## Auth seams
 
 - `src/flow_memory/api/auth.py` implements local API-key checking seam.
 - `src/flow_memory/api/signed_requests.py` implements signed request test seam.
 - DID request signatures are a documented placeholder, not production auth.
 
-## Optional server
+## Optional FastAPI server
 
 `src/flow_memory/api/server.py` exposes a FastAPI server creation seam when FastAPI is installed. FastAPI is not required by the base test suite.
 
 ## Status
 
-The internal router, OpenAPI generation, signed request seam, and API snapshot validation are tested. Production server deployment, rate limiting, auth hardening, and public networking remain future work.
+The internal router, dependency-free HTTP server boundary, OpenAPI generation, signed request seam, API auth/scope/rate-limit checks, and API snapshot validation are tested. Production server deployment, replay protection, TLS termination, tenant isolation, and public networking remain future work.

docs/API_SERVER.md

@@ -1,38 +1,65 @@
 # API Server Seam
 
-Status: local router plus optional FastAPI seam; not a hardened public server.
+Status: dependency-free local HTTP server plus internal router and optional FastAPI seam; not a hardened public server.
 
 ## Purpose
 
-Define the boundary between Flow Memory's in-process API manifest/router and any future network-facing service. The seam keeps endpoint shape, handler dispatch, and generated OpenAPI-like metadata testable without requiring a daemon, reverse proxy, database, or cloud service.
+Define the boundary between Flow Memory's in-process API manifest/router and any future network-facing service. The local HTTP server gives operators a concrete public-alpha loop for health checks, scoped local API calls, JSON error contracts, request audit events, and fixed-window rate-limit testing without adding FastAPI or cloud infrastructure to the base install.
+
+## Local HTTP server
+
+Run the dependency-free local server:
+
+```bash
+python scripts/run_local_api_server.py --host 127.0.0.1 --port 8765
+```
+
+With a local development API key and scope checks:
+
+```bash
+python scripts/run_local_api_server.py --api-key dev-local-only --require-scopes
+```
+
+Example request:
+
+```bash
+python - <<'PY'
+import json, urllib.request
+req = urllib.request.Request(
+    'http://127.0.0.1:8765/health',
+    headers={'x-flow-memory-api-key': 'dev-local-only', 'x-flow-memory-scopes': 'api:read'},
+)
+print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
+PY
+```
 
 ## Local-safe behavior
 
-- Default execution stays in process through the dependency-light router.
-- The endpoint manifest is the source of truth for route groups and handler names.
-- Optional FastAPI wiring may expose health and manifest routes when the dependency is installed.
-- Local handlers should use deterministic state, explicit inputs, and no hidden network calls.
+- Default execution can stay in process through `LocalApiRouter`.
+- `HttpApiGateway` wraps the router with JSON parsing, error contracts, optional API-key checks, optional scope enforcement, fixed-window local rate limiting, and audit events.
+- The endpoint manifest is still the source of truth for route groups and handler names.
+- Optional FastAPI wiring remains a separate application seam when the dependency is installed.
 - Value-bearing or externally visible operations must remain behind policy, approval, audit, and adapter boundaries.
 
 ## Auth seam
 
 - `src/flow_memory/api/auth.py` supports local API-key checks and an explicit signed-request decision helper.
 - Header matching is case-insensitive for `x-flow-memory-api-key`.
+- `src/flow_memory/api/http_server.py` enforces local API-key and scope decisions when configured.
 - Signed requests use the local development signing seam and verify method, path, and payload binding.
 - This is test coverage for the API boundary contract, not production authentication, replay protection, tenant isolation, or key custody.
 
-
 ## Limitations
 
 - Not production-authenticated or internet-facing.
-- API-key and signed-request helpers are local seams only; there is no production authorization model, session handling, replay protection, tenant isolation, rate-limit enforcement at the HTTP edge, or production observability.
+- API-key and signed-request helpers are local seams only; there is no production authorization model, session handling, replay protection, tenant isolation, distributed rate limiting, TLS termination, WAF, or production observability.
 - Optional FastAPI support is an application seam, not a deployment architecture.
 - Endpoint presence does not imply that downstream blockchain, MCP/A2A, libp2p, Redis, Qdrant, Neo4j, or OPA integrations are implemented.
 
 ## Next implementation steps
 
-1. Promote the manifest into generated OpenAPI with stable request/response schemas.
-2. Add authentication, authorization, replay protection, rate limits, and structured audit events at the server boundary.
-3. Bind each network route to explicit capability checks before handler execution.
-4. Add integration tests for HTTP behavior once the server contract is stable.
+1. Add stable request/response schema objects per endpoint.
+2. Add request signing/replay windows at the HTTP boundary.
+3. Add TLS/reverse-proxy deployment profiles.
+4. Add production observability hooks and structured access logs.
 5. Document deployment profiles separately for local development, private lab use, and audited production use.

release_evidence/bundle/index.json

@@ -1,13 +1,13 @@
 {
-  "bundle_hash": "8ac11903c39c504de8de4b0a2118db1fb6480f4c170041719d29ab9a1a4a3acd",
+  "bundle_hash": "6d6ab805d8055970c859baf1df118b0ad6bd87c22d716257255ff545273cc8e6",
   "file_hashes": {
     "api_snapshot.json": "da9a57cefb763e79404254cf146219eeab67960f0f1f1190dcc171729b8badf3",
     "base_artifacts.json": "48508bb9e1d31f01a687101dda8c8591fad2d5abb5a4cf70cbdc189f3638f01f",
     "base_deployment_plan.json": "f53cfe400d5fd425326c3a83b27a8adfb9c7eb3f4baa975ff7fab4b3ad844e0d",
     "clean_clone_validation.json": "5ec2708b78fc7041fafcbe4a4ed0f83ec5d8dbf914013c3f7b943f6a1664ff03",
     "dependency_inventory.json": "9819542e274c038b6ad5c1c07bfaff0806e2803f26c9a329f0d59d61360ffe83",
     "release_gates.json": "218cc98fb0a1b1ff6d4f7b2b037b9b8a93c2f5ef1fdd645809eb080c15062dfc",
-    "release_manifest.json": "323483e8d34711f7e02f150b33d166cb428cae08a17195b500f0199f8466629a",
+    "release_manifest.json": "c849c1ac4db5a70cfb1e9d635540174a42d8220fa5f00d308efd86b9c775b991",
     "storage_schema.json": "7417bed718a4783b050b61bc84f71b0351547b2a57462780641dd53d7b4885a7"
   },
   "files": [

release_evidence/bundle/release_manifest.json

@@ -255,8 +255,8 @@
   },
   "format": "flow-memory-release-manifest-v1",
   "git_branch": "main",
-  "git_commit": "948f70d",
-  "manifest_hash": "b7e5f6cd42a9f5b98e74f8d2f89accfc92845446f4b0557c137332454f3b69a1",
+  "git_commit": "e035a6b",
+  "manifest_hash": "0ec13810bf050587e94ea2e0f4a2421e85aaa844c760c55060e1b0c3ad89222f",
   "release_gates": {
     "ok": true,
     "results": [

scripts/run_local_api_server.py

@@ -0,0 +1,38 @@
+"""Run the dependency-free Flow Memory local HTTP API server."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from flow_memory.api.http_server import HttpApiConfig, serve_local_api
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run Flow Memory local HTTP API server")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--api-key", default="")
+    parser.add_argument("--require-scopes", action="store_true")
+    parser.add_argument("--rate-limit", type=int, default=120)
+    args = parser.parse_args()
+    config = HttpApiConfig(
+        host=args.host,
+        port=args.port,
+        api_key=args.api_key,
+        require_scopes=args.require_scopes,
+        rate_limit=args.rate_limit,
+    )
+    print(f"Flow Memory local API listening on http://{config.host}:{config.port}")
+    serve_local_api(config)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/flow_memory/api/__init__.py

@@ -1,15 +1,20 @@
 """Dependency-free local API surface."""
 
 from flow_memory.api.manifest import API_ENDPOINTS, EndpointSpec, endpoint_manifest
+from flow_memory.api.http_server import HttpApiConfig, HttpApiGateway, HttpApiResponse, create_http_server
 from flow_memory.api.router import LocalApiRouter, create_default_router
 from flow_memory.api.snapshot import api_snapshot, validate_api_snapshot
 
 __all__ = [
     "API_ENDPOINTS",
     "EndpointSpec",
+    "HttpApiConfig",
+    "HttpApiGateway",
+    "HttpApiResponse",
     "LocalApiRouter",
     "api_snapshot",
     "create_default_router",
+    "create_http_server",
     "endpoint_manifest",
     "validate_api_snapshot",
 ]