strongroom-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d266097d730b4561dc0e197cbfb8cb6811626b1cfea5defd21b7f018f0e39ed0
-  data.tar.gz: efc7b6166160438836119409e1c836179daa40b33913dbe4f6a9464eff9f53d3
+  metadata.gz: ec4204432b51f2a1d28d6ca08fa846a6ed9413de15e2164dbc4f506aa0e3f474
+  data.tar.gz: 87eb737c063fbdbe0f8ba0e5767541c37abfa1addcf1e02117fa5754f51102ad
 SHA512:
-  metadata.gz: d9200dd2cdf23a5822286500ee92e35c254d824a2d910c8039df5bfdab0f05402a51ed2dc6e601a7069db72584353d0e8a05681d2ff4b223b4040cd15f8ab6fe
-  data.tar.gz: c109f7251482e29b24b2349ff5cce04958207eaca352d90d5a7b0311d38ca0abc7e55a763e5ec7f25309b323ee092ae8b3e6b415ac675322803e12da3cc5727b
+  metadata.gz: 9dd07c5ee1df0e5ec948bd724ea445f45d61d9c34ec0421ab9f838ebbaa3c41d66d0a997c39e6120d6671fb1f35dbe8c14a3b9c8bc46fc42a20e3ae01a92ff3d
+  data.tar.gz: a4bf94a507478ceeb8f83d5be2e1d3da89afe287e127bfc234d23535338236392db768159dcc80218ff3311c8245f7c5dab908bbdfdd9521ed6bf04b78ff5e9e

data/CHANGELOG.md

@@ -1 +1,10 @@
 # Changelog
