seams 0.1.0

data/lib/generators/seams/auth/templates/README.md.tt

@@ -0,0 +1,289 @@
+# Auth
+
+> Email + password authentication for a Seams-powered host application.
+> The canonical "human" record is `Auth::Identity` (post-Wave-9). Other
+> engines address the human via Identity, not via a host User.
+
+## Events emitted
+
+| Event name | Payload | Emitted when |
+| --- | --- | --- |
+| `identity.signed_up.auth`   | `{ identity_id:, email: }`              | RegistrationsController#create succeeds |
+| `identity.signed_in.auth`   | `{ identity_id:, session_id: }`         | SessionsController#create succeeds |
+| `identity.signed_out.auth`  | `{ identity_id:, session_id: }`         | SessionsController#destroy runs |
+| `session.expired.auth`      | `{ identity_id:, session_id: }`         | sweeper job revokes a stale session |
+
+> `identity_id` is the row id in the engine's `auth_identities` table.
+> Subscribers that resolve identities should use `identity_id`.
+
+## Events consumed
+
+This engine does not subscribe to any other engine's events.
+
+## Exposed concerns
+
+| Concern | Purpose |
+| --- | --- |
+| `Auth::Authenticatable` | Optional post-Wave-9. Mix into a host User (if you keep one) to add session-aware helpers (`signed_in?`, `sign_out_everywhere!`); the host model needs an `identity_id` column. Most hosts skip this — `Auth::Identity` is the canonical human. |
+| `Auth::Authentication`  | Mix into the host's ApplicationController to get `current_identity`, `signed_in?`, `authenticate_identity!` plus a per-request `Auth::Current.identity`. |
+
+## Adapters
+
+Password hashing is provided by `bcrypt` via Rails' `has_secure_password`.
+To swap in a different hasher, override `Auth::Identity`'s
+`password_digest=` setter in your host application.
+
+## Password reset (Rails 8 has_secure_password reset_token)
+
+`Auth::Identity` uses Rails 8's built-in reset token machinery — a
+signed_id with a 15-minute default expiry, generated on demand,
+verified via `find_by_password_reset_token`. **No `password_reset_token`
+column, no `password_reset_token_sent_at`, no sweep job.** Token
+expiry is a property of the signature, not a database row.
+
+To configure the expiry:
+
+```ruby
+class Auth::Identity < ApplicationRecord
+  has_secure_password reset_token: { expires_in: 30.minutes }
+end
+```
+
+## OAuth (Sign in with Google / GitHub)
+
+Two adapters ship with the engine — `Auth::OAuth::Google` and
+`Auth::OAuth::Github` — both built on Faraday. **No `oauth2` gem
+dependency**, no `Net::HTTP`. Adapter contract lives in
+`lib/auth/oauth/abstract.rb`; subclass it for additional providers
+(Apple, GitLab, Microsoft, etc.).
+
+### Configure
+
+```ruby
+# config/initializers/auth.rb
+Auth.configure do |c|
+  c.oauth_providers = {
+    google: {
+      adapter:       "Auth::OAuth::Google",
+      client_id:     ENV.fetch("GOOGLE_OAUTH_CLIENT_ID"),
+      client_secret: ENV.fetch("GOOGLE_OAUTH_CLIENT_SECRET")
+    },
+    github: {
+      adapter:       "Auth::OAuth::Github",
+      client_id:     ENV.fetch("GITHUB_OAUTH_CLIENT_ID"),
+      client_secret: ENV.fetch("GITHUB_OAUTH_CLIENT_SECRET")
+    }
+  }
+end
+```
+
+The provider's redirect URI must match the URL Rails generates for
+`auth.oauth_callback_url(provider: :google)` (e.g.
+`https://your-app.com/auth/oauth/google/callback`).
+
+### Token storage + encryption
+
+`Auth::OAuth::Provider` rows store `access_token` + `refresh_token`
+encrypted at the column level via Rails 7+ ActiveRecord::Encryption.
+**One-time host setup:**
+
+```bash
+bin/rails db:encryption:init
+```
+
+This prints three keys (primary, deterministic, key derivation salt).
+Store them in Rails credentials (`bin/rails credentials:edit`) under
+`active_record_encryption.*` — see
+https://guides.rubyonrails.org/active_record_encryption.html.
+
+### Render the sign-in buttons
+
+Drop the partial into your sessions or registrations form:
+
+```erb
+<%%= render "auth/sessions/oauth_buttons" %>
+```
+
+It iterates `Auth.configuration.oauth_providers` and renders one
+`auth.oauth_start_path(provider:)` link per configured provider.
+
+### Routes
+
+```
+GET  /auth/oauth/:provider/start    → redirect to provider's authorize URL
+GET  /auth/oauth/:provider/callback → exchange code, sign in, set cookie
+```
+
+Verified against:
+- https://developers.google.com/identity/protocols/oauth2/web-server
+- https://developers.google.com/identity/openid-connect/openid-connect
+- https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
+- https://docs.github.com/en/rest/users/users
+- https://docs.github.com/en/rest/users/emails
+
+## API tokens (Bearer auth)
+
+`Auth::ApiToken` ships with the engine for programmatic access. Tokens
+are issued via `Auth::GenerateApiToken.call(identity:, name:, expires_at:)`
+which returns a `Result` carrying both the persisted record and the
+**plaintext token** — the plaintext is shown ONCE and never recoverable
+from the DB (only a SHA-256 digest is stored).
+
+```ruby
+result = Auth::GenerateApiToken.call(identity: current_identity, name: "CI key")
+result.plaintext  # => "seam_tF9...xQ" — display once, then discard
+result.api_token  # => Auth::ApiToken row
+```
+
+Mix `Auth::ApiAuthenticatable` into API controllers and call
+`authenticate_api_token!` in a before_action:
+
+```ruby
+class Api::WidgetsController < ApplicationController
+  include Auth::ApiAuthenticatable
+  before_action :authenticate_api_token!
+end
+```
+
+Clients send `Authorization: Bearer seam_<token>`. On success the
+concern sets `current_identity` + `current_api_token` and bumps the
+token's `last_used_at`. On failure it renders 401 JSON.
+
+Events emitted:
+
+| Event name | Payload |
+| --- | --- |
+| `api_token.issued.auth`  | `{ identity_id:, api_token_id:, token_prefix: }` |
+| `api_token.revoked.auth` | `{ identity_id:, api_token_id:, token_prefix: }` |
+
+## Rate limiting
+
+The engine uses Rails 8's built-in `rate_limit` (backed by Solid Cache):
+
+| Controller | Action | Limit |
+| --- | --- | --- |
+| `SessionsController`       | `create`         | 10 / minute |
+| `RegistrationsController`  | `create`         | 5 / hour    |
+| `PasswordResetsController` | `create`, `update` | 5 / hour  |
+
+Tune by overriding the `rate_limit` declaration in your host app
+controllers. Solid Cache is the default Rails 8 cache store; if your
+host uses a different store, the limit applies to whatever cache backs
+`Rails.cache`.
+
+## Cleanup expired sessions
+
+`Auth::CleanupExpiredSessionsJob` sweeps expired `Auth::Session` rows
+and emits `session.expired.auth` for each one. Wire it as a Solid Queue
+Recurring entry in `config/recurring.yml`:
+
+```yaml
+auth_cleanup_expired_sessions:
+  class: Auth::CleanupExpiredSessionsJob
+  schedule: "every 1 hour"
+```
+
+## Platform admin (`staff?`)
+
+`Auth::Identity` ships with a `staff` boolean (default false) — an
+Identity-level platform-admin flag that host admin tooling can use to
+bypass account scoping. NOT related to per-account roles (those live
+on `Accounts::Membership`, owned by the accounts engine).
+
+```ruby
+identity.staff?       # => false (default)
+identity.update!(staff: true)
+identity.staff?       # => true
+```
+
+Promotion is an admin operation only — `Auth::RegisterIdentity` does
+NOT honour `staff:` from sign-up params.
+
+## GDPR / data protection
+
+Personal data the engine stores and how it's protected at rest:
+
+| Column                                   | At rest        | Why                                                  |
+| ---                                      | ---            | ---                                                  |
+| `auth_identities.email`                  | encrypted (deterministic) | PII (Article 4); deterministic so `find_by(email:)` and the uniqueness index keep working |
+| `auth_identities.password_digest`        | bcrypt one-way hash | not PII — never reversible to a password         |
+| `auth_oauth_providers.access_token`      | encrypted (non-deterministic) | credential                                |
+| `auth_oauth_providers.refresh_token`     | encrypted (non-deterministic) | credential                                |
+| `auth_oauth_providers.provider_uid`      | encrypted (deterministic) | online identifier (Article 4); deterministic so `(provider, provider_uid)` lookup + unique index keep working |
+| `auth_api_tokens.token_digest`           | SHA-256 hash   | not reversible to the plaintext token                |
+| `auth_api_tokens.token_prefix`           | plaintext      | first 12 chars only — display label, not a secret    |
+
+### One-time host setup
+
+```bash
+bin/rails db:encryption:init
+```
+
+Store the printed keys in Rails credentials
+(`bin/rails credentials:edit`) under `active_record_encryption.*`. See
+https://guides.rubyonrails.org/active_record_encryption.html.
+
+### Upgrading from Auth Wave ≤10 (existing hosts only)
+
+Hosts that deployed Auth before Wave 11 have plaintext `email` +
+`provider_uid` already in the database. Re-encrypt them in place:
+
+1. In `config/application.rb`, add the transitional flag so plaintext
+   rows are still readable while rotation runs:
+
+   ```ruby
+   config.active_record.encryption.support_unencrypted_data = true
+   ```
+
+2. Deploy + run:
+
+   ```bash
+   bin/rails seams:auth:rotate_pii_encryption
+   ```
+
+3. Once the task reports zero remaining unencrypted rows, remove the
+   flag (or set it back to `false`) and redeploy.
+
+The task is idempotent — re-running it on already-encrypted rows is a
+no-op. Fresh hosts skip steps 1 and 3 entirely.
+
+### Right to erasure (Article 17)
+
+```ruby
+Auth::Identity.find_by(email: "user@example.com").destroy
+```
+
+cascades to `sessions`, `api_tokens`, and `oauth_providers` via
+`dependent: :destroy`. Hosts that keep their own user-domain records
+linked by `identity_id` must additionally erase those rows — the
+engine does not own that schema.
+
+### Logging
+
+Don't log `email`. Log `identity_id` instead. Encryption protects the
+DB at rest but is moot if PII leaks into log files. Add the column to
+`config.filter_parameters` in your host:
+
+```ruby
+config.filter_parameters += %i[email password password_digest]
+```
+
+### Right to access / portability (Article 15 / 20)
+
+Not yet shipped — `Auth::ExportIdentityData` is on the roadmap. For
+now, hosts can export with a direct query against the identity's rows.
+
+## Mounting
+
+```ruby
+# config/routes.rb (host application)
+Rails.application.routes.draw do
+  mount Auth::Engine, at: "/auth"
+end
+```
+
+## Running the specs
+
+```bash
+bin/rails seams:test[auth]
+```

