@metamask-previews/gator-permissions-controller 4.1.2-preview-9fb8d00e7 → 4.1.2-preview-784cc181c

package/dist/constants.d.cts

@@ -16,11 +16,4 @@ export declare const EXECUTION_PERMISSION_REDEEMER_RULE_TYPE: "redeemer";
  * payee restrictions.
  */
 export declare const EXECUTION_PERMISSION_PAYEE_RULE_TYPE: "payee";
-/**
- * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for
- * permission expiry derived from a TimestampEnforcer caveat. The decoded
- * permission additionally hoists the expiry value onto its top-level `expiry`
- * field for convenience.
- */
-export declare const EXECUTION_PERMISSION_EXPIRY_RULE_TYPE: "expiry";
 //# sourceMappingURL=constants.d.cts.map

package/dist/constants.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.cts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,YAAsB,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,SAAmB,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,UAAoB,CAAC"}
+{"version":3,"file":"constants.d.cts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,YAAsB,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,SAAmB,CAAC"}

package/dist/constants.d.mts

@@ -16,11 +16,4 @@ export declare const EXECUTION_PERMISSION_REDEEMER_RULE_TYPE: "redeemer";
  * payee restrictions.
  */
 export declare const EXECUTION_PERMISSION_PAYEE_RULE_TYPE: "payee";
-/**
- * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for
- * permission expiry derived from a TimestampEnforcer caveat. The decoded
- * permission additionally hoists the expiry value onto its top-level `expiry`
- * field for convenience.
- */
-export declare const EXECUTION_PERMISSION_EXPIRY_RULE_TYPE: "expiry";
 //# sourceMappingURL=constants.d.mts.map

package/dist/constants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.mts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,YAAsB,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,SAAmB,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,UAAoB,CAAC"}
+{"version":3,"file":"constants.d.mts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,YAAsB,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,SAAmB,CAAC"}

package/dist/constants.mjs

@@ -16,11 +16,4 @@ export const EXECUTION_PERMISSION_REDEEMER_RULE_TYPE = 'redeemer';
  * payee restrictions.
  */
 export const EXECUTION_PERMISSION_PAYEE_RULE_TYPE = 'payee';
-/**
- * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for
- * permission expiry derived from a TimestampEnforcer caveat. The decoded
- * permission additionally hoists the expiry value onto its top-level `expiry`
- * field for convenience.
- */
-export const EXECUTION_PERMISSION_EXPIRY_RULE_TYPE = 'expiry';
 //# sourceMappingURL=constants.mjs.map

package/dist/constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.mjs","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,UAAmB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,OAAgB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,QAAiB,CAAC","sourcesContent":["/**\n * Delegation framework version used to select the correct deployed enforcer\n * contract addresses from `@metamask/delegation-deployments`.\n */\nexport const DELEGATION_FRAMEWORK_VERSION = '1.3.0';\n\n/**\n * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for\n * redeemer allowlists (RedeemerEnforcer). Hosts should advertise this for every\n * supported execution permission type.\n */\nexport const EXECUTION_PERMISSION_REDEEMER_RULE_TYPE = 'redeemer' as const;\n\n/**\n * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for\n * payee allowlists (AllowedCalldataEnforcer / AllowedTargetsEnforcer). Hosts\n * should advertise this for every supported execution permission type that supports\n * payee restrictions.\n */\nexport const EXECUTION_PERMISSION_PAYEE_RULE_TYPE = 'payee' as const;\n\n/**\n * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for\n * permission expiry derived from a TimestampEnforcer caveat. The decoded\n * permission additionally hoists the expiry value onto its top-level `expiry`\n * field for convenience.\n */\nexport const EXECUTION_PERMISSION_EXPIRY_RULE_TYPE = 'expiry' as const;\n"]}
+{"version":3,"file":"constants.mjs","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,UAAmB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,OAAgB,CAAC","sourcesContent":["/**\n * Delegation framework version used to select the correct deployed enforcer\n * contract addresses from `@metamask/delegation-deployments`.\n */\nexport const DELEGATION_FRAMEWORK_VERSION = '1.3.0';\n\n/**\n * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for\n * redeemer allowlists (RedeemerEnforcer). Hosts should advertise this for every\n * supported execution permission type.\n */\nexport const EXECUTION_PERMISSION_REDEEMER_RULE_TYPE = 'redeemer' as const;\n\n/**\n * `Rule.type` / `wallet_getSupportedExecutionPermissions` `ruleTypes` entry for\n * payee allowlists (AllowedCalldataEnforcer / AllowedTargetsEnforcer). Hosts\n * should advertise this for every supported execution permission type that supports\n * payee restrictions.\n */\nexport const EXECUTION_PERMISSION_PAYEE_RULE_TYPE = 'payee' as const;\n"]}

package/dist/decodePermission/decodePermission.cjs

@@ -1,44 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reconstructDecodedPermission = exports.selectUniqueDecoderAndDecodedPermission = exports.findDecodersWithMatchingCaveatAddresses = void 0;
+exports.reconstructDecodedPermission = exports.selectUniqueRuleAndDecodedPermission = exports.findRuleWithMatchingCaveatAddresses = exports.findRulesWithMatchingCaveatAddresses = void 0;
 const delegation_core_1 = require("@metamask/delegation-core");
 const utils_1 = require("@metamask/utils");
 /**
- * Returns every permission decoder whose caveat-address pattern matches the
- * given enforcer list for the chain. Used when more than one permission type
- * can share the same enforcer set; the caller must disambiguate by validating
- * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).
+ * Returns every permission rule whose caveat-address pattern matches the given
+ * enforcer list for the chain. Used when more than one permission type can
+ * share the same enforcer set; the caller must disambiguate by validating
+ * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).
  *
  * @param args - The arguments to this function.
  * @param args.enforcers - List of enforcer contract addresses (hex strings).
- * @param args.permissionDecoders - The permission decoders for the chain.
- * @returns All decoders that match, possibly empty.
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns All rules that match, possibly empty.
  */
