@opendatalabs/vana-sdk 3.13.4-pr.186.afb5a4f → 3.14.0

package/dist/direct/controller.js

@@ -10,7 +10,11 @@ import {
   getDirectEndpoints,
   getDirectNetworkChainId
 } from "./endpoints.js";
-import { AccessNotApprovedError, DirectConfigError } from "./errors.js";
+import {
+  AccessNotApprovedError,
+  DirectConfigError,
+  ScopeNotApprovedError
+} from "./errors.js";
 import {
   readPersonalServerData
 } from "./personal-server-read.js";
@@ -93,42 +97,82 @@ function createDirectDataController(config) {
       return accessRequestClient.getAccessRequestStatus(requestId);
     },
     async readApprovedData(input) {
-      const status = await accessRequestClient.getAccessRequestStatus(
-        input.requestId
-      );
-      if (!isReadReadyStatus(status.status) || !status.personalServerUrl || !status.grantId || !status.scope) {
-        throw new AccessNotApprovedError(
-          "Request is not approved or is missing grantId/scope/personalServerUrl",
-          {
-            requestId: input.requestId,
-            status: status.status,
-            hasPersonalServerUrl: Boolean(status.personalServerUrl),
-            hasGrantId: Boolean(status.grantId),
-            hasScope: Boolean(status.scope)
-          }
-        );
+      const status = await requireReadReady(input.requestId);
+      const scope = resolveRequestedScope(status, input.scope);
+      const result = await readScope(status, scope);
+      if (input.acknowledge !== false) {
+        await acknowledgeQuietly(input.requestId);
       }
-      const result = await readPersonalServerData({
-        personalServerUrl: status.personalServerUrl,
-        scope: status.scope,
-        grantId: status.grantId,
-        payerAddress: account.address,
-        signMessage,
-        escrow,
-        fetchFn: config.personalServerFetch,
-        transportRetry: config.personalServerTransportRetry
-      });
-      try {
-        await accessRequestClient.acknowledgeRead?.(input.requestId);
-      } catch {
+      return result;
+    },
+    async readAllApprovedData(input) {
+      const status = await requireReadReady(input.requestId);
+      const scopes = approvedScopes(status);
+      const results = {};
+      const errors = {};
+      for (const scope of scopes) {
+        try {
+          results[scope] = await readScope(status, scope);
+        } catch (error) {
+          errors[scope] = error instanceof Error ? error : new Error(String(error));
+        }
       }
-      return {
-        scope: status.scope,
-        data: result.data,
-        payment: result.payment
-      };
+      if (Object.keys(errors).length === 0) {
+        await acknowledgeQuietly(input.requestId);
+      }
+      return { results, errors };
     }
   };
+  async function requireReadReady(requestId) {
+    const status = await accessRequestClient.getAccessRequestStatus(requestId);
+    if (!isReadReadyStatus(status.status) || !status.personalServerUrl || !status.grantId || approvedScopes(status).length === 0) {
+      throw new AccessNotApprovedError(
+        "Request is not approved or is missing grantId/scope/personalServerUrl",
+        {
+          requestId,
+          status: status.status,
+          hasPersonalServerUrl: Boolean(status.personalServerUrl),
+          hasGrantId: Boolean(status.grantId),
+          hasScope: approvedScopes(status).length > 0
+        }
+      );
+    }
+    return status;
+  }
+  function approvedScopes(status) {
+    if (status.scopes && status.scopes.length > 0) return status.scopes;
+    return status.scope ? [status.scope] : [];
+  }
+  function resolveRequestedScope(status, requested) {
+    const scopes = approvedScopes(status);
+    if (requested === void 0) return scopes[0];
+    if (!scopes.includes(requested)) {
+      throw new ScopeNotApprovedError(
+        `Scope "${requested}" is not approved on this request`,
+        { requestedScope: requested, approvedScopes: scopes }
+      );
+    }
+    return requested;
+  }
+  async function readScope(status, scope) {
+    const result = await readPersonalServerData({
+      personalServerUrl: status.personalServerUrl,
+      scope,
+      grantId: status.grantId,
+      payerAddress: account.address,
+      signMessage,
+      escrow,
+      fetchFn: config.personalServerFetch,
+      transportRetry: config.personalServerTransportRetry
+    });
+    return { scope, data: result.data, payment: result.payment };
+  }
+  async function acknowledgeQuietly(requestId) {
+    try {
+      await accessRequestClient.acknowledgeRead?.(requestId);
+    } catch {
+    }
+  }
 }
 export {
   createDirectDataController

package/dist/direct/controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/controller.ts"],"sourcesContent":["/**\n * Direct Data Controller — the server-side facade for the two-tab Data\n * Portability flow.\n *\n * @remarks\n * One controller owns an app's private key, source, scopes, app identity, and\n * payment flow. It exposes the three methods the builder guide documents:\n *\n * - {@link DirectDataController.createAccessRequest} — start an approval request.\n * - {@link DirectDataController.getAccessRequestStatus} — poll while the Vana tab is open.\n * - {@link DirectDataController.readApprovedData} — read from the Personal Server,\n *   handling 402 Payment Required.\n *\n * Access requests are created through the Vana Account access-request API; the\n * Personal Server read uses Web3Signed auth; and payment uses the DPv2 escrow\n * surface (`protocol/escrow`) — when a read returns `402`, the controller signs\n * a `GenericPayment` with the app key, settles it through the escrow gateway,\n * and retries.\n *\n * @category Direct\n * @module direct/controller\n */\n\nimport { privateKeyToAccount } from \"viem/accounts\";\nimport type { Hex } from \"viem\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport { parseScope } from \"../protocol/scopes\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport { AccessNotApprovedError, DirectConfigError } from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n} from \"./types\";\n\n/** Configuration for {@link createDirectDataController}. */\nexport interface DirectDataControllerConfig {\n  /** Target environment. Defaults to `\"production\"`. */\n  env?: DirectEnv;\n  /**\n   * Target Vana network for chain-aware defaults. Defaults to the selected\n   * environment's historical network (`mainnet` for production, `moksha` for\n   * dev). Use `network: \"moksha\"` with the default production env for\n   * production app/API URLs on testnet.\n   */\n  network?: DirectNetwork;\n  /**\n   * The app private key (`0x`-prefixed, 32 bytes). Server-side only — this key\n   * is the app's on-chain identity and is never exposed to the browser.\n   */\n  appPrivateKey?: string;\n  /**\n   * @deprecated Use {@link DirectDataControllerConfig.appPrivateKey}. Accepted as\n   * a backwards-compatible alias; if both are set, `appPrivateKey` wins.\n   */\n  builderPrivateKey?: string;\n  /** App identity advertised during approval. */\n  app: DirectAppConfig;\n  /** Data source key (e.g. `\"icloud_notes\"`). */\n  source: string;\n  /** Scopes to request (e.g. `[\"icloud_notes.notes\"]`). At least one required. */\n  scopes: string[];\n  /**\n   * Override the resolved service endpoints (partial). Useful for pointing at a\n   * non-standard deployment.\n   */\n  endpoints?: Partial<DirectServiceEndpoints>;\n  /**\n   * Client for the Vana Account access-request API. Defaults to a client against\n   * the resolved Vana Account endpoints; inject your own to point at a custom\n   * deployment or to supply a test double.\n   */\n  accessRequestClient?: AccessRequestClient;\n  /**\n   * Escrow settlement config used when a Personal Server read returns `402`.\n   *\n   * @remarks\n   * Wires the DPv2 escrow gateway (`protocol/escrow`). The controller supplies\n   * the EIP-712 `signTypedData` from the app key automatically.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<DirectEscrowConfig>;\n  /** `fetch` used by the default access-request client. Defaults to `globalThis.fetch`. */\n  fetchFn?: FetchLike;\n  /** `fetch` used for the Personal Server read. Defaults to `globalThis.fetch`. */\n  personalServerFetch?: PersonalServerFetch;\n  /**\n   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\n}\n\n/**\n * Controller-level escrow config — the {@link EscrowPaymentConfig} minus the\n * `signTypedData` and `chainId` the controller injects itself.\n */\nexport interface DirectEscrowConfig extends Omit<\n  EscrowPaymentConfig,\n  \"signTypedData\" | \"chainId\"\n> {\n  /**\n   * Chain id for the EIP-712 domain. Defaults to the controller's environment\n   * (1480 for mainnet, 14800 for moksha).\n   */\n  chainId?: number;\n}\n\n/**\n * Server-side controller for the direct Data Portability flow.\n *\n * @typeParam T - Shape of the data returned by {@link DirectDataController.readApprovedData}.\n */\nexport interface DirectDataController {\n  /** The on-chain address of the app, derived from `appPrivateKey`. */\n  readonly appAddress: string;\n\n  /**\n   * The app's on-chain address — the address to fund and inspect in the Builder\n   * activity report. Equivalent to {@link DirectDataController.appAddress}.\n   *\n   * @returns The app's `0x`-prefixed address.\n   */\n  getAppAddress(): string;\n\n  /**\n   * The app's full identity: its configured id/name/homepage plus the derived\n   * on-chain address. Useful for telling builders which app address to fund or\n   * look up.\n   *\n   * @returns `{ id, name, homepageUrl, address }`.\n   */\n  getAppIdentity(): AppIdentity;\n\n  /**\n   * Create an access request the user can approve.\n   *\n   * @param input - The post-approval return URL.\n   * @returns `{ requestId, approvalUrl, appAddress }`.\n   */\n  createAccessRequest(input: { returnUrl: string }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of an access request.\n   *\n   * @param requestId - The `dcr_*` id from {@link DirectDataController.createAccessRequest}.\n   * @returns `{ status, personalServerUrl?, grantId?, scope? }`.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n\n  /**\n   * Read the approved data from the user's Personal Server.\n   *\n   * @remarks\n   * Resolves the request to its grant + Personal Server and performs a Web3Signed\n   * read. Hides the `402 Payment Required` flow by default: if a read needs\n   * payment, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<ApprovedDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\n}\n\n/**\n * Create a {@link DirectDataController}.\n *\n * @param config - Controller configuration (env, key, app identity, source, scopes).\n * @returns A ready-to-use controller.\n * @throws {@link DirectConfigError} when the key or scopes are invalid.\n */\nexport function createDirectDataController(\n  config: DirectDataControllerConfig,\n): DirectDataController {\n  // `appPrivateKey` is the documented field; `builderPrivateKey` is a\n  // deprecated alias kept for backwards compatibility.\n  const privateKey = config.appPrivateKey ?? config.builderPrivateKey;\n  if (!privateKey || !isHexPrivateKey(privateKey)) {\n    throw new DirectConfigError(\n      \"appPrivateKey must be a 0x-prefixed 32-byte hex string\",\n    );\n  }\n  if (!config.scopes || config.scopes.length === 0) {\n    throw new DirectConfigError(\"At least one scope is required\");\n  }\n  // Validate scopes eagerly so misconfiguration fails at construction.\n  for (const scope of config.scopes) {\n    parseScope(scope);\n  }\n\n  const env: DirectEnv = config.env ?? \"production\";\n  const network: DirectNetwork = config.network ?? getDirectDefaultNetwork(env);\n  const defaultEndpoints = getDirectEndpoints(env);\n  const chainId = config.endpoints?.chainId ?? getDirectNetworkChainId(network);\n  const endpoints: DirectServiceEndpoints = {\n    ...defaultEndpoints,\n    ...config.endpoints,\n    chainId,\n  };\n\n  const account = privateKeyToAccount(privateKey as Hex);\n  const signMessage: Web3SignedSignFn = (message: string) =>\n    account.signMessage({ message });\n  // viem's account.signTypedData satisfies the structural SignTypedDataFn used\n  // by the escrow GenericPayment signer.\n  const signTypedData = account.signTypedData as unknown as SignTypedDataFn;\n  const accessRequestClient: AccessRequestClient =\n    config.accessRequestClient ??\n    createDefaultAccessRequestClient({\n      baseUrl: endpoints.accessRequestBaseUrl,\n      approvalBaseUrl: endpoints.approvalAppBaseUrl,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\n\n  return {\n    appAddress: account.address,\n\n    getAppAddress(): string {\n      return account.address;\n    },\n\n    getAppIdentity(): AppIdentity {\n      return {\n        id: config.app.id,\n        name: config.app.name,\n        homepageUrl: config.app.homepageUrl,\n        address: account.address,\n      };\n    },\n\n    async createAccessRequest(input): Promise<AccessRequest> {\n      return accessRequestClient.createAccessRequest({\n        appAddress: account.address,\n        app: config.app,\n        source: config.source,\n        scopes: config.scopes,\n        returnUrl: input.returnUrl,\n        network,\n      });\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      return accessRequestClient.getAccessRequestStatus(requestId);\n    },\n\n    async readApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await accessRequestClient.getAccessRequestStatus(\n        input.requestId,\n      );\n      if (\n        !isReadReadyStatus(status.status) ||\n        !status.personalServerUrl ||\n        !status.grantId ||\n        !status.scope\n      ) {\n        throw new AccessNotApprovedError(\n          \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n          {\n            requestId: input.requestId,\n            status: status.status,\n            hasPersonalServerUrl: Boolean(status.personalServerUrl),\n            hasGrantId: Boolean(status.grantId),\n            hasScope: Boolean(status.scope),\n          },\n        );\n      }\n\n      const result = await readPersonalServerData({\n        personalServerUrl: status.personalServerUrl,\n        scope: status.scope,\n        grantId: status.grantId,\n        payerAddress: account.address,\n        signMessage,\n        escrow,\n        fetchFn: config.personalServerFetch,\n        transportRetry: config.personalServerTransportRetry,\n      });\n      try {\n        await accessRequestClient.acknowledgeRead?.(input.requestId);\n      } catch {\n        // The read already succeeded; ack only drives Vana Web completion UX.\n      }\n\n      return {\n        scope: status.scope,\n        data: result.data as T,\n        payment: result.payment,\n      };\n    },\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/direct/controller.ts"],"sourcesContent":["/**\n * Direct Data Controller — the server-side facade for the two-tab Data\n * Portability flow.\n *\n * @remarks\n * One controller owns an app's private key, source, scopes, app identity, and\n * payment flow. It exposes the three methods the builder guide documents:\n *\n * - {@link DirectDataController.createAccessRequest} — start an approval request.\n * - {@link DirectDataController.getAccessRequestStatus} — poll while the Vana tab is open.\n * - {@link DirectDataController.readApprovedData} — read from the Personal Server,\n *   handling 402 Payment Required.\n *\n * Access requests are created through the Vana Account access-request API; the\n * Personal Server read uses Web3Signed auth; and payment uses the DPv2 escrow\n * surface (`protocol/escrow`) — when a read returns `402`, the controller signs\n * a `GenericPayment` with the app key, settles it through the escrow gateway,\n * and retries.\n *\n * @category Direct\n * @module direct/controller\n */\n\nimport { privateKeyToAccount } from \"viem/accounts\";\nimport type { Hex } from \"viem\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport { parseScope } from \"../protocol/scopes\";\nimport { createEscrowGatewayClient } from \"../protocol/escrow\";\nimport { CONTRACTS } from \"../generated/addresses\";\nimport {\n  createDefaultAccessRequestClient,\n  type FetchLike,\n} from \"./access-request-client\";\nimport {\n  getDirectDefaultNetwork,\n  getDirectEndpoints,\n  getDirectNetworkChainId,\n} from \"./endpoints\";\nimport {\n  AccessNotApprovedError,\n  DirectConfigError,\n  ScopeNotApprovedError,\n} from \"./errors\";\nimport {\n  type EscrowPaymentConfig,\n  type SignTypedDataFn,\n} from \"./escrow-payment\";\nimport {\n  readPersonalServerData,\n  type PersonalServerFetch,\n  type PersonalServerTransportRetryOptions,\n} from \"./personal-server-read\";\nimport type {\n  AccessRequest,\n  AccessRequestClient,\n  AccessRequestStatus,\n  AccessRequestStatusValue,\n  ApprovedDataResult,\n  AppIdentity,\n  DirectAppConfig,\n  DirectEnv,\n  DirectNetwork,\n  DirectPaymentResponseMetadata,\n  DirectServiceEndpoints,\n  MultiScopeDataResult,\n} from \"./types\";\n\n/** Configuration for {@link createDirectDataController}. */\nexport interface DirectDataControllerConfig {\n  /** Target environment. Defaults to `\"production\"`. */\n  env?: DirectEnv;\n  /**\n   * Target Vana network for chain-aware defaults. Defaults to the selected\n   * environment's historical network (`mainnet` for production, `moksha` for\n   * dev). Use `network: \"moksha\"` with the default production env for\n   * production app/API URLs on testnet.\n   */\n  network?: DirectNetwork;\n  /**\n   * The app private key (`0x`-prefixed, 32 bytes). Server-side only — this key\n   * is the app's on-chain identity and is never exposed to the browser.\n   */\n  appPrivateKey?: string;\n  /**\n   * @deprecated Use {@link DirectDataControllerConfig.appPrivateKey}. Accepted as\n   * a backwards-compatible alias; if both are set, `appPrivateKey` wins.\n   */\n  builderPrivateKey?: string;\n  /** App identity advertised during approval. */\n  app: DirectAppConfig;\n  /** Data source key (e.g. `\"icloud_notes\"`). */\n  source: string;\n  /** Scopes to request (e.g. `[\"icloud_notes.notes\"]`). At least one required. */\n  scopes: string[];\n  /**\n   * Override the resolved service endpoints (partial). Useful for pointing at a\n   * non-standard deployment.\n   */\n  endpoints?: Partial<DirectServiceEndpoints>;\n  /**\n   * Client for the Vana Account access-request API. Defaults to a client against\n   * the resolved Vana Account endpoints; inject your own to point at a custom\n   * deployment or to supply a test double.\n   */\n  accessRequestClient?: AccessRequestClient;\n  /**\n   * Escrow settlement config used when a Personal Server read returns `402`.\n   *\n   * @remarks\n   * Wires the DPv2 escrow gateway (`protocol/escrow`). The controller supplies\n   * the EIP-712 `signTypedData` from the app key automatically.\n   *\n   * When omitted (or partially omitted), the SDK derives defaults from the\n   * per-network endpoints table and the contract registry:\n   * - `client` defaults to a gateway client at `endpoints.escrowGatewayUrl`\n   * - `escrowContract` defaults to `CONTRACTS.DataPortabilityEscrow.addresses[chainId]`\n   * - `chainId` defaults to the controller's resolved chain id\n   *\n   * Provide this field only to override a specific default.\n   */\n  escrow?: Partial<DirectEscrowConfig>;\n  /** `fetch` used by the default access-request client. Defaults to `globalThis.fetch`. */\n  fetchFn?: FetchLike;\n  /** `fetch` used for the Personal Server read. Defaults to `globalThis.fetch`. */\n  personalServerFetch?: PersonalServerFetch;\n  /**\n   * Transport-retry knobs for the Personal Server read\n   * ({@link PersonalServerTransportRetryOptions}). Defaults to 3 attempts with\n   * exponential backoff. Retries fire only when fetch throws (the browser-PS\n   * relay reconnect window), never on a received HTTP status, and never\n   * re-sign a payment.\n   */\n  personalServerTransportRetry?: PersonalServerTransportRetryOptions;\n}\n\n/**\n * Controller-level escrow config — the {@link EscrowPaymentConfig} minus the\n * `signTypedData` and `chainId` the controller injects itself.\n */\nexport interface DirectEscrowConfig extends Omit<\n  EscrowPaymentConfig,\n  \"signTypedData\" | \"chainId\"\n> {\n  /**\n   * Chain id for the EIP-712 domain. Defaults to the controller's environment\n   * (1480 for mainnet, 14800 for moksha).\n   */\n  chainId?: number;\n}\n\n/**\n * Server-side controller for the direct Data Portability flow.\n *\n * @typeParam T - Shape of the data returned by {@link DirectDataController.readApprovedData}.\n */\nexport interface DirectDataController {\n  /** The on-chain address of the app, derived from `appPrivateKey`. */\n  readonly appAddress: string;\n\n  /**\n   * The app's on-chain address — the address to fund and inspect in the Builder\n   * activity report. Equivalent to {@link DirectDataController.appAddress}.\n   *\n   * @returns The app's `0x`-prefixed address.\n   */\n  getAppAddress(): string;\n\n  /**\n   * The app's full identity: its configured id/name/homepage plus the derived\n   * on-chain address. Useful for telling builders which app address to fund or\n   * look up.\n   *\n   * @returns `{ id, name, homepageUrl, address }`.\n   */\n  getAppIdentity(): AppIdentity;\n\n  /**\n   * Create an access request the user can approve.\n   *\n   * @param input - The post-approval return URL.\n   * @returns `{ requestId, approvalUrl, appAddress }`.\n   */\n  createAccessRequest(input: { returnUrl: string }): Promise<AccessRequest>;\n\n  /**\n   * Fetch the current status of an access request.\n   *\n   * @param requestId - The `dcr_*` id from {@link DirectDataController.createAccessRequest}.\n   * @returns `{ status, personalServerUrl?, grantId?, scope?, scopes? }`.\n   */\n  getAccessRequestStatus(requestId: string): Promise<AccessRequestStatus>;\n\n  /**\n   * Read the approved data from the user's Personal Server.\n   *\n   * @remarks\n   * Resolves the request to its grant + Personal Server and performs a Web3Signed\n   * read. Hides the `402 Payment Required` flow by default: if a read needs\n   * payment, it signs the Personal Server's payment challenge, retries with\n   * `X-PAYMENT`, and attaches shape-validated but unauthenticated\n   * {@link DirectPaymentResponseMetadata} under `payment` when the Personal\n   * Server returns it. After a successful read, the controller acknowledges\n   * the DCR so Vana Web can close/redirect the approval tab.\n   *\n   * A request can approve several scopes. This reads **one** of them — `scope`\n   * when given, otherwise the first approved scope. Use\n   * {@link DirectDataController.readAllApprovedData} to read them all.\n   *\n   * Acknowledging moves the DCR to `completed`, which is terminal and no longer\n   * read-ready. To read several scopes with your own loop, pass\n   * `acknowledge: false` on every call but the last.\n   *\n   * @param input - The `dcr_*` request id, the optional `scope` to read, and an\n   *   optional `acknowledge` flag (default `true`).\n   * @returns `{ scope, data, payment? }`.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   * @throws {@link ScopeNotApprovedError} if `scope` is not an approved scope.\n   * @throws {@link PaymentRequiredError} if payment is required but unsettled.\n   */\n  readApprovedData<T = unknown>(input: {\n    requestId: string;\n    scope?: string;\n    acknowledge?: boolean;\n  }): Promise<ApprovedDataResult<T>>;\n\n  /**\n   * Read every scope the user approved on a request.\n   *\n   * @remarks\n   * Reads the scopes in approval order, then acknowledges the DCR **once**,\n   * after the last read — acknowledging earlier would move the request to\n   * `completed` and make the remaining scopes unreadable.\n   *\n   * Each scope is a separate Personal Server read that settles its own\n   * `data_access` fee from escrow, so reading N scopes costs N times a\n   * single-scope read. The one-off registration fee is charged per grant, not\n   * per scope.\n   *\n   * A scope that fails does not abort the rest: successes land in `results` and\n   * failures in `errors`, because the fees for earlier scopes are already spent.\n   * If any scope fails the request is left unacknowledged, so the scopes that\n   * failed stay retryable — read them with `readApprovedData({ scope })` and\n   * acknowledge on the last one.\n   *\n   * @param input - The `dcr_*` request id to read.\n   * @returns `{ results, errors }`, both keyed by scope.\n   * @throws {@link AccessNotApprovedError} if the request is not approved.\n   */\n  readAllApprovedData<T = unknown>(input: {\n    requestId: string;\n  }): Promise<MultiScopeDataResult<T>>;\n}\n\nfunction isHexPrivateKey(value: string): value is Hex {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\n// A DCR is read-ready only while the grant exists and the Personal Server is\n// still serving it: `approved` (durable PS) or `ready_for_read` (browser PS).\n// `completed` is terminal — the app already read and acknowledged, and the\n// browser PS may be gone — so it is deliberately excluded here.\nfunction isReadReadyStatus(status: AccessRequestStatusValue): boolean {\n  return status === \"approved\" || status === \"ready_for_read\";\n}\n\n/**\n * Create a {@link DirectDataController}.\n *\n * @param config - Controller configuration (env, key, app identity, source, scopes).\n * @returns A ready-to-use controller.\n * @throws {@link DirectConfigError} when the key or scopes are invalid.\n */\nexport function createDirectDataController(\n  config: DirectDataControllerConfig,\n): DirectDataController {\n  // `appPrivateKey` is the documented field; `builderPrivateKey` is a\n  // deprecated alias kept for backwards compatibility.\n  const privateKey = config.appPrivateKey ?? config.builderPrivateKey;\n  if (!privateKey || !isHexPrivateKey(privateKey)) {\n    throw new DirectConfigError(\n      \"appPrivateKey must be a 0x-prefixed 32-byte hex string\",\n    );\n  }\n  if (!config.scopes || config.scopes.length === 0) {\n    throw new DirectConfigError(\"At least one scope is required\");\n  }\n  // Validate scopes eagerly so misconfiguration fails at construction.\n  for (const scope of config.scopes) {\n    parseScope(scope);\n  }\n\n  const env: DirectEnv = config.env ?? \"production\";\n  const network: DirectNetwork = config.network ?? getDirectDefaultNetwork(env);\n  const defaultEndpoints = getDirectEndpoints(env);\n  const chainId = config.endpoints?.chainId ?? getDirectNetworkChainId(network);\n  const endpoints: DirectServiceEndpoints = {\n    ...defaultEndpoints,\n    ...config.endpoints,\n    chainId,\n  };\n\n  const account = privateKeyToAccount(privateKey as Hex);\n  const signMessage: Web3SignedSignFn = (message: string) =>\n    account.signMessage({ message });\n  // viem's account.signTypedData satisfies the structural SignTypedDataFn used\n  // by the escrow GenericPayment signer.\n  const signTypedData = account.signTypedData as unknown as SignTypedDataFn;\n  const accessRequestClient: AccessRequestClient =\n    config.accessRequestClient ??\n    createDefaultAccessRequestClient({\n      baseUrl: endpoints.accessRequestBaseUrl,\n      approvalBaseUrl: endpoints.approvalAppBaseUrl,\n      fetchFn: config.fetchFn,\n      appAddress: account.address,\n      signMessage,\n    });\n\n  // Build the escrow payment config, defaulting from the per-network endpoints\n  // table and the contract registry when `config.escrow` is omitted or partial.\n  const escrowChainId = config.escrow?.chainId ?? chainId;\n  const defaultEscrowContract =\n    CONTRACTS.DataPortabilityEscrow.addresses[\n      escrowChainId as keyof typeof CONTRACTS.DataPortabilityEscrow.addresses\n    ] ?? undefined;\n  if (!config.escrow?.escrowContract && !defaultEscrowContract) {\n    throw new DirectConfigError(\n      `No DataPortabilityEscrow address found in the registry for chainId ${escrowChainId}. ` +\n        `Provide an explicit escrow.escrowContract in the controller config.`,\n    );\n  }\n  const escrow: EscrowPaymentConfig = {\n    client:\n      config.escrow?.client ??\n      createEscrowGatewayClient(endpoints.escrowGatewayUrl),\n    escrowContract:\n      config.escrow?.escrowContract ?? (defaultEscrowContract as `0x${string}`),\n    chainId: escrowChainId,\n    nonceSource: config.escrow?.nonceSource,\n    signTypedData,\n  };\n\n  return {\n    appAddress: account.address,\n\n    getAppAddress(): string {\n      return account.address;\n    },\n\n    getAppIdentity(): AppIdentity {\n      return {\n        id: config.app.id,\n        name: config.app.name,\n        homepageUrl: config.app.homepageUrl,\n        address: account.address,\n      };\n    },\n\n    async createAccessRequest(input): Promise<AccessRequest> {\n      return accessRequestClient.createAccessRequest({\n        appAddress: account.address,\n        app: config.app,\n        source: config.source,\n        scopes: config.scopes,\n        returnUrl: input.returnUrl,\n        network,\n      });\n    },\n\n    async getAccessRequestStatus(\n      requestId: string,\n    ): Promise<AccessRequestStatus> {\n      return accessRequestClient.getAccessRequestStatus(requestId);\n    },\n\n    async readApprovedData<T = unknown>(input: {\n      requestId: string;\n      scope?: string;\n      acknowledge?: boolean;\n    }): Promise<ApprovedDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scope = resolveRequestedScope(status, input.scope);\n\n      const result = await readScope<T>(status, scope);\n      if (input.acknowledge !== false) {\n        await acknowledgeQuietly(input.requestId);\n      }\n      return result;\n    },\n\n    async readAllApprovedData<T = unknown>(input: {\n      requestId: string;\n    }): Promise<MultiScopeDataResult<T>> {\n      const status = await requireReadReady(input.requestId);\n      const scopes = approvedScopes(status);\n\n      const results: Record<string, ApprovedDataResult<T>> = {};\n      const errors: Record<string, Error> = {};\n      // Sequential, not parallel: each read settles its own escrow payment and\n      // the default nonce source is process-local, so concurrent reads would\n      // race on the payment nonce.\n      for (const scope of scopes) {\n        try {\n          results[scope] = await readScope<T>(status, scope);\n        } catch (error) {\n          errors[scope] =\n            error instanceof Error ? error : new Error(String(error));\n        }\n      }\n\n      // Acknowledge only after the last read, and only if every scope read —\n      // acking moves the DCR to `completed`, which is terminal and no longer\n      // read-ready, so acking on a partial failure would make the scope that\n      // failed impossible to retry.\n      if (Object.keys(errors).length === 0) {\n        await acknowledgeQuietly(input.requestId);\n      }\n\n      return { results, errors };\n    },\n  };\n\n  async function requireReadReady(\n    requestId: string,\n  ): Promise<AccessRequestStatus> {\n    const status = await accessRequestClient.getAccessRequestStatus(requestId);\n    // `scope` and `scopes` are both optional on the public status type, and a\n    // client may return either one — require at least one approved scope rather\n    // than the singular field specifically.\n    if (\n      !isReadReadyStatus(status.status) ||\n      !status.personalServerUrl ||\n      !status.grantId ||\n      approvedScopes(status).length === 0\n    ) {\n      throw new AccessNotApprovedError(\n        \"Request is not approved or is missing grantId/scope/personalServerUrl\",\n        {\n          requestId,\n          status: status.status,\n          hasPersonalServerUrl: Boolean(status.personalServerUrl),\n          hasGrantId: Boolean(status.grantId),\n          hasScope: approvedScopes(status).length > 0,\n        },\n      );\n    }\n    return status;\n  }\n\n  /** Approved scopes in approval order, falling back to the single `scope`. */\n  function approvedScopes(status: AccessRequestStatus): string[] {\n    if (status.scopes && status.scopes.length > 0) return status.scopes;\n    return status.scope ? [status.scope] : [];\n  }\n\n  /**\n   * Resolve which scope to read. Rejects an unapproved scope up front so it\n   * never reaches the Personal Server and never settles a fee.\n   */\n  function resolveRequestedScope(\n    status: AccessRequestStatus,\n    requested?: string,\n  ): string {\n    const scopes = approvedScopes(status);\n    if (requested === undefined) return scopes[0];\n    if (!scopes.includes(requested)) {\n      throw new ScopeNotApprovedError(\n        `Scope \"${requested}\" is not approved on this request`,\n        { requestedScope: requested, approvedScopes: scopes },\n      );\n    }\n    return requested;\n  }\n\n  async function readScope<T>(\n    status: AccessRequestStatus,\n    scope: string,\n  ): Promise<ApprovedDataResult<T>> {\n    const result = await readPersonalServerData({\n      personalServerUrl: status.personalServerUrl as string,\n      scope,\n      grantId: status.grantId as string,\n      payerAddress: account.address,\n      signMessage,\n      escrow,\n      fetchFn: config.personalServerFetch,\n      transportRetry: config.personalServerTransportRetry,\n    });\n    return { scope, data: result.data as T, payment: result.payment };\n  }\n\n  async function acknowledgeQuietly(requestId: string): Promise<void> {\n    try {\n      await accessRequestClient.acknowledgeRead?.(requestId);\n    } catch {\n      // The read already succeeded; ack only drives Vana Web completion UX.\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/direct/errors.cjs

@@ -21,7 +21,8 @@ __export(errors_exports, {
   AccessNotApprovedError: () => AccessNotApprovedError,
   DirectConfigError: () => DirectConfigError,
   PaymentRequiredError: () => PaymentRequiredError,
-  PersonalServerReadError: () => PersonalServerReadError
+  PersonalServerReadError: () => PersonalServerReadError,
+  ScopeNotApprovedError: () => ScopeNotApprovedError
 });
 module.exports = __toCommonJS(errors_exports);
 var import_errors = require("../errors");
@@ -39,6 +40,13 @@ class AccessNotApprovedError extends import_errors.VanaError {
   }
   details;
 }
