graphql-armory 0.1.0.pre8 → 0.1.0.pre9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4d5727b97311ff099b347c1e06cfbf1ec425a03c6018c1385ec557d8a31fef5
-  data.tar.gz: 78015ec70e63fded090bfbebca21328792a0285f555f11f66e25e4c5b094f675
+  metadata.gz: 3200e9b549bc6bb3b7f77d1905fb79a9d41b59d4730452300437572b4c7cdfe3
+  data.tar.gz: 3653d86878c2395602ac78e48f70266cc89ea42d0f393eb122542e958466e36a
 SHA512:
-  metadata.gz: fcfd1948d727ccfd827c9acefdc76e78ee14e64e01d72fea83d3c367674af1cb3e302c2728b170a8561677d1c6b79ecd20723c639dde2ef9d46fa7b96c577927
-  data.tar.gz: a519a7cf57c9650c7d08965e51a3829fe9860ef31e1ad2bf78f29ca91810a704f7fdb662cfdf390f1efedea1932bd1bafbe1faced26c7deb6323e5eca009640f
+  metadata.gz: aa7fbc795c731c4f11cd8e6a002b3178f377ef97caa1669771b8a641a7a2860a9fdf49525f49d25fcb0eaced66901cace0b74bb8acfe05918f456421bbc4d0e6
+  data.tar.gz: c828ed91f9bd66f7856d603e33f8e44ce875861be873061e4ae016b9b6b3714bb6daeb0001a8862fef1c9b21134a7c80476ec861f18dee25a015bf67218bcb7c

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.0.pre9 (2026-11-02)
+
+This release is about adopting the gem on a real schema, and about limits that hold when a client tries to get around them. An existing app can now [observe a new rule](docs/authorization.md) before enforcing it and keep the audit green on known problems with a baseline; persisted queries can be published without a server deploy and from several manifests ([persisted queries](docs/persisted-queries.md)); and [rate limits](docs/rate-limiting.md) take several keys per query, against clients that rotate one identity. Anyone running the audit or rate limits in hard mode should read Breaking and Security before upgrading.
+
+### Breaking
+
+- An audit that passed can fail after upgrading, because it reports more: see the entries under Security and the audit entry under Fixed. Read each new problem instead of declaring it to get the build green; a baseline can hold them while you work through them. (#42, #44)
+- In hard mode, a query whose rate limiter cannot answer, because a `complexity:` lambda or an `on_store_error` hook raised `ExecutionError`, is now refused with `RATE_LIMIT_NOT_CHARGED`. It used to run uncharged. Stop raising from those, or use soft mode while you do. (#46)
+- In strict mode, a `GraphQL::Query` built by your own code, for example in `multiplex`, is now refused unless its context holds `armory_allow_raw_query: true`. It used to run any query, because it skips the plugin's query class. Add the flag where your code builds queries on purpose. Outside strict mode it now records `:raw_query_run`. (#32)
+- A sink that raises no longer takes the request down: the gem's decision stands, the next sink runs, and the new `on_sink_error:` is called, which by default warns with the signal and the error's class. A monitoring failure used to become an API failure. If a record must exist before data is served, raise from `on_sink_error:` to fail closed as before. A sink's `Encoder::InvalidError` is no longer read as a forged ID. (#29)
+- A sink that could never be called, such as `->(a) {}`, now raises `Telemetry::ConfigurationError` at boot. It used to fail on the first request. (#29)
+
+### Added
+
+- Several keys per query, against clients that rotate one identity: `rate_limit_key` or `key:` may answer a list of up to 5 different Strings, for example `["user:1", "ip:1.2.3.4"]`, on `Points`, `Concurrency` and `Time`. A query runs only if every key allows it, and each is charged. It costs about two store round trips per key. Two queries racing between the read and the charge can leave a refused one having charged other keys. A key whose store fails is left out and `on_store_error` is called for it; the others still decide. A single String behaves as before. See [Clients that change identity](docs/rate-limiting.md#clients-that-change-identity). (#40)
+- Observation mode, to learn who a new rule would refuse before enforcing it: `authorize :read, observe: "why"` on a type, or `authorize: :manage, observe: "why"` on a field. On a query, what the policy refuses is served and recorded as an `:observed` signal. It refuses as usual with no `sinks:`, with the null adapter, or in a mutation or subscription, and a type holding a field with a resolver or a mutation raises `ConfigurationError` instead of being observed; lists of object types and lookups still go through the scope, but a list with no scope (an interface, a union, `scope: false`, `nodes(ids:)`) serves its rows and records them. The audit reports each one as `:observed`, and a baseline cannot accept it. See [Observing a rule](docs/authorization.md#observing-a-rule-before-enforcing-it). (#35)
+- Audit baseline, for adopting the gem on a schema with many problems: `rake "graphql_armory:audit_baseline[AppSchema,path]"` records them, then `rake "graphql_armory:audit[AppSchema,path]"` and `be_fully_authorized(baseline: path)` fail only on new problems, on an accepted one that grew (a field added to that type, a type added under that base class), or on an accepted one that is gone. The file only ever shrinks unless edited by hand, every accepted problem stays listed, and `report.ok?` never changes because of it. A baseline protects nothing: those problems are still open. (#34)
+- `PersistedQueries::RedisStore` and `Publisher` publish operations without a server deploy, for frontends that deploy on their own: their CI runs `graphql-armory-publish manifest.json` before the deploy, and the server reads each operation when first asked. An operation it read keeps working when Redis fails; an id it cannot find or check is refused. A published operation never changes. There is no endpoint: whoever can write to those keys decides what strict mode allows, so give the CI its own credential. The app adds the `redis` gem. (#33)
+- `PersistedQueries::Manifests` puts several manifests behind one `store:`, for several frontends and mobile versions still in use: `Manifests.build("config/persisted_queries/*.json")`. It raises at boot when a pattern matches nothing or two manifests disagree on an id. They are one allowlist, and a new manifest still needs a deploy. (#31)
+- `PersistedQueries.operation_id` now reads Relay's `doc_id`, so Relay clients need no change to send their id. (#30)
+- The Pundit and CanCanCan adapters take `user_key:`, for an app whose context holds the user under another key: `Adapters::Pundit.new(user_key: :viewer)`. It used to take a subclass. (#30)
+- In Rails, `rake graphql_armory:audit[YourSchema]` now loads by itself, through a Railtie that loads only when Rails is there. The task now runs the app's `:environment` when it runs, not only when it was defined before the task, so clearing the task's prerequisites no longer skips it. An adapter subclass with its own `initialize` must call `super`: without it, nobody has a user and everyone is denied. (#30)
+- A sink that requires three arguments now receives the query's context: `->(signal, data, context) { ... }`. It tells who was refused without a request-global. It reads through a view that cannot write to the context. Sinks of two arguments, `*arguments` or a defaulted third are unchanged and never receive it. (#29)
+- A persisted queries refusal now carries `extensions.code`: `RAW_QUERY_REFUSED`, `UNKNOWN_OPERATION` or `OPERATION_MISMATCH`, so an app can match on it instead of on the message. (#29)
+- Rate limiters take `sinks:` and record `:rate_limit_store_failed`, with the limiter and the error's class, when the store fails. A failing store used to reach only `on_store_error:`, or stderr. The query still runs. (#29)
+
+### Fixed
+
+- `Points` and `Time` on one store and one key shared a bucket, as the docs recommend: a query taking 300 ms spent the client's points, and each limiter capped and refilled the balance with its own limit. `Time` now keeps its milliseconds under `time:<key>`, read with `Time.bucket_key(key)`. On upgrading, `Time` balances start full once; `Points` keeps its key, so a balance the mix drained recovers as it refills, within one window. Tools or custom stores that read `Time`'s bucket by the client's key must use the new key. Two limiters of the same class on one store and key still share a bucket: give each its own store or keys. (#43)
+- A payload field declared on a parent mutation with no rule, or on a mutation with `authorize :none` and no `covers_fields`, is denied while the mutation still runs, so the client read null after a write. It stays denied, and the audit now reports it as `:field_without_rule`. (#42)
+- With `Points`, a connection asked for with no `first:` or `last:` on a schema with no page size was a server error any client could cause. It is now refused with `This connection needs first: or last:` (code `PAGE_SIZE_REQUIRED`), and charges nothing. Set `default_max_page_size`. A schema with `max_complexity` still gets graphql-ruby's error. (#41)
+- A schema using `Concurrency` twice kept only the last limiter's slot for a query, so the other leaked until `stale_after`. (#40)
+- When an object's check raised and a `rescue_from` answered true, graphql-ruby served the object. The handler still runs, and the object is denied. (#29)
+- The rate limiters' default warning no longer prints the store error's message, which could hold a password. (#29)
+
+### Security
+
+- An `ExecutionError` raised during analysis, by another analyzer or by a `complexity:` lambda, made `Points`, `Time` and `Concurrency` skip the query or lose a refusal already given, and a client could choose that by field order. Each limiter now still decides. **Upgrading:** in hard mode, a query whose limiter cannot answer, because a `complexity:` lambda or an `on_store_error` hook raised, is refused with the code `RATE_LIMIT_NOT_CHARGED` instead of running. Soft mode runs it and records `charged: false` in the limiter's context record. Limit: a trace that takes no modules from the schema (`context[:trace]`, a class given to `trace_mode`) is not covered. (#46) Docs: [rate limiting](docs/rate-limiting.md#guarantees-and-limits).
+- A resolver, mutation or subscription with no `Base`, on a type with `covers_fields`, was served to anyone while the audit said ok, because the declaration read as covering it and no rule ran. The audit now reports it as `:unprotected`. To fix it, include `Base` and declare `authorize`, or declare `authorize: :none, reason: "..."` on the field. A schema that had this shape fails the audit after upgrading; a plain read that answers a type with a rule is not reported, because that type refuses. Limit: a plain method field under `covers_fields` stays served and listed by its type. Runtime does not change. (#44)
+- A field returning a mutation's payload, without being that mutation, served the payload's fields with no rule run while the audit said ok. The audit now reports it as `:payload_outside_mutation`, as well as a public mutation inheriting fields from a parent with a rule, so a schema that passed may now fail. The runtime does not change: return a type of its own, or give the parent's field `authorize: :none, reason: "..."`. (#42)
+
+### Docs
+
+- Limits named for rate limits (`max_depth` lost when an analyzer raises, `validate: false` on `Execution::Next`, `max_page_size: nil`, a query `Time` refuses still charged by `Points`, a multiplex analyzer raising), the audit (`authorize: false` with a resolver with no `Base`, another resolver at a path a baseline accepts) and persisted queries (graphql before 2.6 with json 3.1). (#47)
+
 ## 0.1.0.pre8 (2026-10-31)
 
 This release is about [authorization](docs/authorization.md): the audit now follows every definition of the types it reaches from the schema's roots, `orphan_types` and what they reference, whether or not `visible?` hides them (the limits are in the module page), and Pundit judges a record by both the declared model's policy and its own class's. Read it if you run the audit in CI or rely on Pundit reading `policy_class` from an instance: rules that were silently skipped now show up, so an audit that passed can fail after upgrading, and each new problem names what to do.

data/README.md

@@ -6,12 +6,12 @@
 
 Open-source extensions for [graphql-ruby](https://github.com/rmosolgo/graphql-ruby), built on its public extension points: no fork, no monkey patching. One gem, one module at a time; each module has its own page in [`docs/`](docs) with the problem it solves, how to use it, and its limits.
 
-> **Status: early development.** Prereleases on RubyGems (`0.1.0.pre8`). The API may change before 1.0.
+> **Status: early development.** Prereleases on RubyGems (`0.1.0.pre9`). The API may change before 1.0.
 
 ## Install
 
 ```ruby
-gem "graphql-armory", "~> 0.1.0.pre8"  # a prerelease: `gem install graphql-armory --pre`
+gem "graphql-armory", "~> 0.1.0.pre9"  # a prerelease: `gem install graphql-armory --pre`
 gem "pundit"      # or "cancancan", for the authorization module
 ```
 
@@ -25,7 +25,7 @@ Status: ✅ released, 🚧 in progress, ⬜ not started. Update this table in th
 |---|---|---|---|---|
 | 1 | Authorization (Pundit, CanCanCan) | ✅ | [docs/authorization.md](docs/authorization.md) | Released in 0.1.0.pre2 (prerelease). Pundit and CanCanCan (the audit checks less with CanCanCan). Global IDs in `loads:` decoded through `object_from_id`; `loads:` inside input objects scoped with `include Base`. `Execution::Next` needs graphql >= 2.6.2. |
 | 2 | Encrypted, versioned IDs and cursors | ✅ | [docs/encrypted-ids.md](docs/encrypted-ids.md) | Released in 0.1.0.pre4 (prerelease). `Encoder` (AES-256-GCM), versioned chains and `Legacy`, `Encoder.default` (ENV or Rails), `use GraphQL::Armory::IDs`. Composite primary keys not supported. |
-| 3 | Persisted queries / operation allowlist | ✅ | [docs/persisted-queries.md](docs/persisted-queries.md) | Released in 0.1.0.pre4 (prerelease). Allowlist from a build manifest (Apollo, Relay), `use GraphQL::Armory::PersistedQueries` with strict mode. A runtime store (database, sync endpoint) is planned for later. |
+| 3 | Persisted queries / operation allowlist | ✅ | [docs/persisted-queries.md](docs/persisted-queries.md) | Released in 0.1.0.pre4 (prerelease). Operations can be published without a server deploy (`RedisStore`, unreleased). Allowlist from a build manifest (Apollo, Relay), `use GraphQL::Armory::PersistedQueries` with strict mode. A runtime store (database, sync endpoint) is planned for later. |
 | 4 | Rate limiting | ✅ | [docs/rate-limiting.md](docs/rate-limiting.md) | Released in 0.1.0.pre5 (prerelease); `RateLimits::Time` in 0.1.0.pre6. Points per client (query complexity) and operations at the same time, `MemoryStore` and `RedisStore`, the budget in response extensions and headers. `RateLimits::Time` charges the wall-clock milliseconds operations take. |
 | 5 | Stable (keyset) connections | ✅ | [docs/keyset-connections.md](docs/keyset-connections.md) | Released in 0.1.0.pre7 (prerelease). `Keyset.build(relation)` per resolver, ActiveRecord only, plain non-null columns of the relation's own table. Base64 cursors refused unless `plain_cursors: true`. No total count. |
 | 6 | Subscriptions over Pusher / Ably | ⬜ | | Research not started. |
@@ -55,8 +55,8 @@ GRAPHQL_VERSION="~> 2.4.0" docker compose run --rm test         # another graphq
 Releases are published from GitHub Actions with RubyGems Trusted Publishing (`.github/workflows/release.yml`): no API key is stored and no OTP is asked. Bump `GraphQL::Armory::VERSION` and the CHANGELOG on `main`, then push the matching tag:
 
 ```
-git tag -a v0.1.0.pre8 -F <message file> main
-git push origin v0.1.0.pre8
+git tag -a v0.1.0.pre9 -F <message file> main
+git push origin v0.1.0.pre9
 ```
 
 The workflow checks that the tag matches the version, runs the specs and pushes the gem. It only publishes a tag on a commit of `main`. The `release` environment can require a maintainer's approval first (on a public repository, or a private one on a paid GitHub plan).

data/docs/authorization.md

@@ -46,7 +46,16 @@ class AppSchema < GraphQL::Schema
 end
 ```
 
-The actor is `context[:current_user]`. A complete, tested version lives in [`examples/invoices.rb`](../examples/invoices.rb).
+With graphql-ruby's install template, which includes `ConnectionBehaviors` and `EdgeBehaviors` in classes that inherit from your base object, also declare this in `BaseConnection` and `BaseEdge`, or the audit reports them as `:ignored_rule` ([why](#lists-connections-and-lookups)):
+
+```ruby
+class Types::BaseConnection < Types::BaseObject
+  authorize :none, reason: "the field that returns it holds the rule; each node has its own", covers_fields: true
+  include GraphQL::Types::Relay::ConnectionBehaviors
+end
+```
+
+The actor is `context[:current_user]`; for another key, pass `adapter: GraphQL::Armory::Authorization::Adapters::Pundit.new(user_key: :viewer)`. A complete, tested version lives in [`examples/invoices.rb`](../examples/invoices.rb).
 
 ## Rules
 
@@ -115,8 +124,11 @@ A declared check is listed as a bypass. Each method is declared on its own, and
 
 **What the audit does not see.**
 
+- `authorize: false` on a field with a resolver that has no `Base`: the audit says ok, and at runtime the field raises `NoMethodError` and serves nothing. Use `authorize: :none, reason: "..."`.
 - It looks at the classes when it runs, so a method defined later is seen by the next audit.
 - A type no definition leads to. The audit follows the schema's roots, `orphan_types` and what each definition references (fields, arguments, interfaces, union members, a connection's node), not filtering by `visible?`, so types hidden with no request and every definition of a duplicated name are audited. A type that only your own `resolve_type` returns, listed nowhere, is not seen.
+- A resolver with no `Base` in a shared payload type is reported even when every mutation returning it has a rule that refuses first. The audit reads the type and not who returns it. Declare `authorize: :none, reason: "..."` on the field. A resolver with its own refusing `authorized?` is reported too: the audit cannot read that method.
+- A plain field under a type with `covers_fields`, with a method or a `resolver_method:`. The declaration says its fields are public, so the field is served and only the type is listed. A resolver or mutation with no `Base` under that type is reported. A read one that answers a type with a rule, a list or a connection of one, or a union of them, is not, because that type refuses; on a write root it is reported, since it has already run.
 - A missing action on an argument of an input object, when a plain field takes that input object. It raises at runtime instead of serving.
 - A Base resolver on a field class with no `Base`, under a type with a rule: its rule's actions and its arguments are not read. It raises at runtime instead of serving.
 - A missing policy action on a field of a bypassed type. The audit does not ask the policy there, so a misspelled action passes it and raises at runtime instead of serving.
@@ -125,6 +137,42 @@ A declared check is listed as a bypass. Each method is declared on its own, and
 - Code written to get past it. The audit reads the classes, it does not run your methods: a declared alias of a library method, a class of yours named under `GraphQL::`, or a forged `__FILE__` are not caught. The audit protects against mistakes, not against the app's own code.
 - `rescue_from(NotAuthorizedError)`: with `on_unauthorized: :raise`, rescuing is what you are meant to do, so keep that handler's message generic. The interpreter catches field denials there and not object denials, which then raise out of the query; `Execution::Next` catches both.
 
+## Observing a rule before enforcing it
+
+To learn who a new rule would refuse on a schema already in production, name the rule and say why:
+
+```ruby
+class Types::Invoice < Types::BaseObject
+  authorize :read, observe: "rollout of invoices, ticket 123"
+end
+
+field :notes, String, authorize: :manage, observe: "rollout of notes, ticket 124"
+
+use GraphQL::Armory::Authorization, adapter: :pundit,
+  sinks: [->(signal, data) { Rails.logger.info("armory #{signal} #{data}") if signal == :observed }]
+```
+
+When the policy answers `false` or `nil`, **the data is served to a user the rule would refuse**, and an `:observed` signal is recorded in place of `:denied`. Remove `observe:` to enforce the rule. There is no switch for a whole schema: each rule says it, with its reason, and the audit reports each one as `:observed` until it is gone, so `report.ok?` is false and a baseline cannot accept it.
+
+| Case | What happens under `observe:` |
+|---|---|
+| A query, and the policy answers `false` or `nil` | Served, `:observed` recorded |
+| No `sinks:` | Refused: observing with nobody listening is only an open door |
+| `Adapters::Null` | Refused |
+| A policy that raises, is missing, or answers anything else | Raises or refuses, as without `observe:` |
+| A type or field with no rule | Denied: there is no rule to observe |
+| A mutation or a subscription, including a read in its response | Refused: only a query runs |
+| A mutation whose response returns a type that cannot be observed | The mutation's own body has already run when that type raises: its write stands |
+| A type under `observe:` with a field that has a `resolver:` or a `mutation:`, its own, inherited or from an interface; a definition shadowed in a subclass does not count | Raises `ConfigurationError` on every query that reaches the type, and its resolvers do not run: observing the type would open the only check before them, and they can write. Remove `observe:`, or put it on the type's plain fields |
+| The same, on the root type | Runs nothing, but the error depends on the engine: on the interpreter with graphql 2.6, graphql-ruby's own rescue reports a `NoMethodError` caused by the `ConfigurationError`. A `rescue_from` handler can turn it into an empty result, so run the audit, which names the type |
+| `authorize: true` with a resolver, where the type's rule is observed | Raises `ConfigurationError`, after graphql-ruby has coerced the arguments: their `prepare:` has run, as it does before any field's rule |
+| A list of an object type, a `loads:` or a `find_by:` | Still goes through the user's scope, and an in-memory lookup still asks the policy: rows are lost, and nothing is recorded about them |
+| A list with no scope: of an interface or a union, `scope: false`, Relay `nodes(ids:)` | **Served row by row and recorded**: the check on each object is all that protects these lists, and it cannot tell it is inside one. A foreign row reaches the user |
+| `visible_when:` | Still hides: the rule it builds is not observed |
+| `observe:` on a mutation, a resolver, a field that holds either, an argument, a bypass, or a field with no action of its own | Raises `ArgumentError` when declared |
+
+**Limits.** Only a `resolver:` or a `mutation:` counts as something that can write: a plain field's method that writes, or a `prepare:` on its arguments, runs for a refused user, so keep writes in mutations. A sink that raises loses that signal, reported to `on_sink_error:`, and the data is still served. `Telemetry::Notifications` counts as listening even when nothing subscribes to it. A rule on a type with lists can already lose rows while observed: declare its `scope` only when you trust it, because observing it would mean a second query per list and serving other users' rows. Any clear "no" counts: with CanCanCan that includes the guard that refuses a Symbol a type returns, and an adapter you wrap around `Adapters::Null` is not recognised as null. `load_through_scope: false` opts out of the scope, so a foreign record is served and recorded. While a rule is observed, `audit_baseline` refuses to write: remove `observe:` first.
+
 ## Lists, connections and lookups
 
 Lists of a type are narrowed through `InvoicePolicy::Scope` (relations) or by calling the policy per item (arrays). Return a relation when you can: SQL filters before Ruby sees anything.
@@ -160,7 +208,8 @@ expect(AppSchema).to be_fully_authorized
 ```
 
 ```ruby
-# Rakefile (or a Rails task file): exits 1 when anything is uncovered
+# Exits 1 when anything is uncovered. In Rails the task loads by itself when the gem is required after Rails, as Bundler does.
+# Elsewhere, in the Rakefile:
 load "tasks/graphql_armory.rake"
 # bundle exec rake "graphql_armory:audit[AppSchema]"
 ```
@@ -174,23 +223,54 @@ load "tasks/graphql_armory.rake"
 | Kind | What it means | What to do |
 |---|---|---|
 | `:plugin` | The schema never installed the plugin. | Add `use GraphQL::Armory::Authorization, adapter: ...`. |
-| `:unprotected` | A base class, or the field class of an interface's field on a bypassed implementer, does not include `Base`, so nothing checks it. | Include `Base`. |
+| `:unprotected` | A base class, or the field class of an interface's field on a bypassed implementer, does not include `Base`, so nothing checks it. Also a resolver, mutation or subscription with no `Base` under a type with `covers_fields`: the declaration says a rule runs elsewhere, and none does. | Include `Base` and declare `authorize`, or declare `authorize: :none, reason: "..."` on the field, which lists it by its own path. |
 | `:no_rule` | A type, mutation or resolver has no rule, so it is denied to everyone. | Add `authorize` or `default_action`. |
 | `:field_without_rule` | A field of a bypassed type has no rule. The message says what really happens: denied, or served with no check (see [Rules](#rules)). | Give the field `authorize:` where it is defined (on the parent, if inherited), or remove it. A field class without `Base` needs one that includes it. |
 | `:adapter` | The policy a rule needs does not exist, or lacks the method or the `Scope`. | Add what is missing. |
 | `:model` | The model a rule needs cannot be worked out. | Pass `model:`. |
 | `:unscoped_load` | A `loads:` goes through `object_from_id` instead of the user's scope. | Let the load use the scope. |
 | `:unscoped_list` | A list or connection of records skips the user's scope, with `scope: false`, `connection: false` on a connection type, or a list type graphql-ruby does not detect such as `X.to_list_type`. A rule on each record hides its fields, not how many there are. | Remove the option, or write the type as `[Type]`. |
+| `:payload_outside_mutation` | A field returns a mutation's payload without being a mutation with a rule, including a shared `payload_type` with no rule of its own. Its fields are covered by the mutation's rule, so here they are served with no check. | Return a type of its own. A public mutation that inherits fields from a parent with a rule serves them with no check, so give those fields `authorize: :none, reason: "..."` on the parent. |
 | `:hook` | The schema's own `unauthorized_field` or `unauthorized_object` wins over the plugin's. | Remove it, or declare it in `own_denial_hooks:`. |
 | `:own_check` | Your own method can skip the rule: `authorized?`, `wrap`, `visible?` and others, or `reauthorize_scoped_objects` turned off. | Remove it, or declare it in `own_checks:`. |
 | `:ignored_rule` | A rule that does not run, or a field or argument defined more than once. | See [Redefined fields and arguments](#redefined-fields-and-arguments) and [Lists, connections and lookups](#lists-connections-and-lookups). |
 | `:foreign_model` | A field rule is defined on an interface or a parent whose model is not this type's, so the policy of this type's model is never asked for that field. A record of another class or a laxer subclass gets past it. Redefine the field on this type with its `authorize:` and an `override_reason:`, or name the same model on the parent. |
 | `:foreign_policy` | A type or a Base resolver names a `policy:`, but a rule it uses is defined on an interface, a parent, an input object or a resolver, so that rule asks another policy. A user this type's policy refuses can get the data. A field never sees its resolved type, so this cannot be fixed at runtime. | Move the rule to the class that names the policy and remove the original, or name the `policy:` on the class that defines the rule, if it can hold one: an interface or an input object cannot. There is no declaration for it. |
+| `:observed` | A rule under `observe:` serves what it would refuse. A baseline cannot accept it. | Remove `observe:` to enforce the rule. |
 
 A declaration (`own_checks:`, `own_denial_hooks:`, `override_reason:`, `authorize :none, reason:`) is your word: the audit stops reporting that problem and lists the reason, so a reviewer can read it. It does not read what your code does. A declaration that names nothing in use is itself a problem.
 
 Upgrading can make an audit that used to pass fail, because the audit reports more: read each new problem instead of declaring it to get the build green.
 
+### Adopting it on a schema with many problems
+
+A first audit of an existing schema can report hundreds of problems. A baseline records them so the build fails only on new ones, while the team works through the list:
+
+```sh
+bundle exec rake "graphql_armory:audit_baseline[AppSchema,config/graphql_armory_baseline.json]"   # once; commit the file
+bundle exec rake "graphql_armory:audit[AppSchema,config/graphql_armory_baseline.json]"            # in CI
+```
+
+```ruby
+expect(AppSchema).to be_fully_authorized(baseline: "config/graphql_armory_baseline.json")
+```
+
+**A baseline does not protect anything.** The accepted problems are still open, and a refused user may still get that data. `report.ok?` stays false and the output lists every accepted problem under "still open".
+
+| What happens | Result |
+|---|---|
+| A problem not in the file | Fails, named under "new" |
+| An accepted problem whose message changed, for example after an upgrade | Fails as new: read it, then edit the file |
+| An accepted problem that grew: a field or a `loads:` added to that type, or a type added under that base class or interface | Fails as new, naming what it now reaches |
+| An accepted problem that now appears more times | The extra ones fail as new |
+| An accepted problem that is gone | Fails until it leaves the file, so it cannot come back unseen |
+| Another resolver put at a path whose problem is accepted | Passes: an entry names the path and the problem, not the code behind them. Review what changes at an accepted path |
+| A file that is missing or invalid | Fails: it never runs as if there were no baseline |
+| A schema without the plugin | Cannot be accepted: install the plugin first |
+| An `:own_check` or a `:hook` problem | Cannot be accepted: whatever uses that method later would pass unseen. Remove it, or declare it in `own_checks:` or `own_denial_hooks:` with a reason, which the audit lists |
+
+Run `audit_baseline` again after fixing problems: on a file that exists it only removes what is gone, and it never adds. To accept a new problem, edit the file by hand, so it shows in the pull request: add its kind, path and message as the output prints them; `count` and `covers` may be left out, and then the entry accepts one problem that reaches nothing, so run `audit_baseline` afterwards to fill them in. The file holds each problem's kind, path, message and count, and the names it reaches (`covers`), and no data of the app. Removing what a problem reaches is fine: running `audit_baseline` narrows the entry.
+
 ### Redefined fields and arguments
 
 When a field is hidden from a user, by `visible?` or anything else, and the request carries no visibility profile, graphql-ruby does not answer "no such field": it looks for another definition of that name and serves it. So this rule does not run for a user the child's field is hidden from:
@@ -227,7 +307,7 @@ Same schema, different adapter. Your types and fields do not change:
 use GraphQL::Armory::Authorization, adapter: :cancan
 ```
 
-The actor is `context[:current_ability]` (it wins over `current_user`), or `Ability.new(context[:current_user])` (pass `Adapters::CanCan.new(ability_class: MyAbility)` for another class). It is built once per query.
+The actor is `context[:current_ability]` (it wins over `current_user`), or `Ability.new(context[:current_user])` (`user_key:` names another key; pass `Adapters::CanCan.new(ability_class: MyAbility)` for another class). It is built once per query.
 
 | Question | CanCanCan call |
 |---|---|
@@ -326,6 +406,7 @@ end
 - **`ready?` runs before authorization** (and, on the interpreter, before a failing `loads:`). Keep it free of side effects.
 - **`loads:` inside an input object** goes through the scope only when your base input object includes `Base` (`class Types::BaseInputObject < GraphQL::Schema::InputObject; include GraphQL::Armory::Authorization::Base; end`); otherwise the audit reports it as `:unscoped_load`.
 - **Do not put `authorize:` on a mutation field or on payload fields**; the mutation's own rule is the one that counts. A subclass that redeclares `authorize :none` is open to everyone, on purpose.
+- **Fields on a parent mutation.** A payload field asks the class that defined it, so a field on a parent with no rule, or on a mutation with `authorize :none` and no `covers_fields`, is denied: the mutation runs and the field answers null. The audit reports it as `:field_without_rule`. Give that field `authorize: :none, reason: "..."`, or use a shared `payload_type`. Moving `authorize` to the parent also works, but every new child then inherits that rule instead of being denied, and the audit does not report it.
 
 ## Interfaces and unions
 
@@ -341,6 +422,8 @@ What an interface adds is its fields, declared once and resolved on many types:
 
 ## Telemetry
 
+**When something raises during an object's check.** If a policy raises and a `rescue_from` handles the error, the handler runs and the object is denied, whatever the handler answers. Without a handler the error reaches the request. This includes a `GraphQL::ExecutionError`: when a `rescue_from` catches it, its message does not reach the client, who gets the ordinary denial.
+
 The decisions are visible to you and not to the client. Pass `sinks:` to hear each one:
 
 ```ruby
@@ -349,7 +432,7 @@ use GraphQL::Armory::Authorization, adapter: :pundit,
 # armory denied {:type=>"Invoice", :action=>:read}
 ```
 
-Signals are `:allowed`, `:denied`, `:bypassed` (an `authorize :none` rule ran) and `:scoped` (a list went through the user's scope). Data holds only `type`, `action` and `reason`, never record attributes. `GraphQL::Armory::Telemetry::Notifications` reports them to `ActiveSupport::Notifications`. Every signal, what to watch for and how to test it: [Telemetry](telemetry.md). A `sinks:` that is not an Array of callables raises `Telemetry::ConfigurationError` at boot.
+Signals are `:allowed`, `:denied`, `:observed` (a rule under `observe:` would have refused; its data also holds the `reason`), `:bypassed` (an `authorize :none` rule ran) and `:scoped` (a list went through the user's scope). Data holds only `type`, `action` and `reason`, never record attributes. `GraphQL::Armory::Telemetry::Notifications` reports them to `ActiveSupport::Notifications`. Every signal, what to watch for and how to test it: [Telemetry](telemetry.md). A `sinks:` that is not an Array of callables raises `Telemetry::ConfigurationError` at boot.
 
 ## Guarantees and limits
 

data/docs/encrypted-ids.md

@@ -137,7 +137,7 @@ The signal never holds the ID, the key or the record. A rising `:invalid` is som
 | `decode(id)` / `decode(cursor, nonce: true)` | The text, or raises `GraphQL::Armory::Encoder::InvalidError` (a `GraphQL::ExecutionError`, so clients see `Invalid ID or cursor`). |
 | `Encoder.versioned(newest, ..., oldest)` | A chain with the same `encode` and `decode`; encodes with `newest`. |
 | `chain.decode_versioned(text, nonce: false)` | `[data, encoder]`, or `[nil, nil]` when no encoder accepts it. |
-| `use GraphQL::Armory::IDs, encoder: nil, find: nil, sinks: []` | Defines `id_from_object` and `object_from_id`; `encoder` defaults to `Encoder.default`; `find:` loads types without `Base`; `sinks:` hears `:id_resolved` and `:id_refused` ([Telemetry](telemetry.md)). |
+| `use GraphQL::Armory::IDs, encoder: nil, find: nil, sinks: [], on_sink_error: nil` | Defines `id_from_object` and `object_from_id`; `encoder` defaults to `Encoder.default`; `find:` loads types without `Base`; `sinks:` hears `:id_resolved` and `:id_refused` ([Telemetry](telemetry.md)). |
 | `Encoder.default` | An encoder keyed by `GRAPHQL_ARMORY_KEY`, else by a key derived with HKDF from Rails' `secret_key_base`; raises `ConfigurationError` without either. |
 
 A subclass inherits `key`, `tag` and `codec`, and can override any of them. Passing `nil` to any of them raises `ConfigurationError`, so an unset environment variable fails at boot instead of being ignored.

data/docs/persisted-queries.md

@@ -101,7 +101,7 @@ class GraphqlController < ApplicationController
 end
 ```
 
-`PersistedQueries.operation_id(params)` reads the id where clients send it: `operationId`, `extensions.operationId`, or Apollo's `extensions.persistedQuery.sha256Hash` (`extensions` may be a JSON string, as in GET requests). The first one present wins, in that order. It answers nil when there is no id, or when it is not a non-empty String. Params must have String keys, as Rack and Rails params do. An empty `query` sent with an id (a GET request with `query=`) counts as no query.
+`PersistedQueries.operation_id(params)` reads the id where clients send it: `operationId`, `extensions.operationId`, Apollo's `extensions.persistedQuery.sha256Hash`, or Relay's `doc_id` (`extensions` may be a JSON string, as in GET requests). The first one present wins, in that order. It answers nil when there is no id, or when it is not a non-empty String. Params must have String keys, as Rack and Rails params do. An empty `query` sent with an id (a GET request with `query=`) counts as no query.
 
 What each request does:
 
@@ -126,7 +126,97 @@ GraphQL::Armory::PersistedQueries::Manifest.load("persisted-queries.json", diges
 
 `digest: false` accepts ids that are not digests (names such as `invoices-v1`). Then nothing proves an id belongs to its query: anyone who can edit the file can change what an id runs.
 
-Relay's example network layer sends the id as `doc_id`. Pass it yourself: `operation_id: params[:doc_id]`.
+### Several clients
+
+Each frontend's build, and every mobile version still in use, has its own manifest. `Manifests` puts them behind one `store:`:
+
+```ruby
+use GraphQL::Armory::PersistedQueries, store: GraphQL::Armory::PersistedQueries::Manifests.build("config/persisted_queries/*.json"), strict: true
+```
+
+`Manifests.build` takes a glob pattern, a path or a list of them, and `digest:`. For manifests with different digests, load each one and pass them: `Manifests.new([Manifest.load("web.json"), Manifest.load("relay.json", digest: :md5)])`.
+
+A pattern skips dotfiles and drops a missing `{a,b}` alternative, and `[` in a name reads as a pattern, so `a[1].json` loads `a1.json` when that file exists. List exact paths when a pattern could miss something, and avoid `[` in names. It raises at boot when a pattern or a path finds nothing, when a file does not load, or when two manifests hold different queries for one id, which only ids that are not digests can do. Keep a version's manifest for as long as that version is in use: removing it refuses those clients with `:unknown_operation`.
+
+They are one allowlist: any client may run any manifest's operation. A new manifest still needs a deploy.
+
+### Publishing without a server deploy
+
+With a `Manifest`, a new query reaches the server only with a server deploy. When frontends deploy on their own, even minutes apart, their users get `UNKNOWN_OPERATION` until the server catches up, and every query change needs a backend deploy. With `RedisStore`, the frontend's CI publishes its operations before the frontend goes out, and the server reads them as they are asked for, with no deploy and no restart.
+
+```mermaid
+sequenceDiagram
+    participant CI as Frontend CI
+    participant R as Redis
+    participant F as Frontend
+    participant S as GraphQL server
+
+    CI->>CI: Build the frontend, generate the manifest
+    CI->>R: graphql-armory-publish manifest.json (SET NX per id)
+    Note over CI,R: A failure stops the deploy
+    CI->>F: Deploy the frontend
+    F->>S: Request with an operation id
+    alt The server already read this id
+        S->>S: Answer from memory
+    else First time it sees this id
+        S->>R: GET the id
+        R-->>S: The query
+        S->>S: Check the digest, parse, keep in memory
+    end
+    S-->>F: The result of the stored query
+```
+
+On the server:
+
+```ruby
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::PersistedQueries,
+    store: GraphQL::Armory::PersistedQueries::RedisStore.build(
+      redis: Redis.new(url: ENV.fetch("PERSISTED_QUERIES_REDIS_URL"), timeout: 0.5, reconnect_attempts: 0),
+      on_error: ->(error) { Rails.error.report(error) }
+    ),
+    strict: true
+end
+```
+
+In the frontend's CI, before its deploy:
+
+```sh
+gem install graphql-armory redis
+REDIS_URL="$PUBLISHER_REDIS_URL" graphql-armory-publish dist/persisted-queries.json
+```
+
+It exits 1 on any problem, so the deploy stops. Publishing again is safe, so a failed run can simply run again. It takes several files, `--digest` and `--prefix`, and answers the same as `Publisher.call(manifest, redis:)` in Ruby. A CI with no Ruby can run `SET <prefix><id> <query> NX` itself: the default prefix is `graphql-armory:persisted-queries:` and the value is the query text. Check each answer: a refused `SET` means the id already exists, and it must hold the same query.
+
+**Who can publish decides what strict mode allows.** Anyone who can write to these keys can make the server run any query they choose, under its digest. So:
+
+- Give the server read access only, and the CI its own write access. With Redis ACLs:
+  ```
+  ACL SETUSER armory-server on >SERVER_PASSWORD ~graphql-armory:persisted-queries:* +get
+  ACL SETUSER armory-ci on >CI_PASSWORD ~graphql-armory:persisted-queries:* +get +set
+  ```
+  On a database other than 0, add `+select` to both: the client selects it when it connects.
+- Keep the CI's credential away from pull requests from forks and from the app's own servers.
+- The gem adds no endpoint to your API, so publishing cannot be reached from it.
+
+What happens when something fails:
+
+| Situation | What the client gets | What you see |
+|---|---|---|
+| Redis is down, the server already read the id | The normal result | Nothing |
+| Redis is down, the server has not read the id | `UNKNOWN_OPERATION`, nothing runs | `on_error` with the error, plus `:operation_refused` |
+| The id was never published | `UNKNOWN_OPERATION`, nothing runs | `:operation_refused` |
+| The stored query is not the digest of its id, or does not parse | `UNKNOWN_OPERATION`, nothing runs | `on_error` with `RedisStore::CorruptOperation`, plus `:operation_refused` |
+| The CI publishes another query under an id that exists | Nothing changes for clients | `PublishError`, exit 1 |
+
+By default `on_error` warns with the error's class only: Redis's messages may hold the URL and its password. `warn` prints nothing under `ruby -W0`, so pass your own `on_error` in production. An `on_error` that raises makes the request fail, and nothing runs.
+
+Limits:
+
+- Set a short Redis timeout, as above: during an outage each id the server does not know waits for it, and a client can send many such ids. Ids are checked for shape first, and one that cannot be an id never reaches Redis.
+- Removing a key does not revoke an operation until every server restarts: a server keeps what it read, with no limit but what was published.
+- They are one allowlist: any client may run any published operation. Use another `prefix:` for each allowlist you want apart. With `digest: false`, do not nest one prefix inside another: an id holding `:` could reach the other allowlist. With a digest, the check refuses it.
+- Keep these keys where they cannot expire or be evicted (`noeviction`, or a Redis of their own). A lost key looks like an id never published.
 
 ### Rolling it out
 
@@ -153,21 +243,25 @@ use GraphQL::Armory::PersistedQueries, store: PERSISTED, sinks: [GraphQL::Armory
 
 While you are in `strict: false`, `:raw_query_run` is the traffic still to migrate: turn on `strict: true` when it reaches zero. After a deploy, `:operation_refused` with `:unknown_operation` is a client build whose operations are not in the manifest. Signals never hold the operation id or the query. See [Telemetry](telemetry.md).
 
+### Telling a refusal apart
+
+Every refusal carries a stable code in `extensions.code`: `RAW_QUERY_REFUSED`, `UNKNOWN_OPERATION` or `OPERATION_MISMATCH`. Match on it instead of on the message.
+
 ### Counting probes in strict mode
 
 In strict mode a raw query is refused before it is validated, so it never produces a validation error. If your abuse detection counts validation errors (`undefinedField`, `argumentNotAccepted`) to spot someone probing your schema, it sees nothing from a strict endpoint. Count the refusal instead: a legitimate client sends operation ids and never a raw query, so `:operation_refused` with `reason: :raw_query` is a clean strike.
 
 ```ruby
-count_probes = lambda do |signal, data|
+count_probes = lambda do |signal, data, context|
   next unless signal == :operation_refused && data[:reason] == :raw_query
 
-  AbuseDetection.strike(Current.client_key) # your detector, with the client from your own request context
+  AbuseDetection.strike(context[:client_key]) # your detector, with a client key your controller put in the context
 end
 
 use GraphQL::Armory::PersistedQueries, store: PERSISTED, strict: true, sinks: [count_probes]
 ```
 
-A signal holds only the reason, so the sink reads who sent the request from your own request context, as in [Telemetry](telemetry.md). Do not strike on `:unknown_operation`: after a deploy it is a legitimate client build whose operations are not in the manifest yet. The example has not been run against a live detector.
+A signal holds only the reason. To know who sent the request, a sink that takes three arguments receives the query's context, as in [Telemetry](telemetry.md#who-asked). Do not strike on `:unknown_operation`: after a deploy it is a legitimate client build whose operations are not in the manifest yet. The example has not been run against a live detector.
 
 ### Testing with persisted queries
 
@@ -182,37 +276,35 @@ A signal holds only the reason, so the sink reads who sent the request from your
 - `fetch(id)` answers the operation (`id`, `name`, `body`, `document`, all frozen) or nil. `size` counts them.
 - Raises `PersistedQueries::ConfigurationError` at boot for: invalid JSON, an unreadable file, an unknown format or version, an id that is not the digest of its query, a query that does not parse, a duplicate id, an entry that is not an object, or an empty manifest. Messages never quote the file's queries.
 
-`use GraphQL::Armory::PersistedQueries, store:, strict: false, sinks: []`
+`use GraphQL::Armory::PersistedQueries, store:, strict: false, sinks: [], on_sink_error: nil`
 
 - `store:` answers `fetch(id)` with an object that has `body` and `document`, or nil. A Manifest, or your own store.
 - `strict:` is `true` or `false`.
-- `sinks:` an Array of callables taking `(signal, data)`; see [Watching the rollout](#watching-the-rollout).
+- `sinks:` an Array of callables taking `(signal, data)` or `(signal, data, context)`; see [Watching the rollout](#watching-the-rollout).
+- `on_sink_error:` a callable `(error, signal)` called when a sink raises; see [Telemetry](telemetry.md#guarantees-and-limits).
 - Works with your own `query_class`, whether it is set before `use`, after it, or in a child schema: the plugin subclasses it.
 - `use` it once per schema hierarchy. A second `use`, on the same schema or a child, raises instead of replacing the first one's settings.
 - A store whose `fetch` raises or answers something without `document` makes the request raise: it fails closed, as an exception.
 
+`Manifests.build(paths, digest: :sha256)` loads manifests from a glob pattern, a path or a list. `Manifests.new(manifests = [])` joins `Manifest` objects (subclasses are refused: their `fetch` would not run). `fetch(id)`, `size`, `empty?`. With no manifests it holds nothing, so every id is unknown, and `strict: false` refuses it at boot.
+
+`RedisStore.build(redis:, prefix: "graphql-armory:persisted-queries:", digest: :sha256, on_error:)` reads what a publisher stored; `new` with no Redis holds nothing, and `strict: false` refuses it at boot. `Publisher.call(manifest, redis:, prefix:)` answers `published` and `unchanged`, and raises `Publisher::PublishError` rather than change an id. `RedisStore::Client::Substitute` stands in for Redis in tests.
+
 Context keys: `operation_id` (a String; anything else is an unknown id), `armory_allow_raw_query` (only `true` allows).
 
 ## Guarantees and limits
 
+- On graphql before 2.6 (checked on 2.4.18 and 2.5.26) with json 3.1, a known id with different text raises instead of answering `OPERATION_MISMATCH` when the stored query holds a string literal, because graphql-ruby's printer passes an option that version of json rejects. Nothing runs.
 - A request with an id runs only the stored document for that id, or nothing.
 - In strict mode a raw query runs only when the app's context says `armory_allow_raw_query: true`. The plugin does not decide who is staff: your controller does.
-- Queries built by your own code as `GraphQL::Query` objects (for example in `multiplex`) bypass the plugin's lookup. In strict mode they are not refused either: the check happens when the plugin's query class builds the query.
+- Queries built by your own code as `GraphQL::Query` objects (for example in `multiplex`) run their own text, so an operation id means nothing on them. In strict mode they are refused unless the context holds `armory_allow_raw_query: true`, and they are recorded like any raw query. The check is a trace on `execute_query`, so `run_partials` and `validate: false` are covered. Two limits: built text that does not validate gets the ordinary validation errors, with no signal and with field suggestions, because validation runs first (nothing resolves); and your own code can skip the check by choosing another trace: `context[:trace]` on a multiplex (or on a query, on the interpreter), or a `trace_mode` or `default_trace_mode` given a class that does not include `trace_with` modules. A signal is recorded per execution, so each `run_partials` entry records one. On `Execution::Next`, a refused query with `validate: false` and variables that do not coerce, or a validation timeout, returns a nil result: nothing runs, the refusal is recorded and sits in `context.errors`.
 - In strict mode, schema introspection run through the plugin is refused too. `Schema.to_json` and `rake graphql:schema:json` need `context: { armory_allow_raw_query: true }` (the rake task's `load_context`). `Schema.to_definition` and `Schema.validate` are not affected.
-- The manifest lives in the server's code: adding an operation needs a deploy. See the runtime store below.
+- A `Manifest` lives in the server's code: adding an operation needs a deploy. `RedisStore` does not: see "Publishing without a server deploy".
 - Subscriptions: graphql-ruby re-runs a subscription with its printed query, which the plugin accepts when it matches the stored document. Subscriptions are not tested with persisted queries yet.
 
-## Planned: a runtime store
-
-The manifest is the simplest store: one file, no database, deployed with the code. Teams that ship clients independently of the server (mobile apps, several frontends) need operations published without a server deploy. That is planned for later, behind the same `store:` interface:
-
-- **A database table** (ActiveRecord) holding operations per client, with the digest checked on write.
-- **A sync endpoint** the client build calls to publish its operations, authenticated per client with an HMAC of the request body and a secret per client.
-- **Several clients**, each with its own operations and secret, so one client cannot publish under another's name.
-- **Archiving** operations that old app versions no longer use, without deleting their history.
-- **Publishing without redeploying**: the server reads new operations as soon as they are synced.
+## Planned: more runtime stores
 
-Until then, any object that answers `fetch(id)` with an operation can be passed as `store:`.
+`RedisStore` is one store behind the `store:` interface. Still planned: a database table, an endpoint a client build calls to publish, operations and secrets per client, and archiving what old app versions no longer use. Until then, any object that answers `fetch(id)` with an operation can be passed as `store:`.
 
 ## References