# Oshun Secrets Management Module

This Terraform module manages secrets in AWS Secrets Manager for all Oshun
services across domains.

## Features

- **Centralized Secrets Management**: All application secrets stored in AWS
  Secrets Manager
- **KMS Encryption**: Dedicated KMS key for secrets encryption with key rotation
- **Automatic Password Generation**: Generate strong passwords for databases and
  services
- **Secret Rotation**: Lambda-based automatic rotation for database credentials
  and tokens
- **Multi-Region Replication**: Replicate secrets across regions for disaster
  recovery
- **ECS Integration**: Pre-formatted outputs for ECS task definition secrets
  blocks
- **Domain Isolation**: Organized secrets by domain (database, redis, jwt,
  encryption, oauth, ai, external)

## Usage

```hcl
module "secrets" {
  source = "../secrets"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  # KMS Configuration
  create_kms_key          = true
  kms_key_deletion_window = 30

  # Multi-region replication
  replica_regions = ["us-west-2"]

  # Database secrets
  database_secrets = {
    main = {
      description       = "Main database credentials"
      database          = "oshun"
      username          = "oshun_app"
      host              = module.rds.endpoint
      port              = 5432
      generate_password = true
      rotation_days     = 30
    }
  }

  # JWT secrets
  jwt_secrets = {
    access = {
      description     = "JWT access token secret"
      generate_secret = true
      length          = 64
      rotation_days   = 90
    }
  }

  # AI provider secrets
  ai_provider_secrets = {
    openai = {
      description = "OpenAI API credentials"
      api_key     = var.openai_api_key
      org_id      = var.openai_org_id
    }
  }

  # Rotation configuration
  enable_database_rotation = true
  rotation_vpc_id          = module.vpc.vpc_id
  rotation_subnet_ids      = module.vpc.private_subnet_ids
  psycopg2_layer_path      = "lambda-layers/psycopg2.zip"

  tags = {
    Environment = "production"
  }
}
```

## Secret Types

### Database Secrets

Stores credentials for PostgreSQL databases with connection string generation.

```hcl
database_secrets = {
  main = {
    description       = "Main database credentials"
    database          = "oshun"
    username          = "oshun_app"
    host              = "db.example.com"
    port              = 5432
    engine            = "postgres"
    generate_password = true
    rotation_days     = 30  # 0 to disable rotation
  }
}
```

Secret structure:

```json
{
  "username": "oshun_app",
  "password": "generated-password",
  "host": "db.example.com",
  "port": 5432,
  "database": "oshun",
  "engine": "postgres",
  "connection_string": "postgresql://oshun_app:password@db.example.com:5432/oshun"
}
```

### Redis Secrets

Stores Redis/ElastiCache authentication tokens.

```hcl
redis_secrets = {
  main = {
    description       = "Main Redis credentials"
    generate_password = true
  }
}
```

### JWT Secrets

Stores JWT signing secrets for token generation.

```hcl
jwt_secrets = {
  access = {
    description     = "JWT access token secret"
    generate_secret = true
    length          = 64
    rotation_days   = 90
  }
}
```

### Encryption Keys

Stores application-level encryption keys.

```hcl
encryption_keys = {
  data = {
    description   = "Data encryption key"
    generate_key  = true
    length        = 32
    rotation_days = 365
  }
}
```

### OAuth Secrets

Stores OAuth provider credentials.

```hcl
oauth_secrets = {
  google = {
    description   = "Google OAuth credentials"
    client_id     = "your-client-id"
    client_secret = "your-client-secret"
  }
}
```

### AI Provider Secrets

Stores AI service API keys.

```hcl
ai_provider_secrets = {
  openai = {
    description = "OpenAI API credentials"
    api_key     = "sk-..."
    org_id      = "org-..."
  }
}
```

### External Service Secrets

Stores credentials for external services.

```hcl
external_service_secrets = {
  stripe = {
    description    = "Stripe credentials"
    api_key        = "pk_..."
    secret_key     = "sk_..."
    webhook_secret = "whsec_..."
  }
}
```

### Storage Secrets

Stores S3-compatible storage credentials.

```hcl
storage_secrets = {
  s3 = {
    description   = "S3 storage credentials"
    access_key    = ""
    secret_key    = ""
    generate_keys = true
  }
}
```

### Custom Secrets

Stores arbitrary secrets with flexible structure.

```hcl
custom_secrets = {
  internal-keys = {
    description   = "Internal service keys"
    secret_string = ""  # Raw string, or use secret_data for JSON
    secret_data = {
      key1 = "value1"
      key2 = "value2"
    }
  }
}
```

## Outputs

### Secret ARNs

```hcl
# Individual secret ARNs
module.secrets.database_secret_arns["main"]
module.secrets.jwt_secret_arns["access"]
module.secrets.ai_provider_secret_arns["openai"]

# Convenience outputs for domain databases
module.secrets.main_database_secret_arn
module.secrets.yemaya_database_secret_arn
module.secrets.lilith_database_secret_arn
```

### ECS Integration

Pre-formatted outputs for ECS task definitions:

```hcl
# Database connection strings
module.secrets.ecs_database_secrets["main"]
# => { name = "MAIN_DATABASE_URL", valueFrom = "arn:...:connection_string::" }

# JWT secrets
module.secrets.ecs_jwt_secrets["access"]
# => { name = "JWT_ACCESS_SECRET", valueFrom = "arn:...:secret::" }
```

### IAM Policy

