@astrasyncai/verification-gateway 2.4.6 → 2.4.7

package/dist/index.mjs

@@ -126,7 +126,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.6";
+var SDK_VERSION = "2.4.7";
 
 // src/verify.ts
 var DEFAULT_CONFIG = {
@@ -513,6 +513,26 @@ async function recordDecision(config, sessionId, decision, reason, override) {
   }).catch(() => {
   });
 }
+async function recordAnonymousLocalOverride(config, correlationId, override, reason) {
+  const headers = { "Content-Type": "application/json" };
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+    headers["X-API-Key"] = config.apiKey;
+  }
+  await fetch(`${config.apiBaseUrl}/agents/verify-access/local-override`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      correlationId,
+      reason,
+      overriddenBy: override.overriddenBy,
+      toolName: override.toolName,
+      requestedLevel: override.requestedLevel,
+      grantedLevel: override.grantedLevel
+    })
+  }).catch(() => {
+  });
+}
 async function fetchRoutes(config, counterpartyId) {
   if (!counterpartyId) return null;
   const headers = { "Content-Type": "application/json" };
@@ -3900,6 +3920,681 @@ function extractCredentialsFromProtocol(protocol, context) {
   }
 }
 
+// src/transport/mcp-server.ts
+var MCP_VERIFIED_HOP_HEADER = "X-Astra-Verified-Hop";
+var MCP_VERIFIED_HOP_MAX_AGE_MS = 6e4;
+function serializeVerifiedHop(marker) {
+  return `${marker.astraId};${marker.sessionId ?? ""};${marker.checkedAt}`;
+}
+function parseVerifiedHop(value) {
+  if (!value) return null;
+  const parts = value.split(";");
+  if (parts.length !== 3) return null;
+  const [astraId, sessionId, checkedAtRaw] = parts;
+  if (!astraId) return null;
+  const checkedAt = Number(checkedAtRaw);
+  if (!Number.isFinite(checkedAt) || checkedAt <= 0) return null;
+  return {
+    astraId,
+    ...sessionId ? { sessionId } : {},
+    checkedAt
+  };
+}
+function isVerifiedHopValidFor(marker, expectedAstraId, opts = {}) {
+  if (!marker) return false;
+  if (marker.astraId !== expectedAstraId) return false;
+  const maxAge = opts.maxAgeMs ?? MCP_VERIFIED_HOP_MAX_AGE_MS;
+  const now = opts.now ?? Date.now();
+  return now - marker.checkedAt <= maxAge && now >= marker.checkedAt;
+}
+function parseMcpJsonRpc(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const obj = body;
+  if (obj.jsonrpc !== "2.0" && obj.jsonrpc !== "1.0") return null;
+  const method = typeof obj.method === "string" ? obj.method : null;
+  if (!method) return null;
+  const params = obj.params;
+  let toolName;
+  if (method === "tools/call" && params && typeof params.name === "string") {
+    toolName = params.name;
+  }
+  let protocolVersion;
+  if (method === "initialize" && params && typeof params.protocolVersion === "string") {
+    protocolVersion = params.protocolVersion;
+  }
+  const meta = params?._meta;
+  const astrasyncMeta = meta?.astrasync;
+  const args = params?.arguments;
+  let agentIdFromBody;
+  if (astrasyncMeta && typeof astrasyncMeta.agentId === "string") {
+    agentIdFromBody = astrasyncMeta.agentId;
+  } else if (args && typeof args.agent_id === "string") {
+    agentIdFromBody = args.agent_id;
+  }
+  const purposeBodyResult = extractFromMcpBody(astrasyncMeta, args, "purpose");
+  const actionBodyResult = extractFromMcpBody(astrasyncMeta, args, "action");
+  const isInitialize = method === "initialize";
+  const isToolCall = method === "tools/call";
+  const isIntrospection = method === "tools/list" || method === "prompts/list" || method === "resources/list" || method === "ping" || method === "notifications/initialized";
+  return {
+    method,
+    ...toolName ? { toolName } : {},
+    ...protocolVersion ? { protocolVersion } : {},
+    ...agentIdFromBody ? { agentIdFromBody } : {},
+    ...purposeBodyResult.value ? { purposeFromBody: purposeBodyResult.value } : {},
+    ...purposeBodyResult.source ? { purposeSourceFromBody: purposeBodyResult.source } : {},
+    ...actionBodyResult.value ? { actionFromBody: actionBodyResult.value } : {},
+    ...actionBodyResult.source ? { actionSourceFromBody: actionBodyResult.source } : {},
+    isInitialize,
+    isToolCall,
+    isIntrospection
+  };
+}
+function extractFromMcpBody(astrasyncMeta, args, key) {
+  if (astrasyncMeta && typeof astrasyncMeta[key] === "string") {
+    return { value: astrasyncMeta[key], source: "meta" };
+  }
+  if (args && typeof args[key] === "string") {
+    return { value: args[key], source: "tool_argument" };
+  }
+  return { value: void 0, source: void 0 };
+}
+function mcpToPdlss(parsed, headerPurpose, headerAction) {
+  const resource = parsed.toolName ? `mcp:tool/${parsed.toolName}` : `mcp:method/${parsed.method}`;
+  let purpose;
+  let purposeSource;
+  if (headerPurpose) {
+    purpose = headerPurpose;
+    purposeSource = "header";
+  } else if (parsed.purposeFromBody && parsed.purposeSourceFromBody) {
+    purpose = parsed.purposeFromBody;
+    purposeSource = parsed.purposeSourceFromBody;
+  } else {
+    purpose = "mcp_invoke";
+    purposeSource = "default_mcp_invoke";
+  }
+  let action;
+  let actionSource;
+  if (headerAction) {
+    action = headerAction;
+    actionSource = "header";
+  } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
+    action = parsed.actionFromBody;
+    actionSource = parsed.actionSourceFromBody;
+  } else {
+    action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
+    actionSource = "transport_layer";
+  }
+  return { purpose, action, resource, purposeSource, actionSource };
+}
+function mcpRiskTier(parsed) {
+  if (parsed.isInitialize || parsed.method === "notifications/initialized") return "none";
+  if (parsed.isIntrospection) return "none";
+  if (parsed.method === "resources/read") return "read-only";
+  if (parsed.isToolCall) return "standard";
+  return "standard";
+}
+
+// src/adapters/mcp.ts
+function readSingleHeader(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0];
+  return void 0;
+}
+function defaultMcpDenied(result, req, res) {
+  const id = req.body?.id ?? null;
+  const status = result.verified ? 403 : 401;
+  res.setHeader("X-Astra-Gateway-Mode", "enforced");
+  res.status(status).json({
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: result.verified ? -32001 : -32e3,
+      message: result.denialReasons?.[0] ?? "Access denied",
+      data: {
+        accessLevel: result.accessLevel,
+        guidance: result.guidance,
+        // Round-10: aggregated per-dimension detail + correlation handle.
+        failures: result.failures,
+        correlationId: result.correlationId
+      }
+    }
+  });
+}
+function resolveMinAccessLevel(parsed, opts) {
+  if (parsed.toolName && opts.toolGates && opts.toolGates[parsed.toolName] !== void 0) {
+    return { level: opts.toolGates[parsed.toolName], source: "toolGate" };
+  }
+  if (opts.methodGates && opts.methodGates[parsed.method] !== void 0) {
+    return { level: opts.methodGates[parsed.method], source: "methodGate" };
+  }
+  return { level: mcpRiskTier(parsed), source: "tier" };
+}
+function createMcpMiddleware(options) {
+  const {
+    toolGates,
+    methodGates,
+    onAgentIdMismatch = "reject",
+    skip = false,
+    onDenied = defaultMcpDenied,
+    trustVerifiedHop = true,
+    verifiedHopMaxAgeMs,
+    recordDecisions,
+    enableRuntimeChallenge = true,
+    ...config
+  } = options;
+  return async (req, res, next) => {
+    try {
+      if (skip) return next();
+      const parsed = parseMcpJsonRpc(req.body);
+      if (!parsed) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
+          res.setHeader("X-Astra-Gateway-Reason", "non-jsonrpc-body");
+        }
+        return next();
+      }
+      req.mcpRequest = parsed;
+      const headerRaw = req.headers["x-astra-id"] ?? req.headers["x-astra-agentid"];
+      const headerAstraId = typeof headerRaw === "string" ? headerRaw : Array.isArray(headerRaw) ? headerRaw[0] : void 0;
+      const bodyAstraId = parsed.agentIdFromBody;
+      let effectiveAstraId;
+      if (headerAstraId && bodyAstraId && headerAstraId !== bodyAstraId) {
+        if (onAgentIdMismatch === "reject") {
+          const id = req.body?.id ?? null;
+          res.status(400).json({
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: -32602,
+              message: "AGENT_ID_MISMATCH",
+              data: {
+                detail: "The agent id in the X-Astra-Id header disagrees with params._meta.astrasync.agentId / params.arguments.agent_id. Reconcile before calling the tool \u2014 see https://astrasync.ai/docs/mcp-integration#identity-reconciliation.",
+                headerAstraId,
+                bodyAstraId
+              }
+            }
+          });
+          return;
+        }
+        effectiveAstraId = onAgentIdMismatch === "prefer-header" ? headerAstraId : bodyAstraId;
+      } else {
+        effectiveAstraId = headerAstraId ?? bodyAstraId;
+      }
+      if (trustVerifiedHop && effectiveAstraId) {
+        const hopRaw = req.headers[MCP_VERIFIED_HOP_HEADER.toLowerCase()];
+        const hopValue = typeof hopRaw === "string" ? hopRaw : Array.isArray(hopRaw) ? hopRaw[0] : void 0;
+        const marker = parseVerifiedHop(hopValue);
+        if (isVerifiedHopValidFor(marker, effectiveAstraId, {
+          ...verifiedHopMaxAgeMs !== void 0 ? { maxAgeMs: verifiedHopMaxAgeMs } : {}
+        })) {
+          return next();
+        }
+      }
+      const { level: minAccessLevel, source: gateSource } = resolveMinAccessLevel(parsed, {
+        toolGates,
+        methodGates
+      });
+      const credentials = extractCredentials(
+        req.headers,
+        req.query
+      );
+      if (effectiveAstraId) credentials.astraId = effectiveAstraId;
+      const shouldEnforce = minAccessLevel !== "none";
+      if (minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
+          res.setHeader("X-Astra-Gateway-Reason", "mcp-tier-none");
+        }
+        return next();
+      }
+      const headerPurpose = readSingleHeader(req.headers["x-astra-purpose"]);
+      const headerAction = readSingleHeader(req.headers["x-astra-action"]);
+      const pdlss = mcpToPdlss(parsed, headerPurpose, headerAction);
+      if (config.debug) {
+        console.debug("[mcp-middleware] pdlss resolved", {
+          purpose_source: pdlss.purposeSource,
+          resolved_purpose: pdlss.purpose,
+          action_source: pdlss.actionSource,
+          resolved_action: pdlss.action
+        });
+      }
+      const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
+      const shouldRecordDecisions = recordDecisions !== false;
+      const result = await verify(config, {
+        credentials,
+        purpose: pdlss.purpose,
+        action: pdlss.action,
+        resource: pdlss.resource,
+        // Round-12 (F19): mark transport protocol separately from intent.
+        // The MCP middleware always sets this to 'mcp'; non-MCP callers
+        // leave it unset (server-side default is 'rest').
+        invocationProtocol: "mcp",
+        createSession: shouldRecordDecisions,
+        counterpartyUrl,
+        counterpartyType: config.counterpartyType || "mcp_server",
+        enableRuntimeChallenge,
+        callerMetadata: {
+          sourceIp: req.ip,
+          userAgent: req.headers["user-agent"],
+          host: req.headers.host
+        }
+      });
+      req.agentVerification = result;
+      const sessionId = result.sessionId;
+      const correlationId = result.correlationId;
+      if (!result.verified) {
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        onDenied(result, req, res);
+        return;
+      }
+      if (!shouldEnforce) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "enforced");
+          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
+        }
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "granted").catch(() => {
+          });
+        }
+        return next();
+      }
+      if (!hasMinimumAccess(result.accessLevel, minAccessLevel)) {
+        const insufficientFailure = {
+          dimension: "access_level.insufficient",
+          message: `Tool requires accessLevel '${minAccessLevel}'; agent has '${result.accessLevel}'.`,
+          guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
+        };
+        result.failures = [...result.failures ?? [], insufficientFailure];
+        result.denialReasons = [...result.denialReasons ?? [], insufficientFailure.message];
+        if (shouldRecordDecisions) {
+          const overrideKind = gateSource === "toolGate" ? "toolGate" : gateSource === "methodGate" ? "methodGate" : "other";
+          const override = {
+            overriddenBy: overrideKind,
+            ...parsed.toolName && { toolName: parsed.toolName },
+            requestedLevel: minAccessLevel,
+            grantedLevel: result.accessLevel
+          };
+          if (sessionId) {
+            recordDecision(config, sessionId, "denied", result.denialReasons?.[0], override).catch(
+              () => {
+              }
+            );
+          } else if (correlationId) {
+            recordAnonymousLocalOverride(
+              config,
+              correlationId,
+              override,
+              result.denialReasons?.[0]
+            ).catch(() => {
+            });
+          }
+        }
+        onDenied(result, req, res);
+        return;
+      }
+      if (effectiveAstraId) {
+        res.setHeader(
+          MCP_VERIFIED_HOP_HEADER,
+          serializeVerifiedHop({
+            astraId: effectiveAstraId,
+            ...sessionId ? { sessionId } : {},
+            checkedAt: Date.now()
+          })
+        );
+      }
+      if (shouldRecordDecisions && sessionId) {
+        recordDecision(config, sessionId, "granted").catch(() => {
+        });
+      }
+      const enhancedResult = result;
+      if (enhancedResult.warningHeader) {
+        res.setHeader(enhancedResult.warningHeader.name, enhancedResult.warningHeader.value);
+      }
+      next();
+    } catch (error) {
+      console.error("[VerificationGateway/MCP] Middleware error:", error);
+      next();
+    }
+  };
+}
+
+// src/registration/errors.ts
+var AstraSyncError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "AstraSyncError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+var KYDRequiredError = class extends AstraSyncError {
+  constructor(response) {
+    const kydUrl = response.kydUrl || "https://astrasync.ai/developer-profile";
+    super(
+      `KYD verification required before registering agents.
+Complete your KYD profile at: ${kydUrl}`,
+      403,
+      "KYD_REQUIRED"
+    );
+    this.name = "KYDRequiredError";
+    this.kydUrl = kydUrl;
+    this.ownerNotified = response.ownerNotified || false;
+  }
+};
+var AuthenticationError = class extends AstraSyncError {
+  constructor(message) {
+    super(message, 401, "AUTH_FAILED");
+    this.name = "AuthenticationError";
+  }
+};
+var RegistrationDeniedError = class extends AstraSyncError {
+  constructor(requestId, reason) {
+    super(
+      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ""}`,
+      403,
+      "REGISTRATION_DENIED"
+    );
+    this.name = "RegistrationDeniedError";
+    this.requestId = requestId;
+    this.reason = reason;
+  }
+};
+var RegistrationExpiredError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,
+      410,
+      "REGISTRATION_EXPIRED"
+    );
+    this.name = "RegistrationExpiredError";
+    this.requestId = requestId;
+  }
+};
+var RegistrationTimeoutError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,
+      408,
+      "REGISTRATION_TIMEOUT"
+    );
+    this.name = "RegistrationTimeoutError";
+    this.requestId = requestId;
+  }
+};
+
+// src/registration/api.ts
+var DEFAULT_BASE_URL = "https://astrasync.ai";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var AstraSync = class {
+  constructor(config = {}) {
+    let raw = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    if (raw.toLowerCase().endsWith("/api")) {
+      raw = raw.slice(0, -"/api".length);
+      if (config.baseUrl && !config.silent) {
+        console.warn(
+          `[AstraSync] baseUrl '${config.baseUrl}' had a trailing /api \u2014 stripped to '${raw}'. Pass the bare origin (e.g. 'https://astrasync.ai' or 'https://staging.astrasync.ai') to AstraSync(). The /api suffix is the verify-gateway (GatewayConfig.apiBaseUrl) convention.`
+        );
+      }
+    }
+    this.baseUrl = raw;
+    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;
+    this.email = config.email;
+    this.password = config.password;
+    this.privateKey = config.privateKey;
+    if (!this.apiKey && !this.email) {
+      throw new AuthenticationError(
+        "Authentication required. Provide apiKey, or email+password. Set ASTRASYNC_API_KEY env var or pass config to constructor."
+      );
+    }
+    if (this.email && !this.password) {
+      throw new AuthenticationError("Password is required when using email authentication.");
+    }
+  }
+  /**
+   * Register a new AI agent on the AstraSync KYA Platform.
+   *
+   * The backend response depends on auth context:
+   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+   *   returns `{ status: 'active', agent }`.
+   * - **API-key only** (no signature): 202 pending, returns
+   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+   *   owner is notified by email and a dashboard alert is emitted; the agent
+   *   becomes active only after the owner approves.
+   *
+   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+   * request until it resolves, then return the live agent record. The promise
+   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+   * `RegistrationTimeoutError` on the corresponding terminal states.
+   *
+   * @example Non-blocking (default — best for serverless / scheduled agents):
+   * ```typescript
+   * const result = await sdk.register({ name, pdlss });
+   * if (result.status === 'pending_approval') {
+   *   storeRequestId(result.requestId);
+   *   return; // function exits; resume later via pollRegistration()
+   * }
+   * ```
+   *
+   * @example Blocking (best for long-running services + CLI):
+   * ```typescript
+   * const agent = await sdk.register({
+   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+   * });
+   * ```
+   */
+  async register(options) {
+    const body = {
+      name: options.name,
+      ...options.description && { description: options.description },
+      ...options.agentType && { agentType: options.agentType },
+      ...options.apiEndpoint && { apiEndpoint: options.apiEndpoint },
+      ...options.model && { model: options.model },
+      ...options.framework && { framework: options.framework },
+      ...options.protocols && { protocols: options.protocols },
+      ...options.metadata && { metadata: options.metadata },
+      ...options.pdlss && { pdlss: options.pdlss }
+    };
+    const { status, body: raw } = await this.requestWithStatus("POST", "/api/agents/register", body);
+    if (status === 201) {
+      const activeBody = raw;
+      const active = {
+        status: "active",
+        agent: activeBody.data.agent,
+        // Round-12 (F16): pass backend advisories through verbatim.
+        // Pre-fix the SDK whitelisted five fields and silently dropped
+        // `warnings`, which left partners with no signal that
+        // `no_callback_endpoint` (or future advisories) had fired.
+        ...activeBody.warnings && { warnings: activeBody.warnings }
+      };
+      return active;
+    }
+    const pendingBody = raw;
+    const pending = {
+      status: "pending_approval",
+      requestId: pendingBody.requestId,
+      expiresAt: pendingBody.expiresAt,
+      pollUrl: pendingBody.pollUrl,
+      message: pendingBody.message,
+      // Round-12 (F16): same pass-through on the pending path.
+      ...pendingBody.warnings && { warnings: pendingBody.warnings }
+    };
+    if (!options.waitForApproval) return pending;
+    return this.waitForApproval(pendingBody.requestId, options);
+  }
+  /**
+   * Poll the current state of a pending-approval registration request.
+   *
+   * Useful for caller-driven polling when `waitForApproval: false` (the
+   * default). The endpoint is unauthenticated — pass the `requestId` that
+   * was returned from the 202 response.
+   *
+   * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+   *          minted agent in `agent`; `'denied'` may carry the owner's
+   *          `reason`; `'expired'` is terminal after 14 days.
+   */
+  async pollRegistration(requestId) {
+    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new AstraSyncError(
+        errBody.error || `pollRegistration failed: ${res.status}`,
+        res.status,
+        errBody.code
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Block until a pending registration request resolves to a terminal state.
+   * Resolves to the live `AgentRecord` on approval; rejects with the matching
+   * Registration*Error on deny/expire/timeout. Usually called via
+   * `register({ waitForApproval: true })`, but exposed for callers that want
+   * to fire-and-forget the initial register call and resume waiting later
+   * (e.g. after restoring a stored `requestId` on cold start).
+   */
+  async waitForApproval(requestId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    const pollIntervalMs = options.pollIntervalMs ?? 5e3;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.pollRegistration(requestId);
+      const ageMs = Date.now() - start;
+      options.onPending?.({ requestId, ageMs });
+      if (result.state === "approved") {
+        if (!result.agent) {
+          throw new AstraSyncError(
+            `Registration ${requestId} reported approved but no agent payload returned.`,
+            500
+          );
+        }
+        return result.agent;
+      }
+      if (result.state === "denied") {
+        throw new RegistrationDeniedError(requestId, result.reason);
+      }
+      if (result.state === "expired") {
+        throw new RegistrationExpiredError(requestId);
+      }
+      await sleep(pollIntervalMs);
+    }
+    throw new RegistrationTimeoutError(requestId);
+  }
+  /**
+   * Look up an agent's public profile by ASTRA ID or UUID.
+   */
+  async verify(agentId) {
+    return this.request("GET", `/api/agents/verify/${agentId}`);
+  }
+  /**
+   * Check API health.
+   */
+  async health() {
+    const res = await fetch(`${this.baseUrl}/api/health/`);
+    if (!res.ok) {
+      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);
+    }
+    return res.json();
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  async request(method, endpoint, body) {
+    const { body: parsed } = await this.requestWithStatus(method, endpoint, body);
+    return parsed;
+  }
+  /**
+   * Variant of {@link request} that also returns the HTTP status code, so
+   * callers can branch on 201 vs 202 (or other success codes) without losing
+   * type information about the response body.
+   */
+  async requestWithStatus(method, endpoint, body) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const token = await this.getAuthToken();
+    headers["Authorization"] = `Bearer ${token}`;
+    if (this.privateKey) {
+      const signature = await this.signRequest(method, endpoint, body || {});
+      headers["X-AstraSync-Signature"] = signature;
+    }
+    const res = await fetch(url, {
+      method,
+      headers,
+      ...body ? { body: JSON.stringify(body) } : {}
+    });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ error: res.statusText }));
+      if (res.status === 403 && errorBody.code === "KYD_REQUIRED") {
+        throw new KYDRequiredError(errorBody);
+      }
+      throw new AstraSyncError(
+        errorBody.error || `Request failed: ${res.status}`,
+        res.status,
+        errorBody.code
+      );
+    }
+    return { status: res.status, body: await res.json() };
+  }
+  async getAuthToken() {
+    if (this.apiKey) {
+      return this.apiKey;
+    }
+    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {
+      return this.cachedJwt;
+    }
+    const res = await fetch(`${this.baseUrl}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: this.email, password: this.password })
+    });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({}));
+      throw new AuthenticationError(
+        errorBody.message || errorBody.error || "Login failed"
+      );
+    }
+    const data = await res.json();
+    this.cachedJwt = data.data.token;
+    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1e3;
+    return this.cachedJwt;
+  }
+  /**
+   * Sign a request using secp256k1 (ethers.js).
+   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY
+   * Must match apps/backend/src/services/signature-verify.service.ts exactly.
+   */
+  async signRequest(method, endpoint, body) {
+    const { Wallet } = await import("ethers");
+    const sorted = this.sortObjectKeys(body);
+    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;
+    const wallet = new Wallet(this.privateKey);
+    return wallet.signMessage(canonical);
+  }
+  /** Recursively sort object keys for canonical JSON representation. */
+  sortObjectKeys(obj) {
+    if (obj === null || typeof obj !== "object") {
+      return obj;
+    }
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.sortObjectKeys(item));
+    }
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = this.sortObjectKeys(obj[key]);
+    }
+    return sorted;
+  }
+};
+
 // src/agent/index.ts
 var agent_exports = {};
 __export(agent_exports, {
@@ -4220,15 +4915,24 @@ export {
   ACCESS_LEVEL_DESCRIPTIONS,
   ACCESS_LEVEL_HIERARCHY,
   AgentClient,
+  AstraSync,
+  AstraSyncError,
+  AuthenticationError,
   ChallengeHandler,
   DEFAULT_TRUST_THRESHOLDS,
+  KYDRequiredError,
+  RegistrationDeniedError,
+  RegistrationExpiredError,
+  RegistrationTimeoutError,
   TRUST_LEVEL_RANGES,
   VERSION,
   agent_exports as agent,
   clearCache,
+  createMcpMiddleware,
   determineAccessLevel,
   express_exports as express,
   extractCredentials,
+  extractMcpCredentials,
   getAccessLevelForScore,
   getCapabilities,
   getTrustLevel,
@@ -4238,6 +4942,7 @@ export {
   quickVerify,
   recordDecision2 as recordDecision,
   sdk_exports as sdk,
+  setMcpMeta,
   transport_exports as transport,
   verify
 };