feat(auth): enhance interactive auth banner customization and integration

Author: antfu

packages/devframe/src/node/instance-shell.ts

@@ -367,8 +367,15 @@ export interface CreateInstanceShellOptions<TContext extends DevframeNodeContext
   app?: H3
   /** Public origin, or a getter. Derived from the first request when omitted. */
   origin?: string | (() => string)
-  /** Resolved auth intent: `undefined`/`true` gates, `false` opts out, a handler installs a scheme. */
-  auth?: boolean | DevframeAuthHandler
+  /**
+   * Resolved auth intent: `undefined`/`true` gates with {@link createInteractiveAuth}'s
+   * defaults, `false` opts out, a handler installs a custom scheme outright.
+   * A function gates too, but builds the handler itself from the now-ready
+   * `ctx` - the seam a wrapping host (e.g. `@devframes/hub`'s UI slot) uses to
+   * hand `createInteractiveAuth` a branded `banner` while still leaving `auth`
+   * itself unset for the caller.
+   */
+  auth?: boolean | DevframeAuthHandler | ((ctx: TContext) => DevframeAuthHandler)
   /** Host `node:http` server to share the WS upgrade with. */
   server?: NodeHttpServer
   /** Explicit WebSocket control; see {@link DevframeWsOptions}. `false` disables the socket (SSE-only). */
@@ -632,12 +639,17 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
 
   /**
    * Auth resolution: gate by default, `false` opts out, a handler object
-   * installs a custom scheme. The `external` tier has no local transport to
-   * gate (the server behind `ws.url` owns auth) so it resolves to nothing.
+   * installs a custom scheme, a function builds one from `ctx`. The `external`
+   * tier has no local transport to gate (the server behind `ws.url` owns
+   * auth) so it resolves to nothing.
    */
   function resolveAuth(): boolean | DevframeAuthHandler {
     if (options.auth === false)
       return false
+    if (typeof options.auth === 'function') {
+      authHandler = options.auth(ctx)
+      return authHandler
+    }
     if (typeof options.auth === 'object') {
       authHandler = options.auth
       return options.auth

packages/devframe/src/recipes/interactive-auth.ts

@@ -1,4 +1,5 @@
 import type { DevframeNodeContext, DevframeNodeRpcSession } from 'devframe/types'
+import type { ColorFn } from 'devframe/utils/colors'
 import type { DevframeAuthHandler } from '../node/auth'
 import { colors } from 'devframe/utils/colors'
 import { s } from 'devframe/utils/simple-schema'
@@ -18,11 +19,12 @@ export interface CreateInteractiveAuthOptions {
   /**
    * Print the current code + magic-link URL. Devframe stays headless, so
    * there is no default banner printed automatically; call
-   * `auth.printBanner()` yourself once the server is listening. Override
-   * this to customize the format; defaults to a small boxed message on
-   * stdout.
+   * `auth.printBanner()` yourself once the server is listening. Defaults to
+   * {@link createAuthBanner}'s output; pass its result here directly to
+   * rebrand the box (title / colors), or your own function to replace the
+   * format outright.
    */
-  banner?: (info: { code: string, url: string }) => void
+  banner?: AuthBannerFunction
   /**
    * Called once a code exchange succeeds, so a host rendering its own
    * banner can retract it. Fires after the rotated code is printed, so
@@ -38,9 +40,68 @@ export interface CreateInteractiveAuthOptions {
   serverUrl?: () => string
 }
 
-function defaultBanner(info: { code: string, url: string }): void {
-  // eslint-disable-next-line no-console
-  console.log(`\n  ${colors.dim('devframe auth code')}  ${colors.bold(info.code)}\n  ${colors.dim('or open')}       ${colors.cyan(info.url)}\n`)
+/** Signature of `options.banner`: render the current auth code + magic-link URL. */
+export type AuthBannerFunction = (info: { code: string, url: string }) => void
+
+/** Palette for {@link createAuthBanner}'s box - one color per part, so a host can rebrand a subset. */
+export interface CreateAuthBannerColorsOptions {
+  border: ColorFn
+  title: ColorFn
+  label: ColorFn
+  code: ColorFn
+  url: ColorFn
+}
+
+export interface CreateAuthBannerOptions {
+  /** Box title. Defaults to `'Devframe'` - set to your product name for branding. */
+  title?: string
+  /** Palette overrides; unset colors fall back to dim/bold/cyan defaults. */
+  colors?: Partial<CreateAuthBannerColorsOptions>
+}
+
+/**
+ * Build a {@link AuthBannerFunction} that renders the auth code + magic-link
+ * URL as a small bordered box, its two rows label-aligned. `createInteractiveAuth`
+ * falls back to `createAuthBanner()` when no `banner` is given; call this
+ * yourself to rebrand the box (`title` / `colors`) and pass the result as
+ * `options.banner`.
+ */
+export function createAuthBanner(options: CreateAuthBannerOptions = {}): AuthBannerFunction {
+  const title = options.title ?? 'Devframe'
+  const palette: CreateAuthBannerColorsOptions = {
+    border: colors.dim,
+    title: colors.bold,
+    label: colors.dim,
+    code: colors.bold,
+    url: colors.cyan,
+    ...options.colors,
+  }
+
+  return (info) => {
+    const rows: [label: string, value: string, color: ColorFn][] = [
+      ['auth code', info.code, palette.code],
+      ['or open', info.url, palette.url],
+    ]
+    const labelWidth = Math.max(...rows.map(([label]) => label.length))
+    const contentWidth = Math.max(...rows.map(([, value]) => labelWidth + 2 + value.length))
+    const titleBarLength = title.length + 3
+    const lineWidth = Math.max(contentWidth, titleBarLength - 2)
+
+    const top = [
+      palette.border(`╭─`),
+      palette.title(title),
+      palette.border(`${'─'.repeat(Math.max(lineWidth + 2 - titleBarLength, 0))}╮`),
+    ].join(' ')
+    const bottom = `╰${'─'.repeat(lineWidth + 2)}╯`
+    const body = rows.map(([label, value, color]) => {
+      const plain = `${label.padEnd(labelWidth)}  ${value}`
+      const pad = ' '.repeat(lineWidth - plain.length)
+      return `${palette.border('│')} ${palette.label(label.padEnd(labelWidth))}  ${color(value)}${pad} ${palette.border('│')}`
+    })
+
+    // eslint-disable-next-line no-console
+    console.log(`\n${palette.border(top)}\n${body.join('\n')}\n${palette.border(bottom)}\n`)
+  }
 }
 
 /**
@@ -80,14 +141,16 @@ export function createInteractiveAuth(
     return options.serverUrl?.() ?? context.host.resolveOrigin()
   }
 
+  const banner = options.banner ?? createAuthBanner()
+
   let bannerPrintedForCode: string | undefined
   function printBanner(): void {
     const code = getTempAuthCode()
     if (code === bannerPrintedForCode)
       return
     bannerPrintedForCode = code
     const url = buildOtpAuthUrl(resolveServerUrl(), code)
-    ;(options.banner ?? defaultBanner)({ code, url })
+    banner({ code, url })
   }
 
   const anonymousAuth = defineRpcFunction({

packages/hub-ui/src/index.ts

@@ -3,6 +3,7 @@ import type { DevframeBranding, DevframeDockPreferences, EmbeddedVisibility } fr
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { createAuthBanner } from 'devframe/recipes/interactive-auth'
 
 export type { ColorSchemeValue, DevframeBranding, DevframeDockPreferences, EmbeddedVisibility, ViewerBackground } from './types'
 
@@ -106,5 +107,13 @@ export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
         ...(options.dockPreferences ? { dockPreferences: options.dockPreferences } : {}),
       }
     },
+    /**
+     * Node-side counterpart to the browser rebrand above: the same
+     * `productName` titles the interactive-auth box printed to the terminal,
+     * so a rebranded hub doesn't print a stray "Devframe" code prompt.
+     */
+    authBanner: createAuthBanner({
+      title: options.branding?.productName,
+    }),
   }
 }

packages/hub/src/node/initiate.ts

@@ -1,5 +1,6 @@
 import type { DevframeInstanceRecord, InstanceShellApi, ResolvedMcpConfig } from 'devframe/internal'
 import type { DevframeAuthHandler } from 'devframe/node/auth'
+import type { AuthBannerFunction } from 'devframe/recipes/interactive-auth'
 import type { WsOriginRegistry } from 'devframe/rpc/transports/ws-server'
 import type { ConnectionMeta, DevframeDefinition, DevframeServiceInput, DevframeSseOptions, DevframeStorageScope, DevframeWsOptions, McpRouteOptions, McpSetting } from 'devframe/types'
 import type { Buffer } from 'node:buffer'
@@ -12,6 +13,7 @@ import { readFile } from 'node:fs/promises'
 import process from 'node:process'
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE } from 'devframe/constants'
 import { createH3DevframeHost, createInstanceShell, importRuntimeModule, loadAutoMcpAdapter, resolveInstanceRegister, resolveMcpConfig } from 'devframe/internal'
