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

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @marinoscar/platform-api
+
+## 0.1.0-next.3
+
+### Minor Changes
+
+- 76fb492: Export `deriveSigningKey(purpose)` from `@marinoscar/platform-api/core`: a 32-byte HMAC key derived from `SECRETS_ENCRYPTION_KEY` under the permanent label `enterpriseappbase:signing-key:v1:`, byte-identical to the app-side copy it replaces (#822).
+- 55a3402: Add the support bundle: `@marinoscar/platform-contract/doctor` (`supportBundleSchema`), `GET <doctor path>/support-bundle` with `SupportBundleRegistry`, `SupportBundleService`, redaction rules v1 and the built-in `meta`, `doctor` and `egress` sections in `@marinoscar/platform-api/doctor`, and the "Download support bundle" button and `useSupportBundleDownload` hook in `@marinoscar/platform-web/doctor` (plus the optional `PlatformApiClient.getBlob`).
+- f1fff88: Add the `telemetry` slice (`@marinoscar/platform-api/telemetry` and `/telemetry/testing`): `TelemetryModule.forRoot({ host, imports, ... })` with host ports for audit, settings, credentials, jobs, AI and app identity, the metric-group registry, the `VERDICT_POLICY` token with configurable verdict thresholds, and the five telemetry Doctor checks.
+
+### Patch Changes
+
+- Updated dependencies [738d71c]
+- Updated dependencies [55a3402]
+- Updated dependencies [bd9ad6f]
+  - @marinoscar/platform-contract@0.1.0-next.3
+
+## 0.1.0-next.2
+
+### Minor Changes
+
+- fd29180: Add `@marinoscar/platform-contract/doctor`, the first contract slice (#701): the Doctor's report, row, status and query schemas, their types and the zod-free status constants. `platform-api`'s Doctor DTOs now wrap these schemas and `platform-web`'s Doctor takes its types from them; both re-export the old names (`DOCTOR_STATUS_ORDER` and `DoctorReportQuery` in `platform-web` are deprecated aliases). No wire or OpenAPI change. Sets the contract conventions (slice layout, zod-free constants, import rules, `schema` catalog kind).
+- c41df57: Doctor slice: add the egress inventory (`EgressRegistry`, `EgressContributor`, `EgressDependency`, `classifyHost`) and the `network.egress` air-gap readiness check (`NetworkEgressDoctorCheck`, graded by `DEPLOYMENT_NETWORK_SOURCE`); `network` joins `PLATFORM_DOCTOR_CATEGORIES`.
+- a2db925: Add the `otel-core` slice: `@marinoscar/platform-api/otel-core/sdk` (the Nest-free `initializeOtel()` bootstrap, the runtime `telemetryGate` and its gated exporters, the service-name and instance-id resolvers) and `@marinoscar/platform-api/otel-core` (the `MetricsHostService` metrics host and `OtelMetricsModule`, the app-metric name registry, label bounding, the gauge-provider seam, `registerRequestSpanAttributes` and `@Trace()`).
+- ab888f5: Scoped data access in `@marinoscar/platform-api/core` (the user-owned data registry, `forUser`/`userScopeExtension`, `asSystem`, `ScopedAccessError`; schema-independent via `@prisma/client/extension`) and the `userOwnedData` conformance suite in `@marinoscar/platform-api/testing`.
+
+### Patch Changes
+
+- Updated dependencies [fd29180]
+  - @marinoscar/platform-contract@0.1.0-next.2
+
+## 0.1.0-next.1
+
+### Minor Changes
+
+- 1ca1ff0: core: add the principal and scope types, HttpExceptionFilter with ErrorDto and its exceptions, the secret cipher with verifyEncryptionKeyAtStartup, and the openApiTags registry.
+
+## 0.1.0-next.0
+
+### Minor Changes
+
+- 385e12f: Add the Doctor slice (`@marinoscar/platform-api/doctor`, `@marinoscar/platform-web/doctor/headless` and `/doctor/ui`), host ports in `core` (`definePlatformHost`, `PlatformHostModule`, `PlatformHostProvider`, `PlatformApiClient`) and in-memory test hosts in `testing`.
+- a66fef1: First pre-release of the platform packages: the six-package scaffold (build formats, boundary lint, pack check, TSDoc and generated API reference, single-instance peer dependencies) plus the first slices.
+
+  - `@marinoscar/platform-api/core`: the typed registry primitive (`defineRegistry`, `Registry`, `RegistryError`, `RegistryFreezeService`, `withTemporaryEntries`).
+  - `@marinoscar/platform-api/testing`: the conformance harness (`runPlatformConformance`, `conformanceSuites`) with the `cron-enqueue-only` suite.
+  - `@marinoscar/platform-cli/core`: the CLI command and env-spec fragment registries.
+  - `@marinoscar/platform-cli/telemetry`: the node span relay and the telemetry env-spec fragment.
+  - `@marinoscar/platform-infra`: `infraFile()`, the `platform-infra` command (`sync` materialises fragments into an app) and the `telemetry` slice (collector and GreptimeDB compose fragments, collector config and overlay, typed manifest).
+  - `@marinoscar/platform-contract`, `@marinoscar/platform-web` and `@marinoscar/platform-db` ship their package scaffold only; their slices follow in later releases.
+
+### Patch Changes
+
+- 9bc1ed1: Declare `fastify` as an optional peer: npm no longer auto-installs a second fastify beside the exact version `@nestjs/platform-fastify` pins in a consumer app (found by the consumer smoke).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marinoscar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @marinoscar/platform-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The NestJS side of the platform: dynamic modules (one subpath export per slice, for example `@marinoscar/platform-api/<slice>`) that an app imports into its own `AppModule` and extends through options, registries and injection tokens. CommonJS, compiled with `tsc` so decorator metadata (`design:paramtypes`) survives for Nest dependency injection.
+
+## Purpose and scope
+
+Dynamic modules, services, guards and registries of the platform's API slices. It does not own the app's composition root, its product identity or its own feature modules.
+
+Status: pre-release (version `0.0.0`). The root export is only the package name (`PLATFORM_PACKAGE`); the slices are subpath exports, each with its own README:
+
+- `@marinoscar/platform-api/core`: the bottom of the slice graph, code only: the typed registry primitive (`defineRegistry`, `Registry`, `RegistryError`, `RegistryFreezeService`, `withTemporaryEntries`), the principal and scope contract (`Principal`, `Scope`, `SystemActor`, ADR 0001), the exception filter and its exceptions (`HttpExceptionFilter`, `ErrorDto`, `withVerbatimErrorBody`, `DatabaseSeedException`), the secret cipher (`encryptSecret`, `decryptSecret`, `userCredentialPurpose`, `deriveSigningKey`, `verifyEncryptionKeyAtStartup`) and the OpenAPI tag registry (`openApiTags`), and scoped data access (`userOwnedModelRegistry`, `forUser`, `userScopeExtension`, `asSystem`, `ScopedAccessError`; schema-independent, #699). [README](src/core/README.md).
+- `@marinoscar/platform-api/testing`: the conformance harness (`runPlatformConformance`, `conformanceSuites`, the `cron-enqueue-only` and `user-owned-data` suites, and the small Prisma schema reader behind the latter). [README](src/testing/README.md).
+- `@marinoscar/platform-api/doctor`: the admin Doctor, `GET /api/admin/doctor` (`DoctorModule.forRoot({ host })`, `DoctorCheckRegistry`, the check contract). The first packaged slice (#696). [README](src/doctor/README.md).
+- `@marinoscar/platform-api/otel-core` and `@marinoscar/platform-api/otel-core/sdk`: the emitting half of telemetry (#700): `initializeOtel` (the Nest-free SDK bootstrap, loaded first), the runtime export gate `telemetryGate`, the metrics host `MetricsHostService` with the app-metric name registry and the gauge-provider seam, `registerRequestSpanAttributes` and `@Trace()`. [README](src/otel-core/README.md).
+
+The `core` slice also holds the **host ports** (#696: `definePlatformHost`, `AUDIT_SINK`, `SYSTEM_SETTINGS_STORE`, `PLATFORM_PRISMA`, `PlatformHostModule`), the one mechanism every packaged slice uses to reach app-owned capabilities, with test doubles in `testing`. [Host ports](src/core/README.md#host-ports).
+
+More slices arrive in later releases of the platform program.
+
+## Install and peer dependencies
+
+```bash
+npm install @marinoscar/platform-api
+```
+
+Install these in the app; the package never bundles its own copy (a second copy breaks dependency injection, hooks or theme context).
+
+| Package | Range |
+|---|---|
+| `@nestjs/common` | `^11.1.12` |
+| `@nestjs/core` | `^11.1.12` |
+| `@nestjs/swagger` | `^11.2.5` |
+| `@opentelemetry/api` | `^1.9.1` |
+| `@prisma/client` | `^7.8.0` |
+| `fastify` | `^5` |
+| `nestjs-zod` | `^5.4.0` |
+| `reflect-metadata` | `^0.2.2` |
+| `rxjs` | `^7.8.1` |
+| `zod` | `^4.4.3` |
+
+The OpenTelemetry SDK packages the `otel-core` slice installs (`@opentelemetry/sdk-node`, the auto-instrumentations, the OTLP/HTTP exporters and their SDK siblings) are regular dependencies, not peers: only `@opentelemetry/api`, which holds the process-wide providers, must be a single shared copy.
+
+## Quick start
+
+Run the platform's conformance suites from a spec of your own (the reference app's is [`apps/api/test/jobs/cron-enqueue-only.spec.ts`](../../apps/api/test/jobs/cron-enqueue-only.spec.ts)):
+
+```ts
+import { join } from 'node:path';
+import { runPlatformConformance } from '@marinoscar/platform-api/testing';
+
+runPlatformConformance({
+  sourceRoots: [join(__dirname, '..', '..', 'src')],
+  suites: { cronEnqueueOnly: { exempt: EXEMPT, minCronFiles: 8 } },
+});
+```
+
+Declare a registry with `defineRegistry`, register the exception filter and validate the encryption key at bootstrap with `@marinoscar/platform-api/core`; see the [core README](src/core/README.md#quick-start).
+
+## Configuration
+
+None at the package level. Each slice documents its own options: `DoctorModule.forRoot()` in the [doctor README](src/doctor/README.md#configuration), `initializeOtel()` and `OtelMetricsModule` in the [otel-core README](src/otel-core/README.md#configuration), `PlatformHostModule.forRoot()` in the [core README](src/core/README.md#host-ports), the harness in the [testing README](src/testing/README.md#configuration).
+
+## Extension-point catalog
+
+None. The root export is only the package name; the extension points live in the slice catalogs ([core](src/core/README.md#extension-point-catalog), [testing](src/testing/README.md#extension-point-catalog), [doctor](src/doctor/README.md#extension-point-catalog), [otel-core](src/otel-core/README.md#extension-point-catalog)).
+
+## Data
+
+None yet. A slice that owns models documents them here and in its own README; the schema fragments and migrations ship in `@marinoscar/platform-db`.
+
+## Permissions and settings
+
+The `doctor` slice requires `system_settings:read` by default and declares no permission of its own ([README](src/doctor/README.md#permissions-and-settings)). Other slices declare theirs in their own README as they are extracted.
+
+## UI
+
+None. Pages and settings cards live in `@marinoscar/platform-web`.
+
+## Infra
+
+Compose, nginx and collector configuration live in `@marinoscar/platform-infra`. The package reads `SECRETS_ENCRYPTION_KEY` (the `core` slice's secret cipher, see the [core README](src/core/README.md#configuration)) and, in the `otel-core` slice, the existing OpenTelemetry variables (`OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_DEBUG`); it exports OTLP/HTTP to the collector ([otel-core README](src/otel-core/README.md#infra)) and adds no variable.
+
+## Observability
+
+The `doctor` slice logs one `warn` line when a check throws; `core` logs one `debug` line when it freezes the static registries, one line per handled error and the encryption-key startup check ([core README](src/core/README.md#observability)). Packaged code logs through Nest's `Logger`, which the app routes to its own logger. `otel-core` installs the OpenTelemetry SDK (when `OTEL_ENABLED=true`) and exports only what its runtime gate lets through ([README](src/otel-core/README.md#observability)). Other slices document theirs as they are extracted.
+
+## Security notes
+
+Every packaged controller takes the app's auth decorators through the host access port (`definePlatformHost`) rather than ship its own, and every `forRoot` refuses to build one without a host, so a packaged route is never public. The one route so far, `GET /api/admin/doctor`, is read-only and requires `system_settings:read` by default. The `core` slice also holds the secret cipher and the exception filter; their key handling, the module-scope key cache (install exactly one copy of the package) and the error-body rules are in the [core README](src/core/README.md#security-notes).
+
+## Conformance suite
+
+The harness is the `testing` slice: `runPlatformConformance()` from `@marinoscar/platform-api/testing` runs the platform's suites in any app: `cron-enqueue-only` and `user-owned-data`. See the [testing README](src/testing/README.md#conformance-suite).
+
+## Upgrade notes
+
+None. No version has been published yet, so there is nothing to migrate from.
+
+## Troubleshooting
+
+None yet. Build and import problems common to every platform package are in [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages).
+
+## Links
+
+- [Platform packages spec](../../docs/specs/platform-packages.md): the extension contract and the package documentation standard
+- [Package documentation standard and checks](../../docs/PACKAGES.md): how this README, the TSDoc and the catalog are checked
+- [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages): build, test and lint commands

package/dist/core/crypto/encryption-key-startup-check.d.ts

@@ -0,0 +1,29 @@
+import type { LoggerService } from '@nestjs/common';
+/**
+ * Validate the encryption key as far as this deployment's state allows, and
+ * throw if the deployment is unable to read secrets it has already stored.
+ *
+ * Call from bootstrap BEFORE the port is bound, so a deployment that cannot
+ * read its own credentials never serves a request. See the header for the
+ * full decision; the short version is that a present key is always validated
+ * and an absent one is only fatal when there is something to decrypt.
+ *
+ * - Key set: validated (throws the cipher's operator-facing error if
+ *   malformed), then one `log` line.
+ * - Key absent, `countStoredSecrets()` rejects: one `warn` line, boot continues.
+ * - Key absent, count above zero: throws.
+ * - Key absent, count zero: one `warn` line, boot continues.
+ *
+ * @param countStoredSecrets - How many encrypted secrets the deployment has
+ *   stored (the reference app counts its `credentials` rows). Called only
+ *   when the key is absent.
+ * @param logger - Where the outcome is logged; a Nest `Logger` fits.
+ * @throws if the key is set but malformed, or unset while secrets are stored.
+ * @stability stable
+ * @example
+ * ```ts
+ * await verifyEncryptionKeyAtStartup(() => app.get(PrismaService).credential.count(), logger);
+ * ```
+ */
+export declare function verifyEncryptionKeyAtStartup(countStoredSecrets: () => Promise<number>, logger: Pick<LoggerService, 'log' | 'warn' | 'error'>): Promise<void>;
+//# sourceMappingURL=encryption-key-startup-check.d.ts.map

package/dist/core/crypto/encryption-key-startup-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-key-startup-check.d.ts","sourceRoot":"","sources":["../../../src/core/crypto/encryption-key-startup-check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAoHpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,4BAA4B,CAChD,kBAAkB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EACzC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,CA2Ff"}

package/dist/core/crypto/encryption-key-startup-check.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyEncryptionKeyAtStartup = verifyEncryptionKeyAtStartup;
+const secret_cipher_1 = require("./secret-cipher");
+// =============================================================================
+// SECRETS_ENCRYPTION_KEY startup validation  (issue #116, epic #108)
+// =============================================================================
+//
+// #114 built the cipher and #115 built the store on top of it. Both fail at the
+// moment of use if the key is missing or malformed, which is the failure this
+// issue exists to move: a deployment that boots happily and then 500s on a
+// settings page has turned a configuration error into a runtime error, and
+// handed it to the wrong person. This module is the bootstrap-time check that
+// puts it back in the deploy log.
+//
+// -----------------------------------------------------------------------------
+// THE DECISION: NO DEVELOPMENT FALLBACK KEY, AND NO NODE_ENV GATE AT ALL
+// -----------------------------------------------------------------------------
+// #116 offered two acceptable shapes for "the variable is absent in
+// development": fail identically everywhere, or fall back to a fixed,
+// loudly-logged development key. This chooses the first, and goes further by
+// not branching on NODE_ENV anywhere in this file. Two reasons.
+//
+// 1. A FIXED FALLBACK KEY IS A KEY IN A PUBLIC REPOSITORY. Whatever constant we
+//    shipped would be the key protecting every secret in any deployment that
+//    reached the fallback branch. The branch is only safe if "is this
+//    production?" is answered correctly 100% of the time — and here it would be
+//    answered by NODE_ENV, which is UNSET by default in Node, which
+//    `configuration.ts` therefore defaults to 'development', and which
+//    `app.module.ts` already uses to decide whether to load TestAuthModule. A
+//    deployment that forgets to set it does not fail; it quietly encrypts real
+//    SMTP passwords under a constant anyone can read off GitHub, and every
+//    symptom of that is invisible. Trading a hard failure for a silent
+//    catastrophic one is a bad trade at any convenience saving.
+//
+// 2. IT WOULD ALSO CORRUPT DEVELOPER DATA. Credentials written under a fallback
+//    key become permanently unreadable the moment a developer sets a real key —
+//    the cipher's auth tag fails, `CredentialsService.getSecret` throws, and the
+//    reported cause ("the payload is corrupt or the key changed") is true but
+//    baffling, because nobody remembers a key they never set.
+//
+// -----------------------------------------------------------------------------
+// SO WHAT MAKES IT STRICT WITHOUT BREAKING EVERY EXISTING DEPLOYMENT?
+// -----------------------------------------------------------------------------
+// The hard constraint: this repository sets SECRETS_ENCRYPTION_KEY NOWHERE
+// today — not in `infra/compose/.env.example` (#116 item 2 adds it), not in the
+// compose files, not in CI. In particular the `Smoke (boot compiled API)` job
+// boots `dist/main.js` with NODE_ENV=production and no such variable. A naive
+// unconditional throw here would therefore red the build immediately and break
+// every running deployment on its next restart — for a feature that, today, has
+// no consumer at all (#109 will be the first).
+//
+// Strictness is gated on whether the credential store IS IN USE, which is a
+// fact about the deployment rather than a claim about it:
+//
+//   key present  ->  validate its format. ALWAYS, in every environment. A
+//                    typo'd key is unambiguously an operator error, it can
+//                    never be the intended state, and catching it costs
+//                    nothing because no deployment sets the variable yet.
+//
+//   key absent,  ->  THROW. Every one of those rows is ciphertext this process
+//   rows exist       cannot read. The deployment is already broken; the only
+//                    question is whether it announces that in the deploy log or
+//                    waits to 500 at an admin. This is the case the issue is
+//                    actually about, and it is strict in development too.
+//
+//   key absent,  ->  WARN and boot. Nothing is stored, so nothing is
+//   no rows          unreadable, and there is no misconfiguration to report —
+//                    the feature is simply not set up. Every deployment in
+//                    existence right now, the smoke job included, is here.
+//
+// The state machine is closed rather than merely convenient, because rows
+// cannot exist without a key having been configured when they were written:
+// `CredentialsService.setSecret` calls `encryptSecret`, which throws without a
+// valid key. So "rows exist" really does mean "a key was working here once",
+// and its absence now really is a regression rather than a first-time setup.
+//
+// WHAT A DEVELOPER RUNNING `docker compose up` FOR THE FIRST TIME EXPERIENCES,
+// which is the trade-off this accepts and is worth stating plainly: the stack
+// comes up normally, with one WARN line naming the variable and giving the
+// generation command. Credential storage is the only thing that does not work,
+// and the first attempt to store one fails with secret-cipher's operator-facing
+// error — which also names the variable and gives the command. So the cost of
+// refusing a fallback key is one deferred error message, on a feature they were
+// deliberately reaching for, that tells them exactly what to do. The cost of
+// accepting one was a public key on production secrets. That is the trade.
+//
+// This is a floor, not a ceiling. Once #116 items 2-5 put the variable in
+// `.env.example` and the security docs, and once #109 gives the store a real
+// consumer, the "absent, no rows" branch can be tightened to a hard failure
+// without stranding anyone — every path that would then break has by that point
+// been told about the variable. Tightening it TODAY would only mean breaking CI
+// and every deployment to protect a feature nothing uses.
+//
+// -----------------------------------------------------------------------------
+// MOVED INTO @marinoscar/platform-api/core (issue #698)
+// -----------------------------------------------------------------------------
+// The one signature change of that move: the function used to take the app's
+// `PrismaService` and call `prisma.credential.count()` itself. It now takes a
+// `countStoredSecrets` callback, so core never imports a Prisma client or an
+// app model. The reference app passes
+// `() => app.get(PrismaService).credential.count()` from `main.ts`. Every
+// message and every decision branch above is unchanged.
+// =============================================================================
+/**
+ * Kept as a literal rather than imported from secret-cipher, which does not
+ * export it. Duplicating one string is the smaller cost: widening that module's
+ * public surface for a log line invites the next caller to reach in for
+ * something that actually matters.
+ */
+const KEY_ENV_VAR = 'SECRETS_ENCRYPTION_KEY';
+/** Repeated in every operator-facing message here. Same text as #114's. */
+const GENERATE_COMMAND = 'openssl rand -base64 32';
+/**
+ * Validate the encryption key as far as this deployment's state allows, and
+ * throw if the deployment is unable to read secrets it has already stored.
+ *
+ * Call from bootstrap BEFORE the port is bound, so a deployment that cannot
+ * read its own credentials never serves a request. See the header for the
+ * full decision; the short version is that a present key is always validated
+ * and an absent one is only fatal when there is something to decrypt.
+ *
+ * - Key set: validated (throws the cipher's operator-facing error if
+ *   malformed), then one `log` line.
+ * - Key absent, `countStoredSecrets()` rejects: one `warn` line, boot continues.
+ * - Key absent, count above zero: throws.
+ * - Key absent, count zero: one `warn` line, boot continues.
+ *
+ * @param countStoredSecrets - How many encrypted secrets the deployment has
+ *   stored (the reference app counts its `credentials` rows). Called only
+ *   when the key is absent.
+ * @param logger - Where the outcome is logged; a Nest `Logger` fits.
+ * @throws if the key is set but malformed, or unset while secrets are stored.
+ * @stability stable
+ * @example
+ * ```ts
+ * await verifyEncryptionKeyAtStartup(() => app.get(PrismaService).credential.count(), logger);
+ * ```
+ */
+async function verifyEncryptionKeyAtStartup(countStoredSecrets, logger) {
+    // An empty value ('SECRETS_ENCRYPTION_KEY=' with nothing after it, which is
+    // exactly what copying `.env.example` produces) is deliberately treated as
+    // ABSENT rather than as malformed — matching `getMasterKey`, which reports
+    // `!raw` as "is not set". A whitespace-only value is NOT absent: it is
+    // truthy, so it takes the strict branch below and is rejected as invalid
+    // base64, which is the honest reading of somebody having typed something.
+    if (process.env[KEY_ENV_VAR]) {
+        // Deliberately not wrapped, re-worded, or downgraded by environment.
+        // secret-cipher's error already names the variable, describes the shape of
+        // the failure ("decoded to 24 bytes") and gives the generation command,
+        // and it is addressed to precisely the person reading a failed deploy.
+        // Rewriting it here could only lose information.
+        (0, secret_cipher_1.assertEncryptionKeyConfigured)();
+        logger.log(`${KEY_ENV_VAR} is configured; encrypted credential storage is available.`);
+        return;
+    }
+    let storedCredentials;
+    try {
+        storedCredentials = await countStoredSecrets();
+    }
+    catch (error) {
+        // A failed probe is NOT a boot failure, and specifically is not reported as
+        // an encryption-key problem.
+        //
+        // The realistic cause is that the `credentials` table does not exist yet —
+        // a deployment running this build before `prisma migrate deploy` (Prisma
+        // P2021). Refusing to boot there would mean a new release could not start
+        // until migrations ran, while the migration step in some setups runs from
+        // the very container being blocked. The other cause is a database that is
+        // unreachable, which readiness already reports accurately and which would
+        // only be obscured by a message about encryption keys sending an operator
+        // to check the wrong thing.
+        //
+        // Failing OPEN here is safe because it cannot hide the dangerous state: if
+        // credentials do exist, this same check throws on the next boot that can
+        // actually see them.
+        logger.warn(`Could not check for stored credentials while validating ${KEY_ENV_VAR} ` +
+            `(the credentials table may not be migrated yet). Continuing startup. ` +
+            `Cause: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (storedCredentials > 0) {
+        // Fatal in EVERY environment, development included. There is no reading of
+        // this state that is intended: rows only exist because a key was working
+        // here at some point, so it has since been removed or the deployment is
+        // pointed at another environment's database.
+        //
+        // The message carries a count and never an address — `purpose`/`name` pairs
+        // are low-risk but this string goes to stdout on a failed deploy, and a
+        // count is all an operator needs to gauge the scale. Recovery detail
+        // (re-entering credentials, which ones) belongs in the rotation runbook,
+        // #116 item 5.
+        throw new Error(`${KEY_ENV_VAR} is not set, but ${storedCredentials} encrypted credential(s) ` +
+            `are stored in the database. Without the key that encrypted them they cannot ` +
+            `be read, so this deployment would fail at the point of use rather than here. ` +
+            `Restore the original key, or — if it is genuinely lost — delete the affected ` +
+            `credentials and have an administrator enter them again under a new key ` +
+            `generated with: ${GENERATE_COMMAND}`);
+    }
+    // Nothing is stored, so nothing is unreadable.
+    //
+    // STILL WARN AND NOT THROW, AND DELIBERATELY SO AFTER #377. Epic #372 moved
+    // object storage's secret access key into this store, so this branch is no
+    // longer "an unused feature is unconfigured" — a deployment here cannot save
+    // a storage credential, and every upload, avatar and database backup will be
+    // refused with a 503 naming the missing field. That is a strictly better
+    // outcome than refusing to boot: an API that will not start serves NOTHING,
+    // takes its health checks, its admin UI and the settings page an operator
+    // needs in order to fix this down with it, and turns a missing variable into
+    // an outage. The 503 says exactly what is wrong, to exactly the person who
+    // can fix it, on exactly the path that needs it.
+    //
+    // WARN and not ERROR for the same reason as before: a boot that then works
+    // for everything except storage is not a failed boot, and logging it at
+    // `error` trains operators to scroll past real ones.
+    logger.warn(`${KEY_ENV_VAR} is not set. Encrypted credential storage is unavailable, so ` +
+        `object storage cannot be configured and file uploads, avatars and database ` +
+        `backups will be refused until it is. No credentials are currently stored, ` +
+        `so nothing already saved is at risk. Generate a key with: ${GENERATE_COMMAND}`);
+}
+//# sourceMappingURL=encryption-key-startup-check.js.map

package/dist/core/crypto/encryption-key-startup-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-key-startup-check.js","sourceRoot":"","sources":["../../../src/core/crypto/encryption-key-startup-check.ts"],"names":[],"mappings":";;AA8IA,oEA8FC;AA1OD,mDAAgE;AAEhE,gFAAgF;AAChF,qEAAqE;AACrE,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,2EAA2E;AAC3E,2EAA2E;AAC3E,8EAA8E;AAC9E,kCAAkC;AAClC,EAAE;AACF,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,oEAAoE;AACpE,sEAAsE;AACtE,6EAA6E;AAC7E,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,6EAA6E;AAC7E,sEAAsE;AACtE,gFAAgF;AAChF,oEAAoE;AACpE,uEAAuE;AACvE,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE;AACvE,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,8EAA8E;AAC9E,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,+CAA+C;AAC/C,EAAE;AACF,4EAA4E;AAC5E,0DAA0D;AAC1D,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,wEAAwE;AACxE,0EAA0E;AAC1E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,qEAAqE;AACrE,8EAA8E;AAC9E,2EAA2E;AAC3E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,0DAA0D;AAC1D,EAAE;AACF,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAChF,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAC7E,sCAAsC;AACtC,0EAA0E;AAC1E,wDAAwD;AACxD,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAE7C,2EAA2E;AAC3E,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,KAAK,UAAU,4BAA4B,CAChD,kBAAyC,EACzC,MAAqD;IAErD,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,uEAAuE;IACvE,yEAAyE;IACzE,0EAA0E;IAC1E,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,qEAAqE;QACrE,2EAA2E;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,iDAAiD;QACjD,IAAA,6CAA6B,GAAE,CAAC;QAEhC,MAAM,CAAC,GAAG,CACR,GAAG,WAAW,4DAA4D,CAC3E,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,iBAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,iBAAiB,GAAG,MAAM,kBAAkB,EAAE,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4EAA4E;QAC5E,6BAA6B;QAC7B,EAAE;QACF,2EAA2E;QAC3E,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,4BAA4B;QAC5B,EAAE;QACF,2EAA2E;QAC3E,yEAAyE;QACzE,qBAAqB;QACrB,MAAM,CAAC,IAAI,CACT,2DAA2D,WAAW,GAAG;YACvE,uEAAuE;YACvE,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACrE,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC1B,2EAA2E;QAC3E,yEAAyE;QACzE,wEAAwE;QACxE,6CAA6C;QAC7C,EAAE;QACF,4EAA4E;QAC5E,wEAAwE;QACxE,qEAAqE;QACrE,yEAAyE;QACzE,eAAe;QACf,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,oBAAoB,iBAAiB,2BAA2B;YAC5E,8EAA8E;YAC9E,+EAA+E;YAC/E,+EAA+E;YAC/E,yEAAyE;YACzE,mBAAmB,gBAAgB,EAAE,CACxC,CAAC;IACJ,CAAC;IAED,+CAA+C;IAC/C,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,iDAAiD;IACjD,EAAE;IACF,2EAA2E;IAC3E,wEAAwE;IACxE,qDAAqD;IACrD,MAAM,CAAC,IAAI,CACT,GAAG,WAAW,+DAA+D;QAC3E,6EAA6E;QAC7E,4EAA4E;QAC5E,6DAA6D,gBAAgB,EAAE,CAClF,CAAC;AACJ,CAAC"}

package/dist/core/crypto/secret-cipher.d.ts

@@ -0,0 +1,151 @@
+/**
+ * First segment of every owner-bound sub-key domain (issue #387). See
+ * {@link userCredentialPurpose}. System purposes may not contain `:` at all
+ * (the reference app enforces it in `credentials/credential-internals.ts`),
+ * so no system purpose can begin with this.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * purpose.startsWith(USER_CREDENTIAL_DOMAIN_PREFIX); // an owner-bound domain
+ * ```
+ */
+export declare const USER_CREDENTIAL_DOMAIN_PREFIX = "user:";
+/**
+ * Is `value` a canonical (lowercase, hyphenated) UUID string?
+ *
+ * @param value - Anything.
+ * @returns `true` for `8-4-4-4-12` lowercase hex, the spelling Postgres and
+ *   Prisma render.
+ * @stability stable
+ * @example
+ * ```ts
+ * isCanonicalUuid('00000000-0000-4000-8000-000000000001'); // true
+ * isCanonicalUuid('00000000-0000-4000-8000-00000000000A'); // false (uppercase)
+ * ```
+ */
+export declare function isCanonicalUuid(value: unknown): value is string;
+/**
+ * Encrypt `plaintext` under the purpose-bound sub-key for `purpose`.
+ *
+ * Returns a base64 string carrying its own IV and auth tag — safe to put
+ * straight into a `text` column.
+ *
+ * @param plaintext - The secret, as UTF-8 text.
+ * @param purpose - The sub-key domain: a short fixed string per kind of
+ *   secret (`'smtp'`), or {@link userCredentialPurpose} for a per-user one.
+ * @returns base64 of `[iv: 12 bytes][authTag: 16 bytes][ciphertext]`.
+ * @throws if the key is missing/malformed, or `purpose` is empty.
+ * @stability stable
+ * @example
+ * ```ts
+ * const stored = encryptSecret(password, 'smtp');
+ * ```
+ */
+export declare function encryptSecret(plaintext: string, purpose: string): string;
+/**
+ * Decrypt a payload produced by `encryptSecret` under the SAME `purpose`.
+ *
+ * Any tampering — a flipped bit in the IV, the tag, or the ciphertext — and
+ * any purpose mismatch fails here rather than returning plausible garbage.
+ * That is the entire reason this is GCM and not CBC: an unauthenticated mode
+ * would hand back corrupted bytes that then get used as an SMTP password.
+ *
+ * @param payload - A string returned by {@link encryptSecret}.
+ * @param purpose - The same purpose it was encrypted under.
+ * @returns The plaintext.
+ * @throws if the key is missing/malformed, `purpose` is empty, the payload is
+ *         truncated, or authentication fails.
+ * @stability stable
+ * @example
+ * ```ts
+ * const password = decryptSecret(row.encryptedValue, 'smtp');
+ * ```
+ */
+export declare function decryptSecret(payload: string, purpose: string): string;
+/**
+ * Throw unless `SECRETS_ENCRYPTION_KEY` is present and well-formed.
+ *
+ * Exists so startup can fail on a bad key instead of the first administrator
+ * who tries to save a credential — a misconfiguration should surface in the
+ * deploy logs, not as a 500 weeks later. Wiring this into bootstrap is #116;
+ * this issue only provides the check.
+ *
+ * Also warms the cache, so the first real encrypt does not pay for validation.
+ *
+ * @throws the operator-facing key error (names the variable, the shape of the
+ *   failure and the generation command; never key material).
+ * @stability stable
+ * @example
+ * ```ts
+ * assertEncryptionKeyConfigured(); // throws if SECRETS_ENCRYPTION_KEY is unusable
+ * ```
+ */
+export declare function assertEncryptionKeyConfigured(): void;
+/**
+ * A 32-byte HMAC key for `purpose`, derived from `SECRETS_ENCRYPTION_KEY`
+ * (issue #822).
+ *
+ * For server-signed, short-lived tokens (a download link, a one-time URL)
+ * that need a deployment secret without a new environment variable: the
+ * master key is already mandatory and validated at startup, and the label
+ * `enterpriseappbase:signing-key:v1:` keeps every signing domain independent
+ * of every encryption domain, so a signing key can never decrypt a stored
+ * credential.
+ *
+ * Derivation: `HMAC-SHA256(masterKey, "enterpriseappbase:signing-key:v1:" + purpose)`.
+ * The label is permanent. Rotating the master key invalidates every
+ * outstanding token, which for minutes-long tokens is the desired behaviour.
+ *
+ * `purpose` is a code constant (`'android-app-download'`), never user input:
+ * derived keys are cached per purpose for the life of the process. Never log
+ * or return the key.
+ *
+ * @param purpose - The signing domain: a short fixed string per kind of token.
+ * @returns A 32-byte key for `createHmac('sha256', key)`.
+ * @throws if the key is missing/malformed (the same operator-facing error as
+ *   {@link assertEncryptionKeyConfigured}), or `purpose` is empty.
+ * @stability stable
+ * @example
+ * ```ts
+ * const mac = createHmac('sha256', deriveSigningKey('android-app-download'))
+ *   .update(payload)
+ *   .digest('base64url');
+ * ```
+ */
+export declare function deriveSigningKey(purpose: string): Buffer;
+/**
+ * The owner-bound sub-key domain for a PER-USER credential (issue #387):
+ * `user:<userId>:<purpose>`.
+ *
+ * Pass the result as the `purpose` argument of {@link encryptSecret} /
+ * {@link decryptSecret}; those functions are unchanged. Binding the owner into
+ * the domain means a ciphertext copied from user A's row into user B's row —
+ * a SQL write, a bug copying rows — fails GCM authentication rather than
+ * handing B the use of A's key. The system store's domain is the bare purpose;
+ * this is the same construction with the owner prepended.
+ *
+ * WHY THE STRING DECOMPOSES ONE WAY ONLY:
+ *   - `userId` must be a canonical UUID: fixed length, no `:`, one spelling
+ *     per id (an uppercase variant would otherwise derive a second key for
+ *     the same user and strand every row written under the first).
+ *   - `purpose` must not contain `:`, so the final segment is unambiguous.
+ *   - System purposes may not contain `:` either, so no system purpose can
+ *     equal, or begin with, `user:` — the two key spaces cannot collide.
+ * Together that makes (userId, purpose) → domain injective, which is what the
+ * concatenation in `deriveKey` relies on.
+ *
+ * @throws a plain Error (no values in it) on a non-canonical id or a bad
+ *         purpose. Callers validate first and report their own 400; this is
+ *         the backstop that keeps a malformed domain from ever deriving a key.
+ * @param userId - The owner: a canonical UUID.
+ * @param purpose - The kind of secret; non-empty, no `:`.
+ * @returns `user:<userId>:<purpose>`.
+ * @stability stable
+ * @example
+ * ```ts
+ * const stored = encryptSecret(apiKey, userCredentialPurpose(userId, 'ai_user_key'));
+ * ```
+ */
+export declare function userCredentialPurpose(userId: string, purpose: string): string;
+//# sourceMappingURL=secret-cipher.d.ts.map

package/dist/core/crypto/secret-cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.d.ts","sourceRoot":"","sources":["../../../src/core/crypto/secret-cipher.ts"],"names":[],"mappings":"AA6EA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,UAAU,CAAC;AAUrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE/D;AA+ID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA8BxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAqDtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAaxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAc7E"}