-const findDecodersWithMatchingCaveatAddresses = ({ enforcers, permissionDecoders, }) => {
-    return permissionDecoders.filter((decoder) => decoder.caveatAddressesMatch(enforcers));
+const findRulesWithMatchingCaveatAddresses = ({ enforcers, permissionRules, }) => {
+    return permissionRules.filter((rule) => rule.caveatAddressesMatch(enforcers));
 };
-exports.findDecodersWithMatchingCaveatAddresses = findDecodersWithMatchingCaveatAddresses;
+exports.findRulesWithMatchingCaveatAddresses = findRulesWithMatchingCaveatAddresses;
 /**
- * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate
- * decoder. Use when several decoders share the same caveat addresses.
+ * Returns the unique permission rule that matches a given set of enforcer
+ * contract addresses (caveat types) for a specific chain.
+ *
+ * A rule matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the rule's required and
+ * optional enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one rule matches, it is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns The matching permission rule.
+ * @throws If no rule matches, or if more than one rule matches.
+ */
+const findRuleWithMatchingCaveatAddresses = ({ enforcers, permissionRules, }) => {
+    const matchingRules = (0, exports.findRulesWithMatchingCaveatAddresses)({
+        enforcers,
+        permissionRules,
+    });
+    if (matchingRules.length === 0) {
+        throw new Error('Unable to identify permission type');
+    }
+    if (matchingRules.length > 1) {
+        throw new Error('Multiple permission types match');
+    }
+    return matchingRules[0];
+};
+exports.findRuleWithMatchingCaveatAddresses = findRuleWithMatchingCaveatAddresses;
+/**
+ * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate
+ * rule. Use when several rules share the same caveat addresses.
  *
  * @param args - The arguments to this function.
- * @param args.candidateDecoders - Decoders whose addresses already match the caveats.
+ * @param args.candidateRules - Rules whose addresses already match the caveats.
  * @param args.caveats - Caveats from the delegation.
- * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.
- * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.
+ * @returns The unique rule and decoded expiry/data when exactly one rule validates.
+ * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.
  */
-const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, caveats, }) => {
-    if (candidateDecoders.length === 0) {
+const selectUniqueRuleAndDecodedPermission = ({ candidateRules, caveats, }) => {
+    if (candidateRules.length === 0) {
         throw new Error('Unable to identify permission type');
     }
     const successfulDecodingResult = [];
     const failedAttempts = [];
-    for (const decoder of candidateDecoders) {
-        const decodeResult = decoder.validateAndDecodePermission(caveats);
+    for (const rule of candidateRules) {
+        const decodeResult = rule.validateAndDecodePermission(caveats);
         if (decodeResult.isValid) {
             successfulDecodingResult.push({
-                decoder,
+                rule,
                 rules: decodeResult.rules,
                 data: decodeResult.data,
                 expiry: decodeResult.expiry,
@@ -46,7 +77,7 @@ const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, caveats, }
         }
         else {
             failedAttempts.push({
-                permissionType: decoder.permissionType,
+                permissionType: rule.permissionType,
                 error: decodeResult.error,
             });
         }
@@ -56,7 +87,7 @@ const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, caveats, }
     }
     if (successfulDecodingResult.length > 1) {
         const types = successfulDecodingResult
-            .map((result) => result.decoder.permissionType)
+            .map((result) => result.rule.permissionType)
             .join(', ');
         throw new Error(`Multiple permission types validate the same delegation caveats: ${types}`);
     }
@@ -68,11 +99,18 @@ const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, caveats, }
         .join('; ');
     throw new Error(`No permission type could validate the delegation caveats. Attempts: ${details}`);
 };
-exports.selectUniqueDecoderAndDecodedPermission = selectUniqueDecoderAndDecodedPermission;
+exports.selectUniqueRuleAndDecodedPermission = selectUniqueRuleAndDecodedPermission;
 /**
  * Reconstructs a {@link DecodedPermission} object from primitive values
  * obtained while decoding a permission context.
  *
+ * The resulting object contains:
+ * - `chainId` encoded as hex (`0x…`)
+ * - `address` set to the delegator (user account)
+ * - `signer` set to an account signer with the delegate address
+ * - `permission` with the identified type and decoded data
+ * - `expiry` timestamp (or null)
+ *
  * @param args - The arguments to this function.
  * @param args.chainId - Chain ID.
  * @param args.permissionType - Identified permission type.

package/dist/decodePermission/decodePermission.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"decodePermission.cjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  PermissionType,\n  PermissionDecoder,\n  ValidateAndDecodeResult,\n} from './types';\n\n/**\n * Returns every permission decoder whose caveat-address pattern matches the\n * given enforcer list for the chain. Used when more than one permission type\n * can share the same enforcer set; the caller must disambiguate by validating\n * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionDecoders - The permission decoders for the chain.\n * @returns All decoders that match, possibly empty.\n */\nexport const findDecodersWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionDecoders,\n}: {\n  enforcers: Hex[];\n  permissionDecoders: PermissionDecoder[];\n}): PermissionDecoder[] => {\n  return permissionDecoders.filter((decoder) =>\n    decoder.caveatAddressesMatch(enforcers),\n  );\n};\n\ntype SuccessfulValidateAndDecodeResult = Extract<\n  ValidateAndDecodeResult,\n  { isValid: true }\n>;\n\ntype DecoderAndDecodedPermission = {\n  decoder: PermissionDecoder;\n  rules: SuccessfulValidateAndDecodeResult['rules'];\n  data: SuccessfulValidateAndDecodeResult['data'];\n  expiry: SuccessfulValidateAndDecodeResult['expiry'];\n};\n\n/**\n * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate\n * decoder. Use when several decoders share the same caveat addresses.\n *\n * @param args - The arguments to this function.\n * @param args.candidateDecoders - Decoders whose addresses already match the caveats.\n * @param args.caveats - Caveats from the delegation.\n * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.\n * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.\n */\nexport const selectUniqueDecoderAndDecodedPermission = ({\n  candidateDecoders,\n  caveats,\n}: {\n  candidateDecoders: PermissionDecoder[];\n  caveats: Caveat<Hex>[];\n}): DecoderAndDecodedPermission => {\n  if (candidateDecoders.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  const successfulDecodingResult: DecoderAndDecodedPermission[] = [];\n\n  const failedAttempts: { permissionType: PermissionType; error: Error }[] = [];\n\n  for (const decoder of candidateDecoders) {\n    const decodeResult = decoder.validateAndDecodePermission(caveats);\n    if (decodeResult.isValid) {\n      successfulDecodingResult.push({\n        decoder,\n        rules: decodeResult.rules,\n        data: decodeResult.data,\n        expiry: decodeResult.expiry,\n      });\n    } else {\n      failedAttempts.push({\n        permissionType: decoder.permissionType,\n        error: decodeResult.error,\n      });\n    }\n  }\n\n  if (successfulDecodingResult.length === 1) {\n    return successfulDecodingResult[0];\n  }\n\n  if (successfulDecodingResult.length > 1) {\n    const types = successfulDecodingResult\n      .map((result) => result.decoder.permissionType)\n      .join(', ');\n    throw new Error(\n      `Multiple permission types validate the same delegation caveats: ${types}`,\n    );\n  }\n\n  if (failedAttempts.length === 1) {\n    throw failedAttempts[0].error;\n  }\n\n  const details = failedAttempts\n    .map(\n      (attempt) =>\n        `${String(attempt.permissionType)}: ${attempt.error.message}`,\n    )\n    .join('; ');\n\n  throw new Error(\n    `No permission type could validate the delegation caveats. Attempts: ${details}`,\n  );\n};\n\n/**\n * Reconstructs a {@link DecodedPermission} object from primitive values\n * obtained while decoding a permission context.\n *\n * @param args - The arguments to this function.\n * @param args.chainId - Chain ID.\n * @param args.permissionType - Identified permission type.\n * @param args.delegator - Address of the account delegating permission.\n * @param args.delegate - Address that will act under the granted permission.\n * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.\n * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.\n * @param args.data - Permission-specific decoded data payload.\n * @param args.justification - Human-readable justification for the permission.\n * @param args.specifiedOrigin - The origin reported in the request metadata.\n * @param args.rules - Rules recovered from caveats (e.g. redeemer allowlist).\n *\n * @returns The reconstructed {@link DecodedPermission}.\n */\nexport const reconstructDecodedPermission = ({\n  chainId,\n  permissionType,\n  delegator,\n  delegate,\n  authority,\n  expiry,\n  data,\n  justification,\n  specifiedOrigin,\n  rules,\n}: {\n  chainId: number;\n  permissionType: PermissionType;\n  delegator: Hex;\n  delegate: Hex;\n  authority: Hex;\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n  justification: string;\n  specifiedOrigin: string;\n  rules?: DecodedPermission['rules'];\n}): DecodedPermission => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    from: delegator,\n    to: delegate,\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n    ...(rules === undefined ? {} : { rules }),\n  };\n\n  return permission;\n};\n"]}
+{"version":3,"file":"decodePermission.cjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  PermissionType,\n  PermissionRule,\n  ValidateAndDecodeResult,\n} from './types';\n\n/**\n * Returns every permission rule whose caveat-address pattern matches the given\n * enforcer list for the chain. Used when more than one permission type can\n * share the same enforcer set; the caller must disambiguate by validating\n * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionRules - The permission rules for the chain.\n * @returns All rules that match, possibly empty.\n */\nexport const findRulesWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionRules,\n}: {\n  enforcers: Hex[];\n  permissionRules: PermissionRule[];\n}): PermissionRule[] => {\n  return permissionRules.filter((rule) => rule.caveatAddressesMatch(enforcers));\n};\n\n/**\n * Returns the unique permission rule that matches a given set of enforcer\n * contract addresses (caveat types) for a specific chain.\n *\n * A rule matches when:\n * - All of its required enforcers are present in the provided list; and\n * - No provided enforcer falls outside the union of the rule's required and\n * optional enforcers (currently only `TimestampEnforcer` is allowed extra).\n *\n * If exactly one rule matches, it is returned.\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionRules - The permission rules for the chain.\n * @returns The matching permission rule.\n * @throws If no rule matches, or if more than one rule matches.\n */\nexport const findRuleWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionRules,\n}: {\n  enforcers: Hex[];\n  permissionRules: PermissionRule[];\n}): PermissionRule => {\n  const matchingRules = findRulesWithMatchingCaveatAddresses({\n    enforcers,\n    permissionRules,\n  });\n\n  if (matchingRules.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n  if (matchingRules.length > 1) {\n    throw new Error('Multiple permission types match');\n  }\n  return matchingRules[0];\n};\n\ntype SuccessfulValidateAndDecodeResult = Extract<\n  ValidateAndDecodeResult,\n  { isValid: true }\n>;\n\ntype RuleAndDecodedPermission = {\n  rule: PermissionRule;\n  rules: SuccessfulValidateAndDecodeResult['rules'];\n  data: SuccessfulValidateAndDecodeResult['data'];\n  expiry: SuccessfulValidateAndDecodeResult['expiry'];\n};\n\n/**\n * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate\n * rule. Use when several rules share the same caveat addresses.\n *\n * @param args - The arguments to this function.\n * @param args.candidateRules - Rules whose addresses already match the caveats.\n * @param args.caveats - Caveats from the delegation.\n * @returns The unique rule and decoded expiry/data when exactly one rule validates.\n * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.\n */\nexport const selectUniqueRuleAndDecodedPermission = ({\n  candidateRules,\n  caveats,\n}: {\n  candidateRules: PermissionRule[];\n  caveats: Caveat<Hex>[];\n}): RuleAndDecodedPermission => {\n  if (candidateRules.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  const successfulDecodingResult: RuleAndDecodedPermission[] = [];\n\n  const failedAttempts: { permissionType: PermissionType; error: Error }[] = [];\n\n  for (const rule of candidateRules) {\n    const decodeResult = rule.validateAndDecodePermission(caveats);\n    if (decodeResult.isValid) {\n      successfulDecodingResult.push({\n        rule,\n        rules: decodeResult.rules,\n        data: decodeResult.data,\n        expiry: decodeResult.expiry,\n      });\n    } else {\n      failedAttempts.push({\n        permissionType: rule.permissionType,\n        error: decodeResult.error,\n      });\n    }\n  }\n\n  if (successfulDecodingResult.length === 1) {\n    return successfulDecodingResult[0];\n  }\n\n  if (successfulDecodingResult.length > 1) {\n    const types = successfulDecodingResult\n      .map((result) => result.rule.permissionType)\n      .join(', ');\n    throw new Error(\n      `Multiple permission types validate the same delegation caveats: ${types}`,\n    );\n  }\n\n  if (failedAttempts.length === 1) {\n    throw failedAttempts[0].error;\n  }\n\n  const details = failedAttempts\n    .map(\n      (attempt) =>\n        `${String(attempt.permissionType)}: ${attempt.error.message}`,\n    )\n    .join('; ');\n\n  throw new Error(\n    `No permission type could validate the delegation caveats. Attempts: ${details}`,\n  );\n};\n\n/**\n * Reconstructs a {@link DecodedPermission} object from primitive values\n * obtained while decoding a permission context.\n *\n * The resulting object contains:\n * - `chainId` encoded as hex (`0x…`)\n * - `address` set to the delegator (user account)\n * - `signer` set to an account signer with the delegate address\n * - `permission` with the identified type and decoded data\n * - `expiry` timestamp (or null)\n *\n * @param args - The arguments to this function.\n * @param args.chainId - Chain ID.\n * @param args.permissionType - Identified permission type.\n * @param args.delegator - Address of the account delegating permission.\n * @param args.delegate - Address that will act under the granted permission.\n * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.\n * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.\n * @param args.data - Permission-specific decoded data payload.\n * @param args.justification - Human-readable justification for the permission.\n * @param args.specifiedOrigin - The origin reported in the request metadata.\n * @param args.rules - Rules recovered from caveats (e.g. redeemer allowlist).\n *\n * @returns The reconstructed {@link DecodedPermission}.\n */\nexport const reconstructDecodedPermission = ({\n  chainId,\n  permissionType,\n  delegator,\n  delegate,\n  authority,\n  expiry,\n  data,\n  justification,\n  specifiedOrigin,\n  rules,\n}: {\n  chainId: number;\n  permissionType: PermissionType;\n  delegator: Hex;\n  delegate: Hex;\n  authority: Hex;\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n  justification: string;\n  specifiedOrigin: string;\n  rules?: DecodedPermission['rules'];\n}): DecodedPermission => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    from: delegator,\n    to: delegate,\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n    ...(rules === undefined ? {} : { rules }),\n  };\n\n  return permission;\n};\n"]}

