seams 0.1.0

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# What: creates the auth_sessions table for the Auth engine.
+# Why:  Auth::Session backs the encrypted cookie set on sign-in; we
+#       store the token + expiry so sign-out can revoke just one device.
+# Risk: empty table on creation — no data migration needed.
+class CreateAuthSessions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :auth_sessions do |t|
+      t.references :identity,    null: false, foreign_key: { to_table: :auth_identities }, index: true
+      t.string     :token,       null: false
+      t.datetime   :expires_at,  null: false
+      t.timestamps
+    end
+
+    add_index :auth_sessions, :token, unique: true
+    add_index :auth_sessions, :expires_at
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "auth/version"
+require "auth/configuration"
+require "auth/engine"
+require "auth/concerns/authenticatable"
+require "auth/concerns/authentication"
+
+module Auth
+  class Error               < StandardError; end
+  class OAuthError          < Error; end
+  class OAuthProviderUnknown < OAuthError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # Build a configured OAuth adapter for the given provider key.
+    # Reads `Auth.configuration.oauth_providers[name]` for the adapter
+    # class + client_id + client_secret + scopes; raises if the
+    # provider isn't configured.
+    def oauth(provider_name)
+      conf = configuration.oauth_providers[provider_name.to_sym]
+      raise OAuthProviderUnknown, "OAuth provider #{provider_name.inspect} is not configured" unless conf
+
+      adapter_class = Object.const_get(conf.fetch(:adapter))
+      adapter_class.new(
+        client_id:     conf.fetch(:client_id),
+        client_secret: conf.fetch(:client_secret),
+        scopes:        conf[:scopes] || adapter_class::DEFAULT_SCOPES
+      )
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/concerns/api_authenticatable.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Auth
+  # Bearer-token controller authentication. Mix into API controllers
+  # that should accept `Authorization: Bearer <token>` instead of the
+  # session cookie.
+  #
+  #   class Api::WidgetsController < ApplicationController
+  #     include Auth::ApiAuthenticatable
+  #     before_action :authenticate_api_token!
+  #   end
+  #
+  # Sets `current_api_token` (the ApiToken row) and `current_identity`
+  # (the Auth::Identity) on success. Renders 401 with a JSON body on
+  # failure. last_used_at is bumped on every successful auth.
+  module ApiAuthenticatable
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :current_api_token
+    end
+
+    def authenticate_api_token!
+      token = current_api_token_or_render_401
+      return unless token
+
+      @current_api_token = token
+      @current_identity  = token.identity
+      Auth::Current.identity = @current_identity if defined?(Auth::Current)
+      token.touch_last_used!
+    end
+
+    def current_identity
+      @current_identity
+    end
+
+    private
+
+    def current_api_token_or_render_401
+      header = request.headers["Authorization"].to_s
+      return render_unauthorized!("missing Authorization header") unless header.start_with?("Bearer ")
+
+      plaintext = header.sub(/\ABearer\s+/, "").strip
+      token     = Auth::ApiToken.find_by_plaintext(plaintext)
+      return render_unauthorized!("invalid token")          unless token
+      return render_unauthorized!("token expired")          if token.expired?
+
+      token
+    end
+
+    def render_unauthorized!(message)
+      render json: { error: message }, status: :unauthorized
+      nil
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/concerns/authenticatable.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Auth
+  # Concern that the host application's user-facing model can include
+  # to gain Auth-engine sign-in tracking, password helpers, and
+  # session-aware queries. Listed in this engine's ExposedConcerns so
+  # cross-engine boundary cops do not flag callers.
+  #
+  # OPTIONAL after Wave 9. Most hosts won't need it because
+  # `Auth::Identity` is now the canonical "human" record — sessions
+  # belong to Identity, not to a host User. Hosts that DO keep a
+  # separate User model (e.g. for domain-specific profile fields) and
+  # want the sugar can include this concern, but the host User must
+  # have an `identity_id` column and the host wires the link itself.
+  module Authenticatable
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :auth_identity, class_name: "Auth::Identity", foreign_key: :identity_id, optional: true
+    end
+
+    def signed_in?
+      auth_identity&.sessions&.active&.exists?
+    end
+
+    def sign_out_everywhere!
+      auth_identity&.sessions&.destroy_all
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/concerns/authentication.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Auth
+  # Mix into the host's ApplicationController to gain `current_identity`,
+  # `signed_in?`, and `authenticate_identity!` helpers backed by the
+  # encrypted Auth session cookie.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Auth::Authentication
+  #     before_action :authenticate_identity!
+  #   end
+  #
+  # Side-effect: when a sign-in is resolved, `Current.identity` is set
+  # so models / services downstream can access the signed-in identity
+  # without threading it through every method. Future waves will add
+  # `Current.account` and `Current.user` (account-membership) — for now
+  # this concern only sets `Current.identity`.
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :current_identity, :signed_in? if respond_to?(:helper_method)
+      before_action :set_current_identity if respond_to?(:before_action)
+    end
+
+    def current_identity
+      @current_identity ||= resolve_current_identity
+    end
+
+    def signed_in?
+      current_identity.present?
+    end
+
+    def authenticate_identity!
+      return if signed_in?
+
+      respond_to?(:redirect_to) ? redirect_to(auth_engine.new_session_path) : head(:unauthorized)
+    end
+
+    private
+
+    def resolve_current_identity
+      token = cookies.encrypted[Auth.configuration.cookie_name]
+      return nil if token.blank?
+
+      session = Auth::Session.active.find_by(token: token)
+      session&.identity
+    end
+
+    def set_current_identity
+      Auth::Current.identity = current_identity if defined?(Auth::Current)
+    end
+
+    def auth_engine
+      Auth::Engine.routes.url_helpers
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/configuration.rb.tt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Auth
+  # Engine-scoped configuration. Override in
+  # config/initializers/auth.rb of the host application:
+  #
+  #   Auth.configure do |c|
+  #     c.session_ttl       = 14.days
+  #     c.cookie_name       = :_my_app_session
+  #     c.after_sign_in_url = "/dashboard"
+  #   end
+  class Configuration
+    attr_accessor :session_ttl, :cookie_name, :after_sign_in_url, :after_sign_out_url,
+                  :password_min_length, :oauth_providers
+    # Follow-up generators that add new top-level configuration knobs (passkey_rp_id, magic_link_ttl) declare their attr_accessor here.
+    # seams:insertion-point auth.configuration.attributes
+
+    def initialize
+      @session_ttl         = 30 * 24 * 60 * 60   # 30 days, in seconds
+      @cookie_name         = :auth_session
+      @after_sign_in_url   = "/"
+      @after_sign_out_url  = "/"
+      @password_min_length = 8
+      # OAuth providers — each entry maps a provider key to a config:
+      #   { adapter: "Auth::OAuth::Google", client_id:, client_secret:, scopes?: }
+      # Configure in 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
+      @oauth_providers     = {
+        # Follow-up generators that ship pre-wired OAuth providers splice a `linkedin: { adapter: "Auth::OAuth::LinkedIn", ... }` entry here.
+        # seams:insertion-point auth.configuration.oauth_providers
+      }
+      # Follow-up generators that add defaults for new attributes (matching auth.configuration.attributes) splice them here.
+      # seams:insertion-point auth.configuration.defaults
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/engine.rb.tt

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Auth
+  class Engine < ::Rails::Engine
+    isolate_namespace Auth
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    # Zeitwerk's default inflector lower-cases everything between
+    # underscores, so an `oauth/` directory maps to `Oauth::` (single-O)
+    # instead of the `OAuth::` (camel-OA) namespace we use for the
+    # provider model + authenticator + callbacks controller (and the
+    # lib/ adapters Google/Github/Abstract). Single-entry inflection so
+    # the override only affects directories named exactly "oauth" — a
+    # host's own `oauth_provider.rb` (no trailing directory) stays on
+    # the default mapping.
+    initializer "auth.zeitwerk_inflections", before: :set_autoload_paths do
+      Rails.autoloaders.main.inflector.inflect("oauth" => "OAuth")
+    end
+
+    initializer "auth.register_events" do
+      Seams::EventRegistry.register("identity.signed_up.auth",   emitted_by: "Auth")
+      Seams::EventRegistry.register("identity.signed_in.auth",   emitted_by: "Auth")
+      Seams::EventRegistry.register("identity.signed_out.auth",  emitted_by: "Auth")
+      Seams::EventRegistry.register("session.expired.auth",      emitted_by: "Auth")
+      # API token lifecycle (issue #2 section 2A)
+      Seams::EventRegistry.register("api_token.issued.auth",     emitted_by: "Auth")
+      Seams::EventRegistry.register("api_token.revoked.auth",    emitted_by: "Auth")
+      # Follow-up generators that emit new auth events (e.g. identity.passkey_added.auth) register them here.
+      # seams:insertion-point auth.engine.events
+    end
+
+    initializer "auth.append_migrations" do |app|
+      unless app.root == root
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+
+    # Follow-up generators that need their own initializer block (e.g. attaching a subscriber on an auth event) declare it here.
+    # seams:insertion-point auth.engine.initializers
+  end
+end

