@mountainpass/addressr 2.5.1 → 2.6.0

package/lib/src/proxy-auth.js

@@ -16,8 +16,22 @@ const HEADER_VAR = 'ADDRESSR_PROXY_AUTH_HEADER';
 const VALUE_VAR = 'ADDRESSR_PROXY_AUTH_VALUE';
 
 // Closed list per ADR 024: /health for monitoring, /api-docs for gateway
-// OpenAPI imports (ADR 023). Exact-match, not prefix.
-const ALLOWLIST = new Set(['/health', '/api-docs']);
+// OpenAPI imports (ADR 023), /debug/shadow-config for operator diagnostics
+// (P035). Exact-match, not prefix.
+//
+// Debug-endpoint policy (deferred from ADR 024 amendment per the P035 plan
+// 2026-05-03; consolidate into ADR amendment when a 2nd /debug/* endpoint
+// lands):
+//   1. Each new /debug/<name> endpoint requires its own ALLOWLIST entry —
+//      no prefix matching, no `/debug/*` glob.
+//   2. Response body must be bounded: booleans, integers, ISO timestamps,
+//      and closed enums only. No free-text error messages, no hostnames /
+//      IPs / ARNs, no stack traces. Information-disclosure analysis must
+//      be trivial by inspection of the response shape.
+//   3. Every new debug endpoint adds a snapshot test in
+//      test/js/__tests__/proxy-auth.test.mjs covering both the new exempt
+//      path AND a "must NOT exempt" assertion to prevent accidental glob.
+const ALLOWLIST = new Set(['/health', '/api-docs', '/debug/shadow-config']);
 function isNonEmpty(value) {
   return typeof value === 'string' && value.length > 0;
 }

package/lib/src/read-shadow.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports._resetShadowClientForTesting = _resetShadowClientForTesting;
+exports._resetShadowCountersForTesting = _resetShadowCountersForTesting;
+exports.getShadowStatus = getShadowStatus;
 exports.mirrorRequest = mirrorRequest;
 exports.validateReadShadowConfig = validateReadShadowConfig;
 var _debug = _interopRequireDefault(require("debug"));
@@ -56,6 +58,20 @@ const DEFAULT_TIMEOUT_MS = 3000;
 // agents internally).
 let cachedClient;
 let cachedClientFingerprint;
+
+// P035: in-memory counters surfaced via /debug/shadow-config so an operator
+// can answer "is shadow firing?" in <200ms without ssh-ing into EB. Reset
+// at process boot; CloudWatch alarms (separate P035 task) cover the
+// persistent + cross-instance surface. Increments are JS-atomic on the
+// single-threaded event loop; no shared-memory worker threads in this
+// process, so no race protection needed. Number.MAX_SAFE_INTEGER is 2^53-1
+// — counter overflow horizon at 1000 q/s is ~285,000 years; not a concern.
+let shadowAttempts = 0;
+let shadowSuccesses = 0;
+let shadowFailures = 0;
+/** @type {{ class: 'AbortError' | 'ConnectionError' | 'AuthError' | 'UnknownError', ts: string } | null} */
+// eslint-disable-next-line unicorn/no-null -- explicit null preserves JSON serialization shape (`lastError: null` vs property dropped when undefined); contract documented in getShadowStatus JSDoc
+let lastShadowError = null;
 function isNonEmpty(value) {
   return typeof value === 'string' && value.length > 0;
 }
@@ -114,7 +130,27 @@ function getTimeoutMs(environment) {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
 }
