atproto_auth 0.0.1 → 0.1.0

data/README.md

@@ -4,7 +4,7 @@
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 [![Documentation](https://img.shields.io/badge/docs-rdoc-blue.svg)](https://www.rubydoc.info/gems/atproto_auth)
 
-A Ruby implementation of the AT Protocol OAuth specification. This library provides comprehensive support for both client and server-side implementations, with built-in security features including DPoP (Demonstrating Proof of Possession), PAR (Pushed Authorization Requests), and dynamic client registration.
+A Ruby implementation of the [AT Protocol OAuth specification](https://docs.bsky.app/docs/advanced-guides/oauth-client). This library provides comprehensive support for both client and server-side implementations, with built-in security features including DPoP (Demonstrating Proof of Possession), PAR (Pushed Authorization Requests), and dynamic client registration.
 
 ## Features
 
@@ -15,6 +15,8 @@ A Ruby implementation of the AT Protocol OAuth specification. This library provi
 - Comprehensive identity resolution and verification
 - Automatic token refresh and session management
 - Robust error handling and recovery mechanisms
+- Configurable storage backends with built-in Redis support
+- Encrypted storage of sensitive data
 
 ## Installation
 
@@ -41,6 +43,7 @@ gem install atproto_auth
 - Ruby 3.0 or higher
 - OpenSSL support
 - For confidential clients: HTTPS-capable domain for client metadata hosting
+- Optional: Redis 5.0+ for production storage backend
 
 ## Basic Usage
 
@@ -59,6 +62,88 @@ AtprotoAuth.configure do |config|
   # Set token lifetimes
   config.default_token_lifetime = 300 # 5 minutes
   config.dpop_nonce_lifetime = 300  # 5 minutes
+
+  # Configure storage backend (default is in-memory)
+  config.storage = AtprotoAuth::Storage::Memory.new
+end
+
+# For production environments, use Redis storage:
+AtprotoAuth.configure do |config|
+  # Configure Redis storage
+  config.storage = AtprotoAuth::Storage::Redis.new(
+    redis_client: Redis.new(url: ENV['REDIS_URL'])
+  )
+end
+```
+
+### Storage Backends
+
+The library supports multiple storage backends for managing OAuth state:
+
+#### In-Memory Storage (Default)
+```ruby
+# Default configuration - good for development
+AtprotoAuth.configure do |config|
+  config.storage = AtprotoAuth::Storage::Memory.new
+end
+```
+
+#### Redis Storage (Recommended for Production)
+```ruby
+# Redis configuration - recommended for production
+require 'redis'
+
+AtprotoAuth.configure do |config|
+  redis_client = Redis.new(
+    url: ENV['REDIS_URL'],
+    ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+  )
+  
+  config.storage = AtprotoAuth::Storage::Redis.new(
+    redis_client: redis_client
+  )
+end
+```
+
+#### Custom Storage Implementation
+```ruby
+# Implement your own storage backend
+class CustomStorage < AtprotoAuth::Storage::Interface
+  def set(key, value, ttl: nil)
+    # Implementation
+  end
+
+  def get(key)
+    # Implementation
+  end
+
+  def delete(key)
+    # Implementation
+  end
+
+  def exists?(key)
+    # Implementation
+  end
+
+  def multi_get(keys)
+    # Implementation
+  end
+
+  def multi_set(hash, ttl: nil)
+    # Implementation
+  end
+
+  def acquire_lock(key, ttl:)
+    # Implementation
+  end
+
+  def release_lock(key)
+    # Implementation
+  end
+
+  def with_lock(key, ttl: 30)
+    # Implementation
+  end
 end
 ```
 
@@ -162,7 +247,8 @@ Built-in security best practices:
 - Constant-time token comparisons
 - Thread-safe state management
 - Protection against SSRF attacks
-- Secure token storage
+- Secure encrypted token storage
+- Atomic storage operations with locking
 
 ## Development
 

data/examples/confidential_client/.gitignore

@@ -0,0 +1,2 @@
+/config/client-metadata.json
+/public/client-metadata.json

data/examples/confidential_client/Gemfile.lock

@@ -4,12 +4,14 @@ PATH
     atproto_auth (0.1.0)
       jose (~> 1.2)
       jwt (~> 2.9)
+      redis (~> 5.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
     base64 (0.2.0)
     concurrent-ruby (1.3.4)
+    connection_pool (2.4.1)
     dotenv (3.1.4)
     faraday (2.12.1)
       faraday-net_http (>= 2.0, < 3.5)
@@ -45,6 +47,10 @@ GEM
     rackup (2.2.1)
       rack (>= 3)
     rbtree (0.4.6)
+    redis (5.3.0)
+      redis-client (>= 0.22.0)
+    redis-client (0.22.2)
+      connection_pool
     ruby2_keywords (0.0.5)
     set (1.1.1)
     sinatra (4.1.1)

data/examples/confidential_client/README.md

@@ -2,14 +2,19 @@
 
 This is an example implementation of a confidential OAuth client for the AT Protocol using the AtprotoAuth gem. It demonstrates how to implement the OAuth flow for a web application, including DPoP token binding and secure session management.
 
+<img src="https://github.com/jhuckabee/atproto_auth/blob/main/examples/confidential_client/screenshots/screenshot-1-sign-in.png?raw=true" alt="Sign In Form Screenshot" title="Sign In Form" width="500">
+
+<img src="https://github.com/jhuckabee/atproto_auth/blob/main/examples/confidential_client/screenshots/screenshot-2-success.png?raw=true" alt="Sign In Success Screenshot" title="Sign In Success" width="500">
+
 ## Overview
 
 The example implements a simple web application using Sinatra that:
 - Allows users to sign in with their AT Protocol handle (@handle)
 - Implements the complete OAuth authorization flow
 - Uses DPoP-bound tokens for API requests
-- Demonstrates secure session management
+- Demonstrates secure session management with encryption
 - Shows how to make authenticated API calls to Bluesky
+- Provides examples of both development and production storage configurations
 
 ## Requirements
 
@@ -17,6 +22,7 @@ The example implements a simple web application using Sinatra that:
 - Bundler
 - A domain name for your application that matches your client metadata
 - SSL certificate for your domain (required for production)
+- Redis (optional, recommended for production)
 
 ## Setup
 
@@ -35,19 +41,61 @@ bundle install
 bundle exec ruby scripts/generate_keys.rb > config/keys.json
 ```
 
-4. Configure your client metadata in `config/client-metadata.json`. Make sure to:
+4. Configure your client metadata:
+   - Copy the example metadata file over:
+     ```
+     cp config/client-metadata.example.json config/client-metadata.json
+     ```
    - Set the correct `client_id` URL where your metadata will be hosted
    - Configure valid `redirect_uris` for your application
    - Add your generated keys from step 3 to the `jwks` field
 
 5. Set up environment variables:
 ```bash
-export SESSION_SECRET=your-secure-session-secret # Required for session encryption
-export PERMITTED_DOMAIN=your.domain.com # Your application's domain name 
+# Required for session encryption
+export SESSION_SECRET=your-secure-session-secret 
+
+# Your application's domain name
+export PERMITTED_DOMAIN=your.domain.com 
+
+# Optional: Redis URL for production storage
+export REDIS_URL=redis://localhost:6379
 ```
 
 ## Configuration
 
+### Storage Configuration
+
+The example app supports both in-memory and Redis storage backends:
+
+#### Development (In-Memory Storage)
+```ruby
+# config/development.rb
+AtprotoAuth.configure do |config|
+  config.storage = AtprotoAuth::Storage::Memory.new
+  config.logger = Logger.new($stdout)
+end
+```
+
+#### Production (Redis Storage)
+```ruby
+# config/production.rb
+require 'redis'
+
+AtprotoAuth.configure do |config|
+  redis_client = Redis.new(
+    url: ENV.fetch('REDIS_URL'),
+    ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+  )
+  
+  config.storage = AtprotoAuth::Storage::Redis.new(
+    redis_client: redis_client
+  )
+  
+  config.logger = Logger.new($stdout)
+end
+```
+
 ### Host Authorization
 
 This application requires specific domain configuration to function properly:
@@ -69,7 +117,7 @@ This application requires specific domain configuration to function properly:
       ```bash
       export PERMITTED_DOMAIN=machinename.xyz.ts.net
       ```
-   6. Run the application (see below).
+   6. Run the application (see below)
 
 Your application will now be accessible via your Tailscale domain with HTTPS enabled.
 
@@ -77,20 +125,25 @@ Your application will now be accessible via your Tailscale domain with HTTPS ena
 
 The application uses encrypted sessions to store authorization data. Configure the session secret with:
 
-```ruby
+```bash
 export SESSION_SECRET=your-secure-random-string
 ```
 
-If not set, a random secret will be generated on startup.
+If not set, a random secret will be generated on startup (not recommended for production).
 
 ## Running the Application
 
+### Development
 ```bash
-bundle exec rackup
+RACK_ENV=development bundle exec rackup
 ```
 
-This will start the server on `http://localhost:9292`.
+### Production
+```bash
+RACK_ENV=production bundle exec rackup -E production
+```
 
+This will start the server on `http://localhost:9292`.
 
 ## Troubleshooting
 
@@ -108,3 +161,27 @@ This will start the server on `http://localhost:9292`.
    - Verify your JWKS configuration
    - Check that your DPoP proofs are being generated correctly
    - Ensure your client authentication is working
+
+4. "Storage errors":
+   - For Redis storage, verify Redis connection settings
+   - Check Redis SSL configuration if using encrypted connections
+   - Ensure proper Redis authentication credentials if required
+
+5. "Session state lost":
+   - Verify storage configuration is correct
+   - Check Redis connection stability if using Redis storage
+   - Ensure session TTLs are appropriately configured
+
+## Understanding the Code
+
+The example demonstrates several important concepts:
+
+1. **Secure Storage**: The app shows proper configuration of both development (in-memory) and production (Redis) storage backends.
+
+2. **Token Management**: All tokens are stored securely with encryption in the configured storage backend.
+
+3. **Session Handling**: The app demonstrates proper session state management with atomic operations and locking.
+
+4. **Error Recovery**: Includes examples of handling storage failures and token refresh scenarios.
+
+The code is thoroughly commented to explain these concepts and their implementation details.

data/examples/confidential_client/app.rb

@@ -9,17 +9,18 @@ require "dotenv/load"
 
 # Main app entry point
 class ExampleApp < Sinatra::Base
+  def check_stored_session(session_id)
+    return false unless session_id
+
+    settings.oauth_client.authorized?(session_id)
+  rescue AtprotoAuth::SessionError
+    false
+  end
+
   configure :development do
     register Sinatra::Reloader
   end
 
-  set :host_authorization, {
-    permitted_hosts: ["localhost", ENV.fetch("PERMITTED_DOMAIN", nil)].compact
-  }
-
-  enable :sessions
-  set :session_secret, ENV.fetch("SESSION_SECRET") { SecureRandom.hex(32) }
-
   # Initialize the AT Protocol OAuth client
   configure do
     # Configure AtprotoAuth settings
@@ -30,6 +31,9 @@ class ExampleApp < Sinatra::Base
       )
       config.default_token_lifetime = 300
       config.dpop_nonce_lifetime = 300
+
+      # Optionally, use Redis storage instead of in-memory
+      # config.storage = AtprotoAuth::Storage::Redis.new
     end
 
     # Load client metadata
@@ -45,10 +49,61 @@ class ExampleApp < Sinatra::Base
     )
   end
 
+  set :host_authorization, {
+    permitted_hosts: ["localhost", ENV.fetch("PERMITTED_DOMAIN", nil)].compact
+  }
+
+  use Rack::Session::Cookie,
+      key: "atproto.session",
+      expire_after: 86_400, # 1 day in seconds
+      secret: ENV.fetch("SESSION_SECRET") { SecureRandom.hex(32) },
+      secure: true,       # Only send over HTTPS
+      httponly: true,     # Not accessible via JavaScript
+      same_site: :lax     # CSRF protection
+
+  helpers do
+    def recover_session
+      session_id = session[:oauth_session_id]
+      return nil unless session_id
+
+      begin
+        # Check if session is still valid
+        return nil unless settings.oauth_client.authorized?(session_id)
+
+        session_id
+      rescue AtprotoAuth::Client::SessionError
+        # Clear invalid session
+        session.delete(:oauth_session_id)
+        nil
+      end
+    end
+  end
+
   get "/" do
+    # Check for existing session
+    redirect "/authorized" if recover_session
+
     erb :index
   end
 
+  get "/client-metadata.json" do
+    content_type :json
+
+    # Read metadata from config file
+    metadata_path = File.join(__dir__, "config", "client-metadata.json")
+    metadata = JSON.parse(File.read(metadata_path))
+
+    # Strip private key 'd' component from each key in the JWKS
+    if metadata["jwks"] && metadata["jwks"]["keys"]
+      metadata["jwks"]["keys"] = metadata["jwks"]["keys"].map do |key|
+        key.except("d")
+      end
+    end
+
+    # Return sanitized metadata
+    JSON.generate(metadata)
+  end
+
   # Start OAuth flow
   post "/auth" do
     handle = params[:handle]
@@ -60,7 +115,7 @@ class ExampleApp < Sinatra::Base
         scope: "atproto"
       )
 
