@nage-api/core 1.0.0-beta.2

package/dist/bootstrap/shutdown.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Graceful shutdown, in the order the stages actually have to happen
+ * (PLAN.md §21).
+ *
+ * `app.enableShutdownHooks()` is not this. Nest 11's signal handler runs
+ * `onModuleDestroy` → `beforeApplicationShutdown` → close the HTTP server →
+ * `onApplicationShutdown`, so **modules destroy their pools while requests are
+ * still running**. Measured against a 600ms handler signalled at 200ms: the
+ * handler's query came back `pool is closed` and the client got that as a 200.
+ * A second measurement: one handler that never returns kept the process alive
+ * past 8 seconds, because nothing in that sequence has a deadline — the
+ * container survives until the orchestrator's `SIGKILL`.
+ *
+ * This runs the stages in the order that makes each one meaningful:
+ *
+ *  1. **Fail readiness.** The load balancer needs to stop choosing this
+ *     instance, and endpoint propagation is not instant (`readinessDelayMs`).
+ *  2. **Stop accepting connections**, and release keep-alive sockets that have
+ *     no request on them. Requests already in flight keep their sockets.
+ *  3. **Wait for those requests**, bounded by `drainTimeoutMs`. Past the
+ *     deadline the remaining sockets are cut, because a client that has hung is
+ *     not a reason to abandon the pools.
+ *  4. **`app.close()`** — only now do modules close pools, queues and Redis.
+ *  5. **Exit.** Zero if the sequence finished, non-zero if `forceExitAfterMs`
+ *     expired, so a deploy can tell a clean drain from a broken one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installShutdown = installShutdown;
+exports.registerShutdownHandle = registerShutdownHandle;
+exports.shutdownHandleFor = shutdownHandleFor;
+const json_logger_js_1 = require("../logging/json.logger.js");
+const lifecycle_js_1 = require("./lifecycle.js");
+const drain_js_1 = require("./drain.js");
+const DEFAULT_SIGNALS = ['SIGTERM', 'SIGINT'];
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+const DEFAULT_FORCE_EXIT_MS = 30_000;
+function installShutdown(app, options = {}) {
+    const config = options.config;
+    const logger = options.logger ?? new json_logger_js_1.JsonLogger(undefined, config);
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const signals = options.signals ?? DEFAULT_SIGNALS;
+    const lifecycle = options.lifecycle ?? (0, lifecycle_js_1.processLifecycle)();
+    const drain = options.drain ?? (0, drain_js_1.requestDrainFor)(app) ?? new drain_js_1.RequestDrain();
+    const readinessDelayMs = config?.shutdown?.readinessDelayMs ?? 0;
+    const drainTimeoutMs = config?.shutdown?.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    const forceExitAfterMs = config?.shutdown?.forceExitAfterMs ?? DEFAULT_FORCE_EXIT_MS;
+    let running;
+    const run = async (reason) => {
+        running ??= sequence(reason);
+        return running;
+    };
+    const sequence = async (reason) => {
+        lifecycle.markDraining();
+        logger.info('Shutdown started', { reason, inFlight: drain.active, drainTimeoutMs });
+        // Deliberately not `unref`ed. An `await` does not hold the event loop open,
+        // so a hook that never settles would otherwise let the process exit 0 with
+        // its pools unclosed — a silent failure dressed as a clean shutdown.
+        // A holder rather than a `let`: the flag is set inside a timer callback, and
+        // the type system narrows a local boolean to `false` at every later read
+        // because it cannot order the closure.
+        const state = { expired: false };
+        const deadline = setTimeout(() => {
+            state.expired = true;
+            logger.fatal('Shutdown deadline expired; exiting without finishing', {
+                reason,
+                forceExitAfterMs,
+                inFlight: drain.active,
+            });
+            exit(1);
+        }, forceExitAfterMs);
+        try {
+            // 1. Readiness fails from `markDraining()` above; this is the window the
+            //    load balancer needs to act on it.
+            if (readinessDelayMs > 0)
+                await delay(readinessDelayMs);
+            // 2. No new connections. Keep-alive sockets with nothing on them are
+            //    released here, so they do not hold the server open for their idle
+            //    timeout.
+            const server = httpServerOf(app);
+            if (server?.listening === true) {
+                server.close();
+                server.closeIdleConnections?.();
+            }
+            // 3. The requests we already accepted.
+            const drained = await drain.whenIdle(drainTimeoutMs);
+            if (drained) {
+                // Again, and deliberately: a socket that was mid-request in step 2 is
+                // idle now. `app.close()` waits on `httpServer.close()`, which waits on
+                // every open socket, so a keep-alive connection whose request has
+                // finished would otherwise hold the shutdown for its idle timeout.
+                server?.closeIdleConnections?.();
+            }
+            else {
+                logger.warn('Drain deadline expired; cutting remaining connections', {
+                    inFlight: drain.active,
+                    drainTimeoutMs,
+                });
+                server?.closeAllConnections?.();
+            }
+            // 4. Now the pools. Nothing is using them.
+            await app.close();
+            clearTimeout(deadline);
+            // The deadline already called `exit(1)`; in a process where `exit` is
+            // injected (a test) the sequence keeps running, and it must not then report
+            // success.
+            if (state.expired)
+                return 1;
+            logger.info('Shutdown complete', { reason });
+            exit(0);
+            return 0;
+        }
+        catch (error) {
+            clearTimeout(deadline);
+            logger.fatal('Shutdown failed', {
+                reason,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            exit(1);
+            return 1;
+        }
+    };
+    const onSignal = (signal) => {
+        if (running !== undefined) {
+            // An operator pressing ctrl-C twice, or a supervisor escalating, is asking
+            // for the drain to stop being polite.
+            logger.warn('Second shutdown signal; exiting immediately', {
+                signal,
+                inFlight: drain.active,
+            });
+            exit(1);
+            return;
+        }
+        void run(signal);
+    };
+    const listeners = new Map();
+    for (const signal of signals) {
+        const listener = () => {
+            onSignal(signal);
+        };
+        listeners.set(signal, listener);
+        process.on(signal, listener);
+    }
+    return {
+        get draining() {
+            return lifecycle.draining;
+        },
+        run,
+        dispose() {
+            for (const [signal, listener] of listeners)
+                process.removeListener(signal, listener);
+            listeners.clear();
+        },
+    };
+}
+/**
+ * The handle `bootstrap` installed for an application.
+ *
+ * Exported for two callers with the same need: a test that boots an application
+ * and must take its signal listeners off the process again, and an application
+ * embedded in something else that owns its own signal handling.
+ */
+const handles = new WeakMap();
+function registerShutdownHandle(app, handle) {
+    handles.set(app, handle);
+}
+function shutdownHandleFor(app) {
+    return handles.get(app);
+}
+function httpServerOf(app) {
+    const server = app.getHttpServer?.();
+    if (server === null || typeof server !== 'object')
+        return undefined;
+    return typeof server.close === 'function' ? server : undefined;
+}
+async function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/constants.d.ts

@@ -0,0 +1,32 @@
+/** Header and metadata names shared across the framework (PLAN.md §16.2). */
+/** Correlation id accepted from the caller and echoed on every response. */
+export declare const REQUEST_ID_HEADER = "x-request-id";
+/** Upstream trace id, when the caller is another service. */
+export declare const CORRELATION_ID_HEADER = "x-correlation-id";
+/** Retained from the legacy framework so existing clients keep working. */
+export declare const API_VERSION_HEADER = "x-application-version";
+export declare const DEFAULT_API_VERSION = 1;
+/**
+ * Accepted shape of a caller-supplied request id. Anything else is replaced with
+ * a generated one — an id echoed into responses and log lines is untrusted input
+ * (log forging, header injection), so it is validated rather than trusted.
+ */
+export declare const REQUEST_ID_PATTERN: RegExp;
+/** Reflector metadata keys. */
+export declare const METADATA_KEYS: {
+    readonly isPublic: "nage:is-public";
+    readonly noEnvelope: "nage:no-envelope";
+    readonly versionRule: "nage:version-rule";
+    readonly rateLimit: "nage:rate-limit";
+    readonly skipRateLimit: "nage:skip-rate-limit";
+    readonly requestTimeout: "nage:request-timeout";
+};
+/**
+ * Ceiling on handler duration (§21). An unbounded handler holds its connection
+ * until the client gives up, and a client that has given up is a connection the
+ * server is still paying for.
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Field names redacted from every log line by default — extend, never shrink (§18). */
+export declare const DEFAULT_REDACTED_FIELDS: readonly string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -0,0 +1,48 @@
+"use strict";
+/** Header and metadata names shared across the framework (PLAN.md §16.2). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REDACTED_FIELDS = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.METADATA_KEYS = exports.REQUEST_ID_PATTERN = exports.DEFAULT_API_VERSION = exports.API_VERSION_HEADER = exports.CORRELATION_ID_HEADER = exports.REQUEST_ID_HEADER = void 0;
+/** Correlation id accepted from the caller and echoed on every response. */
+exports.REQUEST_ID_HEADER = 'x-request-id';
+/** Upstream trace id, when the caller is another service. */
+exports.CORRELATION_ID_HEADER = 'x-correlation-id';
+/** Retained from the legacy framework so existing clients keep working. */
+exports.API_VERSION_HEADER = 'x-application-version';
+exports.DEFAULT_API_VERSION = 1;
+/**
+ * Accepted shape of a caller-supplied request id. Anything else is replaced with
+ * a generated one — an id echoed into responses and log lines is untrusted input
+ * (log forging, header injection), so it is validated rather than trusted.
+ */
+exports.REQUEST_ID_PATTERN = /^[A-Za-z0-9._~-]{8,128}$/;
+/** Reflector metadata keys. */
+exports.METADATA_KEYS = {
+    isPublic: 'nage:is-public',
+    noEnvelope: 'nage:no-envelope',
+    versionRule: 'nage:version-rule',
+    rateLimit: 'nage:rate-limit',
+    skipRateLimit: 'nage:skip-rate-limit',
+    requestTimeout: 'nage:request-timeout',
+};
+/**
+ * Ceiling on handler duration (§21). An unbounded handler holds its connection
+ * until the client gives up, and a client that has given up is a connection the
+ * server is still paying for.
+ */
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Field names redacted from every log line by default — extend, never shrink (§18). */
+exports.DEFAULT_REDACTED_FIELDS = [
+    'password',
+    'passwordConfirmation',
+    'token',
+    'accessToken',
+    'refreshToken',
+    'refresh_token',
+    'authorization',
+    'cookie',
+    'secret',
+    'apiKey',
+    'api_key',
+    'otp',
+];
+//# sourceMappingURL=constants.js.map

package/dist/context/active-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The process-wide `AsyncLocalStorage` backing the request context.
+ *
+ * It lives at module scope, not inside the injectable, for one reason: param
+ * decorators (`@Owner()`), static helpers and non-DI code (a repository base
+ * class, a queue publisher) need the same context that services see, and a
+ * decorator factory has nothing to inject into.
+ *
+ * `RequestContextService` is the DI-facing wrapper over these functions — both
+ * read and write the same store.
+ */
+import type { RequestContext } from '@nage-api/contracts';
+/** Internal, mutable view. Callers outside this module only see the readonly type. */
+export type MutableRequestContext = {
+    -readonly [K in keyof RequestContext]: RequestContext[K];
+};
+/** The active context, or `undefined` outside a request. */
+export declare function getActiveContext(): RequestContext | undefined;
+/** Run `fn` with `context` active for its whole async subtree. */
+export declare function runWithContext<TResult>(context: RequestContext, fn: () => TResult): TResult;
+/** Update one field of the active context; a no-op when none is active. */
+export declare function setContextValue<TKey extends keyof RequestContext>(key: TKey, value: RequestContext[TKey]): void;
+//# sourceMappingURL=active-context.d.ts.map

package/dist/context/active-context.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * The process-wide `AsyncLocalStorage` backing the request context.
+ *
+ * It lives at module scope, not inside the injectable, for one reason: param
+ * decorators (`@Owner()`), static helpers and non-DI code (a repository base
+ * class, a queue publisher) need the same context that services see, and a
+ * decorator factory has nothing to inject into.
+ *
+ * `RequestContextService` is the DI-facing wrapper over these functions — both
+ * read and write the same store.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActiveContext = getActiveContext;
+exports.runWithContext = runWithContext;
+exports.setContextValue = setContextValue;
+const node_async_hooks_1 = require("node:async_hooks");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** The active context, or `undefined` outside a request. */
+function getActiveContext() {
+    return storage.getStore();
+}
+/** Run `fn` with `context` active for its whole async subtree. */
+function runWithContext(context, fn) {
+    return storage.run({ ...context }, fn);
+}
+/** Update one field of the active context; a no-op when none is active. */
+function setContextValue(key, value) {
+    const context = storage.getStore();
+    if (context === undefined)
+        return;
+    context[key] = value;
+}
+//# sourceMappingURL=active-context.js.map

package/dist/context/request-context.middleware.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Opens the request context and settles the correlation id (PLAN.md §16.2, §18).
+ *
+ * Runs before guards, so everything downstream — guards, interceptors, services,
+ * the exception filter — sees the same `requestId`, and the caller gets it back
+ * in the `X-Request-Id` header whether the request succeeded or failed.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type NestMiddleware } from '@nestjs/common';
+import type { NageCoreConfig } from '@nage-api/contracts';
+import { RequestContextService } from './request-context.service.js';
+/** What core needs from a request object, without binding to Express. */
+interface HttpRequestLike extends IncomingMessage {
+    readonly ip?: string;
+}
+/**
+ * A caller-supplied id is echoed into responses and log lines, so it is treated
+ * as untrusted input: anything not matching the expected shape is replaced
+ * rather than sanitized, which closes off log forging and header injection.
+ */
+export declare function resolveRequestId(candidate: string | undefined): string;
+/** Parse `x-application-version`; a malformed value falls back to the default. */
+export declare function parseApiVersion(candidate: string | undefined): number | undefined;
+export declare class RequestContextMiddleware implements NestMiddleware {
+    #private;
+    private readonly context;
+    constructor(context: RequestContextService, config?: NageCoreConfig);
+    use(request: HttpRequestLike, response: ServerResponse, next: () => void): void;
+}
+export {};
+//# sourceMappingURL=request-context.middleware.d.ts.map

package/dist/context/request-context.middleware.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Opens the request context and settles the correlation id (PLAN.md §16.2, §18).
+ *
+ * Runs before guards, so everything downstream — guards, interceptors, services,
+ * the exception filter — sees the same `requestId`, and the caller gets it back
+ * in the `X-Request-Id` header whether the request succeeded or failed.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContextMiddleware = void 0;
+exports.resolveRequestId = resolveRequestId;
+exports.parseApiVersion = parseApiVersion;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+const tokens_js_1 = require("../tokens.js");
+const request_context_service_js_1 = require("./request-context.service.js");
+function headerValue(request, name) {
+    const raw = request.headers[name];
+    if (Array.isArray(raw))
+        return raw[0];
+    return raw;
+}
+/**
+ * A caller-supplied id is echoed into responses and log lines, so it is treated
+ * as untrusted input: anything not matching the expected shape is replaced
+ * rather than sanitized, which closes off log forging and header injection.
+ */
+function resolveRequestId(candidate) {
+    if (candidate !== undefined && constants_js_1.REQUEST_ID_PATTERN.test(candidate))
+        return candidate;
+    return (0, node_crypto_1.randomUUID)();
+}
+/** Parse `x-application-version`; a malformed value falls back to the default. */
+function parseApiVersion(candidate) {
+    if (candidate === undefined)
+        return undefined;
+    const version = Number.parseInt(candidate, 10);
+    if (!Number.isInteger(version) || version < 1)
+        return undefined;
+    return version;
+}
+let RequestContextMiddleware = class RequestContextMiddleware {
+    context;
+    #versionHeader;
+    constructor(context, config) {
+        this.context = context;
+        this.#versionHeader = (config?.versioning?.header ?? constants_js_1.API_VERSION_HEADER).toLowerCase();
+    }
+    use(request, response, next) {
+        // Idempotent: if a context is already open (nested router, double
+        // registration) keep it rather than minting a second correlation id.
+        if (this.context.get() !== undefined) {
+            next();
+            return;
+        }
+        const requestId = resolveRequestId(headerValue(request, constants_js_1.REQUEST_ID_HEADER));
+        const correlationId = headerValue(request, constants_js_1.CORRELATION_ID_HEADER);
+        const apiVersion = parseApiVersion(headerValue(request, this.#versionHeader));
+        const userAgent = headerValue(request, 'user-agent');
+        const context = {
+            requestId,
+            startedAt: Date.now(),
+            ...(correlationId !== undefined && constants_js_1.REQUEST_ID_PATTERN.test(correlationId)
+                ? { correlationId }
+                : {}),
+            ...(apiVersion !== undefined ? { apiVersion } : {}),
+            ...(request.ip !== undefined ? { ip: request.ip } : {}),
+            ...(userAgent !== undefined ? { userAgent } : {}),
+        };
+        response.setHeader(constants_js_1.REQUEST_ID_HEADER, requestId);
+        this.context.run(context, next);
+    }
+};
+exports.RequestContextMiddleware = RequestContextMiddleware;
+exports.RequestContextMiddleware = RequestContextMiddleware = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(request_context_service_js_1.RequestContextService)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_js_1.NAGE_CONFIG)),
+    __metadata("design:paramtypes", [request_context_service_js_1.RequestContextService, Object])
+], RequestContextMiddleware);
+//# sourceMappingURL=request-context.middleware.js.map