+
+## [0.2.0](https://github.com/seuros/strongroom/compare/strongroom-rails-v0.1.0...strongroom-rails/v0.2.0) (2026-10-25)
+
+
+### Features
+
+* add self-service registration, email verification links, an unverified-login grace policy and an event feed ([b39e976](https://github.com/seuros/strongroom/commit/b39e976600085752350b333a3c82a00e4a0493bf))
+
+## Changelog

data/README.md

@@ -1,8 +1,9 @@
-# strongroom-rails — existing-user login adapter
+# strongroom-rails — login and registration adapter
 
 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, MFA, JWT minting and automatic routes
+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.
 
 > **Status: pre-production.** Strongroom has not been audited and is not approved
@@ -30,6 +31,9 @@ Requires Ruby **4.0+** and Rails **8.1+** (currently Rails 8.x).
 - [x] Request-level resolver and an optional Warden strategy.
 - [x] Trusted subject resolution into an allowlisted local model/table, followed by
   an application-supplied active/confirmed/MFA/cohort eligibility check.
+- [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`.
 
 It never finds users by email, creates local accounts, dynamically constantizes
 table names, overrides `current_user`, installs routes or falls back to legacy
@@ -99,7 +103,9 @@ authenticate (for example an asset build without credentials) can opt out with
 Add additional `Account` objects to the registry for other approved namespaces.
 At most 16 are supported; names, tables and same-issuer audiences must be distinct.
 Pass actual model classes, never class names from parameters/configuration.
-`register` defaults false; true records future policy only and adds no route.
+`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.
 
 Controllers opt in explicitly and keep their own frontend response contract:
 
@@ -281,6 +287,98 @@ sent on a connection the server then dropped raises `Unavailable`. Pools are
 per process; a forked child never touches its parent's sockets. Call
 `transport.close` to drop idle connections at shutdown.
 
+## Registration
+
+The kernel serves registration on its service listener (`server.service_listen`,
+loopback or a private network), authenticated by the namespace's service key.
+Give the client both; the key never appears in `inspect`, `pp` or YAML:
+
+```ruby
+client = Strongroom::Client.new(
+  endpoint: ENV.fetch("STRONGROOM_ENDPOINT"), issuer: "https://auth.example.com", namespace: "users",
+  org_id: ENV.fetch("STRONGROOM_USERS_ORG_ID"), app_id: ENV.fetch("STRONGROOM_USERS_APP_ID"),
+  service_endpoint: ENV.fetch("STRONGROOM_SERVICE_ENDPOINT"), service_key: ENV.fetch("STRONGROOM_USERS_SERVICE_KEY")
+)
+users = Strongroom::Rails::Account.new(client: client, table: "users", model: User, register: true,
+  resolve: ..., eligible: ...)
+
+registration = users.register_account(external_id: user.id.to_s, identity: params[:email],
+  password: params[:password])
+registration.created   # false for a replay of the same external_id and address
+VerificationMailer.with(user: user).confirm.deliver_later   # the user, never the token
+```
+
+Issue the link where the mail is built, so the token never becomes a job
+argument (ActiveJob stores and logs those):
+
+```ruby
+class VerificationMailer < ApplicationMailer
+  def confirm
+    user = params.fetch(:user)
+    link = Rails.configuration.x.strongroom_accounts.fetch(:users)
+      .issue_verification(user_id: user.strongroom_user_id)
+    # The token goes in the fragment of a link to your own page: browsers never
+    # send a fragment, so neither your logs nor a Referer header see it.
+    @url = "https://app.example.com/email/confirm##{link.token.reveal}"
+    mail(to: user.email, subject: "Confirm your address")
+  end
+end
+```
+
+If the token must travel through a job, pass it only in an argument your own
+`ActiveJob::Serializers::ObjectSerializer` encrypts (with
+`ActiveSupport::MessageEncryptor`), or call `deliver_now` from the request.
+Never pass the URL or `link.token.reveal` to `deliver_later`.
+
+The page at `/email/confirm` shows a button; its click posts the fragment to
+the kernel's public listener (the gem does not proxy it). List the page's origin
+in the kernel's `[browser] allowed_origins`:
+
+```js
+await fetch(`${STRONGROOM_ORIGIN}/accounts/users/verify`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json", "X-Strongroom-Request": "1" },
+  body: JSON.stringify({ token: location.hash.slice(1) }),
+}); // 200 {"status": "verified" | "already_verified"}, 400 {"error": "invalid_token", "reason": ...}
+```
+
+A mail scanner that fetches the link only fetches your page: nothing it sends
+verifies the address.
+
+- `register` (on the client; `register_account` on an account) creates the
+  account with an unverified email identity. Replaying the same `external_id`
+  and address returns the original receipt and changes nothing, before any
+  password check. It raises `Strongroom::BindingConflict` (the external ID is
+  bound to another address), `Strongroom::IdentityTaken` (another account holds
+  the address) or `Strongroom::InvalidPassword` with `reason` `too_short`,
+  `too_long` or `invalid`. `IdentityTaken` tells your server an address has an
+  account: do not tell the person signing up.
+- `cancel_registration(external_id:)` deletes a registration whose address was
+  never verified (a squatted address, a stale sign-up); the address and the
+  external ID are free again. It raises `Strongroom::AlreadyVerified`,
+  `Strongroom::IdentityDisabled`, `Strongroom::NotFound`, or `Strongroom::Busy`
+  while one of its sessions is mid-rotation (retry).
+- `issue_verification(user_id:)` returns a `Strongroom::Verification` whose
+  `token` is redacted everywhere and is never a session credential. Earlier
+  links stop working. It raises `Strongroom::AlreadyVerified` or
+  `Strongroom::NotFound`.
+- `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:`.
+  `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`
+  means the kernel's database is behind your cursor (restored or failed over):
+  drop the cursor and read from the start.
+- `Strongroom::Session#identity_verified` is `false` only for an unverified
+  identity inside the namespace's `unverified_grace_hours`; with the default of
+  `0` an unverified identity cannot log in at all.
+
+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.
+
 ## Running the daemon
 
 This gem is only the client: it ships no binary and needs none to install. The
@@ -310,9 +408,11 @@ The two gems are versioned separately.
   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.
-- This release is an existing, confirmed, password-only cohort. Real admins,
-  MFA-required/unverified accounts and registration remain on their explicitly
-  selected legacy owner. Do not use failure fallback or mislabel MFA state.
+- 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
+  remain on their explicitly selected legacy owner. Do not use failure fallback
+  or mislabel MFA state.
 - Define old-cookie/JWT retirement and canonical-session-bound compatibility
   before cutting an existing application over. This gem does not preserve existing JWT/frontend
   contracts automatically or share Rails signing secrets with Strongroom.
@@ -322,7 +422,7 @@ 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.
-- Registration/mail/recovery, bulk mapping orchestration, session families,
+- Mail delivery, password recovery and change, bulk mapping orchestration,
   remote admin operations, deployment SLOs and production approval are not shipped.
 
 ## Local checks (no installs, network or database required)
@@ -405,8 +505,15 @@ directory; it may also name the RubyGems launchers of an installed `strongroomd`
 - Exercises the Rails helpers through in-memory Rack/HTTPS requests, encrypted
   cookies, CSRF and a full-scope trusted mapping into synthetic local records.
   It does not validate a real ActiveRecord binding store, browser TLS or an existing application.
-- Checks the database for two bcrypt upgrades, two rotations and no live sessions,
-  and the daemon's `/admin/metrics` for the exact login outcomes.
+- Registers an account through the service listener with a key minted for the
+  run, proves replay idempotency and the typed refusals, that the account
+  cannot log in before its link is confirmed and that a `GET` of the link does
+  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.
 - 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

@@ -8,9 +8,18 @@ module Strongroom
     TIMESTAMP = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})\z/
     MICROSECOND = Rational(1, 1_000_000)
     ISSUER = /\A[a-z][a-z0-9+.-]*:[!-~]{1,255}\z/
-    attr_reader :endpoint, :issuer, :namespace, :org_id, :app_id, :cookie_name
+    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
+    LOGIN = {"session_id" => :uuid, "user_id" => :uuid, "expires_at" => :timestamp,
+             "identity_verified" => :boolean}.freeze
+    METADATA = LOGIN.merge("org_id" => :uuid, "app_id" => :uuid).freeze
+    SERVICE_KEY_HEADER = "X-Strongroom-Service-Key"
+    attr_reader :endpoint, :issuer, :namespace, :org_id, :app_id, :cookie_name, :service_endpoint
 
-    def initialize(endpoint:, issuer:, namespace:, org_id:, app_id:, cookie_base: "__Host-strongroom_session", transport: nil)
+    def initialize(endpoint:, issuer:, namespace:, org_id:, app_id:, cookie_base: "__Host-strongroom_session",
+      transport: nil, service_endpoint: nil, service_key: nil, service_transport: nil)
       @endpoint = NetHTTPTransport.endpoint(endpoint)
       unless issuer.is_a?(String) && issuer.match?(ISSUER)
         raise ConfigurationError, "explicit issuer URI required (stable binding identity, not the network endpoint)"
@@ -24,13 +33,30 @@ module Strongroom
       @org_id, @app_id = [org_id, app_id].map { |value| configured_uuid(value) }
       @cookie_name = "#{cookie_base}_#{@namespace}".freeze
       @transport = transport || NetHTTPTransport.new(endpoint: @endpoint)
-      unless serves_endpoint?(@transport)
+      unless serves_endpoint?(@transport, @endpoint)
         raise ConfigurationError, "transport endpoint does not match the client endpoint"
       end
+      configure_service(service_endpoint, service_key, service_transport)
       freeze
     end
 
-    def inspect = "#<Strongroom::Client issuer=#{issuer} endpoint=#{endpoint} namespace=#{namespace}>"
+    def inspect
+      service = service? ? " service_endpoint=#{service_endpoint}" : ""
+      "#<Strongroom::Client issuer=#{issuer} endpoint=#{endpoint}#{service} namespace=#{namespace}>"
+    end
+
+    def pretty_print(printer) = printer.text(inspect)
+
+    def encode_with(coder)
+      coder.map = {"issuer" => issuer, "endpoint" => endpoint, "namespace" => namespace}
+    end
+
+    def marshal_dump
+      raise TypeError, "clients must not be serialized"
+    end
+
+    # Whether this client can reach the namespace's service API.
+    def service? = !@service_key.nil?
 
     def login(identity:, password:, identity_kind: "email")
       unless [identity, password, identity_kind].all? { |value| value.is_a?(String) }
@@ -40,7 +66,7 @@ module Strongroom
       raise InvalidRequest, "login request too large" if body.bytesize > 16_384
       response = request(:post, "auth/login", body: body)
       issue(response) do |token|
-        declared = object(response, %w[session_id user_id expires_at])
+        declared = object(response, LOGIN)
         current = session(token: token)
         raise ProtocolError, "inconsistent authentication response" unless same_login?(declared, current)
         current
@@ -83,8 +109,81 @@ module Strongroom
       Subject.new(issuer: issuer, namespace: namespace, org_id: org_id, app_id: app_id, user_id: session.user_id)
     end
 
+    # Creates an account with an unverified email identity, keyed by your own
+    # `external_id`. Replaying the same external ID and identity returns the
+    # original receipt (`created: false`) and changes nothing.
+    def register(external_id:, identity:, password:)
+      unless [external_id, identity, password].all? { |value| value.is_a?(String) }
+        raise InvalidRequest, "registration fields must be strings"
+      end
+      body = JSON.generate(external_id: external_id, identity_kind: "email", identity: identity, password: password)
+      raise InvalidRequest, "registration request too large" if body.bytesize > 16_384
+      response = service_request(:post, "registrations", body: body, statuses: [200, 201])
+      values = object(response, {"user_id" => :uuid, "identity_id" => :uuid, "identity_state" => :string})
+      raise ProtocolError, "invalid registration response" unless IDENTITY_STATES.include?(values["identity_state"])
+      Registration.new(user_id: values["user_id"], identity_id: values["identity_id"],
+        identity_state: values["identity_state"], created: response.status == 201)
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid registration payload", cause: nil
+    end
+
+    # Withdraws a registration whose address was never verified: the account
+    # it created is deleted, and the address and external ID are free again.
+    def cancel_registration(external_id:)
+      raise InvalidRequest, "external_id must be a string" unless external_id.is_a?(String)
+      body = JSON.generate(external_id: external_id)
+      response = service_request(:post, "registrations/cancel", body: body, statuses: [200])
+      unless object(response, {"status" => :string})["status"] == "cancelled"
+        raise ProtocolError, "invalid service response"
+      end
+      nil
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid external_id", cause: nil
+    end
+
+    # A fresh verification link for `user_id`'s email identity; earlier links
+    # stop working. The browser confirms it: POST {"token"} to
+    # `/accounts/<namespace>/verify` on the kernel's public listener.
+    def issue_verification(user_id:)
+      raise InvalidRequest, "user_id must be a canonical UUID" unless canonical_uuid?(user_id)
+      response = service_request(:post, "verifications", body: JSON.generate(user_id: user_id), statuses: [201])
+      values = object(response, {"token" => :string, "expires_at" => :timestamp})
+      Verification.new(token: VerificationToken.new(values["token"]), expires_at: values["expires_at"])
+    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))) &&
+          limit.is_a?(Integer) && (1..500).cover?(limit)
+        raise InvalidRequest, "after: must be a feed cursor and limit: 1 to 500"
+      end
+      query = after ? "after=#{after}&limit=#{limit}" : "limit=#{limit}"
+      response = service_request(:get, "events?#{query}", statuses: [200])
+      page = parse(response)
+      unless page.is_a?(Hash) && page.keys.sort == %w[events next oldest_at] && page["events"].is_a?(Array) &&
+          (page["next"].nil? || (page["next"].is_a?(String) && page["next"].match?(CURSOR)))
+        raise ProtocolError, "invalid event feed"
+      end
+      EventPage.new(events: page["events"].map { |event| feed_event(event) }.freeze, next: page["next"]&.freeze,
+        oldest_at: page["oldest_at"]&.then { timestamp(it) })
+    end
+
     private
 
