standard_id-apple 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3886bf49958b7ea2704e0491b0e7225c7f82b0d80ca7ab0dcca192b69e7bc1fa
-  data.tar.gz: 804f776780574d8457d6037148148c823a1011ffe3e68a8b84362c821f61c623
+  metadata.gz: be7fc30fab9732c5874d6d9672193130821d23251e1d838bfaf952851f988a6f
+  data.tar.gz: '0529585c83478d6ce4f11a48dbc2fb54548db01ff75f46a50f3f77673b8bc234'
 SHA512:
-  metadata.gz: f124007a84b444fd05c29af8c990cb878a1f9c63a2947309ca719f7e8bda6c0cdbd78d5d793ad404257dca8115ee8b59e5fdc28e320825db75267266826ed261
-  data.tar.gz: f90487e071ce29728dab12aa31cee722828e54056b90541ca606ea3e54e4728cba7d7f8458fbfe966212b3b2ce1f99afdda2ead034d7c959c7c17ee71fd8ceae
+  metadata.gz: 0fcea150d715a749d08fbdea281f45e790901a4af7e9cacd090492b66f5e6c633fa3e249164d4613309c780350ee1d8ba3c674b7e685573862f1177f89d8dc1e
+  data.tar.gz: 3f131c47f4e7ebe1021a967d3426356efdb80b8eeeed86ded1c3f4f5fb5210257ca58fe95a7292a9246404679cb83a0d38e30be5977ffed50a021ffaa5af2d4a

