dscord 0.2.0-alpha.1 → 0.4.0-alpha.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,22 @@
+DSCord
+Copyright 2026 DSCord contributors
+
+DSCord-specific source code and documentation in this package are licensed
+under the Apache License, Version 2.0. See LICENSE.
+
+Third-party components retain their own licenses and notices.
+
+DS-Bot
+The vendored kernel is based on DS-Bot 0.3.1 by Fei2411 and the DS Bot
+contributors, under Apache-2.0. See vendor/ds-bot/LICENSE,
+vendor/ds-bot/NOTICE and vendor/ds-bot/UPSTREAM.json for provenance,
+additional third-party notices and the DSCord modifications.
+
+Ombre
+The optional memory service is distributed under its MIT license.
+See service/ombre/LICENSE and service/ombre/SOURCE.json.
+
+Web interfaces
+Bundled UI and icon notices are in web/licenses/ and the corresponding
+licenses/ directory in each prebuilt interface. Other installed dependencies
+retain the licenses provided by their respective packages.

package/README.md

@@ -1,87 +1,108 @@
-# DSCord
+# DSCord 0.4.0-alpha.2 安装与连接
 
-人类与独立 Bot 共同参与的聊天协作框架，原项目名为 DS-Group。npm 包包含 Node 服务端、预构建 React PWA、Matrix 接入器、DSH 桥接和固定 DS-Bot 0.2.7。
+> [!WARNING]
+> **实验性项目。** DSCord 目前是实验性质的项目，接口、数据格式和行为随时可能变化，不保证兼容旧版本。项目不考虑安全问题，因此将别人加入到你的服务器当中的时候，请确认你有线下找他喝茶的能力。
 
-当前为 `0.2.0-alpha.1`，使用 `alpha` 标签发布。服务器发行目标为 Linux amd64/arm64，要求 Node 24.19.0 及以上的 24.x。Bot 节点另外需要 DSH 0.2.1-rc.5 和 `opencode-go/deepseek-v4.1-flash` 模型配置。
+DSCord 的 npm 包包含 Core、预构建网页/PWA、Matrix 适配器和 DSCord Bot 内核。完整服务器源码发行包另含 Compose 部署文件；同一部署的 Core、客户端和节点使用同一发行版本。
+
+本指南对应预发布版本 0.4.0-alpha.2，npm 安装包由该版本的 GitHub Release 提供。Node 支持范围由 [package.json](package.json) 声明为 `>=24.19.0 <25`。Bot 宿主固定使用 DSH `0.2.2-rc.1` 的 SDK 契约，见[内核说明](dsh-connect/KERNEL.md)。Docker 服务器无需在宿主另装 Node。
 
 ## 安装
 
