@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/monitoring/observability/audit-observation-emission.backend.d.ts

@@ -0,0 +1,309 @@
+/**
+ * # The seam every FIRE-AND-FORGET audit observation goes through — and the loss signal behind it
+ *
+ * assurance-control: WILDO.AUDIT.SECURITY_EVENT — a lost security observation is DETECTABLE, so a
+ * period with no recorded operator crossings is distinguishable from a period with a broken sink.
+ *
+ * ## The gap this closes, stated precisely
+ *
+ * A handful of security observations — an operator crossing a tenant boundary, an authorization
+ * refusal, a platform-access grant transition, a directory read — are emitted WITHOUT `await`, with
+ * the audit service FEATURE-DETECTED and the returned promise's rejection SWALLOWED. Every one of
+ * those three properties is deliberate and must survive: **an observation must never be able to fail
+ * the request it observes.** A fail-closed variant would hand anyone a way to disable operator
+ * support, or to convert a correct 403 into a 500, by breaking the audit sink.
+ *
+ * What was missing is not a refusal — it is a COUNT. With nothing recording the drops, an operator
+ * reading the trail cannot tell "no operator crossed a tenant boundary this week" from "the audit
+ * service has been unbound since Tuesday". Those two readings of the same empty result are what make
+ * the evidence worthless, and it is the same shape as
+ * `.claude/rules/negative-results-require-a-positive-probe.md`: an empty result is evidence about the
+ * pipeline, never about the world.
+ *
+ * ## What the existing control does NOT cover — measured 2026-09-09
+ *
+ * Three call sites carried the claim that *"detection of a lost row is the audit pipeline's own
+ * control (`audit_store_failure_total`), not this gate's"*. That claim is **true for one loss shape
+ * and false for the three that matter here.** `AuditLogsBackendService._createAuditLog` catches its
+ * Layer-1 store write and increments `audit_store_failure_total` — so a store that is DOWN while the
+ * service is bound and reachable is already counted. But that counter is inside a method the
+ * observer may never reach:
+ *
+ * | Loss shape | Reaches `_createAuditLog`? | Counted before this seam |
+ * |---|---|---|
+ * | {@link AuditObservationLossReason.SERVICE_UNAVAILABLE} — the audit service is unbound, or the `log*` method is absent (a partial DI binding, a host binding an older audit service) | no | **nothing at all** |
+ * | {@link AuditObservationLossReason.EMISSION_THREW} — the call threw synchronously | no | **nothing at all** |
+ * | {@link AuditObservationLossReason.EMISSION_REJECTED} — the returned promise rejected | partially | **nothing at all** at the observer |
+ * | the Layer-1 store write itself failed | yes | `audit_store_failure_total` (unchanged, and still the right control for that shape) |
+ *
+ * So this seam counts the OBSERVER-side drop — the case where the audit pipeline never learned there
+ * was anything to record — and leaves the pipeline's own control alone. The two are complementary,
+ * not duplicates, and a reviewer needs both: one says "we tried and the store refused", the other
+ * says "we never got as far as trying".
+ *
+ * ## Why a METRIC and a LOG, and not an audit row
+ *
+ * The loss signal must survive the audit store being down, so it cannot BE the audit store —
+ * recording "the audit store was unreachable" in the audit store is the circularity that makes the
+ * whole thing worthless. Two channels, deliberately, because neither alone is sufficient:
+ *
+ * - **`audit_observation_dropped_total`** (via {@link MetricsService.recordAuditObservationDropped})
+ *   is the RATE signal, and it is the durable one: the OTLP reader exports it periodically to the
+ *   metrics backend, so its value outlives the process and aggregates across instances. Without the
+ *   OTLP preload wired the global meter is a no-op and this channel is silently inert — which is
+ *   precisely why it is not the only channel.
+ * - **One rate-limited `error` log line** is the always-available channel and the WAKE-UP. It fires
+ *   at most once per {@link LOSS_LOG_INTERVAL_MS} per `(observation, reason)` pair, so a service
+ *   that has been unbound since boot produces one line rather than one per request. Unthrottled it
+ *   would flood, and a channel that floods is a channel operators filter out — which would leave the
+ *   signal technically present and practically absent.
+ *
+ * ## The process-local accumulator, argued rather than assumed
+ *
+ * {@link readAuditObservationLossTotals} is per-process and is **lost on restart**. That is stated
+ * here rather than glossed, because a reader could otherwise take it for durable evidence:
+ *
+ * - It is **not** the evidence. It is a test seam and a door for a future health surface. The
+ *   durable record is the exported counter (metrics backend) plus the log line (log store).
+ * - Per-instance is the correct granularity for the LOG channel anyway — "which replica lost
+ *   evidence" is part of the answer — and the metrics backend does the cross-instance aggregation
+ *   that a process-local number never could.
+ * - Rejected: a durable row for each loss. It is I/O on the observation path, it can fail the
+ *   request the whole design forbids failing, and it introduces a second store that can itself be
+ *   down. Rejected: a dedicated health endpoint. Still per-instance, adds a surface, and gives an
+ *   operator nothing the counter does not already give them.
+ *
+ * ## Why this is a SEAM and not a helper each site copies
+ *
+ * `.claude/rules/invariant-call-site-enumeration.md` — the invariant here ("a dropped observation is
+ * counted") holds at every fire-and-forget security observation in the package, spread across six
+ * subtrees, and the recurring defect in this repository is exactly the invariant applied at one of
+ * them. Routing every site through one function makes the counting structural rather than
+ * remembered: a new fire-and-forget observation that uses this seam is counted the day it lands,
+ * with no author having to know this mechanism exists.
+ *
+ * **Do not quote a call-site count from this file.** An earlier revision named one ("EIGHT call
+ * sites"), and the very next adoption pass made it wrong — a number in prose is one a reader has to
+ * re-measure before believing, which is worse than no number. Measure it:
+ *
+ * ```bash
+ * command grep -rn "emitAuditObservation(\|recordAuditObservationLoss(" engine/saas-backend-lib/src \
+ *   | grep -v __tests__ | grep -v audit-observation-emission.backend.ts
+ * ```
+ */
+/**
+ * WHICH security observation was lost.
+ *
+ * A closed vocabulary with one named runtime source, per `CLAUDE.md` — the member is what a reviewer
+ * reads off the alert, so it has to carry its own explanation rather than being a bare string at
+ * every call site. It is also the metric's `observation` label: bounded, low cardinality, and stable
+ * across renames of the emitting method.
+ *
+ * ## A member names the EVIDENCE, never the emitter
+ *
+ * Two members of this enum are emitted from more than one place, and that is the design rather than
+ * an omission. `CROSS_TENANT_ADMINISTRATIVE_ACCESS` is raised by the per-instance tenant gate AND by
+ * the APPLICATION-scoped collection read; `HTTP_API_READ_THROUGH_ACCESS` by the per-read adapter AND
+ * by the per-run ETL pipeline. Splitting either by emitter would make the one question an operator
+ * actually asks — *how much cross-tenant evidence did we lose?* — a sum over labels, and a sum
+ * somebody has to remember to widen is a sum that goes quietly wrong the day a third emitter lands.
+ * WHICH door dropped it is carried by the log line's `context`, which is the channel with room for
+ * it; the metric carries the rate, which is the thing that has to aggregate.
+ *
+ * The corollary: when you add an emitter for an event a member already names, REUSE the member and
+ * extend its JSDoc to name the new emitter. A member whose prose still names one of two emitters is
+ * a stale claim in the place a reviewer trusts most.
+ */
+export declare enum AuditObservationKind {
+    /**
+     * `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, from BOTH doors that can produce one.
+     *
+     * The most consequential member: this is the operator-crossing trail
+     * `.claude/rules/administrative-continuity-floors.md` requires, and the one whose silence is
+     * indistinguishable from "no operator crossed anything".
+     *
+     * - `authorizeOrganizations` — the per-instance tenant gate, deciding on ONE fetched row.
+     * - `ServiceResourceBackendService.recordCrossTenantReadAccess` — the APPLICATION-scoped
+     *   collection read, one observation per TENANT reached. The authorizer never sees this half: it
+     *   runs only for ORGANIZATIONS-scoped resources, and an application-scoped door returns a SET
+     *   whose rows belong to many tenants. Losing it silently is the larger of the two exposures,
+     *   because it is the door that can enumerate every tenant at once.
+     */
+    CROSS_TENANT_ADMINISTRATIVE_ACCESS = "cross_tenant_administrative_access",
+    /**
+     * `RESOURCE_OPERATION_DENIED` from the authorizer funnel. A lost refusal is a lost negative access
+     * decision — the record half of "record access decisions".
+     */
+    AUTHORIZATION_DENIAL = "authorization_denial",
+    /**
+     * `PLATFORM_ACCESS_GRANT_LIFECYCLE` from the grant custom implementation. A lost transition means
+     * an elevation exists whose request/approval is not in the trail.
+     */
+    PLATFORM_ACCESS_GRANT_LIFECYCLE = "platform_access_grant_lifecycle",
+    /**
+     * `PLATFORM_DIRECTORY_ACCESS` from `ServiceResourceBackendService.recordPlatformDirectoryAccess` —
+     * an APPLICATION-WIDE directory enumeration that no scope confined.
+     *
+     * `returnedCount` is why the row exists at all: it is the only thing separating "an operator
+     * opened the directory" from "an operator exported it". A lost observation does not merely lose an
+     * access record, it loses the SIZE, which is the half a reviewer reads first.
+     */
+    PLATFORM_DIRECTORY_ACCESS = "platform_directory_access",
+    /**
+     * `USER_SESSION_EVICTED` from the token issuer's concurrent-session cap.
+     *
+     * One observation per RETIRED refresh chain, not per enforcement: the cap bounds the blast radius
+     * of undetected token theft, so a burst of evictions for one principal is among the more
+     * interesting things the trail can carry — and a burst is exactly the case where losing some of
+     * the rows understates it. Counting per chain is what keeps the loss signal proportional to the
+     * evidence actually lost rather than to the number of times the cap ran.
+     */
+    USER_SESSION_EVICTED = "user_session_evicted",
+    /**
+     * `PROVIDER_OPERATION_CALL` from the provider operation executor — one row per OUTBOUND call to a
+     * third party, on both the success and the failure path.
+     *
+     * This is the application's record of what it sent to whom on whose behalf. Its silence is
+     * peculiarly misleading: an empty outbound trail reads as "this deployment integrates with
+     * nothing", which is a sentence somebody will believe.
+     */
+    PROVIDER_OPERATION_CALL = "provider_operation_call",
+    /**
+     * The post-call credential-use stamp from the provider operation executor.
+     *
+     * ## Why this is on THIS counter even though its sink is not the audit service
+     *
+     * It writes to the tenant's own credential row rather than to `AuditLogsBackendService`, and it is
+     * still the identical observer-side loss shape: fire-and-forget, sink feature-detected, rejection
+     * swallowed, nothing counting the drops. The counter's subject is the LOSS OF A SECURITY
+     * OBSERVATION, not the identity of the store that was supposed to receive it — so a second counter
+     * for one site would fragment the alert without telling an operator anything the `observation`
+     * label does not already say.
+     *
+     * What it evidences is narrow and worth stating: whether a stored credential was ACCEPTED by the
+     * provider on last use. Losing it leaves a credential whose health is unknown, which surfaces
+     * later as an integration that fails with no record of when it started failing.
+     */
+    PROVIDER_CREDENTIAL_USE = "provider_credential_use",
+    /**
+     * `HTTP_API_READ_THROUGH_ACCESS`, from BOTH emitters — see the enum's naming principle above.
+     *
+     * - `HttpApiResourceRepositoryBackendService.recordReadThroughAccess` — one observation per remote
+     *   round-trip, and the only tier that witnesses every one of them (repository-direct probes never
+     *   reach the services tier at all).
+     * - `ExternalDataPipelineRunBackendService.recordRunReadThroughAccess` — one observation per ETL
+     *   run.
+     *
+     * The evidence at stake is ATTRIBUTION: an HTTP_API read reaches a third party through a SHARED
+     * service principal, so this row is what carries the real initiating user through it. Without it
+     * the external system's own logs show one principal and nothing anywhere resolves it to a person.
+     */
+    HTTP_API_READ_THROUGH_ACCESS = "http_api_read_through_access"
+}
+/**
+ * WHY the observation never reached the audit pipeline.
+ *
+ * Three members, and they are genuinely different diagnoses rather than shades of one — see the
+ * table in this module's header. `SERVICE_UNAVAILABLE` is a WIRING fault and is usually total and
+ * permanent for the life of the process; the other two are runtime faults and are usually partial.
+ * Merging them would leave an operator unable to tell "this deployment audits nothing" from "the
+ * audit store hiccupped twice".
+ */
+export declare enum AuditObservationLossReason {
+    /** The audit service is unbound, or the specific `log*` method is absent on the bound instance. */
+    SERVICE_UNAVAILABLE = "service_unavailable",
+    /** The emitting call threw synchronously — before any `.catch()` could make it fire-and-forget. */
+    EMISSION_THREW = "emission_threw",
+    /** The emitting call returned a promise that rejected. */
+    EMISSION_REJECTED = "emission_rejected"
+}
+/**
+ * How often ONE `(observation, reason)` pair may produce a log line.
+ *
+ * Fifteen minutes: long enough that a permanently broken binding costs four lines an hour rather
+ * than one per request, short enough that a NEW outage hours after an earlier one still announces
+ * itself instead of being swallowed by a latch that never resets. A permanent latch was rejected for
+ * exactly that reason — it makes the second incident invisible.
+ */
+export declare const LOSS_LOG_INTERVAL_MS: number;
+/** The narrow slice of {@link MetricsService} this seam needs. Structural, so a double is trivial. */
+export interface AuditObservationLossMetricsRecorder {
+    recordAuditObservationDropped(params: {
+        observation: string;
+        reason: string;
+    }): void;
+}
+/**
+ * A LAZY door to the recorder, for a site that does not hold one.
+ *
+ * Most emitters here are plain classes built with `new` (repository adapters, the provider executor)
+ * or reach the container only through thunks their builder closes over. Each could resolve the
+ * recorder itself — and each would then need its own `try`/`catch`, because a container resolving a
+ * binding may throw and an observability failure must never reach the request. Five copies of that
+ * guard is precisely the shape `.claude/rules/invariant-call-site-enumeration.md` says will be
+ * applied at four of them, so the seam takes the thunk and does the wrapping once.
+ *
+ * Resolution happens ONLY when there is a loss to record. A site on the happy path never touches its
+ * container, which is what makes handing this in unconditionally cheap.
+ */
+export type AuditObservationLossMetricsResolver = () => AuditObservationLossMetricsRecorder | undefined;
+/** The narrow slice of the logger this seam needs. Optional everywhere — see {@link emitAuditObservation}. */
+export interface AuditObservationLossLogger {
+    error?: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Every loss recorded since this process started, as `<observation>:<reason>` → count.
+ *
+ * A COPY, so a caller cannot mutate the accumulator. Exists so the counting can be pinned without an
+ * OTLP backend, and so a future health surface has a door that does not require one either. Read the
+ * module header before treating the numbers as durable evidence: they are not.
+ */
+export declare function readAuditObservationLossTotals(): Record<string, number>;
+/** Test isolation only. Never called from production code. */
+export declare function resetAuditObservationLossTotals(): void;
+/**
+ * Record one lost observation. Never throws, under any circumstance.
+ *
+ * Exported so a site whose emission does not fit {@link emitAuditObservation}'s shape can still
+ * contribute to the same counter rather than inventing a second one. Prefer the seam.
+ */
+export declare function recordAuditObservationLoss(params: {
+    observation: AuditObservationKind;
+    reason: AuditObservationLossReason;
+    /** The recorder itself, when the site already holds one (a container-injected service). */
+    metricsService?: AuditObservationLossMetricsRecorder;
+    /**
+     * A thunk to the recorder, when the site does not. Consulted only if `metricsService` is absent,
+     * and only on a loss — see {@link AuditObservationLossMetricsResolver}. Two fields rather than one
+     * union: a caller reading `metricsService: X | (() => X)` has to work out which one it holds, and
+     * the answer is a property of the CLASS, so it is better spelled at the field.
+     */
+    metricsResolver?: AuditObservationLossMetricsResolver;
+    logger?: AuditObservationLossLogger;
+    error?: unknown;
+    context?: Record<string, unknown>;
+}): void;
+/**
+ * Emit one fire-and-forget audit observation, counting it if it is lost.
+ *
+ * ## The contract, which is the whole point
+ *
+ * **This function never throws and never returns a promise.** Not on an absent service, not on a
+ * synchronous throw, not on a rejection, and not on a metrics or logger failure. Callers rely on it
+ * to preserve the property their own JSDoc promises: the observation cannot fail the request.
+ *
+ * @param params.emit The emitting call, or `undefined` when the audit service or its method is
+ *   absent. Passing `undefined` is how a site reports {@link AuditObservationLossReason.SERVICE_UNAVAILABLE}
+ *   — the feature detection stays at the site because the method name differs per observation, and a
+ *   generic reflective lookup here would trade a compile-time error for a runtime one.
+ */
+export declare function emitAuditObservation(params: {
+    observation: AuditObservationKind;
+    emit: (() => unknown) | undefined;
+    metricsService?: AuditObservationLossMetricsRecorder;
+    /** See {@link recordAuditObservationLoss}. Never called unless there IS a loss. */
+    metricsResolver?: AuditObservationLossMetricsResolver;
+    logger?: AuditObservationLossLogger;
+    context?: Record<string, unknown>;
+}): void;
+//# sourceMappingURL=audit-observation-emission.backend.d.ts.map

package/dist/esm/monitoring/observability/audit-observation-emission.backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-observation-emission.backend.d.ts","sourceRoot":"","sources":["../../../../../src/monitoring/observability/audit-observation-emission.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oBAAY,oBAAoB;IAC9B;;;;;;;;;;;;;OAaG;IACH,kCAAkC,uCAAuC;IAEzE;;;OAGG;IACH,oBAAoB,yBAAyB;IAE7C;;;OAGG;IACH,+BAA+B,oCAAoC;IAEnE;;;;;;;OAOG;IACH,yBAAyB,8BAA8B;IAEvD;;;;;;;;OAQG;IACH,oBAAoB,yBAAyB;IAE7C;;;;;;;OAOG;IACH,uBAAuB,4BAA4B;IAEnD;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,4BAA4B;IAEnD;;;;;;;;;;;;OAYG;IACH,4BAA4B,iCAAiC;CAC9D;AAED;;;;;;;;GAQG;AACH,oBAAY,0BAA0B;IACpC,mGAAmG;IACnG,mBAAmB,wBAAwB;IAC3C,mGAAmG;IACnG,cAAc,mBAAmB;IACjC,0DAA0D;IAC1D,iBAAiB,sBAAsB;CACxC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAEnD,sGAAsG;AACtG,MAAM,WAAW,mCAAmC;IAClD,6BAA6B,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mCAAmC,GAAG,MAAM,mCAAmC,GAAG,SAAS,CAAC;AAExG,8GAA8G;AAC9G,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACtE;AAOD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvE;AAED,8DAA8D;AAC9D,wBAAgB,+BAA+B,IAAI,IAAI,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,oBAAoB,CAAC;IAClC,MAAM,EAAE,0BAA0B,CAAC;IACnC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,mCAAmC,CAAC;IACrD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,mCAAmC,CAAC;IACtD,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,GAAG,IAAI,CA6CP;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,WAAW,EAAE,oBAAoB,CAAC;IAClC,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC;IAClC,cAAc,CAAC,EAAE,mCAAmC,CAAC;IACrD,mFAAmF;IACnF,eAAe,CAAC,EAAE,mCAAmC,CAAC;IACtD,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,GAAG,IAAI,CAqCP"}