better_auth-api-key 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a2a00e41f4d86078b25bb86e9b515412d48b732f1817a16a33de6916d4ac287
-  data.tar.gz: 0cea4d53a5bee49499501804ea8a80db5a62555f4c5049b24bb1a7469f7eddcf
+  metadata.gz: 2ac9db4e9d87c466c1bf8ecb7be2978d8ffc17fa168b5a626e82b29ddf36c4c2
+  data.tar.gz: 90f8b579bdf6fd84d7d0d2b0360f479c50800bc5ac724b0fdde6c721a8290e3a
 SHA512:
-  metadata.gz: ae64ad016758516945f7a76860196c381358183df9918f06d2c4588d746bbdb57ccf3c6143ecaf8a14074d33eadea558f321ad0295b6012393bc3a306b442b20
-  data.tar.gz: 65b54fd1360d696467f09888e16c0c76b9681aa6ea9b59137b4c16f132f34993d5ebf30b8a63e99f711ab0da136f9eb1e1ab43de474ff023d6b846058b049296
+  metadata.gz: 970bf80895c95174c91e269560260f6b90281dcc5f3a1be4cd708bcdb53a12dd5d567874a3b046b86867b069000009238982bbd22b980edfa990ed7c68a04b6b
+  data.tar.gz: c52b6d7e9d2b98e77754e9105681bd1c1f8e619b1a0819ab93798a7eacc62cd10a40e11a32debe1a119578de868e76f3982dd366f745d4eb7abb60eab97a4332

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.1 - 2026-04-30
+
+- Fixed API key metadata normalization so symbol and string metadata keys preserve nested metadata payloads.
+- Added upstream parity coverage for API key behavior and error-code response details.
+
+## 0.2.0 - 2026-04-29
+
+- Aligned API key behavior with upstream Better Auth v1.6.9, including key verification, permission checks, metadata updates, expiration, rate limiting, prefix handling, and route response shapes.
+- Expanded package documentation and executable coverage for upstream API key edge cases.
+
 ## 0.1.0
 
 - Extract API key support into the `better_auth-api-key` package.

data/README.md

