seams 0.1.0

data/lib/generators/seams/auth/templates/app/models/identity.rb.tt

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Auth
+  # The canonical "who is logging in" record. Owns credentials
+  # (password digest, OAuth links, API tokens, sessions). Lives on
+  # `auth_identities` — a dedicated table so credentials are cleanly
+  # separated from any host-specific User concept (a "human" can exist
+  # in many hosts as the same Identity if they share a database, but
+  # have different per-host User profiles).
+  #
+  # Other engines address the human via Identity, not via a host User.
+  class Identity < ApplicationRecord
+    self.table_name = "auth_identities"
+
+    # Rails 8's has_secure_password ships the password-reset token
+    # machinery: `password_reset_token` (instance method, returns a
+    # signed_id with a 15-minute default expiry) and
+    # `find_by_password_reset_token(token, purpose: :password_reset)`.
+    # Once `Identity` has its own table the historical naming clash
+    # with a `password_reset_token` *column* is gone.
+    has_secure_password
+    has_many :sessions,        class_name: "Auth::Session",         foreign_key: :identity_id, dependent: :destroy
+    has_many :api_tokens,      class_name: "Auth::ApiToken",        foreign_key: :identity_id, dependent: :destroy
+    has_many :oauth_providers, class_name: "Auth::OAuth::Provider", foreign_key: :identity_id, dependent: :destroy
+
+    # Email is PII (GDPR Article 4). Stored encrypted at rest via Rails 7+
+    # ActiveRecord::Encryption. `deterministic: true` keeps `find_by(email:)`
+    # and the uniqueness index working — same plaintext yields the same
+    # ciphertext. `downcase: true` normalises before encryption so two
+    # casings of the same address collide as expected.
+    # Host setup: bin/rails db:encryption:init (one-off).
+    # See https://guides.rubyonrails.org/active_record_encryption.html
+    encrypts :email, deterministic: true, downcase: true
+
+    validates :email, presence: true, uniqueness: { case_sensitive: false }
+    validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+    validates :password,
+              length: { minimum: -> { Auth.configuration.password_min_length } },
+              if:     -> { password.present? }
+
+    normalizes :email, with: ->(value) { value.to_s.strip.downcase }
+
+    # Throwaway bcrypt hash to soak up the cost-12 ~100ms when the
+    # email lookup misses. Without this, `Identity.authenticate(email: ...)`
+    # returns in ~5ms for an unknown email and ~100ms for a known one
+    # — a measurable timing oracle that lets attackers enumerate
+    # registered identities. We pre-compute one digest at class load
+    # so every miss runs the same bcrypt work.
+    DUMMY_PASSWORD_DIGEST = BCrypt::Password.create("never-matches-anything", cost: BCrypt::Engine.cost).freeze
+
+    # Returns the Identity on success, nil on failure (no such identity OR
+    # wrong password). bcrypt's `#authenticate` returns `false` on
+    # failure; we coerce to `nil` so callers can use a uniform
+    # `if identity = Identity.authenticate(...)` idiom.
+    def self.authenticate(email:, password:)
+      identity = find_by(email: email.to_s.strip.downcase)
+      if identity
+        identity.authenticate(password) ? identity : nil
+      else
+        # Constant-time defence against enumeration: do the same
+        # bcrypt work even on a miss, then return nil.
+        BCrypt::Password.new(DUMMY_PASSWORD_DIGEST).is_password?(password.to_s)
+        nil
+      end
+    end
+
+    # Platform-admin predicate. Read-only convenience over the staff
+    # column; host admin tooling can call `identity.staff?` to bypass
+    # account-scope checks for support flows.
+    def staff?
+      !!staff
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/models/oauth/provider.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Auth
+  module OAuth
+    # Links an Auth::Identity to an external OAuth identity (Google
+    # account, GitHub account, etc.). One row per (identity, provider)
+    # pair — multiple rows per identity means the identity signed in
+    # with multiple providers, and the identity can be looked up via
+    # either.
+    #
+    # Tokens are encrypted at the database level via Rails 7+
+    # ActiveRecord::Encryption. Run `bin/rails db:encryption:init` once
+    # in the host to set the keys, then store them as Rails credentials
+    # — see https://guides.rubyonrails.org/active_record_encryption.html.
+    class Provider < ApplicationRecord
+      self.table_name = "auth_oauth_providers"
+
+      PROVIDERS = %w[google github].freeze
+
+      belongs_to :identity, class_name: "Auth::Identity", foreign_key: :identity_id
+
+      validates :provider,     presence: true, inclusion: { in: PROVIDERS }
+      validates :provider_uid, presence: true,
+                               uniqueness: { scope: :provider,
+                                             message: "is already linked to another account" }
+      validates :identity_id,  presence: true,
+                               uniqueness: { scope: :provider,
+                                             message: "already linked this provider" }
+
+      # access_token / refresh_token are credentials — encrypted with
+      # the default (non-deterministic) mode for maximum strength. We
+      # never query by these.
+      encrypts :access_token
+      encrypts :refresh_token
+
+      # provider_uid is the identity's stable id at the OAuth provider
+      # (Google `sub`, GitHub user id). It IS personal data under GDPR
+      # Article 4 ("online identifier"). Deterministic so the
+      # (provider, provider_uid) lookup that powers OAuth sign-in keeps
+      # resolving and the unique index keeps enforcing.
+      encrypts :provider_uid, deterministic: true
+
+      def access_token_expired?
+        expires_at && expires_at < Time.current
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/models/session.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Auth
+  class Session < ApplicationRecord
+    self.table_name = "auth_sessions"
+
+    belongs_to :identity, class_name: "Auth::Identity"
+
+    before_create :assign_token
+    before_create :assign_expiry
+
+    scope :active, -> { where("expires_at > ?", Time.current) }
+
+    def expired?
+      expires_at <= Time.current
+    end
+
+    private
+
+    def assign_token
+      self.token ||= SecureRandom.hex(32)
+    end
+
+    def assign_expiry
+      self.expires_at ||= Time.current + Auth.configuration.session_ttl
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/authenticate_identity.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Auth
+  # Sign-in service. Validates credentials, creates a session, returns
+  # a Result struct: ok?, identity, session, error.
+  class AuthenticateIdentity
+    Result = Struct.new(:ok?, :identity, :session, :error, keyword_init: true)
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(email:, password:)
+      @email    = email
+      @password = password
+    end
+
+    def call
+      identity = Auth::Identity.authenticate(email: @email, password: @password)
+      return Result.new(ok?: false, error: "Invalid email or password") unless identity
+
+      session = identity.sessions.create!
+      Seams::Events::Publisher.publish(
+        "identity.signed_in.auth",
+        identity_id: identity.id,
+        session_id:  session.id
+      )
+      Result.new(ok?: true, identity: identity, session: session)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/generate_api_token.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Auth
+  # Issues a new API token for an identity. Returns a Result with both
+  # the persisted ApiToken row AND the plaintext (which is the only
+  # time it's available — the DB only stores the digest).
+  module GenerateApiToken
+    Result = Struct.new(:ok?, :api_token, :plaintext, :error, keyword_init: true)
+
+    module_function
+
+    def call(identity:, name:, expires_at: nil)
+      plaintext = "#{ApiToken::PREFIX}#{SecureRandom.urlsafe_base64(ApiToken::PLAINTEXT_LENGTH)}"
+      record = identity.api_tokens.create!(
+        name:         name,
+        token_digest: ApiToken.digest(plaintext),
+        token_prefix: plaintext[0, ApiToken::PREFIX_DISPLAY],
+        expires_at:   expires_at
+      )
+
+      Seams::Events::Publisher.publish(
+        "api_token.issued.auth",
+        identity_id:  identity.id,
+        api_token_id: record.id,
+        token_prefix: record.token_prefix
+      )
+
+      Result.new(ok?: true, api_token: record, plaintext: plaintext)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(ok?: false, error: e.message)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/oauth/authenticator.rb.tt

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Auth
+  module OAuth
+    # Orchestrates the OAuth callback flow:
+    #
+    #   1. Exchange the authorization `code` for an access token.
+    #   2. Fetch the provider's user profile.
+    #   3. Find an existing Auth::OAuth::Provider row by (provider,
+    #      provider_uid) OR find an existing Auth::Identity by email OR
+    #      create a new Auth::Identity. Link the row to the identity.
+    #   4. Refresh stored token + profile.
+    #   5. Create a new Auth::Session.
+    #   6. Publish identity.signed_up.auth (first sign-in via OAuth) or
+    #      identity.signed_in.auth (returning identity).
+    #
+    # Returns a Result: ok?, identity, session, oauth_provider, new_identity, error.
+    class Authenticator
+      Result = Struct.new(:ok?, :identity, :session, :oauth_provider, :new_identity, :error,
+                          keyword_init: true)
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(provider:, code:, redirect_uri:)
+        @provider     = provider.to_s
+        @code         = code
+        @redirect_uri = redirect_uri
+      end
+
+      def call
+        adapter = Auth.oauth(@provider)
+        tokens  = adapter.exchange_code(code: @code, redirect_uri: @redirect_uri)
+        profile = adapter.fetch_user_info(access_token: tokens[:access_token])
+
+        return Result.new(ok?: false, error: "OAuth provider returned no email") if profile.email.blank?
+
+        oauth_row, identity, new_identity = link_or_create(profile, tokens)
+        session = identity.sessions.create!
+
+        Seams::Events::Publisher.publish(
+          new_identity ? "identity.signed_up.auth" : "identity.signed_in.auth",
+          identity_id: identity.id,
+          session_id:  session.id,
+          email:       identity.email
+        )
+
+        Result.new(ok?: true, identity: identity, session: session,
+                   oauth_provider: oauth_row, new_identity: new_identity)
+      rescue Auth::OAuthError, ActiveRecord::RecordInvalid => e
+        Result.new(ok?: false, error: e.message)
+      end
+
+      private
+
+      def link_or_create(profile, tokens)
+        Provider.transaction do
+          oauth_row = Provider.find_by(provider: @provider, provider_uid: profile.provider_uid)
+
+          new_identity = false
+          identity =
+            if oauth_row
+              oauth_row.identity
+            else
+              existing = Auth::Identity.find_by(email: profile.email.to_s.downcase)
+              existing || begin
+                new_identity = true
+                # Random unguessable password — OAuth identities don't have a
+                # password but the column is required. They sign in via
+                # the provider; password reset lets them set one later.
+                Auth::Identity.create!(
+                  email:    profile.email,
+                  password: SecureRandom.urlsafe_base64(32)
+                )
+              end
+            end
+
+          oauth_row ||= Provider.new(provider: @provider, provider_uid: profile.provider_uid, identity: identity)
+          oauth_row.assign_attributes(
+            access_token:  tokens[:access_token],
+            refresh_token: tokens[:refresh_token],
+            expires_at:    tokens[:expires_in] ? Time.current + tokens[:expires_in].to_i : nil,
+            token_type:    tokens[:token_type] || "Bearer",
+            profile_data:  profile.raw
+          )
+          oauth_row.save!
+
+          [oauth_row, identity, new_identity]
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/register_identity.rb.tt

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Auth
+  # Sign-up service. Creates the identity + first session in a transaction
+  # and publishes identity.signed_up.auth on success.
+  #
+  # Returns a Result struct: ok?, identity, session, error.
+  class RegisterIdentity
+    Result = Struct.new(:ok?, :identity, :session, :error, keyword_init: true)
+
+    # Whitelist of extra attributes a caller can hand in via
+    # `attributes:`. Anything outside this list is dropped — closes the
+    # mass-assignment hole where internal columns could be set from
+    # forwarded params. Add to the list as the auth_identities schema
+    # grows. NB: `staff` is intentionally NOT here — promotion is an
+    # admin operation, not a sign-up surface.
+    PERMITTED_EXTRA_ATTRIBUTES = %i[].freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(email:, password:, password_confirmation: nil, attributes: {})
+      @email                 = email
+      @password              = password
+      @password_confirmation = password_confirmation
+      @attributes            = sanitize(attributes)
+    end
+
+    def call
+      identity, session = nil
+      Auth::Identity.transaction do
+        identity = Auth::Identity.create!(@attributes.merge(
+          email: @email, password: @password, password_confirmation: @password_confirmation
+        ))
+        session  = identity.sessions.create!
+      end
+
+      Seams::Events::Publisher.publish(
+        "identity.signed_up.auth",
+        identity_id: identity.id,
+        email:       identity.email
+      )
+      Result.new(ok?: true, identity: identity, session: session)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(ok?: false, error: e.message)
+    end
+
+    private
+
+    def sanitize(attrs)
+      return {} if attrs.nil? || attrs.empty?
+
+      attrs.to_h.transform_keys(&:to_sym).slice(*PERMITTED_EXTRA_ATTRIBUTES)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/reset_password.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Auth
+  # Two-phase password reset, backed by Rails 8's built-in
+  # `has_secure_password` reset_token feature. The token is a signed_id
+  # with a built-in 15-minute expiry — no column, no sweep job, no
+  # `password_reset_token_sent_at` needed.
+  #
+  #   Auth::ResetPassword.request(email: "x@y.com")
+  #     → looks up the identity, generates a signed_id token, emails it
+  #
+  #   Auth::ResetPassword.complete(token: "...", new_password: "...")
+  #     → finds the identity by signed_id (Rails verifies expiry +
+  #       purpose), updates the password
+  #
+  # Both phases return a Result struct so the controller has a uniform
+  # success/failure shape regardless of which phase failed.
+  module ResetPassword
+    Result = Struct.new(:ok?, :identity, :error, keyword_init: true)
+
+    module_function
+
+    def request(email:)
+      identity = Auth::Identity.find_by(email: email.to_s.strip.downcase)
+      return Result.new(ok?: true) unless identity # don't leak which emails are registered
+
+      Auth::PasswordsMailer.reset_email(identity).deliver_later
+      Result.new(ok?: true, identity: identity)
+    end
+
+    def complete(token:, new_password:)
+      identity = Auth::Identity.find_by_password_reset_token(token)
+      return Result.new(ok?: false, error: "Invalid or expired reset link") unless identity
+
+      identity.update!(password: new_password)
+      Result.new(ok?: true, identity: identity)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(ok?: false, error: e.message)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/services/revoke_api_token.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Auth
+  # Destroys an Auth::ApiToken row and publishes the canonical
+  # api_token.revoked.auth event so subscribers (notifications,
+  # audit log) can react. Returns a Result with the same shape as
+  # GenerateApiToken so callers can branch uniformly.
+  #
+  #   result = Auth::RevokeApiToken.call(api_token: token)
+  #   result.ok?      # => true
+  #   result.api_token.destroyed?  # => true
+  #
+  # Idempotent: revoking an already-destroyed token returns an
+  # ok? = false Result with code: :not_found rather than raising.
+  module RevokeApiToken
+    Result = Struct.new(:ok?, :api_token, :error, :code, keyword_init: true)
+
+    module_function
+
+    def call(api_token:)
+      return Result.new(ok?: false, error: "API token not found", code: :not_found) if api_token.nil? || api_token.destroyed?
+
+      identity      = api_token.identity
+      api_token_id  = api_token.id
+      token_prefix  = api_token.token_prefix
+      api_token.destroy!
+
+      Seams::Events::Publisher.publish(
+        "api_token.revoked.auth",
+        identity_id:  identity&.id,
+        api_token_id: api_token_id,
+        token_prefix: token_prefix
+      )
+
+      Result.new(ok?: true, api_token: api_token)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/views/password_resets/edit.html.erb.tt

