strongroom-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d266097d730b4561dc0e197cbfb8cb6811626b1cfea5defd21b7f018f0e39ed0
+  data.tar.gz: efc7b6166160438836119409e1c836179daa40b33913dbe4f6a9464eff9f53d3
+SHA512:
+  metadata.gz: d9200dd2cdf23a5822286500ee92e35c254d824a2d910c8039df5bfdab0f05402a51ed2dc6e601a7069db72584353d0e8a05681d2ff4b223b4040cd15f8ab6fe
+  data.tar.gz: c109f7251482e29b24b2349ff5cce04958207eaca352d90d5a7b0311d38ca0abc7e55a763e5ec7f25309b323ee092ae8b3e6b415ac675322803e12da3cc5727b

data/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Seuros
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,415 @@
+# strongroom-rails — existing-user login 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
+are deliberately absent.
+
+> **Status: pre-production.** Strongroom has not been audited and is not approved
+> for production traffic or real credential imports.
+
+Requires Ruby **4.0+** and Rails **8.1+** (currently Rails 8.x).
+
+## What ships
+
+- [x] Namespace-bound login, canonical session lookup, explicit rotation and logout.
+- [x] HTTPS transport (HTTP only on literal loopback/localhost), no redirects,
+  environment proxies or automatic retries. Per-I/O timeouts, a monotonic
+  whole-call `deadline:` (default 15 s; every socket read, headers included, is
+  clamped to the remaining budget) and a 64 KiB response bound.
+- [x] Optional keep-alive and per-request memoization (see below).
+- [x] Strict token/cookie/metadata parsing. Login confirms `/me` audience and metadata
+  before returning an authenticated session; a session issued but not confirmed
+  is revoked before the error is raised. Expiry is compared at microsecond
+  precision (strongroomd reports nanoseconds at login, PostgreSQL stores microseconds).
+  Raw tokens are not JSON, YAML or Marshal payloads.
+- [x] Explicit Rails helpers, Secure/HttpOnly/SameSite=Lax encrypted cookies,
+  mandatory mutation intent (Rails CSRF on `ActionController::Base`, the
+  `X-Strongroom-Request` marker plus Origin policy on `ActionController::API`),
+  strict HTTP verbs and no-store responses varying on Cookie/Authorization.
+- [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.
+
+It never finds users by email, creates local accounts, dynamically constantizes
+table names, overrides `current_user`, installs routes or falls back to legacy
+authentication after a denial/timeout.
+
+## Wiring an application
+
+```ruby
+gem "strongroom-rails", require: "strongroom/rails"
+```
+
+The kernel must be configured for the corresponding named accounts
+(`[accounts.<name>]`, see the [configuration reference](https://github.com/seuros/strongroom#accountsname)).
+Configure existing Strongroom org/app IDs, not Rails IDs.
+Use separate namespaces/bindings for users and admins; naming a namespace
+`admin` does not implement MFA or authorize an admin migration.
+
+Build the registry in a Rails initializer's `to_prepare` block so reloadable
+model classes are resolved afresh. This example deliberately leaves your
+binding storage and eligibility policy explicit:
+
+```ruby
+Rails.application.config.to_prepare do
+  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")
+  )
+
+  users = Strongroom::Rails::Account.new(
+    client: client, table: "users", model: User,
+    # Your store must uniquely bind issuer + namespace + org + app + kernel
+    # user_id to a pre-existing local record. Missing binding returns nil.
+    resolve: ->(subject) { YourTrustedBindingStore.lookup(subject)&.record },
+    # Implement this explicitly: active, confirmed, password-only, enrolled
+    # in the migrated cohort, and authoritative credential/account state.
+    eligible: ->(record) { YourLoginCohortPolicy.allowed?(record) },
+    register: false
+  )
+
+  Rails.application.config.x.strongroom_accounts = Strongroom::Rails::Registry.new(users)
+end
+```
+
+`issuer:` is the stable identity your bindings are keyed by; it is never derived
+from `endpoint:` (the network address), so moving strongroomd to another host or port
+does not orphan existing bindings. Use an absolute URI (`https://...` or `urn:...`)
+and never change it once bindings exist. A custom `transport:` must report the
+same `endpoint` as the client.
+
+`YourTrustedBindingStore` and `YourLoginCohortPolicy` are intentional placeholders,
+not supplied models or a default policy. The resolver receives a frozen,
+secret-free `Strongroom::Subject` with `issuer`, `namespace`, `org_id`, `app_id`,
+`user_id`; it receives no email, password, local ID or bearer token.
+Binding creation/import needs a trusted, collision-rejecting workflow and a
+database uniqueness constraint. Never use a browser-supplied local ID or email
+as linking authority. Resolver exceptions become service failures, not fallback.
+Eligibility must return exactly `true` to authorize a record.
+
+The Railtie verifies this at boot (after `to_prepare` blocks run, and again on
+every code reload): a missing or wrong-typed `config.x.strongroom_accounts`, or an
+app without `ActionDispatch::Cookies` middleware, stops the boot with a specific
+`Strongroom::ConfigurationError` instead of failing on the first request. Account
+and registry errors name the offending setting. Processes that never
+authenticate (for example an asset build without credentials) can opt out with
+`config.strongroom.verify_on_boot = false`.
+
+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.
+
+Controllers opt in explicitly and keep their own frontend response contract:
+
+```ruby
+class Authentication::SessionsController < ApplicationController
+  include Strongroom::Rails::Authentication
+  protect_from_forgery with: :exception
+  rate_limit to: 10, within: 3.minutes, by: -> { request.remote_ip }, only: :create
+
+  rescue_from Strongroom::Unauthorized do
+    head :unauthorized
+  end
+  rescue_from Strongroom::Unavailable, Strongroom::ProtocolError do
+    head :service_unavailable
+  end
+  rescue_from Strongroom::RateLimited do |error|
+    response.set_header("Retry-After", error.retry_after.to_s) if error.retry_after
+    head(error.is_a?(Strongroom::Busy) ? :service_unavailable : :too_many_requests)
+  end
+
+  def create # POST; preserve your approved route/serializer.
+    user = strongroom_login(namespace: :users, identity_kind: "email",
+                        identity: params.require(:email), password: params.require(:password))
+    render json: {id: user.id}
+  end
+
+  def show # GET; checks canonical session and local eligibility every time.
+    user = strongroom_current_account(namespace: :users)
+    user ? render(json: {id: user.id}) : head(:unauthorized)
+  end
+
+  def destroy # DELETE; verified CSRF required, including absent/invalid credentials.
+    strongroom_logout(namespace: :users)
+    head :no_content
+  end
+end
+```
+
+**Add your own per-IP rate limit before `strongroom_login`.** Rails is strongroomd's
+only client, so every login reaches strongroomd from the Rails server's address:
+strongroomd's global and per-identity budgets cannot tell one abusive client from
+all your users, and a single client can drain the global budget (locking
+everyone out) or spray many identities. Rails 8's `rate_limit` (above) refuses
+excess attempts before any upstream call. Behind a load balancer, configure
+`config.action_dispatch.trusted_proxies` so `request.remote_ip` is the client,
+and use a cache store shared by all app instances (the limiter's counters live
+in `cache_store`). Keep the limit on every action that calls `strongroom_login`.
+
+`strongroom_rotate(namespace: :users)` is an explicit POST helper returning the
+validated local record and replacing the encrypted cookie. GET lookup never
+calls rotation or writes/deletes an authentication cookie.
+
+### Mutation intent: `ActionController::Base` vs `ActionController::API`
+
+On controllers with Rails forgery protection (`ActionController::Base`), login,
+rotation and logout require a verified Rails CSRF token; the helpers refuse
+mutations if protection is disabled or unverified, even with the intent header.
+
+`ActionController::API` has no forgery protection, so the concern applies the
+same policy strongroomd enforces instead:
+
+- exactly one `X-Strongroom-Request: 1` header (the kernel's intent marker; HTML
+  forms cannot set it, and cross-origin `fetch` must pass a CORS preflight);
+- if `Origin` is present it must equal the app's own origin (`request.base_url`)
+  or be listed with `strongroom_trust_origins`; `null` and unlisted origins are refused;
+- browser requests carrying Fetch Metadata (`Sec-Fetch-Site`) without `Origin`
+  are refused. Requests with neither header (server-to-server) need only the marker.
+
+```ruby
+class Api::SessionsController < ActionController::API
+  include Strongroom::Rails::Authentication
+  strongroom_trust_origins "https://dashboard.example.com", "https://admin.example.com"
+end
+```
+
+Trusted origins are exact canonical origins (HTTPS; HTTP only on loopback), no
+wildcards. An API-mode app must also provide:
+
+- `config.middleware.use ActionDispatch::Cookies` (absent by default in
+  `api_only` apps); the helpers read and write the encrypted cookie through
+  `request.cookie_jar`, so `ActionController::Cookies` is optional;
+- a CORS policy that allows `X-Strongroom-Request` with `credentials: true` only for
+  those same origins, and never reflects arbitrary origins;
+- frontends that send `credentials: "include"` and the header on every mutation;
+- HTTPS and a cookie scope that fits the deployment (Secure, SameSite=Lax:
+  same-site subdomains work, cross-site frontends do not).
+
+Refusals raise `ActionController::InvalidAuthenticityToken` (422) on both paths.
+The Railtie maps `Strongroom::InvalidRequest` to 400, `Unauthorized` to 401,
+`RateLimited` to 429 and `Busy`/`ProtocolError`/`Unavailable` to 503 for
+controllers that do not `rescue_from` them.
+
+### Request resolver and Warden
+
+`Strongroom::Rails::Resolver.new(request)` accepts an `ActionDispatch::Request`,
+a `Rack::Request` or a Rack env and answers narrow questions with the same
+precedence as the helpers (any `Authorization` header suppresses the cookie):
+
+```ruby
+resolver = Strongroom::Rails::Resolver.new(request)
+resolver.subject(:users)  # Strongroom::Subject or nil (canonical, no local binding)
+resolver.account(:users)  # eligible local record or nil
+```
+
+Service failures raise; they never become `nil`. If Warden is loaded when the
+app finishes booting, the gem registers `Strongroom::Rails::WardenStrategy` as
+`:strongroom` (or `require "strongroom/rails/warden_strategy"` explicitly). Map Warden
+scopes to namespaces in the registry:
+
+```ruby
+Strongroom::Rails::Registry.new(users, admins, warden_scopes: {user: :users, admin: :admin})
+
+warden.authenticate(:strongroom, :jwt, scope: :user)
+```
+
+Unmapped scopes fall back to a namespace of the same name. The strategy is only
+`valid?` when the credential selected by precedence is a Strongroom token, so a
+request still carrying a legacy `Bearer <JWT>` falls through to the next
+strategy. A Strongroom credential that is refused halts the chain (`fail!`): there
+is no fallback to another strategy after a Strongroom denial or outage. The
+strategy never stores the user in the Rack session (`store?` is false), so every
+request is checked against strongroomd and local eligibility. If you keep
+`warden-jwt_auth`, remove migrated routes from its `dispatch_requests`, or it
+will mint a JWT for a user Warden authenticated through Strongroom.
+
+Browser cookie names are `strongroom_users`, `strongroom_admin`, etc. They contain a
+Rails-encrypted token, never a local user ID or a JWT. Secure is always enabled:
+serve the Rails app over HTTPS, including in browser development. The upstream
+cookie base defaults to `__Host-strongroom_session`, the kernel's default
+`[cookies] name`; set `cookie_base:` to the kernel's configured name when it
+differs. Upstream Set-Cookie attributes are never relayed.
+
+For lookups and rotation, if Authorization is present it must be a canonical
+Strongroom Bearer token; invalid, empty or coalesced headers suppress cookie
+fallback. This does **not** accept legacy application JWTs. Every valid credential
+is checked against the configured namespace endpoint/audience; the registry
+never selects a realm from JWT claims.
+
+No successful browser cookie is issued until remote authentication, audience
+verification, trusted mapping and local eligibility all succeed. Mapping failures
+after issuance revoke the new session upstream on a best-effort basis; the
+original error (for example the 401 for an ineligible user) is always the one
+raised, and a session that could not be revoked was never delivered and expires
+at its TTL. No automatic retry is safe after an ambiguous login/rotation outcome.
+
+Logout revokes every Strongroom credential the request carries: the Bearer token
+and the cookie's token, even when the Authorization header is foreign (a SPA
+still sending `Bearer <JWT>`). It never reports success for a credential it did
+not revoke: an upstream failure keeps the cookie and raises, and a request
+whose only credential is a foreign Authorization header gets `Unauthorized`.
+A request with no credentials at all is an idempotent no-op.
+
+strongroomd answers 403 when its intent/Origin policy refuses the Rails server
+itself; that is a deployment misconfiguration, so it raises `ProtocolError`
+(503), never `Unauthorized`.
+
+### Connection reuse and per-request memoization
+
+Within one request, session lookup and local resolution run once per namespace:
+the helpers, `Resolver` and the Warden strategy share a memo stored in the Rack
+env. `strongroom_login`, `strongroom_rotate` and `strongroom_logout` clear it, so a lookup
+after a mutation in the same request sees the new state. Nothing is cached
+across requests.
+
+By default every call opens and closes its own connection. To reuse TLS
+connections, pass a keep-alive transport:
+
+```ruby
+transport = Strongroom::NetHTTPTransport.new(endpoint: ENV.fetch("STRONGROOM_ENDPOINT"), keep_alive: true)
+Strongroom::Client.new(endpoint: ENV.fetch("STRONGROOM_ENDPOINT"), issuer: "https://auth.example.com",
+                   namespace: "users", org_id: ..., app_id: ..., transport: transport)
+```
+
+Each in-flight call checks out its own connection (threads and fibers never share
+one); up to `max_idle:` (default 4) idle connections are kept and dropped after
+`keep_alive_timeout:` (default 2 s) of idleness. A connection that failed, timed
+out or was cut short is never reused. Retries stay disabled: a request that was
+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.
+
+## Running the daemon
+
+This gem is only the client: it ships no binary and needs none to install. The
+daemon comes separately, and the two meet over HTTP:
+
+- The [`strongroomd`](https://rubygems.org/gems/strongroomd) gem: platform gems
+  bundle `strongroomd` and `strongroom-admin`, checked against a SHA-256 manifest
+  before they run.
+
+  ```ruby
+  gem "strongroomd"
+  ```
+
+  ```sh
+  bundle exec strongroom-admin migrate
+  bundle exec strongroomd
+  ```
+
+- The crate: `cargo install strongroomd --locked`.
+- A source build: `cargo build --release --locked -p strongroomd` at the repository root.
+
+The two gems are versioned separately.
+
+## Security / rollout boundaries
+
+- 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.
+- 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.
+- 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.
+- No process-wide principal cache is used. Resolver/eligibility callbacks must
+  query fresh authoritative state; do not cache past disablement/MFA changes.
+- Tokens have explicit `reveal`, redacted inspection/JSON and no Marshal support.
+  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,
+  remote admin operations, deployment SLOs and production approval are not shipped.
+
+## Local checks (no installs, network or database required)
+
+Tests use `padded_cell` 0.2 with Minitest 6. With compatible gems already installed:
+
+```sh
+rake test
+# With a resolved bundle:
+bundle exec rake test
+# Direct runner, e.g. to choose a seed:
+bundle exec ruby -Ilib:test -S padded_cell -j 2 --timeout 30 --seed 1981
+```
+
+The Rake task uses two workers, fork-per-test isolation and a 30-second timeout.
+Timing data under `tmp/padded_cell/` is ignored by Git.
+
+Tests use a mock upstream protocol and real in-memory Rails/Rack requests with
+synthetic local records (Base and API controllers, Warden). The transport is
+tested against real loopback servers: plain HTTP, a self-signed TLS certificate
+generated per test, trickled responses, oversized bodies, redirects, ignored
+environment proxies, keep-alive reuse and fork safety. Boot validation is tested
+by booting fresh Rails processes. They do not prove the Rust scoped SQL,
+actual PostgreSQL bindings or an existing application's routes or cutover.
+The separate Rust/PostgreSQL regressions do not exercise this gem.
+
+Package locally:
+
+```sh
+rake gem:build   # pkg/strongroom-rails-<version>.gem
+rake gems:push   # pull the strongroom-rails-v<version> GitHub release, verify it, push to RubyGems
+```
+
+## Packaged consumer check
+
+```sh
+rake test:package
+```
+
+Builds and verifies a fresh `.gem`, installs it only in an owned temporary gem
+home, and resolves a separate consumer bundle with `bundle lock --local`.
+Runs the ordinary suite plus an installed-entry-point check using `padded_cell`.
+
+The runner's working directory is the temporary consumer, not this checkout:
+`padded_cell` normally adds the current project's `lib/` to its load path. An
+explicit assertion checks that client and Rails code came from the installed
+archive, not the source tree. No dependency downloads or global installs.
+Temporary package, bundle, timing files and gem home are removed afterward.
+
+## Real backend check
+
+The opt-in harness is `integration/run.rb`; ordinary `rake test` does not load it.
+It needs the development-only `pg` gem and an explicitly supplied **disposable**
+PostgreSQL 18+ database. No database URL is inferred from the app or production
+environment.
+
+Build both real binaries first (`cargo build --release --locked -p strongroomd` at the
+repository root). From this gem directory, with disposable PostgreSQL running:
+
+```sh
+STRONGROOM_TEST_DATABASE_URL="$DISPOSABLE_DATABASE_URL" rake test:integration
+```
+
+`STRONGROOM_TEST_BIN_DIR` can override the default repository `target/release`
+directory; it may also name the RubyGems launchers of an installed `strongroomd` platform gem
+(`$(ruby -e 'print Gem.bindir')`). The harness:
+
+- Migrates a unique schema with the actual `strongroom-admin migrate`, then starts
+  the actual public binary on loopback with a private config, the kernel's default
+  `__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.
+  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,
+  wrong passwords, the identity rate limit and canonical logout. Login and `/me`
+  must report the same stored microsecond expiry, which only a nanosecond host
+  clock (Linux) can contradict.
+- 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.
+- 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.
+
+Offline consumer checks are not a successful real-backend lifecycle; this
+harness is the end-to-end gate.

data/lib/strongroom/client.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Strongroom
+  class Client
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+    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
+
+    def initialize(endpoint:, issuer:, namespace:, org_id:, app_id:, cookie_base: "__Host-strongroom_session", 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)"
+      end
+      @issuer = issuer.dup.freeze
+      @namespace = namespace.to_s.dup.freeze
+      unless @namespace.match?(/\A[a-z][a-z0-9_]{0,31}\z/) &&
+          cookie_base.is_a?(String) && cookie_base.match?(/\A[A-Za-z0-9_.-]{1,128}\z/)
+        raise ConfigurationError, "invalid account namespace or cookie base"
+      end
+      @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)
+        raise ConfigurationError, "transport endpoint does not match the client endpoint"
+      end
+      freeze
+    end
+
+    def inspect = "#<Strongroom::Client issuer=#{issuer} endpoint=#{endpoint} namespace=#{namespace}>"
+
+    def login(identity:, password:, identity_kind: "email")
+      unless [identity, password, identity_kind].all? { |value| value.is_a?(String) }
+        raise InvalidRequest, "credentials must be strings"
+      end
+      body = JSON.generate(identity_kind: identity_kind, identity: identity, password: password)
+      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])
+        current = session(token: token)
+        raise ProtocolError, "inconsistent authentication response" unless same_login?(declared, current)
+        current
+      end
+    rescue JSON::GeneratorError
+      raise InvalidRequest, "invalid login payload", cause: nil
+    end
+
+    def session(token:)
+      metadata(request(:get, "me", token: Token.coerce(token)))
+    end
+
+    def rotate(token:)
+      response = request(:post, "auth/rotate", token: Token.coerce(token))
+      issue(response) do |successor|
+        declared = metadata(response)
+        current = session(token: successor)
+        raise ProtocolError, "inconsistent rotation response" unless same_session?(declared, current)
+        current
+      end
+    end
+
+    def logout(token:)
+      request(:delete, "auth/logout", token: Token.coerce(token), status: 204)
+      nil
+    end
+
+    def discard(token:)
+      logout(token: token)
+      true
+    rescue Error
+      false
+    end
+
+    def subject(session)
+      unless session.is_a?(Session) && session.org_id == org_id && session.app_id == app_id &&
+          session.expires_at > Time.now
+        raise Unauthorized, "authentication failed"
+      end
+      Subject.new(issuer: issuer, namespace: namespace, org_id: org_id, app_id: app_id, user_id: session.user_id)
+    end
+
+    private
+
+    def issue(response)
+      token = issued_token(response)
+      IssuedSession.new(session: yield(token), token: token)
+    rescue Error => error
+      discard(token: token) if token
+      raise error
+    end
+
+    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)
+    end
+
+    def same_session?(declared, current)
+      declared.to_h.except(:expires_at) == current.to_h.except(:expires_at) &&
+        same_instant?(declared.expires_at, current.expires_at)
+    end
+
+    def same_instant?(left, right)
+      (left.to_r - right.to_r).abs < MICROSECOND
+    end
+
+    def timestamp(stamp)
+      unless stamp.is_a?(String) && stamp.match?(TIMESTAMP)
+        raise ProtocolError, "invalid authentication response"
+      end
+      Time.iso8601(stamp).freeze
+    rescue ArgumentError
+      raise ProtocolError, "invalid authentication response", cause: nil
+    end
+
+    def serves_endpoint?(transport)
+      transport.respond_to?(:call) && transport.respond_to?(:endpoint) &&
+        NetHTTPTransport.endpoint(transport.endpoint) == endpoint
+    rescue ConfigurationError
+      false
+    end
+
+    def configured_uuid(value)
+      unless canonical_uuid?(value)
+        raise ConfigurationError, "explicit canonical org/app UUIDs required"
+      end
+      value.dup.freeze
+    end
+
+    def canonical_uuid?(value)
+      value.is_a?(String) && value.match?(UUID) && value != "00000000-0000-0000-0000-000000000000"
+    end
+
+    def request(method, suffix, token: nil, body: nil, status: 200)
+      headers = {"Accept" => "application/json", "Accept-Encoding" => "identity",
+                 "Cache-Control" => "no-store", "X-Strongroom-Request" => "1"}
+      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
+      case response.status
+      when 401 then raise Unauthorized, "authentication failed"
+      when 403 then raise ProtocolError, "authentication request refused by service policy"
+      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
+      cache = response.headers.fetch("cache-control", []).join(",").split(",").map(&:strip)
+      unless response.status == 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)
+      values = response.headers.fetch("retry-after", [])
+      return unless values.length == 1 && values[0].match?(/\A[0-9]{1,5}\z/)
+      value = Integer(values[0], 10)
+      value if (1..86_400).cover?(value)
+    end
+
+    def object(response, keys)
+      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
+    rescue JSON::ParserError, EncodingError
+      raise ProtocolError, "invalid authentication response", cause: nil
+    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
+        raise ProtocolError, "unexpected session audience"
+      end
+      expiry = timestamp(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)
+    end
+
+    def issued_token(response)
+      matches = response.headers.fetch("set-cookie", []).filter_map do |cookie|
+        pair = cookie.split(";", 2).first
+        name, value = pair.to_s.split("=", 2)
+        value if name == cookie_name
+      end
+      raise ProtocolError, "ambiguous session cookie" unless matches.length == 1
+      Token.new(matches[0])
+    rescue Unauthorized
+      raise ProtocolError, "invalid issued credential", cause: nil
+    end
+  end
+end