graphql-armory 0.1.0.pre2 → 0.1.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17454310f4c6b683fac81e5fc5e4ea5f810a645319eb083841e42910e7f881b3
-  data.tar.gz: cea12c9b171113f1cb3d6df4658676508056bab51335f8e937adabba18e28817
+  metadata.gz: 3eacfaa8caea3d5963df1d9a12f30efd9b9dc5232bae15b73475fef3f519ad85
+  data.tar.gz: 1176b251773ecf02e4a71cacabe1b4ef4c3f4345ca9d88efdf2ba103be4bf84a
 SHA512:
-  metadata.gz: 915b3068e7fecaee1f409b24cbc0b24832053322da848e7a242302c701479ae293d5b735d9d4ab49784b7f950fbfedb909034f07ea90bf877cb815471926e660
-  data.tar.gz: 9d4809e01699f91be71abc2b2ac4209417ca5d5b39484f91ba492fc9c3bdc24a2d048b1c83c9c9e2aaf6238e193bdd9d17f4b14bdae5ed6c31ae0de4b1977250
+  metadata.gz: 0d8e40044eef04927178f8a75bd0394b833686f6ee4e2a04c5734b1b84fa7644d66c683b8456d1b1d2dbc916c3c3714f15a060a6757f04af2632d8e40b7dd469
+  data.tar.gz: 548f98bc7e3b373f49172d29dfe89a20ea3cf9a1f70eeba4ee9161e38ce429e46c30c27cfdb4afd1d591d221d10f34d56eaa41f1cffca514b62d7821dd8ce88f

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.0.pre3 (2026-10-29)
+
+Encrypted, versioned IDs and cursors (roadmap module 2), and a docs page per module.
+
+- Encrypted IDs and cursors, part 4: `use GraphQL::Armory::IDs` defines `id_from_object` and `object_from_id` with encrypted IDs (default encoder unless `encoder:`); Base types are looked up inside the user's scope, other types through `find:`; every ID it cannot honour answers `null`.
+- Encrypted IDs and cursors, part 3: `Encoder.default`, keyed by `GRAPHQL_ARMORY_KEY` or, in Rails, by a key derived with HKDF from `secret_key_base` (not from `Rails.application.key_generator`, whose digest changes during boot); it raises when the schema loads without either.
+- Encrypted IDs and cursors, part 2: `Encoder.versioned(newest, ..., oldest)` and `decode_versioned` to rotate keys without breaking clients; `Encoder::Legacy` reads graphql-ruby's default base64 to add encryption to an existing API.
+- Encrypted IDs and cursors, part 1: `GraphQL::Armory::Encoder` (AES-256-GCM, HKDF subkeys, stable IDs, random-nonce cursors, `key`, `tag`, `codec`). Works as `cursor_encoder` and inside `object_from_id`; an ID it refuses in `loads:` is answered like a missing record. See `docs/encrypted-ids.md`.
+- Docs: each module has its own page in `docs/` (the problem, the solution, how to use it, guarantees and limits). The authorization guide moved from the README to `docs/authorization.md`; the README now lists the modules.
+
 ## 0.1.0.pre2 (2026-10-29)
 
 Closes the known gaps of the authorization module.

data/MIGRATING.md

@@ -10,7 +10,7 @@ class AppSchema < GraphQL::Schema
 end
 ```
 
-Make your base classes include `GraphQL::Armory::Authorization::Base` (see the README quick start). Types that inherit from them are now covered; run the audit to see the rest.
+Make your base classes include `GraphQL::Armory::Authorization::Base` (see "How to use it" in [docs/authorization.md](docs/authorization.md)). Types that inherit from them are now covered; run the audit to see the rest.
 
 ## 2. Replace `authorized?` with a rule
 

data/README.md

@@ -4,273 +4,39 @@
 
 # graphql-armory
 
-Open-source extensions for [graphql-ruby](https://github.com/rmosolgo/graphql-ruby), built on its public extension points: no fork, no monkey patching.
+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.
 
-The first module is **authorization**. It plugs [Pundit](https://github.com/varvet/pundit) policies into graphql-ruby so that:
-
-- **Nothing is open by default.** A type or field no rule covers answers `null` (or an error), never data.
-- **Lists only contain what the user may see**, including connections: the scope runs before pagination and counting.
-- **Lookups by ID cannot leak** (IDOR). A record you may not read and a record that does not exist look identical.
-- **An audit tells you what you forgot**, from a rake task or an RSpec matcher, so CI fails instead of production leaking.
-
-> **Status: early development (0.1, unreleased).** Pundit and CanCanCan adapters. Not published yet.
+> **Status: early development.** Prereleases on RubyGems (`0.1.0.pre3`). The API may change before 1.0.
 
 ## Install
 
 ```ruby
