payid 0.3.1 → 0.3.3

package/dist/index-DuOeYzN2.d.ts

@@ -0,0 +1,118 @@
+import { ethers } from 'ethers';
+import { P as PayIDSessionPolicyPayloadV1 } from './types-DKt-zH0P.js';
+import { RuleConfig } from 'payid-types';
+
+/**
+ * Create and sign an ephemeral PayID session policy payload.
+ *
+ * A session policy represents a **temporary, off-chain consent**
+ * granted by the receiver to apply additional rule constraints
+ * during rule evaluation (e.g. session limits, QR payments,
+ * intent-scoped conditions).
+ *
+ * ## Security model
+ *
+ * - The session policy is signed by the receiver.
+ * - The signature proves **explicit consent** for the included rule.
+ * - This policy does NOT establish on-chain authority and MUST NOT
+ *   be registered or referenced in any on-chain rule registry.
+ *
+ * ## Canonicalization
+ *
+ * - The rule set is canonicalized BEFORE signing to ensure
+ *   deterministic hashing and signature verification.
+ * - The exact payload signed here MUST be used verbatim during
+ *   policy verification.
+ *
+ * ## Lifecycle
+ *
+ * - Session policies are valid only until `expiresAt`.
+ * - Expired policies MUST be rejected by the verifier.
+ *
+ * @param params
+ * @param params.receiver
+ *   Address of the receiver granting the session policy.
+ *
+ * @param params.rule
+ *   Rule configuration to be applied as an **off-chain evaluation
+ *   override** during the session.
+ *
+ * @param params.expiresAt
+ *   UNIX timestamp (seconds) indicating when the session policy
+ *   becomes invalid.
+ *
+ * @param params.signer
+ *   Signer controlling the receiver address, used to sign the
+ *   session policy payload.
+ *
+ * @returns
+ *   A signed `PayIDSessionPolicyPayloadV1` that may be transmitted
+ *   to clients and verified using `decodeSessionPolicy`.
+ *
+ * @throws
+ *   May throw if signing fails or the signer is misconfigured.
+ */
+declare function createSessionPolicyPayload(params: {
+    receiver: string;
+    rule: {
+        version: string;
+        logic: "AND";
+        rules: any[];
+    };
+    expiresAt: number;
+    signer: ethers.Signer;
+}): Promise<PayIDSessionPolicyPayloadV1>;
+
+/**
+ * Decode and verify an ephemeral PayID session policy.
+ *
+ * This function validates that a session policy:
+ * - Uses a supported policy version
+ * - Has not expired
+ * - Was cryptographically signed by the declared receiver
+ *
+ * If all checks pass, the embedded rule configuration is returned
+ * and may be used as an **off-chain evaluation override**
+ * (e.g. combined with an authoritative on-chain rule).
+ *
+ * ## Security model
+ *
+ * - The session policy signature represents **explicit consent**
+ *   from the receiver for temporary rule constraints.
+ * - This policy does NOT establish on-chain authority and MUST NOT
+ *   be used to derive `ruleSetHash` or interact with rule registries.
+ *
+ * ## Invariants
+ *
+ * - The payload verified here MUST match exactly the payload that was signed.
+ * - No canonicalization or mutation is performed during verification.
+ * - Expired or invalidly signed policies are rejected immediately.
+ *
+ * @export
+ *
+ * @param sessionPolicy
+ *   A signed session policy payload created by
+ *   `createSessionPolicyPayload`.
+ *
+ * @param now
+ *   Current UNIX timestamp (seconds) used to validate policy expiry.
+ *
+ * @returns
+ *   A `RuleConfig` representing the session's evaluation rule.
+ *
+ * @throws
+ *   Throws if:
+ *   - The policy version is unsupported
+ *   - The policy has expired
+ *   - The signature does not match the receiver
+ */
+declare function decodeSessionPolicy(sessionPolicy: PayIDSessionPolicyPayloadV1, now: number): RuleConfig;
+
+declare const index_PayIDSessionPolicyPayloadV1: typeof PayIDSessionPolicyPayloadV1;
+declare const index_createSessionPolicyPayload: typeof createSessionPolicyPayload;
+declare const index_decodeSessionPolicy: typeof decodeSessionPolicy;
+declare namespace index {
+  export { index_PayIDSessionPolicyPayloadV1 as PayIDSessionPolicyPayloadV1, index_createSessionPolicyPayload as createSessionPolicyPayload, index_decodeSessionPolicy as decodeSessionPolicy };
+}
+
+export { createSessionPolicyPayload as c, decodeSessionPolicy as d, index as i };

