@govplane/runtime-sdk 0.2.4 → 0.5.0

package/docs/usage/PolicyDefaults.md

@@ -0,0 +1,220 @@
+---
+description: >-
+  Configure a fallback effect at the policy level that fires when no rule
+  matches a given target.
+---
+
+# Policy Defaults
+
+## Overview
+
+Every policy can declare a `defaults` object. When **no rule within that policy produces a match** for the evaluated target, the engine applies the policy default as a lowest-priority synthetic decision.
+
+This removes the need for catch-all rules and makes deny-by-default, open-allow, or custom-fallback policies cleaner to express.
+
+---
+
+## How it works
+
+Policy defaults are internally treated as a synthetic rule with `priority = -1`. They are only considered when **zero rules** in the same policy matched the target (i.e. either no rule targeted that service/resource/action, or every candidate rule was disabled or had a `when_false` result with no `elseEffect`).
+
+Because the priority is `-1`, any explicit rule — including `when: false` cases where `elseEffect` is defined — will always win over a policy default.
+
+---
+
+## Bundle shape
+
+```json
+{
+  "policyKey":     "my-policy",
+  "activeVersion": 5,
+  "defaults": {
+    "effect": "<effect-type>",
+    ...effect-specific fields...
+  },
+  "rules": [...]
+}
+```
+
+---
+
+## All supported default effect types
+
+### `allow`
+
+All unmatched targets are allowed.
+
+```json
+{
+  "policyKey": "open-api",
+  "defaults":  { "effect": "allow" },
+  "rules": [
+    {
+      "id": "r_block_admin",
+      "status": "active",
+      "priority": 10,
+      "target": { "service": "api", "resource": "admin", "action": "delete" },
+      "effect": { "type": "deny" }
+    }
+  ]
+}
+```
+
+`admin/delete` → `deny` (matched rule).  
+Everything else → `allow` (policy default).
+
+---
+
+### `deny`
+
+All unmatched targets are denied. This is the most common pattern for strict allow-lists.
+
+```json
+{
+  "policyKey": "strict-rbac",
+  "defaults":  { "effect": "deny" },
+  "rules": [
+    {
+      "id": "r_allow_admins",
+      "status": "active",
+      "priority": 10,
+      "target": { "service": "control", "resource": "settings", "action": "write" },
+      "when": { "op": "in", "path": "role", "values": ["admin", "superuser"] },
+      "thenEffect": { "type": "allow" },
+      "effect": { "type": "deny" }
+    }
+  ]
+}
+```
+
+---
+
+### `throttle`
+
+All unmatched targets are throttled.
+
+```json
+{
+  "policyKey": "rate-limited-api",
+  "defaults": {
+    "effect": "throttle",
+    "throttle": { "limit": 100, "windowSeconds": 60, "key": "tenant" }
+  },
+  "rules": []
+}
+```
+
+Decision when no rules match:
+
+```typescript
+{
+  decision: "throttle",
+  reason: "default",
+  policyKey: "rate-limited-api",
+  throttle: { limit: 100, windowSeconds: 60, key: "tenant" }
+}
+```
+
+---
+
+### `kill_switch`
+
+All targets are immediately blocked — useful as an emergency circuit breaker pushed via bundle without a code deploy.
+
+```json
+{
+  "policyKey": "payments-circuit-breaker",
+  "defaults": {
+    "effect":     "kill_switch",
+    "killSwitch": { "service": "payments", "reason": "DB degradation — INC-4421" }
+  },
+  "rules": []
+}
+```
+
+Decision:
+
+```typescript
+{
+  decision:   "kill_switch",
+  reason:     "default",
+  policyKey:  "payments-circuit-breaker",
+  killSwitch: { service: "payments", reason: "DB degradation — INC-4421" }
+}
+```
+
+---
+
+### `custom`
+
+All unmatched targets return a custom string value. Useful for returning default feature-flag states.
+
+```json
+{
+  "policyKey": "feature-flags",
+  "activeVersion": 7,
+  "defaults": {
+    "effect":       "custom",
+    "customEffect": "{\"newDashboard\": false, \"aiSearch\": false}"
+  },
+  "rules": [
+    {
+      "id": "r_flags_enterprise",
+      "status": "active",
+      "priority": 10,
+      "target": { "service": "app", "resource": "features", "action": "read" },
+      "when": { "op": "eq", "path": "plan", "value": "enterprise" },
+      "thenEffect": {
+        "type": "custom",
+        "value": "{\"newDashboard\": true, \"aiSearch\": true}"
+      },
+      "effect": { "type": "deny" }
+    }
+  ]
+}
+```
+
+Enterprise users on the target → `custom` via rule.  
+All other users → `custom` via policy default (the `false` flags).  
+Unrelated targets (different service/resource/action) → policy default (`custom` with `false` flags).
+
+---
+
+## Decision fields when `reason === "default"`
+
+When a decision is produced by a policy default, the following applies:
+
+| Field | Value |
+|---|---|
+| `reason` | `"default"` |
+| `policyKey` | The policy whose default fired |
+| `ruleId` | `undefined` — no rule was involved |
+
+```typescript
+if (result.reason === "default") {
+  // fired from policy default or SDK's global deny-by-default
+  metrics.increment("decisions.default", { policy: result.policyKey ?? "global" });
+}
+```
+
+---
+
+## Global deny-by-default
+
+If **no policy has a matching rule or default** for the evaluated target, the SDK returns:
+
+```typescript
+{ decision: "deny", reason: "default" }  // policyKey is undefined
+```
+
+This is the SDK's last-resort fallback and requires no configuration.
+
+---
+
+{% content-ref url="Effects.md" %}
+[Effect Types](Effects.md)
+{% endcontent-ref %}
+
+{% content-ref url="ConditionalRules.md" %}
+[Conditional Rules](ConditionalRules.md)
+{% endcontent-ref %}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@govplane/runtime-sdk",
-  "version": "0.2.4",
-  "description": "Govplane Runtime SDK (Node/TS) with ETag caching + polling",
+  "version": "0.5.0",
+  "description": "Govplane Runtime SDK (Node/TS)",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,7 +34,5 @@
     "tsup": "^8.2.4",
     "typescript": "^5.6.3"
   },
-  "dependencies": {
-    "undici": "^7.18.2"
-  }
+  "dependencies": {}
 }