strongroom-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2313700e0514a62dbf3f58e5f541e0c4421f4c034a8220840cd9ca243d05b816
-  data.tar.gz: 5530d843f7630a021488e36bcc230bdfd9d1137f3aec6c5a1dd8d233c3a9b09f
+  metadata.gz: 5561c0010955953673794759017eb0f3683d838d60dd70ed09ae88f185954717
+  data.tar.gz: 0d620abade30695c4779dc8e123c9444b4ff723904e3bc19bd903985f1f47d53
 SHA512:
-  metadata.gz: 5b77a81722924260a13456a6416012c2670dafe0360cb8932f21c8fd3250301a50564fd7d86e7c26425e741b5fd781a08b694a812357afece92dec857570b881
-  data.tar.gz: fce5256ee8f35e3f44e70165c0615a0d5c3a0ddc61b05d5b976cf7918368f425d0b0ef026d7009fb1c7a44a733bb0b36f8849b56eda5ee73b5cb32c2b25b4127
+  metadata.gz: aa14aa3c3c14336f886876097bb85afb3c56332583567eadbf88b3839abbf518e8af4841a80023d0085ad5e7df6b58a9dff0962c875b0a028751dd4ff6c42046
+  data.tar.gz: 333bce6b18f73ec77edbe98645668cd40bcbcaa3443eff5e501706c4e915aee4c18c1808298022222622bf4708cf80f21dd4f6e0923aaa0fc03aded6e51dac61

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

data/README.md

@@ -107,8 +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; `issue_recovery` and `events` need only
-the service key. 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:
 
@@ -369,7 +371,8 @@ verifies the address.
   `Strongroom::Event`s (`Provision`, `Register`, `RegistrationCancel`,
   `VerificationIssue`, `IdentityVerify`, `PasswordHashUpgrade`,
   `PasswordReplace`, `Revoke`, `RecoveryIssue`, `RecoveryComplete`,
-  `PasswordChange`); keep `page.next` and pass it as `after:`.
+  `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`
@@ -383,6 +386,39 @@ 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
@@ -445,6 +481,8 @@ class RecoveryMailer < ApplicationMailer
     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
 ```
@@ -453,8 +491,9 @@ end
 `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
+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.
 
@@ -471,16 +510,16 @@ const reply = await fetch(`${STRONGROOM_ORIGIN}/accounts/users/recovery`, {
     // 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
+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.
 
-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.
+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
 

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 RecoveryIssue RecoveryComplete PasswordChange].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
@@ -181,8 +181,11 @@ module Strongroom
     # 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.
+    # `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)
@@ -195,6 +198,76 @@ module Strongroom
       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))) &&
@@ -214,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
@@ -340,7 +423,9 @@ module Strongroom
       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"
+      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
@@ -398,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

@@ -21,9 +21,17 @@ module Strongroom
   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.
+  # 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

@@ -65,6 +65,21 @@ module Strongroom
         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/version.rb

@@ -2,6 +2,6 @@
 
 module Strongroom
   module Rails
-    VERSION = "0.3.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)

metadata

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