data/lib/generators/seams/auth/templates/app/controllers/oauth/callbacks_controller.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Auth
+  module OAuth
+    # Two endpoints per provider — the user-facing flow:
+    #   GET /auth/oauth/:provider/start    → redirect to provider's authorize URL
+    #   GET /auth/oauth/:provider/callback → exchange code + sign in
+    #
+    # State token: cryptographically random, stored in the session, and
+    # re-verified on callback. Mismatch ⇒ 403. Without this, an attacker
+    # can trick a victim into linking the attacker's OAuth identity to
+    # the victim's account.
+    class CallbacksController < ApplicationController
+      skip_before_action :verify_authenticity_token, only: %i[callback]
+
+      rescue_from Auth::OAuthProviderUnknown do |e|
+        redirect_to Auth.configuration.after_sign_out_url, alert: e.message
+      end
+
+      # GET /auth/oauth/:provider/start
+      def start
+        provider = params.require(:provider)
+        Auth.oauth(provider) # raises OAuthProviderUnknown if not configured
+
+        state = SecureRandom.urlsafe_base64(32)
+        session[oauth_state_key(provider)] = state
+
+        redirect_to Auth.oauth(provider).authorize_url(
+          state:        state,
+          redirect_uri: callback_url(provider)
+        ), allow_other_host: true, status: :see_other
+      end
+
+      # GET /auth/oauth/:provider/callback?code=...&state=...
+      def callback
+        provider       = params.require(:provider)
+        returned_state = params[:state]
+        expected_state = session.delete(oauth_state_key(provider))
+
+        if expected_state.nil? || returned_state != expected_state
+          return redirect_to Auth.configuration.after_sign_out_url, alert: "OAuth state mismatch"
+        end
+
+        if (error = params[:error])
+          return redirect_to Auth.configuration.after_sign_out_url,
+                             alert: "OAuth #{provider}: #{error}"
+        end
+
+        result = Auth::OAuth::Authenticator.call(
+          provider:     provider,
+          code:         params.require(:code),
+          redirect_uri: callback_url(provider)
+        )
+
+        if result.ok?
+          cookies.encrypted[Auth.configuration.cookie_name] = {
+            value:    result.session.token,
+            httponly: true,
+            secure:   request.ssl?,
+            expires:  result.session.expires_at
+          }
+          redirect_to Auth.configuration.after_sign_in_url,
+                      notice: result.new_identity ? "Welcome!" : "Signed in"
+        else
+          redirect_to Auth.configuration.after_sign_out_url, alert: result.error
+        end
+      end
+
+      private
+
+      def oauth_state_key(provider)
+        "auth_oauth_state_#{provider}"
+      end
+
+      def callback_url(provider)
+        url_for(action: :callback, provider: provider, only_path: false)
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/controllers/password_resets_controller.rb.tt

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Auth
+  class PasswordResetsController < ApplicationController
+    # 5 reset requests per hour per IP. Cheap to send mail but
+    # creating reset tokens for every email is a guess-the-user attack
+    # vector — rate-limit modestly.
+    rate_limit to: 5, within: 1.hour, only: %i[create update],
+               with: -> { redirect_to auth.new_session_path, alert: "Too many password-reset requests. Try again later." }
+
+    # GET /auth/password_reset/new
+    def new
+    end
+
+    # POST /auth/password_reset
+    def create
+      Auth::ResetPassword.request(email: params[:email])
+      # Don't leak whether the email exists — same response either way.
+      flash[:notice] = "If that email is registered, a reset link is on its way."
+      redirect_to new_session_path
+    end
+
+    # GET /auth/password_reset/edit?token=...
+    def edit
+      @token = params[:token]
+    end
+
+    # PATCH /auth/password_reset
+    def update
+      result = Auth::ResetPassword.complete(
+        token: params[:token],
+        new_password: params[:password]
+      )
+
+      if result.ok?
+        redirect_to new_session_path, notice: "Password updated. Sign in with your new password."
+      else
+        flash.now[:alert] = result.error
+        @token            = params[:token]
+        render :edit, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/controllers/registrations_controller.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Auth
+  class RegistrationsController < ApplicationController
+    # 5 sign-ups per hour per IP. Tighter than sign-in because each
+    # successful row also sends a welcome email + provisions side
+    # effects. Rails 8's built-in rate_limit uses Solid Cache.
+    rate_limit to: 5, within: 1.hour, only: %i[create],
+               with: -> { redirect_to auth.new_registration_path, alert: "Too many sign-ups from this IP. Try again later." }
+
+    def new
+      @identity = Auth::Identity.new
+    end
+
+    def create
+      result = Auth::RegisterIdentity.call(
+        email:                 params.dig(:identity, :email),
+        password:              params.dig(:identity, :password),
+        password_confirmation: params.dig(:identity, :password_confirmation)
+      )
+
+      if result.ok?
+        cookies.encrypted[Auth.configuration.cookie_name] = {
+          value: result.session.token, httponly: true, expires: result.session.expires_at
+        }
+        redirect_to Auth.configuration.after_sign_in_url, notice: "Welcome"
+      else
+        @identity = Auth::Identity.new(email: params.dig(:identity, :email))
+        flash.now[:alert] = result.error
+        render :new, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/controllers/sessions_controller.rb.tt

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Auth
+  class SessionsController < ApplicationController
+    # 10 attempts per minute per IP. Rails 8's built-in rate_limit
+    # uses Solid Cache by default; configure cache_store in your host
+    # if you need to override.
+    rate_limit to: 10, within: 1.minute, only: %i[create],
+               with: -> { redirect_to auth.new_session_path, alert: "Too many attempts. Try again in a minute." }
+
+    def new
+      # render the sign-in form
+    end
+
+    def create
+      result = Auth::AuthenticateIdentity.call(
+        email: params[:email], password: params[:password]
+      )
+
+      if result.ok?
+        cookies.encrypted[Auth.configuration.cookie_name] = {
+          value: result.session.token, httponly: true, expires: result.session.expires_at
+        }
+        redirect_to Auth.configuration.after_sign_in_url, notice: "Signed in"
+      else
+        flash.now[:alert] = result.error
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      token = cookies.encrypted[Auth.configuration.cookie_name]
+      if token
+        session = Auth::Session.find_by(token: token)
+        if session
+          identity = session.identity
+          Seams::Events::Publisher.publish(
+            "identity.signed_out.auth",
+            identity_id: identity.id,
+            session_id:  session.id
+          )
+          session.destroy
+        end
+      end
+      cookies.delete(Auth.configuration.cookie_name)
+      redirect_to Auth.configuration.after_sign_out_url, notice: "Signed out"
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/jobs/application_job.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Auth
+  class ApplicationJob < ::ApplicationJob
+    queue_as :default
+  end
+end

