feat(#581): publish sharing via GrantStore — read=use, write=redeploy/rollback (P3)

[Weegy]

Summary

Phase P3 of issue #581 (publish primitive), stacked on #786 (P2: publish/publish_rollback native tools behind sandbox_publish_enabled). Base branch: feat/581-publish-p2-tools (not main).

Wires the existing GrantStore (#575/#576) into P2's tool handlers, matching the issue text exactly: "Sharing per scope grant (read = use, write = redeploy/rollback)".

What's in this PR

• tools/publishAccess.ts (new) — checkPublishAccess(), the core decision:
  • Ownership is scope-key equality against the app's version-1 sourceScopeKey (already recorded by P1 — nothing new to store). The owner needs no grant lookup at all, so sharing cannot lock the owner out of their own app by construction, not by a special-cased bypass.
  • A brand-new appId with no version yet is allowed unconditionally — the very first publish call is what establishes ownership.
  • For everyone else: resolves a Principal from the caller's session scope (only personal:<userId> scopes map to one — the same omadia-user-id space resolveOrCreateChannelIdentity uses per Scope model with audience-floor permission intersection for shared rooms #575/Identity & Role Projection — omadia as a team-player in the existing IT landscape (Principal = user|role everywhere) #333), then checks resolveCapabilities() for a publish:read:<appId> / publish:write:<appId> capability, with denials winning over grants (same rule audienceFloor.ts/skillSharing.ts apply).
  • Fails CLOSED on every unresolvable case (non-personal: scope, partial role lookup, a throwing grant store) — the opposite failure direction from skillSharing.ts's deliberately fail-open default, because here an unresolved lookup reading as "granted" would let an unrelated scope redeploy or roll back someone else's app.
  • Also ships createGrantCheckedResolveTarget() — the read-gated counterpart for PublishGateway.resolveTarget — as a tested, ready primitive. Not wired into a live server: the anonymous, origin-isolated P1 gateway strips caller identity by design (that's the whole point of the origin-isolation boundary), so an authenticated caller has to come from wherever Wire the #577/#578 service layers to their surfaces: routes, agent tools, admin UIs #778 builds one. Publishing it here rather than leaving the read-share model half-built.
• tools/publishGrantedTools.ts (new) — createGrantCheckedPublishHandler/createGrantCheckedPublishRollbackHandler wrap P2's createPublishHandler/createPublishRollbackHandler with a write-capability check before delegating. Neither P2 file's body is modified — the only change to publishTool.ts is one additive export { resolveScopeKey }; line at the end, so the wrapper resolves the exact same scope key the inner handler provisions its sandbox under. grants.ts itself is untouched — consumed only via its exported GrantStore/resolveCapabilities contract, same posture skillSharing.ts documents.
• plugin.ts — when audienceGrants (the GrantStore Scope model with audience-floor permission intersection for shared rooms #575 already publishes as a service) is configured, both tools register the grant-checked handlers; otherwise the raw P2 handlers run exactly as before. RoleSourceRegistryImpl here is a fresh, empty registry — documented as a known v1 gap (no role-source registry is published as a shared service anywhere in this codebase yet; Orchestrator builds its own private one the same way) — so direct grants work fully today, role grants resolve to nothing until that's wired elsewhere.

Testing

• 26 new tests.
  • publishAccess.test.ts (17): owner needs no grant for both write and read; a fresh appId is open to anyone; a non-owner with no grant is denied for both write and read; a write grant does not imply read and vice versa; a grant for a different appId does not leak; a direct denial beats a direct grant; a role grant covers any holder of that role; a non-personal: scope is denied even with a matching grant on file; a throwing role source fails closed even though a direct grant alone would otherwise have sufficed.
  • publishGrantedTools.test.ts (9): exercises the wrappers end-to-end through the real native-tool handler shape (string in, string out). The owner republishes/rolls back its own app with zero grants configured anywhere — proving sharing cannot lock out the owner. A denied call returns an explicit refusal string naming the app and touches neither the sandbox backend nor the runtime nor the store's pointer — never a silent no-op. A write grant lets a non-owner both publish and roll back. A read grant is proven not sufficient for rollback.
• Combined regression sweep (test/publish/** + test/sandbox/** + buildOrchestrator/orchestratorDispatcher/orchestratorRegistry + skillSharing + audienceFloor + the new plugin-api API-snapshot test from the merged main), after a full npm run build: 190/190 passing, exit 0.
• Mutation-checked (dist/ rebuilt between probes and after restoring):
  • Removed the "denials win" check → failed exactly the denial-direction suite (16 pass / 1 fail).
  • Disabled ownership equality (treated every caller as the owner) → failed 6 of 6 affected suites (12 pass / 14 fail) — the strongest possible signal these tests are load-bearing.
  • Bypassed the publish wrapper's grant check entirely → failed exactly its own suite (8 pass / 1 fail).
  • All three restored, full suite re-verified green after rebuild.
• node scripts/check-core-decoupling.mjs: held at 3296 (unchanged).
• npm run typecheck:test: held at 406 known errors (unchanged) — required switching the two new test files' GrantStore/RoleSourceRegistry/InMemoryGrantStore imports from a relative packages/harness-channel-sdk/src path to the '@omadia/channel-sdk' package specifier (matching skillSharing.test.ts's existing convention): importing a class with private fields from its src/ path while the code under test receives it via the package's dist/ declaration makes TypeScript see two nominally distinct types, even though it's the same source.
• Full npm run build and npx eslint on every changed/new file: clean.

Blast radius

• Two new files in harness-orchestrator/src/tools/, two new test files.
• plugin.ts: one new conditional branch inside the existing sandbox_publish_enabled block (picks the grant-checked handler when audienceGrants is configured, the raw P2 handler otherwise) — no other block in the file touched.
• publishTool.ts: exactly one additive re-export line (export { resolveScopeKey };).
• grants.ts (Scope model with audience-floor permission intersection for shared rooms #575), publishRollbackTool.ts's existing body, and every P1 file: untouched.
• No route, no UI, no migration.
• Nothing changes for a deployment that hasn't set sandbox_publish_enabled=true, and — within that — nothing changes for one that hasn't also wired a GrantStore.

Open questions for Marcel

Carried over from #785/#786 (runtime image scope, stale-version cleanup, apps-host/reverse-proxy config, the synthetic pseudo-command policy shape), plus:

5. createGrantCheckedResolveTarget has no live caller. It's a tested, correct primitive for the read-share half of the model, but wiring it into an actual authenticated request path is Wire the #577/#578 service layers to their surfaces: routes, agent tools, admin UIs #778's job (route/UI), not something this PR could honestly claim to finish — flagging so it doesn't get lost between phases.
6. Role-based publish grants are inert today (empty RoleSourceRegistry, since no shared role-source registry exists anywhere in the codebase yet) — direct grants (grantToPrincipal) work fully. Worth a follow-up once a shared registry exists, or intentionally out of scope for publish specifically?
7. Per your instruction, P4 (admin view) was explicitly NOT started — stays in Wire the #577/#578 service layers to their surfaces: routes, agent tools, admin UIs #778.

Stack

Base: feat/581-publish-p2-tools (#786, P2), which bases on feat/581-publish (#785, P1). This is the third and (per your brief) final PR in the #581 stack before the merge chain runs.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}