authproto 0.3.0.beta1 → 0.3.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77c4682515836e03bc41e1d03724f5ca2a85e65a11655b2af8a8ba09049a73fc
-  data.tar.gz: 0ba9433f0ee89b8617354d1e0245644f421fc1e7264597391b2efa5ebc015f79
+  metadata.gz: a24a4c3d46d68006268cf34364953c33cd23225f2203f2054e7167f8f1470970
+  data.tar.gz: 80287bbe86fc764f9c8b272d090b8736a17ab76470b5ac0fa32903b94dc64cce
 SHA512:
-  metadata.gz: ebbd4f4c9df22f002bbe9be7c02b502bf4fcf5c056d4d0e9290a2c91dde8f03b4756e3b3db9f306cc1b9d5be6be183b88ace24ddb195733c37e92823ec0d5d78
-  data.tar.gz: 3b96e49a8ea9bbb555dab5996c0e6a53f0894616928c4416199f00561f2d9603cf327d0c868cf66501fd7b5982a8ec985d9e27e5032de274ef8daaccad58dbb4
+  metadata.gz: cb4ddce58f52416d16f92dff7f6caf0212c5770addb626610c9459d90894e1c9da4cc664122d359f3a4cdfe572000841cdd3b9daf1ac3defbf472cb3b7fd2474
+  data.tar.gz: 3dd080bf47dc27d1b318784aad020263ab362d2e49f4fbfd4e2716029841de99f0eb7199ac5ba1483208fe1993967b574793ad01fdd41240fd2e5b37d56ddc7f

data/.yardopts

@@ -1,4 +1,5 @@
 --protected
 --no-private
 --markup markdown
+--load misc/yard_attributes.rb
 lib/**/*.rb

data/AGENTS.md

@@ -0,0 +1,80 @@
+### Ruby code:
+
+- always add `# frozen_string_literal: true` at the beginning of Ruby files (both library and tests)
+- keep `require`s and `require_relative`s organized in separate blocks, ordered alphabetically in each:
+
+```
+require 'ipaddr'
+require 'socket'
+require 'timeout'
+require 'uri'
+
+require_relative 'client_metadata'
+require_relative 'validated_uri'
+```
+
+- wrap lines longer than 120 characters
+- for multi-line `if ... end` / `unless ... end` blocks, keep one empty line above/below separating them from the rest of the code in the method, unless it's at the beginning/end of the method, e.g.:
+
+```
+  def validate_grant_types(grant_types)
+    unless grant_types.include?('authorization_code')
+      raise InvalidClientMetadata, "grant_types must include authorization_code"
+    end
+
+    valid_types = %w[authorization_code refresh_token]
+```
+
+- prefer single-quote strings for strings containing identifiers without spaces, like `'code'`, `'access_token'`, and for `require`s
+- prefer double-quote strings for strings containing messages with spaces meant to be shown to the user, e.g. `puts "grant_types must include authorization_code"`
+
+### Unit tests:
+
+- use the classic RSpec `foo.should be_...` matcher style instead of `expect()`
+  - except for calling matchers on blocks as in `expect { ... }.to(not) raise_error...`
+- use the classic `it "should do this"` naming for test cases instead of `it "does this"`
+- use raw `describe` instead of `RSpec.describe` at the top level
+
+### Documentation:
+
+- use YARD with Markdown formatting
+- for class comments, keep one empty # line at the beginning and end, and one empty line above and below that, like:
+
+```
+
+  #
+  # OAuth client implementation class.
+  #
+
+  class ...
+```
+
+- for method comments, leave one empty line above, no empty # starting line, and one empty # trailing line that is immediately followed by the method definition, like:
+
+```
+
+  # Reads tokens for a session with a currently valid access token.
+  #
+  # @param session_id [String] session identifier
+  # @return [Hash{Symbol => String, Integer, nil}, nil] token details, or `nil` for missing/unauthorized sessions
+  #
+  def get_tokens(session_id)
+```
+
+- for properties, and also for one-liner classes like error types, use a compact style like:
+
+```
+
+  # Identifier of the session associated with the failure, if known.
+  # @return [String, nil]
+  attr_reader :session_id
+
+  # Error raised when token operations fail
+  class TokenError < Error; end
+
+```
+
+
+### Running code:
+
+- make sure you don't use the ancient system Ruby 2.6, but a version supported by the library (my installation uses `asdf`)

data/CHANGELOG.md

