@agent-native/core 0.158.6 → 0.158.7

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

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

@@ -1538,6 +1538,162 @@ function escapeHtmlAttr(value) {
 const DESKTOP_MAGIC_LINK_CALLBACK_PATH = "/_agent-native/auth/magic-link/desktop-callback";
 const DESKTOP_MAGIC_LINK_LANDING_PATH = "/_agent-native/auth/magic-link/desktop-landing";
 const BETTER_AUTH_MAGIC_LINK_VERIFY_PATH = "/_agent-native/auth/ba/magic-link/verify";
+function magicLinkDigest(value) {
+    return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function magicLinkStoredIdentifier(token) {
+    return crypto.createHash("sha256").update(token).digest("base64url");
+}
+function redactMagicLinkUrl(value, baseURL) {
+    try {
+        const url = new URL(value, baseURL);
+        for (const key of ["token", "flow_id", "verifier", "state"]) {
+            if (url.searchParams.has(key))
+                url.searchParams.set(key, "[redacted]");
+        }
+        for (const key of [
+            "callbackURL",
+            "newUserCallbackURL",
+            "errorCallbackURL",
+        ]) {
+            const callback = url.searchParams.get(key);
+            if (!callback)
+                continue;
+            try {
+                const callbackURL = new URL(callback, url.origin);
+                for (const nestedKey of ["flow_id", "verifier", "state"]) {
+                    if (callbackURL.searchParams.has(nestedKey)) {
+                        callbackURL.searchParams.set(nestedKey, "[redacted]");
+                    }
+                }
+                url.searchParams.set(key, callbackURL.toString());
+            }
+            catch {
+                url.searchParams.set(key, "[invalid]");
+            }
+        }
+        return `${url.pathname}${url.search}`;
+    }
+    catch {
+        return "[invalid-url]";
+    }
+}
+function magicLinkRequestDetails(event, values, verificationURL) {
+    const token = typeof values.token === "string" ? values.token.trim() : "";
+    const callbackValue = typeof values.callbackURL === "string" ? values.callbackURL : "";
+    let callback;
+    try {
+        callback = callbackValue
+            ? new URL(callbackValue, getOrigin(event))
+            : undefined;
+    }
+    catch {
+        callback = undefined;
+    }
+    return {
+        requestMethod: getMethod(event),
+        requestUrl: redactMagicLinkUrl(event.node?.req?.url ?? event.path ?? "", getOrigin(event)),
+        verificationUrl: verificationURL
+            ? redactMagicLinkUrl(verificationURL.toString(), getOrigin(event))
+            : undefined,
+        verificationMethod: verificationURL ? "GET" : undefined,
+        tokenPresent: Boolean(token),
+        tokenLength: token.length || undefined,
+        tokenDigest: token ? magicLinkDigest(token) : undefined,
+        expectedStoredIdentifierPrefix: token
+            ? magicLinkStoredIdentifier(token).slice(0, 16)
+            : undefined,
+        callbackURLPresent: Boolean(callbackValue),
+        callbackPath: callback?.pathname,
+        hasFlowId: Boolean(callback?.searchParams.get("flow_id")),
+        hasVerifier: Boolean(callback?.searchParams.get("verifier")),
+        hasState: Boolean(callback?.searchParams.get("state") || values.state),
+    };
+}
+async function inspectMagicLinkVerification(auth, token) {
+    const storedIdentifier = magicLinkStoredIdentifier(token);
+    try {
+        const context = await auth.$context;
+        const findVerificationValue = context?.internalAdapter?.findVerificationValue;
+        if (typeof findVerificationValue !== "function") {
+            return {
+                lookup: "adapter-unavailable",
+                lookupKeyPrefix: storedIdentifier.slice(0, 16),
+            };
+        }
+        const record = await findVerificationValue(storedIdentifier);
+        if (!record) {
+            return {
+                lookup: "absent",
+                lookupKeyPrefix: storedIdentifier.slice(0, 16),
+            };
+        }
+        const expiresAt = new Date(String(record.expiresAt ?? ""));
+        const expiryState = Number.isFinite(expiresAt.getTime())
+            ? expiresAt.getTime() <= Date.now()
+                ? "expired"
+                : "valid"
+            : "invalid-expiry";
+        return {
+            lookup: "present",
+            lookupKeyPrefix: storedIdentifier.slice(0, 16),
+            expiryState,
+            expiresAt: Number.isFinite(expiresAt.getTime())
+                ? expiresAt.toISOString()
+                : undefined,
+            valuePresent: "value" in record,
+        };
+    }
+    catch (error) {
+        return {
+            lookup: "lookup-error",
+            lookupKeyPrefix: storedIdentifier.slice(0, 16),
+            errorType: error instanceof Error ? error.constructor.name : "unknown",
+        };
+    }
+}
+function logMagicLinkDebug(event, phase, details = {}) {
+    console.info("[agent-native][magic-link]", {
+        phase,
+        app: getOAuthStateAppId(),
+        agentNativeDesktop: /AgentNativeDesktop/i.test(getHeader(event, "user-agent") || ""),
+        ...details,
+    });
+}
+function magicLinkResponseError(response, baseURL) {
+    const location = response.headers.get("location");
+    if (!location)
+        return undefined;
+    try {
+        return new URL(location, baseURL).searchParams.get("error") || undefined;
+        // coercion-ok: a malformed redirect cannot contain a diagnostic error code.
+    }
+    catch {
+        return undefined;
+    }
+}
+function logMagicLinkVerificationResponse(event, source, response, preConsume) {
+    const error = magicLinkResponseError(response, getOrigin(event));
+    const invalidToken = error === "INVALID_TOKEN";
+    logMagicLinkDebug(event, "verify-response", {
+        source,
+        responseStatus: response.status,
+        responseLocation: redactMagicLinkUrl(response.headers.get("location") || "", getOrigin(event)),
+        producer: invalidToken ? "better-auth.magic-link.verify" : undefined,
+        reason: invalidToken ? "consumeVerificationValue returned null" : undefined,
+        preConsume,
+        classification: invalidToken
+            ? preConsume?.lookup === "present" && preConsume.expiryState === "valid"
+                ? "valid-row-before-consume"
+                : preConsume?.lookup === "present" &&
+                    preConsume.expiryState === "expired"
+                    ? "expired-row"
+                    : preConsume?.lookup === "absent"
+                        ? "row-absent-before-consume"
+                        : "unresolved"
+            : undefined,
+    });
+}
 function desktopMagicLinkVerificationUrl(event, values) {
     const value = (key) => typeof values[key] === "string" ? values[key] : "";
     const token = value("token").trim();
@@ -3092,19 +3248,47 @@ async function mountBetterAuthRoutes(app, options) {
         if (getMethod(event) === "POST") {
             const body = await readBody(event);
             const verificationURL = desktopMagicLinkVerificationUrl(event, body);
+            const requestDetails = magicLinkRequestDetails(event, body, verificationURL);
             if (!verificationURL) {
+                logMagicLinkDebug(event, "verify-rejected-before-better-auth", {
+                    source: "desktop-landing",
+                    ...requestDetails,
+                    reason: "invalid-desktop-verification-url",
+                });
                 setResponseStatus(event, 400);
                 return { error: "Invalid desktop magic-link" };
             }
+            const token = typeof body.token === "string" ? body.token.trim() : "";
+            const preConsume = await inspectMagicLinkVerification(auth, token);
+            logMagicLinkDebug(event, "verify-request", {
+                source: "desktop-landing",
+                ...requestDetails,
+                preConsume,
+            });
             // Verify inside the same request that received the explicit user
             // confirmation. A browser redirect would create a second network
             // hop where link scanners, redirect handling, or a fresh serverless
             // request could consume or lose the one-time token before the
             // desktop callback sees the Better Auth session cookie.
-            return auth.handler(new Request(verificationURL, {
-                method: "GET",
-                headers: event.headers,
-            }));
+            try {
+                const response = await auth.handler(new Request(verificationURL, {
+                    method: "GET",
+                    headers: event.headers,
+                }));
+                if (response instanceof Response) {
+                    logMagicLinkVerificationResponse(event, "desktop-landing", response, preConsume);
+                }
+                return response;
+            }
+            catch (error) {
+                logMagicLinkDebug(event, "verify-exception", {
+                    source: "desktop-landing",
+                    ...requestDetails,
+                    preConsume,
+                    errorType: error instanceof Error ? error.constructor.name : "unknown",
+                });
+                throw error;
+            }
         }
         if (!isReadMethod(event)) {
             setResponseStatus(event, 405);
@@ -3157,6 +3341,17 @@ async function mountBetterAuthRoutes(app, options) {
                 message: AUTH_MAGIC_LINK_FALLBACK,
                 code: code || "callback_error",
             });
+            logMagicLinkDebug(event, "callback-error", {
+                source: "desktop-callback",
+                flow: oauthDebugFlowId(flowId),
+                callbackError: code || "callback_error",
+                producer: code === "INVALID_TOKEN"
+                    ? "better-auth.magic-link.verify"
+                    : "desktop-callback",
+                reason: code === "INVALID_TOKEN"
+                    ? "upstream-verifier-reported-invalid-token"
+                    : "callback-carried-error",
+            });
             logGoogleOAuthDebug(event, "magic-link-callback-error", {
                 flowId,
                 message: callbackError,
@@ -3224,11 +3419,27 @@ async function mountBetterAuthRoutes(app, options) {
         const isSendVerificationEmail = reqPath.includes("send-verification-email") &&
             getMethod(event) === "POST";
         const isMagicLinkRequest = reqPath.includes("/sign-in/magic-link") && getMethod(event) === "POST";
+        const isMagicLinkVerification = reqPath.includes("/magic-link/verify") && getMethod(event) === "GET";
         const isSignOut = reqPath.includes("sign-out") && getMethod(event) === "POST";
         if (isSignOut)
             optOutOfAuthDisabledSession(event);
         const authRequest = toWebRequest(event);
         let requestForAuth = authRequest;
+        let magicLinkPreConsume;
+        if (isMagicLinkVerification) {
+            const verificationURL = new URL(authRequest.url);
+            const values = Object.fromEntries(verificationURL.searchParams.entries());
+            const requestDetails = magicLinkRequestDetails(event, values, verificationURL);
+            const token = typeof values.token === "string" ? values.token.trim() : "";
+            magicLinkPreConsume = token
+                ? await inspectMagicLinkVerification(auth, token)
+                : undefined;
+            logMagicLinkDebug(event, "verify-request", {
+                source: "better-auth-catch-all",
+                ...requestDetails,
+                preConsume: magicLinkPreConsume,
+            });
+        }
         // Better Auth is also reachable directly, outside the legacy login
         // wrapper. Check its password endpoints before handing the request to
         // Better Auth so an org policy cannot be bypassed through the raw API.
@@ -3330,10 +3541,26 @@ async function mountBetterAuthRoutes(app, options) {
                 // validation error.
             }
         }
-        let response = await auth.handler(requestForAuth);
+        let response;
+        try {
+            response = await auth.handler(requestForAuth);
+        }
+        catch (error) {
+            if (isMagicLinkVerification) {
+                logMagicLinkDebug(event, "verify-exception", {
+                    source: "better-auth-catch-all",
+                    errorType: error instanceof Error ? error.constructor.name : "unknown",
+                    preConsume: magicLinkPreConsume,
+                });
+            }
+            throw error;
+        }
         const isResponse = response != null &&
             typeof response.status === "number" &&
             typeof response.headers?.get === "function";
+        if (isMagicLinkVerification && isResponse) {
+            logMagicLinkVerificationResponse(event, "better-auth-catch-all", response, magicLinkPreConsume);
+        }
         if (isResponse && response.status >= 400) {
             // The direct Better Auth surface is also reachable from the browser,
             // so wrapper-route sanitization alone is not enough to keep adapter

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

@@ -1158,7 +1158,35 @@ async function createBetterAuthInstance(config) {
                 storeToken: "hashed",
                 rateLimit: { window: 60, max: 5 },
                 disableSignUp,
-                sendMagicLink: async ({ email, url }) => {
+                sendMagicLink: async ({ email, url, token }) => {
+                    let urlPath;
+                    let urlQueryKeys;
+                    try {
+                        const parsedURL = new URL(url);
+                        urlPath = parsedURL.pathname;
+                        urlQueryKeys = [...parsedURL.searchParams.keys()].sort();
+                    }
+                    catch {
+                        // coercion-ok: diagnostics must never make email delivery fail.
+                        // Better Auth owns URL construction; keep diagnostics non-fatal.
+                    }
+                    if (typeof token === "string") {
+                        console.info("[agent-native][magic-link]", {
+                            phase: "issued",
+                            tokenDigest: crypto
+                                .createHash("sha256")
+                                .update(token)
+                                .digest("hex")
+                                .slice(0, 16),
+                            expectedStoredIdentifierPrefix: crypto
+                                .createHash("sha256")
+                                .update(token)
+                                .digest("base64url")
+                                .slice(0, 16),
+                            urlPath,
+                            urlQueryKeys,
+                        });
+                    }
                     const appBasePath = (process.env.VITE_APP_BASE_PATH ||
                         process.env.APP_BASE_PATH ||
                         "").replace(/\/$/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.158.6",
+  "version": "0.158.7",
   "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": {