@@ -25,3 +25,181 @@ auth = BetterAuth.auth(
 ## Notes
 
 This package matches upstream's separate `@better-auth/api-key` package boundary. The Ruby plugin keeps the public `BetterAuth::Plugins.api_key` entrypoint, while core `better_auth` only provides a compatibility shim.
+
+## Upstream parity
+
+The Ruby package implements the upstream server contract for `@better-auth/api-key`: the same API key routes, response shapes, error messages, metadata/permissions decoding, organization-owned keys, multiple configurations, rate limits, usage limits, secondary storage, fallback-to-database behavior, and API-key-backed sessions.
+
+Frontend applications should use the upstream JavaScript client plugin against the Ruby server:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { apiKeyClient } from "@better-auth/api-key/client";
+
+export const authClient = createAuthClient({
+  baseURL: "https://auth.example.com",
+  plugins: [apiKeyClient()]
+});
+```
+
+Ruby does not expose a separate `apiKeyClient()` equivalent; the public Ruby surface is the server plugin and route contract.
+
+## Configuration
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  secondary_storage: redis_storage,
+  plugins: [
+    BetterAuth::Plugins.api_key(
+      default_key_length: 64,
+      default_prefix: "ba_",
+      enable_metadata: true,
+      enable_session_for_api_keys: true,
+      disable_key_hashing: false,
+      rate_limit: {
+        enabled: true,
+        time_window: 86_400_000,
+        max_requests: 10
+      },
+      key_expiration: {
+        default_expires_in: nil,
+        disable_custom_expires_time: false,
+        min_expires_in: 1,
+        max_expires_in: 365
+      },
+      starting_characters_config: {
+        should_store: true,
+        characters_length: 6
+      },
+      storage: "secondary-storage",
+      fallback_to_database: true,
+      custom_storage: nil,
+      permissions: {
+        default_permissions: {files: ["read"]}
+      }
+    )
+  ]
+)
+```
+
+Multiple configurations are supported with required unique `config_id` values:
+
+```ruby
+BetterAuth::Plugins.api_key([
+  {config_id: "user-keys", references: "user", default_prefix: "usr_"},
+  {config_id: "org-keys", references: "organization", default_prefix: "org_"}
+])
+```
+
+Organization-owned keys require `BetterAuth::Plugins.organization` and use organization permissions for `apiKey` actions: `create`, `read`, `update`, and `delete`.
+
+Secondary-storage mode uses upstream storage keys such as `api-key:<hash>`, `api-key:by-id:<id>`, and `api-key:by-ref:<referenceId>`. When `fallback_to_database: true` is enabled, the reference list is treated as a cache and invalidated on writes/deletes so concurrent writers cannot lose IDs; listing falls back to the database source of truth.
+
+## Storage layout
+
+The Ruby gem writes only to the upstream layout; legacy prefixes are read for
+backward compatibility but never produced by new writes:
+
+| Purpose                          | Upstream key (read + write) | Ruby legacy key (read only) |
+|----------------------------------|------------------------------|------------------------------|
+| Lookup by hashed key             | `api-key:<hash>`             | `api-key:key:<hash>`         |
+| Lookup by id                     | `api-key:by-id:<id>`         | `api-key:id:<id>`            |
+| Reference -> [id] list           | `api-key:by-ref:<refId>`     | `api-key:user:<userId>`      |
+
+When upgrading from older Ruby releases the new server transparently keeps
+serving cached entries from the legacy keys while populating the upstream layout
+on the next mutation. Once a key is rewritten, the legacy entry is also deleted
+on `delete-api-key` to keep the layout converging on a single source of truth.
+
+## Plugin metadata
+
+The plugin object exposes the package version (mirroring upstream
+`@better-auth/api-key` 1.6.0+):
+
+```ruby
+auth.options.plugins.find { |plugin| plugin.id == "api-key" }.version
+# => BetterAuth::APIKey::VERSION
+```
+
+## Hashing
+
+The upstream `defaultKeyHasher` equivalent is available as:
+
+```ruby
+BetterAuth::Plugins.default_api_key_hasher("secret-key")
+BetterAuth::APIKey.default_key_hasher("secret-key")
+```
+
+Both return the SHA-256 base64url digest used for stored API keys when `disable_key_hashing` is false.
+
+## Ruby option naming policy
+
+Public option keys use idiomatic Ruby `snake_case` while the wire JSON keeps
+upstream's `camelCase`. The mapping is fixed and intentionally lossless:
+
+| Ruby option (snake_case)              | Wire field (camelCase)        |
+|---------------------------------------|-------------------------------|
+| `config_id`                           | `configId`                    |
+| `default_key_length`                  | `defaultKeyLength`            |
+| `default_prefix`                      | `defaultPrefix`               |
+| `enable_metadata`                     | `enableMetadata`              |
+| `disable_key_hashing`                 | `disableKeyHashing`           |
+| `require_name`                        | `requireName`                 |
+| `enable_session_for_api_keys`         | `enableSessionForAPIKeys`     |
+| `fallback_to_database`                | `fallbackToDatabase`          |
+| `custom_storage`                      | `customStorage`               |
+| `defer_updates`                       | `deferUpdates`                |
+| `references`                          | `references`                  |
+| `key_expiration.default_expires_in`   | `keyExpiration.defaultExpiresIn` |
+| `key_expiration.disable_custom_expires_time` | `keyExpiration.disableCustomExpiresTime` |
+| `key_expiration.max_expires_in`       | `keyExpiration.maxExpiresIn`  |
+| `key_expiration.min_expires_in`       | `keyExpiration.minExpiresIn`  |
+| `starting_characters_config.should_store` | `startingCharactersConfig.shouldStore` |
+| `starting_characters_config.characters_length` | `startingCharactersConfig.charactersLength` |
+| `rate_limit.enabled`                  | `rateLimit.enabled`           |
+| `rate_limit.time_window`              | `rateLimit.timeWindow`        |
+| `rate_limit.max_requests`             | `rateLimit.maxRequests`       |
+
+Endpoint requests/responses always use the upstream `camelCase` field names, so
+TypeScript clients targeting `@better-auth/api-key/client` interoperate without
+configuration changes.
+
+## Organization-owned API keys
+
+Setting `references: "organization"` on a configuration delegates ownership to
+`BetterAuth::Plugins::Organization`, which must be installed alongside this
+plugin. The organization plugin's access-control bundle must define the
+`apiKey` resource with `create`, `read`, `update`, and `delete` actions:
+
+```ruby
+ac = BetterAuth::Plugins.create_access_control(
+  organization: ["update", "delete"],
+  member: ["create", "update", "delete"],
+  invitation: ["create", "cancel"],
+  team: ["create", "update", "delete"],
+  ac: ["create", "read", "update", "delete"],
+  apiKey: ["create", "read", "update", "delete"]
+)
+```
+
+The configured `creator_role` (default `"owner"`) is treated as having
+implicit permission for every `apiKey` action, mirroring upstream's "owner
+bypasses per-action permission check" behavior. All other roles must be granted
+the appropriate `apiKey:*` permission to perform the corresponding action.
+
+## Intentional Ruby-vs-upstream adaptations
+
+The following decisions are explicit and locked behind tests:
+
+- **OpenAPI metadata blocks** embedded in upstream endpoint definitions are not
+  ported. OpenAPI generation is not part of `better_auth-api-key`'s scope.
+- **Browser-only `@better-auth/api-key/client`** helpers are not implemented in
+  Ruby. Apps should call `/api-key/create`, `/api-key/verify`, `/api-key/get`,
+  `/api-key/list`, `/api-key/update`, `/api-key/delete`, and
+  `/api-key/delete-all-expired-api-keys` directly via JSON.
+- **`apikey` table name** mirrors the upstream package (no `_` separator).
+- **Legacy secondary-storage prefixes** (`api-key:key:*`, `api-key:id:*`,
+  `api-key:user:*`) are still honored on read so existing deployments do not
+  lose data when upgrading. New writes always use the upstream layout
+  documented above.

data/lib/better_auth/api_key/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module APIKey
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/better_auth/api_key.rb

@@ -6,5 +6,10 @@ require_relative "plugins/api_key"
 
 module BetterAuth
   module APIKey
+    module_function
+
+    def default_key_hasher(key)
+      Plugins.default_api_key_hasher(key)
+    end
   end
 end

data/lib/better_auth/plugins/api_key.rb

@@ -47,10 +47,15 @@ module BetterAuth
 
     module_function
 
+    def default_api_key_hasher(key)
+      Crypto.sha256(key.to_s, encoding: :base64url)
+    end
+
     def api_key(configurations = {}, options = nil)
       config = api_key_config(configurations, options)
       Plugin.new(
         id: "api-key",
+        version: BetterAuth::APIKey::VERSION,
         hooks: {
           before: [
             {
@@ -153,7 +158,6 @@ module BetterAuth
             prefix: {type: "string", required: false},
             key: {type: "string", required: true, index: true},
             referenceId: {type: "string", required: true, index: true},
-            userId: {type: "string", required: false, index: true, references: {model: "user", field: "id", on_delete: "cascade"}},
             refillInterval: {type: "number", required: false},
             refillAmount: {type: "number", required: false},
             lastRefillAt: {type: "date", required: false},
@@ -177,17 +181,12 @@ module BetterAuth
 
     def api_key_create_endpoint(config)
       Endpoint.new(path: "/api-key/create", method: "POST") do |ctx|
-        body = normalize_hash(ctx.body)
+        body = api_key_normalize_body(ctx.body)
         resolved_config = api_key_resolve_config(ctx.context, config, body[:config_id])
         session = Routes.current_session(ctx, allow_nil: true)
-        if session && body[:user_id]
-          raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["SERVER_ONLY_PROPERTY"])
-        end
-
         reference_id = api_key_create_reference_id!(ctx, body, session, resolved_config)
-        user_id = (resolved_config[:references].to_s == "organization") ? (session&.dig(:user, "id") || body[:user_id]) : reference_id
 
-        api_key_validate_create_update!(body, resolved_config, create: true, client: !!session)
+        api_key_validate_create_update!(body, resolved_config, create: true, client: !ctx.headers.empty?)
         key_prefix = body.key?(:prefix) ? body[:prefix] : resolved_config[:default_prefix]
         key = api_key_generate_key(resolved_config, key_prefix)
         now = Time.now
@@ -198,17 +197,16 @@ module BetterAuth
           start: resolved_config[:starting_characters_config][:should_store] ? key[0, resolved_config[:starting_characters_config][:characters_length].to_i] : nil,
           prefix: key_prefix,
           key: hashed,
-          userId: user_id,
           referenceId: reference_id,
           enabled: true,
           rateLimitEnabled: body.key?(:rate_limit_enabled) ? body[:rate_limit_enabled] : resolved_config[:rate_limit][:enabled],
           rateLimitTimeWindow: body[:rate_limit_time_window] || resolved_config[:rate_limit][:time_window],
           rateLimitMax: body[:rate_limit_max] || resolved_config[:rate_limit][:max_requests],
           requestCount: 0,
-          remaining: body.key?(:remaining) ? body[:remaining] : (body[:refill_amount] || nil),
+          remaining: body.key?(:remaining) ? body[:remaining] : nil,
           refillAmount: body[:refill_amount],
           refillInterval: body[:refill_interval],
-          lastRefillAt: now,
+          lastRefillAt: nil,
           expiresAt: api_key_expires_at(body, resolved_config),
           createdAt: now,
           updatedAt: now,
@@ -224,16 +222,20 @@ module BetterAuth
       Endpoint.new(path: "/api-key/verify", method: "POST") do |ctx|
         body = normalize_hash(ctx.body)
         resolved_config = api_key_resolve_config(ctx.context, config, body[:config_id])
-        key = body[:key] || api_key_get_from_headers(ctx, config)
+        key = body[:key]
         raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "INVALID_API_KEY") if key.to_s.empty?
 
-        record = api_key_validate!(ctx, key, resolved_config, permissions: body[:permissions])
-        record_config = api_key_resolve_config(ctx.context, config, api_key_record_config_id(record))
-        api_key_delete_expired(ctx.context, record_config)
-        ctx.json({valid: true, error: nil, key: api_key_public(record, include_key_field: false)})
+        if resolved_config[:custom_api_key_validator].respond_to?(:call) && !resolved_config[:custom_api_key_validator].call({ctx: ctx, key: key})
+          ctx.json({valid: false, error: {message: API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "KEY_NOT_FOUND"}, key: nil})
+        else
+          record = api_key_validate!(ctx, key, resolved_config, permissions: body[:permissions])
+          record_config = api_key_resolve_config(ctx.context, config, api_key_record_config_id(record))
+          api_key_schedule_cleanup(ctx, record_config)
+          ctx.json({valid: true, error: nil, key: api_key_public(record, include_key_field: false)})
+        end
       rescue APIError => error
         ctx.context.logger.error("Failed to validate API key: #{error.message}") if ctx.context.logger.respond_to?(:error)
-        ctx.json({valid: false, error: {message: error.message, code: api_key_error_code(error)}, key: nil})
+        ctx.json({valid: false, error: api_key_error_payload(error), key: nil})
       rescue => error
         ctx.context.logger.error("Failed to validate API key: #{error.message}") if ctx.context.logger.respond_to?(:error)
         ctx.json({valid: false, error: {message: API_KEY_ERROR_CODES["INVALID_API_KEY"], code: "INVALID_API_KEY"}, key: nil})
@@ -260,7 +262,7 @@ module BetterAuth
 
     def api_key_update_endpoint(config)
       Endpoint.new(path: "/api-key/update", method: "POST") do |ctx|
-        body = normalize_hash(ctx.body)
+        body = api_key_normalize_body(ctx.body)
         resolved_config = api_key_resolve_config(ctx.context, config, body[:config_id])
         session = Routes.current_session(ctx, allow_nil: true)
         user_id = session&.dig(:user, "id") || body[:user_id]
@@ -277,7 +279,7 @@ module BetterAuth
         record_config = api_key_resolve_config(ctx.context, config, api_key_record_config_id(record))
         api_key_authorize_reference!(ctx, record_config, user_id, api_key_record_reference_id(record), "update")
 
-        api_key_validate_create_update!(body, record_config, create: false, client: !!session)
+        api_key_validate_create_update!(body, record_config, create: false, client: api_key_auth_required?(ctx))
         update = api_key_update_payload(body, record_config)
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["NO_VALUES_TO_UPDATE"]) if update.empty?
 
@@ -291,6 +293,8 @@ module BetterAuth
     def api_key_delete_endpoint(config)
       Endpoint.new(path: "/api-key/delete", method: "POST") do |ctx|
         session = Routes.current_session(ctx)
+        raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["USER_BANNED"]) if session[:user]["banned"] == true
+
         body = normalize_hash(ctx.body)
         resolved_config = api_key_resolve_config(ctx.context, config, body[:config_id])
         key_id = body[:key_id]
@@ -310,6 +314,7 @@ module BetterAuth
       Endpoint.new(path: "/api-key/list", method: "GET") do |ctx|
         session = Routes.current_session(ctx)
         query = normalize_hash(ctx.query)
+        api_key_validate_list_query!(query)
         configs = query[:config_id] ? [api_key_resolve_config(ctx.context, config, query[:config_id])] : config.fetch(:configurations, [config])
         reference_id = query[:organization_id] || session[:user]["id"]
         expected_reference = query[:organization_id] ? "organization" : "user"
@@ -338,8 +343,11 @@ module BetterAuth
 
     def api_key_delete_expired_endpoint(config)
       Endpoint.new(path: "/api-key/delete-all-expired-api-keys", method: "POST") do |ctx|
-        api_key_delete_expired(ctx.context, config)
-        ctx.json({success: true})
+        api_key_delete_expired(ctx.context, config, bypass_last_check: true)
+        ctx.json({success: true, error: nil})
+      rescue => error
+        ctx.context.logger.error("[API KEY PLUGIN] Failed to delete expired API keys: #{error.message}") if ctx.context.logger.respond_to?(:error)
+        ctx.json({success: false, error: error})
       end
     end
 
@@ -371,7 +379,13 @@ module BetterAuth
     def api_key_create_reference_id!(ctx, body, session, config)
       if config[:references].to_s == "organization"
         organization_id = body[:organization_id]
-        raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["ORGANIZATION_ID_REQUIRED"]) if organization_id.to_s.empty?
+        if organization_id.to_s.empty?
+          raise APIError.new(
+            "BAD_REQUEST",
+            message: API_KEY_ERROR_CODES["ORGANIZATION_ID_REQUIRED"],
+            code: "ORGANIZATION_ID_REQUIRED"
+          )
+        end
 
         user_id = session&.dig(:user, "id") || body[:user_id]
         raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["UNAUTHORIZED_SESSION"]) if user_id.to_s.empty?