@@ -1,34 +1,75 @@
-## [0.2.5] - 2024-12-13
+## [0.3.0.beta2] – 2026-10-31 👻
+
+- private keys for signing are now passed separately as `signing_key:` instead of being taken from the same `jwks` in the metadata that holds public keys
+- generate localhost metadata from `client_id` params
+- `confidential_client`: validate `SESSION_SECRET` before start and throw an error early
+- additional validations for URLs, resource server and authorization server metadata, and PAR request and response
+- set `code_challenge_method` in the PAR request automatically to `S256`
+- various renames, refactors, cleanups
+- encode '*' in the authorization URL – unencoded asterisk might break click-to-open-URL in some terminals
+- strip query part from URLs in `htu` in the DPoP proof generator
+- keep existing query part in the PAR authorization endpoint when adding params to it
+- verify that all scopes passed during authorization are declared in client metadata
+- don't reuse client assertion JWT on retried requests
+- POST redirects are not allowed, GET redirects are disabled by default
+
+## [0.3.0.beta1], as AuthProto – 2026-10-28
+
+- modernized code
+- various renames, refactors, cleanups
+- removed some unused code
+- removed strict dependency on the Redis gem
+- added alternative SQLite storage
+- added HTTP client version that allows `http://` connections
+- added experimental Minisky adapter and `minisky_console` example
+- added temporary in-process `localhost` HTTP server for receiving callbacks inside `irb`
+- additional validations for request IPs and URLs, responses, and client metadata
+- fixed `confidential_example` running on localhost
+- updated `confidential_example` with a UI for making a test post to Bluesky
+- updated examples to use `oauth-client-metadata.json` instead of `client-metadata.json`
+- converted test suite to RSpec
+- replaced `Identity` module with DIDKit
+- fixed randomly generated encryption key not being shared between different parts of the app
+- fixed some token refresh code failing due to wrong exception names
+- don't try to add client assertions for public clients
+- switched to JWT gem version 3.x
+
+
+---
+
+# Earlier releases as `atproto_auth`:
+
+## [0.2.5] – 2024-12-13
 
 Fixed:
 
 - Additional token refresh edge case handling
 
-## [0.2.4] - 2024-12-13
+## [0.2.4] – 2024-12-13
 
 Fixed:
 
 - Token refresh now correctly handles expired tokens
 
-## [0.2.2] - 2024-12-12
+## [0.2.2] – 2024-12-12
 
 Added:
 
 - Added support for did:web users
 
-## [0.2.1] - 2024-12-11
+## [0.2.1] – 2024-12-11
 
 Fixed:
 
 - Fixed a bug with access token hash generation
 
-## [0.2.0] - 2024-12-10
+## [0.2.0] – 2024-12-10
 
 Added:
 
 - Client#handle_callback now returns session did as part of the response
 
-## [0.1.0] - 2024-12-07
+## [0.1.0] – 2024-12-07
 
 Added:
 
@@ -47,6 +88,6 @@ Changed:
 - Session and token management now use configured storage backend
 - Improved thread safety for all storage operations
 
-## [0.0.1] - 2024-12-05
+## [0.0.1] – 2024-12-05
 
 - Initial release

data/README.md

@@ -103,6 +103,13 @@ Client metadata must explicitly set `token_endpoint_auth_method` to `none` for
 public clients or `private_key_jwt` for confidential clients. Omitting it defaults
 to `client_secret_basic` in OAuth metadata, which this library does not support.
 
+For localhost development, `Metadata::ClientMetadata.from_url` generates virtual metadata
+without making an HTTP request. It defaults to native public authentication,
+the `atproto` scope, and redirects `http://127.0.0.1/` and `http://[::1]/`.
+The client ID query can specify one `scope` parameter and multiple `redirect_uri`
+parameters, encoded using `URI.encode_www_form`. These values are decoded and
+validated; the original client ID is preserved exactly.
+
 ### Storage Backends
 
 The library supports multiple storage backends for managing OAuth state:
@@ -190,11 +197,24 @@ end
 
 Here's a basic example of using the library in a confidential client application:
 
+Supply the private EC P-256 client-authentication JWK through `signing_key:`,
+separately from metadata. It must have a nonempty `kid` and permit ES256 signing.
+Metadata's `jwks` contains only public keys; the client checks that the matching
+public key and `kid` are advertised and active. A public key may declare
+`use: "sig"` or `key_ops: ["verify"]`.
+Other advertised public keys may serve other purposes, such as encryption;
+the matching authentication key must permit signature verification.
+
+With `jwks_uri`, the client still uses your separate private signing key. It does
+not fetch that URL or check the advertised key locally; the authorization server
+fetches it to verify assertions.
+
 ```ruby
 # Initialize client with metadata
 client = AuthProto::Client.new(
   client_id: "https://app.example.com/oauth-client-metadata.json",
   redirect_uri: "https://app.example.com/callback",
+  signing_key: JSON.parse(File.read("config/keys.json")).fetch("keys").first,
   metadata: {
     # Your client metadata...
   }

data/examples/confidential_client/.gitignore

@@ -1,5 +1,6 @@
 .env
 /config/client-metadata.json
+/config/oauth-client-metadata.json
 /config/keys.json
+/config/public-keys.json
 /db/
-/public/client-metadata.json

data/examples/confidential_client/Gemfile.lock

@@ -1,16 +1,20 @@
 PATH
   remote: ../..
   specs:
-    authproto (0.2.5)
+    authproto (0.3.0.beta1)
+      didkit (~> 0.5.0)
       jose (~> 1.2)
       jwt (~> 3.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    base58 (0.2.3)
     base64 (0.3.0)
     concurrent-ruby (1.3.8)
     connection_pool (3.0.2)
+    didkit (0.5.0)
+      base58 (~> 0.2)
     dotenv (3.2.0)
     faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)

data/examples/confidential_client/README.md

@@ -43,7 +43,7 @@ bundle install
 3. Generate EC keys for client authentication:
 
 ```bash
