@metamask-previews/gator-permissions-controller 0.1.0-preview-0c2c1149 → 0.1.0-preview-463efec

package/dist/decodePermission/decodePermission.cjs

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconstructDecodedPermission = exports.getPermissionDataAndExpiry = exports.identifyPermissionByEnforcers = void 0;
+const delegation_core_1 = require("@metamask/delegation-core");
+const utils_1 = require("@metamask/utils");
+const utils_2 = require("./utils.cjs");
+/**
+ * Identifies the unique permission type that matches a given set of enforcer
+ * contract addresses for a specific chain.
+ *
+ * A permission type matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the type's required and
+ * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one permission type matches, its identifier is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ *
+ * @param args.contracts - The deployed contracts for the chain.
+ * @returns The identifier of the matching permission type.
+ * @throws If no permission type matches, or if more than one permission type matches.
+ */
+const identifyPermissionByEnforcers = ({ enforcers, contracts, }) => {
+    const enforcersSet = new Set(enforcers.map(utils_1.getChecksumAddress));
+    const permissionRules = (0, utils_2.createPermissionRulesForChainId)(contracts);
+    let matchingPermissionType = null;
+    for (const { allowedEnforcers, requiredEnforcers, permissionType, } of permissionRules) {
+        const hasAllRequiredEnforcers = (0, utils_2.isSubset)(requiredEnforcers, enforcersSet);
+        let hasForbiddenEnforcers = false;
+        for (const caveat of enforcersSet) {
+            if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {
+                hasForbiddenEnforcers = true;
+                break;
+            }
+        }
+        if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {
+            if (matchingPermissionType) {
+                throw new Error('Multiple permission types match');
+            }
+            matchingPermissionType = permissionType;
+        }
+    }
+    if (!matchingPermissionType) {
+        throw new Error('Unable to identify permission type');
+    }
+    return matchingPermissionType;
+};
+exports.identifyPermissionByEnforcers = identifyPermissionByEnforcers;
+/**
+ * Extracts the permission-specific data payload and the expiry timestamp from
+ * the provided caveats for a given permission type.
+ *
+ * This function locates the relevant caveat enforcer for the `permissionType`,
+ * interprets its `terms` by splitting the hex string into byte-sized segments,
+ * and converts each segment into the appropriate numeric or address shape.
+ *
+ * The expiry timestamp is derived from the `TimestampEnforcer` terms and must
+ * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.
+ *
+ * @param args - The arguments to this function.
+ * @param args.contracts - The deployed contracts for the chain.
+ * @param args.caveats - Caveats decoded from the permission context.
+ * @param args.permissionType - The previously identified permission type.
+ *
+ * @returns An object containing the `expiry` timestamp and the decoded `data` payload.
+ * @throws If the caveats are malformed, missing, or the terms fail to decode.
+ */
+const getPermissionDataAndExpiry = ({ contracts, caveats, permissionType, }) => {
+    const checksumCaveats = caveats.map((caveat) => ({
+        ...caveat,
+        enforcer: (0, utils_1.getChecksumAddress)(caveat.enforcer),
+    }));
+    const { erc20StreamingEnforcer, erc20PeriodicEnforcer, nativeTokenStreamingEnforcer, nativeTokenPeriodicEnforcer, timestampEnforcer, } = (0, utils_2.getChecksumEnforcersByChainId)(contracts);
+    const expiryTerms = (0, utils_2.getTermsByEnforcer)({
+        caveats: checksumCaveats,
+        enforcer: timestampEnforcer,
+        throwIfNotFound: false,
+    });
+    let expiry = null;
+    if (expiryTerms) {
+        const [after, before] = (0, utils_2.splitHex)(expiryTerms, [16, 16]);
+        if ((0, utils_1.hexToNumber)(after) !== 0) {
+            throw new Error('Invalid expiry');
+        }
+        expiry = (0, utils_1.hexToNumber)(before);
+    }
+    let data;
+    switch (permissionType) {
+        case 'erc20-token-stream': {
+            const erc20StreamingTerms = (0, utils_2.getTermsByEnforcer)({
+                caveats: checksumCaveats,
+                enforcer: erc20StreamingEnforcer,
+            });
+            const [tokenAddress, initialAmount, maxAmount, amountPerSecond, startTimeRaw,] = (0, utils_2.splitHex)(erc20StreamingTerms, [20, 32, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: (0, utils_1.hexToNumber)(startTimeRaw),
+            };
+            break;
+        }
+        case 'erc20-token-periodic': {
+            const erc20PeriodicTerms = (0, utils_2.getTermsByEnforcer)({
+                caveats: checksumCaveats,
+                enforcer: erc20PeriodicEnforcer,
+            });
+            const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] = (0, utils_2.splitHex)(erc20PeriodicTerms, [20, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                periodAmount,
+                periodDuration: (0, utils_1.hexToNumber)(periodDurationRaw),
+                startTime: (0, utils_1.hexToNumber)(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-stream': {
+            const nativeTokenStreamingTerms = (0, utils_2.getTermsByEnforcer)({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenStreamingEnforcer,
+            });
+            const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] = (0, utils_2.splitHex)(nativeTokenStreamingTerms, [32, 32, 32, 32]);
+            data = {
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: (0, utils_1.hexToNumber)(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-periodic': {
+            const nativeTokenPeriodicTerms = (0, utils_2.getTermsByEnforcer)({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenPeriodicEnforcer,
+            });
+            const [periodAmount, periodDurationRaw, startTimeRaw] = (0, utils_2.splitHex)(nativeTokenPeriodicTerms, [32, 32, 32]);
+            data = {
+                periodAmount,
+                periodDuration: (0, utils_1.hexToNumber)(periodDurationRaw),
+                startTime: (0, utils_1.hexToNumber)(startTimeRaw),
+            };
+            break;
+        }
+        default:
+            throw new Error('Invalid permission type');
+    }
+    return { expiry, data };
+};
+exports.getPermissionDataAndExpiry = getPermissionDataAndExpiry;
+/**
+ * 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.
+ * @param args.delegator - Address of the account delegating permission.
+ * @param args.delegate - Address that will act under the granted permission.
+ * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.
+ * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.
+ * @param args.data - Permission-specific decoded data payload.
+ * @param args.justification - Human-readable justification for the permission.
+ * @param args.specifiedOrigin - The origin reported in the request metadata.
+ *
+ * @returns The reconstructed {@link DecodedPermission}.
+ */
+const reconstructDecodedPermission = ({ chainId, permissionType, delegator, delegate, authority, expiry, data, justification, specifiedOrigin, }) => {
+    if (authority !== delegation_core_1.ROOT_AUTHORITY) {
+        throw new Error('Invalid authority');
+    }
+    const permission = {
+        chainId: (0, utils_1.numberToHex)(chainId),
+        address: delegator,
+        signer: { type: 'account', data: { address: delegate } },
+        permission: {
+            type: permissionType,
+            data,
+            justification,
+        },
+        expiry,
+        origin: specifiedOrigin,
+    };
+    return permission;
+};
+exports.reconstructDecodedPermission = reconstructDecodedPermission;
+//# sourceMappingURL=decodePermission.cjs.map

package/dist/decodePermission/decodePermission.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decodePermission.cjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":";;;AACA,+DAA2D;AAC3D,2CAA+E;AAO/E,uCAMiB;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACI,MAAM,6BAA6B,GAAG,CAAC,EAC5C,SAAS,EACT,SAAS,GAIV,EAAkB,EAAE;IACnB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,0BAAkB,CAAC,CAAC,CAAC;IAEhE,MAAM,eAAe,GAAG,IAAA,uCAA+B,EAAC,SAAS,CAAC,CAAC;IAEnE,IAAI,sBAAsB,GAA0B,IAAI,CAAC;IAEzD,KAAK,MAAM,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,GACf,IAAI,eAAe,EAAE;QACpB,MAAM,uBAAuB,GAAG,IAAA,gBAAQ,EAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;QAE1E,IAAI,qBAAqB,GAAG,KAAK,CAAC;QAElC,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE;YACjC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;gBACnE,qBAAqB,GAAG,IAAI,CAAC;gBAC7B,MAAM;aACP;SACF;QAED,IAAI,uBAAuB,IAAI,CAAC,qBAAqB,EAAE;YACrD,IAAI,sBAAsB,EAAE;gBAC1B,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;aACpD;YACD,sBAAsB,GAAG,cAAc,CAAC;SACzC;KACF;IAED,IAAI,CAAC,sBAAsB,EAAE;QAC3B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;KACvD;IAED,OAAO,sBAAsB,CAAC;AAChC,CAAC,CAAC;AA1CW,QAAA,6BAA6B,iCA0CxC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACI,MAAM,0BAA0B,GAAG,CAAC,EACzC,SAAS,EACT,OAAO,EACP,cAAc,GAKf,EAGC,EAAE;IACF,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC/C,GAAG,MAAM;QACT,QAAQ,EAAE,IAAA,0BAAkB,EAAC,MAAM,CAAC,QAAQ,CAAC;KAC9C,CAAC,CAAC,CAAC;IAEJ,MAAM,EACJ,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,GAClB,GAAG,IAAA,qCAA6B,EAAC,SAAS,CAAC,CAAC;IAE7C,MAAM,WAAW,GAAG,IAAA,0BAAkB,EAAC;QACrC,OAAO,EAAE,eAAe;QACxB,QAAQ,EAAE,iBAAiB;QAC3B,eAAe,EAAE,KAAK;KACvB,CAAC,CAAC;IAEH,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,WAAW,EAAE;QACf,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAA,gBAAQ,EAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAExD,IAAI,IAAA,mBAAW,EAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YAC5B,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;SACnC;QACD,MAAM,GAAG,IAAA,mBAAW,EAAC,MAAM,CAAC,CAAC;KAC9B;IAED,IAAI,IAA6C,CAAC;IAElD,QAAQ,cAAc,EAAE;QACtB,KAAK,oBAAoB,CAAC,CAAC;YACzB,MAAM,mBAAmB,GAAG,IAAA,0BAAkB,EAAC;gBAC7C,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,sBAAsB;aACjC,CAAC,CAAC;YAEH,MAAM,CACJ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,eAAe,EACf,YAAY,EACb,GAAG,IAAA,gBAAQ,EAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,IAAI,GAAG;gBACL,YAAY;gBACZ,aAAa;gBACb,SAAS;gBACT,eAAe;gBACf,SAAS,EAAE,IAAA,mBAAW,EAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD,KAAK,sBAAsB,CAAC,CAAC;YAC3B,MAAM,kBAAkB,GAAG,IAAA,0BAAkB,EAAC;gBAC5C,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,qBAAqB;aAChC,CAAC,CAAC;YAEH,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,CAAC,GACjE,IAAA,gBAAQ,EAAC,kBAAkB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAEjD,IAAI,GAAG;gBACL,YAAY;gBACZ,YAAY;gBACZ,cAAc,EAAE,IAAA,mBAAW,EAAC,iBAAiB,CAAC;gBAC9C,SAAS,EAAE,IAAA,mBAAW,EAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QAED,KAAK,qBAAqB,CAAC,CAAC;YAC1B,MAAM,yBAAyB,GAAG,IAAA,0BAAkB,EAAC;gBACnD,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,4BAA4B;aACvC,CAAC,CAAC;YAEH,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,CAAC,GAC7D,IAAA,gBAAQ,EAAC,yBAAyB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,IAAI,GAAG;gBACL,aAAa;gBACb,SAAS;gBACT,eAAe;gBACf,SAAS,EAAE,IAAA,mBAAW,EAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD,KAAK,uBAAuB,CAAC,CAAC;YAC5B,MAAM,wBAAwB,GAAG,IAAA,0BAAkB,EAAC;gBAClD,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,2BAA2B;aACtC,CAAC,CAAC;YAEH,MAAM,CAAC,YAAY,EAAE,iBAAiB,EAAE,YAAY,CAAC,GAAG,IAAA,gBAAQ,EAC9D,wBAAwB,EACxB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CACb,CAAC;YAEF,IAAI,GAAG;gBACL,YAAY;gBACZ,cAAc,EAAE,IAAA,mBAAW,EAAC,iBAAiB,CAAC;gBAC9C,SAAS,EAAE,IAAA,mBAAW,EAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;KAC9C;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC,CAAC;AA7HW,QAAA,0BAA0B,8BA6HrC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,MAAM,4BAA4B,GAAG,CAAC,EAC3C,OAAO,EACP,cAAc,EACd,SAAS,EACT,QAAQ,EACR,SAAS,EACT,MAAM,EACN,IAAI,EACJ,aAAa,EACb,eAAe,GAWhB,EAAE,EAAE;IACH,IAAI,SAAS,KAAK,gCAAc,EAAE;QAChC,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;KACtC;IAED,MAAM,UAAU,GAAsB;QACpC,OAAO,EAAE,IAAA,mBAAW,EAAC,OAAO,CAAC;QAC7B,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;QACxD,UAAU,EAAE;YACV,IAAI,EAAE,cAAc;YACpB,IAAI;YACJ,aAAa;SACd;QACD,MAAM;QACN,MAAM,EAAE,eAAe;KACxB,CAAC;IAEF,OAAO,UAAU,CAAC;AACpB,CAAC,CAAC;AAvCW,QAAA,4BAA4B,gCAuCvC","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { getChecksumAddress, hexToNumber, numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  DeployedContractsByName,\n  PermissionType,\n} from './types';\nimport {\n  createPermissionRulesForChainId,\n  getChecksumEnforcersByChainId,\n  getTermsByEnforcer,\n  isSubset,\n  splitHex,\n} from './utils';\n\n/**\n * Identifies the unique permission type that matches a given set of enforcer\n * contract addresses for a specific chain.\n *\n * A permission type 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 type's required and\n * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).\n *\n * If exactly one permission type matches, its identifier is returned.\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n *\n * @param args.contracts - The deployed contracts for the chain.\n * @returns The identifier of the matching permission type.\n * @throws If no permission type matches, or if more than one permission type matches.\n */\nexport const identifyPermissionByEnforcers = ({\n  enforcers,\n  contracts,\n}: {\n  enforcers: Hex[];\n  contracts: DeployedContractsByName;\n}): PermissionType => {\n  const enforcersSet = new Set(enforcers.map(getChecksumAddress));\n\n  const permissionRules = createPermissionRulesForChainId(contracts);\n\n  let matchingPermissionType: PermissionType | null = null;\n\n  for (const {\n    allowedEnforcers,\n    requiredEnforcers,\n    permissionType,\n  } of permissionRules) {\n    const hasAllRequiredEnforcers = isSubset(requiredEnforcers, enforcersSet);\n\n    let hasForbiddenEnforcers = false;\n\n    for (const caveat of enforcersSet) {\n      if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {\n        hasForbiddenEnforcers = true;\n        break;\n      }\n    }\n\n    if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {\n      if (matchingPermissionType) {\n        throw new Error('Multiple permission types match');\n      }\n      matchingPermissionType = permissionType;\n    }\n  }\n\n  if (!matchingPermissionType) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  return matchingPermissionType;\n};\n\n/**\n * Extracts the permission-specific data payload and the expiry timestamp from\n * the provided caveats for a given permission type.\n *\n * This function locates the relevant caveat enforcer for the `permissionType`,\n * interprets its `terms` by splitting the hex string into byte-sized segments,\n * and converts each segment into the appropriate numeric or address shape.\n *\n * The expiry timestamp is derived from the `TimestampEnforcer` terms and must\n * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.\n *\n * @param args - The arguments to this function.\n * @param args.contracts - The deployed contracts for the chain.\n * @param args.caveats - Caveats decoded from the permission context.\n * @param args.permissionType - The previously identified permission type.\n *\n * @returns An object containing the `expiry` timestamp and the decoded `data` payload.\n * @throws If the caveats are malformed, missing, or the terms fail to decode.\n */\nexport const getPermissionDataAndExpiry = ({\n  contracts,\n  caveats,\n  permissionType,\n}: {\n  contracts: DeployedContractsByName;\n  caveats: Caveat<Hex>[];\n  permissionType: PermissionType;\n}): {\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n} => {\n  const checksumCaveats = caveats.map((caveat) => ({\n    ...caveat,\n    enforcer: getChecksumAddress(caveat.enforcer),\n  }));\n\n  const {\n    erc20StreamingEnforcer,\n    erc20PeriodicEnforcer,\n    nativeTokenStreamingEnforcer,\n    nativeTokenPeriodicEnforcer,\n    timestampEnforcer,\n  } = getChecksumEnforcersByChainId(contracts);\n\n  const expiryTerms = getTermsByEnforcer({\n    caveats: checksumCaveats,\n    enforcer: timestampEnforcer,\n    throwIfNotFound: false,\n  });\n\n  let expiry: number | null = null;\n  if (expiryTerms) {\n    const [after, before] = splitHex(expiryTerms, [16, 16]);\n\n    if (hexToNumber(after) !== 0) {\n      throw new Error('Invalid expiry');\n    }\n    expiry = hexToNumber(before);\n  }\n\n  let data: DecodedPermission['permission']['data'];\n\n  switch (permissionType) {\n    case 'erc20-token-stream': {\n      const erc20StreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20StreamingEnforcer,\n      });\n\n      const [\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTimeRaw,\n      ] = splitHex(erc20StreamingTerms, [20, 32, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'erc20-token-periodic': {\n      const erc20PeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20PeriodicEnforcer,\n      });\n\n      const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] =\n        splitHex(erc20PeriodicTerms, [20, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n\n    case 'native-token-stream': {\n      const nativeTokenStreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenStreamingEnforcer,\n      });\n\n      const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] =\n        splitHex(nativeTokenStreamingTerms, [32, 32, 32, 32]);\n\n      data = {\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'native-token-periodic': {\n      const nativeTokenPeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenPeriodicEnforcer,\n      });\n\n      const [periodAmount, periodDurationRaw, startTimeRaw] = splitHex(\n        nativeTokenPeriodicTerms,\n        [32, 32, 32],\n      );\n\n      data = {\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    default:\n      throw new Error('Invalid permission type');\n  }\n\n  return { expiry, data };\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 *\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}: {\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}) => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    address: delegator,\n    signer: { type: 'account', data: { address: delegate } },\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n  };\n\n  return permission;\n};\n"]}

package/dist/decodePermission/decodePermission.d.cts

@@ -0,0 +1,87 @@
+import type { Caveat, Hex } from "@metamask/delegation-core";
+import type { DecodedPermission, DeployedContractsByName, PermissionType } from "./types.cjs";
+/**
+ * Identifies the unique permission type that matches a given set of enforcer
+ * contract addresses for a specific chain.
+ *
+ * A permission type matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the type's required and
+ * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one permission type matches, its identifier is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ *
+ * @param args.contracts - The deployed contracts for the chain.
+ * @returns The identifier of the matching permission type.
+ * @throws If no permission type matches, or if more than one permission type matches.
+ */
+export declare const identifyPermissionByEnforcers: ({ enforcers, contracts, }: {
+    enforcers: Hex[];
+    contracts: DeployedContractsByName;
+}) => PermissionType;
+/**
+ * Extracts the permission-specific data payload and the expiry timestamp from
+ * the provided caveats for a given permission type.
+ *
+ * This function locates the relevant caveat enforcer for the `permissionType`,
+ * interprets its `terms` by splitting the hex string into byte-sized segments,
+ * and converts each segment into the appropriate numeric or address shape.
+ *
+ * The expiry timestamp is derived from the `TimestampEnforcer` terms and must
+ * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.
+ *
+ * @param args - The arguments to this function.
+ * @param args.contracts - The deployed contracts for the chain.
+ * @param args.caveats - Caveats decoded from the permission context.
+ * @param args.permissionType - The previously identified permission type.
+ *
+ * @returns An object containing the `expiry` timestamp and the decoded `data` payload.
+ * @throws If the caveats are malformed, missing, or the terms fail to decode.
+ */
+export declare const getPermissionDataAndExpiry: ({ contracts, caveats, permissionType, }: {
+    contracts: DeployedContractsByName;
+    caveats: Caveat<Hex>[];
+    permissionType: PermissionType;
+}) => {
+    expiry: number | null;
+    data: DecodedPermission['permission']['data'];
+};
+/**
+ * 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.
+ * @param args.delegator - Address of the account delegating permission.
+ * @param args.delegate - Address that will act under the granted permission.
+ * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.
+ * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.
+ * @param args.data - Permission-specific decoded data payload.
+ * @param args.justification - Human-readable justification for the permission.
+ * @param args.specifiedOrigin - The origin reported in the request metadata.
+ *
+ * @returns The reconstructed {@link DecodedPermission}.
+ */
+export declare const reconstructDecodedPermission: ({ chainId, permissionType, delegator, delegate, authority, expiry, data, justification, specifiedOrigin, }: {
+    chainId: number;
+    permissionType: PermissionType;
+    delegator: Hex;
+    delegate: Hex;
+    authority: Hex;
+    expiry: number | null;
+    data: DecodedPermission['permission']['data'];
+    justification: string;
+    specifiedOrigin: string;
+}) => DecodedPermission;
+//# sourceMappingURL=decodePermission.d.cts.map

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

@@ -0,0 +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,uBAAuB,EACvB,cAAc,EACf,oBAAgB;AASjB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,6BAA6B;eAI7B,GAAG,EAAE;eACL,uBAAuB;MAChC,cAoCH,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B;eAK1B,uBAAuB;aACzB,OAAO,GAAG,CAAC,EAAE;oBACN,cAAc;;YAEtB,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;CAmH9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B;aAW9B,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;uBAoBxB,CAAC"}

package/dist/decodePermission/decodePermission.d.mts

@@ -0,0 +1,87 @@
+import type { Caveat, Hex } from "@metamask/delegation-core";
+import type { DecodedPermission, DeployedContractsByName, PermissionType } from "./types.mjs";
+/**
+ * Identifies the unique permission type that matches a given set of enforcer
+ * contract addresses for a specific chain.
+ *
+ * A permission type matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the type's required and
+ * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one permission type matches, its identifier is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ *
+ * @param args.contracts - The deployed contracts for the chain.
+ * @returns The identifier of the matching permission type.
+ * @throws If no permission type matches, or if more than one permission type matches.
+ */
+export declare const identifyPermissionByEnforcers: ({ enforcers, contracts, }: {
+    enforcers: Hex[];
+    contracts: DeployedContractsByName;
+}) => PermissionType;
+/**
+ * Extracts the permission-specific data payload and the expiry timestamp from
+ * the provided caveats for a given permission type.
+ *
+ * This function locates the relevant caveat enforcer for the `permissionType`,
+ * interprets its `terms` by splitting the hex string into byte-sized segments,
+ * and converts each segment into the appropriate numeric or address shape.
+ *
+ * The expiry timestamp is derived from the `TimestampEnforcer` terms and must
+ * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.
+ *
+ * @param args - The arguments to this function.
+ * @param args.contracts - The deployed contracts for the chain.
+ * @param args.caveats - Caveats decoded from the permission context.
+ * @param args.permissionType - The previously identified permission type.
+ *
+ * @returns An object containing the `expiry` timestamp and the decoded `data` payload.
+ * @throws If the caveats are malformed, missing, or the terms fail to decode.
+ */
+export declare const getPermissionDataAndExpiry: ({ contracts, caveats, permissionType, }: {
+    contracts: DeployedContractsByName;
+    caveats: Caveat<Hex>[];
+    permissionType: PermissionType;
+}) => {
+    expiry: number | null;
+    data: DecodedPermission['permission']['data'];
+};
+/**
+ * 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.
+ * @param args.delegator - Address of the account delegating permission.
+ * @param args.delegate - Address that will act under the granted permission.
+ * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.
+ * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.
+ * @param args.data - Permission-specific decoded data payload.
+ * @param args.justification - Human-readable justification for the permission.
+ * @param args.specifiedOrigin - The origin reported in the request metadata.
+ *
+ * @returns The reconstructed {@link DecodedPermission}.
+ */
+export declare const reconstructDecodedPermission: ({ chainId, permissionType, delegator, delegate, authority, expiry, data, justification, specifiedOrigin, }: {
+    chainId: number;
+    permissionType: PermissionType;
+    delegator: Hex;
+    delegate: Hex;
+    authority: Hex;
+    expiry: number | null;
+    data: DecodedPermission['permission']['data'];
+    justification: string;
+    specifiedOrigin: string;
+}) => DecodedPermission;
+//# sourceMappingURL=decodePermission.d.mts.map

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

@@ -0,0 +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,uBAAuB,EACvB,cAAc,EACf,oBAAgB;AASjB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,6BAA6B;eAI7B,GAAG,EAAE;eACL,uBAAuB;MAChC,cAoCH,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B;eAK1B,uBAAuB;aACzB,OAAO,GAAG,CAAC,EAAE;oBACN,cAAc;;YAEtB,MAAM,GAAG,IAAI;UACf,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;CAmH9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B;aAW9B,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;uBAoBxB,CAAC"}

package/dist/decodePermission/decodePermission.mjs

@@ -0,0 +1,190 @@
+import { ROOT_AUTHORITY } from "@metamask/delegation-core";
+import { getChecksumAddress, hexToNumber, numberToHex } from "@metamask/utils";
+import { createPermissionRulesForChainId, getChecksumEnforcersByChainId, getTermsByEnforcer, isSubset, splitHex } from "./utils.mjs";
+/**
+ * Identifies the unique permission type that matches a given set of enforcer
+ * contract addresses for a specific chain.
+ *
+ * A permission type matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the type's required and
+ * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one permission type matches, its identifier is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ *
+ * @param args.contracts - The deployed contracts for the chain.
+ * @returns The identifier of the matching permission type.
+ * @throws If no permission type matches, or if more than one permission type matches.
+ */
+export const identifyPermissionByEnforcers = ({ enforcers, contracts, }) => {
+    const enforcersSet = new Set(enforcers.map(getChecksumAddress));
+    const permissionRules = createPermissionRulesForChainId(contracts);
+    let matchingPermissionType = null;
+    for (const { allowedEnforcers, requiredEnforcers, permissionType, } of permissionRules) {
+        const hasAllRequiredEnforcers = isSubset(requiredEnforcers, enforcersSet);
+        let hasForbiddenEnforcers = false;
+        for (const caveat of enforcersSet) {
+            if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {
+                hasForbiddenEnforcers = true;
+                break;
+            }
+        }
+        if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {
+            if (matchingPermissionType) {
+                throw new Error('Multiple permission types match');
+            }
+            matchingPermissionType = permissionType;
+        }
+    }
+    if (!matchingPermissionType) {
+        throw new Error('Unable to identify permission type');
+    }
+    return matchingPermissionType;
+};
+/**
+ * Extracts the permission-specific data payload and the expiry timestamp from
+ * the provided caveats for a given permission type.
+ *
+ * This function locates the relevant caveat enforcer for the `permissionType`,
+ * interprets its `terms` by splitting the hex string into byte-sized segments,
+ * and converts each segment into the appropriate numeric or address shape.
+ *
+ * The expiry timestamp is derived from the `TimestampEnforcer` terms and must
+ * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.
+ *
+ * @param args - The arguments to this function.
+ * @param args.contracts - The deployed contracts for the chain.
+ * @param args.caveats - Caveats decoded from the permission context.
+ * @param args.permissionType - The previously identified permission type.
+ *
+ * @returns An object containing the `expiry` timestamp and the decoded `data` payload.
+ * @throws If the caveats are malformed, missing, or the terms fail to decode.
+ */
+export const getPermissionDataAndExpiry = ({ contracts, caveats, permissionType, }) => {
+    const checksumCaveats = caveats.map((caveat) => ({
+        ...caveat,
+        enforcer: getChecksumAddress(caveat.enforcer),
+    }));
+    const { erc20StreamingEnforcer, erc20PeriodicEnforcer, nativeTokenStreamingEnforcer, nativeTokenPeriodicEnforcer, timestampEnforcer, } = getChecksumEnforcersByChainId(contracts);
+    const expiryTerms = getTermsByEnforcer({
+        caveats: checksumCaveats,
+        enforcer: timestampEnforcer,
+        throwIfNotFound: false,
+    });
+    let expiry = null;
+    if (expiryTerms) {
+        const [after, before] = splitHex(expiryTerms, [16, 16]);
+        if (hexToNumber(after) !== 0) {
+            throw new Error('Invalid expiry');
+        }
+        expiry = hexToNumber(before);
+    }
+    let data;
+    switch (permissionType) {
+        case 'erc20-token-stream': {
+            const erc20StreamingTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: erc20StreamingEnforcer,
+            });
+            const [tokenAddress, initialAmount, maxAmount, amountPerSecond, startTimeRaw,] = splitHex(erc20StreamingTerms, [20, 32, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'erc20-token-periodic': {
+            const erc20PeriodicTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: erc20PeriodicEnforcer,
+            });
+            const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] = splitHex(erc20PeriodicTerms, [20, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                periodAmount,
+                periodDuration: hexToNumber(periodDurationRaw),
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-stream': {
+            const nativeTokenStreamingTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenStreamingEnforcer,
+            });
+            const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] = splitHex(nativeTokenStreamingTerms, [32, 32, 32, 32]);
+            data = {
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-periodic': {
+            const nativeTokenPeriodicTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenPeriodicEnforcer,
+            });
+            const [periodAmount, periodDurationRaw, startTimeRaw] = splitHex(nativeTokenPeriodicTerms, [32, 32, 32]);
+            data = {
+                periodAmount,
+                periodDuration: hexToNumber(periodDurationRaw),
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        default:
+            throw new Error('Invalid permission type');
+    }
+    return { expiry, data };
+};
+/**
+ * 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.
+ * @param args.delegator - Address of the account delegating permission.
+ * @param args.delegate - Address that will act under the granted permission.
+ * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.
+ * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.
+ * @param args.data - Permission-specific decoded data payload.
+ * @param args.justification - Human-readable justification for the permission.
+ * @param args.specifiedOrigin - The origin reported in the request metadata.
+ *
+ * @returns The reconstructed {@link DecodedPermission}.
+ */
+export const reconstructDecodedPermission = ({ chainId, permissionType, delegator, delegate, authority, expiry, data, justification, specifiedOrigin, }) => {
+    if (authority !== ROOT_AUTHORITY) {
+        throw new Error('Invalid authority');
+    }
+    const permission = {
+        chainId: numberToHex(chainId),
+        address: delegator,
+        signer: { type: 'account', data: { address: delegate } },
+        permission: {
+            type: permissionType,
+            data,
+            justification,
+        },
+        expiry,
+        origin: specifiedOrigin,
+    };
+    return permission;
+};
+//# sourceMappingURL=decodePermission.mjs.map

