@punica/editor 1.15.1 → 1.17.0

package/package.json

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

package/types/punica.module.flow.engine.d.ts

@@ -116,6 +116,15 @@ declare module 'punica' {
         risk: string;
         approval: string;
         reason?: string;
+        /**
+         * Argument binding carried from the gate — see
+         * `kernel.PolicyRequest.argsBinding`. Without it the approval
+         * recorded when this pending resolves covers every argument
+         * tuple for the step's capability, not just this step's.
+         */
+        argsBinding?: string;
+        /** Redacted view of the bound arguments, for the approval UI. */
+        argsPreview?: unknown;
         workspaceId?: string;
         timestampMs: number;
       }

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

@@ -46,6 +46,20 @@ declare module 'punica' {
         risk: string;
         approval: string;
         reason?: string;
+        /**
+         * The argument binding the gate computed for this call — see
+         * `kernel.PolicyRequest.argsBinding`. Carried across the round
+         * trip so `approvePending` grants for the arguments the user was
+         * shown rather than for the capability as a whole.
+         */
+        argsBinding?: string;
+        /**
+         * Redacted view of those arguments, so an approval prompt can
+         * show what is being bound. A user asked to allow
+         * `mcp.aws.deleteObject` without seeing the bucket is consenting
+         * to a name, not to an action.
+         */
+        argsPreview?: unknown;
         correlationId?: string;
         /**
          * Trace id of the invocation that hit the gate (an agent run id
@@ -509,7 +523,9 @@ declare module 'punica' {
        * history rather than fail a run.
        */
       export interface ToolUsageStore {
-        read(): Promise<Record<string, { calls: number; ok: number; last: number }>>;
+        read(): Promise<
+          Record<string, { calls: number; ok: number; last: number }>
+        >;
         record(capabilityId: string, ok: boolean, atMs: number): Promise<void>;
         forget(): Promise<void>;
       }

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

@@ -22,6 +22,27 @@ declare module 'punica' {
        * Optional human-readable reason shown in UI prompts.
        */
       reason?: string;
+      /**
+       * Which arguments this decision is about — a digest computed by
+       * `computeArgsBinding` from the capability's REDACTED input, or the
+       * literal `'any'` for a grant deliberately made argument-blind
+       * (an unattended-client pre-authorisation).
+       *
+       * Absent means the request has no argument dimension (`llm.remote`,
+       * a flow step). Absence keys exactly as it did before bindings
+       * existed, so those kinds re-prompt nothing.
+       *
+       * The field is what stops one "always" grant on
+       * `mcp.aws.deleteObject` from authorising every bucket.
+       */
+      argsBinding?: string;
+      /**
+       * Redacted, possibly truncated view of the bound arguments.
+       * Carried so an approval prompt can show what is being bound and
+       * an evidence package can read it back — a digest alone means the
+       * user consented to a hash they never saw.
+       */
+      argsPreview?: unknown;
     }
 
     /**
@@ -123,6 +144,15 @@ declare module 'punica' {
        * record + chain state by this id.
        */
       chainRef?: string;
+      /**
+       * The arguments this grant covers. See `PolicyRequest.argsBinding`.
+       * Persisted so a grant matches only the arguments it was given
+       * for, and so a reader can distinguish a bucket-specific approval
+       * from an `'any'` blanket one.
+       */
+      argsBinding?: string;
+      /** Redacted view of the bound arguments, for display and audit. */
+      argsPreview?: unknown;
       /**
        * Time-bounded approvals — Sub-step 3.F. Epoch ms after which
        * the approval is considered expired. `hasApproval` returns
@@ -145,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 {
@@ -153,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(
@@ -191,8 +252,17 @@ declare module 'punica' {
         }
       ): ApprovalRecord;
 
+      /**
+       * `argsBinding` must be supplied when revoking a bound grant —
+       * omitting it targets the unbound key and silently revokes
+       * nothing, which is how a consumed "approve once" would turn into
+       * a permanent allow.
+       */
       revokeApproval(
-        rec: Pick<ApprovalRecord, 'kind' | 'id' | 'scope' | 'workspaceId'>
+        rec: Pick<
+          ApprovalRecord,
+          'kind' | 'id' | 'scope' | 'workspaceId' | 'argsBinding'
+        >
       ): boolean;
 
       /**
@@ -239,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[];
     }
 
     /**
@@ -308,8 +497,85 @@ declare module 'punica' {
       isRevoked(jti: string): boolean;
     }
 
+    /** What `computeArgsBinding` returns. */
+    export interface ArgsBinding {
+      /** Digest of the bound arguments. */
+      binding: string;
+      /** Redacted, possibly truncated view of what was bound. */
+      preview: unknown;
+    }
+
     export namespace Policy {
       const manager: PolicyApi;
+
+      /**
+       * Literal binding meaning "any arguments" — a grant deliberately
+       * made argument-blind, as opposed to a request that has no
+       * argument dimension at all (absent binding).
+       */
+      const ARGS_BINDING_ANY: 'any';
+
+      /**
+       * Digest the arguments a decision is about.
+       *
+       * `source` must be the REDACTED input, so no secret value reaches
+       * the digest. `policyKeyPaths` narrows the binding to the declared
+       * fields, which is what makes an `always` grant practical; empty
+       * binds the whole argument tuple.
+       *
+       * An extension that pre-records a grant must call this rather than
+       * hashing locally — otherwise its key and the gate's key drift and
+       * the grant never matches. Throws when Web Crypto is unavailable
+       * rather than falling back to a weaker hash.
+       */
+      function computeArgsBinding(
+        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[];
+      };
     }
   }
 }