authproto 0.3.0.beta2 → 0.3.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a24a4c3d46d68006268cf34364953c33cd23225f2203f2054e7167f8f1470970
-  data.tar.gz: 80287bbe86fc764f9c8b272d090b8736a17ab76470b5ac0fa32903b94dc64cce
+  metadata.gz: 61754b5e7342299c331cabc76c9585ef1f7b1398d0eae4eed252f5d9a2a019bd
+  data.tar.gz: 5879610764cb56945d3fc260ed0538f5cdaaabfaec4982af38408290a34a547f
 SHA512:
-  metadata.gz: cb4ddce58f52416d16f92dff7f6caf0212c5770addb626610c9459d90894e1c9da4cc664122d359f3a4cdfe572000841cdd3b9daf1ac3defbf472cb3b7fd2474
-  data.tar.gz: 3dd080bf47dc27d1b318784aad020263ab362d2e49f4fbfd4e2716029841de99f0eb7199ac5ba1483208fe1993967b574793ad01fdd41240fd2e5b37d56ddc7f
+  metadata.gz: fe5452fe5a70e70bb3c100b30656eb63fcca61dec4617ccec1413eff03e952156523f39f479096dc2fa23467ad7fa792639571ce5d46a9985049bbb7c0806e82
+  data.tar.gz: 2c6fb2275d03bf3b812a731841fe2b7364d41b8799f5e937a4c4191d7da0b843d68bd5d67a941dea4f6d4b0590320cd757041f518a3c1416000888ca165583d5

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.3.0.beta3] - 2026-11-02
+
+- session's state token is deleted on successfully completed authentication (i.e. `handle_callback`)
+- pending sessions (that haven't completed authentication) are stored with a TTL of 15 minutes by default, and expire after that; this can be changed through `pending_session_ttl` in the global configuration
+- completed but non-renewable session (without a refresh token) are set with a TTL such that they expire when their access token expires
+- fixed deleting a session's state token in `Client#delete_session`
+- DPoP keys are now connected to a specific session and saved & restored with it; multiple sessions used from the same `AuthProto::Client` will have proofs signed with different DPoP keys, and the keys are automatically restored and don't need to be passed in the argument to `Client` or `Minisky::OAuthClient`
+- DPoP nonces are now stored separately per session and per service, not just one per service
+- the `minisky_console` example now supports restoring previous sessions using session ID
+- for security, `Client#handle_callback` and `Minisky::OAuthClient#handle_callback` now require an `expected_session_id:` argument, where you need to pass a session ID previously saved from the output of `authorize` in browser storage or a local variable; token callback is rejected if the passed saved session ID doesn't match the ID of the session looked up using the state token from the callback
+- added `Session#pending?` and `Session#tokens_valid?`
+- removed unused `default_token_lifetime` and `encryption` configuration settings
+- added `client_assertion_lifetime` configuration setting
+- nonce manager now uses the global `dpop_nonce_lifetime` ttl setting by default
+- simplified the DPoP public key JWT included in headers
+- improved validation of nonce-related headers & responses, client metadata, refresh errors, and assertion signing keys
+- sessions store the client assertion signing key's ID in the metadata and check it when deserialized
+- various refactors and reorganizations
+
 ## [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

data/README.md

@@ -62,10 +62,12 @@ AuthProto.configure do |config|
     verify_ssl: true
   )
 
-  # Set token lifetimes
-  config.default_token_lifetime = 300 # 5 minutes
+  # Set the default nonce cache lifetime (seconds), used by newly created clients.
   config.dpop_nonce_lifetime = 300  # 5 minutes
 
+  # Set client assertion validity (seconds), used for each newly generated JWT.
+  config.client_assertion_lifetime = 300  # 5 minutes
+
   # Configure storage backend (default is in-memory)
   config.storage = AuthProto::Storage::Memory.new
 end