@@ -0,0 +1,12 @@
+<h1>Choose a new password</h1>
+
+<%% if flash[:alert] %><p style="color: red"><%%= flash[:alert] %></p><%% end %>
+
+<%%= form_with url: password_reset_path, method: :patch, local: true do |f| %>
+  <%%= hidden_field_tag :token, @token %>
+  <p>
+    <%%= label_tag :password, "New password" %>
+    <%%= password_field_tag :password, nil, required: true, autofocus: true %>
+  </p>
+  <%%= f.submit "Update password" %>
+<%% end %>

data/lib/generators/seams/auth/templates/app/views/password_resets/new.html.erb.tt

@@ -0,0 +1,11 @@
+<h1>Forgot your password?</h1>
+
+<%%= form_with url: password_reset_path, method: :post, local: true do |f| %>
+  <p>
+    <%%= label_tag :email %>
+    <%%= email_field_tag :email, nil, required: true, autofocus: true %>
+  </p>
+  <%%= f.submit "Send reset link" %>
+<%% end %>
+
+<p><%%= link_to "Back to sign in", new_session_path %></p>

data/lib/generators/seams/auth/templates/app/views/passwords_mailer/reset_email.html.erb.tt

@@ -0,0 +1,7 @@
+<h1>Reset your password</h1>
+
+<p>Click the link below to set a new password. The link is valid for 15 minutes.</p>
+
+<p><%%= link_to "Reset password", edit_password_reset_url(token: @token) %></p>
+
+<p>If you didn't request this, ignore this email — your password won't change.</p>

