@musnows/scriverse 1.0.10 → 1.0.12

package/README.en.md

@@ -113,8 +113,8 @@ Run `scriverse --help` for all local server, default server, authentication, wor
 | `APP_AUTH_PASSWORD` | Empty | Optional deployment gateway password, at least 12 characters; must be transported over HTTPS |
 | `APP_TRUST_PROXY` | `false` | Set to the trusted proxy hop count (usually `1`) or `true` behind a trusted reverse proxy |
 | `APP_ALLOW_PRIVATE_AI_ENDPOINTS` | `true` in development, `false` in production | In production, AI provider URLs are validated and loopback, private-network, link-local, and reserved ranges are blocked by default. Setting `true`/`1` disables that validation for a trusted transparent-proxy or fake-IP deployment and writes a startup warning |
-| `APP_ALLOW_REGISTRATION` | `false` | Registration is enabled only when explicitly set to `true`; unset and all other values stay closed, including first-admin setup |
-| `APP_SETUP_TOKEN` | Empty | Required when registration is enabled and must contain at least 32 characters; only the first administrator must enter it |
+| `APP_ALLOW_REGISTRATION` | `false` | Three mutually exclusive levels: unset, `false`, `0`, or any other value disables registration; `invite` requires a one-time invite code; `true` or `1` opens registration. Invite-only and open registration both require a setup token |
+| `APP_SETUP_TOKEN` | Empty | Required when registration is open or invite-only and must contain at least 32 characters; only the first administrator must enter it |
 
 `APP_ALLOW_PRIVATE_AI_ENDPOINTS` disables AI provider URL SSRF validation and should be enabled only for a trusted deployment that must reach a provider through a transparent proxy or fake-IP mapping. Unset production deployments keep validating and blocking loopback, private-network, link-local, and reserved ranges; when enabled, those addresses no longer fail provider connection tests and startup writes a warning log. Remote MCP server URLs retain independent SSRF validation.
 
@@ -138,7 +138,7 @@ APP_AUTH_PASSWORD='replace-with-a-long-random-password' \
 npm start
 ```
 
-Production deployments must use HTTPS at a trusted reverse proxy. For first-time setup, set `APP_ALLOW_REGISTRATION=true` and configure `APP_SETUP_TOKEN` with at least 32 random characters. The first registered user must enter that token and becomes the system administrator. Afterwards, remove both variables or disable registration and restart the service. Later ordinary registrations do not require the setup token. Optional HTTP Basic Auth is only an additional deployment gateway, and its credentials are merely Base64 encoded. `/api/health` remains public for health checks, while business APIs require an in-app login.
+Production deployments must use HTTPS at a trusted reverse proxy. For first-time setup, set `APP_ALLOW_REGISTRATION` to `true` or `invite` and configure `APP_SETUP_TOKEN` with at least 32 random characters. The first registered user must enter that token and becomes the system administrator. Afterwards, set the switch to `false` to close registration, or to `invite` so later users must present a one-time invite code generated by a system administrator. Fully open registration no longer requires the setup token. Optional HTTP Basic Auth is only an additional deployment gateway, and its credentials are merely Base64 encoded. `/api/health` remains public for health checks, while business APIs require an in-app login.
 
 ## AI Provider Setup
 

package/README.md

@@ -122,8 +122,8 @@ CLI 会按服务器保存登录凭据。所有连接服务的数据命令都可
 | `APP_AUTH_PASSWORD` | 空 | 可选的部署网关密码，至少 12 个字符；必须通过 HTTPS 传输 |
 | `APP_TRUST_PROXY` | `false` | 位于可信反向代理后时设为代理跳数（通常为 `1`）或 `true` |
 | `APP_ALLOW_PRIVATE_AI_ENDPOINTS` | 开发环境 `true`，生产环境 `false` | 生产环境默认校验 AI 供应商地址并拦截本机、内网、链路本地和保留网段。显式设为 `true`/`1` 后关闭该校验，适用于受信任的透明代理或 fake-ip 部署；启动时会打印警告 |
-| `APP_ALLOW_REGISTRATION` | `false` | 仅明确设为 `true` 或 `1` 时开放注册；未设置或其他值均关闭，首次初始化创建管理员也必须显式开启 |
-| `APP_SETUP_TOKEN` | 空 | 开放注册时必填且至少 32 个字符；仅首位管理员注册需要在页面输入 |
+| `APP_ALLOW_REGISTRATION` | `false` | 三个互斥等级：未设置、`false`、`0` 或其他值表示彻底禁止注册；`invite` 表示需要一次性邀请码才能注册；`true` 或 `1` 表示完全开放注册。`invite` 与开放注册时都必须配置初始化令牌 |
+| `APP_SETUP_TOKEN` | 空 | 开放或邀请码注册时必填且至少 32 个字符；仅首位管理员注册需要在页面输入 |
 | `SCRIVERSE_AVATAR_IMAGE_MAX_BYTES` | `2097152` | 头像图片上传大小上限，单位为字节 |
 | `SCRIVERSE_COVER_IMAGE_MAX_BYTES` | `5242880` | 作品封面图片上传大小上限，单位为字节；封面不支持 GIF |
 | `SCRIVERSE_ATTACHMENT_IMAGE_MAX_BYTES` | `31457280` | 设定库等其他图片附件上传大小上限，单位为字节；包括 GIF |
@@ -155,7 +155,7 @@ APP_AUTH_PASSWORD='请替换为足够长的随机密码' \
 npm start
 ```
 