@@ -420,15 +434,33 @@ module BetterAuth
 
     def api_key_check_org_permission!(ctx, user_id, organization_id, action)
       org_plugin = ctx.context.options.plugins.find { |plugin| plugin.id == "organization" }
-      raise APIError.new("INTERNAL_SERVER_ERROR", message: API_KEY_ERROR_CODES["ORGANIZATION_PLUGIN_REQUIRED"]) unless org_plugin
+      unless org_plugin
+        raise APIError.new(
+          "INTERNAL_SERVER_ERROR",
+          message: API_KEY_ERROR_CODES["ORGANIZATION_PLUGIN_REQUIRED"],
+          code: "ORGANIZATION_PLUGIN_REQUIRED"
+        )
+      end
 
       member = ctx.context.adapter.find_one(model: "member", where: [{field: "userId", value: user_id}, {field: "organizationId", value: organization_id}])
-      raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["USER_NOT_MEMBER_OF_ORGANIZATION"]) unless member
+      unless member
+        raise APIError.new(
+          "FORBIDDEN",
+          message: API_KEY_ERROR_CODES["USER_NOT_MEMBER_OF_ORGANIZATION"],
+          code: "USER_NOT_MEMBER_OF_ORGANIZATION"
+        )
+      end
+
+      return member if member["role"].to_s == (org_plugin.options[:creator_role] || "owner").to_s
 
       permissions = {"apiKey" => [action]}
       return member if BetterAuth::Plugins.organization_permission?(ctx, org_plugin.options, member["role"], permissions, organization_id)
 