+    def configure_service(endpoint, key, transport)
+      if endpoint.nil? && key.nil? && transport.nil?
+        @service_endpoint = @service_key = @service_transport = nil
+        return
+      end
+      raise ConfigurationError, "service_endpoint: and service_key: go together" if endpoint.nil? || key.nil?
+      @service_endpoint = NetHTTPTransport.endpoint(endpoint)
+      @service_key = ServiceKey.new(key)
+      @service_transport = transport || NetHTTPTransport.new(endpoint: @service_endpoint)
+      unless serves_endpoint?(@service_transport, @service_endpoint)
+        raise ConfigurationError, "service transport endpoint does not match the service endpoint"
+      end
+    end
+
     def issue(response)
       token = issued_token(response)
       IssuedSession.new(session: yield(token), token: token)
@@ -95,7 +194,8 @@ module Strongroom
 
     def same_login?(declared, current)
       declared["session_id"] == current.session_id && declared["user_id"] == current.user_id &&
-        same_instant?(timestamp(declared["expires_at"]), current.expires_at)
+        declared["identity_verified"] == current.identity_verified &&
+        same_instant?(declared["expires_at"], current.expires_at)
     end
 
     def same_session?(declared, current)
@@ -116,7 +216,7 @@ module Strongroom
       raise ProtocolError, "invalid authentication response", cause: nil
     end
 
