authproto 0.3.0.beta4 → 0.3.0.beta5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +21 -0
  3. data/README.md +474 -311
  4. data/examples/basic_webapp/Gemfile +14 -0
  5. data/examples/{confidential_client → basic_webapp}/Gemfile.lock +1 -1
  6. data/examples/basic_webapp/README.md +300 -0
  7. data/examples/basic_webapp/app.rb +351 -0
  8. data/examples/basic_webapp/config/oauth-client-metadata.localhost.json +11 -0
  9. data/examples/basic_webapp/public/styles.css +346 -0
  10. data/examples/basic_webapp/scripts/generate_keys.rb +35 -0
  11. data/examples/basic_webapp/views/authorized.erb +48 -0
  12. data/examples/basic_webapp/views/index.erb +48 -0
  13. data/examples/{confidential_client → basic_webapp}/views/layout.erb +2 -2
  14. data/examples/bookmarks/Gemfile +16 -0
  15. data/examples/bookmarks/Gemfile.lock +158 -0
  16. data/examples/bookmarks/README.md +170 -0
  17. data/examples/bookmarks/Rakefile +23 -0
  18. data/examples/bookmarks/app/account.rb +16 -0
  19. data/examples/bookmarks/app/bookmark.rb +89 -0
  20. data/examples/bookmarks/app/init.rb +26 -0
  21. data/examples/bookmarks/app/oauth.rb +43 -0
  22. data/examples/bookmarks/app/server.rb +184 -0
  23. data/examples/bookmarks/config/oauth-client-metadata.localhost.json +11 -0
  24. data/examples/bookmarks/config/oauth-client-metadata.production.json +19 -0
  25. data/examples/bookmarks/config.ru +5 -0
  26. data/examples/bookmarks/db/migrate/20261107004141_create_bookmarks.rb +27 -0
  27. data/examples/bookmarks/db/schema.rb +33 -0
  28. data/examples/bookmarks/public/styles.css +59 -0
  29. data/examples/bookmarks/scripts/generate_keys.rb +35 -0
  30. data/examples/bookmarks/views/bookmarks.erb +86 -0
  31. data/examples/bookmarks/views/index.erb +17 -0
  32. data/examples/bookmarks/views/layout.erb +20 -0
  33. data/examples/minisky_console/Gemfile.lock +2 -2
  34. data/examples/minisky_console/README.md +29 -25
  35. data/examples/minisky_console/app.rb +3 -3
  36. data/examples/minisky_console/localhost.rb +5 -7
  37. data/examples/minisky_console/production.rb +6 -8
  38. data/lib/authproto/client.rb +413 -126
  39. data/lib/authproto/configuration.rb +1 -1
  40. data/lib/authproto/dpop/client.rb +28 -25
  41. data/lib/authproto/dpop/key_set.rb +2 -0
  42. data/lib/authproto/dpop/nonce_manager.rb +23 -20
  43. data/lib/authproto/dpop/proof_generator.rb +6 -3
  44. data/lib/authproto/dpop/stored_nonce.rb +7 -5
  45. data/lib/authproto/dpop.rb +2 -0
  46. data/lib/authproto/encryption.rb +2 -0
  47. data/lib/authproto/http_client.rb +5 -5
  48. data/lib/authproto/http_helpers.rb +6 -0
  49. data/lib/authproto/metadata/authorization_server.rb +4 -3
  50. data/lib/authproto/metadata/client_metadata.rb +6 -2
  51. data/lib/authproto/metadata/resource_server.rb +4 -3
  52. data/lib/authproto/minisky.rb +120 -33
  53. data/lib/authproto/par/client.rb +4 -2
  54. data/lib/authproto/par/client_assertion.rb +4 -1
  55. data/lib/authproto/par/request.rb +2 -0
  56. data/lib/authproto/par/response.rb +2 -0
  57. data/lib/authproto/par.rb +2 -0
  58. data/lib/authproto/pkce.rb +2 -0
  59. data/lib/authproto/serialization/session.rb +2 -2
  60. data/lib/authproto/serialization/stored_nonce.rb +2 -2
  61. data/lib/authproto/state/session.rb +8 -41
  62. data/lib/authproto/state/session_info.rb +150 -0
  63. data/lib/authproto/state/session_manager.rb +18 -15
  64. data/lib/authproto/state.rb +3 -1
  65. data/lib/authproto/storage/interface.rb +10 -0
  66. data/lib/authproto/storage/key_builder.rb +3 -3
  67. data/lib/authproto/storage/memory.rb +24 -18
  68. data/lib/authproto/storage/sqlite.rb +14 -0
  69. data/lib/authproto/token/refresh.rb +2 -2
  70. data/lib/authproto/token/response.rb +2 -0
  71. data/lib/authproto/token/revocation.rb +4 -2
  72. data/lib/authproto/version.rb +1 -1
  73. data/lib/authproto.rb +6 -3
  74. data/sig/authproto/client.rbs +33 -10
  75. data/sig/authproto/dpop/client.rbs +9 -3
  76. data/sig/authproto/dpop/nonce_manager.rbs +6 -6
  77. data/sig/authproto/dpop/proof_generator.rbs +4 -4
  78. data/sig/authproto/dpop/stored_nonce.rbs +2 -2
  79. data/sig/authproto/http_client.rbs +23 -6
  80. data/sig/authproto/http_helpers.rbs +1 -0
  81. data/sig/authproto/metadata/authorization_server.rbs +3 -3
  82. data/sig/authproto/metadata/client_metadata.rbs +1 -1
  83. data/sig/authproto/metadata/resource_server.rbs +2 -2
  84. data/sig/authproto/minisky.rbs +57 -0
  85. data/sig/authproto/state/session.rbs +12 -6
  86. data/sig/authproto/state/session_info.rbs +23 -0
  87. data/sig/authproto/state/session_manager.rbs +7 -2
  88. data/sig/authproto/storage/interface.rbs +1 -0
  89. data/sig/authproto/storage/key_builder.rbs +1 -1
  90. data/sig/authproto/storage/memory.rbs +1 -1
  91. data/sig/authproto/storage/sqlite.rbs +1 -0
  92. data/sig/authproto/token/revocation.rbs +1 -0
  93. data/sig/authproto.rbs +3 -8
  94. metadata +37 -15
  95. data/examples/confidential_client/Gemfile +0 -14
  96. data/examples/confidential_client/README.md +0 -236
  97. data/examples/confidential_client/app.rb +0 -308
  98. data/examples/confidential_client/public/styles.css +0 -70
  99. data/examples/confidential_client/scripts/generate_keys.rb +0 -21
  100. data/examples/confidential_client/views/authorized.erb +0 -46
  101. data/examples/confidential_client/views/index.erb +0 -44
  102. data/sig/authproto/minisky_oauth.rbs +0 -27
  103. /data/examples/{confidential_client/config/oauth-client-metadata.example.json → basic_webapp/config/oauth-client-metadata.production.json} +0 -0
  104. /data/examples/{confidential_client → basic_webapp}/config.ru +0 -0
  105. /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-1-sign-in.png +0 -0
  106. /data/examples/{confidential_client → basic_webapp}/screenshots/screenshot-2-success.png +0 -0