data/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-24
+
+Adopts the provider-plugin API of standard_id 0.42.
+
+### Upgrade
+
+- **Requires `standard_id` 0.42** (`~> 0.42`, was `>= 0.29, < 1.0`). Bump both
+  together.
+- **Rename `APPLE_PRIVATE_KEY_PEM` to `APPLE_PRIVATE_KEY`** when convenient.
+  Initializers from the 0.5.0 generator assign `ENV["APPLE_PRIVATE_KEY_PEM"]`
+  explicitly and keep working unchanged; the old name is also read as a
+  deprecated ENV fallback (see Deprecated).
+- **Expect a boot warning if Apple is half-configured.** With
+  `apple_client_id` set and any of `apple_team_id` / `apple_key_id` /
+  `apple_private_key` blank, standard_id now logs a warning at boot (raises in
+  production under `c.social.provider_misconfiguration = :raise`). sidekick-web
+  can drop the gated `APPLE_PRIVATE_KEY` / `APPLE_KEY_ID` / `APPLE_TEAM_ID`
+  entries in `config/initializers/standard_health.rb` in favour of that
+  setting, or keep them for the health report.
+- **Anyone rescuing on message text:** several messages changed (see Changed).
+  `StandardId::Apple::Railtie` no longer exists.
+
+### Added
+
+- **Required config fields.** `apple_private_key`, `apple_key_id` and
+  `apple_team_id` are declared `required: true`, so
+  `StandardId::Providers::Apple.configuration_errors` and standard_id's boot
+  check report them whenever `apple_client_id` (the enabling field) is set —
+  the two-stage check sidekick-web rebuilt by hand. `apple_mobile_client_id`
+  stays optional: the native `id_token` flow needs no signing key.
+- **ENV fallback** through standard_id 0.42: `APPLE_CLIENT_ID`,
+  `APPLE_MOBILE_CLIENT_ID`, `APPLE_PRIVATE_KEY`, `APPLE_KEY_ID`, `APPLE_TEAM_ID`.
+- **JWKS caching.** Apple's key set is cached in-process for an hour
+  (`JWKS_CACHE_TTL`) instead of being downloaded on every sign-in. A token whose
+  `kid` is not in the cached set triggers one refetch — Apple rotated — no more
+  than once a minute (`JWKS_MIN_REFRESH_INTERVAL`), so tokens with made-up
+  `kid`s cannot make this process hammer Apple. `reset_jwks_cache!` drops it.
+- Specs for `resolve_params`, `skip_csrf?`, `supports_mobile_callback?` /
+  `flow_for`, nonce handling, JWKS caching and configuration, plus standard_id's
+  `"a registered StandardId provider"` shared example.
+
+### Changed
+
+- **The JWKS is fetched through `StandardId::HttpClient`** — 5s open / 10s read
+  timeouts and the private/internal-address guard — instead of a bare
+  `Net::HTTP.get_response` with Ruby's default 60s timeouts. HttpClient has no
+  public plain GET, so this calls its `validate_url!` / `start_connection`
+  directly; CI's compat job catches it if those change.
+- **Nonce mismatches no longer leak the nonce.** The message was
+  `ID token nonce mismatch. Expected: <nonce>, got: <nonce>`; it is now
+  standard_id's `ID token nonce mismatch`, and the comparison is constant-time.
+- **The duplicated helpers are gone** in favour of standard_id's
+  `Providers::Base`: `rescue_to_oauth_error`, `verify_nonce!`,
+  `build_authorization_url`, `extract_tokens` (the private
+  `extract_token_payload` is removed). `lib/standard_id/apple/railtie.rb` is
+  replaced by `StandardId::Providers.plugin_railtie(:apple, ...)`.
+- **Error messages**, now consistently Apple-prefixed and never echoing a `kid`
+  or nonce:
+  - `Either code or id_token must be provided` → `Apple sign-in requires a code or an id_token`
+  - `Access token login flow is not supported for Apple` → `Apple sign-in does not support the access token flow`
+  - `Missing authorization code` → `Apple authorization code is missing`
+  - `Missing id_token` → `Apple id_token is missing`
+  - `Apple response missing id_token` → `Apple token response is missing id_token`
+  - `Apple OAuth credentials are incomplete` → `... are incomplete: <fields> not set`
+  - `Failed to exchange Apple authorization code: <error>` now falls back to
+    `HTTP <status>` when Apple's body names no error (it printed nothing).
+  - `JWK with kid '<kid>' not found in Apple's JWKS` → `Invalid Apple ID token: signing key not found in Apple's JWKS`
+  - `Failed to fetch JWK: ...` → `Failed to fetch Apple JWKS: ...`. A non-2xx
+    JWKS response is now `StandardId::OAuthError` (an upstream failure) rather
+    than `InvalidRequestError`.
+- Install generator and README use the canonical `APPLE_PRIVATE_KEY`, and
+  document the ENV fallback, required fields and flows.
+
+### Deprecated
+
+- **`APPLE_PRIVATE_KEY_PEM`** as an ENV source for `apple_private_key`. Read only
+  when the field is never assigned and `APPLE_PRIVATE_KEY` is unset, with one
+  warning per process through `StandardId.deprecator`.
+
+### Removed
+
+- `StandardId::Apple::Railtie` (replaced by the Railtie `plugin_railtie`
+  defines, `StandardId::Providers::Railties::Apple`).
+
 ## [0.5.0] - 2026-07-31
 
 ### Added

data/README.md