-      raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["INSUFFICIENT_API_KEY_PERMISSIONS"])
+      raise APIError.new(
+        "FORBIDDEN",
+        message: API_KEY_ERROR_CODES["INSUFFICIENT_API_KEY_PERMISSIONS"],
+        code: "INSUFFICIENT_API_KEY_PERMISSIONS"
+      )
     end
 
     def api_key_sort_records(records, sort_by, direction)
@@ -443,10 +475,31 @@ module BetterAuth
       end
     end
 
+    def api_key_validate_list_query!(query)
+      %i[limit offset].each do |key|
+        next unless query.key?(key)
+
+        value = query[key]
+        raise APIError.new("BAD_REQUEST", message: "Invalid #{key}") unless value.to_s.match?(/\A\d+\z/)
+      end
+
+      direction = query[:sort_direction]
+      return if direction.nil? || %w[asc desc].include?(direction.to_s.downcase)
+
+      raise APIError.new("BAD_REQUEST", message: "Invalid sortDirection")
+    end
+
     def api_key_error_code(error)
       API_KEY_ERROR_CODES.key(error.message) || error.code.to_s
     end
 
+    def api_key_error_payload(error)
+      payload = error.to_h
+      return payload if payload.is_a?(Hash) && payload.key?(:details)
+
+      {message: error.message, code: api_key_error_code(error)}
+    end
+
     def api_key_session_header_config(ctx, config)
       config.fetch(:configurations, [config]).find do |entry|
         entry[:enable_session_for_api_keys] && api_key_get_from_headers(ctx, entry)