data/lib/generators/seams/auth/templates/app/views/registrations/new.html.erb.tt

@@ -0,0 +1,26 @@
+<h1>Create an account</h1>
+
+<%%= form_with model: @identity, url: registration_path, scope: :identity, local: true do |f| %>
+  <%% if @identity.errors.any? %>
+    <ul>
+      <%% @identity.errors.full_messages.each do |msg| %>
+        <li><%%= msg %></li>
+      <%% end %>
+    </ul>
+  <%% end %>
+  <p>
+    <%%= f.label :email %>
+    <%%= f.email_field :email, required: true, autofocus: true %>
+  </p>
+  <p>
+    <%%= f.label :password %>
+    <%%= f.password_field :password, required: true %>
+  </p>
+  <p>
+    <%%= f.label :password_confirmation %>
+    <%%= f.password_field :password_confirmation, required: true %>
+  </p>
+  <%%= f.submit "Sign up" %>
+<%% end %>
+
+<p><%%= link_to "Already have an account? Sign in", new_session_path %></p>

data/lib/generators/seams/auth/templates/app/views/sessions/_oauth_buttons.html.erb.tt

@@ -0,0 +1,18 @@
+<%%# Renders one "Sign in with X" link per configured OAuth provider. %>
+<%%# Drop into the sign-in / sign-up form: %>
+<%%#   <%%= render "auth/sessions/oauth_buttons" %> %>
+<%%# Override by replacing the file in your host. %>
+<%% if Auth.configuration.oauth_providers.any? %>
+  <section class="auth-oauth-buttons">
+    <p>Or sign in with:</p>
+    <ul>
+      <%% Auth.configuration.oauth_providers.each_key do |provider| %>
+        <li>
+          <%%= link_to "Sign in with #{provider.to_s.titleize}",
+                      auth.oauth_start_path(provider: provider),
+                      class: "auth-oauth-button auth-oauth-#{provider}" %>
+        </li>
+      <%% end %>
+    </ul>
+  </section>
+<%% end %>