@@ -0,0 +1,23 @@
1
+ module AuthProto
2
+ module State
3
+ class SessionInfo
4
+ def initialize: (Session session) -> void
5
+ def session_id: () -> String
6
+ def access_token: () -> String?
7
+ def refresh_token: () -> String?
8
+ def expires_at: () -> Time?
9
+ def expires_in: () -> Integer?
10
+ def requested_scope: () -> String
11
+ def granted_scope: () -> String?
12
+ def did: () -> String?
13
+ def pds: () -> String?
14
+ def to_h: () -> Hash[Symbol, String | Integer | Time | nil]
15
+ def pending?: () -> bool
16
+ def tokens_valid?: () -> bool
17
+ alias authorized? tokens_valid?
18
+ def renewable?: () -> bool
19
+ def has_limited_scope?: () -> bool
20
+ def can_be_revoked?: () -> bool
21
+ end
22
+ end
23
+ end
@@ -6,13 +6,18 @@ module AuthProto
6
6
  @supported_signing_keys: Hash[String, String]
7
7
 
8
8
  def initialize: (client_id: String, ?supported_signing_keys: Hash[String, String]) -> void
9
- def create_session: (client_id: String, scope: String, ?auth_server: Metadata::AuthorizationServer?, ?did: String?, ?signing_key_id: String?) -> Session
9
+ def create_session: (
10
+ client_id: String,
11
+ scope: String,
12
+ ?auth_server: Metadata::AuthorizationServer?,
13
+ ?did: String?,
14
+ ?signing_key_id: String?
15
+ ) -> Session
10
16
  def update_session: (Session session) -> Session