@@ -466,12 +519,23 @@ module BetterAuth
       end
 
       record = api_key_validate!(ctx, key, config)
+      api_key_schedule_cleanup(ctx, config)
       if config[:references].to_s != "user"
-        raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"])
+        raise APIError.new(
+          "UNAUTHORIZED",
+          message: API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"],
+          code: "INVALID_REFERENCE_ID_FROM_API_KEY"
+        )
       end
       reference_id = api_key_record_reference_id(record)
       user = ctx.context.internal_adapter.find_user_by_id(reference_id)
-      raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"]) unless user
+      unless user
+        raise APIError.new(
+          "UNAUTHORIZED",
+          message: API_KEY_ERROR_CODES["INVALID_REFERENCE_ID_FROM_API_KEY"],
+          code: "INVALID_REFERENCE_ID_FROM_API_KEY"
+        )
+      end
 
       session = {
         user: user,
@@ -480,7 +544,7 @@ module BetterAuth
           "token" => key,
           "userId" => reference_id,
           "userAgent" => ctx.headers["user-agent"],
-          "ipAddress" => ctx.headers["x-forwarded-for"],
+          "ipAddress" => RequestIP.client_ip(ctx.request || ctx.headers, ctx.context.options),
           "createdAt" => Time.now,
           "updatedAt" => Time.now,
           "expiresAt" => record["expiresAt"] || (Time.now + ctx.context.options.session[:expires_in].to_i)
@@ -493,16 +557,16 @@ module BetterAuth
     def api_key_validate!(ctx, key, config, permissions: nil)
       hashed = api_key_hash(key, config)
       record = api_key_find_by_hash(ctx, hashed, config)
-      raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless record
-      raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless api_key_config_id_matches?(api_key_record_config_id(record), config[:config_id])
-      raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["KEY_DISABLED"]) if record["enabled"] == false
+      raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless record
+      raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["INVALID_API_KEY"]) unless api_key_config_id_matches?(api_key_record_config_id(record), config[:config_id])
+      raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["KEY_DISABLED"]) if record["enabled"] == false
       if record["expiresAt"] && record["expiresAt"] <= Time.now
-        api_key_delete_record(ctx, record, config)
-        raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["KEY_EXPIRED"])
+        api_key_schedule_record_delete(ctx, record, config)
+        raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["KEY_EXPIRED"])
       end
       if record["remaining"].to_i <= 0 && !record["remaining"].nil? && record["refillAmount"].nil?
-        api_key_delete_record(ctx, record, config)
-        raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
+        api_key_schedule_record_delete(ctx, record, config)
+        raise APIError.new("TOO_MANY_REQUESTS", message: API_KEY_ERROR_CODES["USAGE_EXCEEDED"])
       end
 
       api_key_check_permissions!(record, permissions)
@@ -515,38 +579,57 @@ module BetterAuth
       now = Time.now
       update = {lastRequest: now, updatedAt: now}
 
-      if api_key_rate_limited?(record, config, now)
-        raise APIError.new("TOO_MANY_REQUESTS", message: API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"])
+      if (try_again_in = api_key_rate_limit_try_again_in(record, config, now))
+        raise APIError.new(
+          "UNAUTHORIZED",
+          message: API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+          code: "RATE_LIMITED",
+          body: {
+            message: API_KEY_ERROR_CODES["RATE_LIMIT_EXCEEDED"],
+            code: "RATE_LIMITED",
+            details: {tryAgainIn: try_again_in}
+          }
+        )
       end
-      update[:requestCount] = api_key_next_request_count(record, now)
+      update[:requestCount] = api_key_next_request_count(record, now) if api_key_rate_limit_counts_requests?(record, config)
 
       remaining = record["remaining"]
       if !remaining.nil?
         if remaining.to_i <= 0 && record["refillAmount"] && record["refillInterval"]
-          last_refill = api_key_normalize_time(record["lastRefillAt"] || record["lastRequest"] || record["createdAt"])
-          if !last_refill || ((now - last_refill) * 1000) >= record["refillInterval"].to_i
+          last_refill = api_key_normalize_time(record["lastRefillAt"] || record["createdAt"])
+          if !last_refill || ((now - last_refill) * 1000) > record["refillInterval"].to_i
             remaining = record["refillAmount"].to_i
             update[:lastRefillAt] = now
           end
         end
-        raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["USAGE_EXCEEDED"]) if remaining.to_i <= 0
+        raise APIError.new("TOO_MANY_REQUESTS", message: API_KEY_ERROR_CODES["USAGE_EXCEEDED"]) if remaining.to_i <= 0
 
         update[:remaining] = remaining.to_i - 1
       end
       update
     end
 