@@ -4,7 +4,7 @@ This gem extracts the Apple OAuth provider from the core [`standard_id`](https:/
 
 ## Installation
 
-Add the gem next to `standard_id`:
+Requires `standard_id` 0.42 or later. Add the gem next to `standard_id`:
 
 ```ruby
 # Gemfile
@@ -41,18 +41,72 @@ configuring by hand. Configure Apple credentials via the StandardId
 configuration block, in the `social` scope:
 
 ```ruby
-# config/initializers/standard_id.rb
+# config/initializers/standard_id_apple.rb
 StandardId.configure do |config|
   config.social.apple_client_id = ENV["APPLE_CLIENT_ID"]
   config.social.apple_mobile_client_id = ENV["APPLE_MOBILE_CLIENT_ID"] # optional
   config.social.apple_team_id = ENV["APPLE_TEAM_ID"]
   config.social.apple_key_id = ENV["APPLE_KEY_ID"]
-  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY_PEM"]
+  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY"]
 end
 ```
 
 With those values in place, StandardId routes such as `/auth/callback/apple` continue to function using this provider gem.
 
+### ENV fallback
+
+On `standard_id` 0.42+, a field you never assign falls back to the ENV
+variable named after it, upper-cased:
+
+| Field | ENV variable |
+|---|---|
+| `apple_client_id` | `APPLE_CLIENT_ID` |
+| `apple_mobile_client_id` | `APPLE_MOBILE_CLIENT_ID` |
+| `apple_team_id` | `APPLE_TEAM_ID` |
+| `apple_key_id` | `APPLE_KEY_ID` |
+| `apple_private_key` | `APPLE_PRIVATE_KEY` (deprecated fallback: `APPLE_PRIVATE_KEY_PEM`) |
+
+So with those variables set the block above is optional. Explicit
+configuration, even `nil`, always wins. `APPLE_PRIVATE_KEY_PEM` — the name
+install generators before 0.6.0 wrote — is still read when
+`APPLE_PRIVATE_KEY` is unset and the field is never assigned, with a
+deprecation warning; rename it. (An initializer that assigns
+`ENV["APPLE_PRIVATE_KEY_PEM"]` explicitly keeps working as-is.)
+
+### Required fields and the boot check
+
+`apple_client_id` (the web Services ID) switches the provider on — it is what
+`StandardId.social_provider_enabled?(:apple)` and the `apple_enabled` Inertia
+prop report. While it is set, `apple_team_id`, `apple_key_id` and
+`apple_private_key` are required: the code exchange signs its `client_secret`
+with them, so without them the flow starts, the user authenticates with Apple,
+and only then does the callback fail. StandardId checks this once every plugin
+has registered:
+
+```ruby
+StandardId::Providers::Apple.configuration_errors
+# => ["apple_private_key is required when apple_client_id is set"]
+
+config.social.provider_misconfiguration = :raise # fail a production boot instead of warning
+```
+
+`apple_mobile_client_id` gates nothing: the native `id_token` flow verifies the
+token against Apple's JWKS and needs no signing key. A native-only app (mobile
+client ID set, `apple_client_id` not) is therefore "not enabled" for the web
+UI while its native sign-in keeps working.
+
+### Flows
+
+| Flow | Audience (`client_id`) | Needs signing key |
+|---|---|---|
+| Web (`/auth/callback/apple`, form_post, CSRF skipped) | `apple_client_id` | yes |
+| Native `id_token` (`/api/oauth/callback/apple`) | `apple_mobile_client_id` | no |
+| Web flow on Android etc. (`flow=web` on the API callback, redirects back into the app) | `apple_client_id` | yes |
+
+Apple's signing keys (JWKS) are fetched through `StandardId::HttpClient`
+(timeouts, private-address guard) and cached in-process for an hour; a token
+signed with an unknown key triggers one early refetch, at most once a minute.
+
 ### Two corrections to earlier versions of this section
 
 **The `social.` prefix.** This section previously showed the flat form
@@ -92,7 +146,18 @@ without this gem in your Gemfile**, on any `standard_id` version. Configuring
 
 ## Testing
 
-Run the spec suite:
+In a host app, pin the plugin's registration with standard_id's shared
+example:
+
+```ruby
+require "standard_id/testing"
+
+RSpec.describe "StandardId social providers" do
+  it_behaves_like "a registered StandardId provider", :apple
+end
+```
+
+Run this gem's spec suite:
 
 ```bash
 bundle exec rspec

data/lib/generators/standard_id/apple/install/install_generator.rb

@@ -65,9 +65,12 @@ module StandardId
           say "  APPLE_MOBILE_CLIENT_ID  the iOS bundle ID — optional, web-only apps skip it"
           say "  APPLE_TEAM_ID           the 10-character Apple Developer team ID"
           say "  APPLE_KEY_ID            the key ID of the Sign In with Apple private key"
-          say "  APPLE_PRIVATE_KEY_PEM   the .p8 private key contents, PEM, newlines intact"
+          say "  APPLE_PRIVATE_KEY       the .p8 private key contents, PEM, newlines intact"
           say ""
-          say "APPLE_PRIVATE_KEY_PEM is multi-line. Most secret stores flatten it to"
+          say "APPLE_TEAM_ID, APPLE_KEY_ID and APPLE_PRIVATE_KEY are required whenever"
+          say "APPLE_CLIENT_ID is set; StandardId checks for them at boot."
+          say ""
+          say "APPLE_PRIVATE_KEY is multi-line. Most secret stores flatten it to"
           say "literal \\n — if sign-in fails on a JWT signing error, that is why."
           say "=" * 79
           say ""

data/lib/generators/standard_id/apple/install/templates/initializer.rb.erb

@@ -13,17 +13,17 @@
 # routes a unique unqualified name to its owning scope, but it stops working
 # the day another scope declares a colliding name. Use `config.social.`.
 #
-# On standard_id <= 0.32.0 these fields were declared from this gem's Railtie
-# `after_initialize`, which runs AFTER config/initializers — so the plain block
-# below raised at boot and had to be wrapped:
+# ENV: on standard_id >= 0.42 a field this file does not assign falls back to
+# the ENV variable named after it, upper-cased — APPLE_CLIENT_ID,
+# APPLE_MOBILE_CLIENT_ID, APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY — which
+# are the names used below. The assignments are kept so the wiring is visible;
+# delete any you prefer to leave to the fallback, or point one at another
+# source (e.g. Rails credentials).
 #
-#   Rails.application.config.after_initialize do
-#     StandardId.configure { |config| config.social.apple_client_id = ... }
-#   end
-#
-# standard_id >= 0.33.0 declares every loaded provider's fields before
-# `:load_config_initializers`, so the plain form is correct. Existing wrappers
-# keep working and need no change.
+# apple_client_id switches the web flow on. While it is set, StandardId's boot
+# check requires apple_team_id, apple_key_id and apple_private_key (warns by
+# default; `config.social.provider_misconfiguration = :raise` fails a
+# production boot instead).
 StandardId.configure do |config|
   config.social.apple_client_id = ENV["APPLE_CLIENT_ID"]
 
@@ -38,5 +38,6 @@ StandardId.configure do |config|
   # The .p8 contents in PEM form, newlines intact. Secret stores that flatten
   # multi-line values to literal \n produce a key that parses but fails to
   # sign — surfacing as a JWT error at callback time, not at boot.
-  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY_PEM"]
+  # (Installs before standard_id-apple 0.6.0 used APPLE_PRIVATE_KEY_PEM.)
+  config.social.apple_private_key = ENV["APPLE_PRIVATE_KEY"]
 end

data/lib/standard_id/apple/providers/apple.rb

@@ -1,7 +1,7 @@
-require "uri"
-require "net/http"
 require "json"
 require "jwt"
+require "net/http"
+require "openssl"
 
 module StandardId
   module Providers
@@ -17,6 +17,22 @@ module StandardId
         response_mode: DEFAULT_RESPONSE_MODE
       }.freeze
 
