@pepu-chain/sdk 0.0.0-stage → 0.2.1

package/dist/chunk-YKEWWQEJ.js

@@ -0,0 +1,165 @@
+import { PepuPolicyError } from './chunk-6DSZ4Z2N.js';
+import { isAddress, isHex, encodeFunctionData, toHex, toFunctionSelector, toFunctionSignature } from 'viem';
+
+var PRIVY_POLICY_NAME_MAX_LENGTH = 49;
+function assertWithinPolicyNameLimit(value, field) {
+  if (value.length > PRIVY_POLICY_NAME_MAX_LENGTH) {
+    throw new PepuPolicyError(
+      "POLICY_NAME_TOO_LONG",
+      `${field} is ${value.length} characters ("${value}"), but Privy rejects policy/rule names of ${PRIVY_POLICY_NAME_MAX_LENGTH + 1} or more (max ${PRIVY_POLICY_NAME_MAX_LENGTH}). Shorten it.`
+    );
+  }
+  return value;
+}
+function truncateAddress(address) {
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+function buildSessionPolicy({
+  contractAddress,
+  functions,
+  expiresAtUnixSeconds,
+  name
+}) {
+  if (!isAddress(contractAddress, { strict: false })) {
+    throw new PepuPolicyError(
+      "POLICY_UNSCOPED",
+      "buildSessionPolicy: contractAddress must be a valid 0x address; refusing to build an unscoped policy."
+    );
+  }
+  if (functions.length === 0) {
+    throw new PepuPolicyError(
+      "POLICY_UNSCOPED",
+      "buildSessionPolicy: at least one function is required; refusing to build an unscoped policy."
+    );
+  }
+  for (const fn of functions) {
+    if (fn.type !== "function" || !fn.name) {
+      throw new PepuPolicyError(
+        "POLICY_UNSCOPED",
+        "buildSessionPolicy: every entry in `functions` must be an ABI function fragment with a name."
+      );
+    }
+  }
+  if (!Number.isInteger(expiresAtUnixSeconds) || expiresAtUnixSeconds <= 0) {
+    throw new PepuPolicyError(
+      "POLICY_UNSCOPED",
+      "buildSessionPolicy: expiresAtUnixSeconds must be a positive integer (unix seconds); refusing to build a policy with no expiry."
+    );
+  }
+  const short = truncateAddress(contractAddress);
+  const policyName = assertWithinPolicyNameLimit(
+    name ?? `session: ${functions.map((f) => f.name).join("/")} on ${short}`,
+    "Policy name"
+  );
+  const rules = functions.map((fn, index) => ({
+    name: assertWithinPolicyNameLimit(
+      `Allow ${fn.name}() on ${short}, 0 value, expires`,
+      `Rule name ("rules[${index}].name")`
+    ),
+    method: "eth_signTransaction",
+    action: "ALLOW",
+    conditions: [
+      { field_source: "ethereum_transaction", field: "to", operator: "eq", value: contractAddress },
+      {
+        field_source: "ethereum_calldata",
+        field: "function_name",
+        abi: [fn],
+        operator: "eq",
+        value: fn.name
+      },
+      { field_source: "ethereum_transaction", field: "value", operator: "eq", value: "0x0" },
+      {
+        field_source: "system",
+        field: "current_unix_timestamp",
+        operator: "lte",
+        value: String(expiresAtUnixSeconds)
+      }
+    ]
+  }));
+  return { version: "1.0", name: policyName, chain_type: "ethereum", rules };
+}
+function withGasLimitBuffer(estimatedGas) {
+  return estimatedGas + estimatedGas * 20n / 100n;
+}
+async function broadcastSignedTransaction(client, signed) {
+  const raw = typeof signed === "string" ? signed : signed.signed_transaction;
+  if (!isHex(raw) || raw.length <= 2) {
+    throw new Error("broadcastSignedTransaction: expected a 0x-prefixed hex signed transaction.");
+  }
+  return client.sendRawTransaction({ serializedTransaction: raw });
+}
+async function signAndBroadcast(params) {
+  const { client, from, to, chainId, sign } = params;
+  const value = params.value ?? 0n;
+  const data = params.data ?? (params.abi && params.functionName ? encodeFunctionData({
+    abi: params.abi,
+    functionName: params.functionName,
+    ...params.args ? { args: params.args } : {}
+  }) : void 0);
+  if (!data) {
+    throw new Error("signAndBroadcast: provide `data`, or `abi` + `functionName`.");
+  }
+  const [nonce, estimatedGas, gasPrice] = await Promise.all([
+    client.getTransactionCount({ address: from, blockTag: "pending" }),
+    client.estimateGas({ account: from, to, data, value }),
+    client.getGasPrice()
+  ]);
+  const transaction = {
+    to,
+    data,
+    value: toHex(value),
+    chain_id: chainId,
+    type: 0,
+    nonce,
+    gas_limit: toHex(withGasLimitBuffer(estimatedGas)),
+    gas_price: toHex(gasPrice)
+  };
+  return broadcastSignedTransaction(client, await sign(transaction));
+}
+var DEFAULT_SESSION_MINUTES = 15;
+var MAX_SESSION_MINUTES = 1440;
+function resolveSessionMinutes(raw) {
+  if (raw === null || raw === void 0 || typeof raw === "string" && raw.trim() === "") {
+    return DEFAULT_SESSION_MINUTES;
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SESSION_MINUTES;
+  return Math.min(n, MAX_SESSION_MINUTES);
+}
+function sessionExpiry(nowSeconds, minutes) {
+  return Math.floor(nowSeconds + minutes * 60);
+}
+function describeSessionScope(p) {
+  if (!isAddress(p.contractAddress, { strict: false })) {
+    throw new PepuPolicyError("POLICY_UNSCOPED", "describeSessionScope: contractAddress must be a valid 0x address.");
+  }
+  if (p.functions.length === 0) {
+    throw new PepuPolicyError("POLICY_UNSCOPED", "describeSessionScope: at least one function is required.");
+  }
+  return {
+    contractAddress: p.contractAddress,
+    expiresAtUnixSeconds: p.expiresAtUnixSeconds,
+    functions: p.functions.map((fn) => {
+      if (fn.type !== "function" || !fn.name) {
+        throw new PepuPolicyError(
+          "POLICY_UNSCOPED",
+          "describeSessionScope: every entry in `functions` must be an ABI function fragment with a name."
+        );
+      }
+      return {
+        name: fn.name,
+        signature: toFunctionSignature(fn).replace(/^function /, ""),
+        selector: toFunctionSelector(fn),
+        valueWei: "0"
+      };
+    })
+  };
+}
+var SESSION_TRUST_NOTICE = {
+  "privy-offchain": "This scope is enforced by Privy's backend policy engine when it receives each transaction request, not by an on-chain contract. You are trusting Privy's policy engine and this app's policy configuration to enforce the limits correctly. Gas is paid by your wallet and is not capped by the policy.",
+  "kernel-onchain": "This scope is enforced on-chain by your smart account's permission validator (call and timestamp policies). The limits hold even if this app's backend is compromised, but the session key can still act within them until it expires or you revoke it."
+};
+
+export { DEFAULT_SESSION_MINUTES, MAX_SESSION_MINUTES, PRIVY_POLICY_NAME_MAX_LENGTH, SESSION_TRUST_NOTICE, assertWithinPolicyNameLimit, broadcastSignedTransaction, buildSessionPolicy, describeSessionScope, resolveSessionMinutes, sessionExpiry, signAndBroadcast, withGasLimitBuffer };
+//# sourceMappingURL=chunk-YKEWWQEJ.js.map
+//# sourceMappingURL=chunk-YKEWWQEJ.js.map

package/dist/chunk-YKEWWQEJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session/policy.ts"],"names":[],"mappings":"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","file":"chunk-YKEWWQEJ.js","sourcesContent":["import { encodeFunctionData, isAddress, isHex, toFunctionSelector, toFunctionSignature, toHex } from \"viem\";\nimport type { Abi, AbiFunction, Address, Hash, Hex } from \"viem\";\nimport { PepuPolicyError } from \"../errors.js\";\n\n/**\n * SERVER-ONLY helpers (`@pepu-chain/sdk/server`). Nothing here holds a secret,\n * but these run on a backend that does hold Privy's app secret and\n * authorization key; keep this entry point out of client bundles. No module\n * in `src/` imports the `./server` barrel (enforced by a test). This file is the pure policy builder; it is re-exported from `@pepu-chain/sdk/session` and `@pepu-chain/sdk/server`.\n */\n\n/**\n * Privy rejects policy and rule names of 50 characters or more. Its published\n * OpenAPI spec says `maxLength: 50`, but the live validator says \"must be\n * fewer than 50 characters\", so the real limit is 49 (measured on a real\n * `POST /policies` 400). Using 49 is safe under both readings.\n */\nexport const PRIVY_POLICY_NAME_MAX_LENGTH = 49;\n\n/** Throws if `value` is over {@link PRIVY_POLICY_NAME_MAX_LENGTH}; returns it otherwise. */\nexport function assertWithinPolicyNameLimit(value: string, field: string): string {\n  if (value.length > PRIVY_POLICY_NAME_MAX_LENGTH) {\n    throw new PepuPolicyError(\"POLICY_NAME_TOO_LONG\", \n      `${field} is ${value.length} characters (\"${value}\"), but Privy rejects policy/rule names ` +\n        `of ${PRIVY_POLICY_NAME_MAX_LENGTH + 1} or more (max ${PRIVY_POLICY_NAME_MAX_LENGTH}). Shorten it.`,\n    );\n  }\n  return value;\n}\n\nexport type SessionPolicyCondition =\n  | { field_source: \"ethereum_transaction\"; field: \"to\" | \"value\"; operator: \"eq\"; value: string }\n  | {\n      field_source: \"ethereum_calldata\";\n      field: \"function_name\";\n      abi: AbiFunction[];\n      operator: \"eq\";\n      value: string;\n    }\n  | { field_source: \"system\"; field: \"current_unix_timestamp\"; operator: \"lte\"; value: string };\n\nexport interface SessionPolicyRule {\n  name: string;\n  method: \"eth_signTransaction\";\n  action: \"ALLOW\";\n  conditions: SessionPolicyCondition[];\n}\n\n/** Body for `privy.policies().create(...)`. */\nexport interface SessionPolicy {\n  version: \"1.0\";\n  name: string;\n  chain_type: \"ethereum\";\n  rules: SessionPolicyRule[];\n}\n\nexport interface BuildSessionPolicyParams {\n  /** The one contract the session may call. */\n  contractAddress: Address;\n  /** The function(s) the session may call, as ABI function fragments. At least one. */\n  functions: readonly AbiFunction[];\n  /** Unix seconds after which Privy's engine denies every request. */\n  expiresAtUnixSeconds: number;\n  /** Optional dashboard label; must be at most 49 characters. */\n  name?: string;\n}\n\nfunction truncateAddress(address: string): string {\n  return `${address.slice(0, 6)}...${address.slice(-4)}`;\n}\n\n/**\n * Build the scoped Privy session-signer policy: ONE `ALLOW` rule per function,\n * each requiring `to` equals the contract, calldata decodes to that function,\n * `value` is exactly zero, and the clock is before expiry. Privy ANDs the\n * conditions in a rule, ORs the rules, and denies by default.\n *\n * Refuses to build an unscoped policy: it throws on an invalid contract\n * address, no functions, a non-function ABI item, or a bad expiry. Names are\n * checked against {@link PRIVY_POLICY_NAME_MAX_LENGTH}. The method is\n * `eth_signTransaction` (a rule for `eth_sendTransaction` never matches the\n * sign-and-broadcast flow).\n *\n * The scope is enforced by Privy's backend policy engine, not on-chain.\n */\nexport function buildSessionPolicy({\n  contractAddress,\n  functions,\n  expiresAtUnixSeconds,\n  name,\n}: BuildSessionPolicyParams): SessionPolicy {\n  if (!isAddress(contractAddress, { strict: false })) {\n    throw new PepuPolicyError(\"POLICY_UNSCOPED\", \n      \"buildSessionPolicy: contractAddress must be a valid 0x address; refusing to build an unscoped policy.\",\n    );\n  }\n  if (functions.length === 0) {\n    throw new PepuPolicyError(\"POLICY_UNSCOPED\", \n      \"buildSessionPolicy: at least one function is required; refusing to build an unscoped policy.\",\n    );\n  }\n  for (const fn of functions) {\n    if (fn.type !== \"function\" || !fn.name) {\n      throw new PepuPolicyError(\"POLICY_UNSCOPED\", \n        \"buildSessionPolicy: every entry in `functions` must be an ABI function fragment with a name.\",\n      );\n    }\n  }\n  if (!Number.isInteger(expiresAtUnixSeconds) || expiresAtUnixSeconds <= 0) {\n    throw new PepuPolicyError(\"POLICY_UNSCOPED\", \n      \"buildSessionPolicy: expiresAtUnixSeconds must be a positive integer (unix seconds); refusing to build a policy with no expiry.\",\n    );\n  }\n\n  const short = truncateAddress(contractAddress);\n  const policyName = assertWithinPolicyNameLimit(\n    name ?? `session: ${functions.map((f) => f.name).join(\"/\")} on ${short}`,\n    \"Policy name\",\n  );\n\n  const rules: SessionPolicyRule[] = functions.map((fn, index) => ({\n    name: assertWithinPolicyNameLimit(\n      `Allow ${fn.name}() on ${short}, 0 value, expires`,\n      `Rule name (\"rules[${index}].name\")`,\n    ),\n    method: \"eth_signTransaction\",\n    action: \"ALLOW\",\n    conditions: [\n      { field_source: \"ethereum_transaction\", field: \"to\", operator: \"eq\", value: contractAddress },\n      {\n        field_source: \"ethereum_calldata\",\n        field: \"function_name\",\n        abi: [fn],\n        operator: \"eq\",\n        value: fn.name,\n      },\n      { field_source: \"ethereum_transaction\", field: \"value\", operator: \"eq\", value: \"0x0\" },\n      {\n        field_source: \"system\",\n        field: \"current_unix_timestamp\",\n        operator: \"lte\",\n        value: String(expiresAtUnixSeconds),\n      },\n    ],\n  }));\n\n  return { version: \"1.0\", name: policyName, chain_type: \"ethereum\", rules };\n}\n\n/** The unsigned legacy transaction body Privy's `eth_signTransaction` takes (snake_case, hex quantities). */\nexport interface PrivyUnsignedTransaction {\n  readonly to: Address;\n  readonly data: Hex;\n  readonly value: Hex;\n  readonly chain_id: number;\n  readonly type: 0;\n  readonly nonce: number;\n  readonly gas_limit: Hex;\n  readonly gas_price: Hex;\n}\n\n/** What Privy's `signTransaction` returns, or just the raw hex. */\nexport type SignedTransactionLike = Hex | { signed_transaction: string };\n\n/** Minimal viem client surface needed to broadcast. */\nexport interface BroadcastClient {\n  sendRawTransaction(args: { serializedTransaction: Hex }): Promise<Hash>;\n}\n\n/** Minimal viem client surface needed to resolve nonce/gas and broadcast. */\nexport interface SignAndBroadcastClient extends BroadcastClient {\n  getTransactionCount(args: { address: Address; blockTag: \"pending\" }): Promise<number>;\n  estimateGas(args: { account: Address; to: Address; data: Hex; value: bigint }): Promise<bigint>;\n  getGasPrice(): Promise<bigint>;\n}\n\n/** Estimate plus 20%: Nitro gas estimates can undershoot slightly. */\nexport function withGasLimitBuffer(estimatedGas: bigint): bigint {\n  return estimatedGas + (estimatedGas * 20n) / 100n;\n}\n\n/**\n * Broadcast a raw signed transaction (from Privy `eth_signTransaction`) to\n * PEPU through a viem client and return the transaction hash. Accepts the raw\n * hex or Privy's `{ signed_transaction }` object. A failure here is a failed\n * TRANSACTION (revert, nonce race), not proof the session signer is gone.\n */\nexport async function broadcastSignedTransaction(\n  client: BroadcastClient,\n  signed: SignedTransactionLike,\n): Promise<Hash> {\n  const raw = typeof signed === \"string\" ? signed : signed.signed_transaction;\n  if (!isHex(raw) || raw.length <= 2) {\n    throw new Error(\"broadcastSignedTransaction: expected a 0x-prefixed hex signed transaction.\");\n  }\n  return client.sendRawTransaction({ serializedTransaction: raw });\n}\n\nexport interface SignAndBroadcastParams {\n  client: SignAndBroadcastClient;\n  /** The wallet that signs (the session-signer wallet's address). */\n  from: Address;\n  to: Address;\n  /** Pre-encoded calldata, or use `abi` + `functionName` + `args`. */\n  data?: Hex;\n  abi?: Abi;\n  functionName?: string;\n  args?: readonly unknown[];\n  /** Native value in wei. Default 0n. */\n  value?: bigint;\n  chainId: number;\n  /**\n   * Performs the signing, e.g. a call to\n   * `privy.wallets().ethereum().signTransaction(walletId, { params: { transaction }, authorization_context })`\n   * and returns its result. Injected so this package has no Privy dependency.\n   */\n  sign: (transaction: PrivyUnsignedTransaction) => Promise<SignedTransactionLike>;\n}\n\n/**\n * The full sign-with-Privy, broadcast-yourself flow: resolve nonce (pending),\n * gas (+20%) and gas price against PEPU's RPC, build the unsigned legacy\n * transaction, hand it to `sign`, then broadcast the result and return the hash.\n * Privy's server-side `eth_sendTransaction` rejects chain 97741, which is why\n * this exists.\n */\nexport async function signAndBroadcast(params: SignAndBroadcastParams): Promise<Hash> {\n  const { client, from, to, chainId, sign } = params;\n  const value = params.value ?? 0n;\n  const data =\n    params.data ??\n    (params.abi && params.functionName\n      ? encodeFunctionData({\n          abi: params.abi,\n          functionName: params.functionName,\n          ...(params.args ? { args: params.args } : {}),\n        } as Parameters<typeof encodeFunctionData>[0])\n      : undefined);\n  if (!data) {\n    throw new Error(\"signAndBroadcast: provide `data`, or `abi` + `functionName`.\");\n  }\n\n  const [nonce, estimatedGas, gasPrice] = await Promise.all([\n    client.getTransactionCount({ address: from, blockTag: \"pending\" }),\n    client.estimateGas({ account: from, to, data, value }),\n    client.getGasPrice(),\n  ]);\n\n  const transaction: PrivyUnsignedTransaction = {\n    to,\n    data,\n    value: toHex(value),\n    chain_id: chainId,\n    type: 0,\n    nonce,\n    gas_limit: toHex(withGasLimitBuffer(estimatedGas)),\n    gas_price: toHex(gasPrice),\n  };\n\n  return broadcastSignedTransaction(client, await sign(transaction));\n}\n\n/** Default session length when `SESSION_DURATION_MINUTES` is unset or invalid. */\nexport const DEFAULT_SESSION_MINUTES = 15;\n/** Upper bound for a session: 24 hours. Larger requests are clamped. */\nexport const MAX_SESSION_MINUTES = 1440;\n\n/**\n * Parse a session duration (an env value or number) into minutes: anything\n * missing, non-numeric, zero or negative falls back to\n * {@link DEFAULT_SESSION_MINUTES}; anything above {@link MAX_SESSION_MINUTES} is clamped.\n * Lifted from templates/game-app/lib/env.server.ts.\n *\n * @example\n * resolveSessionMinutes(process.env.SESSION_DURATION_MINUTES); // 15 when unset\n * resolveSessionMinutes(\"99999\"); // 1440\n */\nexport function resolveSessionMinutes(raw: string | number | null | undefined): number {\n  if (raw === null || raw === undefined || (typeof raw === \"string\" && raw.trim() === \"\")) {\n    return DEFAULT_SESSION_MINUTES;\n  }\n  const n = Number(raw);\n  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SESSION_MINUTES;\n  return Math.min(n, MAX_SESSION_MINUTES);\n}\n\n/**\n * The unix-seconds expiry for a session that starts at `nowSeconds` and lasts\n * `minutes`. Whole seconds, rounded down.\n *\n * @example\n * sessionExpiry(1_700_000_000, 15); // 1_700_000_900\n */\nexport function sessionExpiry(nowSeconds: number, minutes: number): number {\n  return Math.floor(nowSeconds + minutes * 60);\n}\n\n/** One callable function in a session's scope, ready for a consent screen. */\nexport interface SessionScopeFunction {\n  name: string;\n  /** e.g. `tap()` or `transfer(address,uint256)`. */\n  signature: string;\n  /** 4-byte selector. */\n  selector: Hex;\n  /** Always `\"0\"`: a session call never carries native value. */\n  valueWei: \"0\";\n}\n\n/** What a session may do, as plain data for a consent screen. */\nexport interface SessionScope {\n  contractAddress: Address;\n  functions: SessionScopeFunction[];\n  expiresAtUnixSeconds: number;\n}\n\n/**\n * Consent-screen data for a session: the one contract, each allowed function\n * (name, signature, selector), zero value, and the expiry. Throws on an\n * invalid address or an empty or non-function list, same as {@link buildSessionPolicy}.\n *\n * @example\n * const scope = describeSessionScope({ contractAddress, functions: [tapAbi], expiresAtUnixSeconds });\n * scope.functions[0]?.signature; // \"tap()\"\n */\nexport function describeSessionScope(p: {\n  contractAddress: Address;\n  functions: readonly AbiFunction[];\n  expiresAtUnixSeconds: number;\n}): SessionScope {\n  if (!isAddress(p.contractAddress, { strict: false })) {\n    throw new PepuPolicyError(\"POLICY_UNSCOPED\", \"describeSessionScope: contractAddress must be a valid 0x address.\");\n  }\n  if (p.functions.length === 0) {\n    throw new PepuPolicyError(\"POLICY_UNSCOPED\", \"describeSessionScope: at least one function is required.\");\n  }\n  return {\n    contractAddress: p.contractAddress,\n    expiresAtUnixSeconds: p.expiresAtUnixSeconds,\n    functions: p.functions.map((fn) => {\n      if (fn.type !== \"function\" || !fn.name) {\n        throw new PepuPolicyError(\"POLICY_UNSCOPED\", \n          \"describeSessionScope: every entry in `functions` must be an ABI function fragment with a name.\",\n        );\n      }\n      return {\n        name: fn.name,\n        signature: toFunctionSignature(fn).replace(/^function /, \"\"),\n        selector: toFunctionSelector(fn),\n        valueWei: \"0\" as const,\n      };\n    }),\n  };\n}\n\n/**\n * The mandatory honest statements about who enforces a session's limits. Show\n * the one for the mode in use on the consent screen. Adapted from\n * templates/game-app/components/session-consent-screen.tsx.\n *\n * @example\n * <p>{SESSION_TRUST_NOTICE[\"privy-offchain\"]}</p>\n */\nexport const SESSION_TRUST_NOTICE: Record<\"privy-offchain\" | \"kernel-onchain\", string> = {\n  \"privy-offchain\":\n    \"This scope is enforced by Privy's backend policy engine when it receives each transaction request, not by an on-chain contract. You are trusting Privy's policy engine and this app's policy configuration to enforce the limits correctly. Gas is paid by your wallet and is not capped by the policy.\",\n  \"kernel-onchain\":\n    \"This scope is enforced on-chain by your smart account's permission validator (call and timestamp policies). The limits hold even if this app's backend is compromised, but the session key can still act within them until it expires or you revoke it.\",\n};\n"]}