Repository navigation
Commit 827b193
fix(cloud-connection): audit an unmanaged grant refused after the control plane granted it (#31537)
Fixes #31481
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XJZfATGni9GCmv2TJRug9bZ)_
Clause-②: no — no published surface changes. The in-process door's
`install(request, options?)` gains an optional `grant`, but
`install-local-door-service.ts` is not exported from
`@objectstack/cloud-connection`. The row is the
`package_unmanaged_import` row #30964 ships, with the same metadata
keys.
Metadata-protocol: none
## 维护者速读
1. 控制面批准非托管安装后,如果环境侧在真正导入之前就拒绝了(无安装权限、取清单失败、目录被墙、协议握手不通过,以及
cloud-connection 自己的"读不懂批准结果" 502 和"环境未挂载 install-local" 503),环境现在会写一条
`package_unmanaged_import` 失败审计行,记录错误码和 HTTP 状态,与控制面的批准行对应。
2. 审计一律通过 `audit` 服务写,不手工拼行;审计服务出错不改变安装应答,只记 error 日志。
3. 导入本身的成功行和失败行不变,也不会重复写。
4. 不是从批准路径发起的普通 install-local
调用被拒绝时不写行;控制面拒绝、托管安装、以及在调用控制面之前就被拒绝的请求也不写(这些都还没有批准)。是否也要审计这些"批准前"的拒绝,见下文,本
PR 不改。
5. 无 spec 改动,无新的元数据字段。
## What changes
**The install-local door audits its refusals of a grant.** The
cloud-connection door now hands the in-process install-local door the
grant beside the request: `install(request, { grant })`. The grant
carries the marketplace package id, the granted version, the environment
and the installer, which is the session the cloud-connection door
admitted. The door runs the same `handleInstall`. When it answers a
grant with a refusal, and its unmanaged copy did not already audit the
call, it hands the `audit` slot one `package_unmanaged_import` event.
The event has `outcome: 'failure'`, the answer's `error.code` and its
HTTP status. That covers every refusal before the import runs: the
install capability (403 `FORBIDDEN`), the manifest fetch
(`CLOUD_FETCH_FAILED`), the walled catalog (403 `FORBIDDEN`), the
protocol handshake (422 `OS_PROTOCOL_INCOMPATIBLE`), and every other
step between them, such as the mode check and the dependency check. A
throw from the handler is audited with the status it resolves to, then
rethrown.
- The import's own success and failure events (`installUnmanaged`,
#30964) are unchanged. A call they audited is marked, by its route
context, so it never gets a second, refusal event. A refusal after a
landed import (for example a later 503) keeps the success event alone.
- Without `grant`, the in-process door is exactly the route: a plain
install-local call writes nothing for a refusal.
**The cloud-connection door audits its own refusals of a grant.** A
grant it cannot read (502 `PLUGIN_INSTALL_FAILED`) and an environment
without the install-local door (503 `SERVICE_UNAVAILABLE`) each hand the
environment's `audit` slot the same failure event. The slot, like the
door, is the environment kernel's in a multi-tenant deployment and the
host's in a single-environment one. A door refusal is left to the door,
so it is never written twice.
**The event.** It goes through the `audit` slot's
`recordPackageLifecycleEvent`, never as a hand-built row. The structural
event type and the slot call moved from
`marketplace-install-local-plugin.ts` to
`install-local-door-service.ts`, so both doors use one declaration and
one call (`recordUnmanagedImportEvent`). An audit slot that throws
changes no answer, and the failure is logged at `error` (at `warn` on a
host logger without `error`). plugin-audit stores it as #30964's row:
- `package_id` is the granted marketplace package id, the control
plane's `recordId`, because a refusal before the manifest is read knows
no manifest id;
- `version` is the granted version;
- `environment_id` is filled here, because the grant names its
environment;
- `outcome` is `failure`, with `error_code` and `status`;
- `target_package_id`, `namespace`, `source_namespace` and
`copied_count` are null.
## Refusals before the grant (the card's question)
These write no environment row, and this PR does not change that:
- the cloud-connection door's checks before the control plane is called
(400, 401, 404, 503 `CLOUD_UNCONFIGURED`);
- a control-plane refusal;
- a managed install.
No grant exists for any of them, so there is no control-plane grant row
for an environment row to complete. The control plane's own audit covers
what it refused. An environment row for a request refused before any
grant would record an install that was never granted. My reading is that
it should stay out of `package_unmanaged_import`. If it is wanted, it is
a separate action. That is the seat's call.
## Tests
-
`packages/cloud-connection/src/marketplace-install-local-grant-refusal-audit.test.ts`
(new). The in-process door is booted through `init()` + `start()` +
`kernel:ready`, with an `audit` slot that records what it is handed. 11
cases:
- Four refusals through the grant path each answer their own code,
status and message, never call the import, and hand exactly one failure
event naming the grant's package, version, environment and installer.
They are the install capability (no permission set), the manifest fetch
(cloud 500), the walled catalog (an `isolated` `tenancy` service, with
the installer's grant held in a tenant organization, so it is the
organization's `manage_metadata` holder and not the platform operator),
and the protocol handshake (`engines.protocol: '^1.0.0'`).
- The same four refusals of a plain call hand no event.
- A granted copy that lands hands one success event and no refusal
event.
- A granted copy whose import fails (409) hands the import's one failure
event, never a second.
- An audit slot that throws changes no answer and is logged at `error`.
- `packages/cloud-connection/src/cloud-connection-plugin.test.ts`, 6
cases in the #30964 unmanaged-grant suite:
- The door is handed `{ grant: { packageId, version, environmentId,
actor } }`, and this door hands no event for a copy it handed over.
- An unreadable grant hands one 502 failure event, in both deployments.
- No door hands one 503 failure event.
- A door refusal hands no second event from this door.
- A control-plane refusal and a managed install hand none.
- A throwing slot changes no answer and is logged at `error`.
## Acceptance notes
- **Sibling.** Seat 5's #31392 → #31425 work touches
`marketplace-install-local-plugin.ts`. Whichever lands second merges
origin/main and re-reads the other's pins.
- **Not measured on a live boot.** The cross-repo assumptions in #30964
still hold here. The grant's shape is assumed, and whether a hosted
environment kernel mounts install-local is #31482.
## Verification
Head `2f2318b0`, base origin/main `58f66b93`. The ablations ran at
`dc6d91cf`. `2f2318b0` changes only the logger slice (a `warn` fallback,
for `check:optional-error-sink`) and drops `refusalCodeOf`'s fallback
parameter (for `check:dispatcher-error-vocabulary`). Both gates were red
on the first pass and exit 0 after the fix.
- **Red on main first.** With the three production files restored to
`58f66b93` and the new tests kept, `cloud-connection-plugin.test.ts` and
the new file gave 9 failed, 37 passed. Examples: `expected undefined to
deeply equal { grant: { packageId: 'pkg_1', …(3) } }`, `expected [] to
deeply equal [ { …(8) } ]` (no event, for each of the four door refusals
and for the 502 and 503), and `expected '' to contain
'package_unmanaged_import'`. The success, import-failure and plain-call
cases are controls and passed on main too. Then green on head.
- **Ablations** (`scripts/ablation-replace.mjs`; each mutation landed,
was run, and the tree was restored to HEAD; each red):
- the door's refusal branch → `if (false)`: the four refusal pins and
the throwing-slot pin are red;
- the already-audited guard → `if (!answer.ok)`: the import-failure pin
is red (two events);
- the grant-only rule → `grant ??= { … }` for a plain call: the four
plain-call pins are red;
- the mark → removed: the import-failure pin is red;
- the grant handed to the door → `door.install(request)`: the
handed-grant pin is red;
- the 502 audit → removed: the unreadable-grant pin is red;
- the 503 audit → removed: the no-door pin and the throwing-slot pin are
red.
- **Package suite** (under the verify lock): cloud-connection 76 files,
1034 passed. `pnpm --filter @objectstack/cloud-connection run typecheck`
exit 0, including the test layer. `pnpm lint packages/cloud-connection`
exit 0.
- **Dispatch gates:** `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` derived 71 commands. Each was run
with its exit captured before any pipe and recorded as `<command> ::
exit N`. `--ran` reports `71 derived famil(ies) accounted for — 71 run,
0 NOT-MEASURED (a DERIVED zero — all 71 recorded an exit code and none
of them is 3)`. On the first pass at `dc6d91cf`, two gates were red:
- `check:optional-error-sink`: the new logger slice declared an optional
`error` with no `warn`;
- `check:dispatcher-error-vocabulary`: `refusalCodeOf` took its fallback
code as a parameter, which the scan cannot reduce.
`2f2318b0` fixed both. The full set of 71 was then re-run on `2f2318b0`,
and every gate exited 0.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5pQJCx8STEq28nr3Ej)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent f923bc1 commit 827b193
6 files changed
Lines changed: 582 additions & 65 deletions
| 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 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
403 | 403 | | |
404 | 404 | | |
405 | 405 | | |
406 | | - | |
| 406 | + | |
407 | 407 | | |
| 408 | + | |
| 409 | + | |
408 | 410 | | |
409 | 411 | | |
410 | | - | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
411 | 421 | | |
412 | | - | |
| 422 | + | |
413 | 423 | | |
| 424 | + | |
414 | 425 | | |
415 | 426 | | |
416 | 427 | | |
| |||
419 | 430 | | |
420 | 431 | | |
421 | 432 | | |
| 433 | + | |
422 | 434 | | |
423 | 435 | | |
424 | 436 | | |
425 | 437 | | |
426 | | - | |
| 438 | + | |
427 | 439 | | |
428 | 440 | | |
429 | 441 | | |
| |||
437 | 449 | | |
438 | 450 | | |
439 | 451 | | |
440 | | - | |
| 452 | + | |
441 | 453 | | |
442 | 454 | | |
443 | 455 | | |
| |||
532 | 544 | | |
533 | 545 | | |
534 | 546 | | |
| 547 | + | |
| 548 | + | |
| 549 | + | |
| 550 | + | |
| 551 | + | |
| 552 | + | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
| 566 | + | |
| 567 | + | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
| 571 | + | |
| 572 | + | |
| 573 | + | |
| 574 | + | |
| 575 | + | |
| 576 | + | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
| 581 | + | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
| 592 | + | |
| 593 | + | |
| 594 | + | |
| 595 | + | |
| 596 | + | |
| 597 | + | |
| 598 | + | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
535 | 609 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
155 | 155 | | |
156 | 156 | | |
157 | 157 | | |
158 | | - | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
159 | 162 | | |
160 | 163 | | |
161 | 164 | | |
| |||
1046 | 1049 | | |
1047 | 1050 | | |
1048 | 1051 | | |
1049 | | - | |
| 1052 | + | |
1050 | 1053 | | |
1051 | 1054 | | |
1052 | 1055 | | |
| |||
1069 | 1072 | | |
1070 | 1073 | | |
1071 | 1074 | | |
| 1075 | + | |
| 1076 | + | |
| 1077 | + | |
| 1078 | + | |
| 1079 | + | |
| 1080 | + | |
| 1081 | + | |
1072 | 1082 | | |
1073 | 1083 | | |
1074 | 1084 | | |
1075 | | - | |
| 1085 | + | |
1076 | 1086 | | |
1077 | | - | |
| 1087 | + | |
1078 | 1088 | | |
1079 | 1089 | | |
| 1090 | + | |
| 1091 | + | |
| 1092 | + | |
| 1093 | + | |
| 1094 | + | |
| 1095 | + | |
| 1096 | + | |
| 1097 | + | |
| 1098 | + | |
| 1099 | + | |
| 1100 | + | |
| 1101 | + | |
| 1102 | + | |
| 1103 | + | |
| 1104 | + | |
| 1105 | + | |
| 1106 | + | |
| 1107 | + | |
| 1108 | + | |
| 1109 | + | |
| 1110 | + | |
| 1111 | + | |
| 1112 | + | |
| 1113 | + | |
| 1114 | + | |
| 1115 | + | |
1080 | 1116 | | |
1081 | 1117 | | |
1082 | 1118 | | |
| |||
1094 | 1130 | | |
1095 | 1131 | | |
1096 | 1132 | | |
| 1133 | + | |
1097 | 1134 | | |
1098 | 1135 | | |
1099 | 1136 | | |
| |||
1103 | 1140 | | |
1104 | 1141 | | |
1105 | 1142 | | |
1106 | | - | |
1107 | | - | |
1108 | | - | |
1109 | | - | |
1110 | | - | |
1111 | | - | |
1112 | | - | |
1113 | | - | |
1114 | | - | |
1115 | | - | |
1116 | | - | |
| 1143 | + | |
1117 | 1144 | | |
| 1145 | + | |
1118 | 1146 | | |
1119 | 1147 | | |
1120 | 1148 | | |
| |||
1137 | 1165 | | |
1138 | 1166 | | |
1139 | 1167 | | |
1140 | | - | |
| 1168 | + | |
| 1169 | + | |
1141 | 1170 | | |
1142 | 1171 | | |
1143 | 1172 | | |
| |||
0 commit comments