package/dist/index.d.ts

@@ -1 +1,125 @@
-export { PayID } from "./payid";
+import { RuleContext, RuleConfig, RuleResult } from 'payid-types';
+import { ethers } from 'ethers';
+export { i as sessionPolicy } from './index-DuOeYzN2.js';
+export { i as rule } from './index-C7vziL_Z.js';
+export { i as issuer } from './index-2JCvey4-.js';
+export { i as context } from './index-BEvnPzzt.js';
+export { i as server } from './index-BrD4MTYK.js';
+export { i as client } from './index-DY-T49uU.js';
+import './types-DKt-zH0P.js';
+import './types-B5dv7L-8.js';
+
+interface RuleSource {
+    uri: string;
+    hash?: string;
+}
+
+interface UserOperation {
+    sender: string;
+    nonce: string;
+    initCode: string;
+    callData: string;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymasterAndData: string;
+    signature: string;
+}
+
+interface PayIDClient {
+    evaluate(context: RuleContext, rule: RuleConfig | RuleSource): Promise<RuleResult>;
+}
+interface PayIDServer {
+    evaluateAndProve(params: {
+        context: RuleContext;
+        authorityRule: RuleConfig;
+        evaluationRule?: RuleConfig;
+        payId: string;
+        payer: string;
+        receiver: string;
+        asset: string;
+        amount: bigint;
+        signer: ethers.Signer;
+        verifyingContract: string;
+        ruleRegistryContract: string;
+        ttlSeconds?: number;
+    }): Promise<{
+        result: RuleResult;
+        proof: any | null;
+    }>;
+    buildUserOperation(params: {
+        proof: any;
+        smartAccount: string;
+        nonce: string;
+        gas: any;
+        targetContract: string;
+        paymasterAndData?: string;
+    }): UserOperation;
+}
+
+/**
+ * Create a PayID policy engine instance backed by a WASM rule evaluator.
+ *
+ * ## Responsibility
+ *
+ * - Holds the WASM binary used for rule execution
+ * - Defines the trust boundary for context attestation verification
+ * - Acts as the primary entry point for PayID rule evaluation
+ *
+ * ## Trust model
+ *
+ * - If `trustedIssuers` is provided, Context V2 attestation
+ *   verification is ENFORCED.
+ * - If `trustedIssuers` is omitted, the engine runs in
+ *   legacy (Context V1) mode without cryptographic verification.
+ *
+ * ## Environment
+ *
+ * This class is safe to instantiate in:
+ * - Browsers
+ * - Mobile apps
+ * - Edge runtimes
+ * - Backend services
+ *
+ * @param wasm
+ *   Compiled PayID WASM rule engine binary.
+ *
+ * @param debugTrace
+ *   Optional flag to enable decision trace generation for debugging.
+ *
+ * @param trustedIssuers
+ *   Optional set of trusted attestation issuer addresses.
+ *
+ *   When provided, Context V2 attestation verification is ENFORCED:
+ *   - Only attestations issued by addresses in this set are accepted.
+ *   - Missing, expired, or invalid attestations cause evaluation to fail.
+ *
+ *   When omitted, the engine runs in legacy (Context V1) mode
+ *   without cryptographic verification.
+ *
+ *   ⚠️ Important:
+ *   - Do NOT pass an empty Set.
+ *     An empty set means "no issuer is trusted" and will
+ *     cause all attestations to be rejected.
+ *
+ *   @example
+ *   ```ts
+ *   const trustedIssuers = new Set([
+ *     TIME_ISSUER,
+ *     STATE_ISSUER,
+ *     ORACLE_ISSUER,
+ *     RISK_ISSUER
+ *   ]);
+ *
+ *   const payid = new PayID(wasmBinary, debugTrace, trustedIssuers);
+ *   ```
+ */
+declare function createPayID(params: {
+    wasm: Uint8Array;
+    debugTrace?: boolean;
+    trustedIssuers?: Set<string>;
+}): PayIDClient & PayIDServer;
+
+export { type PayIDClient, type PayIDServer, createPayID };

package/dist/index.js

