bug(api): object read path throws CHECK_FAILED (500) under production ReBAC with a custom domain pack

[wangmingzhou1986]

With NODE_ENV=production + OpenFGA authorization and a custom (non-NHS) domain pack, object reads 500 instead of returning an authorized/empty result:

• { enzyme(id:"...") { ... } } and { enzymes { ... } } both return INTERNAL_SERVER_ERROR with extensions.openfoundry.code = "CHECK_FAILED" (retryable: true).
• The write authorization on the same store works: an action mapped to check(user, can_validate, enzyme:) correctly denies without a tuple and allows after a reviewer tuple is written.
• Writing a viewer tuple for the user/object does not resolve it — the read still 500s.
• In dev mode (authz stub) the same read queries succeed.

This points to the read-side authorization (field-level visibility check or listObjects) throwing rather than returning a boolean deny, when resolving relations for a custom domain-pack model.

Reproduce

1. Prod mode; custom pack with object type enzyme (FGA relations viewer, can_validate, ...).
2. Create an object via a governed action; write user: _{viewer enzyme:.}
3. Query { enzyme(id) {...} } -> CHECK_FAILED 500.

Suspected area

AuthorizationService.check / listObjects usage in read resolvers or the field-redaction path (packages/security/src/authz/authorization-service.ts, resolver generator) — likely a thrown client error surfacing as CHECK_FAILED instead of a deny.

Context

Found during a domain-pack PoC (custom genscript.bio pack). Write-side governance (create / validate / ReBAC deny→allow / immutable audit) works end-to-end; only the read path 500s.

[syzygyhack]

Confirmed — this is a real bug, and your instinct about the read path was right. Thanks for the precise repro; the write-works/read-500s asymmetry was the key clue.

The cause isn't in the read resolvers or redaction — it's in how we merge pack permission files. mergeOpenFGAOverrides merges at type-block granularity:

for (const [typeName, block] of overrideBlocks) {
  typeBlocks.set(typeName, block);   // wholesale replace, not relation-level merge
}

So a pack's permissions/*.fga silently deletes the generated relations for any type it declares. Reproduced with the real codegen on a minimal Enzyme pack:

GENERATED   type enzyme → assigned, viewer, editor
+ override  (reviewer, can_validate)
MERGED      type enzyme → reviewer, can_validate      ← viewer is gone

And that maps exactly onto your 500. Against a live OpenFGA with that merged model:

check	result
can_validate (declared in your .fga)	200 {"allowed":false} → clean deny, so writes work
viewer (dropped by the merge)	400 validation_error: relation 'enzyme#viewer' not found

The 400 makes the client throw, AuthorizationService.check wraps it as CHECK_FAILED, and it surfaces as a retryable 500. It also explains why writing a viewer tuple didn't help — OpenFGA rejects tuples for relations that don't exist in the model — and why dev mode is fine (allow-all stub, no model involved). Our own nhs-acute pack is immune only by luck: its .fga happens to declare viewer on all 7 types it overrides.

Planned fix:

1. Relation-level merge — a pack override redefines only the relations it names, and generated relations it doesn't mention survive. That matches the intuitive reading of an override and means your pack works unmodified. We'll check the one side effect before landing it: overridden types would also inherit the generated assigned: [user], which widens the allowlist used by the relationship grant API.
2. Boot-time validation — refuse to start, with a clear message naming the type and relation, if the merged model lacks what the read path requires. This makes the class of failure impossible to ship silently rather than surfacing as a runtime 500.
3. Defensive read path — treat "relation not found" as a deny so a model gap can never present as a retryable 500 again.

Does that sound agreeable to you? Thanks again for another good find!

[syzygyhack]

Fixed and shipped — thanks again for a genuinely good report. The write-works/read-500s asymmetry was the clue that made this quick to pin down.

What landed

• Boot-time validation — the gateway now verifies the merged model declares every relation the runtime will check. A missing viewer is fatal in production and names the offending type, instead of surfacing as a runtime 500 on every read. (Dev only warns; it runs an allow-all stub with no model pushed.)
• Defensive read path — an undefined relation is now treated as a deny rather than an exception, so a model gap degrades to no-access instead of a retryable 500. Logged once per relation+type with remediation guidance.
• Single source of truth for action relations — see below.
• Docs — docs/external-domain-packs.md gained a "What every type must declare" contract (viewer on every ObjectType, can_<verb> per action), a section on naming action relations, and troubleshooting rows for both symptoms. The old Known Limitation advising you to "only define types new to the pack" was wrong and has been corrected — overriding a generated type is the normal case.

One change from the plan I posted: we dropped the relation-level merge.

I measured it against our own packs first, and it isn't the clean win I described. Merging would silently inject relations into hand-written authorization models — four nhs-acute types that today declare only viewer: [user] would have gained assigned: [user] + editor: assigned, i.e. a brand-new edit path a granter could hand out, plus tuple minting for two link types. Implicitly widening a security artifact is the wrong default, and it contradicts the fail-closed stance we hold elsewhere.

The counter-argument — "omitting viewer can't be a deliberate restriction, since it errors rather than denies" — is true, but it argues the opposite: this is a platform contract, so the right response is to state it and enforce it at boot, not to quietly satisfy it. Your pack needs viewer declared on the type; you now get a precise boot error saying so rather than an opaque 500. Apologies for the change of direction after promising "works unmodified".

Your report also uncovered a second bug. The new validator immediately flagged that several bundled packs declared an action relation the runtime never checked — those actions were silently denied in production. Root cause was the same class: deriveActionAuthzMappings took the first PascalCase word while the ODL generator stripped words matching ObjectType names. Worse, that derivation is data-dependent — adding a first-class Transfer ObjectType made both words of TransferWard match type names, silently renaming can_transfer → can_transfer_ward and breaking that action's authorization.

Both sides now use one exported function, and @actionType gained an optional permission: argument so the name can be declared in the schema:

type TransferWard @actionType(permission: "can_transfer") { ... }

Six actions were reconciled and two genuinely-missing relations added. A cross-pack test now asserts the merged model declares what the runtime checks, so the class can't return.

For your pack: declare viewer on enzyme (plus editor if you want direct edit assignment). If any action name is ambiguous, pin it with @actionType(permission: "...") rather than relying on the derivation. Reads should then work, and a stale realm/model won't hide a gap — boot will tell you.

Closing as fixed. If your enzyme reads don't come up cleanly after declaring viewer, reopen with the boot log and we'll take another look.