+class ScopeNotApprovedError extends import_errors.VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_SCOPE_NOT_APPROVED");
+    this.details = details;
+  }
+  details;
+}
 class PersonalServerReadError extends import_errors.VanaError {
   constructor(message, status, details) {
     super(message, "DIRECT_PERSONAL_SERVER_READ_ERROR");
@@ -60,6 +68,7 @@ class PaymentRequiredError extends import_errors.VanaError {
   AccessNotApprovedError,
   DirectConfigError,
   PaymentRequiredError,
-  PersonalServerReadError
+  PersonalServerReadError,
+  ScopeNotApprovedError
 });
 //# sourceMappingURL=errors.cjs.map

package/dist/direct/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYA,oBAA0B;AAGnB,MAAM,0BAA0B,wBAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,wBAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,wBAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,wBAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}
+{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/**\n * Thrown when a caller asks {@link DirectDataController.readApprovedData} for a\n * scope the user did not approve on this request.\n *\n * @remarks\n * Raised before any network call, so an unapproved scope never reaches the\n * Personal Server and never settles a fee. `details` carries the requested\n * scope and the scopes actually approved.\n */\nexport class ScopeNotApprovedError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_SCOPE_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYA,oBAA0B;AAGnB,MAAM,0BAA0B,wBAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,wBAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAWO,MAAM,8BAA8B,wBAAU;AAAA,EACnD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,2BAA2B;AAF1B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,wBAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,wBAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}

