feat(authz): replace bespoke FGA with embedded OpenFGA ReBAC engine

CLAUDE.md

@@ -58,6 +58,9 @@ Detailed rules load via skills (see below) — don't restate them here.
 | `principal-engineer` | opus | Full SDLC: Plan → Execute → Test → Review across Go, storage, GraphQL, HTTP. Use for any change touching >1 subsystem. |
 | `security-engineer` | opus | OAuth2/OIDC, JWT, MFA, vulnerability audit. Second-pass on auth-sensitive PRs. |
 | `doc-writer` | haiku | API docs, guides, migration docs. |
+| `authz-researcher` | opus | Deep, adversarially-verified research on authz standards (OpenFGA, RFC 8693/8707/9728, MCP, CIBA, AuthZEN). Run before designing/building any authz capability. |
+| `fga-engineer` | opus | Implements the OpenFGA migration (Wave 1) per specs/FGA_OPENFGA_MIGRATION_PLAN.md (authorizer-docs repo). |
+| `delegation-engineer` | opus | Implements the agentic delegation chain (Wave 2) per specs/AGENTIC_DELEGATION_DESIGN.md (authorizer-docs repo). Security-critical. |
 
 ## Project Skills (auto-load on matching files)
 
@@ -70,6 +73,8 @@ Detailed rules load via skills (see below) — don't restate them here.
 | `authorizer-security` | auth-sensitive code or `security/` branches |
 | `authorizer-testing` | any `*_test.go` |
 | `authorizer-frontend` | `web/app/`, `web/dashboard/` |
+| `openfga-modeling` | FGA engine (`internal/authorization/`), authz models/tuples, `check_permissions`/`list_permissions`/`_fga_*` GraphQL |
+| `agentic-auth-standards` | token exchange, delegation, MCP, agent-identity (`internal/token/`, `internal/http_handlers/`) |
 
 ## Token Optimization Notes
 

ROADMAP_V2.md

@@ -18,10 +18,10 @@
 | 13+ Database backends | Done | Unique differentiator |
 | Rate Limiting / Brute Force | Missing | No protection at all |
 | M2M / Client Credentials | Missing | No service accounts or API keys |
-| Fine-Grained Permissions | Missing | Roles only, no resource-level control |
+| Fine-Grained Permissions | In progress (pre-stable) | RBAC/ABAC Resource/Scope/Policy/Permission engine exists; migrating to OpenFGA ReBAC — see specs/FGA_OPENFGA_MIGRATION_PLAN.md (authorizer-docs repo) |
 | SAML | Missing | Zero support |
 | SCIM / Directory Sync | Missing | No provisioning |
-| Audit Logs | Missing | Webhooks only, no queryable audit trail |
+| Audit Logs | Partial | Structured AuditLog + audit provider exist (single actor); needs delegation-chain fields for agents — see specs/AGENTIC_DELEGATION_DESIGN.md (authorizer-docs repo) |
 | Bot Detection | Missing | No CAPTCHA, no fingerprinting |
 | Monitoring / Metrics | Missing | Health check only, no Prometheus |
 | MCP Auth | Missing | No OAuth 2.1 AS capabilities |
@@ -328,6 +328,40 @@ These are table-stakes features that every competitor has. Without them, Authori
 
 ---
 
