if (cached && now < cached.expiresAt) {
  return cached.value;
}

try {
  const command = new GetSecretValueCommand({ SecretId: secretId });
  const response = await this.client.send(command);

  if (!response.SecretString) {
    throw new Error(`Secret ${secretId} has no string value.`);
  }

  const secretValue = response.SecretString;
  
  // Cache the result with expiration
  this.cache.set(secretId, {
    value: secretValue,
    expiresAt: now + this.CACHE_TTL_MS,
    versionId: response.VersionId,
  });

  return secretValue;
} catch (error) {
  // Fallback to cache if provider is unavailable and cache is stale but not expired?
  // Strategy: Fail open is dangerous. Fail closed.
  // However, for resilience, you might allow serving stale cache if provider is down
  // but this should be configurable.
  if (cached) {
    console.warn(`Provider unavailable, serving stale cache for ${secretId}`);
    return cached.value;
  }
  throw new Error(`Failed to retrieve secret ${secretId}: ${error}`);
}

}

/**

• Triggers rotation of a secret.

• Implements a dual-key strategy by generating a new key

• and updating the secret, while the old key remains valid

• until the rotation completes on the target service. */ async rotateApiKey(secretId: string, generateKeyFn: () => Promise<string>): Promise<void> { try { // 1. Generate new key const newKey = await generateKeyFn();

  // 2. Update secret in SMS const putCommand = new GetSecretValueCommand({ SecretId: secretId }); // Note: In practice, use PutSecretValueCommand // This is a placeholder for the actual SDK call

  // 3. Signal target service to accept new key (out of band) // 4. Verify new key works // 5. Revoke old key

  // For this example, we simulate the update console.log(Rotating key for ${secretId}. New key generated.);

  // Invalidate cache to force fetch of new key this.cache.delete(secretId);

} catch (error) {

  throw new Error(`Rotation failed for ${secretId}: ${error}`);
}

}

/**

• Utility to generate a cryptographically secure API key. */ static generateSecureKey(length: number = 32): string { return randomBytes(length).toString("base64url"); } }

**Rationale:**
- **Caching Strategy:** The provider caches keys for a short duration (15 minutes). This balances performance (avoiding constant API calls to the secret manager) with security (ensuring rotated keys propagate quickly).
- **Fail-Closed Design:** The `getApiKey` method throws an error if the secret cannot be retrieved and no cache exists. This prevents the application from starting or operating with missing credentials.
- **Rotation Support:** The `rotateApiKey` method outlines the workflow for rotation. In production, this would integrate with AWS Secrets Manager's rotation lambdas or Vault's dynamic secrets to handle the dual-key lifecycle automatically.

## Pitfall Guide

### Common Mistakes

1.  **Hardcoding Keys in Source Control:**
    Developers occasionally commit keys to Git repositories, even in private repos. Once committed, the key exists in the repository history forever.
    *   *Remediation:* Implement pre-commit hooks (e.g., `gitleaks`, `detect-secrets`) to block commits containing key patterns.

2.  **Over-Privileged Keys:**
    Using a single API key with admin-level access for all services. If one service is compromised, the attacker gains full control.
    *   *Remediation:* Create distinct keys per service with minimum required permissions. Use vendor-specific scoping features.

3.  **Logging Keys in Plaintext:**
    Application logs often capture request headers or configuration dumps, inadvertently exposing keys.
    *   *Remediation:* Configure logging frameworks to redact sensitive fields. Use structured logging with explicit allow-lists for fields.

4.  **Ignoring Key Expiration:**
    Keys are issued with no expiration date, leading to "zombie keys" that are never rotated.
    *   *Remediation:* Enforce expiration policies. Use automated rotation to ensure keys have a finite lifetime.

5.  **Using Environment Variables for Long-Lived Secrets:**
    While better than hardcoding, environment variables are visible in process listings, core dumps, and container orchestration APIs.
    *   *Remediation:* Use secret injection via sidecars (e.g., Vault Agent, AWS Secrets Manager sidecar) or mounted secret volumes that are not accessible to other processes.

6.  **Lack of Revocation Testing:**
    Teams assume they can revoke keys quickly but have never tested the process. During an incident, revocation may take hours due to manual steps.
    *   *Remediation:* Conduct regular chaos engineering exercises to test key revocation and rotation procedures.

7.  **Sharing Keys Across Environments:**
    Using the same API key for development, staging, and production. A breach in dev leads to a breach in prod.
    *   *Remediation:* Maintain strict isolation. Use separate keys and secret managers per environment.

