@nage-api/config 1.0.0-beta.2

package/dist/secrets/aws.secret-provider.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * AWS Secrets Manager provider (PLAN.md §11.1 layer 5).
+ *
+ * The SDK is an **optional peer** loaded lazily: an application using env-based
+ * secrets should not carry an AWS client in its image. The client is also
+ * injectable, which is what makes this testable without the SDK installed and
+ * without a network — the legacy AWS-only singleton was neither.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwsSecretProvider = void 0;
+const core_1 = require("@nage-api/core");
+class AwsSecretProvider {
+    provider = 'aws-secrets-manager';
+    #options;
+    #client;
+    #commandFactory;
+    constructor(options = {}) {
+        this.#options = options;
+        this.#client = options.client;
+        this.#commandFactory = options.commandFactory;
+    }
+    async get(name) {
+        const client = await this.#resolveClient();
+        const commandFactory = this.#commandFactory;
+        if (commandFactory === undefined) {
+            throw new core_1.ConfigurationError({ detail: 'AWS secret provider is not initialised' });
+        }
+        const secretId = `${this.#options.prefix ?? ''}${name}`;
+        try {
+            const response = await client.send(commandFactory({ SecretId: secretId }));
+            return response.SecretString ?? null;
+        }
+        catch (error) {
+            if (isResourceNotFound(error))
+                return null;
+            // The upstream body may quote the secret's own metadata, so it is logged
+            // rather than returned (§17).
+            throw new core_1.ExternalServiceError('aws-secrets-manager', {
+                detail: `Could not read secret "${name}"`,
+                cause: error,
+                meta: { secretId },
+            });
+        }
+    }
+    async require(name) {
+        const value = await this.get(name);
+        if (value === null) {
+            throw new core_1.ConfigurationError({
+                detail: `Required secret "${name}" is not available`,
+                meta: { provider: this.provider, secretId: `${this.#options.prefix ?? ''}${name}` },
+            });
+        }
+        return value;
+    }
+    async #resolveClient() {
+        if (this.#client !== undefined)
+            return this.#client;
+        const importSdk = this.#options.importSdk ?? defaultSdkImport;
+        let sdk;
+        try {
+            sdk = await importSdk();
+        }
+        catch (error) {
+            throw new core_1.ConfigurationError({
+                message: 'secrets.provider is "aws" but @aws-sdk/client-secrets-manager is not installed. ' +
+                    'Install it, or switch secrets.provider to "env".',
+                cause: error,
+            });
+        }
+        this.#client = new sdk.SecretsManagerClient(this.#options.region === undefined ? {} : { region: this.#options.region });
+        this.#commandFactory ??= (input) => new sdk.GetSecretValueCommand(input);
+        return this.#client;
+    }
+}
+exports.AwsSecretProvider = AwsSecretProvider;
+/**
+ * The specifier is held in a variable on purpose: the SDK is an optional peer,
+ * so a literal `import('@aws-sdk/...')` would make the package fail to compile
+ * wherever it is not installed — which is most installs.
+ */
+const AWS_SDK_MODULE = '@aws-sdk/client-secrets-manager';
+async function defaultSdkImport() {
+    const imported = await import(AWS_SDK_MODULE);
+    return imported;
+}
+function isResourceNotFound(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'ResourceNotFoundException');
+}
+//# sourceMappingURL=aws.secret-provider.js.map

package/dist/secrets/caching.secret-provider.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TTL cache in front of any `SecretProviderPort`.
+ *
+ * A remote secret store is a network call and a rate limit; resolving the same
+ * signing key on every request would be both slow and a dependency of every
+ * request on that store's availability. Wrapping is a decorator rather than a
+ * feature of each provider so caching behaves identically for all of them.
+ */
+import type { SecretProviderPort } from '@nage-api/contracts';
+export interface CachingSecretProviderOptions {
+    readonly ttlSeconds?: number;
+    /** Injectable clock, so the TTL is testable without waiting. */
+    readonly now?: () => number;
+}
+export declare class CachingSecretProvider implements SecretProviderPort {
+    #private;
+    constructor(inner: SecretProviderPort, options?: CachingSecretProviderOptions);
+    get provider(): string;
+    get(name: string): Promise<string | null>;
+    require(name: string): Promise<string>;
+    /** Drop cached values — used after a rotation event. */
+    invalidate(name?: string): void;
+}
+//# sourceMappingURL=caching.secret-provider.d.ts.map

