standard_id-oidc 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0def62e4e3706d23a1c7725241984627119723c47ab8b37a6b18cd2612263fe6
+  data.tar.gz: 14b29713e5737c10d314829fd7ae89e8fa2a3099d2c15ebefe72bd0b68f994f0
+SHA512:
+  metadata.gz: d05a49f2f2b26e11ed1215a603809669854ea3d8b7d2d5cea08e2e32dcbce2b2df3d1fbac0eebdba8e7761bbf8780c82460a24cd34b9822600d83b5b619a474b
+  data.tar.gz: e83d15c6f6a92da90678c4712985104ccaa57e335313271e1ec009cc2b45befd886b77ae14d9d17b695367d335bdbfc21aa30c284ffd26f2958ba40bdb167e42

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,231 @@
+# StandardId::Oidc
+
+> [!WARNING]
+> **Experimental.** This engine is not used in production by any rarebit-one
+> app, `prepend`s into non-public `standard_id` internals (see below), and its
+> API may change in any minor release. Pin an exact version if you adopt it.
+
+> [!NOTE]
+> **Formerly `standard_id-provider`.** That gem's final release is 0.5.0. To
+> migrate, swap `gem "standard_id-provider"` for `gem "standard_id-oidc"`.
+> Existing code keeps loading for now. `require "standard_id/provider"` still
+> works, and `StandardId::Provider` is a deprecated alias of `StandardId::Oidc`
+> (that includes `StandardId::Provider::Engine` in your routes). Both will be
+> removed in a future minor release. Then rename:
+>
+> | Before | After |
+> |---|---|
+> | `StandardId::Provider::…` | `StandardId::Oidc::…` |
+> | `rails g standard_id:provider:install` | `rails g standard_id:oidc:install` (the old generator name has **no** compat path: it fails with "Could not find generator") |
+> | `config/initializers/standard_id_provider.rb` | `config/initializers/standard_id_oidc.rb` (the file name is cosmetic) |
+>
+> The shim covers runtime code only (the constant and the require path), not
+> the generator name. You don't need to re-run the generator to upgrade. If you
+> do, it treats `.standard_id_provider` migrations, the old initializer file and
+> a `StandardId::Provider::Engine` mount as already installed.
+>
+> Unchanged: the `c.provider.*` settings (they configure the identity-provider
+> role), the table names (`standard_id_consent_grants`,
+> `standard_id_revoked_tokens`), and the migrations. Rails skips re-copying a
+> migration whose name already exists.
+
+OpenID Connect Identity Provider addon for [`standard_id`](https://github.com/rarebit-one/standard_id).
+
+`standard_id` gives you OAuth 2.0 — authorization codes, token exchange, refresh
+tokens, sessions. This engine adds the parts that make it an **OpenID Connect
+identity provider**:
+
+| | |
+|---|---|
+| **ID tokens** | Signed OIDC ID tokens issued alongside access tokens, with `nonce`, `auth_time`, `at_hash` and `c_hash` |
+| **Consent** | Per-`(account, client)` scope grants, checked on subsequent authorization requests |
+| **Access-token revocation** | An RFC 7009 endpoint backed by a `jti` denylist — the thing that makes revoking a *stateless* access token actually bite |
+| **Discovery** | `/.well-known/openid-configuration`, built from core's document builder so it cannot drift |
+
+## Read this before adopting it
+
+**This engine `prepend`s into non-public `standard_id` internals.** That is not
+an implementation detail you can ignore — it is the coupling you are taking on.
+
+It prepends into five classes, none of which are part of `standard_id`'s public
+API and none of which carry a stability guarantee:
+
+| Class | Why |
+|---|---|
+| `StandardId::Oauth::TokenGrantFlow` | issue an ID token with the access token; stamp `jti` |
+| `StandardId::Oauth::AuthorizationCodeAuthorizationFlow` | carry `nonce` / consent through authorization |
+| `StandardId::Oauth::Subflows::TraditionalCodeGrant` | ditto, for the traditional code grant |
+| `StandardId::Oauth::AuthorizationCodeFlow` | ditto |
+| `StandardId::Api::Oauth::IntrospectionsController` | contribute the revocation denylist into core's RFC 7662 endpoint (a **private** method) |
+
+What that means in practice:
+
+* **A `standard_id` minor release can break this gem** without breaking its own
+  semver contract, because the coupling is to internals rather than API.
+* The gemspec therefore pins `standard_id` to `~> 0.33` — the oldest version
+  this gem's suite has actually been run against.
+* A **`compat` CI job** resolves against the latest *published* `standard_id`
+  and runs the full suite against it on every push, so a break surfaces here
+  before it surfaces in your app.
+
+If you want OIDC without that coupling, you want `standard_id` on its own plus
+your own ID-token issuance. If you want the coupling handled for you, this is
+the gem.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "standard_id-oidc"
+```
+
+```bash
+bundle install
+rails generate standard_id:oidc:install
+rails db:migrate
+```
+
+The generator:
+
+* copies the engine's migrations (`consent_grants`, `revoked_tokens`) into
+  `db/migrate/`
+* writes `config/initializers/standard_id_oidc.rb`
+* mounts the engine in `config/routes.rb`
+
+It is **idempotent** — re-running skips anything already installed and says so.
+
+| Flag | Effect |
+|---|---|
+| `--skip-migrations` | leave `db/migrate/` alone |
+| `--skip-initializer` | do not write the initializer |
+| `--skip-routes` | do not touch `config/routes.rb` |
+| `--mount-path PATH` | mount somewhere other than `/` |
+| `--force` | overwrite an existing initializer |
+
+## Mounting
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount StandardId::Oidc::Engine => "/"
+  mount StandardId::WebEngine => "/", as: :standard_id_web
+
+  scope "api" do
+    mount StandardId::ApiEngine => "/", as: :standard_id_api
+  end
+end
+```
+
+The engine serves, relative to its own mount:
+
+| Route | What |
+|---|---|
+| `GET /.well-known/openid-configuration` | OIDC discovery document |
+| `POST /api/provider/revoke` | RFC 7009 revocation — writes the `jti` denylist |
+| `GET\|POST\|DELETE /api/provider/consent` | consent grant management |
+
+Introspection is **not** here — see below.
+
+## Configuration
+
+The generator writes a fully commented initializer. Two settings are load-bearing
+and easy to miss.
+
+### `discovery_endpoint_base` — required
+
+```ruby
+StandardId.configure do |c|
+  c.issuer = "https://auth.example.com"
+  c.oauth.discovery_endpoint_base = ->(request:) { "#{request.base_url}/api" }
+end
+```
+
+The **issuer** and the **endpoint base** are different things. The issuer is a
+stable security identifier (RFC 8414 §2) that clients match byte-for-byte
+against their discovery URL and against the `iss` claim of issued tokens. The
+endpoint base is merely where the endpoints live.
+
+This engine's discovery document is served from the *Provider* engine's mount.
+Core's own well-known controllers sit inside the `ApiEngine` mount and can read
+it out of `SCRIPT_NAME`; this one cannot. If you do not name the base, the
+document will advertise URLs that 404.
+
+Use `discovery_metadata_overrides` for members that cannot be derived — a
+host-owned authorization shim, a deliberately narrower scope list. They are
+applied last and win over everything else. Setting `issuer` there raises.
+
+### `introspection_enabled` — opt-in, and it is core's endpoint
+
+```ruby
+c.oauth.introspection_enabled = true
+```
+
+RFC 7662 introspection is **core's** endpoint (`POST /oauth/introspect`), not
+this engine's. It is off by default and 404s until you opt in.
+
+This engine used to ship a second one. It no longer does, because core's is
+strictly more conformant — RFC 7662 §2.2 requires every failure mode to render
+`{"active": false}` and nothing else, and this gem's answered `401` on bad
+client credentials and `429` when throttled, which let a caller distinguish
+"your credentials are wrong" and "you are throttled" from "that token is not
+valid". The 429 in particular was a token-validity oracle.
+
+What this engine contributes instead is the one thing core cannot do alone.
+Access tokens are stateless, so core "cannot invalidate a stateless JWT before
+its `exp`". This engine's revocation endpoint maintains a `jti` denylist, and
+`IntrospectionsControllerExt` teaches core's endpoint to consult it — so a
+revoked access token introspects as inactive immediately rather than staying
+active until it expires.
+
+### Provider settings
+
+```ruby
+c.provider.id_token_lifetime      = 3600
+c.provider.scopes_supported       = %w[openid profile email offline_access]
+c.provider.claims_supported       = %w[sub iss aud exp iat nonce auth_time at_hash email name email_verified]
+c.provider.subject_types_supported = %w[public]
+c.provider.revocation_enabled     = true   # false renders /api/provider/revoke as 404
+```
+
+The `*_supported` lists are advertised in the discovery document. They describe
+what you are willing to issue — narrow them rather than widen them.
+
+## Development
+
+```bash
+bin/rails app:db:test:prepare        # build the dummy app's test database
+bundle exec rspec
+bundle exec rubocop --config .rubocop.yml
+bundle exec brakeman --no-pager --force
+bundle exec bundler-audit --update
+```
+
+Specs run against `spec/dummy`, a host app mounting this engine alongside
+`StandardId::WebEngine` and `StandardId::ApiEngine`. `spec/dummy/db/schema.rb`
+and the vendored `spec/dummy/db/migrate/*.standard_id.rb` are committed;
+refresh them with:
+
+```bash
+bin/rails app:standard_id:install:migrations
+bin/rails app:db:migrate
+```
+
+`spec/dummy/config/database.yml` sets `migrations_paths` explicitly. **Leave it
+that way** — without it Rails falls back to the relative default `"db/migrate"`,
+which resolves against RSpec's working directory rather than the dummy app, and
+the suite aborts on permanently-pending migrations.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/rarebit-one/standard_id-oidc>.
+
+Work happens in a git worktree, never the main checkout — see `CLAUDE.md`.
+Commits are signed. CI runs RuboCop, Brakeman, bundler-audit, the full suite on
+Ruby 4.0.0–4.0.4, and the `compat` job against the latest published
+`standard_id`.
+
+## License
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/standard_id/oidc/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/standard_id/oidc/application_controller.rb

@@ -0,0 +1,45 @@
+module StandardId
+  module Oidc
+    class ApplicationController < ActionController::API
+      # Provides the shared rate-limit store + the TooManyRequests -> JSON 429
+      # handler (Retry-After header included), matching the standard_id engine's
+      # rate-limit response shape. Individual controllers declare their limits.
+      include StandardId::RateLimitHandling
+
+      rescue_from StandardId::OAuthError do |e|
+        render json: { error: e.oauth_error_code, error_description: e.message }, status: e.http_status
+      end
+
+      private
+
+      def authenticate_client!
+        extract_client_credentials_from_basic_auth
+
+        @client_credential = StandardId::ClientSecretCredential.active.find_by(client_id: params[:client_id])
+
+        unless @client_credential&.authenticate_client_secret(params[:client_secret])
+          raise StandardId::InvalidClientError, "Client authentication failed"
+        end
+
+        @client_credential
+      end
+
+      def extract_client_credentials_from_basic_auth
+        auth_header = request.headers["Authorization"]
+        return unless auth_header&.start_with?("Basic ")
+
+        if params[:client_id].present? || params[:client_secret].present?
+          raise StandardId::InvalidRequestError,
+            "Client credentials must be sent via Authorization header OR request body, not both"
+        end
+
+        decoded = Base64.strict_decode64(auth_header.split(" ", 2).last)
+        client_id, client_secret = decoded.split(":", 2)
+        params[:client_id] = CGI.unescape(client_id)
+        params[:client_secret] = CGI.unescape(client_secret)
+      rescue ArgumentError
+        raise StandardId::InvalidClientError, "Invalid Basic authentication encoding"
+      end
+    end
+  end
+end

data/app/controllers/standard_id/oidc/consent_controller.rb

@@ -0,0 +1,91 @@
+module StandardId
+  module Oidc
+    class ConsentController < ApplicationController
+      include ActionController::Cookies
+
+      before_action :require_authentication
+      before_action :load_client
+
+      def show
+        render json: {
+          client: { name: @client.name, description: @client.description },
+          scopes: requested_scopes,
+          authorization_params: authorization_params
+        }
+      end
+
+      def create
+        ConsentGrant.grant!(
+          account: current_account,
+          client_application: @client,
+          scopes: authorization_params[:scope]
+        )
+
+        authorize_url = build_authorize_redirect
+        redirect_to authorize_url, allow_other_host: true, status: :found
+      end
+
+      def destroy
+        redirect_uri = authorization_params[:redirect_uri]
+
+        if redirect_uri.present?
+          deny_url = build_error_redirect(redirect_uri, "access_denied", "The user denied the consent request")
+          redirect_to deny_url, allow_other_host: true, status: :found
+        else
+          render json: { error: "access_denied", error_description: "The user denied the consent request" }, status: :forbidden
+        end
+      end
+
+      private
+
+      def require_authentication
+        return if current_account.present?
+
+        render json: { error: "login_required", error_description: "Authentication is required" }, status: :unauthorized
+      end
+
+      def current_account
+        @current_account ||= begin
+          token_manager = StandardId::Web::TokenManager.new(request)
+          session_manager = StandardId::Web::SessionManager.new(token_manager, request: request, session: session, cookies: cookies)
+          session_manager.current_account
+        end
+      end
+
+      def load_client
+        @client = StandardId::ClientApplication.active.find_by(client_id: authorization_params[:client_id])
+
+        unless @client
+          raise StandardId::InvalidClientError, "Invalid client_id"
+        end
+      end
+
+      def authorization_params
+        @authorization_params ||= params.permit(
+          :client_id, :redirect_uri, :scope, :state, :audience,
+          :nonce, :response_type, :code_challenge, :code_challenge_method
+        ).to_h.symbolize_keys
+      end
+
+      def requested_scopes
+        authorization_params[:scope].to_s.split(/\s+/)
+      end
+
+      def build_authorize_redirect
+        uri = URI.parse("#{StandardId.config.issuer}/api/authorize")
+        uri.query = URI.encode_www_form(authorization_params.compact)
+        uri.to_s
+      end
+
+      def build_error_redirect(redirect_uri, error, description)
+        uri = URI.parse(redirect_uri)
+        query = URI.decode_www_form(uri.query || "")
+        query << [ "error", error ]
+        query << [ "error_description", description ]
+        query << [ "state", authorization_params[:state] ] if authorization_params[:state].present?
+        uri.query = URI.encode_www_form(query)
+        uri.to_s
+      end
+    end
+  end
+end

data/app/controllers/standard_id/oidc/discovery_controller.rb

@@ -0,0 +1,106 @@
+module StandardId
+  module Oidc
+    # OpenID Connect Discovery (`GET /.well-known/openid-configuration`).
+    #
+    # ## Why this no longer builds the document by hand
+    #
+    # It used to interpolate every endpoint off the issuer with a hardcoded
+    # `/api` segment:
+    #
+    #     authorization_endpoint: "#{issuer}/api/authorize"
+    #
+    # That is the same defect core fixed in standard_id 0.33.0. It is wrong two
+    # ways at once: it assumes ApiEngine is mounted at exactly `/api`, and it
+    # conflates the ISSUER with the ENDPOINT BASE. Those are different things —
+    # the issuer is a stable security identifier (RFC 8414 §2) that clients
+    # match byte-for-byte against their discovery URL and against the `iss`
+    # claim, while the endpoint base is merely where the endpoints happen to
+    # live. An app whose issuer does not carry the mount path got a document
+    # advertising URLs that 404.
+    #
+    # Resolution is now core's: StandardId::Oauth::DiscoveryResolver reads
+    # `config.oauth.discovery_endpoint_base` and
+    # `config.oauth.discovery_metadata_overrides`, and the document itself is
+    # built by StandardId::Oauth::DiscoveryDocument, so this document cannot
+    # drift from the two core serves.
+    #
+    # ## Setting `discovery_endpoint_base` is not optional for this engine
+    #
+    # Core's own well-known controllers can derive the base from the request,
+    # because they are served from INSIDE the ApiEngine mount, where
+    # `request.script_name` IS the mount path. This controller is served from
+    # the PROVIDER engine's mount, which is a different mount (typically `/`).
+    # `:request` would therefore resolve to the origin root and advertise
+    # `<origin>/oauth/token` for an ApiEngine mounted at `/api`.
+    #
+    # So a host serving this document must say where ApiEngine actually is:
+    #
+    #     c.oauth.discovery_endpoint_base = ->(request:) { "#{request.base_url}/api" }
+    #     # or, for a fixed deployment:
+    #     c.oauth.discovery_endpoint_base = "https://auth.example.com/api"
+    #
+    # That is the hardcoded `/api` moving out of gem code and into host config,
+    # which is the point.
+    class DiscoveryController < ApplicationController
+      def show
+        resolved = StandardId::Oauth::DiscoveryResolver.resolve(request: request)
+
+        if resolved[:issuer].blank?
+          render json: { error: "Issuer not configured" }, status: :not_found
+          return
+        end
+
+        response.headers["Cache-Control"] = "public, max-age=3600"
+        render json: openid_configuration(resolved)
+      end
+
+      private
+
+      def openid_configuration(resolved)
+        doc = StandardId::Oauth::DiscoveryDocument.build(
+          resolved[:issuer],
+          endpoint_base: resolved[:endpoint_base],
+          registration_enabled: StandardId.config.oauth.dynamic_registration_enabled,
+          introspection_enabled: StandardId.config.oauth.introspection_enabled
+        )
+
+        doc.merge!(provider_members)
+
+        # Host overrides are applied LAST so they win over the provider members
+        # too, matching how core's controllers treat them.
+        StandardId::Oauth::DiscoveryDocument.apply_overrides!(doc, resolved[:overrides])
+      end
+
+      # Only the OIDC IdP members core has no opinion on.
+      #
+      # Deliberately NOT re-stated here, though the old hand-built document did:
+      #
+      #   * `response_types_supported: %w[code token]` — this engine extends the
+      #     authorization-code flows only. Advertising the implicit flow's
+      #     `token` promised something nothing implements.
+      #   * `code_challenge_methods_supported: %w[S256 plain]` — core enforces
+      #     PKCE with S256 and does not accept `plain`. Advertising it invites a
+      #     downgrade attempt that is then rejected.
+      #   * `id_token_signing_alg_values_supported` — core derives it from
+      #     `config.oauth.signing_algorithm`, which is the same value.
+      #
+      # `revocation_endpoint` IS replaced: core advertises its own
+      # `/oauth/revoke`, but THIS engine's revoke action is the one that writes
+      # the StandardId::Oidc::RevokedToken denylist that introspection then
+      # consults. Built from the engine's own route helper so it follows the
+      # mount rather than hardcoding a prefix.
+      def provider_members
+        provider_config = StandardId.config.provider
+
+        {
+          revocation_endpoint: standard_id_oidc.revoke_url(
+            host: request.host_with_port, protocol: request.protocol
+          ),
+          scopes_supported: provider_config.scopes_supported,
+          subject_types_supported: provider_config.subject_types_supported,
+          claims_supported: provider_config.claims_supported
+        }
+      end
+    end
+  end
+end

data/app/controllers/standard_id/oidc/revocation_controller.rb

@@ -0,0 +1,49 @@
+module StandardId
+  module Oidc
+    class RevocationController < ApplicationController
+      # Throttle by IP (30 per 15 min) BEFORE client authentication so this
+      # credential-guessable RFC 7009 endpoint can't be brute-forced. Override
+      # with RATE_LIMIT_REVOKE_PER_IP.
+      rate_limit to: (ENV["RATE_LIMIT_REVOKE_PER_IP"] || 30).to_i,
+                 within: 15.minutes,
+                 by: -> { request.remote_ip },
+                 name: "provider-revoke-ip",
+                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+      before_action :require_revocation_enabled!
+      before_action :authenticate_client!
+
+      def create
+        token = params[:token]
+        return head :ok if token.blank?
+
+        payload = StandardId::JwtService.decode(token)
+        return head :ok if payload.nil?
+
+        jti = payload[:jti]
+        return head :ok if jti.blank?
+
+        expires_at = payload[:exp] ? Time.at(payload[:exp]) : 1.day.from_now
+
+        RevokedToken.revoke!(
+          jti: jti,
+          client_id: @client_credential.client_id,
+          token_type: params[:token_type_hint],
+          expires_at: expires_at
+        )
+
+        head :ok
+      end
+
+      private
+
+      # `config.provider.revocation_enabled` was declared from the start and
+      # read by nothing, so the switch silently did not work. Enforced here,
+      # 404 rather than 403 so a disabled endpoint is indistinguishable from
+      # one that does not exist — matching how core gates introspection.
+      def require_revocation_enabled!
+        head(:not_found) unless StandardId.config.provider.revocation_enabled
+      end
+    end
+  end
+end

data/app/helpers/standard_id/oidc/application_helper.rb

@@ -0,0 +1,6 @@
+module StandardId
+  module Oidc
+    module ApplicationHelper
+    end
+  end
+end

data/app/jobs/standard_id/oidc/application_job.rb

@@ -0,0 +1,6 @@
+module StandardId
+  module Oidc
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/mailers/standard_id/oidc/application_mailer.rb

@@ -0,0 +1,8 @@
+module StandardId
+  module Oidc
+    class ApplicationMailer < ActionMailer::Base
+      default from: "from@example.com"
+      layout "mailer"
+    end
+  end
+end

data/app/models/standard_id/oidc/application_record.rb

@@ -0,0 +1,7 @@
+module StandardId
+  module Oidc
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/standard_id/oidc/consent_grant.rb

@@ -0,0 +1,41 @@
+module StandardId
+  module Oidc
+    class ConsentGrant < ApplicationRecord
+      self.table_name = "standard_id_consent_grants"
+
+      belongs_to :account, class_name: StandardId.config.account_class_name
+      belongs_to :client_application, class_name: "StandardId::ClientApplication"
+
+      validates :scopes, presence: true
+
+      scope :active, -> { where(revoked_at: nil) }
+      scope :revoked, -> { where.not(revoked_at: nil) }
+
+      before_validation :set_granted_at, on: :create
+
+      def self.grant!(account:, client_application:, scopes:)
+        transaction do
+          active.where(account: account, client_application: client_application).each(&:revoke!)
+          create!(account: account, client_application: client_application, scopes: scopes)
+        end
+      rescue ActiveRecord::RecordNotUnique
+        retry
+      end
+
+      def revoke!
+        update!(revoked_at: Time.current)
+      end
+
+      def covers_scopes?(requested_scopes)
+        granted = scopes.to_s.split(/\s+/)
+        (requested_scopes - granted).empty?
+      end
+
+      private
+
+      def set_granted_at
+        self.granted_at ||= Time.current
+      end
+    end
+  end
+end