data/lib/generators/seams/auth/templates/app/views/sessions/new.html.erb.tt

@@ -0,0 +1,17 @@
+<h1>Sign in</h1>
+
+<%% if flash[:alert] %><p style="color: red"><%%= flash[:alert] %></p><%% end %>
+
+<%%= form_with url: session_path, method: :post, local: true do |f| %>
+  <p>
+    <%%= label_tag :email %>
+    <%%= email_field_tag :email, nil, required: true, autofocus: true %>
+  </p>
+  <p>
+    <%%= label_tag :password %>
+    <%%= password_field_tag :password, nil, required: true %>
+  </p>
+  <%%= f.submit "Sign in" %>
+<%% end %>
+
+<p><%%= link_to "Create an account", new_registration_path %></p>

data/lib/generators/seams/auth/templates/config/routes.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Auth::Engine.routes.draw do
+  # Follow-up generators that ship sign-in alternatives (passkeys, magic links, SSO) splice their routes here, ahead of the password session resource so they take precedence.
+  # seams:insertion-point auth.routes.before_session
+  resource :session,        only: %i[new create destroy], controller: :sessions
+  resource :registration,   only: %i[new create],         controller: :registrations
+  resource :password_reset, only: %i[new create edit update]
+
+  # OAuth — one URL pair per configured provider. The :provider param
+  # is matched against Auth.configuration.oauth_providers at request
+  # time; unknown providers raise Auth::OAuthProviderUnknown which
+  # the controller handles.
+  scope "/oauth/:provider" do
+    get "start",    to: "oauth/callbacks#start",    as: :oauth_start
+    get "callback", to: "oauth/callbacks#callback", as: :oauth_callback
+  end
+
+  # Follow-up generators that add NEW route surfaces (API token UI, social-link admin) splice their resources here.
+  # seams:insertion-point auth.routes.after_oauth
+end

