@amalgm/core 0.1.0

package/dist/transport/admission.d.ts

@@ -0,0 +1,235 @@
+/**
+ * App and preview admission — who gets routed to at all. Two distinct
+ * laws live side by side and must not be merged:
+ *
+ *  - isAppRoutable is the SERVING gate (may this request reach the
+ *    app right now), lenient by construction: unknown states default
+ *    to routable, because the reader may be looking at rows written
+ *    by an older engine.
+ *  - isAdvertisableApp is the ADVERTISING breaker (should the public
+ *    gateway be told this route exists), strict by construction: it
+ *    assumes normalized rows and refuses 'degraded' and
+ *    'unresponsive' — routing traffic to a zombie is worse than
+ *    routing none.
+ *
+ * Everything here is pure over injected sets and records; reading
+ * apps.json, port-monitor state, and env is the host's (axiom 6).
+ */
+import type { HeadersLike } from './auth.js';
+/**
+ * THE app-ref shape: 8-24 lowercase alphanumerics. The engine spells
+ * this regex in three places — local-gateway.js:198, :657 (inside the
+ * app URL matcher), tunnel-events.js:240 — one constant here.
+ * App refs become DNS labels (`<ref>.<domain>`), hence the charset.
+ */
+export declare const APP_REF_PATTERN: RegExp;
+/** An apps.json row as any engine version may have written it. */
+export interface AppRecordLike {
+    readonly appRef?: unknown;
+    readonly app_ref?: unknown;
+    readonly artifactRef?: unknown;
+    readonly artifact_ref?: unknown;
+    readonly port?: unknown;
+    readonly name?: unknown;
+    readonly status?: unknown;
+    readonly desiredState?: unknown;
+    readonly dnsConnected?: unknown;
+    readonly connected?: unknown;
+}
+/**
+ * The alias chain — local-gateway.js:188-190: appRef → app_ref →
+ * artifactRef → artifact_ref, first truthy wins, stringified and
+ * trimmed. The artifact* names are the pre-rename era and are LIVE
+ * WIRE CONTRACT (old rows on disk, old peers over the wire), not
+ * dead code; they are deprecated for writers, mandatory for readers
+ * (axiom 7: missing fields mean "the other end is older").
+ */
+export declare function normalizeAppRef(app: AppRecordLike | null | undefined): string;
+/**
+ * The liveness triad + the serving gate — local-gateway.js:192-206,
+ * the same clauses tunnel-events.js:228-244 applies as filter + map.
+ * Each triad clause fails OPEN for absent fields:
+ *  - connected: dnsConnected !== false && connected !== false — only
+ *    an explicit false disconnects (connected is the legacy spelling);
+ *  - desiredRunning: (desiredState || 'running') === 'running' — no
+ *    recorded desire means running;
+ *  - active: status !== 'stopped' && status !== 'error' — any other
+ *    status, including undefined and 'degraded', still serves.
+ */
+export declare function isAppRoutable(app: AppRecordLike | null | undefined): boolean;
+/** A normalized apps.json row (post store normalizeApp) — what the advertising breaker reads. */
+export interface AdvertisableAppLike {
+    readonly appRef?: string | null;
+    readonly dnsConnected?: boolean;
+    readonly desiredState?: string;
+    readonly status?: string;
+    readonly port?: number | null;
+    readonly name?: string;
+}
+/**
+ * The route-advertisement breaker — the 8-clause predicate of
+ * getConnectedRoutes (amalgm-mcp/apps/store.js:159-178). Strict where
+ * isAppRoutable is lenient, because it runs over rows the store just
+ * normalized (dnsConnected always boolean, desiredState always set):
+ *  1. dnsConnected truthy — absent means NOT advertised here;
+ *  2. desiredState strictly 'running' — no default;
+ *  3. status not 'stopped';
+ *  4. status not 'error';
+ *  5. status not 'degraded';
+ *  6. status not 'unresponsive' — declared a heartbeat and stopped
+ *     sending it: alive but hung; routing traffic to a zombie is
+ *     worse than routing none;
+ *  7. port truthy;
+ *  8. appRef truthy.
+ */
+export declare function isAdvertisableApp(app: AdvertisableAppLike): boolean;
+/** The advertised shape — store.js:173-177: snake_case app_ref, raw port and name. */
+export interface AppRoute {
+    readonly app_ref: string;
+    readonly port: number;
+    readonly name: string | undefined;
+}
+/** getConnectedRoutes minus the loadApps read: rows in, advertised routes out. */
+export declare function connectedRoutesFrom(apps: readonly AdvertisableAppLike[]): AppRoute[];
+/** The pre-rename projection — apps/advertise.js:76-80 (same shape in tunnel-events.js:247-253): sent when the gateway 404s the app-routes endpoint. */
+export declare function legacyArtifactRoutes(routes: readonly AppRoute[]): Array<{
+    artifact_ref: string;
+    port: number;
+    name: string | undefined;
+}>;
+/** The ports the runtime itself listens on, as the host resolved them. */
+export interface InternalRuntimePorts {
+    /** parseOptionalPort(env.AMALGM_LOCAL_APP_PORT) — null when unset. */
+    readonly localAgentAppPort: number | null;
+    /** The gateway/portMonitor/mcp/chat listen ports (SERVICE_PORTS values). */
+    readonly servicePorts: Iterable<number>;
+}
+/**
+ * local-gateway.js:218-223 — a preview may never target the runtime's
+ * own ports: proxying a browser at the gateway back into the gateway
+ * (or into mcp) would launder the preview path into an auth bypass.
+ */
+export declare function isInternalRuntimePort(port: number, internal: InternalRuntimePorts): boolean;
+export interface PreviewAdmission {
+    readonly internal: InternalRuntimePorts;
+    /** Ports of currently routable apps — activeAppPorts() at local-gateway.js:214-216. */
+    readonly activeAppPorts: ReadonlySet<number>;
+    /** Ports the port monitor observed listening — the gateway's polled cache. */
+    readonly monitoredPreviewPorts: ReadonlySet<number>;
+}
+/**
+ * local-gateway.js:225-233 — a preview port must be a valid port,
+ * not internal, and POSITIVELY known: either an active app's port or
+ * one the port monitor saw listening. Unknown ports are denied, not
+ * probed — the preview path is reachable from outside the machine.
+ */
+export declare function isAllowedPreviewPort(port: number, admission: PreviewAdmission): boolean;
+/** The external proxy URL matchers — local-gateway.js:657 and :671, byte-exact ('artifacts' is the legacy spelling, still served). */
+export declare const APP_PROXY_PATH_PATTERN: RegExp;
+export declare const PREVIEW_PROXY_PATH_PATTERN: RegExp;
+/** What the proxy decision needs from the world; the host wires apps.json and the monitor cache in. */
+export interface ExternalProxyPorts {
+    /** findAppByRef reduced to its answer: the routable app's port, or null. */
+    appPortForRef(appRef: string): number | null;
+    isAllowedPreviewPort(port: number): boolean;
+}
+export type ExternalProxyTarget = {
+    readonly port: number;
+    readonly prefix: string;
+    readonly kind: 'app' | 'preview';
+} | {
+    readonly error: {
+        readonly status: 403 | 404;
+        readonly message: string;
+    };
+} | null;
+/**
+ * externalProxyTargetForPath — local-gateway.js:656-685: app paths
+ * first (an unknown or unroutable ref is the byte-exact 404), then
+ * preview ports (a disallowed port is the byte-exact 403), else null
+ * (not an external proxy path at all). `prefix` is what the proxy
+ * strips before forwarding: the matched span without its trailing
+ * slash.
+ */
+export declare function externalProxyTargetForPath(pathname: string, ports: ExternalProxyPorts): ExternalProxyTarget;
+/** apps/store.js:31-33 — an app's public address is its ref as a DNS label under the apps domain, trailing slash included. */
+export declare function publicUrlForRef(appRef: string, domain: string): string;
+/** The ref alphabet — apps/store.js:36. 36 symbols; see genAppRef for the modulo law. */
+export declare const APP_REF_CHARSET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * The ref-generation law — apps/store.js:35-43: 12 characters, each
+ * `byte % 36` into the charset. The modulo bias (256 % 36 !== 0) is
+ * part of the shipped law and is preserved, not fixed: refs generated
+ * here must be indistinguishable from engine-generated ones.
+ * Randomness is a host effect; the port must yield at least 12 bytes
+ * (node's crypto.randomBytes always does — a short read is a broken
+ * adapter, and throwing beats emitting a low-entropy ref).
+ */
+export declare function genAppRef(randomBytes: (size: number) => Uint8Array): string;
+/**
+ * The engine's default allocation window — config.js:102-103
+ * (AMALGM_APP_PORT_MIN/MAX, defaults 9100..9199). Injected
+ * configuration; exported so hosts without an opinion inherit the
+ * shipped one.
+ */
+export declare const DEFAULT_APP_PORT_RANGE: {
+    readonly min: 9100;
+    readonly max: 9199;
+};
+export interface AllocatePortOptions {
+    /** Ports already claimed by apps — Number(app.port) over the store. */
+    readonly usedPorts: ReadonlySet<number>;
+    readonly range: {
+        readonly min: number;
+        readonly max: number;
+    };
+}
+/**
+ * The allocation law — apps/store.js:135-147: an explicitly
+ * preferred port is honored if it is a valid port AT ALL — even one
+ * already in use (the caller asked; collision is their bug to see) —
+ * and null if invalid, never "fall through to scanning". Only when no
+ * preference is given does the scan hand out the first free port in
+ * the range, or null when the range is exhausted.
+ */
+export declare function allocatePort(preferredPort: unknown, options: AllocatePortOptions): number | null;
+/**
+ * RFC 7230's connection-scoped headers plus host and content-length —
+ * tunnel-events.js:90-102 (same 11-entry list in tunnel-chat.js:65-77
+ * and local-gateway.js:108-120). Stripped from every proxied request:
+ * they describe THIS hop, and the proxy re-derives its own.
+ */
+export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
+/**
+ * The 8 headers the WebSocket handshake owns — tunnel-events.js:103-112
+ * (same list in local-gateway.js:122-131). Forwarding a client's
+ * Sec-WebSocket-Key to an upstream socket the proxy is opening itself
+ * corrupts the upstream handshake; the ws library mints fresh ones.
+ */
+export declare const WS_HANDSHAKE_HEADERS: ReadonlySet<string>;
+/**
+ * The one strip-and-flatten helper behind the engine's normalizeHeaders /
+ * normalizeWsHeaders family (tunnel-events.js:163-173, local-gateway.js:
+ * 570-580 and :593-603): drop every header whose lowercased name is in
+ * `drop` (original casing otherwise preserved), join repeated values
+ * with ', ', stringify stray numbers, and silently drop nulls. Callers
+ * pass HOP_BY_HOP_HEADERS, or its union with WS_HANDSHAKE_HEADERS for
+ * upgrade legs.
+ */
+export declare function stripHeaders(headers: HeadersLike | null | undefined, drop: ReadonlySet<string>): Record<string, string>;
+/**
+ * The log-redaction laws — local-gateway.js:450-459, the four
+ * replaces verbatim and IN ORDER (the order is load-bearing: the
+ * authorization-line rule must consume its Bearer token before the
+ * bare-Bearer rule sees it):
+ *  1. `authorization: <anything token-shaped>` → keep the label,
+ *     redact the value;
+ *  2. bare `Bearer <20+ chars>` anywhere → 'Bearer [REDACTED]';
+ *  3. known token prefixes (sk|pk|rk|ghp|github_pat|glpat|xox[baprs]
+ *     + separator + 16+ token chars) → '[REDACTED_TOKEN]';
+ *  4. `api_key/token/secret/password/cookie`-labeled assignments →
+ *     keep the label, redact the value.
+ * Applied to diagnostic log tails before they leave the machine.
+ */
+export declare function redactSecrets(text: string): string;
+//# sourceMappingURL=admission.d.ts.map