-    def serves_endpoint?(transport)
+    def serves_endpoint?(transport, endpoint)
       transport.respond_to?(:call) && transport.respond_to?(:endpoint) &&
         NetHTTPTransport.endpoint(transport.endpoint) == endpoint
     rescue ConfigurationError
@@ -140,9 +240,7 @@ module Strongroom
       headers["Content-Type"] = "application/json" if body
       headers["Authorization"] = "Bearer #{token.reveal}" if token
       response = @transport.call(method, "/accounts/#{namespace}/#{suffix}", headers: headers, body: body)
-      unless response.is_a?(TransportResponse) && response.body.bytesize <= NetHTTPTransport::MAX_RESPONSE_BYTES
-        raise ProtocolError, "invalid authentication response"
-      end
+      bounded!(response)
       case response.status
       when 401 then raise Unauthorized, "authentication failed"
       when 403 then raise ProtocolError, "authentication request refused by service policy"
@@ -150,13 +248,71 @@ module Strongroom
       when 503 then raise Busy.new(retry_after: retry_after(response))
       when 500..599 then raise Unavailable, "authentication service unavailable"
       end
+      expected!(response, [status])
+      raise ProtocolError, "unexpected logout body" if status == 204 && !response.body.empty?
+      response
+    end
+
+    # The namespace's service API: a server-to-server call with the service
+    # key, never a browser's. Kernel refusals become typed errors.
+    def service_request(method, suffix, statuses:, body: nil)
+      raise ConfigurationError, "no service_endpoint: or service_key: configured for #{namespace}" unless service?
+      headers = {"Accept" => "application/json", "Accept-Encoding" => "identity",
+                 "Cache-Control" => "no-store", SERVICE_KEY_HEADER => @service_key.reveal}
+      headers["Content-Type"] = "application/json" if body
+      response = @service_transport.call(method, "/accounts/#{namespace}/service/#{suffix}", headers: headers, body: body)
+      bounded!(response)
+      refused!(response) unless statuses.include?(response.status)
+      expected!(response, statuses)
+      response
+    end
+
+    def refused!(response)
+      case response.status
+      when 400 then raise InvalidRequest, "service request refused"
+      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 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 conflict!(response)
+      case service_error(response)&.fetch("error", nil)
+      when "identity_taken" then raise IdentityTaken, "identity already belongs to another account"
+      when "binding_conflict" then raise BindingConflict, "external_id is bound to a different identity"
+      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"
+      else raise ProtocolError, "invalid service response"
+      end
+    end
+
+    def service_error(response)
+      error = parse(response)
+      error if error.is_a?(Hash) && error.values.all?(String)
+    rescue ProtocolError
+      nil
+    end
+
+    def bounded!(response)
+      unless response.is_a?(TransportResponse) && response.body.bytesize <= NetHTTPTransport::MAX_RESPONSE_BYTES
+        raise ProtocolError, "invalid authentication response"
+      end
+    end
+
+    def expected!(response, statuses)
       cache = response.headers.fetch("cache-control", []).join(",").split(",").map(&:strip)
