@govplane/runtime-sdk 0.2.4 → 0.5.0

package/docs/usage/ConditionalRules.md

@@ -0,0 +1,251 @@
+---
+description: >-
+  Use when / thenEffect / elseEffect to apply different effects based on
+  run-time context, without writing separate rules.
+---
+
+# Conditional Rules
+
+## Overview
+
+Every rule supports an optional `when` clause — a condition AST evaluated client-side against the `context` you supply at call time. The server compiles and distributes the AST as part of the bundle; it never executes it.
+
+**Effect resolution:**
+
+```
+when is absent          → always apply effect
+when evaluates to true  → apply thenEffect   (fallback: effect)
+when evaluates to false → apply elseEffect   (fallback: skip rule entirely)
+```
+
+---
+
+## Rule shape
+
+```typescript
+{
+  id: string;
+  status: "active" | "disabled";
+  priority: number;
+  target: { service: string; resource: string; action: string };
+
+  when?:       ConditionAST;  // optional condition
+  thenEffect?: Effect;        // applied when when == true  (defaults to effect)
+  elseEffect?: Effect;        // applied when when == false (defaults to skip)
+  effect:      Effect;        // unconditional / fallback effect
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `when` | No | Condition AST evaluated against the call-time context. |
+| `thenEffect` | No | Effect when `when` is `true`. Defaults to `effect` if absent. |
+| `elseEffect` | No | Effect when `when` is `false`. Rule is skipped if absent. |
+| `effect` | Yes | Unconditional effect (used when `when` is absent, or as fallback for `thenEffect`). |
+
+---
+
+## Condition operators
+
+### Comparison — `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
+
+Compares the value at `path` in the evaluation context with a scalar `value`.
+
+```json
+{ "op": "eq",  "path": "role",  "value": "admin" }
+{ "op": "neq", "path": "plan",  "value": "free" }
+{ "op": "gte", "path": "amount","value": 1000 }
+{ "op": "lt",  "path": "amount","value": 50 }
+```
+
+`value` may be `string`, `number`, `boolean`, or `null`.
+
+### Membership — `in`
+
+True when the value at `path` equals one of the entries in `values`.
+
+```json
+{ "op": "in", "path": "role", "values": ["admin", "superuser", "moderator"] }
+```
+
+### Existence — `exists`
+
+True when the value at `path` is present and is not `null` or `undefined`.
+
+```json
+{ "op": "exists", "path": "requestTier" }
+```
+
+### Logical — `and` / `or`
+
+Short-circuit combinators over a non-empty `conditions` array.
+
+```json
+{
+  "op": "and",
+  "conditions": [
+    { "op": "eq",     "path": "isAuthenticated", "value": true },
+    { "op": "exists", "path": "plan" }
+  ]
+}
+```
+
+```json
+{
+  "op": "or",
+  "conditions": [
+    { "op": "eq", "path": "role", "value": "admin" },
+    { "op": "eq", "path": "role", "value": "superuser" }
+  ]
+}
+```
+
+### Negation — `not`
+
+Inverts a single child condition.
+
+```json
+{
+  "op": "not",
+  "condition": { "op": "eq", "path": "role", "value": "banned" }
+}
+```
+
+### `path` notation
+
+`path` is a dot-separated key path resolved against the `context` object:
+
+```typescript
+client.evaluate({
+  target: { service: "api", resource: "export", action: "create" },
+  context: {
+    role:   "editor",          // → "role"
+    plan:   "enterprise",      // → "plan"
+    amount: 250,               // → "amount"
+  },
+});
+```
+
+| Namespace | Example paths |
+|---|---|
+| Top-level | `role`, `plan`, `isAuthenticated` |
+| Nested | `user.role`, `tenant.plan`, `tenant.flags.beta` |
+
+{% hint style="info" %}
+The `ctx.` prefix is optional and stripped automatically. `ctx.plan` and `plan` are equivalent.
+{% endhint %}
+
+---
+
+## Examples
+
+### Simple boolean flag
+
+```json
+{
+  "id": "r_beta",
+  "status": "active",
+  "priority": 10,
+  "target": { "service": "app", "resource": "feature/beta-dashboard", "action": "read" },
+  "when":       { "op": "eq", "path": "isAuthenticated", "value": true },
+  "thenEffect": { "type": "allow" },
+  "elseEffect": { "type": "deny" },
+  "effect":     { "type": "deny" }
+}
+```
+
+### Role-based access using `in`
+
+```json
+{
+  "id": "r_admin_write",
+  "status": "active",
+  "priority": 5,
+  "target": { "service": "control", "resource": "settings", "action": "write" },
+  "when": {
+    "op": "in",
+    "path": "role",
+    "values": ["admin", "superuser"]
+  },
+  "thenEffect": { "type": "allow" },
+  "effect":     { "type": "deny" }
+}
+```
+
+Evaluated with `context: { role: "viewer" }` → `deny` (elseEffect absent → rule skipped → falls to policy default or next rule).  
+Evaluated with `context: { role: "admin" }` → `allow`.
+
+### Plan-gated throttling
+
+Free-plan users are throttled; paid users are allowed freely:
+
+```json
+{
+  "id": "r_plan_throttle",
+  "status": "active",
+  "priority": 20,
+  "target": { "service": "api", "resource": "export", "action": "create" },
+  "when": { "op": "eq", "path": "plan", "value": "free" },
+  "thenEffect": {
+    "type": "throttle",
+    "throttle": { "limit": 5, "windowSeconds": 3600, "key": "tenant" }
+  },
+  "elseEffect": { "type": "allow" },
+  "effect":     { "type": "allow" }
+}
+```
+
+### Compound condition — nested `and` / `or`
+
+```json
+{
+  "id": "r_report_export",
+  "status": "active",
+  "priority": 15,
+  "target": { "service": "app", "resource": "report", "action": "export" },
+  "when": {
+    "op": "and",
+    "conditions": [
+      { "op": "eq", "path": "isAuthenticated", "value": true },
+      {
+        "op": "or",
+        "conditions": [
+          { "op": "eq", "path": "role", "value": "admin" },
+          { "op": "eq", "path": "plan", "value": "enterprise" }
+        ]
+      }
+    ]
+  },
+  "thenEffect": { "type": "allow" },
+  "effect":     { "type": "deny" }
+}
+```
+
+---
+
+## Context at call time
+
+```typescript
+client.evaluate({
+  target: { service: "app", resource: "report", action: "export" },
+  context: {
+    isAuthenticated: true,
+    role:            "admin",
+    plan:            "pro",
+  },
+});
+```
+
+{% hint style="warning" %}
+Only keys declared in your `ContextPolicy.allowedKeys` are permitted. Passing undeclared keys throws a validation error at evaluation time. See [Context Policy](ContextPolicy.md).
+{% endhint %}
+
+---
+
+{% content-ref url="ContextPolicy.md" %}
+[Context Policy & PII Safety](ContextPolicy.md)
+{% endcontent-ref %}
+
+{% content-ref url="PolicyDefaults.md" %}
+[Policy Defaults](PolicyDefaults.md)
+{% endcontent-ref %}