-bundle exec ruby scripts/generate_keys.rb > config/keys.json
+bundle exec ruby scripts/generate_keys.rb
 ```
 
 4. Generate session & encryption keys:
@@ -64,7 +64,7 @@ SESSION_SECRET=<hex value from second command>
      ```
    - 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
+   - Copy the public JWKS from `config/public-keys.json` (not `config/keys.json`, which is the private keys) into the `jwks` field in oauth-client-metadata.json.
    - 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:

data/examples/confidential_client/app.rb

@@ -12,6 +12,9 @@ require 'faraday'
 require 'sinatra/base'
 require 'sinatra/reloader'
 
+session_secret = ENV.fetch("SESSION_SECRET") { SecureRandom.hex(32) }
+raise "SESSION_SECRET must be at least 64 characters long (got: #{session_secret})" unless session_secret.length >= 64
+
 # Main app entry point
 class ExampleApp < Sinatra::Base
   def check_stored_session(session_id)
@@ -54,20 +57,24 @@ class ExampleApp < Sinatra::Base
     metadata_path = File.join(__dir__, "config", "oauth-client-metadata.json")
     metadata = JSON.parse(File.read(metadata_path))
 
-    client_id = metadata["client_id"]
+    client_id = metadata['client_id']
 
     if client_id.chomp("/") == "http://localhost"
-      scope = CGI.escape(metadata["scope"])
-      redirect_uri = CGI.escape(metadata["redirect_uris"][0])
+      scope = CGI.escape(metadata['scope'])
+      redirect_uri = CGI.escape(metadata['redirect_uris'][0])
       client_id += "?scope=#{scope}&redirect_uri=#{redirect_uri}"
     end
 
+    # Private client-authentication keys are kept outside public metadata.
+    signing_key = JSON.parse(File.read(File.join(__dir__, "config", "keys.json")))["keys"].first
+
     # Create OAuth client
     set :oauth_client, AuthProto::Client.new(
       client_id: client_id,
-      redirect_uri: metadata["redirect_uris"][0],
+      redirect_uri: metadata['redirect_uris'][0],
       metadata: metadata,
-      dpop_key: metadata["jwks"]["keys"][0]
+      signing_key: signing_key,
+      dpop_key: signing_key
     )
   end
 
@@ -78,7 +85,7 @@ class ExampleApp < Sinatra::Base
   use Rack::Session::Cookie,
       key: "atproto.session",
       expire_after: 86_400, # 1 day in seconds
-      secret: ENV.fetch("SESSION_SECRET") { SecureRandom.hex(32) },
+      secret: session_secret,
       secure: ENV.fetch("RACK_ENV", "development") == "production",  # Only send over HTTPS
       httponly: true,     # Not accessible via JavaScript
       same_site: :lax     # CSRF protection
@@ -115,14 +122,7 @@ class ExampleApp < Sinatra::Base
     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
+    # This file contains only the public counterparts of config/keys.json.
     JSON.generate(metadata)
   end
 
@@ -190,7 +190,7 @@ class ExampleApp < Sinatra::Base
       # Get auth headers for request
       headers = settings.oauth_client.auth_headers(
         session_id: session_id,
-        method: "GET",
+        method: 'GET',
         url: "https://api.bsky.app/xrpc/com.atproto.identity.resolveHandle"
       )
 
@@ -236,7 +236,7 @@ class ExampleApp < Sinatra::Base
 
     headers = settings.oauth_client.auth_headers(
       session_id: session_id,
-      method: "POST",
+      method: 'POST',
       url: endpoint
     )
 
@@ -273,7 +273,7 @@ class ExampleApp < Sinatra::Base
   get "/signout" do
     if session[:oauth_session_id]
       # Clean up stored session
-      settings.oauth_client.remove_session(session[:oauth_session_id])
+      settings.oauth_client.delete_session(session[:oauth_session_id])
     end
 
     session.clear

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

