better_auth-api-key 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcc6f211dc2f80b2524e48f5fff897caf734ee3316ba5620379820571d2f0729
-  data.tar.gz: 1f111ffa2b175c3ea04c356c1afbc18d361b9b02717c9dea3dd32954b4ac57dc
+  metadata.gz: 4685ca8ec56b74b3bfb4a83e24a1bc38c4366fa3419b0b32362fa719e1aee8b1
+  data.tar.gz: 86575631ac666a0edc77a5bb4eb693cf6754856fec26d92f6371351d2843349e
 SHA512:
-  metadata.gz: fa1c89732eaeba2c8d7d064664d9a34e23287744c534dc19d45254837bd7481b0271b536364e64835b4f750e14d95c3f118bd7ddc0947f02077cbb8d35675034
-  data.tar.gz: 8146aca0fd1ad983d0285eedcc707bcfff2336bac8b64c91141af93ca9e231d8d42b67899a405beef304785464ddedf8fdb06ad5e1dad7d74ac7bc754b5981f2
+  metadata.gz: 6437621c3f7b089604ef61588576b144a9ef996e07808e6ffacff8073900ecf007723c4e3221283ffdebbce7e841b208c56948d30ec950aabdcc61b06a226405
+  data.tar.gz: a57b0e0d4c36a030387420d07d5fd914f70777c9a61cac62e914bc24c1d7f1d060158cbde1df5d789de6fca748d927d7d0f9681ae11f7022f1228fe4fffe6156

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+## 0.7.0 - 2026-05-05
+
+- Changed API-key-backed sessions to expose `tokenFingerprint` instead of storing the raw API key in `session["token"]`.
+- Hardened API key listing and expired-key cleanup behavior.
+- Improved API key metadata handling and added regression coverage for session fingerprint behavior.
+
 ## 0.2.1 - 2026-04-30
 
 - Fixed API key metadata normalization so symbol and string metadata keys preserve nested metadata payloads.

data/README.md