+      # Apple's signing keys rotate rarely; an unknown `kid` forces an early
+      # refetch (see #fetch_jwk), so a long TTL costs nothing on rotation.
+      JWKS_CACHE_TTL = 3600
+      # Floor between forced refetches, so a stream of ID tokens carrying
+      # made-up `kid`s cannot turn this process into a request amplifier
+      # against Apple.
+      JWKS_MIN_REFRESH_INTERVAL = 60
+
+      # Pre-0.6.0 install generators wired `apple_private_key` to this
+      # variable. Still read, with a deprecation warning, when the canonical
+      # APPLE_PRIVATE_KEY is unset and the host never assigns the field.
+      LEGACY_PRIVATE_KEY_ENV = "APPLE_PRIVATE_KEY_PEM".freeze
+
+      @jwks_mutex = Mutex.new
+      @jwks_cache = nil
+
       class << self
         def provider_name
           "apple"
@@ -29,18 +45,12 @@ module StandardId
         def authorization_url(state:, redirect_uri:, **options)
           ensure_basic_credentials!
 
-          query = {
+          build_authorization_url(
+            endpoint: AUTH_ENDPOINT,
             client_id: StandardId.config.apple_client_id,
-            redirect_uri:,
-            response_type: "code",
-            state:
-          }
-
-          supported_authorization_params.each do |param|
-            query[param] = options[param] || AUTHORIZATION_PARAM_DEFAULTS[param]
-          end
-
-          "#{AUTH_ENDPOINT}?#{URI.encode_www_form(query.compact)}"
+            redirect_uri:, state:, options:,
+            defaults: AUTHORIZATION_PARAM_DEFAULTS
+          )
         end
 
         def get_user_info(code: nil, id_token: nil, access_token: nil, redirect_uri: nil, nonce: nil, **options)