-gem "graphql-armory", "~> 0.1.0.pre2"  # a prerelease: `gem install graphql-armory --pre`
-gem "pundit"      # or "cancancan", whichever you use
-```
-
-Requires Ruby >= 3.1 and graphql >= 2.4. `GraphQL::Execution::Next` is supported from graphql 2.6.2 (see [Engines](#engines)).
-
-## Quick start
-
-Your policies stay plain Pundit. The only new thing is where the rules are declared:
-
-```ruby
-class BaseField < GraphQL::Schema::Field
-  include GraphQL::Armory::Authorization::Base
-end
-
-class BaseObject < GraphQL::Schema::Object
-  include GraphQL::Armory::Authorization::Base
-  field_class BaseField
-  default_action :read          # every type is checked with InvoicePolicy#read?, AccountPolicy#read?...
-end
-
-class InvoiceType < BaseObject
-  field :number, String, null: false
-  field :internal_notes, String, authorize: :manage   # this field asks InvoicePolicy#manage?
-end
-
-class QueryType < BaseObject
-  authorize :none, reason: "root type; each field declares its own rule"
-  field :invoices, [InvoiceType], null: false, authorize: :none, reason: "narrowed by InvoicePolicy::Scope"
-end
-
-class AppSchema < GraphQL::Schema
-  query QueryType
-  use GraphQL::Armory::Authorization, adapter: :pundit
-end
-```
-
-The actor is `context[:current_user]`. A complete, tested version lives in [`examples/invoices.rb`](examples/invoices.rb).
-
-### Rules
-
-| Declaration | Meaning |
-|---|---|
-| `default_action :read` | Default rule for every type below this base class. |
-| `authorize :manage` | This type is checked with `manage?` instead. |
-| `authorize :read, model: Invoice` | The model when it is not named like the type. |
-| `field ..., authorize: :manage` | The field asks another question of the same policy. |
-| `authorize :none, reason: "..."` | Explicit bypass. A reason is required and appears in the audit. |
-
-A bypass does not propagate: a field of a bypassed type still needs its own rule, or it is denied.
-
-### What happens on denial
-
-```ruby
-use GraphQL::Armory::Authorization, adapter: :pundit, on_unauthorized: :null # default
-```
-
-| Mode | Client sees | Use |
-|---|---|---|
-| `:null` | `null`, no error | Default. Reveals nothing. |
-| `:error` | `"Not found"`, code `NOT_FOUND`, identical on every path | When clients need to tell. |
-| `:raise` | `NotAuthorizedError` naming only the type | When your app rescues it. |
-
-Denied non-null fields raise the generic "Not found" error, because GraphQL cannot return `null` there (on Execution::Next a denied object in a non-null position answers graphql-ruby's own "Cannot return null for non-nullable field", and `:raise` messages are prefixed with the field path). `find_by:` lookups always answer `null` in every mode: a missing ID cannot raise, and a foreign ID must look the same.
-
-### 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.
-
-```ruby
-field :invoice, InvoiceType, authorize: :none, reason: "looked up through the scope", find_by: :id do
-  argument :id, ID
-end
-
-field :invoice_via_ref, InvoiceType, authorize: :none, reason: "loaded through the scope" do
-  argument :invoice_id, ID, loads: InvoiceType
-end
-```
-
-`find_by:` and `loads:` (also inside input objects whose base class includes `Base`) look the record up **inside the user's scope**, so another tenant's ID answers exactly like a missing one. Opt out of the scope for a field's `loads:` only on purpose, with `load_through_scope: false`; the audit lists it. On `Execution::Next` the opt-out also reaches `loads:` nested in that field's input objects (the interpreter keeps those scoped), and the audit lists them too (`Query.field(filter.invoice_id)`). An input object that overrides `object_from_id` or defines `load_<argument>` itself is honoured on the interpreter and not seen by the audit.
-
-**Global IDs.** When your schema defines `object_from_id` (Relay global IDs), `loads:` decodes the id with it, refuses a record of another model, and looks the record up again inside the scope (one extra query per load). Without `object_from_id`, the id is the primary key. `object_from_id` must return the record itself, not a lazy value: a lazy value is denied. A decoder that raises `ActiveRecord::RecordNotFound` (like `GlobalID.find`) or `ArgumentError` (a malformed id) is answered like a missing record; other errors propagate. `loads:` of an interface or union (for example `Types::Node`) raises `ConfigurationError`: load a concrete type. Composite primary keys are not supported.
-
-## The audit
-
-```ruby
-GraphQL::Armory::Authorization::Audit.(AppSchema)   # => report with problems
-```
-
-```ruby
-# spec/schema_spec.rb
-require "graphql/armory/authorization/rspec"
-expect(AppSchema).to be_fully_authorized
-```
-
-```ruby
-# Rakefile (or a Rails task file): exits 1 when anything is uncovered
-load "tasks/graphql_armory.rake"
-# bundle exec rake "graphql_armory:audit[AppSchema]"
-```
-
-It reports types nobody protects (a base class that never included `Base`), types and fields with no rule, policies missing the method or `Scope`, `loads:` that skip the scope, and lists every declared bypass with its reason.
-
-## CanCanCan
-
-Same schema, different adapter. Your types and fields do not change:
-
-```ruby
-use GraphQL::Armory::Authorization, adapter: :cancan
+gem "graphql-armory", "~> 0.1.0.pre3"  # a prerelease: `gem install graphql-armory --pre`
+gem "pundit"      # or "cancancan", for the authorization module
 ```
 
-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.
-
-| Question | CanCanCan call |
-|---|---|
-| Can this object be seen? | `ability.can?(:read, object)` |
-| Can this field be seen? | `ability.can?(:manage, object, :internal_notes)` for a field that declares `authorize: :manage`: the attribute is passed, because `can :read, User, [:username]` makes `can?(:read, user)` true for the whole object |
-| Which items of a list? | `Model.accessible_by(ability, :read)`, still a paginable relation; Arrays are filtered with `can?` |
-
-**Block-only rules.** `can(:read, Invoice) { |i| ... }` cannot be turned into SQL, so `accessible_by` fails. The adapter raises `MissingScopeError` instead of guessing. To accept the cost, declare it on the type: `authorize :read, scope: :in_memory`. Lists are then filtered with `can?` one by one and efficient pagination is lost; `find_by:` and `loads:` find the record and then ask `can?`. Fields covered by the type's rule are not asked about their attribute: give the ones an attribute rule must hide their own `authorize: :action`. Options the adapter does not understand (`policy:`, another `scope:`) raise `ConfigurationError`.
+Requires Ruby >= 3.1 and graphql >= 2.4.
 
-**The audit covers less.** It still reports missing rules, bypasses and unscoped `loads:`, but not whether the `Ability` grants the action: abilities depend on the user.
+## Modules
 
-**Guests.** `Ability.new(nil)` is your ability class's decision. Make it deny everything if there is no user.
+Status: ✅ released, 🚧 in progress, ⬜ not started. Update this table in the same PR that changes a module.
 
-## Visibility
-
-Hide a type or a field from users who may not use it, in introspection and in "did you mean" suggestions:
-
-```ruby
-class InvoiceExportType < BaseObject
-  authorize :read, model: Invoice, visible_when: :export     # InvoicePolicy#export? / can?(:export, Invoice)
-end
-
-field :internal_notes, String, authorize: :manage, visible_when: :export
-```
-
-`visible_when:` is an action like any other, but it is asked **of the model's class, with no record**: `InvoicePolicy.new(user, Invoice).export?` with Pundit, `can?(:export, Invoice)` with CanCanCan. Write a method that decides from the user (`user.admin?`), not from the record. Nothing is hidden unless you declare it, and the audit reports a `visible_when:` action the policy does not define.
-
-A hidden member also hides what leads only to it: a root field that returns a hidden type disappears with it.
-
-**Schema dumps.** graphql 2.6 builds an ordinary context for `to_definition`, which cannot be told apart from an anonymous request, and an anonymous request must never see hidden members. Ask for the full schema explicitly:
-
-```ruby
-AppSchema.to_definition(context: { armory_full_schema: true })
-```
-
-Things to know:
-
-- **Hiding is not authorization.** A hidden field is absent from the schema, so a query for it fails like a field that never existed. What the user may *read* is still decided by `authorize`.
-- **The policy receives the class.** A policy that reads the record (`record.account_id`) raises `NoMethodError` for a `visible_when:` action; write that action from the user. The error propagates out of `execute`, so make sure your error handler does not echo it.
-- **CanCanCan conditions are not applied to a class.** `can :export, Invoice, account_id: 1` makes the member visible to anyone who holds the rule. For a field, the attribute is passed: `can?(:export, Invoice, :internal_notes)`.
-- **A subclass that redeclares `authorize` replaces the rule**, `visible_when:` included: repeat it.
-- **`visible_when:` on a field needs a type that includes `Base`** (not an interface or a plain type); otherwise it raises `ConfigurationError` when a query selects it.
-- **Static `Schema::Visibility` profiles are not supported** and raise `ConfigurationError`; plain `use Schema::Visibility`, `dynamic: true` and the default warden work.
-
-Visibility is computed per query (and memoized inside it). Role-based profile caching across requests is graphql-ruby's `Schema::Visibility` feature and is not wrapped here.
-
-## Arguments
-
-An argument with no rule is **covered by its field**: the field already decides whether the user may call it. Declare a rule on the arguments that must be stricter, and they are checked when the client sends them:
-
-```ruby
-class BaseArgument < GraphQL::Schema::Argument
-  include GraphQL::Armory::Authorization::Base
-end
-# in your base field: argument_class BaseArgument
-
-field :invoices, [InvoiceType], authorize: :none, reason: "narrowed by the scope" do
-  argument :include_internal, Boolean, required: false, authorize: :manage, model: Invoice
-  argument :tag, String, required: false, visible_when: :export, model: Invoice
-  argument :status, String, required: false, authorize: :none, reason: "public filter"
-end
-```
-
-- **`authorize: :manage`** asks the policy about the parent object when it is an instance of the model, otherwise about the model's class (a root field has no record, so write the action from the user). The model is the one the field's type wraps, or `model:` when it wraps none, as on a root field. A denial denies the whole field, with the usual null or error.
-- **Defaults.** graphql-ruby does not check an argument the client left at its default, and the two engines disagree about it (the interpreter skips the check, `Execution::Next` applies the default), so a restricted argument with a `default_value:` is refused with an `ArgumentError`. Sending `false` explicitly counts as using the argument.
-- **Every argument class needs `Base`.** `argument_class` is not inherited: set it on your base field, and also on resolvers, input objects (for restricted arguments nested in a filter) and directives that need it.
-- **`visible_when:`** hides the argument like it hides a field: it is absent from introspection and from suggestions, and a query that uses it fails like an argument that never existed.
-- **`authorize: :none, reason:`** only declares and documents: the audit lists it with its reason.
-- `authorize: true` is refused on an argument, and an argument with no model to ask about raises `ConfigurationError`.
-
-## Mutations and resolvers
-
-Include `Base` in your base mutation (or resolver) and declare what each one needs. A mutation is an action, not a read, so `default_action` does not apply and **a mutation with no `authorize` is denied**.
-
-```ruby
-class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
-  include GraphQL::Armory::Authorization::Base
-  argument_class Types::BaseArgument
-  field_class Types::BaseField
-  object_class Types::BaseObject
-end
-
-class Mutations::ApproveInvoice < Mutations::BaseMutation
-  authorize :approve, model: Invoice            # InvoicePolicy#approve?(invoice) / can?(:approve, invoice)
-  argument :invoice_id, ID, loads: Types::Invoice
-  field :invoice, Types::Invoice, null: true
-end
-```
-
-- **The record is the loaded one.** The rule runs after `loads:`, once per loaded record of the model (with none loaded, the model's class is asked). `loads:` goes through the user's scope, so a foreign id answers like a missing one.
-- **Denial** follows the schema's `on_unauthorized` mode, like a field (`null`, `"Not found"`, or raise). With `on_denied: :errors` the mutation does not run and answers `{ errors: [{ message: "Not allowed", code: "FORBIDDEN" }] }` as data, so the payload needs an `errors` field.
-- **Payload types** are ordinary objects: declare `authorize :none, reason: "...", covers_fields: true` so their fields are covered by the mutation instead of denied.
-- **`authorize :none, reason:`** documents a mutation anyone may call; the audit lists it with its reason. A mutation with no rule appears as `:no_rule` (for example `Mutation.forgotten`), and a rule the policy does not define as `:adapter`.
-- An unknown `on_denied:` raises `ArgumentError`; a mutation with a rule but no model raises `ConfigurationError`.
-- **Class-level answers are weak.** With no loaded record of the model (no `loads:`, an empty `loads: [ID]`, or a `loads:` of another type) the rule is asked about the model's class: CanCan answers true for anyone holding the right, and a Pundit policy that reads `record` attributes raises. Load the record you are authorizing.
-- **`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.
-
-## Interfaces and unions
-
-They are never authorized themselves: graphql-ruby only runs `authorized?` on the concrete type, and every path ends there (root field, association, each list item, `loads:`, union and interface resolution). A foreign object in a list of a union or an interface comes back `null`, like in any other list. So `include Base` in an interface or a union is refused with a message pointing to the possible types; declare the rule on each concrete type.
-
-What an interface adds is its fields, declared once and resolved on many types:
-
-- A field with no rule is **covered** by the rule of the Base types that implement the interface (a plain implementer runs no check at all), unless one of them is a bypass (`authorize :none`). Then the field is **denied for every implementer**, because it cannot tell which type it runs on, and the audit reports it (`:field_without_rule`, for example `Document.number`). Declare it (`authorize: :none, reason:` or an action) to fix it.
-- `visible_when:` is not supported on an interface field; put it on the concrete types' fields.
-- `authorize: true` is not valid on an interface field: it is always denied, and the audit reports it. Use an action or `:none`.
-- An interface whose field class does not include `Base`, such as graphql-ruby's built-in Relay `Node`, runs no field check, so its `id` stays readable on a bypassed implementer. The audit reports it (`:unprotected`, `Node.id`); give your own `Node` interface a Base field class if that matters.
-- The audit reports an interface field once, on the interface that declares it, not again on each implementer.
-
-## Telemetry
-
-Pass `sinks: [->(signal, data) {}]`. Signals are `:allowed`, `:denied`, `:bypassed`; data holds only `type`, `action` and `reason`, never record attributes.
-
-## Guarantees and limits
-
-Covered by the black-box suite in `spec/security`, on both engines: user A cannot read user B's objects by root field, nested association or `loads:`; lists never contain foreign objects; uncovered types fail closed and show in the audit; a field hidden with `visible?` is absent from introspection and error suggestions (that is graphql-ruby's behaviour, pinned by a test).
-
-Policies must return `true`/`false`/`nil`; anything else raises `AdapterError`. Do not use `dataloader.request` inside policies; use `dataloader.with(...).load`.
-
-## Engines
-
-Both execution engines are tested: the default interpreter and `Execution::Next`. In graphql 2.5.26 to 2.6.1, Next crashes on denied fields, so the gem refuses to run on Next there (`ConfigurationError`). Everything else works from graphql 2.4.
-
-## Performance
-
-`benchmark/authorization.rb`, 1000 invoices, graphql 2.6.2, Ruby 3.2, Docker on Windows:
-
-| Engine | Query | plain | armory (array) | armory (relation) |
+| Order | Module | Status | Docs | Current limits |
 |---|---|---|---|---|
