Store the hashed value of the API key in the database

[thivindu]

Current Limitation

Currently the API key is stored as plain text in the database. This leads to security issues.

Suggested Improvement

Hashed the API key and store that in the database with the hash salt.

Version

No response

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Enhance API key security by storing hashed API keys instead of plaintext in the database, using salted hashing similar to the existing gateway_tokens pattern. This prevents API key recovery even if the database is compromised.

Observations

The project is a Go-based API management platform with a gateway controller, platform API service, and developer portal. It uses SQLite for gateway storage and already implements token hashing for gateway authentication tokens (in the gateway_tokens table with token_hash and salt columns). API keys are currently stored in the api_keys table in the gateway-controller database, loaded into an in-memory store at startup, and distributed to policy engines via xDS for validation during request processing. The codebase has established patterns for cryptographic operations including Argon2id password hashing, random salt generation, and constant-time comparison.

Assumptions

Assumption 1: Hashing Algorithm Choice

Options Considered:

• Argon2id: Memory-hard KDF providing maximum security against offline attacks, following the existing password hashing pattern in common/authenticators/basic_authenticator.go
• SHA-256 with per-key salt: Fast hashing appropriate for high-entropy keys, following the existing gateway_tokens pattern in platform-api

Chosen Option: SHA-256 with per-key salt

Rationale: This aligns with the existing gateway_tokens implementation pattern, maintains performance for high-throughput request validation, and is appropriate for randomly generated high-entropy API keys (as confirmed by web search results indicating fast hashing is acceptable for API keys vs passwords).

Assumption 2: Migration Strategy for Existing API Keys

Options Considered:

• Hash existing keys in-place: Assume existing stored keys are still the original generated values and hash them during migration
• Force regeneration: Mark existing keys for regeneration by developers
• Support both temporarily: Allow validation against both plaintext and hashed keys during a transition period

Chosen Option: Hash existing keys in-place

Rationale: Since API keys are stored plaintext currently, we can hash them during migration and maintain continuity. This provides the smoothest developer experience and avoids requiring immediate regeneration of all keys.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Database Schema and Hashing Utilities

Update the database schema to store hashed API keys with salts, and create reusable hashing utilities following the established gateway_tokens pattern.

Task 1: Add Hash and Salt Columns to API Keys Table

Modify the database schema to support hashed storage while maintaining backward compatibility during migration.

• Update gateway/gateway-controller/pkg/storage/gateway-controller-db.sql to add api_key_hash VARCHAR(255) and salt VARCHAR(255) columns to the api_keys table
• Keep the existing api_key column temporarily to support migration (will be removed after migration is complete)
• Add a migration script or version bump (current version is 5) to handle the schema change on existing databases
• Update indexes to use api_key_hash instead of api_key for uniqueness constraints once migration is complete

Task 2: Create API Key Hashing Utilities

Build shared hashing utilities in the gateway-controller following the salt generation and hashing patterns already established in platform-api's gateway token handling.

• Create hashing utility functions in gateway/gateway-controller/pkg/utils/ directory (or extend existing crypto utilities if present)
• Implement GenerateSalt() function to create 32-byte random salts using crypto/rand, returning hex-encoded strings
• Implement HashAPIKey(apiKey string, salt string) (string, error) using SHA-256 to hash the concatenation of apiKey and decoded salt
• Implement VerifyAPIKey(presentedKey string, storedHash string, salt string) bool that hashes the presented key and uses crypto/subtle.ConstantTimeCompare() for comparison
• Follow the existing pattern from platform-api/src/internal/service/gateway.go for salt generation and token hashing

🤖 Prompt for AI agents

This phase sets up the database schema and cryptographic utilities for hashed
API key storage. The goal is to add the necessary database columns and create
reusable hashing functions following the existing gateway_tokens pattern.

Update the database schema:
- Add `api_key_hash VARCHAR(255)` and `salt VARCHAR(255)` columns to the
`api_keys` table in
`gateway/gateway-controller/pkg/storage/gateway-controller-db.sql`
- Keep the existing `api_key` column for backward compatibility during migration
- Bump the database version and create migration logic to handle schema changes
- Update uniqueness indexes to use `api_key_hash` instead of `api_key`

Create hashing utilities in `gateway/gateway-controller/pkg/utils/`:
- Implement `GenerateSalt()` to generate 32-byte random salts using
`crypto/rand`, return hex-encoded strings
- Implement `HashAPIKey(apiKey, salt string)` using SHA-256 on apiKey
concatenated with decoded salt
- Implement `VerifyAPIKey(presentedKey, storedHash, salt string)` using
`crypto/subtle.ConstantTimeCompare()` for timing-safe comparison
- Follow the pattern from `platform-api/src/internal/service/gateway.go` for
consistency

Phase 2: Update API Key Generation and Storage

Modify the API key generation and storage flow to hash keys before persisting them to the database, ensuring the plaintext key is only returned once during creation.

Task 1: Update API Key Generation to Hash Before Storage

Modify the API key generation logic to generate a random API key, hash it, and store only the hash and salt.