Ready-to-use IAM policy for secret access:

```hcl
resource "aws_iam_role_policy" "secrets_access" {
  role   = aws_iam_role.task.id
  policy = module.secrets.secrets_read_policy_json
}
```

## Secret Rotation

### Database Rotation

When `rotation_days > 0`, a Lambda function is created to automatically rotate
database passwords:

1. **createSecret**: Generates new password and stores as AWSPENDING version
2. **setSecret**: Connects to database and updates the user's password
3. **testSecret**: Verifies the new password works
4. **finishSecret**: Promotes AWSPENDING to AWSCURRENT

Requirements:

- `rotation_vpc_id`: VPC where Lambda will run
- `rotation_subnet_ids`: Private subnets with database connectivity
- `psycopg2_layer_path`: Path to Lambda layer with psycopg2

### JWT/Encryption Key Rotation

Self-contained rotation that generates new keys without external dependencies:

1. Generates new random secret of the same length
2. Stores as AWSPENDING version
3. Promotes to AWSCURRENT after verification

**Note**: Applications should support both current and pending versions during
rotation window.

## Accessing Secrets in Applications

### ECS Task Definition

```hcl
resource "aws_ecs_task_definition" "app" {
  container_definitions = jsonencode([{
    name = "app"
    secrets = [
      {
        name      = "DATABASE_URL"
        valueFrom = "${module.secrets.database_secret_arns["main"]}:connection_string::"
      },
      {
        name      = "JWT_SECRET"
        valueFrom = "${module.secrets.jwt_secret_arns["access"]}:secret::"
      },
      {
        name      = "OPENAI_API_KEY"
        valueFrom = "${module.secrets.ai_provider_secret_arns["openai"]}:api_key::"
      }
    ]
  }])
}
```

### Application Code (Node.js)

```typescript
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({});

async function getSecret(secretArn: string): Promise<Record<string, unknown>> {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretArn })
  );
  return JSON.parse(response.SecretString!);
}

// Get database credentials
const dbSecret = await getSecret(process.env.DATABASE_SECRET_ARN!);
const connectionString = dbSecret.connection_string;
```

## Security Best Practices

1. **Least Privilege**: Use the generated IAM policy and scope to only needed
   secrets
2. **KMS Key Policies**: Restrict KMS key access to authorized services
3. **VPC Endpoints**: Use Secrets Manager VPC endpoints to avoid public internet
4. **Rotation**: Enable rotation for all credentials, especially databases
5. **Audit Logging**: Enable CloudTrail logging for secret access
6. **Recovery Window**: Use appropriate recovery windows (30 days for
   production)

## Inputs

| Name                     | Description                    | Type         | Default     | Required |
| ------------------------ | ------------------------------ | ------------ | ----------- | :------: |
| environment              | Deployment environment         | string       | -           |   yes    |
| region                   | AWS region                     | string       | "us-east-1" |    no    |
| name_prefix              | Prefix for secret names        | string       | "oshun"     |    no    |
| create_kms_key           | Create dedicated KMS key       | bool         | true        |    no    |
| kms_key_arn              | Existing KMS key ARN           | string       | ""          |    no    |
| replica_regions          | Regions for secret replication | list(string) | []          |    no    |
| database_secrets         | Database credentials map       | map(object)  | {}          |    no    |
| redis_secrets            | Redis credentials map          | map(object)  | {}          |    no    |
| jwt_secrets              | JWT secrets map                | map(object)  | {}          |    no    |
| encryption_keys          | Encryption keys map            | map(object)  | {}          |    no    |
| oauth_secrets            | OAuth provider secrets map     | map(object)  | {}          |    no    |
| ai_provider_secrets      | AI provider API keys map       | map(object)  | {}          |    no    |
| external_service_secrets | External service secrets map   | map(object)  | {}          |    no    |
| storage_secrets          | Storage credentials map        | map(object)  | {}          |    no    |
| custom_secrets           | Custom secrets map             | map(object)  | {}          |    no    |
| recovery_window_in_days  | Days before permanent deletion | number       | 7           |    no    |
| enable_database_rotation | Enable database rotation       | bool         | false       |    no    |
| rotation_vpc_id          | VPC for rotation Lambda        | string       | ""          |    no    |
| rotation_subnet_ids      | Subnets for rotation Lambda    | list(string) | []          |    no    |
| psycopg2_layer_path      | Path to psycopg2 Lambda layer  | string       | ""          |    no    |

## Outputs

| Name                         | Description                         |
| ---------------------------- | ----------------------------------- |
| kms_key_arn                  | ARN of the KMS key                  |
| database_secret_arns         | Map of database secret ARNs         |
| redis_secret_arns            | Map of Redis secret ARNs            |
| jwt_secret_arns              | Map of JWT secret ARNs              |
| encryption_key_arns          | Map of encryption key ARNs          |
| oauth_secret_arns            | Map of OAuth secret ARNs            |
| ai_provider_secret_arns      | Map of AI provider secret ARNs      |
| external_service_secret_arns | Map of external service secret ARNs |
| storage_secret_arns          | Map of storage secret ARNs          |
| custom_secret_arns           | Map of custom secret ARNs           |
| all_secret_arns              | Combined map of all secret ARNs     |
| secrets_read_policy_json     | IAM policy JSON for secret access   |
| ecs_database_secrets         | ECS-formatted database secrets      |
| ecs_jwt_secrets              | ECS-formatted JWT secrets           |
| secrets_summary              | Summary of all created secrets      |