11
17
  def complete_authorization: (Session session) -> Session
12
18
  def get_session: (String session_id) -> Session?
13
19
  def get_session_by_state_token: (String? state) -> Session?
14
20
  def delete_session: (String session_id) -> void
15
- def cleanup_expired: () -> void
16
21
 
17
22
  private
18
23
  def validate_client_id: (String client_id) -> void
@@ -10,6 +10,7 @@ module AuthProto
10
10
  def get: (String key) -> untyped
11
11
  def delete: (String key) -> bool
12
12
  def exists?: (String key) -> bool
13
+ def cleanup_expired_records: () -> void
13
14
  def with_lock: [T] (String key, ?ttl: Integer) { () -> T } -> T
14
15
 
15
16
  # Protected in Ruby; RBS exposes protected methods as public.
@@ -5,7 +5,7 @@ module AuthProto
5
5
  NAMESPACE_PREFIX: String
6
6
  def self.session_key: (String id) -> String
7
7
  def self.state_key: (String token) -> String
8
- def self.nonce_key: (String session_id, String server_url) -> String
8
+ def self.nonce_key: (String session_id, String origin) -> String
9
9
  def self.lock_key: (String namespace, String id) -> String
10
10
 
11
11
  private
@@ -6,6 +6,7 @@ module AuthProto
6
6
  def get: (String key) -> untyped
7
7
  def delete: (String key) -> true
8
8
  def exists?: (String key) -> bool
9
+ def cleanup_expired_records: () -> void
9
10
  def with_lock: [T] (String key, ?ttl: Integer) { () -> T } -> T
10
11
  def clear: () -> void
11
12
 
@@ -15,7 +16,6 @@ module AuthProto
15
16
  def expired?: (String key) -> bool
16
17
  def lock_expired?: (String lock_key) -> bool
17
18
  def set_expiration: (String key, Integer ttl) -> Integer
18
- def cleanup_expired: () -> void
19
19
  def start_cleanup_thread: () -> Thread
20
20
  end
21
21
  end
@@ -11,6 +11,7 @@ module AuthProto
11
11
  def get: (String key) -> (String | Numeric | nil)
12
12
  def delete: (String key) -> bool
13
13
  def exists?: (String key) -> bool
14
+ def cleanup_expired_records: () -> void
14
15
  def with_lock: [T] (String key, ?ttl: Integer) { () -> T } -> T
15
16
  def close: () -> void
16
17
 
@@ -1,6 +1,7 @@
1
1
  module AuthProto
2
2
  module Token
3
3
  class Revocation
4
+ include HTTPHelpers
4
5
  class Error < AuthProto::Error
5
6
  end
6
7
 
data/sig/authproto.rbs CHANGED
@@ -6,18 +6,13 @@ end
6
6
  module AuthProto
7
7
  type json_object = Hash[String, untyped]
8
8
  type http_body = String | Hash[untyped, untyped] | nil
9
- type http_response = { status: Integer, headers: Hash[String, String], body: String? }
10
- type session_data = { access_token: String, token_type: String, expires_in: Integer,
11
- refresh_token: String?, scope: String, granted_scope: String, session_id: String, did: String }
12
- type token_info = session_data
13
- type refreshed_tokens = session_data
14
- type callback_result = session_data
9
+ type http_response = { status: Integer | String, headers: Hash[String, String | Array[String]], body: String? }
15
10
  type authorization_result = { url: String, session_id: String }
16
11
 
17
12
  class Error < StandardError
18
13
  end
19
14
 
20
- class OAuthError < Error
15
+ class OAuthError < AuthProto::Error
21
16
  attr_reader error_code: String
22
17
  def initialize: (String message, String error_code) -> void
23
18
  end
@@ -30,7 +25,7 @@ module AuthProto
30
25
  def initialize: (String message) -> void
31
26
  end
32
27
 
33
- class ConfigurationError < Error
28
+ class ConfigurationError < AuthProto::Error
34
29
  end
35
30
 
36
31
  class Configuration
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: authproto
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0.beta4
4
+ version: 0.3.0.beta5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Josh Huckabee
@@ -72,19 +72,39 @@ files:
72
72
  - MIT-LICENSE.txt