data/lib/generators/seams/auth/templates/lib/oauth/abstract.rb.tt

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Auth
+  module OAuth
+    # Contract every OAuth provider adapter must implement. Subclass
+    # this in the host application to wire additional providers
+    # (Apple Sign In, Microsoft, GitLab, etc.) and register the
+    # subclass in `Auth.configuration.oauth_providers`.
+    #
+    # The Auth engine ships two concrete adapters: Auth::OAuth::Google
+    # and Auth::OAuth::Github. See those files for fully-worked
+    # examples + the docs URLs each was verified against.
+    #
+    # All adapters are stateless. Build them per-request via
+    # +Auth::OAuth.build(:provider_name)+ which reads credentials from
+    # +Auth.configuration.oauth_providers+.
+    class Abstract
+      # Returned by #fetch_user_info — the normalised user representation
+      # downstream code uses to find-or-create the local OAuth row.
+      Profile = Struct.new(:provider_uid, :email, :email_verified, :name, :avatar_url, :raw,
+                           keyword_init: true)
+
+      def initialize(client_id:, client_secret:, scopes: [])
+        @client_id     = client_id
+        @client_secret = client_secret
+        @scopes        = scopes
+      end
+
+      # The URL the host redirects the user to. State is the
+      # CSRF-protection token the host generates and re-verifies on
+      # callback.
+      def authorize_url(state:, redirect_uri:)
+        raise NotImplementedError, "#{self.class} must implement #authorize_url"
+      end
+
+      # Exchange the `code` query param from the callback for an
+      # access token. Returns a hash with keys :access_token,
+      # :refresh_token (may be nil), :expires_in (may be nil),
+      # :token_type, :scope.
+      def exchange_code(code:, redirect_uri:)
+        raise NotImplementedError, "#{self.class} must implement #exchange_code"
+      end
+
+      # Fetch the user's profile from the provider's userinfo
+      # endpoint. Returns a Profile struct.
+      def fetch_user_info(access_token:)
+        raise NotImplementedError, "#{self.class} must implement #fetch_user_info"
+      end
+
+      protected
+
+      attr_reader :client_id, :client_secret, :scopes
+
+      # Single Faraday connection per adapter instance. Subclasses set
+      # the base URL; we share timeout + retry config across providers.
+      def conn(base_url)
+        Faraday.new(url: base_url) do |f|
+          f.request :url_encoded
+          f.options.timeout      = 10
+          f.options.open_timeout = 5
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def parse_json(response, action:)
+        return {} if response.body.to_s.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise Auth::OAuthError,
+              "OAuth #{provider_name} #{action}: response was not valid JSON (#{e.message})"
+      end
+
+      def assert_success!(response, action:)
+        return if response.success?
+
+        body = response.body.to_s[0, 200]
+        raise Auth::OAuthError,
+              "OAuth #{provider_name} #{action}: HTTP #{response.status} — #{body}"
+      end
+
+      def provider_name
+        self.class.name.to_s.split("::").last.downcase
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/oauth/github.rb.tt

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "auth/oauth/abstract"
+
+module Auth
+  module OAuth
+    # GitHub OAuth Apps adapter. Faraday-based.
+    #
+    # Verified against:
+    #   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
+    #
+    # GitHub returns form-encoded responses by default — we send
+    # `Accept: application/json` to get JSON consistently.
+    #
+    # The `/user` endpoint returns null email when the user keeps it
+    # private. We additionally fetch `/user/emails` (which requires
+    # the `user:email` scope) and pick the primary verified one. If
+    # `user:email` isn't in scopes, we fall back to whatever `/user`
+    # returns (which may be nil — caller should handle).
+    class Github < Abstract
+      AUTHORIZE_URL    = "https://github.com/login/oauth/authorize"
+      TOKEN_URL        = "https://github.com/login/oauth/access_token"
+      USER_URL         = "https://api.github.com/user"
+      USER_EMAILS_URL  = "https://api.github.com/user/emails"
+
+      DEFAULT_SCOPES = %w[read:user user:email].freeze
+
+      def initialize(client_id:, client_secret:, scopes: DEFAULT_SCOPES)
+        super
+      end
+
+      def authorize_url(state:, redirect_uri:)
+        params = {
+          client_id:    client_id,
+          redirect_uri: redirect_uri,
+          scope:        scopes.join(" "),
+          state:        state,
+          allow_signup: "true"
+        }
+        "#{AUTHORIZE_URL}?#{URI.encode_www_form(params)}"
+      end
+
+      def exchange_code(code:, redirect_uri:)
+        response = conn(TOKEN_URL).post("") do |req|
+          req.headers["Accept"] = "application/json"
+          req.body = URI.encode_www_form(
+            client_id:     client_id,
+            client_secret: client_secret,
+            code:          code,
+            redirect_uri:  redirect_uri
+          )
+        end
+        assert_success!(response, action: "token exchange")
+        body = parse_json(response, action: "token exchange")
+        # GitHub returns 200 with { "error": "bad_verification_code" }
+        # for bad codes — treat that as a failure too.
+        raise Auth::OAuthError, "OAuth github token exchange: #{body["error_description"] || body["error"]}" if body["error"]
+
+        {
+          access_token:  body["access_token"],
+          refresh_token: nil,                    # GitHub OAuth Apps don't issue refresh tokens
+          expires_in:    nil,                    # tokens don't expire (GitHub OAuth Apps)
+          token_type:    body["token_type"] || "bearer",
+          scope:         body["scope"]
+        }
+      end
+
+      def fetch_user_info(access_token:)
+        user  = fetch_user(access_token)
+        email = user["email"] || best_email(access_token)
+
+        Profile.new(
+          provider_uid:   user["id"].to_s,    # GitHub numeric id, stable
+          email:          email,
+          email_verified: !email.nil?,         # /user/emails primary+verified is what we picked
+          name:           user["name"] || user["login"],
+          avatar_url:     user["avatar_url"],
+          raw:            user
+        )
+      end
+
+      private
+
+      def fetch_user(access_token)
+        response = conn(USER_URL).get("") do |req|
+          req.headers["Authorization"] = "Bearer #{access_token}"
+          req.headers["Accept"]        = "application/vnd.github+json"
+          req.headers["User-Agent"]    = "Seams Auth"
+        end
+        assert_success!(response, action: "user fetch")
+        parse_json(response, action: "user fetch")
+      end
+
+      def best_email(access_token)
+        return nil unless scopes.include?("user:email")
+
+        response = conn(USER_EMAILS_URL).get("") do |req|
+          req.headers["Authorization"] = "Bearer #{access_token}"
+          req.headers["Accept"]        = "application/vnd.github+json"
+          req.headers["User-Agent"]    = "Seams Auth"
+        end
+        return nil unless response.success?
+
+        emails = JSON.parse(response.body)
+        primary = emails.find { |e| e["primary"] && e["verified"] }
+        primary&.dig("email")
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/oauth/google.rb.tt

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "auth/oauth/abstract"
+
+module Auth
+  module OAuth
+    # Google OAuth 2.0 + OpenID Connect adapter. Faraday-based
+    # (no oauth2 gem, no Net::HTTP).
+    #
+    # Verified against:
+    #   https://developers.google.com/identity/protocols/oauth2/web-server
+    #   https://developers.google.com/identity/openid-connect/openid-connect
+    #
+    # Default scopes (`openid email profile`) cover the four fields we
+    # populate on Profile. Use `access_type=offline` + `prompt=consent`
+    # only if you need refresh tokens — most "sign in with Google"
+    # flows don't.
+    class Google < Abstract
+      AUTHORIZE_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+      TOKEN_URL     = "https://oauth2.googleapis.com/token"
+      USERINFO_URL  = "https://openidconnect.googleapis.com/v1/userinfo"
+
+      DEFAULT_SCOPES = %w[openid email profile].freeze
+
+      def initialize(client_id:, client_secret:, scopes: DEFAULT_SCOPES)
+        super
+      end
+
+      def authorize_url(state:, redirect_uri:)
+        params = {
+          client_id:     client_id,
+          redirect_uri:  redirect_uri,
+          response_type: "code",
+          scope:         scopes.join(" "),
+          state:         state,
+          access_type:   "online",
+          prompt:        "select_account"
+        }
+        "#{AUTHORIZE_URL}?#{URI.encode_www_form(params)}"
+      end
+
+      def exchange_code(code:, redirect_uri:)
+        response = conn(TOKEN_URL).post("", {
+          client_id:     client_id,
+          client_secret: client_secret,
+          code:          code,
+          redirect_uri:  redirect_uri,
+          grant_type:    "authorization_code"
+        })
+        assert_success!(response, action: "token exchange")
+        body = parse_json(response, action: "token exchange")
+        {
+          access_token:  body["access_token"],
+          refresh_token: body["refresh_token"],
+          expires_in:    body["expires_in"],
+          token_type:    body["token_type"] || "Bearer",
+          scope:         body["scope"]
+        }
+      end
+
+      def fetch_user_info(access_token:)
+        response = conn(USERINFO_URL).get("") do |req|
+          req.headers["Authorization"] = "Bearer #{access_token}"
+        end
+        assert_success!(response, action: "userinfo")
+        body = parse_json(response, action: "userinfo")
+        Profile.new(
+          provider_uid:   body["sub"],     # stable Google account id
+          email:          body["email"],
+          email_verified: body["email_verified"],
+          name:           body["name"],
+          avatar_url:     body["picture"],
+          raw:            body
+        )
+      end
+    end
+  end
+end

