@agent-native/core 0.137.8 → 0.139.0

package/dist/server/auth.js

@@ -54,6 +54,7 @@ import { normalizeWorkspaceAppAudience, workspaceAppAudienceFromEnv, workspaceAp
 import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
 import { injectAnalyticsIntoHtml } from "./analytics.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
+import { getAuthLoginMode } from "./auth-login-mode.js";
 import { ensureGoogleAuthIdentity, getBetterAuth, getBetterAuthSync, } 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";
@@ -791,8 +792,9 @@ function getRequestHost(event) {
         getHeader(event, "host") ??
         undefined);
 }
-function getOnboardingHtmlOptions(options, event, rawPath) {
+function getOnboardingHtmlOptions(options, event, rawPath, authMode) {
     return {
+        authMode,
         googleOnly: options.googleOnly,
         marketing: options.marketing,
         googleSignInNotice: options.googleSignInNotice,
@@ -803,15 +805,16 @@ function getOnboardingHtmlOptions(options, event, rawPath) {
         requestOrigin: event ? getOrigin(event) : undefined,
     };
 }
-function getAuthOnboardingHtml(options, event, rawPath) {
-    return getOnboardingHtml(getOnboardingHtmlOptions(options, event, rawPath));
+function getAuthOnboardingHtml(options, event, rawPath, authMode) {
+    return getOnboardingHtml(getOnboardingHtmlOptions(options, event, rawPath, authMode));
 }
-function getOnboardingLoginHtmlConfig(options) {
+function getOnboardingLoginHtmlConfig(options, authMode) {
     if (options.loginHtml)
-        return { loginHtml: options.loginHtml };
+        return { loginHtml: options.loginHtml, authMode };
     return {
-        loginHtml: getAuthOnboardingHtml(options),
-        getLoginHtml: (event, rawPath) => getAuthOnboardingHtml(options, event, rawPath),
+        authMode,
+        loginHtml: getAuthOnboardingHtml(options, undefined, undefined, authMode),
+        getLoginHtml: (event, rawPath) => getAuthOnboardingHtml(options, event, rawPath, authMode),
     };
 }
 function resolveWorkspaceAppAudience(options = {}) {
@@ -1899,6 +1902,12 @@ function setFirstRunOnboardingCookie(event) {
         maxAge: FIRST_RUN_ONBOARDING_MAX_AGE,
     });
 }
+function clearFirstRunOnboardingCookie(event) {
+    deleteCookie(event, FIRST_RUN_ONBOARDING_COOKIE, {
+        ...crossSiteCookieAttrs(event),
+        path: "/",
+    });
+}
 export function setFrameworkSessionCookie(event, token) {
     clearFrameworkSessionCookies(event);
     setCookie(event, COOKIE_NAME, token, {
@@ -2456,12 +2465,16 @@ async function mountBetterAuthRoutes(app, options) {
         ...(options.googleScopes ? { googleScopes: options.googleScopes } : {}),
     };
     const auth = await getBetterAuth(betterAuthConfig);
+    const authLoginMode = typeof getAuthLoginMode === "function"
+        ? await getAuthLoginMode()
+        : "password";
     // Mount Better Auth catch-all handler at /_agent-native/auth/ba/*
     app.use("/_agent-native/auth/ba", defineEventHandler(async (event) => {
         const reqPath = event.url?.pathname ?? event.path ?? "";
         const isResetPassword = reqPath.includes("reset-password") && getMethod(event) === "POST";
         const isSendVerificationEmail = reqPath.includes("send-verification-email") &&
             getMethod(event) === "POST";
+        const isMagicLinkRequest = reqPath.includes("/sign-in/magic-link") && getMethod(event) === "POST";
         const isSignOut = reqPath.includes("sign-out") && getMethod(event) === "POST";
         if (isSignOut)
             optOutOfAuthDisabledSession(event);
@@ -2471,7 +2484,8 @@ async function mountBetterAuthRoutes(app, options) {
         // wrapper. Check its password endpoints before handing the request to
         // Better Auth so an org policy cannot be bypassed through the raw API.
         if (reqPath.includes("/sign-in/email") ||
-            reqPath.includes("/sign-up/email")) {
+            reqPath.includes("/sign-up/email") ||
+            isMagicLinkRequest) {
             const body = (await authRequest
                 .clone()
                 .json()
@@ -2525,22 +2539,35 @@ async function mountBetterAuthRoutes(app, options) {
         // but the resend endpoint is exposed directly so users can request a
         // fresh link while unauthenticated. Keep that path equally strict:
         // only same-origin relative return paths survive into the email.
-        if (isSendVerificationEmail) {
+        if (isSendVerificationEmail || isMagicLinkRequest) {
             try {
                 const body = (await authRequest
                     .clone()
                     .json()
                     .catch(() => undefined));
-                if (body && typeof body.callbackURL === "string") {
-                    const callbackURL = safeReturnPath(body.callbackURL);
-                    if (callbackURL !== body.callbackURL) {
+                if (body) {
+                    const callbackKeys = isMagicLinkRequest
+                        ? ["callbackURL", "newUserCallbackURL", "errorCallbackURL"]
+                        : ["callbackURL"];
+                    const sanitizedBody = { ...body };
+                    let changed = false;
+                    for (const key of callbackKeys) {
+                        if (typeof body[key] !== "string")
+                            continue;
+                        const callbackURL = safeReturnPath(body[key]);
+                        if (callbackURL !== body[key]) {
+                            sanitizedBody[key] = callbackURL;
+                            changed = true;
+                        }
+                    }
+                    if (changed) {
                         const headers = new Headers(authRequest.headers);
                         headers.delete("content-length");
                         headers.set("content-type", "application/json");
                         requestForAuth = new Request(authRequest.url, {
                             method: authRequest.method,
                             headers,
-                            body: JSON.stringify({ ...body, callbackURL }),
+                            body: JSON.stringify(sanitizedBody),
                             duplex: "half",
                         });
                     }
@@ -2719,6 +2746,46 @@ async function mountBetterAuthRoutes(app, options) {
             return { error: authError.message };
         }
     }));
+    // Passwordless login via Better Auth's rate-limited magic-link plugin.
+    app.use("/_agent-native/auth/magic-link", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const body = await readBody(event);
+        const rawEmail = typeof body?.email === "string" ? body.email : "";
+        const email = normalizeAuthEmail(rawEmail);
+        const callbackURL = typeof body?.callbackURL === "string"
+            ? safeReturnPath(body.callbackURL)
+            : "/";
+        if (!email) {
+            setResponseStatus(event, 400);
+            return { error: VALID_AUTH_EMAIL_MESSAGE };
+        }
+        if (await isGoogleSignInRequiredForEmail(email)) {
+            setResponseStatus(event, 403);
+            return { error: GOOGLE_AUTH_REQUIRED_MESSAGE };
+        }
+        try {
+            await auth.api.signInMagicLink({
+                body: {
+                    email,
+                    callbackURL,
+                    newUserCallbackURL: `${getAppBasePath()}/_agent-native/auth/magic-link/new-user?return=${encodeURIComponent(callbackURL)}`,
+                },
+                headers: event.headers,
+            });
+            return { ok: true };
+        }
+        catch (e) {
+            if (!isExpectedAuthFailure(e)) {
+                captureAuthError(e, { route: "magic-link", email });
+            }
+            const authError = publicAuthError(e, "Unable to send sign-in link");
+            setResponseStatus(event, authError.statusCode ?? 400);
+            return { error: authError.message };
+        }
+    }));
     // Backward-compat: POST /_agent-native/auth/register
     app.use("/_agent-native/auth/register", defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST") {
@@ -2770,6 +2837,7 @@ async function mountBetterAuthRoutes(app, options) {
         if (bearerToken)
             await removeSession(bearerToken);
         clearFrameworkSessionCookies(event);
+        clearFirstRunOnboardingCookie(event);
         optOutOfAuthDisabledSession(event);
         try {
             const result = await auth.api.signOut({
@@ -2838,6 +2906,7 @@ async function mountBetterAuthRoutes(app, options) {
             // 3. Drop the current request's cookie and best-effort sign out
             // of Better Auth (so the response sets the proper expiry header).
             clearFrameworkSessionCookies(event);
+            clearFirstRunOnboardingCookie(event);
             optOutOfAuthDisabledSession(event);
             try {
                 const result = await auth.api.signOut({
@@ -2879,9 +2948,23 @@ async function mountBetterAuthRoutes(app, options) {
             headers: { "Content-Type": "text/html; charset=utf-8" },
         });
     }));
+    // Better Auth redirects new magic-link users through this small public
+    // callback so first-run onboarding is marked only for newly created users.
+    app.use("/_agent-native/auth/magic-link/new-user", defineEventHandler(async (event) => {
+        if (!isReadMethod(event)) {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const query = getQuery(event);
+        const rawReturn = Array.isArray(query.return)
+            ? query.return[0]
+            : query.return;
+        setFirstRunOnboardingCookie(event);
+        return redirectWithStagedCookies(event, safeReturnPath(rawReturn), 302);
+    }));
     // Auth guard — stored both in framework middleware registry AND in
     // _authGuardFn so the server middleware can enforce it on ALL routes.
-    const loginHtmlConfig = getOnboardingLoginHtmlConfig(options);
+    const loginHtmlConfig = getOnboardingLoginHtmlConfig(options, authLoginMode);
     _authGuardConfig = {
         ...loginHtmlConfig,
         publicPaths,
@@ -2996,6 +3079,7 @@ function mountAuthFallbackRoutes(app) {
         if (bearerToken)
             await removeSession(bearerToken);
         clearFrameworkSessionCookies(event);
+        clearFirstRunOnboardingCookie(event);
         optOutOfAuthDisabledSession(event);
         try {
             const auth = await getBetterAuth();
@@ -3064,7 +3148,7 @@ export async function autoMountAuth(app, options = {}) {
                 options.loginHtml ||
                 options.marketing ||
                 options.googleSignInNotice) {
-                const loginHtmlConfig = getOnboardingLoginHtmlConfig(options);
+                const loginHtmlConfig = getOnboardingLoginHtmlConfig(options, _authGuardConfig.authMode);
                 _authGuardConfig.loginHtml = loginHtmlConfig.loginHtml;
                 _authGuardConfig.getLoginHtml = loginHtmlConfig.getLoginHtml;
             }
@@ -3130,6 +3214,7 @@ export async function autoMountAuth(app, options = {}) {
             if (bearerToken)
                 await removeSession(bearerToken);
             clearFrameworkSessionCookies(event);
+            clearFirstRunOnboardingCookie(event);
             optOutOfAuthDisabledSession(event);
             if (isElectronRequest(event))
                 await clearDesktopSso();

package/dist/server/better-auth-instance.d.ts

@@ -6,6 +6,7 @@
  * implementation detail behind those interfaces.
  */
 import { type BetterAuthOptions } from "better-auth";
+export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, type AuthLoginMode, } from "./auth-login-mode.js";
 export declare function hasBetterAuthUserEmail(email: string): Promise<boolean>;
 export declare function trackSignupEvent({ authProvider, authUserId, email, name, attribution, anonymousId, }: {
     authProvider: string;
@@ -64,6 +65,41 @@ export interface BetterAuthInstance {
             token?: string;
             user?: any;
         } | null>;
+        signInMagicLink: (opts: {
+            body: {
+                email: string;
+                name?: string;
+                callbackURL?: string;
+                newUserCallbackURL?: string;
+                errorCallbackURL?: string;
+                metadata?: Record<string, unknown>;
+            };
+            headers: Headers;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        listUserAccounts: (opts: {
+            headers: Headers;
+        }) => Promise<Array<{
+            providerId: string;
+        }>>;
+        setPassword: (opts: {
+            body: {
+                newPassword: string;
+            };
+            headers: Headers;
+        }) => Promise<{
+            status: boolean;
+        }>;
+        changePassword: (opts: {
+            body: {
+                currentPassword: string;
+                newPassword: string;
+            };
+            headers: Headers;
+        }) => Promise<{
+            status: boolean;
+        }>;
         signUpEmail: (opts: {
             body: {
                 email: string;

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

@@ -11,12 +11,14 @@ import path from "node:path";
 import { betterAuth } from "better-auth";
 import { bearer } from "better-auth/plugins/bearer";
 import { jwt } from "better-auth/plugins/jwt";
+import { magicLink } from "better-auth/plugins/magic-link";
 import { pgTable, text as pgText, timestamp as pgTimestamp, boolean as pgBoolean, } from "drizzle-orm/pg-core";
 import { sqliteTable, text as sqliteText, integer as sqliteInteger, } from "drizzle-orm/sqlite-core";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { getDbExec, isPostgres } from "../db/client.js";
 import { getDialect, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolMax, attachNeonPoolErrorLogger, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
 import { ensureTableExists } from "../db/ddl-guard.js";
+import { CORE_RESET_PASSWORD_EMAIL_ID, CORE_VERIFY_SIGNUP_EMAIL_ID, } from "../email-catalog/system-emails.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { getAuthEmailForUserId, getRequiredAuthProviderForEmail, } from "../org/auth-policy.js";
@@ -26,9 +28,10 @@ import { getAppProductionUrl } from "./app-url.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
-import { renderResetPasswordEmail, renderVerifySignupEmail, } from "./email-templates.js";
-import { sendEmail, isEmailConfigured } from "./email.js";
+import { renderMagicLinkEmail, renderResetPasswordEmail, renderVerifySignupEmail, } from "./email-templates.js";
+import { getEmailReadiness, sendEmail } from "./email.js";
 import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
+export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, } from "./auth-login-mode.js";
 async function flushSignupTracking() {
     try {
         await Promise.race([
@@ -889,7 +892,8 @@ async function createBetterAuthInstance(config) {
     const secret = resolveAuthSecret();
     const appUrl = getAppProductionUrl();
     const cookieNamespace = resolveAuthCookieNamespace();
-    const { requireEmailVerification, disableSignUp } = resolveEmailPasswordAuthPolicy(await isEmailConfigured());
+    const emailReadiness = await getEmailReadiness();
+    const { requireEmailVerification, disableSignUp } = resolveEmailPasswordAuthPolicy(emailReadiness.status === "ready");
     const shouldMirrorGoogleAccountTokens = (config?.googleScopes?.length ?? 0) > 0;
     const auth = betterAuth({
         basePath,
@@ -915,7 +919,14 @@ async function createBetterAuthInstance(config) {
                     email: user.email,
                     resetUrl,
                 });
-                await sendEmail({ to: user.email, subject, html, text, appSender });
+                await sendEmail({
+                    to: user.email,
+                    subject,
+                    html,
+                    text,
+                    appSender,
+                    templateId: CORE_RESET_PASSWORD_EMAIL_ID,
+                });
             },
         },
         emailVerification: {
@@ -939,7 +950,14 @@ async function createBetterAuthInstance(config) {
                     email: user.email,
                     verifyUrl,
                 });
-                await sendEmail({ to: user.email, subject, html, text, appSender });
+                await sendEmail({
+                    to: user.email,
+                    subject,
+                    html,
+                    text,
+                    appSender,
+                    templateId: CORE_VERIFY_SIGNUP_EMAIL_ID,
+                });
             },
         },
         socialProviders,
@@ -1111,6 +1129,25 @@ async function createBetterAuthInstance(config) {
                 : {}),
         },
         plugins: [
+            magicLink({
+                expiresIn: 60 * 5,
+                storeToken: "hashed",
+                rateLimit: { window: 60, max: 5 },
+                disableSignUp,
+                sendMagicLink: async ({ email, url }) => {
+                    const appBasePath = (process.env.VITE_APP_BASE_PATH ||
+                        process.env.APP_BASE_PATH ||
+                        "").replace(/\/$/, "");
+                    const magicLinkUrl = appBasePath
+                        ? url.replace(/(\/\/[^/]+)(\/)/, `$1${appBasePath}$2`)
+                        : url;
+                    const { subject, html, text, appSender } = renderMagicLinkEmail({
+                        email,
+                        magicLinkUrl,
+                    });
+                    await sendEmail({ to: email, subject, html, text, appSender });
+                },
+            }),
             // JWT: issue tokens for A2A calls, JWKS endpoint for verification
             jwt({
                 jwt: {

package/dist/server/builder-design-systems.js

@@ -112,7 +112,7 @@ async function resolveBuilderDesignSystemCredentials() {
     if (!credentials.privateKey || !credentials.publicKey) {
         throw new FeatureNotConfiguredError({
             requiredCredential: "BUILDER_PRIVATE_KEY",
-            message: "Connect Builder.io before indexing a design system from Figma or code.",
+            message: "Connect Builder.io (free tier available) before indexing a design system from Figma or code.",
             builderConnectUrl: "/_agent-native/builder/connect",
         });
     }

package/dist/server/core-routes-plugin.js

@@ -856,6 +856,21 @@ export function createCoreRoutesPlugin(options = {}) {
             paths: [FRAMEWORK_ROUTE_PREFIX, "/mcp", "/.well-known"],
         });
         try {
+            const P = FRAMEWORK_ROUTE_PREFIX;
+            // This response is a side-effect-free static contract used by the SSR
+            // shell. Mount it before optional default-plugin/bootstrap work so a
+            // browser's automatic rules fetch cannot inherit the cold-start wait.
+            getH3App(nitroApp).use(`${P}/speculation-rules.json`, defineEventHandler((event) => {
+                // `createH3SSRHandler` points the Speculation-Rules response header
+                // here to prevent Cloudflare Speed Brain from injecting its own
+                // edge prefetch rules. Keep this route public and side-effect free:
+                // browsers may request it while parsing any SSR HTML document.
+                setResponseHeader(event, "content-type", "application/speculationrules+json; charset=utf-8");
+                for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
+                    setResponseHeader(event, name, value);
+                }
+                return EMPTY_SPECULATION_RULES;
+            }));
             await awaitBootstrap(nitroApp);
             const { persistedEnvVars, builderDisconnected } = await readLegacyCoreRouteInitSettings();
             // Legacy cleanup: key saves now go to scoped app_secrets rows. Do not
@@ -959,7 +974,6 @@ export function createCoreRoutesPlugin(options = {}) {
             catch {
                 // Audit module not available — skip
             }
-            const P = FRAMEWORK_ROUTE_PREFIX;
             for (const provider of [
                 "figma",
                 "google_drive",
@@ -1281,17 +1295,6 @@ export function createCoreRoutesPlugin(options = {}) {
                     schema,
                 };
             }));
-            getH3App(nitroApp).use(`${P}/speculation-rules.json`, defineEventHandler((event) => {
-                // `createH3SSRHandler` points the Speculation-Rules response header
-                // here to prevent Cloudflare Speed Brain from injecting its own
-                // edge prefetch rules. Keep this route public and side-effect free:
-                // browsers may request it while parsing any SSR HTML document.
-                setResponseHeader(event, "content-type", "application/speculationrules+json; charset=utf-8");
-                for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
-                    setResponseHeader(event, name, value);
-                }
-                return EMPTY_SPECULATION_RULES;
-            }));
             {
                 const { createAgentNativeOgImageHandler } = await import("./social-og-image.js");
                 getH3App(nitroApp).use(`${P}/og-image.png`, createAgentNativeOgImageHandler());
@@ -2339,7 +2342,7 @@ export function createCoreRoutesPlugin(options = {}) {
                     if (!creds.privateKey || !creds.publicKey) {
                         setResponseStatus(event, 400);
                         return {
-                            error: "Builder not connected. Connect Builder in Setup to use background agent.",
+                            error: "Builder not connected. Connect Builder (free tier available) in Setup to use background agent.",
                         };
                     }
                     const body = (await readBody(event));
@@ -2743,7 +2746,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 }
                 setResponseStatus(event, 503);
                 return {
-                    error: "No file upload provider configured. Connect Builder.io in Settings → File uploads, or register a provider.",
+                    error: "No file upload provider configured. Connect Builder.io (free tier available) in Settings → File uploads, or register a provider.",
                 };
             }));
             // ─── Voice transcription (Whisper) ───────────────────────────────

package/dist/server/credential-provider.js

@@ -42,7 +42,7 @@ export class FeatureNotConfiguredError extends Error {
     byokDocsUrl;
     constructor(opts) {
         super(opts.message ??
-            `Feature requires credential "${opts.requiredCredential}". Connect Builder or set your own key.`);
+            `Feature requires credential "${opts.requiredCredential}". Connect Builder (free tier available) or set your own key.`);
         this.name = "FeatureNotConfiguredError";
         this.requiredCredential = opts.requiredCredential;
         this.builderConnectUrl = opts.builderConnectUrl;
@@ -692,7 +692,7 @@ export async function getBuilderCredentialAuthFailure(creds = {}) {
             fingerprint,
             message: typeof row.message === "string" && row.message
                 ? row.message
-                : "Builder rejected the connected credentials. Reconnect Builder.io.",
+                : "Builder rejected the connected credentials. Reconnect Builder.io (free tier available).",
             status: typeof row.status === "number" ? row.status : undefined,
             code: typeof row.code === "string" ? row.code : undefined,
             at,
@@ -714,7 +714,7 @@ export async function recordBuilderCredentialAuthFailure(details) {
         await putSetting(builderAuthFailureSettingKey(fingerprint), {
             fingerprint,
             message: details?.message ||
-                "Builder rejected the connected credentials. Reconnect Builder.io.",
+                "Builder rejected the connected credentials. Reconnect Builder.io (free tier available).",
             ...(typeof details?.status === "number" && { status: details.status }),
             ...(details?.code && { code: details.code }),
             at: Date.now(),

package/dist/server/email-templates.d.ts

@@ -45,6 +45,13 @@ export interface RenderVerifySignupEmailArgs {
     verifyUrl: string;
 }
 export declare function renderVerifySignupEmail(args: RenderVerifySignupEmailArgs): RenderedEmailMessage;
+export interface RenderMagicLinkEmailArgs {
+    /** The account email receiving the one-time sign-in link. */
+    email: string;
+    /** The full Better Auth URL containing the one-time token. */
+    magicLinkUrl: string;
+}
+export declare function renderMagicLinkEmail(args: RenderMagicLinkEmailArgs): RenderedEmailMessage;
 export interface RenderResetPasswordEmailArgs {
     /** The account email the reset is for. */
     email: string;

package/dist/server/email-templates.js

@@ -103,6 +103,30 @@ export function renderVerifySignupEmail(args) {
             : undefined,
     };
 }
+export function renderMagicLinkEmail(args) {
+    const email = stripCrlf(args.email);
+    const slug = getAppSlug();
+    const brand = resolveBrand(slug);
+    const { html, text } = renderEmail({
+        brandName: brand,
+        preheader: `Sign in to ${brand} with your secure one-time link.`,
+        heading: `Sign in to ${brand}`,
+        paragraphs: [
+            `Use the button below to sign in as ${emailStrong(email)}. This link expires in 5 minutes and can only be used once.`,
+            `If you didn't request this email, you can safely ignore it.`,
+        ],
+        cta: { label: "Sign in securely", url: args.magicLinkUrl },
+        footer: `For your security, never forward this email or share the link.`,
+    });
+    return {
+        subject: `Your sign-in link for ${brand}`,
+        html,
+        text,
+        appSender: slug
+            ? { name: brand, slug, replyTo: AGENT_NATIVE_REPLY_TO }
+            : undefined,
+    };
+}
 export function renderResetPasswordEmail(args) {
     const email = stripCrlf(args.email);
     // Match the verification email branding so password resets are clearly tied

package/dist/server/email.d.ts

@@ -10,6 +10,16 @@
  * so the reset-password flow still works end-to-end for local development.
  */
 export type EmailProvider = "resend" | "sendgrid" | "dev";
+export type EmailReadiness = {
+    status: "ready";
+    provider: Exclude<EmailProvider, "dev">;
+} | {
+    status: "not-configured";
+    provider: "dev";
+} | {
+    status: "misconfigured" | "unavailable";
+    provider: EmailProvider | "unknown";
+};
 export interface EmailAttachment {
     filename: string;
     content: string | Buffer;
@@ -48,8 +58,24 @@ export interface SendEmailArgs {
     references?: string;
     attachments?: EmailAttachment[];
     timeoutMs?: number;
+    /**
+     * Registered transactional email id (see `defineTransactionalEmail`), e.g.
+     * `calendar.booking-confirmed`. Tags the message at the provider so delivery
+     * and open metrics attribute to one email instead of to the whole account,
+     * and keys the row written to `email_log`. Omit for genuinely one-off sends.
+     */
+    templateId?: string;
+    /** App slug that owns the send. Defaults to the running app. */
+    app?: string;
 }
 export declare function isEmailConfigured(): Promise<boolean>;
+/**
+ * Auth must only offer magic links when sending can succeed. In particular,
+ * SendGrid needs EMAIL_FROM while Resend can use its sandbox sender. Keep
+ * unreadable credential stores distinct from an unconfigured deployment so
+ * callers can fail closed without claiming setup is absent.
+ */
+export declare function getEmailReadiness(): Promise<EmailReadiness>;
 export declare function getEmailProvider(): Promise<EmailProvider>;
 export declare function sendEmail(args: SendEmailArgs): Promise<void>;
 //# sourceMappingURL=email.d.ts.map