torii-backend 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69b936da488f917cf7110687e96fa696678e689e75e82bd209ea829a26ffc73d
+  data.tar.gz: ce1f78461f54b62eed2a7f926a0aab7d427bef3b6d101ab6c44331da262a0680
+SHA512:
+  metadata.gz: 4a9f56628fc8f49fae8667c8f11d716189853daa1a87bc6b839c93dd75c496ded4a8c47340c3ff682c67ce31eb62c3a775872468bb4538463e74dbf04f0d3bfe
+  data.tar.gz: 3eab77aaa2315b52295d8ca1bc895d87c44c8569879b45a4183c614c9949c3202da11efb83b16705866ad03f71d5aa44d8117f5c387d2793d1221c5df0cca12e

data/README.md

@@ -0,0 +1,120 @@
+# torii-backend (Ruby)
+
+Backend SDK for [torii](https://torii.so) — verify end-user JWTs without a per-request round trip and manage users from your Ruby server.
+
+> **v0.x — API may still change.**
+
+## Setup
+
+1. Sign in to [app.torii.so](https://app.torii.so) and from your dashboard copy:
+   - your **issuer URL** (e.g. `https://acme.torii.so`)
+   - a **secret key** (`sk_test_…` for development, `sk_live_…` for production)
+
+2. Install the gem:
+
+   ```sh
+   gem install torii-backend
+   ```
+
+   or in your `Gemfile`:
+
+   ```ruby
+   gem 'torii-backend'
+   ```
+
+   Requires Ruby 3.1+.
+
+3. Verify an end-user JWT:
+
+   ```ruby
+   require 'torii/backend'
+
+   auth = Torii::Backend.verify_token(token, issuer: 'https://acme.torii.so')
+   auth.user_id          # => "user_abc"
+   auth.environment_id   # => "env_xyz"
+   auth.email_verified   # => true
+   ```
+
+   The first call fetches the issuer's JWKS at `{issuer}/_torii/.well-known/jwks.json`; subsequent calls reuse a process-wide cache (5-minute TTL, automatic refresh on `kid` miss). ES256 only.
+
+4. Call the backend REST API:
+
+   ```ruby
+   torii = Torii::Backend::Client.new(secret_key: ENV.fetch('TORII_SECRET_KEY'))
+   user = torii.users.get(user_id)
+   ```
+
+   Default base URL is `https://api.torii.so`. Override with `api_url:` for staging or self-hosted.
+
+## Rack middleware (Rails / Sinatra / Roda)
+
+```ruby
+# config/application.rb (Rails)
+config.middleware.use Torii::Backend::Rack::RequireAuth,
+  issuer: 'https://acme.torii.so'
+```
+
+```ruby
+# config.ru (Sinatra / plain Rack)
+use Torii::Backend::Rack::RequireAuth, issuer: 'https://acme.torii.so'
+run MyApp
+```
+
+On success the verified `Torii::Backend::Auth` is placed at `env['torii.auth']`. On failure the middleware short-circuits with a `401` JSON body:
+
+```json
+{ "error": { "code": "authentication_failed", "message": "..." } }
+```
+
+For ad-hoc verification outside Rack:
+
+```ruby
+auth = Torii::Backend.authenticate_request(
+  request.env,
+  issuer: 'https://acme.torii.so',
+)
+```
+
+`authenticate_request` accepts a Rack `env`, a plain `Hash` of headers (string or symbol keys), or anything that responds to `#each` with `[name, value]` pairs.
+
+## Backend API (REST client)
+
+```ruby
+page = torii.users.list(limit: 50)
+page[:items]        # => [{ id: "...", ... }, ...]
+page[:next_cursor]  # => "cursor_..." or nil
+page[:has_more]     # => true / false
+
+user = torii.users.create(email: 'x@y.com')
+torii.users.update(user[:id], name: Torii::Backend::Patch.set('New name'))
+torii.users.ban(user[:id])
+
+sessions = torii.sessions.list_for_user(user[:id])
+torii.sessions.revoke_all_for_user(user[:id])
+```
+
+The REST client is generated from the OpenAPI spec at `spec/server-v1.json` via [openapi-generator-cli](https://openapi-generator.tech/) (target: `ruby`); hand-written wrappers in `lib/torii/backend/client.rb` give it the Ruby-idiomatic surface above.
+
+### Partial updates
+
+PATCH fields are tri-state: set to a value, clear (JSON null on the wire), or leave alone. Ruby keyword args can't express that on their own (a literal `nil` can't be told apart from "absent"), so every kwarg accepted by `update` must be wrapped in `Torii::Backend::Patch`:
+
+```ruby
+torii.users.update(user_id,
+  name: Torii::Backend::Patch.set('New name'),  # update the name
+  phone: Torii::Backend::Patch.set(nil),        # null on the wire
+  # locale, address, date_of_birth omitted -> untouched
+)
+```
+
+`Patch.set(value)` updates the field; `Patch.set(nil)` clears it; omitted kwargs are left untouched on the server.
+
+## Errors
+
+* `Torii::Backend::Error` — base.
+* `Torii::Backend::AuthError` — raised by `verify_token` / `authenticate_request`.
+* `Torii::Backend::ApiError` — raised by REST calls on non-2xx. Inspect `status`, `code`, `support_id`, `body`.
+
+## License
+
+MIT

data/spec/server-v1.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:52334","description":"Generated server url"}],"tags":[{"name":"Server Users","description":"Server user management endpoints (secret key auth)"},{"name":"Server Sessions","description":"Server session management endpoints (secret key auth)"}],"paths":{"/api/server/v1/users":{"post":{"tags":["Server Users"],"summary":"Create user","description":"Creates an end-user in your environment. All body fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","operationId":"createUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}},"required":true},"responses":{"201":{"description":"The created user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"400":{"description":"Invalid body (e.g. weak password, malformed email).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Another user with this email already exists in the environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/unban":{"post":{"tags":["Server Users"],"summary":"Unban user","description":"Reverses a previous ban. The user can sign in again on next request.","operationId":"unbanUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to unban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now active) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/ban":{"post":{"tags":["Server Users"],"summary":"Ban user","description":"Marks the user as banned and revokes all their active sessions.","operationId":"banUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to ban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now banned) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/search":{"post":{"tags":["Server Users"],"summary":"Search users","description":"Returns a cursor-paginated page of end-users in the environment matching the optional filters. Filters use the same tri-state PATCH semantics as `UpdateUserRequest`: omit a field to skip that filter, send a value to require it, send null to require null. Uses POST so the filter body can be sent without URL-encoding.","operationId":"searchUsers","parameters":[{"name":"limit","in":"query","description":"Maximum number of items in the returned page (default 20).","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":50},{"name":"cursor","in":"query","description":"Opaque cursor returned by the previous page's `nextCursor`. Omit to fetch the first page.","required":false,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserSearchRequest"}}}},"responses":{"200":{"description":"Page of matching users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPageResponseUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}":{"get":{"tags":["Server Users"],"summary":"Get user","description":"Returns the full profile for one end-user.","operationId":"getUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to fetch.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Users"],"summary":"Delete user","description":"Soft-deletes the user. Not idempotent at the HTTP layer: the authorization grant for the user is revoked on the first successful delete, so a subsequent DELETE for the same id returns 403 rather than 204. Treat 403 from a retry as a confirmation that the user is already deleted.","operationId":"deleteUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to delete.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"User deleted."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Server Users"],"summary":"Update user","description":"Partial update with tri-state PATCH semantics. Every field in `UpdateUserRequest` is tri-state: omit the key to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","operationId":"updateUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to update.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}},"required":true},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"400":{"description":"Invalid body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/sessions":{"get":{"tags":["Server Sessions"],"summary":"List user sessions","description":"Returns all active (unexpired, unrevoked) sessions for the user, ordered by most recently used.","operationId":"listSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to list.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"All active sessions for the user.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserSessionResponse"}}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Sessions"],"summary":"Revoke all sessions","description":"Immediately revokes every active session for the user. Idempotent.","operationId":"revokeAllSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"Sessions revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/sessions/{sessionId}":{"delete":{"tags":["Server Sessions"],"summary":"Revoke specific session","description":"Revokes a single session by id. Idempotent: returns 204 even if the session was already revoked or expired.","operationId":"revokeSession","parameters":[{"name":"userId","in":"path","description":"Identifier of the user who owns the session.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"},{"name":"sessionId","in":"path","description":"Identifier of the session to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a74-1234-7000-8000-000000000000"}],"responses":{"204":{"description":"Session revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User or session belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}},"components":{"schemas":{"CreateUserRequest":{"type":"object","description":"Request body for creating an end-user in your environment. All fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","properties":{"email":{"type":["string","null"],"description":"Primary email for the new user. If omitted, the user is created without a sign-in identity.","example":"ada@example.com"},"password":{"type":["string","null"],"description":"Initial password. Subject to the environment's password policy. Omit to create a passwordless user (e.g. social-only).","example":"correct horse battery staple"},"name":{"type":["string","null"],"description":"Display name to seed on the profile.","example":"Ada Lovelace"},"phone":{"type":["string","null"],"description":"Phone number to seed on the profile.","example":"+15555550100"},"address":{"type":["string","null"],"description":"Postal address to seed on the profile.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"Date of birth in ISO-8601 (YYYY-MM-DD).","example":"1815-12-10"}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","format":"int32"},"detail":{"type":"string"},"instance":{"type":"string","format":"uri"},"properties":{"type":"object","additionalProperties":{}}}},"UserResponse":{"type":"object","description":"An end-user belonging to one of your environments.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this user.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this user belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"name":{"type":["string","null"],"description":"Full name on the profile, if any.","example":"Ada Lovelace"},"phone":{"type":["string","null"],"description":"Phone number on the profile, if any. Not guaranteed to be verified.","example":"+15555550100"},"locale":{"type":["string","null"],"description":"Preferred locale for emails and UI messages.","enum":["en","da"]},"address":{"type":["string","null"],"description":"Free-form address string, if provided.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"Date of birth in ISO-8601 (YYYY-MM-DD), if provided.","example":"1815-12-10"},"status":{"type":"string","description":"Lifecycle status of the user (e.g. active, banned).","enum":["pending_verification","active","banned","deleted"]},"createdAt":{"type":"string","format":"date-time","description":"When this user was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this user was last modified (ISO-8601 UTC).","example":"2026-05-16T10:00:00Z"},"email":{"type":["string","null"],"description":"Primary email on the profile, if any. Not guaranteed to be verified.","example":"ada@example.com"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"When this user was deleted, if soft-deleted. Null for active users.","example":"2026-05-20T12:00:00Z"}},"required":["createdAt","environmentId","id","status","updatedAt"]},"ServerUserSearchRequest":{"type":"object","description":"Optional filter body for `POST /users/search`. Every field is tri-state: omit to skip that filter, send a value to require it. Fields whose inner type is nullable (currently `name`, `email`) additionally accept JSON null to filter for users where that column is null; the non-nullable `statuses` field rejects null.","properties":{"name":{"type":["string","null"],"description":"Filter by name (case-insensitive substring match). Send null to require users with no name.","example":"Ada"},"email":{"type":["string","null"],"description":"Filter by primary email (case-insensitive substring match). Send null to require users with no email.","example":"@example.com"},"statuses":{"type":"array","description":"Filter by user status. Returns users matching any of the supplied statuses.","items":{"type":"string","enum":["pending_verification","active","banned","deleted"]},"uniqueItems":true},"createdAfter":{"type":["string","null"],"format":"date-time","description":"Only return users created at or after this instant (ISO-8601 UTC).","example":"2026-01-01T00:00:00Z"},"createdBefore":{"type":["string","null"],"format":"date-time","description":"Only return users created at or before this instant (ISO-8601 UTC).","example":"2026-12-31T23:59:59Z"}}},"CursorPageResponseUserResponse":{"type":"object","description":"A single page of results in a cursor-paginated list. Pass `nextCursor` as the `cursor` query parameter to fetch the following page.","properties":{"items":{"type":"array","description":"Items in this page, in stable order.","items":{"$ref":"#/components/schemas/UserResponse"}},"nextCursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass to fetch the next page. Null when this is the last page.","example":"01931a73-8b00-7000-8000-000000000000"},"hasMore":{"type":"boolean","description":"True if more pages are available (equivalent to `nextCursor != null`).","example":true}},"required":["hasMore","items"]},"UpdateUserRequest":{"type":"object","description":"PATCH body for updating an end-user. Every field is tri-state: omit the key entirely to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","properties":{"name":{"type":["string","null"],"description":"New display name. Send null to clear; omit to leave unchanged.","example":"Ada Lovelace"},"phone":{"type":["string","null"],"description":"New phone number. Send null to clear; omit to leave unchanged.","example":"+15555550100"},"locale":{"type":["string","null"],"description":"New preferred locale. Send null to clear; omit to leave unchanged.","enum":["en","da"]},"address":{"type":["string","null"],"description":"New postal address. Send null to clear; omit to leave unchanged.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"New date of birth (YYYY-MM-DD). Send null to clear; omit to leave unchanged.","example":"1815-12-10"}}},"UserSessionResponse":{"type":"object","description":"An active end-user session in your environment.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this session.","example":"01931a74-1234-7000-8000-000000000000"},"userId":{"type":"string","format":"uuid","description":"Identifier of the end-user this session belongs to.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this session belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"userAgent":{"type":["string","null"],"description":"Raw User-Agent string captured when the session was created.","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_0) AppleWebKit/537.36"},"ipAddress":{"type":["string","null"],"description":"IP address captured when the session was created.","example":"203.0.113.42"},"createdAt":{"type":"string","format":"date-time","description":"When this session was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"expiresAt":{"type":"string","format":"date-time","description":"When this session expires (ISO-8601 UTC).","example":"2026-05-23T09:30:00Z"},"lastUsedAt":{"type":"string","format":"date-time","description":"When this session was last seen by the API (ISO-8601 UTC).","example":"2026-05-16T11:42:00Z"}},"required":["createdAt","environmentId","expiresAt","id","lastUsedAt","userId"]}}}}

data/src/torii/backend/auth.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Torii
+  module Backend
+    # Subset of fields the backend SDK exposes from a verified torii JWT.
+    # For full claim access (custom claims, audience, etc.) read +raw+.
+    #
+    # Kept as a plain Struct for Ruby 3.1 compatibility (Data.define is
+    # 3.2+). Behaviour is the same — frozen value object, positional or
+    # keyword construction, hash-like access.
+    Auth = Struct.new(
+      :user_id,
+      :environment_id,
+      :issuer,
+      :email_verified,
+      :profile_complete,
+      :impersonating,
+      :locale,
+      :raw,
+      keyword_init: true,
+    ) do
+      def initialize(*) # rubocop:disable Lint/MissingSuper
+        super
+        freeze
+      end
+    end
+  end
+end

data/src/torii/backend/authenticate_request.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'verify'
+
+module Torii
+  module Backend
+    module_function
+
+    # Extract a bearer token from a Rack +env+ hash (or any plain header
+    # hash) and verify it. Accepts either:
+    #
+    # * a Rack environment, in which case the +header+ option is matched
+    #   against the +HTTP_*+ keys (default: +HTTP_AUTHORIZATION+);
+    # * a plain hash of headers (string keys like +"authorization"+ or
+    #   symbol keys like +:authorization+).
+    #
+    # The header name match is case-insensitive and tolerant of the Rack
+    # +HTTP_AUTHORIZATION+ convention.
+    #
+    # @return [Torii::Backend::Auth]
+    # @raise [Torii::Backend::AuthError]
+    def authenticate_request(env_or_headers, issuer:, audience: nil, leeway: 30, header: 'authorization')
+      raw = extract_header(env_or_headers, header)
+      raise AuthError, "Missing #{header} header" if raw.nil? || raw.empty?
+
+      match = /\ABearer\s+(.+)\z/i.match(raw)
+      raise AuthError, "#{header} header is not in 'Bearer <token>' form" unless match
+
+      verify_token(match[1].strip, issuer: issuer, audience: audience, leeway: leeway)
+    end
+
+    # Internal: pull a header value out of a Rack env or a plain hash.
+    # Handles the +HTTP_*+ rack convention, dashes-vs-underscores, and
+    # both string and symbol keys.
+    def extract_header(env_or_headers, name) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      return nil unless env_or_headers.respond_to?(:each_pair) || env_or_headers.respond_to?(:each)
+
+      lower = name.to_s.downcase
+      rack_key = "HTTP_#{name.to_s.upcase.tr('-', '_')}"
+      # Rack always uses HTTP_AUTHORIZATION even when the input header is
+      # 'authorization', so check that explicitly too.
+      rack_key = 'HTTP_AUTHORIZATION' if lower == 'authorization'
+
+      env_or_headers.each do |key, value|
+        key_str = key.to_s
+        next unless key_str == rack_key ||
+                    key_str.downcase == lower ||
+                    key_str.downcase.tr('_', '-') == lower
+
+        return value.is_a?(Array) ? value.first : value
+      end
+      nil
+    end
+  end
+end

data/src/torii/backend/client.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative '../../torii-backend-generated'
+require_relative 'errors'
+require_relative 'patch'
+require_relative 'version'
+
+module Torii
+  module Backend
+    # Default torii API base URL. Override via +api_url+ for staging or
+    # self-hosted.
+    DEFAULT_API_URL = 'https://api.torii.so'
+
+    # Top-level entry point for the REST surface.
+    #
+    # Construct with +Torii::Backend::Client.new(secret_key: '...')+.
+    # Reuse the instance across requests — the underlying generated
+    # client (which wraps Faraday) maintains a connection-keeping
+    # configuration.
+    class Client
+      attr_reader :users, :sessions
+
+      # @param secret_key [String] backend secret key, e.g. +sk_live_*+
+      #   or +sk_test_*+. Required.
+      # @param api_url [String] backend base URL. Defaults to
+      #   +https://api.torii.so+. Override for staging/self-hosted.
+      # @param http_adapter [Object, nil] optional callable used to stub
+      #   requests in tests. When provided, it must respond to
+      #   +#call(method, url, headers, body, query)+ and return a Hash
+      #   with +:status+, +:headers+, +:body+. The generated client uses
+      #   Typhoeus by default; the stub is only consulted when the
+      #   underlying +ApiClient+ is replaced by a test helper.
+      def initialize(secret_key:, api_url: DEFAULT_API_URL, http_adapter: nil)
+        raise ArgumentError, 'secret_key is required' if !secret_key.is_a?(String) || secret_key.empty?
+
+        @config = build_config(secret_key: secret_key, api_url: api_url)
+        @api_client = ToriiBackendGenerated::ApiClient.new(@config)
+        @http_adapter = http_adapter
+        @users = UsersClient.new(@api_client)
+        @sessions = SessionsClient.new(@api_client)
+      end
+
+      # @return [ToriiBackendGenerated::ApiClient] the underlying
+      #   generated client. Exposed for advanced callers who need to
+      #   tweak Faraday config; most code should not need this.
+      attr_reader :api_client
+
+      private
+
+      def build_config(secret_key:, api_url:)
+        config = ToriiBackendGenerated::Configuration.new
+        uri = URI.parse(api_url)
+        config.scheme = uri.scheme || 'https'
+        config.host = [uri.host, uri.port].compact.join(':')
+        config.base_path = uri.path.to_s.sub(%r{/+\z}, '')
+        # The generated client treats +access_token+ as a Bearer token
+        # but only applies it when an operation declares +bearerAuth+ as
+        # an auth_setting. Our spec doesn't (yet), so the per-call
+        # wrappers below inject the header directly.
+        config.access_token = secret_key
+        config
+      end
+    end
+
+    # Hand-written wrapper around the generated +ServerUsersApi+. The
+    # wrapper:
+    #
+    # * keeps a Pythonic / idiomatic-Ruby keyword surface that matches
+    #   the surface promised in the SDK docs across languages;
+    # * sets the secret-key header on every call (the generated client
+    #   does not, see comment in Client#build_config);
+    # * deserialises generated model instances to plain hashes so
+    #   callers don't need to learn the generated namespace.
+    class UsersClient
+      def initialize(api_client)
+        @api_client = api_client
+        @api = ToriiBackendGenerated::ServerUsersApi.new(api_client)
+      end
+
+      # Search users. Server-side cursor-paginated; call repeatedly with
+      # +cursor: page[:next_cursor]+ until +page[:has_more]+ is false.
+      def list(limit: nil, cursor: nil, name: nil, email: nil, statuses: nil, created_after: nil, created_before: nil)
+        body = ToriiBackendGenerated::ServerUserSearchRequest.new(
+          name: name,
+          email: email,
+          statuses: statuses,
+          created_after: created_after,
+          created_before: created_before,
+        )
+        opts = { server_user_search_request: body, header_params: auth_headers }
+        opts[:limit] = limit unless limit.nil?
+        opts[:cursor] = cursor unless cursor.nil?
+        result = @api.search_users(opts)
+        page_to_hash(result)
+      end
+
+      def get(user_id)
+        model_to_hash(@api.get_user(user_id, header_params: auth_headers))
+      end
+
+      def create(email: nil, name: nil, phone: nil, password: nil, address: nil, date_of_birth: nil)
+        body = ToriiBackendGenerated::CreateUserRequest.new(
+          email: email,
+          name: name,
+          phone: phone,
+          password: password,
+          address: address,
+          date_of_birth: date_of_birth,
+        )
+        model_to_hash(@api.create_user(body, header_params: auth_headers))
+      end
+
+      # PATCH a user. Each kwarg must be a {Torii::Backend::Patch}
+      # instance — Ruby keyword args can't distinguish "absent" from
+      # "explicit nil" on their own, so we use a wrapper:
+      #
+      #   client.users.update(user_id,
+      #     name: Torii::Backend::Patch.set("Ada"),  # set field
+      #     phone: Torii::Backend::Patch.set(nil),   # null on the wire (clear)
+      #   )
+      #
+      # Omitted kwargs are left untouched on the server. Field names map
+      # to the JSON keys the server expects (camelCase).
+      def update(user_id, **patches)
+        body = {}
+        patches.each do |field, patch|
+          unless patch.is_a?(Patch)
+            raise ArgumentError, "kwarg #{field} must be a Torii::Backend::Patch (got #{patch.class})"
+          end
+
+          json_key = PATCH_FIELD_MAP.fetch(field) do
+            raise ArgumentError, "unknown PATCH field: #{field}. Valid: #{PATCH_FIELD_MAP.keys.inspect}"
+          end
+
+          # Patch.set(value) emits the key; nil value → JSON null (clear).
+          body[json_key] = patch.value
+        end
+
+        # +debug_body+ on the generated client is the escape hatch for
+        # sending a pre-rendered request body. The generated
+        # +UpdateUserRequest+ model strips nil-valued attributes when
+        # serialising, which would defeat the +Patch.clear+ case, so we
+        # bypass it and ship our hand-built JSON instead.
+        result = @api.update_user(
+          user_id,
+          ToriiBackendGenerated::UpdateUserRequest.new,
+          debug_body: body.to_json,
+          header_params: auth_headers,
+        )
+        model_to_hash(result)
+      end
+
+      # Map of Ruby snake_case kwargs to the JSON keys the server
+      # expects on the PATCH body. Centralised so +update+ can validate
+      # field names with a single +fetch+.
+      PATCH_FIELD_MAP = {
+        name: 'name',
+        phone: 'phone',
+        locale: 'locale',
+        address: 'address',
+        date_of_birth: 'dateOfBirth',
+      }.freeze
+
+      def delete(user_id)
+        @api.delete_user(user_id, header_params: auth_headers)
+        nil
+      end
+
+      def ban(user_id)
+        model_to_hash(@api.ban_user(user_id, header_params: auth_headers))
+      end
+
+      def unban(user_id)
+        model_to_hash(@api.unban_user(user_id, header_params: auth_headers))
+      end
+
+      private
+
+      def auth_headers
+        { 'Authorization' => "Bearer #{@api_client.config.access_token}" }
+      end
+
+      def model_to_hash(model)
+        return model if model.nil? || model.is_a?(Hash)
+
+        model.respond_to?(:to_hash) ? model.to_hash : model
+      end
+
+      def page_to_hash(page)
+        return page if page.nil? || page.is_a?(Hash)
+
+        {
+          items: (page.items || []).map { |u| model_to_hash(u) },
+          next_cursor: page.respond_to?(:next_cursor) ? page.next_cursor : nil,
+          has_more: page.respond_to?(:has_more) ? page.has_more : false,
+        }
+      end
+    end
+
+    # Hand-written wrapper around the generated +ServerSessionsApi+.
+    # See the +UsersClient+ docstring for the rationale.
+    class SessionsClient
+      def initialize(api_client)
+        @api_client = api_client
+        @api = ToriiBackendGenerated::ServerSessionsApi.new(api_client)
+      end
+
+      def list_for_user(user_id)
+        result = @api.list_sessions(user_id, header_params: auth_headers)
+        (result || []).map { |s| s.respond_to?(:to_hash) ? s.to_hash : s }
+      end
+
+      def revoke_all_for_user(user_id)
+        @api.revoke_all_sessions(user_id, header_params: auth_headers)
+        nil
+      end
+
+      def revoke(user_id, session_id)
+        @api.revoke_session(user_id, session_id, header_params: auth_headers)
+        nil
+      end
+
+      private
+
+      def auth_headers
+        { 'Authorization' => "Bearer #{@api_client.config.access_token}" }
+      end
+    end
+  end
+end

data/src/torii/backend/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Torii
+  module Backend
+    # Base class for all errors raised by torii-backend.
+    class Error < StandardError; end
+
+    # Raised when /api/server/v1/** responds non-2xx. Inspect +status+, +code+
+    # (from the error body if present), and +support_id+ (echoed correlation
+    # id) for diagnostics. +body+ is the raw parsed response.
+    class ApiError < Error
+      attr_reader :status, :code, :support_id, :body
+
+      def initialize(message, status:, body: nil)
+        super(message)
+        @status = status
+        @body = body
+        @code = body['code'] if body.is_a?(Hash) && body['code'].is_a?(String)
+        @support_id = (body['supportId'] || body['support_id']) if body.is_a?(Hash)
+      end
+    end
+
+    # Raised by verify_token / authenticate_request when a token cannot be
+    # verified (bad signature, wrong issuer, missing claim, expired, ...).
+    class AuthError < Error
+      attr_reader :cause
+
+      def initialize(message, cause: nil)
+        super(message)
+        @cause = cause
+      end
+    end
+  end
+end