package/dist/context/request-context.service.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ambient per-request context (PLAN.md §18).
+ *
+ * The legacy framework declared a `ClsStore` and never populated it, so no log
+ * line or response could be correlated to a request. This is the DI-facing
+ * wrapper over the process-wide store in `active-context.ts`: any code running
+ * inside the request — service, guard, repository, queue publisher — reads the
+ * same context, with nothing threaded through call signatures.
+ */
+import type { AuthUser, ContextStore, Id, RequestContext } from '@nage-api/contracts';
+export declare class RequestContextService implements ContextStore {
+    /** The active context, or `undefined` outside a request (jobs, boot code). */
+    get(): RequestContext | undefined;
+    /** The active context, or a thrown `INTERNAL_ERROR` when there is none. */
+    require(): RequestContext;
+    /** Run `fn` with `context` as the ambient context. */
+    run<TResult>(context: RequestContext, fn: () => TResult): TResult;
+    /**
+     * Update one field of the active context — how the auth guard attaches the
+     * resolved user once a token has been verified. A no-op outside a request, so
+     * background code never has to guard the call.
+     */
+    set<TKey extends keyof RequestContext>(key: TKey, value: RequestContext[TKey]): void;
+    /** Convenience accessors for the fields nearly every caller wants. */
+    get requestId(): string | undefined;
+    get user(): AuthUser | undefined;
+    get tenantId(): Id | undefined;
+}
+//# sourceMappingURL=request-context.service.d.ts.map