@@ -54,19 +64,32 @@ module StandardId
           elsif code.present?
             exchange_code_for_user_info(code: code, redirect_uri: redirect_uri, client_id: client_id, nonce: nonce)
           elsif access_token.present?
-            raise StandardId::InvalidRequestError, "Access token login flow is not supported for Apple"
+            raise StandardId::InvalidRequestError, "Apple sign-in does not support the access token flow"
           else
-            raise StandardId::InvalidRequestError, "Either code or id_token must be provided"
+            raise StandardId::InvalidRequestError, "Apple sign-in requires a code or an id_token"
           end
         end
 
+        # `apple_client_id` (the web Services ID) switches the provider on —
+        # it is the enabling field, so StandardId's boot check reports the
+        # three signing credentials below whenever it is set. They are what
+        # the code exchange needs to sign its client_secret; without them the
+        # web flow starts fine and only fails at the callback, after the user
+        # has authenticated with Apple.
+        #
+        # `apple_mobile_client_id` gates nothing: the native id_token flow
+        # verifies against Apple's JWKS and needs no signing key.
+        #
+        # ENV fallbacks (standard_id >= 0.42) use the upper-cased field names:
+        # APPLE_CLIENT_ID, APPLE_MOBILE_CLIENT_ID, APPLE_PRIVATE_KEY,
+        # APPLE_KEY_ID, APPLE_TEAM_ID.
         def config_schema
           {
             apple_client_id: { type: :string, default: nil },
             apple_mobile_client_id: { type: :string, default: nil },
-            apple_private_key: { type: :string, default: nil },
-            apple_key_id: { type: :string, default: nil },
-            apple_team_id: { type: :string, default: nil }
+            apple_private_key: { type: :string, default: -> { legacy_private_key_from_env }, required: true },
+            apple_key_id: { type: :string, default: nil, required: true },
+            apple_team_id: { type: :string, default: nil, required: true }
           }
         end
 
@@ -74,14 +97,19 @@ module StandardId
           DEFAULT_SCOPE
         end
 
+        # Apple posts the web callback (response_mode=form_post).
         def skip_csrf?
           true
         end
 
+        # Android and other non-Apple platforms sign in through Apple's web
+        # flow and need the server to redirect back into the app.
         def supports_mobile_callback?
           true
         end
 
+        # The web flow authenticates against the Services ID, the native flow
+        # against the app's bundle ID.
         def resolve_params(params, context: {})
           flow = context[:flow] || :web
           client_id = flow == :mobile ? StandardId.config.apple_mobile_client_id : StandardId.config.apple_client_id
@@ -90,83 +118,71 @@ module StandardId
         end
 
         def exchange_code_for_user_info(code:, redirect_uri:, client_id: StandardId.config.apple_client_id, nonce: nil)
-          ensure_full_credentials!(client_id: client_id)
-          raise StandardId::InvalidRequestError, "Missing authorization code" if code.blank?
-
-          token_response = HttpClient.post_form(TOKEN_ENDPOINT, {
-                                                  client_id: client_id,
-                                                  client_secret: generate_client_secret(client_id: client_id),
-                                                  code: code,
-                                                  grant_type: "authorization_code",
-                                                  redirect_uri: redirect_uri
-                                                })
-
-          unless token_response.is_a?(Net::HTTPSuccess)
-            error_body = begin
-              JSON.parse(token_response.body)
-            rescue StandardError
-              {}
+          rescue_to_oauth_error do
+            ensure_full_credentials!(client_id: client_id)
+            raise StandardId::InvalidRequestError, "Apple authorization code is missing" if code.blank?
+
+            token_response = HttpClient.post_form(TOKEN_ENDPOINT, {
+                                                    client_id: client_id,
+                                                    client_secret: generate_client_secret(client_id: client_id),
+                                                    code: code,
+                                                    grant_type: "authorization_code",
+                                                    redirect_uri: redirect_uri
+                                                  })
+
+            unless token_response.is_a?(Net::HTTPSuccess)
+              raise StandardId::InvalidRequestError,
+                    "Failed to exchange Apple authorization code: #{error_reason(token_response)}"
             end