-    def api_key_rate_limited?(record, config, now)
-      return false if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
+    def api_key_rate_limit_try_again_in(record, config, now)
+      return nil if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
 
       window = record["rateLimitTimeWindow"]
       max = record["rateLimitMax"]
-      return false if window.nil? || max.nil?
+      return nil if window.nil? || max.nil?
 
       last = api_key_normalize_time(record["lastRequest"])
-      return false unless last && ((now - last) * 1000) <= window.to_i
+      return nil unless last
+
+      elapsed = (now - last) * 1000
+      return nil if elapsed > window.to_i
+      return nil unless record["requestCount"].to_i >= max.to_i
 
-      record["requestCount"].to_i >= max.to_i
+      (window.to_i - elapsed).ceil
+    end
+
+    def api_key_rate_limit_counts_requests?(record, config)
+      return false if config[:rate_limit][:enabled] == false || record["rateLimitEnabled"] == false
+
+      !record["rateLimitTimeWindow"].nil? && !record["rateLimitMax"].nil?
     end
 
     def api_key_next_request_count(record, now)
@@ -578,23 +661,25 @@ module BetterAuth
         minimum = create ? 0 : 1
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["INVALID_REMAINING"]) if body[:remaining].to_i < minimum
       end
-      if body.key?(:metadata)
+      if body[:metadata] && (create || config[:enable_metadata])
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["METADATA_DISABLED"]) unless config[:enable_metadata]
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["INVALID_METADATA_TYPE"]) unless body[:metadata].nil? || body[:metadata].is_a?(Hash)
       end
-      server_only_keys = %i[refill_amount refill_interval rate_limit_max rate_limit_time_window rate_limit_enabled remaining]
-      server_only_keys << :permissions unless create
-      if client && server_only_keys.any? { |key| body.key?(key) }
+      server_only_keys = %i[refill_amount refill_interval rate_limit_max rate_limit_time_window rate_limit_enabled remaining permissions]
+      if client && server_only_keys.any? { |key| (create && key == :remaining) ? !body[:remaining].nil? : body.key?(key) }
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["SERVER_ONLY_PROPERTY"])
       end
-      if body[:refill_amount] && !body[:refill_interval]
-        raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["REFILL_INTERVAL_AND_AMOUNT_REQUIRED"])
-      end
-      if body[:refill_interval] && !body[:refill_amount]
+      amount_present = body.key?(:refill_amount)
+      interval_present = body.key?(:refill_interval)
+      if amount_present && !interval_present
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["REFILL_AMOUNT_AND_INTERVAL_REQUIRED"])
       end
+      if interval_present && !amount_present
+        raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["REFILL_INTERVAL_AND_AMOUNT_REQUIRED"])
+      end
       if body.key?(:expires_in)
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["KEY_DISABLED_EXPIRATION"]) if config[:key_expiration][:disable_custom_expires_time]
+        return if body[:expires_in].nil?
 
         days = body[:expires_in].to_f / 86_400
         raise APIError.new("BAD_REQUEST", message: API_KEY_ERROR_CODES["EXPIRES_IN_IS_TOO_SMALL"]) if days < config[:key_expiration][:min_expires_in].to_f
@@ -602,7 +687,7 @@ module BetterAuth
       end
     end
 
-    def api_key_update_payload(body, _config)
+    def api_key_update_payload(body, config)
       update = {}
       update[:name] = body[:name] if body.key?(:name)
       update[:enabled] = body[:enabled] unless body[:enabled].nil?
@@ -613,7 +698,7 @@ module BetterAuth
       update[:rateLimitTimeWindow] = body[:rate_limit_time_window] if body.key?(:rate_limit_time_window)
       update[:rateLimitMax] = body[:rate_limit_max] if body.key?(:rate_limit_max)
       update[:expiresAt] = body[:expires_in].nil? ? nil : Time.now + body[:expires_in].to_i if body.key?(:expires_in)
-      update[:metadata] = api_key_encode_json(body[:metadata]) if body.key?(:metadata)
+      update[:metadata] = api_key_encode_json(body[:metadata]) if body.key?(:metadata) && config[:enable_metadata]
       update[:permissions] = api_key_encode_json(body[:permissions]) if body.key?(:permissions)
       update
     end
@@ -622,16 +707,26 @@ module BetterAuth
       generator = config[:custom_key_generator]
       return generator.call({length: config[:default_key_length], prefix: prefix}) if generator.respond_to?(:call)
 
