cloudflare-origin-jwt 0.1.0

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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 84a11179d2ce0b98cf3cbf16e89403bf1c7506211de0a515c2081937432472b9
4
+ data.tar.gz: 748b6d20783547697898c2c15756e7b8ed484c5c3252d3c26c03948cde10cdf2
5
+ SHA512:
6
+ metadata.gz: b3e0d6cc696b3e05c110b5a502975e6f805e556d3d4af1ed7aed5d9cbe884c1df0cf1563dff013093f1bc2a6537152f9507c0a13e181bd2e60cffd11e0c7999c
7
+ data.tar.gz: 9f58d79910b4d363842e6bb46744dd10b8798e04d8199dc07e4910b4fde1abde4c545b48e806eab646125eef9ad36b6da7e279dbc587f90259c9c9b21081c78d
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 aileron
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,161 @@
1
+ # cloudflare-origin-jwt
2
+
3
+ 拒否する。**Cloudflare の前段(gateway)が署名した JWT を持たないリクエストは、アプリに届かない。**
4
+
5
+ Rails / Rack アプリの origin を「うちの gateway 経由だけ」に閉じるための middleware。Cloudflare Access のように利用者へログインを求めないので、**公開ページ**にも使える。
6
+
7
+ - 検証は EdDSA(Ed25519)。origin は**公開鍵だけ**を持つ。origin が漏れてもトークンは偽造できない
8
+ - 署名は短命(既定の例は 60 秒)。リプレイの窓を小さくする
9
+ - 失敗は **404**。本文は返さない(存在を隠す)
10
+ - 検証済みの claims に、gateway が詰めたデータ(サロンのフラグなど)を載せられる
11
+ - 実行時依存は `jwt` と `jwt-eddsa`(公式拡張)だけ。Rails / ActiveSupport に依存しない
12
+
13
+ ## インストール
14
+
15
+ ```ruby
16
+ gem "cloudflare-origin-jwt"
17
+ ```
18
+
19
+ Rails なら initializer を1つ置くだけで、middleware が先頭に入る(Railtie)。
20
+
21
+ **公開鍵はリポジトリに置く**。秘密ではないし、ENV にすると環境ごとに同じ値を揃える運用が増えるだけになる。秘密鍵だけが Worker の secret。
22
+
23
+ ```ruby
24
+ # config/initializers/cloudflare_origin_jwt.rb
25
+ module OriginKeys
26
+ CURRENT = <<~PEM
27
+ -----BEGIN PUBLIC KEY-----
28
+ ...
29
+ -----END PUBLIC KEY-----
30
+ PEM
31
+
32
+ # ローテーション中だけ残す。古いトークンの寿命が切れたら消す。
33
+ PREVIOUS = <<~PEM
34
+ -----BEGIN PUBLIC KEY-----
35
+ ...
36
+ -----END PUBLIC KEY-----
37
+ PEM
38
+ end
39
+
40
+ CloudflareOriginJwt.configure do |config|
41
+ config.public_keys = [OriginKeys::CURRENT, OriginKeys::PREVIOUS]
42
+ config.issuer = "hairbook-gateway"
43
+ config.audience = "salonpage"
44
+ end
45
+ ```
46
+
47
+ ENV で上書きしたい場合だけ、初期化の前に差し込む。
48
+
49
+ ```ruby
50
+ config.public_keys = ENV["CF_ORIGIN_JWT_PUBLIC_KEYS"]&.split(",") || [OriginKeys::CURRENT]
51
+ ```
52
+
53
+ `public_key` が空なら**何もしない**(ローカル開発・テストは gateway 無しで動く)。
54
+
55
+ Rails 以外(Rack):
56
+
57
+ ```ruby
58
+ use CloudflareOriginJwt::Middleware
59
+ ```
60
+
61
+ ## gateway 側(Cloudflare Worker)
62
+
63
+ リクエストごとに Ed25519 で署名した JWT を作り、ヘッダに載せる。
64
+
65
+ ```js
66
+ // 秘密鍵は Worker の secret に置く(PKCS#8 PEM など)
67
+ const key = await crypto.subtle.importKey(
68
+ "pkcs8", pemToArrayBuffer(env.CF_ORIGIN_JWT_PRIVATE_KEY),
69
+ { name: "Ed25519" }, false, ["sign"],
70
+ );
71
+ const b64 = (obj) => btoa(JSON.stringify(obj)).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
72
+ const now = Math.floor(Date.now() / 1000);
73
+ const payload = b64({ iss: "hairbook-gateway", aud: "salonpage", iat: now, exp: now + 60,
74
+ flags: { page_published: 1, noroshi_reserve: 0 } });
75
+ const input = b64({ alg: "EdDSA", typ: "JWT" }) + "." + payload;
76
+ const sig = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key, new TextEncoder().encode(input)));
77
+ const jwt = input + "." + base64url(sig);
78
+ headers.set("X-Cf-Origin-Jwt", jwt);
79
+ ```
80
+
81
+ ## claims の読み方
82
+
83
+ ```ruby
84
+ CloudflareOriginJwt.claims(env) # => { "iss" => ..., "aud" => ..., "flags" => { ... } }
85
+ CloudflareOriginJwt.flags(env) # => { "page_published" => 1, ... }(無ければ {})
86
+ ```
87
+
88
+ ビューやコントローラでは `request.env` を渡す。
89
+
90
+ ## 設定
91
+
92
+ | 設定 | 既定 | 説明 |
93
+ |---|---|---|
94
+ | `public_keys` | `[]` | Ed25519 公開鍵の配列。Hash にすると `kid` で選ぶ。空なら middleware は素通し |
95
+ | `issuer` | `nil` | 検証する `iss`。空なら検証しない |
96
+ | `audience` | `nil` | 検証する `aud`。空なら検証しない |
97
+ | `header` | `HTTP_X_CF_ORIGIN_JWT` | Rack の env キー |
98
+ | `exempt_paths` | `["/up", "/healthz"]` | トークン無しで通すパス(完全一致) |
99
+ | `leeway` | `30` | `exp`/`iat` の時計ずれ許容(秒) |
100
+ | `status` | `404` | 拒否時のステータス |
101
+ | `logger` | `nil` | 検証失敗の理由を残す(`warn`) |
102
+
103
+ ## 注意
104
+
105
+ - **短命にする**。60 秒程度。長くするとリプレイの窓が広がる
106
+ - **鍵は分ける**。gateway ごと・用途ごとに鍵ペアを分けると、片方の漏洩が他へ広がらない
107
+ - **Cloudflare Access の代わりではない**。ログインして使う社内画面を Access で守るなら [`cloudflare_access_gate`](https://rubygems.org/gems/cloudflare_access_gate) など別の仕組みを使う。この gem は「gateway を通ったか」だけを見る
108
+
109
+ ## デプロイの順序
110
+
111
+ **gateway を先、origin(Rails)を後**。逆にすると、トークンを付けない古い gateway のリクエストが origin で 404 になる。
112
+
113
+ ```
114
+ 1. gateway をデプロイ(トークンを付け始める。古い origin は無視するので無害)
115
+ 2. origin をデプロイ(この時点で全リクエストに有効なトークンが付いている)
116
+ ```
117
+
118
+ Workers のデプロイは一括で切り替わるので、「トークン無しの gateway」と「検証する origin」が同時に生きる窓は作らない。Fly 側のロールアウト中も、旧マシンは無視・新マシンは検証で、どちらにもトークンは付いている。
119
+
120
+ 鍵を変えるときは「鍵のローテーション」の順で、origin に新鍵を先に足す。
121
+
122
+ ## 鍵のローテーション
123
+
124
+ 公開鍵は**複数**持てる。切り替えで止まらないように、次の順で回す。
125
+
126
+ ```ruby
127
+ # 1. 新しい鍵を「追加」してデプロイ(古い鍵も残す)
128
+ config.public_keys = [
129
+ ENV["CF_ORIGIN_JWT_PUBLIC_KEY_2026_11"],
130
+ ENV["CF_ORIGIN_JWT_PUBLIC_KEY_2025_05"],
131
+ ]
132
+
133
+ # 2. gateway の署名鍵を新しいものに切り替える(両方の鍵が有効なので即時で安全)
134
+
135
+ # 3. 古いトークンが寿命で消えたら、古い鍵を外す
136
+ config.public_keys = [ENV["CF_ORIGIN_JWT_PUBLIC_KEY_2026_11"]]
137
+ ```
138
+
139
+ `kid` をトークンのヘッダに入れると、照合する鍵を1つに絞れる。Hash で登録する。
140
+
141
+ ```ruby
142
+ config.public_keys = {
143
+ "2026-11" => ENV["CF_ORIGIN_JWT_PUBLIC_KEY_2026_11"],
144
+ "2025-05" => ENV["CF_ORIGIN_JWT_PUBLIC_KEY_2025_05"],
145
+ }
146
+ ```
147
+
148
+ `kid` が一致しなければ、登録した全部の鍵を順に試す(鍵が数個なら誤差)。
149
+
150
+ **署名の寿命(既定 60 秒)より長く古い鍵を残さない**こと。寿命を過ぎたトークンは `exp` で落ちるので、古い鍵を外しても安全。
151
+
152
+ ## 開発
153
+
154
+ ```sh
155
+ bundle install
156
+ bundle exec rake test
157
+ ```
158
+
159
+ ## License
160
+
161
+ MIT
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloudflareOriginJwt
4
+ # Everything the middleware needs. Nothing is read from ENV unless the host
5
+ # app puts it there, so a Rails app stays in charge of its own secrets.
6
+ class Configuration
7
+ DEFAULT_HEADER = "HTTP_X_CF_ORIGIN_JWT"
8
+ DEFAULT_EXEMPT_PATHS = ["/up", "/healthz"].freeze
9
+ DEFAULT_LEEWAY = 30
10
+ DEFAULT_STATUS = 404
11
+
12
+ attr_accessor :issuer, :audience, :header, :exempt_paths, :leeway, :status, :logger
13
+ attr_reader :public_keys
14
+
15
+ def initialize
16
+ @header = DEFAULT_HEADER
17
+ @exempt_paths = DEFAULT_EXEMPT_PATHS.dup
18
+ @leeway = DEFAULT_LEEWAY
19
+ @status = DEFAULT_STATUS
20
+ @public_keys = []
21
+ end
22
+
23
+ # Several keys at once, so a key can be rotated without a flag day: publish
24
+ # the new one next to the old, switch the gateway, then drop the old.
25
+ #
26
+ # Accepts an Array of PEM strings (or Ed25519::VerifyKey) or a Hash of
27
+ # { "kid" => key }, which lets the token name its key in the JWT header.
28
+ def public_keys=(values)
29
+ @public_keys = values.nil? ? [] : values
30
+ @verify_keys = nil
31
+ end
32
+
33
+ # Single-key shorthand, kept for the common case.
34
+ def public_key=(value)
35
+ self.public_keys = value.nil? ? [] : [value]
36
+ end
37
+
38
+ def public_key
39
+ list = verify_keys
40
+ list.length == 1 ? list.first : nil
41
+ end
42
+
43
+ def verify_keys
44
+ @verify_keys ||= key_list.map { |value| VerifyKey.build(value) }.compact
45
+ end
46
+
47
+ def verify_key
48
+ list = verify_keys
49
+ list.length == 1 ? list.first : nil
50
+ end
51
+
52
+ # The key the token names in its "kid" header, when the host registered a
53
+ # hash. nil means "try every key".
54
+ def key_for_kid(kid)
55
+ return nil unless public_keys.is_a?(Hash) && !kid.to_s.empty?
56
+
57
+ VerifyKey.build(public_keys[kid.to_s])
58
+ end
59
+
60
+ # A missing key means the middleware stays out of the way: local
61
+ # development and test runs do not need a gateway in front of them.
62
+ def enabled?
63
+ !verify_keys.empty?
64
+ end
65
+
66
+ def exempt?(path)
67
+ exempt_paths.any? { |candidate| candidate == path }
68
+ end
69
+
70
+ private
71
+
72
+ def key_list
73
+ public_keys.is_a?(Hash) ? public_keys.values : Array(public_keys)
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "jwt"
4
+ require "jwt/eddsa"
5
+
6
+ module CloudflareOriginJwt
7
+ # Rejects any request that does not carry a JWT signed by the gateway.
8
+ #
9
+ # The gateway runs at the Cloudflare edge and signs a short-lived token per
10
+ # request. The origin only ever holds public keys, so a compromised origin
11
+ # cannot mint tokens. Anything without a valid token never reaches the app.
12
+ class Middleware
13
+ ENV_KEY = "cloudflare_origin_jwt.claims"
14
+
15
+ def initialize(app, configuration: CloudflareOriginJwt.configuration)
16
+ @app = app
17
+ @configuration = configuration
18
+ end
19
+
20
+ def call(env)
21
+ config = @configuration
22
+ return @app.call(env) unless config.enabled?
23
+ return @app.call(env) if config.exempt?(env["PATH_INFO"].to_s)
24
+
25
+ payload = verify(env[config.header].to_s, config)
26
+ return reject(config) if payload.nil?
27
+
28
+ env[ENV_KEY] = payload
29
+ @app.call(env)
30
+ end
31
+
32
+ private
33
+
34
+ # More than one key is allowed so keys can be rotated. The token's "kid"
35
+ # narrows the search when the host registered keys by kid; otherwise every
36
+ # key is tried, which is cheap with a handful of keys.
37
+ def verify(token, config)
38
+ return nil if token.empty?
39
+
40
+ error = nil
41
+ candidates(token, config).each do |key|
42
+ begin
43
+ payload, = JWT.decode(token, key, true, decode_options(config))
44
+ return payload
45
+ rescue JWT::DecodeError => cause
46
+ error = cause
47
+ end
48
+ end
49
+ config.logger&.warn("cloudflare_origin_jwt: #{error&.class}: #{error&.message}")
50
+ nil
51
+ end
52
+
53
+ def candidates(token, config)
54
+ keys = config.verify_keys
55
+ named = config.key_for_kid(kid_of(token))
56
+ named ? [named] + (keys - [named]) : keys
57
+ end
58
+
59
+ def kid_of(token)
60
+ header, = JWT.decode(token, nil, false)
61
+ header["kid"]
62
+ rescue JWT::DecodeError
63
+ nil
64
+ end
65
+
66
+ def decode_options(config)
67
+ {
68
+ algorithm: "EdDSA",
69
+ iss: config.issuer,
70
+ verify_iss: !config.issuer.to_s.empty?,
71
+ aud: config.audience,
72
+ verify_aud: !config.audience.to_s.empty?,
73
+ leeway: config.leeway
74
+ }
75
+ end
76
+
77
+ # The body stays empty on purpose: an unauthenticated caller learns only
78
+ # that the path is not theirs to see.
79
+ def reject(config)
80
+ [config.status, { "content-type" => "text/plain; charset=utf-8", "content-length" => "0" }, []]
81
+ end
82
+ end
83
+ end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloudflareOriginJwt
4
+ # Inserts the middleware in front of everything once the app has configured
5
+ # it, so hosts only add the gem and an initializer.
6
+ class Railtie < Rails::Railtie
7
+ initializer "cloudflare_origin_jwt.middleware" do |app|
8
+ app.config.middleware.insert_before(0, CloudflareOriginJwt::Middleware)
9
+ end
10
+ end
11
+ end
@@ -0,0 +1,29 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "openssl"
4
+ require "ed25519"
5
+
6
+ module CloudflareOriginJwt
7
+ # jwt-eddsa only accepts an Ed25519::VerifyKey, never a PEM string. Hosts
8
+ # keep the key in their environment as PEM, so translate once and memoize.
9
+ module VerifyKey
10
+ module_function
11
+
12
+ def build(value)
13
+ return value if value.is_a?(::Ed25519::VerifyKey)
14
+ return nil if value.nil?
15
+
16
+ text = value.to_s.strip
17
+ return nil if text.empty?
18
+
19
+ raw = text.include?("BEGIN") ? raw_from_pem(text) : text
20
+ ::Ed25519::VerifyKey.new(raw.b)
21
+ end
22
+
23
+ # OpenSSL 3 parses an Ed25519 SubjectPublicKeyInfo and hands back the 32
24
+ # raw key bytes that the ed25519 gem wants.
25
+ def raw_from_pem(pem)
26
+ OpenSSL::PKey.read(pem).raw_public_key
27
+ end
28
+ end
29
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CloudflareOriginJwt
4
+ VERSION = "0.1.0"
5
+ end
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "cloudflare_origin_jwt/version"
4
+ require "cloudflare_origin_jwt/verify_key"
5
+ require "cloudflare_origin_jwt/configuration"
6
+ require "cloudflare_origin_jwt/middleware"
7
+
8
+ # Verifies the JWT a Cloudflare Worker puts on origin requests, so a Rails app
9
+ # can refuse anything that did not come through the gateway.
10
+ #
11
+ # CloudflareOriginJwt.configure do |config|
12
+ # config.public_key = ENV["CF_ORIGIN_JWT_PUBLIC_KEY"]
13
+ # config.issuer = "hairbook-gateway"
14
+ # config.audience = "salonpage"
15
+ # end
16
+ #
17
+ # The gateway may carry data the origin needs (salon flags, for example) in the
18
+ # claims; read it with CloudflareOriginJwt.claims(env).
19
+ module CloudflareOriginJwt
20
+ class << self
21
+ def configuration
22
+ @configuration ||= Configuration.new
23
+ end
24
+
25
+ def configure
26
+ yield configuration
27
+ configuration
28
+ end
29
+
30
+ def reset!
31
+ @configuration = nil
32
+ end
33
+
34
+ # Claims of the verified request, or nil when no token was verified.
35
+ def claims(env)
36
+ env[Middleware::ENV_KEY]
37
+ end
38
+
39
+ # Data the gateway put in the token, as a Hash with string keys.
40
+ def flags(env)
41
+ (claims(env) || {})["flags"] || {}
42
+ end
43
+ end
44
+ end
45
+
46
+ require "cloudflare_origin_jwt/railtie" if defined?(Rails::Railtie)
metadata ADDED
@@ -0,0 +1,81 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: cloudflare-origin-jwt
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - aileron
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: jwt
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '3.3'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - "~>"
24
+ - !ruby/object:Gem::Version
25
+ version: '3.3'
26
+ - !ruby/object:Gem::Dependency
27
+ name: jwt-eddsa
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - "~>"
31
+ - !ruby/object:Gem::Version
32
+ version: '1.1'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - "~>"
38
+ - !ruby/object:Gem::Version
39
+ version: '1.1'
40
+ description: |
41
+ Rack middleware that verifies a short-lived EdDSA JWT minted by a Cloudflare
42
+ Worker in front of your app. Requests without a valid token get a 404 and
43
+ never reach the application. Claims can carry data the origin needs, such as
44
+ feature flags. No Rails or ActiveSupport dependency at runtime.
45
+ executables: []
46
+ extensions: []
47
+ extra_rdoc_files: []
48
+ files:
49
+ - LICENSE.txt
50
+ - README.md
51
+ - lib/cloudflare_origin_jwt.rb
52
+ - lib/cloudflare_origin_jwt/configuration.rb
53
+ - lib/cloudflare_origin_jwt/middleware.rb
54
+ - lib/cloudflare_origin_jwt/railtie.rb
55
+ - lib/cloudflare_origin_jwt/verify_key.rb
56
+ - lib/cloudflare_origin_jwt/version.rb
57
+ homepage: https://github.com/aileron-inc/cloudflare-origin-jwt
58
+ licenses:
59
+ - MIT
60
+ metadata:
61
+ homepage_uri: https://github.com/aileron-inc/cloudflare-origin-jwt
62
+ source_code_uri: https://github.com/aileron-inc/cloudflare-origin-jwt
63
+ rubygems_mfa_required: 'true'
64
+ rdoc_options: []
65
+ require_paths:
66
+ - lib
67
+ required_ruby_version: !ruby/object:Gem::Requirement
68
+ requirements:
69
+ - - ">="
70
+ - !ruby/object:Gem::Version
71
+ version: '3.1'
72
+ required_rubygems_version: !ruby/object:Gem::Requirement
73
+ requirements:
74
+ - - ">="
75
+ - !ruby/object:Gem::Version
76
+ version: '0'
77
+ requirements: []
78
+ rubygems_version: 4.0.7
79
+ specification_version: 4
80
+ summary: Reject origin requests that did not come through your Cloudflare gateway
81
+ test_files: []