+import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
@@ -120,6 +122,17 @@ export interface DevframeHubUi {
    * The hub stays policy-free about what the UI writes.
    */
   setup?: (ctx: DevframeHubContext) => void | Promise<void>
+  /**
+   * The interactive OTP banner (auth code + magic-link URL) to print when
+   * {@link InitHubOptions.auth} is left at its default. A node-side
+   * counterpart to `setup`'s browser-facing branding: the reference UI's
+   * `createUi()` derives one from its own `branding.productName` via
+   * `createAuthBanner` (see `devframe/recipes/interactive-auth`), so the
+   * printed code matches the rebranded viewer without the caller wiring
+   * `auth` themselves. Ignored once `auth` is set explicitly - a `false` or
+   * a full {@link DevframeAuthHandler} both mean the caller owns the banner.
+   */
+  authBanner?: AuthBannerFunction
 }
 
 export type DevframesInput = Array<
@@ -398,7 +411,16 @@ export function initHub(options: InitHubOptions): HubInstance {
     app,
     host: options.host,
     origin: options.origin,
-    auth: options.auth,
+    /**
+     * `false`/an explicit handler are the caller's own call, passed through
+     * as-is; `true`/unset both mean "gate with the defaults", so the handler
+     * is built lazily from `ctx` either way, taking the UI slot's
+     * `authBanner` (e.g. `createUi()`'s branded box) without the caller
+     * wiring `auth` themselves.
+     */
+    auth: options.auth === false || typeof options.auth === 'object'
+      ? options.auth
+      : (ctx: DevframeHubContext) => createInteractiveAuth(ctx, { banner: options.ui?.authBanner }),
     server: options.server,
     ws: options.ws,
     sse: options.sse,