-      unless response.status == status && cache.include?("no-store") &&
+      unless statuses.include?(response.status) && cache.include?("no-store") &&
           response.headers.fetch("content-encoding", ["identity"]) == ["identity"]
         raise ProtocolError, "unexpected authentication response"
       end
-      raise ProtocolError, "unexpected logout body" if status == 204 && !response.body.empty?
-      response
     end
 
     def retry_after(response)
@@ -166,30 +322,65 @@ module Strongroom
       value if (1..86_400).cover?(value)
     end
 
-    def object(response, keys)
+    def parse(response)
       types = response.headers.fetch("content-type", [])
       unless types.length == 1 && types[0].split(";").first.to_s.strip.casecmp?("application/json")
         raise ProtocolError, "invalid authentication response"
       end
-      result = JSON.parse(response.body)
-      unless result.is_a?(Hash) && result.keys.sort == keys.sort && result.values.all? { |value| value.is_a?(String) }
-        raise ProtocolError, "invalid authentication response"
-      end
-      result
+      JSON.parse(response.body)
     rescue JSON::ParserError, EncodingError
       raise ProtocolError, "invalid authentication response", cause: nil
     end
 
+    # Exactly `schema`'s keys, each of its kind; timestamps parsed.
+    def object(response, schema)
+      result = parse(response)
+      unless result.is_a?(Hash) && result.keys.sort == schema.keys.sort &&
+          schema.all? { |key, kind| kind?(result[key], kind) }
+        raise ProtocolError, "invalid authentication response"
+      end
+      result.to_h { |key, value| [key, schema[key] == :timestamp ? timestamp(value) : value] }
+    end
+
+    def kind?(value, kind)
+      case kind
+      when :uuid then canonical_uuid?(value)
+      when :boolean then value == true || value == false
+      when :uuid_or_nil then value.nil? || canonical_uuid?(value)
+      else value.is_a?(String)
+      end
+    end
+
     def metadata(response)
