buckyos 0.7.5-99 → 0.7.114

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BuckyOS Core Dev Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# BuckyOS SDK 与 Tool
+
+`buckyos` npm 包同时提供 browser/node/provision SDK 和项目本地 CLI。App 开发者只需项目已有的
+Node.js，不需要安装 Deno，也不需要 checkout BuckyOS 或本仓库：
+
+```bash
+npm install buckyos
+npx buckyos --version
+npx buckyos pikg init . --owner did:bns:alice --kind static-web --source ./dist
+npm run build
+npx buckyos pikg build ./dapp_meta
+npx buckyos pikg pack ./dapp_dist
+npx buckyos pikg info ./dapp_dist/example-0.1.0.pikg
+npx buckyos app install ./dapp_dist/example-0.1.0.pikg --policy local-developer
+npx buckyos task wait <task-id>
+npx buckyos app status example
+npx buckyos log tail --app example
+```
+
+`npx buckyos` 和 npm scripts 中的 `buckyos` 固定使用项目 lockfile 对应的 Tool。PATH 中裸 `buckyos`
+由 BuckyOS 系统安装器管理并指向 `$BUCKYOS_ROOT/bin/buckyos`；文档不推荐全局
+`npm install -g buckyos`。两种分发运行同一套命令实现，互不覆盖、互不调用、也不会自更新。
+
+遇到本地构建或目标配置问题，先运行 `npx buckyos pikg doctor`。`--version --verbose` 会打印 实际
+executable、Node/Deno host、distribution、Tool/SDK/协议版本和本地 policy。
+
+## 身份验证
+
+然后在浏览器中允许的,属于dApp的页面，都应使用BuckyOS SDK提供的登陆功能来获得一个有效身份。
+身份验证流程如下：
+
+路径1：1.浏览器发送请求 --HTTPs--> 2.cyfs-gateway进行验证 --Local HTTP--> 3.dApp Server使用BuckyOS
+Rust SDK进行验证。 路径2：1. App -->http@bdt--> 2.cyfs-gateway进行验证 -- Local HTTP--> 3.dApp
+Server使用BuckyOS Rust SDK进行验证。 **路径2 依赖有客户端身份的App/CYFS 浏览器，暂未实现**
+路径3：1.App Service --RPC@http--> 2. system_service(验证rpc.token,系统调用验证，不走cyfs-gateway)
+
+### cyfs-gateway的验证
+
+cyfs-gateway会根据HTTP Request的Host字段和cookie中的buckyos_token字段来进行验证。
+该buckyos_token通常是有相对较长有效期的普通权限jwt.
+对POST请求，验证首先要得到jwt格式的rpc.token，然后进一步验证该rpc请求是否有正确的授权。涉及到敏感操作的rpc.jwt通常是短期的，甚至是一次性的,并有sudo级别权限。
+
+验证方根据buckyos_token /
+rpc_token得到appid,userid,resource,OP组成四元组，到RBAC库中查询对应权限，并进行验证。
+RBCL需要的四元组:
+
+```
+appid,来自http request的host字段,web sdk里不可设置
+userid:必填
+resource:来自http request的path字段.完整写法是app://appid/http_path/，各种系统调用都有自己构造path的方法，与参数有关。jwt中通常不包resource信息，除非特别敏感的一次性sudo操作
+OP: 来自http request的method字段 (GET/POST/PUT/DELETE/...),jwt中是可以包含的。
+```
+
+cyfs-gateway会根据这四元组，到RBAC库中查询对应权限，并进行验证。其验证方法是先判断appid是否有权限，再判断userid是否有权限。任何一个不通过，都会返回权限不足。
+
+cyfs-gateway对于需要http验证的请求，如果没有buckyos_token字段，会重定向到一个预设的访问登陆页，引导用户登陆成功后，再重定向回原URL。该登陆页面通常是支持guest访问的。
+
+### buckyos_token字段的生成
+
+```javascript
+// at feedlist.excample.com
+await buckyos.loginByBrowserSSO()
+// 当前窗口会跳转到 sys.$zoneid/sso/login
+// SSO 成功并跳回当前页后，再读取当前账号状态
+let user_info = await buckyos.getAccountInfo()
+let bucky_token = user_info?.session_token
+let user_id = user_info?.user_id
+let rpc_client = new buckyos.kRPCClient(feedlist_api_url, bucky_token)
+let user_feeds = rpc_client.get_user_feeds(user_id)
+```
+
+执行高权限操作
+
+```javascript
+on_click_change_password(){
+    let new_password = get_new_password();
+    let bucky_token =await buckyos.authClient.request("change password");
+    let rpc_client = new buckyos.kRPCClient(account_api_url,bucky_token);
+    //高权限操作的所有参数都在bucky_token的payload中
+    rpc_client.change_password(bucky_token);
+}
+```
+
+下面是feedlist_api的实现
+
+```javascript
+on_request(request,response){
+    let user_id = request.params.user_id
+    let token = request.bucky_token;
+    payload = verify_token(token,verify_hub.public_key);
+    if payload.userid != user_id {
+        response.send(403,"permission denied");
+    }
+
+    if payload.appid != "feedlist" {
+        response.send(403,"permission denied");
+    }
+
+    
+    response.send(user_feeds);
+}
+```
+
+### buckyos.authClient的实现
+
+authClient主要靠系统的内置verify_hub服务来完成功能，其基本逻辑是
+
+1. 在当前窗口直接跳转到标准的 `sys.$zoneid/sso/login` 页面，该页面会根据 login 时的参数调整一些行为
+2. 用户在跳转后的页面中完成登录，有2种方法 a.
+   使用用户名密码向verify_hub发起请求，verify_hub会根据其掌握的账号信息返回必要的jwt验证信息 b.
+   要求用户输入一个加密后的私钥，当用户输入正确的解密密码后，可以用该私钥来构造jwt
+
+### bucky_token jwt payload的内容
+
+签名都是verify_hub服务完成的
+
+```
+{
+    "appid": "$appid",
+    "userid": "$did",
+    "key":"$aes_key", 用verify_hub的公钥加密的aes key，也用来做session key
+    "iss": "verify_hub", 或 "$did",使用用户的私钥来构造jwt时，会使用用户的sudo权限
+    "exp": "$exp"
+}
+```
+
+### 防御jwt的重放攻击
+
+因为会工作在http环境，因此会用明文发送jwt.
+
+## namelib 与 provision（身份文档构造）
+
+SDK 自带 Rust `name-lib` 的 TS 镜像（`namelib`，universal 导出），以及 `buckycli` 构造侧命令的 TS
+镜像（`buckyos/provision`，**node-only**，要求 Node >= 22.13 或 Deno >= 2.2，依赖
+`node:sqlite`）。格式与 Rust 端逐字节对齐 （Ed25519 PKCS8 PEM / JWK / EdDSA JWT），由 golden fixture
+单测保障 （`tests/fixtures/provision/`）。
+
+### Quickstart：keygen → createUserEnv → createNodeConfigs
+
+```ts
+import { namelib } from 'buckyos'
+import { createNodeConfigs, createSnConfigs, createUserEnv } from 'buckyos/provision'
+
+// 1. 生成 Ed25519 身份密钥（私钥 PKCS8 PEM + 公钥 JWK）
+const { privateKeyPem, publicKeyJwk } = await namelib.generateEd25519KeyPair()
+
+// 2. 构造用户/zone 环境（user_config.json、zone_config.json、zone TXT record 等）
+await createUserEnv({
+  username: 'alice',
+  hostname: 'alice.bns.did',
+  oodName: 'ood1',
+  snBaseHost: 'devtests.org',
+  outputDir: '/tmp/alice-env',
+})
+
+// 3. 构造节点身份（node_identity.json、device_mini_config.jwt、start_config.json）
+await createNodeConfigs({ deviceName: 'ood1', envDir: '/tmp/alice-env' })
+```
+
+其它能力：`createSnConfigs` / `registerUserToSn` / `registerDeviceToSn`（SN 侧）、 `setPkgMeta` /
+`MetaIndexDb`（pkg meta 索引库）、`buildDidDocs`（内核服务 did docs）、 `createCa` /
+`createCertFromCa`（旧 CertManager 兼容 TLS 证书），以及 `IdentityRoots` /
+`createIdentityCertFromCa`（按 identity path 协议写入
+`$BUCKYOS_IDENTITY_ROOT/{encoded raw host URI}/server.*` 和
+`$BUCKYOS_SECURITY_ROOT/{encoded raw host URI}/server.private.pem`；现阶段不生成
+`server.keyref.json`）。
+
+注意：`buckyos/provision` 导出的 `DEV_TEST_KEYS` / dev EVM account helper 是**仅供本地开发**
+的公开测试密钥，使用固定 dev 助记词按 Rust `name-lib` 的 mnemonic 派生规则构造，严禁用于
+真实激活流程；浏览器 bundle 不包含 provision。
+
+## 构建与发布
+
+### 本地构建
+
+构建项目并生成类型定义文件：
+
+```bash
+# 使用 pnpm（推荐）
+pnpm run build:all
+
+# 或使用 npm
+npm run build:all
+```
+
+该命令会执行以下操作：
+
+1. 运行 `vite build` 构建项目，生成 `dist/index.*`、`dist/browser.*`、`dist/node.*`
+2. 运行 `tsc -p tsconfig.build.json` 生成对应的 TypeScript 类型定义文件
+3. 生成与 package version 一致的 Tool 版本文件，并构建 Node CLI bundle
+
+构建产物位于 `dist/` 目录。
+
+### AppClient Demo
+
+仓库里带了一个最小可运行的 AppClient 示例：`examples/app_client_demo.ts`。
+
+它会：
+
+1. 使用本机私钥目录初始化 `AppClient`
+2. 向真实运行中的 `system_config` 读取 `boot/config`
+3. 打印当前 `session_token` 的 claims 和 `boot/config` 的顶层 key
+
+运行方式：
+
+```bash
+pnpm run demo:app-client
+```
+
+可选环境变量：
+
+```bash
+BUCKYOS_TEST_APP_ID=buckycli
+BUCKYOS_SYSTEM_CONFIG_URL=http://127.0.0.1:3200/kapi/system_config
+```
+
+如果你是在已发布的 SDK 包里使用，同样的示例代码应从 `buckyos/node` 导入，而不是仓库内的相对路径。
+
+### 发布到 GitHub
+
+#### 1. 更新版本号
+
+在 `package.json` 中更新版本号：
+
+```bash
+# 使用 npm version 自动更新版本号并创建 git tag
+npm version patch  # 1.0.0 -> 1.0.1
+npm version minor  # 1.0.0 -> 1.1.0
+npm version major  # 1.0.0 -> 2.0.0
+```
+
+#### 2. 构建项目
+
+确保构建产物是最新的：
+
+```bash
+pnpm run build:all
+```
+
+#### 3. 提交并推送
+
+```bash
+# 提交更改
+git add .
+git commit -m "chore: release v1.0.1"
+
+# 推送代码和标签到 GitHub
+git push
+git push --tags
+```
+
+#### 4. 创建 GitHub Release（可选）
+
+1. 访问 GitHub 仓库页面
+2. 点击 "Releases" -> "Create a new release"
+3. 选择刚才推送的 tag
+4. 填写 Release 标题和描述
+5. 上传构建产物（`dist/` 目录下的文件）作为附件（可选）
+
+### 发布到 npm
+
+发布工作流使用 npm Trusted Publishing/provenance、最小权限和 npm 账号 2FA。首次包含 Tool 的
+版本只能进入 `next`/`beta`，不得直接覆盖 `latest`：
+
+```bash
+pnpm run build
+pnpm run check:cli
+pnpm run test:cli
+pnpm run test:cli-conformance
+pnpm run test:tarball
+pnpm run test:release-manifest
+npm publish --tag next --provenance
+```
+
+系统打包必须固定这次 CI 生成的原始 npm tarball、CycloneDX SBOM、release manifest 和 Deno
+digest，不得重新 checkout 或重建。真实 App/DV、系统离线安装、升级和回滚验收通过后，只移动 dist-tag：
+
+```bash
+npm dist-tag add buckyos@<已验证版本> latest
+```
+
+回滚 dist-tag 不会改变已经安装的 BuckyOS system Tool；系统 Tool 只随 installer/updater 事务
+更新或回滚。