@@ -16,7 +16,6 @@
         "kid": "key-1",
         "x": "...",
         "crv": "P-256",
-        "d": "...",
         "kty": "EC",
         "y": "..."
       }

data/examples/confidential_client/scripts/generate_keys.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
 require 'jose'
+require 'json'
 
-# Generate a new EC key using P-256 curve
-keypair = JOSE::JWK.generate_key([:ec, "P-256"])
+key = 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
+private_jwk = key.to_map.to_h.merge("kid" => "key-1", "use" => "sig")
+public_jwk = key.to_public.to_map.to_h.merge("kid" => "key-1", "use" => "sig")
 
-# Pretty print the JWK to stdout
-require 'json'
-puts JSON.pretty_generate({
-                            keys: [jwk]
-                          })
+config_dir = File.expand_path('../config', __dir__)
+private_path = File.join(config_dir, 'keys.json')
+
+File.open(private_path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+  file.chmod(0o600)
+  file.write(JSON.pretty_generate('keys' => [private_jwk]) + "\n")
+end
+
+File.write(File.join(config_dir, 'public-keys.json'), JSON.pretty_generate('keys' => [public_jwk]) + "\n")
+
+puts "Private keys saved to config/keys.json; publish only config/public-keys.json in metadata."

data/examples/minisky_console/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    authproto (0.2.5)
+    authproto (0.3.0.beta1)
       didkit (~> 0.5.0)
       jose (~> 1.2)
       jwt (~> 3.3)
@@ -91,7 +91,7 @@ DEPENDENCIES
   sqlite3
 
 CHECKSUMS
-  authproto (0.2.5)
+  authproto (0.3.0.beta1)
   base58 (0.2.3) sha256=fda5c5d3bda8b429ad0d1a5309c2d1e488ba46f0a2ab99a639890f26c61bf3be
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bundler (4.0.23) sha256=407ba8a1d928f412847f819aa5f8b6aef7c59fb51feb517112af8a165487287b

data/examples/minisky_console/localhost.rb

@@ -1,3 +1,5 @@
+require 'authproto/insecure_http_client'
+require 'authproto/localhost_server'
 require 'authproto/minisky'
 require 'dotenv/load'
 require 'uri'
@@ -10,41 +12,22 @@ AuthProto.configure do |config|
   )
 end
 
-$metadata = {
-  'application_type' => 'native',
-  'client_id' => 'http://localhost/',
-  'client_name' => 'AT Protocol OAuth Ruby Example',
-  'redirect_uris' => ['http://127.0.0.1:9292/callback'],
-  'grant_types' => ['authorization_code', 'refresh_token'],
-  'response_types' => ['code'],
-  'scope' => 'atproto repo:app.bsky.feed.post rpc:app.bsky.feed.getTimeline?aud=*',
-  'token_endpoint_auth_method' => 'none',
-  'dpop_bound_access_tokens' => true,
-}
-
-$client_id = $metadata['client_id'] + '?' + URI.encode_www_form({
-  redirect_uri: $metadata['redirect_uris'][0],
-  scope: $metadata['scope']
-})
-
-$metadata['client_id'] = $client_id
+REDIRECT_URI = 'http://127.0.0.1:9292/callback'
+SCOPE = 'atproto repo:app.bsky.feed.post rpc:app.bsky.feed.getTimeline?aud=*'
+CLIENT_ID = 'http://localhost/?' + URI.encode_www_form({ redirect_uri: REDIRECT_URI, scope: SCOPE })
 
 def create_client(pds)
-  Minisky::OAuthClient.new(pds,
-    client_id: $client_id,
-    redirect_uri: $metadata['redirect_uris'][0],
-    metadata: $metadata
-  )
+  Minisky::OAuthClient.new(pds, client_id: CLIENT_ID, redirect_uri: REDIRECT_URI)
 end
 
 def authorize(client)
-  auth = client.authorize(pds_url: "https://#{client.host}", scope: $metadata['scope'])
+  auth = client.authorize(pds: "https://#{client.host}", scope: SCOPE)
 
   puts "Open this URL in the browser and complete authorization:"
   puts auth[:url]
   puts
 
-  AuthProto::LocalhostServer.start($metadata) do |json|
+  AuthProto::LocalhostServer.start(client.oauth_client.client_metadata) do |json|
     client.handle_callback(**json)
   end
 

data/examples/minisky_console/production.rb

@@ -18,7 +18,7 @@ def create_client(server_hostname, pds)
 end
 
 def authorize(client)
-  auth = client.authorize(pds_url: "https://#{client.host}", scope: client.oauth_client.client_metadata.scope)
+  auth = client.authorize(pds: "https://#{client.host}", scope: client.oauth_client.client_metadata.scope)
 
   puts "Open this URL in the browser and complete authorization:"
   puts auth[:url]