service-datasource: the `AuthzStoreUnavailableError` the admin guard re-raises reaches the wire as `500 INTERNAL_ERROR`, not the `503 SERVICE_UNAVAILABLE` the brand declares

[zhuangjianguo]

Found while implementing #15350 (out of its scope, filed rather than fixed inline).

What was measured

requireDatasourceAdmin in packages/services/service-datasource/src/admin-routes.ts deliberately re-raises the outage brand rather than laundering it into a denial:

} catch (err) {
  if (isAuthzStoreUnavailableError(err)) throw err;
  userId = undefined;
  systemPermissions = [];
}

That is the #13279 discipline and it is correct: an unreadable authorization store licenses no verdict. But every route in this family opens with if (await requireDatasourceAdmin(req, res)) return; and that call is not inside a try, so the throw escapes the route handler entirely. The Hono adapter renders any escaped throw as a bare 500 (adapter.ts, "route handler threw — request answered 500 with no cause in the body").

Measured on origin/main plus the #15350 branch, driving GET /api/v1/datasources with a tenancy service registered through a factory that throws:

status: 500
body:   { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "No response from handler" } }

AuthzStoreUnavailableError declares status: 503 / code: SERVICE_UNAVAILABLE, and that class exists precisely so an outage is distinguishable from a capability denial on the wire. Here the distinction survives only in the sense that 500 is not 403; the declared code never reaches the caller, and the message says nothing an operator can act on.

Why this is pre-existing, and not #15350's

The escape has existed since #13279 for the ql permission-store outage, which is the fault that catch was written for. #15350 adds a second source of the identical brand at the identical seam (a tenancy service that was registered and failed to build), so it makes the path easier to reach but does not create it. #15350's pin asserts the outage CLASS deliberately — status in the set 500 or 503, never 200 and never 403 — so repairing the status here does not redden a security pin.

Scope question this card should settle

git grep over non-test packages/**/*.ts finds six sites re-raising this brand, five of them direct-mount registrars:

• packages/services/service-datasource/src/admin-routes.ts:501 (measured, this card)
• packages/services/service-settings/src/settings-service-plugin.ts:292
• packages/services/service-storage/src/storage-service-plugin.ts:921
• packages/cloud-connection/src/marketplace-install-local-plugin.ts:1764
• packages/plugins/plugin-sharing/src/sharing-plugin.ts:857
• packages/core/src/security/authz-store-unavailable.ts:208 (the shared helper itself)

Only the first was measured. Whether the other four render the declared 503 depends on each transport's own error path, and none of them was driven here — please do not read this list as five confirmed defects.

Two directions, not obviously one-line

1. Per-family: each route's own catch reads err.status / err.code and relays, the way badRequest in this same file already relays a service-thrown 503/SERVICE_UNAVAILABLE envelope (IMetadataService.list() presents a known-partial answer as a complete one — the #5840 shape on the plural read #6504). Repeats the relay at every call site.
2. Shared: the adapter, or a registrar wrapper, renders an escaped ADR-0112 envelope by its declared status and code. One place, but it changes what an escaped throw means for every direct-mount route in the repo, which is a design decision rather than a repair.

Filed unassigned; no labels, for triage to grade.

[claude]

PM note on the census in this card, from the round that filed it (#15350 / PR #16011).

The round's recommendation for extending this beyond the datasource family was A — measure all five direct-mount registrars, then decide per-family relay versus one shared render of an escaped ADR-0112 envelope — and it asked that this be carried on this card rather than as a second one, since this card already records the census honestly.

⚠️ Recording its caveat verbatim in substance, because the list is easy to misread: git grep finds six re-raise sites, five of them direct-mount registrars. The round drove only this family. Whether each of the others renders the declared 503 or a bare 500 depends on its own transport, and it measured none of them. ⛔ Do not read that list as five confirmed defects. It is one measured site and four unmeasured ones.

So the work this card can carry, if a maintainer wants it: measure the remaining four, per-transport, and only then choose between a per-family relay and a shared render. ⛔ The choice should not be made from the datasource reading alone — one transport's behaviour is not a reading about another's.

For the record, the measured one: requireDatasourceAdmin re-raises AuthzStoreUnavailableError, it escapes route handlers that have no catch, and the Hono adapter renders it as 500 INTERNAL_ERROR ("No response from handler") rather than the 503 SERVICE_UNAVAILABLE the brand declares. The security pin added in #16011 deliberately asserts the outage class (status in {500, 503}, never 200, never 403), so repairing the status later will not redden that pin.

---

Generated by Claude Code

[claude]

A second site measured — service-settings, one of the four this card listed but did not drive. Found while implementing #15351 (the tenancy-posture supply at that seam), out of its scope, so it is contributed here rather than filed as a new card: this card already owns the question and explicitly asked that its list not be read as confirmed defects.

What was measured

packages/services/service-settings/src/settings-service-plugin.ts:292 — the site this card names — re-raises the brand exactly as the datasource guard does:

} catch (err) {
  if (isAuthzStoreUnavailableError(err)) throw err;
  return { enforced: true }; // fail closed
}