+从发行页下载 `dscord-0.4.0-alpha.2.tgz` 后，可在 DSH 的 `Plugins → Add plugin` 中安装并启用 `dscord`，再登录服务器连接 Bot。发行页同时提供 `SHA256SUMS` 校验文件。[下载发行包](https://github.com/MixGeekers/dscord/releases/tag/ds-group-v0.4.0-alpha.2)
+
+全局安装 CLI 用于服务器与独立节点管理。npm 可以直接安装同一发行包，安装后核对 `dscord --version`。
+
 ```sh
-npm install --global dscord@alpha
+npm install --global https://github.com/MixGeekers/dscord/releases/download/ds-group-v0.4.0-alpha.2/dscord-0.4.0-alpha.2.tgz
 dscord --help
 dscord --version
 ```
 
-服务端与网页已经随包提供。运行时通过 `DS_GROUP_DATA_DIR` 指定数据目录，默认使用执行命令时所在目录下的 `.dscord`。在多个终端管理同一实例时，设置相同的绝对数据路径。`DS_GROUP_*` 是当前配置接口。
+Core、CLI 和 DSH 插件使用同一发行版本。已有全局安装可用上述命令升级。
 
-## 启动本机服务器
-
-以下步骤使用 Docker 运行独立 Synapse，核心通过 Node 启动。先安装 Docker Engine 并启动 Docker 服务。
+从源码构建 npm 包，在 `apps/ds-group/` 中执行：
 
 ```sh
-export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord"
-export DS_GROUP_SERVER_NAME=localhost
-export DS_GROUP_MATRIX_URL=http://127.0.0.1:18008
-export DS_GROUP_MATRIX_PUBLIC_URL=http://localhost:18008
-export DS_GROUP_PUBLIC_URL=http://localhost:18100
-dscord init
-
-docker run --detach --name dscord-synapse \
-  --user "$(id -u):$(id -g)" \
-  --publish 127.0.0.1:18008:8008 \
-  --mount "type=bind,source=$DS_GROUP_DATA_DIR/synapse,target=/data" \
-  ghcr.io/element-hq/synapse@sha256:f0df87cff259872637b4b5e5174b9977e5e3046dd421505407803b5e45c5f842
+npm ci --ignore-scripts
+npm run npm:pack
 ```
 
-等待 Synapse 的 `http://127.0.0.1:18008/_matrix/client/versions` 返回成功，再执行。
+该版本默认生成 `.local/npm-release/dscord-0.4.0-alpha.2.tgz`，仍应核对命令实际输出的版本、路径与校验值。构建需要开发依赖，运行已提供的预构建包不需要重新构建界面。
+
+## 部署服务器
+
+完整服务器采用[Compose 部署指南](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.2/apps/ds-group/deploy/README.md)，先配置自己的 Matrix 身份域、公开地址和持久存储。npm CLI 不代替 Synapse 或反向代理。需要 `dscord server`、初始化及节点导入等命令时，在各终端保持同一个绝对数据路径：
 
 ```sh
-dscord bootstrap
-dscord admin credentials alice
-dscord server
+export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-server"
+dscord --version
 ```
 
-浏览器访问 `http://localhost:18100`，使用上一步在管理员终端显示的 Alice 登录信息。初始化会创建 Alice、Bob、财务和人事四个独立成员。Bot 在各自节点接入后上线。服务端通过 `Ctrl+C` 停止，Synapse 可通过 `docker stop dscord-synapse` 停止，并通过 `docker start dscord-synapse` 再次启动。
+上面的路径可自行替换。npm CLI 未设置数据目录时使用当前工作目录下的 `.dscord/`，在不同目录执行管理命令可能选中不同实例。
+
+## 在 DSH 中连接
+
+1. 准备固定基线的官方 CLI，或提供相同 SDK 服务的 DSH 宿主。CLI 可执行 `npm install --global @deepseek-ai/dsh@0.2.2-rc.1`。在 DSH 中配置自己的业务模型和凭据。
+2. 安装同版本 `dscord` 插件并启用，打开左侧 **DSCord**，填写 Core/PWA 的地址和自己的账号，登录服务器。
+3. 在“此节点的 Bot”中创建 Bot，选择 DSH 已配置的模型并填写职责，或选择已有 Bot。纯读取状态不会自动创建 Bot。
+4. 点击“加入服务器”。网页“我的 Bot → 添加已有 Bot”也可选择这个已连接节点公布的 Bot。两端必须是同一账号。
+5. 在网页打开私聊或邀请 Bot 进入需要参与的群聊。参与方式、来源记忆和当前工作在 Bot 设置中查看。
 
-HTTPS、Docker Compose、备份恢复与 systemd 的完整部署流程见源码仓库中的部署指南。手机 PWA 安装和通知需要可信 HTTPS。[服务器部署指南](https://github.com/MixGeekers/ds_group/blob/main/apps/ds-group/deploy/README.md)
+地址、账号、模型和路径都来自部署者自己的配置。业务模型没有指定服务商；自然参与的单独判断服务是可选功能，见[模型与参与设置](模型配置与迁移.md)。
 
-## 连接 Bot 节点
+Core 提供的 Matrix 公开地址必须能从节点访问。一个连接页使用一个归属账号，可管理多个本机 Bot。连接数据默认位于实际 DSH home 的 `dscord/<profile>/`，Bot 数据保留在该 home 的 `bot/`。断开服务器、退出连接页或关闭网页不删除本机 Bot；DSH 停止后，Bot 也无法继续工作。
 
-先按服务器部署指南配置 HTTPS 反向代理，使核心 API 和 Matrix API 可从 Bot 机器访问。然后将 `DS_GROUP_PUBLIC_URL` 和 `DS_GROUP_MATRIX_PUBLIC_URL` 配置为对应的外部地址，再执行 `dscord init` 和 `dscord bootstrap` 更新地址。使用目标 Bot 的名称导出节点配置。
+## 升级和已有 Bot
+
+先备份服务器数据和各 DSH Bot home，再停止当前工作并升级到同一发行版本。已有 `ds-bot` 插件必须先停用，DSCord 才能在同一目录接管；同时启动两个内核会报冲突。接管会保存迁移快照，保留 Bot 与 Session 身份。[生命周期与迁移](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.2/apps/ds-group/deploy/kernel-runtime.md)
+
+旧服务器 Bot 可在连接页绑定已有本机 Bot，保留 Matrix 身份；两套独立 Session 或记忆不会自动合并。已有原生绑定的 Bot 应从所属 DSH 连接，导出其配置不能在另一台机器创建身份副本。
+
+## 独立 CLI 节点
+
+CLI 适用于没有已有原生绑定的独立 Bot。已绑定本机 Bot 的成员必须使用所属 DSH 的连接页，启动器会拒绝复制其身份。
+
+在服务器端导出目标 Bot，参数使用完整 Matrix ID 中 `@` 与 `:` 之间的账号部分，不是显示名称：
 
 ```sh
+BOT_ACCOUNT='your-bot-account'
 umask 077
-dscord admin export-node finance > finance-node.json
+dscord admin export-node "$BOT_ACCOUNT" > bot-node.json
 ```
 
-将配置文件传到 Bot 机器，在该机器安装 `dscord@alpha` 和 DSH，再执行。
+将私有导出文件传到节点，安装同版本程序和兼容 DSH。以下数据目录、空闲端口、来源 profile 和 `provider/model-id` 均须替换为自己的配置：
 
 ```sh
-npm install --global @deepseek-ai/dsh@0.2.1-rc.5
-export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-finance"
-dscord admin import-node finance-node.json "$DS_GROUP_DATA_DIR"
-read -r -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dscord service up finance
+BOT_ACCOUNT='your-bot-account'
+export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-nodes/$BOT_ACCOUNT"
+export DS_GROUP_BRIDGE_PORT=23100
+dscord admin import-node bot-node.json "$DS_GROUP_DATA_DIR"
+export DS_GROUP_DSH_SOURCE_HOME='/absolute/path/to/your/dsh-home'
+export DS_GROUP_DSH_SOURCE_PROFILE='your-profile'
+export DS_GROUP_MODEL='provider/model-id'
+dscord service up "$BOT_ACCOUNT"
 ```
 
-`OPENCODE_API_KEY` 在本地终端输入。人事节点使用 `hr` 及独立数据目录。使用以下命令停止财务节点及其 DSH。
+若 DSH 不在 PATH，用 `DS_GROUP_DSH_CLI` 指定可执行文件、`DS_GROUP_DSH_RUNTIME` 指定实际 SDK 包根或安装前缀。启动器按锁准备自己的运行依赖，不需要手工复制库目录。独立节点会复制所选模型配置所需的凭据到私有数据目录，行为与直接复用宿主的图形节点不同。[模型与凭据](模型配置与迁移.md)
+
+在同一组环境变量下停止：
 
 ```sh
-dscord service down finance
-dscord dsh stop finance
+dscord service down "$BOT_ACCOUNT"
+dscord dsh stop "$BOT_ACCOUNT"
 ```
 
-当前 npm 入口提供 CLI 部署。DSH 桌面“添加插件”中的直接安装与自动接入仍待实现。
+每个 Bot 同时运行一个节点，每个独立节点使用自己的数据目录和桥接端口。Linux 常驻服务见 [systemd](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.2/apps/ds-group/deploy/systemd/README.md)。
+
+## 存储与组件
+
+附件默认使用 Synapse 本地媒体目录，可选 S3-compatible 后端。[存储配置](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.2/apps/ds-group/deploy/storage/README.md)说明远端对象、缓存和备份关系；已有云盘扫描与历史迁移不是自动功能。
+
+`dscord server` 运行 Core/PWA，`init` 和 `bootstrap` 初始化服务器，`admin` 管理导出与导入，`node` 运行 Matrix 适配器，`dsh` 管理独立宿主，`service` 管理本机进程，`path` 显示安装目录。
 
-## 包内组件
+DS-Bot 的 Apache-2.0 LICENSE 与 NOTICE 位于 `vendor/ds-bot/`，界面图标许可随 `dist/web/licenses/` 提供。
 
-- `dscord server` 启动核心 API 和预构建 PWA。
-- `dscord init` 与 `dscord bootstrap` 管理服务器初始化和 Matrix 成员。
-- `dscord admin` 读取账号、导出和导入节点配置。
-- `dscord node` 运行 Matrix 适配进程。
-- `dscord dsh` 管理独立 DSH 运行时。
-- `dscord service` 管理本机核心和 Bot 进程。
-- `dscord path` 显示安装目录。
+## 许可证
 
-上游 DS-Bot 的 Apache-2.0 LICENSE 与 NOTICE 位于 `vendor/ds-bot/`。Lucide 的 ISC 与 Feather MIT 许可位于 `dist/web/licenses/lucide.txt`。
+DSCord 自有代码和文档采用 Apache-2.0。安装包包含本体许可及第三方声明，预构建界面的依赖许可位于各自的 `licenses/` 目录。[LICENSE](LICENSE) · [NOTICE](NOTICE)

package/bin/dscord.mjs

@@ -17,8 +17,8 @@ const entries = new Map([
 ]);
 const help = `Usage: dscord <command> [arguments]
 
-  server                 Run the core server and PWA
-  init                   Prepare server and Synapse configuration
+  server                 Run the core server in its configured web mode
+  init [--web-mode MODE]  Prepare configuration (MODE: bundled or api-only)
   bootstrap              Register initial members on the configured Synapse
   admin <arguments>      Manage server credentials and node exports
   node <arguments>       Run a Matrix Bot adapter
@@ -29,6 +29,7 @@ const help = `Usage: dscord <command> [arguments]
   help                   Show this help
 
 DS_GROUP_DATA_DIR defaults to .dscord in the current directory.
+DS_GROUP_WEB_MODE overrides web hosting; init persists it in core-config.json.
 `;
 
 async function run() {
@@ -48,10 +49,10 @@ async function run() {
   const entry = entries.get(command);
   if (!entry) throw new Error(`Unknown command "${command}". Run dscord help.`);
   if (command === 'service' && ['up', 'down', 'restart'].includes(args[0]) && !args[1]) {
-    throw new Error('Choose a service component explicitly: all, core, finance, or hr.');
+    throw new Error('Choose a service component explicitly: all, core, or a local Bot account name.');
   }
   if (command === 'dsh' && args.length < 2) {
-    throw new Error('Use dscord dsh <start|run|stop|status|prepare> <finance|hr>.');
+    throw new Error('Use dscord dsh <start|run|stop|status|prepare> <bot-account>.');
   }
 
   const env = { ...process.env };

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dscord-connect
+      name: dscord

package/deploy/synapse/dscord_guard.py

@@ -0,0 +1,212 @@
+"""DSCord private federation admission. Pinned and tested with Synapse 1.164.2.
+
+Policy is local authority, never instructions from room content. Each host enforces
+its own local users and rooms; remote message history is not rewritten by this module.
+"""
+import json
+import hashlib
+import os
+import time
+import uuid
+
+from synapse.module_api import NOT_SPAM
+from synapse.module_api.errors import Codes, SynapseError
+from twisted.web.resource import Resource
+
+
+def domain(user_id):
+    return user_id.split(":", 1)[1] if isinstance(user_id, str) and ":" in user_id else None
+
+
+def acl_host(server):
+    return server.split(":", 1)[0]
+
+
+class GovernanceStatus(Resource):
+    isLeaf = True
+
+    def __init__(self, guard):
+        super().__init__()
+        self.guard = guard
+
+    def render_GET(self, request):
+        self.guard.policy()
+        request.setHeader(b"Content-Type", b"application/json")
+        request.setHeader(b"Cache-Control", b"no-store")
+        if self.guard.document["error"]:
+            request.setResponseCode(503)
+        return json.dumps(self.guard.document).encode("utf-8")
+
+
+class GovernanceModule:
+    def __init__(self, config, api):
+        self.api = api
+        self.config = config
+        self.server = config["server_name"]
+        self.boot_id = str(uuid.uuid4())
+        with open(__file__, "rb") as stream:
+            self.source_hash = hashlib.sha256(stream.read()).hexdigest()
+        self.last_status = None
+        self.document = {}
+        api.register_spam_checker_callbacks(user_may_invite=self.may_invite, user_may_join_room=self.may_join)
+        api.register_third_party_rules_callbacks(check_event_allowed=self.check_event, on_create_room=self.on_create)
+        api.register_web_resource("/_synapse/client/dscord-governance/status", GovernanceStatus(self))
+        self.policy()
+
+    @staticmethod
+    def parse_config(config):
+        for key in ("server_name", "policy_path", "status_path"):
+            if not isinstance(config.get(key), str) or not config[key]:
+                raise ValueError("Missing DSCord guard " + key)
+        return config
+
+    def policy(self):
+        try:
+            with open(self.config["policy_path"], encoding="utf-8") as stream:
+                policy = json.load(stream)
+            if policy["schemaVersion"] != 1 or policy["serverName"] != self.server or not isinstance(policy["revision"], int):
+                raise ValueError("Invalid policy identity")
+            # Fail closed on missing or malformed configuration, including local operations.
+            for key in ("partners", "members", "rooms", "botPolicies"):
+                if not isinstance(policy[key], list):
+                    raise ValueError("Invalid policy collection")
+            revision = policy["revision"]
+            error = None
+        except (OSError, ValueError, KeyError, TypeError):
+            policy = None
+            revision = None
+            error = "POLICY_UNAVAILABLE"
+        status = (revision, error)
+        self.document = {"serverName": self.server, "bootId": self.boot_id, "synapseVersion": "1.164.2",
+                         "sourceSha256": self.source_hash,
+                         "liveRevision": revision, "loadedPartners": self.config.get("loaded_partners", []),
+                         "observedAt": int(time.time() * 1000), "error": error}
+        if status != self.last_status:
+            self.last_status = status
+            filename = self.config["status_path"]
+            temporary = filename + "." + str(os.getpid()) + ".tmp"
+            try:
+                with open(temporary, "w", encoding="utf-8") as stream:
+                    json.dump(self.document, stream)
+                os.chmod(temporary, 0o600)
+                os.replace(temporary, filename)
+            except OSError:
+                self.last_status = None
+        return policy
+
+    def partners(self, policy):
+        return [row["serverName"] for row in policy["partners"] if row.get("enabled") is True]
+
+    def admitted(self, policy, user):
+        return domain(user) == self.server or domain(user) in self.partners(policy) and any(
+            row["id"] == user and row.get("enabled") is True for row in policy["members"])
+
+    def rule(self, policy, room):
+        return next((row for row in policy["rooms"] if row["roomId"] == room), None)
+
+    def allowed(self, policy, room, user):
+        row = self.rule(policy, room)
+        return bool(row and row.get("enabled") is True and self.admitted(policy, user)
+                    and (user in row.get("memberIds", []) or domain(user) == self.server and row["authority"] == self.server))
+
+    async def may_invite(self, inviter, invitee, room_id):
+        policy = self.policy()
+        if not policy:
+            return Codes.FORBIDDEN
+        if domain(inviter) == self.server and domain(invitee) == self.server:
+            return NOT_SPAM
+        # Both participating servers approve the exact room and external identity.
+        if not self.admitted(policy, inviter) or not self.admitted(policy, invitee):
+            return Codes.FORBIDDEN
+        row = self.rule(policy, room_id)
+        if not row or not row.get("enabled"):
+            return Codes.FORBIDDEN
+        if row["authority"] == self.server:
+            return NOT_SPAM if self.allowed(policy, room_id, invitee) else Codes.FORBIDDEN
+        return NOT_SPAM if row["authority"] in self.partners(policy) and invitee in row.get("memberIds", []) else Codes.FORBIDDEN
+
+    async def may_join(self, user, room, is_invited):
+        policy = self.policy()
+        if not policy:
+            return Codes.FORBIDDEN
+        row = self.rule(policy, room)
+        if row:
+            return NOT_SPAM if self.allowed(policy, room, user) and (row["authority"] == self.server or is_invited) else Codes.FORBIDDEN
+        # Legacy local-only rooms retain their membership behavior. Foreign rooms
+        # need an explicit policy even when a user bypasses Core and calls /join.
+        state = await self.api.get_room_state(room, [("m.room.create", "")])
+        creator = state.get(("m.room.create", ""))
+        return NOT_SPAM if creator and domain(creator.sender) == self.server and domain(user) == self.server else Codes.FORBIDDEN
+
+    async def on_create(self, requester, request_content, is_requester_admin):
+        policy = self.policy()
+        if not policy:
+            raise SynapseError(403, "DSCord admission policy unavailable", Codes.FORBIDDEN)
+        for target in request_content.get("invite", []):
+            if domain(target) != self.server:
+                # Register the room rule first, then invite. There is no stable
+                # room ID before creation to which an external grant can bind.
+                raise SynapseError(403, "Create the room, approve its rule, then invite external members", Codes.FORBIDDEN)
+        states = [row for row in request_content.get("initial_state", []) if row.get("type") not in ("m.room.server_acl", "m.room.join_rules")]
+        states.extend([{"type": "m.room.server_acl", "state_key": "", "content": {
+            "allow": sorted({acl_host(self.server), self.server}), "deny": [], "allow_ip_literals": False}},
+            {"type": "m.room.join_rules", "state_key": "", "content": {"join_rule": "invite"}}])
+        request_content["initial_state"] = states
+        request_content["visibility"] = "private"
+
+    async def check_event(self, event, state_events):
+        policy = self.policy()
+        # Incoming federated history is governed by Matrix auth; rejecting its
+        # messages here would create divergent room DAGs. Revoke through bans.
+        if domain(event.sender) != self.server:
+            if event.type == "m.room.member" and event.content.get("membership") in ("invite", "join"):
+                creator = state_events.get(("m.room.create", ""))
+                row = self.rule(policy, event.room_id) if policy else None
+                local_authority = row["authority"] == self.server if row else creator and domain(creator.sender) == self.server
+                if local_authority:
+                    return bool(policy and self.allowed(policy, event.room_id, event.state_key)), None
+            return True, None
+        if not policy:
+            return False, None
+        row = self.rule(policy, event.room_id)
+        creator = state_events.get(("m.room.create", ""))
+        local_room = row["authority"] == self.server if row else not creator or domain(creator.sender) == self.server
+        if not local_room and event.type not in ("m.room.member", "m.room.server_acl", "m.room.join_rules", "org.dscord.work_policy"):
+            return bool(row and self.allowed(policy, event.room_id, event.sender)), None
+        if event.type == "m.room.member":
+            membership = event.content.get("membership")
+            if membership in ("leave", "ban"):
+                return True, None
+            if domain(event.state_key) != self.server:
+                return self.allowed(policy, event.room_id, event.state_key), None
+            if not local_room:
+                return self.allowed(policy, event.room_id, event.state_key), None
+        if event.type == "m.room.join_rules":
+            return event.content.get("join_rule") == "invite", None
+        if event.type == "m.room.server_acl":
+            # Host patterns enforce the specification. The full local name also
+            # satisfies Synapse 1.164.2's validator, which checks the port-bearing
+            # local server name without stripping its port.
+            permitted = {acl_host(self.server), self.server}
+            if row and row.get("enabled"):
+                if row["authority"] == self.server or row["authority"] in self.partners(policy):
+                    permitted.add(acl_host(row["authority"]))
+                    permitted.add(row["authority"])
+                for user in row["memberIds"]:
+                    if self.admitted(policy, user):
+                        permitted.update({acl_host(domain(user)), domain(user)})
+            allow = event.content.get("allow", [])
+            return bool(allow and set(allow).issubset(permitted) and event.content.get("allow_ip_literals") is False), None
+        if event.type == "org.dscord.work_policy":
+            if not local_room:
+                return False, None
+            expected = {"schemaVersion": 1, "roomId": event.room_id,
+                        "revision": policy["revision"], "authority": self.server,
+                        "issuerId": "@dscord-control:" + self.server,
+                        "localMemberAdmission": "matrix-membership",
+                        "enabled": bool(row and row.get("enabled")),
+                        "botIds": [user for user in row.get("botIds", []) if self.admitted(policy, user)] if row else [],
+                        "tools": row.get("tools", []) if row else [],
+                        "memberIds": [user for user in row.get("memberIds", []) if self.admitted(policy, user)] if row else []}
+            return event.sender == expected["issuerId"] and event.content == expected, None
+        return True, None