package/dist/decodePermission/decodePermission.d.cts

@@ -1,47 +1,75 @@
 import type { Caveat, Hex } from "@metamask/delegation-core";
-import type { DecodedPermission, PermissionType, PermissionDecoder, ValidateAndDecodeResult } from "./types.cjs";
+import type { DecodedPermission, PermissionType, PermissionRule, ValidateAndDecodeResult } from "./types.cjs";
 /**
- * Returns every permission decoder whose caveat-address pattern matches the
- * given enforcer list for the chain. Used when more than one permission type
- * can share the same enforcer set; the caller must disambiguate by validating
- * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).
+ * Returns every permission rule whose caveat-address pattern matches the given
+ * enforcer list for the chain. Used when more than one permission type can
+ * share the same enforcer set; the caller must disambiguate by validating
+ * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).
  *
  * @param args - The arguments to this function.
  * @param args.enforcers - List of enforcer contract addresses (hex strings).
- * @param args.permissionDecoders - The permission decoders for the chain.
- * @returns All decoders that match, possibly empty.
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns All rules that match, possibly empty.
  */
-export declare const findDecodersWithMatchingCaveatAddresses: ({ enforcers, permissionDecoders, }: {
+export declare const findRulesWithMatchingCaveatAddresses: ({ enforcers, permissionRules, }: {
     enforcers: Hex[];
-    permissionDecoders: PermissionDecoder[];
-}) => PermissionDecoder[];
+    permissionRules: PermissionRule[];
+}) => PermissionRule[];
+/**
+ * Returns the unique permission rule that matches a given set of enforcer
+ * contract addresses (caveat types) for a specific chain.
+ *
+ * A rule matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the rule's required and
+ * optional enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one rule matches, it is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns The matching permission rule.
+ * @throws If no rule matches, or if more than one rule matches.
+ */
+export declare const findRuleWithMatchingCaveatAddresses: ({ enforcers, permissionRules, }: {
+    enforcers: Hex[];
+    permissionRules: PermissionRule[];
+}) => PermissionRule;
 type SuccessfulValidateAndDecodeResult = Extract<ValidateAndDecodeResult, {
     isValid: true;
 }>;
