seams 0.1.0

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Factories for Auth engine specs. Tests that need a saved record use
+# `create(:auth_identity)` etc.; tests that only need attributes use
+# `build(:auth_identity)`. Sequence on email keeps uniqueness happy
+# across the full spec run.
+FactoryBot.define do
+  factory :auth_identity, class: "Auth::Identity" do
+    sequence(:email) { |n| "identity-#{n}@example.com" }
+    password         { "verysecret" }
+    staff            { false }
+  end
+
+  factory :auth_session, class: "Auth::Session" do
+    association :identity, factory: :auth_identity
+    token       { SecureRandom.hex(32) }
+    expires_at  { 30.days.from_now }
+  end
+
+  factory :auth_oauth_provider, class: "Auth::OAuth::Provider" do
+    association :identity, factory: :auth_identity
+    provider          { "google" }
+    sequence(:provider_uid) { |n| "google-uid-#{n}" }
+    access_token      { "fake-access-token" }
+    refresh_token     { "fake-refresh-token" }
+    expires_at        { 1.hour.from_now }
+  end
+
+  factory :auth_api_token, class: "Auth::ApiToken" do
+    association :identity, factory: :auth_identity
+    name              { "Test token" }
+    transient do
+      plaintext { "seam_#{SecureRandom.urlsafe_base64(32)}" }
+    end
+    token_digest      { Auth::ApiToken.digest(plaintext) }
+    token_prefix      { plaintext[0, Auth::ApiToken::PREFIX_DISPLAY] }
+  end
+end