-      "#{prefix}#{Array.new(config[:default_key_length].to_i) { ("A".."Z").to_a[SecureRandom.random_number(26)] }.join}"
+      alphabet = [*("a".."z"), *("A".."Z")]
+      "#{prefix}#{Array.new(config[:default_key_length].to_i) { alphabet[SecureRandom.random_number(alphabet.length)] }.join}"
     end
 
     def api_key_hash(key, config)
-      config[:disable_key_hashing] ? key.to_s : Crypto.sha256(key.to_s, encoding: :base64url)
+      config[:disable_key_hashing] ? key.to_s : default_api_key_hasher(key)
+    end
+
+    def api_key_normalize_body(raw)
+      body = normalize_hash(raw)
+      return body unless raw.is_a?(Hash)
+
+      metadata_key = raw.key?(:metadata) ? :metadata : ("metadata" if raw.key?("metadata"))
+      body[:metadata] = raw[metadata_key] if metadata_key
+      body
     end
 
     def api_key_expires_at(body, config)
       if body.key?(:expires_in)
-        Time.now + body[:expires_in].to_i
+        Time.now + body[:expires_in].to_i unless body[:expires_in].nil?
       elsif config[:key_expiration][:default_expires_in]
         Time.now + config[:key_expiration][:default_expires_in].to_i
       end
@@ -653,7 +748,9 @@ module BetterAuth
         return record if record
         return nil unless config[:fallback_to_database]
       end
-      ctx.context.adapter.find_one(model: API_KEY_TABLE_NAME, where: [{field: "key", value: hashed}])
+      record = ctx.context.adapter.find_one(model: API_KEY_TABLE_NAME, where: [{field: "key", value: hashed}])
+      api_key_storage_set(ctx, record, config) if record && config[:storage] == "secondary-storage" && config[:fallback_to_database]
+      record
     end
 
     def api_key_find_by_id(ctx, id, config)
@@ -662,7 +759,9 @@ module BetterAuth
         return record if record
         return nil unless config[:fallback_to_database]
       end
-      ctx.context.adapter.find_one(model: API_KEY_TABLE_NAME, where: [{field: "id", value: id}])
+      record = ctx.context.adapter.find_one(model: API_KEY_TABLE_NAME, where: [{field: "id", value: id}])
+      api_key_storage_set(ctx, record, config) if record && config[:storage] == "secondary-storage" && config[:fallback_to_database]
+      record
     end
 
     def api_key_list_for_user(ctx, user_id, config)
@@ -682,7 +781,9 @@ module BetterAuth
       end
       records = ctx.context.adapter.find_many(model: API_KEY_TABLE_NAME, where: [{field: "referenceId", value: reference_id}])
       legacy = ctx.context.adapter.find_many(model: API_KEY_TABLE_NAME, where: [{field: "userId", value: reference_id}])
-      (records + legacy).uniq { |record| record["id"] }
+      combined = (records + legacy).uniq { |record| record["id"] }
+      api_key_storage_populate_reference(ctx, reference_id, combined, config) if config[:storage] == "secondary-storage" && config[:fallback_to_database]
+      combined
     end
 
     def api_key_update_record(ctx, record, update, config, defer: false)
@@ -710,8 +811,34 @@ module BetterAuth
       api_key_storage_delete(ctx, record, config) if config[:storage] == "secondary-storage"
     end
 
-    def api_key_delete_expired(context, config)
+    def api_key_schedule_record_delete(ctx, record, config)
+      task = -> { api_key_delete_record(ctx, record, config) }
+      if config[:defer_updates] && api_key_background_tasks?(ctx)
+        ctx.context.run_in_background(task)
+      else
+        task.call
+      end
+    end
+
+    def api_key_schedule_cleanup(ctx, config)
+      task = -> { api_key_delete_expired(ctx.context, config) }
+      if config[:defer_updates] && api_key_background_tasks?(ctx)
+        ctx.context.run_in_background(task)
+      else
+        task.call
+      end
+    end
+
+    @api_key_last_expired_check = nil
+
+    def api_key_delete_expired(context, config, bypass_last_check: false)
       return unless config[:storage] == "database" || config[:fallback_to_database]
+      unless bypass_last_check
+        now = Time.now
+        return if @api_key_last_expired_check && ((now - @api_key_last_expired_check) * 1000) < 10_000
+
+        @api_key_last_expired_check = now
+      end
 
       expired = context.adapter.find_many(model: API_KEY_TABLE_NAME).select do |record|
         record["expiresAt"] && record["expiresAt"] < Time.now
@@ -734,35 +861,98 @@ module BetterAuth
 
     def api_key_storage_set(ctx, record, config)
       storage = api_key_storage(config, ctx.context)
-      return unless storage
+      unless storage
+        raise APIError.new("INTERNAL_SERVER_ERROR", message: "Secondary storage is required when storage mode is 'secondary-storage'")
+      end
 
       serialized = JSON.generate(api_key_storage_record(record))
       expires_at = api_key_normalize_time(record["expiresAt"])
       ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
       reference_id = api_key_record_reference_id(record)
-      storage.set("api-key:#{record["key"]}", serialized, ttl)
-      storage.set("api-key:by-id:#{record["id"]}", serialized, ttl)
       user_key = "api-key:by-ref:#{reference_id}"