-      values = object(response, %w[session_id user_id org_id app_id expires_at])
-      unless %w[session_id user_id org_id app_id].all? { |key| canonical_uuid?(values[key]) } &&
-          values["org_id"] == org_id && values["app_id"] == app_id
+      values = object(response, METADATA)
+      unless values["org_id"] == org_id && values["app_id"] == app_id
         raise ProtocolError, "unexpected session audience"
       end
-      expiry = timestamp(values.fetch("expires_at"))
+      expiry = values.fetch("expires_at")
       raise Unauthorized, "session expired" unless expiry > Time.now
       Session.new(session_id: values["session_id"].freeze, user_id: values["user_id"].freeze,
-                  org_id: org_id, app_id: app_id, expires_at: expiry)
+                  org_id: org_id, app_id: app_id, expires_at: expiry, identity_verified: values["identity_verified"])
+    end
+
+    EVENT = {"id" => :uuid, "type" => :string, "user_id" => :uuid_or_nil, "identity_id" => :uuid_or_nil,
+             "at" => :timestamp, "meta" => :meta}.freeze
+    private_constant :EVENT
+
+    def feed_event(event)
+      unless event.is_a?(Hash) && event.keys.sort == EVENT.keys.sort && EVENT_TYPES.include?(event["type"]) &&
+          event["meta"].is_a?(Hash) && EVENT.all? { |key, kind| kind == :meta || kind?(event[key], kind) }
+        raise ProtocolError, "invalid event feed"
+      end
+      Event.new(id: event["id"].freeze, type: event["type"].freeze, user_id: event["user_id"]&.freeze,
+        identity_id: event["identity_id"]&.freeze, at: timestamp(event["at"]), meta: deep_freeze(event["meta"]))
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.to_h { |key, item| [key.freeze, deep_freeze(item)] }.freeze
+      when Array then value.map { |item| deep_freeze(item) }.freeze
+      else value.freeze
+      end
     end
 
     def issued_token(response)

data/lib/strongroom/errors.rb

@@ -7,6 +7,30 @@ module Strongroom
   class Unauthorized < Error; end
   class ProtocolError < Error; end
   class Unavailable < Error; end
+  class NotFound < Error; end
+
+  # The service API refused a request that conflicts with stored state.
+  class Conflict < Error; end
+  class IdentityTaken < Conflict; end
+  class BindingConflict < Conflict; end
+  class AlreadyVerified < Conflict; end
+  class IdentityDisabled < 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
+
+  # A new password the kernel's policy refuses; `reason` is `too_short`,
+  # `too_long` or `invalid`. The password itself is never kept.
+  class InvalidPassword < InvalidRequest
+    REASONS = %w[too_short too_long invalid].freeze
+    attr_reader :reason
+
+    def initialize(reason:)
+      @reason = reason
+      super("password refused: #{reason}")
+    end
+  end
 
   class RateLimited < Error
     attr_reader :retry_after