-生产环境必须在可信反向代理后启用 HTTPS。首次初始化时，将 `APP_ALLOW_REGISTRATION` 设为 `true`，并为 `APP_SETUP_TOKEN` 配置至少 32 个字符的随机值；创建的第一个用户会自动成为系统管理员，且必须在页面输入该令牌。完成后应删除这两个环境变量或关闭注册并重启服务。后续添加普通用户只需临时开放注册，不再要求初始化令牌。可选的 HTTP Basic Auth 仅作为额外部署网关，其凭据只是 Base64 编码，未使用 HTTPS 时不能防止链路窃听。`/api/health` 保持免认证以供探活，业务 API 需要应用内登录。
+生产环境必须在可信反向代理后启用 HTTPS。首次初始化时，将 `APP_ALLOW_REGISTRATION` 设为 `true` 或 `invite`，并为 `APP_SETUP_TOKEN` 配置至少 32 个字符的随机值；创建的第一个用户会自动成为系统管理员，且必须在页面输入该令牌。完成后可将注册改为 `false` 彻底关闭，或改为 `invite` 仅允许持有一次性邀请码的用户注册。后续完全开放注册时不再要求初始化令牌；邀请码模式下普通注册必须填写系统管理员生成的一次性邀请码。可选的 HTTP Basic Auth 仅作为额外部署网关，其凭据只是 Base64 编码，未使用 HTTPS 时不能防止链路窃听。`/api/health` 保持免认证以供探活，业务 API 需要应用内登录。
 
 ## AI 供应商配置
 

package/dist/app.js

@@ -39,7 +39,7 @@ import { composeRoleplayStoredUserContent } from "./roleplay-turn.js";
 import { ROLEPLAY_MEMORY_CATEGORIES, ROLEPLAY_MEMORY_CERTAINTY, ROLEPLAY_MEMORY_IMPORTANCE, ROLEPLAY_MEMORY_STATUSES } from "./roleplay-memory.js";
 import { paginated, parsePagination } from "./pagination.js";
 import { normalizeUploadFileName } from "./utils.js";
-import { assertSafeAiEndpoint, assertSafeS3Endpoint, createApiRateLimitMiddleware, createAuthenticationRateLimitMiddleware, createBasicAuthMiddleware, createCaptchaRateLimitMiddleware, createExpensiveApiRateLimitMiddleware, createSameOriginMiddleware, createSecurityHeadersMiddleware, createUploadRateLimitMiddleware, enforceCaseInsensitiveRouting, normalizeApiPath, resolveTrustProxySetting, verifySetupToken } from "./security.js";
+import { assertSafeAiEndpoint, assertSafeS3Endpoint, createApiRateLimitMiddleware, createAuthenticationRateLimitMiddleware, createBasicAuthMiddleware, createCaptchaRateLimitMiddleware, createExpensiveApiRateLimitMiddleware, createSameOriginMiddleware, createSecurityHeadersMiddleware, createUploadRateLimitMiddleware, enforceCaseInsensitiveRouting, isRegistrationEnabled, normalizeApiPath, resolveRegistrationMode, resolveTrustProxySetting, verifySetupToken } from "./security.js";
 import { ImageCaptchaService } from "./image-captcha.js";
 import { ImService } from "./im.js";
 import { ImOrchestrator } from "./im-orchestrator.js";
