@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/core/errors/verbatim-error-body.exception.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withVerbatimErrorBody = withVerbatimErrorBody;
+exports.hasVerbatimErrorBody = hasVerbatimErrorBody;
+const common_1 = require("@nestjs/common");
+/**
+ * Opt-out from the shared error envelope (issue #153).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS EXISTS
+ * ---------------------------------------------------------------------------
+ * `HttpExceptionFilter` rebuilds EVERY error response from a fixed key
+ * allowlist — it reads `message`, `code` and `details` off the thrown payload
+ * and discards everything else. That is the right default and must stay the
+ * default: one envelope, parsed by exactly one code path in the web app and one
+ * in the CLI (`ApiError`, #140), with no endpoint quietly inventing its own
+ * error shape for its own callers to special-case.
+ *
+ * It is wrong for the small set of endpoints whose error body is dictated by an
+ * external specification rather than by us. `POST /auth/device/token` is the
+ * live example and the reason this file exists: RFC 8628 §3.5 (deferring to
+ * RFC 6749 §5.2) specifies `{ error, error_description }` at the TOP LEVEL of
+ * the token response, and the codes it defines — `authorization_pending`,
+ * `slow_down`, `expired_token`, `access_denied` — ARE the protocol. Each one
+ * demands a different action from the polling client: keep waiting, back off,
+ * restart the flow, stop and tell the user they declined. Flattened into the
+ * envelope all four arrived byte-identical, the RFC code destroyed server-side
+ * where no amount of client parsing could recover it, and the endpoint was
+ * simply not RFC 8628 compliant.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY A BRAND, AND NOT "A PAYLOAD THAT HAPPENS TO CARRY `error`"
+ * ---------------------------------------------------------------------------
+ * The smaller fix considered in #153 was for the filter to sniff the payload:
+ * if it has an `error` key, pass it through untouched. Fewer lines, no new
+ * concepts — and implicit in exactly the way that hurts later. It would make an
+ * endpoint's WIRE SHAPE a consequence of the KEY NAMES somebody happened to
+ * pick inside a thrown object, decided silently and at a distance from both the
+ * throw site and the filter.
+ *
+ * `throw new BadRequestException({ error: 'could not reach the mailer' })` is a
+ * completely natural line for someone to write. Under a sniffing filter that
+ * line drops its endpoint out of the envelope, the web app's error rendering
+ * stops finding `message`, and nothing at the throw site hints at why. Nobody
+ * would connect the failure to a decision made in an exception filter over a
+ * key name.
+ *
+ * The brand inverts that. An error leaves the envelope only because someone
+ * said so, in the throw, in one word that is greppable and links back here. An
+ * ordinary exception cannot fall out of the envelope by accident no matter what
+ * keys it carries, and the next person to add an RFC-shaped endpoint finds the
+ * mechanism by following the brand from the filter or from the throw site.
+ * The cost is one file of machinery; the thing it buys is that the default
+ * cannot be broken by inattention.
+ *
+ * ---------------------------------------------------------------------------
+ * WHEN TO USE IT
+ * ---------------------------------------------------------------------------
+ * Only when an external standard dictates the body. NOT to give an endpoint a
+ * nicer error shape, and NOT to smuggle an extra field to a client: that field
+ * belongs under `details`, which the envelope already carries through. Every
+ * new use is a new shape some client has to learn, so it should be rare enough
+ * that each one is argued for.
+ */
+/**
+ * Registered via `Symbol.for` rather than a module-local `Symbol()` on purpose.
+ * The brand is set in one module and read in another, and both this module and
+ * the filter can be instantiated twice in a single process — ts-jest gives each
+ * test file its own module registry, and a `src`/`dist` double-load does the
+ * same in a mis-built container. Two module instances mean two distinct local
+ * symbols, and the brand check would then silently return false: the response
+ * would quietly revert to the flattened envelope and #153 would be back with no
+ * error anywhere. The global symbol registry is keyed by string, so every copy
+ * of this module resolves to the same symbol.
+ */
+const VERBATIM_ERROR_BODY = Symbol.for('EnterpriseAppBase.verbatimErrorBody');
+/**
+ * Mark an exception so `HttpExceptionFilter` sends its payload to the client
+ * exactly as given, instead of rebuilding it as
+ * `{ statusCode, code, message, … }`.
+ *
+ * Returns the same exception instance, so the class identity is untouched:
+ * `withVerbatimErrorBody(new BadRequestException(…))` is still a
+ * `BadRequestException` and still carries status 400. That matters — guards,
+ * interceptors and existing tests that branch on the exception type keep
+ * working, and the opt-out stays a single orthogonal fact about the response
+ * body rather than a parallel exception hierarchy.
+ *
+ * The payload MUST be an object; a string payload has nothing to send verbatim
+ * and the filter falls back to the envelope for it.
+ *
+ * Only for a body an external standard dictates (RFC 8628's
+ * `{ error, error_description }` is the one use in the reference app); see
+ * the header of this file.
+ *
+ * @param exception - The exception to brand; returned as is.
+ * @returns The same exception instance.
+ * @stability stable
+ * @example
+ * ```ts
+ * throw withVerbatimErrorBody(
+ *   new BadRequestException({ error: 'slow_down', error_description: 'Polling too fast' }),
+ * );
+ * ```
+ */
+function withVerbatimErrorBody(exception) {
+    Object.defineProperty(exception, VERBATIM_ERROR_BODY, {
+        value: true,
+        // Non-enumerable so the brand cannot leak into anything that walks the
+        // exception's own properties — a log serializer, a test snapshot, an
+        // error-reporting SDK. It is an instruction to the filter, not data.
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return exception;
+}
+/**
+ * Whether an exception opted out of the envelope. Read only by
+ * `HttpExceptionFilter`.
+ *
+ * @param exception - Anything thrown.
+ * @returns `true` only for an `HttpException` branded by
+ *   {@link withVerbatimErrorBody}.
+ * @stability stable
+ * @example
+ * ```ts
+ * hasVerbatimErrorBody(withVerbatimErrorBody(new BadRequestException({ error: 'x' }))); // true
+ * ```
+ */
+function hasVerbatimErrorBody(exception) {
+    return (exception instanceof common_1.HttpException &&
+        exception[VERBATIM_ERROR_BODY] === true);
+}
+//# sourceMappingURL=verbatim-error-body.exception.js.map

package/dist/core/errors/verbatim-error-body.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbatim-error-body.exception.js","sourceRoot":"","sources":["../../../src/core/errors/verbatim-error-body.exception.ts"],"names":[],"mappings":";;AAwGA,sDAcC;AAeD,oDAOC;AA5ID,2CAA+C;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,SAAgB,qBAAqB,CACnC,SAAY;IAEZ,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,mBAAmB,EAAE;QACpD,KAAK,EAAE,IAAI;QACX,uEAAuE;QACvE,qEAAqE;QACrE,qEAAqE;QACrE,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,SAAkB;IACrD,OAAO,CACL,SAAS,YAAY,sBAAa;QACjC,SAAgD,CAC/C,mBAAmB,CACpB,KAAK,IAAI,CACX,CAAC;AACJ,CAAC"}

package/dist/core/host/index.d.ts

@@ -0,0 +1,7 @@
+export { definePlatformHost } from './platform-host';
+export type { PlatformAccessPort, PlatformHost } from './platform-host';
+export { AUDIT_SINK, PLATFORM_PRISMA, SYSTEM_SETTINGS_STORE } from './ports';
+export type { AuditEventInput, AuditSink, PortBinding, PrismaClientLike, SystemSettingsSnapshot, SystemSettingsStore, } from './ports';
+export { PlatformHostModule } from './platform-host.module';
+export type { PlatformHostPorts } from './platform-host.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/host/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAC7E,YAAY,EACV,eAAe,EACf,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/core/host/index.js

@@ -0,0 +1,14 @@
+"use strict";
+// The host ports (issue #696, PP-2.7): how a packaged slice reaches app-owned
+// capabilities without importing app code. Recipe: ../README.md, "Host ports".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformHostModule = exports.SYSTEM_SETTINGS_STORE = exports.PLATFORM_PRISMA = exports.AUDIT_SINK = exports.definePlatformHost = void 0;
+var platform_host_1 = require("./platform-host");
+Object.defineProperty(exports, "definePlatformHost", { enumerable: true, get: function () { return platform_host_1.definePlatformHost; } });
+var ports_1 = require("./ports");
+Object.defineProperty(exports, "AUDIT_SINK", { enumerable: true, get: function () { return ports_1.AUDIT_SINK; } });
+Object.defineProperty(exports, "PLATFORM_PRISMA", { enumerable: true, get: function () { return ports_1.PLATFORM_PRISMA; } });
+Object.defineProperty(exports, "SYSTEM_SETTINGS_STORE", { enumerable: true, get: function () { return ports_1.SYSTEM_SETTINGS_STORE; } });
+var platform_host_module_1 = require("./platform-host.module");
+Object.defineProperty(exports, "PlatformHostModule", { enumerable: true, get: function () { return platform_host_module_1.PlatformHostModule; } });
+//# sourceMappingURL=index.js.map

package/dist/core/host/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/host/index.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,+EAA+E;;;AAE/E,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAE3B,iCAA6E;AAApE,mGAAA,UAAU,OAAA;AAAE,wGAAA,eAAe,OAAA;AAAE,8GAAA,qBAAqB,OAAA;AAS3D,+DAA4D;AAAnD,0HAAA,kBAAkB,OAAA"}

package/dist/core/host/platform-host.d.ts

@@ -0,0 +1,67 @@
+/**
+ * How a packaged controller authenticates and authorizes its caller, supplied
+ * by the app. Each function returns ONE decorator (usually the app's own
+ * `applyDecorators(...)` composite) that a packaged controller applies to a
+ * handler or a class.
+ *
+ * @stability experimental
+ */
+export interface PlatformAccessPort {
+    /**
+     * Decorators that authenticate the caller AND require every listed
+     * permission. Must never be a no-op.
+     *
+     * @param permissions - the permission strings, all required; never empty.
+     */
+    requirePermissions(permissions: readonly string[]): MethodDecorator & ClassDecorator;
+    /** Decorators that authenticate the caller with no specific permission. */
+    requireAuthenticated(): MethodDecorator & ClassDecorator;
+    /**
+     * Optional: the app's marker for a DELIBERATELY public route (the reference
+     * app binds its `@Public()`), so its route inventory and conformance checks
+     * see the route as public on purpose rather than unguarded by accident. A
+     * slice applies it only to a route its README documents as public (the
+     * sharing slice's link resolution, #730) and authenticates that route by
+     * other means. A slice that needs it and finds it absent leaves the route out.
+     */
+    allowPublic?(): MethodDecorator & ClassDecorator;
+}
+/**
+ * Everything a packaged slice needs from the app at decorator time. Built once
+ * with {@link definePlatformHost} and passed to every slice's `forRoot({ host })`.
+ *
+ * @stability experimental
+ */
+export interface PlatformHost {
+    /** The app's authentication and authorization decorators. */
+    readonly access: PlatformAccessPort;
+}
+/**
+ * Validates and freezes the app's platform host.
+ *
+ * Checks that `access.requirePermissions` and `access.requireAuthenticated`
+ * (and the optional `access.allowPublic`) are functions and that each returns
+ * a decorator (each is called once, with a probe permission, to find out). The returned host wraps them so a later
+ * call that returns something else, or `requirePermissions([])`, throws too.
+ * Passing an already-defined host returns it unchanged.
+ *
+ * @param host - the app's access decorators.
+ * @returns the frozen, validated host.
+ * @throws Error when either access function is missing or returns a non-function.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/platform/platform-host.ts
+ * export const platformHost = definePlatformHost({
+ *   access: {
+ *     requirePermissions: (permissions) => Auth({ permissions: [...permissions] as PermissionName[] }),
+ *     requireAuthenticated: () => Auth(),
+ *   },
+ * });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function definePlatformHost(host: PlatformHost): PlatformHost;
+//# sourceMappingURL=platform-host.d.ts.map

package/dist/core/host/platform-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-host.d.ts","sourceRoot":"","sources":["../../../src/core/host/platform-host.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,GAAG,cAAc,CAAC;IACrF,2EAA2E;IAC3E,oBAAoB,IAAI,eAAe,GAAG,cAAc,CAAC;IACzD;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,eAAe,GAAG,cAAc,CAAC;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CA2CnE"}

package/dist/core/host/platform-host.js

@@ -0,0 +1,118 @@
+"use strict";
+// =============================================================================
+// The decorator-time host port (issue #696, PP-2.7)
+// =============================================================================
+//
+// A packaged controller must authenticate and authorize its caller exactly as
+// the app's own controllers do, without importing the app's auth code. Nest
+// applies decorators when a class is DEFINED, long before any container
+// exists, so access cannot be an injection token: it is a static port, built
+// once by the app (`apps/api/src/platform/platform-host.ts`) and handed to each
+// slice's `forRoot({ host })`. The slice then creates its controller class
+// inside `forRoot` with the host's decorators (the controller-factory recipe,
+// README.md next to this folder).
+//
+// FAIL CLOSED. `definePlatformHost` refuses a host whose access functions are
+// missing or do not return decorators, and a gate with no permission at all,
+// so a packaged route can never be public by accident.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePlatformHost = definePlatformHost;
+/** Hosts already validated and frozen, so passing one twice is free. */
+const definedHosts = new WeakSet();
+/** A permission string the define-time probe passes; never enforced anywhere. */
+const PROBE_PERMISSION = 'platform:probe';
+function fail(why) {
+    throw new Error(`definePlatformHost: ${why}. A platform host must supply working access decorators; ` +
+        'without them a packaged route would have no access check, and a platform route is never public.');
+}
+function assertDecorator(value, name) {
+    if (typeof value !== 'function')
+        fail(`access.${name}() returned ${value === null ? 'null' : typeof value}, not a decorator`);
+}
+function assertPermissions(permissions) {
+    if (!Array.isArray(permissions) || permissions.length === 0) {
+        fail('access.requirePermissions() was called with no permission; use requireAuthenticated() for "any signed-in caller"');
+    }
+    for (const permission of permissions) {
+        if (typeof permission !== 'string' || permission.trim() === '') {
+            fail(`access.requirePermissions() was called with an invalid permission ${JSON.stringify(permission)}`);
+        }
+    }
+    return permissions;
+}
+/**
+ * Validates and freezes the app's platform host.
+ *
+ * Checks that `access.requirePermissions` and `access.requireAuthenticated`
+ * (and the optional `access.allowPublic`) are functions and that each returns
+ * a decorator (each is called once, with a probe permission, to find out). The returned host wraps them so a later
+ * call that returns something else, or `requirePermissions([])`, throws too.
+ * Passing an already-defined host returns it unchanged.
+ *
+ * @param host - the app's access decorators.
+ * @returns the frozen, validated host.
+ * @throws Error when either access function is missing or returns a non-function.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/platform/platform-host.ts
+ * export const platformHost = definePlatformHost({
+ *   access: {
+ *     requirePermissions: (permissions) => Auth({ permissions: [...permissions] as PermissionName[] }),
+ *     requireAuthenticated: () => Auth(),
+ *   },
+ * });
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+function definePlatformHost(host) {
+    if (host !== null && typeof host === 'object' && definedHosts.has(host))
+        return host;
+    if (host === null || typeof host !== 'object')
+        fail('no host was given');
+    const access = host.access;
+    if (access === null || typeof access !== 'object')
+        fail('`access` is missing');
+    if (typeof access.requirePermissions !== 'function')
+        fail('`access.requirePermissions` is missing or not a function');
+    if (typeof access.requireAuthenticated !== 'function')
+        fail('`access.requireAuthenticated` is missing or not a function');
+    const requirePermissions = access.requirePermissions.bind(access);
+    const requireAuthenticated = access.requireAuthenticated.bind(access);
+    assertDecorator(requirePermissions([PROBE_PERMISSION]), 'requirePermissions');
+    assertDecorator(requireAuthenticated(), 'requireAuthenticated');
+    if (access.allowPublic !== undefined && typeof access.allowPublic !== 'function')
+        fail('`access.allowPublic` is not a function');
+    const allowPublic = access.allowPublic?.bind(access);
+    if (allowPublic)
+        assertDecorator(allowPublic(), 'allowPublic');
+    const defined = Object.freeze({
+        access: Object.freeze({
+            requirePermissions(permissions) {
+                const decorator = requirePermissions([...assertPermissions(permissions)]);
+                assertDecorator(decorator, 'requirePermissions');
+                return decorator;
+            },
+            requireAuthenticated() {
+                const decorator = requireAuthenticated();
+                assertDecorator(decorator, 'requireAuthenticated');
+                return decorator;
+            },
+            ...(allowPublic
+                ? {
+                    allowPublic() {
+                        const decorator = allowPublic();
+                        assertDecorator(decorator, 'allowPublic');
+                        return decorator;
+                    },
+                }
+                : {}),
+        }),
+    });
+    definedHosts.add(defined);
+    return defined;
+}
+//# sourceMappingURL=platform-host.js.map

package/dist/core/host/platform-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-host.js","sourceRoot":"","sources":["../../../src/core/host/platform-host.ts"],"names":[],"mappings":"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"}

package/dist/core/host/platform-host.module.d.ts

@@ -0,0 +1,53 @@
+import { DynamicModule, ModuleMetadata } from '@nestjs/common';
+import { AuditSink, PortBinding, PrismaClientLike, SystemSettingsStore } from './ports';
+/**
+ * The app's adapters for the DI-time ports, plus the modules they need.
+ *
+ * @stability experimental
+ */
+export interface PlatformHostPorts {
+    /** Binds {@link AUDIT_SINK}. */
+    audit?: PortBinding<AuditSink>;
+    /** Binds {@link SYSTEM_SETTINGS_STORE}. */
+    settings?: PortBinding<SystemSettingsStore>;
+    /** Binds {@link PLATFORM_PRISMA}. */
+    prisma?: PortBinding<PrismaClientLike>;
+    /**
+     * Modules the adapters' own dependencies come from (a settings adapter that
+     * injects the app's settings service needs that service's module). Global
+     * modules (the app's Prisma module) need not be listed.
+     */
+    imports?: ModuleMetadata['imports'];
+}
+/**
+ * Binds the platform's DI-time host ports to the app's adapters.
+ *
+ * @stability experimental
+ */
+export declare class PlatformHostModule {
+    /**
+     * Global. Binds the DI-time ports to the app's adapters. Each port is
+     * optional; a slice that injects a missing port fails at boot with Nest's
+     * missing-provider error naming the token.
+     *
+     * @param ports - one binding per port the app supplies, and the modules the
+     *   adapters need.
+     * @returns a global dynamic module exporting every bound token.
+     * @throws Error when a binding names no provider shape, or more than one.
+     *
+     * @example
+     * ```ts
+     * PlatformHostModule.forRoot({
+     *   audit: { useClass: PrismaAuditSink },
+     *   settings: { useClass: SystemSettingsStoreAdapter },
+     *   prisma: { useExisting: PrismaService },
+     *   imports: [SettingsModule],
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(ports?: PlatformHostPorts): DynamicModule;
+}
+//# sourceMappingURL=platform-host.module.d.ts.map

package/dist/core/host/platform-host.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-host.module.d.ts","sourceRoot":"","sources":["../../../src/core/host/platform-host.module.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,aAAa,EAAU,cAAc,EAAY,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAEL,SAAS,EAET,WAAW,EACX,gBAAgB,EAEhB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,KAAK,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAC5C,qCAAqC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CACrC;AAeD;;;;GAIG;AACH,qBACa,kBAAkB;IAC7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,GAAE,iBAAsB,GAAG,aAAa;CAqB7D"}

package/dist/core/host/platform-host.module.js

@@ -0,0 +1,90 @@
+"use strict";
+// =============================================================================
+// PlatformHostModule: binds the DI-time host ports once (issue #696, PP-2.7)
+// =============================================================================
+//
+// The app imports `PlatformHostModule.forRoot({...})` ONCE, in its root
+// module (`apps/api/src/platform/platform-host.module.ts`). The module is
+// global, so every packaged slice injects `AUDIT_SINK`, `SYSTEM_SETTINGS_STORE`
+// or `PLATFORM_PRISMA` without importing anything of the app.
+//
+// Every port is optional. A slice that injects a port the app did not bind
+// fails at boot with Nest's own missing-provider error, which names the token:
+// loud, early and specific, the same failure a missing app provider gives.
+// =============================================================================
+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 PlatformHostModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformHostModule = void 0;
+const common_1 = require("@nestjs/common");
+const ports_1 = require("./ports");
+function toProvider(token, name, binding) {
+    const shape = binding;
+    const kinds = shape && typeof shape === 'object' ? ['useExisting', 'useClass', 'useFactory'].filter((k) => k in shape) : [];
+    if (kinds.length !== 1) {
+        throw new Error(`PlatformHostModule.forRoot: the "${name}" port needs exactly one of useExisting, useClass or useFactory` +
+            (kinds.length > 1 ? ` (got ${kinds.join(', ')})` : '') +
+            '.');
+    }
+    return { provide: token, ...shape };
+}
+/**
+ * Binds the platform's DI-time host ports to the app's adapters.
+ *
+ * @stability experimental
+ */
+let PlatformHostModule = PlatformHostModule_1 = class PlatformHostModule {
+    /**
+     * Global. Binds the DI-time ports to the app's adapters. Each port is
+     * optional; a slice that injects a missing port fails at boot with Nest's
+     * missing-provider error naming the token.
+     *
+     * @param ports - one binding per port the app supplies, and the modules the
+     *   adapters need.
+     * @returns a global dynamic module exporting every bound token.
+     * @throws Error when a binding names no provider shape, or more than one.
+     *
+     * @example
+     * ```ts
+     * PlatformHostModule.forRoot({
+     *   audit: { useClass: PrismaAuditSink },
+     *   settings: { useClass: SystemSettingsStoreAdapter },
+     *   prisma: { useExisting: PrismaService },
+     *   imports: [SettingsModule],
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(ports = {}) {
+        const providers = [];
+        const exported = [];
+        const bind = (token, name, binding) => {
+            if (binding === undefined)
+                return;
+            providers.push(toProvider(token, name, binding));
+            exported.push(token);
+        };
+        bind(ports_1.AUDIT_SINK, 'audit', ports.audit);
+        bind(ports_1.SYSTEM_SETTINGS_STORE, 'settings', ports.settings);
+        bind(ports_1.PLATFORM_PRISMA, 'prisma', ports.prisma);
+        return {
+            global: true,
+            module: PlatformHostModule_1,
+            imports: ports.imports ?? [],
+            providers,
+            exports: exported,
+        };
+    }
+};
+exports.PlatformHostModule = PlatformHostModule;
+exports.PlatformHostModule = PlatformHostModule = PlatformHostModule_1 = __decorate([
+    (0, common_1.Module)({})
+], PlatformHostModule);
+//# sourceMappingURL=platform-host.module.js.map

package/dist/core/host/platform-host.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-host.module.js","sourceRoot":"","sources":["../../../src/core/host/platform-host.module.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,gFAAgF;AAChF,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,2EAA2E;AAC3E,gFAAgF;;;;;;;;;;AAEhF,2CAAiF;AAEjF,mCAQiB;AAsBjB,SAAS,UAAU,CAAC,KAAa,EAAE,IAAY,EAAE,OAAgB;IAC/D,MAAM,KAAK,GAAG,OAAyC,CAAC;IACxD,MAAM,KAAK,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5H,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,iEAAiE;YACvG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,GAAG,CACN,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAI,KAAgB,EAAc,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAC7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,QAA2B,EAAE;QAC1C,MAAM,SAAS,GAAe,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,OAAgB,EAAE,EAAE;YAC7D,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO;YAClC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;YACjD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CAAC;QAEF,IAAI,CAAC,kBAAU,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,6BAAqB,EAAE,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,uBAAe,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAE9C,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,oBAAkB;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,SAAS;YACT,OAAO,EAAE,QAAQ;SAClB,CAAC;IACJ,CAAC;CACF,CAAA;AA7CY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,kBAAkB,CA6C9B"}

package/dist/core/host/ports.d.ts

@@ -0,0 +1,132 @@
+import type { Type } from '@nestjs/common';
+/**
+ * Injection token of the app's {@link AuditSink}.
+ *
+ * @example
+ * ```ts
+ * constructor(@Inject(AUDIT_SINK) private readonly audit: AuditSink) {}
+ * ```
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const AUDIT_SINK: unique symbol;
+/**
+ * One audit event, as a packaged slice reports it. Never carries secret
+ * material: `meta` holds scalars only.
+ *
+ * @stability experimental
+ */
+export interface AuditEventInput {
+    /** What happened, `<resource>.<verb>` (`settings.updated`). */
+    action: string;
+    /** Who did it; `null` for the system itself. */
+    actorUserId: string | null;
+    /** The kind of thing it happened to (`system_settings`). */
+    targetType: string;
+    /** Which one. */
+    targetId: string;
+    /** Small scalar facts about the event. Never secret material. */
+    meta?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Where a packaged slice records audit events. The app persists them in its
+ * own audit table.
+ *
+ * @stability experimental
+ */
+export interface AuditSink {
+    /**
+     * Persists one audit event. Called after the triggering write commits.
+     * Never receives secret material.
+     */
+    record(event: AuditEventInput): Promise<void>;
+}
+/**
+ * Injection token of the app's {@link SystemSettingsStore}.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const SYSTEM_SETTINGS_STORE: unique symbol;
+/**
+ * One settings namespace and the version of the row it was read from.
+ *
+ * @stability experimental
+ */
+export interface SystemSettingsSnapshot {
+    /** The namespace's current value, as the app's namespace registry validated it. */
+    value: unknown;
+    /** The row version, for `If-Match` optimistic concurrency. */
+    version: number;
+}
+/**
+ * The app's deployment-wide settings, one namespace at a time. Validation,
+ * `If-Match` and the settings audit trail stay in the app.
+ *
+ * @stability experimental
+ */
+export interface SystemSettingsStore {
+    /**
+     * The current value of one settings namespace (validated by the app's
+     * namespace registry), plus the row version for If-Match.
+     */
+    read(namespace: string): Promise<SystemSettingsSnapshot>;
+    /**
+     * Patches one namespace with optimistic concurrency; audits through the
+     * app's own settings path. Rejects on a version mismatch (the app's 409).
+     */
+    patch(namespace: string, patch: Record<string, unknown>, ctx: {
+        actorUserId: string;
+        ifMatchVersion?: number;
+    }): Promise<SystemSettingsSnapshot>;
+}
+/**
+ * Injection token of the app's Prisma client, seen as a {@link PrismaClientLike}.
+ *
+ * @extensionPoint token
+ * @stability experimental
+ */
+export declare const PLATFORM_PRISMA: unique symbol;
+/**
+ * Schema-independent view of the app's generated client. Slices that own
+ * models narrow it with their own structural delegate types.
+ *
+ * @stability experimental
+ */
+export interface PrismaClientLike {
+    /** A tagged-template raw query. */
+    $queryRaw<T = unknown>(query: TemplateStringsArray, ...values: unknown[]): Promise<T>;
+    /** A tagged-template raw statement; resolves to the affected row count. */
+    $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+    /** An interactive transaction. */
+    $transaction<T>(fn: (tx: unknown) => Promise<T>, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    /** A client extension. */
+    $extends(extension: unknown): unknown;
+}
+/**
+ * How the app binds one port: an existing provider, a class, or a factory
+ * (Nest's own provider shapes, minus `provide`).
+ *
+ * @typeParam T - the port's interface.
+ *
+ * @stability experimental
+ */
+export type PortBinding<T> = {
+    /** Reuse a provider the app already has (a class, or a string or symbol token). */
+    useExisting: Type<T> | string | symbol;
+} | {
+    /** Instantiate this class (its own dependencies are injected). */
+    useClass: Type<T>;
+} | {
+    /**
+     * Build the port. Nest's own factory signature: dependencies arrive
+     * untyped, in `inject` order.
+     */
+    useFactory: (...deps: any[]) => T | Promise<T>;
+    /** The tokens whose instances `useFactory` receives. */
+    inject?: any[];
+};
+//# sourceMappingURL=ports.d.ts.map