@@ -75,6 +77,16 @@ gem 'sqlite3', '~> 2.9'
 gem 'redis', '~> 5.4'
 ```
 
+Set `dpop_nonce_lifetime` to a positive integer before creating clients or nonce
+managers. Its default is 300 seconds. An explicit `NonceManager.new(ttl: ...)` or
+`DPoP::Client.new(nonce_ttl: ...)` overrides it. Existing managers retain the
+lifetime chosen at initialization.
+
+`client_assertion_lifetime` must also be a positive integer and defaults to 300
+seconds. It is read for each assertion, including by existing clients and signers.
+An explicit `ClientAssertion#generate_jwt(lifetime: ...)` overrides the configured
+default. This controls assertion validity, not access-token or session lifetime.
+
 ### Local HTTP debugging
 
 For debugging a flow that needs both local HTTP and remote HTTPS (handle/PLC
@@ -114,6 +126,19 @@ validated; the original client ID is preserved exactly.
 
 The library supports multiple storage backends for managing OAuth state:
 
+Pending authorization sessions and their state-token lookups expire after 15 minutes by default.
+Configure the lifetime in seconds with a positive integer:
+
+```ruby
+AuthProto.configure do |config|
+  config.pending_session_ttl = 900
+end
+```
+
+Updating a pending session preserves its original deadline. Successful authorization removes
+the pending deadline and state-token lookup. Authenticated sessions without refresh tokens
+expire with their access token; sessions with refresh tokens have no automatic storage expiry.
+
 #### In-Memory Storage (Default)
 
 ```ruby
@@ -193,6 +218,42 @@ class CustomStorage < AuthProto::Storage::Interface
 end
 ```
 
+### DPoP Session Keys
+
+Each new OAuth session generates its own DPoP key before PAR. The session serializer
+stores its private JWK with the session and encrypts the private `d` component.
+Restoring the session restores that same key for code exchange, refresh and API
+requests. Configure persistent storage and a stable `ATPROTO_MASTER_KEY` to retain
+sessions across application restarts.
+
+`Client` and the Minisky integration no longer accept `dpop_key:`. Restore sessions
+by their session ID; no separate key export or constructor argument is needed.
+`Client#dpop_client` remains shared and accepts `session:` when generating proofs.
+Its `ProofGenerator` accepts `key_set:` per call. Nonces are stored separately with
+TTLs, indexed by session ID and server origin. URLs on the same origin share a
+nonce within that session; other sessions and origins have independent nonces.
+`DPoP::Client#with_nonce_handling(session, url) { ... }` runs a request block,
+processes its response, and runs it once more if the server sends a nonce challenge.
+The block must generate a fresh proof and send the request on each invocation.
+The helper returns the final response; other errors and exceptions are left to
+its caller. PAR, code exchange, and refresh use this helper.
+
+`DPoP::Client#process_response` accepts the whole HTTP response hash and requires
+`server_url:` and `session_id:` to update the requesting
+session's nonce. When sending requests without `with_nonce_handling`, call it
+for every DPoP response, including successes, failures, and retry responses; missing or empty `DPoP-Nonce` headers raise an error. Nonces must use RFC 9449's
+`NQCHAR` syntax; malformed values and duplicate nonce headers are rejected.
+`has_nonce_error?` recognizes HTTP 400 JSON nonce errors and HTTP 401 DPoP
+authentication challenges. It does not update the nonce or send a retry.
+Direct nonce manager calls to `get`, `update`, and `clear` also
+require `server_url:` and `session_id:` keywords. Old per-server cache entries are
+ignored and expire normally; a missing nonce can be obtained through a server challenge.
+
+Serialized sessions from older versions that lack a private DPoP key cannot be
+restored: start authorization again. Loading never generates a replacement key for
+an existing session. Client-authentication signing keys remain separate from these
+per-session DPoP keys.
+
 ### Confidential Client Example
 
 Here's a basic example of using the library in a confidential client application:
@@ -202,6 +263,7 @@ 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"]`.
+Each key in an inline `jwks` must have a distinct, case-sensitive `kid`.
 Other advertised public keys may serve other purposes, such as encryption;
 the matching authentication key must permit signature verification.
 
@@ -209,6 +271,21 @@ With `jwks_uri`, the client still uses your separate private signing key. It doe
 not fetch that URL or check the advertised key locally; the authorization server
 fetches it to verify assertions.
 
+New confidential-client sessions record the signing key's `kid` as `signing_key_id`
+and its RFC 7638 SHA-256 thumbprint as `signing_key_thumbprint` before PAR. Both
+values persist through callbacks and refreshes without including the private
+client-authentication key. The session manager returns `nil` if the key ID is
+unsupported or its thumbprint no longer matches, leaving stored data intact.
+`Client` supplies a key-ID-to-thumbprint mapping derived from its configured
+private signing key, rather than the public keys advertised in metadata.
+Sessions with a recorded key ID but no thumbprint must authorize again.
+Clients still accept one `signing_key:`; automatic key selection and rotation
+are not implemented.
+
+Public-client sessions have no signing key ID. Older serialized sessions without
+this field remain readable and use the configured signing key without an ID check;
+their original key ID cannot be inferred from the stored session.
+
 ```ruby
 # Initialize client with metadata
 client = AuthProto::Client.new(
@@ -226,14 +303,17 @@ auth = client.authorize(
   scope: "atproto"
 )
 
-# Use auth[:url] to redirect user
+# Retain the expected ID in this browser's session before redirecting to auth[:url].
+session[:pending_oauth_session_id] = auth.fetch(:session_id)
 
 # Handle callback
 tokens = client.handle_callback(
   code: params[:code],
   state: params[:state],
-  iss: params[:iss]
+  iss: params[:iss],
+  expected_session_id: session[:pending_oauth_session_id]
 )
+session.delete(:pending_oauth_session_id)
 
 # Make authenticated requests
 headers = client.auth_headers(
@@ -267,14 +347,37 @@ auth = client.authorize(
   scope: "atproto"
 )
 
+# Retain this in the initiating browser session, or locally for a native app.
+session[:pending_oauth_session_id] = auth.fetch(:session_id)
+
 # After callback, exchange code for tokens
 tokens = client.handle_callback(
   code: params[:code],
   state: params[:state],
-  iss: params[:iss]
+  iss: params[:iss],
+  expected_session_id: session[:pending_oauth_session_id]
 )
+session.delete(:pending_oauth_session_id)
 ```
 
+### Binding Callbacks to the Initiating Login
+
+`handle_callback` requires `expected_session_id:` for both `AuthProto::Client` and
+`Minisky::OAuthClient`. Retain the `:session_id` returned by `authorize` in the
+initiating browser's session, then supply that retained ID on callback. Missing,
+`nil`, empty, or mismatched IDs are rejected before any token exchange.
+
+Never take the expected ID from callback parameters or derive it from the returned
+`state`: that would not establish which browser started the login. A shared web
+client's `session_id` is not a substitute for per-browser session storage. Remove
+the pending association after successful completion. For concurrent login attempts,
+retain each expected ID separately and verify membership in that browser's pending attempts.
+
+Native and console apps can retain the ID in the local context for that login
+attempt, as the localhost example does. The console example's manual callback helper
+uses the ID remembered by its local Minisky client. When upgrading existing callers,
+add this required keyword using the retained authorization result.
+
 ## Features In Detail
 
 ### Identity Resolution

data/examples/confidential_client/README.md

@@ -168,6 +168,16 @@ export SESSION_SECRET=your-secure-random-string
 
 If not set, a random secret will be generated on startup (not recommended for production).
 
+The app stores the ID returned by `authorize` as `session[:pending_oauth_session_id]`
+before redirecting. On callback, it passes that browser-session value as the required
+`expected_session_id:` argument to `handle_callback`. The library rejects a missing
+or mismatched ID before exchanging the code. After success, the app removes the
+pending association and remembers the authenticated session separately.
+
+The expected ID must come from the initiating browser session, never from the
+callback URL or by looking up the returned `state`. This example supports one pending
+login per browser; starting another replaces the previous pending association.
+
 ## Running the Application
 
 ### Development

data/examples/confidential_client/app.rb

@@ -34,7 +34,6 @@ class ExampleApp < Sinatra::Base
     # 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")
@@ -73,8 +72,7 @@ class ExampleApp < Sinatra::Base
       client_id: client_id,
       redirect_uri: metadata['redirect_uris'][0],
       metadata: metadata,
-      signing_key: signing_key,
-      dpop_key: signing_key
+      signing_key: signing_key
     )
   end
 