@@ -1 +1,303 @@
-export { PayID } from "./payid";
+import {
+  context_exports
+} from "./chunk-RCXMRX4F.js";
+import {
+  issuer_exports
+} from "./chunk-AOKLY2QN.js";
+import "./chunk-7U3P7XJE.js";
+import {
+  rule_exports
+} from "./chunk-JRVCGSKK.js";
+import {
+  sessionPolicy_exports
+} from "./chunk-ATWJEWZH.js";
+import {
+  client_exports
+} from "./chunk-XWOB3JVE.js";
+import "./chunk-QYH3FNQ4.js";
+import "./chunk-MXKZJKXE.js";
+import "./chunk-JJEWYFOV.js";
+import {
+  server_exports
+} from "./chunk-FIMJNWJ3.js";
+import {
+  evaluate,
+  generateDecisionProof,
+  resolveRule
+} from "./chunk-4MPVXPLM.js";
+import "./chunk-5ZEKI5Y2.js";
+import "./chunk-R5U7XKVJ.js";
+
+// src/erc4337/build.ts
+import { ethers } from "ethers";
+function buildPayCallData(contractAddress, proof) {
+  const iface = new ethers.Interface([
+    "function pay(bytes payload, bytes signature)"
+  ]);
+  return iface.encodeFunctionData("pay", [
+    ethers.toUtf8Bytes(JSON.stringify(proof.payload)),
+    proof.signature
+  ]);
+}
+
+// src/erc4337/userop.ts
+function buildUserOperation(params) {
+  return {
+    sender: params.sender,
+    nonce: params.nonce,
+    initCode: params.initCode ?? "0x",
+    callData: params.callData,
+    callGasLimit: params.gas.callGasLimit,
+    verificationGasLimit: params.gas.verificationGasLimit,
+    preVerificationGas: params.gas.preVerificationGas,
+    maxFeePerGas: params.gas.maxFeePerGas,
+    maxPriorityFeePerGas: params.gas.maxPriorityFeePerGas,
+    paymasterAndData: params.paymasterAndData ?? "0x",
+    signature: "0x"
+    // signed later by smart account
+  };
+}
+
+// src/core/payid.ts
+function isRuleSource(rule) {
+  return typeof rule === "object" && rule !== null && "uri" in rule;
+}
+var PayID = class {
+  constructor(wasm, debugTrace, trustedIssuers) {
+    this.wasm = wasm;
+    this.debugTrace = debugTrace;
+    this.trustedIssuers = trustedIssuers;
+  }
+  /**
+   * Evaluate a rule set against a given context using the PayID WASM engine.
+   *
+   * ## Responsibility
+   *
+   * This method performs **pure rule evaluation only**:
+   * - Resolves the rule configuration (inline or via RuleSource)
+   * - Executes the rule engine
+   * - Returns an ALLOW / REJECT decision
+   *
+   * This method does NOT:
+   * - Generate decision proofs
+   * - Interact with on-chain rule registries
+   * - Enforce rule ownership or authority
+   * - Perform any signing
+   *
+   * ## Environment
+   *
+   * This method is **client-safe** and may be called from:
+   * - Browsers
+   * - Mobile apps
+   * - Edge runtimes
+   * - Backend services
+   *
+   * ## Rule source behavior
+   *
+   * - If `rule` is a `RuleConfig`, it is evaluated directly.
+   * - If `rule` is a `RuleSource`, it is resolved off-chain
+   *   before evaluation.
+   *
+   * @param context
+   *   Rule execution context (transaction data, payId, etc.).
+   *
+   * @param rule
+   *   Rule configuration to evaluate, either:
+   *   - An inline `RuleConfig`, or
+   *   - A `RuleSource` that resolves to a `RuleConfig`.
+   *
+   * @returns
+   *   A `RuleResult` indicating whether the rule allows or
+   *   rejects the given context.
+   *
+   * @throws
+   *   May throw if rule resolution or evaluation fails.
+   */
+  async evaluate(context, rule) {
+    const config = isRuleSource(rule) ? (await resolveRule(rule)).config : rule;
+    return evaluate(this.wasm, context, config, { debug: this.debugTrace, trustedIssuers: this.trustedIssuers });
+  }
+  /**
+   * Evaluate a payment intent against PayID rules and (if allowed)
+   * generate an off-chain Decision Proof for on-chain verification.
+   *
+   * ## Conceptual model
+   *
+   * - `authorityRule` defines the **authoritative rule set**
+   *   registered on-chain (NFT / combined rule).
+   * - `evaluationRule` (optional) is an **off-chain override**
+   *   used only for evaluation (e.g. QR / session / intent rule).
+   * - On-chain verification ALWAYS references `authorityRule`.
+   *
+   * Invariant:
+   * - Evaluation may use `authorityRule ∧ evaluationRule`
+   * - Proof MUST reference `authorityRule` only
+   *
+   * @param params
+   * @param params.context
+   *   Normalized rule execution context (tx, payId, etc.)
+   *
+   * @param params.authorityRule
+   *   The authoritative rule set owned by the receiver and
+   *   registered in the on-chain rule registry.
+   *   This rule defines on-chain sovereignty.
+   *
+   * @param params.evaluationRule
+   *   Optional evaluation override applied off-chain only
+   *   (e.g. QR rule, ephemeral constraint).
+   *   If omitted, `authorityRule` is used for evaluation.
+   *
+   * @param params.payId
+   *   PayID identifier associated with the receiver.
+   *
+   * @param params.payer
+   *   Address initiating the payment and signing the decision proof.
+   *
+   * @param params.receiver
+   *   Address receiving the payment and owning the authoritative rule.
+   *
+   * @param params.asset
+   *   Asset address to be transferred (address(0) for native ETH).
+   *
+   * @param params.amount
+   *   Amount to be transferred (uint256 semantics).
+   *
+   * @param params.signer
+   *   Signer corresponding to `payer`, used to sign the EIP-712
+   *   decision proof payload.
+   *
+   * @param params.ruleRegistryContract
+   *   Address of the on-chain rule registry / storage contract
+   *   used by the verifier to resolve `ruleSetHash`.
+   *
+   * @param params.ttlSeconds
+   *   Optional proof validity duration (seconds).
+   *   Defaults to implementation-defined TTL.
+   *
+   * @returns
+   *   An object containing:
+   *   - `result`: rule evaluation result (ALLOW / REJECT)
+   *   - `proof`: signed decision proof if allowed, otherwise `null`
+   *
+   * @throws
+   *   May throw if rule resolution, evaluation, or signing fails.
+   */
+  async evaluateAndProve(params) {
+    const authorityConfig = isRuleSource(params.authorityRule) ? (await resolveRule(params.authorityRule)).config : params.authorityRule;
+    const evalConfig = params.evaluationRule ?? authorityConfig;
+    const result = await evaluate(
+      this.wasm,
+      params.context,
+      evalConfig,
+      {
+        debug: this.debugTrace,
+        trustedIssuers: this.trustedIssuers
+      }
+    );
+    if (result.decision !== "ALLOW") {
+      return { result, proof: null };
+    }
+    const proof = await generateDecisionProof({
+      payId: params.payId,
+      payer: params.payer,
+      receiver: params.receiver,
+      asset: params.asset,
+      amount: params.amount,
+      context: params.context,
+      ruleConfig: authorityConfig,
+      signer: params.signer,
+      verifyingContract: params.verifyingContract,
+      ruleRegistryContract: params.ruleRegistryContract,
+      ttlSeconds: params.ttlSeconds
+    });
+    return { result, proof };
+  }
+  /**
+   * Build an ERC-4337 UserOperation that executes a PayID payment
+   * using a previously generated Decision Proof.
+   *
+   * ## Responsibility
+   *
+   * This function:
+   * - Encodes the PayID `pay(...)` calldata using the provided proof
+   * - Wraps it into an ERC-4337 UserOperation
+   *
+   * This function does NOT:
+   * - Evaluate rules
+   * - Generate decision proofs
+   * - Perform any signature validation
+   *
+   * ## Environment constraint
+   *
+   * This function is **server-only** and MUST NOT be called in a browser:
+   * - It is intended for bundlers, relayers, or backend services
+   * - Client-side apps should only generate the proof
+   *
+   * A runtime guard is enforced to prevent accidental browser usage.
+   *
+   * @param params
+   * @param params.proof
+   *   A valid Decision Proof generated by `evaluateAndProve`.
+   *
+   * @param params.smartAccount
+   *   The ERC-4337 smart account address that will submit the UserOperation.
+   *
+   * @param params.nonce
+   *   Current nonce of the smart account.
+   *
+   * @param params.gas
+   *   Gas parameters for the UserOperation
+   *   (callGasLimit, verificationGasLimit, preVerificationGas,
+   *    maxFeePerGas, maxPriorityFeePerGas).
+   *
+   * @param params.targetContract
+   *   Address of the PayID-compatible payment contract
+   *   (e.g. PayWithPayID).
+   *
+   * @param params.paymasterAndData
+   *   Optional paymaster data for sponsored transactions.
+   *
+   * @returns
+   *   A fully constructed ERC-4337 UserOperation ready to be
+   *   submitted to a bundler.
+   *
+   * @throws
+   *   Throws if called in a browser environment.
+   */
+  buildUserOperation(params) {
+    if (typeof globalThis !== "undefined" && "document" in globalThis) {
+      throw new Error(
+        "buildUserOperation must not be called in browser"
+      );
+    }
+    const callData = buildPayCallData(
+      params.targetContract,
+      params.proof
+    );
+    return buildUserOperation({
+      sender: params.smartAccount,
+      nonce: params.nonce,
+      callData,
+      gas: params.gas,
+      paymasterAndData: params.paymasterAndData
+    });
+  }
+};
+
+// src/factory.ts
+function createPayID(params) {
+  return new PayID(
+    params.wasm,
+    params.debugTrace ?? false,
+    params.trustedIssuers
+  );
+}
+export {
+  server_exports as client,
+  context_exports as context,
+  createPayID,
+  issuer_exports as issuer,
+  rule_exports as rule,
+  client_exports as server,
+  sessionPolicy_exports as sessionPolicy
+};