data/lib/generators/seams/auth/templates/db/migrate/create_auth_api_tokens.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# What: creates auth_api_tokens — Bearer-style API tokens issued to
+#       Auth::Identity rows for programmatic access.
+# Why:  the engine ships native API token support so hosts don't
+#       roll their own. Plaintext is shown once at creation; only the
+#       SHA-256 digest is persisted.
+# Risk: append-mostly. Unique index on token_digest enforces no
+#       collisions (cosmetic — SHA-256 collision space is huge).
+#       Partial index on expires_at speeds up the .active scope.
+class CreateAuthApiTokens < ActiveRecord::Migration[7.1]
+  def change
+    create_table :auth_api_tokens do |t|
+      t.references :identity,     null: false, foreign_key: { to_table: :auth_identities }
+      t.string     :name,         null: false   # human label ("CI deploy key")
+      t.string     :token_digest, null: false   # SHA-256 of the plaintext
+      t.string     :token_prefix, null: false   # first ~12 chars for display
+      t.datetime   :expires_at                  # nil = never expires
+      t.datetime   :last_used_at                # nil = never used
+      t.timestamps
+    end
+
+    add_index :auth_api_tokens, :token_digest, unique: true
+    add_index :auth_api_tokens, :expires_at, where: "expires_at IS NOT NULL"
+  end
+end

