@absol-labs/agent 0.5.0 → 0.7.0

package/src/wallet/privy-session-provider.ts

@@ -0,0 +1,129 @@
+import { getAddress, type Address, type Hex } from "viem";
+import { z } from "zod";
+
+import type { PrivyEip1193Provider } from "./provider.js";
+
+const jsonRpcResponseSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number(), z.null()]),
+  result: z.unknown().optional(),
+  error: z
+    .object({
+      code: z.number(),
+      message: z.string(),
+      data: z.unknown().optional(),
+    })
+    .optional(),
+});
+
+export interface PrivySessionProviderConfig {
+  readonly brokerUrl: string;
+  readonly sessionToken: string;
+  readonly address: Address;
+  readonly rpcUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+}
+
+export class PrivySessionProviderError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "PrivySessionProviderError";
+  }
+}
+
+/**
+ * EIP-1193 provider for a policy-bound Metrik/Privy headless session.
+ * Signing and writes go only to the broker; public read RPCs go directly to
+ * Base Sepolia and never receive the session token.
+ */
+export function createPrivySessionProvider(
+  config: PrivySessionProviderConfig,
+): PrivyEip1193Provider {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const address = getAddress(config.address);
+  const brokerUrl = new URL("/v1/rpc", requireHttpsBase(config.brokerUrl));
+  const rpcUrl = config.rpcUrl ?? "https://base-sepolia-rpc.publicnode.com";
+  let rpcId = 0;
+
+  return {
+    async request({ method, params = [] }) {
+      if (method === "eth_chainId") return "0x14a34";
+      if (method === "eth_accounts" || method === "eth_requestAccounts") {
+        return [address];
+      }
+      if (
+        method === "eth_sendTransaction" ||
+        method === "eth_signTypedData_v4"
+      ) {
+        const response = await fetchImpl(brokerUrl, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${config.sessionToken}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ method, params }, bigintJson),
+        }).catch((error: unknown) => {
+          throw new PrivySessionProviderError("session broker is unreachable", {
+            cause: error,
+          });
+        });
+        const body = (await response.json().catch(() => null)) as {
+          result?: Hex;
+          error?: string;
+        } | null;
+        if (!response.ok || body?.result === undefined) {
+          throw new PrivySessionProviderError(
+            body?.error ??
+              `session broker rejected ${method} (${response.status})`,
+          );
+        }
+        return body.result;
+      }
+      if (
+        method === "personal_sign" ||
+        method === "eth_sign" ||
+        method === "eth_signTransaction" ||
+        method === "wallet_sendCalls"
+      ) {
+        throw new PrivySessionProviderError(
+          `${method} is outside the Metrik agent-session policy`,
+        );
+      }
+
+      const id = ++rpcId;
+      const response = await fetchImpl(rpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(
+          { jsonrpc: "2.0", id, method, params },
+          bigintJson,
+        ),
+      }).catch((error: unknown) => {
+        throw new PrivySessionProviderError("Base Sepolia RPC is unreachable", {
+          cause: error,
+        });
+      });
+      const body = jsonRpcResponseSchema.parse(await response.json());
+      if (!response.ok || body.error !== undefined) {
+        throw new PrivySessionProviderError(
+          body.error?.message ?? `Base Sepolia RPC rejected ${method}`,
+        );
+      }
+      return body.result;
+    },
+  };
+}
+
+function requireHttpsBase(value: string): URL {
+  const url = new URL(value);
+  if (url.protocol !== "https:" && url.hostname !== "localhost") {
+    throw new PrivySessionProviderError(
+      "session broker URL must use HTTPS (except localhost development)",
+    );
+  }
+  return url;
+}
+
+function bigintJson(_key: string, value: unknown) {
+  return typeof value === "bigint" ? `0x${value.toString(16)}` : value;
+}

package/src/wallet/provider.ts

@@ -4,8 +4,19 @@ import {
   type EvmServerAccount,
   type EvmSmartAccount,
 } from "@coinbase/cdp-sdk";
-import type { Account } from "viem";
-import { privateKeyToAccount, toAccount } from "viem/accounts";
+import {
+  custom,
+  toHex,
+  serializeTypedData,
+  type Account,
+  type Address,
+  type Hex,
+  type SignableMessage,
+  type TypedData,
+  type TypedDataDefinition,
+  isAddress,
+} from "viem";
+import { parseAccount, privateKeyToAccount, toAccount } from "viem/accounts";
 import { z } from "zod";
 
 import {
@@ -38,6 +49,51 @@ export class AgentWalletConfigError extends Error {
   }
 }
 