-            raise StandardId::InvalidRequestError, "Failed to exchange Apple authorization code: #{error_body["error"]}"
-          end
-
-          parsed_token = JSON.parse(token_response.body)
-          id_token = parsed_token["id_token"]
-          raise StandardId::InvalidRequestError, "Apple response missing id_token" if id_token.blank?
-
-          tokens = extract_token_payload(parsed_token)
-          user_info = verify_id_token(id_token: id_token, client_id: client_id, nonce: nonce)
 
-          build_response(user_info, tokens: tokens)
-        rescue StandardError => e
-          raise e if e.is_a?(StandardId::OAuthError)
+            parsed_token = JSON.parse(token_response.body)
+            id_token = parsed_token["id_token"]
+            raise StandardId::InvalidRequestError, "Apple token response is missing id_token" if id_token.blank?
 
-          raise StandardId::OAuthError, e.message, cause: e
+            user_info = verify_id_token(id_token: id_token, client_id: client_id, nonce: nonce)
+            build_response(user_info, tokens: extract_tokens(parsed_token))
+          end
         end
 
         def verify_id_token(id_token:, client_id: StandardId.config.apple_client_id, nonce: nil)
-          raise StandardId::InvalidRequestError, "Missing id_token" if id_token.blank?
-          raise StandardId::InvalidRequestError, "Apple client_id is not configured" if client_id.blank?
-
-          decoded_token = JWT.decode(id_token, nil, false)
-          header = decoded_token[1]
-
-          jwk = fetch_jwk(kid: header["kid"])
-
-          verified_payload, = JWT.decode(
-            id_token,
-            jwk.public_key,
-            true,
-            algorithms: ["RS256"],
-            iss: ISSUER,
-            verify_iss: true,
-            aud: client_id,
-            verify_aud: true
-          )
+          rescue_to_oauth_error do
+            raise StandardId::InvalidRequestError, "Apple id_token is missing" if id_token.blank?
+            raise StandardId::InvalidRequestError, "Apple client_id is not configured" if client_id.blank?
+
+            _unverified_payload, header = JWT.decode(id_token, nil, false)
+            jwk = fetch_jwk(kid: header["kid"])
+
+            verified_payload, = JWT.decode(
+              id_token,
+              jwk.public_key,
+              true,
+              algorithms: ["RS256"],
+              iss: ISSUER,
+              verify_iss: true,
+              aud: client_id,
+              verify_aud: true
+            )
 
-          # Validate nonce if provided (web flow with server-generated nonce)
-          if nonce.present?
-            token_nonce = verified_payload["nonce"]
-            if token_nonce != nonce
-              raise StandardId::InvalidRequestError,
-                    "ID token nonce mismatch. Expected: #{nonce}, got: #{token_nonce}"
-            end
+            # Web flow with a server-generated nonce; constant-time, and the
+            # error never echoes either value.
+            verify_nonce!(expected: nonce, actual: verified_payload["nonce"])
+
+            {
+              "sub" => verified_payload["sub"],
+              "email" => verified_payload["email"],
+              "email_verified" => verified_payload["email_verified"],
+              "is_private_email" => verified_payload["is_private_email"]
+            }.compact
+          rescue JWT::InvalidAudError => e
+            raise StandardId::InvalidRequestError, "Invalid Apple ID token audience: #{e.message}"
+          rescue JWT::DecodeError => e
+            raise StandardId::InvalidRequestError, "Invalid Apple ID token: #{e.message}"
           end