package/dist/context/request-context.service.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Ambient per-request context (PLAN.md §18).
+ *
+ * The legacy framework declared a `ClsStore` and never populated it, so no log
+ * line or response could be correlated to a request. This is the DI-facing
+ * wrapper over the process-wide store in `active-context.ts`: any code running
+ * inside the request — service, guard, repository, queue publisher — reads the
+ * same context, with nothing threaded through call signatures.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContextService = void 0;
+const common_1 = require("@nestjs/common");
+const catalog_js_1 = require("../errors/catalog.js");
+const active_context_js_1 = require("./active-context.js");
+let RequestContextService = class RequestContextService {
+    /** The active context, or `undefined` outside a request (jobs, boot code). */
+    get() {
+        return (0, active_context_js_1.getActiveContext)();
+    }
+    /** The active context, or a thrown `INTERNAL_ERROR` when there is none. */
+    require() {
+        const context = (0, active_context_js_1.getActiveContext)();
+        if (context === undefined) {
+            throw new catalog_js_1.InternalError({
+                detail: 'No request context is active',
+                meta: {
+                    hint: 'RequestContextMiddleware must run before this code, or wrap the work in context.run().',
+                },
+            });
+        }
+        return context;
+    }
+    /** Run `fn` with `context` as the ambient context. */
+    run(context, fn) {
+        return (0, active_context_js_1.runWithContext)(context, fn);
+    }
+    /**
+     * Update one field of the active context — how the auth guard attaches the
+     * resolved user once a token has been verified. A no-op outside a request, so
+     * background code never has to guard the call.
+     */
+    set(key, value) {
+        (0, active_context_js_1.setContextValue)(key, value);
+    }
+    /** Convenience accessors for the fields nearly every caller wants. */
+    get requestId() {
+        return (0, active_context_js_1.getActiveContext)()?.requestId;
+    }
+    get user() {
+        return (0, active_context_js_1.getActiveContext)()?.user;
+    }
+    get tenantId() {
+        return (0, active_context_js_1.getActiveContext)()?.tenantId;
+    }
+};
+exports.RequestContextService = RequestContextService;
+exports.RequestContextService = RequestContextService = __decorate([
+    (0, common_1.Injectable)()
+], RequestContextService);
+//# sourceMappingURL=request-context.service.js.map