• Update API key generation in gateway/gateway-controller/pkg/utils/api_key.go or wherever GenerateAPIKey functionality exists
• Generate a high-entropy random API key (at least 32 bytes, base64 or hex encoded for URL safety)
• Generate a unique salt for this key using the new GenerateSalt() utility
• Hash the API key using the new HashAPIKey() utility
• Store the hash and salt in the database while keeping a reference to the plaintext key for the return response

Task 2: Update Storage Layer to Handle Hash and Salt

Modify the storage layer to persist hashed values and adapt the in-memory store to work with hashed keys.

• Update the Storage interface and SQLite implementation in gateway/gateway-controller/pkg/storage/ to accept hash and salt fields when storing API keys
• Modify APIKeyStore in gateway/gateway-controller/pkg/storage/apikey_store.go to store the hash instead of plaintext in the value-based index (or maintain both temporarily during migration)
• Update the database INSERT/UPDATE operations to include api_key_hash and salt columns
• Ensure the API key creation response returns the plaintext key to the caller (this is the only time it will be visible)

Task 3: Update Developer Portal Integration

Modify the developer portal's API key generation endpoints to handle hashed keys from the control plane.

• Review and update portals/developer-portal/src/controllers/devportalController.js to ensure generateAPIKeys and regenerateAPIKeys functions properly handle the response containing only the plaintext key on generation
• Ensure the generated plaintext key is shown to the user immediately and clearly indicate it cannot be retrieved later
• Update any application key generation flows in portals/developer-portal/src/routes/devportalRoute.js as needed

🤖 Prompt for AI agents

This phase modifies the API key generation and storage flow to hash keys before
database persistence. The goal is to ensure plaintext keys are only returned
once during creation and never stored.

Update API key generation logic:
- Modify `GenerateAPIKey` in `gateway/gateway-controller/pkg/utils/api_key.go`
to generate high-entropy random keys (at least 32 bytes, base64/hex encoded)
- Generate a unique salt using `GenerateSalt()`
- Hash the API key using `HashAPIKey()`
- Keep a reference to the plaintext key for the response, but store only hash
and salt

Update storage layer:
- Modify the Storage interface and SQLite implementation in
`gateway/gateway-controller/pkg/storage/` to accept `api_key_hash` and `salt`
fields
- Update `APIKeyStore` in
`gateway/gateway-controller/pkg/storage/apikey_store.go` to index by hash
instead of plaintext
- Update INSERT/UPDATE operations to include hash and salt columns
- Ensure API key creation response returns the plaintext key

Update developer portal:
- Modify `generateAPIKeys` and `regenerateAPIKeys` in
`portals/developer-portal/src/controllers/devportalController.js` to handle
responses with plaintext keys
- Display the plaintext key to users immediately with a warning that it cannot
be retrieved later
- Update related flows in
`portals/developer-portal/src/routes/devportalRoute.js`

Phase 3: Update Validation Logic and Migration

Modify the API key validation flow to compare hashed values and migrate existing plaintext keys to hashed storage.

Task 1: Update Policy Engine Validation

Modify the API key validation logic in the policy engine to hash presented keys before comparison.

• Update ValidateAPIKey() in sdk/gateway/policy/v1alpha/api_key.go to accept hash and salt alongside or instead of plaintext key
• Modify validation logic to hash the presented API key and compare against stored hash using crypto/subtle.ConstantTimeCompare()
• Update the xDS API key data structures in sdk/gateway/policyengine/v1/api_key_xds.go to include hash and salt fields instead of plaintext keys

Task 2: Update xDS Distribution

Modify the xDS snapshot manager to distribute hashed keys instead of plaintext keys to policy engines.

• Update APIKeyStateResource structure in gateway/gateway-controller/pkg/apikeyxds/ to include api_key_hash and salt fields instead of plaintext api_key
• Modify the snapshot generation logic to load and distribute hash/salt values from the database
• Update the translator that converts stored API keys into xDS resources to use the new hash/salt fields

Task 3: Create Migration Path for Existing Keys

Implement a one-time migration to hash existing plaintext API keys in the database.

• Create a migration function in gateway/gateway-controller/pkg/storage/ or migration scripts to:
  • Query all API keys where api_key_hash is NULL (indicating unmigrated plaintext keys)
  • For each plaintext key, generate a salt and hash the key
  • Update the record with the hash and salt
• Ensure the migration can be run safely (idempotent) and logs progress
• After migration is verified, optionally remove the api_key plaintext column in a follow-up schema change

Task 4: Update API Key Revocation and Regeneration

Ensure revocation and regeneration flows work correctly with hashed keys.

• Update revocation logic in the developer portal and gateway-controller to work with key IDs rather than plaintext values
• Modify regeneration endpoints in portals/developer-portal/src/controllers/devportalController.js to generate new hash/salt pairs
• Ensure regeneration invalidates the old hash and creates a new one, returning the new plaintext key only once

🤖 Prompt for AI agents

This phase updates validation logic to work with hashed keys and migrates
existing plaintext keys. The goal is to enable hash-based validation in the
policy engine and safely migrate all existing data.

