authproto 0.3.0.beta1

data/examples/confidential_client/README.md

@@ -0,0 +1,226 @@
+# AT Protocol OAuth Confidential Client Example
+
+This is an example implementation of a confidential OAuth client for the AT Protocol using the AuthProto 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/mackuba/authproto/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/mackuba/authproto/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) and make a test Bluesky post
+- Implements the complete OAuth authorization flow
+- Uses DPoP-bound tokens for API requests
+- Demonstrates secure session management with encryption
+- Shows how to make authenticated API calls to Bluesky
+- Provides examples of both development and production storage configurations
+- Supports running on localhost
+
+## Requirements
+
+- Ruby 3.3+
+- Bundler
+- A domain name for your application that matches your client metadata (required for production)
+- SSL certificate for your domain (required for production)
+- optionally, Redis for production
+
+## Setup
+
+1. Clone the repository and navigate to the example directory:
+
+```bash
+cd examples/confidential_client
+```
+
+2. Install dependencies:
+
+```bash
+bundle install
+```
+
+3. Generate EC keys for client authentication:
+
+```bash
+bundle exec ruby scripts/generate_keys.rb > config/keys.json
+```
+
+4. Generate session & encryption keys:
+
+```bash
+openssl rand -base64 32
+openssl rand -hex 32
+
+cat > .env
+ATPROTO_MASTER_KEY=<base64 value from first command>
+SESSION_SECRET=<hex value from second command>
+```
+
+5. Configure your client metadata:
+   - Copy the example metadata file over:
+     ```
+     cp config/client-metadata.example.json config/oauth-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
+   - For localhost testing, set `client_id` to `http://localhost/` and `redirect_uris` to `["http://127.0.0.1:9292/callback"]`
+
+6. Set up environment variables:
+
+```bash
+# Your application's domain name
+export PERMITTED_DOMAIN=your.domain.com
+# or 127.0.0.1 for localhost testing
+
+# Select a storage backend: memory (default), sqlite, or redis
+export STORAGE_BACKEND=sqlite
+
+# Optional SQLite path (defaults to ./db/authproto.sqlite3)
+export SQLITE_PATH=/var/lib/my-app/authproto.sqlite3
+
+# Required when STORAGE_BACKEND=redis
+export REDIS_URL=redis://localhost:6379
+```
+
+## Configuration
+
+### Storage Configuration
+
+The example app supports in-memory, SQLite and Redis storage backends. Select
+one by passing `STORAGE_BACKEND=memory`, `STORAGE_BACKEND=sqlite`, or
+`STORAGE_BACKEND=redis`.
+
+#### In-memory storage (for development)
+
+```ruby
+# config/development.rb
+AuthProto.configure do |config|
+  config.storage = AuthProto::Storage::Memory.new
+  config.logger = Logger.new($stdout)
+end
+```
+
+#### SQLite storage
+
+SQLite can be used for persistent storage in development or in low traffic production setups:
+
+```bash
+export STORAGE_BACKEND=sqlite
+export SQLITE_PATH=/var/lib/my-app/authproto.sqlite3
+```
+
+#### Redis storage
+
+Use Redis in more complex production setups:
+
+```ruby
+# config/production.rb
+require 'redis'
+
+AuthProto.configure do |config|
+  redis_client = Redis.new(
+    url: ENV.fetch('REDIS_URL'),
+    ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+  )
+  
+  config.storage = AuthProto::Storage::Redis.new(
+    redis_client: redis_client
+  )
+  
+  config.logger = Logger.new($stdout)
+end
+```
+
+### Host Authorization
+
+This application requires specific domain configuration to function properly:
+
+1. **Domain-Client Matching**: The domain where you run the application must exactly match the `client_id` domain in your client metadata. For example, if your `client_id` is `https://myapp.example.com/oauth-client-metadata.json`, the application must be accessible at `myapp.example.com`.
+
+2. **Internet Accessibility**: The application must be accessible from the internet for AT Protocol OAuth to work. The Authorization Server needs to be able to reach your application's redirect URI during the OAuth flow.
+
+3. **Quick Setup with Tailscale Funnel**: One easy way to expose your local development server to the internet is using Tailscale Funnel:
+
+   1. Set up [Tailscale Funnel](https://tailscale.com/kb/1223/funnel)
+   2. Ensure you have HTTPS certificates configured
+   5. Start your Funnel:
+      ```bash
+      tailscale funnel 9292
+      ```
+   4. Ensure your client_id and redirect_uris match your funnel path
+   5. Set the `PERMITTED_DOMAIN` environment variable to your Tailscale domain
+      ```bash
+      export PERMITTED_DOMAIN=machinename.xyz.ts.net
+      ```
+   6. Run the application (see below)
+
+Your application will now be accessible via your Tailscale domain with HTTPS enabled.
+
+### Session Security
+
+The application uses encrypted sessions to store authorization data. Configure the session secret with:
+
+```bash
+export SESSION_SECRET=your-secure-random-string
+```
+
+If not set, a random secret will be generated on startup (not recommended for production).
+
+## Running the Application
+
+### Development
+```bash
+RACK_ENV=development bundle exec rackup
+```
+
+### Production
+```bash
+RACK_ENV=production bundle exec rackup -E production
+```
+
+This will start the server on `http://localhost:9292`.
+
+## Troubleshooting
+
+### Common Issues
+
+1. "Invalid redirect URI":
+   - Ensure your redirect URI matches exactly what's in your client metadata
+   - Check that your domain matches the client_id domain
+
+2. "Invalid client metadata":
+   - Verify your client metadata is accessible at the URL specified in client_id
+   - Check that your JSON is valid and contains all required fields
+
+3. "Authorization failed":
+   - Verify your JWKS configuration
+   - Check that your DPoP proofs are being generated correctly
+   - Ensure your client authentication is working
+
+4. "Storage errors":
+   - For SQLite storage, verify the database path is writable
+   - 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 that SQLite storage is on persistent local disk
+   - 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 in-memory, SQLite and Redis storage.
+
+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

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'json'
+require 'securerandom'
+require 'time'
+require 'uri'
+
+require 'authproto'
+require 'dotenv/load'
+require 'faraday'
+require 'sinatra/base'
+require 'sinatra/reloader'
+
+# 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 AuthProto::SessionError
+    false
+  end
+
+  configure :development do
+    register Sinatra::Reloader
+  end
+
+  # Initialize the AT Protocol OAuth client
+  configure do
+    # Configure AuthProto settings
+    AuthProto.configure do |config|
+      config.http_client = AuthProto::HTTPClient.new(timeout: 10, verify_ssl: true)
+      config.default_token_lifetime = 300
+      config.dpop_nonce_lifetime = 300
+
+      case ENV.fetch("STORAGE_BACKEND", "memory")
+      when "memory"
+        config.storage = AuthProto::Storage::Memory.new
+      when "sqlite"
+        config.storage = AuthProto::Storage::SQLite.new(
+          path: ENV.fetch("SQLITE_PATH", File.join(__dir__, "db", "authproto.sqlite3"))
+        )
+      when "redis"
+        config.storage = AuthProto::Storage::Redis.new(
+          redis_client: Redis.new(url: ENV.fetch("REDIS_URL"))
+        )
+      else
+        raise "STORAGE_BACKEND must be memory, sqlite, or redis"
+      end
+    end
+
+    # Load client metadata
+    metadata_path = File.join(__dir__, "config", "oauth-client-metadata.json")
+    metadata = JSON.parse(File.read(metadata_path))
+
+    client_id = metadata["client_id"]
+
+    if client_id.chomp("/") == "http://localhost"
+      scope = CGI.escape(metadata["scope"])
+      redirect_uri = CGI.escape(metadata["redirect_uris"][0])
+      client_id += "?scope=#{scope}&redirect_uri=#{redirect_uri}"
+    end
+
+    # Create OAuth client
+    set :oauth_client, AuthProto::Client.new(
+      client_id: client_id,
+      redirect_uri: metadata["redirect_uris"][0],
+      metadata: metadata,
+      dpop_key: metadata["jwks"]["keys"][0]
+    )
+  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: ENV.fetch("RACK_ENV", "development") == "production",  # 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 AuthProto::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 "/oauth-client-metadata.json" do
+    content_type :json
+
+    # Read metadata from config file
+    metadata_path = File.join(__dir__, "config", "oauth-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]
+
+    begin
+      # Start authorization flow
+      auth = settings.oauth_client.authorize(
+        handle: handle,
+        scope: "atproto repo:app.bsky.feed.post"
+      )
+
+      # Store session ID in user's browser session
+      session[:oauth_session_id] = auth[:session_id]
+
+      # Redirect to authorization URL
+      redirect auth[:url]
+    rescue StandardError => e
+      session[:error] = "Authorization failed: #{e.message}"
+      redirect "/"
+    end
+  end
+
+  # OAuth callback handler
+  get "/callback" do
+    # Handle the callback
+    result = settings.oauth_client.handle_callback(
+      code: params[:code],
+      state: params[:state],
+      iss: params[:iss]
+    )
+
+    # Store tokens
+    session[:oauth_session_id] = result[:session_id]
+
+    redirect "/authorized"
+  rescue StandardError => e
+    session[:error] = "Callback failed: #{e.message}"
+    redirect "/"
+  end
+
+  # Show authorized state and test API call
+  get "/authorized" do
+    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
+        f.response :json
+      end
+
+      # Get auth headers for request
+      headers = settings.oauth_client.auth_headers(
+        session_id: session_id,
+        method: "GET",
+        url: "https://api.bsky.app/xrpc/com.atproto.identity.resolveHandle"
+      )
+
+      # Make authenticated request
+      response = conn.get("/xrpc/com.atproto.identity.resolveHandle") do |req|
+        headers.each { |k, v| req.headers[k] = v }
+        req.params[:handle] = "bsky.app"
+      end
+
+      @api_result = response.body
+      @session = oauth_session
+      erb :authorized
+    rescue StandardError => e
+      session[:error] = "API call failed: #{e.message}"
+      redirect "/"
+    end
+  end
+
+  post "/posts" do
+    session_id = session[:oauth_session_id]
+    return redirect "/" unless check_stored_session(session_id)
+
+    text = params[:text].to_s
+    if text.strip.empty?
+      session[:error] = "Post text cannot be empty"
+      return redirect "/authorized"
+    end
+
+    if text.length > 300 || text.bytesize > 3_000
+      session[:error] = "Post text must be at most 300 characters and 3,000 bytes"
+      return redirect "/authorized"
+    end
+
+    oauth_session = settings.oauth_client.session_manager.get_session(session_id)
+
+    pds_url = ENV['PDS_URL'] || DIDKit::DID.new(oauth_session.did).document.pds_endpoint
+    raise "No HTTPS PDS location found" unless pds_url && URI(pds_url).is_a?(URI::HTTPS)
+
+    endpoint = URI.join(
+      "#{pds_url.chomp("/")}/",
+      "xrpc/com.atproto.repo.createRecord"
+    ).to_s
+
+    headers = settings.oauth_client.auth_headers(
+      session_id: session_id,
+      method: "POST",
+      url: endpoint
+    )
+
+    conn = Faraday.new do |f|
+      f.request :json
+      f.response :json
+    end
+    response = conn.post(endpoint) do |req|
+      headers.each { |key, value| req.headers[key] = value }
+      req.body = {
+        repo: oauth_session.did,
+        collection: "app.bsky.feed.post",
+        record: {
+          "$type": "app.bsky.feed.post",
+          text: text,
+          langs: ["en"],
+          createdAt: Time.now.utc.iso8601(3)
+        }
+      }
+    end
+
+    unless response.success?
+      error_body = response.body.is_a?(String) ? response.body : JSON.generate(response.body)
+      raise "PDS rejected post (#{response.status}): #{error_body}"
+    end
+
+    session[:notice] = "Post published successfully"
+    redirect "/authorized"
+  rescue StandardError => e
+    session[:error] = "Publishing post failed: #{e.message}"
+    redirect "/authorized"
+  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 "/"
+  end
+
+  # Helper method to check if user is authenticated
+  def authenticated?
+    return false unless session[:tokens]
+
+    settings.oauth_client.authorized?(session[:tokens][:session_id])
+  end
+end

data/examples/confidential_client/config/client-metadata.example.json

@@ -0,0 +1,25 @@
+{
+  "client_id": "https://YOUR_DOMAIN_HERE/oauth-client-metadata.json",
+  "client_name": "AT Protocol OAuth Ruby Example",
+  "redirect_uris": ["https://YOUR_DOMAIN_HERE/callback"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "scope": "atproto repo:app.bsky.feed.post",
+  "token_endpoint_auth_method": "private_key_jwt",
+  "token_endpoint_auth_signing_alg": "ES256",
+  "application_type": "web",
+  "dpop_bound_access_tokens": true,
+  "jwks": {
+    "keys": [
+      {
+        "use": "sig",
+        "kid": "key-1",
+        "x": "...",
+        "crv": "P-256",
+        "d": "...",
+        "kty": "EC",
+        "y": "..."
+      }
+    ]
+  }
+}

data/examples/confidential_client/config.ru

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'app'
+run ExampleApp

data/examples/confidential_client/public/styles.css

@@ -0,0 +1,70 @@
+.container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 20px;
+}
+
+.header {
+    max-width: 400px;
+    margin: 0 auto;
+}
+
+.error {
+    background-color: #ffebee;
+    color: #c62828;
+    padding: 10px;
+    margin-bottom: 20px;
+    border-radius: 4px;
+}
+
+.auth-form {
+    max-width: 400px;
+    margin: 40px auto;
+}
+
+.form-group {
+    margin-bottom: 15px;
+}
+
+.form-group label {
+    display: block;
+    margin-bottom: 5px;
+}
+
+.form-group input {
+    width: 100%;
+    padding: 8px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+}
+
+button {
+    background: #2196f3;
+    color: white;
+    padding: 10px 20px;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+}
+
+button:hover {
+    background: #1976d2;
+}
+
+.token-info,
+.api-test {
+    margin-top: 20px;
+    padding: 15px;
+    background: #f5f5f5;
+    border-radius: 4px;
+}
+
+pre {
+    overflow-x: auto;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}
+
+code {
+    font-size: 14px;
+}

data/examples/confidential_client/scripts/generate_keys.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'jose'
+
+# Generate a new EC key using P-256 curve
+keypair = JOSE::JWK.generate_key([:ec, "P-256"])
+
+# Get the key as a hash (need to convert from JOSE::Map)
+jwk = keypair.to_map.to_h
+
+# Pretty print the JWK to stdout
+require 'json'
+puts JSON.pretty_generate({
+                            keys: [jwk]
+                          })

data/examples/confidential_client/views/authorized.erb

@@ -0,0 +1,46 @@
+<div class="flex flex-col items-center md:flex md:flex-row md:justify-stretch md:items-center min-h-screen min-w-screen bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">
+  <div class="px-6 pt-4 md:max-w-lg md:grid md:content-center md:justify-items-end md:self-stretch md:w-1/2 md:max-w-fix md:p-4 md:text-right md:dark:border-r md:dark:border-gray-700 md:bg-gray-100 md:dark:bg-gray-800">
+    <h1 class="text-xl md:text-2xl lg:text-5xl md:mt-4 mb-4 font-semibold text-brand">Successfully Authenticated!</h1>
+  </div>
+  <div class="w-full px-6 md:max-w-3xl md:px-12">
+    <div class="space-y-8">
+      <% if session[:error] %>
+        <div class="mb-8 bg-red-50 border-red-700 text-red-700 p-4 rounded-md">
+          <%= session[:error] %>
+          <% session[:error] = nil %>
+        </div>
+      <% end %>
+
+      <% if session[:notice] %>
+        <div class="mb-8 bg-green-50 border-green-700 text-green-700 p-4 rounded-md">
+          <%= session[:notice] %>
+          <% session[:notice] = nil %>
+        </div>
+      <% end %>
+
+      <form method="post" action="/posts" class="flex flex-col py-4 space-y-4">
+        <fieldset>
+          <label for="post-text" class="mb-1 block text-gray-600 dark:text-gray-400 text-sm font-medium">New Bluesky post</label>
+          <textarea id="post-text" name="text" rows="4" maxlength="300" required placeholder="What's up?" class="w-full rounded-lg text-gray-700 dark:text-gray-100 bg-gray-100 dark:bg-gray-800 p-3 outline-none border-solid border-2 border-transparent hover:border-gray-400 focus:border-brand dark:hover:border-gray-500"></textarea>
+        </fieldset>
+        <div>
+          <button type="submit" class="py-2 px-6 rounded-lg cursor-pointer touch-manipulation tracking-wide bg-blue-400 text-white">Post to Bluesky</button>
+        </div>
+      </form>
+
+      <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) %></code></pre>
+      </div>
+
+      <div class="api-test">
+        <p class="mb-1 text-gray-600 dark:text-gray-400 text-sm font-medium">Test API Call Result</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(@api_result) %></code></pre>
+      </div>
+
+      <div class="flex">
+        <a href="/signout" aria-label="Signout" class="py-2 px-6 rounded-lg truncate cursor-pointer touch-manipulation tracking-wide overflow-hidden bg-blue-400 text-white">Sign out</a>
+      </div>
+    </div>
+  </div>
+</div>