data/lib/generators/seams/auth/templates/app/jobs/cleanup_expired_sessions_job.rb.tt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Auth
+  # Sweeps expired Auth::Session rows. Wire as a Solid Queue Recurring
+  # entry in config/recurring.yml:
+  #
+  #   auth_cleanup_expired_sessions:
+  #     class: Auth::CleanupExpiredSessionsJob
+  #     schedule: "every 1 hour"
+  #
+  # Publishes session.expired.auth for each row destroyed so any
+  # downstream listener (Notifications, audit log) can react.
+  class CleanupExpiredSessionsJob < ApplicationJob
+    queue_as :auth
+
+    BATCH_SIZE = 500
+
+    def perform
+      Auth::Session.where(expires_at: ..Time.current).find_each(batch_size: BATCH_SIZE) do |session|
+        identity = session.identity
+        Seams::Events::Publisher.publish(
+          "session.expired.auth",
+          identity_id: identity&.id,
+          session_id:  session.id
+        )
+        session.destroy
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/app/mailers/passwords_mailer.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Auth
+  class PasswordsMailer < ::ApplicationMailer
+    def reset_email(identity)
+      @identity = identity
+      # Rails 8 has_secure_password defines `password_reset_token` —
+      # a signed_id with a 15-minute default expiry. The mailer is
+      # responsible for calling it (so the token is generated as
+      # late as possible to maximise validity).
+      @token    = identity.password_reset_token
+      mail(to: identity.email, subject: "Reset your password")
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module Auth
+  # Bearer-style API token. Issued to an Identity, presented in the
+  # Authorization header by API clients.
+  #
+  # Storage: only a SHA-256 hash of the token lives in the DB —
+  # `token_digest`. The plaintext (`token`) is shown ONCE, at
+  # creation time, via the GenerateApiToken service. If the identity
+  # loses it they must rotate; we cannot recover it.
+  #
+  # `token_prefix` is the first few characters of the plaintext, kept
+  # in the DB for identification in dashboards / audit logs without
+  # exposing the secret. Format: `seam_<8 random chars>` so it's
+  # easy to grep for.
+  #
+  # Optional `expires_at`. Optional `last_used_at` for activity
+  # tracking. `name` lets the identity label the token ("CI deploy key",
+  # "iPhone shortcut").
+  class ApiToken < ApplicationRecord
+    self.table_name = "auth_api_tokens"
+
+    PREFIX           = "seam_"
+    PLAINTEXT_LENGTH = 32  # bytes → 43 chars urlsafe-base64
+    PREFIX_DISPLAY   = 12  # chars stored in token_prefix
+
+    belongs_to :identity, class_name: "Auth::Identity", foreign_key: :identity_id
+
+    validates :token_digest, presence: true, uniqueness: true
+    validates :token_prefix, presence: true
+    validates :name,         presence: true
+
+    scope :active,  -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+    scope :expired, -> { where(expires_at: ..Time.current) }
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def touch_last_used!
+      update_column(:last_used_at, Time.current)  # rubocop:disable Rails/SkipsModelValidations
+    end
+
+    # Hash a plaintext token the same way #find_by_plaintext does, so
+    # callers can verify a candidate token without exposing the digest.
+    def self.digest(plaintext)
+      Digest::SHA256.hexdigest(plaintext.to_s)
+    end
+
+    # Returns the ApiToken matching the plaintext, or nil. Does NOT
+    # touch last_used_at — callers do that explicitly so a passive
+    # presence check doesn't bump the timestamp.
+    def self.find_by_plaintext(plaintext)
+      return nil if plaintext.to_s.empty?
+
+      find_by(token_digest: digest(plaintext))
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Auth
+  class ApplicationRecord < ::ApplicationRecord
+    self.abstract_class = true
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Auth
+  # ActiveSupport::CurrentAttributes namespace for the Auth engine.
+  # Set once per request by the Authentication concern; readable from
+  # anywhere downstream (services, models, jobs that re-resolve via
+  # the same controller stack) without explicit threading.
+  #
+  # Wave 9 Phase 1a only sets `identity`. Phase 1b will add
+  # `Current.account`; Phase 2 will add `Current.user` (the account
+  # membership, NOT a host User).
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :identity
+  end
+end