@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex/cloud/internal.mjs

@@ -0,0 +1,533 @@
+import { InvalidResponseError } from "./Errors.mjs";
+
+const CLOUD_ACCOUNT_PROVIDERS = Object.freeze([
+  "github",
+  "gmail",
+  "gdrive",
+  "gcalendar",
+  "gtasks",
+  "gdocs",
+  "gsheets",
+  "gslides",
+  "gcontacts",
+  "slack",
+  "x",
+  "chatgpt",
+]);
+const MCP_CONNECTION_ID = /^[A-Za-z0-9_-]{43}$/;
+const AGENT_CONVERSATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const CATALOG_DIGEST = /^0x[0-9a-f]{64}$/;
+const HOST_PRINCIPAL_ID = /^[A-Za-z0-9_-]{43}$/;
+
+export function connectionFromWire(value) {
+  const wire = object(value, "connection");
+  const grant = object(wire.grant, "connection.grant");
+  const accessKey = wire.access_key === undefined
+    ? undefined
+    : object(wire.access_key, "connection.access_key");
+  const authorization = authorizationMode(wire.authorization_mode ?? (accessKey ? "access_key" : "hosted"));
+  const mpp = wire.mpp === undefined ? undefined : object(wire.mpp, "connection.mpp");
+  const hasAccount = wire.account_address !== undefined;
+  const hasPrincipal = wire.principal !== undefined;
+  if (hasAccount === hasPrincipal) {
+    throw new InvalidResponseError("connection must contain exactly one wallet or host principal owner");
+  }
+  const owner = hasPrincipal
+    ? { principal: hostPrincipal(wire.principal, "connection.principal") }
+    : { accountAddress: hex(wire.account_address, "connection.account_address") };
+  if (hasPrincipal && authorization !== "hosted") {
+    throw new InvalidResponseError("host principal connections require hosted authorization");
+  }
+  if (authorization === "hosted" && (accessKey !== undefined || mpp !== undefined)) {
+    throw new InvalidResponseError("hosted connections cannot contain access-key or MPP authority");
+  }
+  if (authorization === "access_key" && (accessKey === undefined || mpp === undefined)) {
+    throw new InvalidResponseError("access-key connections require access-key and MPP authority");
+  }
+  const capabilities = strings(grant.capabilities, "connection.grant.capabilities");
+  const grantMcpConnections = mcpConnections(
+    grant.mcp_connections,
+    "connection.grant.mcp_connections",
+  );
+  requireExactMcpProjection(
+    capabilities,
+    grantMcpConnections,
+    "connection.grant",
+  );
+  const grantConnectors = connectors(capabilities, "connection.grant.capabilities");
+  const grantConnectorConnections = connectorConnections(
+    grant.connector_connections,
+    grantConnectors,
+    "connection.grant.connector_connections",
+  );
+  return Object.freeze({
+    ...owner,
+    agentId: string(wire.agent_id, "connection.agent_id"),
+    grant: Object.freeze({
+      id: hex(grant.id, "connection.grant.id"),
+      permission: string(grant.permission, "connection.grant.permission"),
+      status: status(grant.status),
+      expiresAt: integer(grant.expires_at, "connection.grant.expires_at"),
+      ...(grant.conversation_id === undefined ? {} : {
+        conversationId: agentConversationId(grant.conversation_id, "connection.grant.conversation_id"),
+      }),
+      capabilities,
+      connectors: grantConnectors,
+      ...(grantConnectorConnections === undefined ? {} : {
+        connectorConnections: grantConnectorConnections,
+      }),
+      mcpConnections: grantMcpConnections,
+      visibility: agentVisibility(capabilities),
+      ...(grant.app_tool_catalog_digest === undefined ? {} : {
+        appToolCatalogDigest: catalogDigest(
+          grant.app_tool_catalog_digest,
+          "connection.grant.app_tool_catalog_digest",
+        ),
+      }),
+    }),
+    authorization,
+    ...(accessKey === undefined ? {} : { accessKey: accessKeyFromWire(accessKey) }),
+    ...(mpp === undefined ? {} : { mpp: Object.freeze({
+      token: hex(mpp.token, "connection.mpp.token"),
+      symbol: string(mpp.symbol, "connection.mpp.symbol"),
+      balance: bigint(mpp.balance_atomics, "connection.mpp.balance_atomics"),
+      balanceStatus: mpp.balance_status === "ready" ? "ready" : "pending",
+      settlementToken: hex(mpp.settlement_token, "connection.mpp.settlement_token"),
+      settlementSymbol: string(mpp.settlement_symbol, "connection.mpp.settlement_symbol"),
+      settlementBalance: bigint(mpp.settlement_balance_atomics, "connection.mpp.settlement_balance_atomics"),
+      spent: bigint(mpp.spent_atomics, "connection.mpp.spent_atomics"),
+      limit: bigint(mpp.limit_atomics, "connection.mpp.limit_atomics"),
+      period: integer(mpp.period, "connection.mpp.period"),
+      maxPerRequest: bigint(mpp.max_per_request_atomics, "connection.mpp.max_per_request_atomics"),
+    }) }),
+  });
+}
+
+function hostPrincipal(value, label) {
+  const principal = object(value, label);
+  if (principal.kind !== "host" || typeof principal.id !== "string"
+    || !HOST_PRINCIPAL_ID.test(principal.id)
+    || Object.keys(principal).some((key) => key !== "kind" && key !== "id")) {
+    throw new InvalidResponseError(`${label} must contain an exact host principal`);
+  }
+  return Object.freeze({ kind: "host", id: principal.id });
+}
+
+export function connectionMatchesRequest(connection, options = {}) {
+  if (options.permission !== undefined && connection.grant.permission !== options.permission) {
+    return false;
+  }
+  if (options.authorization !== undefined && connection.authorization !== options.authorization) return false;
+  if (Object.hasOwn(options, "appToolCatalogDigest")) {
+    if (options.appToolCatalogDigest !== connection.grant.appToolCatalogDigest) return false;
+  }
+  if (Object.hasOwn(options, "conversationId")) {
+    const requested = options.conversationId;
+    if (requested === null) {
+      if (connection.grant.conversationId !== undefined) return false;
+    } else if (typeof requested !== "string" || !AGENT_CONVERSATION_ID.test(requested)
+      || connection.grant.conversationId !== requested) {
+      return false;
+    }
+  }
+  const requestedCloudAccounts = options.capabilities?.cloudAccounts;
+  if (requestedCloudAccounts !== undefined) {
+    const requested = CLOUD_ACCOUNT_PROVIDERS.filter(
+      (provider) => requestedCloudAccounts?.[provider] === true,
+    );
+    if (requested.length !== connection.grant.connectors.length
+      || requested.some((provider) => !connection.grant.connectors.includes(provider))) {
+      return false;
+    }
+  }
+  if (Object.hasOwn(options, "connectorConnections")
+    && !sameConnectorConnections(
+      options.connectorConnections,
+      connection.grant.connectorConnections,
+    )) return false;
+  const requestedAgent = options.capabilities?.agent;
+  if (requestedAgent !== undefined) {
+    const rawTraces = requestedAgent?.rawTraces === true;
+    const expected = {
+      finalMessages: rawTraces || requestedAgent?.finalMessages !== false,
+      actionSummaries: rawTraces || requestedAgent?.actionSummaries !== false,
+      conversationHistory: rawTraces || requestedAgent?.conversationHistory === true,
+      rawTraces,
+    };
+    for (const name of Object.keys(expected)) {
+      if (connection.grant.visibility[name] !== expected[name]) return false;
+    }
+  }
+  if (options.mcpConnectionIds !== undefined) {
+    if (!Array.isArray(options.mcpConnectionIds)
+      || options.mcpConnectionIds.some((id) => typeof id !== "string" || !MCP_CONNECTION_ID.test(id))
+      || new Set(options.mcpConnectionIds).size !== options.mcpConnectionIds.length) {
+      return false;
+    }
+    const actual = connection.grant.mcpConnections.map(({ id }) => id);
+    if (actual.length !== options.mcpConnectionIds.length
+      || actual.some((id) => !options.mcpConnectionIds.includes(id))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Builds the exact non-secret request projection retained by one minted grant. */
+export function reconnectRequestFromConnection(connection) {
+  return connectionRequestFromGrant({
+    ...connection.grant,
+    authorization: connection.authorization,
+  });
+}
+
+/** Builds the exact non-secret request projection for normalized grant fields. */
+export function connectionRequestFromGrant(grant) {
+  return Object.freeze({
+    capabilities: Object.freeze({
+      agent: grant.visibility,
+      cloudAccounts: Object.freeze(Object.fromEntries(
+        grant.connectors.map((provider) => [provider, true]),
+      )),
+    }),
+    mcpConnectionIds: Object.freeze(grant.mcpConnections.map(({ id }) => id)),
+    ...(grant.connectorConnections === undefined ? {} : {
+      connectorConnections: grant.connectorConnections,
+    }),
+    authorization: grant.authorization ?? "access_key",
+    appToolCatalogDigest: grant.appToolCatalogDigest,
+    permission: grant.permission,
+    conversationId: grant.conversationId ?? null,
+  });
+}
+
+export function preparedConnectionFromWire(value) {
+  const wire = object(value, "prepared connection");
+  const app = object(wire.app, "prepared connection.app");
+  const auth = object(wire.auth, "prepared connection.auth");
+  const permission = object(wire.permission, "prepared connection.permission");
+  const mpp = object(wire.mpp, "prepared connection.mpp");
+  const prepared = Object.freeze({
+    requestId: string(wire.request_id, "prepared connection.request_id"),
+    app: Object.freeze({
+      id: string(app.id, "prepared connection.app.id"),
+      name: string(app.name, "prepared connection.app.name"),
+      origin: string(app.origin, "prepared connection.app.origin"),
+    }),
+    accountAddress: hex(wire.account_address, "prepared connection.account_address"),
+    auth: Object.freeze({
+      message: string(auth.message, "prepared connection.auth.message"),
+      resources: strings(auth.resources, "prepared connection.auth.resources"),
+    }),
+    permission: Object.freeze({
+      id: string(permission.id, "prepared connection.permission.id"),
+      title: string(permission.title, "prepared connection.permission.title"),
+      description: string(permission.description, "prepared connection.permission.description"),
+      connectors: array(permission.connectors, "prepared connection.permission.connectors").map((item, index) => {
+        const connector = object(item, `prepared connection.permission.connectors[${index}]`);
+        return Object.freeze({
+          id: string(connector.id, `prepared connection.permission.connectors[${index}].id`),
+          name: string(connector.name, `prepared connection.permission.connectors[${index}].name`),
+          detail: string(connector.detail, `prepared connection.permission.connectors[${index}].detail`),
+        });
+      }),
+    }),
+    accessKey: accessKeyFromWire(object(wire.access_key, "prepared connection.access_key")),
+    mpp: Object.freeze({
+      token: hex(mpp.token, "prepared connection.mpp.token"),
+      symbol: string(mpp.symbol, "prepared connection.mpp.symbol"),
+      limit: bigint(mpp.limit_atomics, "prepared connection.mpp.limit_atomics"),
+      period: integer(mpp.period, "prepared connection.mpp.period"),
+      maxPerRequest: bigint(mpp.max_per_request_atomics, "prepared connection.mpp.max_per_request_atomics"),
+    }),
+  });
+  return { prepared, wire };
+}
+
+export function accessKeyFromWire(wire) {
+  return Object.freeze({
+    address: hex(wire.address, "access key.address"),
+    chainId: bigint(wire.chain_id, "access key.chain_id"),
+    keyId: hex(wire.key_id, "access key.key_id"),
+    ...(wire.public_key === undefined ? {} : { publicKey: hex(wire.public_key, "access key.public_key") }),
+    keyType: keyType(wire.key_type),
+    limits: Object.freeze(array(wire.limits, "access key.limits").map((item, index) => {
+      const limit = object(item, `access key.limits[${index}]`);
+      return Object.freeze({
+        token: hex(limit.token, `access key.limits[${index}].token`),
+        limit: bigint(limit.limit, `access key.limits[${index}].limit`),
+        ...(limit.period === undefined ? {} : { period: integer(limit.period, `access key.limits[${index}].period`) }),
+      });
+    })),
+    scopes: Object.freeze(array(wire.scopes, "access key.scopes").map((item, index) => {
+      const scope = object(item, `access key.scopes[${index}]`);
+      return Object.freeze({
+        address: hex(scope.address, `access key.scopes[${index}].address`),
+        ...(scope.selector === undefined ? {} : { selector: string(scope.selector, `access key.scopes[${index}].selector`) }),
+        ...(scope.recipients === undefined ? {} : { recipients: strings(scope.recipients, `access key.scopes[${index}].recipients`) }),
+      });
+    })),
+    witness: hex(wire.witness, "access key.witness"),
+    expiry: integer(wire.expiry, "access key.expiry"),
+    ...(wire.authorization === undefined ? {} : { authorization: hex(wire.authorization, "access key.authorization") }),
+  });
+}
+
+export function grantFromWire(value) {
+  const grant = object(value, "grant");
+  const capabilities = strings(grant.capabilities, "grant.capabilities");
+  const grantMcpConnections = mcpConnections(grant.mcp_connections, "grant.mcp_connections");
+  requireExactMcpProjection(capabilities, grantMcpConnections, "grant");
+  const grantConnectors = connectors(capabilities, "grant.capabilities");
+  const grantConnectorConnections = connectorConnections(
+    grant.connector_connections,
+    grantConnectors,
+    "grant.connector_connections",
+  );
+  return Object.freeze({
+    id: hex(grant.id, "grant.id"),
+    permission: string(grant.permission, "grant.permission"),
+    status: status(grant.status),
+    expiresAt: integer(grant.expires_at, "grant.expires_at"),
+    ...(grant.conversation_id === undefined ? {} : {
+      conversationId: agentConversationId(grant.conversation_id, "grant.conversation_id"),
+    }),
+    capabilities,
+    connectors: grantConnectors,
+    ...(grantConnectorConnections === undefined ? {} : {
+      connectorConnections: grantConnectorConnections,
+    }),
+    mcpConnections: grantMcpConnections,
+    visibility: agentVisibility(capabilities),
+    ...(grant.app_tool_catalog_digest === undefined ? {} : {
+      appToolCatalogDigest: catalogDigest(grant.app_tool_catalog_digest, "grant.app_tool_catalog_digest"),
+    }),
+  });
+}
+
+function authorizationMode(value) {
+  if (value === "access_key" || value === "hosted") return value;
+  throw new InvalidResponseError("connection.authorization_mode must be access_key or hosted");
+}
+
+function catalogDigest(value, name) {
+  if (typeof value !== "string" || !CATALOG_DIGEST.test(value)) {
+    throw new InvalidResponseError(`${name} must be a lowercase SHA-256 digest`);
+  }
+  return value;
+}
+
+const AGENT_VISIBILITY_CAPABILITIES = Object.freeze({
+  finalMessages: "agent.output.final",
+  actionSummaries: "agent.output.actions",
+  conversationHistory: "agent.history.read",
+  rawTraces: "agent.trace.read",
+});
+
+function agentVisibility(capabilities) {
+  const recognized = Object.values(AGENT_VISIBILITY_CAPABILITIES)
+    .some((capability) => capabilities.includes(capability));
+  const rawTraces = capabilities.includes(AGENT_VISIBILITY_CAPABILITIES.rawTraces);
+  return Object.freeze({
+    finalMessages: rawTraces || !recognized || capabilities.includes(AGENT_VISIBILITY_CAPABILITIES.finalMessages),
+    actionSummaries: rawTraces || !recognized || capabilities.includes(AGENT_VISIBILITY_CAPABILITIES.actionSummaries),
+    conversationHistory: rawTraces || capabilities.includes(AGENT_VISIBILITY_CAPABILITIES.conversationHistory),
+    rawTraces,
+  });
+}
+
+function agentConversationId(value, name) {
+  const id = string(value, name);
+  if (!AGENT_CONVERSATION_ID.test(id)) throw new InvalidResponseError(`${name} must be a lowercase UUIDv4`);
+  return id;
+}
+
+export function machineUsdConfigFromWire(value) {
+  const wire = object(value, "MACH config");
+  return Object.freeze({
+    chainId: integer(wire.chain_id, "MACH config.chain_id"),
+    minUsdAmountCents: integer(wire.min_usd_amount_cents, "MACH config.min_usd_amount_cents"),
+    maxUsdAmountCents: integer(wire.max_usd_amount_cents, "MACH config.max_usd_amount_cents"),
+    onrampEnabled: wire.onramp_enabled === undefined
+      ? true
+      : boolean(wire.onramp_enabled, "MACH config.onramp_enabled"),
+    stripePublishableKey: string(wire.stripe_publishable_key, "MACH config.stripe_publishable_key"),
+    tokenAddress: hex(wire.token_address, "MACH config.token_address"),
+  });
+}
+
+export function fundResultFromWire(value, client) {
+  const wire = object(value, "MACH funding result");
+  const order = object(wire.order, "MACH funding result.order");
+  return Object.freeze({
+    order: Object.freeze({
+      id: string(order.id, "MACH order.id"),
+      status: string(order.status, "MACH order.status"),
+      usdAmountCents: integer(order.usd_amount_cents, "MACH order.usd_amount_cents"),
+      machineUsdAmount: bigint(
+        order.mach_amount_atomics ?? order.machine_usd_amount_atomics,
+        "MACH order.mach_amount_atomics",
+      ),
+      issuanceTransactionHash: hex(order.issuance_transaction_hash, "MACH order.issuance_transaction_hash"),
+    }),
+    connection: connectionFromWire(wire.connection),
+  });
+}
+
+export function chargeResultFromWire(value, client) {
+  const wire = object(value, "MPP charge result");
+  const receipt = object(wire.receipt, "MPP charge result.receipt");
+  return Object.freeze({
+    receipt: Object.freeze({
+      id: string(receipt.id, "MPP receipt.id"),
+      amount: bigint(receipt.amount_atomics, "MPP receipt.amount_atomics"),
+      origin: string(receipt.origin, "MPP receipt.origin"),
+      transactionHash: hex(receipt.transaction_hash, "MPP receipt.transaction_hash"),
+    }),
+    connection: connectionFromWire(wire.connection),
+  });
+}
+
+function array(value, label) {
+  if (!Array.isArray(value)) throw new InvalidResponseError(`${label} must be an array`);
+  return value;
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new InvalidResponseError(`${label} must be an object`);
+  }
+  return value;
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new InvalidResponseError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function strings(value, label) {
+  return Object.freeze(array(value, label).map((item, index) => string(item, `${label}[${index}]`)));
+}
+
+function connectors(capabilities, label) {
+  const items = strings(capabilities, label);
+  return Object.freeze(CLOUD_ACCOUNT_PROVIDERS.filter((provider) =>
+    items.includes(provider) || items.includes(`urn:nanocodex:connector:${provider}`)
+  ));
+}
+
+function connectorConnections(value, grantConnectors, label) {
+  if (value === undefined) return undefined;
+  const selection = object(value, label);
+  const projected = {};
+  for (const [capability, rawIds] of Object.entries(selection)) {
+    if (capability === "chatgpt" || !grantConnectors.includes(capability)) {
+      throw new InvalidResponseError(`${label} contains an ungranted connector capability`);
+    }
+    const ids = array(rawIds, `${label}.${capability}`);
+    if (ids.length > 64) {
+      throw new InvalidResponseError(`${label}.${capability} contains too many connections`);
+    }
+    const normalized = ids.map((id, index) => {
+      const connectionId = string(id, `${label}.${capability}[${index}]`);
+      if (!MCP_CONNECTION_ID.test(connectionId)) {
+        throw new InvalidResponseError(`${label}.${capability}[${index}] is not an opaque connection ID`);
+      }
+      return connectionId;
+    });
+    if (new Set(normalized).size !== normalized.length) {
+      throw new InvalidResponseError(`${label}.${capability} contains duplicate connections`);
+    }
+    projected[capability] = Object.freeze(normalized);
+  }
+  return Object.freeze(projected);
+}
+
+function sameConnectorConnections(left, right) {
+  if (left === undefined || right === undefined) return left === right;
+  if (!left || typeof left !== "object" || Array.isArray(left)
+    || !right || typeof right !== "object" || Array.isArray(right)) return false;
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  if (leftKeys.length !== rightKeys.length
+    || leftKeys.some((key, index) => key !== rightKeys[index])) return false;
+  return leftKeys.every((key) => Array.isArray(left[key]) && Array.isArray(right[key])
+    && left[key].length === right[key].length
+    && left[key].every((id, index) => id === right[key][index]));
+}
+
+function mcpConnections(value, label) {
+  if (value === undefined) return Object.freeze([]);
+  const ids = new Set();
+  const connections = array(value, label);
+  if (connections.length > 16) throw new InvalidResponseError(`${label} must contain at most 16 connections`);
+  return Object.freeze(connections.map((item, index) => {
+    const connection = object(item, `${label}[${index}]`);
+    if (Object.keys(connection).some((key) => key !== "id" && key !== "name")) {
+      throw new InvalidResponseError(`${label}[${index}] contains private or unknown fields`);
+    }
+    const id = string(connection.id, `${label}[${index}].id`);
+    const name = string(connection.name, `${label}[${index}].name`);
+    if (!MCP_CONNECTION_ID.test(id) || ids.has(id)
+      || name.length < 1 || name.length > 256 || name.trim() !== name) {
+      throw new InvalidResponseError(`${label}[${index}] must contain an exact hosted MCP identity`);
+    }
+    ids.add(id);
+    return Object.freeze({ id, name });
+  }));
+}
+
+function requireExactMcpProjection(capabilities, connections, label) {
+  const ids = capabilities.flatMap((capability) => capability.startsWith("mcp:")
+    ? [capability.slice("mcp:".length)]
+    : []);
+  if (ids.length > 16
+    || ids.some((id) => !MCP_CONNECTION_ID.test(id))
+    || new Set(ids).size !== ids.length) {
+    throw new InvalidResponseError(`${label}.capabilities contains invalid hosted MCP identities`);
+  }
+  const metadataIds = connections.map(({ id }) => id);
+  if (ids.length !== metadataIds.length || ids.some((id) => !metadataIds.includes(id))) {
+    throw new InvalidResponseError(`${label} MCP capabilities and metadata must match exactly`);
+  }
+}
+
+function hex(value, label) {
+  const result = string(value, label);
+  if (!/^0x[0-9a-fA-F]+$/.test(result)) throw new InvalidResponseError(`${label} must be hex`);
+  return result;
+}
+
+function bigint(value, label) {
+  try {
+    return BigInt(value);
+  } catch {
+    throw new InvalidResponseError(`${label} must be an integer string`);
+  }
+}
+
+function integer(value, label) {
+  if (!Number.isSafeInteger(value)) throw new InvalidResponseError(`${label} must be a safe integer`);
+  return value;
+}
+
+function boolean(value, label) {
+  if (typeof value !== "boolean") throw new InvalidResponseError(`${label} must be a boolean`);
+  return value;
+}
+
+function status(value) {
+  if (value !== "active" && value !== "revoked" && value !== "expired") {
+    throw new InvalidResponseError("grant.status is invalid");
+  }
+  return value;
+}
+
+function keyType(value) {
+  if (value !== "secp256k1" && value !== "p256" && value !== "webAuthn") {
+    throw new InvalidResponseError("access key.key_type is invalid");
+  }
+  return value;
+}

package/vendor/nanocodex/cloud/mercator.mjs

@@ -0,0 +1,108 @@
+import { DEFAULT_MERCATOR_MCP_URL } from "../runtime/tempo-provider.mjs";
+
+const MERCATOR_ORIGIN = new URL(DEFAULT_MERCATOR_MCP_URL).origin;
+const JOBS_PATH = "/v1/jobs";
+const MAX_BODY_BYTES = 64 * 1024;
+const PAYMENT_DECIMALS = 6;
+
+/** @internal Creates the bounded executor for Mercator's paid REST handoff. */
+export function mercatorRestTool({ connection, fetch, calls, relay }) {
+  if (typeof fetch !== "function") {
+    throw new TypeError("Mercator REST execution requires an MPP-aware fetch function");
+  }
+  if (!connection.mpp) {
+    throw new TypeError("Mercator requires a Connect grant with explicit payment authority");
+  }
+  const relayUrl = new URL(relay);
+  return {
+    description: "Execute Mercator's run_rest_request handoff through MPP. Use only the exact rest and maxSpend fields returned by Mercator create_job, then poll the returned job with Mercator get_job.",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        method: { type: "string", enum: ["POST"] },
+        body: { type: "object", additionalProperties: true },
+        maxSpend: { type: "string", description: "Maximum quoted spend in decimal USDC, copied from the Mercator handoff." },
+      },
+      required: ["url", "method", "body", "maxSpend"],
+      additionalProperties: false,
+    },
+    async handler(input, context) {
+      calls.add("run_rest_request", context);
+      const url = mercatorJobUrl(input?.url);
+      if (input?.method !== "POST") {
+        throw new Error("Mercator REST handoffs must use POST.");
+      }
+      const maxAmount = decimalAtomics(input?.maxSpend, PAYMENT_DECIMALS);
+      if (maxAmount <= 0n) throw new Error("Mercator maxSpend must be greater than zero.");
+      if (maxAmount > connection.mpp.maxPerRequest) {
+        throw new Error(
+          `Mercator maxSpend exceeds this Connect grant's per-request limit (${connection.mpp.maxPerRequest} atomics).`,
+        );
+      }
+      if (!plainObject(input.body)) {
+        throw new TypeError("Mercator REST handoff body must be an object.");
+      }
+      const body = JSON.stringify(input.body);
+      if (new TextEncoder().encode(body).byteLength > MAX_BODY_BYTES) {
+        throw new Error(`Mercator REST handoff body exceeds ${MAX_BODY_BYTES} bytes.`);
+      }
+
+      const response = await fetch(relayUrl, {
+        method: "POST",
+        headers: { accept: "application/json", "content-type": "application/json" },
+        body,
+      }, { intent: "charge", maxAmount });
+      const responseText = await response.text();
+      if (!response.ok) {
+        throw new Error(
+          `Mercator job submission failed with HTTP ${response.status}: ${responseText.slice(0, 2_048)}`,
+        );
+      }
+      return {
+        status: response.status,
+        paymentReceipt: response.headers.get("payment-receipt") ?? undefined,
+        result: parseResponse(responseText),
+      };
+    },
+  };
+}
+
+function mercatorJobUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch (error) {
+    throw new TypeError("Mercator REST handoff URL is invalid.", { cause: error });
+  }
+  if (url.origin !== MERCATOR_ORIGIN || url.pathname !== JOBS_PATH
+    || url.username || url.password || url.search || url.hash) {
+    throw new Error(`Mercator REST handoff must target ${MERCATOR_ORIGIN}${JOBS_PATH}.`);
+  }
+  return url.href;
+}
+
+function decimalAtomics(value, decimals) {
+  if (typeof value !== "string") throw new TypeError("Mercator maxSpend must be a decimal string.");
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(value);
+  if (!match || (match[2]?.length ?? 0) > decimals) {
+    throw new TypeError(`Mercator maxSpend must have at most ${decimals} decimal places.`);
+  }
+  return BigInt(match[1]) * (10n ** BigInt(decimals))
+    + BigInt((match[2] ?? "").padEnd(decimals, "0") || "0");
+}
+
+function plainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function parseResponse(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}