package/dist/direct/errors.d.ts

@@ -23,6 +23,19 @@ export declare class AccessNotApprovedError extends VanaError {
     readonly details?: Record<string, unknown> | undefined;
     constructor(message?: string, details?: Record<string, unknown> | undefined);
 }
+/**
+ * Thrown when a caller asks {@link DirectDataController.readApprovedData} for a
+ * scope the user did not approve on this request.
+ *
+ * @remarks
+ * Raised before any network call, so an unapproved scope never reaches the
+ * Personal Server and never settles a fee. `details` carries the requested
+ * scope and the scopes actually approved.
+ */
+export declare class ScopeNotApprovedError extends VanaError {
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
 /** Thrown when the Personal Server cannot be reached or returns an error. */
 export declare class PersonalServerReadError extends VanaError {
     readonly status?: number | undefined;

package/dist/direct/errors.js

@@ -13,6 +13,13 @@ class AccessNotApprovedError extends VanaError {
   }
   details;
 }
+class ScopeNotApprovedError extends VanaError {
+  constructor(message, details) {
+    super(message, "DIRECT_SCOPE_NOT_APPROVED");
+    this.details = details;
+  }
+  details;
+}
 class PersonalServerReadError extends VanaError {
   constructor(message, status, details) {
     super(message, "DIRECT_PERSONAL_SERVER_READ_ERROR");
@@ -33,6 +40,7 @@ export {
   AccessNotApprovedError,
   DirectConfigError,
   PaymentRequiredError,
-  PersonalServerReadError
+  PersonalServerReadError,
+  ScopeNotApprovedError
 };
 //# sourceMappingURL=errors.js.map

package/dist/direct/errors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":"AAYA,SAAS,iBAAiB;AAGnB,MAAM,0BAA0B,UAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,UAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,UAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,UAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}
+{"version":3,"sources":["../../src/direct/errors.ts"],"sourcesContent":["/**\n * Typed errors for the Direct Data Controller flow.\n *\n * @remarks\n * These extend {@link VanaError} so direct-controller callers can branch on the\n * structured `code` field. The messages map to the failure modes documented in\n * the builder guide (\"Common Errors\").\n *\n * @category Direct\n * @module direct/errors\n */\n\nimport { VanaError } from \"../errors\";\n\n/** Thrown when configuration passed to {@link createDirectDataController} is invalid. */\nexport class DirectConfigError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_CONFIG_ERROR\");\n  }\n}\n\n/**\n * Thrown when {@link DirectDataController.readApprovedData} is called for a\n * request that is not yet approved (missing grantId, scope, or personalServerUrl).\n */\nexport class AccessNotApprovedError extends VanaError {\n  constructor(\n    message = \"Access request is not approved yet\",\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_ACCESS_NOT_APPROVED\");\n  }\n}\n\n/**\n * Thrown when a caller asks {@link DirectDataController.readApprovedData} for a\n * scope the user did not approve on this request.\n *\n * @remarks\n * Raised before any network call, so an unapproved scope never reaches the\n * Personal Server and never settles a fee. `details` carries the requested\n * scope and the scopes actually approved.\n */\nexport class ScopeNotApprovedError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_SCOPE_NOT_APPROVED\");\n  }\n}\n\n/** Thrown when the Personal Server cannot be reached or returns an error. */\nexport class PersonalServerReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PERSONAL_SERVER_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a Personal Server requires payment (HTTP 402) but no escrow config\n * is set, or the read still requires payment after escrow settlement.\n *\n * @remarks\n * `details` carries structured debug data (`scope`, `grantId`, `asset`,\n * `amount`, and — after a settlement attempt — the `payment` receipt) so callers\n * can see exactly what was owed.\n */\nexport class PaymentRequiredError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"DIRECT_PAYMENT_REQUIRED\");\n  }\n}\n"],"mappings":"AAYA,SAAS,iBAAiB;AAGnB,MAAM,0BAA0B,UAAU;AAAA,EAC/C,YACE,SACgB,SAChB;AACA,UAAM,SAAS,qBAAqB;AAFpB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAMO,MAAM,+BAA+B,UAAU;AAAA,EACpD,YACE,UAAU,sCACM,SAChB;AACA,UAAM,SAAS,4BAA4B;AAF3B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAWO,MAAM,8BAA8B,UAAU;AAAA,EACnD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,2BAA2B;AAF1B;AAAA,EAGlB;AAAA,EAHkB;AAIpB;AAGO,MAAM,gCAAgC,UAAU;AAAA,EACrD,YACE,SACgB,QACA,SAChB;AACA,UAAM,SAAS,mCAAmC;AAHlC;AACA;AAAA,EAGlB;AAAA,EAJkB;AAAA,EACA;AAIpB;AAWO,MAAM,6BAA6B,UAAU;AAAA,EAClD,YACE,SACgB,SAChB;AACA,UAAM,SAAS,yBAAyB;AAFxB;AAAA,EAGlB;AAAA,EAHkB;AAIpB;","names":[]}

package/dist/direct/escrow-payment.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * challenged operation through the escrow gateway:\n *\n *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module supports legacy `\"grant\"` operations and receipt-bound\n * `\"data_access\"` operations. It adapts the escrow `payForOp` flow to the\n * direct-read use case; it does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowPaymentClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n/** The escrow `GenericPayment.opType` used for receipt-bound data access. */\nexport const DATA_ACCESS_OP_TYPE = \"data_access\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface EscrowPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE | typeof DATA_ACCESS_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedEscrowPayment {\n  message: EscrowPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedEscrowPayment;\n}\n\n/** Configuration required to sign an escrow X-PAYMENT header. */\nexport interface EscrowPaymentHeaderConfig {\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/**\n * Escrow settlement configuration for gateway authorization.\n *\n * @remarks\n * Extends the header-signing boundary with the gateway client used by\n * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper\n * callers can continue to provide this full configuration.\n */\nexport interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowPaymentClient;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\nconst UINT256_MAX = (1n << 256n) - 1n;\nconst ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;\nconst BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;\nconst SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    BYTES32_RE.test(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    ADDRESS_RE.test(record.accessor) &&\n    BYTES32_RE.test(record.recordId) &&\n    SIGNATURE_RE.test(record.signature)\n  );\n}\n\nfunction validateSigningOperation(\n  payerAddress: `0x${string}`,\n  required: PersonalServerPaymentOperation,\n): void {\n  if (!ADDRESS_RE.test(payerAddress)) {\n    throw new Error(\"Payment payer must be a 20-byte EVM address\");\n  }\n  if (!BYTES32_RE.test(required.opId)) {\n    throw new Error(\"Payment operation id must be a 32-byte hex value\");\n  }\n  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {\n    throw new Error(\"Payment asset must be a 20-byte EVM address\");\n  }\n  if (!isUint256Decimal(required.amount, true)) {\n    throw new Error(\"Payment amount must be a canonical uint256 decimal\");\n  }\n  if (\n    required.paymentNonce !== undefined &&\n    !isUint256Decimal(required.paymentNonce, false)\n  ) {\n    throw new Error(\"Payment nonce must be a positive uint256 decimal\");\n  }\n\n  const accessRecord = required.accessRecord;\n  if (required.opType === DATA_ACCESS_OP_TYPE) {\n    if (!accessRecord || !isValidAccessRecord(accessRecord)) {\n      throw new Error(\"Data-access payment requires a valid access record\");\n    }\n    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment operation id must equal the access record id\",\n      );\n    }\n    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment accessor must equal the payment payer address\",\n      );\n    }\n    return;\n  }\n\n  if (required.amount === \"0\") {\n    if (\n      !accessRecord ||\n      !isValidAccessRecord(accessRecord) ||\n      accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()\n    ) {\n      throw new Error(\n        \"Zero-amount grant payments require a valid access record for the payer\",\n      );\n    }\n  }\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signEscrowPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentOperation;\n  config: EscrowPaymentHeaderConfig;\n}): Promise<SignedEscrowPayment> {\n  const { payerAddress, required, config } = params;\n  validateSigningOperation(payerAddress, required);\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.opId as `0x${string}`;\n  const amount = BigInt(required.amount);\n  if (amount < 0n || amount > UINT256_MAX) {\n    throw new Error(\"Payment amount must be a uint256\");\n  }\n  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {\n    throw new Error(\"Payment nonce must be a positive uint256\");\n  }\n\n  const message = {\n    payerAddress,\n    opType: required.opType,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\n/**\n * Build the canonical X-PAYMENT header for a validated escrow operation.\n *\n * @remarks\n * Supports both legacy grant payments and receipt-bound data-access payments.\n * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.\n */\nexport async function buildEscrowPaymentHeader(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation parsed from the Personal Server challenge. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow contract, chain, signer, and nonce configuration. */\n  config: EscrowPaymentHeaderConfig;\n}): Promise<string> {\n  const network = params.required.network ?? `vana:${params.config.chainId}`;\n  if (network !== `vana:${params.config.chainId}`) {\n    throw new Error(\"Payment network must match the configured chain\");\n  }\n\n  const signed = await signEscrowPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\n/** Build a legacy grant X-PAYMENT header. */\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  return buildEscrowPaymentHeader({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  value: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  const field = value?.[key];\n  return typeof field === \"string\" ? field : undefined;\n}\n\nfunction isCanonicalIsoTimestamp(value: string): boolean {\n  try {\n    return new Date(value).toISOString() === value;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse shape-validated payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * This metadata is not authenticated by the gateway. It is suitable for\n * display and debugging, not as proof that a payment occurred.\n */\nexport function paymentResponseMetadataFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  if (!header) return undefined;\n  try {\n    const result = asRecord(base64DecodeJson(header));\n    const breakdown = asRecord(result?.breakdown);\n    const opType = stringField(result, \"opType\");\n    const opId = stringField(result, \"opId\");\n    const payerAddress = stringField(result, \"payerAddress\");\n    const asset = stringField(result, \"asset\");\n    const amount = stringField(result, \"amount\");\n    const paymentNonce = stringField(result, \"paymentNonce\");\n    const registrationFee = stringField(breakdown, \"registrationFee\");\n    const dataAccessFee = stringField(breakdown, \"dataAccessFee\");\n    const paidAt = stringField(result, \"paidAt\");\n    if (\n      result?.success !== true ||\n      !opType ||\n      !opId ||\n      !BYTES32_RE.test(opId) ||\n      !payerAddress ||\n      !ADDRESS_RE.test(payerAddress) ||\n      !asset ||\n      !ADDRESS_RE.test(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !registrationFee ||\n      !isUint256Decimal(registrationFee, true) ||\n      !dataAccessFee ||\n      !isUint256Decimal(dataAccessFee, true) ||\n      typeof breakdown?.registrationPaid !== \"boolean\" ||\n      !paidAt ||\n      !isCanonicalIsoTimestamp(paidAt)\n    ) {\n      return undefined;\n    }\n    return {\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      breakdown: {\n        registrationFee,\n        dataAccessFee,\n        registrationPaid: breakdown.registrationPaid,\n      },\n      paidAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal\n * Server response header is untrusted metadata, not a gateway-authenticated\n * receipt.\n */\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  return paymentResponseMetadataFromHeader(header);\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  return authorizeEscrowPayment({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\n/**\n * Authorize a validated grant or data-access operation through the escrow\n * gateway.\n */\nexport async function authorizeEscrowPayment(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation to authorize. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow gateway and signing configuration. */\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, config } = params;\n  const signed = await signEscrowPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: signed.message.opType,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: signed.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,oBAQO;AAUA,MAAM,gBAAgB;AAEtB,MAAM,sBAAsB;AAgF5B,SAAS,qBACd,WACoB;AACpB,SAAO;AAAA,IACL,iBAAiB,UAAU;AAAA,IAC3B,eAAe,UAAU;AAAA,IACzB,kBAAkB,UAAU;AAAA,EAC9B;AACF;AAGO,SAAS,uBACd,QACsB;AACtB,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,MAAM,OAAO;AAAA,IACb,OAAO,OAAO;AAAA,IACd,QAAQ,OAAO;AAAA,IACf,cAAc,OAAO;AAAA,IACrB,WAAW,qBAAqB,OAAO,SAAS;AAAA,IAChD,QAAQ,OAAO;AAAA,EACjB;AACF;AAGO,SAAS,2BAA+C;AAC7D,QAAM,WAAW,oBAAI,IAAoB;AACzC,SAAO,CAAC,iBAAiC;AACvC,UAAM,MAAM,aAAa,YAAY;AACrC,UAAM,QAAQ,SAAS,IAAI,GAAG,KAAK,MAAM;AACzC,aAAS,IAAI,KAAK,IAAI;AACtB,WAAO;AAAA,EACT;AACF;AAEA,MAAM,0BAA0B,yBAAyB;AACzD,MAAM,eAAe,MAAM,QAAQ;AACnC,MAAM,aAAa;AACnB,MAAM,aAAa;AACnB,MAAM,eAAe;AAErB,SAAS,iBAAiB,OAAe,WAA6B;AACpE,QAAM,UAAU,YAAY,mBAAmB;AAC/C,SACE,MAAM,UAAU,YAAY,SAAS,EAAE,UACvC,QAAQ,KAAK,KAAK,KAClB,OAAO,KAAK,KAAK;AAErB;AAEA,SAAS,oBAAoB,QAAqC;AAChE,SACE,WAAW,KAAK,OAAO,WAAW,KAClC,iBAAiB,OAAO,SAAS,KAAK,KACtC,WAAW,KAAK,OAAO,QAAQ,KAC/B,WAAW,KAAK,OAAO,QAAQ,KAC/B,aAAa,KAAK,OAAO,SAAS;AAEtC;AAEA,SAAS,yBACP,cACA,UACM;AACN,MAAI,CAAC,WAAW,KAAK,YAAY,GAAG;AAClC,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,MAAI,CAAC,WAAW,KAAK,SAAS,IAAI,GAAG;AACnC,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AACA,MAAI,CAAC,WAAW,KAAK,SAAS,SAAS,kCAAoB,GAAG;AAC5D,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,MAAI,CAAC,iBAAiB,SAAS,QAAQ,IAAI,GAAG;AAC5C,UAAM,IAAI,MAAM,oDAAoD;AAAA,EACtE;AACA,MACE,SAAS,iBAAiB,UAC1B,CAAC,iBAAiB,SAAS,cAAc,KAAK,GAC9C;AACA,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AAEA,QAAM,eAAe,SAAS;AAC9B,MAAI,SAAS,WAAW,qBAAqB;AAC3C,QAAI,CAAC,gBAAgB,CAAC,oBAAoB,YAAY,GAAG;AACvD,YAAM,IAAI,MAAM,oDAAoD;AAAA,IACtE;AACA,QAAI,SAAS,KAAK,YAAY,MAAM,aAAa,SAAS,YAAY,GAAG;AACvE,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,QAAI,aAAa,SAAS,YAAY,MAAM,aAAa,YAAY,GAAG;AACtE,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA;AAAA,EACF;AAEA,MAAI,SAAS,WAAW,KAAK;AAC3B,QACE,CAAC,gBACD,CAAC,oBAAoB,YAAY,KACjC,aAAa,SAAS,YAAY,MAAM,aAAa,YAAY,GACjE;AACA,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,iBAAiB,OAAwB;AAChD,QAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,KAAK,CAAC;AAC5D,MAAI,SAAS;AACb,aAAW,QAAQ,MAAO,WAAU,OAAO,aAAa,IAAI;AAC5D,SAAO,KAAK,MAAM;AACpB;AAEA,SAAS,iBAAiB,OAAwB;AAChD,QAAM,SAAS,KAAK,KAAK;AACzB,QAAM,QAAQ,WAAW,KAAK,QAAQ,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC;AAClE,SAAO,KAAK,MAAM,IAAI,YAAY,EAAE,OAAO,KAAK,CAAC;AACnD;AAEA,eAAe,kBAAkB,QAIA;AAC/B,QAAM,EAAE,cAAc,UAAU,OAAO,IAAI;AAC3C,2BAAyB,cAAc,QAAQ;AAC/C,QAAM,cAAc,OAAO,eAAe;AAC1C,QAAM,eAAe;AAAA,IACnB,SAAS,gBAAiB,MAAM,YAAY,YAAY;AAAA,EAC1D;AACA,QAAM,QAAS,SAAS,SAAS;AACjC,QAAM,OAAO,SAAS;AACtB,QAAM,SAAS,OAAO,SAAS,MAAM;AACrC,MAAI,SAAS,MAAM,SAAS,aAAa;AACvC,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACpD;AACA,MAAI,gBAAgB,MAAM,eAAe,aAAa;AACpD,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AAEA,QAAM,UAAU;AAAA,IACd;AAAA,IACA,QAAQ,SAAS;AAAA,IACjB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,QAAM,YAAY,MAAM,OAAO,cAAc;AAAA,IAC3C,YAAQ,oCAAqB,OAAO,SAAS,OAAO,cAAc;AAAA,IAClE,OAAO;AAAA,IACP,aAAa;AAAA,IACb;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL,SAAS;AAAA,MACP,GAAG;AAAA,MACH,QAAQ,OAAO,SAAS;AAAA,MACxB,cAAc,aAAa,SAAS;AAAA,IACtC;AAAA,IACA;AAAA,IACA,GAAI,SAAS,eAAe,EAAE,cAAc,SAAS,aAAa,IAAI,CAAC;AAAA,EACzE;AACF;AASA,eAAsB,yBAAyB,QAO3B;AAClB,QAAM,UAAU,OAAO,SAAS,WAAW,QAAQ,OAAO,OAAO,OAAO;AACxE,MAAI,YAAY,QAAQ,OAAO,OAAO,OAAO,IAAI;AAC/C,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AAEA,QAAM,SAAS,MAAM,kBAAkB,MAAM;AAC7C,QAAM,UAA6B;AAAA,IACjC,aAAa;AAAA,IACb,QAAQ;AAAA,IACR;AAAA,IACA,SAAS;AAAA,EACX;AACA,SAAO,iBAAiB,OAAO;AACjC;AAGA,eAAsB,wBAAwB,QAI1B;AAClB,SAAO,yBAAyB;AAAA,IAC9B,GAAG;AAAA,IACH,UAAU;AAAA,MACR,GAAG,OAAO;AAAA,MACV,QAAQ;AAAA,MACR,MAAM,OAAO,SAAS;AAAA,IACxB;AAAA,EACF,CAAC;AACH;AAEA,SAAS,SAAS,OAAqD;AACrE,SAAO,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAC5D,QACD;AACN;AAEA,SAAS,YACP,OACA,KACoB;AACpB,QAAM,QAAQ,QAAQ,GAAG;AACzB,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEA,SAAS,wBAAwB,OAAwB;AACvD,MAAI;AACF,WAAO,IAAI,KAAK,KAAK,EAAE,YAAY,MAAM;AAAA,EAC3C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASO,SAAS,kCACd,QAC2C;AAC3C,MAAI,CAAC,OAAQ,QAAO;AACpB,MAAI;AACF,UAAM,SAAS,SAAS,iBAAiB,MAAM,CAAC;AAChD,UAAM,YAAY,SAAS,QAAQ,SAAS;AAC5C,UAAM,SAAS,YAAY,QAAQ,QAAQ;AAC3C,UAAM,OAAO,YAAY,QAAQ,MAAM;AACvC,UAAM,eAAe,YAAY,QAAQ,cAAc;AACvD,UAAM,QAAQ,YAAY,QAAQ,OAAO;AACzC,UAAM,SAAS,YAAY,QAAQ,QAAQ;AAC3C,UAAM,eAAe,YAAY,QAAQ,cAAc;AACvD,UAAM,kBAAkB,YAAY,WAAW,iBAAiB;AAChE,UAAM,gBAAgB,YAAY,WAAW,eAAe;AAC5D,UAAM,SAAS,YAAY,QAAQ,QAAQ;AAC3C,QACE,QAAQ,YAAY,QACpB,CAAC,UACD,CAAC,QACD,CAAC,WAAW,KAAK,IAAI,KACrB,CAAC,gBACD,CAAC,WAAW,KAAK,YAAY,KAC7B,CAAC,SACD,CAAC,WAAW,KAAK,KAAK,KACtB,CAAC,UACD,CAAC,iBAAiB,QAAQ,IAAI,KAC9B,CAAC,gBACD,CAAC,iBAAiB,cAAc,KAAK,KACrC,CAAC,mBACD,CAAC,iBAAiB,iBAAiB,IAAI,KACvC,CAAC,iBACD,CAAC,iBAAiB,eAAe,IAAI,KACrC,OAAO,WAAW,qBAAqB,aACvC,CAAC,UACD,CAAC,wBAAwB,MAAM,GAC/B;AACA,aAAO;AAAA,IACT;AACA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA;AAAA,QACA,kBAAkB,UAAU;AAAA,MAC9B;AAAA,MACA;AAAA,IACF;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAOO,SAAS,yBACd,QAC2C;AAC3C,SAAO,kCAAkC,MAAM;AACjD;AASA,eAAsB,sBAAsB,QAIV;AAChC,SAAO,uBAAuB;AAAA,IAC5B,GAAG;AAAA,IACH,UAAU;AAAA,MACR,GAAG,OAAO;AAAA,MACV,QAAQ;AAAA,MACR,MAAM,OAAO,SAAS;AAAA,IACxB;AAAA,EACF,CAAC;AACH;AAMA,eAAsB,uBAAuB,QAOX;AAChC,QAAM,EAAE,cAAc,OAAO,IAAI;AACjC,QAAM,SAAS,MAAM,kBAAkB,MAAM;AAE7C,QAAM,SAAS,MAAM,OAAO,OAAO,SAAS;AAAA,IAC1C;AAAA,IACA,QAAQ,OAAO,QAAQ;AAAA,IACvB,MAAM,OAAO,QAAQ;AAAA,IACrB,OAAO,OAAO,QAAQ;AAAA,IACtB,QAAQ,OAAO,QAAQ;AAAA,IACvB,cAAc,OAAO,QAAQ;AAAA,IAC7B,WAAW,OAAO;AAAA,IAClB,cAAc,OAAO;AAAA,EACvB,CAAC;AAED,SAAO,uBAAuB,MAAM;AACtC;","names":[]}
+{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * challenged operation through the escrow gateway:\n *\n *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module supports legacy `\"grant\"` operations and receipt-bound\n * `\"data_access\"` operations. It adapts the escrow `payForOp` flow to the\n * direct-read use case; it does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n/** The escrow `GenericPayment.opType` used for receipt-bound data access. */\nexport const DATA_ACCESS_OP_TYPE = \"data_access\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface EscrowPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE | typeof DATA_ACCESS_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedEscrowPayment {\n  message: EscrowPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedEscrowPayment;\n}\n\n/** Configuration required to sign an escrow X-PAYMENT header. */\nexport interface EscrowPaymentHeaderConfig {\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/**\n * Escrow settlement configuration for gateway authorization.\n *\n * @remarks\n * Extends the header-signing boundary with the gateway client used by\n * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper\n * callers can continue to provide this full configuration.\n */\nexport interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\nconst UINT256_MAX = (1n << 256n) - 1n;\nconst ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;\nconst BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;\nconst SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    BYTES32_RE.test(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    ADDRESS_RE.test(record.accessor) &&\n    BYTES32_RE.test(record.recordId) &&\n    SIGNATURE_RE.test(record.signature)\n  );\n}\n\nfunction validateSigningOperation(\n  payerAddress: `0x${string}`,\n  required: PersonalServerPaymentOperation,\n): void {\n  if (!ADDRESS_RE.test(payerAddress)) {\n    throw new Error(\"Payment payer must be a 20-byte EVM address\");\n  }\n  if (!BYTES32_RE.test(required.opId)) {\n    throw new Error(\"Payment operation id must be a 32-byte hex value\");\n  }\n  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {\n    throw new Error(\"Payment asset must be a 20-byte EVM address\");\n  }\n  if (!isUint256Decimal(required.amount, true)) {\n    throw new Error(\"Payment amount must be a canonical uint256 decimal\");\n  }\n  if (\n    required.paymentNonce !== undefined &&\n    !isUint256Decimal(required.paymentNonce, false)\n  ) {\n    throw new Error(\"Payment nonce must be a positive uint256 decimal\");\n  }\n\n  const accessRecord = required.accessRecord;\n  if (required.opType === DATA_ACCESS_OP_TYPE) {\n    if (!accessRecord || !isValidAccessRecord(accessRecord)) {\n      throw new Error(\"Data-access payment requires a valid access record\");\n    }\n    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment operation id must equal the access record id\",\n      );\n    }\n    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment accessor must equal the payment payer address\",\n      );\n    }\n    return;\n  }\n\n  if (required.amount === \"0\") {\n    if (\n      !accessRecord ||\n      !isValidAccessRecord(accessRecord) ||\n      accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()\n    ) {\n      throw new Error(\n        \"Zero-amount grant payments require a valid access record for the payer\",\n      );\n    }\n  }\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signEscrowPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentOperation;\n  config: EscrowPaymentHeaderConfig;\n}): Promise<SignedEscrowPayment> {\n  const { payerAddress, required, config } = params;\n  validateSigningOperation(payerAddress, required);\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.opId as `0x${string}`;\n  const amount = BigInt(required.amount);\n  if (amount < 0n || amount > UINT256_MAX) {\n    throw new Error(\"Payment amount must be a uint256\");\n  }\n  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {\n    throw new Error(\"Payment nonce must be a positive uint256\");\n  }\n\n  const message = {\n    payerAddress,\n    opType: required.opType,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\n/**\n * Build the canonical X-PAYMENT header for a validated escrow operation.\n *\n * @remarks\n * Supports both legacy grant payments and receipt-bound data-access payments.\n * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.\n */\nexport async function buildEscrowPaymentHeader(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation parsed from the Personal Server challenge. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow contract, chain, signer, and nonce configuration. */\n  config: EscrowPaymentHeaderConfig;\n}): Promise<string> {\n  const network = params.required.network ?? `vana:${params.config.chainId}`;\n  if (network !== `vana:${params.config.chainId}`) {\n    throw new Error(\"Payment network must match the configured chain\");\n  }\n\n  const signed = await signEscrowPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\n/** Build a legacy grant X-PAYMENT header. */\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  return buildEscrowPaymentHeader({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  value: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  const field = value?.[key];\n  return typeof field === \"string\" ? field : undefined;\n}\n\nfunction isCanonicalIsoTimestamp(value: string): boolean {\n  try {\n    return new Date(value).toISOString() === value;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse shape-validated payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * This metadata is not authenticated by the gateway. It is suitable for\n * display and debugging, not as proof that a payment occurred.\n */\nexport function paymentResponseMetadataFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  if (!header) return undefined;\n  try {\n    const result = asRecord(base64DecodeJson(header));\n    const breakdown = asRecord(result?.breakdown);\n    const opType = stringField(result, \"opType\");\n    const opId = stringField(result, \"opId\");\n    const payerAddress = stringField(result, \"payerAddress\");\n    const asset = stringField(result, \"asset\");\n    const amount = stringField(result, \"amount\");\n    const paymentNonce = stringField(result, \"paymentNonce\");\n    const registrationFee = stringField(breakdown, \"registrationFee\");\n    const dataAccessFee = stringField(breakdown, \"dataAccessFee\");\n    const paidAt = stringField(result, \"paidAt\");\n    if (\n      result?.success !== true ||\n      !opType ||\n      !opId ||\n      !BYTES32_RE.test(opId) ||\n      !payerAddress ||\n      !ADDRESS_RE.test(payerAddress) ||\n      !asset ||\n      !ADDRESS_RE.test(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !registrationFee ||\n      !isUint256Decimal(registrationFee, true) ||\n      !dataAccessFee ||\n      !isUint256Decimal(dataAccessFee, true) ||\n      typeof breakdown?.registrationPaid !== \"boolean\" ||\n      !paidAt ||\n      !isCanonicalIsoTimestamp(paidAt)\n    ) {\n      return undefined;\n    }\n    return {\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      breakdown: {\n        registrationFee,\n        dataAccessFee,\n        registrationPaid: breakdown.registrationPaid,\n      },\n      paidAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal\n * Server response header is untrusted metadata, not a gateway-authenticated\n * receipt.\n */\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  return paymentResponseMetadataFromHeader(header);\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  return authorizeEscrowPayment({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\n/**\n * Authorize a validated grant or data-access operation through the escrow\n * gateway.\n */\nexport async function authorizeEscrowPayment(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation to authorize. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow gateway and signing configuration. */\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, config } = params;\n  const signed = await signEscrowPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: signed.message.opType,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: signed.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}

package/dist/direct/escrow-payment.d.ts

@@ -18,7 +18,7 @@
  * @category Direct
  * @module direct/escrow-payment
  */
-import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowPaymentClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow.js";
+import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowGatewayClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow.js";
 import type { DirectFeeBreakdown, DirectPaymentReceipt, DirectPaymentResponseMetadata, PersonalServerPaymentOperation, PersonalServerPaymentRequired } from "./types.js";
 /** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */
 export declare const GRANT_OP_TYPE: "grant";
@@ -71,7 +71,7 @@ export interface EscrowPaymentHeaderConfig {
  */
 export interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {
     /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */
-    client: EscrowPaymentClient;
+    client: EscrowGatewayClient;
 }
 /** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */
 export declare function toDirectFeeBreakdown(breakdown: PaymentBreakdown): DirectFeeBreakdown;

package/dist/direct/escrow-payment.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * challenged operation through the escrow gateway:\n *\n *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module supports legacy `\"grant\"` operations and receipt-bound\n * `\"data_access\"` operations. It adapts the escrow `payForOp` flow to the\n * direct-read use case; it does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowPaymentClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n/** The escrow `GenericPayment.opType` used for receipt-bound data access. */\nexport const DATA_ACCESS_OP_TYPE = \"data_access\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface EscrowPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE | typeof DATA_ACCESS_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedEscrowPayment {\n  message: EscrowPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedEscrowPayment;\n}\n\n/** Configuration required to sign an escrow X-PAYMENT header. */\nexport interface EscrowPaymentHeaderConfig {\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/**\n * Escrow settlement configuration for gateway authorization.\n *\n * @remarks\n * Extends the header-signing boundary with the gateway client used by\n * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper\n * callers can continue to provide this full configuration.\n */\nexport interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowPaymentClient;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\nconst UINT256_MAX = (1n << 256n) - 1n;\nconst ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;\nconst BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;\nconst SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    BYTES32_RE.test(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    ADDRESS_RE.test(record.accessor) &&\n    BYTES32_RE.test(record.recordId) &&\n    SIGNATURE_RE.test(record.signature)\n  );\n}\n\nfunction validateSigningOperation(\n  payerAddress: `0x${string}`,\n  required: PersonalServerPaymentOperation,\n): void {\n  if (!ADDRESS_RE.test(payerAddress)) {\n    throw new Error(\"Payment payer must be a 20-byte EVM address\");\n  }\n  if (!BYTES32_RE.test(required.opId)) {\n    throw new Error(\"Payment operation id must be a 32-byte hex value\");\n  }\n  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {\n    throw new Error(\"Payment asset must be a 20-byte EVM address\");\n  }\n  if (!isUint256Decimal(required.amount, true)) {\n    throw new Error(\"Payment amount must be a canonical uint256 decimal\");\n  }\n  if (\n    required.paymentNonce !== undefined &&\n    !isUint256Decimal(required.paymentNonce, false)\n  ) {\n    throw new Error(\"Payment nonce must be a positive uint256 decimal\");\n  }\n\n  const accessRecord = required.accessRecord;\n  if (required.opType === DATA_ACCESS_OP_TYPE) {\n    if (!accessRecord || !isValidAccessRecord(accessRecord)) {\n      throw new Error(\"Data-access payment requires a valid access record\");\n    }\n    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment operation id must equal the access record id\",\n      );\n    }\n    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment accessor must equal the payment payer address\",\n      );\n    }\n    return;\n  }\n\n  if (required.amount === \"0\") {\n    if (\n      !accessRecord ||\n      !isValidAccessRecord(accessRecord) ||\n      accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()\n    ) {\n      throw new Error(\n        \"Zero-amount grant payments require a valid access record for the payer\",\n      );\n    }\n  }\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signEscrowPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentOperation;\n  config: EscrowPaymentHeaderConfig;\n}): Promise<SignedEscrowPayment> {\n  const { payerAddress, required, config } = params;\n  validateSigningOperation(payerAddress, required);\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.opId as `0x${string}`;\n  const amount = BigInt(required.amount);\n  if (amount < 0n || amount > UINT256_MAX) {\n    throw new Error(\"Payment amount must be a uint256\");\n  }\n  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {\n    throw new Error(\"Payment nonce must be a positive uint256\");\n  }\n\n  const message = {\n    payerAddress,\n    opType: required.opType,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\n/**\n * Build the canonical X-PAYMENT header for a validated escrow operation.\n *\n * @remarks\n * Supports both legacy grant payments and receipt-bound data-access payments.\n * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.\n */\nexport async function buildEscrowPaymentHeader(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation parsed from the Personal Server challenge. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow contract, chain, signer, and nonce configuration. */\n  config: EscrowPaymentHeaderConfig;\n}): Promise<string> {\n  const network = params.required.network ?? `vana:${params.config.chainId}`;\n  if (network !== `vana:${params.config.chainId}`) {\n    throw new Error(\"Payment network must match the configured chain\");\n  }\n\n  const signed = await signEscrowPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\n/** Build a legacy grant X-PAYMENT header. */\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  return buildEscrowPaymentHeader({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  value: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  const field = value?.[key];\n  return typeof field === \"string\" ? field : undefined;\n}\n\nfunction isCanonicalIsoTimestamp(value: string): boolean {\n  try {\n    return new Date(value).toISOString() === value;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse shape-validated payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * This metadata is not authenticated by the gateway. It is suitable for\n * display and debugging, not as proof that a payment occurred.\n */\nexport function paymentResponseMetadataFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  if (!header) return undefined;\n  try {\n    const result = asRecord(base64DecodeJson(header));\n    const breakdown = asRecord(result?.breakdown);\n    const opType = stringField(result, \"opType\");\n    const opId = stringField(result, \"opId\");\n    const payerAddress = stringField(result, \"payerAddress\");\n    const asset = stringField(result, \"asset\");\n    const amount = stringField(result, \"amount\");\n    const paymentNonce = stringField(result, \"paymentNonce\");\n    const registrationFee = stringField(breakdown, \"registrationFee\");\n    const dataAccessFee = stringField(breakdown, \"dataAccessFee\");\n    const paidAt = stringField(result, \"paidAt\");\n    if (\n      result?.success !== true ||\n      !opType ||\n      !opId ||\n      !BYTES32_RE.test(opId) ||\n      !payerAddress ||\n      !ADDRESS_RE.test(payerAddress) ||\n      !asset ||\n      !ADDRESS_RE.test(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !registrationFee ||\n      !isUint256Decimal(registrationFee, true) ||\n      !dataAccessFee ||\n      !isUint256Decimal(dataAccessFee, true) ||\n      typeof breakdown?.registrationPaid !== \"boolean\" ||\n      !paidAt ||\n      !isCanonicalIsoTimestamp(paidAt)\n    ) {\n      return undefined;\n    }\n    return {\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      breakdown: {\n        registrationFee,\n        dataAccessFee,\n        registrationPaid: breakdown.registrationPaid,\n      },\n      paidAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal\n * Server response header is untrusted metadata, not a gateway-authenticated\n * receipt.\n */\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  return paymentResponseMetadataFromHeader(header);\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  return authorizeEscrowPayment({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\n/**\n * Authorize a validated grant or data-access operation through the escrow\n * gateway.\n */\nexport async function authorizeEscrowPayment(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation to authorize. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow gateway and signing configuration. */\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, config } = params;\n  const signed = await signEscrowPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: signed.message.opType,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: signed.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * challenged operation through the escrow gateway:\n *\n *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module supports legacy `\"grant\"` operations and receipt-bound\n * `\"data_access\"` operations. It adapts the escrow `payForOp` flow to the\n * direct-read use case; it does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n/** The escrow `GenericPayment.opType` used for receipt-bound data access. */\nexport const DATA_ACCESS_OP_TYPE = \"data_access\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface EscrowPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE | typeof DATA_ACCESS_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedEscrowPayment {\n  message: EscrowPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedEscrowPayment;\n}\n\n/** Configuration required to sign an escrow X-PAYMENT header. */\nexport interface EscrowPaymentHeaderConfig {\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/**\n * Escrow settlement configuration for gateway authorization.\n *\n * @remarks\n * Extends the header-signing boundary with the gateway client used by\n * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper\n * callers can continue to provide this full configuration.\n */\nexport interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\nconst UINT256_MAX = (1n << 256n) - 1n;\nconst ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;\nconst BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;\nconst SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    BYTES32_RE.test(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    ADDRESS_RE.test(record.accessor) &&\n    BYTES32_RE.test(record.recordId) &&\n    SIGNATURE_RE.test(record.signature)\n  );\n}\n\nfunction validateSigningOperation(\n  payerAddress: `0x${string}`,\n  required: PersonalServerPaymentOperation,\n): void {\n  if (!ADDRESS_RE.test(payerAddress)) {\n    throw new Error(\"Payment payer must be a 20-byte EVM address\");\n  }\n  if (!BYTES32_RE.test(required.opId)) {\n    throw new Error(\"Payment operation id must be a 32-byte hex value\");\n  }\n  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {\n    throw new Error(\"Payment asset must be a 20-byte EVM address\");\n  }\n  if (!isUint256Decimal(required.amount, true)) {\n    throw new Error(\"Payment amount must be a canonical uint256 decimal\");\n  }\n  if (\n    required.paymentNonce !== undefined &&\n    !isUint256Decimal(required.paymentNonce, false)\n  ) {\n    throw new Error(\"Payment nonce must be a positive uint256 decimal\");\n  }\n\n  const accessRecord = required.accessRecord;\n  if (required.opType === DATA_ACCESS_OP_TYPE) {\n    if (!accessRecord || !isValidAccessRecord(accessRecord)) {\n      throw new Error(\"Data-access payment requires a valid access record\");\n    }\n    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment operation id must equal the access record id\",\n      );\n    }\n    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment accessor must equal the payment payer address\",\n      );\n    }\n    return;\n  }\n\n  if (required.amount === \"0\") {\n    if (\n      !accessRecord ||\n      !isValidAccessRecord(accessRecord) ||\n      accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()\n    ) {\n      throw new Error(\n        \"Zero-amount grant payments require a valid access record for the payer\",\n      );\n    }\n  }\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signEscrowPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentOperation;\n  config: EscrowPaymentHeaderConfig;\n}): Promise<SignedEscrowPayment> {\n  const { payerAddress, required, config } = params;\n  validateSigningOperation(payerAddress, required);\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.opId as `0x${string}`;\n  const amount = BigInt(required.amount);\n  if (amount < 0n || amount > UINT256_MAX) {\n    throw new Error(\"Payment amount must be a uint256\");\n  }\n  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {\n    throw new Error(\"Payment nonce must be a positive uint256\");\n  }\n\n  const message = {\n    payerAddress,\n    opType: required.opType,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\n/**\n * Build the canonical X-PAYMENT header for a validated escrow operation.\n *\n * @remarks\n * Supports both legacy grant payments and receipt-bound data-access payments.\n * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.\n */\nexport async function buildEscrowPaymentHeader(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation parsed from the Personal Server challenge. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow contract, chain, signer, and nonce configuration. */\n  config: EscrowPaymentHeaderConfig;\n}): Promise<string> {\n  const network = params.required.network ?? `vana:${params.config.chainId}`;\n  if (network !== `vana:${params.config.chainId}`) {\n    throw new Error(\"Payment network must match the configured chain\");\n  }\n\n  const signed = await signEscrowPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\n/** Build a legacy grant X-PAYMENT header. */\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  return buildEscrowPaymentHeader({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  value: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  const field = value?.[key];\n  return typeof field === \"string\" ? field : undefined;\n}\n\nfunction isCanonicalIsoTimestamp(value: string): boolean {\n  try {\n    return new Date(value).toISOString() === value;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse shape-validated payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * This metadata is not authenticated by the gateway. It is suitable for\n * display and debugging, not as proof that a payment occurred.\n */\nexport function paymentResponseMetadataFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  if (!header) return undefined;\n  try {\n    const result = asRecord(base64DecodeJson(header));\n    const breakdown = asRecord(result?.breakdown);\n    const opType = stringField(result, \"opType\");\n    const opId = stringField(result, \"opId\");\n    const payerAddress = stringField(result, \"payerAddress\");\n    const asset = stringField(result, \"asset\");\n    const amount = stringField(result, \"amount\");\n    const paymentNonce = stringField(result, \"paymentNonce\");\n    const registrationFee = stringField(breakdown, \"registrationFee\");\n    const dataAccessFee = stringField(breakdown, \"dataAccessFee\");\n    const paidAt = stringField(result, \"paidAt\");\n    if (\n      result?.success !== true ||\n      !opType ||\n      !opId ||\n      !BYTES32_RE.test(opId) ||\n      !payerAddress ||\n      !ADDRESS_RE.test(payerAddress) ||\n      !asset ||\n      !ADDRESS_RE.test(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !registrationFee ||\n      !isUint256Decimal(registrationFee, true) ||\n      !dataAccessFee ||\n      !isUint256Decimal(dataAccessFee, true) ||\n      typeof breakdown?.registrationPaid !== \"boolean\" ||\n      !paidAt ||\n      !isCanonicalIsoTimestamp(paidAt)\n    ) {\n      return undefined;\n    }\n    return {\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      breakdown: {\n        registrationFee,\n        dataAccessFee,\n        registrationPaid: breakdown.registrationPaid,\n      },\n      paidAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal\n * Server response header is untrusted metadata, not a gateway-authenticated\n * receipt.\n */\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  return paymentResponseMetadataFromHeader(header);\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  return authorizeEscrowPayment({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\n/**\n * Authorize a validated grant or data-access operation through the escrow\n * gateway.\n */\nexport async function authorizeEscrowPayment(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation to authorize. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow gateway and signing configuration. */\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, config } = params;\n  const signed = await signEscrowPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: signed.message.opType,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: signed.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}