@nage-api/core 1.0.0-beta.2

package/dist/security/redaction.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Redaction (PLAN.md §12, §18).
+ *
+ * Structured logs are only safe if the structure cannot smuggle a credential
+ * out. Three places need scrubbing, and all three are here so they cannot drift:
+ * arbitrary field values, request headers, and URLs carrying tokens in the query
+ * string.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTED_QUERY_PARAMS = exports.REDACTED_HEADERS = exports.CIRCULAR = exports.TRUNCATED = exports.REDACTED = void 0;
+exports.redactionSet = redactionSet;
+exports.redact = redact;
+exports.redactHeaders = redactHeaders;
+exports.redactUrl = redactUrl;
+const constants_js_1 = require("../constants.js");
+exports.REDACTED = '[redacted]';
+/**
+ * Substituted where the walk stops.
+ *
+ * The depth bound used to `return value`, which meant a credential nested deeper
+ * than the bound was written out verbatim — the redaction failed *open* at
+ * exactly the point where the structure was most likely to be something the
+ * caller had not thought about. Whatever cannot be scrubbed is not logged.
+ */
+exports.TRUNCATED = '[truncated]';
+/** A structure that refers to itself. Emitted instead of recursing forever. */
+exports.CIRCULAR = '[circular]';
+/** How deep the walk goes before it substitutes `TRUNCATED`. */
+const MAX_DEPTH = 8;
+/** Headers that carry credentials and are never logged verbatim. */
+exports.REDACTED_HEADERS = [
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+    'x-auth-token',
+    'x-csrf-token',
+];
+/** Query parameters that carry credentials, e.g. `?access_token=…`. */
+exports.REDACTED_QUERY_PARAMS = [
+    'token',
+    'access_token',
+    'refresh_token',
+    'api_key',
+    'apikey',
+    'password',
+    'secret',
+    'code',
+    'otp',
+];
+/** Build a lookup set from the defaults plus any configured extras. */
+function redactionSet(extra = []) {
+    return new Set([...constants_js_1.DEFAULT_REDACTED_FIELDS, ...extra].map((field) => field.toLowerCase()));
+}
+/**
+ * Replace the value of any matching key, at any depth.
+ *
+ * Three things this has to survive, because a logger that throws inside a
+ * request handler turns a log line into a 500:
+ *
+ *  - **Depth.** Bounded, and the bound substitutes `TRUNCATED` rather than
+ *    passing the subtree through — see that constant.
+ *  - **Cycles.** A request object, a Sequelize instance and an Axios error all
+ *    refer back to themselves. Tracked per branch, so a value that legitimately
+ *    appears twice side by side is still logged twice.
+ *  - **Values `JSON.stringify` mangles.** A `Date` has no own enumerable
+ *    properties, so walking it produced `{}` and lost the timestamp entirely; a
+ *    `Buffer` expanded into one key per byte, turning a 1MB upload into a log
+ *    line nothing will ever read.
+ */
+function redact(value, fields, depth = 0, seen = new Set()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= MAX_DEPTH)
+        return exports.TRUNCATED;
+    if (seen.has(value))
+        return exports.CIRCULAR;
+    // Left whole: the caller's own serializer knows what to do with these, and
+    // walking them destroys or explodes them.
+    if (value instanceof Date)
+        return value;
+    if (value instanceof Error)
+        return value;
+    if (isBufferLike(value))
+        return `[binary ${String(value.byteLength)} bytes]`;
+    const branch = new Set(seen).add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redact(item, fields, depth + 1, branch));
+    }
+    const result = {};
+    for (const key of Object.keys(value)) {
+        if (fields.has(key.toLowerCase())) {
+            result[key] = exports.REDACTED;
+            continue;
+        }
+        try {
+            result[key] = redact(value[key], fields, depth + 1, branch);
+        }
+        catch (error) {
+            // A getter that throws — an ORM instance with a lazy association, a proxy
+            // whose target is gone. One unreadable field must not lose the whole line.
+            result[key] = `[unreadable: ${error instanceof Error ? error.message : 'unknown'}]`;
+        }
+    }
+    return result;
+}
+function isBufferLike(value) {
+    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+/** Scrub credential-bearing request headers before they reach a log line. */
+function redactHeaders(headers, extra = []) {
+    if (headers === undefined)
+        return {};
+    const sensitive = new Set([...exports.REDACTED_HEADERS, ...extra].map((header) => header.toLowerCase()));
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        result[name] = sensitive.has(name.toLowerCase()) ? exports.REDACTED : value;
+    }
+    return result;
+}
+/**
+ * Scrub credentials out of a URL's query string.
+ *
+ * Request URLs are logged on every error; a token passed as a query parameter
+ * (which the legacy WebSocket handshake did) would otherwise be written to disk
+ * in clear text on every failure.
+ */
+function redactUrl(url) {
+    if (url?.includes('?') !== true)
+        return url;
+    const [path, query] = url.split('?', 2);
+    if (query === undefined)
+        return url;
+    const sensitive = new Set(exports.REDACTED_QUERY_PARAMS);
+    const scrubbed = query
+        .split('&')
+        .map((pair) => {
+        const key = pair.split('=', 1)[0] ?? '';
+        return sensitive.has(key.toLowerCase()) ? `${key}=${exports.REDACTED}` : pair;
+    })
+        .join('&');
+    return `${path ?? ''}?${scrubbed}`;
+}
+//# sourceMappingURL=redaction.js.map

