feat(router): expand signed authorization roles

CHANGELOG.md

@@ -14,6 +14,19 @@ This file is the authoritative user-facing release chronology. The former
 [release-notes ledger](docs/archive/2026/graphql-orm-release-notes.md) is retained
 for historical context.
 
+## 0.25.0 - 2026-08-22
+
+Companion macros crate: `graphql-orm-macros` **0.25.0**. Generated ORM and
+database behavior are unchanged.
+
+- Aligned the optional `auth-agql` bridge to `agql-auth` 0.17.0 at merged full
+  revision `82650a447f3b6875160254fa1293b3a0e305c224` so hosts share the neutral
+  role-scope catalogue and principal type universe.
+- The bridge projection, assurance evaluation, database policy, schema, and
+  generated resolver behavior are unchanged.
+- The companion macro version remains aligned as required by the workspace
+  release contract; its emitted code and public behavior are unchanged.
+
 ## 0.24.0 - 2026-08-22
 
 Companion macros crate: `graphql-orm-macros` **0.24.0**. Generated ORM and

Cargo.toml

@@ -27,7 +27,7 @@ license = "MIT"
 repository = "https://github.com/Dastari/graphql-orm"
 
 [workspace.dependencies]
-agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "3bc38cd94794f1e868a9cc3a5551047b95a32105", version = "0.16.0" }
+agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "82650a447f3b6875160254fa1293b3a0e305c224", version = "0.17.0" }
 arc-swap = "1.7"
 async-graphql = { version = "7", features = ["dataloader", "uuid"] }
 async-graphql-parser = "7"
@@ -37,7 +37,7 @@ cynic-parser = { version = "=0.11.2", features = ["pretty"] }
 futures = "0.3"
 getrandom = "0.3"
 graphql-composition = "=0.12.2"
-graphql-orm = { path = "crates/graphql-orm", version = "0.24.0", default-features = false }
+graphql-orm = { path = "crates/graphql-orm", version = "0.25.0", default-features = false }
 graphql-orm-ai-tool-profiles = { path = "crates/graphql-orm-ai-tool-profiles", version = "0.9.0" }
 graphql-orm-backup = { path = "crates/graphql-orm-backup", version = "0.7.1", default-features = false }
 graphql-orm-operation-catalog = { path = "crates/graphql-orm-operation-catalog", version = "0.3.0" }

MIGRATION.md

@@ -13,6 +13,15 @@ supersedes: []
 `graphql-orm` is distributed from GitHub only. Use a reviewed full 40-character commit in `rev`;
 neither the runtime nor macros crate is published to crates.io.
 
+## 0.24.0 to 0.25.0: agql-auth 0.17 alignment
+
+Git consumers using `auth-agql` must align direct `agql-auth` dependencies to
+0.17.0 at merged revision `82650a447f3b6875160254fa1293b3a0e305c224`.
+The role-scope expansion contract is additive and opt-in; the ORM bridge does
+not fetch catalogues or change authorization decisions. No schema, migration,
+generated code, or database-policy change is required. Adopt aligned
+`graphql-orm` and `graphql-orm-macros` 0.25.0 from the same reviewed revision.
+
 ## 0.23.0 to 0.24.0: agql-auth 0.16 alignment
 
 Hosts enabling `auth-agql` or depending directly on `agql-auth` must align to

README.md

@@ -42,12 +42,12 @@ schema changes explicitly.
 
 Packages are distributed from this repository, not crates.io. Pin the reviewed
 release revision, not a moving branch or tag. The current coordinated
-`graphql-orm` version is 0.23.0. Replace the placeholder below with the final
+`graphql-orm` version is 0.25.0. Replace the placeholder below with the final
 reviewed full SHA for the release:
 
 ```toml
 [dependencies]
-graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
+graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.25.0", default-features = false, features = ["sqlite"] }
 ```
 
 Choose exactly the backend support needed by each service. Cargo can unify

crates/graphql-orm-ai/CHANGELOG.md