package/dist/decodePermission/decodePermission.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decodePermission.mjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,wBAAwB;AAO/E,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACT,oBAAgB;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,EAC5C,SAAS,EACT,SAAS,GAIV,EAAkB,EAAE;IACnB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAEhE,MAAM,eAAe,GAAG,+BAA+B,CAAC,SAAS,CAAC,CAAC;IAEnE,IAAI,sBAAsB,GAA0B,IAAI,CAAC;IAEzD,KAAK,MAAM,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,GACf,IAAI,eAAe,EAAE;QACpB,MAAM,uBAAuB,GAAG,QAAQ,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;QAE1E,IAAI,qBAAqB,GAAG,KAAK,CAAC;QAElC,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE;YACjC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;gBACnE,qBAAqB,GAAG,IAAI,CAAC;gBAC7B,MAAM;aACP;SACF;QAED,IAAI,uBAAuB,IAAI,CAAC,qBAAqB,EAAE;YACrD,IAAI,sBAAsB,EAAE;gBAC1B,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;aACpD;YACD,sBAAsB,GAAG,cAAc,CAAC;SACzC;KACF;IAED,IAAI,CAAC,sBAAsB,EAAE;QAC3B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;KACvD;IAED,OAAO,sBAAsB,CAAC;AAChC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,EACzC,SAAS,EACT,OAAO,EACP,cAAc,GAKf,EAGC,EAAE;IACF,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC/C,GAAG,MAAM;QACT,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC;KAC9C,CAAC,CAAC,CAAC;IAEJ,MAAM,EACJ,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,GAClB,GAAG,6BAA6B,CAAC,SAAS,CAAC,CAAC;IAE7C,MAAM,WAAW,GAAG,kBAAkB,CAAC;QACrC,OAAO,EAAE,eAAe;QACxB,QAAQ,EAAE,iBAAiB;QAC3B,eAAe,EAAE,KAAK;KACvB,CAAC,CAAC;IAEH,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,WAAW,EAAE;QACf,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAExD,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YAC5B,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;SACnC;QACD,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;KAC9B;IAED,IAAI,IAA6C,CAAC;IAElD,QAAQ,cAAc,EAAE;QACtB,KAAK,oBAAoB,CAAC,CAAC;YACzB,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;gBAC7C,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,sBAAsB;aACjC,CAAC,CAAC;YAEH,MAAM,CACJ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,eAAe,EACf,YAAY,EACb,GAAG,QAAQ,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,IAAI,GAAG;gBACL,YAAY;gBACZ,aAAa;gBACb,SAAS;gBACT,eAAe;gBACf,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD,KAAK,sBAAsB,CAAC,CAAC;YAC3B,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;gBAC5C,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,qBAAqB;aAChC,CAAC,CAAC;YAEH,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,CAAC,GACjE,QAAQ,CAAC,kBAAkB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAEjD,IAAI,GAAG;gBACL,YAAY;gBACZ,YAAY;gBACZ,cAAc,EAAE,WAAW,CAAC,iBAAiB,CAAC;gBAC9C,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QAED,KAAK,qBAAqB,CAAC,CAAC;YAC1B,MAAM,yBAAyB,GAAG,kBAAkB,CAAC;gBACnD,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,4BAA4B;aACvC,CAAC,CAAC;YAEH,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,CAAC,GAC7D,QAAQ,CAAC,yBAAyB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,IAAI,GAAG;gBACL,aAAa;gBACb,SAAS;gBACT,eAAe;gBACf,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD,KAAK,uBAAuB,CAAC,CAAC;YAC5B,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;gBAClD,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,2BAA2B;aACtC,CAAC,CAAC;YAEH,MAAM,CAAC,YAAY,EAAE,iBAAiB,EAAE,YAAY,CAAC,GAAG,QAAQ,CAC9D,wBAAwB,EACxB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CACb,CAAC;YAEF,IAAI,GAAG;gBACL,YAAY;gBACZ,cAAc,EAAE,WAAW,CAAC,iBAAiB,CAAC;gBAC9C,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC;aACrC,CAAC;YACF,MAAM;SACP;QACD;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;KAC9C;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,EAC3C,OAAO,EACP,cAAc,EACd,SAAS,EACT,QAAQ,EACR,SAAS,EACT,MAAM,EACN,IAAI,EACJ,aAAa,EACb,eAAe,GAWhB,EAAE,EAAE;IACH,IAAI,SAAS,KAAK,cAAc,EAAE;QAChC,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;KACtC;IAED,MAAM,UAAU,GAAsB;QACpC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;QAC7B,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;QACxD,UAAU,EAAE;YACV,IAAI,EAAE,cAAc;YACpB,IAAI;YACJ,aAAa;SACd;QACD,MAAM;QACN,MAAM,EAAE,eAAe;KACxB,CAAC;IAEF,OAAO,UAAU,CAAC;AACpB,CAAC,CAAC","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { getChecksumAddress, hexToNumber, numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  DeployedContractsByName,\n  PermissionType,\n} from './types';\nimport {\n  createPermissionRulesForChainId,\n  getChecksumEnforcersByChainId,\n  getTermsByEnforcer,\n  isSubset,\n  splitHex,\n} from './utils';\n\n/**\n * Identifies the unique permission type that matches a given set of enforcer\n * contract addresses for a specific chain.\n *\n * A permission type 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 type's required and\n * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).\n *\n * If exactly one permission type matches, its identifier is returned.\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n *\n * @param args.contracts - The deployed contracts for the chain.\n * @returns The identifier of the matching permission type.\n * @throws If no permission type matches, or if more than one permission type matches.\n */\nexport const identifyPermissionByEnforcers = ({\n  enforcers,\n  contracts,\n}: {\n  enforcers: Hex[];\n  contracts: DeployedContractsByName;\n}): PermissionType => {\n  const enforcersSet = new Set(enforcers.map(getChecksumAddress));\n\n  const permissionRules = createPermissionRulesForChainId(contracts);\n\n  let matchingPermissionType: PermissionType | null = null;\n\n  for (const {\n    allowedEnforcers,\n    requiredEnforcers,\n    permissionType,\n  } of permissionRules) {\n    const hasAllRequiredEnforcers = isSubset(requiredEnforcers, enforcersSet);\n\n    let hasForbiddenEnforcers = false;\n\n    for (const caveat of enforcersSet) {\n      if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {\n        hasForbiddenEnforcers = true;\n        break;\n      }\n    }\n\n    if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {\n      if (matchingPermissionType) {\n        throw new Error('Multiple permission types match');\n      }\n      matchingPermissionType = permissionType;\n    }\n  }\n\n  if (!matchingPermissionType) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  return matchingPermissionType;\n};\n\n/**\n * Extracts the permission-specific data payload and the expiry timestamp from\n * the provided caveats for a given permission type.\n *\n * This function locates the relevant caveat enforcer for the `permissionType`,\n * interprets its `terms` by splitting the hex string into byte-sized segments,\n * and converts each segment into the appropriate numeric or address shape.\n *\n * The expiry timestamp is derived from the `TimestampEnforcer` terms and must\n * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.\n *\n * @param args - The arguments to this function.\n * @param args.contracts - The deployed contracts for the chain.\n * @param args.caveats - Caveats decoded from the permission context.\n * @param args.permissionType - The previously identified permission type.\n *\n * @returns An object containing the `expiry` timestamp and the decoded `data` payload.\n * @throws If the caveats are malformed, missing, or the terms fail to decode.\n */\nexport const getPermissionDataAndExpiry = ({\n  contracts,\n  caveats,\n  permissionType,\n}: {\n  contracts: DeployedContractsByName;\n  caveats: Caveat<Hex>[];\n  permissionType: PermissionType;\n}): {\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n} => {\n  const checksumCaveats = caveats.map((caveat) => ({\n    ...caveat,\n    enforcer: getChecksumAddress(caveat.enforcer),\n  }));\n\n  const {\n    erc20StreamingEnforcer,\n    erc20PeriodicEnforcer,\n    nativeTokenStreamingEnforcer,\n    nativeTokenPeriodicEnforcer,\n    timestampEnforcer,\n  } = getChecksumEnforcersByChainId(contracts);\n\n  const expiryTerms = getTermsByEnforcer({\n    caveats: checksumCaveats,\n    enforcer: timestampEnforcer,\n    throwIfNotFound: false,\n  });\n\n  let expiry: number | null = null;\n  if (expiryTerms) {\n    const [after, before] = splitHex(expiryTerms, [16, 16]);\n\n    if (hexToNumber(after) !== 0) {\n      throw new Error('Invalid expiry');\n    }\n    expiry = hexToNumber(before);\n  }\n\n  let data: DecodedPermission['permission']['data'];\n\n  switch (permissionType) {\n    case 'erc20-token-stream': {\n      const erc20StreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20StreamingEnforcer,\n      });\n\n      const [\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTimeRaw,\n      ] = splitHex(erc20StreamingTerms, [20, 32, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'erc20-token-periodic': {\n      const erc20PeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20PeriodicEnforcer,\n      });\n\n      const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] =\n        splitHex(erc20PeriodicTerms, [20, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n\n    case 'native-token-stream': {\n      const nativeTokenStreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenStreamingEnforcer,\n      });\n\n      const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] =\n        splitHex(nativeTokenStreamingTerms, [32, 32, 32, 32]);\n\n      data = {\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'native-token-periodic': {\n      const nativeTokenPeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenPeriodicEnforcer,\n      });\n\n      const [periodAmount, periodDurationRaw, startTimeRaw] = splitHex(\n        nativeTokenPeriodicTerms,\n        [32, 32, 32],\n      );\n\n      data = {\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    default:\n      throw new Error('Invalid permission type');\n  }\n\n  return { expiry, data };\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 *\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}: {\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}) => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    address: delegator,\n    signer: { type: 'account', data: { address: delegate } },\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n  };\n\n  return permission;\n};\n"]}

