@parmanasystems/server 1.0.19

package/README.md

@@ -0,0 +1,407 @@
+# @parmanasystems/server
+
+Fastify REST API server for the parmanasystems deterministic governance runtime.
+
+[![npm](https://img.shields.io/npm/v/@parmanasystems/server)](https://www.npmjs.com/package/@parmanasystems/server)
+
+---
+
+## Overview
+
+`@parmanasystems/server` is an HTTP wrapper over `@parmanasystems/execution`. It exposes the governance execution pipeline over a REST API so that any language or platform can execute and independently verify governance decisions without embedding the TypeScript SDK directly.
+
+---
+
+## Installation
+
+```bash
+npm install @parmanasystems/server
+```
+
+---
+
+## Quick start
+
+```bash
+# Start with default ephemeral Ed25519 keypair (development)
+npx Parmana-server
+
+# Start with persistent keys from environment variables
+Parmana_PRIVATE_KEY="$(cat private.pem)" Parmana_PUBLIC_KEY="$(cat public.pem)" npx Parmana-server
+
+# Enable API key authentication
+Parmana_API_KEY=my-secret-key npx Parmana-server
+```
+
+The server listens on `http://0.0.0.0:3000` by default.
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PORT` | No | HTTP port (default: `3000`) |
+| `HOST` | No | Bind address (default: `0.0.0.0`) |
+| `Parmana_API_KEY` | No | When set, all routes require `Authorization: Bearer <key>` |
+| `Parmana_PRIVATE_KEY` | No | PEM-encoded Ed25519 private key for signing |
+| `Parmana_PUBLIC_KEY` | No | PEM-encoded Ed25519 public key for verification |
+
+When `Parmana_PRIVATE_KEY` and `Parmana_PUBLIC_KEY` are absent, the server generates an ephemeral Ed25519 keypair on startup. This is suitable for development but means attestations cannot be verified after a restart.
+
+---
+
+## API routes
+
+### `GET /health`
+
+Returns runtime status, version, and per-subsystem health checks.
+
+```bash
+curl http://localhost:3000/health
+```
+
+```json
+{
+  "status": "ok",
+  "version": "1.2.3",
+  "timestamp": "2026-05-03T10:00:00.000Z",
+  "checks": {
+    "runtime_manifest": "ok",
+    "signing_key": "ok",
+    "audit_db": "unconfigured"
+  }
+}
+```
+
+**`status`** is `"ok"` when all checks are `"ok"` or `"unconfigured"`. It is `"degraded"` if any check is `"error"` or `"unavailable"`. The HTTP status code is always `200` — callers decide how to act on a degraded response.
+
+**Check values:**
+
+| Check | Values | Meaning |
+|---|---|---|
+| `runtime_manifest` | `ok` / `error` | Whether `getRuntimeManifest()` succeeds |
+| `signing_key` | `ok` / `unconfigured` | `Parmana_PRIVATE_KEY` env var set, or dev key on disk |
+| `audit_db` | `ok` / `unavailable` / `unconfigured` | DB reachable / unreachable / `AUDIT_DATABASE_URL` not set |
+
+---
+
+### `POST /execute`
+
+Runs the deterministic governance runtime and returns a signed `ExecutionAttestation`.
+
+**Request body validation:**
+
+| Field | Type | minLength | maxLength | Pattern |
+|---|---|---|---|---|
+| `policy_id` | string | 1 | 128 | `^[a-zA-Z0-9_-]+$` |
+| `policy_version` | string | 1 | 32 | `^v?\d+(\.\d+){0,2}([-+][\w.-]+)?$` |
+| `decision_type` | string | 1 | 64 | `^[a-zA-Z0-9_-]+$` |
+| `signals_hash` | string | 64 | 64 | `^[0-9a-f]{64}$` |
+
+Extra fields not listed above are rejected with `400 Bad Request` (`additionalProperties: false`).
+
+```bash
+curl -X POST http://localhost:3000/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "policy_id":      "loan-approval",
+    "policy_version": "v1",
+    "decision_type":  "approve",
+    "signals_hash":   "a3f1e2d4b5c6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
+  }'
+```
+
+```json
+{
+  "result": {
+    "execution_id":    "550e8400-e29b-41d4-a716-446655440000",
+    "policy_id":       "loan-approval",
+    "policy_version":  "v1",
+    "schema_version":  "1.0.0",
+    "runtime_version": "1.0.0",
+    "runtime_hash":    "a1b2c3...",
+    "decision":        "approve",
+    "signals_hash":    "a3f1e2d4b5c6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
+    "executed_at":     "2025-05-02T10:00:00.000Z"
+  },
+  "signature": "base64-encoded-Ed25519-signature"
+}
+```
+
+**Error responses:**
+
+| Status | Meaning |
+|---|---|
+| `400` | Missing required fields, failed pattern/length validation, or unexpected fields |
+| `422` | Execution failed (token expired, replay detected, etc.) |
+
+---
+
+### `POST /verify`
+
+Independently verifies an `ExecutionAttestation`. Pass the response from `POST /execute` directly.
+
+```bash
+curl -X POST http://localhost:3000/verify \
+  -H "Content-Type: application/json" \
+  -d '{ "result": { ... }, "signature": "..." }'
+```
+
+```json
+{
+  "valid": true,
+  "checks": {
+    "signature_verified": true,
+    "runtime_verified":   true,
+    "schema_compatible":  true
+  }
+}
+```
+
+**Error responses:**
+
+| Status | Meaning |
+|---|---|
+| `400` | Malformed attestation body |
+| `422` | Verification threw an unexpected error |
+
+---
+
+### Audit routes (requires `AUDIT_DATABASE_URL`)
+
+When `AUDIT_DATABASE_URL` is configured, five read-only audit query routes are registered:
+
+| Route | Description |
+|---|---|
+| `GET /audit/decisions` | Decision timeline. Query params: `limit` (default 100), `offset`, `policy_id`, `decision`, `from`, `to` |
+| `GET /audit/decisions/:executionId` | Single decision row with full `ExecutionAttestation` JSONB |
+| `GET /audit/security` | Security event dashboard. Query params: `from`, `to`, `limit` |
+| `GET /audit/stats` | Aggregate counts: total decisions, decisions today, verifications, security events, API calls |
+| `GET /audit/verifications/:executionId` | All verification attempts for an execution, newest first |
+
+All audit routes return `404` if the database is not configured.
+
+---
+
+### Stub endpoints (501 Not Implemented)
+
+These endpoints are defined in the OpenAPI spec and will be implemented in future releases:
+
+| Endpoint | Description |
+|---|---|
+| `GET /runtime/manifest` | Returns the signed bundle manifest for the active runtime |
+| `GET /runtime/capabilities` | Lists runtime capabilities |
+| `POST /evaluate` | Dry-run policy evaluation without attestation |
+| `POST /simulate` | Full simulation mode — no side effects |
+
+---
+
+## Rate limits
+
+All routes are rate-limited per API key (when `Parmana_API_KEY` is set) or per client IP (in dev mode).
+
+| Route | Limit |
+|---|---|
+| `POST /execute` | 100 req/min |
+| `POST /verify` | 200 req/min |
+| `GET /audit/*` | 60 req/min |
+| `GET /health` | 300 req/min |
+| `GET /runtime/*` | 60 req/min |
+| `POST /evaluate` | 60 req/min |
+| `POST /simulate` | 60 req/min |
+
+When authenticated, the rate limit key is `sha256(Parmana_API_KEY)`. In dev mode (no `Parmana_API_KEY`), the key falls back to `X-Forwarded-For` → `X-Real-IP` → socket IP.
+
+Every response includes rate limit headers:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 99
+X-RateLimit-Reset: 1714640460
+```
+
+**Payload size limits** (enforced independently of rate limits):
+
+| Route | Max body |
+|---|---|
+| `POST /execute` | 64 KB |
+| `POST /verify` | 64 KB |
+| `POST /evaluate` | 64 KB |
+| `POST /simulate` | 64 KB |
+| All other routes | 1 MB (global default) |
+
+Requests exceeding the limit receive `413 Payload Too Large`. GET routes carry no body so no limit applies.
+
+When a rate limit is exceeded the server responds with `429 Too Many Requests`:
+
+```json
+{
+  "error": "Rate limit exceeded",
+  "limit": 100,
+  "remaining": 0,
+  "reset": 1714640460
+}
+```
+
+---
+
+## CORS
+
+Cross-origin requests are controlled via the `CORS_ORIGIN` environment variable.
+
+| `CORS_ORIGIN` value | Behaviour |
+|---|---|
+| _(not set)_ | Allow `http://localhost:5173` and `http://localhost:8080` (dev default) |
+| `http://localhost:5173,https://app.example.com` | Allow those two origins only |
+| `*` | Reflect any request origin (allows all — use with care in production) |
+
+```bash
+# Single origin
+CORS_ORIGIN=https://app.example.com
+
+# Multiple origins (comma-separated, no spaces)
+CORS_ORIGIN=https://app.example.com,https://admin.example.com
+```
+
+**`credentials: true`** is set on all CORS responses. This means browsers will include cookies and `Authorization` headers on cross-origin requests. When using `CORS_ORIGIN=*`, the server reflects the specific request origin rather than sending a literal `*` so that credentials continue to work.
+
+Allowed methods: `GET`, `POST`.  
+Allowed request headers: `Content-Type`, `Authorization`, `X-Request-ID`.  
+Exposed response headers: `X-Request-ID`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.  
+Preflight cache (`Access-Control-Max-Age`): **86400 s** (24 h).
+
+---
+
+## Security headers
+
+All responses include the following HTTP security headers, set via [`@fastify/helmet`](https://github.com/fastify/fastify-helmet):
+
+| Header | Value | Purpose |
+|---|---|---|
+| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` | Blocks all resource loading and framing — this is a pure API, not a browser app |
+| `Cross-Origin-Resource-Policy` | `cross-origin` | Allows cross-origin reads (needed for browser clients consuming the API) |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` | Enforces HTTPS for 1 year across all subdomains; eligible for HSTS preload list |
+| `X-Content-Type-Options` | `nosniff` | Prevents MIME-type sniffing |
+| `X-Frame-Options` | `DENY` | Blocks the response from being embedded in a frame |
+| `X-DNS-Prefetch-Control` | `off` | Disables DNS prefetching |
+| `Referrer-Policy` | `no-referrer` | Suppresses the `Referer` header on all requests |
+| `X-Download-Options` | `noopen` | Prevents IE from executing downloaded files in the browser context |
+| `X-XSS-Protection` | `0` | Disables the legacy XSS auditor (modern browsers ignore it; CSP is the correct control) |
+| `X-Powered-By` | _(removed)_ | Suppressed to avoid leaking server technology |
+
+`Cross-Origin-Embedder-Policy` is intentionally disabled — it would block cross-origin API requests from browser clients that have not opted in to COEP.
+
+---
+
+## Graceful shutdown
+
+The server handles `SIGTERM` and `SIGINT` (Ctrl-C) with a clean, ordered shutdown:
+
+1. Stops accepting new connections (`app.close()`).
+2. Waits for in-flight requests to complete.
+3. Closes the PostgreSQL audit pool (`auditDb.disconnect()`), if configured.
+4. Logs `"Server closed cleanly"` and exits `0`.
+
+If shutdown takes longer than **10 seconds** the process force-exits with code `1` and logs `"Graceful shutdown timed out, forcing exit"`. The timeout is `unref()`-ed so it does not extend the process lifetime on its own.
+
+```
+SIGTERM/SIGINT
+  └─ app.close()         — drain in-flight HTTP requests
+  └─ auditDb.disconnect() — close postgres pool (if configured)
+  └─ process.exit(0)
+```
+
+---
+
+## Logging
+
+The server uses [pino](https://getpino.io/) structured JSON logging via Fastify.
+
+### Log level
+
+| `LOG_LEVEL` | Default |
+|---|---|
+| `trace` / `debug` / `info` / `warn` / `error` / `fatal` | `debug` in development, `info` in production |
+
+Set `NODE_ENV=production` or `LOG_LEVEL=info` to suppress debug output. `LOG_LEVEL` takes priority over `NODE_ENV`.
+
+### Request ID (`X-Request-ID`)
+
+Every request gets a unique ID. The server:
+
+- Reuses `X-Request-ID` from the incoming request if present.
+- Generates a `crypto.randomUUID()` otherwise.
+- Echoes the ID back in the `X-Request-ID` response header.
+- Includes `reqId` in every structured log line for that request.
+
+```bash
+curl -H "X-Request-ID: my-trace-id" http://localhost:3000/health
+# Response header: X-Request-ID: my-trace-id
+```
+
+### Redacted fields
+
+The following fields are replaced with `[REDACTED]` in all log output:
+
+| Field | Why |
+|---|---|
+| `req.headers.authorization` | Bearer token must not appear in logs |
+| `req.body.signature` | Ed25519 signature is key material |
+| `req.body.attestation.signature` | Nested signature in verify requests |
+
+### Structured log events
+
+| Event | Level | Fields |
+|---|---|---|
+| Governance decision executed | `info` | `reqId`, `policy_id`, `policy_version`, `decision_type` |
+| Governance decision failed | `warn` | `reqId`, `error` |
+| Attestation verified | `info` | `reqId`, `valid`, `checks` |
+| Authentication failure | `warn` | `reqId`, `reason: "auth_failure"` |
+
+---
+
+## Authentication
+
+When `Parmana_API_KEY` is set, all requests must include:
+
+```
+Authorization: Bearer <your-api-key>
+```
+
+Requests without a valid bearer token receive `401 Unauthorized`.
+
+When `Parmana_API_KEY` is unset, the auth hook is disabled. This is the default development mode.
+
+---
+
+## OpenAPI specification
+
+The full OpenAPI 3.0.3 specification is available at [`openapi.json`](../../openapi.json) in the repository root.
+
+To regenerate it:
+
+```bash
+npx tsx scripts/export-openapi.ts
+```
+
+---
+
+## Programmatic usage
+
+```ts
+import { createServer } from "@parmanasystems/server";
+
+const { app, auditDb } = await createServer();
+await app.listen({ port: 3000, host: "0.0.0.0" });
+
+// On shutdown:
+// await auditDb?.disconnect();
+// await app.close();
+```
+
+---
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import * as node_http from 'node:http';
+import * as fastify from 'fastify';
+
+declare const app: fastify.FastifyInstance<fastify.RawServerDefault, node_http.IncomingMessage, node_http.ServerResponse<node_http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>;
+declare function startServer(): Promise<void>;
+
+export { app, startServer };