meta apps by-name route: answer an explicit permission-denied envelope for an unauthorized session, instead of being indistinguishable from "not published" (backend half of objectui#4252)

[hotlong]

Filed by the triage seat implementing a maintainer ruling (2026-08-12, live PM session, verbatim: 「接受你的全部建议。」 on the decision digest covering objectui#4252). Contract-first split: this is the backend half; the console half is objectui#4252, which is blocked on this card.

Problem (measured in objectui#4252)

GET /api/v1/meta/apps omits apps the session isn't authorized for (filterAppForUser, packages/rest/src/rest-server.ts). From the console's point of view an unauthorized app and a nonexistent/unpublished app are byte-identical — both absent — so the console renders "may still be publishing" for a permanent authorization denial. That copy already cost two acceptance-test batches chasing a "platform defect" that was a missing permission-set binding (evidence on objectui#4252).

Ruled scope

• By-name app route: when the app exists but the session lacks its requiredPermissions, answer an explicit permission-denied envelope (code + status, standard error shape) instead of the absence/404-equivalent.
• List route (/meta/apps) stays filtered as-is — deliberately unchanged, to avoid widening the enumeration surface beyond what a direct by-name probe already implies.
• The console (objectui#4252) then distinguishes: absent ⇒ current "not published" copy; denied envelope ⇒ plain "you don't have access to this app".

Acceptance

1. Session WITHOUT the capability, by-name request ⇒ permission-denied envelope (assert code + status, not just non-200).
2. Session WITH the capability ⇒ app unchanged.
3. Nonexistent app name ⇒ existing absence behavior unchanged.
4. List route output for the unauthorized session unchanged (no authorized: false leakage).

Landing

packages/rest/src/rest-server.ts (filterAppForUser and the by-name meta app handler) ⇒ domain:cli. If implementation shows the by-name path actually resolves in metadata-protocol instead, report the corrected landing in the claim — do not silently widen the file surface.

Links

• objectui half (blocked on this): [console] Apps blocked by requiredPermissions render the "may still be publishing" placeholder, disguising an authorization denial as a transient deploy state objectui#4252
• Related: Nav gating cannot express "prune when the destination cannot serve" — enable.apiEnabled is never consulted by filterAppForUser #7912 (filterAppForUser never consults enable.apiEnabled — separate card, do not fold in)

[hotlong]

Claimed and dispatched — domain:cli PM seat (#6024), session session_01B3Kurx8qufrDzNjk4rag7V, branch claude/issue-8013-meta-app-by-name-denied-envelope.

The card is dispatched as written; the ruling and all four acceptance criteria go into the brief verbatim. Two things carried in as hard constraints beyond the card text:

Acceptance criterion 3 is the security criterion, not a formality. Turning "absent" into an explicit denial for an app the session may not touch is a deliberate, ruled disclosure — the app's existence becomes observable to an unauthorized caller. That is licensed here only for the by-name route on an app that exists. A fix that also converts the nonexistent-name path into a denial envelope has silently made every app name enumerable, which is a different and unruled change. Criterion 3 is what pins the difference, so it must be asserted on the envelope, not on "still an error."

Criterion 4 likewise. The list route stays filtered exactly as-is — the ruling says so explicitly, to avoid widening the enumeration surface past what a direct by-name probe already implies. No authorized: false may appear in list output.

Concurrency note for the implementer: #8071 is in flight on the same file (packages/rest/src/rest-server.ts, the /security/suggested-bindings routes). Different region, but that file is the repo's hottest — the brief instructs rebasing onto main before pushing and touching only the meta-apps region.

⛔ #7912 (filterAppForUser never consults enable.apiEnabled) stays out — separate card, per this card's own Links section.

---

Generated by Claude Code

[hotlong]

{
 "issue": 8013,
 "status": "done",
 "branch": "claude/issue-8013-meta-app-by-name-denied-envelope",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8135",
 "premise_still_valid": true,
 "summary": "Confirmed landing: packages/rest/src/rest-server.ts, NOT metadata-protocol. The by-name gate is re-derived in rest-server.ts, and the cached read path is excluded for isAppType (line ~5692), so every app-typed by-name request already takes the uncached branch holding the gate — no second file was edited. filterAppForUser now delegates to a new filterAppForUserWithReason returning { app, withheld: 'unpublished' | 'permission' | 'service' }; filterAppForUser is an unchanged thin wrapper, so the list route and the existing unit pins are untouched. The by-name handler converts ONLY withheld === 'permission' into 403 PERMISSION_DENIED, written through the SHARED sendError from @objectstack/types (imported as sendEnvelopeError — this module has its own local sendError, the sanitizing responder for THROWN errors). Chosen code/status: code = PERMISSION_DENIED, status = 403 — the ADR-0112 STANDARD catalog member (the ledger's own rule: a generic permission condition takes the catalog, not a synonym), and what standardErrorCodeForHttpStatus(403) answers. Wire body: { success: false, error: { code, message } }, so objectui#4252 reads body.error.code — the same accessor as the neighbouring 404. Unpublished (ADR-0045 §3 unobservability, and _unpublished is judged FIRST so it wins over the disclosure), absent-service (ADR-0057 D10 — a deployment fact, not a denial to this caller), a nonexistent name, and the whole list route all keep their existing behavior.",
 "tests": "All on the REBASED tree (onto 3670cf9f2, which includes #8071 and #8088), dependency closure built first.\n\n(1) pnpm --filter @objectstack/rest test -> 'Test Files 101 passed (101) / Tests 1678 passed (1678)'.\n(2) pnpm --filter @objectstack/rest typecheck -> 'tsc --noEmit' clean, no output.\n(3) pnpm check:type-check-debt (full closure built) -> 'OK - 33 ledger entr(ies) re-measured in 300.7s, 1966 raw tsc error(s) total, none above its recorded number.' @objectstack/rest is NOT among the 9 surplus entries, i.e. it measured exactly its recorded 155 — zero-margin ceiling held, ledger not raised.\n(4) pnpm check:route-envelope -> self-test passed + 'ratchet ... rest-server.ts (dialect facts only - stringError 44, siblingCode 75)'. Unmoved: 75 is #8071's freshly-lowered baseline, and the new call site adds no write-site literal (the body lives in the pinned SHARED_BUILDER).\n(5) pnpm check:nul-bytes -> self-test 75 assertions + 'OK (scanned 7407 text file(s) ... no raw ASCII control bytes)', plus a wider grep -naP self-scan of the changed files: no hits.\n\nREVERSE VERIFICATION — 5 reversals, each pin red for its own reason (verbatim):\n R1 restore the pre-fix single 404 -> criterion 1: 'AssertionError: expected 404 to be 403 // Object.is equality'\n R2 drop the `visible` guard + infer the reason from null -> criterion 3: 'AssertionError: expected 403 not to be 403 // Object.is equality'\n R2b map the producer's miss onto a denial -> criterion 3 (production shape): 'AssertionError: expected 403 to be 404 // Object.is equality'\n R3 list route annotates authorized:false instead of dropping -> criterion 4: \"AssertionError: expected [ 'account', 'crm', 'finance', …(1) ] to not include 'finance'\"\n R4 deny the capability holder too -> criterion 2: 'AssertionError: expected 403 to be 200 // Object.is equality' (and criterion 4's holder half: \"expected [ 'account', 'crm', 'telephony' ] to include 'finance'\")\n R5 naive 'any null => 403' -> FOUR pins at once: criterion 3, both partition pins, AND the pre-existing #4829 pin 'SINGLE ITEM: the unpublished app 404s for a non-builder' — 'expected 403 to be 404' x3 plus 'expected 403 not to be 403'.\nRestored after each; final tree byte-identical to the saved patch (diff of `git diff` against the saved fix.patch was empty).\n\nNote on direction, reported rather than papered over: criteria 2/3/4 stay GREEN under R1. That is correct, not a gap — they pin behavior the fix deliberately leaves UNCHANGED, so removing the fix cannot break them. Each therefore has its own targeted reversal above (R4, R2/R2b, R3), which is what proves they are live pins.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Chosen envelope, for objectui#4252 to branch on: code: "PERMISSION_DENIED", status: 403, nested as body.error.code in the declared { success: false, error: { code, message } }.

⛔ #7912 was NOT folded in, per this card's Links section. The list route's filtering is unchanged.

---

Generated by Claude Code