@zapier/policy-schema 0.18.0 → 0.19.0

package/dist/index.cjs

@@ -4,9 +4,10 @@ var zod = require('zod');
 
 // src/schema.ts
 var RUBBERDUCK_POLICY_VERSION = "rc-rubberduck";
-var VALID_VERSIONS = [1, 2, 3, RUBBERDUCK_POLICY_VERSION];
+var VALID_VERSIONS = [1, 2, 3, 4, RUBBERDUCK_POLICY_VERSION];
 var ID_BASED_VERSIONS = /* @__PURE__ */ new Set([
   3,
+  4,
   RUBBERDUCK_POLICY_VERSION
 ]);
 var VALID_EFFECTS = ["allow", "ask", "deny"];
@@ -191,6 +192,7 @@ var V2StatementSchema = zod.z.object({
 var StatementSchema = V2StatementSchema;
 var StatementIdSchema = zod.z.string().regex(/^s_\S+$/, { error: "Statement id must match ^s_\\S+$" }).max(512);
 var PolicyIdSchema = zod.z.string().regex(/^p_\S+$/, { error: "Policy id must match ^p_\\S+$" }).max(512);
+var RuleIdSchema = zod.z.string().regex(/^r_\S+$/, { error: "Rule id must match ^r_\\S+$" }).max(512);
 var V1PolicySchema = zod.z.object({
   version: zod.z.literal(1),
   statements: zod.z.array(V1StatementSchema)
@@ -227,10 +229,25 @@ var V3PolicySchema = zod.z.object({
   // empty (e.g. `[[]]` denies everything).
   statements: zod.z.array(zod.z.array(V3StatementSchema)).min(1).max(V3_MAX_TIERS)
 }).strict();
+var V4_MAX_TIERS = 3;
+var V4RuleSchema = zod.z.object({
+  id: RuleIdSchema,
+  effect: zod.z.enum(["allow", "ask", "deny"]),
+  permissions: zod.z.array(zod.z.string()).min(1),
+  resources: zod.z.array(zod.z.string()).min(1),
+  conditions: zod.z.array(ConditionSchema).optional()
+}).strict();
+var V4PolicySchema = zod.z.object({
+  version: zod.z.literal(4),
+  // Ordered tiers, in priority order. 1..V4_MAX_TIERS tiers; a tier may be
+  // empty (e.g. `[[]]` denies everything). Renamed from v3's `statements`.
+  rules: zod.z.array(zod.z.array(V4RuleSchema)).min(1).max(V4_MAX_TIERS)
+}).strict();
 var PolicySchema = zod.z.union([
   V1PolicySchema,
   V2PolicySchema,
   V3PolicySchema,
+  V4PolicySchema,
   RcRubberduckPolicySchema
 ]);
 var CanonicalHashSchema = zod.z.custom(
@@ -265,6 +282,12 @@ var OverridePolicyIdBaseShape = {
   policyId: PolicyIdSchema,
   effect: zod.z.literal("allow")
 };
+var OverrideRuleIdBaseShape = {
+  id: zod.z.string().optional(),
+  /** Targets a v4 rule by id (r_ prefix, non-null). */
+  ruleId: RuleIdSchema,
+  effect: zod.z.literal("allow")
+};
 var OverrideSchema = zod.z.union([
   // statementHash × match
   zod.z.object({ ...OverrideHashBaseShape, match: zod.z.literal("any") }).strict(),
@@ -292,6 +315,15 @@ var OverrideSchema = zod.z.union([
   zod.z.object({
     ...OverridePolicyIdBaseShape,
     conditionals: zod.z.array(ConditionSchema)
+  }).strict(),
+  // ruleId × match
+  zod.z.object({ ...OverrideRuleIdBaseShape, match: zod.z.literal("any") }).strict(),
+  // ruleId × contextHash
+  zod.z.object({ ...OverrideRuleIdBaseShape, contextHash: CanonicalHashSchema }).strict(),
+  // ruleId × conditionals
+  zod.z.object({
+    ...OverrideRuleIdBaseShape,
+    conditionals: zod.z.array(ConditionSchema)
   }).strict()
 ]);
 function getOpenApiSchema() {
@@ -306,7 +338,7 @@ function getOpenApiSchema() {
       effect: {
         type: "string",
         enum: [...VALID_EFFECTS].sort(),
-        description: "Whether to allow, ask, or deny the specified permissions. The 'ask' effect is valid in version 2, version 3, and rc-rubberduck policies."
+        description: "Whether to allow, ask, or deny the specified permissions. The 'ask' effect is valid in version 2, version 3, version 4, and rc-rubberduck policies."
       },
       permissions: {
         type: "array",
@@ -385,42 +417,123 @@ function getOpenApiSchema() {
       }
     }
   };
-  return {
-    type: "object",
-    required: ["version", "statements"],
+  const ruleItems = {
+    ...statementItems,
     properties: {
-      version: {
-        anyOf: [
-          { type: "integer", enum: [1, 2, 3] },
-          { type: "string", enum: [RUBBERDUCK_POLICY_VERSION] }
-        ],
-        description: "Policy schema version. Stable versions are 1, 2, and 3; supported release candidates are rc-rubberduck."
-      },
+      ...statementItems.properties,
       id: {
         type: "string",
-        description: "Policy id (required for rc-rubberduck policies; not permitted on any other version). Must use the p_ prefix and contain no whitespace."
+        description: "Rule identifier. Required for v4 policies; must use the r_ prefix with no whitespace."
       },
-      defaultEffect: {
-        type: "string",
-        enum: [...DefaultEffectSchema.options],
-        description: "Effect applied when no statement matches. Required on rc-rubberduck policies (deny equals implicit deny); not permitted on any other version."
+      resources: {
+        ...statementItems.properties.resources,
+        description: "List of resource identifiers the rule applies to."
       },
-      statements: {
-        type: "array",
-        description: "Policy statements. For v1/v2/rc-rubberduck each entry is a statement. For v3 each entry is a tier (a list of statements); tiers are in priority order and evaluated first-to-last (the first tier with a match decides), so `statements` is a list of lists.",
-        items: {
-          anyOf: [
-            statementItems,
-            {
-              type: "array",
-              description: "A v3 tier: statements evaluated together with deny > ask > allow precedence.",
-              items: statementItems
-            }
-          ]
-        }
+      conditions: {
+        ...statementItems.properties.conditions,
+        description: "Optional conditions that must be met for the rule to apply."
       }
     }
   };
+  const versionDescription = "Policy schema version. Stable versions are 1, 2, 3, and 4; supported release candidates are rc-rubberduck.";
+  const flatStatements = {
+    type: "array",
+    description: "Policy statements; each entry is a statement.",
+    items: statementItems
+  };
+  const statementTiers = {
+    type: "array",
+    description: "v3 tiers in priority order; each entry is a tier (a list of statements) evaluated first-to-last (the first tier with a match decides), so `statements` is a list of lists.",
+    items: {
+      type: "array",
+      description: "A v3 tier: statements evaluated together with deny > ask > allow precedence.",
+      items: statementItems
+    }
+  };
+  const ruleTiers = {
+    type: "array",
+    description: "v4 rules in priority order; each entry is a tier (a list of rules) evaluated first-to-last (the first tier with a match decides), so `rules` is a list of lists.",
+    items: {
+      type: "array",
+      description: "A v4 tier: rules evaluated together with deny > ask > allow precedence.",
+      items: ruleItems
+    }
+  };
+  const idProperty = {
+    type: "string",
+    description: "Policy id (rc-rubberduck only). Must use the p_ prefix and contain no whitespace."
+  };
+  const defaultEffectProperty = {
+    type: "string",
+    enum: [...DefaultEffectSchema.options],
+    description: "Effect applied when no statement matches (rc-rubberduck only; deny equals implicit deny)."
+  };
+  return {
+    oneOf: [
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 1,
+            description: versionDescription
+          },
+          statements: flatStatements
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 2,
+            description: versionDescription
+          },
+          statements: flatStatements
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 3,
+            description: versionDescription
+          },
+          statements: statementTiers
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "rules"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 4,
+            description: versionDescription
+          },
+          rules: ruleTiers
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "id", "defaultEffect", "statements"],
+        properties: {
+          version: {
+            type: "string",
+            const: RUBBERDUCK_POLICY_VERSION,
+            description: versionDescription
+          },
+          id: idProperty,
+          defaultEffect: defaultEffectProperty,
+          statements: flatStatements
+        }
+      }
+    ]
+  };
 }
 
 exports.ArrayOperatorSchema = ArrayOperatorSchema;
@@ -436,12 +549,14 @@ exports.PolicyIdSchema = PolicyIdSchema;
 exports.PolicySchema = PolicySchema;
 exports.RUBBERDUCK_POLICY_VERSION = RUBBERDUCK_POLICY_VERSION;
 exports.RangeValueSchema = RangeValueSchema;
+exports.RuleIdSchema = RuleIdSchema;
 exports.ScalarOperatorSchema = ScalarOperatorSchema;
 exports.SizeValueSchema = SizeValueSchema;
 exports.StatementIdSchema = StatementIdSchema;
 exports.StatementSchema = StatementSchema;
 exports.UrlOperatorSchema = UrlOperatorSchema;
 exports.V3_MAX_TIERS = V3_MAX_TIERS;
+exports.V4_MAX_TIERS = V4_MAX_TIERS;
 exports.VALID_EFFECTS = VALID_EFFECTS;
 exports.VALID_OPERATOR_LIST = VALID_OPERATOR_LIST;
 exports.VALID_VERSIONS = VALID_VERSIONS;

package/dist/index.d.cts

@@ -3,14 +3,14 @@ import { z } from 'zod';
 /** Release-candidate policy document version for the current experimental shape. */
 declare const RUBBERDUCK_POLICY_VERSION: "rc-rubberduck";
 /** Supported policy document versions. */
-declare const VALID_VERSIONS: readonly [1, 2, 3, "rc-rubberduck"];
+declare const VALID_VERSIONS: readonly [1, 2, 3, 4, "rc-rubberduck"];
 /**
  * Versions whose statements carry an id (s_/p_) and are therefore targeted by
  * that id rather than canonical hash. Single source of truth shared with the
  * engine's usesIds override-targeting predicate: "requires an id" and
  * "targeted by id" coincide for every supported version.
  */
-declare const ID_BASED_VERSIONS: Set<"rc-rubberduck" | 1 | 2 | 3>;
+declare const ID_BASED_VERSIONS: Set<"rc-rubberduck" | 1 | 2 | 3 | 4>;
 /** Valid policy effects. */
 declare const VALID_EFFECTS: readonly ["allow", "ask", "deny"];
 /** Derived from VALID_EFFECTS — the constant is the single source of truth. */
@@ -359,6 +359,10 @@ type StatementId = z.infer<typeof StatementIdSchema>;
 declare const PolicyIdSchema: z.ZodString;
 /** Derived from PolicyIdSchema — the schema is the single source of truth. */
 type PolicyId = z.infer<typeof PolicyIdSchema>;
+/** Rule identifier for v4 policies. Must match ^r_\S+$ and be ≤512 chars. */
+declare const RuleIdSchema: z.ZodString;
+/** Derived from RuleIdSchema — the schema is the single source of truth. */
+type RuleId = z.infer<typeof RuleIdSchema>;
 /** Effect applied when no statement matches (rc-rubberduck, required). deny == implicit deny. */
 declare const DefaultEffectSchema: z.ZodEnum<{
     deny: "deny";
@@ -368,6 +372,8 @@ declare const DefaultEffectSchema: z.ZodEnum<{
 type DefaultEffect = z.infer<typeof DefaultEffectSchema>;
 /** Upper bound on v3 statement tiers. Raising this later is backwards-compatible. */
 declare const V3_MAX_TIERS = 3;
+/** Upper bound on v4 rule tiers. Separate from V3_MAX_TIERS so the two versions can diverge. */
+declare const V4_MAX_TIERS = 3;
 declare const PolicySchema: z.ZodUnion<readonly [z.ZodObject<{
     version: z.ZodLiteral<1>;
     statements: z.ZodArray<z.ZodObject<{
@@ -790,6 +796,147 @@ declare const PolicySchema: z.ZodUnion<readonly [z.ZodObject<{
             }, z.core.$strict>]>>;
         }, z.core.$strict>]>>>;
     }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<4>;
+    rules: z.ZodArray<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        effect: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        permissions: z.ZodArray<z.ZodString>;
+        resources: z.ZodArray<z.ZodString>;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"equals">;
+            value: z.ZodJSONSchema;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_host">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_path">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"range">;
+            value: z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_url">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"values_in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"exists">;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"keys_in">;
+            value: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"size">;
+            value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>]>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodEnum<{
+                some: "some";
+                all: "all";
+                none: "none";
+            }>;
+            where: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"equals">;
+                value: z.ZodJSONSchema;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"in">;
+                value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_host">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_path">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"range">;
+                value: z.ZodObject<{
+                    min: z.ZodOptional<z.ZodNumber>;
+                    max: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_url">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"values_in">;
+                value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"exists">;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"keys_in">;
+                value: z.ZodArray<z.ZodString>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"size">;
+                value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                    min: z.ZodOptional<z.ZodNumber>;
+                    max: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>]>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>]>>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodObject<{
     version: z.ZodLiteral<"rc-rubberduck">;
     id: z.ZodString;
@@ -943,15 +1090,17 @@ type Policy = z.infer<typeof PolicySchema>;
 declare const CanonicalHashSchema: z.ZodCustom<CanonicalHash, CanonicalHash>;
 /**
  * Runtime schema for the Override type. Each variant has exactly one target
- * field (statementHash for v1/v2, statementId or policyId for rc-rubberduck) and exactly
+ * field (statementHash for v1/v2, statementId for v3/rc-rubberduck, policyId for
+ * rc-rubberduck, ruleId for v4) and exactly
  * one binding mode (match, contextHash, or conditionals). `.strict()` keeps
  * the variants mutually exclusive (an object carrying fields from two variants
  * fails all branches).
  *
  * Targets are all non-null:
  * - statementHash: targets a v1/v2 statement by canonical hash
- * - statementId: targets an rc-rubberduck statement by id
+ * - statementId: targets a v3/rc-rubberduck statement by id
  * - policyId: targets that policy's default effect (rc-rubberduck only)
+ * - ruleId: targets a v4 rule by id
  *
  * Empty conditionals is intentional (the "blank check"): the override applies
  * whenever the targeted ask statement fires, with no extra conditions. Do not
@@ -1386,6 +1535,149 @@ declare const OverrideSchema: z.ZodUnion<readonly [z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     policyId: z.ZodString;
     effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    match: z.ZodLiteral<"any">;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    contextHash: z.ZodCustom<CanonicalHash, CanonicalHash>;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    conditionals: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"equals">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"in">;
+        value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_host">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_path">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"range">;
+        value: z.ZodObject<{
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_url">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"values_in">;
+        value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"exists">;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"keys_in">;
+        value: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"size">;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodEnum<{
+            some: "some";
+            all: "all";
+            none: "none";
+        }>;
+        where: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"equals">;
+            value: z.ZodJSONSchema;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_host">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_path">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"range">;
+            value: z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_url">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"values_in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"exists">;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"keys_in">;
+            value: z.ZodArray<z.ZodString>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"size">;
+            value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>]>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>]>>;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
 }, z.core.$strict>]>;
 /** Derived from OverrideSchema — the schema is the single source of truth. */
 type Override = z.infer<typeof OverrideSchema>;
@@ -1432,6 +1724,18 @@ interface StatementTrace {
     passed: boolean;
     overrides?: OverrideTrace[];
 }
+/**
+ * v4 rule trace. Identical to StatementTrace but the matched object is keyed
+ * `rule` instead of `statement`, matching the v4 `statements`->`rules` rename.
+ */
+interface RuleTrace {
+    rule: Statement;
+    permissionMatched: boolean;
+    resourceMatched: boolean;
+    conditionResults?: ConditionTrace[];
+    passed: boolean;
+    overrides?: OverrideTrace[];
+}
 interface EvaluatePolicyOptions {
     policy: Policy;
     request: PolicyRequest;
@@ -1447,6 +1751,19 @@ interface PolicyResult {
     /** Trace mode only. Present when no statement matched and an ask default was consulted (never attached for deny defaults). */
     default?: DefaultTrace;
 }
+/**
+ * Result of evaluating a v4 policy. Version-gated shape: the trace array is
+ * keyed `rules` (of RuleTrace) instead of `statements`, matching the v4
+ * `statements`->`rules` rename. Only ever returned for a v4 policy; all other
+ * versions return {@link PolicyResult}. v4 has no ask default (no
+ * defaultEffect), so there is no `default` field.
+ */
+interface PolicyResultV4 {
+    effect: Effect;
+    explicit: boolean;
+    reason: PolicyReason;
+    rules: RuleTrace[];
+}
 interface ParsedUrl {
     scheme: string;
     host: string;
@@ -1476,10 +1793,11 @@ interface OpenApiSchema {
     properties?: Record<string, OpenApiSchema>;
     items?: OpenApiSchema;
     enum?: (string | number)[];
+    const?: string | number;
     description?: string;
     minItems?: number;
     oneOf?: OpenApiSchema[];
     anyOf?: OpenApiSchema[];
 }
 
-export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, ID_BASED_VERSIONS, type JsonValue, type OpenApiSchema, type Operator, OperatorSchema, type OtherOperator, OtherOperatorSchema, type Override, OverrideSchema, type OverrideTrace, type ParsedUrl, type Policy, type PolicyActionRequest, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, type PolicyRequest, type PolicyResult, PolicySchema, RUBBERDUCK_POLICY_VERSION, type RangeValue, RangeValueSchema, type ScalarOperator, ScalarOperatorSchema, type SizeValue, SizeValueSchema, type Statement, type StatementId, StatementIdSchema, StatementSchema, type StatementTrace, type UrlOperator, UrlOperatorSchema, V3_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };
+export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, ID_BASED_VERSIONS, type JsonValue, type OpenApiSchema, type Operator, OperatorSchema, type OtherOperator, OtherOperatorSchema, type Override, OverrideSchema, type OverrideTrace, type ParsedUrl, type Policy, type PolicyActionRequest, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, type PolicyRequest, type PolicyResult, type PolicyResultV4, PolicySchema, RUBBERDUCK_POLICY_VERSION, type RangeValue, RangeValueSchema, type RuleId, RuleIdSchema, type RuleTrace, type ScalarOperator, ScalarOperatorSchema, type SizeValue, SizeValueSchema, type Statement, type StatementId, StatementIdSchema, StatementSchema, type StatementTrace, type UrlOperator, UrlOperatorSchema, V3_MAX_TIERS, V4_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };

package/dist/index.d.ts

@@ -3,14 +3,14 @@ import { z } from 'zod';
 /** Release-candidate policy document version for the current experimental shape. */
 declare const RUBBERDUCK_POLICY_VERSION: "rc-rubberduck";
 /** Supported policy document versions. */
-declare const VALID_VERSIONS: readonly [1, 2, 3, "rc-rubberduck"];
+declare const VALID_VERSIONS: readonly [1, 2, 3, 4, "rc-rubberduck"];
 /**
  * Versions whose statements carry an id (s_/p_) and are therefore targeted by
  * that id rather than canonical hash. Single source of truth shared with the
  * engine's usesIds override-targeting predicate: "requires an id" and
  * "targeted by id" coincide for every supported version.
  */
-declare const ID_BASED_VERSIONS: Set<"rc-rubberduck" | 1 | 2 | 3>;
+declare const ID_BASED_VERSIONS: Set<"rc-rubberduck" | 1 | 2 | 3 | 4>;
 /** Valid policy effects. */
 declare const VALID_EFFECTS: readonly ["allow", "ask", "deny"];
 /** Derived from VALID_EFFECTS — the constant is the single source of truth. */
@@ -359,6 +359,10 @@ type StatementId = z.infer<typeof StatementIdSchema>;
 declare const PolicyIdSchema: z.ZodString;
 /** Derived from PolicyIdSchema — the schema is the single source of truth. */
 type PolicyId = z.infer<typeof PolicyIdSchema>;
+/** Rule identifier for v4 policies. Must match ^r_\S+$ and be ≤512 chars. */
+declare const RuleIdSchema: z.ZodString;
+/** Derived from RuleIdSchema — the schema is the single source of truth. */
+type RuleId = z.infer<typeof RuleIdSchema>;
 /** Effect applied when no statement matches (rc-rubberduck, required). deny == implicit deny. */
 declare const DefaultEffectSchema: z.ZodEnum<{
     deny: "deny";
@@ -368,6 +372,8 @@ declare const DefaultEffectSchema: z.ZodEnum<{
 type DefaultEffect = z.infer<typeof DefaultEffectSchema>;
 /** Upper bound on v3 statement tiers. Raising this later is backwards-compatible. */
 declare const V3_MAX_TIERS = 3;
+/** Upper bound on v4 rule tiers. Separate from V3_MAX_TIERS so the two versions can diverge. */
+declare const V4_MAX_TIERS = 3;
 declare const PolicySchema: z.ZodUnion<readonly [z.ZodObject<{
     version: z.ZodLiteral<1>;
     statements: z.ZodArray<z.ZodObject<{
@@ -790,6 +796,147 @@ declare const PolicySchema: z.ZodUnion<readonly [z.ZodObject<{
             }, z.core.$strict>]>>;
         }, z.core.$strict>]>>>;
     }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<4>;
+    rules: z.ZodArray<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        effect: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        permissions: z.ZodArray<z.ZodString>;
+        resources: z.ZodArray<z.ZodString>;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"equals">;
+            value: z.ZodJSONSchema;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_host">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_path">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"range">;
+            value: z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"matches_url">;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"values_in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"exists">;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"keys_in">;
+            value: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodLiteral<"size">;
+            value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>]>;
+        }, z.core.$strict>, z.ZodObject<{
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            operator: z.ZodEnum<{
+                some: "some";
+                all: "all";
+                none: "none";
+            }>;
+            where: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"equals">;
+                value: z.ZodJSONSchema;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"in">;
+                value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_host">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_path">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"range">;
+                value: z.ZodObject<{
+                    min: z.ZodOptional<z.ZodNumber>;
+                    max: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"matches_url">;
+                value: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"values_in">;
+                value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"exists">;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"keys_in">;
+                value: z.ZodArray<z.ZodString>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>, z.ZodObject<{
+                negate: z.ZodOptional<z.ZodBoolean>;
+                operator: z.ZodLiteral<"size">;
+                value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                    min: z.ZodOptional<z.ZodNumber>;
+                    max: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>]>;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>]>>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodObject<{
     version: z.ZodLiteral<"rc-rubberduck">;
     id: z.ZodString;
@@ -943,15 +1090,17 @@ type Policy = z.infer<typeof PolicySchema>;
 declare const CanonicalHashSchema: z.ZodCustom<CanonicalHash, CanonicalHash>;
 /**
  * Runtime schema for the Override type. Each variant has exactly one target
- * field (statementHash for v1/v2, statementId or policyId for rc-rubberduck) and exactly
+ * field (statementHash for v1/v2, statementId for v3/rc-rubberduck, policyId for
+ * rc-rubberduck, ruleId for v4) and exactly
  * one binding mode (match, contextHash, or conditionals). `.strict()` keeps
  * the variants mutually exclusive (an object carrying fields from two variants
  * fails all branches).
  *
  * Targets are all non-null:
  * - statementHash: targets a v1/v2 statement by canonical hash
- * - statementId: targets an rc-rubberduck statement by id
+ * - statementId: targets a v3/rc-rubberduck statement by id
  * - policyId: targets that policy's default effect (rc-rubberduck only)
+ * - ruleId: targets a v4 rule by id
  *
  * Empty conditionals is intentional (the "blank check"): the override applies
  * whenever the targeted ask statement fires, with no extra conditions. Do not
@@ -1386,6 +1535,149 @@ declare const OverrideSchema: z.ZodUnion<readonly [z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     policyId: z.ZodString;
     effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    match: z.ZodLiteral<"any">;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    contextHash: z.ZodCustom<CanonicalHash, CanonicalHash>;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
+}, z.core.$strict>, z.ZodObject<{
+    conditionals: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"equals">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"in">;
+        value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_host">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_path">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"range">;
+        value: z.ZodObject<{
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"matches_url">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"values_in">;
+        value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"exists">;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"keys_in">;
+        value: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        negate: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodLiteral<"size">;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        operator: z.ZodEnum<{
+            some: "some";
+            all: "all";
+            none: "none";
+        }>;
+        where: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"equals">;
+            value: z.ZodJSONSchema;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_host">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_path">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"range">;
+            value: z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"matches_url">;
+            value: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"values_in">;
+            value: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"exists">;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"keys_in">;
+            value: z.ZodArray<z.ZodString>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>, z.ZodObject<{
+            negate: z.ZodOptional<z.ZodBoolean>;
+            operator: z.ZodLiteral<"size">;
+            value: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>]>;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>]>>;
+    id: z.ZodOptional<z.ZodString>;
+    ruleId: z.ZodString;
+    effect: z.ZodLiteral<"allow">;
 }, z.core.$strict>]>;
 /** Derived from OverrideSchema — the schema is the single source of truth. */
 type Override = z.infer<typeof OverrideSchema>;
@@ -1432,6 +1724,18 @@ interface StatementTrace {
     passed: boolean;
     overrides?: OverrideTrace[];
 }
+/**
+ * v4 rule trace. Identical to StatementTrace but the matched object is keyed
+ * `rule` instead of `statement`, matching the v4 `statements`->`rules` rename.
+ */
+interface RuleTrace {
+    rule: Statement;
+    permissionMatched: boolean;
+    resourceMatched: boolean;
+    conditionResults?: ConditionTrace[];
+    passed: boolean;
+    overrides?: OverrideTrace[];
+}
 interface EvaluatePolicyOptions {
     policy: Policy;
     request: PolicyRequest;
@@ -1447,6 +1751,19 @@ interface PolicyResult {
     /** Trace mode only. Present when no statement matched and an ask default was consulted (never attached for deny defaults). */
     default?: DefaultTrace;
 }
+/**
+ * Result of evaluating a v4 policy. Version-gated shape: the trace array is
+ * keyed `rules` (of RuleTrace) instead of `statements`, matching the v4
+ * `statements`->`rules` rename. Only ever returned for a v4 policy; all other
+ * versions return {@link PolicyResult}. v4 has no ask default (no
+ * defaultEffect), so there is no `default` field.
+ */
+interface PolicyResultV4 {
+    effect: Effect;
+    explicit: boolean;
+    reason: PolicyReason;
+    rules: RuleTrace[];
+}
 interface ParsedUrl {
     scheme: string;
     host: string;
@@ -1476,10 +1793,11 @@ interface OpenApiSchema {
     properties?: Record<string, OpenApiSchema>;
     items?: OpenApiSchema;
     enum?: (string | number)[];
+    const?: string | number;
     description?: string;
     minItems?: number;
     oneOf?: OpenApiSchema[];
     anyOf?: OpenApiSchema[];
 }
 
-export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, ID_BASED_VERSIONS, type JsonValue, type OpenApiSchema, type Operator, OperatorSchema, type OtherOperator, OtherOperatorSchema, type Override, OverrideSchema, type OverrideTrace, type ParsedUrl, type Policy, type PolicyActionRequest, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, type PolicyRequest, type PolicyResult, PolicySchema, RUBBERDUCK_POLICY_VERSION, type RangeValue, RangeValueSchema, type ScalarOperator, ScalarOperatorSchema, type SizeValue, SizeValueSchema, type Statement, type StatementId, StatementIdSchema, StatementSchema, type StatementTrace, type UrlOperator, UrlOperatorSchema, V3_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };
+export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, ID_BASED_VERSIONS, type JsonValue, type OpenApiSchema, type Operator, OperatorSchema, type OtherOperator, OtherOperatorSchema, type Override, OverrideSchema, type OverrideTrace, type ParsedUrl, type Policy, type PolicyActionRequest, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, type PolicyRequest, type PolicyResult, type PolicyResultV4, PolicySchema, RUBBERDUCK_POLICY_VERSION, type RangeValue, RangeValueSchema, type RuleId, RuleIdSchema, type RuleTrace, type ScalarOperator, ScalarOperatorSchema, type SizeValue, SizeValueSchema, type Statement, type StatementId, StatementIdSchema, StatementSchema, type StatementTrace, type UrlOperator, UrlOperatorSchema, V3_MAX_TIERS, V4_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };

package/dist/index.mjs

@@ -2,9 +2,10 @@ import { z } from 'zod';
 
 // src/schema.ts
 var RUBBERDUCK_POLICY_VERSION = "rc-rubberduck";
-var VALID_VERSIONS = [1, 2, 3, RUBBERDUCK_POLICY_VERSION];
+var VALID_VERSIONS = [1, 2, 3, 4, RUBBERDUCK_POLICY_VERSION];
 var ID_BASED_VERSIONS = /* @__PURE__ */ new Set([
   3,
+  4,
   RUBBERDUCK_POLICY_VERSION
 ]);
 var VALID_EFFECTS = ["allow", "ask", "deny"];
@@ -189,6 +190,7 @@ var V2StatementSchema = z.object({
 var StatementSchema = V2StatementSchema;
 var StatementIdSchema = z.string().regex(/^s_\S+$/, { error: "Statement id must match ^s_\\S+$" }).max(512);
 var PolicyIdSchema = z.string().regex(/^p_\S+$/, { error: "Policy id must match ^p_\\S+$" }).max(512);
+var RuleIdSchema = z.string().regex(/^r_\S+$/, { error: "Rule id must match ^r_\\S+$" }).max(512);
 var V1PolicySchema = z.object({
   version: z.literal(1),
   statements: z.array(V1StatementSchema)
@@ -225,10 +227,25 @@ var V3PolicySchema = z.object({
   // empty (e.g. `[[]]` denies everything).
   statements: z.array(z.array(V3StatementSchema)).min(1).max(V3_MAX_TIERS)
 }).strict();
+var V4_MAX_TIERS = 3;
+var V4RuleSchema = z.object({
+  id: RuleIdSchema,
+  effect: z.enum(["allow", "ask", "deny"]),
+  permissions: z.array(z.string()).min(1),
+  resources: z.array(z.string()).min(1),
+  conditions: z.array(ConditionSchema).optional()
+}).strict();
+var V4PolicySchema = z.object({
+  version: z.literal(4),
+  // Ordered tiers, in priority order. 1..V4_MAX_TIERS tiers; a tier may be
+  // empty (e.g. `[[]]` denies everything). Renamed from v3's `statements`.
+  rules: z.array(z.array(V4RuleSchema)).min(1).max(V4_MAX_TIERS)
+}).strict();
 var PolicySchema = z.union([
   V1PolicySchema,
   V2PolicySchema,
   V3PolicySchema,
+  V4PolicySchema,
   RcRubberduckPolicySchema
 ]);
 var CanonicalHashSchema = z.custom(
@@ -263,6 +280,12 @@ var OverridePolicyIdBaseShape = {
   policyId: PolicyIdSchema,
   effect: z.literal("allow")
 };
+var OverrideRuleIdBaseShape = {
+  id: z.string().optional(),
+  /** Targets a v4 rule by id (r_ prefix, non-null). */
+  ruleId: RuleIdSchema,
+  effect: z.literal("allow")
+};
 var OverrideSchema = z.union([
   // statementHash × match
   z.object({ ...OverrideHashBaseShape, match: z.literal("any") }).strict(),
@@ -290,6 +313,15 @@ var OverrideSchema = z.union([
   z.object({
     ...OverridePolicyIdBaseShape,
     conditionals: z.array(ConditionSchema)
+  }).strict(),
+  // ruleId × match
+  z.object({ ...OverrideRuleIdBaseShape, match: z.literal("any") }).strict(),
+  // ruleId × contextHash
+  z.object({ ...OverrideRuleIdBaseShape, contextHash: CanonicalHashSchema }).strict(),
+  // ruleId × conditionals
+  z.object({
+    ...OverrideRuleIdBaseShape,
+    conditionals: z.array(ConditionSchema)
   }).strict()
 ]);
 function getOpenApiSchema() {
@@ -304,7 +336,7 @@ function getOpenApiSchema() {
       effect: {
         type: "string",
         enum: [...VALID_EFFECTS].sort(),
-        description: "Whether to allow, ask, or deny the specified permissions. The 'ask' effect is valid in version 2, version 3, and rc-rubberduck policies."
+        description: "Whether to allow, ask, or deny the specified permissions. The 'ask' effect is valid in version 2, version 3, version 4, and rc-rubberduck policies."
       },
       permissions: {
         type: "array",
@@ -383,42 +415,123 @@ function getOpenApiSchema() {
       }
     }
   };
-  return {
-    type: "object",
-    required: ["version", "statements"],
+  const ruleItems = {
+    ...statementItems,
     properties: {
-      version: {
-        anyOf: [
-          { type: "integer", enum: [1, 2, 3] },
-          { type: "string", enum: [RUBBERDUCK_POLICY_VERSION] }
-        ],
-        description: "Policy schema version. Stable versions are 1, 2, and 3; supported release candidates are rc-rubberduck."
-      },
+      ...statementItems.properties,
       id: {
         type: "string",
-        description: "Policy id (required for rc-rubberduck policies; not permitted on any other version). Must use the p_ prefix and contain no whitespace."
+        description: "Rule identifier. Required for v4 policies; must use the r_ prefix with no whitespace."
       },
-      defaultEffect: {
-        type: "string",
-        enum: [...DefaultEffectSchema.options],
-        description: "Effect applied when no statement matches. Required on rc-rubberduck policies (deny equals implicit deny); not permitted on any other version."
+      resources: {
+        ...statementItems.properties.resources,
+        description: "List of resource identifiers the rule applies to."
       },
-      statements: {
-        type: "array",
-        description: "Policy statements. For v1/v2/rc-rubberduck each entry is a statement. For v3 each entry is a tier (a list of statements); tiers are in priority order and evaluated first-to-last (the first tier with a match decides), so `statements` is a list of lists.",
-        items: {
-          anyOf: [
-            statementItems,
-            {
-              type: "array",
-              description: "A v3 tier: statements evaluated together with deny > ask > allow precedence.",
-              items: statementItems
-            }
-          ]
-        }
+      conditions: {
+        ...statementItems.properties.conditions,
+        description: "Optional conditions that must be met for the rule to apply."
       }
     }
   };
+  const versionDescription = "Policy schema version. Stable versions are 1, 2, 3, and 4; supported release candidates are rc-rubberduck.";
+  const flatStatements = {
+    type: "array",
+    description: "Policy statements; each entry is a statement.",
+    items: statementItems
+  };
+  const statementTiers = {
+    type: "array",
+    description: "v3 tiers in priority order; each entry is a tier (a list of statements) evaluated first-to-last (the first tier with a match decides), so `statements` is a list of lists.",
+    items: {
+      type: "array",
+      description: "A v3 tier: statements evaluated together with deny > ask > allow precedence.",
+      items: statementItems
+    }
+  };
+  const ruleTiers = {
+    type: "array",
+    description: "v4 rules in priority order; each entry is a tier (a list of rules) evaluated first-to-last (the first tier with a match decides), so `rules` is a list of lists.",
+    items: {
+      type: "array",
+      description: "A v4 tier: rules evaluated together with deny > ask > allow precedence.",
+      items: ruleItems
+    }
+  };
+  const idProperty = {
+    type: "string",
+    description: "Policy id (rc-rubberduck only). Must use the p_ prefix and contain no whitespace."
+  };
+  const defaultEffectProperty = {
+    type: "string",
+    enum: [...DefaultEffectSchema.options],
+    description: "Effect applied when no statement matches (rc-rubberduck only; deny equals implicit deny)."
+  };
+  return {
+    oneOf: [
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 1,
+            description: versionDescription
+          },
+          statements: flatStatements
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 2,
+            description: versionDescription
+          },
+          statements: flatStatements
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "statements"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 3,
+            description: versionDescription
+          },
+          statements: statementTiers
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "rules"],
+        properties: {
+          version: {
+            type: "integer",
+            const: 4,
+            description: versionDescription
+          },
+          rules: ruleTiers
+        }
+      },
+      {
+        type: "object",
+        required: ["version", "id", "defaultEffect", "statements"],
+        properties: {
+          version: {
+            type: "string",
+            const: RUBBERDUCK_POLICY_VERSION,
+            description: versionDescription
+          },
+          id: idProperty,
+          defaultEffect: defaultEffectProperty,
+          statements: flatStatements
+        }
+      }
+    ]
+  };
 }
 
-export { ArrayOperatorSchema, CanonicalHashSchema, ConditionSchema, ConditionValueSchema, DefaultEffectSchema, ID_BASED_VERSIONS, OperatorSchema, OtherOperatorSchema, OverrideSchema, PolicyIdSchema, PolicySchema, RUBBERDUCK_POLICY_VERSION, RangeValueSchema, ScalarOperatorSchema, SizeValueSchema, StatementIdSchema, StatementSchema, UrlOperatorSchema, V3_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };
+export { ArrayOperatorSchema, CanonicalHashSchema, ConditionSchema, ConditionValueSchema, DefaultEffectSchema, ID_BASED_VERSIONS, OperatorSchema, OtherOperatorSchema, OverrideSchema, PolicyIdSchema, PolicySchema, RUBBERDUCK_POLICY_VERSION, RangeValueSchema, RuleIdSchema, ScalarOperatorSchema, SizeValueSchema, StatementIdSchema, StatementSchema, UrlOperatorSchema, V3_MAX_TIERS, V4_MAX_TIERS, VALID_EFFECTS, VALID_OPERATOR_LIST, VALID_VERSIONS, getOpenApiSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/policy-schema",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Zod schemas and TypeScript types for the Zapier policy engine",
   "type": "module",
   "main": "dist/index.cjs",