[INFRA] Type-Safe Config Module with Zod Validation

[oomokaro1]

[INFRA] Type-Safe Config Module with Zod Validation

Priority: Medium

Difficulty: Medium
Estimated Effort: 1-2 days
Relevant Packages: OrbitStream_backend/
Labels: infrastructure, enhancement, priority:medium

Requirements

1. Zod Validation Schema

Create a comprehensive config schema using zod:

// src/config/config.schema.ts
import { z } from 'zod';

export const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3001),

  DATABASE_URL: z.string().url({ message: 'DATABASE_URL must be a valid PostgreSQL URL' }),
  REDIS_URL: z.string().url({ message: 'REDIS_URL must be a valid Redis URL' }),

  JWT_SECRET: z.string().min(32, { message: 'JWT_SECRET must be at least 32 characters' }),
  JWT_EXPIRES_IN: z.string().default('7d'),

  STELLAR_NETWORK: z.enum(['testnet', 'mainnet']),
  STELLAR_HORIZON_URL: z.string().url(),
  STELLAR_NETWORK_PASSPHRASE: z.string().min(1),

  PLATFORM_RECEIVING_ACCOUNT: z.string().startsWith('G', { message: 'Must be a valid Stellar public key' }),

  FRONTEND_URL: z.string().url().default('http://localhost:3000'),
  CHECKOUT_SESSION_TTL_MINUTES: z.coerce.number().int().positive().default(30),
  CHALLENGE_TTL_SECONDS: z.coerce.number().int().positive().default(300),

  CORS_ALLOWED_ORIGINS: z.string().transform(s => s.split(',').map(o => o.trim())),
  REDIS_CURSOR_TTL_HOURS: z.coerce.number().int().positive().default(24),
});

export type Config = z.infer<typeof configSchema>;

2. Config Module

• Create src/config/config.module.ts using @nestjs/config
• Load and validate config on app bootstrap
• If validation fails, crash with a clear error message showing which vars are invalid
• Export a typed ConfigService that provides config.DATABASE_URL, config.JWT_SECRET, etc.

3. Environment-Specific Behavior

• NODE_ENV=production: crash if any var uses a default value (all must be explicitly set)
• NODE_ENV=development: allow defaults, log warnings for missing vars
• Support .env.local overrides (loaded after .env)

4. Secrets Manager Support (Optional)

• Support reading secrets from AWS SSM Parameter Store or HashiCorp Vault
• If SECRETS_MANAGER env var is set, read JWT_SECRET and DATABASE_URL from the secrets manager instead of env vars
• Keep env var as fallback for local development

5. Config Check Script

• Add npm run config:check script that validates config without starting the app
• Useful for CI/CD pipelines and Docker health checks

6. Update All Config Reads

• Replace all process.env.X reads with config.X from the ConfigService
• Update all services to inject ConfigService instead of reading env directly

7. Update .env.example

• Add ALL required env vars with comments
• Mark which are required vs optional
• Add examples for each

8. Testing

• Unit test: valid config passes validation
• Unit test: missing required var fails with clear error
• Unit test: invalid value (short JWT_SECRET) fails with clear error
• Unit test: defaults applied correctly in development mode
• Unit test: production mode rejects defaults

[Uchechukwu-Ekezie]

hi maintainer please can i hop on this

[grantfox-oss]

🦊 GrantFox — @Uchechukwu-Ekezie has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #11)
2. Your PR will be reviewed by the OrbitStream maintainers

Good luck! Track your progress on GrantFox.

[Uchechukwu-Ekezie]

All requirements from this issue have been implemented in PR #31: #31

Here is what was done:

Zod schema (src/config/config.schema.ts)

• Full schema covering every env var with coercion (z.coerce), URL validation, string minimums, enum checks, and defaults
• CORS_ALLOWED_ORIGINS transforms a comma-separated string into string[]
• validate() function: in production all defaultable keys must be explicitly set (no silent fallbacks); in development missing defaults emit a console.warn

Config module (src/config/config.module.ts)

• Wraps @nestjs/config's ConfigModule.forRoot with isGlobal: true, cache: true, and the Zod validate hook
• AppModule imports it first so validation runs at bootstrap

All process.env.* reads migrated

• CheckoutService, StellarService, RedisService, AuthService, PaymentDetectorService, WebhookQueueService, DynamicCorsMiddleware — all now inject ConfigService<Config> with { infer: true } for full type safety

config:check script

• scripts/config-check.ts — calls validate(process.env) and exits 0/1
• "config:check": "ts-node scripts/config-check.ts" added to package.json

.env.example

• Fully rewritten; every variable marked REQUIRED or OPTIONAL with a description

Tests (src/config/config.schema.spec.ts — 14 tests)

• Valid config passes, defaults applied, PORT coercion, CORS transform, mainnet accepted
• Missing DATABASE_URL, short JWT_SECRET, invalid URL, non-G receiving account, unknown STELLAR_NETWORK
• validate() throws descriptive message on invalid input
• Production rejects defaults; production passes when all keys explicitly set

All 283 tests pass, no lint errors, prettier clean.