@absol-labs/agent 0.1.0

package/src/mandates/env.ts

@@ -0,0 +1,222 @@
+import {
+  getAddress,
+  isAddress,
+  keccak256,
+  stringToHex,
+  type Account,
+} from "viem";
+import { z } from "zod";
+
+import {
+  createSpendMandateTypedData,
+  signedSpendMandateSchema,
+  type SignedSpendMandate,
+  type SpendMandate,
+} from "./mandate.js";
+
+/**
+ * Server-side spend-mandate provisioning.
+ *
+ * The MCP/x402 fund-moving surface is driven by autonomous callers (an LLM over
+ * MCP, a paying agent over x402) that CANNOT produce an EIP-712 signature. The
+ * spend mandate is therefore NOT a per-call argument — it is configured once, at
+ * the server's construction, exactly like the AgentKit action provider's
+ * `signedMandate`. The deploying operator declares the spend caps via env and the
+ * server self-signs the mandate from its OWN wallet (the wallet that opens and
+ * funds the streams is the mandate owner — signing your own spend ceiling is the
+ * correct trust relationship).
+ *
+ * Fail-closed: a fund-moving server with NO configured caps refuses to sign a
+ * mandate. There is no implicit "unbounded" mandate.
+ */
+
+export class ServerMandateConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServerMandateConfigError";
+  }
+}
+
+const decimalStringSchema = z
+  .string()
+  .regex(
+    /^(0|[1-9]\d*)$/,
+    "must be a base-10 integer string (USDC atomic units, 6 decimals)",
+  );
+const positiveIntSchema = z.coerce.number().int().positive();
+
+const mandateEnvSchema = z.object({
+  METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC: decimalStringSchema,
+  METRIK_AGENT_MANDATE_MAX_TOTAL_USDC: decimalStringSchema,
+  METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC: decimalStringSchema,
+  METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS: positiveIntSchema,
+  METRIK_AGENT_MANDATE_ALLOWED_OPERATORS: z.string().optional(),
+  METRIK_AGENT_MANDATE_TTL_SECONDS: positiveIntSchema.optional(),
+});
+
+/** Default mandate lifetime when `METRIK_AGENT_MANDATE_TTL_SECONDS` is unset. */
+export const DEFAULT_SERVER_MANDATE_TTL_SECONDS = 24 * 60 * 60;
+
+export interface ServerMandateCaps {
+  readonly maxPerStreamUsdc: bigint;
+  readonly maxTotalUsdc: bigint;
+  readonly maxRatePerSecondUsdc: bigint;
+  readonly maxDurationSeconds: number;
+  readonly allowedOperators: readonly `0x${string}`[];
+  readonly ttlSeconds: number;
+}
+
+/**
+ * Parses the server mandate caps from env. Returns `null` when NONE of the
+ * `METRIK_AGENT_MANDATE_*` variables are set (so a caller can decide whether a
+ * mandate is required in that deployment). Throws {@link ServerMandateConfigError}
+ * when the caps are partially configured or malformed — fail closed, never
+ * silently fall back to an unbounded mandate.
+ */
+export function parseServerMandateCapsEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ServerMandateCaps | null {
+  const anySet = [
+    env.METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC,
+    env.METRIK_AGENT_MANDATE_MAX_TOTAL_USDC,
+    env.METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC,
+    env.METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS,
+    env.METRIK_AGENT_MANDATE_ALLOWED_OPERATORS,
+    env.METRIK_AGENT_MANDATE_TTL_SECONDS,
+  ].some((value) => value !== undefined);
+  if (!anySet) {
+    return null;
+  }
+
+  const parsed = mandateEnvSchema.safeParse(env);
+  if (!parsed.success) {
+    throw new ServerMandateConfigError(
+      `invalid server mandate configuration: ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".")} ${issue.message}`)
+        .join("; ")}`,
+    );
+  }
+
+  const allowedOperators = (
+    parsed.data.METRIK_AGENT_MANDATE_ALLOWED_OPERATORS ?? ""
+  )
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  for (const operator of allowedOperators) {
+    if (!isAddress(operator)) {
+      throw new ServerMandateConfigError(
+        `METRIK_AGENT_MANDATE_ALLOWED_OPERATORS contains a non-address entry: ${operator}`,
+      );
+    }
+  }
+
+  const maxTotalUsdc = BigInt(parsed.data.METRIK_AGENT_MANDATE_MAX_TOTAL_USDC);
+  const maxPerStreamUsdc = BigInt(
+    parsed.data.METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC,
+  );
+  if (maxPerStreamUsdc > maxTotalUsdc) {
+    throw new ServerMandateConfigError(
+      "METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC cannot exceed METRIK_AGENT_MANDATE_MAX_TOTAL_USDC",
+    );
+  }
+
+  return {
+    maxPerStreamUsdc,
+    maxTotalUsdc,
+    maxRatePerSecondUsdc: BigInt(
+      parsed.data.METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC,
+    ),
+    maxDurationSeconds: parsed.data.METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS,
+    allowedOperators: allowedOperators.map(
+      (operator) => getAddress(operator) as `0x${string}`,
+    ),
+    ttlSeconds:
+      parsed.data.METRIK_AGENT_MANDATE_TTL_SECONDS ??
+      DEFAULT_SERVER_MANDATE_TTL_SECONDS,
+  };
+}
+
+export interface SignServerMandateOptions {
+  readonly chainId: number;
+  /** Unix seconds the mandate is issued at. Defaults to the wall clock. */
+  readonly nowSeconds?: number;
+}
+
+/**
+ * Deterministic mandate id derived from the owner, caps, chain, and issuance
+ * time. Stable for identical inputs within the same second, so a restarted
+ * server with the same config and a wired revocation store can be revoked by id.
+ */
+function deriveMandateId(
+  owner: `0x${string}`,
+  mandate: SpendMandate,
+  chainId: number,
+  issuedAt: number,
+): `0x${string}` {
+  const canonical = [
+    owner.toLowerCase(),
+    chainId,
+    issuedAt,
+    mandate.expiresAt,
+    mandate.maxPerStreamUsdc.toString(),
+    mandate.maxTotalUsdc.toString(),
+    mandate.maxRatePerSecondUsdc.toString(),
+    mandate.maxDurationSeconds,
+    (mandate.allowedOperators ?? []).map((op) => op.toLowerCase()).join(","),
+  ].join("|");
+  return keccak256(stringToHex(canonical));
+}
+
+/**
+ * Self-signs a spend mandate from the server's own wallet, bounded by the
+ * configured caps. The signing account MUST be the account that will fund the
+ * streams (its address becomes the mandate `owner`, which every downstream
+ * `checkMandate` recovers the signature against).
+ */
+export async function signServerMandate(
+  account: Account,
+  caps: ServerMandateCaps,
+  options: SignServerMandateOptions,
+): Promise<SignedSpendMandate> {
+  if (account.signTypedData === undefined) {
+    throw new ServerMandateConfigError(
+      "signing account does not support signTypedData; cannot self-sign a server mandate",
+    );
+  }
+
+  const owner = getAddress(account.address) as `0x${string}`;
+  const issuedAt = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const expiresAt = issuedAt + caps.ttlSeconds;
+
+  const mandate: SpendMandate = {
+    maxPerStreamUsdc: caps.maxPerStreamUsdc,
+    maxTotalUsdc: caps.maxTotalUsdc,
+    maxRatePerSecondUsdc: caps.maxRatePerSecondUsdc,
+    maxDurationSeconds: caps.maxDurationSeconds,
+    ...(caps.allowedOperators.length > 0
+      ? { allowedOperators: [...caps.allowedOperators] }
+      : {}),
+    expiresAt,
+  };
+
+  const mandateId = deriveMandateId(owner, mandate, options.chainId, issuedAt);
+  const typedData = createSpendMandateTypedData({
+    mandateId,
+    owner,
+    chainId: options.chainId,
+    issuedAt,
+    mandate,
+  });
+
+  const signature = await account.signTypedData(typedData);
+
+  return signedSpendMandateSchema.parse({
+    mandateId,
+    owner,
+    chainId: options.chainId,
+    issuedAt,
+    mandate,
+    signature,
+  });
+}

package/src/mandates/mandate.ts

@@ -0,0 +1,280 @@
+import {
+  encodeAbiParameters,
+  getAddress,
+  isAddress,
+  isHex,
+  keccak256,
+  recoverTypedDataAddress,
+} from "viem";
+import { z } from "zod";
+
+/**
+ * Spend mandate — the guardrail that lets an AI agent transact autonomously while
+ * its owner stays in control. A signed mandate caps how much, how fast, for how
+ * long, and with whom an agent may open verified payment streams.
+ */
+
+const addressSchema = z
+  .string()
+  .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 66,
+    "must be bytes32 hex",
+  );
+const signatureSchema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 132,
+    "must be a 65-byte signature",
+  );
+
+export const spendMandateSchema = z.object({
+  /** Max deposit for any single stream. */
+  maxPerStreamUsdc: z.bigint().positive(),
+  /** Cumulative cap across all streams opened under this mandate. */
+  maxTotalUsdc: z.bigint().positive(),
+  /** Max ratePerSecond an agent may agree to. */
+  maxRatePerSecondUsdc: z.bigint().positive(),
+  /** Max stream duration in seconds. */
+  maxDurationSeconds: z.number().int().positive(),
+  /** Allowed operator addresses; empty/undefined = any operator. */
+  allowedOperators: z.array(addressSchema).optional(),
+  /** Mandate expiry, unix seconds. */
+  expiresAt: z.number().int().positive(),
+});
+
+export type SpendMandate = z.infer<typeof spendMandateSchema>;
+
+export const signedSpendMandateSchema = z.object({
+  mandateId: bytes32Schema,
+  owner: addressSchema,
+  chainId: z.number().int().positive(),
+  issuedAt: z.number().int().nonnegative(),
+  mandate: spendMandateSchema,
+  signature: signatureSchema,
+});
+
+export type SignedSpendMandate = z.infer<typeof signedSpendMandateSchema>;
+
+export interface HireRequest {
+  operator: `0x${string}`;
+  budgetUsdc: bigint;
+  ratePerSecondUsdc: bigint;
+  maxDurationSeconds: number;
+}
+
+export interface MandateDecision {
+  allowed: boolean;
+  /** Machine-readable denial reason; undefined when allowed. */
+  reason?:
+    | "invalid-signature"
+    | "mandate-revoked"
+    | "mandate-expired"
+    | "exceeds-per-stream-cap"
+    | "exceeds-total-cap"
+    | "exceeds-rate-cap"
+    | "exceeds-duration-cap"
+    | "operator-not-allowed";
+}
+
+export interface MandateVerificationContext {
+  readonly nowSeconds: number;
+  readonly revokedMandateIds?: Iterable<`0x${string}`>;
+}
+
+export const spendMandateDomain = {
+  name: "MetrikAgentMandate",
+  version: "1",
+} as const;
+
+export const spendMandateTypedData = {
+  SpendMandate: [
+    { name: "mandateId", type: "bytes32" },
+    { name: "owner", type: "address" },
+    { name: "issuedAt", type: "uint64" },
+    { name: "expiresAt", type: "uint64" },
+    { name: "maxPerStreamUsdc", type: "uint256" },
+    { name: "maxTotalUsdc", type: "uint256" },
+    { name: "maxRatePerSecondUsdc", type: "uint256" },
+    { name: "maxDurationSeconds", type: "uint64" },
+    { name: "allowedOperatorsHash", type: "bytes32" },
+  ],
+} as const;
+
+const ALLOW: MandateDecision = { allowed: true };
+
+export function createSpendMandateTypedData(
+  input: Omit<SignedSpendMandate, "signature">,
+) {
+  const parsed = signedSpendMandateSchema
+    .omit({ signature: true })
+    .parse(input);
+
+  return {
+    domain: {
+      ...spendMandateDomain,
+      chainId: parsed.chainId,
+    },
+    primaryType: "SpendMandate" as const,
+    types: spendMandateTypedData,
+    message: {
+      mandateId: parsed.mandateId as `0x${string}`,
+      owner: getAddress(parsed.owner),
+      issuedAt: BigInt(parsed.issuedAt),
+      expiresAt: BigInt(parsed.mandate.expiresAt),
+      maxPerStreamUsdc: parsed.mandate.maxPerStreamUsdc,
+      maxTotalUsdc: parsed.mandate.maxTotalUsdc,
+      maxRatePerSecondUsdc: parsed.mandate.maxRatePerSecondUsdc,
+      maxDurationSeconds: BigInt(parsed.mandate.maxDurationSeconds),
+      allowedOperatorsHash: hashAllowedOperators(
+        parsed.mandate.allowedOperators,
+      ),
+    },
+  };
+}
+
+export async function verifySignedMandate(
+  signedMandate: SignedSpendMandate,
+  context: MandateVerificationContext,
+): Promise<MandateDecision> {
+  const parsedMandate = signedSpendMandateSchema.parse(signedMandate);
+  const recovered = await recoverTypedDataAddress({
+    ...createSpendMandateTypedData(parsedMandate),
+    signature: parsedMandate.signature as `0x${string}`,
+  }).catch(() => null);
+
+  if (
+    recovered === null ||
+    recovered.toLowerCase() !== parsedMandate.owner.toLowerCase()
+  ) {
+    return { allowed: false, reason: "invalid-signature" };
+  }
+
+  if (
+    isRevoked(
+      parsedMandate.mandateId as `0x${string}`,
+      context.revokedMandateIds,
+    )
+  ) {
+    return { allowed: false, reason: "mandate-revoked" };
+  }
+
+  if (context.nowSeconds >= parsedMandate.mandate.expiresAt) {
+    return { allowed: false, reason: "mandate-expired" };
+  }
+
+  return ALLOW;
+}
+
+/**
+ * Signature-only authorization for BUYER-RECOVERY actions (close / reclaim).
+ *
+ * Close and reclaim only ever return unspent funds to the buyer or stop further
+ * payment — they never move funds to a seller. Gating them on mandate expiry or
+ * revocation would let a lapsed/revoked mandate strand the buyer's OWN funds in
+ * escrow, defeating the auto-refund guarantee. So these actions verify only that
+ * the mandate is authentically owner-signed (proving buyer intent); they do NOT
+ * check expiry, revocation, or spend caps. Fail-closed on a bad signature.
+ */
+export async function verifyMandateOwnerSignature(
+  signedMandate: SignedSpendMandate,
+): Promise<MandateDecision> {
+  const parsed = signedSpendMandateSchema.parse(signedMandate);
+  const recovered = await recoverTypedDataAddress({
+    ...createSpendMandateTypedData(parsed),
+    signature: parsed.signature as `0x${string}`,
+  }).catch(() => null);
+
+  if (
+    recovered === null ||
+    recovered.toLowerCase() !== parsed.owner.toLowerCase()
+  ) {
+    return { allowed: false, reason: "invalid-signature" };
+  }
+
+  return ALLOW;
+}
+
+/**
+ * Full mandate authorization check. A mandate must be owner-signed, unrevoked,
+ * and unexpired before the policy engine runs. Fail-closed: any breach denies.
+ */
+export async function checkMandate(
+  signedMandate: SignedSpendMandate,
+  request: HireRequest,
+  spentSoFarUsdc: bigint,
+  context: MandateVerificationContext,
+): Promise<MandateDecision> {
+  const signatureDecision = await verifySignedMandate(signedMandate, context);
+  if (!signatureDecision.allowed) {
+    return signatureDecision;
+  }
+
+  return checkMandatePolicy(
+    signedMandate.mandate,
+    request,
+    spentSoFarUsdc,
+    context.nowSeconds,
+  );
+}
+
+/**
+ * Pure policy check over an already-verified mandate.
+ */
+export function checkMandatePolicy(
+  mandate: SpendMandate,
+  request: HireRequest,
+  spentSoFarUsdc: bigint,
+  nowSeconds: number,
+): MandateDecision {
+  if (nowSeconds >= mandate.expiresAt)
+    return { allowed: false, reason: "mandate-expired" };
+  if (request.budgetUsdc > mandate.maxPerStreamUsdc) {
+    return { allowed: false, reason: "exceeds-per-stream-cap" };
+  }
+  if (spentSoFarUsdc + request.budgetUsdc > mandate.maxTotalUsdc) {
+    return { allowed: false, reason: "exceeds-total-cap" };
+  }
+  if (request.ratePerSecondUsdc > mandate.maxRatePerSecondUsdc) {
+    return { allowed: false, reason: "exceeds-rate-cap" };
+  }
+  if (request.maxDurationSeconds > mandate.maxDurationSeconds) {
+    return { allowed: false, reason: "exceeds-duration-cap" };
+  }
+  if (
+    mandate.allowedOperators &&
+    mandate.allowedOperators.length > 0 &&
+    !mandate.allowedOperators.some(
+      (operator) => operator.toLowerCase() === request.operator.toLowerCase(),
+    )
+  ) {
+    return { allowed: false, reason: "operator-not-allowed" };
+  }
+  return ALLOW;
+}
+
+function hashAllowedOperators(
+  operators: readonly string[] | undefined,
+): `0x${string}` {
+  const normalized = (operators ?? []).map((operator) => getAddress(operator));
+  return keccak256(encodeAbiParameters([{ type: "address[]" }], [normalized]));
+}
+
+function isRevoked(
+  mandateId: `0x${string}`,
+  revokedMandateIds: Iterable<`0x${string}`> | undefined,
+): boolean {
+  if (revokedMandateIds === undefined) {
+    return false;
+  }
+
+  for (const revokedMandateId of revokedMandateIds) {
+    if (revokedMandateId.toLowerCase() === mandateId.toLowerCase()) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/mcp/http-server.ts

@@ -0,0 +1,38 @@
+import { startHostedMcpHttpServerFromEnv } from "./http.js";
+
+/**
+ * Runnable entrypoint for the hosted, multi-tenant MCP server over Streamable
+ * HTTP. Reads all configuration from the environment (see
+ * {@link parseHostedMcpServerConfig}) and refuses to start when no tenant
+ * tokens are configured (fail-closed).
+ *
+ * Start with: `pnpm mcp:http` (or `node dist/mcp/http-server.js`).
+ */
+async function main(): Promise<void> {
+  const server = await startHostedMcpHttpServerFromEnv();
+  const path = process.env.METRIK_MCP_PATH ?? "/mcp";
+  const host = process.env.METRIK_MCP_HOST ?? "0.0.0.0";
+  // Config only — never log tokens or wallet secrets.
+  console.error(
+    `[metrik-agent-mcp-http] listening on http://${host}:${server.boundPort}${path}`,
+  );
+
+  const shutdown = (signal: string) => {
+    console.error(`[metrik-agent-mcp-http] ${signal} received — shutting down`);
+    server
+      .close()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+main().catch((error) => {
+  console.error(
+    error instanceof Error
+      ? error.message
+      : "failed to start hosted MCP server",
+  );
+  process.exit(1);
+});