package/dist/security/tls.d.ts

@@ -0,0 +1,29 @@
+/**
+ * TLS policy for outbound connections (PLAN.md §12).
+ *
+ * The legacy framework set `rejectUnauthorized: false` in two places — the SQL
+ * connection and the SMTP client — which silently accepts any certificate and
+ * makes the connection interceptable. Drivers and integrations translate a
+ * declared `TlsMode` through this helper instead of hand-rolling options, so
+ * "verification is off" is a value in the config that `doctor` can see rather
+ * than a literal buried in a driver.
+ */
+import type { NodeEnvironment, TlsMode } from '@nage-api/contracts';
+/** Node TLS options a driver can pass straight to its client. */
+export interface TlsOptions {
+    readonly enabled: boolean;
+    readonly rejectUnauthorized: boolean;
+    /** Verify the certificate's hostname as well as its chain. */
+    readonly checkServerIdentity: boolean;
+}
+export declare const DEFAULT_TLS_MODE: TlsMode;
+/** Translate a declared mode into concrete client options. */
+export declare function resolveTlsOptions(mode?: TlsMode): TlsOptions;
+/**
+ * Refuse an unverified mode where it is indefensible.
+ *
+ * Development gets a warning and carries on — over-strict defaults that break
+ * local work get disabled wholesale, which is worse (§26).
+ */
+export declare function assertTlsAllowed(mode: TlsMode, environment: NodeEnvironment, location?: string): void;
+//# sourceMappingURL=tls.d.ts.map

