Repository navigation
Commit 58f66b9
feat(cloud-connection,plugin-audit): forward the install mode and the installer; an unmanaged grant is copied and audited by the environment (#31475)
domain:server#3 · os-project-manager · session_01FEkQ5pXkgNXVpCn2GZDjyy
Body: seat refresh (round 1) · 2026-11-08T11:19Z
Fixes #30964
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XJZfATGni9GCmv2TJRug9bZ)_
Clause-②: yes (widening) — `POST /api/v1/cloud-connection/install`
accepts `install_mode` (or `installMode`) and sends
`sys_package.install_package` the body params `install_mode` and
`installer_user_id`; on an unmanaged grant it answers the install-local
door's answer; the install-local plugin registers the in-process
`marketplace-install-local` service; `sys_audit_log.action` gains
`package_unmanaged_import`, which plugin-audit's package lifecycle
writer accepts; `@objectstack/plugin-audit` newly exports
`PACKAGE_UNMANAGED_IMPORT_AUDIT_ACTION`, `PackageUninstallAuditEvent`
and `PackageUnmanagedImportAuditEvent`, `PackageLifecycleAuditEvent` is
now their union (narrow it on `action`), and
`PackageLifecycleAuditAction` gains `package_unmanaged_import`. No spec
schema changes
Metadata-protocol: none
## 维护者速读
1. 云端托管环境的安装入口 `POST /cloud-connection/install` 现在会把安装模式
`install_mode`(不传即托管)和安装人 `installer_user_id` 以 body
参数转发给控制平面;安装人取自本入口已认证的会话,不取请求体里的值,也不用请求头。
2. 控制平面批准非托管安装后,由环境自己的 install-local
入口完成复制:以调用者本人的请求头、批准的版本进行,install-local
的全部关卡照常生效(安装权限、协议握手、命名空间占用、副本记录、示例数据归安装人);默认不加载示例数据,调用者要求时才加载。
3. 跨仓库假设,未实测:控制平面批准非托管时跳过自身安装,并在应答中回显 `install_mode: 'unmanaged'` 和
`version_id`。若应答不回显模式或缺少版本号,返回 502,不复制任何内容;应答里完全没有 `install_mode` 时,502
还会提示:不读取该参数的控制平面可能已按托管方式安装,重试前先查看已安装列表。应答里即使带 `data.manifest` 也不读取。cloud
仓库本会话无权读取。另一项未实测的假设:托管环境的内核是否挂载了 install-local 插件。本仓库的托管 Console 认为云端
base 没有 install-local 入口(30963 changeset);未挂载时返回 503,不复制(#31482)。
4. `target_namespace` 暂不转发给控制平面(不确定其 action 是否拒绝未知参数),后续见 #31482。
5. 环境侧审计:每次非托管复制(无论成败)都在 `sys_audit_log` 写一条 `package_unmanaged_import`
行,记录源包与版本、新 base、命名空间、复制条数、成功或失败(失败时记错误码和 HTTP 状态,不记消息);审计服务异常不改变安装应答。
6. 无 spec 改动;`sys_audit_log.action` 新增选项,标签由 `os i18n extract`
生成(各语言暂为英文回填);#30512(ru)后合并者需重新执行提取。
## What changes
**The install mode, forwarded (`@objectstack/cloud-connection`, `POST
/api/v1/cloud-connection/install`).** The door reads `install_mode`, the
control plane's spelling, or `installMode`, the install-local door's
spelling, and parses it against `InstallModeSchema` by reference. A
value the schema refuses, or the two spellings naming different modes,
answers 400 `INVALID_REQUEST` before the control plane is called. When
the caller names a mode, it is sent as the action's `install_mode` body
param, the name the cloud half asked for (comment 6696363641). When the
caller names none, nothing is sent, and the control plane reads that as
`managed`, so a managed install's request differs from today's only by
the installer below.
**The installing user, forwarded.** Every install sends
`installer_user_id` as a body param on the same `install_package`
action, never as a header, because cloud#2245 removed `x-actor-id` as an
authorization input. The value is the id of the session this door
admitted. A value in the request body is never read. How the control
plane bounds the assertion (triage's question) is the cloud half's: per
comment 6696363641 it reads the id only when the user is a member of the
environment's organization, and otherwise records its service principal
and logs the unverified claim. This PR does not change that bound.
**An unmanaged grant is copied by the environment (Ask 3).** On an
unmanaged grant, the door hands the copy to the environment's own
install-local door. It sends `installMode: 'unmanaged'`, the granted
`version_id`, `seedSampleData` only when the caller asked for it, and
the caller's own headers, so the door admits and gates the same person.
The answer is that door's answer, status included. The copy is not
re-implemented here. It keeps every gate `POST
/api/v1/marketplace/install-local` applies: the installer's install
capability (`manage_metadata`), the protocol handshake, the namespace
holds, the #30808 copy record, and sample rows owned by the installer.
By default it loads no sample data, matching the framework default (Ask
3's "framework parity").
- In a multi-tenant deployment the door is read from the environment's
own kernel (`kernel-manager`). In a single-environment deployment it is
read from the host kernel. That a hosted environment's kernel mounts the
install-local plugin at all is NOT MEASURED (see below, #31482).
- A grant the door cannot read answers 502 `PLUGIN_INSTALL_FAILED` and
copies nothing. That covers an answer that does not echo `install_mode:
'unmanaged'` and one with no `version_id`. A `data.manifest` in the
answer is never read. When the answer has no `install_mode` at all, the
502 and its warn line add: "The control plane did not echo install_mode;
a control plane that does not read it may have installed the package
managed. Check Installed before retrying." An echoed different mode, or
an echoed `unmanaged` with no `version_id`, keeps the plain 502.
- An environment without the install-local plugin answers 503
`SERVICE_UNAVAILABLE` and copies nothing.
- A control-plane refusal, and every managed install, is answered
exactly as before.
**The in-process install door.** The install-local plugin registers the
`marketplace-install-local` service at `init` and declares it in
`providesServices`. Its `install(request)` takes a Fetch `Request` and
runs the same `handleInstall` the `POST` route mounts. It answers that
route's `Response`. `routeContextOf` is the slice of a route context the
handler reads: one cached read of the body, `header`, `raw`, `url`, and
`json` for the answer. The seat approved this registration line in the
claim amendment.
**The environment's audit row (Ask 4, `@objectstack/plugin-audit`).**
The install-local door's unmanaged branch (`installUnmanaged`) hands the
`audit` slot one `package_unmanaged_import` event per copy it attempted,
whether it landed or not. Both doors that reach the branch do this. The
event is declared structurally in cloud-connection, as metadata-protocol
declares its uninstall event, so cloud-connection does not depend on
plugin-audit.
plugin-audit's package lifecycle writer stores the event as a
deployment-level `sys_audit_log` row: no record and no organization,
like `package_uninstall`. Its `metadata` holds:
- `package_id` and `version`;
- `environment_id`, which is null because the door does not know it;
- `target_package_id`, `namespace` and `source_namespace`;
- `copied_count`;
- `outcome`, which is `success` or `failure`. A failure adds
`error_code` and `status`, never the message, because a refusal message
can quote package content.
The ledger's `action` select gains the value writer-first, as
`package_uninstall` did in #31186. The enum test and the writer
inventory each name its writer. Its labels were regenerated with `os
i18n extract` (the command in the plugin's
`scripts/i18n-extract.config.ts`). Every locale is filled from English,
with a source-hash record, until a translator replaces it. An audit slot
that throws changes no answer; the failure is logged at `error`.
## Cross-repo, NOT MEASURED
The grant's shape is assumed, not measured. The cloud half is cloud PR
#3683, and neither this session nor the seat could read
objectstack-ai/cloud. The assumption, ruled by the seat: on an unmanaged
grant the control plane skips its own install and answers
`data.install_mode: 'unmanaged'` with the granted `data.version_id` (and
`data.version`). The environment then fetches that version's manifest
itself, through the install-local cloud branch's existing
`/api/v1/marketplace/packages/:id/versions/:versionId/manifest` fetch.
The door fails closed when the answer is not that shape. The
control-plane double in `cloud-connection-plugin.test.ts` pins this
shape and names it as assumed.
Also not measured: that a hosted environment's kernel mounts the
install-local plugin at all. Nothing in this repo shows it, and this
repo's own hosted Console reads a cloud base as having no install-local
door (the 30963 changeset, `MarketplacePage`). Where the door is not
mounted, an unmanaged grant copies nothing and answers 503
`SERVICE_UNAVAILABLE`, naming the missing plugin. The
`install-local-door-service.ts` docblock states the same. Follow-up:
#31482.
`target_namespace` is held back. Ask 1 forwards the namespace "once
#30794 lands", and it has landed. Whether cloud's action rejects an
unknown body param with 400 is not known here, so this PR does not send
one. Follow-up: #31482. The install-local door already accepts
`targetNamespace` on an unmanaged copy, but this door does not pass one
to it yet either.
## Tests
- `packages/cloud-connection/src/cloud-connection-plugin.test.ts`, 3
forwarding cases and 9 unmanaged-grant cases:
- The managed request now carries `installer_user_id`, and no
`install_mode` when none was named.
- Both body spellings send `install_mode: 'unmanaged'`, and `'managed'`
is sent when named.
- `installer_user_id` is the session's user even when the body names
another.
- `'copy'`, `true`, or two disagreeing spellings answer 400 with no
control-plane call.
- The granted version is copied through the door as the caller: the
cookie is forwarded, no `Authorization` is added, and the body is
exactly `{ packageId, versionId, installMode }`.
- `seed_sample_data: true` asks the door for `seedSampleData: true`.
- A door refusal is the answer, status and all.
- In single-environment mode the door is the host's.
- Five unreadable grants answer 502 and the door is never called; one of
them carries a manifest.
- An answer with no `install_mode` at all (absent, null, or no data)
adds the "may have installed the package managed" sentence to the 502
and the warn line; an echoed `managed`, or `unmanaged` with a missing or
blank `version_id`, does not.
- A control-plane 403 is relayed and the door is never called.
- A managed install never reaches the door.
- No door answers 503.
-
`packages/cloud-connection/src/marketplace-install-local-install-modes.test.ts`,
5 cases on the #30808 harness, now with `init` called and an `audit`
slot:
- A landed copy hands one success event naming the new base, namespace
and count.
- A re-run's 409 hands one failure event with `RESOURCE_CONFLICT` and
409.
- A throwing slot changes no answer and logs one `error` line.
- The in-process door makes the same copy, sample rows included, and
refuses a malformed JSON body with 400.
- The in-process door refuses a caller without the install capability
(`manage_metadata`) with 403 `FORBIDDEN`, as the route does: no import
call and no audit event.
- `packages/plugins/plugin-audit/src/package-lifecycle-audit.test.ts`, 2
cases on the real `audit` slot (`ObjectQLPlugin` + `AuditPlugin` on
sqlite), each read back: the success row's columns and exact `metadata`,
and the failure row's `metadata` with its absences as null.
- `sys-audit-log-action-labels.test.ts`,
`sys-audit-log-retired-actions.test.ts` (the writer inventory) and
`audit-log-deployment-level-rows.integration.test.ts` name the new
value.
## Acceptance notes
- **Who gates the copy.** `POST /cloud-connection/install` admits any
signed-in environment session. The copy additionally needs the install
capability (`manage_metadata`), because it runs through that door. A
caller without it gets the door's 403 after the control plane has
already recorded its grant. Nothing is copied, and the environment's
audit has no row: the door refused before the import ran, and only an
attempted copy is recorded. Follow-up: #31481.
- **What the environment row does not hold.** The environment id is
null, because the install-local door has no reading of it; the row lives
in that environment's own ledger. The new label reads English in every
locale until it is translated.
- **Sibling.** #30512 (ru) adds an ru bundle in the same translations
directory. Whichever lands second merges origin/main and re-runs the
extraction.
## Verification
Head `6a9ae1bd` (review round 1 on top of `359ed69a`), origin/main
merged at `c0dc4059`.
- **Round 1 (`6a9ae1bd`).** Three new ablations, each red: `unechoed`
forced `false` (the absent-echo case loses its sentence), `unechoed`
forced `true` (the echoed-mismatch case gains it), and the
install-capability check forced off (the in-process door answers 200
instead of 403). The cloud-connection suite then passed 75 files, 1011
tests. Typecheck (including the test layer) and lint passed. The 75
derived dispatch gates were re-run, all exit 0, and `--ran` reports
75/75 with a derived zero.
- **Red on main first.** With the production files restored to base
`1ff99441`, the new file removed and the new tests kept:
- `cloud-connection-plugin.test.ts` and
`marketplace-install-local-install-modes.test.ts`: 14 failed, 69 passed.
For example: `expected { recordId: 'pkg_1', params: { …(2) } } to deeply
equal { recordId: 'pkg_1', params: { …(4) } }`,
`{"package_id":"pkg_1","install_mode":"copy"}: expected 200 to be 400`,
`{"version_id":"ver_9"}: expected 200 to be 502`, `expected undefined to
deeply equal { packageId: 'pkg_1', …(3) }`, and `expected [] to deeply
equal [ { …(8) } ]` (no audit event).
- The plugin-audit files: 4 failed, 34 passed. For example: `expected [
'create', 'read', 'update', …(11) ] to deeply equal [ …(12) ]`, the
writer-inventory refusal "sys_audit_log.action and the writer inventory
in this file disagree", and the two row cases (no row was written).
- Then green on head.
- **Ablations** (`scripts/ablation-replace.mjs`; each mutation landed,
was run, and the tree was restored to HEAD; each red):
- the echo check → `const unread = false`: the fail-closed pin is red;
- the version check → `: false ? …`: the fail-closed pin is red;
- the enum refusal → `if (false)`: the 400 pin is red;
- the disagreeing-spellings refusal → `if (false)`: the 400 pin is red;
- the installer → `body?.installer_user_id ?? session.userId`: the
installer pin is red;
- the refusal relay → `if (installMode !== 'unmanaged')`: the
control-plane refusal pin is red, because the door was called;
- the missing-door answer → `if (false)`: the 503 pin is red;
- the failure event's outcome → `'success'`: the failure-event pin is
red;
- the writer's acceptance of the new action → removed: both plugin-audit
row pins are red.
- **Package suites** (under the verify lock): cloud-connection 75 files,
1009 passed; plugin-audit 79 files, 1222 passed. `pnpm --filter
@objectstack/plugin-audit --filter @objectstack/cloud-connection run
typecheck` exit 0, including each test layer. `pnpm lint
packages/cloud-connection packages/plugins/plugin-audit` exit 0.
- **Dispatch gates:** `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` derived 75 commands. Each was run
with its exit captured before any pipe and recorded as `<command> ::
exit N`; `--ran` reports `75 derived famil(ies) accounted for — 75 run,
0 NOT-MEASURED (a DERIVED zero — all 75 recorded an exit code and none
of them is 3)`. The first pass found `check:slot-lookup` red:
`cloud-connection-plugin.ts: erasure count grew 5 → 6`, from the new
`getService<any>('kernel-manager')` read. It was fixed in `359ed69a` by
typing the read with its one member, then exit 0. The other 74 exited 0
on the first pass.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5pQJCx8STEq28nr3Ej)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 7d0b47c commit 58f66b9
35 files changed
Lines changed: 915 additions & 33 deletions
File tree
- .changeset
- packages
- cloud-connection/src
- plugins/plugin-audit/src
- objects
- translations
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
185 | 185 | | |
186 | 186 | | |
187 | 187 | | |
188 | | - | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
189 | 192 | | |
190 | 193 | | |
191 | 194 | | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
192 | 244 | | |
193 | 245 | | |
194 | 246 | | |
| |||
330 | 382 | | |
331 | 383 | | |
332 | 384 | | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
| 388 | + | |
| 389 | + | |
| 390 | + | |
| 391 | + | |
| 392 | + | |
| 393 | + | |
| 394 | + | |
| 395 | + | |
| 396 | + | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
| 401 | + | |
| 402 | + | |
| 403 | + | |
| 404 | + | |
| 405 | + | |
| 406 | + | |
| 407 | + | |
| 408 | + | |
| 409 | + | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
| 454 | + | |
| 455 | + | |
| 456 | + | |
| 457 | + | |
| 458 | + | |
| 459 | + | |
| 460 | + | |
| 461 | + | |
| 462 | + | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
| 466 | + | |
| 467 | + | |
| 468 | + | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
| 481 | + | |
| 482 | + | |
| 483 | + | |
| 484 | + | |
| 485 | + | |
| 486 | + | |
| 487 | + | |
| 488 | + | |
| 489 | + | |
| 490 | + | |
| 491 | + | |
| 492 | + | |
| 493 | + | |
| 494 | + | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
| 498 | + | |
| 499 | + | |
| 500 | + | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
| 504 | + | |
| 505 | + | |
| 506 | + | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
| 512 | + | |
| 513 | + | |
| 514 | + | |
| 515 | + | |
| 516 | + | |
| 517 | + | |
| 518 | + | |
| 519 | + | |
| 520 | + | |
| 521 | + | |
| 522 | + | |
| 523 | + | |
| 524 | + | |
| 525 | + | |
| 526 | + | |
| 527 | + | |
| 528 | + | |
| 529 | + | |
| 530 | + | |
| 531 | + | |
| 532 | + | |
| 533 | + | |
| 534 | + | |
| 535 | + | |
0 commit comments