@superblocksteam/telemetry 2.0.173-next.4 → 2.0.174

package/dist-esm/npm-registry/sanitize.d.ts

@@ -0,0 +1,174 @@
+/**
+ * NPM Registry Attribute Sanitization (APPS-4190)
+ *
+ * Sanitization helpers for the telemetry attributes that P6.2 (APPS-4189
+ * metrics) and P6.3 (APPS-4191 audit events) emit from every npm install
+ * path. Every emitter MUST pass values through these helpers before
+ * attaching them to a span, metric, log, or audit event so that cloud-prem
+ * telemetry never carries customer infra hostnames or registry tokens.
+ *
+ * Policy split — package_name is destination-dependent (decision-point
+ * captured in PR / README "NPM Registry Sanitization"):
+ *
+ *   - For metric destinations (Datadog tags, OTel metric attributes,
+ *     anything where cardinality is a billing/scale concern OR the
+ *     destination is shared across orgs): emit a low-cardinality bucket
+ *     instead of the raw name. Use `npmAttributesForMetric` →
+ *     `package_name_bucket` ∈ { public | private | unknown | invalid }.
+ *
+ *   - For audit / log destinations (per-org event streams, forensic
+ *     value, internally retained): emit the lowercased name verbatim,
+ *     gated against known-secret value shapes. Use `npmAttributesForAudit`
+ *     → `package_name` ∈ { <verbatim> | unknown | invalid }.
+ *
+ * Other attributes (the same across destinations):
+ *   - registry_host → bounded enum: public_npm | private | unknown
+ *   - npm.outcome   → closed allowlist; unknown values → `other`
+ *   - tokens        → never appear in any attribute (regression-tested)
+ */
+export declare const NPM_REGISTRY_BUCKETS: readonly ["public_npm", "private", "unknown"];
+export type NpmRegistryBucket = (typeof NPM_REGISTRY_BUCKETS)[number];
+/**
+ * Map a registry URL or bare hostname to a bounded bucket. Raw hostnames
+ * are never emitted; downstream emitters always pass values through here.
+ *
+ * Rules:
+ *   - null/undefined/blank → `unknown`
+ *   - parse failure        → `unknown`
+ *   - hostname exact-matches PUBLIC_NPM_HOSTS (case-insensitive) → `public_npm`
+ *   - anything else        → `private`
+ *
+ * `npm.pkg.github.com` is conservatively bucketed as `private`: customers
+ * deploy it as their private registry, and bucketing it as private avoids
+ * the false-negative of suppressing private-registry behavior in telemetry.
+ */
+export declare function bucketNpmRegistryHost(input: string | null | undefined): NpmRegistryBucket;
+/**
+ * Audit/log-destination form of `registry_host`. Unlike the metric/span
+ * path (which buckets to `public_npm | private | unknown` so a raw customer
+ * hostname never reaches a shared, cross-tenant destination), logs are
+ * per-org and retained internally, so on-call needs the **raw** hostname for
+ * forensic value ("which registry did org X actually hit?"). This helper is
+ * the log-boundary guard: it returns the host verbatim EXCEPT when it
+ *
+ *   - matches a known-secret value shape (`containsForbiddenPattern`) — a
+ *     developer-error backstop against a token smuggled in via a host arg, or
+ *   - contains an ASCII C0 control character or DEL — a log-injection /
+ *     line-spoofing payload,
+ *
+ * in which case it returns `"invalid"`. null/blank → `"unknown"`. The value
+ * is trimmed but otherwise unchanged (not lowercased): the host is the
+ * forensic signal and case is preserved as attempted.
+ */
+export declare function auditNpmRegistryHost(input: string | null | undefined): string;
+/**
+ * Audit/log-destination form of the `package_name` attribute. Returns the
+ * lowercased input verbatim when it parses as an npm name AND does not
+ * match a known-secret value shape. Use only for destinations that can
+ * tolerate per-package cardinality and per-org name sensitivity (audit
+ * event streams, internal logs). For metric destinations, use
+ * `bucketNpmPackageName` instead — emitting raw names as metric tags is
+ * unbounded cardinality and leaks customer-internal package names across
+ * orgs sharing a metric destination.
+ *
+ *   - null/undefined/blank        → `unknown`
+ *   - matches a known-secret value pattern (token, JWT, AWS key, etc.)
+ *                                 → `invalid` (defense for developer error
+ *                                    that stuffs a secret into a name arg)
+ *   - input fails npm name spec   → `invalid`
+ *   - otherwise                   → lowercased input verbatim
+ *
+ * The known-secret check uses `containsForbiddenPattern` from the tier-2
+ * traces contract, so this helper stays in sync with the existing
+ * runtime/lint guardrails as new secret shapes are added there.
+ */
+export declare function sanitizeNpmPackageName(input: string | null | undefined): string;
+/**
+ * Metric-destination bucket for the package name. Low-cardinality and
+ * agnostic of the specific name — dashboards split installs by registry
+ * source without ever seeing customer-internal package names.
+ *
+ *   - public_npm registry + valid name → `public`
+ *   - private registry   + valid name  → `private`
+ *   - unknown registry   + valid name  → `unknown`
+ *   - name fails npm spec OR matches a known-secret value pattern → `invalid`
+ *   - name is null/empty                                          → `unknown`
+ *
+ * The registry bucket is taken as input rather than recomputed so callers
+ * never accidentally bucket a name without also bucketing its registry.
+ */
+export declare const NPM_PACKAGE_NAME_BUCKETS: readonly ["public", "private", "unknown", "invalid"];
+export type NpmPackageNameBucket = (typeof NPM_PACKAGE_NAME_BUCKETS)[number];
+export declare function bucketNpmPackageName(input: string | null | undefined, registryBucket: NpmRegistryBucket): NpmPackageNameBucket;
+/**
+ * Closed outcome enum. First five values match the structured error from
+ * APPS-4179 (P1.2) and APPS-4195 (P1.5); `tls_failed` was added in
+ * APPS-4381 to give TLS handshake failures their own dashboard facet
+ * (previously routed to `other` and lost the actionable CA-bundle signal);
+ * `other` is the catch-all so dashboards never see free-form strings.
+ */
+export declare const NPM_OUTCOMES: readonly ["success", "not_in_registry", "registry_unreachable", "registry_auth_failed", "tls_failed", "lockfile_url_mismatch", "package_substituted", "vulnerable_package", "vulnerability_triaged", "vulnerability_user_override", "other"];
+export type NpmOutcome = (typeof NPM_OUTCOMES)[number];
+/** Coerce an outcome to the closed enum at the emit boundary. */
+export declare function normalizeNpmOutcome(input: string | null | undefined): NpmOutcome;
+export interface NpmAttributesInput {
+    registry_host?: string | null;
+    package_name?: string | null;
+    outcome?: string | null;
+}
+/** Metric-destination output shape. Low-cardinality across all fields. */
+export interface NpmMetricAttributes {
+    registry_host: NpmRegistryBucket;
+    package_name_bucket: NpmPackageNameBucket;
+    outcome: NpmOutcome;
+}
+/**
+ * Audit/log-destination output shape. `package_name` is verbatim
+ * (lowercased) — use only for destinations that can tolerate per-package
+ * cardinality and per-org name sensitivity.
+ */
+export interface NpmAuditAttributes {
+    registry_host: NpmRegistryBucket;
+    package_name: string;
+    outcome: NpmOutcome;
+}
+/**
+ * Metric-safe attributes. Emitters of OTel metrics, Datadog metric tags,
+ * Tempo span attributes that flow to shared metric destinations, etc.
+ * MUST use this wrapper. The output never contains a raw package name.
+ */
+export declare function npmAttributesForMetric(input: NpmAttributesInput): NpmMetricAttributes;
+/**
+ * Audit/log-safe attributes. Emitters of audit events and internal logs
+ * that retain per-org context (and that operators rely on for forensic
+ * value, e.g. "which package failed for org X?") use this wrapper. The
+ * verbatim name is gated by the known-secret value pattern set.
+ */
+export declare function npmAttributesForAudit(input: NpmAttributesInput): NpmAuditAttributes;
+/**
+ * Redact registry URLs and bare hostnames from a free-text npm/pnpm error
+ * blob before it lands in a shared operational log line (auto-upgrade
+ * `[npm-install-blocked]` and any future caller). The destination is shared
+ * across orgs, so even an incidental hostname in the npm-emitted phrasing —
+ * `"401 Unauthorized - GET https://customer.jfrog.io/..."`,
+ * `"request to https://npm.private/... failed, reason: ENOTFOUND npm.private"`,
+ * `"connect ECONNREFUSED 10.0.0.5:4873"` — is a customer-infra leak that
+ * `bucketNpmRegistryHost` already prevents for the structured `registry_host`
+ * facet. This helper extends the same rule to free-text fields:
+ *
+ *   - Every `http(s)://...` URL is replaced with its registry bucket token
+ *     (`<public_npm>` or `<private>`), preserving the diagnostic shape of
+ *     the line while erasing the host.
+ *   - Bare `ENOTFOUND <host>` / `EAI_AGAIN <host>` payloads — npm emits the
+ *     host as the next whitespace-delimited token after these DNS error
+ *     codes — get the host replaced with `<host>`.
+ *   - `connect E* <ip>[:port]` payloads (ECONNREFUSED, ETIMEDOUT, …) — the
+ *     IP literal carries the same private-infra signal as a hostname — get
+ *     the address replaced with `<host>`.
+ *
+ * The replacement is intentionally lossy: the npm phrasing ("Unauthorized",
+ * "self-signed certificate in chain", "ENOTFOUND") is what operators need
+ * for triage; the host identity is what we must drop.
+ */
+export declare function redactNpmRegistryHostsFromText(input: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist-esm/npm-registry/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/npm-registry/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,eAAO,MAAM,oBAAoB,+CAIvB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AA2BtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,iBAAiB,CAkBnB;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAS7E;AAeD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,CAWR;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,sDAK3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,cAAc,EAAE,iBAAiB,GAChC,oBAAoB,CAetB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,8OAYf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvD,iEAAiE;AACjE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,UAAU,CAGZ;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,iBAAiB,CAAC;IACjC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,iBAAiB,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAUrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAMpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA0BpE"}

package/dist-esm/npm-registry/sanitize.js

@@ -0,0 +1,331 @@
+/**
+ * NPM Registry Attribute Sanitization (APPS-4190)
+ *
+ * Sanitization helpers for the telemetry attributes that P6.2 (APPS-4189
+ * metrics) and P6.3 (APPS-4191 audit events) emit from every npm install
+ * path. Every emitter MUST pass values through these helpers before
+ * attaching them to a span, metric, log, or audit event so that cloud-prem
+ * telemetry never carries customer infra hostnames or registry tokens.
+ *
+ * Policy split — package_name is destination-dependent (decision-point
+ * captured in PR / README "NPM Registry Sanitization"):
+ *
+ *   - For metric destinations (Datadog tags, OTel metric attributes,
+ *     anything where cardinality is a billing/scale concern OR the
+ *     destination is shared across orgs): emit a low-cardinality bucket
+ *     instead of the raw name. Use `npmAttributesForMetric` →
+ *     `package_name_bucket` ∈ { public | private | unknown | invalid }.
+ *
+ *   - For audit / log destinations (per-org event streams, forensic
+ *     value, internally retained): emit the lowercased name verbatim,
+ *     gated against known-secret value shapes. Use `npmAttributesForAudit`
+ *     → `package_name` ∈ { <verbatim> | unknown | invalid }.
+ *
+ * Other attributes (the same across destinations):
+ *   - registry_host → bounded enum: public_npm | private | unknown
+ *   - npm.outcome   → closed allowlist; unknown values → `other`
+ *   - tokens        → never appear in any attribute (regression-tested)
+ */
+import { containsForbiddenPattern } from "../common/contracts/tier2-traces.js";
+export const NPM_REGISTRY_BUCKETS = [
+    "public_npm",
+    "private",
+    "unknown",
+];
+/**
+ * Exact-match allowlist for the `public_npm` bucket: hostnames that serve the
+ * public npm package set and need no login, so labelling them `public_npm`
+ * leaks nothing and keeps them out of the `private` count.
+ *
+ *   - `registry.npmjs.org` / `registry.npmjs.com`: the npm public registry
+ *     (the `.com` form is a long-standing alias customers still pin).
+ *   - `registry.npmmirror.com`: the public npmmirror CDN (popular in Asia),
+ *     formerly `registry.npm.taobao.org`.
+ *   - `registry.npm.taobao.org`: the old taobao mirror hostname, still set in
+ *     older lockfiles and `.npmrc` files.
+ *
+ * Deliberately NOT here: `npm.pkg.github.com` (GitHub Packages), `*.jfrog.io`,
+ * and AWS CodeArtifact hostnames. Customers deploy those as their own private
+ * registry and each needs a login, so even when one proxies the public npm
+ * registry the access is scoped to a single org. Bucketing them `private` is
+ * the correct and safe choice.
+ */
+const PUBLIC_NPM_HOSTS = new Set([
+    "registry.npmjs.org",
+    "registry.npmjs.com",
+    "registry.npmmirror.com",
+    "registry.npm.taobao.org",
+]);
+/**
+ * Map a registry URL or bare hostname to a bounded bucket. Raw hostnames
+ * are never emitted; downstream emitters always pass values through here.
+ *
+ * Rules:
+ *   - null/undefined/blank → `unknown`
+ *   - parse failure        → `unknown`
+ *   - hostname exact-matches PUBLIC_NPM_HOSTS (case-insensitive) → `public_npm`
+ *   - anything else        → `private`
+ *
+ * `npm.pkg.github.com` is conservatively bucketed as `private`: customers
+ * deploy it as their private registry, and bucketing it as private avoids
+ * the false-negative of suppressing private-registry behavior in telemetry.
+ */
+export function bucketNpmRegistryHost(input) {
+    if (input == null)
+        return "unknown";
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "unknown";
+    let host;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+        try {
+            host = new URL(trimmed).hostname.toLowerCase();
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    else {
+        host = trimmed.split(/[/:]/, 1)[0].toLowerCase();
+    }
+    if (host === "")
+        return "unknown";
+    return PUBLIC_NPM_HOSTS.has(host) ? "public_npm" : "private";
+}
+/**
+ * Control characters (ASCII C0 range + DEL) that must never reach a log
+ * line: a newline/carriage-return lets a hostile value forge a second log
+ * record, and other C0 bytes corrupt structured-log parsers.
+ */
+function hasControlChar(value) {
+    // ASCII C0 controls (0x00-0x1F) + DEL (0x7F). A regex literal holding these
+    // raw bytes is invisible in source and trips no-control-regex, so we scan
+    // code points instead.
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Audit/log-destination form of `registry_host`. Unlike the metric/span
+ * path (which buckets to `public_npm | private | unknown` so a raw customer
+ * hostname never reaches a shared, cross-tenant destination), logs are
+ * per-org and retained internally, so on-call needs the **raw** hostname for
+ * forensic value ("which registry did org X actually hit?"). This helper is
+ * the log-boundary guard: it returns the host verbatim EXCEPT when it
+ *
+ *   - matches a known-secret value shape (`containsForbiddenPattern`) — a
+ *     developer-error backstop against a token smuggled in via a host arg, or
+ *   - contains an ASCII C0 control character or DEL — a log-injection /
+ *     line-spoofing payload,
+ *
+ * in which case it returns `"invalid"`. null/blank → `"unknown"`. The value
+ * is trimmed but otherwise unchanged (not lowercased): the host is the
+ * forensic signal and case is preserved as attempted.
+ */
+export function auditNpmRegistryHost(input) {
+    if (input == null)
+        return "unknown";
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "unknown";
+    // Secret-shape check runs on the trimmed (case-preserved) value: AKIA/JWT
+    // patterns are case-sensitive and must be caught before they reach a log.
+    if (containsForbiddenPattern(trimmed))
+        return "invalid";
+    if (hasControlChar(trimmed))
+        return "invalid";
+    return trimmed;
+}
+/** npm package name spec (lowercased): optional `@scope/` prefix + name body. */
+const VALID_PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/**
+ * npm name length cap from the package-name spec. The character-set regex
+ * alone admits arbitrarily long strings of `[a-z0-9._-]`; without this cap
+ * a hostile or buggy caller can flow a 10k-char payload through the
+ * verbatim audit/log path. Enforced on both the audit and metric helpers
+ * so an oversize input is `invalid` in either destination.
+ */
+const NPM_PACKAGE_NAME_MAX_LENGTH = 214;
+/**
+ * Audit/log-destination form of the `package_name` attribute. Returns the
+ * lowercased input verbatim when it parses as an npm name AND does not
+ * match a known-secret value shape. Use only for destinations that can
+ * tolerate per-package cardinality and per-org name sensitivity (audit
+ * event streams, internal logs). For metric destinations, use
+ * `bucketNpmPackageName` instead — emitting raw names as metric tags is
+ * unbounded cardinality and leaks customer-internal package names across
+ * orgs sharing a metric destination.
+ *
+ *   - null/undefined/blank        → `unknown`
+ *   - matches a known-secret value pattern (token, JWT, AWS key, etc.)
+ *                                 → `invalid` (defense for developer error
+ *                                    that stuffs a secret into a name arg)
+ *   - input fails npm name spec   → `invalid`
+ *   - otherwise                   → lowercased input verbatim
+ *
+ * The known-secret check uses `containsForbiddenPattern` from the tier-2
+ * traces contract, so this helper stays in sync with the existing
+ * runtime/lint guardrails as new secret shapes are added there.
+ */
+export function sanitizeNpmPackageName(input) {
+    if (input == null)
+        return "unknown";
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "unknown";
+    if (trimmed.length > NPM_PACKAGE_NAME_MAX_LENGTH)
+        return "invalid";
+    // Check against secret patterns BEFORE lowercasing: AKIA/JWT/PEM patterns
+    // are case-sensitive and would otherwise slip through after toLowerCase().
+    if (containsForbiddenPattern(trimmed))
+        return "invalid";
+    const normalized = trimmed.toLowerCase();
+    if (!VALID_PACKAGE_NAME_RE.test(normalized))
+        return "invalid";
+    return normalized;
+}
+/**
+ * Metric-destination bucket for the package name. Low-cardinality and
+ * agnostic of the specific name — dashboards split installs by registry
+ * source without ever seeing customer-internal package names.
+ *
+ *   - public_npm registry + valid name → `public`
+ *   - private registry   + valid name  → `private`
+ *   - unknown registry   + valid name  → `unknown`
+ *   - name fails npm spec OR matches a known-secret value pattern → `invalid`
+ *   - name is null/empty                                          → `unknown`
+ *
+ * The registry bucket is taken as input rather than recomputed so callers
+ * never accidentally bucket a name without also bucketing its registry.
+ */
+export const NPM_PACKAGE_NAME_BUCKETS = [
+    "public",
+    "private",
+    "unknown",
+    "invalid",
+];
+export function bucketNpmPackageName(input, registryBucket) {
+    if (input == null)
+        return "unknown";
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return "unknown";
+    if (trimmed.length > NPM_PACKAGE_NAME_MAX_LENGTH)
+        return "invalid";
+    if (containsForbiddenPattern(trimmed))
+        return "invalid";
+    if (!VALID_PACKAGE_NAME_RE.test(trimmed.toLowerCase()))
+        return "invalid";
+    switch (registryBucket) {
+        case "public_npm":
+            return "public";
+        case "private":
+            return "private";
+        case "unknown":
+            return "unknown";
+    }
+}
+/**
+ * Closed outcome enum. First five values match the structured error from
+ * APPS-4179 (P1.2) and APPS-4195 (P1.5); `tls_failed` was added in
+ * APPS-4381 to give TLS handshake failures their own dashboard facet
+ * (previously routed to `other` and lost the actionable CA-bundle signal);
+ * `other` is the catch-all so dashboards never see free-form strings.
+ */
+export const NPM_OUTCOMES = [
+    "success",
+    "not_in_registry",
+    "registry_unreachable",
+    "registry_auth_failed",
+    "tls_failed",
+    "lockfile_url_mismatch",
+    "package_substituted",
+    "vulnerable_package",
+    "vulnerability_triaged",
+    "vulnerability_user_override",
+    "other",
+];
+const NPM_OUTCOME_SET = new Set(NPM_OUTCOMES);
+/** Coerce an outcome to the closed enum at the emit boundary. */
+export function normalizeNpmOutcome(input) {
+    if (typeof input !== "string")
+        return "other";
+    return NPM_OUTCOME_SET.has(input) ? input : "other";
+}
+/**
+ * Metric-safe attributes. Emitters of OTel metrics, Datadog metric tags,
+ * Tempo span attributes that flow to shared metric destinations, etc.
+ * MUST use this wrapper. The output never contains a raw package name.
+ */
+export function npmAttributesForMetric(input) {
+    const registry_host = bucketNpmRegistryHost(input.registry_host);
+    return {
+        registry_host,
+        package_name_bucket: bucketNpmPackageName(input.package_name, registry_host),
+        outcome: normalizeNpmOutcome(input.outcome),
+    };
+}
+/**
+ * Audit/log-safe attributes. Emitters of audit events and internal logs
+ * that retain per-org context (and that operators rely on for forensic
+ * value, e.g. "which package failed for org X?") use this wrapper. The
+ * verbatim name is gated by the known-secret value pattern set.
+ */
+export function npmAttributesForAudit(input) {
+    return {
+        registry_host: bucketNpmRegistryHost(input.registry_host),
+        package_name: sanitizeNpmPackageName(input.package_name),
+        outcome: normalizeNpmOutcome(input.outcome),
+    };
+}
+/**
+ * Redact registry URLs and bare hostnames from a free-text npm/pnpm error
+ * blob before it lands in a shared operational log line (auto-upgrade
+ * `[npm-install-blocked]` and any future caller). The destination is shared
+ * across orgs, so even an incidental hostname in the npm-emitted phrasing —
+ * `"401 Unauthorized - GET https://customer.jfrog.io/..."`,
+ * `"request to https://npm.private/... failed, reason: ENOTFOUND npm.private"`,
+ * `"connect ECONNREFUSED 10.0.0.5:4873"` — is a customer-infra leak that
+ * `bucketNpmRegistryHost` already prevents for the structured `registry_host`
+ * facet. This helper extends the same rule to free-text fields:
+ *
+ *   - Every `http(s)://...` URL is replaced with its registry bucket token
+ *     (`<public_npm>` or `<private>`), preserving the diagnostic shape of
+ *     the line while erasing the host.
+ *   - Bare `ENOTFOUND <host>` / `EAI_AGAIN <host>` payloads — npm emits the
+ *     host as the next whitespace-delimited token after these DNS error
+ *     codes — get the host replaced with `<host>`.
+ *   - `connect E* <ip>[:port]` payloads (ECONNREFUSED, ETIMEDOUT, …) — the
+ *     IP literal carries the same private-infra signal as a hostname — get
+ *     the address replaced with `<host>`.
+ *
+ * The replacement is intentionally lossy: the npm phrasing ("Unauthorized",
+ * "self-signed certificate in chain", "ENOTFOUND") is what operators need
+ * for triage; the host identity is what we must drop.
+ */
+export function redactNpmRegistryHostsFromText(input) {
+    if (input === "")
+        return input;
+    // URLs first. The match is greedy on non-whitespace/closing-paren chars to
+    // capture query strings and paths along with the host so the whole URL is
+    // replaced as a unit (a trailing `/path?token=...` containing a leaked
+    // host substring would otherwise survive a host-only replacement).
+    let out = input.replace(/https?:\/\/[^\s)]+/gi, (match) => {
+        const bucket = bucketNpmRegistryHost(match);
+        return bucket === "public_npm" ? "<public_npm>" : "<private>";
+    });
+    // DNS error codes name the host on the same line. Match the code as a
+    // word boundary so substrings inside other tokens don't trigger. The
+    // captured host token is whatever sits between the code and the next
+    // whitespace / punctuation that npm uses as a separator.
+    out = out.replace(/\b(ENOTFOUND|EAI_AGAIN)\s+([^\s,;:'")\]]+)/gi, (_m, code) => `${code} <host>`);
+    // `connect E<CODE> <ip>[:port]` — npm phrasing for low-level socket
+    // errors. The IP literal is the host facet to redact; the port is dropped
+    // alongside because port + private-IP together is the same infra signal.
+    out = out.replace(/\bconnect\s+(E[A-Z]+)\s+([0-9a-fA-F.:]+)(?::\d+)?/g, (_m, code) => `connect ${code} <host>`);
+    return out;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist-esm/npm-registry/sanitize.js.map

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

package/dist-esm/npm-registry/spans.d.ts

@@ -0,0 +1,61 @@
+/**
+ * NPM Registry Spans (APPS-4378)
+ *
+ * OTel-native `startActiveSpan` helpers for the four named npm-registry spans.
+ * Using the global tracer (`trace.getTracer`) means LLMObs interop is
+ * automatic: a span started inside an `@llmobs.decorate`'d context becomes a
+ * child of that task span (shared global tracer provider); outside any LLMObs
+ * context (server verify, CLI bootstrap) it is a root span.
+ *
+ * `org_id` rides on spans (per-trace context), never on a metric label. Raw
+ * registry hostnames are bucketed via {@link bucketNpmRegistryHost} before
+ * they reach a span attribute, matching the metric path — the one exception
+ * is the structured-log path, which keeps the raw host (see
+ * {@link auditNpmRegistryHost} in ./sanitize).
+ */
+import { type Attributes, type Span } from "@opentelemetry/api";
+/** The four named spans (APPS-4378). */
+export declare const NPM_REGISTRY_SPAN: {
+    readonly VERIFY: "npm_registry.verify";
+    readonly LOOKUP_PACKAGE: "npm_registry.lookup_package";
+    readonly PREPARE_FOR_PRIVATE_REGISTRY: "npm_registry.prepare_for_private_registry";
+    readonly SYNC_HOME_NPMRC: "npm_registry.sync_home_npmrc";
+};
+/**
+ * Canonical span-attribute keys, shared across the four spans so the
+ * dimension names never drift between call sites.
+ */
+export declare const NPM_REGISTRY_SPAN_ATTR: {
+    readonly ORG_ID: "org_id";
+    /** Bucketed (`public_npm | private | unknown`) — never the raw host. */
+    readonly REGISTRY_HOST: "registry_host";
+    readonly OUTCOME: "outcome";
+    readonly DURATION_MS: "duration_ms";
+    /** Richer `NpmRegistryFetchResult.source` for drill-down. */
+    readonly SOURCE: "source";
+    readonly REGISTRY_CONFIGURED: "registry_configured";
+    /** Tri-valued: `true | false | "unknown"`. */
+    readonly ALLOW_INSTALL_SCRIPTS: "allow_install_scripts";
+    readonly PACKAGE_NAME_BUCKET: "package_name_bucket";
+    /** Span-attribute ONLY — raw byte counts are unbounded, never a metric label. */
+    readonly PACKAGE_UNPACKED_SIZE_BYTES: "package_unpacked_size_bytes";
+};
+/**
+ * Start an active npm-registry span over the global tracer, run `fn`, and
+ * end the span in `finally`. On throw, the error is recorded
+ * (`span.recordException`) and the span status set to ERROR before the throw
+ * propagates. `fn` receives the span so it can attach final attributes
+ * (outcome / duration) once the operation resolves.
+ */
+export declare function withNpmRegistrySpan<T>(spanName: string, initialAttributes: Attributes, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Coerce a registry-reported `dist.unpackedSize` to a span-safe value: a
+ * finite, non-negative number, else `undefined`. A hostile or buggy registry
+ * cannot smuggle a non-numeric byte count onto the span through this guard.
+ *
+ * Callers MUST omit the attribute when this returns `undefined` rather than
+ * calling `setAttribute(key, undefined)` (some OTel exporters mishandle
+ * undefined values). The lookup call site guards with `if (size !== undefined)`.
+ */
+export declare function npmPackageUnpackedSizeBytes(raw: unknown): number | undefined;
+//# sourceMappingURL=spans.d.ts.map

package/dist-esm/npm-registry/spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../src/npm-registry/spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,IAAI,EAGV,MAAM,oBAAoB,CAAC;AAK5B,wCAAwC;AACxC,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;IAEjC,wEAAwE;;;;IAIxE,6DAA6D;;;IAG7D,8CAA8C;;;IAG9C,iFAAiF;;CAEzE,CAAC;AAEX;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,UAAU,EAC7B,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI5E"}