package/docs/usage/ContextPolicy.md

@@ -0,0 +1,196 @@
+---
+description: >-
+  Control which keys and values are permitted in the evaluation context to keep
+  PII out of the policy evaluation path.
+---
+
+# Context Policy & PII Safety
+
+## Overview
+
+The `context` object you pass to `evaluate()` is tested against rule `when` conditions. To ensure no personally identifiable information enters the evaluation path, the engine enforces a configurable **context policy** before every evaluation.
+
+Validation happens synchronously, in-process, before any rule is tested. A violation throws an `Error` immediately.
+
+---
+
+## Default context policy
+
+Out of the box the following keys are allowed:
+
+```typescript
+const DEFAULT_CONTEXT_POLICY: ContextPolicy = {
+  allowedKeys: [
+    "plan",
+    "country",
+    "requestTier",
+    "feature",
+    "amount",
+    "isAuthenticated",
+    "role",
+  ],
+  maxStringLen:        64,
+  maxArrayLen:         10,
+  blockLikelyPiiKeys:  true,
+};
+```
+
+---
+
+## `ContextPolicy` shape
+
+```typescript
+type ContextPolicy = {
+  allowedKeys:        string[];  // keys permitted in context
+  maxStringLen:       number;    // max length for string values
+  maxArrayLen:        number;    // max length for array values
+  blockLikelyPiiKeys: boolean;   // block heuristic PII key names
+};
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `allowedKeys` | see above | Exhaustive list of permitted top-level context keys. Any unlisted key throws. |
+| `maxStringLen` | `64` | String values exceeding this length throw. |
+| `maxArrayLen` | `10` | Arrays exceeding this length throw. Array elements must all be strings. |
+| `blockLikelyPiiKeys` | `true` | Blocks keys matching common PII patterns even if they appear in `allowedKeys` (see [Blocked patterns](#blocked-key-patterns) below). |
+
+---
+
+## Configuring a custom policy
+
+Pass `engine.contextPolicy` when constructing `RuntimeClient`:
+
+```typescript
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+  engine: {
+    contextPolicy: {
+      allowedKeys:        ["plan", "role", "country", "requestTier", "featureSet"],
+      maxStringLen:       128,
+      maxArrayLen:        20,
+      blockLikelyPiiKeys: true,
+    },
+  },
+});
+```
+
+Or with `createPolicyEngine` directly:
+
+```typescript
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+
+const engine = createPolicyEngine({
+  getBundle: () => bundle,
+  contextPolicy: {
+    allowedKeys:        ["plan", "role", "country"],
+    maxStringLen:       64,
+    maxArrayLen:        10,
+    blockLikelyPiiKeys: true,
+  },
+});
+```
+
+---
+
+## Disabling validation
+
+{% hint style="danger" %}
+Disabling context validation removes all PII safety guarantees. Only use this in **test environments** or when you control the call sites 100%.
+{% endhint %}
+
+```typescript
+const client = new RuntimeClient({
+  ...
+  engine: { validateContext: false },
+});
+```
+
+---
+
+## Blocked key patterns
+
+When `blockLikelyPiiKeys: true`, the following patterns are tested against every key name (case-insensitive). A match throws even if the key is in `allowedKeys`:
+
+| Pattern | Blocks keys containing… |
+|---|---|
+| `email` | `email`, `userEmail`, `contactEmail` |
+| `phone` / `mobile` | `phone`, `mobileNumber` |
+| `name` / `firstname` / `lastname` | `displayName`, `firstName` |
+| `address` / `street` | `address`, `streetAddress` |
+| `postcode` / `postal` | `postalCode`, `postcode` |
+| `city` | `city`, `hometown` |
+| `ip` | `ip`, `ipAddress`, `clientIp` |
+| `ssn` | `ssn` |
+| `dni` / `nie` | `dni`, `nie` |
+| `passport` | `passportNumber` |
+
+---
+
+## Permitted value types
+
+| Type | Notes |
+|---|---|
+| `string` | Length must not exceed `maxStringLen`. |
+| `number` | No length restriction. |
+| `boolean` | No restriction. |
+| `null` / `undefined` | Allowed; the key is resolved as not-present in `when` conditions. |
+| `string[]` | Length must not exceed `maxArrayLen`; each element must be a string within `maxStringLen`. |
+| `object` | **Not permitted** at the top level. Nested structures are not validated and will throw. |
+
+---
+
+## Example: valid and invalid contexts
+
+```typescript
+// ✅ Valid
+client.evaluate({
+  target:  { service: "api", resource: "export", action: "create" },
+  context: {
+    plan:            "enterprise",
+    role:            "editor",
+    isAuthenticated: true,
+    amount:          1500,
+    country:         "US",
+  },
+});
+
+// ❌ Throws — "email" is blocked by PII heuristic
+client.evaluate({
+  context: { email: "user@example.com" },
+  ...
+});
+
+// ❌ Throws — "orgId" is not in allowedKeys
+client.evaluate({
+  context: { orgId: "org_abc" },
+  ...
+});
+
+// ❌ Throws — string value exceeds maxStringLen
+client.evaluate({
+  context: { plan: "x".repeat(100) },
+  ...
+});
+```
+
+---
+
+## Nested context paths in `when` conditions
+
+Even though the context policy only validates top-level keys, `when` conditions can reference nested paths using dot notation. The keys used in `path` must still correspond to allowed top-level namespaces.
+
+{% hint style="info" %}
+If you use nested context objects (e.g. `user.role`), the top-level key `user` must be in `allowedKeys`. The validation engine does not recurse into nested objects — it only validates the top-level keys and their scalar/array values.
+{% endhint %}
+
+---
+
+{% content-ref url="ConditionalRules.md" %}
+[Conditional Rules](ConditionalRules.md)
+{% endcontent-ref %}
+
+{% content-ref url="../reference/Configuration.md" %}
+[Configuration Reference](../reference/Configuration.md)
+{% endcontent-ref %}

package/docs/usage/CustomEffect.md

@@ -0,0 +1,217 @@
+---
+description: >-
+  Return arbitrary string or JSON payloads from policy rules — useful for
+  feature flags, A/B variants, and structured metadata.
+---
+
+# Custom Effects
+
+## Overview
+
+A `custom` effect lets a rule or policy default carry an arbitrary **string value** back to the caller. That string can be anything — a plain flag, a JSON object, a variant name, or a serialised configuration blob.
+
+Custom effects fill the gap when none of the standard effects (`allow`, `deny`, `throttle`, `kill_switch`) are expressive enough. Common use cases:
+
+* Feature-flag payloads per user/plan/experiment
+* A/B test variant assignments
+* Per-tenant configuration overlays
+* Structured response metadata injected by the policy layer
+
+---
+
+## Bundle shape
+
+### In a rule
+
+```json
+{
+  "id": "r_flags_pro",
+  "status": "active",
+  "priority": 10,
+  "target": { "service": "app", "resource": "features", "action": "read" },
+  "effect": {
+    "type": "custom",
+    "value": "{\"newCheckout\": true, \"aiSearch\": true, \"variant\": \"B\"}"
+  }
+}
+```
+
+### As a policy default
+
+```json
+{
+  "policyKey": "feature-flags",
+  "activeVersion": 3,
+  "defaults": {
+    "effect": "custom",
+    "customEffect": "{\"newCheckout\": false, \"aiSearch\": false, \"variant\": \"A\"}"
+  },
+  "rules": []
+}
+```
+
+{% hint style="info" %}
+In a **rule** the field is `effect.value`. In a **policy default** the field is `defaults.customEffect`. The engine normalises both internally.
+{% endhint %}
+
+---
+
+## Receiving the decision
+
+### Raw string (default)
+
+By default no parsing is performed. The raw `value` string is available on the decision:
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "app", resource: "features", action: "read" },
+  context: { plan: "pro", isAuthenticated: true },
+});
+
+if (result.decision === "custom") {
+  console.log(result.value);
+  // '{"newCheckout": true, "aiSearch": true, "variant": "B"}'
+}
+```
+
+### Automatic JSON parsing
+
+Pass `engine.parseCustomEffect: true` when constructing `RuntimeClient` (or `createPolicyEngine`). The SDK will call `JSON.parse()` on `value` and attach the result as `parsedValue`. Non-JSON strings leave `parsedValue` as `undefined`; the raw `value` is always present as a fallback.
+
+```typescript
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+  engine: {
+    parseCustomEffect: true,   // ← enable JSON parsing
+  },
+});
+
+const result = client.evaluate({ target, context });
+
+if (result.decision === "custom") {
+  const flags = result.parsedValue as {
+    newCheckout: boolean;
+    aiSearch:    boolean;
+    variant:     string;
+  };
+
+  if (flags?.newCheckout) renderNewCheckout();
+  if (flags?.aiSearch)    enableAiSearch();
+}
+```
+
+{% hint style="warning" %}
+`parsedValue` is typed as `unknown`. Always perform a type-guard or cast before accessing its properties. JSON parsing errors are caught silently — always check `parsedValue !== undefined` before use.
+{% endhint %}
+
+---
+
+## Using `createPolicyEngine` directly
+
+```typescript
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+
+const engine = createPolicyEngine({
+  getBundle: () => bundle,
+  parseCustomEffect: true,
+});
+```
+
+---
+
+## Real-world examples
+
+### Feature flags — plan-based
+
+Different flag sets depending on the user's plan using `thenEffect` / `elseEffect`:
+
+```json
+{
+  "id": "r_flags_by_plan",
+  "status": "active",
+  "priority": 10,
+  "target": { "service": "app", "resource": "features", "action": "read" },
+  "when": { "op": "eq", "path": "plan", "value": "enterprise" },
+  "thenEffect": {
+    "type": "custom",
+    "value": "{\"analytics\": true, \"exports\": true, \"aiSearch\": true}"
+  },
+  "elseEffect": {
+    "type": "custom",
+    "value": "{\"analytics\": false, \"exports\": false, \"aiSearch\": false}"
+  },
+  "effect": { "type": "deny" }
+}
+```
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "app", resource: "features", action: "read" },
+  context: { plan: "enterprise" },
+});
+
+if (result.decision === "custom" && result.parsedValue) {
+  const flags = result.parsedValue as Record<string, boolean>;
+  // flags = { analytics: true, exports: true, aiSearch: true }
+}
+```
+
+### A/B experiment variant
+
+```json
+{
+  "id": "r_ab_checkout",
+  "status": "active",
+  "priority": 5,
+  "target": { "service": "app", "resource": "checkout", "action": "render" },
+  "effect": {
+    "type": "custom",
+    "value": "\"variant-B\""
+  }
+}
+```
+
+```typescript
+const result = client.evaluate({ target, context });
+if (result.decision === "custom") {
+  renderCheckout(result.value === '"variant-B"' ? "B" : "A");
+}
+```
+
+### Structured per-tenant config overlay
+
+```json
+{
+  "id": "r_tenant_cfg",
+  "status": "active",
+  "priority": 1,
+  "target": { "service": "app", "resource": "config", "action": "get" },
+  "effect": {
+    "type": "custom",
+    "value": "{\"maxUploadsPerDay\": 500, \"allowedFileTypes\": [\"pdf\", \"csv\"]}"
+  }
+}
+```
+
+---
+
+## Precedence
+
+`custom` sits **below** `allow` in the precedence chain:
+
+```
+kill_switch  >  deny  >  throttle  >  allow  >  custom  >  deny-by-default
+```
+
+This means: if any rule in any policy matches with `allow`, the custom effect is ignored. Design your policies so that if you want a `custom` response to be the primary output for a target, no `allow` rules target the same service/resource/action.
+
+---
+
+{% content-ref url="PolicyDefaults.md" %}
+[Policy Defaults](PolicyDefaults.md)
+{% endcontent-ref %}
+
+{% content-ref url="ConditionalRules.md" %}
+[Conditional Rules](ConditionalRules.md)
+{% endcontent-ref %}