Imported from vertigo-prime/devise_scim (AGENTS.md). Install upstream with npx skills add vertigo-prime/devise_scim. Copyright stays with the author.

AGENTS.md

This is devise_scim — a SCIM 2.0 server engine for Rails + Devise applications.

Key directory layout

Required checks before any commit

Run all three before opening a PR. A single failure is a blocker.

bundle exec rspec                              # 0 failures required
bundle exec rubocop                            # 0 offenses required (run --autocorrect for safe fixes first)
bundle exec brakeman --force --no-pager        # 0 security warnings required

Configuration contract

All configuration lives in DeviseScim::Configuration (lib/devise_scim/configuration.rb). The generated initializer template is lib/generators/devise_scim/templates/devise_scim.rb.tt.

Rule: changing a default or adding a new attribute requires updating both files. The .tt template is what host apps receive — it must stay in sync with configuration.rb.

Validation is in Configuration#validate! — add a corresponding guard there for any new attribute with a constrained value set.

Migration template location

Templates live in lib/generators/devise_scim/templates/*.rb.tt.

The multi-tenant templates reference the tenant_fk_column helper method defined in InstallGenerator — it resolves to scim_tenant_id for the built-in model or <tenant_model_underscored>_id for a custom one. The add_scim_to_tenant.rb.tt template guards every add_column with unless column_exists? so it is safe to run against an existing table.

Auth strategies

lib/devise_scim/auth/
  base_strategy.rb    # extracts Bearer token from Authorization header
  token_strategy.rb   # compares against config.token (single) or tenant_model.authenticate_token (multi)
  oauth_strategy.rb   # validates Doorkeeper access tokens
lib/devise_scim/middleware/authenticator.rb

Authenticator is a Rack middleware inserted early in the stack. It intercepts every request whose path starts with route_prefix, delegates to the appropriate strategy, and either sets env["devise_scim.tenant"] (multi-tenant) or returns a 401 SCIM error response. It also calls warden.custom_failure! so Warden does not swallow the 401.

In multi-tenant mode with a custom tenant_model, auth strategies call class methods/columns on that model (authenticate_token, doorkeeper_application_id, active). Include DeviseScim::Concerns::ScimTenant on custom tenant models to satisfy that contract.

Do not move auth logic into controllers — the middleware layer is the single authentication boundary.

Filter system

lib/devise_scim/filter/
  parser.rb        # tokenizer + recursive descent parser → AST
  arel_visitor.rb  # walks AST → pure Arel conditions

The tokenizer uses explicit m = regex.match(s) calls rather than gsub to avoid $& clobbering. Keep it that way — String#gsub clears $& even for String patterns, which silently breaks the tokenizer.

ArelVisitor maps SCIM attribute names to AR column names and emits only Arel nodes — no string interpolation, ever. If you add a new filterable attribute, add it to the column mapping in ArelVisitor and add a spec in spec/filter/arel_visitor_spec.rb.

Adding a new SCIM attribute

1. Add the field to the relevant struct in lib/devise_scim/scim/user.rb or lib/devise_scim/scim/group.rb.
2. Update from_h to parse the new attribute from the incoming hash.
3. Update to_h to serialize it in the outgoing hash.
4. Update ScimAdapter#attributes_for_create, #attributes_for_update, and #to_scim defaults in lib/devise_scim/scim_adapter.rb as appropriate.
5. If the attribute is filterable, add the SCIM→column mapping to ArelVisitor.
6. Add spec coverage: a unit spec for the struct, a request spec or shared-example assertion for the endpoint.

Test app

spec/internal/ is a Combustion application loaded before the RSpec suite.

• Schema: spec/internal/db/schema.rb is loaded at suite start via ActiveRecord::Schema.define. Do not drop or rename existing tables or columns — doing so breaks specs that depend on those structures.
• Routes: spec/internal/config/routes.rb mounts three scim_for variants (default, groups-enabled, OAuth-enabled) to exercise conditional route generation. Keep all three.
• Models: spec/internal/app/models/ contains the minimal User and ScimGroup models used by the suite.

When adding a new integration spec, use the existing models and schema. Add columns to the schema only when genuinely required, and add them to the end of the relevant create_table block.

Commit message convention

• Imperative mood, under 72 characters on the subject line (Add, Fix, Remove, not Added / Fixes)
• Body explains why, not what — the diff already shows what changed
• Reference an issue number in the body when one exists (Closes #123)

Example:

Add :reassign exclusivity_conflict mode

Reassigning to a new tenant is safer than returning an error when an
IdP reprovisioning cycle runs across a tenant boundary. Closes #47.