Update policy engine validation:
- Modify `ValidateAPIKey()` in `sdk/gateway/policy/v1alpha/api_key.go` to accept
hash and salt instead of plaintext
- Hash the presented API key and compare using
`crypto/subtle.ConstantTimeCompare()`
- Update xDS data structures in `sdk/gateway/policyengine/v1/api_key_xds.go` to
include hash and salt fields

Update xDS distribution:
- Modify `APIKeyStateResource` in `gateway/gateway-controller/pkg/apikeyxds/` to
include `api_key_hash` and `salt` instead of plaintext `api_key`
- Update snapshot generation to load and distribute hash/salt values from the
database
- Update the translator that converts stored API keys to xDS resources

Create migration for existing keys:
- Implement migration function in `gateway/gateway-controller/pkg/storage/` to
query API keys where `api_key_hash` is NULL
- For each plaintext key, generate a salt, hash the key, and update the record
- Make migration idempotent and add progress logging
- Plan for removing the plaintext `api_key` column after verification

Update revocation and regeneration:
- Modify revocation logic to work with key IDs instead of plaintext values
- Update regeneration endpoints in
`portals/developer-portal/src/controllers/devportalController.js` to generate
new hash/salt pairs
- Ensure regeneration invalidates old hashes and returns new plaintext keys only
once

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase sets up the database schema and cryptographic utilities for hashed
API key storage. The goal is to add the necessary database columns and create
reusable hashing functions following the existing gateway_tokens pattern.

Update the database schema:
- Add `api_key_hash VARCHAR(255)` and `salt VARCHAR(255)` columns to the
`api_keys` table in
`gateway/gateway-controller/pkg/storage/gateway-controller-db.sql`
- Keep the existing `api_key` column for backward compatibility during migration
- Bump the database version and create migration logic to handle schema changes
- Update uniqueness indexes to use `api_key_hash` instead of `api_key`

Create hashing utilities in `gateway/gateway-controller/pkg/utils/`:
- Implement `GenerateSalt()` to generate 32-byte random salts using
`crypto/rand`, return hex-encoded strings
- Implement `HashAPIKey(apiKey, salt string)` using SHA-256 on apiKey
concatenated with decoded salt
- Implement `VerifyAPIKey(presentedKey, storedHash, salt string)` using
`crypto/subtle.ConstantTimeCompare()` for timing-safe comparison
- Follow the pattern from `platform-api/src/internal/service/gateway.go` for
consistency
===============================================================================

Task: 2

This phase modifies the API key generation and storage flow to hash keys before
database persistence. The goal is to ensure plaintext keys are only returned
once during creation and never stored.

Update API key generation logic:
- Modify `GenerateAPIKey` in `gateway/gateway-controller/pkg/utils/api_key.go`
to generate high-entropy random keys (at least 32 bytes, base64/hex encoded)
- Generate a unique salt using `GenerateSalt()`
- Hash the API key using `HashAPIKey()`
- Keep a reference to the plaintext key for the response, but store only hash
and salt

Update storage layer:
- Modify the Storage interface and SQLite implementation in
`gateway/gateway-controller/pkg/storage/` to accept `api_key_hash` and `salt`
fields
- Update `APIKeyStore` in
`gateway/gateway-controller/pkg/storage/apikey_store.go` to index by hash
instead of plaintext
- Update INSERT/UPDATE operations to include hash and salt columns
- Ensure API key creation response returns the plaintext key

Update developer portal:
- Modify `generateAPIKeys` and `regenerateAPIKeys` in
`portals/developer-portal/src/controllers/devportalController.js` to handle
responses with plaintext keys
- Display the plaintext key to users immediately with a warning that it cannot
be retrieved later
- Update related flows in
`portals/developer-portal/src/routes/devportalRoute.js`
===============================================================================

Task: 3

This phase updates validation logic to work with hashed keys and migrates
existing plaintext keys. The goal is to enable hash-based validation in the
policy engine and safely migrate all existing data.

Update policy engine validation:
- Modify `ValidateAPIKey()` in `sdk/gateway/policy/v1alpha/api_key.go` to accept
hash and salt instead of plaintext
- Hash the presented API key and compare using
`crypto/subtle.ConstantTimeCompare()`
- Update xDS data structures in `sdk/gateway/policyengine/v1/api_key_xds.go` to
include hash and salt fields

Update xDS distribution:
- Modify `APIKeyStateResource` in `gateway/gateway-controller/pkg/apikeyxds/` to
include `api_key_hash` and `salt` instead of plaintext `api_key`
- Update snapshot generation to load and distribute hash/salt values from the
database
- Update the translator that converts stored API keys to xDS resources

Create migration for existing keys:
- Implement migration function in `gateway/gateway-controller/pkg/storage/` to
query API keys where `api_key_hash` is NULL
- For each plaintext key, generate a salt, hash the key, and update the record
- Make migration idempotent and add progress logging
- Plan for removing the plaintext `api_key` column after verification

Update revocation and regeneration:
- Modify revocation logic to work with key IDs instead of plaintext values
- Update regeneration endpoints in
`portals/developer-portal/src/controllers/devportalController.js` to generate
new hash/salt pairs
- Ensure regeneration invalidates old hashes and returns new plaintext keys only
once

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!