+## Agentic Authorization Track (cross-phase sequencing)
+
+> A re-sequencing lens over the items above, ordered by dependency for enterprise + agentic auth. Authorization for agents is a **pipeline**, not one feature; each wave builds on the last. ReBAC is necessary but not sufficient. Design detail: `../authorizer-docs/specs/FGA_OPENFGA_MIGRATION_PLAN.md`, `../authorizer-docs/specs/AGENTIC_DELEGATION_DESIGN.md`.
+
+**The pipeline (evaluated per request):** Identity → Authentication → Token/Delegation → Authorization (scope → RBAC → ReBAC → ABAC → list_objects) → Human-in-the-loop → Governance.
+
+### Wave 1 — Decision core *(now; replaces 2.1)*
+Object-level authorization + the RAG primitive.
+- [ ] **OpenFGA ReBAC engine** (replaces Resource/Scope/Policy/Permission) — `Check`, `list_objects`, `batch_check`, Conditions (ABAC). SQL-backed FGA store (embedded default / external optional).
+- [ ] **Keep & integrate** OAuth scopes (coarse gate), RBAC roles (optionally mirrored as tuples), custom-token-script hook (may call FGA).
+- [ ] **FGA-for-RAG** SDK helpers (`list_objects` pre-filter) in authorizer-go / authorizer-js.
+- *Unlocks:* document sharing, hierarchical/B2B authz, secure RAG retrieval.
+
+### Wave 2 — Delegation core *(next; folds in 2.2, 4.2, 4.3, 5.5)*
+Who is asking, with whose borrowed authority, constrained to what.
+- [ ] **Agent identity** — agents as first-class service-account principals (4.2).
+- [ ] **RFC 8693 token exchange** + **`act` delegation claim** (5.5 / 4.2) — see design doc.
+- [ ] **Attenuation / least-privilege** — exchanged-token scope = `subject ∩ requested ∩ agent ceiling` (reuses `Principal.MaxScopes`) (4.3).
+- [ ] **Audit delegation chain** — `on_behalf_of` + `act` chain on AuditLog (all DBs).
+- *Unlocks:* "agent acting for user, least-privilege, fully audited."
+
+### Wave 3 — Async + credential custody
+Human approval and safe third-party access.
+- [ ] **CIBA + Rich Authorization Requests (RAR)** — out-of-band human approval for sensitive agent actions.
+- [ ] **Token Vault** — encrypted per-user third-party token custody; agent never sees raw credentials.
+- *Unlocks:* human-in-the-loop, agents calling Google/Slack/etc. on a user's behalf.
+
+### Wave 4 — Enterprise hardening
+- [ ] **MCP authorization** (OAuth 2.1 + RFC 9728 + RFC 8707) (4.1) and **ID-JAG / Cross-App Access** for enterprise-managed MCP.
+- [ ] **JIT / time-bound grants** (TTL tuples), **per-agent guardrails** (spend/rate limits), **consent management**.
+- *Unlocks:* enterprise-managed agent deployments at scale.
+
+---
+
 ## Phase 5: Advanced Security & Enterprise (Q2-Q3 2027)
 
 ### 5.1 Passkeys / WebAuthn

cmd/root.go