package/dist/decodePermission/index.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconstructDecodedPermission = exports.getPermissionDataAndExpiry = exports.identifyPermissionByEnforcers = void 0;
+var decodePermission_1 = require("./decodePermission.cjs");
+Object.defineProperty(exports, "identifyPermissionByEnforcers", { enumerable: true, get: function () { return decodePermission_1.identifyPermissionByEnforcers; } });
+Object.defineProperty(exports, "getPermissionDataAndExpiry", { enumerable: true, get: function () { return decodePermission_1.getPermissionDataAndExpiry; } });
+Object.defineProperty(exports, "reconstructDecodedPermission", { enumerable: true, get: function () { return decodePermission_1.reconstructDecodedPermission; } });
+//# sourceMappingURL=index.cjs.map

package/dist/decodePermission/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":";;;AAAA,2DAI4B;AAH1B,iIAAA,6BAA6B,OAAA;AAC7B,8HAAA,0BAA0B,OAAA;AAC1B,gIAAA,4BAA4B,OAAA","sourcesContent":["export {\n  identifyPermissionByEnforcers,\n  getPermissionDataAndExpiry,\n  reconstructDecodedPermission,\n} from './decodePermission';\n\nexport type { DecodedPermission } from './types';\n"]}

package/dist/decodePermission/index.d.cts

@@ -0,0 +1,3 @@
+export { identifyPermissionByEnforcers, getPermissionDataAndExpiry, reconstructDecodedPermission, } from "./decodePermission.cjs";
+export type { DecodedPermission } from "./types.cjs";
+//# sourceMappingURL=index.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,GAC7B,+BAA2B;AAE5B,YAAY,EAAE,iBAAiB,EAAE,oBAAgB"}

package/dist/decodePermission/index.d.mts

@@ -0,0 +1,3 @@
+export { identifyPermissionByEnforcers, getPermissionDataAndExpiry, reconstructDecodedPermission, } from "./decodePermission.mjs";
+export type { DecodedPermission } from "./types.mjs";
+//# sourceMappingURL=index.d.mts.map