package/dist/transport/admission.d.ts.map

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

package/dist/transport/admission.js

@@ -0,0 +1,313 @@
+/**
+ * App and preview admission — who gets routed to at all. Two distinct
+ * laws live side by side and must not be merged:
+ *
+ *  - isAppRoutable is the SERVING gate (may this request reach the
+ *    app right now), lenient by construction: unknown states default
+ *    to routable, because the reader may be looking at rows written
+ *    by an older engine.
+ *  - isAdvertisableApp is the ADVERTISING breaker (should the public
+ *    gateway be told this route exists), strict by construction: it
+ *    assumes normalized rows and refuses 'degraded' and
+ *    'unresponsive' — routing traffic to a zombie is worse than
+ *    routing none.
+ *
+ * Everything here is pure over injected sets and records; reading
+ * apps.json, port-monitor state, and env is the host's (axiom 6).
+ */
+import { appNotRoutableError, previewPortDeniedError } from './routing.js';
+/**
+ * THE app-ref shape: 8-24 lowercase alphanumerics. The engine spells
+ * this regex in three places — local-gateway.js:198, :657 (inside the
+ * app URL matcher), tunnel-events.js:240 — one constant here.
+ * App refs become DNS labels (`<ref>.<domain>`), hence the charset.
+ */
+export const APP_REF_PATTERN = /^[a-z0-9]{8,24}$/;
+/**
+ * The alias chain — local-gateway.js:188-190: appRef → app_ref →
+ * artifactRef → artifact_ref, first truthy wins, stringified and
+ * trimmed. The artifact* names are the pre-rename era and are LIVE
+ * WIRE CONTRACT (old rows on disk, old peers over the wire), not
+ * dead code; they are deprecated for writers, mandatory for readers
+ * (axiom 7: missing fields mean "the other end is older").
+ */
+export function normalizeAppRef(app) {
+    return String(app?.appRef || app?.app_ref || app?.artifactRef || app?.artifact_ref || '').trim();
+}
+/**
+ * The liveness triad + the serving gate — local-gateway.js:192-206,
+ * the same clauses tunnel-events.js:228-244 applies as filter + map.
+ * Each triad clause fails OPEN for absent fields:
+ *  - connected: dnsConnected !== false && connected !== false — only
+ *    an explicit false disconnects (connected is the legacy spelling);
+ *  - desiredRunning: (desiredState || 'running') === 'running' — no
+ *    recorded desire means running;
+ *  - active: status !== 'stopped' && status !== 'error' — any other
+ *    status, including undefined and 'degraded', still serves.
+ */
+export function isAppRoutable(app) {
+    const port = Number(app?.port);
+    const connected = app?.dnsConnected !== false && app?.connected !== false;
+    const desiredRunning = (app?.desiredState || 'running') === 'running';
+    const active = app?.status !== 'stopped' && app?.status !== 'error';
+    return (APP_REF_PATTERN.test(normalizeAppRef(app))
+        && Number.isInteger(port)
+        && port > 0
+        && port <= 65535
+        && connected
+        && desiredRunning
+        && active);
+}
+/**
+ * The route-advertisement breaker — the 8-clause predicate of
+ * getConnectedRoutes (amalgm-mcp/apps/store.js:159-178). Strict where
+ * isAppRoutable is lenient, because it runs over rows the store just
+ * normalized (dnsConnected always boolean, desiredState always set):
+ *  1. dnsConnected truthy — absent means NOT advertised here;
+ *  2. desiredState strictly 'running' — no default;
+ *  3. status not 'stopped';
+ *  4. status not 'error';
+ *  5. status not 'degraded';
+ *  6. status not 'unresponsive' — declared a heartbeat and stopped
+ *     sending it: alive but hung; routing traffic to a zombie is
+ *     worse than routing none;
+ *  7. port truthy;
+ *  8. appRef truthy.
+ */
+export function isAdvertisableApp(app) {
+    return Boolean(app.dnsConnected
+        && app.desiredState === 'running'
+        && app.status !== 'stopped'
+        && app.status !== 'error'
+        && app.status !== 'degraded'
+        && app.status !== 'unresponsive'
+        && app.port
+        && app.appRef);
+}
+/** getConnectedRoutes minus the loadApps read: rows in, advertised routes out. */
+export function connectedRoutesFrom(apps) {
+    const routes = [];
+    for (const app of apps) {
+        const { appRef, port } = app;
+        if (appRef == null || port == null || !isAdvertisableApp(app))
+            continue;
+        routes.push({ app_ref: appRef, port, name: app.name });
+    }
+    return routes;
+}
+/** The pre-rename projection — apps/advertise.js:76-80 (same shape in tunnel-events.js:247-253): sent when the gateway 404s the app-routes endpoint. */
+export function legacyArtifactRoutes(routes) {
+    return routes.map((route) => ({
+        artifact_ref: route.app_ref,
+        port: route.port,
+        name: route.name,
+    }));
+}
+/**
+ * local-gateway.js:218-223 — a preview may never target the runtime's
+ * own ports: proxying a browser at the gateway back into the gateway
+ * (or into mcp) would launder the preview path into an auth bypass.
+ */
+export function isInternalRuntimePort(port, internal) {
+    if (internal.localAgentAppPort !== null && port === internal.localAgentAppPort)
+        return true;
+    for (const value of internal.servicePorts) {
+        if (Number(value) === port)
+            return true;
+    }
+    return false;
+}
+/**
+ * local-gateway.js:225-233 — a preview port must be a valid port,
+ * not internal, and POSITIVELY known: either an active app's port or
+ * one the port monitor saw listening. Unknown ports are denied, not
+ * probed — the preview path is reachable from outside the machine.
+ */
+export function isAllowedPreviewPort(port, admission) {
+    return (Number.isInteger(port)
+        && port > 0
+        && port <= 65535
+        && !isInternalRuntimePort(port, admission.internal)
+        && (admission.activeAppPorts.has(port) || admission.monitoredPreviewPorts.has(port)));
+}
+/** The external proxy URL matchers — local-gateway.js:657 and :671, byte-exact ('artifacts' is the legacy spelling, still served). */
+export const APP_PROXY_PATH_PATTERN = /^\/__amalgm\/(?:apps|artifacts)\/([a-z0-9]{8,24})(?:\/|$)/;
+export const PREVIEW_PROXY_PATH_PATTERN = /^\/__amalgm\/preview\/(\d{1,5})(?:\/|$)/;
+/**
+ * externalProxyTargetForPath — local-gateway.js:656-685: app paths
+ * first (an unknown or unroutable ref is the byte-exact 404), then
+ * preview ports (a disallowed port is the byte-exact 403), else null
+ * (not an external proxy path at all). `prefix` is what the proxy
+ * strips before forwarding: the matched span without its trailing
+ * slash.
+ */
+export function externalProxyTargetForPath(pathname, ports) {
+    const appMatch = pathname.match(APP_PROXY_PATH_PATTERN);
+    if (appMatch) {
+        const appRef = appMatch[1] ?? '';
+        const matched = appMatch[0] ?? '';
+        const port = ports.appPortForRef(appRef);
+        if (port === null) {
+            return { error: appNotRoutableError(appRef) };
+        }
+        return {
+            port,
+            prefix: matched.endsWith('/') ? matched.slice(0, -1) : matched,
+            kind: 'app',
+        };
+    }
+    const previewMatch = pathname.match(PREVIEW_PROXY_PATH_PATTERN);
+    if (previewMatch) {
+        const port = Number(previewMatch[1]);
+        if (!ports.isAllowedPreviewPort(port)) {
+            return { error: previewPortDeniedError(port) };
+        }
+        return {
+            port,
+            prefix: `/__amalgm/preview/${port}`,
+            kind: 'preview',
+        };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// App identity and port allocation
+// ---------------------------------------------------------------------------
+/** apps/store.js:31-33 — an app's public address is its ref as a DNS label under the apps domain, trailing slash included. */
+export function publicUrlForRef(appRef, domain) {
+    return `https://${appRef}.${domain}/`;
+}
+/** The ref alphabet — apps/store.js:36. 36 symbols; see genAppRef for the modulo law. */
+export const APP_REF_CHARSET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+/**
+ * The ref-generation law — apps/store.js:35-43: 12 characters, each
+ * `byte % 36` into the charset. The modulo bias (256 % 36 !== 0) is
+ * part of the shipped law and is preserved, not fixed: refs generated
+ * here must be indistinguishable from engine-generated ones.
+ * Randomness is a host effect; the port must yield at least 12 bytes
+ * (node's crypto.randomBytes always does — a short read is a broken
+ * adapter, and throwing beats emitting a low-entropy ref).
+ */
+export function genAppRef(randomBytes) {
+    const bytes = randomBytes(12);
+    let out = '';
+    for (let i = 0; i < 12; i += 1) {
+        const byte = bytes[i];
+        if (byte === undefined)
+            throw new Error('randomBytes port returned fewer than 12 bytes');
+        out += APP_REF_CHARSET.charAt(byte % APP_REF_CHARSET.length);
+    }
+    return out;
+}
+/**
+ * The engine's default allocation window — config.js:102-103
+ * (AMALGM_APP_PORT_MIN/MAX, defaults 9100..9199). Injected
+ * configuration; exported so hosts without an opinion inherit the
+ * shipped one.
+ */
+export const DEFAULT_APP_PORT_RANGE = { min: 9100, max: 9199 };
+/**
+ * The allocation law — apps/store.js:135-147: an explicitly
+ * preferred port is honored if it is a valid port AT ALL — even one
+ * already in use (the caller asked; collision is their bug to see) —
+ * and null if invalid, never "fall through to scanning". Only when no
+ * preference is given does the scan hand out the first free port in
+ * the range, or null when the range is exhausted.
+ */
+export function allocatePort(preferredPort, options) {
+    if (preferredPort !== undefined && preferredPort !== null) {
+        const parsed = Number(preferredPort);
+        if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535)
+            return parsed;
+        return null;
+    }
+    for (let port = options.range.min; port <= options.range.max; port += 1) {
+        if (!options.usedPorts.has(port))
+            return port;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Header hygiene
+// ---------------------------------------------------------------------------
+/**
+ * RFC 7230's connection-scoped headers plus host and content-length —
+ * tunnel-events.js:90-102 (same 11-entry list in tunnel-chat.js:65-77
+ * and local-gateway.js:108-120). Stripped from every proxied request:
+ * they describe THIS hop, and the proxy re-derives its own.
+ */
+export const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'trailers',
+    'transfer-encoding',
+    'upgrade',
+    'host',
+    'content-length',
+]);
+/**
+ * The 8 headers the WebSocket handshake owns — tunnel-events.js:103-112
+ * (same list in local-gateway.js:122-131). Forwarding a client's
+ * Sec-WebSocket-Key to an upstream socket the proxy is opening itself
+ * corrupts the upstream handshake; the ws library mints fresh ones.
+ */
+export const WS_HANDSHAKE_HEADERS = new Set([
+    'connection',
+    'upgrade',
+    'host',
+    'sec-websocket-key',
+    'sec-websocket-version',
+    'sec-websocket-extensions',
+    'sec-websocket-accept',
+    'sec-websocket-protocol',
+]);
+/**
+ * The one strip-and-flatten helper behind the engine's normalizeHeaders /
+ * normalizeWsHeaders family (tunnel-events.js:163-173, local-gateway.js:
+ * 570-580 and :593-603): drop every header whose lowercased name is in
+ * `drop` (original casing otherwise preserved), join repeated values
+ * with ', ', stringify stray numbers, and silently drop nulls. Callers
+ * pass HOP_BY_HOP_HEADERS, or its union with WS_HANDSHAKE_HEADERS for
+ * upgrade legs.
+ */
+export function stripHeaders(headers, drop) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers || {})) {
+        const lower = key.toLowerCase();
+        if (drop.has(lower))
+            continue;
+        if (Array.isArray(value))
+            out[key] = value.join(', ');
+        else if (typeof value === 'string')
+            out[key] = value;
+        else if (value != null)
+            out[key] = String(value);
+    }
+    return out;
+}
+/**
+ * The log-redaction laws — local-gateway.js:450-459, the four
+ * replaces verbatim and IN ORDER (the order is load-bearing: the
+ * authorization-line rule must consume its Bearer token before the
+ * bare-Bearer rule sees it):
+ *  1. `authorization: <anything token-shaped>` → keep the label,
+ *     redact the value;
+ *  2. bare `Bearer <20+ chars>` anywhere → 'Bearer [REDACTED]';
+ *  3. known token prefixes (sk|pk|rk|ghp|github_pat|glpat|xox[baprs]
+ *     + separator + 16+ token chars) → '[REDACTED_TOKEN]';
+ *  4. `api_key/token/secret/password/cookie`-labeled assignments →
+ *     keep the label, redact the value.
+ * Applied to diagnostic log tails before they leave the machine.
+ */
+export function redactSecrets(text) {
+    return String(text)
+        .replace(/(authorization\s*[:=]\s*)(?:Bearer\s+)?[A-Za-z0-9._~+/=-]{8,}/gi, '$1[REDACTED]')
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{20,}\b/gi, 'Bearer [REDACTED]')
+        .replace(/\b(?:sk|pk|rk|ghp|github_pat|glpat|xox[baprs])[-_][A-Za-z0-9_./+=-]{16,}\b/g, '[REDACTED_TOKEN]')
+        .replace(/((?:api[_-]?key|apikey|token|secret|password|cookie|set-cookie)[^:=\n]{0,32}[:=]\s*["']?)[^\s"',;}]+/gi, '$1[REDACTED]');
+}
+//# sourceMappingURL=admission.js.map

package/dist/transport/admission.js.map

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