data/lib/strongroom/rails/account.rb

@@ -20,12 +20,39 @@ module Strongroom
         raise ConfigurationError, "resolve must be callable (subject -> record or nil)" unless resolve.respond_to?(:call)
         raise ConfigurationError, "eligible must be callable (record -> true)" unless eligible.respond_to?(:call)
         raise ConfigurationError, "register must be true or false" unless [true, false].include?(register)
+        if register && !client.service?
+          raise ConfigurationError, "register: true needs a client with service_endpoint: and service_key:"
+        end
         @client, @model, @table = client, model, table.dup.freeze
         @resolver, @eligible, @register = resolve, eligible, register
         @cookie_name = "strongroom_#{client.namespace}".freeze
         freeze
       end
 
+      # Self-service registration through the kernel's service API. Only a
+      # namespace configured with `register: true` (here and in the kernel) may.
+      def register_account(external_id:, identity:, password:)
+        registering!
+        client.register(external_id: external_id, identity: identity, password: password)
+      end
+
+      # Withdraws a registration whose address was never verified.
+      def cancel_registration(external_id:)
+        registering!
+        client.cancel_registration(external_id: external_id)
+      end
+
+      # A fresh verification link for a registered user's email identity.
+      def issue_verification(user_id:)
+        registering!
+        client.issue_verification(user_id: user_id)
+      end
+
+      # The namespace's event feed; needs only the service key.
+      def events(after: nil, limit: 100)
+        client.events(after: after, limit: limit)
+      end
+
       def resolve(session)
         subject = client.subject(session)
         record = @resolver.call(subject)
@@ -38,6 +65,12 @@ module Strongroom
       rescue StandardError
         raise Unavailable, "local principal lookup unavailable", cause: nil
       end
+
+      private
+
+      def registering!
+        raise ConfigurationError, "registration is not enabled for #{client.namespace} (register: false)" unless register
+      end
     end
   end
 end

data/lib/strongroom/rails/railtie.rb

@@ -8,7 +8,15 @@ module Strongroom
 
       config.action_dispatch.rescue_responses.merge!(
         "Strongroom::InvalidRequest" => :bad_request,
+        "Strongroom::InvalidPassword" => :unprocessable_entity,
         "Strongroom::Unauthorized" => :unauthorized,
+        "Strongroom::NotFound" => :not_found,
+        "Strongroom::Conflict" => :conflict,
+        "Strongroom::IdentityTaken" => :conflict,
+        "Strongroom::BindingConflict" => :conflict,
+        "Strongroom::AlreadyVerified" => :conflict,
+        "Strongroom::IdentityDisabled" => :conflict,
+        "Strongroom::CursorAhead" => :conflict,
         "Strongroom::RateLimited" => :too_many_requests,
         "Strongroom::Busy" => :service_unavailable,
         "Strongroom::ProtocolError" => :service_unavailable,
@@ -16,7 +24,8 @@ module Strongroom
       )
 
       initializer "strongroom.filter_credentials" do |app|
-        app.config.filter_parameters |= %i[password password_confirmation identity authorization cookie strongroom_token]
+        app.config.filter_parameters |= %i[password password_confirmation identity authorization cookie strongroom_token
+          service_key verification_token]
       end
 
       config.after_initialize do |app|

data/lib/strongroom/rails/version.rb

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

data/lib/strongroom/session.rb

@@ -3,9 +3,24 @@
 require "time"
 
 module Strongroom
-  Session = Data.define(:session_id, :user_id, :org_id, :app_id, :expires_at)
+  Session = Data.define(:session_id, :user_id, :org_id, :app_id, :expires_at, :identity_verified)
   Subject = Data.define(:issuer, :namespace, :org_id, :app_id, :user_id)
 
+  # A registration's receipt. `created` is false for an exact replay, which
+  # changed nothing; `identity_state` is the identity's current state.
+  Registration = Data.define(:user_id, :identity_id, :identity_state, :created)
+
+  # 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)
+
+  # A page of the feed. `next` is the cursor after its last event, or nil when
+  # the page is empty: keep the previous cursor and ask again later.
+  # `oldest_at` is when the oldest event the feed still holds happened (nil if
+  # none): retention prunes from there, so a consumer whose last event is older
+  # has lost the events in between.
+  EventPage = Data.define(:events, :next, :oldest_at)
+
   class IssuedSession
     attr_reader :session, :token
 
