0Pricing
NestJS Enterprise Backend APIs · درس

تحميل الأسرار من HashiCorp Vault وAWS SSM

اجلب أسرار وقت التشغيل من مخازن خارجية باستخدام async config factories وcustom loaders

تحميل الأسرار من HashiCorp Vault وAWS SSM درس مجاني في NestJS Enterprise Backend APIs على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في NestJS Enterprise Backend APIs، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة NestJS Enterprise Backend APIs 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Why Pull Secrets at Runtime?

Hardcoding API keys and DB passwords in .env files works for a single laptop, but it falls apart at enterprise scale.

  • Rotation: security teams rotate credentials frequently; baking them into images means a redeploy on every rotation.
  • Auditing: central stores like HashiCorp Vault and AWS SSM Parameter Store log who read which secret and when.
  • Least privilege: each service authenticates with its own identity and only sees the secrets it needs.

In this lesson we wire NestJS's ConfigModule to fetch secrets asynchronously at boot from these external stores using custom loaders.

The Async Config Factory Pattern

NestJS's ConfigModule normally loads from static files. To reach a network store we need code that runs before the rest of the app, returning a plain object of resolved values.

That code is a custom loader — an async function passed to ConfigModule.forRoot({ load: [...] }). Nest awaits each loader and merges the results into the config namespace.

Key rule: a loader must fully resolve its promise before the module finishes initializing, so every downstream provider sees fully-populated config.

// config/config.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { vaultLoader } from './loaders/vault.loader';
import { ssmLoader } from './loaders/ssm.loader';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      // each loader is an async () => Record<string, unknown>
      load: [vaultLoader, ssmLoader],
    }),
  ],
})
export class AppConfigModule {}

Anatomy of a Custom Loader

A loader is just an async function returning an object. The keys become config paths you read later with configService.get('database.password').

Best practices:

  • Group secrets under a namespace key (database, jwt) so reads are predictable.
  • Convert and validate types here — external stores return everything as strings.
  • Throw on missing critical secrets so the app fails fast at boot, not mid-request.
// loaders/example.loader.ts
export const exampleLoader = async () => {
  const raw = await fetchFromStore(); // returns string map
  if (!raw.DB_PASSWORD) {
    throw new Error('Missing DB_PASSWORD from secret store');
  }
  return {
    database: {
      host: raw.DB_HOST ?? 'localhost',
      port: Number(raw.DB_PORT ?? 5432),
      password: raw.DB_PASSWORD,
    },
  };
};

async function fetchFromStore() {
  // placeholder for the real Vault/SSM call
  return {} as Record<string, string>;
}

How Vault Stores Secrets

HashiCorp Vault exposes secrets over an HTTP API. The common KV v2 engine stores versioned key-value pairs at a path like secret/data/myapp/database.

To read, a client sends a token in the X-Vault-Token header and receives JSON shaped like { data: { data: { ... } } } — note the double data nesting unique to KV v2.

In production the token usually comes from an AppRole login (a role id + secret id exchanged for a short-lived token), not a static root token.

A Vault Loader with AppRole Login

This loader first exchanges an AppRole roleId/secretId for a client token, then reads a KV v2 path. We use the built-in fetch available in Node 18+.

Notice how we unwrap the double data nesting and namespace the result under vault.

