@zapier/policy-context 1.3.0 → 3.0.0

package/README.md

@@ -16,7 +16,7 @@ npm install @zapier/policy-context zod
 
 ## What it provides
 
-Three layers, each building on the previous:
+Four layers, each building on the previous:
 
 1. **Types** — Zod schemas for `HttpRequestContext`, `ActionRunContext`, and the
    `RequestContext` discriminated union. The canonical shapes stored in
@@ -25,7 +25,10 @@ Three layers, each building on the previous:
    body coercion) into validated contexts.
 3. **Conditions / Policies** — Convert stored contexts into
    [`@zapier/policy-schema`](https://www.npmjs.com/package/@zapier/policy-schema)
-   `Condition[]` and full `Policy` documents.
+   `Condition[]` and full v3 `Policy` documents with one statement tier and
+   randomly generated UUID statement IDs prefixed with `s_`.
+4. **Zapier policy validation** — `ZapierPolicySchema` composes the generic
+   `PolicySchema` with Zapier resource grammar and permission/resource rules.
 
 ## Usage
 
@@ -65,6 +68,8 @@ import { toExactPolicy } from "@zapier/policy-context";
 const policy = toExactPolicy(context);
 ```
 
+Policy builders emit version 3 policies with a single statement tier.
+
 ### Connection-scoped policies
 
 ```ts
@@ -76,6 +81,23 @@ const policy = buildConnectionPolicy({
 });
 ```
 
+### Validate a Zapier policy
+
+```ts
+import { ZapierPolicySchema } from "@zapier/policy-context";
+
+const policy = ZapierPolicySchema.parse(input);
+```
+
+This accepts `http`, `connection/{id|*}`, canonical
+`action/{selected_api}/{action_type|*}/{action_key}` patterns, and the lone `*`
+god-mode resource. It validates structure only; app, API version, and action-key
+existence remain the caller's responsibility. It also rejects a statement when
+one higher-precedence statement (`deny` > `ask` > `allow`) fully subsumes it.
+For v3 policies, validation traverses each ordered tier and masking is checked
+only within that tier. Same-effect redundancy and coverage assembled from
+multiple statements remain valid.
+
 ## License
 
 Published as part of Zapier's services. Use is governed by the

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AccessLevelSchema: () => AccessLevelSchema,
+  ActionResourcePatternSchema: () => ActionResourcePatternSchema,
   ActionRunContextInputSchema: () => ActionRunContextInputSchema,
   ActionRunContextSchema: () => ActionRunContextSchema,
   ActionTypeSchema: () => ActionTypeSchema,
@@ -33,6 +34,7 @@ __export(index_exports, {
   READ_ACTION_TYPES: () => READ_ACTION_TYPES,
   READ_HTTP_METHODS: () => READ_HTTP_METHODS,
   RequestContextSchema: () => RequestContextSchema,
+  ZapierPolicySchema: () => ZapierPolicySchema,
   buildActionResource: () => buildActionResource,
   buildActionRunContext: () => buildActionRunContext,
   buildBroadActionResource: () => buildBroadActionResource,
@@ -44,6 +46,7 @@ __export(index_exports, {
   buildHttpRequestContext: () => buildHttpRequestContext,
   buildUrlString: () => buildUrlString,
   globSelectedApiVersion: () => globSelectedApiVersion,
+  isIgnoredHeader: () => isIgnoredHeader,
   isWriteRequest: () => isWriteRequest,
   parseActionResource: () => parseActionResource,
   parseUrl: () => parseUrl,
@@ -54,6 +57,21 @@ module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
 var import_zod = require("zod");
+function containsUnsafeInteger(value) {
+  if (typeof value === "number") {
+    return Number.isInteger(value) && !Number.isSafeInteger(value);
+  }
+  if (Array.isArray(value)) {
+    return value.some(containsUnsafeInteger);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.values(value).some(containsUnsafeInteger);
+  }
+  return false;
+}
+var SafeJsonValueSchema = import_zod.z.json().refine((value) => !containsUnsafeInteger(value), {
+  message: "JSON integers must be within the IEEE-754 safe range; encode larger identifiers as strings"
+});
 var ParsedUrlSchema = import_zod.z.object({
   scheme: import_zod.z.string().describe('URL scheme, e.g. "https"'),
   host: import_zod.z.string().describe('Hostname, e.g. "api.example.com"'),
@@ -112,7 +130,7 @@ var HttpRequestContextSchema = import_zod.z.object({
    * `z.json()` still rejects non-JSON values (`Date`, `undefined`,
    * functions) at parse time. Same inferred `JsonValue` type either way.
    */
-  body_json: import_zod.z.unknown().pipe(import_zod.z.json()).nullable().describe("Parsed JSON body (if applicable)"),
+  body_json: import_zod.z.unknown().pipe(SafeJsonValueSchema).nullable().describe("Parsed JSON body (if applicable)"),
   /** Zapier connection ID used for this request */
   connection_id: import_zod.z.string().max(255).optional().describe("Zapier connection ID used for this request"),
   /** Optional human-readable reason for the request */
@@ -130,6 +148,11 @@ var ActionTypeSchema = import_zod.z.enum([
 ]).meta({ id: "action_type", description: "Canonical Zapier action type." });
 var ACTION_RESOURCE_SEGMENT_PATTERN = /^[A-Za-z0-9._+-]+(?:@[A-Za-z0-9._+-]+)?$/;
 var ACTION_KEY_SEGMENT_PATTERN = /^[A-Za-z0-9._+:-]+(?:@[A-Za-z0-9._+:-]+)?$/;
+var CONNECTION_ID_CHARS = "[^/*\\x00-\\x20\\x7f-\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]";
+var CONNECTION_ID_PATTERN = new RegExp(`^${CONNECTION_ID_CHARS}+$`);
+var CONNECTION_RESOURCE_PATTERN = new RegExp(
+  `^connection/(?:\\*|${CONNECTION_ID_CHARS}+)$`
+);
 function parseActionResource(resource) {
   const segments = resource.split("/");
   if (segments.length !== 4 || segments[0] !== "action") {
@@ -190,7 +213,7 @@ var ActionRunContextInputSchema = import_zod.z.object({
   }),
   connection_id: import_zod.z.string().max(255).optional().describe("Zapier connection ID used for this request"),
   /** Action input parameters. See body_json above for the pipe rationale. */
-  inputs: import_zod.z.unknown().pipe(import_zod.z.json()).optional().describe("Action input parameters"),
+  inputs: import_zod.z.unknown().pipe(SafeJsonValueSchema).optional().describe("Action input parameters"),
   reason: import_zod.z.string().max(1024).optional().describe("Optional human-readable reason for the request")
 }).meta({
   id: "ActionRunContext",
@@ -221,7 +244,7 @@ var ActionRunContextSchema = ActionRunContextInputSchema.transform(
       ...input.connection_id !== void 0 && {
         connection_id: input.connection_id
       },
-      ...input.inputs !== void 0 && { inputs: input.inputs },
+      ...input.inputs !== void 0 && input.inputs !== null && { inputs: input.inputs },
       ...input.reason !== void 0 && { reason: input.reason }
     };
   }
@@ -265,8 +288,15 @@ var IGNORED_HEADERS = /* @__PURE__ */ new Set([
   "x-real-ip",
   // Proxy internal — sdkapi-specific headers
   "x-is-interactive-session",
-  "x-relay-callback-url"
+  "x-relay-callback-url",
+  // Subsumed by isIgnoredHeader's x-zapier- prefix rule; kept for byte-parity
+  // with the approvalsapi source and for consumers reading the set directly.
+  "x-zapier-approval-token"
 ]);
+function isIgnoredHeader(name) {
+  const normalized = name.toLowerCase();
+  return IGNORED_HEADERS.has(normalized) || normalized.startsWith("zapier-") || normalized.startsWith("x-zapier-");
+}
 
 // src/builders.ts
 var import_zod2 = require("zod");
@@ -289,14 +319,14 @@ function buildExactHttpConditions(context) {
     conditions.push({
       path: ["url", "query", key],
       operator: "equals",
-      value: values
+      value: structuredClone(values)
     });
   }
   if (context.body_json !== null) {
     conditions.push({
       path: ["body_json"],
       operator: "equals",
-      value: context.body_json
+      value: structuredClone(context.body_json)
     });
   } else if (context.body !== null) {
     conditions.push({
@@ -306,7 +336,7 @@ function buildExactHttpConditions(context) {
     });
   }
   for (const [key, value] of Object.entries(context.headers)) {
-    if (!IGNORED_HEADERS.has(key.toLowerCase()) && typeof value === "string") {
+    if (!isIgnoredHeader(key) && typeof value === "string") {
       conditions.push({
         path: ["headers", key.toLowerCase()],
         operator: "equals",
@@ -331,7 +361,7 @@ function buildExactActionConditions(context) {
     conditions.push({
       path: ["inputs"],
       operator: "equals",
-      value: context.inputs
+      value: structuredClone(context.inputs)
     });
   }
   return conditions;
@@ -348,7 +378,7 @@ var BuildHttpRequestContextOptionsSchema = import_zod2.z.object({
   method: import_zod2.z.string(),
   /** Raw URL string. Will be normalized with https:// if no protocol present. */
   url: import_zod2.z.string(),
-  /** Raw headers from the request. Will be filtered through IGNORED_HEADERS. */
+  /** Raw headers from the request. Will be filtered through isIgnoredHeader. */
   headers: import_zod2.z.record(
     import_zod2.z.string(),
     import_zod2.z.union([import_zod2.z.string(), import_zod2.z.array(import_zod2.z.string()), import_zod2.z.undefined()])
@@ -356,7 +386,7 @@ var BuildHttpRequestContextOptionsSchema = import_zod2.z.object({
   /** Raw body string */
   body: import_zod2.z.string().nullable().optional(),
   /** Pre-parsed JSON body (e.g. from Fastify's automatic JSON parsing) */
-  body_json: import_zod2.z.json().optional(),
+  body_json: SafeJsonValueSchema.optional(),
   /** Connection ID associated with this request */
   connection_id: import_zod2.z.string().optional()
 });
@@ -368,7 +398,7 @@ function buildHttpRequestContext(options) {
   if (parsed.headers) {
     for (const [key, value] of Object.entries(parsed.headers)) {
       const lowerKey = key.toLowerCase();
-      if (!IGNORED_HEADERS.has(lowerKey) && typeof value === "string") {
+      if (!isIgnoredHeader(lowerKey) && typeof value === "string") {
         headers[lowerKey] = value;
       }
     }
@@ -391,7 +421,7 @@ function buildHttpRequestContext(options) {
     method: parsed.method.toUpperCase(),
     url,
     headers,
-    body: parsed.body ?? null,
+    body: body_json === null ? parsed.body ?? null : null,
     body_json,
     connection_id: parsed.connection_id
   });
@@ -405,7 +435,7 @@ var BuildActionRunContextOptionsSchema = import_zod2.z.object({
     message: "action_key must contain only [A-Za-z0-9._@:+-] (no globs, slashes, or whitespace)"
   }),
   connection_id: import_zod2.z.string().optional(),
-  inputs: import_zod2.z.json().optional(),
+  inputs: SafeJsonValueSchema.optional(),
   reason: import_zod2.z.string().optional()
 });
 function buildActionRunContext(options) {
@@ -426,6 +456,7 @@ function buildActionRunContext(options) {
 // src/policies.ts
 function buildAuthStatement(authenticationId) {
   return {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_use"],
     resources: [`connection/${authenticationId}`],
@@ -433,36 +464,38 @@ function buildAuthStatement(authenticationId) {
   };
 }
 function httpContextToPolicy(context) {
-  const statements = [];
-  if (context.connection_id) {
-    statements.push(buildAuthStatement(context.connection_id));
-  }
   const conditions = buildExactHttpConditions(context);
   conditions.push({
     path: ["url", "query"],
     operator: "keys_in",
     value: Object.keys(context.url.query)
   });
-  statements.push({
+  const statement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_execute"],
     resources: ["http"],
     conditions
-  });
-  return { version: 2, statements };
+  };
+  const statements = context.connection_id ? [buildAuthStatement(context.connection_id), statement] : [statement];
+  return {
+    version: 3,
+    statements: [statements]
+  };
 }
 function actionContextToPolicy(context) {
-  const statements = [];
-  if (context.connection_id) {
-    statements.push(buildAuthStatement(context.connection_id));
-  }
-  statements.push({
+  const statement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_execute"],
     resources: [context.resource],
     conditions: buildExactActionConditions(context)
-  });
-  return { version: 2, statements };
+  };
+  const statements = context.connection_id ? [buildAuthStatement(context.connection_id), statement] : [statement];
+  return {
+    version: 3,
+    statements: [statements]
+  };
 }
 function toExactPolicy(context) {
   if (context.request_type === "http_request") {
@@ -471,9 +504,140 @@ function toExactPolicy(context) {
   return actionContextToPolicy(context);
 }
 
-// src/connection-policy.ts
+// src/zapier-policy.ts
+var import_policy = require("@zapier/policy");
+var import_policy_schema = require("@zapier/policy-schema");
 var import_zod3 = require("zod");
-var AccessLevelSchema = import_zod3.z.enum(["read", "read_write"]);
+var SELECTED_API_GLOB_PART_PATTERN = /^[A-Za-z0-9._+*-]+$/;
+var ACTION_KEY_GLOB_PART_PATTERN = /^[A-Za-z0-9._+:*-]+$/;
+var PERMISSIONS = /* @__PURE__ */ new Set([
+  "can_execute",
+  "can_use",
+  "can_view",
+  "can_edit",
+  "*"
+]);
+var EFFECT_PRECEDENCE = { allow: 0, ask: 1, deny: 2 };
+function isSelectedApiPattern(value) {
+  return isGlobSegment(
+    value,
+    ACTION_RESOURCE_SEGMENT_PATTERN,
+    SELECTED_API_GLOB_PART_PATTERN
+  );
+}
+function isActionKeyPattern(value) {
+  return isGlobSegment(
+    value,
+    ACTION_KEY_SEGMENT_PATTERN,
+    ACTION_KEY_GLOB_PART_PATTERN
+  );
+}
+function isGlobSegment(value, exactPattern, globPartPattern) {
+  if (exactPattern.test(value)) {
+    return true;
+  }
+  if (!value.includes("*") || value.includes("**")) {
+    return false;
+  }
+  const parts = value.split("@");
+  return parts.length <= 2 && parts.every((part) => globPartPattern.test(part));
+}
+function isActionResourcePattern(value) {
+  const segments = value.split("/");
+  if (segments.length !== 4 || segments[0] !== "action") {
+    return false;
+  }
+  const [, selectedApi, actionType, actionKey] = segments;
+  return selectedApi !== void 0 && actionType !== void 0 && actionKey !== void 0 && isSelectedApiPattern(selectedApi) && (actionType === "*" || ActionTypeSchema.safeParse(actionType).success) && isActionKeyPattern(actionKey);
+}
+var ActionResourcePatternSchema = import_zod3.z.string().refine(isActionResourcePattern, {
+  message: "Expected action/{selected_api}/{canonical_action_type|*}/{action_key_pattern}"
+});
+function resourceFamily(resource) {
+  if (resource === "*" || resource === "http") {
+    return resource;
+  }
+  if (ActionResourcePatternSchema.safeParse(resource).success) {
+    return "action";
+  }
+  if (CONNECTION_RESOURCE_PATTERN.test(resource)) {
+    return "connection";
+  }
+  return void 0;
+}
+function permissionAppliesTo(permission, family) {
+  if (permission === "*" || family === "*") {
+    return true;
+  }
+  return permission === "can_execute" ? family === "action" || family === "http" : family === "connection";
+}
+var ZapierPolicySchema = import_policy_schema.PolicySchema.superRefine((policy, ctx) => {
+  const tiers = policy.version === 3 ? policy.statements.map((statements, tierIndex) => ({
+    statements,
+    path: ["statements", tierIndex]
+  })) : [{ statements: policy.statements, path: ["statements"] }];
+  tiers.forEach(({ statements, path }) => {
+    statements.forEach((statement, statementIndex) => {
+      const families = statement.resources.map((resource, resourceIndex) => {
+        const family = resourceFamily(resource);
+        if (family === void 0) {
+          ctx.addIssue({
+            code: "custom",
+            message: 'Expected "http", "connection/{id|*}", a valid action pattern, or "*"',
+            path: [...path, statementIndex, "resources", resourceIndex]
+          });
+        }
+        return family;
+      });
+      statement.permissions.forEach((permission, permissionIndex) => {
+        if (!PERMISSIONS.has(permission)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `Unknown Zapier permission "${permission}"`,
+            path: [...path, statementIndex, "permissions", permissionIndex]
+          });
+          return;
+        }
+        const incompatibleFamily = families.find(
+          (family) => family !== void 0 && !permissionAppliesTo(permission, family)
+        );
+        if (incompatibleFamily !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            message: `Permission "${permission}" cannot apply to ${incompatibleFamily} resources`,
+            path: [...path, statementIndex, "permissions", permissionIndex]
+          });
+        }
+      });
+      const maskingStatementIndex = statements.findIndex(
+        (maskingStatement, maskingIndex) => maskingIndex !== statementIndex && EFFECT_PRECEDENCE[maskingStatement.effect] > EFFECT_PRECEDENCE[statement.effect] && (0, import_policy.isStatementSubsumedBy)(statement, {
+          ...maskingStatement,
+          effect: statement.effect
+        })
+      );
+      if (maskingStatementIndex !== -1) {
+        const maskingStatement = statements[maskingStatementIndex];
+        const maskingId = maskingStatement.id ? ` (id "${maskingStatement.id}")` : "";
+        ctx.addIssue({
+          code: "custom",
+          message: `Statement is entirely masked by higher-precedence statement at index ${maskingStatementIndex}${maskingId}`,
+          path: [...path, statementIndex]
+        });
+      }
+    });
+  });
+});
+
+// src/connection-policy.ts
+var import_zod4 = require("zod");
+var AccessLevelSchema = import_zod4.z.enum(["read", "read_write"]);
+function requireAccessLevel(accessLevel) {
+  if (!AccessLevelSchema.safeParse(accessLevel).success) {
+    throw new Error(
+      `invalid access_level "${accessLevel}": expected "read" or "read_write"`
+    );
+  }
+}
 var READ_HTTP_METHODS = ["GET", "HEAD", "OPTIONS"];
 var READ_ACTION_TYPES = [
   "read",
@@ -493,7 +657,19 @@ function isWriteRequest(context) {
 }
 function buildConnectionPolicy(options) {
   const { connectionId, selectedApi, accessLevel } = options;
+  requireAccessLevel(accessLevel);
+  if (!CONNECTION_ID_PATTERN.test(connectionId)) {
+    throw new Error(
+      `invalid connection_id "${connectionId}": must not contain "/", "*", or whitespace`
+    );
+  }
+  if (!ACTION_RESOURCE_SEGMENT_PATTERN.test(selectedApi)) {
+    throw new Error(
+      `invalid selected_api "${selectedApi}": must not contain "/", "*", or whitespace`
+    );
+  }
   const authStatement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_use"],
     resources: [`connection/${connectionId}`],
@@ -513,6 +689,7 @@ function buildConnectionPolicy(options) {
     });
   }
   const httpStatement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_execute"],
     resources: ["http"],
@@ -521,20 +698,22 @@ function buildConnectionPolicy(options) {
   const apiPattern = globSelectedApiVersion(selectedApi);
   const actionResources = accessLevel === "read" ? READ_ACTION_TYPES.map((t) => `action/${apiPattern}/${t}/*`) : [`action/${apiPattern}/*/*`];
   const actionStatement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_execute"],
     resources: actionResources,
     conditions: [connectionCondition]
   };
   return {
-    version: 2,
-    statements: [authStatement, httpStatement, actionStatement]
+    version: 3,
+    statements: [[authStatement, httpStatement, actionStatement]]
   };
 }
 
 // src/connectionless-policy.ts
 function buildConnectionlessPolicy(options) {
   const { context, accessLevel } = options;
+  requireAccessLevel(accessLevel);
   if (context.request_type === "http_request") {
     const conditions = [
       {
@@ -551,27 +730,36 @@ function buildConnectionlessPolicy(options) {
       });
     }
     const statement2 = {
+      id: `s_${crypto.randomUUID()}`,
       effect: "allow",
       permissions: ["can_execute"],
       resources: ["http"],
       conditions
     };
-    return { version: 2, statements: [statement2] };
+    return {
+      version: 3,
+      statements: [[statement2]]
+    };
   }
   const { selected_api } = parseActionResource(context.resource);
   const apiPattern = globSelectedApiVersion(selected_api);
   const resources = accessLevel === "read" ? READ_ACTION_TYPES.map((t) => `action/${apiPattern}/${t}/*`) : [`action/${apiPattern}/*/*`];
   const statement = {
+    id: `s_${crypto.randomUUID()}`,
     effect: "allow",
     permissions: ["can_execute"],
     resources,
     conditions: []
   };
-  return { version: 2, statements: [statement] };
+  return {
+    version: 3,
+    statements: [[statement]]
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AccessLevelSchema,
+  ActionResourcePatternSchema,
   ActionRunContextInputSchema,
   ActionRunContextSchema,
   ActionTypeSchema,
@@ -584,6 +772,7 @@ function buildConnectionlessPolicy(options) {
   READ_ACTION_TYPES,
   READ_HTTP_METHODS,
   RequestContextSchema,
+  ZapierPolicySchema,
   buildActionResource,
   buildActionRunContext,
   buildBroadActionResource,
@@ -595,6 +784,7 @@ function buildConnectionlessPolicy(options) {
   buildHttpRequestContext,
   buildUrlString,
   globSelectedApiVersion,
+  isIgnoredHeader,
   isWriteRequest,
   parseActionResource,
   parseUrl,