package/dist/issuer/index.d.ts

@@ -0,0 +1,3 @@
+export { a as issueEnvContext, b as issueOracleContext, c as issueRiskContext, d as issueStateContext, s as signAttestation } from '../index-2JCvey4-.js';
+import 'payid-types';
+import 'ethers';

package/dist/issuer/index.js

@@ -0,0 +1,16 @@
+import "../chunk-AOKLY2QN.js";
+import {
+  issueEnvContext,
+  issueOracleContext,
+  issueRiskContext,
+  issueStateContext,
+  signAttestation
+} from "../chunk-7U3P7XJE.js";
+import "../chunk-R5U7XKVJ.js";
+export {
+  issueEnvContext,
+  issueOracleContext,
+  issueRiskContext,
+  issueStateContext,
+  signAttestation
+};

package/dist/rule/index.d.ts

@@ -0,0 +1,2 @@
+export { a as canonicalizeRuleSet, c as combineRules, h as hashRuleSet } from '../index-C7vziL_Z.js';
+import 'payid-types';

package/dist/rule/index.js

@@ -0,0 +1,15 @@
+import {
+  hashRuleSet
+} from "../chunk-JRVCGSKK.js";
+import {
+  combineRules
+} from "../chunk-QYH3FNQ4.js";
+import {
+  canonicalizeRuleSet
+} from "../chunk-JJEWYFOV.js";
+import "../chunk-R5U7XKVJ.js";
+export {
+  canonicalizeRuleSet,
+  combineRules,
+  hashRuleSet
+};