+
+// Closed enum mapping (P035, ADR 024 information-disclosure remediation):
+// arbitrary error shapes from the OpenSearch client get bucketed into a
+// fixed-size set so the /debug/shadow-config response cannot leak free-text
+// (which routinely contains hostnames, IPs, ARNs in OpenSearch errors).
+function classifyError(reason) {
+  if (reason && reason.name === 'AbortError') return 'AbortError';
+  if (reason && (reason.code === 'ECONNREFUSED' || reason.code === 'ENOTFOUND' || reason.code === 'ETIMEDOUT' || reason.code === 'EAI_AGAIN' || reason.code === 'ECONNRESET')) {
+    return 'ConnectionError';
+  }
+  if (reason && (reason.statusCode === 401 || reason.statusCode === 403)) {
+    return 'AuthError';
+  }
+  return 'UnknownError';
+}
 function swallowError(reason) {
+  shadowFailures += 1;
+  lastShadowError = {
+    class: classifyError(reason),
+    ts: new Date().toISOString()
+  };
   if (reason && reason.name === 'AbortError') {
     error('read-shadow: request aborted by timeout');
     return;
@@ -154,6 +190,7 @@ function mirrorRequest({
   if (!client) {
     return; // feature disabled (HOST unset)
   }
+  shadowAttempts += 1;
   const timeoutMs = getTimeoutMs(environment);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -174,9 +211,18 @@ function mirrorRequest({
     clearTimeout(timer);
     return;
   }
+  // Architect §3 / risk R2: success-callback body is wrapped in try so a
+  // counter-increment exception (or any other synchronous throw) cannot
+  // propagate as an unhandled rejection. Failure paths land in swallowError
+  // via .catch which is itself try-shaped.
   promise.then(() => {
     clearTimeout(timer);
-    logger('read-shadow: %s ok', method);
+    try {
+      shadowSuccesses += 1;
+      logger('read-shadow: %s ok', method);
+    } catch (callbackError) {
+      swallowError(callbackError);
+    }
     return;
   }).catch(error_ => {
     clearTimeout(timer);
@@ -184,9 +230,65 @@ function mirrorRequest({
   });
 }
 
+/**
+ * Returns a snapshot of read-shadow runtime state for the
+ * `/debug/shadow-config` endpoint. Pure read of module-scoped state plus
+ * env-var presence checks; no I/O, no env-var values returned, no free-text
+ * error messages, no stack traces.
+ *
+ * Response shape:
+ * - `hostSet` / `credentialsSet`: booleans only — env vars present, not their values.
+ * - `clientConstructed`: true after the first `mirrorRequest` invocation that
+ *   reached the client construction step (i.e., HOST set and shadow has been
+ *   exercised at least once since boot).
+ * - `attempts` / `successes` / `failures`: integer counters since process start.
+ *   Reset on process restart; CloudWatch covers persistent metrics.
+ * - `lastError.class`: closed enum, never free text. One of:
+ *   - `'AbortError'` — request timeout (AbortController fired)
+ *   - `'ConnectionError'` — TCP/TLS/DNS/network reach failure (ECONNREFUSED, ENOTFOUND, etc.)
+ *   - `'AuthError'` — 401/403 from shadow target
+ *   - `'UnknownError'` — anything else (rare; the catch-all)
+ * - `lastError.ts`: ISO 8601 timestamp of the last failure.
+ *
+ * P035 / ADR 024 information-disclosure remediation: the bounded enum
+ * mechanically prevents leakage of hostnames, IPs, ARNs, or stack traces
+ * even though the endpoint is on the proxy-auth ALLOWLIST.
+ *
+ * @returns {{
+ *   hostSet: boolean,
+ *   credentialsSet: boolean,
+ *   clientConstructed: boolean,
+ *   attempts: number,
+ *   successes: number,
+ *   failures: number,
+ *   lastError: { class: 'AbortError' | 'ConnectionError' | 'AuthError' | 'UnknownError', ts: string } | null,
+ * }}
+ */
+function getShadowStatus(environment = process.env) {
+  return {
+    hostSet: isNonEmpty(environment[HOST_VAR]),
+    credentialsSet: isNonEmpty(environment[USERNAME_VAR]) && isNonEmpty(environment[PASSWORD_VAR]),
+    clientConstructed: !!cachedClient,
+    attempts: shadowAttempts,
+    successes: shadowSuccesses,
+    failures: shadowFailures,
+    lastError: lastShadowError
+  };
+}
+
 // Internal: lets unit tests reset the singleton between cases. Not part of
 // the public contract; flagged with a leading underscore by convention.
 function _resetShadowClientForTesting() {
   cachedClient = undefined;
   cachedClientFingerprint = undefined;
+}
+
+// Internal: lets unit tests reset counters between cases. Same convention
+// as _resetShadowClientForTesting.
+function _resetShadowCountersForTesting() {
+  shadowAttempts = 0;
+  shadowSuccesses = 0;
+  shadowFailures = 0;
+  // eslint-disable-next-line unicorn/no-null -- match initial value semantics for the public lastError contract
+  lastShadowError = null;
 }

package/lib/src/waycharter-server.js

@@ -987,6 +987,22 @@ function startRest2Server() {
       };
     }
   });
+
+  // P035: operator-diagnostic endpoint for read-shadow runtime introspection.
+  // Returns config-presence booleans + counters + closed-enum lastError;
+  // never returns hostnames, secrets, or free-text error messages.
+  // ALLOWLIST'd in src/proxy-auth.js per the debug-endpoint policy.
+  waycharter.registerResourceType({
+    path: '/debug/shadow-config',
+    loader: async () => {
+      return {
+        body: (0, _readShadow.getShadowStatus)(),
+        headers: {
+          'cache-control': 'no-cache'
+        }
+      };
+    }
+  });
   waycharter.registerResourceType({
     path: '/',
     loader: async () => {

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.5.1';
+const version = exports.version = '2.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",