@@ -137,8 +135,8 @@ class ExampleApp < Sinatra::Base
         scope: "atproto repo:app.bsky.feed.post"
       )
 
-      # Store session ID in user's browser session
-      session[:oauth_session_id] = auth[:session_id]
+      # Bind the pending authorization attempt to this browser, separately from any active login.
+      session[:pending_oauth_session_id] = auth[:session_id]
 
       # Redirect to authorization URL
       redirect auth[:url]
@@ -154,10 +152,13 @@ class ExampleApp < Sinatra::Base
     result = settings.oauth_client.handle_callback(
       code: params[:code],
       state: params[:state],
-      iss: params[:iss]
+      iss: params[:iss],
+      expected_session_id: session[:pending_oauth_session_id]
     )
 
-    # Store tokens
+    session.delete(:pending_oauth_session_id)
+
+    # Remember the authenticated session ID.
     session[:oauth_session_id] = result[:session_id]
 
     redirect "/authorized"

data/examples/confidential_client/scripts/generate_keys.rb

@@ -6,7 +6,7 @@ require 'json'
 key = JOSE::JWK.generate_key([:ec, "P-256"])
 
 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")
+public_jwk = key.to_public_map.to_h.merge("kid" => "key-1", "use" => "sig")
 
 config_dir = File.expand_path('../config', __dir__)
 private_path = File.join(config_dir, 'keys.json')