@@ -44,6 +44,31 @@ export const authClient = createAuthClient({
 
 Ruby does not expose a separate `apiKeyClient()` equivalent; the public Ruby surface is the server plugin and route contract.
 
+| Method | Path | Ruby API method |
+| --- | --- | --- |
+| `POST` | `/api-key/create` | `auth.api.create_api_key` |
+| `POST` | `/api-key/verify` | `auth.api.verify_api_key` |
+| `GET` | `/api-key/get` | `auth.api.get_api_key` |
+| `GET` | `/api-key/list` | `auth.api.list_api_keys` |
+| `POST` | `/api-key/update` | `auth.api.update_api_key` |
+| `POST` | `/api-key/delete` | `auth.api.delete_api_key` |
+| `POST` | `/api-key/delete-all-expired-api-keys` | `auth.api.delete_all_expired_api_keys` |
+
+## Operational notes
+
+Expired API key cleanup runs against the database when `storage` is `"database"`
+or `fallback_to_database` is true. Secondary-storage-only deployments should
+align Redis or KV TTLs with API key expiration because database cleanup does not
+purge secondary-only keys.
+
+The scheduled expired-key cleanup throttle is per Ruby process. It is not
+coordinated across web workers, hosts, or background job runners.
+
+When `defer_updates` is combined with `advanced.background_tasks.handler`, usage
+updates such as request counts, remaining limits, refill state, and scheduled
+cleanup can be reordered under concurrency. Use database transactions or
+deployment-level coordination if strict counters are required.
+
 ## Configuration
 
 ```ruby
@@ -165,6 +190,9 @@ Endpoint requests/responses always use the upstream `camelCase` field names, so
 TypeScript clients targeting `@better-auth/api-key/client` interoperate without
 configuration changes.
 
+The cleanup route is also exposed through `auth.api.delete_all_expired_api_keys`
+and returns `{success: true, error: nil}` on success.
+
 ## Organization-owned API keys
 
 Setting `references: "organization"` on a configuration delegates ownership to

data/lib/better_auth/api_key/adapter.rb

@@ -61,10 +61,14 @@ module BetterAuth
         if config[:storage] == "secondary-storage"
           begin
             storage_instance = storage(config, ctx.context)
-            ids = JSON.parse((storage_instance&.get(storage_key_by_reference(reference_id)) || storage_instance&.get("api-key:user:#{reference_id}")).to_s)
+            raw_ids = storage_instance&.get(storage_key_by_reference(reference_id)) || storage_instance&.get("api-key:user:#{reference_id}")
+            ids = parse_id_list!(raw_ids)
             records = ids.filter_map { |id| find_by_id(ctx, id, config) }
             return records unless records.empty? && config[:fallback_to_database]
-          rescue JSON::ParserError, NoMethodError
+          rescue JSON::ParserError, NoMethodError => error
+            if ctx.context.respond_to?(:logger) && ctx.context.logger.respond_to?(:warn)
+              ctx.context.logger.warn("[API KEY PLUGIN] Corrupt api-key reference index for #{reference_id.inspect}: #{error.class}: #{error.message}")
+            end
             return [] unless config[:fallback_to_database]
           end
         end
@@ -88,7 +92,7 @@ module BetterAuth
 
         if defer && config[:defer_updates] && BetterAuth::Plugins.api_key_background_tasks?(ctx)
           scheduled = record.merge(update.transform_keys { |key| BetterAuth::Schema.storage_key(key) })
-          ctx.context.run_in_background(performer)
+          BetterAuth::APIKey::Utils.run_background_task(ctx, "Deferred API key update", performer)
           scheduled
         else
           performer.call
@@ -103,7 +107,7 @@ module BetterAuth
       def schedule_record_delete(ctx, record, config)
         task = -> { delete_record(ctx, record, config) }
         if config[:defer_updates] && BetterAuth::APIKey::Utils.background_tasks?(ctx)
-          ctx.context.run_in_background(task)
+          BetterAuth::APIKey::Utils.run_background_task(ctx, "Deferred API key delete", task)
         else
           task.call
         end
@@ -124,6 +128,11 @@ module BetterAuth
         updated
       end
 
+      def legacy_metadata_migration_needed?(record)
+        parsed = BetterAuth::APIKey::Utils.decode_json(record["metadata"])
+        parsed.is_a?(Hash) && BetterAuth::APIKey::Utils.encode_json(parsed) != record["metadata"]
+      end
+
       def storage(config, context = nil)
         config[:custom_storage] || context&.options&.secondary_storage
       end
@@ -198,13 +207,21 @@ module BetterAuth
 
       def safe_parse_id_list(raw)
         return [] if raw.nil?
+        return raw.dup if raw.is_a?(Array)
 
-        parsed = JSON.parse(raw.to_s)
-        parsed.is_a?(Array) ? parsed : []
+        parse_id_list!(raw)
       rescue JSON::ParserError
         []
       end
 
+      def parse_id_list!(raw)
+        return [] if raw.nil?
+        return raw.dup if raw.is_a?(Array)
+
+        parsed = JSON.parse(raw.to_s)
+        parsed.is_a?(Array) ? parsed : []
+      end
+
       def batch(storage_instance, &block)
         if storage_instance.respond_to?(:batch)
           storage_instance.batch(&block)
@@ -217,17 +234,25 @@ module BetterAuth
         storage_instance = storage(config, ctx.context)
         return unless storage_instance
 
-        ids = []
-        records.each do |record|
-          serialized = JSON.generate(storage_record(record))
-          expires_at = BetterAuth::APIKey::Utils.normalize_time(record["expiresAt"])
-          ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
-          storage_instance.set(storage_key_by_hash(record["key"]), serialized, ttl)
-          storage_instance.set(storage_key_by_id(record["id"]), serialized, ttl)
-          ids << record["id"]
+        batch(storage_instance) do
+          ids = []
+          records.each do |record|
+            serialized = JSON.generate(storage_record(record))
+            expires_at = BetterAuth::APIKey::Utils.normalize_time(record["expiresAt"])
+            ttl = expires_at ? [(expires_at - Time.now).to_i, 0].max : nil
+            storage_instance.set(storage_key_by_hash(record["key"]), serialized, ttl)
+            storage_instance.set(storage_key_by_id(record["id"]), serialized, ttl)
+            ids << record["id"]
+          end
+          reference_key = storage_key_by_reference(reference_id)
+          ids.empty? ? storage_instance.delete(reference_key) : storage_instance.set(reference_key, JSON.generate(ids))
         end
-        reference_key = storage_key_by_reference(reference_id)
-        ids.empty? ? storage_instance.delete(reference_key) : storage_instance.set(reference_key, JSON.generate(ids))
+      end
+
+      def batch_migrate_legacy_metadata(ctx, records, config)
+        return records unless config[:storage] == "database" || config[:fallback_to_database]
+
+        records.map { |record| migrate_legacy_metadata(ctx, record, config) }
       end
 
       def storage_record(record)

data/lib/better_auth/api_key/routes/delete_all_expired_api_keys.rb

@@ -14,7 +14,7 @@ module BetterAuth
             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})
+            ctx.json({success: false, error: {message: error.message.to_s, name: error.class.name}})
           end
         end
       end

data/lib/better_auth/api_key/routes/index.rb

@@ -51,18 +51,20 @@ module BetterAuth
           @last_expired_check = now
         end
 
-        expired = context.adapter.find_many(model: BetterAuth::Plugins::API_KEY_TABLE_NAME).select do |record|
-          record["expiresAt"] && record["expiresAt"] < Time.now
-        end
-        expired.each do |record|
-          context.adapter.delete(model: BetterAuth::Plugins::API_KEY_TABLE_NAME, where: [{field: "id", value: record["id"]}])
-        end
+        now = Time.now
+        context.adapter.delete_many(
+          model: BetterAuth::Plugins::API_KEY_TABLE_NAME,
+          where: [
+            {field: "expiresAt", value: now, operator: "lt"},
+            {field: "expiresAt", value: nil, operator: "ne"}
+          ]
+        )
       end
 
       def schedule_cleanup(ctx, config)
         task = -> { delete_expired(ctx.context, config) }
         if config[:defer_updates] && BetterAuth::APIKey::Utils.background_tasks?(ctx)
-          ctx.context.run_in_background(task)
+          BetterAuth::APIKey::Utils.run_background_task(ctx, "Deferred API key cleanup", task)
         else
           task.call
         end

data/lib/better_auth/api_key/routes/list_api_keys.rb

@@ -31,9 +31,21 @@ module BetterAuth
             records = records.drop(offset) if offset
             records = records.first(limit) if limit
             records.each { |record| BetterAuth::Plugins.api_key_delete_expired(ctx.context, BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))) }
+            migration_records = records.select { |record| BetterAuth::APIKey::Adapter.legacy_metadata_migration_needed?(record) }
+            if migration_records.any?
+              BetterAuth::APIKey::Utils.run_background_task(
+                ctx,
+                "API key metadata migration",
+                lambda do
+                  migration_records.each do |record|
+                    record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
+                    BetterAuth::APIKey::Adapter.batch_migrate_legacy_metadata(ctx, [record], record_config)
+                  end
+                end
+              )
+            end
             api_keys = records.map do |record|
-              record_config = BetterAuth::Plugins.api_key_resolve_config(ctx.context, config, BetterAuth::Plugins.api_key_record_config_id(record))
-              BetterAuth::Plugins.api_key_public(BetterAuth::Plugins.api_key_migrate_legacy_metadata(ctx, record, record_config), include_key_field: false)
+              BetterAuth::Plugins.api_key_public(record, include_key_field: false)
             end
             ctx.json({apiKeys: api_keys, total: total, limit: limit, offset: offset})
           end

data/lib/better_auth/api_key/session.rb

@@ -46,7 +46,7 @@ module BetterAuth
           user: user,
           session: {
             "id" => record["id"],
-            "token" => key,
+            "tokenFingerprint" => BetterAuth::Plugins.default_api_key_hasher(key),
             "userId" => reference_id,
             "userAgent" => ctx.headers["user-agent"],
             "ipAddress" => BetterAuth::RequestIP.client_ip(ctx.request || ctx.headers, ctx.context.options),

data/lib/better_auth/api_key/utils.rb

@@ -85,6 +85,16 @@ module BetterAuth
         ctx.context.options.advanced.dig(:background_tasks, :handler).respond_to?(:call)
       end
 
+      def run_background_task(ctx, label, task)
+        wrapped = lambda do
+          task.call
+        rescue => error
+          logger = ctx.context.logger if ctx.context.respond_to?(:logger)
+          logger.error("[API KEY PLUGIN] #{label} failed: #{error.message}") if logger.respond_to?(:error)
+        end
+        ctx.context.run_in_background(wrapped)
+      end
+
       def auth_required?(ctx)
         !!(ctx.request || (ctx.headers && !ctx.headers.empty?))
       end

data/lib/better_auth/api_key/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module APIKey
-    VERSION = "0.6.2"
+    VERSION = "0.7.0"
   end
 end

metadata

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