payid 0.3.1 → 0.3.3

package/dist/chunk-XWOB3JVE.js

@@ -0,0 +1,78 @@
+import {
+  combineRules
+} from "./chunk-QYH3FNQ4.js";
+import {
+  decodeSessionPolicy
+} from "./chunk-MXKZJKXE.js";
+import {
+  evaluate,
+  generateDecisionProof,
+  resolveRule
+} from "./chunk-4MPVXPLM.js";
+import {
+  __export
+} from "./chunk-R5U7XKVJ.js";
+
+// src/core/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  createPayID: () => createPayID
+});
+
+// src/core/client/client.ts
+import "ethers";
+function isRuleSource(rule) {
+  return typeof rule === "object" && rule !== null && "uri" in rule;
+}
+var PayIDClient = class {
+  constructor(wasm, debugTrace) {
+    this.wasm = wasm;
+    this.debugTrace = debugTrace;
+  }
+  async evaluateAndProve(params) {
+    const authorityConfig = isRuleSource(params.authorityRule) ? (await resolveRule(params.authorityRule)).config : params.authorityRule;
+    const evalConfig = params.evaluationRule ?? (params.sessionPolicy ? combineRules(
+      params.authorityRule,
+      decodeSessionPolicy(
+        params.sessionPolicy,
+        Math.floor(Date.now() / 1e3)
+      ).rules
+    ) : params.authorityRule);
+    const result = await evaluate(
+      this.wasm,
+      params.context,
+      evalConfig,
+      { debug: this.debugTrace }
+    );
+    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 };
+  }
+};
+
+// src/core/client/index.ts
+function createPayID(params) {
+  return new PayIDClient(
+    params.wasm,
+    params.debugTrace ?? false
+  );
+}
+
+export {
+  createPayID,
+  client_exports
+};

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { b as buildContextV2 } from '../index-BEvnPzzt.js';
+import 'ethers';
+import 'payid-types';

package/dist/context/index.js

@@ -0,0 +1,8 @@
+import {
+  buildContextV2
+} from "../chunk-RCXMRX4F.js";
+import "../chunk-7U3P7XJE.js";
+import "../chunk-R5U7XKVJ.js";
+export {
+  buildContextV2
+};

package/dist/core/client/index.d.ts

@@ -0,0 +1,5 @@
+export { c as createPayID } from '../../index-BrD4MTYK.js';
+import 'payid-types';
+import 'ethers';
+import '../../types-B5dv7L-8.js';
+import '../../types-DKt-zH0P.js';

package/dist/core/client/index.js

@@ -0,0 +1,12 @@
+import {
+  createPayID
+} from "../../chunk-XWOB3JVE.js";
+import "../../chunk-QYH3FNQ4.js";
+import "../../chunk-MXKZJKXE.js";
+import "../../chunk-JJEWYFOV.js";
+import "../../chunk-4MPVXPLM.js";
+import "../../chunk-5ZEKI5Y2.js";
+import "../../chunk-R5U7XKVJ.js";
+export {
+  createPayID
+};

package/dist/core/server/index.d.ts

@@ -0,0 +1,4 @@
+export { c as createPayID } from '../../index-DY-T49uU.js';
+import 'ethers';
+import 'payid-types';
+import '../../types-B5dv7L-8.js';

package/dist/core/server/index.js

@@ -0,0 +1,9 @@
+import {
+  createPayID
+} from "../../chunk-FIMJNWJ3.js";
+import "../../chunk-4MPVXPLM.js";
+import "../../chunk-5ZEKI5Y2.js";
+import "../../chunk-R5U7XKVJ.js";
+export {
+  createPayID
+};

package/dist/index-2JCvey4-.d.ts

@@ -0,0 +1,23 @@
+import { EnvContext, OracleContext, RiskContext, StateContext, Attestation } from 'payid-types';
+import { Wallet } from 'ethers';
+
+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_issueEnvContext: typeof issueEnvContext;
+declare const index_issueOracleContext: typeof issueOracleContext;
+declare const index_issueRiskContext: typeof issueRiskContext;
+declare const index_issueStateContext: typeof issueStateContext;
+declare const index_signAttestation: typeof signAttestation;
+declare namespace index {
+  export { index_issueEnvContext as issueEnvContext, index_issueOracleContext as issueOracleContext, index_issueRiskContext as issueRiskContext, index_issueStateContext as issueStateContext, index_signAttestation as signAttestation };
+}
+
+export { issueEnvContext as a, issueOracleContext as b, issueRiskContext as c, issueStateContext as d, index as i, signAttestation as s };

package/dist/index-BEvnPzzt.d.ts