@@ -21,4 +36,28 @@ module Strongroom
       raise TypeError, "issued credentials must not be serialized"
     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
+  # or serialize.
+  class Verification
+    attr_reader :token, :expires_at
+
+    def initialize(token:, expires_at:)
+      @token, @expires_at = token, expires_at
+      freeze
+    end
+
+    def inspect = "#<Strongroom::Verification 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"
+    end
+
+    def marshal_dump
+      raise TypeError, "verification links must not be serialized"
+    end
+  end
 end

data/lib/strongroom/token.rb

@@ -3,24 +3,29 @@
 require "base64"
 
 module Strongroom
-  class Token
+  # A kernel secret: a fixed prefix and 32 random bytes in canonical unpadded
+  # base64url. Redacted everywhere; never JSON, YAML or Marshal payloads.
+  class Credential
+    def self.prefix = raise(NotImplementedError, "#{self} has no wire prefix")
+    def self.refusal = [Unauthorized, "invalid credential"]
+
     def initialize(value)
-      unless value.is_a?(String) && value.bytesize == 47 && value.match?(/\Asr1_[A-Za-z0-9_-]{43}\z/)
-        raise Unauthorized, "invalid session credential", cause: nil
+      prefix = self.class.prefix
+      unless value.is_a?(String) && value.bytesize == prefix.bytesize + 43 && value.start_with?(prefix) &&
+          value.byteslice(prefix.bytesize..).match?(/\A[A-Za-z0-9_-]{43}\z/)
+        refuse
       end
-      encoded = value.delete_prefix("sr1_")
+      encoded = value.delete_prefix(prefix)
       decoded = Base64.urlsafe_decode64(encoded)
-      unless decoded.bytesize == 32 && Base64.urlsafe_encode64(decoded, padding: false) == encoded
-        raise Unauthorized, "invalid session credential", cause: nil
-      end
+      refuse unless decoded.bytesize == 32 && Base64.urlsafe_encode64(decoded, padding: false) == encoded
       @wire = value.dup.freeze
       freeze
     rescue ArgumentError
-      raise Unauthorized, "invalid session credential", cause: nil
+      refuse
     end
 
     def reveal = @wire
-    def inspect = "#<Strongroom::Token [FILTERED]>"
+    def inspect = "#<#{self.class.name} [FILTERED]>"
     alias to_s inspect
     def as_json(*) = "[FILTERED]"
     def pretty_print(printer) = printer.text(inspect)
@@ -30,13 +35,26 @@ module Strongroom
     end
 
     def init_with(_coder)
-      raise TypeError, "session tokens must not be deserialized"
+      raise TypeError, "credentials must not be deserialized"
     end
 
     def _dump(_depth)
-      raise TypeError, "session tokens must not be serialized"
+      raise TypeError, "credentials must not be serialized"
     end
 
+    private
+
+    def refuse
+      error, message = self.class.refusal
+      raise error, message, cause: nil
+    end
+  end
+
+  # A session bearer token, `sr1_...`.
+  class Token < Credential
+    def self.prefix = "sr1_"
+    def self.refusal = [Unauthorized, "invalid session credential"]
+
     def self.coerce(value)
       value.is_a?(self) ? value : new(value)
     end
@@ -50,4 +68,22 @@ module Strongroom
       nil
     end
   end
+
+  # A verification link's secret, `srv1_...`: mail it, never log it.
+  class VerificationToken < Credential
+    def self.prefix = "srv1_"
+    def self.refusal = [ProtocolError, "invalid verification token"]
+  end
+
+  # A namespace's service key, `srk1_...`, sent only to the service listener.
+  class ServiceKey < Credential
+    def self.prefix = "srk1_"
+    def self.refusal = [ConfigurationError, "service_key: must be srk1_ followed by 43 base64url characters"]
+
+    def initialize(value)
+      super
+      # Every byte the same is a placeholder, as the kernel refuses too.
+      refuse if Base64.urlsafe_decode64(@wire.delete_prefix("srk1_")).bytes.uniq.size == 1
+    end
+  end
 end

metadata

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