@govplane/runtime-sdk 0.2.4

package/README.md

@@ -0,0 +1,365 @@
+# @govplane/runtime-sdk
+
+Official **Govplane Runtime SDK** for Node.js.
+
+The Govplane Runtime SDK is a **secure, production-grade client and policy engine** designed to consume **precompiled runtime governance bundles** and evaluate decisions **locally**, with **zero PII**, no exposed endpoints, and minimal operational risk.
+
+It is intended for backend services, workers, gateways, and critical paths that must react to policy changes in near real-time without delegating decisions to a remote service.
+
+---
+
+## Design Principles
+
+- 🔒 **No exposed endpoints** – no middleware, no inbound surface
+- 🧠 **Local-first evaluation** – decisions are made in-process
+- 🧼 **Zero PII by design** – strict context validation and allowlists
+- 📦 **Precompiled policies** – no DSL or dynamic code at runtime
+- 🧩 **Deterministic outcomes** – same input, same decision
+- ⚡ **Cheap polling** – HEAD + ETag + conditional GET
+- 🧯 **Failure-safe** – backoff, degraded mode, deny-by-default
+
+---
+
+## Key Capabilities
+
+### Runtime Client
+- Efficient **HEAD-first polling** using `ETag` and `If-None-Match`
+- In-memory bundle cache
+- Automatic request de-duplication
+- Configurable polling interval
+- **Burst mode** for incident response
+- **Exponential backoff with jitter**
+- Automatic **degraded state**
+- Status subscriptions (`ok` / `degraded`)
+
+### Policy Engine (SDK-only)
+- Supports:
+  - `allow`
+  - `deny`
+  - `kill_switch`
+  - `throttle`
+- **Deny-by-default**
+- Kill-switch always wins
+- Throttle selects the **most restrictive rule**
+- Deterministic rule ordering
+- Precompiled `when` AST evaluation
+- No dynamic evaluation or code execution
+
+### Security & Context Safety
+- Explicit context allowlist
+- Unknown keys rejected (PII protection)
+- Configurable limits:
+  - max string length
+  - max array length
+  - max depth
+- Context policy is fully configurable per engine
+
+### Decision Trace / Explain (SDK-only)
+- Optional decision trace generation
+- Compact or full trace modes
+- Sampling support (e.g. 1% in production)
+- Force tracing for debugging
+- Structured JSON trace output
+- **Async trace sinks** (fire-and-forget)
+- Bounded queues with drop strategies
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18**
+- A valid **Govplane Runtime Key**
+- Access to a Govplane Runtime API (`gp-runtime`)
+
+---
+
+## Installation
+
+```bash
+npm install @govplane/runtime-sdk
+```
+
+---
+
+## Quick Start
+
+### 1. Create a Runtime Client
+
+```ts
+import { RuntimeClient } from "@govplane/runtime-sdk";
+
+const client = new RuntimeClient({
+  baseUrl: "https://runtime.govplane.com",
+  runtimeKey: process.env.GP_RUNTIME_KEY!,
+  orgId: "org_dev",
+  projectId: "prj_web",
+  env: "prod"
+});
+
+client.start();
+```
+
+### 2. Create a Policy Engine
+
+```ts
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+
+const engine = createPolicyEngine({
+  getBundle: () => client.getCached().bundle,
+  validateContext: true,
+  contextPolicy: {
+    allowedKeys: [
+      "ctx.plan",
+      "ctx.country",
+      "ctx.amount",
+      "ctx.isAuthenticated"
+    ],
+    maxStringLen: 64,
+    maxArrayLen: 10
+  }
+});
+```
+
+### 3. Evaluate a Decision
+
+```ts
+const result = engine.evaluate({
+  target: {
+    service: "payments",
+    resource: "checkout",
+    action: "create"
+  },
+  context: {
+    plan: "pro",
+    country: "ES",
+    amount: 42,
+    isAuthenticated: true
+  }
+});
+
+console.log(result.decision); // allow | deny | throttle | kill_switch
+```
+
+---
+
+## Runtime Bundle Model
+
+The SDK retrieves **materialized runtime bundles** generated by Govplane.
+
+```ts
+type RuntimeBundleV1 = {
+  schemaVersion: 1;
+  orgId: string;
+  projectId: string;
+  env: string;
+  generatedAt: string;
+  policies: unknown[];
+};
+```
+
+The bundle is treated as **immutable and read-only**.
+
+---
+
+## Polling & Burst Mode
+
+```ts
+// Force immediate refresh
+await client.refreshNow();
+
+// Temporarily increase polling frequency (e.g. incident response)
+await client.refreshNow({ burst: true });
+```
+
+Polling strategy:
+1. `HEAD /v1/runtime/bundle`
+2. Compare `ETag`
+3. If changed → `GET`
+4. If unchanged → no download, no JSON parse
+
+---
+
+## Backoff & Degraded Mode
+
+On repeated failures, the client:
+- Applies exponential backoff with jitter
+- Enters **degraded** state after N failures
+- Emits status updates
+
+```ts
+client.onStatus((status) => {
+  if (status.state === "degraded") {
+    console.warn("Runtime degraded:", status);
+  }
+});
+```
+
+In degraded mode, cached bundles remain active.
+
+---
+
+## Runtime Incident Controls
+
+During an incident (DDoS, fraud spike, abuse, misconfiguration), it may be necessary to:
+- Force faster policy propagation
+- Trigger immediate policy refresh
+- Temporarily increase polling frequency (“burst mode”)
+
+Govplane Runtime SDK provides **passive incident controls** that allow operators to react to incidents **without exposing endpoints**, **without handling PII**, and **without recompiling application code**.
+
+These controls are designed to be:
+- Local-only
+- Zero-network-surface
+- Safe under active attack
+- Compatible with containerized and orchestrated environments
+
+### Supported Incident Control Mechanisms
+
+| Mechanism | Restart Required | Network Surface | Hot | Recommended |
+|---------|------------------|-----------------|-----|-------------|
+| Environment Variable | Usually yes | None | ❌ | ✅ |
+| File-based Hot Reload | No | None | ✅ | ⭐ **Primary** |
+| POSIX Signal (SIGUSR1) | No | None | ✅ | Optional |
+
+---
+
+**Example: Environment Variable Incident Mode**
+
+If the following environment variable is set, the Runtime SDK automatically enters **incident mode**:
+
+```bash
+GP_RUNTIME_INCIDENT=1
+```
+
+When detected:
+	•	Burst polling is enabled
+	•	Refresh cadence increases
+	•	Degraded recovery is accelerated
+
+Notes
+	•	In most container platforms (ECS, Kubernetes), environment variables cannot be changed at runtime
+	•	A rolling restart is usually required
+	•	For zero-restart response, use File-based Hot Reload
+
+
+**More details: [Govplane Runtime SDK – Runtime Incident Controls](docs/operations/Govplane_Runtime_Incident_Controls.md)**
+
+---
+
+## Throttle Decisions
+
+```ts
+if (result.decision === "throttle") {
+  rateLimiter.apply(
+    result.throttle.key,
+    result.throttle.limit,
+    result.throttle.windowSeconds
+  );
+}
+```
+
+When multiple throttle rules match, the **most restrictive** one is selected.
+
+---
+
+## Decision Trace / Explain
+
+### Production (Sampled)
+
+```ts
+const out = engine.evaluateWithTrace(
+  { target, context },
+  { sampling: 0.01, mode: "compact" }
+);
+
+if (out.trace) {
+  console.log(out.trace.summary);
+}
+```
+
+### Debug (Forced)
+
+```ts
+engine.evaluateWithTrace(
+  { target, context },
+  { force: true, mode: "full" }
+);
+```
+
+### Trace Guarantees
+
+- No rule bodies
+- No context values
+- No PII
+- Deterministic structure
+
+---
+
+## Async Trace Sink
+
+```ts
+engine.setTraceSink(
+  createAsyncTraceSink({
+    maxQueue: 100,
+    drop: "drop_new",
+    sink: async (event) => {
+      await fetch("https://trace-endpoint", {
+        method: "POST",
+        body: JSON.stringify(event)
+      });
+    }
+  })
+);
+```
+
+The sink:
+- Never blocks evaluation
+- Never throws
+- Drops safely under pressure
+
+---
+
+## What This SDK Does NOT Do
+
+- ❌ No HTTP middleware
+- ❌ No inbound endpoints
+- ❌ No request interception
+- ❌ No PII handling
+- ❌ No policy authoring
+- ❌ No dynamic code execution
+
+---
+
+## Security Notes
+
+- Runtime keys are **read-only**
+- Keys are scoped by org / project / env
+- Bundles are immutable
+- SDK cannot modify state
+- Safe to embed in critical paths
+
+### Threat Model
+
+Please refer to the [Govplane Runtime SDK Threat Model & Security Guarantees](docs/security/Govplane_Threat_Model.md) for a detailed analysis.
+
+---
+
+## Performance Notes
+
+- Designed for second-level polling
+- Suitable for APIs, workers, gateways
+- Not intended for browser usage
+
+---
+
+## Versioning & Compatibility
+
+- Bundles are versioned (`schemaVersion`)
+- Current version: `RuntimeBundleV1`
+- Future versions will be backward-compatible
+
+---
+
+## License
+
+MIT © Govplane