package/cli/README.md

@@ -0,0 +1,73 @@
+# BuckyOS Tool internals
+
+This directory is the single source for the `buckyos` command shipped in the npm `buckyos` package
+and in BuckyOS system images. CLI modules are internal implementation details; the package's public
+JavaScript exports remain the SDK exports declared in `package.json`.
+
+## Two distributions, one command registry
+
+- `cli/launcher.mjs` starts the prebuilt `cli/dist/cli.mjs` on Node for `npx buckyos`. The developer
+  package contains no second runtime.
+- `cli/system_bootstrap.ts` starts `cli/system_launcher.ts` with the Deno binary bundled in
+  `$BUCKYOS_ROOT/libexec/buckyos-tool/runtime/`. The bootstrap derives Deno permissions from the
+  same system policy enforced by the host.
+- `main.ts`, `core/`, and `modules/` depend only on the typed host in `runtime/host.ts`. Runtime
+  APIs are confined to `host_node.ts` and `host_deno.ts`; the boundary check blocks regressions.
+
+Neither distribution discovers, invokes, overwrites, or updates the other. Use
+`buckyos --version --verbose` or `buckyos pikg doctor` to see the selected executable, host,
+distribution, policy, artifact versions, target and identity candidate order.
+
+## Local development
+
+Build the Node CLI before using its launcher:
+
+```bash
+pnpm run build
+node cli/launcher.mjs --version
+node cli/launcher.mjs command describe pikg build
+```
+
+The PIKG-first App workflow is:
+
+```bash
+node cli/launcher.mjs --non-interactive pikg init . \
+  --owner did:bns:root --kind static-web --source ./web/dist
+node cli/launcher.mjs pikg build ./dapp_meta
+node cli/launcher.mjs pikg pack ./dapp_dist
+node cli/launcher.mjs pikg info ./dapp_dist/example-0.1.0.pikg
+node cli/launcher.mjs --non-interactive --yes pikg clean ./dapp_meta
+```
+
+`pikg` consumes existing build output; it does not replace an App's Vite, Webpack, Cargo, or Docker
+build scripts. Set `SOURCE_DATE_EPOCH` for byte-reproducible Node/Deno PIKG builds.
+
+## Policy and identity
+
+The developer policy grants the package root, cwd, Tool config, and explicit input/output paths. It
+does not include `$BUCKYOS_ROOT` or scan system credentials. The system policy additionally grants
+its paired BuckyOS root. Both policies constrain environment names and subprocesses; only PIKG
+Docker inputs may invoke `docker`.
+
+An explicitly selected identity is tried once. Without an explicit identity, readable candidate
+roots are scanned in the frozen source order `explicit`, `tool`, `environment`, `buckyos-root`, with
+directories sorted and a maximum of eight usable candidates. Rotation occurs only during session
+creation and only for `IDENTITY_KIND_NOT_ACCEPTED` or `AUTHENTICATION_REJECTED`; timeouts, network
+errors, capability mismatches and RBAC denial never rotate. Private keys and tokens are never shown.
+
+## Verification
+
+```bash
+pnpm run check:cli
+pnpm run test:cli
+pnpm run test:cli-conformance
+pnpm run test:tarball
+pnpm run test:release-manifest
+```
+
+The conformance test executes registry/error cases and a complete PIKG lifecycle under both hosts,
+then compares normalized stdout/stderr, exit codes and every generated file digest. The tarball test
+installs the real package with npm and pnpm in paths containing spaces and non-ASCII characters and
+runs the developer workflow with Node only. The release-manifest smoke also creates a deterministic
+CycloneDX SBOM containing the production dependency graph, npm tarball hashes, lockfile hash, and
+the pinned system Deno version and digest.