dominds 1.25.19 → 1.26.0

package/README.md

@@ -253,6 +253,23 @@ Platform note:
 
 - Windows also registers `codex_inspect_and_patch_tools`; its `readonly_shell` tool runs through `cmd.exe`, so prefer allowlisted commands available in that shell/PATH, such as `rg`, `git`, `dir`, `type`, and `where`.
 
+### Local HTTPS Certificates
+
+Dominds always keeps an HTTP listener. When a valid certificate matching the current `--host` exists under `~/.dominds/certs/`, Dominds also starts HTTPS. Certificates match DNS/IP hostnames, not ports, so one certificate covers all Dominds WebUI ports on that host.
+
+```bash
+# Create a 10-year self-signed certificate for detected non-loopback LAN hosts
+dominds cert create
+
+# Add explicit SAN hosts; --host can be repeated
+dominds cert create --host 192.168.1.10 --host my-host.local
+
+# Inspect whether a host can use an HTTPS certificate
+dominds cert status --host 0.0.0.0
+```
+
+`localhost`, `loopback`, `127.0.0.0/8`, `::1`, `0.0.0.0`, and `::` are not certificate hosts. `0.0.0.0` / `::` only mean bind-all; certificate matching uses detected non-loopback LAN hosts. A bare `--port 5666` disables Dominds built-in HTTPS and assumes a front proxy handles HTTPS, while the default port behavior and `--port 5666+/-` may auto-enable built-in HTTPS when a matching certificate exists.
+
 ## Start from scratch
 
 Starting from scratch means: create an empty folder, run `dominds`, let Setup generate the minimal `.minds/team.yaml`, then use the shadow team manager (`@fuxi`) to design a real team for your product.

package/README.zh.md

@@ -192,6 +192,23 @@ dominds
 
 - Windows 也会注册 `codex_inspect_and_patch_tools`；其中 `readonly_shell` 通过 `cmd.exe` 执行，因此优先使用该 shell/PATH 中可用的白名单命令，例如 `rg`、`git`、`dir`、`type` 和 `where`。
 
+### 本地 HTTPS 证书
+
+Dominds 默认始终提供 HTTP 监听；当 `~/.dominds/certs/` 下存在匹配当前 `--host` 的有效证书时，会额外启用 HTTPS。证书按 DNS/IP 主机名匹配，不绑定端口，因此同一张证书可覆盖该主机上的所有 Dominds WebUI 端口。
+
+```bash
+# 自动为检测到的一个或多个非 loopback LAN 主机创建 10 年有效的自签名证书
+dominds cert create
+
+# 显式指定证书 SAN，可重复 --host
+dominds cert create --host 192.168.1.10 --host my-host.local
+
+# 查看指定 host 是否能匹配到证书
+dominds cert status --host 0.0.0.0
+```
+
+`localhost`、`loopback`、`127.0.0.0/8`、`::1`、`0.0.0.0`、`::` 不会作为 HTTPS 证书主机；其中 `0.0.0.0` / `::` 仅表示绑定所有地址，匹配证书时会使用检测到的非 loopback LAN 主机。使用裸 `--port 5666` 启动时，Dominds 会认为 HTTPS 由前置代理负责，不启用内建 HTTPS；使用默认端口或 `--port 5666+/-` 时才会自动启用内建 HTTPS。
+
 ## 从零开始（空文件夹启动）
 
 若暂无模板或团队配置，可直接从空目录启动：