package/dist/security/tls.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * TLS policy for outbound connections (PLAN.md §12).
+ *
+ * The legacy framework set `rejectUnauthorized: false` in two places — the SQL
+ * connection and the SMTP client — which silently accepts any certificate and
+ * makes the connection interceptable. Drivers and integrations translate a
+ * declared `TlsMode` through this helper instead of hand-rolling options, so
+ * "verification is off" is a value in the config that `doctor` can see rather
+ * than a literal buried in a driver.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TLS_MODE = void 0;
+exports.resolveTlsOptions = resolveTlsOptions;
+exports.assertTlsAllowed = assertTlsAllowed;
+const catalog_js_1 = require("../errors/catalog.js");
+exports.DEFAULT_TLS_MODE = 'verify-full';
+/** Translate a declared mode into concrete client options. */
+function resolveTlsOptions(mode = exports.DEFAULT_TLS_MODE) {
+    switch (mode) {
+        case 'disable':
+            return { enabled: false, rejectUnauthorized: false, checkServerIdentity: false };
+        case 'require':
+            // Encrypted, but the chain is not verified — acceptable only on a network
+            // you already trust, such as a private VPC with a self-signed CA.
+            return { enabled: true, rejectUnauthorized: false, checkServerIdentity: false };
+        case 'no-verify':
+            return { enabled: true, rejectUnauthorized: false, checkServerIdentity: false };
+        case 'verify-full':
+            return { enabled: true, rejectUnauthorized: true, checkServerIdentity: true };
+    }
+}
+/**
+ * Refuse an unverified mode where it is indefensible.
+ *
+ * Development gets a warning and carries on — over-strict defaults that break
+ * local work get disabled wholesale, which is worse (§26).
+ */
+function assertTlsAllowed(mode, environment, location = 'database.ssl') {
+    const unverified = mode === 'no-verify' || mode === 'disable';
+    if (unverified && environment === 'production') {
+        throw new catalog_js_1.ConfigurationError({
+            detail: `${location} is "${mode}" in production; certificate verification must not be disabled`,
+            meta: { location, mode, environment },
+        });
+    }
+}
+//# sourceMappingURL=tls.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DI tokens (PLAN.md §7.3).
+ *
+ * Feature packages must not import each other; they collaborate through the
+ * interfaces in `@nage-api/contracts` and these tokens. A token carries its port
+ * type as a phantom parameter so `inject<T>()` stays type-safe without any cast
+ * at the call site.
+ */
+import type { ContextStore, KeyValueStore, LoggerPort, NageCoreConfig, RateLimitStore, RepositoryPort, UnitOfWork } from '@nage-api/contracts';
+import type { LifecycleState } from './bootstrap/lifecycle.js';
+/** A DI token that remembers what it resolves to. */
+export type Token<TPort> = symbol & {
+    readonly __port?: TPort;
+};
+/**
+ * Create a typed injection token.
+ *
+ * Unmemoised on purpose: every caller is a module-level constant, so identity
+ * comes from the single evaluation of that constant. A *derived* token — one
+ * computed from a name at more than one call site — must go through
+ * `namedToken` instead.
+ */
+export declare function createToken<TPort>(description: string): Token<TPort>;
+/** The validated core configuration the application booted with. */
+export declare const NAGE_CONFIG: Token<NageCoreConfig>;
+/** Structured logger; correlation ids are attached by the implementation. */
+export declare const NAGE_LOGGER: Token<LoggerPort>;
+/** Ambient per-request context (requestId / user / tenant). */
+export declare const NAGE_REQUEST_CONTEXT: Token<ContextStore>;
+/**
+ * Counter store behind the global throttle. Defaults to the in-process store,
+ * which counts per process; a multi-instance deployment supplies a shared one
+ * through `NageCoreModule.forRoot(config, { rateLimitStore })` (§12).
+ *
+ * Exported so an application can inject the store it supplied. Providing this
+ * token from the application module does **not** override the default — the
+ * binding lives inside `NageCoreModule` and that is where the guard resolves it.
+ */
+export declare const NAGE_RATE_LIMIT_STORE: Token<RateLimitStore>;
+/**
+ * Whether this process is starting, live, or draining after a shutdown signal.
+ *
+ * Published so `/health/ready` can fail the instant a signal arrives (§21): a
+ * draining process that still reports ready keeps being sent traffic it is about
+ * to disconnect.
+ */
+export declare const NAGE_LIFECYCLE: Token<LifecycleState>;
+/** Transaction boundary provided by the selected data driver (Phase 5). */
+export declare const NAGE_UNIT_OF_WORK: Token<UnitOfWork>;
+/**
+ * Repository token for one model. Drivers register against it, application
+ * services inject it — neither side imports the other.
+ *
+ * Same model name, same token, however many times it is asked for: that identity
+ * *is* the decoupling. See `namedToken`.
+ */
+export declare function repositoryToken<TEntity>(model: string): Token<RepositoryPort<TEntity>>;
+/** Named key/value store — sessions, throttling counters, caches (Phase 7-8). */
+export declare function keyValueStoreToken<TValue>(name: string): Token<KeyValueStore<TValue>>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * DI tokens (PLAN.md §7.3).
+ *
+ * Feature packages must not import each other; they collaborate through the
+ * interfaces in `@nage-api/contracts` and these tokens. A token carries its port
+ * type as a phantom parameter so `inject<T>()` stays type-safe without any cast
+ * at the call site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_UNIT_OF_WORK = exports.NAGE_LIFECYCLE = exports.NAGE_RATE_LIMIT_STORE = exports.NAGE_REQUEST_CONTEXT = exports.NAGE_LOGGER = exports.NAGE_CONFIG = void 0;
+exports.createToken = createToken;
+exports.repositoryToken = repositoryToken;
+exports.keyValueStoreToken = keyValueStoreToken;
+/**
+ * Create a typed injection token.
+ *
+ * Unmemoised on purpose: every caller is a module-level constant, so identity
+ * comes from the single evaluation of that constant. A *derived* token — one
+ * computed from a name at more than one call site — must go through
+ * `namedToken` instead.
+ */
+function createToken(description) {
+    return Symbol(description);
+}
+/**
+ * Tokens derived from a name, memoised by that name.
+ *
+ * `Symbol()` returns a fresh symbol every call, so a factory that wrapped it
+ * directly produced a *different* token each time it was asked for the same
+ * model — which quietly breaks the one property these tokens exist for. A driver
+ * registering `repositoryToken('Invoice')` and a service injecting
+ * `repositoryToken('Invoice')` would be talking about two different symbols, and
+ * Nest would report the provider as missing however correctly both sides were
+ * written.
+ *
+ * Scoped to this module rather than `Symbol.for`, which would put the keys in a
+ * process-global registry shared with every other library.
+ */
+const namedTokens = new Map();
+function namedToken(description) {
+    const existing = namedTokens.get(description);
+    if (existing !== undefined)
+        return existing;
+    const token = createToken(description);
+    namedTokens.set(description, token);
+    return token;
+}
+/** The validated core configuration the application booted with. */
+exports.NAGE_CONFIG = createToken('NAGE_CONFIG');
+/** Structured logger; correlation ids are attached by the implementation. */
+exports.NAGE_LOGGER = createToken('NAGE_LOGGER');
+/** Ambient per-request context (requestId / user / tenant). */
+exports.NAGE_REQUEST_CONTEXT = createToken('NAGE_REQUEST_CONTEXT');
+/**
+ * Counter store behind the global throttle. Defaults to the in-process store,
+ * which counts per process; a multi-instance deployment supplies a shared one
+ * through `NageCoreModule.forRoot(config, { rateLimitStore })` (§12).
+ *
+ * Exported so an application can inject the store it supplied. Providing this
+ * token from the application module does **not** override the default — the
+ * binding lives inside `NageCoreModule` and that is where the guard resolves it.
+ */
+exports.NAGE_RATE_LIMIT_STORE = createToken('NAGE_RATE_LIMIT_STORE');
+/**
+ * Whether this process is starting, live, or draining after a shutdown signal.
+ *
+ * Published so `/health/ready` can fail the instant a signal arrives (§21): a
+ * draining process that still reports ready keeps being sent traffic it is about
+ * to disconnect.
+ */
+exports.NAGE_LIFECYCLE = createToken('NAGE_LIFECYCLE');
+/** Transaction boundary provided by the selected data driver (Phase 5). */
+exports.NAGE_UNIT_OF_WORK = createToken('NAGE_UNIT_OF_WORK');
+/**
+ * Repository token for one model. Drivers register against it, application
+ * services inject it — neither side imports the other.
+ *
+ * Same model name, same token, however many times it is asked for: that identity
+ * *is* the decoupling. See `namedToken`.
+ */
+function repositoryToken(model) {
+    return namedToken(`NAGE_REPOSITORY:${model}`);
+}
+/** Named key/value store — sessions, throttling counters, caches (Phase 7-8). */
+function keyValueStoreToken(name) {
+    return namedToken(`NAGE_KV_STORE:${name}`);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/** Package version marker, useful in `nage doctor` / `nage info` output. */
+export declare const NAGE_CORE_VERSION = "0.0.0";
+/** Minimum Node.js runtime supported by the framework (PLAN.md §21). */
+export declare const NAGE_MIN_NODE_VERSION = "22.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_MIN_NODE_VERSION = exports.NAGE_CORE_VERSION = void 0;
+/** Package version marker, useful in `nage doctor` / `nage info` output. */
+exports.NAGE_CORE_VERSION = '0.0.0';
+/** Minimum Node.js runtime supported by the framework (PLAN.md §21). */
+exports.NAGE_MIN_NODE_VERSION = '22.0.0';
+//# sourceMappingURL=version.js.map

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@nage-api/core",
+  "version": "1.0.0-beta.2",
+  "description": "Cross-cutting primitives for @nage-api applications — context, response envelope, error catalog, bootstrap",
+  "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": {
+    "compression": "1.8.1",
+    "helmet": "8.3.0",
+    "@nage-api/contracts": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0"
+  },
+  "peerDependenciesMeta": {
+    "class-transformer": {
+      "optional": true
+    },
+    "class-validator": {
+      "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/compression": "1.8.1",
+    "@types/node": "22.20.1",
+    "@types/supertest": "7.2.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "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",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "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"
+  }
+}