sessions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 342cda70d0a4f3ed6b760d8dee9ff8dea68c97151d932e77c478474e216fe9ef
+  data.tar.gz: 6885d70e1cc6cbb5ebd9850c0b3f5d015ce22d1aeae5ba2968b0fd5bb33412e0
+SHA512:
+  metadata.gz: a15d061c3b9397265aa2e7581ed5e06ce64ae50943a54aa71b45539dfe528153004422b9c782d1dcd5cd2b62a55edef8612ed26c4f8a55ee8d91c0379f3d9133
+  data.tar.gz: 4ecef8ccd7f56454a31feb6623245c38585dbae7601fdb681daa6192e764964a4c47300dc3b8aaaa6dbe2811246a66c304210d202e5a6f9e46c40085d34a246f

data/.rubocop.yml

@@ -0,0 +1,61 @@
+# MERGE our excludes with rubocop's defaults (vendor/, node_modules/, …) —
+# a bare Exclude key would REPLACE them.
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    # The dummy host app mirrors GENERATED code: its auth files are vendored
+    # verbatim from `rails generate authentication` (Rails-omakase style) and
+    # its sessions migrations are copies of the install templates — don't
+    # lint generated-code mirrors against the gem's own style.
+    - test/dummy/**/*
+    # Generator templates are emitted into HOST apps (host style, and some
+    # carry ERB tags rubocop can't parse as Ruby).
+    - lib/generators/sessions/templates/**/*
+    # Appraisal-generated Gemfiles.
+    - gemfiles/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Hard size metrics fight readable, well-commented domain code and thorough
+# test classes; we optimize for the latter.
+Metrics:
+  Enabled: false
+
+# The warden hook ABI fixes block parameter names (|user, warden, opts| and
+# |env, opts|) — renaming them to appease a cop would only obscure the
+# upstream contract the code mirrors.
+Naming/MethodParameterName:
+  AllowedNames: [at, by, id, ip, to, ua]
+
+# `has_sessions` is the macro and the product — it matches the ecosystem
+# grammar (has_credits, has_api_keys, has_wallets), not a predicate.
+Naming/PredicatePrefix:
+  AllowedMethods: [has_sessions]
+
+# %{client} / %{platform} are I18n interpolation tokens — annotated tokens
+# aren't a thing in I18n templates.
+Style/FormatStringToken:
+  EnforcedStyle: template
+
+# Duck-typed contracts (the ua_parser lambda, hook procs) fix keyword names
+# even where an implementation doesn't use them.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Hook lambdas spell out their kwargs (->(user:, session:, event:) { … })
+# even when a body ignores some — the names ARE the documented contract.
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - sessions.gemspec # the long-form rubygems description is one line by design

data/.simplecov

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices.
+# Coherent with the rest of the gem ecosystem (chats, moderate, usage_credits, pricing_plans, …).
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Don't count the test suite itself toward coverage
+  add_filter "/test/"
+
+  # Don't count code that ISN'T unit-testable by this suite and would only
+  # distort the numbers:
+  #   - Generators + their templates: these run via `rails generate
+  #     sessions:install` / `sessions:views` in a real host. The generator
+  #     classes ARE exercised by Rails::Generators::TestCase, but the
+  #     migration .erb itself is never loaded as Ruby here (the dummy
+  #     migrates a copy of it instead).
+  #   - version.rb: a single constant; nothing to cover.
+  add_filter "/lib/generators/"
+  add_filter "/lib/sessions/version.rb"
+
+  # Track Ruby files in the lib directory (gem source code)
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Minimum coverage thresholds to prevent coverage REGRESSION. The
+  # primitives (models, parsing, classification, configuration, the facade)
+  # are thoroughly covered by the unit suite; the adapters and engine
+  # controllers are driven by the integration tests against the dummy app.
+  # The thresholds sit just under the current floor so the gate catches a
+  # real regression without failing on the existing baseline; raise them as
+  # coverage grows.
+  minimum_coverage line: 80, branch: 60
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV["TEST_ENV_NUMBER"]}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n#{"=" * 60}"
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read `docs/PRD.md` for the full product requirements — it's the source of truth for what we're building and why, and every technical decision in it is backed by the research memos in `docs/research/` (read the relevant memo before touching the corresponding subsystem). Once the gem has code, the README and the code itself become the source of truth for the public API.