package/vendor/nanocodex/cloud/server/HostPrincipal.d.mts

@@ -0,0 +1,34 @@
+export type Claims = Readonly<{
+  /** Stable opaque identity-provider namespace. Limited to 512 non-control characters. */
+  issuer: string;
+  /** Stable opaque tenant namespace within the issuer. Limited to 512 non-control characters. */
+  tenant: string;
+  /** Stable opaque user subject; limited to 512 non-control characters. */
+  subject: string;
+  /** Opaque host-login session identifier; limited to 512 non-control characters. */
+  sessionId: string;
+}>;
+
+export type Exchange = Readonly<{ token: string; expiresAt: number }>;
+
+export type Client = Readonly<{
+  create(options: Claims & Readonly<{
+    resources: readonly string[];
+    expiresIn?: number | undefined;
+    signal?: AbortSignal | undefined;
+  }>): Promise<Exchange>;
+  handler(options: Readonly<{
+    authenticate(request: Request): Promise<Claims | undefined> | Claims | undefined;
+  }>): (request: Request) => Promise<Response>;
+  revoke(options: Claims & Readonly<{
+    signal?: AbortSignal | undefined;
+  }>): Promise<void>;
+}>;
+
+export function create(parameters: Readonly<{
+  appId: string;
+  appOrigin: string;
+  secret: string;
+  baseUrl?: string | URL | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+}>): Client;