@watchlight/engine 0.1.0 → 0.2.0

package/README.md

@@ -50,6 +50,38 @@ console.log(atten.decision); // "Allow" (child ⊆ parent) — a superset would
 WebAssembly has no blocking wait, so they return Promises). `attenuateScope`
 is synchronous. TypeScript types ship in `index.d.ts`.
 
+### Obligations on permits
+
+A `permit` can attach constraints to its own Allow with `@obligate_*` Cedar
+annotations. They are validated at `addPolicy` time and returned on the
+decision — per policy on `details.policy_results[].obligations` (applicable
+permits only) and merged on `details.obligations` — on `Allow` only. A Deny
+carries none; every field is omitted when unset.
+
+```js
+await engine.addPolicy({
+  name: "list-customers",
+  code: `
+    @obligate_redact("ssn, card.pan")   // comma-separated field names (at least one)
+    @obligate_max_items("8")            // decimal integer 1..=4294967295
+    @obligate_log_values("false")       // exactly "true" or "false"
+    @obligate_watermark("acme")         // unknown keys pass through raw: extra.watermark
+    permit(principal, action == Action::"list_customers", resource);
+  `,
+});
+const resp = await engine.authorize({ principal: 'User::"carol"', action: 'Action::"list_customers"', resource: 'Document::"crm"' });
+resp.details.obligations;
+// { redact: ["ssn", "card.pan"], max_items: 8, log_values: false }
+resp.details.policy_results[0].obligations.extra; // { watermark: "acme" }
+```
+
+Merge across several applicable permits is deterministic: `redact` = union,
+`max_items` = min, `log_values` = logical AND; `extra` is never merged (read
+it per policy). A malformed value — `@obligate_max_items("eight")`,
+`@obligate_log_values("yes")`, an empty `@obligate_redact` — or any
+`@obligate_*` on a `forbid` **rejects the policy** at `addPolicy`; an
+obligation is never silently dropped.
+
 ## Graduation to Enterprise
 
 The same code moves to the networked Watchlight control plane (signed lineage,
@@ -64,7 +96,7 @@ and (optionally, for a smaller artifact) a modern [`binaryen`](https://github.co
 ```bash
 rustup target add wasm32-unknown-unknown
 npm run build        # → ./wasm (regenerated; not committed)
-npm test             # Node conformance (7/7)
+npm test             # Node conformance (decisions, obligations, load-time rejection)
 npm run conformance  # Node + Python parity (needs: pip install watchlight-engine)
 ```
 

package/index.d.ts

@@ -23,11 +23,65 @@ export interface AuthorizationRequest {
   [k: string]: unknown;
 }
 
+/**
+ * Obligations a `permit` declares via `@obligate_*` Cedar annotations —
+ * constraints the caller MUST honour when acting on an `Allow`. Parsed and
+ * validated by the engine at `addPolicy` time (a malformed value rejects the
+ * policy). Every field is omitted when unset.
+ *
+ * - `@obligate_redact("ssn, card.pan")` → `redact` (comma-separated, trimmed,
+ *   de-duplicated, at least one entry)
+ * - `@obligate_max_items("8")` → `max_items` (decimal integer, 1..=4294967295)
+ * - `@obligate_log_values("false")` → `log_values` (exactly `true`/`false`)
+ * - any other `@obligate_<name>("raw")` → `extra[name] = "raw"`, uninterpreted
+ */
+export interface Obligations {
+  redact?: string[];
+  max_items?: number;
+  log_values?: boolean;
+  /** Unknown `@obligate_*` keys, raw. Never interpreted or merged by the engine. */
+  extra?: Record<string, string>;
+}
+
+/** One entry of `details.policy_results`. */
+export interface PolicyResult {
+  policy_id: string;
+  policy_name?: string;
+  /** `true` when this policy determined the decision. */
+  applicable: boolean;
+  decision: string;
+  reason: string;
+  evaluation_time_ms: number;
+  /** The `@enforcement_effect("…")` annotation value, when declared. */
+  enforcement_effect?: string;
+  /**
+   * Present ONLY on a `permit` that carried a final `"Allow"`: the
+   * determining permit(s) on a Cedar Allow, or — when an `observe` /
+   * `attenuate` forbid downgraded a Cedar Deny to Allow (monitor mode) —
+   * every permit whose own conditions matched (`applicable` stays `false`
+   * there). Absent on every forbid and on every Deny.
+   */
+  obligations?: Obligations;
+  [k: string]: unknown;
+}
+
 /** The engine's decision. Fail-closed: an unmatched request is `"Deny"`. */
 export interface AuthorizationResponse {
   decision: "Allow" | "Deny" | string;
   reason?: string;
-  details?: Record<string, unknown>;
+  details?: {
+    policy_results?: PolicyResult[];
+    /**
+     * Deterministic merge of every carrying permit's obligations, present
+     * ONLY on a final `"Allow"` and only when non-empty: `redact` = union,
+     * `max_items` = min, `log_values` = logical AND. `extra` is NOT merged —
+     * read it per policy from `policy_results[].obligations.extra`. A
+     * monitor-mode downgrade that cannot attach its permits' obligations is
+     * refused by the engine (the decision stays `"Deny"`).
+     */
+    obligations?: Obligations;
+    [k: string]: unknown;
+  };
   [k: string]: unknown;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchlight/engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Watchlight Developer Edition authorization engine for Node — the real wl-apdp Cedar pipeline (delegation → intent → goal → policy selection → Cedar → strict-subset attenuation → enforcement effects) compiled to WebAssembly. In-process, fail-closed, zero infrastructure.",
   "type": "commonjs",
   "main": "./index.js",
@@ -34,6 +34,13 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://www.watchlight.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/watchlight-ai-beacon/watchlight-de.git"
+  },
+  "bugs": {
+    "url": "https://github.com/watchlight-ai-beacon/watchlight-de/issues"
+  },
   "publishConfig": {
     "access": "public"
   }

package/wasm/wl_apdp_wasm.js

@@ -169,7 +169,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_3775(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_3842(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -224,8 +224,8 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 477, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3744);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 482, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3812);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
@@ -247,10 +247,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_3744(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_3812(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_3744(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_3812(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -261,8 +261,8 @@ function __wasm_bindgen_func_elem_3744(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_3775(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_3775(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_3842(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_3842(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const PolicyEngineFinalization = (typeof FinalizationRegistry === 'undefined')