package/dist/secrets/caching.secret-provider.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * TTL cache in front of any `SecretProviderPort`.
+ *
+ * A remote secret store is a network call and a rate limit; resolving the same
+ * signing key on every request would be both slow and a dependency of every
+ * request on that store's availability. Wrapping is a decorator rather than a
+ * feature of each provider so caching behaves identically for all of them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachingSecretProvider = void 0;
+class CachingSecretProvider {
+    #inner;
+    #ttlMs;
+    #now;
+    #cache = new Map();
+    constructor(inner, options = {}) {
+        this.#inner = inner;
+        this.#ttlMs = (options.ttlSeconds ?? 300) * 1000;
+        this.#now = options.now ?? Date.now;
+    }
+    get provider() {
+        return `${this.#inner.provider}+cache`;
+    }
+    async get(name) {
+        const cached = this.#cache.get(name);
+        if (cached !== undefined && cached.expiresAt > this.#now())
+            return cached.value;
+        const value = await this.#inner.get(name);
+        if (this.#ttlMs > 0) {
+            this.#cache.set(name, { value, expiresAt: this.#now() + this.#ttlMs });
+        }
+        return value;
+    }
+    async require(name) {
+        const cached = this.#cache.get(name);
+        if (cached !== undefined && cached.expiresAt > this.#now() && cached.value !== null) {
+            return cached.value;
+        }
+        const value = await this.#inner.require(name);
+        if (this.#ttlMs > 0) {
+            this.#cache.set(name, { value, expiresAt: this.#now() + this.#ttlMs });
+        }
+        return value;
+    }
+    /** Drop cached values — used after a rotation event. */
+    invalidate(name) {
+        if (name === undefined)
+            this.#cache.clear();
+        else
+            this.#cache.delete(name);
+    }
+}
+exports.CachingSecretProvider = CachingSecretProvider;
+//# sourceMappingURL=caching.secret-provider.js.map

package/dist/secrets/env.secret-provider.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Secrets from the environment (PLAN.md §11.1 layer 5).
+ *
+ * The default provider, and the right one for container platforms that inject
+ * secrets as env vars. Swapping to AWS or Vault is a config change because
+ * consumers depend on `SecretProviderPort`, not on this class.
+ */
+import type { SecretProviderPort } from '@nage-api/contracts';
+export interface EnvSecretProviderOptions {
+    /** Prefix applied to every lookup, e.g. `APP_`. */
+    readonly prefix?: string;
+    readonly source?: Record<string, string | undefined>;
+}
+export declare class EnvSecretProvider implements SecretProviderPort {
+    #private;
+    readonly provider = "env";
+    constructor(options?: EnvSecretProviderOptions);
+    get(name: string): Promise<string | null>;
+    require(name: string): Promise<string>;
+}
+//# sourceMappingURL=env.secret-provider.d.ts.map

package/dist/secrets/env.secret-provider.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Secrets from the environment (PLAN.md §11.1 layer 5).
+ *
+ * The default provider, and the right one for container platforms that inject
+ * secrets as env vars. Swapping to AWS or Vault is a config change because
+ * consumers depend on `SecretProviderPort`, not on this class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvSecretProvider = void 0;
+const core_1 = require("@nage-api/core");
+class EnvSecretProvider {
+    provider = 'env';
+    #prefix;
+    #source;
+    constructor(options = {}) {
+        this.#prefix = options.prefix ?? '';
+        this.#source = options.source ?? process.env;
+    }
+    get(name) {
+        const value = this.#source[`${this.#prefix}${name}`];
+        // An empty string is treated as unset: a blank secret is a misconfiguration,
+        // not a valid credential.
+        return Promise.resolve(value === undefined || value === '' ? null : value);
+    }
+    async require(name) {
+        const value = await this.get(name);
+        if (value === null) {
+            throw new core_1.ConfigurationError({
+                detail: `Required secret "${name}" is not set`,
+                meta: { provider: this.provider, variable: `${this.#prefix}${name}` },
+            });
+        }
+        return value;
+    }
+}
+exports.EnvSecretProvider = EnvSecretProvider;
+//# sourceMappingURL=env.secret-provider.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DI tokens owned by `@nage-api/config`.
+ *
+ * `NAGE_CONFIG` itself is declared by `@nage-api/core`, since core's bootstrap reads
+ * the config without knowing this package exists — the direction that lets an
+ * app boot with a hand-written literal and adopt `@nage-api/config` later.
+ */
+import { type Token } from '@nage-api/core';
+import type { SecretProviderPort } from '@nage-api/contracts';
+import type { EnvRecord } from './config.service.js';
+/** The validated environment object produced by the app's zod schema. */
+export declare const NAGE_ENV: Token<EnvRecord>;
+/** The configured secret source (§11.1 layer 5). */
+export declare const NAGE_SECRET_PROVIDER: Token<SecretProviderPort>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * DI tokens owned by `@nage-api/config`.
+ *
+ * `NAGE_CONFIG` itself is declared by `@nage-api/core`, since core's bootstrap reads
+ * the config without knowing this package exists — the direction that lets an
+ * app boot with a hand-written literal and adopt `@nage-api/config` later.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_SECRET_PROVIDER = exports.NAGE_ENV = void 0;
+const core_1 = require("@nage-api/core");
+/** The validated environment object produced by the app's zod schema. */
+exports.NAGE_ENV = (0, core_1.createToken)('NAGE_ENV');
+/** The configured secret source (§11.1 layer 5). */
+exports.NAGE_SECRET_PROVIDER = (0, core_1.createToken)('NAGE_SECRET_PROVIDER');
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nage-api/config",
+  "version": "1.0.0-beta.2",
+  "description": "One typed configuration for a @nage-api application — defineConfig, zod env validation, secret providers",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-secrets-manager": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/platform-express": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@types/supertest": "7.2.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "supertest": "7.2.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}