@absol-labs/agent 0.7.3 → 0.9.0

package/src/wallet/secret-service-probe.ts

@@ -0,0 +1,487 @@
+import { existsSync } from "node:fs";
+import { connect, type Socket } from "node:net";
+
+/**
+ * Detects whether a freedesktop Secret Service provider (gnome-keyring,
+ * KeePassXC, KWallet, ...) is reachable on the D-Bus session bus.
+ *
+ * Why this exists: `@napi-rs/keyring` ships BOTH a `dbus-secret-service`
+ * backend and a `linux-keyutils` backend in the same native module and picks
+ * one at runtime. When no Secret Service provider answers on the session bus
+ * it silently falls through to `linux-keyutils` — the Linux *kernel* keyring,
+ * which lives in RAM and is destroyed on reboot. A credential written there
+ * looks durable (it round-trips across processes and SSH sessions) but is not,
+ * so an agent that provisioned a funded wallet loses its owner key on reboot.
+ *
+ * The keyring module exposes no API to report which backend it resolved, so the
+ * only way to know is to ask the session bus the same question it asks: does
+ * anyone own the well-known name `org.freedesktop.secrets`?
+ *
+ * This talks the D-Bus wire protocol directly over `node:net` (SASL EXTERNAL
+ * handshake, then `org.freedesktop.DBus.Hello` and `NameHasOwner`) so no extra
+ * dependency and no external binary is required. It is deliberately
+ * FAIL-CLOSED: any missing bus, malformed reply, protocol error or timeout
+ * reports "not available", which callers must treat as "not durable".
+ */
+
+const SECRET_SERVICE_BUS_NAME = "org.freedesktop.secrets";
+const DBUS_PATH = "/org/freedesktop/DBus";
+const DBUS_INTERFACE = "org.freedesktop.DBus";
+const DBUS_DESTINATION = "org.freedesktop.DBus";
+
+const MESSAGE_TYPE_METHOD_RETURN = 2;
+const MESSAGE_TYPE_ERROR = 3;
+
+const HEADER_FIELD_ERROR_NAME = 4;
+const HEADER_FIELD_REPLY_SERIAL = 5;
+const HEADER_FIELD_SIGNATURE = 8;
+
+const HELLO_SERIAL = 1;
+const NAME_HAS_OWNER_SERIAL = 2;
+
+export interface SecretServiceProbeResult {
+  readonly available: boolean;
+  /** Human-readable reason, safe to surface in an error message. */
+  readonly detail: string;
+}
+
+export interface ProbeSecretServiceOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly timeoutMs?: number;
+  readonly uid?: number;
+}
+
+function alignTo(value: number, alignment: number): number {
+  const remainder = value % alignment;
+  return remainder === 0 ? value : value + (alignment - remainder);
+}
+
+/** Minimal little-endian D-Bus marshaller. Messages here are a few dozen bytes. */
+class ByteWriter {
+  private readonly bytes: number[] = [];
+
+  get length(): number {
+    return this.bytes.length;
+  }
+
+  byte(value: number): void {
+    this.bytes.push(value & 0xff);
+  }
+
+  align(alignment: number): void {
+    while (this.bytes.length % alignment !== 0) this.bytes.push(0);
+  }
+
+  uint32(value: number): void {
+    this.align(4);
+    this.bytes.push(
+      value & 0xff,
+      (value >>> 8) & 0xff,
+      (value >>> 16) & 0xff,
+      (value >>> 24) & 0xff,
+    );
+  }
+
+  raw(buffer: Buffer): void {
+    for (const byte of buffer) this.bytes.push(byte);
+  }
+
+  /** DBus STRING / OBJECT_PATH: uint32 length, utf8 bytes, NUL. */
+  string(value: string): void {
+    const encoded = Buffer.from(value, "utf8");
+    this.uint32(encoded.length);
+    this.raw(encoded);
+    this.byte(0);
+  }
+
+  /** DBus SIGNATURE: single length byte, ascii bytes, NUL. */
+  signature(value: string): void {
+    const encoded = Buffer.from(value, "ascii");
+    this.byte(encoded.length);
+    this.raw(encoded);
+    this.byte(0);
+  }
+
+  toBuffer(): Buffer {
+    return Buffer.from(this.bytes);
+  }
+}
+
+type HeaderFieldValue =
+  | { readonly type: "s" | "o" | "g"; readonly value: string }
+  | { readonly type: "u"; readonly value: number };
+
+function encodeHeaderFields(
+  fields: ReadonlyArray<readonly [number, HeaderFieldValue]>,
+): Buffer {
+  const writer = new ByteWriter();
+  for (const [code, field] of fields) {
+    // Each ARRAY-of-STRUCT element is 8-byte aligned. The field array always
+    // starts at message offset 16, which is itself 8-aligned, so writing this
+    // buffer standalone produces identical padding.
+    writer.align(8);
+    writer.byte(code);
+    writer.signature(field.type);
+    if (field.type === "u") writer.uint32(field.value);
+    else if (field.type === "g") writer.signature(field.value);
+    else writer.string(field.value);
+  }
+  return writer.toBuffer();
+}
+
+export interface EncodeMethodCallInput {
+  readonly serial: number;
+  readonly path: string;
+  readonly interfaceName: string;
+  readonly member: string;
+  readonly destination: string;
+  readonly signature?: string;
+  readonly body?: Buffer;
+}
+
+/** Exported for unit tests: encodes one METHOD_CALL message. */
+export function encodeMethodCall(input: EncodeMethodCallInput): Buffer {
+  const body = input.body ?? Buffer.alloc(0);
+  const fields: Array<readonly [number, HeaderFieldValue]> = [
+    [1, { type: "o", value: input.path }],
+    [2, { type: "s", value: input.interfaceName }],
+    [3, { type: "s", value: input.member }],
+    [6, { type: "s", value: input.destination }],
+  ];
+  if (input.signature !== undefined) {
+    fields.push([
+      HEADER_FIELD_SIGNATURE,
+      { type: "g", value: input.signature },
+    ]);
+  }
+  const encodedFields = encodeHeaderFields(fields);
+
+  const message = new ByteWriter();
+  message.byte(0x6c); // 'l' — little endian
+  message.byte(1); // METHOD_CALL
+  message.byte(0); // no flags
+  message.byte(1); // protocol version
+  message.uint32(body.length);
+  message.uint32(input.serial);
+  message.uint32(encodedFields.length);
+  message.raw(encodedFields);
+  message.align(8);
+  message.raw(body);
+  return message.toBuffer();
+}
+
+/** Exported for unit tests: encodes a single-STRING message body. */
+export function encodeStringBody(value: string): Buffer {
+  const writer = new ByteWriter();
+  writer.string(value);
+  return writer.toBuffer();
+}
+
+export interface DBusMessage {
+  readonly type: number;
+  readonly serial: number;
+  readonly replySerial?: number;
+  readonly signature?: string;
+  readonly errorName?: string;
+  readonly body: Buffer;
+  readonly littleEndian: boolean;
+}
+
+/**
+ * Exported for unit tests: decodes as many complete messages as `buffer` holds
+ * and returns the undecoded remainder. Throws on a malformed stream.
+ */
+export function decodeMessages(buffer: Buffer): {
+  readonly messages: readonly DBusMessage[];
+  readonly rest: Buffer;
+} {
+  const messages: DBusMessage[] = [];
+  let offset = 0;
+  while (buffer.length - offset >= 16) {
+    const start = offset;
+    const endian = buffer[start];
+    if (endian !== 0x6c && endian !== 0x42) {
+      throw new Error("invalid D-Bus endianness marker");
+    }
+    const littleEndian = endian === 0x6c;
+    const readUint32 = (at: number): number =>
+      littleEndian ? buffer.readUInt32LE(at) : buffer.readUInt32BE(at);
+    const type = buffer[start + 1]!;
+    const bodyLength = readUint32(start + 4);
+    const serial = readUint32(start + 8);
+    const fieldsLength = readUint32(start + 12);
+    const bodyOffset = alignTo(16 + fieldsLength, 8);
+    const total = bodyOffset + bodyLength;
+    if (buffer.length - start < total) break;
+
+    let replySerial: number | undefined;
+    let signature: string | undefined;
+    let errorName: string | undefined;
+    const fieldsEnd = 16 + fieldsLength;
+    let cursor = 16;
+    while (cursor < fieldsEnd) {
+      cursor = alignTo(cursor, 8);
+      if (cursor >= fieldsEnd) break;
+      const code = buffer[start + cursor]!;
+      cursor += 1;
+      const typeLength = buffer[start + cursor]!;
+      cursor += 1;
+      const fieldType = buffer.toString(
+        "ascii",
+        start + cursor,
+        start + cursor + typeLength,
+      );
+      cursor += typeLength + 1;
+      if (fieldType === "u") {
+        cursor = alignTo(cursor, 4);
+        const value = readUint32(start + cursor);
+        cursor += 4;
+        if (code === HEADER_FIELD_REPLY_SERIAL) replySerial = value;
+      } else if (fieldType === "s" || fieldType === "o") {
+        cursor = alignTo(cursor, 4);
+        const length = readUint32(start + cursor);
+        cursor += 4;
+        const value = buffer.toString(
+          "utf8",
+          start + cursor,
+          start + cursor + length,
+        );
+        cursor += length + 1;
+        if (code === HEADER_FIELD_ERROR_NAME) errorName = value;
+      } else if (fieldType === "g") {
+        const length = buffer[start + cursor]!;
+        cursor += 1;
+        const value = buffer.toString(
+          "ascii",
+          start + cursor,
+          start + cursor + length,
+        );
+        cursor += length + 1;
+        if (code === HEADER_FIELD_SIGNATURE) signature = value;
+      } else {
+        throw new Error(`unsupported D-Bus header field type "${fieldType}"`);
+      }
+      if (cursor > fieldsEnd) {
+        throw new Error("malformed D-Bus header fields");
+      }
+    }
+
+    messages.push({
+      type,
+      serial,
+      ...(replySerial === undefined ? {} : { replySerial }),
+      ...(signature === undefined ? {} : { signature }),
+      ...(errorName === undefined ? {} : { errorName }),
+      body: buffer.subarray(start + bodyOffset, start + total),
+      littleEndian,
+    });
+    offset = start + total;
+  }
+  return { messages, rest: buffer.subarray(offset) };
+}
+
+type BusAddress =
+  | { readonly kind: "path"; readonly path: string }
+  | { readonly kind: "error"; readonly detail: string };
+
+/** Exported for unit tests. */
+export function resolveSessionBusPath(env: NodeJS.ProcessEnv): BusAddress {
+  const address = env.DBUS_SESSION_BUS_ADDRESS;
+  if (typeof address === "string" && address.trim() !== "") {
+    for (const entry of address.split(";")) {
+      const trimmed = entry.trim();
+      if (!trimmed.startsWith("unix:")) continue;
+      const parameters = new Map<string, string>();
+      for (const pair of trimmed.slice("unix:".length).split(",")) {
+        const separator = pair.indexOf("=");
+        if (separator > 0) {
+          parameters.set(pair.slice(0, separator), pair.slice(separator + 1));
+        }
+      }
+      const path = parameters.get("path");
+      if (path !== undefined && path !== "") return { kind: "path", path };
+      const abstract = parameters.get("abstract");
+      if (abstract !== undefined && abstract !== "") {
+        // Linux abstract namespace sockets are addressed with a leading NUL.
+        return { kind: "path", path: `\0${abstract}` };
+      }
+    }
+    return {
+      kind: "error",
+      detail: `DBUS_SESSION_BUS_ADDRESS has no usable unix transport (${address})`,
+    };
+  }
+  const runtimeDirectory = env.XDG_RUNTIME_DIR;
+  if (typeof runtimeDirectory === "string" && runtimeDirectory !== "") {
+    const candidate = `${runtimeDirectory.replace(/\/$/, "")}/bus`;
+    if (existsSync(candidate)) return { kind: "path", path: candidate };
+    return {
+      kind: "error",
+      detail: `no D-Bus session socket at ${candidate}`,
+    };
+  }
+  return {
+    kind: "error",
+    detail:
+      "no D-Bus session bus (DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR are unset)",
+  };
+}
+
+/**
+ * Asks the D-Bus session bus whether `org.freedesktop.secrets` has an owner.
+ * Never throws; every failure path resolves to `available: false`.
+ */
+export async function probeSecretServiceAvailable(
+  options: ProbeSecretServiceOptions = {},
+): Promise<SecretServiceProbeResult> {
+  const env = options.env ?? process.env;
+  const timeoutMs = options.timeoutMs ?? 2_000;
+  const address = resolveSessionBusPath(env);
+  if (address.kind === "error") {
+    return { available: false, detail: address.detail };
+  }
+  const uid =
+    options.uid ??
+    (typeof process.getuid === "function" ? process.getuid() : 0);
+
+  return new Promise<SecretServiceProbeResult>((resolve) => {
+    let socket: Socket;
+    try {
+      socket = connect({ path: address.path });
+    } catch (error) {
+      resolve({
+        available: false,
+        detail: `could not connect to the D-Bus session bus: ${describe(error)}`,
+      });
+      return;
+    }
+    let settled = false;
+    let authenticated = false;
+    let buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+
+    const finish = (result: SecretServiceProbeResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      finish({
+        available: false,
+        detail: `D-Bus session bus did not answer within ${timeoutMs}ms`,
+      });
+    }, timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    socket.on("error", (error) => {
+      finish({
+        available: false,
+        detail: `D-Bus session bus connection failed: ${describe(error)}`,
+      });
+    });
+    socket.on("close", () => {
+      finish({
+        available: false,
+        detail: "D-Bus session bus closed the connection before replying",
+      });
+    });
+    socket.on("connect", () => {
+      // SASL EXTERNAL: the NUL byte, then the uid as ASCII hex.
+      const identity = Buffer.from(String(uid), "ascii").toString("hex");
+      socket.write(`\0AUTH EXTERNAL ${identity}\r\n`);
+    });
+    socket.on("data", (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      if (!authenticated) {
+        const terminator = buffer.indexOf("\r\n");
+        if (terminator < 0) return;
+        const line = buffer.toString("ascii", 0, terminator);
+        buffer = buffer.subarray(terminator + 2);
+        if (!line.startsWith("OK")) {
+          finish({
+            available: false,
+            detail: `D-Bus session bus rejected authentication (${line})`,
+          });
+          return;
+        }
+        authenticated = true;
+        socket.write("BEGIN\r\n");
+        socket.write(
+          encodeMethodCall({
+            serial: HELLO_SERIAL,
+            path: DBUS_PATH,
+            interfaceName: DBUS_INTERFACE,
+            member: "Hello",
+            destination: DBUS_DESTINATION,
+          }),
+        );
+        socket.write(
+          encodeMethodCall({
+            serial: NAME_HAS_OWNER_SERIAL,
+            path: DBUS_PATH,
+            interfaceName: DBUS_INTERFACE,
+            member: "NameHasOwner",
+            destination: DBUS_DESTINATION,
+            signature: "s",
+            body: encodeStringBody(SECRET_SERVICE_BUS_NAME),
+          }),
+        );
+        if (buffer.length === 0) return;
+      }
+      let decoded: ReturnType<typeof decodeMessages>;
+      try {
+        decoded = decodeMessages(buffer);
+      } catch (error) {
+        finish({
+          available: false,
+          detail: `could not decode the D-Bus reply: ${describe(error)}`,
+        });
+        return;
+      }
+      buffer = decoded.rest;
+      for (const message of decoded.messages) {
+        if (message.replySerial !== NAME_HAS_OWNER_SERIAL) continue;
+        if (message.type === MESSAGE_TYPE_ERROR) {
+          finish({
+            available: false,
+            detail: `D-Bus NameHasOwner failed (${message.errorName ?? "unknown error"})`,
+          });
+          return;
+        }
+        if (
+          message.type !== MESSAGE_TYPE_METHOD_RETURN ||
+          message.signature !== "b" ||
+          message.body.length < 4
+        ) {
+          finish({
+            available: false,
+            detail: "D-Bus returned an unexpected NameHasOwner reply",
+          });
+          return;
+        }
+        const owned =
+          (message.littleEndian
+            ? message.body.readUInt32LE(0)
+            : message.body.readUInt32BE(0)) !== 0;
+        finish(
+          owned
+            ? {
+                available: true,
+                detail: `${SECRET_SERVICE_BUS_NAME} is owned on the D-Bus session bus`,
+              }
+            : {
+                available: false,
+                detail: `no process owns ${SECRET_SERVICE_BUS_NAME} on the D-Bus session bus`,
+              },
+        );
+        return;
+      }
+    });
+  });
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/zktls/reclaim-js-sdk.ts

@@ -0,0 +1,50 @@
+/**
+ * `@reclaimprotocol/js-sdk` is an OPTIONAL peer dependency: only consumers that
+ * actually generate/verify zkTLS delivery proofs (T2, issue #24) need it, and it
+ * carries a large transitive graph. The top-level "@absol-labs/agent" barrel
+ * DOES re-export the zkTLS modules, so those modules must import the SDK's
+ * TYPES only (`import type`, erased at compile time) and load the runtime module
+ * lazily through this loader at the point of first use.
+ *
+ * Deliberately NOT a top-level `await import(...)` (the pattern used by
+ * `../frameworks/langchain.ts`): that module is not barrel-reachable, this one
+ * is, and a top-level await would re-introduce the hard dependency at
+ * barrel-import time.
+ */
+
+type ReclaimJsSdkModule = typeof import("@reclaimprotocol/js-sdk");
+
+let modulePromise: Promise<ReclaimJsSdkModule> | undefined;
+
+/** Memoized lazy load with an actionable missing-peer error. */
+export async function loadReclaimJsSdk(): Promise<ReclaimJsSdkModule> {
+  modulePromise ??= import("@reclaimprotocol/js-sdk").catch(
+    (error: unknown) => {
+      throw new Error(
+        "@absol-labs/agent zkTLS delivery-proof support requires the optional peer dependency '@reclaimprotocol/js-sdk'. Install it with `npm install @reclaimprotocol/js-sdk`.",
+        { cause: error },
+      );
+    },
+  );
+  return await modulePromise;
+}
+
+/**
+ * `@reclaimprotocol/zk-fetch` is the companion optional peer used to PRODUCE
+ * proofs (the SDK above verifies them). Same contract, same actionable error.
+ */
+type ReclaimZkFetchModule = typeof import("@reclaimprotocol/zk-fetch");
+
+let zkFetchModulePromise: Promise<ReclaimZkFetchModule> | undefined;
+
+export async function loadReclaimZkFetch(): Promise<ReclaimZkFetchModule> {
+  zkFetchModulePromise ??= import("@reclaimprotocol/zk-fetch").catch(
+    (error: unknown) => {
+      throw new Error(
+        "@absol-labs/agent zkTLS delivery-proof support requires the optional peer dependency '@reclaimprotocol/zk-fetch'. Install it with `npm install @reclaimprotocol/zk-fetch`.",
+        { cause: error },
+      );
+    },
+  );
+  return await zkFetchModulePromise;
+}

package/src/zktls/reclaim.ts

@@ -1,13 +1,16 @@
-import {
-  getHttpProviderClaimParamsFromProof,
-  getProviderHashRequirementsFromSpec,
+// `@reclaimprotocol/js-sdk` is an OPTIONAL peer dependency: TYPES only here
+// (erased at compile time), runtime values via `loadReclaimJsSdk()` at the point
+// of first use. See ./reclaim-js-sdk.ts.
+import type {
   verifyProof,
-  type Proof as ReclaimProtocolProof,
-  type RequestSpec,
-  type VerifyProofResult,
+  Proof as ReclaimProtocolProof,
+  RequestSpec,
+  VerifyProofResult,
 } from "@reclaimprotocol/js-sdk";
 import { z } from "zod";
 
+import { loadReclaimJsSdk, loadReclaimZkFetch } from "./reclaim-js-sdk.js";
+
 const addressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
 const bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
 const httpMethodSchema = z.enum(["GET", "POST", "PUT"]);
@@ -172,7 +175,14 @@ const reclaimProofInputSchema = z.object({
 export class ReclaimConsumerProofService implements ConsumerDeliveryProofService {
   private readonly client: ReclaimClientLike;
   private readonly config: ReclaimProofServiceConfig;
-  private readonly verifyProofImpl: VerifyProofFn;
+  /**
+   * Caller-supplied verifier, if any. NOT defaulted in the constructor: the real
+   * `verifyProof` lives in the optional peer `@reclaimprotocol/js-sdk`, which is
+   * loaded lazily at first use so that merely constructing this service — or
+   * importing the package barrel — never requires the peer to be installed.
+   * Resolved in {@link resolveVerifyProof}.
+   */
+  private readonly verifyProofOverride: VerifyProofFn | undefined;
 
   constructor(
     config: ReclaimProofServiceConfig,
@@ -194,7 +204,16 @@ export class ReclaimConsumerProofService implements ConsumerDeliveryProofService
       this.config.applicationSecret,
       this.config.logs ?? false,
     );
-    this.verifyProofImpl = options.verifyProof ?? verifyProof;
+    this.verifyProofOverride = options.verifyProof;
+  }
+
+  /**
+   * The verifier to use: a caller-supplied override, else the optional peer's
+   * `verifyProof`, loaded on first use with an actionable missing-peer error.
+   */
+  private async resolveVerifyProof(): Promise<VerifyProofFn> {
+    if (this.verifyProofOverride !== undefined) return this.verifyProofOverride;
+    return (await loadReclaimJsSdk()).verifyProof;
   }
 
   async proveConsumedHttpsResponse(
@@ -244,8 +263,15 @@ export class ReclaimConsumerProofService implements ConsumerDeliveryProofService
       );
     }
 
-    const verification = await this.verifyProofImpl(proof, {
-      ...getProviderHashRequirementsFromSpec({
+    // Both the verifier and the provider-hash helper live in the optional peer;
+    // load it once here rather than importing it at module scope.
+    const [verifyProofFn, reclaimSdk] = await Promise.all([
+      this.resolveVerifyProof(),
+      loadReclaimJsSdk(),
+    ]);
+
+    const verification = await verifyProofFn(proof, {
+      ...reclaimSdk.getProviderHashRequirementsFromSpec({
         requests: [toRequestSpec(parsed, method)],
       }),
       ...(parsed.useTee === true
@@ -271,25 +297,33 @@ export class ReclaimConsumerProofService implements ConsumerDeliveryProofService
       );
     }
 
-    const request = getHttpProviderClaimParamsFromProof(proof);
+    // Same optional peer, already memoized by the loader above.
+    const request = reclaimSdk.getHttpProviderClaimParamsFromProof(proof);
+    type ClaimParams = ReturnType<
+      typeof reclaimSdk.getHttpProviderClaimParamsFromProof
+    >;
     return {
       proof,
       request: {
         url: request.url,
         method: request.method as "GET" | "POST" | "PUT",
         body: request.body === "" ? null : (request.body ?? null),
-        responseMatches: request.responseMatches.map((match) => ({
-          value: match.value,
-          type: match.type,
-          invert: match.invert,
-          isOptional: match.isOptional,
-        })),
-        responseRedactions: request.responseRedactions.map((redaction) => ({
-          regex: redaction.regex,
-          jsonPath: redaction.jsonPath,
-          xPath: redaction.xPath,
-          hash: redaction.hash,
-        })),
+        responseMatches: request.responseMatches.map(
+          (match: ClaimParams["responseMatches"][number]) => ({
+            value: match.value,
+            type: match.type,
+            invert: match.invert,
+            isOptional: match.isOptional,
+          }),
+        ),
+        responseRedactions: request.responseRedactions.map(
+          (redaction: ClaimParams["responseRedactions"][number]) => ({
+            regex: redaction.regex,
+            jsonPath: redaction.jsonPath,
+            xPath: redaction.xPath,
+            hash: redaction.hash,
+          }),
+        ),
       },
       verification: {
         context: trusted.context,