73
73
  - README.md
74
74
  - SECURITY.md
75
- - examples/confidential_client/Gemfile
76
- - examples/confidential_client/Gemfile.lock
77
- - examples/confidential_client/README.md
78
- - examples/confidential_client/app.rb
79
- - examples/confidential_client/config.ru
80
- - examples/confidential_client/config/oauth-client-metadata.example.json
81
- - examples/confidential_client/public/styles.css
82
- - examples/confidential_client/screenshots/screenshot-1-sign-in.png
83
- - examples/confidential_client/screenshots/screenshot-2-success.png
84
- - examples/confidential_client/scripts/generate_keys.rb
85
- - examples/confidential_client/views/authorized.erb
86
- - examples/confidential_client/views/index.erb
87
- - examples/confidential_client/views/layout.erb
75
+ - examples/basic_webapp/Gemfile
76
+ - examples/basic_webapp/Gemfile.lock
77
+ - examples/basic_webapp/README.md
78
+ - examples/basic_webapp/app.rb
79
+ - examples/basic_webapp/config.ru
80
+ - examples/basic_webapp/config/oauth-client-metadata.localhost.json
81
+ - examples/basic_webapp/config/oauth-client-metadata.production.json
82
+ - examples/basic_webapp/public/styles.css
83
+ - examples/basic_webapp/screenshots/screenshot-1-sign-in.png
84
+ - examples/basic_webapp/screenshots/screenshot-2-success.png
85
+ - examples/basic_webapp/scripts/generate_keys.rb
86
+ - examples/basic_webapp/views/authorized.erb
87
+ - examples/basic_webapp/views/index.erb
88
+ - examples/basic_webapp/views/layout.erb
89
+ - examples/bookmarks/Gemfile
90
+ - examples/bookmarks/Gemfile.lock
91
+ - examples/bookmarks/README.md
92
+ - examples/bookmarks/Rakefile
93
+ - examples/bookmarks/app/account.rb
94
+ - examples/bookmarks/app/bookmark.rb
95
+ - examples/bookmarks/app/init.rb
96
+ - examples/bookmarks/app/oauth.rb
97
+ - examples/bookmarks/app/server.rb
98
+ - examples/bookmarks/config.ru
99
+ - examples/bookmarks/config/oauth-client-metadata.localhost.json
100
+ - examples/bookmarks/config/oauth-client-metadata.production.json
101
+ - examples/bookmarks/db/migrate/20261107004141_create_bookmarks.rb
102
+ - examples/bookmarks/db/schema.rb
103
+ - examples/bookmarks/public/styles.css
104
+ - examples/bookmarks/scripts/generate_keys.rb
105
+ - examples/bookmarks/views/bookmarks.erb
106
+ - examples/bookmarks/views/index.erb
107
+ - examples/bookmarks/views/layout.erb
88
108
  - examples/minisky_console/Gemfile
89
109
  - examples/minisky_console/Gemfile.lock
90
110
  - examples/minisky_console/README.md
@@ -125,6 +145,7 @@ files:
125
145
  - lib/authproto/serialization/token_set.rb
126
146
  - lib/authproto/state.rb
127
147
  - lib/authproto/state/session.rb
148
+ - lib/authproto/state/session_info.rb
128
149
  - lib/authproto/state/session_manager.rb
129
150
  - lib/authproto/state/token_set.rb
130
151
  - lib/authproto/storage/interface.rb
@@ -155,7 +176,7 @@ files:
155
176
  - sig/authproto/metadata/authorization_server.rbs
156
177
  - sig/authproto/metadata/client_metadata.rbs
157
178
  - sig/authproto/metadata/resource_server.rbs
158
- - sig/authproto/minisky_oauth.rbs
179
+ - sig/authproto/minisky.rbs
159
180
  - sig/authproto/par.rbs
160
181
  - sig/authproto/par/client.rbs
161
182
  - sig/authproto/par/client_assertion.rbs
@@ -168,6 +189,7 @@ files:
168
189
  - sig/authproto/serialization/token_set.rbs
169
190
  - sig/authproto/state.rbs
170
191
  - sig/authproto/state/session.rbs
192
+ - sig/authproto/state/session_info.rbs
171
193
  - sig/authproto/state/session_manager.rbs
172
194
  - sig/authproto/state/token_set.rbs
173
195
  - sig/authproto/storage/interface.rbs
