dsh-feishu-auth 0.1.0

package/lib/index.js

@@ -0,0 +1,196 @@
+/**
+ * dsh-feishu-auth — Feishu (Lark) web-app login for the DSH web GUI.
+ *
+ * The plugin claims one interception point in front of the harness web
+ * server's dispatch, then serves its own OAuth endpoints and requires a signed
+ * session cookie for everything else. It answers on every address the server
+ * is bound to, because the decision never depends on the Host header.
+ *
+ * Two safety properties are deliberate:
+ *  - Fail closed. Missing credentials do not stop the plugin from loading (a
+ *    plugin that fails to load would leave the GUI wide open); they put the
+ *    gate into a mode where every request is refused with the reason.
+ *  - Fail loudly. After mounting, the gate probes its own listening socket in
+ *    both directions. A gate that is not actually intercepting is reported as
+ *    an error, not assumed.
+ *
+ * Zero runtime dependencies: node builtins only, so the package resolves in a
+ * profile that never installed it through pnpm.
+ * @module dsh-feishu-auth
+ */
+
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Config, SESSION_COOKIE, analyzeConfig } from './config.js';
+import { createGate } from './gate.js';
+import { loadOrCreateSecret, signPayload } from './session.js';
+
+/** Stable Cordis plugin name. */
+const name = 'feishu-auth';
+
+/** Services required before the gate can mount. */
+const inject = ['webServer'];
+
+const PROBE_ATTEMPTS = 40;
+const PROBE_DELAY_MS = 250;
+const BLOCKED_STATUSES = new Set([302, 401, 403, 503]);
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+/** Resolve the harness home the same way the CLI does. */
+function resolveHarnessHome() {
+  const fromEnvironment = process.env.DSH_HOME;
+  if (typeof fromEnvironment === 'string' && fromEnvironment !== '') return fromEnvironment;
+  return join(homedir(), '.dsh');
+}
+
+/**
+ * Build the gate's logger.
+ *
+ * `ctx.logger` only feeds the harness's in-memory log buffer — nothing it
+ * receives is printed by the CLI — so every gate message is mirrored to stderr
+ * as well. An operator must be able to see "the gate is mounted", "the gate is
+ * refusing everyone", and "this account was denied" in the terminal that runs
+ * `dsh web`.
+ */
+function createOperatorLogger(ctx) {
+  const mirror = (level, message) => {
+    const text = String(message).replaceAll('\n', '\n    ');
+    try {
+      process.stderr.write(`${new Date().toISOString()} feishu-auth[${level}] ${text}\n`);
+    } catch {
+      // A closed stderr must never break the gate.
+    }
+  };
+  return {
+    info: (message) => {
+      ctx?.logger?.info?.(message);
+      mirror('info', message);
+    },
+    warn: (message) => {
+      ctx?.logger?.warn?.(message);
+      mirror('warn', message);
+    },
+    error: (message) => {
+      ctx?.logger?.error?.(message);
+      mirror('error', message);
+    },
+  };
+}
+
+/**
+ * Probe the gate through its own listening socket, in both directions: the
+ * unauthenticated request must be refused, and a request carrying a session
+ * this process just signed must reach the harness. Anything else means the
+ * interception is not in effect.
+ */
+async function verifyGate({ server, secret, logger }) {
+  const port = server?.port;
+  if (!Number.isInteger(port) || port <= 0) return;
+  const host = server.host === '0.0.0.0' ? '127.0.0.1' : (server.host ?? '127.0.0.1');
+  const probeUrl = `http://${host}:${String(port)}/_dsh_feishu_auth_probe_`;
+  const probeHeaders = { accept: '*/*', 'x-dsh-feishu-probe': '1' };
+  for (let attempt = 0; attempt < PROBE_ATTEMPTS; attempt += 1) {
+    try {
+      const anonymous = await fetch(probeUrl, { headers: probeHeaders, redirect: 'manual' });
+      if (BLOCKED_STATUSES.has(anonymous.status) !== true) {
+        logger.error(
+          `自检失败：未登录请求返回 HTTP ${String(anonymous.status)}，网关没有生效。请检查插件行是否启用，并确认没有其它插件覆盖 webServer.match。`,
+        );
+        return;
+      }
+      const sessionValue = signPayload(secret, {
+        kind: 'session',
+        sub: 'self-check',
+        name: 'self-check',
+        iat: Date.now(),
+        exp: Date.now() + 60_000,
+      });
+      const authenticated = await fetch(probeUrl, {
+        headers: { ...probeHeaders, cookie: `${SESSION_COOKIE}=${sessionValue}` },
+        redirect: 'manual',
+      });
+      if (BLOCKED_STATUSES.has(authenticated.status)) {
+        logger.error(`自检失败：持有效会话的请求仍被拒绝 (HTTP ${String(authenticated.status)})，登录后将无法访问页面。`);
+        return;
+      }
+      logger.info(
+        `网关自检通过（未登录 → HTTP ${String(anonymous.status)}，已登录 → HTTP ${String(authenticated.status)}）`,
+      );
+      return;
+    } catch {
+      // The socket is not accepting yet; the server binds during its own init.
+    }
+    await delay(PROBE_DELAY_MS);
+  }
+  logger.warn('自检未完成：服务器在预期时间内没有开始监听，无法确认网关状态。');
+}
+
+/**
+ * Mount the Feishu login gate.
+ * @param ctx - plugin context carrying the webServer service.
+ * @param rawConfig - the config object from this plugin's patch row.
+ */
+async function apply(ctx, rawConfig = {}) {
+  const { config, fatal } = analyzeConfig(rawConfig);
+  const logger = createOperatorLogger(ctx);
+
+  const fatalProblems = [...fatal];
+  const secretFile = join(resolveHarnessHome(), 'feishu-auth', 'session-secret');
+  let secret;
+  try {
+    secret = loadOrCreateSecret(secretFile);
+  } catch (error) {
+    fatalProblems.push(`无法读写会话密钥 ${secretFile}：${error?.message ?? String(error)}`);
+    secret = randomBytes(32);
+  }
+
+  /** Set while the `connection` injection is live; read per request by the gate. */
+  let entryUrlProvider;
+
+  /**
+   * The harness entry URL carrying this process's launch token.
+   *
+   * `connection` is reachable only through `ctx.inject`: the scoped callback's
+   * context carries the injected service, while `ctx.get('connection')` and
+   * `ctx.connection` both fail here. Losing this resolver is not fatal to
+   * mounting, so it must fail loud rather than silently degrade every login.
+   */
+  ctx.inject(['connection'], (connectionCtx) => {
+    const { connection } = connectionCtx;
+    if (typeof connection?.authenticatedUrl !== 'function') {
+      logger.error('connection 服务没有 authenticatedUrl()，无法把浏览器交给 harness 的令牌兑换流程。');
+      return;
+    }
+    connectionCtx.effect(() => {
+      entryUrlProvider = (baseUrl) => connection.authenticatedUrl(baseUrl);
+      return () => {
+        entryUrlProvider = undefined;
+      };
+    }, 'feishu-auth: harness entry resolver');
+  });
+
+  const gate = createGate({
+    config,
+    secret,
+    fatalProblems,
+    logger,
+    entryUrl: (baseUrl) => entryUrlProvider?.(baseUrl),
+  });
+  ctx.effect(() => gate.install(ctx.webServer), 'feishu-auth: http gate');
+
+  if (fatalProblems.length > 0) {
+    logger.error(`网关已进入故障关闭模式，所有页面访问都会被拒绝：\n  - ${fatalProblems.join('\n  - ')}`);
+  } else {
+    logger.info(
+      `飞书登录已挂载  prefix=${gate.prefix}  允许范围=${
+        config.allowedUsers.length > 0 ? `${String(config.allowedUsers.length)} 个账号` : '本应用可用范围内的任意成员'
+      }  会话有效期=${String(config.sessionMaxAgeDays)} 天`,
+    );
+  }
+
+  void verifyGate({ server: ctx.webServer, secret, logger });
+}
+
+export { Config, apply, inject, name };

package/lib/pages.js

@@ -0,0 +1,137 @@
+/**
+ * Self-contained HTML for the gate's terminal states: denied, error, logged
+ * out, and not-configured. Everything is inline, so these pages never depend
+ * on the assets the gate protects.
+ * @module dsh-feishu-auth/pages
+ */
+
+const STYLE = `
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+    padding: 32px 20px; background: #f5f5f7; color: #1d1d1f;
+    font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", Roboto, sans-serif;
+  }
+  @media (prefers-color-scheme: dark) { body { background: #16171a; color: #e8e8ea; } }
+  main {
+    width: 100%; max-width: 520px; background: #fff; border-radius: 14px; padding: 32px;
+    box-shadow: 0 1px 2px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.08);
+  }
+  @media (prefers-color-scheme: dark) { main { background: #202124; box-shadow: 0 1px 2px rgba(0,0,0,.4); } }
+  .badge { font-size: 12px; font-weight: 600; letter-spacing: .04em; text-transform: uppercase; color: #8a8a8e; margin-bottom: 10px; }
+  h1 { font-size: 20px; margin: 0 0 12px; }
+  p { margin: 0 0 12px; }
+  code, .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 13px; word-break: break-all; }
+  dl { margin: 0 0 16px; padding: 14px 16px; border-radius: 10px; background: rgba(127,127,127,.10); }
+  dt { font-size: 12px; color: #8a8a8e; margin-top: 8px; }
+  dt:first-child { margin-top: 0; }
+  dd { margin: 2px 0 0; }
+  .actions { display: flex; gap: 10px; flex-wrap: wrap; margin-top: 20px; }
+  a.button { display: inline-block; padding: 9px 16px; border-radius: 8px; text-decoration: none; font-weight: 600; background: #1a73e8; color: #fff; }
+  .tone-error a.button { background: #d93025; }
+  .note { font-size: 13px; color: #8a8a8e; }
+`;
+
+/**
+ * Escape text placed into HTML text or a quoted attribute.
+ * @param value - untrusted text.
+ * @returns escaped text.
+ */
+export function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function renderPage({ title, heading, body, tone = 'neutral' }) {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>${escapeHtml(title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main class="tone-${escapeHtml(tone)}">
+<div class="badge">DSH · 飞书登录</div>
+<h1>${escapeHtml(heading)}</h1>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+function retry(loginPath, label = '重新登录') {
+  return `<div class="actions"><a class="button" href="${escapeHtml(loginPath)}">${escapeHtml(label)}</a></div>`;
+}
+
+function facts(rows) {
+  const items = rows
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([label, value]) => `<dt>${escapeHtml(label)}</dt><dd class="mono">${escapeHtml(value)}</dd>`)
+    .join('');
+  return items === '' ? '' : `<dl>${items}</dl>`;
+}
+
+/**
+ * The page an authenticated-but-unauthorized account sees: its own identifiers
+ * and nothing about anyone else, so the operator can allowlist the right value.
+ * @param options - the signed-in account, the reason, and the login path.
+ * @returns the HTML document.
+ */
+export function renderDenied({ name, openId, reason, loginPath }) {
+  const body = `
+<p>飞书已完成身份认证，但这个账号没有访问这台 DSH 的权限。</p>
+<p><b>原因：</b>${escapeHtml(reason)}</p>
+${facts([['姓名', name], ['open_id', openId]])}
+<p class="note">把上面的 open_id 加入配置的 <code>allowedUsers</code>（或把该成员加入飞书应用的可用范围），然后重启 <code>dsh web</code>。</p>
+${retry(loginPath, '换一个飞书账号登录')}`;
+  return renderPage({ title: '无权访问 · DSH', heading: '这个账号没有访问权限', body, tone: 'error' });
+}
+
+/**
+ * A terminal error page for a failed or expired login attempt.
+ * @param options - heading, message, optional detail, and the login path.
+ * @returns the HTML document.
+ */
+export function renderError({ heading, message, detail, loginPath }) {
+  const body = `
+<p>${escapeHtml(message)}</p>
+${detail === undefined || detail === '' ? '' : `<p class="note mono">${escapeHtml(detail)}</p>`}
+${retry(loginPath)}`;
+  return renderPage({ title: '登录失败 · DSH', heading, body, tone: 'error' });
+}
+
+/**
+ * The page shown after an explicit logout.
+ * @param options - the login path.
+ * @returns the HTML document.
+ */
+export function renderLoggedOut({ loginPath }) {
+  return renderPage({
+    title: '已退出 · DSH',
+    heading: '已退出登录',
+    body: `<p>本机浏览器上的访问凭据已清除。</p>${retry(loginPath, '使用飞书登录')}`,
+  });
+}
+
+/**
+ * The fail-closed page: the gate is mounted but cannot authenticate anyone, so
+ * the page stays shut until configuration is fixed.
+ * @param options - the configuration problem.
+ * @returns the HTML document.
+ */
+export function renderMisconfigured({ problem }) {
+  const body = `
+<p>飞书登录未配置完成，因此<b>所有访问都被拒绝</b>（包括你自己的）。</p>
+<p><b>问题：</b>${escapeHtml(problem)}</p>
+<p class="note">在终端修好配置后重启 <code>dsh web</code> 即可恢复。急着重启：见 README「停用」。</p>`;
+  return renderPage({ title: '未就绪 · DSH', heading: '飞书登录未就绪', body, tone: 'error' });
+}

package/lib/session.js

@@ -0,0 +1,206 @@
+/**
+ * Signed-cookie sessions for the Feishu gate.
+ *
+ * One HMAC-SHA256 secret signs two kinds of payload: the short-lived OAuth
+ * `state` cookie that survives the round trip through Feishu, and the browser
+ * session cookie minted after a successful login. Both are self-contained
+ * (no server-side session store), tamper-evident, and bounded by `exp`.
+ * @module dsh-feishu-auth/session
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/** Cookie payload version prefix; a future format bumps it instead of guessing. */
+export const COOKIE_VERSION = 'v1';
+
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Encode bytes as unpadded base64url, the only alphabet safe in a cookie value.
+ * @param value - bytes or a string to encode.
+ * @returns the unpadded base64url text.
+ */
+export function encodeBase64Url(value) {
+  return Buffer.from(value).toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+}
+
+/**
+ * Decode unpadded base64url text, rejecting anything that is not canonical
+ * (so two different strings can never decode to the same bytes).
+ * @param value - the base64url text.
+ * @returns the decoded bytes, or undefined when the input is not canonical.
+ */
+export function decodeBase64Url(value) {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  if (!BASE64URL_PATTERN.test(value) || value.length % 4 === 1) return undefined;
+  const padding = '='.repeat((4 - (value.length % 4)) % 4);
+  const decoded = Buffer.from(value.replaceAll('-', '+').replaceAll('_', '/') + padding, 'base64');
+  return encodeBase64Url(decoded) === value ? decoded : undefined;
+}
+
+/**
+ * Generate a fresh random token in cookie-safe form.
+ * @param bytes - entropy size; 32 bytes for secrets, 24 for one-shot nonces.
+ * @returns the encoded token.
+ */
+export function generateToken(bytes = 32) {
+  return encodeBase64Url(randomBytes(bytes));
+}
+
+function signature(secret, body) {
+  return createHmac('sha256', secret).update(body).digest();
+}
+
+/**
+ * Serialize a payload into `v1.<body>.<signature>`.
+ * @param secret - the signing secret bytes.
+ * @param payload - any JSON-serializable payload.
+ * @returns the signed cookie value.
+ */
+export function signPayload(secret, payload) {
+  const body = encodeBase64Url(Buffer.from(JSON.stringify(payload), 'utf8'));
+  return `${COOKIE_VERSION}.${body}.${encodeBase64Url(signature(secret, body))}`;
+}
+
+/**
+ * Verify and decode a signed value. Any structural damage, signature mismatch,
+ * or non-object JSON is a plain rejection: the caller decides what to do.
+ * @param secret - the signing secret bytes.
+ * @param value - the cookie value to verify.
+ * @returns the decoded payload, or undefined when it is not authentic.
+ */
+export function verifyPayload(secret, value) {
+  if (typeof value !== 'string') return undefined;
+  const parts = value.split('.');
+  if (parts.length !== 3) return undefined;
+  const [version, body, provided] = parts;
+  if (version !== COOKIE_VERSION || body === undefined || provided === undefined) return undefined;
+  const providedBytes = decodeBase64Url(provided);
+  if (providedBytes === undefined) return undefined;
+  const expectedBytes = signature(secret, body);
+  if (providedBytes.byteLength !== expectedBytes.byteLength) return undefined;
+  if (!timingSafeEqual(providedBytes, expectedBytes)) return undefined;
+  const decoded = decodeBase64Url(body);
+  if (decoded === undefined) return undefined;
+  try {
+    const payload = JSON.parse(decoded.toString('utf8'));
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined;
+    return payload;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Constant-time string comparison for OAuth state nonces.
+ * @param actual - value received in the callback query.
+ * @param expected - value recorded in the state cookie.
+ * @returns true only when both are identical.
+ */
+export function safeEqual(actual, expected) {
+  if (typeof actual !== 'string' || typeof expected !== 'string') return false;
+  const actualBytes = Buffer.from(actual, 'utf8');
+  const expectedBytes = Buffer.from(expected, 'utf8');
+  if (actualBytes.byteLength !== expectedBytes.byteLength) return false;
+  return timingSafeEqual(actualBytes, expectedBytes);
+}
+
+/**
+ * Parse a Cookie header into a name to value map. Generated cookie names and
+ * values are cookie-safe base64url, so a simple split is enough and no general
+ * cookie grammar is reimplemented here.
+ * @param headerValue - the raw `Cookie` header.
+ * @returns a map of the cookies that were present.
+ */
+export function parseCookies(headerValue) {
+  const cookies = new Map();
+  if (typeof headerValue !== 'string') return cookies;
+  for (const segment of headerValue.split(';')) {
+    const at = segment.indexOf('=');
+    if (at === -1) continue;
+    const name = segment.slice(0, at).trim();
+    if (name === '') continue;
+    cookies.set(name, segment.slice(at + 1).trim());
+  }
+  return cookies;
+}
+
+/**
+ * List the cookie names present on a request. Used to expire the harness's own
+ * signed browser cookie on logout without knowing how it derives that name.
+ * @param headerValue - the raw `Cookie` header.
+ * @returns the cookie names, in header order.
+ */
+export function cookieNames(headerValue) {
+  return [...parseCookies(headerValue).keys()];
+}
+
+/**
+ * Read one cookie out of the parsed map.
+ * @param headerValue - the raw `Cookie` header.
+ * @param name - the cookie name.
+ * @returns the value, or undefined when absent.
+ */
+export function readCookie(headerValue, name) {
+  return parseCookies(headerValue).get(name);
+}
+
+/**
+ * Serialize a `Set-Cookie` value for a session/state cookie.
+ *
+ * `SameSite=Lax` is required, not cosmetic: the OAuth callback arrives as a
+ * cross-site top-level GET navigation, which Lax still sends while Strict
+ * would not. `Secure` follows the scheme the cookie was minted on so a
+ * plain-HTTP LAN address keeps working.
+ * @param name - cookie name.
+ * @param value - cookie value.
+ * @param options - lifetime, Secure flag, and SameSite policy.
+ * @returns the header value.
+ */
+export function serializeCookie(name, value, { maxAgeSeconds, secure = false, sameSite = 'Lax', httpOnly = true } = {}) {
+  const parts = [`${name}=${value}`, 'Path=/'];
+  if (Number.isFinite(maxAgeSeconds)) parts.push(`Max-Age=${String(Math.max(0, Math.floor(maxAgeSeconds)))}`);
+  if (httpOnly) parts.push('HttpOnly');
+  if (secure) parts.push('Secure');
+  parts.push(`SameSite=${sameSite}`);
+  return parts.join('; ');
+}
+
+/**
+ * Serialize the deletion form of a cookie.
+ * @param name - cookie name.
+ * @param options - `secure` must match how the cookie was set.
+ * @returns the header value that expires the cookie.
+ */
+export function expiredCookie(name, { secure = false } = {}) {
+  return serializeCookie(name, '', { maxAgeSeconds: 0, secure });
+}
+
+/**
+ * Load the gate's signing secret from `file`, creating it once with owner-only
+ * permissions. A stable secret is what lets a login survive a harness restart.
+ * @param file - absolute path of the secret file.
+ * @returns the secret bytes.
+ */
+export function loadOrCreateSecret(file) {
+  try {
+    const existing = readFileSync(file, 'utf8').trim();
+    const decoded = decodeBase64Url(existing);
+    if (decoded !== undefined && decoded.byteLength >= 16) return decoded;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  const secret = randomBytes(32);
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid.toString()}.tmp`;
+  writeFileSync(temporary, `${encodeBase64Url(secret)}\n`, { mode: 0o600 });
+  renameSync(temporary, file);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // A filesystem without POSIX modes still has the secret safely written.
+  }
+  return secret;
+}

package/lib/urls.js

@@ -0,0 +1,94 @@
+/**
+ * Request-derived URLs and the open-redirect guard.
+ *
+ * Pure functions of request-shaped data, so the security-relevant decisions
+ * stay testable without a live server.
+ * @module dsh-feishu-auth/urls
+ */
+
+/**
+ * Canonicalize a Host header into a lowercase `host[:port]` authority.
+ *
+ * Rejects anything carrying userinfo, a path, a query, a fragment, whitespace,
+ * or a backslash, so a hostile Host can never become a `Set-Cookie` audience
+ * for another origin.
+ * @param host - the raw `Host` header value.
+ * @returns the canonical authority, or undefined when it is not one.
+ */
+export function normalizeAuthority(host) {
+  if (typeof host !== 'string') return undefined;
+  const trimmed = host.trim();
+  if (trimmed.length === 0 || trimmed.length > 255) return undefined;
+  if (/[\s/\\?#@]/.test(trimmed)) return undefined;
+  try {
+    const url = new URL(`http://${trimmed}`);
+    if (url.pathname !== '/' || url.search !== '' || url.hash !== '') return undefined;
+    return url.host.toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the externally visible origin of this request: scheme plus Host as
+ * the request presents them.
+ *
+ * The OAuth `redirect_uri` is derived from this value, so one deployment
+ * serves a LAN IP, loopback, and a tunnel hostname without per-address
+ * configuration. A reverse proxy's `X-Forwarded-Proto` is honored because a
+ * forged value can only break the caller's own login: it would hand out a
+ * `Secure` cookie over plain http, which the browser then refuses.
+ * @param req - incoming request.
+ * @returns origin without a trailing slash, or undefined for an invalid Host.
+ */
+export function requestBaseUrl(req) {
+  const authority = normalizeAuthority(req?.headers?.host);
+  if (authority === undefined) return undefined;
+  const forwarded = req?.headers?.['x-forwarded-proto'];
+  const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim().toLowerCase() : undefined;
+  const scheme = first === 'https' || first === 'http' ? first : req?.socket?.encrypted === true ? 'https' : 'http';
+  return `${scheme}://${authority}`;
+}
+
+/**
+ * Sanitize a `next` target into a same-origin absolute path.
+ * @param raw - the untrusted `next` query value.
+ * @returns an absolute path beginning with exactly one `/`.
+ */
+export function sanitizeNext(raw) {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 2048) return '/';
+  if (!raw.startsWith('/') || raw.startsWith('//')) return '/';
+  // eslint-disable-next-line no-control-regex -- rejecting control characters is the point
+  if (/[\u0000-\u001f\u007f]/.test(raw)) return '/';
+  // Some clients normalize '\' to '/', which would resurrect a '//' prefix.
+  if (raw.includes('\\')) return '/';
+  return raw;
+}
+
+/**
+ * Client address for the audit log: the socket peer, plus the first forwarded
+ * hop when a proxy supplied one.
+ * @param req - incoming request.
+ * @returns a loggable address string.
+ */
+export function clientAddress(req) {
+  const socketAddress = req?.socket?.remoteAddress ?? 'unknown';
+  const forwarded = req?.headers?.['x-forwarded-for'];
+  const first = typeof forwarded === 'string' ? forwarded.split(',')[0]?.trim() : undefined;
+  return first === undefined || first === '' ? socketAddress : `${first} via ${socketAddress}`;
+}
+
+/**
+ * Whether this request is a browser navigation, which decides between a
+ * redirect to the login page and a JSON 401 for programmatic callers.
+ * @param req - incoming request.
+ * @returns true when the response should be an HTML redirect.
+ */
+export function isNavigationRequest(req) {
+  if (req?.method !== 'GET') return false;
+  const accept = req?.headers?.accept;
+  if (typeof accept === 'string' && accept.includes('text/html')) return true;
+  // Fetch Metadata is authoritative when the browser sends it and there is no
+  // Accept header at all.
+  return req?.headers?.['sec-fetch-mode'] === 'navigate' && accept === undefined;
+}