@absol-labs/agent 0.6.0 → 0.7.1

package/src/wallet/privy-broker-server-entry.ts

@@ -0,0 +1,9 @@
+import { startPrivyBrokerServer } from "./privy-broker-server.js";
+
+const server = await startPrivyBrokerServer();
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.once(signal, () => {
+    server.close(() => process.exit(0));
+  });
+}

package/src/wallet/privy-broker-server.ts

@@ -0,0 +1,573 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { dirname, resolve } from "node:path";
+
+import { PrivyClient } from "@privy-io/node";
+import { MetrikClient } from "@absol-labs/sdk";
+import type { Hex } from "viem";
+import { z } from "zod";
+
+import {
+  AutonomousWalletBroker,
+  AutonomousWalletBrokerError,
+  createPrivyAutonomousProvider,
+  type AutonomousPreparedRequest,
+  type AutonomousWalletBrokerStore,
+  type AutonomousWalletProvision,
+} from "./autonomous-wallet-broker.js";
+import {
+  PrivySessionBroker,
+  PrivySessionBrokerError,
+  type PrivyBrokerProvider,
+  type PrivyBrokerSession,
+  type PrivyBrokerSessionStore,
+} from "./privy-session-broker.js";
+
+const serverEnvSchema = z.object({
+  PRIVY_APP_ID: z.string().min(1),
+  PRIVY_APP_SECRET: z.string().min(1),
+  PRIVY_AUTHORIZATION_PRIVATE_KEY_FILE: z.string().min(1),
+  PRIVY_KEY_QUORUM_ID: z.string().min(1),
+  PRIVY_POLICY_ID: z.string().min(1),
+  METRIK_PRIVY_SESSION_STORE: z.string().min(1),
+  METRIK_PRIVY_AUTONOMOUS_STORE: z.string().min(1).optional(),
+  METRIK_PRIVY_BROKER_PORT: z.coerce.number().int().positive().default(8095),
+  METRIK_PRIVY_ALLOWED_ORIGINS: z
+    .string()
+    .default(
+      "https://app.metrik.live,http://localhost:5173,http://localhost:4173",
+    ),
+});
+
+const createSessionSchema = z.object({
+  walletId: z.string().min(1),
+  address: z.string().min(1),
+  signedMandate: z.unknown(),
+});
+const revokeSchema = z.object({ sessionId: z.string().min(1) });
+const rpcSchema = z.object({
+  method: z.enum(["eth_sendTransaction", "eth_signTypedData_v4"]),
+  params: z.array(z.unknown()),
+});
+const autonomousProofSchema = z.object({
+  version: z.literal(1),
+  appId: z.string().min(1).max(200),
+  chainId: z.literal(84532),
+  publicKey: z.string().min(1).max(1_024),
+  nonce: z.string().min(16).max(256),
+  issuedAt: z.number().int().safe(),
+  signature: z.string().min(1).max(1_024),
+});
+const autonomousProvisionSchema = z.object({
+  appId: z.string().min(1).max(200),
+  chainId: z.literal(84532),
+  publicKey: z.string().min(1).max(1_024),
+  proof: autonomousProofSchema,
+  idempotencyKey: z.string().min(16).max(256),
+});
+const autonomousPrepareSchema = z.object({
+  walletId: z.string().min(1).max(256),
+  publicKey: z.string().min(1).max(1_024),
+  method: z.enum(["eth_sendTransaction", "eth_signTypedData_v4"]),
+  params: z.array(z.unknown()).max(4),
+});
+const autonomousExecuteSchema = z.object({
+  requestId: z.string().uuid(),
+  publicKey: z.string().min(1).max(1_024),
+  signature: z.string().min(1).max(1_024),
+});
+
+export async function startPrivyBrokerServer(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<ReturnType<typeof createServer>> {
+  const config = serverEnvSchema.parse(env);
+  const authorizationPrivateKey = (
+    await readFile(resolve(config.PRIVY_AUTHORIZATION_PRIVATE_KEY_FILE))
+  ).toString("base64");
+  const client = new PrivyClient({
+    appId: config.PRIVY_APP_ID,
+    appSecret: config.PRIVY_APP_SECRET,
+  });
+  const metrik = MetrikClient.baseSepolia();
+  const provider = createPrivyProvider(client);
+  const autonomousBroker = new AutonomousWalletBroker({
+    appId: config.PRIVY_APP_ID,
+    policyId: config.PRIVY_POLICY_ID,
+    provider: createPrivyAutonomousProvider(client),
+    store: new JsonAutonomousWalletBrokerStore(
+      config.METRIK_PRIVY_AUTONOMOUS_STORE ??
+        `${config.METRIK_PRIVY_SESSION_STORE}.autonomous`,
+    ),
+    streamReader: {
+      getStream: async (streamId) => {
+        const stream = await metrik.getStreamV2(streamId);
+        return {
+          buyer: stream.buyer,
+          serviceRef: stream.serviceRef,
+          status: stream.status,
+        };
+      },
+    },
+  });
+  const broker = new PrivySessionBroker({
+    provider,
+    store: new JsonPrivyBrokerSessionStore(config.METRIK_PRIVY_SESSION_STORE),
+    authorizationPrivateKey,
+    streamReader: {
+      getStream: async (streamId) => {
+        const stream = await metrik.getStreamV2(streamId);
+        return {
+          buyer: stream.buyer,
+          serviceRef: stream.serviceRef,
+          status: stream.status,
+        };
+      },
+    },
+  });
+  const allowedOrigins = new Set(
+    config.METRIK_PRIVY_ALLOWED_ORIGINS.split(",").map((value) => value.trim()),
+  );
+  const limiter = new BrokerRateLimiter();
+
+  const server = createServer(async (request, response) => {
+    try {
+      applyCors(request, response, allowedOrigins);
+      if (request.method === "OPTIONS") {
+        response.writeHead(204).end();
+        return;
+      }
+      const url = new URL(request.url ?? "/", "http://localhost");
+      if (request.method === "GET" && url.pathname === "/health") {
+        sendJson(response, 200, { ok: true });
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/v1/config") {
+        sendJson(response, 200, {
+          appId: config.PRIVY_APP_ID,
+          keyQuorumId: config.PRIVY_KEY_QUORUM_ID,
+          policyId: config.PRIVY_POLICY_ID,
+          chainId: 84532,
+          maxTotalUsdcAtomic: "1000000",
+          maxRatePerSecondAtomic: "1000",
+          maxDurationSeconds: 3600,
+        });
+        return;
+      }
+      if (request.method === "POST" && url.pathname === "/v1/sessions") {
+        const input = createSessionSchema.parse(await readJson(request));
+        const result = await broker.createSession({
+          accessToken: requireBearer(request),
+          walletId: input.walletId,
+          address: input.address as `0x${string}`,
+          signedMandate: input.signedMandate,
+        });
+        sendJson(response, 201, result);
+        return;
+      }
+      if (request.method === "POST" && url.pathname === "/v1/sessions/revoke") {
+        const input = revokeSchema.parse(await readJson(request));
+        await broker.revokeSession(requireBearer(request), input.sessionId);
+        sendJson(response, 200, { revoked: true });
+        return;
+      }
+      if (request.method === "POST" && url.pathname === "/v1/rpc") {
+        const input = rpcSchema.parse(await readJson(request));
+        const result = await broker.rpc({
+          token: requireBearer(request),
+          method: input.method,
+          params: input.params,
+        });
+        sendJson(response, 200, { result });
+        return;
+      }
+      if (
+        request.method === "POST" &&
+        url.pathname === "/v1/autonomous-wallets"
+      ) {
+        limiter.require(request, "provision", 5, 60 * 60);
+        const input = autonomousProvisionSchema.parse(await readJson(request));
+        const result = await autonomousBroker.provision(input);
+        sendJson(response, 201, result);
+        return;
+      }
+      if (
+        request.method === "POST" &&
+        url.pathname === "/v1/autonomous-wallets/prepare"
+      ) {
+        limiter.require(request, "prepare", 120, 60);
+        const input = autonomousPrepareSchema.parse(await readJson(request));
+        const result = await autonomousBroker.prepare(input);
+        sendJson(response, 201, result);
+        return;
+      }
+      if (
+        request.method === "POST" &&
+        url.pathname === "/v1/autonomous-wallets/execute"
+      ) {
+        limiter.require(request, "execute", 120, 60);
+        const input = autonomousExecuteSchema.parse(await readJson(request));
+        const result = await autonomousBroker.execute(input);
+        sendJson(response, 200, { result });
+        return;
+      }
+      sendJson(response, 404, { error: "not-found" });
+    } catch (error) {
+      const status = statusFor(error);
+      const message =
+        error instanceof PrivySessionBrokerError ||
+        error instanceof AutonomousWalletBrokerError ||
+        error instanceof z.ZodError
+          ? error.message
+          : "internal-error";
+      sendJson(response, status, { error: message });
+    }
+  });
+  await new Promise<void>((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(config.METRIK_PRIVY_BROKER_PORT, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolveListen();
+    });
+  });
+  return server;
+}
+
+export class JsonPrivyBrokerSessionStore implements PrivyBrokerSessionStore {
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(private readonly path: string) {}
+
+  async findByTokenHash(tokenHash: string): Promise<PrivyBrokerSession | null> {
+    const sessions = await this.read();
+    return sessions.find((session) => session.tokenHash === tokenHash) ?? null;
+  }
+
+  async get(id: string): Promise<PrivyBrokerSession | null> {
+    const sessions = await this.read();
+    return sessions.find((session) => session.id === id) ?? null;
+  }
+
+  async put(session: PrivyBrokerSession): Promise<void> {
+    const operation = this.queue
+      .catch(() => undefined)
+      .then(async () => {
+        const sessions = await this.read();
+        const index = sessions.findIndex(
+          (candidate) => candidate.id === session.id,
+        );
+        if (index === -1) sessions.push(session);
+        else sessions[index] = session;
+        const target = resolve(this.path);
+        const temp = `${target}.${process.pid}.tmp`;
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await writeFile(temp, JSON.stringify(sessions, bigintJson), {
+          mode: 0o600,
+        });
+        await rename(temp, target);
+      });
+    this.queue = operation;
+    return operation;
+  }
+
+  private async read(): Promise<PrivyBrokerSession[]> {
+    try {
+      const raw = await readFile(resolve(this.path), "utf8");
+      return JSON.parse(raw, bigintReviver) as PrivyBrokerSession[];
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+  }
+}
+
+interface AutonomousBrokerDiskState {
+  readonly provisions: AutonomousWalletProvision[];
+  readonly prepared: AutonomousPreparedRequest[];
+}
+
+/** Persistent replay/idempotency state. It never contains an agent private key. */
+export class JsonAutonomousWalletBrokerStore implements AutonomousWalletBrokerStore {
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(private readonly path: string) {}
+
+  async findProvisionByPublicKey(publicKey: string) {
+    return (
+      (await this.read()).provisions.find(
+        (value) => value.publicKey === publicKey,
+      ) ?? null
+    );
+  }
+
+  async findProvisionByNonce(nonce: string) {
+    return (
+      (await this.read()).provisions.find((value) => value.nonce === nonce) ??
+      null
+    );
+  }
+
+  async putProvision(provision: AutonomousWalletProvision): Promise<void> {
+    await this.mutate((state) => {
+      const provisions = [...state.provisions];
+      const index = provisions.findIndex(
+        (value) => value.publicKey === provision.publicKey,
+      );
+      if (index === -1) provisions.push(provision);
+      else provisions[index] = provision;
+      return { ...state, provisions };
+    });
+  }
+
+  async getPrepared(requestId: string) {
+    return (
+      (await this.read()).prepared.find(
+        (value) => value.requestId === requestId,
+      ) ?? null
+    );
+  }
+
+  async putPrepared(request: AutonomousPreparedRequest): Promise<void> {
+    await this.mutate((state) => {
+      const prepared = [...state.prepared];
+      const index = prepared.findIndex(
+        (value) => value.requestId === request.requestId,
+      );
+      if (index === -1) prepared.push(request);
+      else prepared[index] = request;
+      return { ...state, prepared };
+    });
+  }
+
+  async completePrepared(requestId: string, result: Hex, consumedAt: number) {
+    let completed: AutonomousPreparedRequest | null = null;
+    await this.mutate((state) => {
+      const prepared = [...state.prepared];
+      const index = prepared.findIndex(
+        (value) => value.requestId === requestId,
+      );
+      if (index === -1) return state;
+      const current = prepared[index]!;
+      completed =
+        current.result === undefined
+          ? { ...current, result, consumedAt }
+          : current;
+      prepared[index] = completed;
+      return { ...state, prepared };
+    });
+    return completed;
+  }
+
+  private async mutate(
+    operation: (state: AutonomousBrokerDiskState) => AutonomousBrokerDiskState,
+  ): Promise<void> {
+    const queued = this.queue
+      .catch(() => undefined)
+      .then(async () => {
+        const state = operation(await this.read());
+        const target = resolve(this.path);
+        const temp = `${target}.${process.pid}.tmp`;
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await writeFile(temp, JSON.stringify(state), { mode: 0o600 });
+        await rename(temp, target);
+      });
+    this.queue = queued;
+    return queued;
+  }
+
+  private async read(): Promise<AutonomousBrokerDiskState> {
+    try {
+      const parsed = JSON.parse(
+        await readFile(resolve(this.path), "utf8"),
+      ) as AutonomousBrokerDiskState;
+      if (!Array.isArray(parsed.provisions) || !Array.isArray(parsed.prepared))
+        throw new Error("invalid autonomous broker store");
+      return parsed;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT")
+        return { provisions: [], prepared: [] };
+      throw error;
+    }
+  }
+}
+
+function createPrivyProvider(client: PrivyClient): PrivyBrokerProvider {
+  return {
+    verifyAccessToken: async (token) => {
+      const verified = await client.utils().auth().verifyAccessToken(token);
+      return { userId: verified.user_id };
+    },
+    getUserWallets: async (userId) => {
+      const user = await client.users()._get(userId);
+      return user.linked_accounts.flatMap((account) => {
+        if (
+          account.type !== "wallet" ||
+          !("id" in account) ||
+          !("chain_type" in account) ||
+          !("address" in account)
+        ) {
+          return [];
+        }
+        return [
+          {
+            id: typeof account.id === "string" ? account.id : null,
+            address: account.address,
+            chain_type: account.chain_type,
+            ...(account.connector_type === undefined
+              ? {}
+              : { connector_type: String(account.connector_type) }),
+            ...(account.wallet_client_type === undefined
+              ? {}
+              : { wallet_client_type: String(account.wallet_client_type) }),
+          },
+        ];
+      });
+    },
+    sendTransaction: async (input) => {
+      const result = await client
+        .wallets()
+        .ethereum()
+        .sendTransaction(input.walletId, {
+          caip2: "eip155:84532",
+          params: { transaction: input.transaction as never },
+          sponsor: input.sponsor,
+          authorization_context: {
+            authorization_private_keys: [input.authorizationPrivateKey],
+          },
+        });
+      return result.hash as Hex;
+    },
+    signTypedData: async (input) => {
+      const result = await client
+        .wallets()
+        .ethereum()
+        .signTypedData(input.walletId, {
+          params: { typed_data: input.typedData as never },
+          authorization_context: {
+            authorization_private_keys: [input.authorizationPrivateKey],
+          },
+        });
+      return result.signature as Hex;
+    },
+  };
+}
+
+async function readJson(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += value.length;
+    if (size > 64 * 1024) {
+      throw new PrivySessionBrokerError("invalid-request", "request too large");
+    }
+    chunks.push(value);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function requireBearer(request: IncomingMessage): string {
+  const value = request.headers.authorization;
+  if (!value?.startsWith("Bearer ") || value.length <= 39) {
+    throw new PrivySessionBrokerError("unauthorized", "missing bearer token");
+  }
+  return value.slice(7);
+}
+
+function applyCors(
+  request: IncomingMessage,
+  response: ServerResponse,
+  allowedOrigins: ReadonlySet<string>,
+): void {
+  const origin = request.headers.origin;
+  if (origin && allowedOrigins.has(origin)) {
+    response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("vary", "Origin");
+    response.setHeader(
+      "access-control-allow-headers",
+      "authorization,content-type",
+    );
+    response.setHeader("access-control-allow-methods", "GET,POST,OPTIONS");
+  }
+}
+
+function sendJson(
+  response: ServerResponse,
+  status: number,
+  body: unknown,
+): void {
+  if (response.headersSent) return;
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+  });
+  response.end(JSON.stringify(body));
+}
+
+function statusFor(error: unknown): number {
+  if (error instanceof z.ZodError) return 400;
+  if (error instanceof AutonomousWalletBrokerError) {
+    if (error.code === "unauthorized") return 401;
+    if (error.code === "policy-denied" || error.code === "replay") return 403;
+    if (error.code === "invalid-request") return 400;
+    return 502;
+  }
+  if (!(error instanceof PrivySessionBrokerError)) return 500;
+  if (error.code === "unauthorized") return 401;
+  if (error.code === "expired" || error.code === "revoked") return 403;
+  if (error.code === "policy-denied") return 403;
+  if (error.code === "invalid-request") return 400;
+  return 502;
+}
+
+class BrokerRateLimiter {
+  private readonly buckets = new Map<
+    string,
+    { readonly startedAt: number; readonly count: number }
+  >();
+
+  require(
+    request: IncomingMessage,
+    scope: string,
+    limit: number,
+    windowSeconds: number,
+  ): void {
+    const now = Math.floor(Date.now() / 1_000);
+    const key = `${scope}:${clientAddress(request)}`;
+    const current = this.buckets.get(key);
+    if (current === undefined || now - current.startedAt >= windowSeconds) {
+      this.buckets.set(key, { startedAt: now, count: 1 });
+      return;
+    }
+    if (current.count >= limit)
+      throw new AutonomousWalletBrokerError(
+        "replay",
+        "autonomous wallet request rate exceeded",
+      );
+    this.buckets.set(key, { ...current, count: current.count + 1 });
+  }
+}
+
+function clientAddress(request: IncomingMessage): string {
+  const forwarded = request.headers["x-forwarded-for"];
+  const raw = Array.isArray(forwarded) ? forwarded.at(-1) : forwarded;
+  // Caddy appends the direct client as the right-most address. The server is
+  // loopback-only, so this header can only arrive through that local proxy.
+  return (
+    raw?.split(",").at(-1)?.trim() || request.socket.remoteAddress || "unknown"
+  );
+}
+
+function bigintJson(_key: string, value: unknown) {
+  return typeof value === "bigint" ? `${value.toString()}n` : value;
+}
+
+function bigintReviver(_key: string, value: unknown) {
+  return typeof value === "string" && /^\d+n$/.test(value)
+    ? BigInt(value.slice(0, -1))
+    : value;
+}