@@ -0,0 +1,160 @@
+import { Wallet } from 'ethers';
+import { ContextV1, ContextV2 } from 'payid-types';
+
+/**
+ * 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_buildContextV2: typeof buildContextV2;
+declare namespace index {
+  export { index_buildContextV2 as buildContextV2 };
+}
+
+export { buildContextV2 as b, index as i };

package/dist/index-BrD4MTYK.d.ts

@@ -0,0 +1,75 @@
+import { RuleContext, RuleConfig, RuleResult } from 'payid-types';
+import { ethers } from 'ethers';
+import { D as DecisionProof } from './types-B5dv7L-8.js';
+import { P as PayIDSessionPolicyPayloadV1 } from './types-DKt-zH0P.js';
+
+declare class PayIDClient {
+    private readonly wasm;
+    private readonly debugTrace?;
+    constructor(wasm: Uint8Array, debugTrace?: boolean | undefined);
+    evaluateAndProve(params: {
+        context: RuleContext;
+        authorityRule: RuleConfig;
+        evaluationRule?: RuleConfig;
+        sessionPolicy?: PayIDSessionPolicyPayloadV1;
+        payId: string;
+        payer: string;
+        receiver: string;
+        asset: string;
+        amount: bigint;
+        signer: ethers.Signer;
+        ruleRegistryContract: string;
+        verifyingContract: string;
+        ttlSeconds?: 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(params: {
+    wasm: Uint8Array;
+    debugTrace?: boolean;
+}): PayIDClient;
+
+declare const index_createPayID: typeof createPayID;
+declare namespace index {
+  export { index_createPayID as createPayID };
+}
+
+export { createPayID as c, index as i };

package/dist/index-C7vziL_Z.d.ts

@@ -0,0 +1,150 @@
+import { RuleConfig } from 'payid-types';
+
+/**
+ * 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: {
+        id: any;
+        if: any;
+    }[];
+};
+
+/**
+ * Canonicalize a rule set into a deterministic, order-independent form.
+ *
+ * Canonicalization ensures that semantically identical rule sets
+ * always produce the same structural representation, regardless of:
+ * - Rule insertion order
+ * - Object key order
+ * - Nested object layout
+ *
+ * This function is CRITICAL for:
+ * - Rule hashing (`ruleSetHash`)
+ * - Policy signing (QR / session / intent)
+ * - Consistent off-chain evaluation
+ *
+ * ## Canonicalization rules
+ *
+ * - Rules are normalized individually.
+ * - Rule entries are sorted lexicographically by `id`.
+ * - All nested objects are recursively sorted by key.
+ * - Arrays preserve their original order unless explicitly sorted.
+ *
+ * ## Security model
+ *
+ * - Canonicalization MUST be applied BEFORE hashing or signing.
+ * - Canonicalization MUST NOT be applied during verification
+ *   (the verified payload must match exactly what was signed).
+ *
+ * ## Invariants
+ *
+ * - Canonicalization does NOT change rule semantics.
+ * - Canonicalization does NOT weaken rule constraints.
+ * - Canonicalization is a pure, deterministic operation.
+ *
+ * @param ruleSet
+ *   A rule configuration object containing:
+ *   - `version`: rule schema version
+ *   - `logic`: logical operator ("AND" | "OR")
+ *   - `rules`: list of rule definitions
+ *
+ * @returns
+ *   A canonicalized rule configuration suitable for hashing,
+ *   signing, and deterministic evaluation.
+ */
+declare function canonicalizeRuleSet(ruleSet: {
+    version: string;
+    logic: "AND" | "OR";
+    rules: any[];
+}): {
+    version: string;
+    logic: "AND" | "OR";
+    rules: {
+        id: any;
+        if: any;
+    }[];
+};
+
+/**
+ * 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_canonicalizeRuleSet: typeof canonicalizeRuleSet;
+declare const index_combineRules: typeof combineRules;
+declare const index_hashRuleSet: typeof hashRuleSet;
+declare namespace index {
+  export { index_canonicalizeRuleSet as canonicalizeRuleSet, index_combineRules as combineRules, index_hashRuleSet as hashRuleSet };
+}
+
+export { canonicalizeRuleSet as a, combineRules as c, hashRuleSet as h, index as i };

package/dist/index-DY-T49uU.d.ts

@@ -0,0 +1,101 @@
+import { ethers } from 'ethers';
+import { RuleContext, RuleConfig, RuleResult } from 'payid-types';
+import { D as DecisionProof } from './types-B5dv7L-8.js';
+
+declare class PayIDServer {
+    private readonly wasm;
+    private readonly signer;
+    private readonly trustedIssuers?;
+    private readonly debugTrace?;
+    constructor(wasm: Uint8Array, signer: ethers.Signer, trustedIssuers?: Set<string> | undefined, debugTrace?: boolean | undefined);
+    evaluateAndProve(params: {
+        context: RuleContext;
+        authorityRule: RuleConfig;
+        evaluationRule?: RuleConfig;
+        payId: string;
+        payer: string;
+        receiver: string;
+        asset: string;
+        amount: bigint;
+        ruleRegistryContract: string;
+        verifyingContract: string;
+        ttlSeconds?: 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 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 { createPayID as c, index as i };