data/Appraisals

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Test the minimum supported Rails version (matches the gemspec floor).
+# There's no omakase auth generator on 7.1 — this lane proves the Devise/
+# Warden side and the engine still work (the omakase adapter simply stays
+# duck-detected off… except the dummy vendors the generated code, which runs
+# fine on 7.1 because the concern only uses 7.1-era APIs).
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# The version that shipped `rails generate authentication` — the substrate
+# this gem decorates.
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+# The latest Rails — also adds the rate_limit.action_controller notification
+# the failed-login pipeline subscribes to.
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 (2026-06-12)
+
+First release — the missing session layer for Rails. 🔐
+
+- **Live device registry** on the session table your app already has: the Rails 8 `sessions` table is adopted and enriched in place (zero app-code edits), and Devise apps get the same Rails-8-shaped table generated for them.
+- **Per-session remote revocation** that actually works on both stacks: `session.revoke!`, `user.revoke_other_sessions!`, `user.revoke_all_sessions!` — row destroyed, device signed out on its very next request. On Devise this generalizes the proven `session_limitable` mechanism into token-per-row (N devices, each individually revocable) and rotates remember-me credentials on revoke.
+- **Append-only login-activity trail** (`sessions_events`): every successful *and failed* login, logout, revocation and expiry — with the attempted identity (even for unknown accounts), the device, the geo, and the trail↔registry linkage (`session_id`) no prior art has.
+- **Device dedup via browser continuity**: a signed, long-lived `sessions_device_id` cookie (minted only at login — never a pre-login tracker) identifies the browser install, so a repeat login from the same browser *supersedes* its old row instead of stacking duplicate "Firefox on macOS" entries. Robust to browser updates (identity is the cookie, not the UA); private windows and other users on the same machine stay separate; superseding is quiet housekeeping (no revocation hook, no remember-me rotation, and the surviving trail prevents false new-device alerts).
+- **The "Last used" badge, server-side**: `Sessions.last_login(request)` returns the most recent login event from THIS browser — on the login page, signed out — because the continuity cookie survives logout and login events carry the device id. One lookup powers the "Last used" pill next to your OAuth/passkey/password buttons; no JavaScript, no localStorage.
+- **Repeated-failed-logins detection**: `config.repeated_failed_logins = { threshold:, within: }` + `on_repeated_failed_logins` hook — fires exactly once at the threshold crossing (never per attempt: that's notification fatigue and an inbox-flooding vector), with the tripping event's IP/location/device. Complements lockable/rate-limiting: they stop the attacker, this tells the user.
+- **Two-factor awareness, verified from source against every mainstream setup**: devise-two-factor classifies automatically (single-phase password+TOTP → `password` + `auth_detail.second_factor: "totp"`/`"backup_code"`); passkey-first logins (devise-passkeys, warden-webauthn) classify as `passkey` by strategy name, and passkey *re*authentication (sudo confirms) is recognized — never a duplicate device row; `session.second_factor?`/`#second_factor` on rows and events plus `Session#second_factor!` for post-login step-up gates; `Sessions.skip!(request)` so a two-phase challenge's password phase (right password, no session yet) is never miscounted as a failed login; one-line recipes for devise-otp, authentication-zero `--two-factor` (whose Rails-8-shaped table the installer adopts), webauthn-rails second-factor mode, and DIY rotp/active_model_otp flows — every shape exercised end-to-end in the test suite (single-phase, two-phase challenge, passkey-first, step-up, failed factors).
+- `Event#source_line` — the location-first one-liner ("🇪🇸 Madrid, Spain · IP 83.45.112.7 · Firefox 139 on Windows") shared by rows and events, ready for security emails and notification bodies (`ip: false` for compact feed rows).
+- **Device intelligence**: Hotwire Native detection out of the box (platform, OS version, app name/version/build, device model — including the documented UA prefix convention and validated `X-Client-*` headers), web parsing via the `browser` gem with an automatic `device_detector` upgrade, client-hints consumption, and *honest* display names (frozen UA tokens are never rendered as facts).
+- **Auth-method classification**: password, OAuth (any OmniAuth provider, with failure capture via an `on_failure` composer), Google One Tap, passkeys, magic links (devise-passwordless auto-detected), OTP/SSO — automatic where possible, one-line `Sessions.tag` where flows can't self-identify.
+- **A mountable "Your devices" page** (en + es): device names, approximate location, last active, "This device" badge, per-row Log out, "Sign out of all other sessions", login history — view-by-view ejectable with `rails g sessions:views`, or rendered as partials inside your own settings page.
+- **Lifecycle**: throttled `last_seen_at` touch (one conditional UPDATE per window — finally making the Rails security guide's own `Session.sweep` recommendation implementable), per-user session cap with oldest-eviction, opt-in idle/absolute timeouts with NIST presets, revoke-on-password-change (ASVS 3.3.3) on both stacks.
+- **Privacy first**: bounded trail retention (12 months, CNIL) with a generated sweep job, optional IP truncation before persistence (the Google Analytics precedent), lat/lng precision reduction, no client-side fingerprinting ever, GDPR `Sessions.forget(user)` helper.
+- **Never breaks login**: every tracking path is error-isolated — a parsing/geo/hook/database failure may lose a log row; it can never 500 a sign-in (proven by a chaos test that detonates every pipeline stage at once).
+- **Fails open, never closed** (pre-release security audit hardening): an *errored* registry lookup is an outage, not a revocation — the request proceeds untracked instead of kicking every active session; kicks are scope-precise (an admin scope and host session data survive a user-scope kick); the sudo gate fails closed (a falsy gate 403s — it can never fall through to the destructive action); the trail rejects rewrites (normal AR `update`/`destroy` raise `ReadOnlyRecord`; geo backfill, GDPR scrubs and retention sweeps use the callback-bypassing APIs, which remain available — a model-contract guardrail, not a database constraint); polymorphic installs sweep per (owner type, id); `--model` on an omakase app takes the create-table path; `user.session_history` is the honest user-facing trail read (identity-matched failures included — the raw association can't see them by design); login-burst rate limits are the only throttles recorded as failed logins; `Sessions.current(request, scope:)` disambiguates multi-scope sessions.
+- Geolocation via the [`trackdown`](https://github.com/rameerez/trackdown) gem (soft dependency): Cloudflare headers synchronously for free, MaxMind asynchronously.
+- Adaptive install generator: detects Rails 8 auth vs Devise (capability-based: table shape / controller duck-test — never guessed from file names), honors uuid/bigint primary keys and jsonb/json column types **on both tables** (the trail's own primary key follows the host too — uuid apps embed events in uuid polymorphic associations like Noticed records, where a bigint id silently casts to NULL), ships an annotated initializer and the `SessionsSweepJob`.
+- `config.layout` for hosts whose signed-in surfaces use a non-default layout; the engine's route proxy is discovered from the host's routes, so `mount … as: :anything` keeps every partial working.
+- Incubated against TWO production apps before release — a Devise 5 + Hotwire Native + Cloudflare + PostGIS app (Spanish UI) and a Devise 4.9 + MaxMind + api_keys app (English UI): the Warden logout hook reads the raw session (a Devise-activatable-style logout-and-throw can't recurse through it), the trail's device columns power `Sessions::Event#device_name` for admin lists, PostGIS counts as PostgreSQL everywhere adapters are sniffed, the madmin generator's controllers are self-contained on stock Madmin (a `resource_name` override, never a host-patch class attribute), and token-authenticated API traffic never mints rows.
+- PostgreSQL (and PostGIS), MySQL and SQLite supported; Rails 7.1 → 8.1; Ruby 3.2+.

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read `docs/PRD.md` for the full product requirements — it's the source of truth for what we're building and why, and every technical decision in it is backed by the research memos in `docs/research/` (read the relevant memo before touching the corresponding subsystem). Once the gem has code, the README and the code itself become the source of truth for the public API.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 rameerez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.