data/lib/generators/seams/auth/templates/db/migrate/create_auth_identities.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# What: creates the auth_identities table for the Auth engine.
+# Why:  Auth::Identity owns credentials (password digest, email) and
+#       acts as the canonical "who is logging in" record. Other engines
+#       address the human via Identity, not via the host's own User.
+# Risk: empty table on creation — no data migration needed.
+class CreateAuthIdentities < ActiveRecord::Migration[7.1]
+  def change
+    create_table :auth_identities do |t|
+      # `:text` (not `:string`) because `email` is encrypted via
+      # ActiveRecord::Encryption (deterministic). Stripe-style envelope
+      # ciphertext + base64 + IV/key-id headers expand a 30-char email
+      # to ~150–250 bytes; on MySQL `:string` defaults to VARCHAR(255)
+      # which silently truncates the cipher and breaks decryption.
+      # https://guides.rubyonrails.org/active_record_encryption.html#about-storage-and-column-size
+      t.text    :email,            null: false
+      t.string  :password_digest,  null: false
+      # Platform-admin flag. Identity-level (not Account-scoped) so
+      # host admin tooling can bypass account scoping for support.
+      # Default false — explicit opt-in only.
+      t.boolean :staff,            null: false, default: false
+      t.timestamps
+    end
+
+    add_index :auth_identities, :email, unique: true
+    add_index :auth_identities, :staff, where: "staff = true"
+  end
+end

data/lib/generators/seams/auth/templates/db/migrate/create_auth_oauth_providers.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# What: creates auth_oauth_providers — links Auth::Identity to external
+#       OAuth identities (Google, GitHub, etc.). One row per (identity,
+#       provider) pair.
+# Why:  the engine ships native OAuth support so hosts don't roll their
+#       own. Tokens are encrypted at the column level via
+#       ActiveRecord::Encryption — the host must run
+#       `bin/rails db:encryption:init` to seed the keys.
+# Risk: append-mostly. profile_data is a json column for the raw
+#       provider response (sub/login/etc) so we can re-derive things
+#       like display name without re-fetching.
+class CreateAuthOauthProviders < ActiveRecord::Migration[7.1]
+  def change
+    create_table :auth_oauth_providers do |t|
+      t.references :identity,     null: false, foreign_key: { to_table: :auth_identities }
+      t.string     :provider,     null: false
+      # `:text` because `provider_uid` is encrypted via
+      # ActiveRecord::Encryption (deterministic) — see Wave 11. Same
+      # ciphertext-overflow concern as auth_identities.email.
+      t.text       :provider_uid, null: false
+      # encrypts :access_token / :refresh_token store ciphertext as
+      # text. ActiveRecord::Encryption handles the (de)cipher.
+      t.text       :access_token
+      t.text       :refresh_token
+      t.datetime   :expires_at
+      t.string     :token_type,   default: "Bearer"
+      t.jsonb      :profile_data, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :auth_oauth_providers, %i[provider provider_uid], unique: true
+    add_index :auth_oauth_providers, %i[identity_id provider],  unique: true
+  end
+end