-      # Store session ID for callback
+      # Store session ID in user's browser session
       session[:oauth_session_id] = auth[:session_id]
 
       # Redirect to authorization URL
@@ -80,8 +135,8 @@ class ExampleApp < Sinatra::Base
       iss: params[:iss]
     )
 
-    # Store tokens in session
-    session[:tokens] = result
+    # Store tokens
+    session[:oauth_session_id] = result[:session_id]
 
     redirect "/authorized"
   rescue StandardError => e
@@ -91,9 +146,19 @@ class ExampleApp < Sinatra::Base
 
   # Show authorized state and test API call
   get "/authorized" do
-    return redirect "/" unless session[:tokens]
+    session_id = session[:oauth_session_id]
+    return redirect "/" unless check_stored_session(session_id)
 
     begin
+      # Get current session tokens
+      oauth_session = settings.oauth_client.get_tokens(session_id)
+
+      # Check if token needs refresh
+      if oauth_session[:expires_in] < 30
+        # Refresh token
+        oauth_session = settings.oauth_client.refresh_token(session_id)
+      end
+
       # Make test API call to com.atproto.identity.resolveHandle
       conn = Faraday.new(url: "https://api.bsky.app") do |f|
         f.request :json
@@ -102,7 +167,7 @@ class ExampleApp < Sinatra::Base
 
       # Get auth headers for request
       headers = settings.oauth_client.auth_headers(
-        session_id: session[:tokens][:session_id],
+        session_id: session_id,
         method: "GET",
         url: "https://api.bsky.app/xrpc/com.atproto.identity.resolveHandle"
       )
