@agent-native/core 0.214.0 → 0.217.0

package/dist/server/analytics.js

@@ -1,5 +1,7 @@
 import { getAppConfig } from "../app-config/index.js";
+import { CONSENT_REGION_PATH, CONSENT_REGION_TIME_ZONE_LIST, } from "../shared/consent.js";
 import { SYNTHETIC_TRAFFIC_BETA_E2E } from "../shared/test-traffic.js";
+import { publicFrameworkPath } from "./framework-route-prefix.js";
 const AGENT_NATIVE_ANALYTICS_DEFAULT_ENDPOINT = "https://analytics.agent-native.com/track";
 function normalizeMeasurementId(value) {
     const trimmed = value?.trim();
@@ -54,18 +56,18 @@ export function getAgentNativeAnalyticsConfigScript() {
         ");</script>",
     ].join("");
 }
-function escapeHtmlAttribute(value) {
-    return value
-        .replace(/&/g, "&amp;")
-        .replace(/"/g, "&quot;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
-}
-export function getHeadScriptTag() {
+// A deployment's widget may set cookies or track, so it waits for
+// performance consent like GA does.
+function getHeadScript() {
     const src = getAppConfig().analytics.headScriptSrc;
     if (!src)
         return null;
-    return `<script src="${escapeHtmlAttribute(src)}" defer data-agent-native-head-script></script>`;
+    // "<" inside an inline script could close it early.
+    const jsSrc = JSON.stringify(src).replace(/</g, "\\x3c");
+    return consentGatedScript("performance", `var agentNativeHeadScript=document.createElement('script');` +
+        `agentNativeHeadScript.src=${jsSrc};` +
+        `agentNativeHeadScript.setAttribute('data-agent-native-head-script','');` +
+        `document.head.appendChild(agentNativeHeadScript);`);
 }
 export function getGaInlineConfigScriptBody(options) {
     const id = getGaMeasurementId();
@@ -100,47 +102,106 @@ export function getGaInlineConfigScriptBody(options) {
         `document.head.appendChild(agentNativeGtagScript);` +
         `}`);
 }
+/**
+ * Queue `body` until the visitor's region and choice allow `category`; the
+ * bootstrap after it, or `client/consent.ts` once loaded, runs it. A reject
+ * then a fresh accept calls it again, so it loads its tag only once a page.
+ */
+function consentGatedScript(category, body) {
+    return `<script>(window.__AN_CONSENT_QUEUE__=window.__AN_CONSENT_QUEUE__||[]).push([${JSON.stringify(category)},(function(){var ran=false;return function(){if(ran)return;ran=true;${body}}})()]);</script>`;
+}
+const GA_FALLBACK_DATA_LAYER = "__AGENT_NATIVE_GA_DATA_LAYER__";
+// gtag reads an `arguments` object from the data layer, never an array.
+const GOOGLE_CONSENT_PUSH = `function push(g){for(var i=0;i<L.length;i++){var l=w[L[i]]=w[L[i]]||[];` +
+    `(function(){l.push(arguments)})("consent",g.mode,{analytics_storage:g.p?"granted":"denied",ad_storage:g.t?"granted":"denied",ad_user_data:g.t?"granted":"denied",ad_personalization:g.t?"granted":"denied"})}}`;
+/**
+ * Google Consent Mode: before any Google tag loads, tell each data layer
+ * what the stored choice allows (nothing, without one), so tags already on
+ * the page stop storing and sending when `client/consent.ts` later pushes a
+ * reject. Lists the layers there, under `__AN_CONSENT_LAYERS__`.
+ */
+function getGoogleConsentDefaultScript(dataLayers) {
+    return (`<script data-agent-native-consent-mode>(function(w,d){var L=${JSON.stringify(dataLayers)};w.__AN_CONSENT_LAYERS__=L;` +
+        GOOGLE_CONSENT_PUSH +
+        `var m=/(?:^|;\\s*)an_consent=1\\.p([01])\\.t([01])(?:;|$)/.exec(d.cookie||"");` +
+        `push({mode:"default",p:!!m&&m[1]==="1",t:!!m&&m[2]==="1"})` +
+        `})(window,document);</script>`);
+}
+/**
+ * Runs the queued tags on pages that never load the app bundle, like the
+ * plain sign-in page, and runs them without waiting for it elsewhere: at once
+ * for a stored choice or a region already known this session, else after
+ * asking the server, with the time zone as fallback. Once
+ * `client/consent.ts` replaces the queue it owns what's left, so nothing runs
+ * twice. Keep its cookie and region rules in step with that module.
+ */
+function getConsentBootstrapScript() {
+    const zones = JSON.stringify(CONSENT_REGION_TIME_ZONE_LIST);
+    const regionPath = JSON.stringify(publicFrameworkPath(CONSENT_REGION_PATH));
+    return (`<script data-agent-native-consent>(function(w,d){var Q="__AN_CONSENT_QUEUE__",K="an_consent_region";` +
+        `function choice(){var m=/(?:^|;\\s*)an_consent=1\\.p([01])\\.t([01])(?:;|$)/.exec(d.cookie||"");return m?{performance:m[1]==="1",targeting:m[2]==="1"}:null}` +
+        `function allows(c,k,region){return c?c[k]:region==="none"}` +
+        `function run(region){var q=w[Q];if(!Array.isArray(q))return;var c=choice(),keep=[],L=w.__AN_CONSENT_LAYERS__||[];` +
+        GOOGLE_CONSENT_PUSH +
+        `push({mode:"update",p:allows(c,"performance",region),t:allows(c,"targeting",region)});` +
+        `for(var i=0;i<q.length;i++){var e=q[i];if(allows(c,e[0],region)){e[1]()}else{keep.push(e)}}q.length=0;q.push.apply(q,keep)}` +
+        `function zone(){try{return ${zones}.indexOf(Intl.DateTimeFormat().resolvedOptions().timeZone)>-1?"consent":"none"}catch(e){return"consent"}}` +
+        // coercion-ok: a page without session storage asks the server again.
+        `var cached=null;try{cached=w.sessionStorage.getItem(K)}catch(e){}` +
+        `if(choice()||cached==="consent"||cached==="none"){run(cached);return}` +
+        // An unreachable server falls back to the time zone.
+        // coercion-ok: a region it can't save is asked again on the next page.
+        `fetch(${regionPath},{credentials:"same-origin"}).then(function(r){return r.ok?r.json():{}}).then(function(b){return b&&(b.region==="consent"||b.region==="none")?b.region:zone()},zone).then(function(region){try{w.sessionStorage.setItem(K,region)}catch(e){}run(region)})` +
+        `})(window,document);</script>`);
+}
 function getGaScript() {
     const id = getGaMeasurementId();
     if (!id)
         return null;
     const inlineBody = getGaInlineConfigScriptBody();
-    return `<script>${inlineBody}</script>`;
+    return inlineBody ? consentGatedScript("performance", inlineBody) : null;
 }
 function getGtmGaFallbackScript() {
     const inlineBody = getGaInlineConfigScriptBody({
-        dataLayerName: "__AGENT_NATIVE_GA_DATA_LAYER__",
+        dataLayerName: GA_FALLBACK_DATA_LAYER,
         sendPageView: false,
     });
-    return inlineBody ? `<script>${inlineBody}</script>` : null;
+    return inlineBody ? consentGatedScript("performance", inlineBody) : null;
 }
+// The container carries the ad pixels (Meta, LinkedIn, Reddit, X, Bing,
+// Google Ads, OpenAI) and B2B identification tags alongside GA events, so it
+// all waits for targeting. Its <noscript> iframe can't wait, so there is none.
 function getGtmHeadScript(containerId) {
     const jsId = JSON.stringify(containerId);
-    return `<script>if(${getSyntheticTrafficBrowserGuard()}){(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer',${jsId});}</script>`;
-}
-function getGtmBodyFallback(containerId) {
-    const src = encodeURIComponent(containerId);
-    return `<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=${src}" height="0" width="0" style="display:none;visibility:hidden" title="Google Tag Manager"></iframe></noscript>`;
+    return consentGatedScript("targeting", `if(${getSyntheticTrafficBrowserGuard()}){(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer',${jsId});}`);
 }
 function getAnalyticsInjection() {
     const agentNativeAnalytics = getAgentNativeAnalyticsConfigScript();
-    const headScript = getHeadScriptTag();
+    const headScript = getHeadScript();
     const containerId = getGtmContainerId();
     if (containerId) {
         return {
             head: [
                 agentNativeAnalytics,
+                getGoogleConsentDefaultScript(["dataLayer", GA_FALLBACK_DATA_LAYER]),
                 getGtmHeadScript(containerId),
                 getGtmGaFallbackScript(),
                 headScript,
+                getConsentBootstrapScript(),
             ]
                 .filter(Boolean)
                 .join(""),
-            body: getGtmBodyFallback(containerId),
+            body: "",
         };
     }
     const gaScript = getGaScript();
-    const head = [agentNativeAnalytics, gaScript, headScript]
+    const head = [
+        agentNativeAnalytics,
+        gaScript ? getGoogleConsentDefaultScript(["dataLayer"]) : null,
+        gaScript,
+        headScript,
+        gaScript || headScript ? getConsentBootstrapScript() : null,
+    ]
         .filter(Boolean)
         .join("");
     return head ? { head, body: "" } : null;

package/dist/server/application-state-maintenance.d.ts

@@ -0,0 +1,2 @@
+/** Server maintenance helpers stay within the current app-state namespace. */
+export { appStateListKeysByKeySuffixPrefix } from "../application-state/store.js";

package/dist/server/application-state-maintenance.js

@@ -0,0 +1,2 @@
+/** Server maintenance helpers stay within the current app-state namespace. */
+export { appStateListKeysByKeySuffixPrefix } from "../application-state/store.js";

package/dist/server/attribution.d.ts

@@ -13,6 +13,10 @@
  * acquisition; last touch answers "what brought them to sign up?" and credits
  * the post, video, or person that converted them.
  *
+ * First touch also has a durable copy, `an_fts`, that our server sets for a
+ * year (see `first-touch-route.ts`). Signup reads both first-touch cookies and
+ * keeps the one `preferFirstTouch` picks.
+ *
  * This module is intentionally pure and dependency-free so it is trivially
  * unit-testable and can never throw into the signup path. The single hard rule:
  * parsing untrusted cookie input must NEVER throw — every accessor is defensive.
@@ -80,11 +84,21 @@ export declare const LAST_TOUCH_COOKIE_NAME = "an_lt";
 export declare function parseCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
 export declare function decodeFirstTouchValue(value: string | null | undefined): FirstTouchAttribution | null;
 export declare function decodeLastTouchValue(value: string | null | undefined): LastTouchAttribution | null;
+/**
+ * Decode the year-long `an_fts` cookie. A value from another format version
+ * is unreadable here, so it holds no touch.
+ */
+export declare function decodeFirstTouchServerValue(value: string | null | undefined): FirstTouchAttribution | null;
 /**
  * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.
  * Returns `null` when the cookie is absent or unparseable. Never throws.
  */
 export declare function readFirstTouchAttribution(cookieHeader: string | null | undefined): FirstTouchAttribution | null;
+/**
+ * The `an_fts` cookie value for a first touch, dropping the lowest-priority
+ * fields until `name=value` fits its budget.
+ */
+export declare function encodeFirstTouchServerCookieValue(touch: FirstTouchAttribution): string;
 /**
  * Read the `an_lt` last-touch attribution out of a raw `Cookie:` header.
  * Returns `null` when the cookie is absent or unparseable. Never throws.

package/dist/server/attribution.js

@@ -1,6 +1,7 @@
 import { ANALYTICS_ANONYMOUS_ID_COOKIE_NAME, ANALYTICS_ANONYMOUS_ID_MAX_LENGTH, normalizeAnalyticsAnonymousId, } from "../shared/analytics-anonymous-id.js";
 import { ANALYTICS_SESSION_ID_COOKIE_NAME, normalizeAnalyticsSessionId, } from "../shared/analytics-session-id.js";
 import { isSourceReferrerHost, shareLandingSource, } from "../shared/attribution-source.js";
+import { FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES, FIRST_TOUCH_SERVER_COOKIE_NAME, FIRST_TOUCH_SERVER_COOKIE_VERSION, preferFirstTouch, } from "../shared/first-touch-persistence.js";
 export const SIGNUP_ATTRIBUTION_HEADER_NAME = "x-agent-native-signup-attribution";
 const SIGNUP_ATTRIBUTION_HEADER_MAX_LENGTH = 4096;
 export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
@@ -70,7 +71,14 @@ export function decodeFirstTouchValue(value) {
 export function decodeLastTouchValue(value) {
     return decodeAttributionCookieValue(value, LAST_TOUCH_STRING_FIELDS);
 }
-function decodeAttributionCookieValue(value, fields) {
+/**
+ * Decode the year-long `an_fts` cookie. A value from another format version
+ * is unreadable here, so it holds no touch.
+ */
+export function decodeFirstTouchServerValue(value) {
+    return decodeAttributionCookieValue(value, STRING_FIELDS, FIRST_TOUCH_SERVER_COOKIE_VERSION);
+}
+function decodeAttributionCookieValue(value, fields, version) {
     if (!value || typeof value !== "string")
         return null;
     let decoded = value;
@@ -91,6 +99,8 @@ function decodeAttributionCookieValue(value, fields) {
         return null;
     }
     const source = parsed;
+    if (version !== undefined && source.v !== version)
+        return null;
     const result = {};
     let any = false;
     for (const field of fields) {
@@ -109,12 +119,62 @@ function decodeAttributionCookieValue(value, fields) {
 export function readFirstTouchAttribution(cookieHeader) {
     try {
         const cookies = parseCookieHeader(cookieHeader);
-        return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);
+        return preferFirstTouch(decodeFirstTouchServerValue(cookies[FIRST_TOUCH_SERVER_COOKIE_NAME]), decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]));
     }
     catch {
         return null;
     }
 }
+// `landed_at` sets the cookie's expiry and identifies the visit, so it is
+// never the field dropped to fit.
+const FIRST_TOUCH_SERVER_FIELD_PRIORITY = [
+    "landed_at",
+    "gclid",
+    "msclkid",
+    "vector_source",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "ref",
+    "via",
+    "utm_content",
+    "utm_term",
+    "landing_path",
+    "landing_referrer",
+    "site_referrer",
+    "site_landing_path",
+];
+/**
+ * The `an_fts` cookie value for a first touch, dropping the lowest-priority
+ * fields until `name=value` fits its budget.
+ */
+export function encodeFirstTouchServerCookieValue(touch) {
+    const compact = {
+        v: FIRST_TOUCH_SERVER_COOKIE_VERSION,
+    };
+    let truncated = touch.capture_truncated === "1";
+    const encode = (value) => encodeURIComponent(JSON.stringify(value));
+    const fits = (value) => FIRST_TOUCH_SERVER_COOKIE_NAME.length + 1 + encode(value).length <=
+        FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES;
+    // Room for the marker, so adding it later can't push the value over.
+    const withMarker = (value) => ({
+        ...value,
+        capture_truncated: "1",
+    });
+    for (const field of FIRST_TOUCH_SERVER_FIELD_PRIORITY) {
+        const value = touch[field];
+        if (!value)
+            continue;
+        const candidate = { ...compact, [field]: value };
+        if (fits(withMarker(candidate))) {
+            compact[field] = value;
+        }
+        else {
+            truncated = true;
+        }
+    }
+    return encode(truncated ? withMarker(compact) : compact);
+}
 /**
  * Read the `an_lt` last-touch attribution out of a raw `Cookie:` header.
  * Returns `null` when the cookie is absent or unparseable. Never throws.

package/dist/server/auth.js

@@ -5,14 +5,18 @@ import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { newOrgSelection, ORG_SELECTION_COOKIE, } from "../org/request-org-cache.js";
 import { isWorkspaceAppAccessUnavailable, workspaceAppAccessUnavailableBody, } from "../org/workspace-app-access-outcome.js";
 import { checkWorkspaceAppAccessForRequest } from "../org/workspace-app-access-request.js";
+import { CONSENT_PATH, CONSENT_REGION_PATH } from "../shared/consent.js";
 import { EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TARGET_HEADER, isMcpDirectoryWidgetCapabilityScope, } from "../shared/embed-auth.js";
 import { FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_MAX_AGE, } from "../shared/first-run-onboarding.js";
+import { FIRST_TOUCH_SERVER_PATH } from "../shared/first-touch-persistence.js";
 import { isGoogleProfileImageUrl } from "../shared/google-profile-image.js";
 import { EMBED_TRANSPLANT_HEADER, isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
+import { createConsentHandler, createConsentRegionHandler, } from "./consent-route.js";
 import { readDevActionDiscoveryFile } from "./dev-action-discovery.js";
 import { devLoopbackAuthHint } from "./dev-origin-hint.js";
 import { EMAIL_AUTH_LINK_LANDING_PATH, emailAuthLinkFields, emailAuthLinkLandingPage, emailAuthVerificationPath, emailAuthVerificationUrl, } from "./email-auth-links.js";
 import { isEmbedCapabilityScope, revokeEmbedSessionsForOwners, requestHasEmbedAuthMarker, resolveEmbedSessionCookieOwners, resolveEmbedSessionFromRequest, verifyEmbedSessionToken, } from "./embed-session.js";
+import { createFirstTouchHandler } from "./first-touch-route.js";
 import { getPublicFrameworkPathname } from "./framework-request-context.js";
 import { FRAMEWORK_INTERNAL_ROUTE_PREFIX, canonicalFrameworkPathname, getFrameworkRoutePrefix, publicFrameworkPath, } from "./framework-route-prefix.js";
 import { isHttpsRequest } from "./https-request.js";
@@ -5547,6 +5551,9 @@ export async function autoMountAuth(app, options = {}) {
     const workspaceAppAudience = resolveWorkspaceAppAudience(options);
     const workspaceAppRouteAccess = resolveWorkspaceAppRouteAccess(options);
     mountAuthCorsMiddleware(app);
+    app.use(FIRST_TOUCH_SERVER_PATH, createFirstTouchHandler());
+    app.use(CONSENT_REGION_PATH, createConsentRegionHandler());
+    app.use(CONSENT_PATH, createConsentHandler());
     if (options.getSession) {
         customGetSession = options.getSession;
         trustCustomEmailVerification =

package/dist/server/builder-api-auth.d.ts

@@ -16,6 +16,13 @@ export interface BuilderRequestAuthorization {
     authorization: string;
     source: "oauth" | "legacy";
     oauthScope?: RemoteMcpScope;
+    oauthResource?: "general" | "publish";
+    oauthConnectionId?: string;
+    /**
+     * Space selected during Builder OAuth. This is only a request locator; the
+     * provider must verify the token and reject a different apiKey.
+     */
+    oauthSelectedPublicKey?: string;
     legacyCredentialKey?: BuilderLegacyCredentialKey;
     legacyPublicKey?: string;
     userId?: string;

package/dist/server/builder-api-auth.js

@@ -51,6 +51,22 @@ function isBuilderPublishResource(value) {
         !url.search &&
         !url.hash);
 }
+function selectedPublicKeyFromBuilderAccessToken(token) {
+    const payload = token.split(".")[1];
+    if (!payload)
+        return undefined;
+    try {
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return typeof decoded.org === "string" && decoded.org.trim()
+            ? decoded.org.trim()
+            : undefined;
+    }
+    catch {
+        // coercion-ok: an opaque or malformed optional locator claim is absent;
+        // authorization remains the provider's signed-token responsibility.
+        return undefined;
+    }
+}
 async function resolveBuilderPublishAuthorization(ownerEmail, orgId) {
     const candidates = orgId
         ? [{ scope: "org", scopeId: orgId }]
@@ -108,6 +124,7 @@ async function resolveBuilderPublishAuthorization(ownerEmail, orgId) {
             authorization: `Bearer ${match[1]}`,
             source: "oauth",
             oauthScope: candidate.scope,
+            oauthResource: "publish",
         };
     }
     if (ownerEmail) {
@@ -154,6 +171,7 @@ export async function resolveBuilderRequestAuthorization(input = {}) {
                 throw new ActionContractError(`Builder.io access needs re-authorizing to grant ${input.requiredScope}. Open Settings and authorize Builder.io again.`, {
                     errorCode: "builder_oauth_reauthorization_required",
                     statusCode: 400,
+                    details: { reason: "missing_scope", scope: input.requiredScope },
                 });
             }
             throw err;
@@ -168,6 +186,7 @@ export async function resolveBuilderRequestAuthorization(input = {}) {
             throw new ActionContractError(`Builder.io access needs re-authorizing to grant ${input.requiredScope}. Open Settings and authorize Builder.io again.`, {
                 errorCode: "builder_oauth_reauthorization_required",
                 statusCode: 400,
+                details: { reason: "missing_scope", scope: input.requiredScope },
             });
         }
         return {
@@ -175,6 +194,11 @@ export async function resolveBuilderRequestAuthorization(input = {}) {
             authorization: `Bearer ${session.accessToken}`,
             source: "oauth",
             oauthScope: session.scope,
+            oauthResource: "general",
+            ...(session.connectionId
+                ? { oauthConnectionId: session.connectionId }
+                : {}),
+            oauthSelectedPublicKey: selectedPublicKeyFromBuilderAccessToken(session.accessToken),
         };
     }
     return resolveBuilderLegacyRequestAuthorization(input.legacyCredentialKeys);

package/dist/server/builder-oauth.d.ts

@@ -3,7 +3,9 @@ export declare const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
 export declare const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
 export declare const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
 export declare const BUILDER_ASSETS_WRITE_SCOPE = "builder:assets:write";
-export declare const BUILDER_OAUTH_SCOPES: readonly ["builder:ai:invoke", "builder:agents:run", "builder:browser:connect", "builder:assets:write", "builder:projects:read", "builder:projects:write", "builder:designsystem:read", "builder:designsystem:write"];
+export declare const BUILDER_CONTENT_READ_SCOPE = "builder:content:read";
+export declare const BUILDER_CONTENT_WRITE_SCOPE = "builder:content:write";
+export declare const BUILDER_OAUTH_SCOPES: readonly ["builder:ai:invoke", "builder:agents:run", "builder:browser:connect", "builder:assets:write", "builder:content:read", "builder:content:write", "builder:projects:read", "builder:projects:write", "builder:designsystem:read", "builder:designsystem:write"];
 export type BuilderOAuthPermissionScope = (typeof BUILDER_OAUTH_SCOPES)[number];
 export type BuilderOAuthPendingFlow = {
     codeVerifier: string;
@@ -43,6 +45,8 @@ export type BuilderOAuthSession = {
     expiresAt?: number;
     scopes: string[];
     scope: BuilderOAuthScope;
+    /** Opaque identity of the selected stored OAuth credential lane. */
+    connectionId?: string;
 };
 export type BuilderOAuthRequestAccess = BuilderOAuthSession & {
     ownerEmail: string;

package/dist/server/builder-oauth.js

@@ -9,11 +9,15 @@ export const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
 export const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
 export const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
 export const BUILDER_ASSETS_WRITE_SCOPE = "builder:assets:write";
+export const BUILDER_CONTENT_READ_SCOPE = "builder:content:read";
+export const BUILDER_CONTENT_WRITE_SCOPE = "builder:content:write";
 export const BUILDER_OAUTH_SCOPES = [
     BUILDER_OAUTH_SCOPE,
     "builder:agents:run",
     "builder:browser:connect",
     BUILDER_ASSETS_WRITE_SCOPE,
+    BUILDER_CONTENT_READ_SCOPE,
+    BUILDER_CONTENT_WRITE_SCOPE,
     "builder:projects:read",
     "builder:projects:write",
     "builder:designsystem:read",
@@ -290,6 +294,7 @@ export async function getBuilderOAuthSession(ownerEmail, orgId, requiredScope, a
             expiresAt: credentials.tokenExpiresAt,
             scopes,
             scope: options.scope,
+            connectionId: options.key,
         };
     }
     if (requiredScope && missingRequiredScope) {

package/dist/server/consent-route.d.ts

@@ -0,0 +1,41 @@
+import type { H3Event } from "h3";
+import { type ConsentCategory } from "../shared/consent.js";
+/**
+ * The visitor's country from the host's geo header, if it sent one. The
+ * headers a CDN always overwrites come first, so a visitor's own `x-country`
+ * can't outrank them.
+ */
+export declare function requestCountry(event: H3Event): string | undefined;
+/**
+ * A stored choice applies everywhere; without one, the country decides
+ * whether storing `category` cookies requires an opt-in.
+ */
+export declare function requestAllowsConsentCategory(event: H3Event, category: ConsentCategory): boolean;
+/**
+ * `GET /_agent-native/auth/consent-region`: `consent` when the visitor's
+ * country gets the banner, `none` when it doesn't, `unknown` when the host
+ * sent no country. The SSR shell is cached for everyone, so the browser asks
+ * here instead of reading it from the page.
+ */
+export declare function createConsentRegionHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, {
+    error: string;
+    region?: undefined;
+} | {
+    error?: undefined;
+    region: string;
+}>;
+/**
+ * `POST /_agent-native/auth/consent` with `{ choice: "1.p1.t0" }`: write the
+ * visitor's choice from the server. Safari keeps a cookie page JavaScript
+ * wrote for seven days at most, and builder.io asks again only after a year.
+ * Uses the same domain as the browser's copy, so it replaces that copy.
+ */
+export declare function createConsentHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    error: string;
+    stored?: undefined;
+    choice?: undefined;
+} | {
+    error?: undefined;
+    stored: boolean;
+    choice: any;
+}>>;

package/dist/server/consent-route.js

@@ -0,0 +1,102 @@
+import { appendResponseHeader, defineEventHandler, getHeader, getMethod, setResponseHeader, setResponseStatus, } from "h3";
+import { CONSENT_COOKIE_LIFETIME_SECONDS, CONSENT_COOKIE_NAME, consentCookieDomain, isConsentRegionCountry, parseConsent, serializeConsent, } from "../shared/consent.js";
+import { parseCookieHeader } from "./attribution.js";
+import { readBodyWithSizeLimit } from "./h3-helpers.js";
+import { getForwardedRequestOrigin, getForwardedRequestURL, isSameOriginPost, } from "./request-origin.js";
+const MAX_CONSENT_BODY_BYTES = 256;
+/**
+ * The visitor's country from the host's geo header, if it sent one. The
+ * headers a CDN always overwrites come first, so a visitor's own `x-country`
+ * can't outrank them.
+ */
+export function requestCountry(event) {
+    return (netlifyGeoCountry(event) ??
+        getHeader(event, "cf-ipcountry") ??
+        getHeader(event, "x-vercel-ip-country") ??
+        getHeader(event, "x-country"));
+}
+function netlifyGeoCountry(event) {
+    const geo = getHeader(event, "x-nf-geo");
+    if (!geo)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(geo, "base64").toString("utf8"));
+        const code = parsed?.country?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        // coercion-ok: an unreadable geo header is an unknown country; the next
+        // header, or the browser's time zone, decides.
+        return undefined;
+    }
+}
+/**
+ * A stored choice applies everywhere; without one, the country decides
+ * whether storing `category` cookies requires an opt-in.
+ */
+export function requestAllowsConsentCategory(event, category) {
+    const consent = parseConsent(parseCookieHeader(getHeader(event, "cookie"))[CONSENT_COOKIE_NAME]);
+    if (consent)
+        return consent[category];
+    return !isConsentRegionCountry(requestCountry(event));
+}
+/**
+ * `GET /_agent-native/auth/consent-region`: `consent` when the visitor's
+ * country gets the banner, `none` when it doesn't, `unknown` when the host
+ * sent no country. The SSR shell is cached for everyone, so the browser asks
+ * here instead of reading it from the page.
+ */
+export function createConsentRegionHandler() {
+    return defineEventHandler((event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const country = requestCountry(event);
+        if (!country)
+            return { region: "unknown" };
+        return { region: isConsentRegionCountry(country) ? "consent" : "none" };
+    });
+}
+/**
+ * `POST /_agent-native/auth/consent` with `{ choice: "1.p1.t0" }`: write the
+ * visitor's choice from the server. Safari keeps a cookie page JavaScript
+ * wrote for seven days at most, and builder.io asks again only after a year.
+ * Uses the same domain as the browser's copy, so it replaces that copy.
+ */
+export function createConsentHandler() {
+    return defineEventHandler(async (event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        if (!isSameOriginPost(event)) {
+            setResponseStatus(event, 403);
+            return { error: "Cross-origin request" };
+        }
+        let choice;
+        try {
+            const body = await readBodyWithSizeLimit(event, MAX_CONSENT_BODY_BYTES);
+            choice = parseConsent(body?.choice);
+        }
+        catch (error) {
+            if (error.statusCode === 413) {
+                return { error: "Body too large" };
+            }
+            setResponseStatus(event, 400);
+            return { error: "Invalid JSON" };
+        }
+        if (!choice) {
+            setResponseStatus(event, 400);
+            return { error: "Missing choice" };
+        }
+        const domain = consentCookieDomain(getForwardedRequestURL(event).hostname);
+        const secure = getForwardedRequestOrigin(event).startsWith("https:");
+        appendResponseHeader(event, "set-cookie", `${CONSENT_COOKIE_NAME}=${serializeConsent(choice)}; ` +
+            `Max-Age=${CONSENT_COOKIE_LIFETIME_SECONDS}; Path=/; SameSite=Lax` +
+            `${domain ? `; Domain=${domain}` : ""}${secure ? "; Secure" : ""}`);
+        return { stored: true, choice };
+    });
+}

package/dist/server/core-routes-plugin.d.ts

@@ -588,8 +588,8 @@ export declare function createPublicRemoteAgentsHandler(discover?: PublicAgentDi
     error: string;
     agents?: undefined;
 } | {
-    error?: undefined;
     agents: Omit<import("./agent-discovery.js").DiscoveredAgent, "auth" | "kind">[];
+    error?: undefined;
 }>>;
 export declare function getBuilderConnectErrorDisposition(error: unknown, connectAttemptId: string | null): "correlated" | "legacy" | null;
 export declare function getBuilderConnectErrorKey(ownerEmail: string, connectAttemptId?: string | null): string;

package/dist/server/first-touch-route.d.ts

@@ -0,0 +1,39 @@
+import { type FirstTouchAttribution } from "./attribution.js";
+export type FirstTouchSyncResult = {
+    stored: true;
+    firstTouch: FirstTouchAttribution;
+} | {
+    stored: false;
+    reason: "consent_required" | "expired";
+};
+/**
+ * `POST /_agent-native/auth/attribution` with `{ firstTouch }`: keep the
+ * browser's first touch in the year-long `an_fts` cookie. Anyone may call it,
+ * signed in or not, but only from this origin. The value already in the
+ * cookie wins unless `preferFirstTouch` picks the new one, so a slow request
+ * from another tab can't replace a better first touch it never saw. Where the
+ * banner applies and the visitor hasn't accepted targeting cookies, it stores
+ * nothing and clears every attribution cookie. Elsewhere it also writes the
+ * browser's `an_ft` and `an_lt` again, so Safari keeps them their 30 days.
+ */
+export declare function createFirstTouchHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    error: string;
+    reason?: undefined;
+    stored?: undefined;
+    firstTouch?: undefined;
+} | {
+    error?: undefined;
+    stored: false;
+    reason: "consent_required";
+    firstTouch?: undefined;
+} | {
+    error?: undefined;
+    stored: false;
+    reason: "expired";
+    firstTouch?: undefined;
+} | {
+    error?: undefined;
+    reason?: undefined;
+    stored: true;
+    firstTouch: FirstTouchAttribution;
+}>>;