// loaders/vault.loader.ts
export const vaultLoader = async () => {
  const addr = process.env.VAULT_ADDR!;

  // 1) AppRole login -> short-lived client token
  const login = await fetch(`${addr}/v1/auth/approle/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      role_id: process.env.VAULT_ROLE_ID,
      secret_id: process.env.VAULT_SECRET_ID,
    }),
  });
  const { auth } = await login.json();

  // 2) Read KV v2 secret using the issued token
  const res = await fetch(`${addr}/v1/secret/data/myapp/database`, {
    headers: { 'X-Vault-Token': auth.client_token },
  });
  const body = await res.json();
  const kv = body.data.data; // KV v2 double nesting

  return {
    database: {
      host: kv.host,
      port: Number(kv.port),
      password: kv.password,
    },
  };
};

How AWS SSM Parameter Store Works

AWS SSM Parameter Store holds parameters by name, e.g. /myapp/prod/db-password. Secrets use type SecureString, encrypted with a KMS key.

  • GetParametersByPath fetches every parameter under a prefix in one call — ideal for loading a whole namespace.
  • Pass WithDecryption: true to receive plaintext values (your IAM role needs kms:Decrypt).
  • Authentication is automatic via the instance/task IAM role — no token to manage.

An SSM Loader by Path

This loader pulls every parameter under /myapp/prod and strips the prefix to build clean keys. We page through results because GetParametersByPath caps each response and returns a NextToken.

// loaders/ssm.loader.ts
import { SSMClient, GetParametersByPathCommand } from '@aws-sdk/client-ssm';

export const ssmLoader = async () => {
  const client = new SSMClient({ region: process.env.AWS_REGION });
  const prefix = '/myapp/prod/';
  const out: Record<string, string> = {};
  let NextToken: string | undefined;

  do {
    const res = await client.send(
      new GetParametersByPathCommand({
        Path: prefix,
        Recursive: true,
        WithDecryption: true,
        NextToken,
      }),
    );
    for (const p of res.Parameters ?? []) {
      const key = p.Name!.replace(prefix, '');
      out[key] = p.Value!;
    }
    NextToken = res.NextToken;
  } while (NextToken);

  return {
    jwt: { secret: out['jwt-secret'] },
    database: { password: out['db-password'] },
  };
};

Merging Loaders & Precedence

When you list multiple loaders in load: [vaultLoader, ssmLoader], Nest deep-merges their returned objects. Loaders later in the array win on key conflicts.

This lets you layer sources: a base loader for defaults, then an override loader for environment-specific secrets. Plan the order intentionally — accidental overrides are a common bug.

The merge is a simple example of how last-write-wins resolves overlapping keys:

function deepMerge(target: any, source: any): any {
  for (const key of Object.keys(source)) {
    if (
      source[key] && typeof source[key] === 'object' &&
      !Array.isArray(source[key])
    ) {
      target[key] = deepMerge(target[key] ?? {}, source[key]);
    } else {
      target[key] = source[key]; // later source wins
    }
  }
  return target;
}

const base = { db: { host: 'localhost', port: 5432 } };
const override = { db: { host: 'prod-db', password: 's3cr3t' } };
console.log(deepMerge(base, override));
// { db: { host: 'prod-db', port: 5432, password: 's3cr3t' } }

Validating Loaded Secrets

External stores fail in surprising ways — a typo'd path returns nothing, a rotated secret may be empty. Validate the merged config with a schema so the app refuses to start when something critical is missing.

NestJS supports a validate function in forRoot. Here we use a lightweight check, but Joi or class-validator are common in production.

// config/validate.ts
export function validateConfig(config: Record<string, any>) {
  const required = [
    ['database', 'password'],
    ['jwt', 'secret'],
  ];
  for (const [ns, key] of required) {
    if (!config[ns]?.[key]) {
      throw new Error(`Missing required secret: ${ns}.${key}`);
    }
  }
  return config; // must return the validated config
}

Consuming Secrets in Providers

Once loaders have run, any provider injects ConfigService and reads namespaced values. Because loading was async at boot, reads are synchronous and cheap — no network call per request.

For modules that themselves need config (like TypeORM), use the forRootAsync + useFactory pattern so they receive resolved secrets.

// database/database.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get<string>('database.host'),
        port: config.get<number>('database.port'),
        password: config.get<string>('database.password'),
        autoLoadEntities: true,
      }),
    }),
  ],
})
export class DatabaseModule {}

Caching, TTL, and Rotation

Loaders run once at boot, so a value rotated in Vault won't reach a long-running pod until restart. Strategies to handle rotation:

  • Lease-aware refresh: Vault dynamic secrets carry a TTL; a background job renews or re-fetches before expiry.
  • Sidecar injection: tools like Vault Agent or AWS Secrets Manager rotation write fresh values to a file/env the app watches.
  • Rolling restart: simplest for static KV secrets — redeploy on rotation.

Avoid fetching secrets on every request — it adds latency and can hit store rate limits. Cache in memory with an explicit, bounded TTL instead.

Quick Check: Loader Behavior

Test your understanding of async config loaders in NestJS.

Recap & Takeaways

You learned how to load runtime secrets from external stores into NestJS:

  • Custom loaders are async functions passed to ConfigModule.forRoot({ load }); they fully resolve before providers initialize.
  • Vault (KV v2) is read over HTTP with an AppRole-issued token; remember the double data nesting.
  • AWS SSM uses GetParametersByPath with WithDecryption and IAM-role auth; page through NextToken.
  • Loaders are deep-merged with last-write-wins, so order matters.
  • Validate merged config to fail fast, and plan a rotation strategy since loaders run only at boot.

With these patterns your services authenticate with their own identity, never ship plaintext secrets in images, and stay auditable at scale.

الأسئلة الشائعة

هل درس «تحميل الأسرار من HashiCorp Vault وAWS SSM» مجاني؟

نعم — نص درس «تحميل الأسرار من HashiCorp Vault وAWS SSM» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة NestJS Enterprise Backend APIs، انتقل إلى CoddyKit PRO. تتضمن دورة NestJS Enterprise Backend APIs 4 دروس في المجموع.

ماذا ستتعلم في «تحميل الأسرار من HashiCorp Vault وAWS SSM»؟

اجلب أسرار وقت التشغيل من مخازن خارجية باستخدام async config factories وcustom loaders تتمرن على NestJS Enterprise Backend APIs مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ NestJS Enterprise Backend APIs؟

لا تُشترط خبرة سابقة. NestJS Enterprise Backend APIs على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «تحميل الأسرار من HashiCorp Vault وAWS SSM»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس NestJS Enterprise Backend APIs هذا؟

نعم. كل درس في NestJS Enterprise Backend APIs يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. التحقق من Env باستخدام Schema وJoi وforRoot
  2. إعدادات ذات نطاقات أسماء باستخدام registerAs
  3. تحميل الأسرار من HashiCorp Vault وAWS SSM
  4. الإعدادات حسب البيئة والقيم الافتراضية الآمنة
← العودة إلى NestJS Enterprise Backend APIs