## Production Bundle

### Action Checklist

- [ ] **Audit Existing Keys:** Inventory all API keys across services, identify owners, and check for over-privilege or sharing.
- [ ] **Implement Pre-Commit Hooks:** Deploy `gitleaks` or equivalent tooling in CI/CD pipelines to prevent secret leakage.
- [ ] **Centralize Storage:** Migrate all keys to a Secret Management Service (Vault, AWS SM, Azure Key Vault). Remove keys from env vars and config files.
- [ ] **Enforce Scoping:** Review and restrict permissions for each key. Ensure least-privilege access is applied.
- [ ] **Automate Rotation:** Configure rotation policies for all keys. Implement dual-key rotation to avoid downtime.
- [ ] **Set Up Alerting:** Create alerts for key usage anomalies, rotation failures, and unauthorized access attempts.
- [ ] **Test Revocation:** Perform a drill to revoke a key and verify service impact and recovery time.
- [ ] **Document Procedures:** Create runbooks for key rotation, revocation, and incident response.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|----------------------|-----|-------------|
| **Server-to-Server Internal** | Workload Identity / mTLS | Eliminates keys entirely; strongest security; automatic lifecycle. | High initial complexity; Low operational cost. |
| **Third-Party Integration** | Scoped Static Key + Rotation | Vendor may not support OIDC; keys are necessary. Scoping limits risk. | Medium (Rotation automation needed). |
| **Public Client App** | No API Keys; Use App Check / OIDC | Keys in client code are extractable. Use dynamic tokens or app attestation. | High dev effort; Low security risk. |
| **CI/CD Pipeline** | Short-Lived Tokens / OIDC | Pipelines should assume roles or use short-lived tokens, not static keys. | Low; Native support in most CI systems. |
| **Legacy System** | Proxy with Key Rotation | Wrap legacy system in a proxy that manages key lifecycle and rotation. | Medium; Adds latency and infrastructure. |

### Configuration Template

**Terraform Example: AWS Secrets Manager with Rotation**

This template provisions a secret with automatic rotation using a Lambda function.

```hcl
resource "aws_secretsmanager_secret" "api_key" {
  name                    = "prod/service/api-key"
  description             = "API key for service authentication"
  recovery_window_in_days = 0 # Force deletion for security

  tags = {
    Environment = "prod"
    ManagedBy   = "terraform"
  }
}

resource "aws_secretsmanager_secret_version" "initial_key" {
  secret_id     = aws_secretsmanager_secret.api_key.id
  secret_string = jsonencode({
    "key" = "initial-placeholder-key" # Should be replaced by rotation
  })
}

resource "aws_lambda_function" "rotation_lambda" {
  filename         = "rotation_lambda.zip"
  function_name    = "api-key-rotation"
  role             = aws_iam_role.rotation_role.arn
  handler          = "rotation.handler"
  runtime          = "python3.9"
  
  # Environment variables for the rotation logic
  environment {
    variables = {
      SECRET_ID = aws_secretsmanager_secret.api_key.id
    }
  }
}

resource "aws_secretsmanager_secret_rotation" "rotation" {
  secret_id           = aws_secretsmanager_secret.api_key.id
  rotation_lambda_arn = aws_lambda_function.rotation_lambda.arn

  rotation_rules {
    automatically_after_days = 30
  }
}

Quick Start Guide

1. Install CLI Tools: Install the AWS CLI or Vault CLI. Configure credentials with appropriate permissions.

   aws configure
   

2. Create a Secret: Generate a secure key and store it in the secret manager.

   # Generate a random key
   KEY=$(openssl rand -base64 32)
   
   # Store in AWS Secrets Manager
   aws secretsmanager create-secret \
     --name prod/my-service/api-key \
     --secret-string "{\"key\":\"$KEY\"}"
   

3. Configure Application: Update your application code to use the SecureApiKeyProvider class or equivalent SDK to fetch the key dynamically. Ensure the application has IAM permissions to read the secret.

4. Verify Access: Run the application and verify it can retrieve the key and authenticate successfully. Check logs to ensure no keys are printed.

   node dist/index.js
   # Verify output: "Authenticated successfully"
   

5. Set Up Rotation: Configure rotation in the secret manager. For AWS, attach a rotation lambda or use the console to set rotation schedule. Verify rotation occurs and the application picks up the new key within the cache TTL.