@@ -146,6 +146,7 @@ const registrationSchema = z.object({
     password: passwordSchema,
     passwordConfirmation: passwordSchema,
     setupToken: z.string().max(500).optional(),
+    inviteCode: z.string().trim().max(32).optional(),
     ...captchaFields
 }).strict().refine((input) => input.password === input.passwordConfirmation, {
     path: ["passwordConfirmation"],
@@ -164,6 +165,20 @@ const desktopLoginSchema = z.object({
     clientVersion: z.string().trim().min(1).max(80),
     ...captchaFields
 }).strict();
+const desktopRegistrationSchema = z.object({
+    username: usernameSchema,
+    password: passwordSchema,
+    passwordConfirmation: passwordSchema,
+    setupToken: z.string().max(500).optional(),
+    inviteCode: z.string().trim().max(32).optional(),
+    desktopId: z.string().uuid(),
+    profileId: z.string().uuid(),
+    clientVersion: z.string().trim().min(1).max(80),
+    ...captchaFields
+}).strict().refine((input) => input.password === input.passwordConfirmation, {
+    path: ["passwordConfirmation"],
+    message: "两次输入的密码不一致"
+});
 const userUpdateSchema = z.object({ role: z.enum(["admin", "user"]).optional(), status: z.enum(["active", "disabled"]).optional() }).strict();
 const memberRoleValueSchema = z.enum(["editor", "settings-editor", "viewer"]);
 const moduleAccessSchema = z.enum(["none", "read", "write"]);
@@ -1502,15 +1517,38 @@ export function createRuntime(options) {
         app.use(createSameOriginMiddleware());
     app.use("/api/sync/works", express.json({ limit: "3mb" }));
     app.use(express.json({ limit: "2mb" }));
+    const registrationMode = resolveRegistrationMode(options.security);
+    const registrationEnabled = isRegistrationEnabled(registrationMode);
+    const registrationPolicy = (setupRequired) => ({
+        registrationMode,
+        registrationOpen: registrationEnabled,
+        inviteRequired: registrationMode === "invite" && !setupRequired
+    });
+    const resolvedInviteCode = (inviteCode, setupRequired) => {
+        if (registrationMode !== "invite" || setupRequired)
+            return undefined;
+        const trimmed = inviteCode?.trim() ?? "";
+        if (!trimmed)
+            throw new AppError(400, "INVITE_CODE_REQUIRED", "当前部署需要邀请码才能注册");
+        return trimmed;
+    };
     app.get("/api/auth/session", (request, response) => {
         const desktopSession = auth.authenticateDesktop(request);
         const session = desktopSession ? null : auth.authenticate(request);
-        const registrationOpen = options.security?.allowRegistration === true;
         const setupRequired = !auth.hasUsers();
         const setupTokenRequired = setupRequired && Boolean(options.security?.setupToken);
+        const policy = registrationPolicy(setupRequired);
         const developmentUser = getDevelopmentUser();
         if (!session && developmentUser) {
-            data(response, { authenticated: true, user: developmentUser, csrfToken: null, bootId, setupRequired: false, setupTokenRequired: false, registrationOpen });
+            data(response, {
+                authenticated: true,
+                user: developmentUser,
+                csrfToken: null,
+                bootId,
+                setupRequired: false,
+                setupTokenRequired: false,
+                ...registrationPolicy(false)
+            });
             return;
         }
         const interactiveSession = desktopSession ?? session;
@@ -1522,25 +1560,33 @@ export function createRuntime(options) {
                 bootId,
                 setupRequired: false,
                 setupTokenRequired: false,
-                registrationOpen
+                ...registrationPolicy(false)
             }
-            : { authenticated: false, user: null, csrfToken: null, bootId, setupRequired, setupTokenRequired, registrationOpen });
+            : { authenticated: false, user: null, csrfToken: null, bootId, setupRequired, setupTokenRequired, ...policy });
     });
     app.get("/api/auth/captcha", (_request, response) => {
         data(response, captcha.create());
     });
     app.post("/api/auth/register", (request, response) => {
-        if (options.security?.allowRegistration !== true) {
+        if (!registrationEnabled) {
             throw new AppError(403, "REGISTRATION_DISABLED", "当前部署已关闭新用户注册");
         }
         const input = parse(registrationSchema, request.body);
         captcha.consume(input.captchaId, input.captchaAnswer);
-        if (!auth.hasUsers() && !verifySetupToken(options.security?.setupToken, input.setupToken)) {
+        const setupRequired = !auth.hasUsers();
+        if (setupRequired && !verifySetupToken(options.security?.setupToken, input.setupToken)) {
             throw new AppError(403, "SETUP_TOKEN_INVALID", "初始化令牌无效或未配置");
         }
-        const result = auth.register({ username: input.username, password: input.password });
+        const result = auth.register({
+            username: input.username,
+            password: input.password,
+            inviteCode: resolvedInviteCode(input.inviteCode, setupRequired)
+        });
         setSessionCookie(response, result.token, request.secure);
-        runWithRequestActor(result.session.user, () => store.audit(null, "user.registered", "user", result.session.user.userId, { role: result.session.user.role }));
+        runWithRequestActor(result.session.user, () => store.audit(null, "user.registered", "user", result.session.user.userId, {
+            role: result.session.user.role,
+            ...(result.inviteId ? { inviteId: result.inviteId } : {})
+        }));
         logger.info("auth.registration.succeeded", { actorRef: accountReference(result.session.user.userId) });
         data(response, { user: result.session.user, csrfToken: result.session.csrfToken }, 201);
     });
@@ -1567,6 +1613,34 @@ export function createRuntime(options) {
         logger.info("auth.desktop_login.succeeded", { actorRef: accountReference(result.session.user.userId) });
         data(response, { token: result.token, expiresAt: result.session.expiresAt, user: result.session.user });
     });
+    app.post("/api/desktop/auth/register", (request, response) => {
+        if (!registrationEnabled) {
+            throw new AppError(403, "REGISTRATION_DISABLED", "当前部署已关闭新用户注册");
+        }
+        const input = parse(desktopRegistrationSchema, request.body);
+        captcha.consume(input.captchaId, input.captchaAnswer);
+        const setupRequired = !auth.hasUsers();
+        if (setupRequired && !verifySetupToken(options.security?.setupToken, input.setupToken)) {
+            throw new AppError(403, "SETUP_TOKEN_INVALID", "初始化令牌无效或未配置");
+        }
+        const result = auth.registerDesktop({
+            username: input.username,
+            password: input.password,
+            inviteCode: resolvedInviteCode(input.inviteCode, setupRequired),
+            desktopId: input.desktopId,
+            profileId: input.profileId,
+            clientVersion: input.clientVersion
+        });
+        imOrchestrator.disconnectUser(result.session.user.userId);
+        response.setHeader("Cache-Control", "no-store");
+        runWithRequestActor(result.session.user, () => store.audit(null, "user.registered", "user", result.session.user.userId, {
+            role: result.session.user.role,
+            source: "desktop",
+            ...(result.inviteId ? { inviteId: result.inviteId } : {})
+        }));
+        logger.info("auth.desktop_registration.succeeded", { actorRef: accountReference(result.session.user.userId) });
+        data(response, { token: result.token, expiresAt: result.session.expiresAt, user: result.session.user }, 201);
+    });
     app.use(createUserSessionMiddleware(auth, {
         disabled: options.disableUserAuth === true,
         resolveBypassUser: getDevelopmentUser
@@ -1714,6 +1788,28 @@ export function createRuntime(options) {
         store.audit(null, "user.updated", "user", updated.userId, { role: updated.role, status: updated.status });
         data(response, updated);
     });
+    app.get("/api/registration-invites", (request, response) => {
+        if (!request.authUser)
+            throw new AppError(401, "AUTH_REQUIRED", "请先登录");
+        if (request.authUser.role !== "admin")
+            throw new AppError(403, "ADMIN_REQUIRED", "该操作仅限系统管理员");
+        data(response, {
+            registrationMode,
+            registrationOpen: registrationEnabled,
+            items: auth.listRegistrationInvites()
+        });
+    });
+    app.post("/api/registration-invites", (request, response) => {
+        if (!request.authUser)
+            throw new AppError(401, "AUTH_REQUIRED", "请先登录");
+        if (request.authUser.role !== "admin")
+            throw new AppError(403, "ADMIN_REQUIRED", "该操作仅限系统管理员");
+        parse(z.object({}).strict(), request.body ?? {});
+        const created = auth.createRegistrationInvite(request.authUser);
+        store.audit(null, "registration-invite.created", "registration-invite", created.id, {});
+        logger.info("auth.registration_invite.created", { actorRef: accountReference(request.authUser.userId) });
+        data(response, created, 201);
+    });
     const requireImUser = (request) => {
         if (!request.authUser || !hasInteractiveSession(request)) {
             throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话访问 IM");