package/dist/decorators/owner.decorator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@Owner()` — the authenticated principal for the current request
+ * (PLAN.md §13, §15.2).
+ *
+ * Typed as `AuthUser`, not `any`: the legacy `OwnerDto.info: any` is exactly the
+ * kind of boundary this framework refuses. Reads from the ambient context rather
+ * than `request.user`, so the same value is visible to services, repositories
+ * and queue publishers without threading it through call signatures.
+ */
+import type { AuthUser } from '@nage-api/contracts';
+/**
+ * @param field optional property to pluck, e.g. `@Owner('id')`
+ * @throws AuthenticationError when the route is reached without a principal
+ */
+export declare const Owner: (...dataOrPipes: (keyof AuthUser<string> | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/** Same as `@Owner()` but yields `undefined` on public routes instead of throwing. */
+export declare const OptionalOwner: (...dataOrPipes: unknown[]) => ParameterDecorator;
+//# sourceMappingURL=owner.decorator.d.ts.map

package/dist/decorators/owner.decorator.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * `@Owner()` — the authenticated principal for the current request
+ * (PLAN.md §13, §15.2).
+ *
+ * Typed as `AuthUser`, not `any`: the legacy `OwnerDto.info: any` is exactly the
+ * kind of boundary this framework refuses. Reads from the ambient context rather
+ * than `request.user`, so the same value is visible to services, repositories
+ * and queue publishers without threading it through call signatures.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionalOwner = exports.Owner = void 0;
+const common_1 = require("@nestjs/common");
+const catalog_js_1 = require("../errors/catalog.js");
+const active_context_js_1 = require("../context/active-context.js");
+/**
+ * @param field optional property to pluck, e.g. `@Owner('id')`
+ * @throws AuthenticationError when the route is reached without a principal
+ */
+exports.Owner = (0, common_1.createParamDecorator)((field, _context) => {
+    const user = (0, active_context_js_1.getActiveContext)()?.user;
+    if (user === undefined) {
+        throw new catalog_js_1.AuthenticationError('AUTH_REQUIRED', {
+            meta: { hint: '@Owner() used on a route that is not behind an authentication guard' },
+        });
+    }
+    return field === undefined ? user : user[field];
+});
+/** Same as `@Owner()` but yields `undefined` on public routes instead of throwing. */
+exports.OptionalOwner = (0, common_1.createParamDecorator)((_data, _context) => (0, active_context_js_1.getActiveContext)()?.user);
+//# sourceMappingURL=owner.decorator.js.map

package/dist/decorators/public.decorator.d.ts

@@ -0,0 +1,13 @@
+import { type CustomDecorator, type ExecutionContext } from '@nestjs/common';
+import type { Reflector } from '@nestjs/core';
+/**
+ * Marks a route as reachable without authentication (PLAN.md §15.1).
+ *
+ * Authentication is global and opt-**out**: forgetting a decorator leaves a
+ * route protected rather than open, which is the inverse of the legacy
+ * per-controller guard wiring.
+ */
+export declare const Public: () => CustomDecorator;
+/** Read the `@Public()` marker for the handler being executed. */
+export declare function isPublicRoute(reflector: Reflector, context: ExecutionContext): boolean;
+//# sourceMappingURL=public.decorator.d.ts.map

package/dist/decorators/public.decorator.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Public = void 0;
+exports.isPublicRoute = isPublicRoute;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+/**
+ * Marks a route as reachable without authentication (PLAN.md §15.1).
+ *
+ * Authentication is global and opt-**out**: forgetting a decorator leaves a
+ * route protected rather than open, which is the inverse of the legacy
+ * per-controller guard wiring.
+ */
+const Public = () => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.isPublic, true);
+exports.Public = Public;
+/** Read the `@Public()` marker for the handler being executed. */
+function isPublicRoute(reflector, context) {
+    return (reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.isPublic, [
+        context.getHandler(),
+        context.getClass(),
+    ]) === true);
+}
+//# sourceMappingURL=public.decorator.js.map