package/dist/sessionPolicy/index.d.ts

@@ -0,0 +1,4 @@
+export { c as createSessionPolicyPayload, d as decodeSessionPolicy } from '../index-DuOeYzN2.js';
+export { P as PayIDSessionPolicyPayloadV1 } from '../types-DKt-zH0P.js';
+import 'ethers';
+import 'payid-types';

package/dist/sessionPolicy/index.js

@@ -0,0 +1,13 @@
+import {
+  createSessionPolicyPayload
+} from "../chunk-ATWJEWZH.js";
+import {
+  decodeSessionPolicy
+} from "../chunk-MXKZJKXE.js";
+import "../chunk-JJEWYFOV.js";
+import "../chunk-5ZEKI5Y2.js";
+import "../chunk-R5U7XKVJ.js";
+export {
+  createSessionPolicyPayload,
+  decodeSessionPolicy
+};

package/dist/types-B5dv7L-8.d.ts

@@ -0,0 +1,21 @@
+interface DecisionPayload {
+    version: string;
+    payId: string;
+    payer: string;
+    receiver: string;
+    asset: string;
+    amount: bigint;
+    contextHash: string;
+    ruleSetHash: string;
+    ruleAuthority: string;
+    issuedAt: bigint;
+    expiresAt: bigint;
+    nonce: string;
+    requiresAttestation: boolean;
+}
+interface DecisionProof {
+    payload: DecisionPayload;
+    signature: string;
+}
+
+export type { DecisionProof as D };

package/dist/types-DKt-zH0P.d.ts

@@ -0,0 +1,15 @@
+interface PayIDSessionPolicyPayloadV1 {
+    version: "payid.session.policy.v1" | string;
+    receiver: string;
+    rule: {
+        version: string;
+        logic: "AND" | "OR";
+        rules: any[];
+    };
+    expiresAt: number;
+    nonce: string;
+    issuedAt: number;
+    signature: string;
+}
+
+export type { PayIDSessionPolicyPayloadV1 as P };