@@ -15,12 +15,12 @@ import (
 
 	"github.com/authorizerdev/authorizer/internal/audit"
 	"github.com/authorizerdev/authorizer/internal/authenticators"
-	"github.com/authorizerdev/authorizer/internal/authorization"
+	"github.com/authorizerdev/authorizer/internal/authorization/engine"
+	fgaengine "github.com/authorizerdev/authorizer/internal/authorization/engine/openfga"
 	"github.com/authorizerdev/authorizer/internal/config"
 	"github.com/authorizerdev/authorizer/internal/constants"
 	"github.com/authorizerdev/authorizer/internal/email"
 	"github.com/authorizerdev/authorizer/internal/events"
-	"github.com/authorizerdev/authorizer/internal/graph/model"
 	"github.com/authorizerdev/authorizer/internal/http_handlers"
 	"github.com/authorizerdev/authorizer/internal/memory_store"
 	"github.com/authorizerdev/authorizer/internal/metrics"
@@ -237,10 +237,12 @@ func init() {
 	// Back-channel logout (OIDC BCL 1.0)
 	f.StringVar(&rootArgs.config.BackchannelLogoutURI, "backchannel-logout-uri", "", "URL to POST a signed logout_token to when users log out successfully. Leave empty (default) to disable back-channel logout notifications. See OIDC Back-Channel Logout 1.0.")
 
-	// Fine-grained authorization flags
-	f.Int64Var(&rootArgs.config.AuthorizationCacheTTL, "authorization-cache-ttl", 300, "Cache TTL in seconds for permission checks (0 to disable)")
-	f.BoolVar(&rootArgs.config.IncludePermissionsInToken, "include-permissions-in-token", false, "Include permissions in JWT access tokens")
-	f.BoolVar(&rootArgs.config.AuthorizationLogAllChecks, "authorization-log-all-checks", false, "Audit log all permission checks, not just denials")
+	// OpenFGA fine-grained authorization. By default FGA reuses the main database
+	// when it is sqlite/postgres/mysql/mariadb (no extra config needed). These
+	// flags override that — required only when the main DB is unsupported
+	// (mongodb, dynamodb, …) or to use a dedicated FGA store.
+	f.StringVar(&rootArgs.config.FGAStore, "fga-store", "", "Override the OpenFGA datastore: 'sqlite', 'postgres', 'mysql', or 'memory' (dev). Default: reuse the main database when it is SQL-compatible; required only for unsupported main DBs (mongodb, dynamodb, …)")
+	f.StringVar(&rootArgs.config.FGAStoreURL, "fga-store-url", "", "Connection URI for an overridden --fga-store (file: URI for sqlite, DSN for postgres/mysql). Ignored when FGA reuses the main database")
 
 	// Deprecated flags
 	f.MarkDeprecated("database_url", "use --database-url instead")
@@ -462,34 +464,51 @@ func runRoot(c *cobra.Command, args []string) {
 	}
 	defer rateLimitProvider.Close()
 
-	// Authorization provider
-	authorizationProvider, err := authorization.New(
-		&authorization.Config{
-			CacheTTL: rootArgs.config.AuthorizationCacheTTL,
-		},
-		&authorization.Dependencies{
-			Log:                 &log,
-			StorageProvider:     storageProvider,
-			MemoryStoreProvider: memoryStoreProvider,
-		},
-	)
-	if err != nil {
-		log.Fatal().Err(err).Msg("failed to create authorization provider")
-	}
-
-	// Check once at startup whether any permissions exist. If zero, emit a
-	// loud warn so operators don't lock themselves out in prod. Bounded
-	// context prevents a hung DB at boot from blocking startup indefinitely.
-	probeCtx, probeCancel := context.WithTimeout(context.Background(), 5*time.Second)
-	_, pr, lerr := storageProvider.ListPermissions(probeCtx, &model.Pagination{Limit: 1, Page: 1})
-	probeCancel()
-	switch {
-	case lerr != nil:
-		log.Warn().Err(lerr).Msg("authz: failed to probe permission count at startup; authorization is enforcing")
-	case pr != nil && pr.Total == 0:
-		log.Warn().Msg("authz: 0 permissions configured — all authorization checks will DENY. Seed permissions via the dashboard or admin GraphQL mutations.")
-	default:
-		log.Info().Msg("authz: enforcing; unmatched CheckPermission calls will be DENIED.")
+	// OpenFGA fine-grained authorization engine (embedded, in-process).
+	//
+	// Authorizer embeds OpenFGA — it IS the engine. The engine is constructed
+	// only when an FGA store is configured (--fga-store); otherwise it stays nil
+	// and the fga_* resolvers fail closed ("fine-grained authorization is not
+	// enabled"). Routed into GraphQL and session/validate below.
+	//
+	// By default FGA reuses the main database (sqlite/postgres/mysql/mariadb);
+	// --fga-store is only needed when the main DB is unsupported (mongodb,
+	// dynamodb, etc.) or to point at a dedicated store. FGAStoreConfig() resolves
+	// this. OpenFGA migrations run on boot for SQL stores (idempotent); memory
+	// needs none. NOTE: multi-replica deployments should prefer running
+	// migrations once via an init job — concurrent on-boot migrations rely on
+	// the migration tool's own locking and add cold-start latency.
+	//
+	// Engine-init failure is deliberately NON-fatal: FGA is an optional
+	// subsystem, so a failure here (e.g. the DB user lacks DDL rights for the
+	// OpenFGA tables) logs loudly and leaves authzEngine nil — fga_* and the
+	// permission APIs fail closed while core authentication keeps serving.
+	var authzEngine engine.AuthorizationEngine
+	if fgaStore, fgaStoreURL, fgaEnabled := rootArgs.config.FGAStoreConfig(); fgaEnabled {
+		runMigrations := !strings.EqualFold(fgaStore, fgaengine.StoreMemory)
+		fgaEngine, ferr := fgaengine.New(
+			&fgaengine.Config{
+				Store:         fgaStore,
+				StoreURL:      fgaStoreURL,
+				StoreName:     rootArgs.config.OrganizationName,
+				RunMigrations: runMigrations,
+			},
+			&fgaengine.Dependencies{Log: &log},
+		)
+		if ferr != nil {
+			log.Error().Err(ferr).
+				Str("fga_store", fgaStore).
+				Msg("failed to initialize OpenFGA authorization engine; fine-grained authorization is DISABLED (fail-closed) — core auth continues")
+		} else {
+			if closer, ok := fgaEngine.(interface{ Close() }); ok {
+				defer closer.Close()
+			}
+			authzEngine = fgaEngine
+			log.Info().
+				Str("fga_store", fgaStore).
+				Bool("reused_main_db", strings.TrimSpace(rootArgs.config.FGAStore) == "").
+				Msg("OpenFGA authorization engine initialized (embedded); routed into GraphQL + session/validate")
+		}
 	}
 
 	// SMS provider
@@ -542,7 +561,7 @@ func runRoot(c *cobra.Command, args []string) {
 		TokenProvider:         tokenProvider,
 		OAuthProvider:         oauthProvider,
 		RateLimitProvider:     rateLimitProvider,
-		AuthorizationProvider: authorizationProvider,
+		AuthzEngine:           authzEngine,
 	})
 	if err != nil {
 		log.Fatal().Err(err).Msg("failed to create http provider")