data/examples/minisky_console/Gemfile.lock

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

data/examples/minisky_console/README.md

@@ -62,12 +62,19 @@ Once the browser redirects to the callback URL after your approval, the console
 
 ```
 Authentication complete ✓
+Your session id: ......
 ```
 
+The callback block supplies `expected_session_id:` from the authorization result
+retained locally before opening the browser. The library checks it before exchanging the code.
+
 Then, you can run `client.get_request(...)` and `client.post_request(...)` to perform authorized actions on the given account. By default, the example asks for permissions `repo:app.bsky.feed.post` and `rpc:app.bsky.feed.getTimeline?aud=*`, which allow calling `getTimeline` and creating/modifying posts.
 
-(Note, the session is currently lost when you close the console.)
+To restore a session after closing and reopening the console, write down the sesion ID printed after successful authentication, and then pass it back to the `OAuthClient` constructor:
 
+```rb
+client = create_client('your.pds.hostname.here', session_id: '123456-789-abc-...')
+```
 
 ## Production use
 
@@ -103,10 +110,22 @@ Copy the printed command back to the console:
 handle_callback(client, { ... })
 ```
 
+Use the same local `client` that started this authorization attempt. The helper
+passes its remembered session ID as `expected_session_id:` and forwards only the
+`code`, `state`, and `iss` callback parameters. The expected ID is not supplied by
+the callback page. Each console client supports one current login attempt.
+
 This will print:
 
 ```
 Authentication complete ✓
+Your session id: ......
 ```
 
 Then, you can run `client.get_request(...)` and `client.post_request(...)` to perform authorized actions on the given account.
+
+Again, to restore a session after closing and reopening the console, write down the sesion ID printed after successful authentication, and then pass it back to the `OAuthClient` constructor:
+
+```rb
+client = create_client('your.server.hostname', 'your.pds.hostname', session_id: '123456-789-abc-...')
+```

data/examples/minisky_console/localhost.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'authproto/insecure_http_client'
 require 'authproto/localhost_server'
 require 'authproto/minisky'
@@ -16,8 +18,8 @@ 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: REDIRECT_URI)
+def create_client(pds, session_id: nil)
+  Minisky::OAuthClient.new(pds, client_id: CLIENT_ID, redirect_uri: REDIRECT_URI, session_id: session_id)
 end
 
 def authorize(client)
@@ -28,7 +30,7 @@ def authorize(client)
   puts
 
   AuthProto::LocalhostServer.start(client.oauth_client.client_metadata) do |json|
-    client.handle_callback(**json)
+    client.handle_callback(**json, expected_session_id: auth.fetch(:session_id))
   end
 
   puts "Authentication complete ✓"

data/examples/minisky_console/production.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'authproto/minisky'
 require 'dotenv/load'
 require 'uri'
@@ -10,10 +12,11 @@ AuthProto.configure do |config|
   )
 end
 
-def create_client(server_hostname, pds)
+def create_client(server_hostname, pds, session_id: nil)
   Minisky::OAuthClient.new(pds,
     client_id: "https://#{server_hostname}/oauth-client-metadata.json",
-    redirect_uri: "https://#{server_hostname}/callback"
+    redirect_uri: "https://#{server_hostname}/callback",
+    session_id: session_id
   )
 end
 
@@ -25,7 +28,10 @@ def authorize(client)
 end
 
 def handle_callback(client, json)
-  result = client.handle_callback(**json)
+  # Use the ID retained by this local client, not a value copied from the callback page.
+  result = client.handle_callback(
+    **json.slice(:code, :state, :iss), expected_session_id: client.session_id
+  )
 
   puts "Authentication complete ✓"
   puts "Your session id: #{result[:session_id]}"