+/** A deliberately small EIP-1193 seam implemented by an authenticated Privy session. */
+export interface PrivyEip1193Provider {
+  request(args: {
+    readonly method: string;
+    readonly params?: readonly unknown[];
+  }): Promise<unknown>;
+}
+
+/**
+ * Configuration for a user-owned Privy embedded EOA.
+ *
+ * The browser/site owns authentication and obtains the provider from Privy's
+ * authenticated wallet. This package does not import Privy's UI SDK, accept a
+ * secret, persist a wallet, or create a wallet from an app id alone.
+ */
+export interface PrivyEmbeddedWalletConfig {
+  /** Public Privy app id; never an app secret. */
+  readonly appId: string;
+  /** Address returned by the authenticated user wallet. */
+  readonly address: Address;
+  /** Authenticated Privy wallet provider (EIP-1193). */
+  readonly provider: PrivyEip1193Provider;
+  /** Metrik currently supports Base Sepolia only. */
+  readonly chainId?: number;
+}
+
+export class PrivyEmbeddedWalletError extends Error {
+  readonly code:
+    | "invalid-config"
+    | "provider-error"
+    | "chain-mismatch"
+    | "account-mismatch"
+    | "invalid-signature";
+
+  constructor(
+    code: PrivyEmbeddedWalletError["code"],
+    message: string,
+    options?: { readonly cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "PrivyEmbeddedWalletError";
+    this.code = code;
+  }
+}
+
 export interface CdpWalletConfig {
   readonly apiKeyId?: string;
   readonly apiKeySecret?: string;
@@ -53,13 +109,20 @@ export type AgentWalletInput =
     }
   | {
       readonly cdp: CdpWalletConfig;
+    }
+  | {
+      readonly privy: PrivyEmbeddedWalletConfig;
     };
 
 export interface ResolvedAgentWallet {
-  readonly source: "injected" | "cdp";
+  readonly source: "injected" | "cdp" | "privy";
   readonly account: Account;
   readonly cdpOwner?: EvmServerAccount;
   readonly smartAccount?: EvmSmartAccount;
+  readonly privy?: {
+    readonly appId: string;
+    readonly chainId: number;
+  };
 }
 
 export interface CdpClientLike {
@@ -98,6 +161,16 @@ export async function resolveAgentWallet(
     };
   }
 
+  if ("privy" in input) {
+    const chainId = input.privy.chainId ?? BASE_SEPOLIA_CHAIN_ID;
+    const account = await createPrivyEmbeddedAccount(input.privy);
+    return {
+      source: "privy",
+      account,
+      privy: { appId: input.privy.appId, chainId },
+    };
+  }
+
   const cdpClient = (options.createCdpClient ?? defaultCdpClientFactory)(
     input.cdp,
   );
@@ -119,6 +192,62 @@ export async function resolveAgentWallet(
   };
 }
 
