@agent-native/core 0.101.6 → 0.101.10

package/corpus/core/src/integrations/webhook-handler.ts

@@ -2,6 +2,7 @@ import type { H3Event } from "h3";
 
 import {
   appendA2AArtifactLinks,
+  extractA2AArtifactIdentities,
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js";
@@ -35,6 +36,7 @@ import {
 import {
   buildAssistantMessage,
   extractThreadMeta,
+  threadDataToEngineMessages,
 } from "../agent/thread-data-builder.js";
 import { attachToolSearch } from "../agent/tool-search.js";
 import { createThread, getThread } from "../chat-threads/store.js";
@@ -63,7 +65,11 @@ import {
 } from "./pending-tasks-store.js";
 import { integrationScopeSubjectKey } from "./scope-store.js";
 import { getThreadMapping, saveThreadMapping } from "./thread-mapping-store.js";
-import type { PlatformAdapter, IncomingMessage } from "./types.js";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  PlatformDeliveryReceipt,
+} from "./types.js";
 import {
   listIntegrationUsageBudgets,
   releaseIntegrationUsageBudget,
@@ -710,34 +716,7 @@ async function processIncomingMessage(
   }
   const existingMessages: EngineMessage[] = [];
   if (thread?.threadData) {
-    try {
-      const data = JSON.parse(thread.threadData);
-      if (Array.isArray(data.messages)) {
-        for (const msg of data.messages) {
-          const m = msg.message ?? msg;
-          const textContent =
-            typeof m.content === "string"
-              ? m.content
-              : Array.isArray(m.content)
-                ? m.content
-                    .filter((c: any) => c.type === "text")
-                    .map((c: any) => c.text)
-                    .join("\n")
-                : "";
-          if (m.role === "user") {
-            existingMessages.push({
-              role: "user",
-              content: [{ type: "text", text: textContent }],
-            });
-          } else if (m.role === "assistant") {
-            existingMessages.push({
-              role: "assistant",
-              content: [{ type: "text", text: textContent }],
-            });
-          }
-        }
-      }
-    } catch {}
+    existingMessages.push(...threadDataToEngineMessages(thread.threadData));
   }
 
   // Add the new user message. Include verified platform identity as lightweight
@@ -988,12 +967,11 @@ async function processIncomingMessage(
           // preview card.
           const baseUrl = process.env.APP_URL || process.env.URL || "";
           const appBaseUrl = baseUrl ? withConfiguredAppBasePath(baseUrl) : "";
+          const toolResults = collectToolResultSummaries(completedRun);
           if (!suppressPlatformReply) {
-            responseText = appendA2AArtifactLinks(
-              responseText,
-              collectToolResultSummaries(completedRun),
-              { baseUrl: appBaseUrl || undefined },
-            );
+            responseText = appendA2AArtifactLinks(responseText, toolResults, {
+              baseUrl: appBaseUrl || undefined,
+            });
           }
           const threadDeepLinkUrl =
             appBaseUrl && threadId
@@ -1002,34 +980,60 @@ async function processIncomingMessage(
 
           // Format and send back to platform — update the "thinking…"
           // placeholder in place if the adapter supplied one.
+          let deliveredResponse:
+            | {
+                platform: string;
+                status: "delivered";
+                text: string;
+                deliveredAt: string;
+                messageRefs?: string[];
+              }
+            | undefined;
           if (!suppressPlatformReply) {
             const outgoing = adapter.formatAgentResponse(responseText, {
               threadDeepLinkUrl,
             });
-            let delivered = false;
+            let deliveryReceipt: void | PlatformDeliveryReceipt;
             if (queuedA2AContinuation && progress?.ref) {
               // Post substantive parent results as a normal thread reply while
               // the one continuation that claimed this resumable stream keeps
               // it open for its eventual terminal result.
-              await adapter.sendResponse(outgoing, incoming, {
+              deliveryReceipt = await adapter.sendResponse(outgoing, incoming, {
                 placeholderRef: opts.placeholderRef,
               });
-              delivered = true;
             } else if (progress) {
               try {
-                await progress.complete(outgoing);
-                delivered = true;
+                deliveryReceipt = await progress.complete(outgoing);
               } catch {
-                await adapter.sendResponse(outgoing, incoming, {
-                  placeholderRef: opts.placeholderRef,
-                });
-                delivered = true;
+                deliveryReceipt = await adapter.sendResponse(
+                  outgoing,
+                  incoming,
+                  {
+                    placeholderRef: opts.placeholderRef,
+                  },
+                );
               }
             } else {
-              await adapter.sendResponse(outgoing, incoming, {
+              deliveryReceipt = await adapter.sendResponse(outgoing, incoming, {
                 placeholderRef: opts.placeholderRef,
               });
-              delivered = true;
+            }
+            const delivered = deliveryReceipt?.status === "delivered";
+            if (!delivered) {
+              throw new Error(
+                `${incoming.platform} response completed without delivery proof`,
+              );
+            }
+            if (delivered) {
+              deliveredResponse = {
+                platform: incoming.platform,
+                status: "delivered",
+                text: outgoing.text,
+                deliveredAt: new Date().toISOString(),
+                ...(deliveryReceipt?.messageRefs?.length
+                  ? { messageRefs: deliveryReceipt.messageRefs }
+                  : {}),
+              };
             }
             if (slackInputRequest && delivered && incoming.senderId) {
               await setIntegrationAwaitingInput({
@@ -1078,6 +1082,8 @@ async function processIncomingMessage(
             incoming.text,
             completedRun,
             thread,
+            deliveredResponse,
+            toolResults,
           );
           await recordIntegrationUsage({
             usage,
@@ -1533,6 +1539,14 @@ async function persistThreadData(
   userText: string,
   completedRun: ActiveRun,
   thread: any,
+  deliveredResponse?: {
+    platform: string;
+    status: "delivered";
+    text: string;
+    deliveredAt: string;
+    messageRefs?: string[];
+  },
+  toolResults: A2AToolResultSummary[] = [],
 ): Promise<void> {
   try {
     let repo: any;
@@ -1556,6 +1570,16 @@ async function persistThreadData(
       completedRun.events ?? [],
       completedRun.runId,
     );
+    if (assistantMsg) {
+      assistantMsg.metadata.integrationDeliveryAttempted = true;
+      if (deliveredResponse) {
+        assistantMsg.metadata.integrationDelivery = deliveredResponse;
+        const artifactIdentities = extractA2AArtifactIdentities(toolResults);
+        if (artifactIdentities.length > 0) {
+          assistantMsg.metadata.integrationArtifacts = artifactIdentities;
+        }
+      }
+    }
 
     repo.messages.push(userMsg);
     if (assistantMsg) {

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -110,6 +110,7 @@ export function assembleA2AFinalResponse(
   const finalText = appendA2AArtifactLinks(responseText, [...toolResults], {
     baseUrl: options.baseUrl ?? resolveArtifactBaseUrl(options.event),
     includeReferencedArtifacts: true,
+    includePersistedArtifactMarker: true,
   });
   if (terminalError && !finalText.trim()) {
     throw new Error(formatA2ATerminalError(terminalError));

package/corpus/core/src/server/auth.ts

@@ -104,9 +104,12 @@ import type { BetterAuthConfig } from "./better-auth-instance.js";
 import {
   BUILDER_CONNECT_OWNER_COOKIE,
   BUILDER_CONNECT_PARAM,
+  BUILDER_RELAY_PATH,
+  BUILDER_RELAY_STATE_PARAM,
   BUILDER_STATE_PARAM,
   verifyBuilderCallbackStateAndGetOwner,
   verifyBuilderConnectTokenAndGetOwner,
+  verifyBuilderPreviewRelayStateForCallback,
 } from "./builder-browser.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import {
@@ -1522,7 +1525,15 @@ function verifiedBuilderConnectOwnerFromUrl(url: string): string | null {
   return verifyBuilderConnectTokenAndGetOwner(token);
 }
 
-function shouldBypassAuthForBuilderConnect(event: H3Event, p: string): boolean {
+export function shouldBypassAuthForBuilderConnect(
+  event: H3Event,
+  p: string,
+): boolean {
+  // The preview-safe second hop is authenticated by its timestamped HMAC and
+  // one-shot pending row. It cannot carry a browser session from the corporate
+  // callback deployment, so let the route perform that stronger check itself.
+  if (p === BUILDER_RELAY_PATH) return true;
+
   if (p === "/_agent-native/builder/connect") {
     const url = event.node?.req?.url ?? event.path ?? "/";
     return Boolean(verifiedBuilderConnectOwnerFromUrl(url));
@@ -1537,6 +1548,19 @@ function shouldBypassAuthForBuilderConnect(event: H3Event, p: string): boolean {
             BUILDER_STATE_PARAM,
           )
         : null;
+    const relayState =
+      queryStart >= 0
+        ? new URLSearchParams(url.slice(queryStart + 1)).get(
+            BUILDER_RELAY_STATE_PARAM,
+          )
+        : null;
+    if (relayState) {
+      try {
+        if (verifyBuilderPreviewRelayStateForCallback(relayState)) return true;
+      } catch {
+        // Dedicated relay secret missing: let the auth guard fail closed.
+      }
+    }
     // The signed `_an_state` authenticates this specific Builder callback
     // flow back to our app. A stale localhost session cookie can otherwise
     // make the global guard reject the callback before the handler gets to

package/corpus/core/src/server/builder-browser.ts

@@ -1,4 +1,9 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import {
+  createHash,
+  createHmac,
+  randomBytes,
+  timingSafeEqual,
+} from "node:crypto";
 
 import type { H3Event } from "h3";
 import { getHeader } from "h3";
@@ -15,6 +20,349 @@ const BUILDER_BROWSER_HOST = "agent-native-browser";
 const BUILDER_BROWSER_CLIENT_ID = "Agent Native Browser";
 
 export const BUILDER_CALLBACK_PATH = "/_agent-native/builder/callback";
+export const BUILDER_RELAY_PATH = "/_agent-native/builder/relay";
+export const BUILDER_RELAY_STATE_PARAM = "_an_relay";
+export const BUILDER_RELAY_SECRET_ENV = "AGENT_NATIVE_BUILDER_RELAY_SECRET";
+export const BUILDER_RELAY_TARGET_ORIGINS_ENV =
+  "AGENT_NATIVE_BUILDER_RELAY_TARGET_ORIGINS";
+export const BUILDER_RELAY_TIMESTAMP_HEADER = "x-agent-native-relay-timestamp";
+export const BUILDER_RELAY_FLOW_HEADER = "x-agent-native-relay-flow";
+export const BUILDER_RELAY_SIGNATURE_HEADER = "x-agent-native-relay-signature";
+
+const BUILDER_RELAY_PURPOSE = "builder-preview-callback-relay";
+const BUILDER_RELAY_STATE_VERSION = 1;
+const BUILDER_RELAY_TTL_MS = 10 * 60 * 1000;
+const BUILDER_RELAY_REQUEST_SKEW_MS = 2 * 60 * 1000;
+
+export interface BuilderPreviewRelayState {
+  v: 1;
+  purpose: typeof BUILDER_RELAY_PURPOSE;
+  flowId: string;
+  ownerEmail: string;
+  targetOrigin: string;
+  basePath: string;
+  iat: number;
+  exp: number;
+}
+
+export interface BuilderRelayCredentials {
+  privateKey: string;
+  publicKey: string;
+  userId: string | null;
+  orgName: string | null;
+  orgKind: string | null;
+  subscription: string | null;
+  subscriptionLevel: string | null;
+  subscriptionName: string | null;
+  isEnterprise: boolean | null;
+  isFreeAccount: boolean | null;
+}
+
+export interface BuilderRelayRequestBody {
+  relayState: string;
+  credentials: BuilderRelayCredentials;
+}
+
+function builderRelaySecret(): string {
+  const secret = process.env[BUILDER_RELAY_SECRET_ENV]?.trim();
+  if (!secret) {
+    throw new Error(
+      `${BUILDER_RELAY_SECRET_ENV} is required for Builder preview authorization relay.`,
+    );
+  }
+  if (secret.length < 32) {
+    throw new Error(
+      `${BUILDER_RELAY_SECRET_ENV} must be at least 32 characters long.`,
+    );
+  }
+  return secret;
+}
+
+function builderRelayMac(value: string): string {
+  return createHmac("sha256", builderRelaySecret())
+    .update(value)
+    .digest("base64url");
+}
+
+function safeEqualText(expected: string, actual: string): boolean {
+  const expectedBuffer = Buffer.from(expected);
+  const actualBuffer = Buffer.from(actual);
+  return (
+    expectedBuffer.length === actualBuffer.length &&
+    timingSafeEqual(expectedBuffer, actualBuffer)
+  );
+}
+
+function normalizeBuilderRelayBasePath(value: string): string | null {
+  if (!value) return "";
+  if (!value.startsWith("/") || value.includes("?") || value.includes("#")) {
+    return null;
+  }
+  const normalized = value.replace(/\/+$/, "");
+  if (normalized.split("/").some((part) => part === "." || part === "..")) {
+    return null;
+  }
+  return normalized;
+}
+
+export function isSafeBuilderRelayTargetOrigin(value: string): boolean {
+  try {
+    const url = new URL(value);
+    if (
+      url.origin !== value ||
+      url.username ||
+      url.password ||
+      url.hostname.includes("*")
+    )
+      return false;
+    const hostname = url.hostname.toLowerCase();
+    const loopback =
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "::1" ||
+      hostname === "[::1]";
+    if (loopback)
+      return url.protocol === "http:" && process.env.NODE_ENV !== "production";
+    if (url.protocol !== "https:") return false;
+    return (
+      hostname.endsWith(".netlify.app") ||
+      hostname.endsWith(".vercel.app") ||
+      hostname === "agent-native.com" ||
+      hostname.endsWith(".agent-native.com") ||
+      hostname.endsWith(".builder.io") ||
+      hostname.endsWith(".builderio.xyz") ||
+      hostname.endsWith(".builderio.dev") ||
+      hostname.endsWith(".builder.codes")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function isTrustedBuilderRelayTargetOrigin(value: string): boolean {
+  if (!isSafeBuilderRelayTargetOrigin(value)) return false;
+  const hostname = new URL(value).hostname.toLowerCase();
+  if (
+    hostname.endsWith(".netlify.app") &&
+    !/^[a-f0-9]{24}--[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.netlify\.app$/.test(
+      hostname,
+    )
+  ) {
+    return false;
+  }
+  const configured = process.env[BUILDER_RELAY_TARGET_ORIGINS_ENV];
+  if (!configured) return false;
+  return configured
+    .split(",")
+    .map((origin) => origin.trim())
+    .filter(Boolean)
+    .some((origin) => origin === value && !origin.includes("*"));
+}
+
+export function signBuilderPreviewRelayState(input: {
+  ownerEmail: string;
+  targetOrigin: string;
+  basePath?: string;
+  flowId?: string;
+  now?: number;
+}): { state: string; payload: BuilderPreviewRelayState } {
+  if (!isSafeBuilderRelayTargetOrigin(input.targetOrigin)) {
+    throw new Error(
+      "Builder relay target origin is not an approved preview origin.",
+    );
+  }
+  const basePath = normalizeBuilderRelayBasePath(input.basePath ?? "");
+  if (basePath === null) throw new Error("Builder relay base path is invalid.");
+  const now = input.now ?? Date.now();
+  const payload: BuilderPreviewRelayState = {
+    v: BUILDER_RELAY_STATE_VERSION,
+    purpose: BUILDER_RELAY_PURPOSE,
+    flowId: input.flowId ?? randomBytes(24).toString("base64url"),
+    ownerEmail: input.ownerEmail,
+    targetOrigin: input.targetOrigin,
+    basePath,
+    iat: now,
+    exp: now + BUILDER_RELAY_TTL_MS,
+  };
+  const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString(
+    "base64url",
+  );
+  return { state: `${encoded}.${builderRelayMac(encoded)}`, payload };
+}
+
+export function verifyBuilderPreviewRelayState(
+  state: string | null | undefined,
+  options: { now?: number } = {},
+): BuilderPreviewRelayState | null {
+  if (!state) return null;
+  const parts = state.split(".");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
+  if (!safeEqualText(builderRelayMac(parts[0]), parts[1])) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const payload = value as Partial<BuilderPreviewRelayState>;
+  const now = options.now ?? Date.now();
+  if (
+    payload.v !== BUILDER_RELAY_STATE_VERSION ||
+    payload.purpose !== BUILDER_RELAY_PURPOSE ||
+    typeof payload.flowId !== "string" ||
+    !/^[A-Za-z0-9_-]{24,128}$/.test(payload.flowId) ||
+    typeof payload.ownerEmail !== "string" ||
+    !payload.ownerEmail.includes("@") ||
+    typeof payload.targetOrigin !== "string" ||
+    !isSafeBuilderRelayTargetOrigin(payload.targetOrigin) ||
+    typeof payload.basePath !== "string" ||
+    normalizeBuilderRelayBasePath(payload.basePath) !== payload.basePath ||
+    typeof payload.iat !== "number" ||
+    typeof payload.exp !== "number" ||
+    payload.exp <= payload.iat ||
+    payload.exp - payload.iat > BUILDER_RELAY_TTL_MS ||
+    payload.iat > now + BUILDER_RELAY_REQUEST_SKEW_MS ||
+    payload.exp < now
+  ) {
+    return null;
+  }
+  return payload as BuilderPreviewRelayState;
+}
+
+/**
+ * Corporate callback trust check. Preview-side state verification and relay
+ * receipt deliberately do not require this callback-only allowlist.
+ */
+export function verifyBuilderPreviewRelayStateForCallback(
+  state: string | null | undefined,
+  options: { now?: number } = {},
+): BuilderPreviewRelayState | null {
+  const payload = verifyBuilderPreviewRelayState(state, options);
+  return payload && isTrustedBuilderRelayTargetOrigin(payload.targetOrigin)
+    ? payload
+    : null;
+}
+
+export function getBuilderPreviewRelayUrl(
+  payload: BuilderPreviewRelayState,
+): string {
+  return `${payload.targetOrigin}${payload.basePath}${BUILDER_RELAY_PATH}`;
+}
+
+function builderRelayBodyDigest(body: string): string {
+  return createHash("sha256").update(body).digest("base64url");
+}
+
+function builderRelayRequestSignature(
+  timestamp: number,
+  flowId: string,
+  body: string,
+): string {
+  return builderRelayMac(
+    `v1.${timestamp}.${flowId}.${builderRelayBodyDigest(body)}`,
+  );
+}
+
+export function createBuilderRelayRequest(
+  relayState: string,
+  credentials: BuilderRelayCredentials,
+  options: { now?: number } = {},
+): { body: string; headers: Record<string, string>; url: string } {
+  const payload = verifyBuilderPreviewRelayState(relayState, options);
+  if (!payload) throw new Error("Builder relay state is invalid or expired.");
+  const body = JSON.stringify({
+    relayState,
+    credentials,
+  } satisfies BuilderRelayRequestBody);
+  const timestamp = options.now ?? Date.now();
+  return {
+    body,
+    url: getBuilderPreviewRelayUrl(payload),
+    headers: {
+      "content-type": "application/json",
+      [BUILDER_RELAY_TIMESTAMP_HEADER]: String(timestamp),
+      [BUILDER_RELAY_FLOW_HEADER]: payload.flowId,
+      [BUILDER_RELAY_SIGNATURE_HEADER]: builderRelayRequestSignature(
+        timestamp,
+        payload.flowId,
+        body,
+      ),
+    },
+  };
+}
+
+export function verifyBuilderRelayRequest(input: {
+  body: string;
+  timestamp: string | null | undefined;
+  flowId: string | null | undefined;
+  signature: string | null | undefined;
+  requestOrigin: string;
+  requestBasePath: string;
+  now?: number;
+}): {
+  payload: BuilderPreviewRelayState;
+  body: BuilderRelayRequestBody;
+} | null {
+  const timestamp = Number(input.timestamp);
+  const now = input.now ?? Date.now();
+  if (
+    !Number.isFinite(timestamp) ||
+    Math.abs(now - timestamp) > BUILDER_RELAY_REQUEST_SKEW_MS ||
+    !input.flowId ||
+    !input.signature ||
+    !safeEqualText(
+      builderRelayRequestSignature(timestamp, input.flowId, input.body),
+      input.signature,
+    )
+  ) {
+    return null;
+  }
+  let body: BuilderRelayRequestBody;
+  try {
+    body = JSON.parse(input.body) as BuilderRelayRequestBody;
+  } catch {
+    return null;
+  }
+  const payload = verifyBuilderPreviewRelayState(body.relayState, { now });
+  if (
+    !payload ||
+    payload.flowId !== input.flowId ||
+    payload.targetOrigin !== input.requestOrigin ||
+    payload.basePath !== input.requestBasePath ||
+    !body.credentials ||
+    typeof body.credentials.privateKey !== "string" ||
+    typeof body.credentials.publicKey !== "string" ||
+    !body.credentials.privateKey ||
+    !body.credentials.publicKey
+  ) {
+    return null;
+  }
+  const nullableString = (value: unknown): string | null =>
+    typeof value === "string" ? value : null;
+  const nullableBoolean = (value: unknown): boolean | null =>
+    typeof value === "boolean" ? value : null;
+  return {
+    payload,
+    body: {
+      relayState: body.relayState,
+      // Explicitly rebuild the credential payload. Extra fields such as an
+      // attacker-supplied ownerEmail/orgId never reach the credential writer.
+      credentials: {
+        privateKey: body.credentials.privateKey,
+        publicKey: body.credentials.publicKey,
+        userId: nullableString(body.credentials.userId),
+        orgName: nullableString(body.credentials.orgName),
+        orgKind: nullableString(body.credentials.orgKind),
+        subscription: nullableString(body.credentials.subscription),
+        subscriptionLevel: nullableString(body.credentials.subscriptionLevel),
+        subscriptionName: nullableString(body.credentials.subscriptionName),
+        isEnterprise: nullableBoolean(body.credentials.isEnterprise),
+        isFreeAccount: nullableBoolean(body.credentials.isFreeAccount),
+      },
+    },
+  };
+}
 
 function escapeHtml(value: string): string {
   return value.replace(/[&<>"']/g, (ch) => {
@@ -516,6 +864,7 @@ export function buildBuilderCliAuthUrl(
   state: string | null = null,
   options: {
     previewOrigin?: string;
+    relayState?: string;
     tracking?: BuilderConnectTrackingParams;
   } = {},
 ): string {
@@ -536,6 +885,9 @@ export function buildBuilderCliAuthUrl(
   if (state) {
     callbackUrl.searchParams.set(BUILDER_STATE_PARAM, state);
   }
+  if (options.relayState) {
+    callbackUrl.searchParams.set(BUILDER_RELAY_STATE_PARAM, options.relayState);
+  }
   // When the cli-auth allow-list forces preview_url onto the gateway origin,
   // the callback would otherwise lose the real opener origin and post its
   // success message to the gateway instead of the preview tab. Embed the