strongroom-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec4204432b51f2a1d28d6ca08fa846a6ed9413de15e2164dbc4f506aa0e3f474
-  data.tar.gz: 87eb737c063fbdbe0f8ba0e5767541c37abfa1addcf1e02117fa5754f51102ad
+  metadata.gz: 5561c0010955953673794759017eb0f3683d838d60dd70ed09ae88f185954717
+  data.tar.gz: 0d620abade30695c4779dc8e123c9444b4ff723904e3bc19bd903985f1f47d53
 SHA512:
-  metadata.gz: 9dd07c5ee1df0e5ec948bd724ea445f45d61d9c34ec0421ab9f838ebbaa3c41d66d0a997c39e6120d6671fb1f35dbe8c14a3b9c8bc46fc42a20e3ae01a92ff3d
-  data.tar.gz: a4bf94a507478ceeb8f83d5be2e1d3da89afe287e127bfc234d23535338236392db768159dcc80218ff3311c8245f7c5dab908bbdfdd9521ed6bf04b78ff5e9e
+  metadata.gz: aa14aa3c3c14336f886876097bb85afb3c56332583567eadbf88b3839abbf518e8af4841a80023d0085ad5e7df6b58a9dff0962c875b0a028751dd4ff6c42046
+  data.tar.gz: 333bce6b18f73ec77edbe98645668cd40bcbcaa3443eff5e501706c4e915aee4c18c1808298022222622bf4708cf80f21dd4f6e0923aaa0fc03aded6e51dac61

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.0](https://github.com/seuros/strongroom/compare/strongroom-rails-v0.3.0...strongroom-rails-v0.4.0) (2026-10-26)
+
+
+### Features
+
+* add account suspension and session revocation, service imports with conditional password replacement and in-daemon pruning; recover only verified identities ([be52bd1](https://github.com/seuros/strongroom/commit/be52bd1654b9f104aa8e82eb2129d0751a62f3d1))
+
+## [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,10 @@ 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`, `events`, `suspend`,
+`reinstate` and `revoke_sessions` need only the service key, and
+`import_account` and `replace_imported_password` a namespace with
+`import = true`. The gem still installs no route.
 
 Controllers opt in explicitly and keep their own frontend response contract:
 
@@ -365,7 +370,9 @@ 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`, `AccountSuspend`, `AccountReinstate`); 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 +386,141 @@ 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.
 
+## Account control and imports
+
+On the client of any keyed namespace:
+
+- `suspend(user_id:)` suspends the user's account in the namespace's org: every
+  session it holds there ends, its verification and recovery links stop
+  working, and nothing authenticates until `reinstate(user_id:)`, which leaves
+  those sessions and links ended. Both return a `Strongroom::AccountChange`
+  (`state`, `changed`: false for a repeat, `revoked_sessions`).
+- `revoke_sessions(user_id:)` ends every live session of the user in the org
+  ("sign out everywhere") and returns how many ended.
+- All three raise `Strongroom::NotFound` for a user outside the namespace,
+  `Strongroom::AccountDisabled` (suspension and reinstatement) for a disabled
+  account, and `Strongroom::Busy` while one of the user's sessions is being
+  rotated or logged out: retry, nothing changed.
+
+With `import = true` on the namespace:
+
+- `import_account(source:, external_id:, identity:, password_hash:,
+  account_state:, grant_state:, identity_state:, credential_state:,
+  mfa_required:)` imports an account with a pre-hashed password, as
+  `strongroom-admin provision` does, and returns a `Strongroom::Import`
+  (`user_id`, `identity_id`, `credential_id`, `created`: false for a replay).
+  Every state is explicit. It raises `Strongroom::BindingConflict`,
+  `Strongroom::IdentityTaken` or `Strongroom::InvalidRequest`.
+- `replace_imported_password(source:, external_id:, expected_password_hash:,
+  password_hash:)` replaces that account's password only while it still holds
+  `expected_password_hash`, and returns a `Strongroom::PasswordReplacement`
+  (`status` `"replaced"` or `"unchanged"`). Once the kernel owns the password
+  (a login upgraded the hash, a recovery or password change replaced it), it
+  raises `Strongroom::CredentialChanged` and changes nothing: stop sending
+  hashes for that account.
+
+## 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.
+  rescue Strongroom::IdentityUnverified
+    # Registered, never verified: cancel that registration instead (see below).
+  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, and `Strongroom::IdentityUnverified` when
+the address was registered but never verified: answer your users the same way
+in every case, 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 and ends every session of the user
+in the org (in every app) and their other recovery links. 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.
+
+Only verified addresses recover: anybody can register an address, and its
+owner would inherit the account whoever registered it prepared (your records
+for that `external_id`). On `Strongroom::IdentityUnverified`, cancel that
+registration and let the owner register afresh; do not send a verification
+link instead, which would let the owner verify that account and recover it.
+
 ## Running the daemon
 
 This gem is only the client: it ships no binary and needs none to install. The
@@ -406,8 +548,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 +565,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 +638,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 +655,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 AccountSuspend AccountReinstate].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,97 @@ 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, and
+    # `IdentityUnverified` when the address was registered but never verified:
+    # whoever registered it may not own it, so cancel that registration and let
+    # the owner register afresh rather than recover it. Answer your users the
+    # same way in every case.
+    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
+
+    # Suspends the account of `user_id` in this namespace's org: every session
+    # it holds there ends, its verification and recovery links stop working,
+    # and it authenticates nowhere in the org until `reinstate`. Raises
+    # `NotFound`, `AccountDisabled`, or `Busy` while one of its sessions is
+    # being rotated or logged out (retry).
+    def suspend(user_id:)
+      account_change("suspensions", user_id, "Suspended")
+    end
+
+    # Lifts a suspension. The sessions and links it ended stay ended.
+    def reinstate(user_id:)
+      account_change("reinstatements", user_id, "Active")
+    end
+
+    # Ends every live session of `user_id` in this namespace's org, whatever
+    # its account's state, and returns how many ended. `Busy` as for `suspend`.
+    def revoke_sessions(user_id:)
+      raise InvalidRequest, "user_id must be a canonical UUID" unless canonical_uuid?(user_id)
+      response = service_request(:post, "revocations", body: JSON.generate(user_id: user_id), statuses: [200])
+      object(response, {"revoked_sessions" => :count})["revoked_sessions"]
+    end
+
+    # Imports one account with a pre-hashed password (bcrypt or Argon2id), keyed
+    # by your `source` and `external_id`, as `strongroom-admin provision` does;
+    # the namespace needs `import = true`. Every state is explicit: the kernel
+    # refuses MFA and unverified identities. Replaying the same import returns
+    # its receipt (`created: false`); a changed one raises `BindingConflict`,
+    # an address another account holds `IdentityTaken`.
+    def import_account(source:, external_id:, identity:, password_hash:, account_state:, grant_state:,
+      identity_state:, credential_state:, mfa_required:, identity_kind: "email")
+      fields = {source: source, external_id: external_id, identity_kind: identity_kind, identity: identity,
+                account_state: account_state, grant_state: grant_state, identity_state: identity_state,
+                credential_state: credential_state, password_hash: password_hash}
+      unless fields.values.all?(String) && [true, false].include?(mfa_required)
+        raise InvalidRequest, "import fields must be strings and mfa_required a boolean"
+      end
+      body = JSON.generate(fields.merge(mfa_required: mfa_required))
+      raise InvalidRequest, "import request too large" if body.bytesize > 16_384
+      response = service_request(:post, "imports", body: body, statuses: [200, 201])
+      values = object(response, {"user_id" => :uuid, "identity_id" => :uuid, "credential_id" => :uuid})
+      Import.new(user_id: values["user_id"], identity_id: values["identity_id"],
+        credential_id: values["credential_id"], created: response.status == 201)
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid import payload", cause: nil
+    end
+
+    # Replaces the password of the account an import bound to `source` and
+    # `external_id` with `password_hash`, but only while its active credential
+    # still holds `expected_password_hash`, the hash you imported or last
+    # replaced. Once the kernel owns the password (a login upgraded its hash, a
+    # recovery or password change replaced it) this raises `CredentialChanged`
+    # and changes nothing. Its sessions end with the old credential.
+    def replace_imported_password(source:, external_id:, expected_password_hash:, password_hash:)
+      fields = {source: source, external_id: external_id, expected_password_hash: expected_password_hash,
+                password_hash: password_hash}
+      raise InvalidRequest, "replacement fields must be strings" unless fields.values.all?(String)
+      body = JSON.generate(fields)
+      raise InvalidRequest, "replacement request too large" if body.bytesize > 16_384
+      response = service_request(:post, "imports/password", body: body, statuses: [200])
+      values = object(response, {"status" => :string, "user_id" => :uuid, "identity_id" => :uuid,
+                                 "credential_id" => :uuid, "revoked_credential_id" => :uuid_or_nil})
+      unless (values["status"] == "replaced") == !values["revoked_credential_id"].nil? &&
+          %w[replaced unchanged].include?(values["status"])
+        raise ProtocolError, "invalid service response"
+      end
+      PasswordReplacement.new(**values.transform_keys(&:to_sym))
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid replacement 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))) &&
@@ -170,6 +287,16 @@ module Strongroom
 
     private
 
+    def account_change(suffix, user_id, state)
+      raise InvalidRequest, "user_id must be a canonical UUID" unless canonical_uuid?(user_id)
+      response = service_request(:post, suffix, body: JSON.generate(user_id: user_id), statuses: [200])
+      schema = {"state" => :string, "changed" => :boolean}
+      schema["revoked_sessions"] = :count if state == "Suspended"
+      values = object(response, schema)
+      raise ProtocolError, "invalid service response" unless values["state"] == state
+      AccountChange.new(state: state, changed: values["changed"], revoked_sessions: values.fetch("revoked_sessions", 0))
+    end
+
     def configure_service(endpoint, key, transport)
       if endpoint.nil? && key.nil? && transport.nil?
         @service_endpoint = @service_key = @service_transport = nil
@@ -244,6 +371,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 +402,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 +422,10 @@ 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, "the identity's password credential changed"
+      when "account_disabled" then raise AccountDisabled, "account is disabled"
+      when "no_active_credential" then raise NoActiveCredential, "account has no active password"
       else raise ProtocolError, "invalid service response"
       end
     end
@@ -347,6 +483,7 @@ module Strongroom
       when :uuid then canonical_uuid?(value)
       when :boolean then value == true || value == false
       when :uuid_or_nil then value.nil? || canonical_uuid?(value)
+      when :count then value.is_a?(Integer) && value >= 0
       else value.is_a?(String)
       end
     end

data/lib/strongroom/errors.rb

@@ -16,6 +16,22 @@ 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. For an imported
+  # password replacement: the kernel's credential no longer holds the expected
+  # hash, so the kernel owns that password now. Nothing changed.
+  class CredentialChanged < Conflict; end
+
+  # A suspension or reinstatement of an account that is disabled, which is final.
+  class AccountDisabled < Conflict; end
+
+  # An imported password replacement for an account without an active password.
+  class NoActiveCredential < 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,11 +48,38 @@ 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)
       end
 
+      # Suspends the user's account in the namespace's org, ending its sessions
+      # and links; needs only the service key.
+      def suspend(user_id:)
+        client.suspend(user_id: user_id)
+      end
+
+      def reinstate(user_id:)
+        client.reinstate(user_id: user_id)
+      end
+
+      # Ends every live session of the user in the namespace's org.
+      def revoke_sessions(user_id:)
+        client.revoke_sessions(user_id: user_id)
+      end
+
       def resolve(session)
         subject = client.subject(session)
         record = @resolver.call(subject)

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.4.0" # x-release-please-version
   end
 end

data/lib/strongroom/session.rb

@@ -10,6 +10,20 @@ module Strongroom
   # changed nothing; `identity_state` is the identity's current state.
   Registration = Data.define(:user_id, :identity_id, :identity_state, :created)
 
+  # What a suspension or reinstatement did: the account's `state` now
+  # ("Suspended" or "Active"), whether this call `changed` it, and how many
+  # sessions a suspension ended (0 for a reinstatement or a repeat).
+  AccountChange = Data.define(:state, :changed, :revoked_sessions)
+
+  # An import's receipt. `created` is false for an exact replay, which changed
+  # nothing.
+  Import = Data.define(:user_id, :identity_id, :credential_id, :created)
+
+  # A replaced imported password. `status` is "replaced" (the credential
+  # `revoked_credential_id` was revoked for `credential_id`) or "unchanged"
+  # (the active credential held that hash already; `revoked_credential_id` nil).
+  PasswordReplacement = Data.define(:status, :user_id, :identity_id, :credential_id, :revoked_credential_id)
+
   # One account event from the namespace's feed. `meta` is a frozen Hash of
   # non-secret IDs (session, credential, token).
   Event = Data.define(:id, :type, :user_id, :identity_id, :at, :meta)
@@ -37,10 +51,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 +62,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.4.0
 platform: ruby
 authors:
 - Seuros