The escape path differs from the datasource one, and it does NOT reach the adapter: verifiedContextFromRequest is called as await ctxOf(req) from INSIDE each route's own try in packages/services/service-settings/src/settings-routes.ts. Every one of those catches ends in the same untyped tail:

sendError(res, 500, 'INTERNAL_ERROR', err?.message ?? 'Failed to read namespace');

So the brand is caught, and then flattened. Driven through the real SettingsServicePlugin over a real ObjectQL engine, with tenancy registered through a factory that throws:

PUT /api/settings/:ns   ->  500  { success: false, error: { code: 'INTERNAL_ERROR', ... } }
GET /api/settings       ->  500  { success: false, error: { code: 'INTERNAL_ERROR', ... } }

The message does survive here (The authorization store could not be read, ... (failed read: tenancy)), which the datasource site's No response from handler does not — but code and status are both lost, and those are what a client branches on.

What this changes about the scope question

The two measured sites lose the envelope in two different places: the datasource one escapes the handler and is rendered by the adapter, the settings one is caught by the route's own catch and re-encoded. So direction 1 (per-family catch relays err.status / err.code) is not one edit repeated — the settings family needs a new arm in three route catches, the datasource family needs the call wrapped at all. That is an argument for direction 2 (one shared mapping the transports call), but it is an argument, not a measurement, and the remaining three sites are still undriven.

⚠️ Same caveat as this card's own: the other three (service-storage, cloud-connection, plugin-sharing) remain unmeasured here.

The settings-side pin added by #15351 asserts the outage CLASS at the door (status 500, never 200 and never 403) and asserts the declared code / status / object at the seam that raises it, so repairing the status here reddens one line of a test that already names this card in its comment.

---

Generated by Claude Code

[zhuangjianguo]

Census row filled: service-storage's download door is MEASURED, and it is neither 503 nor 500 — it is 403 FILE_DOWNLOAD_DENIED.

This card's scope section names packages/services/service-storage/src/storage-service-plugin.ts:921 as one of the five re-raise sites it explicitly did not drive, and asks not to read the list as five confirmed defects. Measured while implementing #15352 (PR #16017), on that branch, with a tenancy service registered through a factory that throws:

GET /api/v1/storage/files/:fileId/url   -> 403
GET /api/v1/storage/files/:fileId       -> 403
body: { "success": false, "error": { "code": "FILE_DOWNLOAD_DENIED",
        "message": "You do not have access to the record this file belongs to" } }

Identical for all three principals driven (a current member, an ex-member's org-stamped key, an organization-less key), on both download routes. getPresignedDownload was called 0 times, so no capability is minted — this door is fail-CLOSED, as service-datasource is.

The mechanism differs from this card's, and that matters for the "two directions" question. Here the brand never escapes the handler at all. buildFileReadAuthorizer re-raises it exactly as requireDatasourceAdmin does:

} catch (err) {
  if (isAuthzStoreUnavailableError(err)) throw err;
  return 'deny'; // fail closed
}

but registerStorageRoutes' authorizeDownload, one frame above, wraps the whole authorizer call in catch { verdict = 'deny'; } — commented "a failed authz check must never fall open". So the re-raise is absorbed there and rendered as the download gate's own capability denial. The outer route handler's catch (which would have produced this card's 500) is never reached.

Consequence for the repair directions this card weighs:

• Direction 2 (a shared renderer for an escaped ADR-0112 envelope) does nothing for this door on its own — nothing escapes to render. The inner catch { verdict = 'deny' } has to learn the brand first.
• Direction 1 (per-family relay) is the only one that reaches this door, and here it is two edits, not one: authorizeDownload must re-raise or return a distinct outage verdict, and the route must relay it.

This door is also the worst-case shape of the very thing #13279 was filed about: the outage is answered as a permission denial, indistinguishable on the wire from a genuine refusal — not merely as an uninformative 500. And it is pre-existing here for the same reason it is next door: that catch has flattened the ql permission-store outage since #13279 landed. #15352 adds a second producer of the identical brand at the identical seam; it does not create the path, and it repairs none of it.

⚠️ Still UNMEASURED after this comment: service-settings, cloud-connection, plugin-sharing. Three of five now, not four.

#15352's pin asserts the outage CLASS (status in 403 / 500 / 503, never 200, never 302, never a minted capability) rather than the digits, deliberately — so whatever this card decides, repairing the status here does not redden a security pin.

---

Generated by Claude Code