refactor(authz): OpenFGA parser, profile validator, and compiler

[livio-a]

Summary

• Implements OpenFGA Parser, IR & Profile Compiler #421: OpenFGA DSL/JSON → portable authz IR (internal/authz/openfga), MVP profile validation with structured diagnostics (internal/authz/profile), and compilation to storage-neutral catalog mutations + query-plan metadata (internal/authz/compiler).
• Uses upstream github.com/openfga/language/pkg/go for parsing; Zitadel owns profile enforcement and plan output. Persistence/SQL mapping stays with Relational Schema & Migrations for Authorization #422.

Validation

• go test ./internal/authz/...

Release notes / changeset

• Changeset: .changeset/openfga-authz-compiler.md — OpenFGA authz parser/profile/compiler foundation (@zitadel/server minor)

Notes

• Output deliberately has no catalog IDs, SQL, or dialect types — Relational Schema & Migrations for Authorization #422 maps rows to Postgres/Spanner.
• Bundles / flat {resource}.{verb} catalog alignment and Leopard flattening are deferred.
• Closes OpenFGA Parser, IR & Profile Compiler #421

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview	Aug 5, 2026 7:44am
nextgen-docs	Ready	Preview	Aug 5, 2026 7:44am
nextgen-mock-zitadel	Ready	Preview	Aug 5, 2026 7:44am

[github-actions]

🦋 Changeset detected

Latest commit: abfeed1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Implements the first stage of the ADR-032 OpenFGA→catalog pipeline by introducing a storage-neutral authz intermediate representation, an OpenFGA DSL/JSON parser adapter, a bounded-profile validator with structured diagnostics, and a compiler that emits catalog mutations plus query-plan metadata (leaving persistence/SQL mapping to #422).

Changes:

• Add internal/authz/openfga to parse OpenFGA DSL/JSON via github.com/openfga/language/pkg/go and normalize into a deterministic internal/authz IR.
• Add internal/authz/profile validator to enforce the MVP “portable/bounded” profile and return structured Diagnostics.
• Add internal/authz/compiler to compile a profile-valid model into storage-neutral catalog mutations, flattened query terms, and same-object computed-userset closure metadata.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/authz/profile/profile.go	Implements profile validation (schema version, unsupported constructs, TTU bounding).
internal/authz/profile/profile_test.go	Unit tests for accepted profile, rejection diagnostics, and configurability.
internal/authz/profile/index.go	Adds deterministic model index + reference graph traversal for recursion detection.
internal/authz/profile/diagnostic.go	Defines stable diagnostic codes + Diagnostics error semantics (Unwrap for errors.Is).
internal/authz/openfga/parse.go	Adapts upstream OpenFGA parser/transformer to normalized Zitadel IR.
internal/authz/openfga/parse_test.go	Tests DSL/JSON parsing, normalization ordering, and condition preservation.
internal/authz/model.go	Introduces the shared storage-independent authz IR types.
internal/authz/compiler/output.go	Defines storage-neutral catalog mutation records and query-plan term structures.
internal/authz/compiler/compiler.go	Validates then compiles IR into catalog mutations, query plans, and implication graph inputs.
internal/authz/compiler/compiler_test.go	Tests compilation output, closure properties, TTU handling, and diagnostics passthrough.
internal/authz/compiler/closure.go	Computes shortest-depth reflexive transitive closure for computed-userset implications.
go.mod	Adds OpenFGA language + proto dependencies.
go.sum	Adds checksums for new dependencies (including indirects).
.changeset/openfga-authz-compiler.md	Declares @zitadel/server minor release note for the new authz foundation.

[fforootd]

Solid implementation — this tracks ADR 032 §2 closely: the package boundary is verbatim from the ADR table, the hierarchy edges and unsupported-construct set match, and the output types stay clean of catalog IDs/SQL so #422 keeps full freedom on the relational shape.

What I did beyond reading: checked out the branch, ran go vet + go test ./internal/authz/... (green, matching CI), hand-checked the closure BFS and its deterministic catalog-order emission against the test expectations, and threw four adversarial models at it. Recursion detection held up well — a self-type TTU through a valid hierarchy edge (define parent: [project] + define viewer: [user] or viewer from parent) is rejected as unbounded_recursion, and a cross-type team↔project TTU cycle rejects both participants with stable diagnostics. The two shapes that slipped through are both crafted-JSON-only and deny-safe; repros are in the inline comments.

Things I want to call out as particularly good:

• The diagnostics design: comparable Diagnostic + Diagnostics.Unwrap() []error makes a single violation errors.Is-matchable without scanning, and reusing OpenFGA's own error vocabulary (with the documented rationale for not reusing 2002) is exactly the right customer-empathy call.
• Determinism is handled at every layer (sorted normalization, positions, catalog-order closure rows) — the future catalog-diff story will lean on this.
• The oneof-discriminator switch in normalizeRewrite instead of the unreliable GetThis() is a subtle trap avoided, and the comment explains it for the next reader.
• The closure/plan split (computed usersets → closure; TTU and userset refs → plan terms) is the correct reading of ADR 032 §3's write-cheap model, and there's a test pinning that TTU is not treated as a global implication.

Two notes that don't belong on any one line:

• Upload-path bounds: recursion checking is O(V·E) per relation, the closure is O(V²) rows worst case, and ANTLR parses untrusted tenant input. All fine at schema scale, but #422's upload API should cap input size and type/relation counts — worth carrying over as a note on that issue so it doesn't get lost.
• ADR bookkeeping: ADR 032 is still marked Proposed and its follow-up item 4 is exactly this PR — worth ticking off (or revisiting the status) when this lands.

The one thing I'd change before merge is the changeset/title pairing — see the comment on the changeset file.

[adlerhurst]

No additional comments to ffo's review.