@onlineapps/service-common 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-09-15
+
+### Fixed — vadná hodnota jmenuje klíč, ne interní `"value"` (d.466b)
+
+Všechny čtyři env helpery (`requireEnv`, `requireTypedEnv` — tedy
+`requireNumberEnv` i `requireFloatEnv` —, `optionalEnv`, `optionalNumberEnv`)
+stavěly resolveru schéma pod interním jménem `value`. Hlášku o vadné hodnotě
+vlastní `@onlineapps/runtime-config` a píše do ní klíč, který dostal, takže
+operátor četl `Invalid number value for "value" (env: WS_MISSED_PONGS_LIMIT)` —
+jméno, které v žádné konfiguraci není. INFRA to viděla při kaskádě 2026-09-15.
+Klíč schématu je nově jméno proměnné prostředí: `Invalid number value for
+"WS_MISSED_PONGS_LIMIT" (env: WS_MISSED_PONGS_LIMIT)`.
+
+`requireNumberEnv`/`requireFloatEnv` navíc předávají do schématu `options.file`,
+které se do té doby použilo jen na větu o CHYBĚJÍCÍ proměnné a pro vadnou
+hodnotu zahodilo — obě věty přitom mluví o témž klíči v témž souboru. Místo
+(`in config/env-active/<file>`) se v hlášce objeví s pinem
+`@onlineapps/runtime-config` 1.2.0; pin 1.1.0 ji ještě nenese.
+
+Hlášky o CHYBĚJÍCÍ proměnné a veřejné API balíčku se nemění.
+
+### Fixed — redakce se bere z `@onlineapps/logger-contract`, lokální kopie jsou pryč (d.455)
+
+Balíček držel dvě vlastní implementace pravidla „co smí dorazit do logu“:
+`src/redactUrl.js` (userinfo z connection URL) a `src/redactSensitive.js`
+(`sensitive_input_fields`, SecretBox F1.5). Obě jsou smazány; `src/index.js`
+je teď **re-exportuje identitou** z `@onlineapps/logger-contract` 1.2.0.
+Veřejné API balíčku se nemění — `redactUrl`, `redactSensitiveDeep`,
+`sensitiveFieldsForOperation` a `REDACTED_PLACEHOLDER` se dál importují odsud,
+protože odsud si je berou `@onlineapps/infrastructure-tools` (a přes něj
+gateway) i monitoring.
+
+Čtyři otázky ke smazané deklaraci (`change-discipline.md` § Removing):
+
+1. **Proč vznikla** — obě kopie vznikly dřív, než core vrstva měla domov pro
+   toto pravidlo: `redactUrl` v d.245/d.245b (heslo z `REDIS_URL` ve třech
+   boot log lines), `redactSensitive` pro SecretBox F1.5. Importovat je
+   z vyšší vrstvy nešlo (`architecture-principles.md` §7), takže si každá
+   vrstva nesla svou.
+2. **Která část koncepce je nesla** — `change-discipline.md` § One rail per
+   concern je naopak zakazuje: tři vlastníci jednoho pravidla (tady,
+   `mq-client-core`, `conn-orch-registry`) a nic, co selže, když se rozejdou.
+   Ta část koncepce stojí dál.
+3. **Proč je dnes nikdo nečte** — `@onlineapps/logger-contract` 1.2.0 (d.453)
+   exportuje `redactUrl`, `UNPARSEABLE_PLACEHOLDER`, `redactSensitiveDeep`,
+   `sensitiveFieldsForOperation` a `REDACTED_PLACEHOLDER`; spustitelné řádky
+   jsou s oběma zdejšími kopiemi shodné (ověřeno `diff`, liší se jen JSDoc).
+4. **Je náhrada koncepčnější** — ano. `logger-contract` je vrstva L1 bez
+   `@onlineapps` závislostí, takže na ni dosáhne každá kategorie balíčků;
+   brána G7 naopak odmítá pin `orchestration` → `runtime`, kterým si dřív
+   `conn-orch-orchestrator` sahal pro tyto helpery sem.
+
+Testy `tests/unit/redactUrl.test.js` a `tests/unit/redactSensitive.test.js`
+odešly s implementací (pokrytí drží `@onlineapps/logger-contract`). Místo nich
+je `tests/unit/redactionReexport.test.js`: re-export je **identita**, lokální
+soubory na disku nejsou, chování (happy path, cesta selhání) dorazí ke
+konzumentovi beze změny, a kontrolní případ hlídá, že vlastní exporty balíčku
+se tím nehnuly.
+
+## [3.0.0] — 2026-09-14
+
 ### Fixed — registryReader se připojuje přes `connectRedis`; jeho timeoutová hláška renderovala heslo z `REDIS_URL` (d.441)
 
 `registryReader.connect()` měl ve větvi, kde klienta vlastní, **druhou kolej**

