@punica/editor 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/punica.module.kernel.policy.d.ts

@@ -175,6 +175,12 @@ declare module 'punica' {
       requiresApproval: boolean;
       suggestedScope?: ApprovalScope;
       reason?: string;
+      /**
+       * Set when a rule from a policy template decided this. Absent
+       * means the decision came from the capability's own declaration,
+       * which is the state of every install with no `.punica/policy.yaml`.
+       */
+      policyRule?: PolicyRuleRef;
     }
 
     export interface PolicyApi {
@@ -183,7 +189,32 @@ declare module 'punica' {
 
       evaluate(
         req: PolicyRequest,
-        ctx?: { workspaceId?: string }
+        ctx?: {
+          workspaceId?: string;
+          /**
+           * The REDACTED arguments, for rule conditions to test. The
+           * same value `argsBinding` is computed from, so a condition
+           * can never read a secret and the decision, the binding and
+           * the audit record's `input` all agree.
+           *
+           * Used transiently for matching and never persisted — only the
+           * digest and the capped preview are.
+           */
+          args?: unknown;
+          /**
+           * Input paths the redactor has already replaced. A condition
+           * on one of them never matches — comparing a bucket name
+           * against `'[REDACTED]'` would be governance in appearance
+           * only.
+           */
+          redactedPaths?: ReadonlyArray<ReadonlyArray<string>>;
+          /**
+           * Every string in `args` was replaced, not selected paths —
+           * what the redactor does for a `secretBearing` capability. No
+           * condition can mean anything against that, so none apply.
+           */
+          argsWhollyRedacted?: boolean;
+        }
       ): PolicyDecision;
 
       requestApproval(
@@ -278,31 +309,150 @@ declare module 'punica' {
     }
 
     /**
-     * Policy template for workspace-scoped policy rules
+     * What a matching rule does to the decision.
+     *
+     *  - `deny`    — the call does not run, and no approval can make it
+     *                run. Terminal by design: a rule that a prompt could
+     *                click past is a suggestion, not a policy.
+     *  - `require` — the call needs approval even if the capability
+     *                declares `approval: none`.
+     *  - `allow`   — the call runs without a prompt. Attributed by name
+     *                in the decision and in the durable audit record, so
+     *                a later reader can tell "a rule allowed this" from
+     *                "a human approved this".
+     */
+    export type PolicyRuleEffect = 'allow' | 'deny' | 'require';
+
+    /**
+     * Comparison operators a rule condition may use.
+     *
+     * A deliberately closed set. Every entry has an obvious equivalent
+     * in the gateway policy schemas this vocabulary is meant to be
+     * exported into (K4) — regex is absent for exactly that reason: it
+     * cannot cross into a foreign engine without either changing meaning
+     * or carrying a ReDoS hazard with it.
+     */
+    export type PolicyConditionOp =
+      | 'eq'
+      | 'neq'
+      | 'in'
+      | 'notIn'
+      | 'startsWith'
+      | 'endsWith'
+      | 'glob'
+      | 'exists'
+      | 'absent'
+      | 'lt'
+      | 'lte'
+      | 'gt'
+      | 'gte';
+
+    /**
+     * One test against one argument path.
+     *
+     * `path` is dotted, with `*` for every element of an array
+     * (`bucket`, `target.path`, `items.*.id`) — the same grammar as the
+     * `policyKey` annotation, so there is one path syntax to learn.
+     *
+     * The value tested is the REDACTED argument, the same one the
+     * binding is computed from. A condition on a `sensitive` field
+     * therefore cannot match anything meaningful and never matches at
+     * all; the capability linter reports the declaration side of that
+     * contradiction.
+     */
+    export interface PolicyCondition {
+      path: string;
+      op: PolicyConditionOp;
+      /** Not read by `exists` / `absent`. */
+      value?: unknown;
+    }
+
+    /**
+     * One rule. `kind`/`id` select which requests it applies to; `when`
+     * selects which argument tuples.
+     */
+    export interface PolicyRule {
+      /** Request kind, e.g. `capability`. */
+      kind: string;
+      /** Exact id, or a trailing-`*` prefix glob. Absent matches every id of the kind. */
+      id?: string;
+      effect: PolicyRuleEffect;
+      /** ANDed. Absent or empty matches every argument tuple. */
+      when?: PolicyCondition[];
+      /** Which approval `effect: 'require'` demands. Default `step`. */
+      approval?: 'none' | 'plan' | 'step';
+      /** Shown to the user on a denial and written into the audit record. */
+      reason?: string;
+    }
+
+    /** Which rule decided, carried on the decision and into the audit record. */
+    export interface PolicyRuleRef {
+      /** Name of the template the rule came from. */
+      template: string;
+      /** Index within that template's `rules`. */
+      ruleIndex: number;
+      effect: PolicyRuleEffect;
+      reason?: string;
+      /** Digest of the template's rules — which policy text was in force. */
+      digest?: string;
+    }
+
+    /** A rule that matched, plus the rule itself for the caller to read. */
+    export interface PolicyRuleMatch {
+      ref: PolicyRuleRef;
+      rule: PolicyRule;
+    }
+
+    /** One problem found while validating rule input. */
+    export interface PolicyRuleProblem {
+      /** Dotted path into the parsed input, e.g. `templates.0.rules.2.op`. */
+      path: string;
+      message: string;
+    }
+
+    /**
+     * A named, workspace-scoped bundle of rules.
+     *
+     * Until 1.17.0 this type existed but nothing read it: `evaluate()`
+     * never consulted the template store, `#persist()` never saved it,
+     * and its `condition?: string` field was marked "Future" and read by
+     * nobody. The string expression is gone — a structured matcher is
+     * the half that can be translated into another engine's schema,
+     * which is the entire purpose of exporting policy at all.
      */
     export interface PolicyTemplate {
       name: string;
       description?: string;
       workspaceId?: string;
-      rules: Array<{
-        kind: string;
-        id?: string;
-        risk?: 'low' | 'medium' | 'high';
-        approval?: 'none' | 'plan' | 'step';
-        condition?: string; // Future: expression for conditional rules
-      }>;
+      rules: PolicyRule[];
+      /**
+       * Where the template came from. `file` templates are owned by
+       * `.punica/policy.yaml` and are removed when they leave it, so
+       * deleting the file cannot leave stale rules enforcing from
+       * persisted state. Absent is treated as `api`.
+       */
+      source?: 'file' | 'api';
+      /** Digest of `rules`, set by whoever loaded them. */
+      digest?: string;
       createdAtMs?: number;
       updatedAtMs?: number;
     }
 
     /**
-     * Exported policy state format (v2).
+     * Exported policy state.
+     *
+     * v3 adds `templates`, so an export answers "what was in force"
+     * rather than only "what was approved" — the question an evidence
+     * package has to answer. `importState` accepts v2 as well: a v2 blob
+     * simply carries no rules.
      */
     export interface PolicyExport {
-      version: 2;
+      version: 2 | 3;
       exportedAt: number;
       mode: PolicyMode;
       approvals: ApprovalRecord[];
+      /** Present in v3. Absent in a v2 blob. */
+      templates?: PolicyTemplate[];
     }
 
     /**
@@ -382,6 +532,50 @@ declare module 'punica' {
         source: unknown,
         options?: { policyKeyPaths?: ReadonlyArray<ReadonlyArray<string>> }
       ): Promise<ArgsBinding>;
+
+      /**
+       * SHA-256 over the canonical JSON of `value`, 128 bits of hex.
+       * Used for the rule-set digest that says which policy text was in
+       * force; shares its implementation with `computeArgsBinding` so
+       * the two cannot drift.
+       */
+      function canonicalDigest(value: unknown): Promise<string>;
+
+      /**
+       * Which rule applies to a request, if any.
+       *
+       * Precedence is `deny` > `require` > `allow`, independent of the
+       * order rules were written in — order-dependent precedence does
+       * not survive translation into another policy engine.
+       *
+       * `args` must be the REDACTED arguments. Exported so a policy
+       * exporter reads the same matcher the gate enforces instead of
+       * reimplementing it.
+       */
+      function matchRules(
+        templates: readonly PolicyTemplate[],
+        req: { kind: string; id: string },
+        args: unknown,
+        options?: {
+          /** Paths the redactor has already replaced; conditions on them never match. */
+          sensitivePaths?: ReadonlyArray<ReadonlyArray<string>>;
+          /** The whole tuple was replaced (a `secretBearing` capability); no condition applies. */
+          argsWhollyRedacted?: boolean;
+        }
+      ): PolicyRuleMatch | null;
+
+      /**
+       * Normalise and check rule input, e.g. parsed
+       * `.punica/policy.yaml`.
+       *
+       * An invalid rule is dropped and reported while its siblings load;
+       * a file-level shape error yields zero templates and a problem.
+       * Never returns a partial set that reads as complete.
+       */
+      function validatePolicyTemplates(raw: unknown): {
+        templates: PolicyTemplate[];
+        problems: PolicyRuleProblem[];
+      };
     }
   }
 }