@agent-native/core 0.153.0 → 0.153.1

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/auth.js

@@ -56,9 +56,9 @@ import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
 import { injectAnalyticsIntoHtml } from "./analytics.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { getAppProductionUrl } from "./app-url.js";
-import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
+import { readAnalyticsAnonymousId, readFirstTouchAttribution, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
-import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
+import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } 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 { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
@@ -67,6 +67,7 @@ import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
 import { isElectron as isElectronRequest, getAppBasePath, getAppUrl, getOrigin, encodeOAuthState, decodeOAuthState, createOAuthSession, oauthCallbackResponse, oauthDesktopExchangePage, oauthErrorPage, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, } from "./google-oauth.js";
 import { isCanonicalAgentNativeAppRequest, isDesktopSsoCanaryUserAgent, isIdentitySsoEnabled, } from "./identity-sso-store.js";
 import { ensureCanonicalUserForLegacySession } from "./legacy-auth-migration.js";
+import { encodeMagicLinkSignupAttribution, MAGIC_LINK_ATTRIBUTION_PARAM, } from "./magic-link-attribution.js";
 import { safeOAuthReturnUrl } from "./oauth-return-url.js";
 import { getOnboardingHtml, getResetPasswordHtml, } from "./onboarding-html.js";
 import { captureAuthError } from "./sentry.js";
@@ -3333,12 +3334,25 @@ async function mountBetterAuthRoutes(app, options) {
                 callbackPath = withDesktopMagicLinkFlow(callbackPath, desktopFlow);
             }
             const callbackURL = betterAuthCallbackURL(callbackPath, true, event);
-            const newUserCallbackPath = `${getAppBasePath()}/_agent-native/auth/magic-link/new-user?return=${encodeURIComponent(callbackPath)}`;
+            const cookieHeader = getHeader(event, "cookie") ?? null;
+            const signupAttribution = signupAttributionFromCookieHeader(cookieHeader);
+            const signupAnonymousId = readAnalyticsAnonymousId(cookieHeader);
+            const hasSignupAttribution = !!readFirstTouchAttribution(cookieHeader) || !!signupAnonymousId;
+            const attributionToken = hasSignupAttribution
+                ? encodeMagicLinkSignupAttribution({
+                    attribution: signupAttribution,
+                    anonymousId: signupAnonymousId,
+                }, getAuthSecret())
+                : undefined;
+            const newUserCallbackUrl = new URL(`${getAppBasePath()}/_agent-native/auth/magic-link/new-user?return=${encodeURIComponent(callbackPath)}`, getOrigin(event));
+            if (attributionToken) {
+                newUserCallbackUrl.searchParams.set(MAGIC_LINK_ATTRIBUTION_PARAM, attributionToken);
+            }
             await auth.api.signInMagicLink({
                 body: {
                     email,
                     callbackURL,
-                    newUserCallbackURL: betterAuthCallbackURL(newUserCallbackPath, true, event),
+                    newUserCallbackURL: betterAuthCallbackURL(`${newUserCallbackUrl.pathname}${newUserCallbackUrl.search}`, true, event),
                 },
                 headers: event.headers,
             });

package/dist/server/better-auth-instance.js

@@ -32,6 +32,7 @@ import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
 import { renderMagicLinkEmail, renderResetPasswordEmail, renderVerifySignupEmail, } from "./email-templates.js";
 import { getEmailReadiness, sendEmail } from "./email.js";
 import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
+import { readMagicLinkSignupAttribution } from "./magic-link-attribution.js";
 export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, } from "./auth-login-mode.js";
 async function flushSignupTracking() {
     try {
@@ -982,8 +983,14 @@ async function createBetterAuthInstance(config) {
                             const cookieHeader = context?.headers?.get("cookie") ??
                                 context?.request?.headers?.get("cookie") ??
                                 null;
+                            const magicLinkAttribution = context?.request?.url?.includes("newUserCallbackURL")
+                                ? readMagicLinkSignupAttribution(context.request.url, getAuthSecret())
+                                : undefined;
                             attribution = signupAttributionFromCookieHeader(cookieHeader);
-                            anonymousId = readAnalyticsAnonymousId(cookieHeader);
+                            attribution = magicLinkAttribution?.attribution ?? attribution;
+                            anonymousId =
+                                magicLinkAttribution?.anonymousId ??
+                                    readAnalyticsAnonymousId(cookieHeader);
                         }
                         catch (err) {
                             console.error("[auth] failed to derive signup attribution", err);

package/dist/server/magic-link-attribution.d.ts

@@ -0,0 +1,21 @@
+/** Query parameter carried by Better Auth's new-user callback URL. */
+export declare const MAGIC_LINK_ATTRIBUTION_PARAM = "signup_attribution";
+export interface MagicLinkSignupAttribution {
+    attribution?: Record<string, string>;
+    anonymousId?: string;
+}
+/**
+ * Sign the attribution captured when a magic link is requested. The token is
+ * analytics context only; it never authorizes the user or changes the return
+ * URL. The Better Auth secret keeps the callback from accepting forged data.
+ */
+export declare function encodeMagicLinkSignupAttribution(value: MagicLinkSignupAttribution, secret: string, now?: number): string | undefined;
+/** Verify and decode a token previously produced by
+ * {@link encodeMagicLinkSignupAttribution}. */
+export declare function decodeMagicLinkSignupAttribution(token: string | null | undefined, secret: string, now?: number): MagicLinkSignupAttribution | null | undefined;
+/**
+ * Read the signed handoff from Better Auth's magic-link verification request.
+ * Better Auth copies `newUserCallbackURL` into the verification URL, so this
+ * remains available even when the link is opened on another device.
+ */
+export declare function readMagicLinkSignupAttribution(requestUrl: string | undefined, secret: string, now?: number): MagicLinkSignupAttribution | null | undefined;

package/dist/server/magic-link-attribution.js

@@ -0,0 +1,115 @@
+import crypto from "node:crypto";
+import { normalizeAnalyticsAnonymousId } from "../shared/analytics-anonymous-id.js";
+/** Query parameter carried by Better Auth's new-user callback URL. */
+export const MAGIC_LINK_ATTRIBUTION_PARAM = "signup_attribution";
+/** Better Auth's magic-link token is valid for five minutes; keep this handoff
+ * slightly longer so clock skew does not discard a still-valid link. */
+const MAGIC_LINK_ATTRIBUTION_TTL_SECONDS = 10 * 60;
+const MAX_ATTRIBUTION_FIELDS = 32;
+const MAX_ATTRIBUTION_VALUE_LENGTH = 200;
+function sanitizeAttribution(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, raw] of Object.entries(value).slice(0, MAX_ATTRIBUTION_FIELDS)) {
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(key) ||
+            typeof raw !== "string" ||
+            raw.length === 0) {
+            continue;
+        }
+        out[key] = raw.slice(0, MAX_ATTRIBUTION_VALUE_LENGTH);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function encodePayload(payload) {
+    return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+/**
+ * Sign the attribution captured when a magic link is requested. The token is
+ * analytics context only; it never authorizes the user or changes the return
+ * URL. The Better Auth secret keeps the callback from accepting forged data.
+ */
+export function encodeMagicLinkSignupAttribution(value, secret, now = Date.now()) {
+    if (!secret)
+        return undefined;
+    const attribution = sanitizeAttribution(value.attribution);
+    const anonymousId = normalizeAnalyticsAnonymousId(value.anonymousId);
+    if (!attribution && !anonymousId)
+        return undefined;
+    const payload = {
+        exp: Math.floor(now / 1000) + MAGIC_LINK_ATTRIBUTION_TTL_SECONDS,
+        ...(attribution ? { attribution } : {}),
+        ...(anonymousId ? { anonymousId } : {}),
+    };
+    const data = encodePayload(payload);
+    const signature = crypto
+        .createHmac("sha256", secret)
+        .update(data)
+        .digest("base64url");
+    return `${data}.${signature}`;
+}
+/** Verify and decode a token previously produced by
+ * {@link encodeMagicLinkSignupAttribution}. */
+export function decodeMagicLinkSignupAttribution(token, secret, now = Date.now()) {
+    if (token === null || token === undefined)
+        return undefined;
+    if (!token || !secret)
+        return null;
+    try {
+        const dotIndex = token.lastIndexOf(".");
+        if (dotIndex <= 0 || dotIndex === token.length - 1)
+            return null;
+        const data = token.slice(0, dotIndex);
+        const signature = token.slice(dotIndex + 1);
+        const expected = crypto
+            .createHmac("sha256", secret)
+            .update(data)
+            .digest("base64url");
+        if (signature.length !== expected.length ||
+            !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+            return null;
+        }
+        const payload = JSON.parse(Buffer.from(data, "base64url").toString("utf8"));
+        if (typeof payload.exp !== "number" ||
+            payload.exp < Math.floor(now / 1000)) {
+            return null;
+        }
+        const attribution = sanitizeAttribution(payload.attribution);
+        const anonymousId = normalizeAnalyticsAnonymousId(payload.anonymousId);
+        if (!attribution && !anonymousId)
+            return undefined;
+        return {
+            ...(attribution ? { attribution } : {}),
+            ...(anonymousId ? { anonymousId } : {}),
+        };
+    }
+    catch {
+        // coercion-ok: malformed signed input is distinct from absent context.
+        return null;
+    }
+}
+/**
+ * Read the signed handoff from Better Auth's magic-link verification request.
+ * Better Auth copies `newUserCallbackURL` into the verification URL, so this
+ * remains available even when the link is opened on another device.
+ */
+export function readMagicLinkSignupAttribution(requestUrl, secret, now = Date.now()) {
+    if (!requestUrl)
+        return undefined;
+    try {
+        const verificationUrl = new URL(requestUrl, "http://localhost");
+        if (!verificationUrl.pathname.endsWith("/magic-link/verify")) {
+            return undefined;
+        }
+        const callback = verificationUrl.searchParams.get("newUserCallbackURL");
+        if (!callback)
+            return undefined;
+        const callbackUrl = new URL(callback, verificationUrl.origin);
+        return decodeMagicLinkSignupAttribution(callbackUrl.searchParams.get(MAGIC_LINK_ATTRIBUTION_PARAM), secret, now);
+    }
+    catch {
+        // coercion-ok: malformed request input is distinct from absent context.
+        return null;
+    }
+}

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.153.0",
+  "version": "0.153.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {