docnest 0.1.7 → 0.1.9

package/README.md

@@ -58,6 +58,28 @@ export default defineConfig({
 
 水印默认关闭。开启后，PDF 导出弹窗会读取配置文字，并允许本次导出临时修改；临时修改不会写回文件或浏览器存储。
 
+### 极简单口令授权
+
+需要让文档中心只对知道口令的人开放时，可以启用单口令授权：
+
+```js
+export default defineConfig({
+  auth: {
+    enabled: true,
+    passphrase: '请替换为项目自己的长口令',
+    stateFile: '.docnest/auth.json',
+    sessionTtlMinutes: 24 * 60,
+  },
+})
+```
+
+授权只有一道关口，没有账号、密码组合或角色体系。首次启动时，`passphrase` 会初始化到由
+`stateFile` 指定的本地授权状态文件；状态文件只保存带随机盐的口令哈希，不保存明文口令。
+进入文档中心后，右上角的“修改口令”可以动态更新口令。修改后所有现有会话立即失效，必须使用新口令重新进入。
+建议把 `.docnest/` 加入宿主项目的 `.gitignore`，并为口令状态文件设置仅当前用户可读写的权限。
+
+授权开启但既没有状态文件，也没有初始 `passphrase` 时，DocNest 会拒绝启动，避免意外以空口令开放文档。
+
 如需显式指定端口、文档目录或监听地址：
 
 ```bash
@@ -70,7 +92,7 @@ npx docnest serve --port 3000 --docs-dir docs --host 127.0.0.1
 
 ## 嵌入现有 Node 服务
 
-需要接入项目自己的鉴权或文档来源时，在加载 `docnest/server` 前注入中间件和文档存储适配器，然后使用导出的 Express/Socket.IO 实例：
+需要接入项目自己的鉴权或文档来源时，在加载 `docnest/server` 前注入中间件和文档存储适配器，然后使用导出的 Express/Socket.IO 实例。项目若不使用上面的内置单口令授权，仍可在这里接入自己的访问控制：
 
 ```js
 globalThis.__DOCNEST_BEFORE_DOCUMENT_ROUTES__ = [projectAuthMiddleware]
@@ -82,7 +104,7 @@ io.use(projectSocketAuth)
 startServer(3000)
 ```
 
-存储适配器实现 `name`、`readDir`、`fileExists`、`readFile`、`readAsset`，可选实现 `ready`；这样文档内容仍由宿主项目提供，DocNest 只负责展示和交互。
+存储适配器实现 `name`、`readDir`、`fileExists`、`readFile`、`readAsset`，可选实现 `ready`；这样文档内容仍由宿主项目提供，DocNest 负责展示、交互和可选的单口令授权。
 
 ## 静态构建中的文档附件
 

package/dist/attachments.js

@@ -86,6 +86,8 @@ function resolveAttachmentPath(docsRoot, realDocsRoot, markdownPath, rawTarget,
     }
     if (!decodedTarget)
         return null;
+    if (decodedTarget.endsWith('/'))
+        return null;
     const extension = node_path_1.default.extname(decodedTarget).toLowerCase();
     if (MARKDOWN_SOURCE_EXTENSIONS.has(extension))
         return null;

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+export type DocNestAuthConfig = {
+    enabled: boolean;
+    passphrase: string;
+    stateFile: string;
+    sessionTtlMinutes: number;
+};
+export type DocNestAuthManager = {
+    enabled: boolean;
+    stateFile: string;
+    sessionCookieName: string;
+    sessionMaxAgeSeconds: number;
+    verifyPassphrase: (passphrase: string) => boolean;
+    createSession: (passphrase: string) => string | null;
+    authenticateSession: (token: string | undefined) => boolean;
+    revokeSession: (token: string | undefined) => void;
+    changePassphrase: (currentPassphrase: string, nextPassphrase: string) => boolean;
+};
+export declare function createAuthManager(config: DocNestAuthConfig): DocNestAuthManager;

package/dist/auth.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthManager = createAuthManager;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const AUTH_STATE_VERSION = 1;
+const HASH_LENGTH = 32;
+const SALT_LENGTH = 16;
+const MAX_PASSPHRASE_LENGTH = 1024;
+const DEFAULT_SESSION_TTL_SECONDS = 24 * 60 * 60;
+const SCRYPT_OPTIONS = { N: 16_384, r: 8, p: 1 };
+function assertPassphrase(passphrase, label) {
+    if (typeof passphrase !== 'string' || passphrase.length === 0) {
+        throw new Error(`${label}不能为空`);
+    }
+    if (passphrase.length > MAX_PASSPHRASE_LENGTH) {
+        throw new Error(`${label}长度不能超过 ${MAX_PASSPHRASE_LENGTH} 个字符`);
+    }
+}
+function hashPassphrase(passphrase, salt) {
+    return node_crypto_1.default.scryptSync(passphrase, salt, HASH_LENGTH, SCRYPT_OPTIONS);
+}
+function createState(passphrase) {
+    assertPassphrase(passphrase, '授权口令');
+    const salt = node_crypto_1.default.randomBytes(SALT_LENGTH);
+    return {
+        version: AUTH_STATE_VERSION,
+        salt: salt.toString('base64url'),
+        hash: hashPassphrase(passphrase, salt).toString('base64url'),
+    };
+}
+function parseState(raw, stateFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`授权状态文件无法解析：${stateFile}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`授权状态文件格式无效：${stateFile}`);
+    }
+    const state = parsed;
+    if (state.version !== AUTH_STATE_VERSION ||
+        typeof state.salt !== 'string' ||
+        typeof state.hash !== 'string') {
+        throw new Error(`授权状态文件格式无效：${stateFile}`);
+    }
+    let salt;
+    let hash;
+    try {
+        salt = Buffer.from(state.salt, 'base64url');
+        hash = Buffer.from(state.hash, 'base64url');
+    }
+    catch {
+        throw new Error(`授权状态文件格式无效：${stateFile}`);
+    }
+    if (salt.length !== SALT_LENGTH || hash.length !== HASH_LENGTH) {
+        throw new Error(`授权状态文件格式无效：${stateFile}`);
+    }
+    return {
+        version: AUTH_STATE_VERSION,
+        salt: salt.toString('base64url'),
+        hash: hash.toString('base64url'),
+    };
+}
+function readOrCreateState(config) {
+    try {
+        return parseState(node_fs_1.default.readFileSync(config.stateFile, 'utf8'), config.stateFile);
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    if (!config.passphrase) {
+        throw new Error(`授权已启用，但未配置初始口令，也找不到授权状态文件：${config.stateFile}`);
+    }
+    const state = createState(config.passphrase);
+    writeState(config.stateFile, state);
+    return state;
+}
+function writeState(stateFile, state) {
+    const directory = node_path_1.default.dirname(stateFile);
+    node_fs_1.default.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporaryFile = `${stateFile}.${process.pid}.${node_crypto_1.default.randomBytes(6).toString('hex')}.tmp`;
+    try {
+        node_fs_1.default.writeFileSync(temporaryFile, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+        node_fs_1.default.chmodSync(temporaryFile, 0o600);
+        node_fs_1.default.renameSync(temporaryFile, stateFile);
+        node_fs_1.default.chmodSync(stateFile, 0o600);
+    }
+    finally {
+        try {
+            node_fs_1.default.unlinkSync(temporaryFile);
+        }
+        catch {
+            // The temporary file was renamed successfully, or cleanup is unnecessary.
+        }
+    }
+}
+function matchesHash(passphrase, state) {
+    if (typeof passphrase !== 'string' || passphrase.length > MAX_PASSPHRASE_LENGTH)
+        return false;
+    const salt = Buffer.from(state.salt, 'base64url');
+    const expected = Buffer.from(state.hash, 'base64url');
+    const actual = hashPassphrase(passphrase, salt);
+    return expected.length === actual.length && node_crypto_1.default.timingSafeEqual(expected, actual);
+}
+function normalizeSessionTtl(minutes) {
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        return DEFAULT_SESSION_TTL_SECONDS;
+    return Math.max(5 * 60, Math.min(Math.floor(minutes * 60), 30 * 24 * 60 * 60));
+}
+function createAuthManager(config) {
+    const enabled = config.enabled === true;
+    const sessionMaxAgeSeconds = normalizeSessionTtl(config.sessionTtlMinutes);
+    const sessionCookieName = 'docnest_session';
+    const sessions = new Map();
+    if (!enabled) {
+        return {
+            enabled: false,
+            stateFile: config.stateFile,
+            sessionCookieName,
+            sessionMaxAgeSeconds,
+            verifyPassphrase: () => true,
+            createSession: () => null,
+            authenticateSession: () => true,
+            revokeSession: () => undefined,
+            changePassphrase: () => false,
+        };
+    }
+    let state = readOrCreateState(config);
+    function verifyPassphrase(passphrase) {
+        return matchesHash(passphrase, state);
+    }
+    function purgeExpiredSessions() {
+        const now = Date.now();
+        for (const [token, session] of sessions) {
+            if (session.expiresAt <= now)
+                sessions.delete(token);
+        }
+    }
+    function createSession(passphrase) {
+        if (!verifyPassphrase(passphrase))
+            return null;
+        purgeExpiredSessions();
+        const token = node_crypto_1.default.randomBytes(32).toString('base64url');
+        sessions.set(token, { expiresAt: Date.now() + sessionMaxAgeSeconds * 1000 });
+        return token;
+    }
+    function authenticateSession(token) {
+        if (!token)
+            return false;
+        purgeExpiredSessions();
+        const session = sessions.get(token);
+        if (!session)
+            return false;
+        session.expiresAt = Date.now() + sessionMaxAgeSeconds * 1000;
+        return true;
+    }
+    function revokeSession(token) {
+        if (token)
+            sessions.delete(token);
+    }
+    function changePassphrase(currentPassphrase, nextPassphrase) {
+        if (!verifyPassphrase(currentPassphrase))
+            return false;
+        assertPassphrase(nextPassphrase, '新授权口令');
+        state = createState(nextPassphrase);
+        writeState(config.stateFile, state);
+        sessions.clear();
+        return true;
+    }
+    return {
+        enabled,
+        stateFile: config.stateFile,
+        sessionCookieName,
+        sessionMaxAgeSeconds,
+        verifyPassphrase,
+        createSession,
+        authenticateSession,
+        revokeSession,
+        changePassphrase,
+    };
+}

package/dist/cli.js

@@ -68,6 +68,8 @@ function exposeConfig(config) {
     process.env.DOCS_PORT_START = String(config.server.port);
     process.env.DOCS_WATCH_ENABLED = String(config.server.watch);
     process.env.DOCS_OPEN_BROWSER = String(config.server.openBrowser);
+    const runtime = globalThis;
+    runtime.__DOCNEST_AUTH_CONFIG__ = config.auth;
 }
 const dynamicImport = new Function('specifier', 'return import(specifier)');
 async function main() {

package/dist/config.d.ts

@@ -25,6 +25,12 @@ export type DocNestConfig = {
         watch?: boolean;
         openBrowser?: boolean;
     };
+    auth?: {
+        enabled?: boolean;
+        passphrase?: string;
+        stateFile?: string;
+        sessionTtlMinutes?: number;
+    };
     export?: {
         watermark?: {
             enabled?: boolean;
@@ -40,6 +46,12 @@ export type ResolvedDocNestConfig = Required<DocNestConfig> & {
     navigation: Required<NonNullable<DocNestConfig['navigation']>>;
     appearance: Required<NonNullable<DocNestConfig['appearance']>>;
     server: Required<NonNullable<DocNestConfig['server']>>;
+    auth: {
+        enabled: boolean;
+        passphrase: string;
+        stateFile: string;
+        sessionTtlMinutes: number;
+    };
     export: {
         watermark: Required<NonNullable<NonNullable<DocNestConfig['export']>['watermark']>>;
     };

package/dist/config.js

@@ -41,6 +41,10 @@ function normalizePort(value, fallback) {
         return fallback;
     return port;
 }
+function normalizePositiveNumber(value, fallback) {
+    const normalized = Number(value);
+    return Number.isFinite(normalized) && normalized > 0 ? normalized : fallback;
+}
 function normalizeThemeName(value) {
     if (value === 'current-docs')
         return 'slate-modern';
@@ -82,6 +86,7 @@ async function loadConfig(projectRoot = process.cwd()) {
     const navigation = userConfig.navigation ?? {};
     const appearance = userConfig.appearance ?? {};
     const server = userConfig.server ?? {};
+    const auth = userConfig.auth ?? {};
     const watermark = userConfig.export?.watermark ?? {};
     const storageKeyPrefix = site.storageKeyPrefix?.trim() || `docnest:${projectName}`;
     return {
@@ -105,6 +110,12 @@ async function loadConfig(projectRoot = process.cwd()) {
             watch: server.watch ?? true,
             openBrowser: server.openBrowser ?? true,
         },
+        auth: {
+            enabled: auth.enabled ?? false,
+            passphrase: typeof auth.passphrase === 'string' ? auth.passphrase : '',
+            stateFile: node_path_1.default.resolve(projectRoot, auth.stateFile?.trim() || '.docnest/auth.json'),
+            sessionTtlMinutes: normalizePositiveNumber(auth.sessionTtlMinutes, 24 * 60),
+        },
         export: {
             watermark: {
                 enabled: watermark.enabled ?? false,

package/dist/server.js

@@ -14,6 +14,7 @@ const { Server } = require('socket.io');
 const chokidar = require('chokidar');
 const MarkdownIt = require('markdown-it');
 const hljs = require('highlight.js');
+const { createAuthManager } = require('./auth');
 const app = express();
 exports.app = app;
 const server = createServer(app);
@@ -87,7 +88,15 @@ const JSPDF_DIR = dependencyDir('jspdf');
 const injectedDocumentStore = globalThis.__DOCNEST_DOCUMENT_STORE__ || null;
 const STORAGE_DRIVER = injectedDocumentStore?.name || 'local';
 const DOCS_ROOT_LABEL = injectedDocumentStore?.rootLabel || DOCS_DIR;
-const AUTH_ENABLED = globalThis.__DOCNEST_AUTH_ENABLED__ === true;
+const AUTH_CONFIG = globalThis.__DOCNEST_AUTH_CONFIG__ || {
+    enabled: false,
+    passphrase: '',
+    stateFile: path.join(process.cwd(), '.docnest', 'auth.json'),
+    sessionTtlMinutes: 24 * 60,
+};
+const AUTH_MANAGER = createAuthManager(AUTH_CONFIG);
+const BUILT_IN_AUTH_ENABLED = AUTH_MANAGER.enabled;
+const AUTH_ENABLED = BUILT_IN_AUTH_ENABLED || globalThis.__DOCNEST_AUTH_ENABLED__ === true;
 // 配置 EJS 模板引擎
 app.set('view engine', 'ejs');
 app.set('views', path.join(SERVER_DIR, 'views'));
@@ -100,6 +109,7 @@ app.locals.docsThemeModeDefault = DOCS_THEME_MODE_DEFAULT;
 app.locals.docsThemeEnabled = DOCS_THEME_ENABLED;
 app.locals.docsWatermarkEnabled = DOCS_WATERMARK_ENABLED;
 app.locals.docsWatermarkText = DOCS_WATERMARK_TEXT;
+app.locals.docsAuthEnabled = BUILT_IN_AUTH_ENABLED;
 function normalizeDocRelativePath(value) {
     const raw = String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
     const normalized = path.posix.normalize(raw);
@@ -232,6 +242,122 @@ app.use('/vendor/html2canvas', express.static(HTML2CANVAS_DIR));
 app.use('/vendor/dompurify', express.static(DOMPURIFY_DIR));
 // jsPDF（本地，用于 Mermaid 图导出 PDF）
 app.use('/vendor/jspdf', express.static(JSPDF_DIR));
+app.use(express.json({ limit: '16kb' }));
+app.use(express.urlencoded({ extended: false, limit: '16kb' }));
+function readCookie(cookieHeader, name) {
+    if (!cookieHeader)
+        return undefined;
+    for (const item of String(cookieHeader).split(';')) {
+        const separator = item.indexOf('=');
+        if (separator === -1)
+            continue;
+        const key = item.slice(0, separator).trim();
+        if (key !== name)
+            continue;
+        try {
+            return decodeURIComponent(item.slice(separator + 1).trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function readAuthToken(req) {
+    return readCookie(req.headers.cookie, AUTH_MANAGER.sessionCookieName);
+}
+function safeNextPath(value) {
+    if (typeof value !== 'string' ||
+        !value.startsWith('/') ||
+        value.startsWith('//') ||
+        value.includes('\\') ||
+        /[\r\n]/.test(value))
+        return '/';
+    return value;
+}
+function setAuthCookie(res, token) {
+    const maxAge = AUTH_MANAGER.sessionMaxAgeSeconds;
+    res.setHeader('Set-Cookie', `${AUTH_MANAGER.sessionCookieName}=${encodeURIComponent(token)}; Max-Age=${maxAge}; Path=/; HttpOnly; SameSite=Lax`);
+}
+function clearAuthCookie(res) {
+    res.setHeader('Set-Cookie', `${AUTH_MANAGER.sessionCookieName}=; Max-Age=0; Path=/; HttpOnly; SameSite=Lax`);
+}
+function wantsJson(req) {
+    return req.path.startsWith('/auth/') || req.get('accept')?.includes('application/json');
+}
+function renderLoginPage(res, nextPath, error, status = 200) {
+    return res.status(status).render('login', {
+        nextPath: safeNextPath(nextPath),
+        error: error || '',
+        assetVersion: ASSET_VERSION,
+    });
+}
+app.get('/login', (req, res) => {
+    if (!BUILT_IN_AUTH_ENABLED)
+        return res.redirect('/');
+    if (AUTH_MANAGER.authenticateSession(readAuthToken(req))) {
+        return res.redirect(safeNextPath(req.query.next));
+    }
+    const message = req.query.changed
+        ? '口令已更新，请使用新口令重新进入。'
+        : '';
+    return renderLoginPage(res, req.query.next, message);
+});
+app.post('/auth/login', (req, res) => {
+    if (!BUILT_IN_AUTH_ENABLED)
+        return res.redirect('/');
+    const nextPath = safeNextPath(req.body?.next);
+    const token = AUTH_MANAGER.createSession(String(req.body?.passphrase || ''));
+    if (!token)
+        return renderLoginPage(res, nextPath, '口令不正确，请重试。', 401);
+    setAuthCookie(res, token);
+    return res.redirect(nextPath);
+});
+app.post('/auth/logout', (req, res) => {
+    AUTH_MANAGER.revokeSession(readAuthToken(req));
+    clearAuthCookie(res);
+    return res.redirect('/login');
+});
+app.post('/auth/change-password', (req, res) => {
+    if (!BUILT_IN_AUTH_ENABLED || !AUTH_MANAGER.authenticateSession(readAuthToken(req))) {
+        return res.status(401).json({ ok: false, error: '当前会话未授权。' });
+    }
+    try {
+        const changed = AUTH_MANAGER.changePassphrase(String(req.body?.currentPassphrase || ''), String(req.body?.nextPassphrase || ''));
+        if (!changed)
+            return res.status(401).json({ ok: false, error: '当前口令不正确。' });
+        clearAuthCookie(res);
+        return res.json({ ok: true });
+    }
+    catch (error) {
+        return res.status(400).json({
+            ok: false,
+            error: error instanceof Error ? error.message : '新口令无效。',
+        });
+    }
+});
+function documentAuthMiddleware(req, res, next) {
+    if (!BUILT_IN_AUTH_ENABLED)
+        return next();
+    if (req.path === '/health' || req.path === '/ready')
+        return next();
+    if (AUTH_MANAGER.authenticateSession(readAuthToken(req))) {
+        res.locals.authenticated = true;
+        return next();
+    }
+    if (wantsJson(req))
+        return res.status(401).json({ ok: false, error: '需要授权口令。' });
+    return res.redirect(`/login?next=${encodeURIComponent(req.originalUrl || '/')}`);
+}
+app.use(documentAuthMiddleware);
+io.use((socket, next) => {
+    if (!BUILT_IN_AUTH_ENABLED)
+        return next();
+    const token = readCookie(socket.handshake.headers.cookie, AUTH_MANAGER.sessionCookieName);
+    if (AUTH_MANAGER.authenticateSession(token))
+        return next();
+    return next(new Error('需要授权口令。'));
+});
 // 文档中的本地图片、附件等静态资源，只允许从文档根目录读取。
 app.get('/doc-asset/*', async (req, res) => {
     let requestedPath = req.path.slice('/doc-asset/'.length);

package/docnest.config.example.mjs

@@ -0,0 +1,48 @@
+import { defineConfig } from 'docnest/config'
+
+export default defineConfig({
+  // 默认读取项目根目录 docs/
+  docsDir: 'docs',
+  site: {
+    title: '我的项目文档',
+    subtitle: '本地 Markdown 文档服务',
+    logo: '',
+    storageKeyPrefix: 'docnest:my-project',
+  },
+  navigation: {
+    rootDirectoryOrder: [],
+  },
+  appearance: {
+    // slate-modern | editorial-atlas | precision-index | archive-room | swiss-manual
+    defaultTheme: 'slate-modern',
+    // auto | light | dark
+    defaultMode: 'auto',
+    enabledThemes: [
+      'slate-modern',
+      'editorial-atlas',
+      'precision-index',
+      'archive-room',
+      'swiss-manual',
+    ],
+  },
+  server: {
+    host: '127.0.0.1',
+    port: 3000,
+    watch: true,
+    openBrowser: true,
+  },
+  auth: {
+    // 极简单口令授权；关闭时文档中心保持本地开放。
+    enabled: false,
+    // 仅首次启动且授权状态文件不存在时使用，之后可在页面内修改。
+    passphrase: '',
+    stateFile: '.docnest/auth.json',
+    sessionTtlMinutes: 24 * 60,
+  },
+  export: {
+    watermark: {
+      enabled: false,
+      text: '我的项目文档',
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docnest",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "可复用的本地 Markdown 文档中心",
   "repository": {
     "type": "git",
@@ -28,7 +28,8 @@
     "server/static/img/404-deep-space-light.webp",
     "server/static/img/404-deep-space.webp",
     "server/static/js",
-    "server/views"
+    "server/views",
+    "docnest.config.example.mjs"
   ],
   "engines": {
     "node": ">=20"

package/server/static/css/styles.css

@@ -5760,3 +5760,250 @@ body[data-theme="dark"] .dir-listing-count {
     font-size: 1.1rem;
   }
 }
+
+/* 极简单口令授权 */
+.auth-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.auth-logout-form {
+  display: inline-flex;
+  margin: 0;
+}
+
+.auth-change-password-btn,
+.auth-logout-btn {
+  white-space: nowrap;
+}
+
+.auth-modal[hidden] {
+  display: none;
+}
+
+.auth-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: grid;
+  place-items: center;
+  padding: 1.25rem;
+}
+
+.auth-modal-backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(10, 16, 24, 0.42);
+  backdrop-filter: blur(4px);
+}
+
+.auth-modal-card,
+.auth-login-card {
+  position: relative;
+  z-index: 1;
+  color: var(--linear-text, #18212a);
+  background: var(--linear-bg, #ffffff);
+  border: 1px solid var(--linear-border, #d7dee5);
+  border-radius: 14px;
+  box-shadow: 0 24px 70px rgba(17, 29, 40, 0.2);
+}
+
+.auth-modal-card {
+  width: min(100%, 440px);
+  padding: 1.5rem;
+}
+
+.auth-modal-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.auth-modal-header h2,
+.auth-login-card h1 {
+  margin: 0;
+  color: var(--linear-text, #18212a);
+}
+
+.auth-modal-eyebrow,
+.auth-login-eyebrow {
+  margin: 0 0 0.35rem;
+  color: var(--linear-accent, #267c83);
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+}
+
+.auth-modal-close {
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  color: var(--linear-text-muted, #63727f);
+  background: transparent;
+  font-size: 1.5rem;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.auth-modal-close:hover {
+  background: var(--linear-bg-subtle, #eef2f5);
+}
+
+.auth-modal-help,
+.auth-login-description,
+.auth-login-note {
+  color: var(--linear-text-muted, #63727f);
+  line-height: 1.6;
+}
+
+.auth-modal-help {
+  margin: 1rem 0 1.25rem;
+  font-size: 0.875rem;
+}
+
+.auth-form {
+  display: grid;
+  gap: 0.9rem;
+}
+
+.auth-form label {
+  display: grid;
+  gap: 0.4rem;
+  color: var(--linear-text, #18212a);
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.auth-form input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.7rem 0.8rem;
+  border: 1px solid var(--linear-border, #d7dee5);
+  border-radius: 8px;
+  color: var(--linear-text, #18212a);
+  background: var(--linear-bg, #ffffff);
+  font: inherit;
+}
+
+.auth-form input:focus {
+  outline: 2px solid var(--linear-accent, #267c83);
+  outline-offset: 1px;
+}
+
+.auth-form-error {
+  margin: 0;
+  padding: 0.65rem 0.75rem;
+  border: 1px solid #e8b7b3;
+  border-radius: 8px;
+  color: #a32e26;
+  background: #fff4f2;
+  font-size: 0.875rem;
+}
+
+.auth-modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.6rem;
+  margin-top: 0.25rem;
+}
+
+.auth-primary-btn,
+.auth-secondary-btn {
+  min-height: 2.5rem;
+  padding: 0.55rem 0.95rem;
+  border-radius: 8px;
+  font: inherit;
+  font-weight: 650;
+  cursor: pointer;
+}
+
+.auth-primary-btn {
+  border: 1px solid var(--linear-accent, #267c83);
+  color: #fff;
+  background: var(--linear-accent, #267c83);
+}
+
+.auth-secondary-btn {
+  border: 1px solid var(--linear-border, #d7dee5);
+  color: var(--linear-text, #18212a);
+  background: var(--linear-bg-subtle, #eef2f5);
+}
+
+.auth-page {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+  box-sizing: border-box;
+  padding: 1.5rem;
+  background: linear-gradient(135deg, #eef3f4 0%, #f8fafb 48%, #e5eeee 100%);
+}
+
+.auth-login-card {
+  width: min(100%, 450px);
+  padding: clamp(1.5rem, 4vw, 2.5rem);
+}
+
+.auth-login-brand {
+  display: flex;
+  align-items: center;
+  gap: 0.9rem;
+}
+
+.auth-login-logo,
+.auth-login-logo-fallback {
+  width: 3rem;
+  height: 3rem;
+  flex: 0 0 3rem;
+  display: grid;
+  place-items: center;
+  border-radius: 10px;
+  object-fit: contain;
+  font-size: 1.8rem;
+}
+
+.auth-login-logo-fallback {
+  background: var(--linear-bg-subtle, #eef2f5);
+}
+
+.auth-login-card h1 {
+  font-size: clamp(1.35rem, 4vw, 1.8rem);
+}
+
+.auth-login-brand p:last-child {
+  margin: 0.3rem 0 0;
+  color: var(--linear-text-muted, #63727f);
+  font-size: 0.875rem;
+}
+
+.auth-login-divider {
+  height: 1px;
+  margin: 1.6rem 0 1.25rem;
+  background: var(--linear-border, #d7dee5);
+}
+
+.auth-login-description {
+  margin: 0 0 1.25rem;
+}
+
+.auth-login-note {
+  margin: 1rem 0 0;
+  font-size: 0.75rem;
+  text-align: center;
+}
+
+@media (max-width: 768px) {
+  .auth-actions {
+    gap: 0.25rem;
+  }
+
+  .auth-change-password-btn,
+  .auth-logout-btn {
+    min-width: 44px;
+    padding-inline: 0.5rem;
+    font-size: 0.75rem;
+  }
+}

package/server/static/js/core/auth.js

@@ -0,0 +1,61 @@
+(function () {
+  var modal = document.getElementById('auth-change-password-modal');
+  var openButton = document.getElementById('auth-change-password-btn');
+  var form = document.getElementById('auth-change-password-form');
+  var error = document.getElementById('auth-change-password-error');
+  if (!modal || !openButton || !form) return;
+
+  var closeButtons = modal.querySelectorAll('[data-auth-close]');
+
+  function setError(message) {
+    if (!error) return;
+    error.textContent = message || '';
+    error.hidden = !message;
+  }
+
+  function closeModal() {
+    modal.hidden = true;
+    setError('');
+    form.reset();
+  }
+
+  openButton.addEventListener('click', function () {
+    modal.hidden = false;
+    var firstInput = form.querySelector('input');
+    if (firstInput) firstInput.focus();
+  });
+
+  closeButtons.forEach(function (button) {
+    button.addEventListener('click', closeModal);
+  });
+
+  form.addEventListener('submit', async function (event) {
+    event.preventDefault();
+    setError('');
+    var formData = new FormData(form);
+    var nextPassphrase = String(formData.get('nextPassphrase') || '');
+    var confirmPassphrase = String(formData.get('confirmPassphrase') || '');
+    if (nextPassphrase !== confirmPassphrase) {
+      setError('两次输入的新口令不一致。');
+      return;
+    }
+
+    try {
+      var response = await fetch('/auth/change-password', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+          currentPassphrase: String(formData.get('currentPassphrase') || ''),
+          nextPassphrase: nextPassphrase,
+        }),
+      });
+      var result = await response.json().catch(function () { return {}; });
+      if (!response.ok || !result.ok) {
+        throw new Error(result.error || '修改口令失败，请重试。');
+      }
+      window.location.assign('/login?changed=1');
+    } catch (requestError) {
+      setError(requestError instanceof Error ? requestError.message : '修改口令失败，请重试。');
+    }
+  });
+})();

package/server/views/login.ejs

@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
+  <title>授权进入 - <%= docsTitle %></title>
+  <link rel="icon" href="/favicon.ico?v=<%= assetVersion %>" sizes="any">
+  <link rel="stylesheet" href="/static/css/styles.css?v=<%= assetVersion %>">
+  <link rel="stylesheet" href="/static/css/themes.css?v=<%= assetVersion %>">
+</head>
+<body class="auth-page">
+  <main class="auth-login-card" aria-labelledby="auth-login-title">
+    <div class="auth-login-brand">
+      <% if (docsLogo) { %>
+        <img class="auth-login-logo" src="<%= docsLogo %>" alt="">
+      <% } else { %>
+        <span class="auth-login-logo-fallback" aria-hidden="true">📚</span>
+      <% } %>
+      <div>
+        <p class="auth-login-eyebrow">LOCAL DOCUMENT CENTER</p>
+        <h1 id="auth-login-title"><%= docsTitle %></h1>
+        <p><%= docsSubtitle %></p>
+      </div>
+    </div>
+    <div class="auth-login-divider"></div>
+    <p class="auth-login-description">此文档中心需要授权口令。知道口令即可查看全部文档。</p>
+    <form action="/auth/login" method="post" class="auth-form auth-login-form">
+      <input type="hidden" name="next" value="<%= nextPath %>">
+      <label>
+        授权口令
+        <input type="password" name="passphrase" autocomplete="current-password" autofocus required>
+      </label>
+      <% if (error) { %>
+        <p class="auth-form-error" role="alert"><%= error %></p>
+      <% } %>
+      <button type="submit" class="auth-primary-btn">进入文档中心</button>
+    </form>
+    <p class="auth-login-note">没有账号体系，也没有角色区分；口令是唯一的入口。</p>
+  </main>
+</body>
+</html>

package/server/views/partials/header.ejs

@@ -54,7 +54,52 @@
           <span class="theme-icon" aria-hidden="true">A</span>
           <span class="theme-text">跟随系统</span>
         </button>
+        <% if (docsAuthEnabled) { %>
+          <div class="auth-actions" aria-label="文档授权">
+            <button id="auth-change-password-btn" class="header-action-btn auth-change-password-btn" type="button">
+              修改口令
+            </button>
+            <form action="/auth/logout" method="post" class="auth-logout-form">
+              <button class="header-action-btn auth-logout-btn" type="submit">退出</button>
+            </form>
+          </div>
+        <% } %>
       </div>
     </div>
   </div>
 </header>
+<% if (docsAuthEnabled) { %>
+  <div class="auth-modal" id="auth-change-password-modal" hidden>
+    <div class="auth-modal-backdrop" data-auth-close></div>
+    <section class="auth-modal-card" role="dialog" aria-modal="true" aria-labelledby="auth-change-password-title">
+      <div class="auth-modal-header">
+        <div>
+          <p class="auth-modal-eyebrow">DOCUMENT ACCESS</p>
+          <h2 id="auth-change-password-title">修改授权口令</h2>
+        </div>
+        <button type="button" class="auth-modal-close" data-auth-close aria-label="关闭">×</button>
+      </div>
+      <p class="auth-modal-help">修改后所有已打开的文档会退出授权，需要使用新口令重新进入。</p>
+      <form id="auth-change-password-form" class="auth-form">
+        <label>
+          当前口令
+          <input type="password" name="currentPassphrase" autocomplete="current-password" required>
+        </label>
+        <label>
+          新口令
+          <input type="password" name="nextPassphrase" autocomplete="new-password" required>
+        </label>
+        <label>
+          确认新口令
+          <input type="password" name="confirmPassphrase" autocomplete="new-password" required>
+        </label>
+        <p class="auth-form-error" id="auth-change-password-error" role="alert" hidden></p>
+        <div class="auth-modal-actions">
+          <button type="button" class="auth-secondary-btn" data-auth-close>取消</button>
+          <button type="submit" class="auth-primary-btn">保存新口令</button>
+        </div>
+      </form>
+    </section>
+  </div>
+  <script src="/static/js/core/auth.js?v=<%= typeof assetVersion !== 'undefined' ? assetVersion : 'dev' %>"></script>
+<% } %>