@@ -114,6 +179,7 @@ class ExampleApp < Sinatra::Base
       end
 
       @api_result = response.body
+      @session = oauth_session
       erb :authorized
     rescue StandardError => e
       session[:error] = "API call failed: #{e.message}"
@@ -122,6 +188,11 @@ class ExampleApp < Sinatra::Base
   end
 
   get "/signout" do
+    if session[:oauth_session_id]
+      # Clean up stored session
+      settings.oauth_client.remove_session(session[:oauth_session_id])
+    end
+
     session.clear
     session[:notice] = "Successfully signed out"
     redirect "/"

data/examples/confidential_client/{public/client-metadata.json → config/client-metadata.example.json}

@@ -1,7 +1,7 @@
 {
-  "client_id": "https://mac.tail7f768.ts.net/client-metadata.json",
+  "client_id": "https://YOUR_DOMAIN_HERE/client-metadata.json",
   "client_name": "AT Protocol OAuth Ruby Example",
-  "redirect_uris": ["https://mac.tail7f768.ts.net/callback"],
+  "redirect_uris": ["https://YOUR_DOMAIN_HERE/callback"],
   "grant_types": ["authorization_code", "refresh_token"],
   "response_types": ["code"],
   "scope": "atproto",
@@ -14,10 +14,11 @@
       {
         "use": "sig",
         "kid": "key-1",
-        "x": "SzXlDk9rSyrZ3b0fVKOWFYY-AFZtld2zElycsmDZ3Xk",
+        "x": "...",
         "crv": "P-256",
+        "d": "...",
         "kty": "EC",
-        "y": "4hIBLl-BLD1Ypk-mvPxT2OR52ezMs4XI1MGBdhlLLm4"
+        "y": "..."
       }
     ]
   }

data/examples/confidential_client/views/authorized.erb

@@ -13,7 +13,7 @@
 
       <div class="token-info">
         <p class="mb-1 text-gray-600 dark:text-gray-400 text-sm font-medium">Token Information</p>
-        <pre class="rounded-lg text-gray-700 dark:text-gray-100 bg-gray-100 dark:bg-slate-800 border border-gray-400 p-2 overflow-auto"><code><%= JSON.pretty_generate(session[:tokens]) %></code></pre>
+        <pre class="rounded-lg text-gray-700 dark:text-gray-100 bg-gray-100 dark:bg-slate-800 border border-gray-400 p-2 overflow-auto"><code><%= JSON.pretty_generate(@session) %></code></pre>
       </div>
 
       <div class="api-test">