package/dist/apps/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { DomindsKernelEndpoint } from '@longrun-ai/kernel/app-host-contract';
 import { type AppsHostClient } from '../apps-host/client';
 export type DynamicAppToolAvailabilityResult = Readonly<{
     status: 'ready';
@@ -36,8 +37,5 @@ export declare function resolveDynamicAppToolAvailabilityForMember(_params: {
 }): Promise<DynamicAppToolAvailabilityResult>;
 export declare function initAppsRuntime(params: {
     rtwsRootAbs: string;
-    kernel: Readonly<{
-        host: string;
-        port: number;
-    }>;
+    kernel: DomindsKernelEndpoint;
 }): Promise<void>;

package/dist/apps-host/client.d.ts

@@ -1,4 +1,4 @@
-import type { DomindsAppDynamicToolsetsContext, DomindsAppReminderOwnerApplyContext, DomindsAppReminderOwnerRenderContext, DomindsAppReminderOwnerUpdateContext, DomindsAppReminderRenderedMessage, DomindsAppRunControlContext, DomindsAppRunControlResult } from '@longrun-ai/kernel/app-host-contract';
+import type { DomindsAppDynamicToolsetsContext, DomindsAppReminderOwnerApplyContext, DomindsAppReminderOwnerRenderContext, DomindsAppReminderOwnerUpdateContext, DomindsAppReminderRenderedMessage, DomindsAppRunControlContext, DomindsAppRunControlResult, DomindsKernelEndpoint } from '@longrun-ai/kernel/app-host-contract';
 import type { DomindsAppHostReminderUpdateResult, DomindsAppHostToolResult, DomindsAppInstallJson, DomindsAppReminderApplyRequest, DomindsAppReminderApplyResult } from '@longrun-ai/kernel/app-json';
 import type { ToolArguments } from '../tool';
 import type { AppsHostMessageToKernel } from './ipc-types';
@@ -29,10 +29,7 @@ export type AppsHostReadyMessage = Extract<AppsHostMessageToKernel, {
 }>;
 export declare function startAppsHost(params: {
     rtwsRootAbs: string;
-    kernel: Readonly<{
-        host: string;
-        port: number;
-    }>;
+    kernel: DomindsKernelEndpoint;
     apps: ReadonlyArray<EnabledAppForHost>;
 }): Promise<Readonly<{
     client: AppsHostClient;

package/dist/apps-host/ipc-types.d.ts

@@ -1,14 +1,11 @@
-import type { DomindsAppReminderRenderedMessage, DomindsAppRunControlResult } from '@longrun-ai/kernel/app-host-contract';
+import type { DomindsAppReminderRenderedMessage, DomindsAppRunControlResult, DomindsKernelEndpoint } from '@longrun-ai/kernel/app-host-contract';
 import type { DomindsAppDialogReminderRequestBatch, DomindsAppHostReminderUpdateResult, DomindsAppInstallJson, DomindsAppReminderApplyRequest, DomindsAppReminderApplyResult, DomindsAppReminderState } from '@longrun-ai/kernel/app-json';
 import type { LanguageCode } from '@longrun-ai/kernel/types/language';
 import type { ToolArguments, ToolCallOutput } from '../tool';
 export type AppsHostKernelInitMessage = Readonly<{
     type: 'init';
     rtwsRootAbs: string;
-    kernel: Readonly<{
-        host: string;
-        port: number;
-    }>;
+    kernel: DomindsKernelEndpoint;
     apps: ReadonlyArray<Readonly<{
         appId: string;
         runtimePort: number | null;

package/dist/apps-host/ipc-types.js

@@ -126,9 +126,13 @@ function parseAppsHostMessageFromKernel(v) {
             throw new Error('Invalid init message: rtwsRootAbs required');
         if (!isRecord(kernel))
             throw new Error('Invalid init message: kernel must be object');
+        const scheme = kernel['scheme'];
         const host = asString(kernel['host']);
         const portRaw = kernel['port'];
         const port = typeof portRaw === 'number' && Number.isFinite(portRaw) ? Math.floor(portRaw) : null;
+        if (scheme !== 'http' && scheme !== 'https') {
+            throw new Error('Invalid init message: kernel.scheme must be http|https');
+        }
         if (!host)
             throw new Error('Invalid init message: kernel.host required');
         if (port === null || port < 0) {
@@ -157,7 +161,7 @@ function parseAppsHostMessageFromKernel(v) {
             }
             return { appId, runtimePort, installJson: installJson };
         });
-        return { type: 'init', rtwsRootAbs, kernel: { host, port }, apps: parsedApps };
+        return { type: 'init', rtwsRootAbs, kernel: { scheme, host, port }, apps: parsedApps };
     }
     if (type === 'tool_call') {
         const callId = asString(v['callId']);

package/dist/cli/cert.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(args?: readonly string[]): Promise<void>;

package/dist/cli/cert.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const auth_1 = require("../server/auth");
+const certificates_1 = require("../server/certificates");
+function printHelp() {
+    console.log(`
+Dominds certificate tools
+
+Usage:
+  dominds cert create [--host <host>] [--days <days>] [--force]
+  dominds cert self-cert [--host <host>] [--days <days>] [--force]
+  dominds cert status --host <host> [--port <port>] [--origin]
+
+Options:
+  --host <host>      Host name or IP address (default for create: detected non-loopback LAN hosts)
+  --days <days>      Certificate validity in days (default: ${certificates_1.DEFAULT_SELF_SIGNED_CERT_DAYS})
+  --force            Overwrite existing generated files
+  --port <port>      Port for status --origin output
+  --origin           Print only the effective origin, using https when a matching cert exists
+  --help             Show this help message
+
+Certificates live in ~/.dominds/certs/. A WebUI server automatically enables HTTPS when it finds
+a certificate/key pair that matches the bind host or, for 0.0.0.0/::, a detected non-loopback LAN host.
+`);
+}
+async function main(args = process.argv.slice(2)) {
+    const first = args[0];
+    if (first === undefined || first === '--help' || first === '-h') {
+        printHelp();
+        return;
+    }
+    const action = parseAction(first);
+    if (action === null) {
+        console.error(`Error: Unknown cert subcommand '${first}'`);
+        printHelp();
+        process.exit(1);
+    }
+    const options = parseOptions(args.slice(1), action);
+    if (options.kind === 'error') {
+        console.error(`Error: ${options.message}`);
+        printHelp();
+        process.exit(1);
+    }
+    if (action === 'create') {
+        const created = await (0, certificates_1.createSelfSignedCertificate)({
+            host: options.host,
+            altHosts: options.altHosts,
+            days: options.days,
+            force: options.force,
+        });
+        console.log(`Created self-signed certificate for ${created.host}`);
+        console.log(`  hosts: ${created.hosts.join(', ')}`);
+        console.log(`  cert: ${created.certPath}`);
+        console.log(`  key:  ${created.keyPath}`);
+        console.log(`  meta: ${created.metadataPath}`);
+        console.log(`  days: ${created.days}`);
+        return;
+    }
+    if (options.host === undefined) {
+        console.error('Error: cert status requires --host <host>');
+        printHelp();
+        process.exit(1);
+    }
+    const lookup = await (0, certificates_1.findAutoHttpsCertificateForHost)({ host: options.host });
+    if (options.origin) {
+        if (options.port === undefined) {
+            console.error('Error: cert status --origin requires --port <port>');
+            process.exit(1);
+        }
+        console.log((0, auth_1.formatServerOrigin)({
+            scheme: lookup.kind === 'found' ? 'https' : 'http',
+            host: lookup.kind === 'found' ? lookup.certificate.matchedHost : lookup.endpoint.urlHost,
+            port: options.port,
+        }));
+        return;
+    }
+    for (const diagnostic of lookup.diagnostics) {
+        console.warn(`warning: ${diagnostic.message}`);
+    }
+    if (lookup.kind === 'found') {
+        console.log(`HTTPS certificate: found`);
+        console.log(`  cert: ${lookup.certificate.certPath}`);
+        console.log(`  key:  ${lookup.certificate.keyPath}`);
+        console.log(`  matchedHost: ${lookup.certificate.matchedHost}`);
+        console.log(`  validTo: ${lookup.certificate.validTo.toISOString()}`);
+    }
+    else {
+        console.log(`HTTPS certificate: not found`);
+        console.log(`  certsDir: ${lookup.certsDirAbs}`);
+    }
+}
+function parseAction(value) {
+    switch (value) {
+        case 'create':
+        case 'self-cert':
+            return 'create';
+        case 'status':
+            return 'status';
+        default:
+            return null;
+    }
+}
+function parseOptions(args, action) {
+    let host;
+    let days;
+    const altHosts = [];
+    let force = false;
+    let port;
+    let origin = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--host') {
+            const next = args[i + 1];
+            if (!next)
+                return { kind: 'error', message: '--host requires a value' };
+            if (host === undefined)
+                host = next;
+            else
+                altHosts.push(next);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--host=')) {
+            const value = arg.slice('--host='.length);
+            if (host === undefined)
+                host = value;
+            else
+                altHosts.push(value);
+            continue;
+        }
+        if (arg === '--days') {
+            const next = args[i + 1];
+            const parsed = next === undefined ? null : parseInteger(next);
+            if (parsed === null)
+                return { kind: 'error', message: '--days requires an integer' };
+            days = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--days=')) {
+            const parsed = parseInteger(arg.slice('--days='.length));
+            if (parsed === null)
+                return { kind: 'error', message: '--days requires an integer' };
+            days = parsed;
+            continue;
+        }
+        if (arg === '--port') {
+            const next = args[i + 1];
+            const parsed = next === undefined ? null : parseInteger(next);
+            if (parsed === null || parsed < 1 || parsed > 65535) {
+                return { kind: 'error', message: '--port requires a valid TCP port' };
+            }
+            port = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--port=')) {
+            const parsed = parseInteger(arg.slice('--port='.length));
+            if (parsed === null || parsed < 1 || parsed > 65535) {
+                return { kind: 'error', message: '--port requires a valid TCP port' };
+            }
+            port = parsed;
+            continue;
+        }
+        if (arg === '--force') {
+            force = true;
+            continue;
+        }
+        if (arg === '--origin') {
+            origin = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        if (!arg.startsWith('-') && host === undefined && action === 'create') {
+            host = arg;
+            continue;
+        }
+        return { kind: 'error', message: `Unknown option '${arg}'` };
+    }
+    return { kind: 'ok', host, days, altHosts, force, port, origin };
+}
+function parseInteger(raw) {
+    if (!/^[0-9]+$/.test(raw))
+        return null;
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/cli/webui.d.ts

@@ -9,7 +9,7 @@
  *   -p, --port <port>    Port to listen on. Bare port is strict; suffix + tries higher ports; suffix - tries lower ports.
  *   -h, --host <host>    Host to bind to (default: localhost)
  *   --nobrowser          Do not open a browser (opt-out)
- *   -h, --help           Show help
+ *   --help               Show help
  */
 declare function main(args?: readonly string[]): Promise<void>;
 export { main };

package/dist/cli/webui.js

@@ -10,7 +10,7 @@
  *   -p, --port <port>    Port to listen on. Bare port is strict; suffix + tries higher ports; suffix - tries lower ports.
  *   -h, --host <host>    Host to bind to (default: localhost)
  *   --nobrowser          Do not open a browser (opt-out)
- *   -h, --help           Show help
+ *   --help               Show help
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
@@ -22,6 +22,14 @@ const server_1 = require("../server");
 const auth_1 = require("../server/auth");
 const port_selection_1 = require("../server/port-selection");
 const log = (0, log_1.createLogger)('webui');
+function formatWebSocketEndpoint(params) {
+    const httpOrigin = (0, auth_1.formatServerOrigin)({
+        scheme: params.scheme === 'ws' ? 'http' : 'https',
+        host: params.host,
+        port: params.port,
+    });
+    return `${params.scheme}${httpOrigin.slice(httpOrigin.indexOf(':'))}/ws`;
+}
 function printHelp() {
     console.log(`
 WebUI Server for dominds
@@ -145,12 +153,34 @@ async function main(args = process.argv.slice(2)) {
         });
         const httpServer = started.httpServer;
         const auth = started.auth;
-        const baseUrl = `http://${started.host}:${started.port}`;
+        const baseUrl = (0, auth_1.formatServerOrigin)({
+            scheme: 'http',
+            host: started.urlHost,
+            port: started.port,
+        });
         log.info(`WebUI ready: ${baseUrl}`);
-        log.debug(`WebSocket endpoint: ws://${started.host}:${started.port}/ws`);
+        log.debug(`WebSocket endpoint: ${formatWebSocketEndpoint({
+            scheme: 'ws',
+            host: started.urlHost,
+            port: started.port,
+        })}`);
+        if (started.httpsPort !== undefined && started.httpsUrlHost !== undefined) {
+            const httpsBaseUrl = (0, auth_1.formatServerOrigin)({
+                scheme: 'https',
+                host: started.httpsUrlHost,
+                port: started.httpsPort,
+            });
+            log.info(`HTTPS WebUI ready: ${httpsBaseUrl}`);
+            log.debug(`HTTPS WebSocket endpoint: ${formatWebSocketEndpoint({
+                scheme: 'wss',
+                host: started.httpsUrlHost,
+                port: started.httpsPort,
+            })}`);
+        }
         if (auth.kind === 'enabled') {
             const autoAuthUrl = (0, auth_1.formatAutoAuthUrl)({
-                host: started.host,
+                scheme: 'http',
+                host: started.urlHost,
                 port: started.port,
                 authKey: auth.key,
             });

package/dist/cli.d.ts

@@ -13,6 +13,7 @@
  *   man      - Render toolset manual to stdout
  *   manual   - Alias for man
  *   validate_team_def - Validate explicit team toolset declarations
+ *   cert     - Create and inspect local HTTPS certificates
  *   create   - Create a new runtime workspace (rtws) from a template
  *   install  - Install a Dominds App into this rtws
  *   doctor   - Diagnose Dominds App state in this rtws

package/dist/cli.js

@@ -14,6 +14,7 @@
  *   man      - Render toolset manual to stdout
  *   manual   - Alias for man
  *   validate_team_def - Validate explicit team toolset declarations
+ *   cert     - Create and inspect local HTTPS certificates
  *   create   - Create a new runtime workspace (rtws) from a template
  *   install  - Install a Dominds App into this rtws
  *   doctor   - Diagnose Dominds App state in this rtws
@@ -70,6 +71,7 @@ const path = __importStar(require("path"));
 const runtime_1 = require("./apps/runtime");
 const dotenv_1 = require("./bootstrap/dotenv");
 const rtws_cli_1 = require("./bootstrap/rtws-cli");
+const cert_1 = require("./cli/cert");
 const create_1 = require("./cli/create");
 const disable_1 = require("./cli/disable");
 const doctor_1 = require("./cli/doctor");
@@ -120,6 +122,7 @@ Subcommands:
   man [options]      Render toolset manual to stdout
   manual [options]   Alias for man
   validate_team_def [options] Validate explicit team toolset declarations
+  cert [options]     Create and inspect local HTTPS certificates
   create [options]   Create a new runtime workspace (rtws) from a template
   install [options]  Install a Dominds App into this rtws
   doctor [options]   Read-only diagnosis across manifest/lock/configuration/resolution/handshake
@@ -139,6 +142,7 @@ Examples:
   dominds read               # Read team configuration
   dominds man ws_read --lang zh --all
   dominds validate_team_def  # Validate toolset references in .minds/team.yaml
+  dominds cert create --host 192.168.1.10
   dominds create web-scaffold my-project   # Create rtws from a template
   dominds doctor @longrun-ai/web-dev       # Diagnose a single app across all app-state layers
 
@@ -195,7 +199,8 @@ async function main(argv = process.argv.slice(2)) {
         printVersion();
         process.exit(0);
     }
-    const shouldSkipRtwsSetup = subcommandArgs.includes('--help') ||
+    const shouldSkipRtwsSetup = subcommand === 'cert' ||
+        subcommandArgs.includes('--help') ||
         (subcommand === 'tui' && subcommandArgs.includes('-h')) ||
         (subcommand === 'run' && subcommandArgs.includes('-h')) ||
         (subcommand === 'read' && subcommandArgs.includes('-h')) ||
@@ -232,6 +237,7 @@ async function main(argv = process.argv.slice(2)) {
         configureEnvProxySupport();
     }
     const shouldLoadApps = subcommand !== 'webui' &&
+        subcommand !== 'cert' &&
         subcommand !== 'create' &&
         subcommand !== 'new' &&
         subcommand !== 'install' &&
@@ -249,7 +255,7 @@ async function main(argv = process.argv.slice(2)) {
             if (shouldStartAppsHost) {
                 await (0, runtime_1.initAppsRuntime)({
                     rtwsRootAbs: process.cwd(),
-                    kernel: { host: '127.0.0.1', port: 0 },
+                    kernel: { scheme: 'http', host: '127.0.0.1', port: 0 },
                 });
             }
         }
@@ -279,6 +285,9 @@ async function main(argv = process.argv.slice(2)) {
         case 'validate_team_def':
             await runSubcommand('validate_team_def', subcommandArgs);
             break;
+        case 'cert':
+            await runSubcommand('cert', subcommandArgs);
+            break;
         case 'create':
         case 'new':
             await runSubcommand('create', subcommandArgs);
@@ -325,6 +334,9 @@ async function runSubcommand(subcommand, args) {
         else if (subcommand === 'validate_team_def') {
             await (0, validate_team_def_1.main)(args);
         }
+        else if (subcommand === 'cert') {
+            await (0, cert_1.main)(args);
+        }
         else if (subcommand === 'create') {
             await (0, create_1.main)(args);
         }
@@ -352,7 +364,7 @@ async function runSubcommand(subcommand, args) {
         }
     }
     catch (err) {
-        console.error(`Failed to execute subcommand '${subcommand}':`, err);
+        console.error(`Failed to execute subcommand '${subcommand}': ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
 }

package/dist/docs/cli-usage.md

@@ -18,6 +18,7 @@ The `dominds` CLI provides a unified entry point, but the **primary interaction
     - [Web UI Interface](#web-ui-interface)
     - [Text User Interface (TUI) (Not Implemented Yet)](#text-user-interface-tui-not-implemented-yet)
     - [Minds Reader](#minds-reader)
+    - [Certificate Tools](#certificate-tools)
     - [rtws Creation](#rtws-creation)
   - [Usage Examples](#usage-examples)
   - [Dialog Storage](#dialog-storage)
@@ -32,6 +33,7 @@ The `dominds` package provides a unified CLI with subcommands:
 | `dominds` or `dominds webui`      | Start Web UI (default, recommended)                           | Web UI         |
 | `dominds tui` or `dominds run`    | Terminal UI (planned; no stable implementation at the moment) | N/A            |
 | `dominds read`                    | Read and inspect rtws/team minds configuration                | CLI            |
+| `dominds cert`                    | Create and inspect local WebUI HTTPS certificates             | CLI            |
 | `dominds create` or `dominds new` | Create a new rtws (runtime workspace) from a template         | CLI            |
 | `dominds help`                    | Show help message                                             | CLI            |
 | `dominds --version`               | Show version information                                      | CLI            |
@@ -54,6 +56,11 @@ dominds webui -C /path/to/my-rtws
 # Minds reader: inspect team configuration
 dominds read [options] [member-id]
 
+# Certificate tools: create/inspect local HTTPS certificates
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+
 # rtws creation: scaffold a new runtime workspace
 dominds create <template> [directory]
 dominds new <template> [directory]  # alias for create
@@ -137,6 +144,35 @@ dominds read --only-prompt
 dominds read --only-mem
 ```
 
+### Certificate Tools
+
+```bash
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+```
+
+Create or inspect local HTTPS certificates for the Dominds WebUI. Certificates live in `~/.dominds/certs/` and match DNS/IP hostnames, not ports; one certificate covers every WebUI port on that host.
+
+**Options:**
+
+- `--host <host>` - Certificate SAN hostname or IP; repeatable for certificate creation; defaults to one or more detected non-loopback LAN hosts
+- `--days <days>` - Certificate validity in days (default: 3650, or 10 years)
+- `--force` - Overwrite existing generated files
+- `--port <port>` - Port used when formatting `status --origin`
+- `--origin` - Print only the effective origin; HTTPS when a cert matches, HTTP otherwise
+
+**Examples:**
+
+```bash
+dominds cert create
+dominds cert create --host 192.168.1.10 --host my-host.local
+dominds cert status --host 0.0.0.0
+dominds cert status --host 0.0.0.0 --port 5666 --origin
+```
+
+`localhost`, `loopback`, `127.0.0.0/8`, `::1`, `0.0.0.0`, and `::` are not certificate hosts. `0.0.0.0` / `::` only mean bind-all; certificate matching uses detected non-loopback LAN hosts.
+
 ### rtws Creation
 
 ```bash

package/dist/docs/cli-usage.zh.md

@@ -18,6 +18,7 @@
     - [Web UI 界面](#web-ui-界面)
     - [文本用户界面 (TUI)（尚未实现）](#文本用户界面-tui尚未实现)
     - [Minds 阅读器](#minds-阅读器)
+    - [证书工具](#证书工具)
     - [rtws 创建](#rtws-创建)
   - [使用示例](#使用示例)
   - [对话存储](#对话存储)
@@ -32,6 +33,7 @@
 | `dominds` 或 `dominds webui`      | 启动 Web UI（默认、推荐）                | Web UI   |
 | `dominds tui` 或 `dominds run`    | 终端界面（规划中；当前版本暂不提供稳定） | N/A      |
 | `dominds read`                    | 读取/分析团队 minds 配置                 | CLI      |
+| `dominds cert`                    | 创建/检查本机 WebUI HTTPS 证书           | CLI      |
 | `dominds create` 或 `dominds new` | 从模板创建新 rtws（运行时工作区）        | CLI      |
 | `dominds help`                    | 显示帮助消息                             | CLI      |
 | `dominds --version`               | 显示版本信息                             | CLI      |
@@ -54,6 +56,11 @@ dominds webui -C /path/to/my-rtws
 # Minds 阅读器：分析团队配置
 dominds read [options] [member-id]
 
+# 证书工具：创建/检查本机 HTTPS 证书
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+
 # rtws 创建：搭建新项目/运行时工作区
 dominds create <template> [directory]
 dominds new <template> [directory]  # create 的别名
@@ -144,6 +151,35 @@ dominds read --only-prompt
 dominds read --only-mem
 ```
 
+### 证书工具
+
+```bash
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+```
+
+创建或检查 Dominds WebUI 的本机 HTTPS 证书。证书保存在 `~/.dominds/certs/`，按 DNS/IP 主机名匹配，不绑定端口；同一张证书可覆盖该主机上的所有 WebUI 端口。
+
+**选项：**
+
+- `--host <host>` - 证书 SAN 主机名或 IP；创建证书时可重复指定；未指定时使用检测到的一个或多个非 loopback LAN 主机
+- `--days <days>` - 证书有效天数（默认：3650，即 10 年）
+- `--force` - 覆盖已有的同名生成文件
+- `--port <port>` - `status --origin` 输出 URL 时使用的端口
+- `--origin` - 仅输出有效访问 origin；找到证书时输出 HTTPS，否则输出 HTTP
+
+**示例：**
+
+```bash
+dominds cert create
+dominds cert create --host 192.168.1.10 --host my-host.local
+dominds cert status --host 0.0.0.0
+dominds cert status --host 0.0.0.0 --port 5666 --origin
+```
+
+`localhost`、`loopback`、`127.0.0.0/8`、`::1`、`0.0.0.0`、`::` 不会作为 HTTPS 证书主机。`0.0.0.0` / `::` 只表示绑定所有地址，匹配证书时会使用检测到的非 loopback LAN 主机。
+
 ### rtws 创建
 
 ```bash

package/dist/server/auth.d.ts

@@ -37,7 +37,14 @@ export declare function isAuthEnabled(auth: AuthConfig): auth is Extract<AuthCon
 export declare function getHttpAuthCheck(req: IncomingMessage, auth: AuthConfig): AuthCheckResult;
 export declare function getHttpAuthCheckAllowUrlParam(req: IncomingMessage, auth: AuthConfig, requestUrl: URL): AuthCheckResult;
 export declare function getWebSocketAuthCheck(req: IncomingMessage, auth: AuthConfig): AuthCheckResult;
+export type ServerUrlScheme = 'http' | 'https';
+export declare function formatServerOrigin(params: {
+    scheme: ServerUrlScheme;
+    host: string;
+    port: number;
+}): string;
 export declare function formatAutoAuthUrl(params: {
+    scheme?: ServerUrlScheme;
     host: string;
     port: number;
     authKey: string;