@@ -18,6 +18,18 @@ checkpoint facts. For the current workspace baseline and active gates, use the
 [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## [0.90.0] - 2026-08-22
+
+Persistent schema module: **0.63.0** (unchanged from 0.89.0).
+
+### Changed
+
+- Aligned the public `agql-auth` type universe to 0.17.0 at merged revision
+  `82650a447f3b6875160254fa1293b3a0e305c224`. Consumers using the AI prelude's
+  re-exported principal types must resolve the same full revision.
+- AI authorization, principal rehydration, providers, persistence, GraphQL SDL,
+  backup, and restore behavior are unchanged.
+
 ## [0.89.0] - 2026-08-22
 
 Persistent schema module: **0.63.0** (unchanged from 0.88.0).

crates/graphql-orm-ai/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-ai"
-version = "0.89.0"
+version = "0.90.0"
 edition = "2024"
 authors = ["Toby Martin <toby@dastari.net>"]
 description = "Project-agnostic AI agent runtime for graphql-orm applications"

crates/graphql-orm-ai/MIGRATION.md

@@ -19,6 +19,14 @@ they describe. For the current workspace baseline and active delivery gates,
 use [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## 0.89.0 to 0.90.0: agql-auth 0.17 type-universe alignment
+
+Adopt `graphql-orm-ai` 0.90.0 from one reviewed full monorepo revision and
+align every direct `agql-auth` dependency to version 0.17.0 at merged revision
+`82650a447f3b6875160254fa1293b3a0e305c224`. The change is dependency-only for
+the AI crate; no schema, data, provider, backup, restore, or runtime migration
+is required.
+
 ## 0.88.0 to 0.89.0: agql-auth 0.16 type-universe alignment
 
 Adopt `graphql-orm-ai` 0.89.0 from one reviewed full monorepo revision and

crates/graphql-orm-ai/README.md

@@ -28,7 +28,7 @@ for AI, ORM, storage, backup, and tool-profile packages:
 
 ```toml
 [dependencies]
-graphql-orm-ai = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.89.0", default-features = false, features = ["sqlite"] }
+graphql-orm-ai = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.90.0", default-features = false, features = ["sqlite"] }
 ```
 
 Exactly one persistence backend is required: `sqlite` (default), `postgres`,

crates/graphql-orm-ai/docs/implementation-status.md

@@ -10,10 +10,10 @@ supersedes: []
 
 # Implementation Status
 
-`graphql-orm-ai` is at crate version `0.89.0` with AI schema module
-`0.63.0`. It uses workspace `graphql-orm` `0.24.0`, backend-neutral
+`graphql-orm-ai` is at crate version `0.90.0` with AI schema module
+`0.63.0`. It uses workspace `graphql-orm` `0.25.0`, backend-neutral
 `graphql-orm-ai-tool-profiles` `0.9.0`, and external `agql-auth`
-`0.16.0` at `3bc38cd94794f1e868a9cc3a5551047b95a32105`.
+`0.17.0` at `82650a447f3b6875160254fa1293b3a0e305c224`.
 
 Completed stateless local-provider turns can carry a proof-bearing contained
 native-item refusal after authoritative usage settlement. Those runs close as

crates/graphql-orm-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-macros"
-version = "0.24.0"
+version = "0.25.0"
 edition = "2024"
 authors = ["Toby Martin"]
 description = "Procedural macros for async-graphql and ORM-backed entities, relations, and CRUD operations."

crates/graphql-orm-macros/README.md

@@ -16,13 +16,13 @@ macro/runtime versions aligned:
 
 ```toml
 [dependencies]
-graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
+graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.25.0", default-features = false, features = ["sqlite"] }
 ```
 
 Direct use is supported for tooling that needs the macro package:
 
 ```toml
-graphql-orm-macros = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
+graphql-orm-macros = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.25.0", default-features = false, features = ["sqlite"] }
 ```
 
 The direct dependency still requires a compatible `graphql-orm` runtime in the

crates/graphql-orm-router/CHANGELOG.md

@@ -10,6 +10,23 @@ supersedes: []
 
 # Changelog
 
+## 0.3.0 - 2026-08-22
+
+- Added optional strict `authentication.roleScopeCatalogue` configuration for
+  a bounded, signed, versioned role-to-scope catalogue fetched alongside JWKS.
+- Access-token roles are validated and expanded through the neutral
+  `agql-auth` 0.17.0 provider contract. Expanded scopes are unioned with direct
+  scopes before the existing preflight matcher runs.
+- Initial retrieval, signature/key/issuer/audience/purpose binding, catalogue
+  structure, and lifetime are mandatory before readiness. Failed refresh keeps
+  a still-current complete snapshot; role-bearing credentials fail closed once
+  it is stale or expired. Direct-scope-only credentials remain independent.
+
+No membership, role name, scope value, private key, issuer endpoint, or cache
+authority is supplied by the router. Resolver authorization remains
+authoritative. Omission preserves 0.2.0 behavior; the optional catalogue
+requires the `auth-agql` feature.
+
 ## 0.2.0 - 2026-08-22
 
 - Added strict `scopeMatcher` file configuration. Omission and `kind: exact`

crates/graphql-orm-router/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-router"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.90"
 description = "Federated GraphQL router for graphql-orm and project-neutral subgraphs"

crates/graphql-orm-router/MIGRATION.md

@@ -10,6 +10,26 @@ supersedes: []
 
 # graphql-orm-router migration guide
 
+## 0.2.0 to 0.3.0
+
+Align direct `agql-auth` consumers to 0.17.0 at the reviewed full revision.
+Existing configurations remain unchanged when `roleScopeCatalogue` is omitted.
+
+To adopt compact role grants, first publish a signed
+`agql_auth::SignedRoleScopeCatalogue`, then build the router with `auth-agql`
+and configure `authentication.roleScopeCatalogue` with its HTTPS URL, exact
+signature audience, cache TTL, and body limit. The authentication refresh
+interval must be shorter than the catalogue TTL. Run `--check` while the
+catalogue and JWKS endpoints are available; initial verification is a readiness
+gate.
+
+Only after every resource server expands the same verified role IDs should an
+issuer remove expanded scopes from access tokens. A role-bearing token is
+denied when the catalogue is absent, forged, expired, stale, or invalid. A
+failed refresh preserves a still-current snapshot. Roll back by restoring
+expanded scope issuance and removing `roleScopeCatalogue` after all compact
+tokens expire.
+
 ## 0.1.4 to 0.2.0
 
 Replace the reviewed full-revision pin and rebuild the router. Hosts that also

crates/graphql-orm-router/README.md

@@ -26,7 +26,7 @@ This unpublished package is Git-only:
 
 ```toml
 [dependencies]
-graphql-orm-router = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.2.0" }
+graphql-orm-router = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.3.0" }
 ```
 
 Enable `auth-agql` only when adapting a separately configured
@@ -67,7 +67,7 @@ composition warnings before serving.
 
 | Surface | Default or boundary |
 | --- | --- |
-| Authentication | Fail-closed; anonymous mode is explicit development-only. |
+| Authentication | Fail-closed; optional signed role expansion requires `auth-agql`. |
 | Scope matching | Exact by default; hierarchical matching requires `auth-agql` and explicit file or programmatic configuration. |
 | Public path | `/graphql`; `/health` and `/readiness` are also exposed. |
 | Subgraphs | At least one static source; file configuration requires strict JSON. |

crates/graphql-orm-router/docs/configuration.md

@@ -43,6 +43,7 @@ The public field-level source contracts are:
 | [`RouterTelemetryConfig`](../src/config.rs) | Log and optional Prometheus listener settings. |
 | [`AdminConfig`](../src/config.rs) | Separate authenticated administration listener and scopes. |
 | [`JwksAuthenticationConfig`](../src/jwt.rs) | RS256 public-key verification, issuer/audience, cache, and bounded JWKS fetch. |
+| [`RoleScopeCatalogueConfig`](../src/jwt.rs) | Optional signed role-to-scope catalogue retrieval and cache bounds. |
 | [`NetworkPolicy`](../src/network.rs) | Dynamic destination host/port/CIDR/DNS policy. |
 | [`RouterFileConfig`](../src/file_config.rs) | Strict file representation and environment-secret mapping. |
 
@@ -86,6 +87,21 @@ array. JWKS uses HTTPS. Plain HTTP is accepted only for loopback when
 `cacheTtlSeconds`, `refreshIntervalSeconds`, `requestTimeoutMs`,
 `maxJwksBytes`, and `leewaySeconds`. `acceptLegacyScopes` defaults false.
 
+`roleScopeCatalogue` is optional and requires `auth-agql`. It accepts `url`,
+`audience`, `cacheTtlSeconds`, `maxBodyBytes`, and
+`allowInsecureLoopbackHttp`. Its URL is HTTPS-only except for explicit
+loopback development, has no credentials/query/fragment, and uses the
+authentication request timeout and refresh interval. The refresh interval must
+be shorter than the catalogue TTL. Startup verifies the RS256 signature with
+the JWKS cache and binds the exact catalogue, issuer, audience, purpose, and
+signed lifetime before readiness.
+
+When configured, well-formed token roles expand through the current verified
+catalogue and are unioned with direct token scopes. Unknown roles grant
+nothing. Role-bearing credentials fail closed when no current verified
+catalogue exists; direct-scope-only credentials do not depend on that optional
+authority source.
+
 The router validates RS256 public keys only. Configuration has no private-key,
 token-signing, session, refresh-token, or RSA-decryption field.
 

crates/graphql-orm-router/examples/router.example.json

@@ -6,7 +6,13 @@
     "issuer": "https://identity.example",
     "audiences": ["graphql-router"],
     "refreshIntervalSeconds": 300,
-    "cacheTtlSeconds": 900
+    "cacheTtlSeconds": 900,
+    "roleScopeCatalogue": {
+      "url": "https://identity.example/auth/catalogue",
+      "audience": "graphql-resource-servers",
+      "cacheTtlSeconds": 900,
+      "maxBodyBytes": 1048576
+    }
   },
   "scopeMatcher": {
     "kind": "exact"