atproto_auth 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 32471644f76751fd94dd3e7ede93e8b88c43494a23afa6b5d48196163d2d427c
+  data.tar.gz: 3a92957c782c800c23be621be8ecf85da19c4f3b2145705d79d3b8a9ac898d73
+SHA512:
+  metadata.gz: b19ee50bae30ffba5a45deea718a7587c2db0c02a0f9ead117d2750e87943473ba8758c72fe5f8246d1499cd67bd2996d38f6144396130fd55252fb0e3acf5f8
+  data.tar.gz: a0f12a5e81da053323fd2712f21626bb6e719b45282a26039c480d37bce652998d0180b96c47751c4245792cbdaed8a8f02798790042b6eb50ea9e14feb158b6

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.0
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/MethodLength:
+  Max: 50
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-12-02
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Josh Huckabee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# AtprotoAuth
+
+[![Gem Version](https://badge.fury.io/rb/atproto_auth.svg)](https://badge.fury.io/rb/atproto_auth)
+[![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.
+
+## Features
+
+- Complete AT Protocol OAuth 2.0 implementation
+- Secure by default with mandatory DPoP and PKCE
+- Support for confidential (backend) and public clients
+- Thread-safe session and token management
+- Comprehensive identity resolution and verification
+- Automatic token refresh and session management
+- Robust error handling and recovery mechanisms
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'atproto_auth'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install atproto_auth
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- OpenSSL support
+- For confidential clients: HTTPS-capable domain for client metadata hosting
+
+## Basic Usage
+
+### Configuration
+
+```ruby
+require 'atproto_auth'
+
+AtprotoAuth.configure do |config|
+  # Configure HTTP client settings
+  config.http_client = AtprotoAuth::HttpClient.new(
+    timeout: 10,
+    verify_ssl: true
+  )
+
+  # Set token lifetimes
+  config.default_token_lifetime = 300 # 5 minutes
+  config.dpop_nonce_lifetime = 300  # 5 minutes
+end
+```
+
+### Confidential Client Example
+
+Here's a basic example of using the library in a confidential client application:
+
+```ruby
+# Initialize client with metadata
+client = AtprotoAuth::Client.new(
+  client_id: "https://app.example.com/client-metadata.json",
+  redirect_uri: "https://app.example.com/callback",
+  metadata: {
+    # Your client metadata...
+  }
+)
+
+# Start authorization flow
+auth = client.authorize(
+  handle: "user.bsky.social",
+  scope: "atproto"
+)
+
+# Use auth[:url] to redirect user
+
+# Handle callback
+tokens = client.handle_callback(
+  code: params[:code],
+  state: params[:state],
+  iss: params[:iss]
+)
+
+# Make authenticated requests
+headers = client.auth_headers(
+  session_id: tokens[:session_id],
+  method: "GET",
+  url: "https://api.example.com/resource"
+)
+```
+
+For a complete working example of a confidential client implementation, check out the example application in `examples/confidential_client/`. This Sinatra-based web application demonstrates:
+- Complete OAuth flow implementation
+- Session management
+- DPoP token binding
+- Making authenticated API requests
+- Proper error handling
+- Key generation and management
+
+See `examples/confidential_client/README.md` for setup instructions and implementation details.
+
+### Public Client Example
+
+```ruby
+client = AtprotoAuth::Client.new(
+  client_id: "https://app.example.com/client-metadata.json",
+  redirect_uri: "https://app.example.com/callback"
+)
+
+# Browser will open authorization URL
+auth = client.authorize(
+  handle: "user.bsky.social",
+  scope: "atproto"
+)
+
+# After callback, exchange code for tokens
+tokens = client.handle_callback(
+  code: params[:code],
+  state: params[:state],
+  iss: params[:iss]
+)
+```
+
+## Features In Detail
+
+### Identity Resolution
+
+The library handles the complete AT Protocol identity resolution flow:
+
+- Handle to DID resolution (DNS-based or HTTP fallback)
+- DID document fetching and validation
+- PDS (Personal Data Server) location verification
+- Bidirectional handle verification
+- Authorization server binding verification
+
+### Token & Session Management
+
+Comprehensive token lifecycle management:
+
+- Secure token storage with encryption
+- Automatic token refresh
+- DPoP proof generation and binding
+- Session state tracking
+- Cleanup of expired sessions
+
+### Security Features
+
+Built-in security best practices:
+
+- Mandatory PKCE for all flows
+- DPoP token binding
+- Constant-time token comparisons
+- Thread-safe state management
+- Protection against SSRF attacks
+- Secure token storage
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jhuckabee/atproto_auth.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/examples/confidential_client/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "atproto_auth", path: "../.."
+gem "dotenv"
+gem "faraday"
+gem "json"
+gem "puma"
+gem "rackup"
+gem "sinatra"
+gem "sinatra-contrib"

data/examples/confidential_client/Gemfile.lock

@@ -0,0 +1,84 @@
+PATH
+  remote: ../..
+  specs:
+    atproto_auth (0.1.0)
+      jose (~> 1.2)
+      jwt (~> 2.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.2.0)
+    concurrent-ruby (1.3.4)
+    dotenv (3.1.4)
+    faraday (2.12.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.0)
+      net-http (>= 0.5.0)
+    immutable-ruby (0.2.0)
+      concurrent-ruby (~> 1.1)
+      sorted_set (~> 1.0)
+    jose (1.2.0)
+      base64
+      immutable-ruby
+    json (2.9.0)
+    jwt (2.9.3)
+      base64
+    logger (1.6.2)
+    multi_json (1.15.0)
+    mustermann (3.0.3)
+      ruby2_keywords (~> 0.0.1)
+    net-http (0.6.0)
+      uri
+    nio4r (2.7.4)
+    puma (6.5.0)
+      nio4r (~> 2.0)
+    rack (3.1.8)
+    rack-protection (4.1.1)
+      base64 (>= 0.1.0)
+      logger (>= 1.6.0)
+      rack (>= 3.0.0, < 4)
+    rack-session (2.0.0)
+      rack (>= 3.0.0)
+    rackup (2.2.1)
+      rack (>= 3)
+    rbtree (0.4.6)
+    ruby2_keywords (0.0.5)
+    set (1.1.1)
+    sinatra (4.1.1)
+      logger (>= 1.6.0)
+      mustermann (~> 3.0)
+      rack (>= 3.0.0, < 4)
+      rack-protection (= 4.1.1)
+      rack-session (>= 2.0.0, < 3)
+      tilt (~> 2.0)
+    sinatra-contrib (4.1.1)
+      multi_json (>= 0.0.2)
+      mustermann (~> 3.0)
+      rack-protection (= 4.1.1)
+      sinatra (= 4.1.1)
+      tilt (~> 2.0)
+    sorted_set (1.0.3)
+      rbtree
+      set (~> 1.0)
+    tilt (2.4.0)
+    uri (1.0.2)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  atproto_auth!
+  dotenv
+  faraday
+  json
+  puma
+  rackup
+  sinatra
+  sinatra-contrib
+
+BUNDLED WITH
+   2.5.23

data/examples/confidential_client/README.md

@@ -0,0 +1,110 @@
+# AT Protocol OAuth Confidential Client Example
+
+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.
+
+## 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
+- Shows how to make authenticated API calls to Bluesky
+
+## Requirements
+
+- Ruby 3.0+
+- Bundler
+- A domain name for your application that matches your client metadata
+- SSL certificate for your domain (required 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. Configure your client metadata in `config/client-metadata.json`. Make sure to:
+   - 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 
+```
+
+## Configuration
+
+### 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/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:
+
+```ruby
+export SESSION_SECRET=your-secure-random-string
+```
+
+If not set, a random secret will be generated on startup.
+
+## Running the Application
+
+```bash
+bundle exec rackup
+```
+
+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

data/examples/confidential_client/app.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "sinatra/base"
+require "sinatra/reloader"
+require "atproto_auth"
+require "faraday"
+require "json"
+require "dotenv/load"
+
+# Main app entry point
+class ExampleApp < Sinatra::Base
+  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
+    AtprotoAuth.configure do |config|
+      config.http_client = AtprotoAuth::HttpClient.new(
+        timeout: 10,
+        verify_ssl: true
+      )
+      config.default_token_lifetime = 300
+      config.dpop_nonce_lifetime = 300
+    end
+
+    # Load client metadata
+    metadata_path = File.join(__dir__, "config", "client-metadata.json")
+    metadata = JSON.parse(File.read(metadata_path))
+
+    # Create OAuth client
+    set :oauth_client, AtprotoAuth::Client.new(
+      client_id: metadata["client_id"],
+      redirect_uri: metadata["redirect_uris"][0],
+      metadata: metadata,
+      dpop_key: metadata["jwks"]["keys"][0]
+    )
+  end
+
+  get "/" do
+    erb :index
+  end
+
+  # Start OAuth flow
+  post "/auth" do
+    handle = params[:handle]
+
+    begin
+      # Start authorization flow
+      auth = settings.oauth_client.authorize(
+        handle: handle,
+        scope: "atproto"
+      )
+
+      # Store session ID for callback
+      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 in session
+    session[:tokens] = result
+
+    redirect "/authorized"
+  rescue StandardError => e
+    session[:error] = "Callback failed: #{e.message}"
+    redirect "/"
+  end
+
+  # Show authorized state and test API call
+  get "/authorized" do
+    return redirect "/" unless session[:tokens]
+
+    begin
+      # 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[:tokens][: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
+      erb :authorized
+    rescue StandardError => e
+      session[:error] = "API call failed: #{e.message}"
+      redirect "/"
+    end
+  end
+
+  get "/signout" do
+    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.json

@@ -0,0 +1,25 @@
+{
+  "client_id": "https://mac.tail7f768.ts.net/client-metadata.json",
+  "client_name": "AT Protocol OAuth Ruby Example",
+  "redirect_uris": ["https://mac.tail7f768.ts.net/callback"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "scope": "atproto",
+  "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": "SzXlDk9rSyrZ3b0fVKOWFYY-AFZtld2zElycsmDZ3Xk",
+        "crv": "P-256",
+        "d": "OLJJKo9T9W7taz8gFd5YdsBw8cOpv3p5zPPtv2XaKcM",
+        "kty": "EC",
+        "y": "4hIBLl-BLD1Ypk-mvPxT2OR52ezMs4XI1MGBdhlLLm4"
+      }
+    ]
+  }
+}

data/examples/confidential_client/config.ru

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

data/examples/confidential_client/public/client-metadata.json

@@ -0,0 +1,24 @@
+{
+  "client_id": "https://mac.tail7f768.ts.net/client-metadata.json",
+  "client_name": "AT Protocol OAuth Ruby Example",
+  "redirect_uris": ["https://mac.tail7f768.ts.net/callback"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "scope": "atproto",
+  "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": "SzXlDk9rSyrZ3b0fVKOWFYY-AFZtld2zElycsmDZ3Xk",
+        "crv": "P-256",
+        "kty": "EC",
+        "y": "4hIBLl-BLD1Ypk-mvPxT2OR52ezMs4XI1MGBdhlLLm4"
+      }
+    ]
+  }
+}