package/README.md

@@ -1,5 +1,5 @@
 > Status: current
-> Owns: the utilities infrastructure and business services share — JWT verification and tenant context, the Redis client, env and config readers, redaction, and the scope rules
+> Owns: the utilities infrastructure and business services share — JWT verification and tenant context, the Redis client, env and config readers, and the scope rules; redakce se sem jen re-exportuje z `@onlineapps/logger-contract`, který ji vlastní
 
 <!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
 Uniform: [library/runtime](../connector/conn-orch-validator/manifests/library.manifest.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis client, business errors, runtime config)",
   "oa": {
     "category": "runtime"
@@ -20,8 +20,8 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/logger-contract": "1.1.0",
-    "@onlineapps/runtime-config": "1.1.0",
+    "@onlineapps/logger-contract": "1.3.0",
+    "@onlineapps/runtime-config": "1.2.0",
     "jsonwebtoken": "^9.0.3",
     "nodemailer": "^10.0.9",
     "redis": "^4.6.0"

package/src/index.js

@@ -37,9 +37,9 @@ const {
 const {
   REDACTED_PLACEHOLDER,
   sensitiveFieldsForOperation,
-  redactSensitiveDeep
-} = require('./redactSensitive');
-const { redactUrl } = require('./redactUrl');
+  redactSensitiveDeep,
+  redactUrl
+} = require('@onlineapps/logger-contract');
 const {
   isVisible,
   filterVisible,
@@ -93,14 +93,17 @@ module.exports = {
   extractTenantContext,
   ROLES_VERSION_PREFIX,
 
-  // Sensitive-input redaction for observability sinks (SecretBox F1.5)
+  // Sensitive-input redaction for observability sinks (SecretBox F1.5).
+  // Re-export by identity from @onlineapps/logger-contract, which owns the rule
+  // (d.455); this package keeps the export because its consumers import it here.
   // See: docs/architecture/secretbox.md §8
   REDACTED_PLACEHOLDER,
   sensitiveFieldsForOperation,
   redactSensitiveDeep,
 
   // Credential redaction for connection URLs written to a log
-  // (REDIS_URL carries the Redis password — one rail, INFRA lead 2026-09-10)
+  // (REDIS_URL carries the Redis password — one rail, INFRA lead 2026-09-10).
+  // Re-export by identity from @onlineapps/logger-contract (d.455).
   redactUrl,
 
   // Scoped-registry visibility rule (system ∪ own workspace)

package/src/infrastructure/waitForHealthCheckQueueReady.js

@@ -2,7 +2,7 @@
 
 const { connectRedis, buildRedisUrl } = require('../redisClient');
 const { createPrefixedLogger } = require('./prefixedLogger');
-const { redactUrl } = require('../redactUrl');
+const { redactUrl } = require('@onlineapps/logger-contract');
 const runtimeCfg = require('../config');
 
 /**

package/src/infrastructure/waitForInfrastructureReady.js

@@ -2,7 +2,7 @@
 
 const { connectRedis, buildRedisUrl } = require('../redisClient');
 const { createPrefixedLogger } = require('./prefixedLogger');
-const { redactUrl } = require('../redactUrl');
+const { redactUrl } = require('@onlineapps/logger-contract');
 const runtimeCfg = require('../config');
 
 /**

package/src/redisClient.js

@@ -16,7 +16,7 @@ const { createClient } = require('redis');
 const runtimeCfg = require('./config');
 const { createRuntimeConfig } = require('@onlineapps/runtime-config');
 const { assertLogger } = require('@onlineapps/logger-contract');
-const { redactUrl } = require('./redactUrl');
+const { redactUrl } = require('@onlineapps/logger-contract');
 
 /**
  * Share of the caller's `timeoutMs` that node-redis' OWN connect attempt gets;
@@ -144,7 +144,7 @@ function createRedisClient(options = {}) {
   });
 
   // The URL carries the credential; the log carries the endpoint only.
-  // @see ./redactUrl.js
+  // @see @onlineapps/logger-contract
   const loggedUrl = redactUrl(url);
 
   client.on('error', (err) => {

package/src/runtime-config.js

@@ -79,12 +79,18 @@ function owningFileOf(options) {
  */
 function requireEnv(name, description, options) {
   const file = owningFileOf(options);
+  // Klíč schématu je jméno proměnné, ne interní `value`. Resolver jiné jméno
+  // klíče nezná, a co mu helper předá, to napíše do hlášky: do d.466b psal
+  // `Invalid number value for "value"`, takže z hlášky nešlo přečíst, který klíč
+  // je špatně (INFRA, kaskáda 2026-09-15). Zdejší kolej žádné jiné jméno nemá —
+  // helper dostává proměnnou, ne konfigurační klíč — a vymyslet mu jméno by
+  // znamenalo psát do hlášky fakt, který nikdo nedeklaroval.
   const cfg = createRuntimeConfig({
     defaults: {},
-    schema: { value: { env: name, required: true } },
+    schema: { [name]: { env: name, required: true } },
   });
   try {
-    return cfg.get('value');
+    return cfg.get(name);
   } catch (err) {
     // Jeden šablonový literál, ne skládání polem: statická sonda
     // `tests/unit/error-message-contract.test.js` čte zprávu ze zdroje, a
@@ -116,11 +122,16 @@ function requireEnv(name, description, options) {
  */
 function requireTypedEnv(name, description, type, options) {
   requireEnv(name, description, options);
+  // `file` dojde až do schématu: hlášku o vadné hodnotě skládá resolver a bez
+  // deklarace nemá odkud vzít místo, kam má operátor sáhnout. Do d.466b se
+  // `options.file` použil jen na větu o CHYBĚJÍCÍ proměnné a pro vadnou hodnotu
+  // se zahodil, ačkoli obě věty mluví o témž klíči v témž souboru.
+  const file = owningFileOf(options);
   const cfg = createRuntimeConfig({
     defaults: {},
-    schema: { value: { env: name, required: true, type } },
+    schema: { [name]: { env: name, required: true, type, ...(file ? { file } : {}) } },
   });
-  return cfg.get('value');
+  return cfg.get(name);
 }
 
 /**
@@ -191,9 +202,9 @@ function requireBoolEnv(name, description, options) {
 function optionalEnv(name, defaultValue) {
   const cfg = createRuntimeConfig({
     defaults: {},
-    schema: { value: { env: name, default: defaultValue } },
+    schema: { [name]: { env: name, default: defaultValue } },
   });
-  return cfg.get('value');
+  return cfg.get(name);
 }
 
 /**
@@ -205,9 +216,9 @@ function optionalEnv(name, defaultValue) {
 function optionalNumberEnv(name, defaultValue) {
   const cfg = createRuntimeConfig({
     defaults: {},
-    schema: { value: { env: name, default: defaultValue, type: 'number' } },
+    schema: { [name]: { env: name, default: defaultValue, type: 'number' } },
   });
-  return cfg.get('value');
+  return cfg.get(name);
 }
 
 /**

package/src/redactSensitive.js

@@ -1,87 +0,0 @@
-'use strict';
-
-/**
- * Sensitive-input redaction (SecretBox F1.5).
- * Contract: api/docs/architecture/secretbox.md §8.
- *
- * Pure, dependency-free helpers used by every layer that logs, traces, or
- * otherwise persists workflow/operation inputs (gateway, orchestrator, monitoring
- * consumer). Single implementation — no duplication across layers.
- *
- * Operations declare sensitive input fields at operation level in operations.json:
- *   "sensitive_input_fields": ["value", ...]
- * (NOT inside the JSON Schema — service-wrapper compiles input schemas with AJV
- * strict:true, which throws on unknown keywords.)
- *
- * `redactSensitiveDeep` deep-clones the value and replaces any object key whose
- * name is in `fieldNames` with the REDACTED placeholder, at any depth. It never
- * mutates the input. Over-redaction (a sensitive field name matching elsewhere in
- * the same payload) is acceptable and safe for observability sinks.
- *
- * IMPORTANT: this is for observability/log/trace copies only. The execution message
- * that carries the value to its owning handler MUST NOT be redacted.
- */
-
-const REDACTED_PLACEHOLDER = '[REDACTED]';
-const CIRCULAR_PLACEHOLDER = '[Circular]';
-
-/**
- * Extract the sensitive input field names for one operation from a service spec
- * (the `registry:service:<name>:spec` shape, or a local operations.json object).
- * @param {object} serviceSpec - object with `.operations[<op>]`.
- * @param {string} operationName
- * @returns {string[]} field names (empty array when none / not found).
- */
-function sensitiveFieldsForOperation(serviceSpec, operationName) {
-  const op =
-    serviceSpec &&
-    serviceSpec.operations &&
-    typeof serviceSpec.operations === 'object'
-      ? serviceSpec.operations[operationName]
-      : undefined;
-  const list = op && op.sensitive_input_fields;
-  return Array.isArray(list) ? list.filter((f) => typeof f === 'string' && f.length > 0) : [];
-}
-
-function _walk(node, fields, seen) {
-  if (node === null || typeof node !== 'object') return node;
-  // Do not recurse into non-plain objects; return a shallow copy where safe.
-  if (node instanceof Date) return new Date(node.getTime());
-  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(node)) return node;
-  if (seen.has(node)) return CIRCULAR_PLACEHOLDER;
-  seen.add(node);
-
-  if (Array.isArray(node)) {
-    return node.map((el) => _walk(el, fields, seen));
-  }
-
-  const out = {};
-  for (const key of Object.keys(node)) {
-    if (fields.has(key)) {
-      out[key] = REDACTED_PLACEHOLDER;
-    } else {
-      out[key] = _walk(node[key], fields, seen);
-    }
-  }
-  return out;
-}
-
-/**
- * Deep-clone `value`, replacing any object property named in `fieldNames` with
- * the REDACTED placeholder. Does not mutate the input.
- * @param {*} value - any JSON-ish value (object/array/primitive).
- * @param {string[]|Set<string>} fieldNames - sensitive field names to redact.
- * @returns {*} redacted deep clone (or the original value when there is nothing
- *   to redact — no sensitive fields means no mutation risk).
- */
-function redactSensitiveDeep(value, fieldNames) {
-  const fields = fieldNames instanceof Set ? fieldNames : new Set(fieldNames || []);
-  if (fields.size === 0) return value;
-  return _walk(value, fields, new WeakSet());
-}
-
-module.exports = {
-  REDACTED_PLACEHOLDER,
-  sensitiveFieldsForOperation,
-  redactSensitiveDeep
-};

package/src/redactUrl.js

@@ -1,58 +0,0 @@
-'use strict';
-
-/**
- * Redaction of credentials carried in a connection URL.
- *
- * `REDIS_URL` is the single rail for the Redis credential (INFRA lead's decision
- * 2026-09-10: one rail, no separate `REDIS_PASSWORD` in the shared env set).
- * That makes every place which logs the URL verbatim a credential leak — and
- * these logs go to Loki, so the leak is durable and searchable.
- *
- * `redactUrl` returns the same URL with the userinfo removed: what stays is the
- * part a reader of the log actually needs — scheme, host, port, path.
- *
- * A value that is not a parseable URL is returned as a fixed placeholder rather
- * than echoed: an unparseable string is exactly the case where nobody can say
- * whether it holds a credential, and echoing it would be the leak this helper
- * exists to prevent.
- */
-
-const UNPARSEABLE_PLACEHOLDER = '<unparseable-url>';
-
-/**
- * Strip userinfo (`user:password@`) from a connection URL.
- *
- * @param {string} url - connection URL, e.g. `redis://:secret@cache:6379`
- * @returns {string} the URL without userinfo, e.g. `redis://cache:6379`,
- *   or `<unparseable-url>` when the input is not a URL.
- */
-function redactUrl(url) {
-  if (typeof url !== 'string' || url.length === 0) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch (_) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  // `new URL('cache-host:6379')` SUCCEEDS — it reads `cache-host:` as the scheme
-  // and `6379` as an opaque path, so the value comes back with an empty host and
-  // no userinfo to strip. Measured 2026-09-11; without this guard such a value
-  // would be echoed verbatim, which is the leak this helper exists to prevent.
-  if (!parsed.host) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  parsed.username = '';
-  parsed.password = '';
-  // `URL.href` re-appends a trailing slash for an empty path; the URLs this is
-  // used on are host:port endpoints, and `redis://cache:6379/` is not the shape
-  // the rest of the platform writes.
-  const href = parsed.href;
-  return parsed.pathname === '/' && !url.endsWith('/') ? href.replace(/\/$/, '') : href;
-}
-
-module.exports = {
-  redactUrl,
-  UNPARSEABLE_PLACEHOLDER
-};