payid 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -1,16 +1,27 @@
-import { RuleContext, RuleConfig, RuleResult } from 'payid-types';
-import { R as RuleSource } from './types-B8pJQdMQ.js';
-import { U as UserOperation } from './index-C1DHMQA0.js';
-export { i as server } from './index-C1DHMQA0.js';
-import { ethers } from 'ethers';
-export { i as sessionPolicy } from './index-BQQnMG2H.js';
-export { i as rule } from './index-DerQdZmf.js';
-export { i as issuer } from './index-2JCvey4-.js';
-export { i as context } from './index-BEvnPzzt.js';
-export { i as client } from './index-2O3usHUn.js';
-import './types-BmMf7udp.js';
-
-interface PayIDClient {
+import * as payid_types from 'payid-types';
+import { RuleContext, RuleConfig, RuleResult, AnyRule, EnvContext, OracleContext, RiskContext, StateContext, Attestation, ContextV1, ContextV2 } from 'payid-types';
+import { ethers, Wallet } from 'ethers';
+
+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$1 {
     /**
      * Pure rule evaluation — client-safe, no signing
      */
@@ -37,7 +48,7 @@ interface PayIDClient {
         proof: any | null;
     }>;
 }
-interface PayIDServer {
+interface PayIDServer$1 {
     /**
      * Evaluate + generate proof dengan trusted issuers
      * Signer sudah di-inject saat construct PayIDServer
@@ -132,11 +143,411 @@ interface PayIDServer {
  *   const payid = new PayID(wasmBinary, debugTrace, trustedIssuers);
  *   ```
  */
-declare function createPayID(params: {
+declare function createPayID$2(params: {
     wasm?: Uint8Array;
     debugTrace?: boolean;
     trustedIssuers?: Set<string>;
-}): PayIDClient & PayIDServer;
+}): PayIDClient$1 & PayIDServer$1;
+
+interface PayIDSessionPolicyPayloadV1 {
+    version: "payid.session.policy.v1" | string;
+    receiver: string;
+    rule: RuleConfig;
+    expiresAt: number;
+    nonce: string;
+    issuedAt: number;
+    signature: string;
+}
+
+/**
+ * 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: RuleConfig;
+    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;
+
+type index$5_PayIDSessionPolicyPayloadV1 = PayIDSessionPolicyPayloadV1;
+declare const index$5_createSessionPolicyPayload: typeof createSessionPolicyPayload;
+declare const index$5_decodeSessionPolicy: typeof decodeSessionPolicy;
+declare namespace index$5 {
+  export { type index$5_PayIDSessionPolicyPayloadV1 as PayIDSessionPolicyPayloadV1, index$5_createSessionPolicyPayload as createSessionPolicyPayload, index$5_decodeSessionPolicy as decodeSessionPolicy };
+}
+
+/**
+ * Combine an authoritative rule set with additional ephemeral rules
+ * for off-chain evaluation.
+ *
+ * This helper merges:
+ * - A **default (authoritative) rule set** owned by the receiver
+ * - One or more **ephemeral rule constraints** (e.g. session / QR rules)
+ *
+ * The resulting rule set is intended **ONLY for off-chain evaluation**
+ * and MUST NOT be used as an authoritative rule on-chain.
+ *
+ * ## Security model
+ *
+ * - The default rule set defines sovereignty and ownership.
+ * - Ephemeral rules can only further restrict behavior
+ *   (logical AND composition).
+ * - Ephemeral rules MUST NOT bypass or weaken default rules.
+ *
+ * ## Canonicalization
+ *
+ * - The combined rule set is canonicalized to ensure deterministic
+ *   hashing and evaluation behavior.
+ *
+ * ## Invariants
+ *
+ * - The resulting rule set always uses logical AND semantics.
+ * - Rule order is normalized via canonicalization.
+ *
+ * @param defaultRuleSet
+ *   The authoritative rule configuration (on-chain registered).
+ *
+ * @param sessionRule
+ *   A list of additional rule conditions derived from an ephemeral
+ *   policy (session, QR, intent, etc.).
+ *
+ * @returns
+ *   A canonicalized rule configuration suitable for off-chain
+ *   evaluation.
+ */
+declare function combineRules(defaultRuleSet: RuleConfig, sessionRule: any[]): {
+    version: string;
+    logic: "AND" | "OR";
+    rules: payid_types.AnyRule[];
+};
+
+/**
+ * Canonicalize a rule set into a deterministic, order-independent form.
+ *
+ * Supports all three v4 rule formats:
+ *   - Format A: { id, if, message? }
+ *   - Format B: { id, logic, conditions[], message? }
+ *   - Format C: { id, logic, rules[], message? }
+ */
+declare function canonicalizeRuleSet(ruleSet: {
+    version?: string;
+    logic: "AND" | "OR";
+    rules: any[];
+}): {
+    version: string;
+    logic: "AND" | "OR";
+    rules: AnyRule[];
+};
+
+/**
+ * Compute a deterministic hash of a canonicalized rule set.
+ *
+ * This function produces the `ruleSetHash` used to:
+ * - Reference authoritative rules in on-chain registries
+ * - Bind decision proofs to a specific rule configuration
+ * - Ensure integrity between off-chain evaluation and on-chain verification
+ *
+ * ## Canonicalization requirement
+ *
+ * - The input rule set MUST already be canonicalized using
+ *   `canonicalizeRuleSet`.
+ * - Hashing a non-canonical rule set may result in inconsistent
+ *   hashes for semantically identical rules.
+ *
+ * ## Security model
+ *
+ * - The hash represents the exact structure of the rule set at the
+ *   time of hashing.
+ * - Any mutation (key order, rule order, value change) will produce
+ *   a different hash.
+ *
+ * ## Invariants
+ *
+ * - This function does NOT perform canonicalization.
+ * - This function is pure and deterministic.
+ * - The same canonical rule set will always yield the same hash.
+ *
+ * @param ruleSet
+ *   A canonicalized rule configuration object.
+ *
+ * @returns
+ *   A `bytes32` hex string (keccak256) uniquely identifying the rule set.
+ */
+declare function hashRuleSet(ruleSet: any): string;
+
+declare const index$4_canonicalizeRuleSet: typeof canonicalizeRuleSet;
+declare const index$4_combineRules: typeof combineRules;
+declare const index$4_hashRuleSet: typeof hashRuleSet;
+declare namespace index$4 {
+  export { index$4_canonicalizeRuleSet as canonicalizeRuleSet, index$4_combineRules as combineRules, index$4_hashRuleSet as hashRuleSet };
+}
+
+declare function issueEnvContext(wallet: Wallet): Promise<EnvContext>;
+
+declare function issueOracleContext(wallet: Wallet, data: Record<string, string | number>): Promise<OracleContext>;
+
+declare function issueRiskContext(wallet: Wallet, score: number, category: string, modelHash: string): Promise<RiskContext>;
+
+declare function issueStateContext(wallet: Wallet, spentToday: string, period: string): Promise<StateContext>;
+
+declare function signAttestation(issuerWallet: Wallet, payload: object, ttlSeconds?: number): Promise<Attestation>;
+
+declare const index$3_issueEnvContext: typeof issueEnvContext;
+declare const index$3_issueOracleContext: typeof issueOracleContext;
+declare const index$3_issueRiskContext: typeof issueRiskContext;
+declare const index$3_issueStateContext: typeof issueStateContext;
+declare const index$3_signAttestation: typeof signAttestation;
+declare namespace index$3 {
+  export { index$3_issueEnvContext as issueEnvContext, index$3_issueOracleContext as issueOracleContext, index$3_issueRiskContext as issueRiskContext, index$3_issueStateContext as issueStateContext, index$3_signAttestation as signAttestation };
+}
+
+/**
+ * Build an attested Context V2 object from a base execution context
+ * and a set of optional attestation issuers.
+ *
+ * ## Purpose
+ *
+ * This function assembles **Context V2**, which extends a raw
+ * execution context (Context V1) with **cryptographically attested
+ * facts** such as:
+ * - Environment data (time, runtime conditions)
+ * - Stateful data (daily spend, quotas)
+ * - Oracle data (country, FX rate, KYC attributes)
+ * - Risk signals (ML score, risk category)
+ *
+ * The resulting context is suitable for:
+ * - Deterministic rule evaluation
+ * - Context V2 verification via `preprocessContextV2`
+ * - Off-chain decision proof generation
+ * - On-chain attestation verification
+ *
+ * ## Trust model
+ *
+ * - Each context domain (`env`, `state`, `oracle`, `risk`) MUST be
+ *   issued and signed by a trusted issuer.
+ * - The rule engine does NOT trust raw values; it only trusts
+ *   verified attestations.
+ * - Which domains are required is determined by `ruleConfig.requires`.
+ *
+ * ## Responsibility
+ *
+ * This function:
+ * - Calls the appropriate issuer functions to generate attestations
+ * - Aggregates all issued contexts into a single Context V2 object
+ * - Does NOT evaluate rules
+ * - Does NOT perform attestation verification
+ *
+ * ## Environment
+ *
+ * This function may be called from:
+ * - Backend services
+ * - Relayers / bundlers
+ * - Edge runtimes
+ *
+ * It SHOULD NOT be called directly from untrusted clients unless
+ * issuer keys are properly secured.
+ *
+ * @example
+ * ### Minimal Context V2 (env + state only)
+ *
+ * ```ts
+ * const contextV2 = await buildContextV2({
+ *   baseContext: {
+ *     tx,
+ *     payId
+ *   },
+ *   env: {
+ *     issuer: envIssuer
+ *   },
+ *   state: {
+ *     issuer: stateIssuer,
+ *     spentToday: "2500000",
+ *     period: "DAY"
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ### Full Context V2 (env + state + oracle + risk)
+ *
+ * ```ts
+ * const contextV2 = await buildContextV2({
+ *   baseContext: {
+ *     tx,
+ *     payId
+ *   },
+ *   env: {
+ *     issuer: envIssuer
+ *   },
+ *   state: {
+ *     issuer: stateIssuer,
+ *     spentToday: "2500000",
+ *     period: "DAY"
+ *   },
+ *   oracle: {
+ *     issuer: oracleIssuer,
+ *     data: {
+ *       country: "ID",
+ *       fxRate: 15600
+ *     }
+ *   },
+ *   risk: {
+ *     issuer: riskIssuer,
+ *     score: 72,
+ *     category: "MEDIUM",
+ *     modelHash: "0xmodelhash123"
+ *   }
+ * });
+ * ```
+ *
+ * @param params
+ *   Context assembly parameters.
+ *
+ * @param params.baseContext
+ *   Base execution context (Context V1), containing transaction
+ *   and PayID-related fields.
+ *
+ * @param params.env
+ *   Optional environment attestation.
+ *   Typically used for time-based or runtime constraints.
+ *
+ * @param params.state
+ *   Optional state attestation.
+ *   Used for cumulative values such as daily spend or quota tracking.
+ *
+ * @param params.oracle
+ *   Optional oracle attestation.
+ *   Used for external facts such as country, FX rate, or KYC signals.
+ *
+ * @param params.risk
+ *   Optional risk attestation.
+ *   Used for ML-based risk scoring and categorization.
+ *
+ * @returns
+ *   A fully assembled Context V2 object containing the base context
+ *   and all requested attested sub-contexts.
+ *
+ * @throws
+ *   May throw if attestation issuance fails for any domain.
+ */
+declare function buildContextV2(params: {
+    baseContext: ContextV1;
+    env?: {
+        issuer: Wallet;
+    };
+    state?: {
+        issuer: Wallet;
+        spentToday: string;
+        period: string;
+    };
+    oracle?: {
+        issuer: Wallet;
+        data: Record<string, string | number>;
+    };
+    risk?: {
+        issuer: Wallet;
+        score: number;
+        category: string;
+        modelHash: string;
+    };
+}): Promise<ContextV2>;
+
+declare const index$2_buildContextV2: typeof buildContextV2;
+declare namespace index$2 {
+  export { index$2_buildContextV2 as buildContextV2 };
+}
 
 /**
  * @module eas
@@ -203,4 +614,261 @@ declare namespace eas {
   export { type eas_EASAttestation as EASAttestation, eas_EASClient as EASClient, type eas_EASClientOptions as EASClientOptions, eas_EAS_ADDRESSES as EAS_ADDRESSES };
 }
 
-export { type PayIDClient, type PayIDServer, createPayID, eas };
+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;
+}
+
+/**
+ * @class PayIDClient
+ * @description Client-side PayID engine.
+ *
+ * Fully serverless — aman dipakai di browser, mobile, edge.
+ * Tidak butuh issuer wallet, tidak butuh server.
+ *
+ * Untuk attestation, gunakan EAS UIDs yang di-fetch via `eas.EASClient`.
+ *
+ * @example
+ * ```ts
+ * const client = new PayIDClient(wasmBinary)
+ *
+ * // 1. Evaluate rule
+ * const result = await client.evaluate(context, ruleConfig)
+ *
+ * // 2. Evaluate + generate proof (payer sign sendiri)
+ * const { result, proof } = await client.evaluateAndProve({
+ *   context,
+ *   authorityRule: ruleConfig,
+ *   payId: "pay.id/merchant",
+ *   payer: await signer.getAddress(),
+ *   receiver: "0xRECEIVER",
+ *   asset: USDT_ADDRESS,
+ *   amount: parseUnits("100", 6),
+ *   signer,
+ *   verifyingContract: PAYID_VERIFIER_ADDRESS,
+ *   ruleAuthority: RULE_AUTHORITY_ADDRESS,
+ * })
+ * ```
+ */
+declare class PayIDClient {
+    private readonly debugTrace?;
+    private readonly wasm?;
+    constructor(debugTrace?: boolean | undefined, wasm?: Uint8Array | undefined);
+    evaluate(context: RuleContext, rule: RuleConfig | RuleSource): Promise<RuleResult>;
+    evaluateAndProve(params: {
+        context: RuleContext;
+        authorityRule: RuleConfig | RuleSource;
+        evaluationRule?: RuleConfig;
+        sessionPolicy?: PayIDSessionPolicyPayloadV1;
+        payId: string;
+        payer: string;
+        receiver: string;
+        asset: string;
+        amount: bigint;
+        signer: ethers.Signer;
+        verifyingContract: string;
+        ruleAuthority: string;
+        ttlSeconds?: number;
+        chainId: number;
+        blockTimestamp: number;
+    }): Promise<{
+        result: RuleResult;
+        proof: DecisionProof | null;
+    }>;
+}
+
+/**
+ * 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.
+ *   @example
+ *   ```ts
+ *
+ *   const payid = new PayID(wasmBinary, debugTrace);
+ *   ```
+ */
+declare function createPayID$1(params: {
+    wasm?: Uint8Array;
+    debugTrace?: boolean;
+}): PayIDClient;
+
+declare namespace index$1 {
+  export { createPayID$1 as createPayID };
+}
+
+/**
+ * @class PayIDServer
+ * @description Server-side PayID engine.
+ *
+ * Digunakan ketika butuh:
+ * - Context V2 (env, state, oracle, risk) dengan trusted issuers
+ * - Build ERC-4337 UserOperation untuk bundler
+ *
+ * Signer di-inject saat construct — jangan pakai ini di browser.
+ *
+ * @example
+ * ```ts
+ * // Server/bundler side
+ * const server = new PayIDServer(wasmBinary, serverSigner, trustedIssuers)
+ *
+ * const { result, proof } = await server.evaluateAndProve({
+ *   context: contextV2,    // ← Context V2 dengan attestations
+ *   authorityRule,
+ *   payId: "pay.id/merchant",
+ *   payer: "0xPAYER",
+ *   receiver: "0xRECEIVER",
+ *   asset: USDT_ADDRESS,
+ *   amount: parseUnits("100", 6),
+ *   verifyingContract: PAYID_VERIFIER_ADDRESS,
+ *   ruleAuthority: RULE_AUTHORITY_ADDRESS,
+ * })
+ * ```
+ */
+declare class PayIDServer {
+    private readonly signer;
+    private readonly trustedIssuers?;
+    private readonly debugTrace?;
+    private readonly wasm?;
+    constructor(signer: ethers.Signer, trustedIssuers?: Set<string> | undefined, debugTrace?: boolean | undefined, wasm?: Uint8Array | undefined);
+    evaluateAndProve(params: {
+        context: RuleContext;
+        authorityRule: RuleConfig | RuleSource;
+        evaluationRule?: RuleConfig;
+        payId: string;
+        payer: string;
+        receiver: string;
+        asset: string;
+        amount: bigint;
+        verifyingContract: string;
+        ruleAuthority: string;
+        ttlSeconds?: number;
+        chainId: number;
+        blockTimestamp: number;
+    }): Promise<{
+        result: RuleResult;
+        proof: DecisionProof | null;
+    }>;
+    buildUserOperation(params: {
+        proof: DecisionProof;
+        smartAccount: string;
+        nonce: string;
+        gas: any;
+        targetContract: string;
+        paymasterAndData?: string;
+        attestationUIDs?: 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 signer
+ *   Signer account
+ *
+ * @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, ethers.Signer,  debugTrace, trustedIssuers);
+ *   ```
+ */
+declare function createPayID(params: {
+    wasm?: Uint8Array;
+    signer: ethers.Signer;
+    debugTrace?: boolean;
+    trustedIssuers?: Set<string>;
+}): PayIDServer;
+
+declare const index_createPayID: typeof createPayID;
+declare namespace index {
+  export { index_createPayID as createPayID };
+}
+
+export { type PayIDClient$1 as PayIDClient, type PayIDServer$1 as PayIDServer, index$1 as client, index$2 as context, createPayID$2 as createPayID, eas, index$3 as issuer, index$4 as rule, index as server, index$5 as sessionPolicy };