+/**
+ * Adapts an authenticated Privy EIP-1193 wallet to a viem JSON-RPC Account.
+ * It deliberately remains a JSON-RPC account so viem sends transactions via
+ * Privy's documented `eth_sendTransaction` boundary instead of assuming that
+ * the embedded provider exposes raw transaction signing. Every signing
+ * operation rechecks chain and account identity so a
+ * browser account/network switch cannot silently redirect a spend.
+ *
+ * This is an EOA adapter only. It does not implement EIP-1271, smart accounts,
+ * session-key issuance, or gas sponsorship; those require provider/site or
+ * backend integration and must be wired explicitly by the caller.
+ */
+export async function createPrivyEmbeddedAccount(
+  config: PrivyEmbeddedWalletConfig,
+): Promise<Account> {
+  validatePrivyConfig(config);
+  const chainId = config.chainId ?? BASE_SEPOLIA_CHAIN_ID;
+  await assertPrivySession(config, chainId);
+
+  const account = {
+    ...parseAccount(config.address),
+    signMessage: async ({ message }: { message: SignableMessage }) => {
+      await assertPrivySession(config, chainId);
+      const raw =
+        typeof message === "string"
+          ? toHex(message)
+          : message.raw instanceof Uint8Array
+            ? toHex(message.raw)
+            : message.raw;
+      return requireSignature(
+        await requestPrivy(config.provider, "personal_sign", [
+          raw,
+          config.address,
+        ]),
+      );
+    },
+    signTypedData: async <
+      const typedData extends TypedData | Record<string, unknown>,
+      primaryType extends keyof typedData | "EIP712Domain" = keyof typedData,
+    >(
+      parameters: TypedDataDefinition<typedData, primaryType>,
+    ) => {
+      await assertPrivySession(config, chainId);
+      const serialized = serializeTypedData(parameters);
+      return requireSignature(
+        await requestPrivy(config.provider, "eth_signTypedData_v4", [
+          config.address,
+          serialized,
+        ]),
+      );
+    },
+  } as Account;
+
+  return account;
+}
+
 export async function createWalletBackedAgentClient(
   sdkConfig: StreamProofClientConfig,
   walletInput: AgentWalletInput,
@@ -129,6 +258,9 @@ export async function createWalletBackedAgentClient(
     {
       ...sdkConfig,
       account: wallet.account,
+      ...("privy" in walletInput
+        ? { transport: custom(createCheckedPrivyProvider(walletInput.privy)) }
+        : {}),
     },
     {
       ...(options.createSdkClient === undefined
@@ -195,3 +327,128 @@ function defaultCdpClientFactory(config: CdpWalletConfig): CdpClientLike {
       : { walletSecret: config.walletSecret }),
   });
 }
+
+const BASE_SEPOLIA_CHAIN_ID = 84532;
+
+function validatePrivyConfig(config: PrivyEmbeddedWalletConfig): void {
+  if (config.appId.trim() === "") {
+    throw new PrivyEmbeddedWalletError(
+      "invalid-config",
+      "Privy public app id is required; an app secret is never accepted by this adapter",
+    );
+  }
+  if (!isAddress(config.address)) {
+    throw new PrivyEmbeddedWalletError(
+      "invalid-config",
+      "Privy wallet address is invalid",
+    );
+  }
+  if (
+    config.chainId !== undefined &&
+    config.chainId !== BASE_SEPOLIA_CHAIN_ID
+  ) {
+    throw new PrivyEmbeddedWalletError(
+      "invalid-config",
+      `Metrik Privy wallets support Base Sepolia chain ID ${BASE_SEPOLIA_CHAIN_ID} only`,
+    );
+  }
+}
+
+async function assertPrivySession(
+  config: PrivyEmbeddedWalletConfig,
+  expectedChainId: number,
+): Promise<void> {
+  let chainResult: unknown;
+  let accountsResult: unknown;
+  try {
+    [chainResult, accountsResult] = await Promise.all([
+      config.provider.request({ method: "eth_chainId" }),
+      config.provider.request({ method: "eth_accounts" }),
+    ]);
+  } catch (error) {
+    throw new PrivyEmbeddedWalletError(
+      "provider-error",
+      "Privy wallet provider rejected the session check",
+      { cause: error },
+    );
+  }
+
+  const chainId = parseChainId(chainResult);
+  if (chainId !== expectedChainId) {
+    throw new PrivyEmbeddedWalletError(
+      "chain-mismatch",
+      `Privy wallet chain ID ${chainId} is not Base Sepolia (${expectedChainId})`,
+    );
+  }
+  if (
+    !Array.isArray(accountsResult) ||
+    accountsResult.length === 0 ||
+    typeof accountsResult[0] !== "string" ||
+    accountsResult[0].toLowerCase() !== config.address.toLowerCase()
+  ) {
+    throw new PrivyEmbeddedWalletError(
+      "account-mismatch",
+      "Privy provider account does not match configured address",
+    );
+  }
+}
+
+async function requestPrivy(
+  provider: PrivyEip1193Provider,
+  method: string,
+  params: readonly unknown[],
+): Promise<unknown> {
+  try {
+    return await provider.request({ method, params });
+  } catch (error) {
+    throw new PrivyEmbeddedWalletError(
+      "provider-error",
+      `Privy wallet provider rejected ${method}`,
+      { cause: error },
+    );
+  }
+}
+
+function createCheckedPrivyProvider(
+  config: PrivyEmbeddedWalletConfig,
+): PrivyEip1193Provider {
+  const expectedChainId = config.chainId ?? BASE_SEPOLIA_CHAIN_ID;
+  return {
+    request: async (args) => {
+      if (args.method === "eth_sendTransaction") {
+        await assertPrivySession(config, expectedChainId);
+      }
+      try {
+        return await config.provider.request(args);
+      } catch (error) {
+        throw new PrivyEmbeddedWalletError(
+          "provider-error",
+          `Privy wallet provider rejected ${args.method}`,
+          { cause: error },
+        );
+      }
+    },
+  };
+}
+
+function parseChainId(value: unknown): number {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+    return value;
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value)) {
+    const parsed = Number.parseInt(value.slice(2), 16);
+    if (Number.isSafeInteger(parsed) && parsed > 0) return parsed;
+  }
+  throw new PrivyEmbeddedWalletError(
+    "provider-error",
+    "Privy wallet provider returned an invalid chain ID",
+  );
+}
+
+function requireSignature(value: unknown): Hex {
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value))
+    return value as Hex;
+  throw new PrivyEmbeddedWalletError(
+    "invalid-signature",
+    "Privy wallet provider returned a non-hex signature",
+  );
+}