data/lib/generators/seams/auth/templates/spec/mailers/passwords_mailer_spec.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Auth::PasswordsMailer, type: :mailer do
+  describe "#reset_email" do
+    let(:identity) { create(:auth_identity, email: "ada@example.com") }
+
+    it "sends to the identity's email" do
+      mail = described_class.reset_email(identity)
+      expect(mail.to).to eq(["ada@example.com"])
+    end
+
+    it "uses the engine's reset subject" do
+      mail = described_class.reset_email(identity)
+      expect(mail.subject).to match(/reset/i)
+    end
+
+    it "embeds a Rails 8 signed_id reset token in the link so the email is actionable" do
+      mail = described_class.reset_email(identity)
+      # Rails 8 signed_id tokens are url-safe base64 with embedded
+      # purpose + expiry. The mailer generates the token at send time
+      # (so its expiry is as late as possible), which means we can't
+      # pre-generate a token in the spec and string-match — every
+      # call to `password_reset_token` produces a different signed_id
+      # because the exp timestamp moves. Instead extract the token
+      # from the rendered link and verify it round-trips back to the
+      # original Identity.
+      body  = mail.body.encoded
+      match = body.match(/token=([^"&\s]+)/)
+      expect(match).not_to be_nil, "no `token=` query param found in: #{body}"
+      raw_token = CGI.unescape(match[1])
+      resolved  = Auth::Identity.find_by_password_reset_token(raw_token)
+      expect(resolved).to eq(identity)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/spec/models/api_token_spec.rb.tt

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Auth::ApiToken do
+  describe "validations" do
+    it "requires identity, name, token_digest, token_prefix" do
+      token = described_class.new
+      expect(token).not_to be_valid
+      %i[identity name token_digest token_prefix].each do |attr|
+        expect(token.errors[attr]).not_to be_empty
+      end
+    end
+
+    it "enforces token_digest uniqueness at the model level" do
+      create(:auth_api_token, token_digest: "fixed-digest")
+      duplicate = build(:auth_api_token, token_digest: "fixed-digest")
+      expect(duplicate).not_to be_valid
+      expect(duplicate.errors[:token_digest]).to include("has already been taken")
+    end
+  end
+
+  describe ".digest" do
+    it "is a SHA-256 hexdigest of the plaintext" do
+      expected = Digest::SHA256.hexdigest("seam_abc123")
+      expect(described_class.digest("seam_abc123")).to eq(expected)
+    end
+
+    it "returns the same digest for the same input" do
+      expect(described_class.digest("foo")).to eq(described_class.digest("foo"))
+    end
+  end
+
+  describe ".find_by_plaintext" do
+    it "returns the token whose digest matches the plaintext" do
+      plaintext = "seam_known_plaintext"
+      record    = create(:auth_api_token, plaintext: plaintext)
+      expect(described_class.find_by_plaintext(plaintext)).to eq(record)
+    end
+
+    it "returns nil for an unknown plaintext" do
+      create(:auth_api_token)
+      expect(described_class.find_by_plaintext("seam_does_not_exist")).to be_nil
+    end
+
+    it "returns nil for a blank plaintext (does not match nil-digest rows)" do
+      expect(described_class.find_by_plaintext("")).to be_nil
+      expect(described_class.find_by_plaintext(nil)).to be_nil
+    end
+  end
+
+  describe "#expired?" do
+    it "is false when expires_at is nil" do
+      expect(build(:auth_api_token, expires_at: nil)).not_to be_expired
+    end
+
+    it "is false when expires_at is in the future" do
+      expect(build(:auth_api_token, expires_at: 1.hour.from_now)).not_to be_expired
+    end
+
+    it "is true when expires_at is in the past" do
+      expect(build(:auth_api_token, expires_at: 1.hour.ago)).to be_expired
+    end
+  end
+
+  describe "scopes" do
+    it ".active includes never-expiring + future-expiring; excludes past-expiring" do
+      live   = create(:auth_api_token, expires_at: nil)
+      future = create(:auth_api_token, expires_at: 1.day.from_now)
+      past   = create(:auth_api_token, expires_at: 1.day.ago)
+
+      expect(described_class.active).to include(live, future)
+      expect(described_class.active).not_to include(past)
+    end
+  end
+
+  describe "#touch_last_used!" do
+    it "updates last_used_at" do
+      token = create(:auth_api_token, last_used_at: nil)
+      expect { token.touch_last_used! }
+        .to change { token.reload.last_used_at }.from(nil)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/spec/models/identity_spec.rb.tt

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Auth::Identity do
+  describe "validations" do
+    it "requires an email" do
+      identity = described_class.new(password: "secret123")
+      expect(identity).not_to be_valid
+      expect(identity.errors[:email]).to include("can't be blank")
+    end
+
+    it "requires the email to look like an email" do
+      identity = described_class.new(email: "not-an-email", password: "secret123")
+      expect(identity).not_to be_valid
+      expect(identity.errors[:email].join).to match(/invalid/i)
+    end
+
+    it "normalises emails to lowercase" do
+      identity = described_class.new(email: "  Foo@BAR.com  ", password: "secret123")
+      identity.valid?
+      expect(identity.email).to eq("foo@bar.com")
+    end
+  end
+
+  describe ".authenticate" do
+    it "returns the identity when the password matches" do
+      identity = described_class.create!(email: "x@y.com", password: "secret123")
+      expect(described_class.authenticate(email: "x@y.com", password: "secret123")).to eq(identity)
+    end
+
+    it "returns nil when the password does not match" do
+      described_class.create!(email: "x@y.com", password: "secret123")
+      expect(described_class.authenticate(email: "x@y.com", password: "wrong")).to be_nil
+    end
+  end
+
+  describe "#staff?" do
+    it "is false by default" do
+      expect(described_class.new).not_to be_staff
+    end
+
+    it "is true when staff column is set" do
+      expect(described_class.new(staff: true)).to be_staff
+    end
+  end
+
+  describe "password reset (Rails 8 has_secure_password)" do
+    it "issues a reset token via the instance method" do
+      identity = described_class.create!(email: "x@y.com", password: "secret123")
+      token = identity.password_reset_token
+      expect(token).to be_a(String)
+      expect(described_class.find_by_password_reset_token(token)).to eq(identity)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/spec/models/oauth/provider_spec.rb.tt

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Auth::OAuth::Provider do
+  describe "validations" do
+    it "requires provider, provider_uid, identity_id" do
+      record = described_class.new
+      expect(record).not_to be_valid
+      %i[provider provider_uid identity_id].each do |attr|
+        expect(record.errors[attr]).not_to be_empty
+      end
+    end
+
+    it "limits provider to the known set" do
+      record = build(:auth_oauth_provider, provider: "myspace")
+      expect(record).not_to be_valid
+      expect(record.errors[:provider].join).to match(/included|inclusion/i)
+    end
+
+    it "rejects a duplicate (provider, provider_uid) pair" do
+      create(:auth_oauth_provider, provider: "google", provider_uid: "abc")
+      dup = build(:auth_oauth_provider, provider: "google", provider_uid: "abc")
+      expect(dup).not_to be_valid
+      expect(dup.errors[:provider_uid].join).to match(/already linked/)
+    end
+
+    it "rejects an identity being linked to the same provider twice" do
+      identity = create(:auth_identity)
+      create(:auth_oauth_provider, identity: identity, provider: "google", provider_uid: "uid-1")
+      dup = build(:auth_oauth_provider, identity: identity, provider: "google", provider_uid: "uid-2")
+      expect(dup).not_to be_valid
+      expect(dup.errors[:identity_id].join).to match(/already linked/)
+    end
+  end
+
+  describe "encryption" do
+    it "round-trips access_token / refresh_token through Rails encryption" do
+      record = create(:auth_oauth_provider,
+                      access_token:  "secret-access",
+                      refresh_token: "secret-refresh")
+      record.reload
+      expect(record.access_token).to  eq("secret-access")
+      expect(record.refresh_token).to eq("secret-refresh")
+    end
+
+    it "round-trips provider_uid (deterministic so it remains queryable)" do
+      record = create(:auth_oauth_provider, provider: "google", provider_uid: "google-sub-42")
+      found  = described_class.find_by(provider: "google", provider_uid: "google-sub-42")
+      expect(found).to eq(record)
+    end
+  end
+
+  describe "#access_token_expired?" do
+    it "is false when expires_at is nil or in the future" do
+      expect(build(:auth_oauth_provider, expires_at: nil)).not_to be_access_token_expired
+      expect(build(:auth_oauth_provider, expires_at: 1.hour.from_now)).not_to be_access_token_expired
+    end
+
+    it "is true when expires_at is in the past" do
+      expect(build(:auth_oauth_provider, expires_at: 1.minute.ago)).to be_access_token_expired
+    end
+  end
+end

data/lib/generators/seams/auth/templates/spec/models/session_spec.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Auth::Session do
+  let(:identity) { Auth::Identity.create!(email: "x@y.com", password: "secret123") }
+
+  describe "creation" do
+    it "auto-assigns a token and expiry" do
+      session = identity.sessions.create!
+      expect(session.token).to be_present
+      expect(session.expires_at).to be > Time.current
+    end
+  end
+
+  describe "#expired?" do
+    it "is false for a fresh session" do
+      expect(identity.sessions.create!).not_to be_expired
+    end
+
+    it "is true once expires_at has passed" do
+      session = identity.sessions.create!(expires_at: 1.minute.ago)
+      expect(session).to be_expired
+    end
+  end
+
+  describe ".active" do
+    it "excludes expired sessions" do
+      live    = identity.sessions.create!
+      _stale  = identity.sessions.create!(expires_at: 1.minute.ago)
+      expect(described_class.active).to contain_exactly(live)
+    end
+  end
+end

data/lib/generators/seams/auth/templates/spec/runtime/boot_spec.rb.tt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Auth engine boot", type: :integration do
+  it "loads the engine" do
+    expect(defined?(Auth::Engine)).to eq("constant")
+  end
+
+  it "registers the four canonical auth events" do
+    %w[identity.signed_up.auth identity.signed_in.auth identity.signed_out.auth session.expired.auth].each do |event|
+      expect(Seams::EventRegistry.registered?(event)).to be(true)
+    end
+  end
+
+  it "creates the auth tables from the dummy schema" do
+    expect(ActiveRecord::Base.connection.table_exists?(:auth_identities)).to be(true)
+    expect(ActiveRecord::Base.connection.table_exists?(:auth_sessions)).to   be(true)
+  end
+
+  it "exposes the canonical concerns + service objects + Configuration" do
+    expect(defined?(Auth::Authenticatable)).to       eq("constant")
+    expect(defined?(Auth::Authentication)).to        eq("constant")
+    expect(defined?(Auth::RegisterIdentity)).to      eq("constant")
+    expect(defined?(Auth::AuthenticateIdentity)).to  eq("constant")
+    expect(defined?(Auth::ResetPassword)).to         eq("constant")
+    expect(defined?(Auth::Configuration)).to         eq("constant")
+    expect(defined?(Auth::Current)).to               eq("constant")
+  end
+end

data/lib/generators/seams/auth/templates/spec/runtime/event_payload_spec.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# Pins the event payload contract for the four identity.* events.
+# Subscribers in other engines (notifications etc.) depend on
+# identity_id being present.
+RSpec.describe "Auth event payloads", type: :integration do
+  let(:captured) { [] }
+
+  before do
+    @sub = Seams::Events::Publisher.adapter.subscribe("identity.signed_up.auth") do |*args|
+      captured << args.last
+    end
+  end
+
+  after { Seams::Events::Publisher.adapter.unsubscribe(@sub) if @sub }
+
+  it "identity.signed_up.auth carries identity_id and email" do
+    Auth::RegisterIdentity.call(
+      email: "ada-#{SecureRandom.hex(4)}@example.com",
+      password: "verysecret"
+    )
+
+    payload = captured.last
+    expect(payload).to include(:identity_id, :email)
+    expect(payload[:identity_id]).to be_a(Integer)
+  end
+end

data/lib/generators/seams/auth/templates/spec/runtime/login_flow_spec.rb.tt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# End-to-end login flow: signup → signed-in session → signout.
+# Lives under spec/runtime so it boots the dummy app's full Rack stack
+# (routing + sessions + cookies) rather than just the model layer.
+RSpec.describe "Auth login flow", type: :request do
+  describe "signup → signin → signout round-trip" do
+    let(:email)    { "round-trip-#{SecureRandom.hex(4)}@example.com" }
+    let(:password) { "verysecret" }
+
+    it "creates an identity, opens an Auth::Session, then revokes it on signout" do
+      expect {
+        post "/auth/registration",
+             params: { identity: { email: email, password: password } }
+      }.to change(Auth::Identity, :count).by(1)
+
+      identity = Auth::Identity.find_by(email: email)
+      expect(identity).not_to be_nil
+
+      expect {
+        post "/auth/session",
+             params: { email: email, password: password }
+      }.to change(Auth::Session, :count).by(1)
+
+      session = Auth::Session.last
+      expect(session.identity).to eq(identity)
+      expect(session.expires_at).to be > Time.current
+
+      delete "/auth/session"
+      expect(Auth::Session.where(id: session.id)).to be_empty
+    end
+  end
+
+  describe "signin with the wrong password" do
+    it "does not create a session" do
+      create(:auth_identity, email: "ada@example.com", password: "verysecret")
+
+      expect {
+        post "/auth/session", params: { email: "ada@example.com", password: "wrong" }
+      }.not_to change(Auth::Session, :count)
+    end
+  end
+end