data/lib/generators/seams/auth/templates/lib/tasks/auth_pii.rake.tt

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Re-encrypts plaintext PII columns for hosts upgrading from Auth
+# generator versions ≤ Wave 10 (where `email` and `provider_uid` were
+# stored plaintext).
+#
+# Usage on the host:
+#
+#   1. Set the transitional flag in config/application.rb so existing
+#      plaintext rows can still be read while the rotation runs:
+#
+#        config.active_record.encryption.support_unencrypted_data = true
+#
+#   2. Deploy + run:
+#
+#        bin/rails seams:auth:rotate_pii_encryption
+#
+#   3. Once the task reports zero remaining unencrypted rows, set the
+#      flag back to `false` (default) and redeploy.
+#
+# Idempotent — re-running on already-encrypted rows is a no-op because
+# the assignment goes through the encryption setter every time.
+namespace :seams do
+  namespace :auth do
+    desc "Re-encrypt PII columns (email, provider_uid) — host upgrades from Wave ≤10"
+    task rotate_pii_encryption: :environment do
+      counts   = { identities: 0, oauth_providers: 0 }
+      failures = { identities: [], oauth_providers: [] }
+
+      # `update!` runs ALL validations. Legacy rows whose data fails
+      # today's regex (e.g. emails without @, stale imports) would
+      # raise RecordInvalid mid-`find_each` and abort the rotation,
+      # leaving downstream rows plaintext. Trap per-row, log, count
+      # the failure, and keep going — the operator gets a final report
+      # of which rows still need attention before flipping
+      # support_unencrypted_data back to false.
+      Auth::Identity.find_each do |identity|
+        identity.update!(email: identity.email)
+        counts[:identities] += 1
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+        failures[:identities] << { id: identity.id, error: "#{e.class}: #{e.message}" }
+      end
+
+      Auth::OAuth::Provider.find_each do |provider|
+        provider.update!(provider_uid: provider.provider_uid)
+        counts[:oauth_providers] += 1
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+        failures[:oauth_providers] << { id: provider.id, error: "#{e.class}: #{e.message}" }
+      end
+
+      puts "Auth PII rotation complete:"
+      puts "  identities      re-encrypted: #{counts[:identities]}, failures: #{failures[:identities].size}"
+      puts "  oauth_providers re-encrypted: #{counts[:oauth_providers]}, failures: #{failures[:oauth_providers].size}"
+
+      if failures.values.any?(&:any?)
+        puts ""
+        puts "Failures (fix the underlying data, then re-run this task):"
+        failures.each do |table, rows|
+          rows.each { |row| puts "  #{table} id=#{row[:id]} — #{row[:error]}" }
+        end
+        puts ""
+        puts "DO NOT set support_unencrypted_data = false until failure count is zero — " \
+             "those rows are still plaintext."
+        abort("Rotation incomplete: #{failures.values.flatten.size} row(s) failed.")
+      end
+    end
+  end
+end