+        end
 
-          {
-            "sub" => verified_payload["sub"],
-            "email" => verified_payload["email"],
-            "email_verified" => verified_payload["email_verified"],
-            "is_private_email" => verified_payload["is_private_email"]
-          }.compact
-        rescue JWT::InvalidAudError => e
-          raise StandardId::InvalidRequestError, "Invalid Apple ID token audience: #{e.message}"
-        rescue JWT::DecodeError => e
-          raise StandardId::InvalidRequestError, "Invalid Apple ID token: #{e.message}"
-        rescue StandardError => e
-          raise e if e.is_a?(StandardId::OAuthError)
-
-          raise StandardId::OAuthError, e.message, cause: e
+        # Drop the in-process JWKS cache (tests, or after a known rotation).
+        def reset_jwks_cache!
+          @jwks_mutex.synchronize { @jwks_cache = nil }
         end
 
         private
@@ -177,18 +193,18 @@ module StandardId
           raise StandardId::InvalidRequestError, "Apple OAuth is not configured"
         end
 
+        # The same fields StandardId's boot check reports (required_config_fields),
+        # checked again at the point of use because the mobile code exchange
+        # can run with only apple_mobile_client_id set. Names fields, never
+        # values.
         def ensure_full_credentials!(client_id: nil)
           ensure_basic_credentials!(client_id: client_id)
 
-          required = [
-            StandardId.config.apple_private_key,
-            StandardId.config.apple_key_id,
-            StandardId.config.apple_team_id
-          ]
-
-          return unless required.any?(&:blank?)
+          missing = required_config_fields.select { |field| config_value(field).blank? }
+          return if missing.empty?
 
-          raise StandardId::InvalidRequestError, "Apple OAuth credentials are incomplete"
+          raise StandardId::InvalidRequestError,
+                "Apple OAuth credentials are incomplete: #{missing.join(', ')} not set"
         end
 
         def generate_client_secret(client_id: StandardId.config.apple_client_id)
@@ -209,32 +225,77 @@ module StandardId
           JWT.encode(payload, private_key, "ES256", header)
         end
 
+        # Look `kid` up in Apple's JWKS, served from an in-process cache
+        # (JWKS_CACHE_TTL). An unknown `kid` refetches once — Apple may have
+        # rotated — subject to JWKS_MIN_REFRESH_INTERVAL.
         def fetch_jwk(kid:)
-          uri = URI(JWKS_URI)
-          jwks_response = Net::HTTP.get_response(uri)
+          raise StandardId::InvalidRequestError, "Invalid Apple ID token: header has no kid" if kid.blank?
+
+          jwk_data = find_jwk(jwks_keys, kid) || find_jwk(jwks_keys(refresh: true), kid)
+          raise StandardId::InvalidRequestError, "Invalid Apple ID token: signing key not found in Apple's JWKS" unless jwk_data
+
+          JWT::JWK.import(jwk_data)
+        end
+
+        def find_jwk(keys, kid)
+          keys.find { |key| key["kid"] == kid }
+        end
+
+        def jwks_keys(refresh: false)
+          @jwks_mutex.synchronize do
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            cache = @jwks_cache
+
+            stale = cache.nil? || now - cache[:fetched_at] > JWKS_CACHE_TTL
+            forced = refresh && cache && now - cache[:fetched_at] >= JWKS_MIN_REFRESH_INTERVAL
+            if stale || forced
+              @jwks_cache = cache = { keys: download_jwks, fetched_at: now }
+            end
 
-          unless jwks_response.is_a?(Net::HTTPSuccess)
-            raise StandardId::InvalidRequestError, "Failed to fetch Apple JWKS"
+            cache[:keys]
           end
+        end
 