-| interpreter | `number` | 117.6 i/s | 45.9 i/s | 44.2 i/s |
-| interpreter | 3 fields | 58.8 i/s | 21.6 i/s | 21.0 i/s |
-| next | `number` | 654.2 i/s | 71.8 i/s | 70.8 i/s |
-| next | 3 fields | 417.5 i/s | 42.1 i/s | 39.5 i/s |
+| 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.pre3 (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 whitelisting | ⬜ | | Research not started. |
+| 4 | Rate limiting | ⬜ | | Research not started. |
+| 5 | Stable (keyset) connections | ⬜ | | Research not started. |
+| 6 | Subscriptions over Pusher / Ably | ⬜ | | Research not started. |
+| 7 | Response caching | ⬜ | | Research not started. |
+| 8 | API versioning (changesets) | ⬜ | | Research not started. |
+| 9 | `@defer` / `@stream` | ⬜ | | Research not started. |
+| 10 | Dashboard | ⬜ | | Research not started. |
 
-The absolute cost is about 13 to 15 ms per 1000 items on both engines; most of it is probably Pundit's policy lookup, which is not cached so code reloading cannot serve stale classes. Run it yourself: `docker compose run --rm test bundle exec ruby benchmark/authorization.rb` (add `GRAPHQL_ARMORY_ENGINE=next` for Next).
+Each module starts with its own research before design. A module is ✅ only when it is released and its page documents its limits.
 
-## Migrating
-
-Coming from hand-written `authorized?` and `scope_items`? See [MIGRATING.md](MIGRATING.md).
+Every module page follows the same outline: **The problem**, **The solution**, **How to use it**, reference sections, **Guarantees and limits**.
 
 ## Development
 
@@ -287,30 +53,11 @@ 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 v0.1.0.pre2 && git push origin v0.1.0.pre2
+git tag v0.1.0.pre3 && git push origin v0.1.0.pre3
 ```
 
 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).
 
-## Roadmap
-
-Status: ✅ done, 🚧 in progress, ⬜ not started. Update this table in the same PR that changes a module.
-
-| Order | Module | Status | Current limits |
-|---|---|---|---|
-| 1 | Authorization (Pundit, CanCanCan) | ✅ | 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 | ⬜ | Research not started. |
-| 3 | Persisted queries / operation whitelisting | ⬜ | Research not started. |
-| 4 | Rate limiting | ⬜ | Research not started. |
-| 5 | Stable (keyset) connections | ⬜ | Research not started. |
-| 6 | Subscriptions over Pusher / Ably | ⬜ | Research not started. |
-| 7 | Response caching | ⬜ | Research not started. |
-| 8 | API versioning (changesets) | ⬜ | Research not started. |
-| 9 | `@defer` / `@stream` | ⬜ | Research not started. |
-| 10 | Dashboard | ⬜ | Research not started. |
-
-Each module starts with its own research before design. A module is ✅ only when it is released and its limits are documented here.
-
 ## Related gems
 
 - [graphql-armory-rust_parser](https://github.com/israelb/graphql-armory-rust_parser): a GraphQL parser written in Rust, installable as graphql-ruby's default parser.

data/docs/authorization.md

@@ -0,0 +1,264 @@
+# Authorization
+
+Pundit or CanCanCan policies for graphql-ruby, declared once on your types and enforced on every path.
+
+## The problem
+
+graphql-ruby leaves authorization to you. Each type needs an `authorized?` method, each list a `scope_items`, each `loads:` its own check, and nothing tells you which ones you forgot. One forgotten type is enough for user A to read user B's invoice by its ID (an IDOR), through a root field, a nested association, a list, or an argument that loads a record. And an error that says "not allowed" instead of "not found" tells an attacker the record exists.
+
+## The solution
+
+graphql-armory plugs your existing policies into graphql-ruby's public hooks:
+
+- **Nothing is open by default.** A type or field no rule covers answers `null` (or an error), never data.
+- **Lists only contain what the user may see**, including connections: the scope runs before pagination and counting.
+- **Lookups by ID cannot leak** (IDOR). A record you may not read and a record that does not exist look identical.
+- **An audit tells you what you forgot**, from a rake task or an RSpec matcher, so CI fails instead of production leaking.
+
+## How to use it
+
+Your policies stay plain Pundit. The only new thing is where the rules are declared:
+
+```ruby
+class BaseField < GraphQL::Schema::Field
+  include GraphQL::Armory::Authorization::Base
+end
+
+class BaseObject < GraphQL::Schema::Object
+  include GraphQL::Armory::Authorization::Base
+  field_class BaseField
+  default_action :read          # every type is checked with InvoicePolicy#read?, AccountPolicy#read?...
+end
+
+class InvoiceType < BaseObject
+  field :number, String, null: false
+  field :internal_notes, String, authorize: :manage   # this field asks InvoicePolicy#manage?
+end
+
+class QueryType < BaseObject
+  authorize :none, reason: "root type; each field declares its own rule"
+  field :invoices, [InvoiceType], null: false, authorize: :none, reason: "narrowed by InvoicePolicy::Scope"
+end
+
+class AppSchema < GraphQL::Schema
+  query QueryType
+  use GraphQL::Armory::Authorization, adapter: :pundit
+end
+```
+
+The actor is `context[:current_user]`. A complete, tested version lives in [`examples/invoices.rb`](../examples/invoices.rb).
+
+## Rules
+
+| Declaration | Meaning |
+|---|---|
+| `default_action :read` | Default rule for every type below this base class. |
+| `authorize :manage` | This type is checked with `manage?` instead. |
+| `authorize :read, model: Invoice` | The model when it is not named like the type. |
+| `field ..., authorize: :manage` | The field asks another question of the same policy. |
+| `authorize :none, reason: "..."` | Explicit bypass. A reason is required and appears in the audit. |
+
+A bypass does not propagate: a field of a bypassed type still needs its own rule, or it is denied.
+
+## What happens on denial
+
+```ruby
+use GraphQL::Armory::Authorization, adapter: :pundit, on_unauthorized: :null # default
+```
+
+| Mode | Client sees | Use |
+|---|---|---|
+| `:null` | `null`, no error | Default. Reveals nothing. |
+| `:error` | `"Not found"`, code `NOT_FOUND`, identical on every path | When clients need to tell. |
+| `:raise` | `NotAuthorizedError` naming only the type | When your app rescues it. |
+
+Denied non-null fields raise the generic "Not found" error, because GraphQL cannot return `null` there (on Execution::Next a denied object in a non-null position answers graphql-ruby's own "Cannot return null for non-nullable field", and `:raise` messages are prefixed with the field path). `find_by:` lookups always answer `null` in every mode: a missing ID cannot raise, and a foreign ID must look the same.
+
+## 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.
+
+```ruby
+field :invoice, InvoiceType, authorize: :none, reason: "looked up through the scope", find_by: :id do
+  argument :id, ID
+end
+
+field :invoice_via_ref, InvoiceType, authorize: :none, reason: "loaded through the scope" do
+  argument :invoice_id, ID, loads: InvoiceType
+end
+```
+
+`find_by:` and `loads:` (also inside input objects whose base class includes `Base`) look the record up **inside the user's scope**, so another tenant's ID answers exactly like a missing one. Opt out of the scope for a field's `loads:` only on purpose, with `load_through_scope: false`; the audit lists it. On `Execution::Next` the opt-out also reaches `loads:` nested in that field's input objects (the interpreter keeps those scoped), and the audit lists them too (`Query.field(filter.invoice_id)`). An input object that overrides `object_from_id` or defines `load_<argument>` itself is honoured on the interpreter and not seen by the audit.
+
+**Global IDs.** When your schema defines `object_from_id` (Relay global IDs), `loads:` decodes the id with it, refuses a record of another model, and looks the record up again inside the scope (one extra query per load). Without `object_from_id`, the id is the primary key. `object_from_id` must return the record itself, not a lazy value: a lazy value is denied. A decoder that raises `ActiveRecord::RecordNotFound` (like `GlobalID.find`), `ArgumentError` (a malformed id) or `GraphQL::Armory::Encoder::InvalidError` (see [encrypted IDs](encrypted-ids.md)) is answered like a missing record; other errors propagate. `loads:` of an interface or union (for example `Types::Node`) raises `ConfigurationError`: load a concrete type. Composite primary keys are not supported.
+
+## The audit
+
+```ruby
+GraphQL::Armory::Authorization::Audit.(AppSchema)   # => report with problems
+```
+
+```ruby
+# spec/schema_spec.rb
+require "graphql/armory/authorization/rspec"
+expect(AppSchema).to be_fully_authorized
+```
+
+```ruby
+# Rakefile (or a Rails task file): exits 1 when anything is uncovered
+load "tasks/graphql_armory.rake"
+# bundle exec rake "graphql_armory:audit[AppSchema]"
+```
+
+It reports types nobody protects (a base class that never included `Base`), types and fields with no rule, policies missing the method or `Scope`, `loads:` that skip the scope, and lists every declared bypass with its reason.
+
+## CanCanCan
+
+Same schema, different adapter. Your types and fields do not change:
+
+```ruby
+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.
+
+| Question | CanCanCan call |
+|---|---|
+| Can this object be seen? | `ability.can?(:read, object)` |
+| Can this field be seen? | `ability.can?(:manage, object, :internal_notes)` for a field that declares `authorize: :manage`: the attribute is passed, because `can :read, User, [:username]` makes `can?(:read, user)` true for the whole object |
+| Which items of a list? | `Model.accessible_by(ability, :read)`, still a paginable relation; Arrays are filtered with `can?` |
+
+**Block-only rules.** `can(:read, Invoice) { |i| ... }` cannot be turned into SQL, so `accessible_by` fails. The adapter raises `MissingScopeError` instead of guessing. To accept the cost, declare it on the type: `authorize :read, scope: :in_memory`. Lists are then filtered with `can?` one by one and efficient pagination is lost; `find_by:` and `loads:` find the record and then ask `can?`. Fields covered by the type's rule are not asked about their attribute: give the ones an attribute rule must hide their own `authorize: :action`. Options the adapter does not understand (`policy:`, another `scope:`) raise `ConfigurationError`.
+
+**The audit covers less.** It still reports missing rules, bypasses and unscoped `loads:`, but not whether the `Ability` grants the action: abilities depend on the user.
+
+**Guests.** `Ability.new(nil)` is your ability class's decision. Make it deny everything if there is no user.
+
+## Visibility
+
+Hide a type or a field from users who may not use it, in introspection and in "did you mean" suggestions:
+
+```ruby
+class InvoiceExportType < BaseObject
+  authorize :read, model: Invoice, visible_when: :export     # InvoicePolicy#export? / can?(:export, Invoice)
+end
+
+field :internal_notes, String, authorize: :manage, visible_when: :export
+```
+
+`visible_when:` is an action like any other, but it is asked **of the model's class, with no record**: `InvoicePolicy.new(user, Invoice).export?` with Pundit, `can?(:export, Invoice)` with CanCanCan. Write a method that decides from the user (`user.admin?`), not from the record. Nothing is hidden unless you declare it, and the audit reports a `visible_when:` action the policy does not define.
+
+A hidden member also hides what leads only to it: a root field that returns a hidden type disappears with it.
+
+**Schema dumps.** graphql 2.6 builds an ordinary context for `to_definition`, which cannot be told apart from an anonymous request, and an anonymous request must never see hidden members. Ask for the full schema explicitly:
+
+```ruby
+AppSchema.to_definition(context: { armory_full_schema: true })
+```
+
+Things to know:
+
+- **Hiding is not authorization.** A hidden field is absent from the schema, so a query for it fails like a field that never existed. What the user may *read* is still decided by `authorize`.
+- **The policy receives the class.** A policy that reads the record (`record.account_id`) raises `NoMethodError` for a `visible_when:` action; write that action from the user. The error propagates out of `execute`, so make sure your error handler does not echo it.
+- **CanCanCan conditions are not applied to a class.** `can :export, Invoice, account_id: 1` makes the member visible to anyone who holds the rule. For a field, the attribute is passed: `can?(:export, Invoice, :internal_notes)`.
+- **A subclass that redeclares `authorize` replaces the rule**, `visible_when:` included: repeat it.
+- **`visible_when:` on a field needs a type that includes `Base`** (not an interface or a plain type); otherwise it raises `ConfigurationError` when a query selects it.
+- **Static `Schema::Visibility` profiles are not supported** and raise `ConfigurationError`; plain `use Schema::Visibility`, `dynamic: true` and the default warden work.
+
+Visibility is computed per query (and memoized inside it). Role-based profile caching across requests is graphql-ruby's `Schema::Visibility` feature and is not wrapped here.
+
+## Arguments
+
+An argument with no rule is **covered by its field**: the field already decides whether the user may call it. Declare a rule on the arguments that must be stricter, and they are checked when the client sends them:
+
+```ruby
+class BaseArgument < GraphQL::Schema::Argument
+  include GraphQL::Armory::Authorization::Base
+end
+# in your base field: argument_class BaseArgument
+
+field :invoices, [InvoiceType], authorize: :none, reason: "narrowed by the scope" do
+  argument :include_internal, Boolean, required: false, authorize: :manage, model: Invoice
+  argument :tag, String, required: false, visible_when: :export, model: Invoice
+  argument :status, String, required: false, authorize: :none, reason: "public filter"
+end
+```
+
+- **`authorize: :manage`** asks the policy about the parent object when it is an instance of the model, otherwise about the model's class (a root field has no record, so write the action from the user). The model is the one the field's type wraps, or `model:` when it wraps none, as on a root field. A denial denies the whole field, with the usual null or error.
+- **Defaults.** graphql-ruby does not check an argument the client left at its default, and the two engines disagree about it (the interpreter skips the check, `Execution::Next` applies the default), so a restricted argument with a `default_value:` is refused with an `ArgumentError`. Sending `false` explicitly counts as using the argument.
+- **Every argument class needs `Base`.** `argument_class` is not inherited: set it on your base field, and also on resolvers, input objects (for restricted arguments nested in a filter) and directives that need it.
+- **`visible_when:`** hides the argument like it hides a field: it is absent from introspection and from suggestions, and a query that uses it fails like an argument that never existed.
+- **`authorize: :none, reason:`** only declares and documents: the audit lists it with its reason.
+- `authorize: true` is refused on an argument, and an argument with no model to ask about raises `ConfigurationError`.
+
+## Mutations and resolvers
+
+Include `Base` in your base mutation (or resolver) and declare what each one needs. A mutation is an action, not a read, so `default_action` does not apply and **a mutation with no `authorize` is denied**.
+
+```ruby
+class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
+  include GraphQL::Armory::Authorization::Base
+  argument_class Types::BaseArgument
+  field_class Types::BaseField
+  object_class Types::BaseObject
+end
+
+class Mutations::ApproveInvoice < Mutations::BaseMutation
+  authorize :approve, model: Invoice            # InvoicePolicy#approve?(invoice) / can?(:approve, invoice)
+  argument :invoice_id, ID, loads: Types::Invoice
+  field :invoice, Types::Invoice, null: true
+end
+```
+
+- **The record is the loaded one.** The rule runs after `loads:`, once per loaded record of the model (with none loaded, the model's class is asked). `loads:` goes through the user's scope, so a foreign id answers like a missing one.
+- **Denial** follows the schema's `on_unauthorized` mode, like a field (`null`, `"Not found"`, or raise). With `on_denied: :errors` the mutation does not run and answers `{ errors: [{ message: "Not allowed", code: "FORBIDDEN" }] }` as data, so the payload needs an `errors` field.
+- **Payload types** are ordinary objects: declare `authorize :none, reason: "...", covers_fields: true` so their fields are covered by the mutation instead of denied.
+- **`authorize :none, reason:`** documents a mutation anyone may call; the audit lists it with its reason. A mutation with no rule appears as `:no_rule` (for example `Mutation.forgotten`), and a rule the policy does not define as `:adapter`.
+- An unknown `on_denied:` raises `ArgumentError`; a mutation with a rule but no model raises `ConfigurationError`.
+- **Class-level answers are weak.** With no loaded record of the model (no `loads:`, an empty `loads: [ID]`, or a `loads:` of another type) the rule is asked about the model's class: CanCan answers true for anyone holding the right, and a Pundit policy that reads `record` attributes raises. Load the record you are authorizing.
+- **`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.
+
+## Interfaces and unions
+
+They are never authorized themselves: graphql-ruby only runs `authorized?` on the concrete type, and every path ends there (root field, association, each list item, `loads:`, union and interface resolution). A foreign object in a list of a union or an interface comes back `null`, like in any other list. So `include Base` in an interface or a union is refused with a message pointing to the possible types; declare the rule on each concrete type.
+
+What an interface adds is its fields, declared once and resolved on many types:
+
+- A field with no rule is **covered** by the rule of the Base types that implement the interface (a plain implementer runs no check at all), unless one of them is a bypass (`authorize :none`). Then the field is **denied for every implementer**, because it cannot tell which type it runs on, and the audit reports it (`:field_without_rule`, for example `Document.number`). Declare it (`authorize: :none, reason:` or an action) to fix it.
+- `visible_when:` is not supported on an interface field; put it on the concrete types' fields.
+- `authorize: true` is not valid on an interface field: it is always denied, and the audit reports it. Use an action or `:none`.
+- An interface whose field class does not include `Base`, such as graphql-ruby's built-in Relay `Node`, runs no field check, so its `id` stays readable on a bypassed implementer. The audit reports it (`:unprotected`, `Node.id`); give your own `Node` interface a Base field class if that matters.
+- The audit reports an interface field once, on the interface that declares it, not again on each implementer.
+
+## Telemetry
+
+Pass `sinks: [->(signal, data) {}]`. Signals are `:allowed`, `:denied`, `:bypassed`; data holds only `type`, `action` and `reason`, never record attributes.
+
+## Guarantees and limits
+
+Covered by the black-box suite in `spec/security`, on both engines: user A cannot read user B's objects by root field, nested association or `loads:`; lists never contain foreign objects; uncovered types fail closed and show in the audit; a field hidden with `visible?` is absent from introspection and error suggestions (that is graphql-ruby's behaviour, pinned by a test).
+
+Policies must return `true`/`false`/`nil`; anything else raises `AdapterError`. Do not use `dataloader.request` inside policies; use `dataloader.with(...).load`.
+
+## Engines
+
+Both execution engines are tested: the default interpreter and `Execution::Next`. In graphql 2.5.26 to 2.6.1, Next crashes on denied fields, so the gem refuses to run on Next there (`ConfigurationError`). Everything else works from graphql 2.4.
+
+## Performance
+
+`benchmark/authorization.rb`, 1000 invoices, graphql 2.6.2, Ruby 3.2, Docker on Windows:
+
+| Engine | Query | plain | armory (array) | armory (relation) |
+|---|---|---|---|---|
+| interpreter | `number` | 117.6 i/s | 45.9 i/s | 44.2 i/s |
+| interpreter | 3 fields | 58.8 i/s | 21.6 i/s | 21.0 i/s |
+| next | `number` | 654.2 i/s | 71.8 i/s | 70.8 i/s |
+| next | 3 fields | 417.5 i/s | 42.1 i/s | 39.5 i/s |
+
+The absolute cost is about 13 to 15 ms per 1000 items on both engines; most of it is probably Pundit's policy lookup, which is not cached so code reloading cannot serve stale classes. Run it yourself: `docker compose run --rm test bundle exec ruby benchmark/authorization.rb` (add `GRAPHQL_ARMORY_ENGINE=next` for Next).
+
+## Migrating
+
+Coming from hand-written `authorized?` and `scope_items`? See [MIGRATING.md](../MIGRATING.md).

data/docs/encrypted-ids.md

@@ -0,0 +1,136 @@
+# Encrypted IDs and cursors
+
+IDs and pagination cursors that clients can neither read, guess, nor forge.
+
+## The problem
+
+graphql-ruby's IDs and cursors are base64, which is an encoding, not encryption. A Relay ID such as `SW52b2ljZS80Mg` is `Invoice/42` to anyone who decodes it, and a cursor such as `MTA` is the position `10`. From them a client can:
+
+- **Guess other IDs.** `Invoice/43`, `Invoice/44`… or `User/1`, `Admin/1`. Authorization still decides what it may read, but every guess costs you a lookup and probes your API.
+- **Learn about your business.** Sequential IDs tell how many invoices or users you have and how fast they grow.
+- **Edit cursors** to jump anywhere in a list or count its rows.
+
+## The solution
+
+`GraphQL::Armory::Encoder` encrypts and authenticates them with AES-256-GCM:
+
+- **Opaque.** The ID of `Invoice/42` looks like `x0Tn…Qw`; nothing in it can be read.
+- **Tamper-proof.** Change one character, use another key or another tag, and it does not decode. Every failure gives the same error, `Invalid ID or cursor`, without saying why.
+- **Stable IDs.** The same object always has the same ID, so client caches (Apollo, Relay) keep working. Its nonce is derived from the ID, so two different IDs do not share one (a collision needs around 2^48 IDs).
+- **Unpredictable cursors.** The same position gives a different cursor in every response.
+- **IDs and cursors are not interchangeable.** Each uses its own derived key.
+- **One line for the whole schema.** `use GraphQL::Armory::IDs` defines `id_from_object` and `object_from_id`, looking records up inside the user's scope.
+- **Keys can be rotated, and encryption added to an existing API**, without breaking the IDs and cursors clients already hold: a versioned chain reads old values and writes new ones.
+
+## How to use it
+
+Generate a key once and keep it out of the code: `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`, and set it as `GRAPHQL_ARMORY_KEY` (in a Rails app you can skip this: a key is derived from `secret_key_base`, see [the default encoder](#the-default-encoder)).
+
+```ruby
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::Authorization, adapter: :pundit   # optional, but recommended
+  use GraphQL::Armory::IDs                               # encrypted global IDs
+  cursor_encoder GraphQL::Armory::Encoder.default        # encrypted cursors
+end
+```
+
+`use GraphQL::Armory::IDs` defines `id_from_object` and `object_from_id` for you. An ID holds the type name and the record's id, encrypted. When the schema decodes one:
+
+- A type that includes the authorization module's `Base` is looked up **inside the user's scope**, so another tenant's ID answers `null`, like a missing record (in `node(id:)`, `loads:` and anything else that calls `object_from_id`).
+- A tampered ID, an ID made with another key, an unknown type, a type hidden from this user (`visible_when:`), or a type that is not an object type implementing `Node` (root types, payloads, introspection) answer `null` too, with no error.
+- A type without `Base` is loaded only if you say how: `use GraphQL::Armory::IDs, find: ->(type, key, context) { ... }`. Otherwise its IDs answer `null`. `find:` only sees `Node` types; return `nil` for a missing record (`find_by`, not `find`): an error it raises reaches the client.
+- A `Base` type named unlike its model (Rails' `Types::InvoiceType`) needs `authorize :read, model: Invoice`, or every lookup of it raises `ConfigurationError`.
+
+Pass your own encoder with `use GraphQL::Armory::IDs, encoder: AppEncoder` (or a versioned chain, below).
+
+### Your own encoder
+
+```ruby
+class AppEncoder < GraphQL::Armory::Encoder
+  key ENV.fetch("GRAPHQL_ARMORY_KEY")
+end
+
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::IDs, encoder: AppEncoder
+  cursor_encoder AppEncoder                      # every built-in connection now uses encrypted cursors
+end
+```
+
+Without the plugin, call the encoder from your own `id_from_object` and `object_from_id` (`AppEncoder.encode("#{type.graphql_name}/#{object.id}")` and `AppEncoder.decode(id)`). With the [authorization module](authorization.md), an ID the encoder refuses in a `loads:` argument is answered exactly like a missing record.
+
+### The default encoder
+
+If you do not need your own encoder class, use the default one. It never ships a key: it takes `GRAPHQL_ARMORY_KEY` from the environment or, in a Rails app, derives a key of its own from `secret_key_base` with HKDF (purpose `graphql-armory/ids`, so the Rails secret itself is never used to encrypt). Without either, it raises when the schema loads (at boot, with eager loading) instead of serving unencrypted IDs.
+
+```ruby
+class AppSchema < GraphQL::Schema
+  cursor_encoder GraphQL::Armory::Encoder.default
+end
+```
+
+`GRAPHQL_ARMORY_KEY` wins over Rails; an empty value counts as unset, and a value with surrounding whitespace is refused (another process might strip it and get other IDs). Changing `secret_key_base` changes every ID: if you rotate it, keep the old encoder in a versioned chain (below). The key does not depend on any other Rails setting: it does not use `Rails.application.key_generator`, whose digest changes during boot. With `SECRET_KEY_BASE_DUMMY` Rails invents a secret per process, so IDs do not survive a restart; set a real secret where IDs matter. `MyEncoder.default` keeps `MyEncoder`'s tag and codec but replaces its key with the default one.
+
+## Rotating keys and migrating from base64
+
+Put encoders in a chain, newest first. The chain encodes with the first and decodes with whichever accepts the value, so clients keep working while you change keys:
+
+```ruby
+class AppEncoder2026 < GraphQL::Armory::Encoder
+  key ENV.fetch("GRAPHQL_ARMORY_KEY")
+end
+
+class AppEncoder2025 < GraphQL::Armory::Encoder
+  key ENV.fetch("GRAPHQL_ARMORY_OLD_KEY")
+end
+
+AppIDs = GraphQL::Armory::Encoder.versioned(AppEncoder2026, AppEncoder2025)
+# cursor_encoder AppIDs, and AppIDs.encode / AppIDs.decode in id_from_object / object_from_id
+```
+
+Drop the old encoder from the chain once its values have expired (cursors are short-lived; IDs may be bookmarked or cached by clients for longer).
+
+**Adding encryption to an existing API.** `GraphQL::Armory::Encoder::Legacy` reads graphql-ruby's default base64 (padded or not, url-safe or standard), so the IDs and cursors clients already hold keep working:
+
+```ruby
+AppIDs = GraphQL::Armory::Encoder.versioned(AppEncoder, GraphQL::Armory::Encoder::Legacy)
+```
+
+`Legacy` is not encryption: while it is in the chain, anyone can still forge a base64 value. It only accepts printable text, so a tampered full-length encrypted value does not come back as data (a truncated one may decode to short gibberish, like any forged value). Do not put `GraphQL::Schema::Base64Encoder` in a chain: it would turn tampered values into binary data. To treat old values differently, ask which encoder decoded them:
+
+```ruby
+data, encoder = AppIDs.decode_versioned(id)
+return nil if encoder.nil?                                  # nothing in the chain accepted it
+log_legacy_id(id) if encoder == GraphQL::Armory::Encoder::Legacy
+```
+
+## Reference
+
+| Declaration | Meaning |
+|---|---|
+| `key "..."` | Required. At least 32 bytes. Subkeys for IDs and cursors are derived from it with HKDF. |
+| `tag "v1"` | Optional authenticated data. An ID made with another tag does not decode: use it to separate apps or environments sharing a key. |
+| `codec MyCodec` | Optional. How the encrypted bytes become text; anything with `encode(bytes)` and `decode(text)`. Default: base64url without padding. Any error it raises while decoding becomes `InvalidError`. |
+
+| Call | Returns |
+|---|---|
+| `encode(text)` | A stable, encrypted ID. |
+| `encode(text, nonce: true)` | A cursor, different every time. |
+| `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` | Defines `id_from_object` and `object_from_id`; `encoder` defaults to `Encoder.default`; `find:` loads types without `Base`. |
+| `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.
+
+## Guarantees and limits
+
+Covered by `spec/security/encoder_spec.rb`, `encoder_versioning_spec.rb`, `default_encoder_spec.rb` and `ids_plugin_spec.rb` on both engines: round trips, tampering at several positions, another key, another tag, a cursor used as an ID and the reverse, malformed and truncated input, encrypted pagination and a tampered cursor, rotation and migration from base64 cursors, where the default encoder takes its key, and the plugin answering every ID it cannot honour (foreign, tampered, unknown or non-object type, another model in `loads:`) like a missing one.
+
+- **Changing the key invalidates every ID and cursor already handed out**, unless the old encoder stays in a versioned chain.
+- **`Legacy` in a chain can be forged**, and it does not separate IDs from cursors. Keep it only while migrating.
+- **Encryption hides the ID; it does not authorize.** Whoever obtained a valid ID can still send it. What they may read is decided by the authorization module.
+- IDs are longer than base64 ones: 28 extra bytes (nonce and authentication tag) before encoding.
+- graphql-ruby decodes an `after:` cursor once per selection that uses it, so a tampered cursor can produce the same error more than once.
+- Without the plugin, graphql-ruby's own `node(id:)` field does not rescue errors: a refused ID answers `Invalid ID or cursor` while a missing record answers `null`. `use GraphQL::Armory::IDs` answers both with `null`.
+- The plugin builds IDs from `object.id` and looks them up by primary key: composite primary keys are not supported.

data/lib/graphql/armory/authorization/integration.rb

@@ -78,11 +78,12 @@ module GraphQL
         end
 
         # `GlobalID.find`, graphql-ruby's documented `object_from_id`, raises for a missing record, and a
-        # decoder may raise for a malformed id. Both must answer like a record out of scope: nil.
+        # decoder may raise for a malformed id (ArgumentError, or the Encoder's InvalidError). All must answer like a
+        # record out of scope: nil.
         def self.decode(schema, id, context)
           schema.object_from_id(id, context)
         rescue StandardError => error
-          raise unless error.is_a?(ArgumentError) || error.class.name == "ActiveRecord::RecordNotFound"
+          raise unless error.is_a?(ArgumentError) || error.is_a?(Encoder::InvalidError) || error.class.name == "ActiveRecord::RecordNotFound"
 
           nil
         end

data/lib/graphql/armory/encoder/default.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      ENV_KEY = "GRAPHQL_ARMORY_KEY"
+      RAILS_PURPOSE = "graphql-armory/ids"
+
+      # An encoder whose key comes from the app, never from the gem: `GRAPHQL_ARMORY_KEY`, or else a key derived
+      # with HKDF from Rails' secret_key_base for this purpose alone. Without either it raises, so the app fails
+      # when the schema loads instead of serving unencrypted IDs.
+      #
+      # It reads `secret_key_base` instead of `Rails.application.key_generator`: that generator is built once per
+      # process with whatever digest Rails has configured at that moment, which changes during boot, so the same
+      # secret could give different IDs in a web server and in a rake task (and calling it early would also fix
+      # Rails' own cookie keys to the wrong digest).
+      def self.default(env: ENV, rails: rails_application)
+        secret = env_key(env)
+        secret = rails_key(rails) if secret.nil? && rails
+        if secret.nil?
+          raise ConfigurationError,
+                "no key for the default encoder: set #{ENV_KEY} (try `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`), " \
+                "or run inside a Rails app with a secret_key_base"
+        end
+
+        Class.new(self) { key(secret) }
+      end
+
+      def self.env_key(env)
+        value = env[ENV_KEY].to_s
+        return nil if value.empty?
+        if value.strip != value || value.strip.empty?
+          raise ConfigurationError, "#{ENV_KEY} has leading or trailing whitespace, or only whitespace: remove it"
+        end
+
+        value
+      end
+      private_class_method :env_key
+
+      def self.rails_application
+        ::Rails.application if defined?(::Rails) && ::Rails.respond_to?(:application)
+      end
+      private_class_method :rails_application
+
+      def self.rails_key(rails)
+        secret = begin
+          rails.secret_key_base
+        rescue StandardError => error
+          # Rails' message may come from app code; name only its class so nothing secret is echoed.
+          raise ConfigurationError, "the default encoder could not read Rails' secret_key_base (#{error.class})"
+        end
+        raise ConfigurationError, "this Rails app has no secret_key_base for the default encoder" if secret.to_s.empty?
+
+        OpenSSL::KDF.hkdf(secret.to_s, salt: "graphql-armory", info: RAILS_PURPOSE, length: 32, hash: "SHA256")
+      end
+      private_class_method :rails_key
+    end
+  end
+end

data/lib/graphql/armory/encoder/legacy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module GraphQL
+  module Armory
+    class Encoder
+      # graphql-ruby's default base64, to keep reading the cursors and IDs clients already hold while migrating to
+      # encryption: put it last in `Encoder.versioned`. It reads base64 padded or not, url-safe or standard, and
+      # only when it holds printable text, so a tampered encrypted value never comes back as garbage. It is not
+      # encryption: anyone can forge what it reads. Remove it from the chain once old values have expired.
+      module Legacy
+        PRINTABLE = /\A[[:print:]]*\z/
+
+        def self.encode(text, nonce: false)
+          Base64.urlsafe_encode64(text.to_s, padding: false)
+        end
+
+        def self.decode(text, nonce: false)
+          raise InvalidError unless text.is_a?(String) && !text.empty?
+
+          plain = Base64.urlsafe_decode64(text.tr("+/", "-_").delete_suffix("==").delete_suffix("="))
+          raise InvalidError if plain.empty?
+          plain.force_encoding(Encoding::UTF_8)
+          raise InvalidError unless plain.valid_encoding? && plain.match?(PRINTABLE)
+
+          plain
+        rescue StandardError
+          raise InvalidError
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder/versioned.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      # A chain of encoders, newest first: encodes with the first, decodes with whichever accepts the value.
+      # Build it with `Encoder.versioned(NewEncoder, OldEncoder, Encoder::Legacy)`.
+      class Versioned
+        attr_reader :encoders
+
+        def initialize(encoders)
+          raise ConfigurationError, "a versioned encoder needs at least one encoder" if encoders.empty?
+
+          encoders.each { |encoder| check(encoder) }
+          @encoders = encoders.freeze
+        end
+
+        def encode(text, nonce: false)
+          encoders.first.encode(text, nonce: nonce)
+        end
+
+        def decode(text, nonce: false)
+          data, encoder = decode_versioned(text, nonce: nonce)
+          raise InvalidError unless encoder
+
+          data
+        end
+
+        # The data and the encoder that decoded it, or `[nil, nil]`, so the app can treat old values differently.
+        def decode_versioned(text, nonce: false)
+          encoders.each do |encoder|
+            data = encoder.decode(text, nonce: nonce)
+            return [data, encoder] if data.is_a?(String)
+          rescue ConfigurationError
+            raise
+          rescue StandardError
+            next
+          end
+          [nil, nil]
+        end
+
+        private
+
+        # Fails at boot for a member that would otherwise refuse every value at request time.
+        def check(encoder)
+          unless %i[encode decode].all? { |name| encoder.respond_to?(name) }
+            raise ConfigurationError, "#{encoder.inspect} cannot be versioned: it must respond to encode and decode"
+          end
+          unless %i[encode decode].all? { |name| accepts_nonce?(encoder.method(name)) }
+            raise ConfigurationError, "#{encoder.inspect} cannot be versioned: encode and decode must accept `nonce:`"
+          end
+          return unless encoder.respond_to?(:key) && encoder.respond_to?(:tag) && encoder.key.nil?
+
+          raise ConfigurationError, "#{encoder.inspect} cannot be versioned: it has no key"
+        end
+
+        def accepts_nonce?(method)
+          method.parameters.any? { |kind, name| kind == :keyrest || (%i[key keyreq].include?(kind) && name == :nonce) }
+        end
+      end
+
+      def self.versioned(*encoders)
+        Versioned.new(encoders)
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module GraphQL
+  module Armory
+    # Encrypts and authenticates IDs and cursors with AES-256-GCM. Subclass it and set a key:
+    #
+    #   class AppEncoder < GraphQL::Armory::Encoder
+    #     key ENV.fetch("GRAPHQL_ARMORY_KEY")
+    #   end
+    #
+    # Cursors (`nonce: true`, as graphql-ruby's connections ask) get a random nonce, so the same position
+    # never gives the same cursor. IDs must be stable, so their nonce is derived from the ID itself with an
+    # HMAC: the same ID always encrypts the same way, and two different IDs never share a nonce.
+    # IDs and cursors use separate keys, so one is never accepted as the other.
+    class Encoder
+      # Raised for anything that does not decode: tampered, foreign, malformed. The message never says which.
+      class InvalidError < GraphQL::ExecutionError
+        def initialize(message = "Invalid ID or cursor")
+          super
+        end
+      end
+
+      class ConfigurationError < Armory::Error; end
+
+      # graphql-ruby's default text form for cursors: base64url without padding.
+      module URLSafeBase64
+        def self.encode(bytes)
+          Base64.urlsafe_encode64(bytes, padding: false)
+        end
+
+        def self.decode(text)
+          Base64.urlsafe_decode64(text)
+        end
+      end
+
+      MINIMUM_KEY_BYTES = 32
+      NONCE_BYTES = 12
+      AUTH_TAG_BYTES = 16
+      CIPHER = "aes-256-gcm"
+
+      class << self
+        # The key, at least 32 bytes. With no argument, answers it (inherited from the parent class).
+        def key(*value)
+          return setting(:@key, nil) if value.empty?
+
+          secret = value.first
+          unless secret.is_a?(String) && secret.bytesize >= MINIMUM_KEY_BYTES
+            raise ConfigurationError, "an Encoder key must be a String of at least #{MINIMUM_KEY_BYTES} bytes (try SecureRandom.hex(32))"
+          end
+
+          @key = secret
+        end
+
+        # Authenticated data: an ID made with another tag does not decode. Use it to separate apps or versions.
+        def tag(*value)
+          return setting(:@tag, "") if value.empty?
+          raise ConfigurationError, "an Encoder tag cannot be nil" if value.first.nil?
+
+          @tag = value.first.to_s
+        end
+
+        # Turns the encrypted bytes into text and back. Anything with `encode(bytes)` and `decode(text)`.
+        def codec(*value)
+          return setting(:@codec, URLSafeBase64) if value.empty?
+          raise ConfigurationError, "an Encoder codec must respond to encode and decode" unless %i[encode decode].all? { |name| value.first.respond_to?(name) }
+
+          @codec = value.first
+        end
+
+        def encode(text, nonce: false)
+          purpose = nonce ? :cursor : :id
+          bytes = text.to_s.b
+          iv = nonce ? OpenSSL::Random.random_bytes(NONCE_BYTES) : derived_nonce(bytes)
+          cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+          cipher.key = subkey(purpose, :cipher)
+          cipher.iv = iv
+          cipher.auth_data = tag
+          sealed = cipher.update(bytes) + cipher.final
+          codec.encode(iv + sealed + cipher.auth_tag)
+        end
+
+        def decode(text, nonce: false)
+          purpose = nonce ? :cursor : :id
+          bytes = codec.decode(text.to_s)
+          # One text form only: a base64 variant with other padding bits is not the same ID.
+          raise InvalidError unless codec.encode(bytes) == text.to_s
+          raise InvalidError if bytes.bytesize < NONCE_BYTES + AUTH_TAG_BYTES
+
+          iv = bytes[0, NONCE_BYTES]
+          cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+          cipher.key = subkey(purpose, :cipher)
+          cipher.iv = iv
+          cipher.auth_tag = bytes[-AUTH_TAG_BYTES..]
+          cipher.auth_data = tag
+          plain = cipher.update(bytes[NONCE_BYTES...-AUTH_TAG_BYTES]) + cipher.final
+          # An ID has one valid form only: its nonce must be the one derived from it.
+          raise InvalidError if !nonce && !OpenSSL.fixed_length_secure_compare(iv, derived_nonce(plain))
+
+          plain.force_encoding(Encoding::UTF_8)
+        rescue ConfigurationError
+          raise
+        rescue StandardError
+          # Whatever the codec, OpenSSL or the input raise, the client learns only that it did not decode.
+          raise InvalidError
+        end
+
+        private
+
+        def setting(ivar, default)
+          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+          superclass.respond_to?(:key) ? superclass.send(:setting, ivar, default) : default
+        end
+
+        def derived_nonce(bytes)
+          OpenSSL::HMAC.digest("SHA256", subkey(:id, :nonce), tag.b + "\0".b + bytes)[0, NONCE_BYTES]
+        end
+
+        # Separate keys per purpose and use, derived with HKDF and cached by the secret they come from, so a key
+        # changed later (here or in a parent class) is used at once.
+        def subkey(purpose, use)
+          secret = key or raise ConfigurationError, "#{name || "Encoder"} has no key: call `key` in its class body"
+          @subkeys ||= {}
+          @subkeys[[secret, purpose, use]] ||= OpenSSL::KDF.hkdf(secret, salt: "graphql-armory", info: "#{purpose}/#{use}",
+                                                                         length: 32, hash: "SHA256")
+        end
+      end
+    end
+  end
+end
+
+require "graphql/armory/encoder/versioned"
+require "graphql/armory/encoder/legacy"
+require "graphql/armory/encoder/default"

data/lib/graphql/armory/ids.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    # Encrypted global IDs in one line:
+    #
+    #   class AppSchema < GraphQL::Schema
+    #     use GraphQL::Armory::IDs                         # the default encoder
+    #     use GraphQL::Armory::IDs, encoder: AppEncoder    # or your own
+    #   end
+    #
+    # Defines `id_from_object` (the type name and the record's id, encrypted) and `object_from_id`, which only
+    # honours visible object types that implement Node. A type that
+    # includes the authorization module's Base is looked up inside the user's scope; any other type only through
+    # `find: ->(type, key, context) { ... }`. Every ID that cannot be honoured answers nil, like a missing record.
+    module IDs
+      SEPARATOR = "/"
+
+      def self.use(schema, encoder: nil, find: nil)
+        lookup = Lookup.new(encoder: encoder || Encoder.default, find: find)
+        schema.define_singleton_method(:id_from_object) { |object, type, _context| lookup.id_for(object, type) }
+        schema.define_singleton_method(:object_from_id) { |id, context| lookup.object_for(id, context) }
+      end
+
+      # Turns records into IDs and IDs back into records.
+      class Lookup
+        attr_reader :encoder, :find
+
+        def initialize(encoder:, find: nil)
+          @encoder = encoder
+          @find = find
+        end
+
+        def id_for(object, type)
+          key = object.id
+          raise Encoder::ConfigurationError, "#{type.graphql_name} object has no id to build a global ID from" if key.nil?
+
+          encoder.encode("#{type.graphql_name}#{SEPARATOR}#{key}")
+        end
+
+        def object_for(id, context)
+          type_name, key = encoder.decode(id).split(SEPARATOR, 2)
+          return nil if key.nil? || key.empty?
+
+          type = visible_type(type_name, context)
+          return nil unless node_type?(type)
+
+          load(type, key, context)
+        rescue Encoder::InvalidError
+          nil
+        end
+
+        private
+
+        # Through the query's own view of the schema: `Schema.get_type(name, context)` does not apply `visible?`
+        # when graphql-ruby runs without `Schema::Visibility`, `context.types` does in both modes.
+        def visible_type(type_name, context)
+          context.respond_to?(:types) ? context.types.type(type_name) : context.schema.get_type(type_name, context)
+        end
+
+        # Only object types that implement Node can have handed out an ID: root types, payloads and introspection
+        # types never did, so an ID naming them is not honoured (and their model is never looked up).
+        def node_type?(type)
+          type.respond_to?(:kind) && type.kind.object? &&
+            type.interfaces.any? { |interface| interface.graphql_name == "Node" }
+        end
+
+        def load(type, key, context)
+          return Authorization::Integration.find(type, nil, key, context) if type.respond_to?(:armory_model)
+
+          find&.call(type, key, context)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Armory
-    VERSION = "0.1.0.pre2"
+    VERSION = "0.1.0.pre3"
   end
 end

data/lib/graphql/armory.rb

@@ -10,4 +10,6 @@ module GraphQL
   end
 end
 
+require "graphql/armory/encoder"
 require "graphql/armory/authorization"
+require "graphql/armory/ids"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-armory
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre2
+  version: 0.1.0.pre3
 platform: ruby
 authors:
 - Israel
@@ -41,6 +41,8 @@ files:
 - LICENSE
 - MIGRATING.md
 - README.md
+- docs/authorization.md
+- docs/encrypted-ids.md
 - lib/graphql-armory.rb
 - lib/graphql/armory.rb
 - lib/graphql/armory/authorization.rb
@@ -72,6 +74,11 @@ files:
 - lib/graphql/armory/authorization/rule.rb
 - lib/graphql/armory/authorization/scope.rb
 - lib/graphql/armory/authorization/telemetry.rb
+- lib/graphql/armory/encoder.rb
+- lib/graphql/armory/encoder/default.rb
+- lib/graphql/armory/encoder/legacy.rb
+- lib/graphql/armory/encoder/versioned.rb
+- lib/graphql/armory/ids.rb
 - lib/graphql/armory/version.rb
 - lib/tasks/graphql_armory.rake
 homepage: https://github.com/israelb/graphql-armory