strongroom-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec4204432b51f2a1d28d6ca08fa846a6ed9413de15e2164dbc4f506aa0e3f474
-  data.tar.gz: 87eb737c063fbdbe0f8ba0e5767541c37abfa1addcf1e02117fa5754f51102ad
+  metadata.gz: 2313700e0514a62dbf3f58e5f541e0c4421f4c034a8220840cd9ca243d05b816
+  data.tar.gz: 5530d843f7630a021488e36bcc230bdfd9d1137f3aec6c5a1dd8d233c3a9b09f
 SHA512:
-  metadata.gz: 9dd07c5ee1df0e5ec948bd724ea445f45d61d9c34ec0421ab9f838ebbaa3c41d66d0a997c39e6120d6671fb1f35dbe8c14a3b9c8bc46fc42a20e3ae01a92ff3d
-  data.tar.gz: a4bf94a507478ceeb8f83d5be2e1d3da89afe287e127bfc234d23535338236392db768159dcc80218ff3311c8245f7c5dab908bbdfdd9521ed6bf04b78ff5e9e
+  metadata.gz: 5b77a81722924260a13456a6416012c2670dafe0360cb8932f21c8fd3250301a50564fd7d86e7c26425e741b5fd781a08b694a812357afece92dec857570b881
+  data.tar.gz: fce5256ee8f35e3f44e70165c0615a0d5c3a0ddc61b05d5b976cf7918368f425d0b0ef026d7009fb1c7a44a733bb0b36f8849b56eda5ee73b5cb32c2b25b4127

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/seuros/strongroom/compare/strongroom-rails-v0.2.0...strongroom-rails-v0.3.0) (2026-10-25)
+
+
+### Features
+
+* add password recovery links and self-service password change ([b4f9160](https://github.com/seuros/strongroom/commit/b4f9160b352fb0122086c57a56c701ddb29b461a))
+
 ## [0.2.0](https://github.com/seuros/strongroom/compare/strongroom-rails-v0.1.0...strongroom-rails/v0.2.0) (2026-10-25)
 
 

data/README.md

@@ -2,9 +2,9 @@
 
 Rails adapter for [Strongroom](https://github.com/seuros/strongroom), a Postgres-first authentication kernel
 that acts as your application's security coprocessor: Rails never sees password
-hashes or session secrets. Registration goes through the kernel's service API
-from your server; MFA, password recovery, JWT minting, mail and automatic routes
-are deliberately absent.
+hashes or session secrets. Registration and recovery links go through the
+kernel's service API from your server; MFA, JWT minting, mail and automatic
+routes are deliberately absent.
 
 > **Status: pre-production.** Strongroom has not been audited and is not approved
 > for production traffic or real credential imports.
@@ -34,6 +34,8 @@ Requires Ruby **4.0+** and Rails **8.1+** (currently Rails 8.x).
 - [x] Registration, verification links and the account event feed through the
   kernel's service listener, with the namespace's service key (see
   [Registration](#registration)). Sessions report `identity_verified`.
+- [x] Self-service password change and password recovery links (see
+  [Password change and recovery](#password-change-and-recovery)).
 
 It never finds users by email, creates local accounts, dynamically constantizes
 table names, overrides `current_user`, installs routes or falls back to legacy
@@ -105,7 +107,8 @@ At most 16 are supported; names, tables and same-issuer audiences must be distin
 Pass actual model classes, never class names from parameters/configuration.
 `register` defaults false; `register: true` needs a client configured with
 `service_endpoint:` and `service_key:` and enables `register_account` and
-`issue_verification` on the account. The gem still installs no route.
+`issue_verification` on the account; `issue_recovery` and `events` need only
+the service key. The gem still installs no route.
 
 Controllers opt in explicitly and keep their own frontend response contract:
 
@@ -365,7 +368,8 @@ verifies the address.
 - `events(after: nil, limit: 100)` returns a `Strongroom::EventPage` of
   `Strongroom::Event`s (`Provision`, `Register`, `RegistrationCancel`,
   `VerificationIssue`, `IdentityVerify`, `PasswordHashUpgrade`,
-  `PasswordReplace`, `Revoke`); keep `page.next` and pass it as `after:`.
+  `PasswordReplace`, `Revoke`, `RecoveryIssue`, `RecoveryComplete`,
+  `PasswordChange`); keep `page.next` and pass it as `after:`.
   `next` is `nil` for an empty page: ask again later with the cursor you have.
   `page.oldest_at` is the oldest event the kernel still holds; if your last
   event is older, retention pruned events you never read. `Strongroom::CursorAhead`
@@ -379,6 +383,105 @@ Service-key refusals raise `Strongroom::ProtocolError` (a deployment error, not
 a user's), rate limits `Strongroom::RateLimited`/`Busy` with `retry_after`. The
 Railtie maps `Conflict`s to 409, `InvalidPassword` to 422 and `NotFound` to 404.
 
+## Password change and recovery
+
+### Changing a password
+
+A signed-in user changes their password through your controller; the helper
+verifies mutation intent like the others, sends the request's session to the
+kernel and replaces the encrypted cookie with the session the kernel rotated
+onto the new password. The user stays signed in; every other session of theirs
+in the org ends, in every app.
+
+```ruby
+def update # POST; verified CSRF required.
+  user = strongroom_change_password(namespace: :users,
+    current_password: params.require(:current_password), new_password: params.require(:new_password))
+  render json: {id: user.id}
+end
+```
+
+A wrong current password raises `Strongroom::Unauthorized` (401) and changes
+nothing: the session keeps working. A refused new password raises
+`Strongroom::InvalidPassword` with `reason` `too_short`, `too_long` or
+`invalid` (422), before the current password is even checked. An unverified
+identity raises `Strongroom::IdentityUnverified` (409): nobody has proven they
+own the address, so its password proves nothing; have the user confirm it
+first. A session issued with a password the identity no longer logs in with
+raises `Strongroom::CredentialChanged` (409): sign in again. The kernel's
+per-user budget raises `Strongroom::RateLimited` (429). Add your own per-IP
+`rate_limit` too, as for logins. Recovery links the user asked for keep
+working after a change. `client.change_password(token:, current_password:,
+new_password:)` (or `account.change_password`) is the same call without the
+cookie: it returns the rotated `Strongroom::IssuedSession`, confirmed through
+`/me` like a rotation. If that confirmation fails after the kernel made the
+change, the rotated session is logged out before `ProtocolError` is raised:
+the new password is set, and the user signs in with it.
+
+### Recovering a password
+
+Any namespace whose client has `service_endpoint:` and `service_key:` can
+issue recovery links, for imported and registered accounts alike; `register:`
+is not needed. Ask for a link where the mail is built, never in the request
+that asked for it, and never hand the token to a job:
+
+```ruby
+class RecoveriesController < ApplicationController
+  rate_limit to: 5, within: 10.minutes, by: -> { request.remote_ip }, only: :create
+
+  def create # POST; the same answer whether or not the address has an account.
+    RecoveryMailer.with(email: params.require(:email)).reset.deliver_later # the address, never a token
+    head :accepted
+  end
+end
+
+class RecoveryMailer < ApplicationMailer
+  def reset
+    users = Rails.configuration.x.strongroom_accounts.fetch(:users)
+    link = users.issue_recovery(identity: params.fetch(:email))
+    # The fragment of a link to your own page: browsers never send it, so
+    # neither your logs nor a Referer header see the token.
+    @url = "https://app.example.com/password/reset##{link.token.reveal}"
+    mail(to: params.fetch(:email), subject: "Choose a new password")
+  rescue Strongroom::NotFound
+    # No usable account holds the address: without `mail`, nothing is sent.
+  end
+end
+```
+
+`issue_recovery(identity:)` returns a `Strongroom::Recovery` (`token`, a
+`Strongroom::RecoveryToken` redacted everywhere and never a session credential;
+`expires_at`, by default 30 minutes away; `user_id`). Earlier links of that
+address stop working. It raises `Strongroom::NotFound` when no usable account
+holds the address in the namespace: answer your users the same way either way,
+or the form tells anyone which addresses have accounts. If the token must
+travel through a job after all, only in an argument your own
+`ActiveJob::Serializers::ObjectSerializer` encrypts.
+
+The page at `/password/reset` asks for the new password and posts it with the
+fragment to the kernel's public listener (list the page's origin in its
+`[browser] allowed_origins`; the gem does not proxy it):
+
+```js
+const reply = await fetch(`${STRONGROOM_ORIGIN}/accounts/users/recovery`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json", "X-Strongroom-Request": "1" },
+  body: JSON.stringify({ token: location.hash.slice(1), password: form.password.value }),
+}); // 200 {"status": "recovered"}; 422 {"error": "invalid_password", "reason": ...} keeps the link
+    // usable; 400 {"error": "invalid_token", "reason": "invalid" | "expired"}; 503: retry
+```
+
+A completed recovery sets the new password, ends every session of the user in
+the org (in every app) and their other recovery links, and verifies an address
+that was never verified: following the link proved the mailbox. Send the
+person to your sign-in page afterwards. A second use of the link answers
+`invalid_token`. Links belong to the address across every app of the org.
+
+Do not offer recovery for an address whose registration is still unverified:
+the owner would inherit the account whoever registered it prepared (your
+records for that `external_id`), and `cancel_registration` refuses it once
+verified. Cancel such a registration and let the owner register afresh.
+
 ## Running the daemon
 
 This gem is only the client: it ships no binary and needs none to install. The
@@ -406,8 +509,9 @@ The two gems are versioned separately.
 
 - Keep direct backend access restricted and TLS/service networking trusted.
   Local eligibility checks do not synchronize kernel account state or revoke
-  all remote sessions. Password changes/resets, disablement and MFA enablement
-  still need authoritative credential/state updates and invalidation.
+  all remote sessions. Disablement and MFA enablement still need authoritative
+  credential/state updates and invalidation; password changes and recoveries
+  through the kernel revoke its sessions themselves.
 - Imports remain an existing, confirmed, password-only cohort; registration
   creates unverified accounts the kernel refuses until they are verified (or
   until a configured grace runs out). Real admins and MFA-required accounts
@@ -422,8 +526,8 @@ The two gems are versioned separately.
   Ruby/parser/network/framework copies cannot be reliably erased. Do not log
   headers, cookie jars, passwords, transport bodies or explicit token strings.
   The Railtie adds parameter filters; separately audit proxy/middleware/APM logs.
-- Mail delivery, password recovery and change, bulk mapping orchestration,
-  remote admin operations, deployment SLOs and production approval are not shipped.
+- Mail delivery, bulk mapping orchestration, remote admin operations,
+  deployment SLOs and production approval are not shipped.
 
 ## Local checks (no installs, network or database required)
 
@@ -495,7 +599,8 @@ directory; it may also name the RubyGems launchers of an installed `strongroomd`
   `__Host-` cookie and a free admin port, and waits for `/admin/ready`. If the
   daemon exits, the failure carries its stderr (database URL redacted).
 - Seeds only synthetic org/app bindings, then uses the actual admin CLI to
-  provision two distinct, confirmed password-only principals with the same email.
+  provision three distinct, confirmed password-only principals, two of them with
+  the same email in different namespaces.
   The `admin` fixture is a realm-isolation test, not real admin/MFA migration.
 - Installs a fresh package in a temporary consumer bundle, then uses its real
   Net::HTTP client for login, audience isolation, rotation, reuse detection,
@@ -511,9 +616,16 @@ directory; it may also name the RubyGems launchers of an installed `strongroomd`
   nothing, then confirms it by `POST` on the public listener and logs in with
   `identity_verified` true, reads the event feed, and cancels a squatted
   registration so the address can be registered again.
-- Checks the database for two bcrypt upgrades, one verified registration, two
-  rotations and no live sessions, and the daemon's `/admin/metrics` for the
-  exact login, registration and verification outcomes.
+- Changes a registered account's password: a wrong current password and a weak
+  new one change nothing, the session that asked continues on the new
+  password, its other session and the old password stop working. Recovers a
+  registered account (refused weak password, one-time link, every session
+  ended, the new password logs in), an address that was never verified (the
+  recovery verifies it) and an imported bcrypt account.
+- Checks the database for the imports, the verified registrations, the bcrypt
+  upgrades, the rotations and no live sessions, and the daemon's
+  `/admin/metrics` for the exact login, registration, verification, recovery
+  and password change outcomes.
 - Bounds subprocesses and kills/reaps its owned process groups, drops its schema
   and removes temporary files on completion or handled failure/interruption.
   The caller remains responsible for stopping the supplied PostgreSQL server.

data/lib/strongroom/client.rb

@@ -11,7 +11,7 @@ module Strongroom
     CURSOR = /\A[A-Za-z0-9_-]{34}\z/
     IDENTITY_STATES = %w[Unverified Verified Disabled].freeze
     EVENT_TYPES = %w[Provision Register RegistrationCancel VerificationIssue IdentityVerify PasswordHashUpgrade
-      PasswordReplace Revoke].freeze
+      PasswordReplace Revoke RecoveryIssue RecoveryComplete PasswordChange].freeze
     LOGIN = {"session_id" => :uuid, "user_id" => :uuid, "expires_at" => :timestamp,
              "identity_verified" => :boolean}.freeze
     METADATA = LOGIN.merge("org_id" => :uuid, "app_id" => :uuid).freeze
@@ -89,6 +89,32 @@ module Strongroom
       end
     end
 
+    # Changes the password of the identity `token`'s session was issued for and
+    # returns that session rotated onto it, confirmed through `/me` as rotation
+    # is. Every other session of the user in the org ends. A wrong
+    # `current_password` raises `Unauthorized` and leaves the session as it was;
+    # an unverified identity raises `IdentityUnverified`, a session issued with
+    # a password the identity no longer logs in with `CredentialChanged`. If
+    # the change went through but `/me` does not confirm the rotated session,
+    # that session is logged out before `ProtocolError` is raised: the new
+    # password is set and the user signs in with it.
+    def change_password(token:, current_password:, new_password:)
+      unless [current_password, new_password].all? { |value| value.is_a?(String) }
+        raise InvalidRequest, "passwords must be strings"
+      end
+      body = JSON.generate(current_password: current_password, new_password: new_password)
+      raise InvalidRequest, "password change request too large" if body.bytesize > 16_384
+      response = request(:post, "auth/password", token: Token.coerce(token), body: body)
+      issue(response) do |successor|
+        declared = metadata(response)
+        current = session(token: successor)
+        raise ProtocolError, "inconsistent password change response" unless same_session?(declared, current)
+        current
+      end
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid password change payload", cause: nil
+    end
+
     def logout(token:)
       request(:delete, "auth/logout", token: Token.coerce(token), status: 204)
       nil
@@ -151,6 +177,24 @@ module Strongroom
       Verification.new(token: VerificationToken.new(values["token"]), expires_at: values["expires_at"])
     end
 
+    # A recovery link for the account holding the email address `identity` in
+    # this namespace; earlier recovery links of that address stop working. The
+    # browser completes it: POST {"token", "password"} to
+    # `/accounts/<namespace>/recovery` on the kernel's public listener. Raises
+    # `NotFound` when no usable account holds the address: answer your users
+    # the same way either way.
+    def issue_recovery(identity:)
+      raise InvalidRequest, "identity must be a string" unless identity.is_a?(String)
+      body = JSON.generate(identity_kind: "email", identity: identity)
+      raise InvalidRequest, "recovery request too large" if body.bytesize > 16_384
+      response = service_request(:post, "recoveries", body: body, statuses: [201])
+      values = object(response, {"token" => :string, "expires_at" => :timestamp, "user_id" => :uuid})
+      Recovery.new(token: RecoveryToken.new(values["token"]), expires_at: values["expires_at"],
+        user_id: values["user_id"].freeze)
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid recovery payload", cause: nil
+    end
+
     # One page of the namespace's event feed, in commit-safe order.
     def events(after: nil, limit: 100)
       unless (after.nil? || (after.is_a?(String) && after.match?(CURSOR))) &&
@@ -244,6 +288,8 @@ module Strongroom
       case response.status
       when 401 then raise Unauthorized, "authentication failed"
       when 403 then raise ProtocolError, "authentication request refused by service policy"
+      when 409 then conflict!(response)
+      when 422 then invalid_password!(response)
       when 429 then raise RateLimited.new(retry_after: retry_after(response))
       when 503 then raise Busy.new(retry_after: retry_after(response))
       when 500..599 then raise Unavailable, "authentication service unavailable"
@@ -273,16 +319,19 @@ module Strongroom
       when 401, 403 then raise ProtocolError, "service key or caller refused by the kernel"
       when 404 then raise NotFound, "not found in this namespace"
       when 409 then conflict!(response)
-      when 422
-        reason = service_error(response)&.fetch("reason", nil)
-        raise InvalidPassword.new(reason: reason) if InvalidPassword::REASONS.include?(reason)
-        raise ProtocolError, "invalid service response"
+      when 422 then invalid_password!(response)
       when 429 then raise RateLimited.new(retry_after: retry_after(response))
       when 503 then raise Busy.new(retry_after: retry_after(response))
       when 500..599 then raise Unavailable, "authentication service unavailable"
       end
     end
 
+    def invalid_password!(response)
+      reason = service_error(response)&.fetch("reason", nil)
+      raise InvalidPassword.new(reason: reason) if InvalidPassword::REASONS.include?(reason)
+      raise ProtocolError, "invalid authentication response"
+    end
+
     def conflict!(response)
       case service_error(response)&.fetch("error", nil)
       when "identity_taken" then raise IdentityTaken, "identity already belongs to another account"
@@ -290,6 +339,8 @@ module Strongroom
       when "already_verified" then raise AlreadyVerified, "identity is already verified"
       when "identity_disabled" then raise IdentityDisabled, "identity is disabled"
       when "cursor_ahead" then raise CursorAhead, "feed cursor is ahead of the kernel's database"
+      when "identity_unverified" then raise IdentityUnverified, "identity is not verified"
+      when "credential_changed" then raise CredentialChanged, "session predates the identity's password"
       else raise ProtocolError, "invalid service response"
       end
     end

data/lib/strongroom/errors.rb

@@ -16,6 +16,14 @@ module Strongroom
   class AlreadyVerified < Conflict; end
   class IdentityDisabled < Conflict; end
 
+  # A password change for an unverified identity: nobody has proven they own
+  # the address, so knowing its password proves nothing. Nothing changed.
+  class IdentityUnverified < Conflict; end
+
+  # A password change from a session issued with a password the identity no
+  # longer logs in with: sign in again, then change it. Nothing changed.
+  class CredentialChanged < Conflict; end
+
   # The feed cursor names a point the kernel's database has not reached (it was
   # restored, failed over or copied): drop the cursor and read from the start.
   class CursorAhead < Conflict; end

data/lib/strongroom/rails/account.rb

@@ -48,6 +48,18 @@ module Strongroom
         client.issue_verification(user_id: user_id)
       end
 
+      # A recovery link for the account holding `identity`; needs only the
+      # service key, so imported and registered accounts alike can recover.
+      def issue_recovery(identity:)
+        client.issue_recovery(identity: identity)
+      end
+
+      # Changes the password of `token`'s session and returns it rotated onto
+      # the new one; prefer the controller helper, which also replaces the cookie.
+      def change_password(token:, current_password:, new_password:)
+        client.change_password(token: token, current_password: current_password, new_password: new_password)
+      end
+
       # The namespace's event feed; needs only the service key.
       def events(after: nil, limit: 100)
         client.events(after: after, limit: limit)

data/lib/strongroom/rails/authentication.rb

@@ -50,6 +50,22 @@ module Strongroom
         strongroom_resolver.forget(namespace)
       end
 
+      # Changes the password of the request's session and replaces the cookie
+      # with the session rotated onto the new password. Every other session of
+      # the user in the org ends; a wrong current password raises
+      # `Unauthorized`, an unverified identity `IdentityUnverified`, and
+      # neither changes anything.
+      def strongroom_change_password(namespace:, current_password:, new_password:)
+        strongroom_verify_mutation!(:post)
+        account = strongroom_registry.fetch(namespace)
+        token = strongroom_resolver.credential(namespace) or raise Unauthorized, "authentication failed"
+        changed = account.change_password(token: token, current_password: current_password,
+          new_password: new_password)
+        strongroom_publish(account, changed)
+      ensure
+        strongroom_resolver.forget(namespace)
+      end
+
       def strongroom_logout(namespace:)
         strongroom_verify_mutation!(:delete)
         account = strongroom_registry.fetch(namespace)

data/lib/strongroom/rails/railtie.rb

@@ -17,6 +17,8 @@ module Strongroom
         "Strongroom::AlreadyVerified" => :conflict,
         "Strongroom::IdentityDisabled" => :conflict,
         "Strongroom::CursorAhead" => :conflict,
+        "Strongroom::IdentityUnverified" => :conflict,
+        "Strongroom::CredentialChanged" => :conflict,
         "Strongroom::RateLimited" => :too_many_requests,
         "Strongroom::Busy" => :service_unavailable,
         "Strongroom::ProtocolError" => :service_unavailable,
@@ -25,7 +27,7 @@ module Strongroom
 
       initializer "strongroom.filter_credentials" do |app|
         app.config.filter_parameters |= %i[password password_confirmation identity authorization cookie strongroom_token
-          service_key verification_token]
+          service_key verification_token recovery_token]
       end
 
       config.after_initialize do |app|

data/lib/strongroom/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Strongroom
   module Rails
-    VERSION = "0.2.0" # x-release-please-version
+    VERSION = "0.3.0" # x-release-please-version
   end
 end

data/lib/strongroom/session.rb

@@ -37,10 +37,10 @@ module Strongroom
     end
   end
 
-  # A verification link's secret. Put it in the URL fragment of a link to your
-  # own page, whose button posts it to the kernel; nothing here is safe to log
+  # A link's secret and its expiry. Put the token in the URL fragment of a link
+  # to your own page, which posts it to the kernel; nothing here is safe to log
   # or serialize.
-  class Verification
+  class Link
     attr_reader :token, :expires_at
 
     def initialize(token:, expires_at:)
@@ -48,16 +48,33 @@ module Strongroom
       freeze
     end
 
-    def inspect = "#<Strongroom::Verification expires_at=#{expires_at.iso8601} token=[FILTERED]>"
+    def inspect = "#<#{self.class.name} expires_at=#{expires_at.iso8601} token=[FILTERED]>"
     alias to_s inspect
     def pretty_print(printer) = printer.text(inspect)
 
     def as_json(*)
-      raise TypeError, "verification links must not be serialized"
+      raise TypeError, "links must not be serialized"
     end
 
     def marshal_dump
-      raise TypeError, "verification links must not be serialized"
+      raise TypeError, "links must not be serialized"
     end
   end
+
+  # A verification link: its page's button confirms the address.
+  class Verification < Link; end
+
+  # A recovery link for `user_id`: its page asks for a new password and posts
+  # both to the kernel.
+  class Recovery < Link
+    attr_reader :user_id
+
+    def initialize(token:, expires_at:, user_id:)
+      @user_id = user_id
+      super(token: token, expires_at: expires_at)
+    end
+
+    def inspect = "#<Strongroom::Recovery user_id=#{user_id} expires_at=#{expires_at.iso8601} token=[FILTERED]>"
+    alias to_s inspect
+  end
 end

data/lib/strongroom/token.rb

@@ -75,6 +75,12 @@ module Strongroom
     def self.refusal = [ProtocolError, "invalid verification token"]
   end
 
+  # A recovery link's secret, `srr1_...`: mail it, never log it.
+  class RecoveryToken < Credential
+    def self.prefix = "srr1_"
+    def self.refusal = [ProtocolError, "invalid recovery token"]
+  end
+
   # A namespace's service key, `srk1_...`, sent only to the service listener.
   class ServiceKey < Credential
     def self.prefix = "srk1_"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strongroom-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Seuros