-          jwks_data = JSON.parse(jwks_response.body)
-          jwk_data = jwks_data["keys"].find { |key| key["kid"] == kid }
+        # Fetched through StandardId::HttpClient's connection setup, so the
+        # request gets its timeouts and its private/internal-address guard.
+        # HttpClient has no public plain GET (only get_with_bearer, which would
+        # send an empty Authorization header), hence the two private calls.
+        def download_jwks
+          rescue_to_oauth_error("Failed to fetch Apple JWKS") do
+            uri, resolved_ip = HttpClient.send(:validate_url!, JWKS_URI)
+            response = HttpClient.send(:start_connection, uri, resolved_ip: resolved_ip) do |http|
+              http.request(Net::HTTP::Get.new(uri))
+            end
+            raise StandardId::OAuthError, "Failed to fetch Apple JWKS: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
 
-          raise StandardId::InvalidRequestError, "JWK with kid '#{kid}' not found in Apple's JWKS" unless jwk_data
+            keys = JSON.parse(response.body)["keys"]
+            raise StandardId::OAuthError, "Failed to fetch Apple JWKS: response has no keys" unless keys.is_a?(Array)
 
-          JWT::JWK.import(jwk_data)
-        rescue StandardError => e
-          raise e if e.is_a?(StandardId::OAuthError)
+            keys
+          end
+        end
 
-          raise StandardId::OAuthError, "Failed to fetch JWK: #{e.message}"
+        def error_reason(response)
+          body = JSON.parse(response.body.to_s)
+          reason = body["error"] if body.is_a?(Hash)
+          reason.presence || "HTTP #{response.code}"
+        rescue JSON::ParserError
+          "HTTP #{response.code}"
         end
 
-        def extract_token_payload(parsed_token)
-          {
-            access_token: parsed_token["access_token"],
-            refresh_token: parsed_token["refresh_token"],
-            id_token: parsed_token["id_token"]
-          }.compact
+        def legacy_private_key_from_env
+          value = ENV[LEGACY_PRIVATE_KEY_ENV]
+          return nil if value.blank?
+
+          # An unassigned field's default is re-evaluated on read; warn once.
+          return value if @legacy_private_key_warned
+
+          @legacy_private_key_warned = true
+          StandardId.deprecator.warn(
+            "standard_id-apple: reading apple_private_key from #{LEGACY_PRIVATE_KEY_ENV} is deprecated. " \
+            "Rename the variable to APPLE_PRIVATE_KEY (or assign config.social.apple_private_key explicitly)."
+          )
+          value
         end
       end
     end

data/lib/standard_id/apple/version.rb

@@ -2,6 +2,6 @@
 
 module StandardId
   module Apple
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/standard_id/apple.rb

@@ -1,5 +1,10 @@
 require "active_support/core_ext/numeric/time"
 require "active_support/core_ext/hash/indifferent_access"
 require "standard_id"
+require "standard_id/apple/version"
 require "standard_id/apple/providers/apple"
-require "standard_id/apple/railtie" if defined?(Rails)
+
+# Registers the provider from a Railtie's after_initialize (a no-op outside
+# Rails). Its config fields are declared earlier, before config/initializers,
+# by standard_id's own engine initializer.
+StandardId::Providers.plugin_railtie(:apple, "StandardId::Providers::Apple")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id-apple
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -47,22 +47,16 @@ dependencies:
   name: standard_id
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.29'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.42'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.29'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.42'
 description: Extracted StandardId::Providers::Apple implementation packaged as a standalone
   gem so StandardId installations can opt into Sign in with Apple independently.
 email:
@@ -79,7 +73,6 @@ files:
 - lib/generators/standard_id/apple/install/templates/initializer.rb.erb
 - lib/standard_id/apple.rb
 - lib/standard_id/apple/providers/apple.rb
-- lib/standard_id/apple/railtie.rb
 - lib/standard_id/apple/version.rb
 homepage: https://github.com/rarebit-one/standard_id_apple
 licenses:

data/lib/standard_id/apple/railtie.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module StandardId
-  module Apple
-    class Railtie < ::Rails::Railtie
-      config.after_initialize do
-        StandardId::ProviderRegistry.register(:apple, StandardId::Providers::Apple)
-
-        Rails.logger.debug("[StandardId::Apple] registered provider") if Rails.logger
-      end
-    end
-  end
-end