@zapier/policy-schema 0.19.0 → 1.0.0

package/dist/index.d.cts

@@ -1693,10 +1693,10 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 type ConditionValue = JsonValue | RangeValue | SizeValue;
-interface PolicyRequest {
+/** One permission/resource pair checked against the shared request context. */
+interface PolicyCheck {
     permission: string;
     resource: string;
-    context?: Record<string, unknown>;
 }
 /** SHA-256 hex digest of an RFC 8785 (JCS) canonicalized JSON value. */
 type CanonicalHash = string & {
@@ -1736,9 +1736,17 @@ interface RuleTrace {
     passed: boolean;
     overrides?: OverrideTrace[];
 }
+/**
+ * One request, one context, one or more checks. `requestContext` describes the
+ * whole request and is shared by every check; it is required and must be
+ * non-empty — an empty context has no binding to a real request, and an
+ * approval token for it could be replayed against anything. A single check
+ * is a one-element `checks` array.
+ */
 interface EvaluatePolicyOptions {
     policy: Policy;
-    request: PolicyRequest;
+    requestContext: Record<string, unknown>;
+    checks: PolicyCheck[];
     overrides?: Override[];
     trace?: boolean;
 }
@@ -1747,6 +1755,12 @@ interface PolicyResult {
     effect: Effect;
     explicit: boolean;
     reason: PolicyReason;
+    /**
+     * Ids of passed, non-overridden ask statements, in statement order. Empty
+     * unless `effect === "ask"`; always empty for v1/v2 (no statement ids) and
+     * for an ask that came from the policy's ask defaultEffect.
+     */
+    askRuleIds: string[];
     statements: StatementTrace[];
     /** Trace mode only. Present when no statement matched and an ask default was consulted (never attached for deny defaults). */
     default?: DefaultTrace;
@@ -1762,8 +1776,38 @@ interface PolicyResultV4 {
     effect: Effect;
     explicit: boolean;
     reason: PolicyReason;
+    /** Ids of passed, non-overridden ask rules. Empty unless `effect === "ask"`. */
+    askRuleIds: string[];
     rules: RuleTrace[];
 }
+/**
+ * Result of `evaluatePolicy`: the combined decision plus one per-check result.
+ * Every check is always evaluated, so on successful return `results` always
+ * has one entry per input check, in `checks` order (`results[i]` corresponds
+ * to `checks[i]`). A call can still throw for an invalid override (e.g. one
+ * targeting a deny statement or default) even when an earlier check already
+ * decided the call denies -- that override was invalid regardless of check
+ * order; evaluating every check is what surfaces it.
+ *
+ * - Deny on any check wins the combined effect (a deny cannot be approved
+ *   around), and `askRuleIds` is empty -- but `results` still reports every
+ *   check that was evaluated.
+ * - `askRuleIds` is the union of every asking check's non-overridden ask
+ *   statement/rule ids, deduplicated, first-appearance order. Empty
+ *   unless `effect === "ask"`.
+ *
+ * No combined `explicit`/`reason`: with multiple checks, which check's
+ * explicit/reason "wins" is an artifact of check order rather than a
+ * meaningful signal (e.g. an implicit deny on check[0] and an explicit deny
+ * on check[1] would report differently depending on which check ran first,
+ * even though the combined effect is deny either way). A caller that needs
+ * explicit/reason must read the per-check `results` (ENT-2614 review).
+ */
+interface EvaluatePolicyResult<R extends PolicyResult | PolicyResultV4 = PolicyResult | PolicyResultV4> {
+    effect: Effect;
+    askRuleIds: string[];
+    results: R[];
+}
 interface ParsedUrl {
     scheme: string;
     host: string;
@@ -1800,4 +1844,4 @@ interface 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, 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 };
+export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, type EvaluatePolicyResult, 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 PolicyCheck, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, 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

@@ -1693,10 +1693,10 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 type ConditionValue = JsonValue | RangeValue | SizeValue;
-interface PolicyRequest {
+/** One permission/resource pair checked against the shared request context. */
+interface PolicyCheck {
     permission: string;
     resource: string;
-    context?: Record<string, unknown>;
 }
 /** SHA-256 hex digest of an RFC 8785 (JCS) canonicalized JSON value. */
 type CanonicalHash = string & {
@@ -1736,9 +1736,17 @@ interface RuleTrace {
     passed: boolean;
     overrides?: OverrideTrace[];
 }
+/**
+ * One request, one context, one or more checks. `requestContext` describes the
+ * whole request and is shared by every check; it is required and must be
+ * non-empty — an empty context has no binding to a real request, and an
+ * approval token for it could be replayed against anything. A single check
+ * is a one-element `checks` array.
+ */
 interface EvaluatePolicyOptions {
     policy: Policy;
-    request: PolicyRequest;
+    requestContext: Record<string, unknown>;
+    checks: PolicyCheck[];
     overrides?: Override[];
     trace?: boolean;
 }
@@ -1747,6 +1755,12 @@ interface PolicyResult {
     effect: Effect;
     explicit: boolean;
     reason: PolicyReason;
+    /**
+     * Ids of passed, non-overridden ask statements, in statement order. Empty
+     * unless `effect === "ask"`; always empty for v1/v2 (no statement ids) and
+     * for an ask that came from the policy's ask defaultEffect.
+     */
+    askRuleIds: string[];
     statements: StatementTrace[];
     /** Trace mode only. Present when no statement matched and an ask default was consulted (never attached for deny defaults). */
     default?: DefaultTrace;
@@ -1762,8 +1776,38 @@ interface PolicyResultV4 {
     effect: Effect;
     explicit: boolean;
     reason: PolicyReason;
+    /** Ids of passed, non-overridden ask rules. Empty unless `effect === "ask"`. */
+    askRuleIds: string[];
     rules: RuleTrace[];
 }
+/**
+ * Result of `evaluatePolicy`: the combined decision plus one per-check result.
+ * Every check is always evaluated, so on successful return `results` always
+ * has one entry per input check, in `checks` order (`results[i]` corresponds
+ * to `checks[i]`). A call can still throw for an invalid override (e.g. one
+ * targeting a deny statement or default) even when an earlier check already
+ * decided the call denies -- that override was invalid regardless of check
+ * order; evaluating every check is what surfaces it.
+ *
+ * - Deny on any check wins the combined effect (a deny cannot be approved
+ *   around), and `askRuleIds` is empty -- but `results` still reports every
+ *   check that was evaluated.
+ * - `askRuleIds` is the union of every asking check's non-overridden ask
+ *   statement/rule ids, deduplicated, first-appearance order. Empty
+ *   unless `effect === "ask"`.
+ *
+ * No combined `explicit`/`reason`: with multiple checks, which check's
+ * explicit/reason "wins" is an artifact of check order rather than a
+ * meaningful signal (e.g. an implicit deny on check[0] and an explicit deny
+ * on check[1] would report differently depending on which check ran first,
+ * even though the combined effect is deny either way). A caller that needs
+ * explicit/reason must read the per-check `results` (ENT-2614 review).
+ */
+interface EvaluatePolicyResult<R extends PolicyResult | PolicyResultV4 = PolicyResult | PolicyResultV4> {
+    effect: Effect;
+    askRuleIds: string[];
+    results: R[];
+}
 interface ParsedUrl {
     scheme: string;
     host: string;
@@ -1800,4 +1844,4 @@ interface 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, 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 };
+export { type ArrayOperator, ArrayOperatorSchema, type CanonicalHash, CanonicalHashSchema, type Condition, ConditionSchema, type ConditionTrace, type ConditionValue, ConditionValueSchema, type DefaultEffect, DefaultEffectSchema, type DefaultTrace, type Effect, type EvaluatePolicyOptions, type EvaluatePolicyResult, 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 PolicyCheck, type PolicyHttpRequest, type PolicyId, PolicyIdSchema, type PolicyReason, 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/package.json

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