@@ -1,14 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- source "https://rubygems.org"
4
-
5
- gem "authproto", path: "../.."
6
- gem "dotenv"
7
- gem "faraday"
8
- gem "json"
9
- gem "puma"
10
- gem "rackup"
11
- gem "redis"
12
- gem "sinatra"
13
- gem "sinatra-contrib"
14
- gem "sqlite3", "~> 2.9"
@@ -1,236 +0,0 @@
1
- # AT Protocol OAuth Confidential Client Example
2
-
3
- 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.
4
-
5
- <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">
6
-
7
- <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">
8
-
9
- ## Overview
10
-
11
- The example implements a simple web application using Sinatra that:
12
-
13
- - Allows users to sign in with their AT Protocol handle (@handle) and make a test Bluesky post
14
- - Implements the complete OAuth authorization flow
15
- - Uses DPoP-bound tokens for API requests
16
- - Demonstrates secure session management with encryption
17
- - Shows how to make authenticated API calls to Bluesky
18
- - Provides examples of both development and production storage configurations
19
- - Supports running on localhost (but as a public client)
20
-
21
- ## Requirements
22
-
23
- - Ruby 3.3+
24
- - Bundler
25
- - A domain name for your application that matches your client metadata (required for production)
26
- - SSL certificate for your domain (required for production)
27
- - optionally, Redis for production
28
-
29
- ## Setup
30
-
31
- 1. Clone the repository and navigate to the example directory:
32
-
33
- ```bash
34
- cd examples/confidential_client
35
- ```
36
-
37
- 2. Install dependencies:
38
-
39
- ```bash
40
- bundle install
41
- ```
42
-
43
- 3. Generate EC keys for client authentication:
44
-
45
- ```bash
46
- bundle exec ruby scripts/generate_keys.rb
47
- ```
48
-
49
- 4. Generate session & encryption keys:
50
-
51
- ```bash
52
- openssl rand -base64 32
53
- openssl rand -hex 32
54
-
55
- cat > .env
56
- ATPROTO_MASTER_KEY=<base64 value from first command>
57
- SESSION_SECRET=<hex value from second command>
58
- ```
59
-
60
- 5. Configure your client metadata:
61
- - Copy the example metadata file over:
62
- ```
63
- cp config/client-metadata.example.json config/oauth-client-metadata.json
64
- ```
65
- - Set the correct `client_id` URL where your metadata will be hosted
66
- - Configure valid `redirect_uris` for your application
67
- - 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.
68
- - For localhost testing, set `client_id` to `http://localhost/` and `redirect_uris` to `["http://127.0.0.1:9292/callback"]`
69
-
70
- 6. Set up environment variables:
71
-
72
- ```bash
73
- # Your application's domain name
74
- export PERMITTED_DOMAIN=your.domain.com
75
- # or 127.0.0.1 for localhost testing
76
-
77
- # Select a storage backend: memory (default), sqlite, or redis
78
- export STORAGE_BACKEND=sqlite
79
-
80
- # Optional SQLite path (defaults to ./db/authproto.sqlite3)
81
- export SQLITE_PATH=/var/lib/my-app/authproto.sqlite3
82
-
83
- # Required when STORAGE_BACKEND=redis
84
- export REDIS_URL=redis://localhost:6379
85
- ```
86
-
87
- ## Configuration
88
-
89
- ### Storage Configuration
90
-
91
- The example app supports in-memory, SQLite and Redis storage backends. Select
92
- one by passing `STORAGE_BACKEND=memory`, `STORAGE_BACKEND=sqlite`, or
93
- `STORAGE_BACKEND=redis`.
94
-
95
- #### In-memory storage (for development)
96
-
97
- ```ruby
98
- # config/development.rb
99
- AuthProto.configure do |config|
100
- config.storage = AuthProto::Storage::Memory.new
101
- config.logger = Logger.new($stdout)
102
- end
103
- ```
104
-
105
- #### SQLite storage
106
-
107
- SQLite can be used for persistent storage in development or in low traffic production setups:
108
-
109
- ```bash
110
- export STORAGE_BACKEND=sqlite
111
- export SQLITE_PATH=/var/lib/my-app/authproto.sqlite3
112
- ```
113
-
114
- #### Redis storage
115
-
116
- Use Redis in more complex production setups:
117
-
118
- ```ruby
119
- # config/production.rb
120
- require 'redis'
121
-
122
- AuthProto.configure do |config|
123
- redis_client = Redis.new(
124
- url: ENV.fetch('REDIS_URL'),
125
- ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_PEER }
126
- )
127
-
128
- config.storage = AuthProto::Storage::Redis.new(
129
- redis_client: redis_client
130
- )
131
-
132
- config.logger = Logger.new($stdout)
133
- end
134
- ```
135
-
136
- ### Host Authorization
137
-
138
- This application requires specific domain configuration to function properly:
139
-
140
- 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`.
141
-
142
- 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.
143
-
144
- 3. **Quick Setup with Tailscale Funnel**: One easy way to expose your local development server to the internet is using Tailscale Funnel:
145
-
146
- 1. Set up [Tailscale Funnel](https://tailscale.com/kb/1223/funnel)
147
- 2. Ensure you have HTTPS certificates configured
148
- 5. Start your Funnel:
149
- ```bash
150
- tailscale funnel 9292
151
- ```
152
- 4. Ensure your client_id and redirect_uris match your funnel path
153
- 5. Set the `PERMITTED_DOMAIN` environment variable to your Tailscale domain
154
- ```bash
155
- export PERMITTED_DOMAIN=machinename.xyz.ts.net
156
- ```
157
- 6. Run the application (see below)
158
-
159
- Your application will now be accessible via your Tailscale domain with HTTPS enabled.
160
-
161
- ### Session Security
162
-
163
- The application uses encrypted sessions to store authorization data. Configure the session secret with:
164
-
165
- ```bash
166
- export SESSION_SECRET=your-secure-random-string
167
- ```
168
-
169
- If not set, a random secret will be generated on startup (not recommended for production).
170
-
171
- The app stores the ID returned by `authorize` as `session[:pending_oauth_session_id]`
172
- before redirecting. On callback, it passes that browser-session value as the required
173
- `expected_session_id:` argument to `handle_callback`. The library rejects a missing
174
- or mismatched ID before exchanging the code. After success, the app removes the
175
- pending association and remembers the authenticated session separately.
176
-
177
- The expected ID must come from the initiating browser session, never from the
178
- callback URL or by looking up the returned `state`. This example supports one pending
179
- login per browser; starting another replaces the previous pending association.
180
-
181
- ## Running the Application
182
-
183
- ### Development
184
- ```bash
185
- RACK_ENV=development bundle exec rackup
186
- ```
187
-
188
- ### Production
189
- ```bash
190
- RACK_ENV=production bundle exec rackup -E production
191
- ```
192
-
193
- This will start the server on `http://localhost:9292`.
194
-
195
- ## Troubleshooting
196
-
197
- ### Common Issues
198
-
199
- 1. "Invalid redirect URI":
200
- - Ensure your redirect URI matches exactly what's in your client metadata
201
- - Check that your domain matches the client_id domain
202
-
203
- 2. "Invalid client metadata":
204
- - Verify your client metadata is accessible at the URL specified in client_id
205
- - Check that your JSON is valid and contains all required fields
206
-
207
- 3. "Authorization failed":
208
- - Verify your JWKS configuration
209
- - Check that your DPoP proofs are being generated correctly
210
- - Ensure your client authentication is working
211
-
212
- 4. "Storage errors":
213
- - For SQLite storage, verify the database path is writable
214
- - For Redis storage, verify Redis connection settings
215
- - Check Redis SSL configuration if using encrypted connections
216
- - Ensure proper Redis authentication credentials if required
217
-
218
- 5. "Session state lost":
219
- - Verify storage configuration is correct
220
- - Check that SQLite storage is on persistent local disk
221
- - Check Redis connection stability if using Redis storage
222
- - Ensure session TTLs are appropriately configured
223
-
224
- ## Understanding the Code
225
-
226
- The example demonstrates several important concepts:
227
-
228
- 1. **Secure Storage**: The app shows proper configuration of in-memory, SQLite and Redis storage.
229
-
230
- 2. **Token Management**: All tokens are stored securely with encryption in the configured storage backend.
231
-
232
- 3. **Session Handling**: The app demonstrates proper session state management with atomic operations and locking.
233
-
234
- 4. **Error Recovery**: Includes examples of handling storage failures and token refresh scenarios.
235
-
236
- The code is thoroughly commented to explain these concepts and their implementation details.