-type DecoderAndDecodedPermission = {
-    decoder: PermissionDecoder;
+type RuleAndDecodedPermission = {
+    rule: PermissionRule;
     rules: SuccessfulValidateAndDecodeResult['rules'];
     data: SuccessfulValidateAndDecodeResult['data'];
     expiry: SuccessfulValidateAndDecodeResult['expiry'];
 };
 /**
- * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate
- * decoder. Use when several decoders share the same caveat addresses.
+ * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate
+ * rule. Use when several rules share the same caveat addresses.
  *
  * @param args - The arguments to this function.
- * @param args.candidateDecoders - Decoders whose addresses already match the caveats.
+ * @param args.candidateRules - Rules whose addresses already match the caveats.
  * @param args.caveats - Caveats from the delegation.
- * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.
- * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.
+ * @returns The unique rule and decoded expiry/data when exactly one rule validates.
+ * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.
  */
-export declare const selectUniqueDecoderAndDecodedPermission: ({ candidateDecoders, caveats, }: {
-    candidateDecoders: PermissionDecoder[];
+export declare const selectUniqueRuleAndDecodedPermission: ({ candidateRules, caveats, }: {
+    candidateRules: PermissionRule[];
     caveats: Caveat<Hex>[];
-}) => DecoderAndDecodedPermission;
+}) => RuleAndDecodedPermission;
 /**
  * Reconstructs a {@link DecodedPermission} object from primitive values
  * obtained while decoding a permission context.
  *
+ * The resulting object contains:
+ * - `chainId` encoded as hex (`0x…`)
+ * - `address` set to the delegator (user account)
+ * - `signer` set to an account signer with the delegate address
+ * - `permission` with the identified type and decoded data
+ * - `expiry` timestamp (or null)
+ *
  * @param args - The arguments to this function.
  * @param args.chainId - Chain ID.
  * @param args.permissionType - Identified permission type.

package/dist/decodePermission/decodePermission.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"decodePermission.d.cts","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,kCAAkC;AAI7D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACxB,oBAAgB;AAEjB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uCAAuC;eAIvC,GAAG,EAAE;wBACI,iBAAiB,EAAE;MACrC,iBAAiB,EAIpB,CAAC;AAEF,KAAK,iCAAiC,GAAG,OAAO,CAC9C,uBAAuB,EACvB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAClB,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,EAAE,iCAAiC,CAAC,QAAQ,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uCAAuC;uBAI/B,iBAAiB,EAAE;aAC7B,OAAO,GAAG,CAAC,EAAE;MACpB,2BAqDH,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B;aAY9B,MAAM;oBACC,cAAc;eACnB,GAAG;cACJ,GAAG;eACF,GAAG;YACN,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;mBAC9B,MAAM;qBACJ,MAAM;YACf,iBAAiB,CAAC,OAAO,CAAC;MAChC,iBAoBH,CAAC"}
+{"version":3,"file":"decodePermission.d.cts","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,kCAAkC;AAI7D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,uBAAuB,EACxB,oBAAgB;AAEjB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oCAAoC;eAIpC,GAAG,EAAE;qBACC,cAAc,EAAE;MAC/B,cAAc,EAEjB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mCAAmC;eAInC,GAAG,EAAE;qBACC,cAAc,EAAE;MAC/B,cAaH,CAAC;AAEF,KAAK,iCAAiC,GAAG,OAAO,CAC9C,uBAAuB,EACvB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAClB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,EAAE,iCAAiC,CAAC,QAAQ,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,oCAAoC;oBAI/B,cAAc,EAAE;aACvB,OAAO,GAAG,CAAC,EAAE;MACpB,wBAqDH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,4BAA4B;aAY9B,MAAM;oBACC,cAAc;eACnB,GAAG;cACJ,GAAG;eACF,GAAG;YACN,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;mBAC9B,MAAM;qBACJ,MAAM;YACf,iBAAiB,CAAC,OAAO,CAAC;MAChC,iBAoBH,CAAC"}

package/dist/decodePermission/decodePermission.d.mts

@@ -1,47 +1,75 @@
 import type { Caveat, Hex } from "@metamask/delegation-core";
-import type { DecodedPermission, PermissionType, PermissionDecoder, ValidateAndDecodeResult } from "./types.mjs";
+import type { DecodedPermission, PermissionType, PermissionRule, ValidateAndDecodeResult } from "./types.mjs";
 /**
- * Returns every permission decoder whose caveat-address pattern matches the
- * given enforcer list for the chain. Used when more than one permission type
- * can share the same enforcer set; the caller must disambiguate by validating
- * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).
+ * Returns every permission rule whose caveat-address pattern matches the given
+ * enforcer list for the chain. Used when more than one permission type can
+ * share the same enforcer set; the caller must disambiguate by validating
+ * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).
  *
  * @param args - The arguments to this function.
  * @param args.enforcers - List of enforcer contract addresses (hex strings).
- * @param args.permissionDecoders - The permission decoders for the chain.
- * @returns All decoders that match, possibly empty.
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns All rules that match, possibly empty.
  */
-export declare const findDecodersWithMatchingCaveatAddresses: ({ enforcers, permissionDecoders, }: {
+export declare const findRulesWithMatchingCaveatAddresses: ({ enforcers, permissionRules, }: {
     enforcers: Hex[];
-    permissionDecoders: PermissionDecoder[];
-}) => PermissionDecoder[];
+    permissionRules: PermissionRule[];
+}) => PermissionRule[];
+/**
+ * Returns the unique permission rule that matches a given set of enforcer
+ * contract addresses (caveat types) for a specific chain.
+ *
+ * A rule matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the rule's required and
+ * optional enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one rule matches, it is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns The matching permission rule.
+ * @throws If no rule matches, or if more than one rule matches.
+ */
+export declare const findRuleWithMatchingCaveatAddresses: ({ enforcers, permissionRules, }: {
+    enforcers: Hex[];
+    permissionRules: PermissionRule[];
+}) => PermissionRule;
 type SuccessfulValidateAndDecodeResult = Extract<ValidateAndDecodeResult, {
     isValid: true;
 }>;
-type DecoderAndDecodedPermission = {
-    decoder: PermissionDecoder;
+type RuleAndDecodedPermission = {
+    rule: PermissionRule;
     rules: SuccessfulValidateAndDecodeResult['rules'];
     data: SuccessfulValidateAndDecodeResult['data'];
     expiry: SuccessfulValidateAndDecodeResult['expiry'];
 };
 /**
- * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate
- * decoder. Use when several decoders share the same caveat addresses.
+ * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate
+ * rule. Use when several rules share the same caveat addresses.
  *
  * @param args - The arguments to this function.
- * @param args.candidateDecoders - Decoders whose addresses already match the caveats.
+ * @param args.candidateRules - Rules whose addresses already match the caveats.
  * @param args.caveats - Caveats from the delegation.
- * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.
- * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.
+ * @returns The unique rule and decoded expiry/data when exactly one rule validates.
+ * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.
  */
-export declare const selectUniqueDecoderAndDecodedPermission: ({ candidateDecoders, caveats, }: {
-    candidateDecoders: PermissionDecoder[];
+export declare const selectUniqueRuleAndDecodedPermission: ({ candidateRules, caveats, }: {
+    candidateRules: PermissionRule[];
     caveats: Caveat<Hex>[];
-}) => DecoderAndDecodedPermission;
+}) => RuleAndDecodedPermission;
 /**
  * Reconstructs a {@link DecodedPermission} object from primitive values
  * obtained while decoding a permission context.
  *
+ * The resulting object contains:
+ * - `chainId` encoded as hex (`0x…`)
+ * - `address` set to the delegator (user account)
+ * - `signer` set to an account signer with the delegate address
+ * - `permission` with the identified type and decoded data
+ * - `expiry` timestamp (or null)
+ *
  * @param args - The arguments to this function.
  * @param args.chainId - Chain ID.
  * @param args.permissionType - Identified permission type.

package/dist/decodePermission/decodePermission.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"decodePermission.d.mts","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,kCAAkC;AAI7D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACxB,oBAAgB;AAEjB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uCAAuC;eAIvC,GAAG,EAAE;wBACI,iBAAiB,EAAE;MACrC,iBAAiB,EAIpB,CAAC;AAEF,KAAK,iCAAiC,GAAG,OAAO,CAC9C,uBAAuB,EACvB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAClB,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,EAAE,iCAAiC,CAAC,QAAQ,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uCAAuC;uBAI/B,iBAAiB,EAAE;aAC7B,OAAO,GAAG,CAAC,EAAE;MACpB,2BAqDH,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B;aAY9B,MAAM;oBACC,cAAc;eACnB,GAAG;cACJ,GAAG;eACF,GAAG;YACN,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;mBAC9B,MAAM;qBACJ,MAAM;YACf,iBAAiB,CAAC,OAAO,CAAC;MAChC,iBAoBH,CAAC"}
+{"version":3,"file":"decodePermission.d.mts","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,kCAAkC;AAI7D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,uBAAuB,EACxB,oBAAgB;AAEjB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oCAAoC;eAIpC,GAAG,EAAE;qBACC,cAAc,EAAE;MAC/B,cAAc,EAEjB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mCAAmC;eAInC,GAAG,EAAE;qBACC,cAAc,EAAE;MAC/B,cAaH,CAAC;AAEF,KAAK,iCAAiC,GAAG,OAAO,CAC9C,uBAAuB,EACvB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAClB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,EAAE,iCAAiC,CAAC,QAAQ,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,oCAAoC;oBAI/B,cAAc,EAAE;aACvB,OAAO,GAAG,CAAC,EAAE;MACpB,wBAqDH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,4BAA4B;aAY9B,MAAM;oBACC,cAAc;eACnB,GAAG;cACJ,GAAG;eACF,GAAG;YACN,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;mBAC9B,MAAM;qBACJ,MAAM;YACf,iBAAiB,CAAC,OAAO,CAAC;MAChC,iBAoBH,CAAC"}

package/dist/decodePermission/decodePermission.mjs

@@ -1,40 +1,70 @@
 import { ROOT_AUTHORITY } from "@metamask/delegation-core";
 import { numberToHex } from "@metamask/utils";
 /**
- * Returns every permission decoder whose caveat-address pattern matches the
- * given enforcer list for the chain. Used when more than one permission type
- * can share the same enforcer set; the caller must disambiguate by validating
- * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).
+ * Returns every permission rule whose caveat-address pattern matches the given
+ * enforcer list for the chain. Used when more than one permission type can
+ * share the same enforcer set; the caller must disambiguate by validating
+ * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).
  *
  * @param args - The arguments to this function.
  * @param args.enforcers - List of enforcer contract addresses (hex strings).
- * @param args.permissionDecoders - The permission decoders for the chain.
- * @returns All decoders that match, possibly empty.
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns All rules that match, possibly empty.
  */
-export const findDecodersWithMatchingCaveatAddresses = ({ enforcers, permissionDecoders, }) => {
-    return permissionDecoders.filter((decoder) => decoder.caveatAddressesMatch(enforcers));
+export const findRulesWithMatchingCaveatAddresses = ({ enforcers, permissionRules, }) => {
+    return permissionRules.filter((rule) => rule.caveatAddressesMatch(enforcers));
 };
 /**
- * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate
- * decoder. Use when several decoders share the same caveat addresses.
+ * Returns the unique permission rule that matches a given set of enforcer
+ * contract addresses (caveat types) for a specific chain.
+ *
+ * A rule matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the rule's required and
+ * optional enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one rule matches, it is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ * @param args.permissionRules - The permission rules for the chain.
+ * @returns The matching permission rule.
+ * @throws If no rule matches, or if more than one rule matches.
+ */
+export const findRuleWithMatchingCaveatAddresses = ({ enforcers, permissionRules, }) => {
+    const matchingRules = findRulesWithMatchingCaveatAddresses({
+        enforcers,
+        permissionRules,
+    });
+    if (matchingRules.length === 0) {
+        throw new Error('Unable to identify permission type');
+    }
+    if (matchingRules.length > 1) {
+        throw new Error('Multiple permission types match');
+    }
+    return matchingRules[0];
+};
+/**
+ * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate
+ * rule. Use when several rules share the same caveat addresses.
  *
  * @param args - The arguments to this function.
- * @param args.candidateDecoders - Decoders whose addresses already match the caveats.
+ * @param args.candidateRules - Rules whose addresses already match the caveats.
  * @param args.caveats - Caveats from the delegation.
- * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.
- * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.
+ * @returns The unique rule and decoded expiry/data when exactly one rule validates.
+ * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.
  */
-export const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, caveats, }) => {
-    if (candidateDecoders.length === 0) {
+export const selectUniqueRuleAndDecodedPermission = ({ candidateRules, caveats, }) => {
+    if (candidateRules.length === 0) {
         throw new Error('Unable to identify permission type');
     }
     const successfulDecodingResult = [];
     const failedAttempts = [];
-    for (const decoder of candidateDecoders) {
-        const decodeResult = decoder.validateAndDecodePermission(caveats);
+    for (const rule of candidateRules) {
+        const decodeResult = rule.validateAndDecodePermission(caveats);
         if (decodeResult.isValid) {
             successfulDecodingResult.push({
-                decoder,
+                rule,
                 rules: decodeResult.rules,
                 data: decodeResult.data,
                 expiry: decodeResult.expiry,
@@ -42,7 +72,7 @@ export const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, cav
         }
         else {
             failedAttempts.push({
-                permissionType: decoder.permissionType,
+                permissionType: rule.permissionType,
                 error: decodeResult.error,
             });
         }
@@ -52,7 +82,7 @@ export const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, cav
     }
     if (successfulDecodingResult.length > 1) {
         const types = successfulDecodingResult
-            .map((result) => result.decoder.permissionType)
+            .map((result) => result.rule.permissionType)
             .join(', ');
         throw new Error(`Multiple permission types validate the same delegation caveats: ${types}`);
     }
@@ -68,6 +98,13 @@ export const selectUniqueDecoderAndDecodedPermission = ({ candidateDecoders, cav
  * Reconstructs a {@link DecodedPermission} object from primitive values
  * obtained while decoding a permission context.
  *
+ * The resulting object contains:
+ * - `chainId` encoded as hex (`0x…`)
+ * - `address` set to the delegator (user account)
+ * - `signer` set to an account signer with the delegate address
+ * - `permission` with the identified type and decoded data
+ * - `expiry` timestamp (or null)
+ *
  * @param args - The arguments to this function.
  * @param args.chainId - Chain ID.
  * @param args.permissionType - Identified permission type.

package/dist/decodePermission/decodePermission.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"decodePermission.mjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  PermissionType,\n  PermissionDecoder,\n  ValidateAndDecodeResult,\n} from './types';\n\n/**\n * Returns every permission decoder whose caveat-address pattern matches the\n * given enforcer list for the chain. Used when more than one permission type\n * can share the same enforcer set; the caller must disambiguate by validating\n * caveat terms (see {@link selectUniqueDecoderAndDecodedPermission}).\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionDecoders - The permission decoders for the chain.\n * @returns All decoders that match, possibly empty.\n */\nexport const findDecodersWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionDecoders,\n}: {\n  enforcers: Hex[];\n  permissionDecoders: PermissionDecoder[];\n}): PermissionDecoder[] => {\n  return permissionDecoders.filter((decoder) =>\n    decoder.caveatAddressesMatch(enforcers),\n  );\n};\n\ntype SuccessfulValidateAndDecodeResult = Extract<\n  ValidateAndDecodeResult,\n  { isValid: true }\n>;\n\ntype DecoderAndDecodedPermission = {\n  decoder: PermissionDecoder;\n  rules: SuccessfulValidateAndDecodeResult['rules'];\n  data: SuccessfulValidateAndDecodeResult['data'];\n  expiry: SuccessfulValidateAndDecodeResult['expiry'];\n};\n\n/**\n * Runs {@link PermissionDecoder.validateAndDecodePermission} on each candidate\n * decoder. Use when several decoders share the same caveat addresses.\n *\n * @param args - The arguments to this function.\n * @param args.candidateDecoders - Decoders whose addresses already match the caveats.\n * @param args.caveats - Caveats from the delegation.\n * @returns The unique decoder and decoded expiry/data when exactly one decoder validates.\n * @throws If `candidateDecoders` is empty, if no decoder validates, or if more than one decoder validates.\n */\nexport const selectUniqueDecoderAndDecodedPermission = ({\n  candidateDecoders,\n  caveats,\n}: {\n  candidateDecoders: PermissionDecoder[];\n  caveats: Caveat<Hex>[];\n}): DecoderAndDecodedPermission => {\n  if (candidateDecoders.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  const successfulDecodingResult: DecoderAndDecodedPermission[] = [];\n\n  const failedAttempts: { permissionType: PermissionType; error: Error }[] = [];\n\n  for (const decoder of candidateDecoders) {\n    const decodeResult = decoder.validateAndDecodePermission(caveats);\n    if (decodeResult.isValid) {\n      successfulDecodingResult.push({\n        decoder,\n        rules: decodeResult.rules,\n        data: decodeResult.data,\n        expiry: decodeResult.expiry,\n      });\n    } else {\n      failedAttempts.push({\n        permissionType: decoder.permissionType,\n        error: decodeResult.error,\n      });\n    }\n  }\n\n  if (successfulDecodingResult.length === 1) {\n    return successfulDecodingResult[0];\n  }\n\n  if (successfulDecodingResult.length > 1) {\n    const types = successfulDecodingResult\n      .map((result) => result.decoder.permissionType)\n      .join(', ');\n    throw new Error(\n      `Multiple permission types validate the same delegation caveats: ${types}`,\n    );\n  }\n\n  if (failedAttempts.length === 1) {\n    throw failedAttempts[0].error;\n  }\n\n  const details = failedAttempts\n    .map(\n      (attempt) =>\n        `${String(attempt.permissionType)}: ${attempt.error.message}`,\n    )\n    .join('; ');\n\n  throw new Error(\n    `No permission type could validate the delegation caveats. Attempts: ${details}`,\n  );\n};\n\n/**\n * Reconstructs a {@link DecodedPermission} object from primitive values\n * obtained while decoding a permission context.\n *\n * @param args - The arguments to this function.\n * @param args.chainId - Chain ID.\n * @param args.permissionType - Identified permission type.\n * @param args.delegator - Address of the account delegating permission.\n * @param args.delegate - Address that will act under the granted permission.\n * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.\n * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.\n * @param args.data - Permission-specific decoded data payload.\n * @param args.justification - Human-readable justification for the permission.\n * @param args.specifiedOrigin - The origin reported in the request metadata.\n * @param args.rules - Rules recovered from caveats (e.g. redeemer allowlist).\n *\n * @returns The reconstructed {@link DecodedPermission}.\n */\nexport const reconstructDecodedPermission = ({\n  chainId,\n  permissionType,\n  delegator,\n  delegate,\n  authority,\n  expiry,\n  data,\n  justification,\n  specifiedOrigin,\n  rules,\n}: {\n  chainId: number;\n  permissionType: PermissionType;\n  delegator: Hex;\n  delegate: Hex;\n  authority: Hex;\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n  justification: string;\n  specifiedOrigin: string;\n  rules?: DecodedPermission['rules'];\n}): DecodedPermission => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    from: delegator,\n    to: delegate,\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n    ...(rules === undefined ? {} : { rules }),\n  };\n\n  return permission;\n};\n"]}
+{"version":3,"file":"decodePermission.mjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  PermissionType,\n  PermissionRule,\n  ValidateAndDecodeResult,\n} from './types';\n\n/**\n * Returns every permission rule whose caveat-address pattern matches the given\n * enforcer list for the chain. Used when more than one permission type can\n * share the same enforcer set; the caller must disambiguate by validating\n * caveat terms (see {@link selectUniqueRuleAndDecodedPermission}).\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionRules - The permission rules for the chain.\n * @returns All rules that match, possibly empty.\n */\nexport const findRulesWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionRules,\n}: {\n  enforcers: Hex[];\n  permissionRules: PermissionRule[];\n}): PermissionRule[] => {\n  return permissionRules.filter((rule) => rule.caveatAddressesMatch(enforcers));\n};\n\n/**\n * Returns the unique permission rule that matches a given set of enforcer\n * contract addresses (caveat types) for a specific chain.\n *\n * A rule matches when:\n * - All of its required enforcers are present in the provided list; and\n * - No provided enforcer falls outside the union of the rule's required and\n * optional enforcers (currently only `TimestampEnforcer` is allowed extra).\n *\n * If exactly one rule matches, it is returned.\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n * @param args.permissionRules - The permission rules for the chain.\n * @returns The matching permission rule.\n * @throws If no rule matches, or if more than one rule matches.\n */\nexport const findRuleWithMatchingCaveatAddresses = ({\n  enforcers,\n  permissionRules,\n}: {\n  enforcers: Hex[];\n  permissionRules: PermissionRule[];\n}): PermissionRule => {\n  const matchingRules = findRulesWithMatchingCaveatAddresses({\n    enforcers,\n    permissionRules,\n  });\n\n  if (matchingRules.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n  if (matchingRules.length > 1) {\n    throw new Error('Multiple permission types match');\n  }\n  return matchingRules[0];\n};\n\ntype SuccessfulValidateAndDecodeResult = Extract<\n  ValidateAndDecodeResult,\n  { isValid: true }\n>;\n\ntype RuleAndDecodedPermission = {\n  rule: PermissionRule;\n  rules: SuccessfulValidateAndDecodeResult['rules'];\n  data: SuccessfulValidateAndDecodeResult['data'];\n  expiry: SuccessfulValidateAndDecodeResult['expiry'];\n};\n\n/**\n * Runs {@link PermissionRule.validateAndDecodePermission} on each candidate\n * rule. Use when several rules share the same caveat addresses.\n *\n * @param args - The arguments to this function.\n * @param args.candidateRules - Rules whose addresses already match the caveats.\n * @param args.caveats - Caveats from the delegation.\n * @returns The unique rule and decoded expiry/data when exactly one rule validates.\n * @throws If `candidateRules` is empty, if no rule validates, or if more than one rule validates.\n */\nexport const selectUniqueRuleAndDecodedPermission = ({\n  candidateRules,\n  caveats,\n}: {\n  candidateRules: PermissionRule[];\n  caveats: Caveat<Hex>[];\n}): RuleAndDecodedPermission => {\n  if (candidateRules.length === 0) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  const successfulDecodingResult: RuleAndDecodedPermission[] = [];\n\n  const failedAttempts: { permissionType: PermissionType; error: Error }[] = [];\n\n  for (const rule of candidateRules) {\n    const decodeResult = rule.validateAndDecodePermission(caveats);\n    if (decodeResult.isValid) {\n      successfulDecodingResult.push({\n        rule,\n        rules: decodeResult.rules,\n        data: decodeResult.data,\n        expiry: decodeResult.expiry,\n      });\n    } else {\n      failedAttempts.push({\n        permissionType: rule.permissionType,\n        error: decodeResult.error,\n      });\n    }\n  }\n\n  if (successfulDecodingResult.length === 1) {\n    return successfulDecodingResult[0];\n  }\n\n  if (successfulDecodingResult.length > 1) {\n    const types = successfulDecodingResult\n      .map((result) => result.rule.permissionType)\n      .join(', ');\n    throw new Error(\n      `Multiple permission types validate the same delegation caveats: ${types}`,\n    );\n  }\n\n  if (failedAttempts.length === 1) {\n    throw failedAttempts[0].error;\n  }\n\n  const details = failedAttempts\n    .map(\n      (attempt) =>\n        `${String(attempt.permissionType)}: ${attempt.error.message}`,\n    )\n    .join('; ');\n\n  throw new Error(\n    `No permission type could validate the delegation caveats. Attempts: ${details}`,\n  );\n};\n\n/**\n * Reconstructs a {@link DecodedPermission} object from primitive values\n * obtained while decoding a permission context.\n *\n * The resulting object contains:\n * - `chainId` encoded as hex (`0x…`)\n * - `address` set to the delegator (user account)\n * - `signer` set to an account signer with the delegate address\n * - `permission` with the identified type and decoded data\n * - `expiry` timestamp (or null)\n *\n * @param args - The arguments to this function.\n * @param args.chainId - Chain ID.\n * @param args.permissionType - Identified permission type.\n * @param args.delegator - Address of the account delegating permission.\n * @param args.delegate - Address that will act under the granted permission.\n * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.\n * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.\n * @param args.data - Permission-specific decoded data payload.\n * @param args.justification - Human-readable justification for the permission.\n * @param args.specifiedOrigin - The origin reported in the request metadata.\n * @param args.rules - Rules recovered from caveats (e.g. redeemer allowlist).\n *\n * @returns The reconstructed {@link DecodedPermission}.\n */\nexport const reconstructDecodedPermission = ({\n  chainId,\n  permissionType,\n  delegator,\n  delegate,\n  authority,\n  expiry,\n  data,\n  justification,\n  specifiedOrigin,\n  rules,\n}: {\n  chainId: number;\n  permissionType: PermissionType;\n  delegator: Hex;\n  delegate: Hex;\n  authority: Hex;\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n  justification: string;\n  specifiedOrigin: string;\n  rules?: DecodedPermission['rules'];\n}): DecodedPermission => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    from: delegator,\n    to: delegate,\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n    ...(rules === undefined ? {} : { rules }),\n  };\n\n  return permission;\n};\n"]}