-      ids = JSON.parse(storage.get(user_key).to_s)
-      ids << record["id"] unless ids.include?(record["id"])
-      storage.set(user_key, JSON.generate(ids))
-    rescue JSON::ParserError
-      storage.set("api-key:by-ref:#{api_key_record_reference_id(record)}", JSON.generate([record["id"]]))
+
+      api_key_storage_batch(storage) do
+        operations = [
+          -> { storage.set("api-key:#{record["key"]}", serialized, ttl) },
+          -> { storage.set("api-key:by-id:#{record["id"]}", serialized, ttl) }
+        ]
+        operations << if config[:fallback_to_database]
+          # In fallback mode the ref list is a cache invalidated on writes
+          # to avoid races with concurrent writers of the same reference.
+          -> { storage.delete(user_key) }
+        else
+          -> { api_key_ref_list_add(storage, user_key, record["id"]) }
+        end
+        operations.each(&:call)
+      end
     end
 
     def api_key_storage_delete(ctx, record, config)
       storage = api_key_storage(config, ctx.context)
       return unless storage
 
-      storage.delete("api-key:#{record["key"]}")
-      storage.delete("api-key:by-id:#{record["id"]}")
-      storage.delete("api-key:key:#{record["key"]}")
-      storage.delete("api-key:id:#{record["id"]}")
-      user_key = "api-key:by-ref:#{api_key_record_reference_id(record)}"
-      ids = JSON.parse(storage.get(user_key).to_s).reject { |id| id == record["id"] }
+      reference_id = api_key_record_reference_id(record)
+      user_key = "api-key:by-ref:#{reference_id}"
+
+      api_key_storage_batch(storage) do
+        operations = [
+          -> { storage.delete("api-key:#{record["key"]}") },
+          -> { storage.delete("api-key:by-id:#{record["id"]}") },
+          # Ruby-only legacy storage layout cleanup; upstream never wrote here.
+          -> { storage.delete("api-key:key:#{record["key"]}") },
+          -> { storage.delete("api-key:id:#{record["id"]}") }
+        ]
+        operations << if config[:fallback_to_database]
+          -> { storage.delete(user_key) }
+        else
+          -> { api_key_ref_list_remove(storage, user_key, record["id"]) }
+        end
+        operations.each(&:call)
+      end
+    end
+
+    def api_key_ref_list_add(storage, user_key, id)
+      ids = api_key_safe_parse_id_list(storage.get(user_key))
+      ids << id unless ids.include?(id)
+      storage.set(user_key, JSON.generate(ids))
+    end
+
+    def api_key_ref_list_remove(storage, user_key, id)
+      ids = api_key_safe_parse_id_list(storage.get(user_key)).reject { |existing| existing == id }
       ids.empty? ? storage.delete(user_key) : storage.set(user_key, JSON.generate(ids))
+    end
+
+    def api_key_safe_parse_id_list(raw)
+      return [] if raw.nil?
+
+      parsed = JSON.parse(raw.to_s)
+      parsed.is_a?(Array) ? parsed : []
     rescue JSON::ParserError
-      nil
+      []
+    end
+
+    def api_key_storage_batch(storage, &block)
+      if storage.respond_to?(:batch)
+        storage.batch(&block)
+      else
+        block.call
+      end
+    end
+
+    def api_key_storage_populate_reference(ctx, reference_id, records, config)
+      storage = api_key_storage(config, ctx.context)
+      return unless storage
+
+      ids = []
+      records.each do |record|
+        serialized = JSON.generate(api_key_storage_record(record))
+        expires_at = api_key_normalize_time(record["expiresAt"])
+        ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
+        storage.set("api-key:#{record["key"]}", serialized, ttl)
+        storage.set("api-key:by-id:#{record["id"]}", serialized, ttl)
+        ids << record["id"]
+      end
+      ids.empty? ? storage.delete("api-key:by-ref:#{reference_id}") : storage.set("api-key:by-ref:#{reference_id}", JSON.generate(ids))
     end
 
     def api_key_storage_record(record)
@@ -806,6 +996,10 @@ module BetterAuth
       ctx.context.options.advanced.dig(:background_tasks, :handler).respond_to?(:call)
     end
 
+    def api_key_auth_required?(ctx)
+      !!(ctx.request || (ctx.headers && !ctx.headers.empty?))
+    end
+
     def api_key_get_from_headers(ctx, config)
       getter = config[:custom_api_key_getter]
       return getter.call(ctx) if getter.respond_to?(:call)
@@ -821,11 +1015,9 @@ module BetterAuth
       return if required.nil? || required == {}
 
       actual = api_key_decode_json(record["permissions"]) || {}
-      required.each do |resource, actions|
-        allowed = Array(actual[resource.to_s] || actual[resource.to_sym])
-        unless Array(actions).all? { |action| allowed.include?(action) || allowed.include?(action.to_s) }
-          raise APIError.new("FORBIDDEN", message: API_KEY_ERROR_CODES["INVALID_API_KEY"])
-        end
+      result = Role.new(actual).authorize(required)
+      unless result[:success]
+        raise APIError.new("UNAUTHORIZED", message: API_KEY_ERROR_CODES["KEY_NOT_FOUND"], code: "KEY_NOT_FOUND")
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-api-key
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sebastian Sala