@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/handles.ts

@@ -0,0 +1,212 @@
+/**
+ * CES credential handle formats and parser helpers.
+ *
+ * A "handle" is an opaque string that the assistant passes to CES to identify
+ * which credential context should be used for a given execution. Handles never
+ * contain secret material — they are references that CES resolves internally.
+ *
+ * v1 handle formats:
+ *
+ * 1. **Local static** — references a credential stored in the local secure-key
+ *    backend. Format: `local_static:<service>/<field>` (matches the
+ *    `credential/{service}/{field}` key pattern from credential-storage).
+ *
+ * 2. **Local OAuth** — references a locally persisted OAuth connection.
+ *    Format: `local_oauth:<providerKey>/<connectionId>` where providerKey
+ *    is the bare provider name (e.g. `google`).
+ *
+ * 3. **Managed OAuth** — references an OAuth connection managed by the
+ *    platform. Format: `platform_oauth:<connectionId>` where connectionId
+ *    is the platform-assigned connection identifier.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Handle type discriminator
+// ---------------------------------------------------------------------------
+
+export const HandleType = {
+  LocalStatic: "local_static",
+  LocalOAuth: "local_oauth",
+  PlatformOAuth: "platform_oauth",
+} as const;
+
+export type HandleType = (typeof HandleType)[keyof typeof HandleType];
+
+// ---------------------------------------------------------------------------
+// Parsed handle shapes
+// ---------------------------------------------------------------------------
+
+export interface LocalStaticHandle {
+  type: typeof HandleType.LocalStatic;
+  /** Service name (e.g. "github", "fal"). */
+  service: string;
+  /** Field name within the service (e.g. "api_key", "password"). */
+  field: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface LocalOAuthHandle {
+  type: typeof HandleType.LocalOAuth;
+  /** Provider key (e.g. "google", "slack"). */
+  providerKey: string;
+  /** Connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface PlatformOAuthHandle {
+  type: typeof HandleType.PlatformOAuth;
+  /** Platform-assigned connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export type ParsedHandle =
+  | LocalStaticHandle
+  | LocalOAuthHandle
+  | PlatformOAuthHandle;
+
+// ---------------------------------------------------------------------------
+// Handle construction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a local static credential handle from service and field.
+ *
+ * Accepts the same service/field values used in `credentialKey()` from
+ * `@vellumai/credential-storage`.
+ */
+export function localStaticHandle(service: string, field: string): string {
+  return `${HandleType.LocalStatic}:${service}/${field}`;
+}
+
+/**
+ * Build a local OAuth credential handle from a provider key and connection ID.
+ */
+export function localOAuthHandle(
+  providerKey: string,
+  connectionId: string,
+): string {
+  return `${HandleType.LocalOAuth}:${providerKey}/${connectionId}`;
+}
+
+/**
+ * Build a managed (platform) OAuth credential handle from a connection ID.
+ */
+export function platformOAuthHandle(connectionId: string): string {
+  return `${HandleType.PlatformOAuth}:${connectionId}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handle parsing
+// ---------------------------------------------------------------------------
+
+export type ParseHandleResult =
+  | { ok: true; handle: ParsedHandle }
+  | { ok: false; error: string };
+
+/**
+ * Parse a raw handle string into a structured `ParsedHandle`.
+ *
+ * Returns a discriminated result so callers can inspect parse errors
+ * without catching exceptions.
+ */
+export function parseHandle(raw: string): ParseHandleResult {
+  const colonIdx = raw.indexOf(":");
+  if (colonIdx === -1) {
+    return { ok: false, error: `Invalid handle format: missing type prefix in "${raw}"` };
+  }
+
+  const prefix = raw.slice(0, colonIdx);
+  const rest = raw.slice(colonIdx + 1);
+
+  switch (prefix) {
+    case HandleType.LocalStatic: {
+      const slashIdx = rest.indexOf("/");
+      if (slashIdx === -1 || slashIdx === 0 || slashIdx === rest.length - 1) {
+        return {
+          ok: false,
+          error: `Invalid local_static handle: expected "local_static:<service>/<field>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalStatic,
+          service: rest.slice(0, slashIdx),
+          field: rest.slice(slashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.LocalOAuth: {
+      // Split providerKey from connectionId.
+      const slashIdx = rest.indexOf("/");
+      if (
+        slashIdx === -1 ||
+        slashIdx === 0 ||
+        slashIdx === rest.length - 1
+      ) {
+        return {
+          ok: false,
+          error: `Invalid local_oauth handle: expected "local_oauth:<providerKey>/<connectionId>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalOAuth,
+          providerKey: rest.slice(0, slashIdx),
+          connectionId: rest.slice(slashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.PlatformOAuth: {
+      if (!rest || rest.length === 0) {
+        return {
+          ok: false,
+          error: `Invalid platform_oauth handle: missing connectionId in "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.PlatformOAuth,
+          connectionId: rest,
+          raw,
+        },
+      };
+    }
+
+    default:
+      return {
+        ok: false,
+        error: `Unknown handle type prefix "${prefix}" in "${raw}"`,
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema for wire validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod schema that validates a string as a well-formed CES credential handle.
+ * Useful in RPC schemas where the handle travels on the wire.
+ */
+export const CredentialHandleSchema = z
+  .string()
+  .check(
+    z.refine((val: string) => {
+      const result = parseHandle(val);
+      return result.ok;
+    }, "Must be a valid CES credential handle (local_static:*, local_oauth:*, or platform_oauth:*)"),
+  );

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @vellumai/service-contracts — aggregate export (compat entry point)
+ *
+ * This is a compatibility aggregate that re-exports everything from all
+ * submodules. Prefer the explicit domain subpaths for new code:
+ *
+ *   - `@vellumai/service-contracts/credential-rpc`  — transport, RPC, handles, error
+ *   - `@vellumai/service-contracts/trust-rules`     — trust-rule types and parsing helpers
+ *   - `@vellumai/service-contracts/twilio-ingress`  — shared Twilio ingress config constants
+ *   - `@vellumai/service-contracts/ingress`         — shared public ingress URL helpers
+ *
+ * Fine-grained subpaths are also available for low-friction migration:
+ *   `./rpc`, `./handles`, `./error`, `./trust-rules`, `./ingress`, `./twilio-ingress`
+ *
+ * Neutral wire-protocol contracts for communication between the assistant
+ * daemon and the Credential Execution Service (CES). This package is
+ * intentionally free of imports from `assistant/` or any CES implementation
+ * module so that both sides can depend on it without circular references.
+ */
+
+export * from "./channels.js";
+export * from "./client-metadata.js";
+export * from "./conversation-handle.js";
+export * from "./transport.js";
+export * from "./error.js";
+export * from "./handles.js";
+export * from "./rpc.js";
+export * from "./trust-rules.js";
+export * from "./ingress.js";
+export * from "./remote-web-pairing.js";
+export * from "./twilio-ingress.js";
+export * from "./url-normalization.js";

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -0,0 +1,175 @@
+/**
+ * Map a Vellum platform host onto its environment's velay host, following the
+ * deployment naming convention (`platform.vellum.ai` → `velay.vellum.ai`,
+ * `{env}-platform.vellum.ai` → `velay-{env}.vellum.ai`). Returns null for
+ * hosts outside that convention (localhost, custom domains). Shared by the
+ * gateway speech relay and the web live-voice client so the two ends of the
+ * managed-speech transport can't drift.
+ */
+export function velayHostForPlatformHost(host: string): string | null {
+  if (host === "platform.vellum.ai") {
+    return "velay.vellum.ai";
+  }
+  const match = /^([a-z0-9-]+)-platform\.vellum\.ai$/.exec(host);
+  return match ? `velay-${match[1]}.vellum.ai` : null;
+}
+
+export function normalizePublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+/**
+ * Application close code the gateway's velay bridge sends to proxied
+ * WebSockets when the tunnel itself is lost (velay disconnect, gateway
+ * shutdown). A dedicated code because the natural 1001 (going away) cannot
+ * be sent through the JS `close()` API (the bridge would remap it to a
+ * misleading 4001), and Bun's WebSocket client drops close reasons, so the
+ * code is the only signal that survives the relay to the daemon.
+ */
+export const GATEWAY_TUNNEL_LOST_WS_CLOSE_CODE = 4801;
+
+export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  if (/[?#]/.test(trimmed)) return undefined;
+
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return undefined;
+    }
+    if (!url.hostname) return undefined;
+    url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The same validation as `normalizeHttpPublicBaseUrl`, minus the root path it
+ * always emits (`https://x` becomes `https://x/`). Callers that append a path
+ * or persist the result want this shape, so they neither join through a double
+ * slash nor re-strip what the normalizer just added.
+ */
+export function normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+  value: unknown,
+): string | undefined {
+  return normalizePublicBaseUrl(normalizeHttpPublicBaseUrl(value));
+}
+
+/**
+ * A trimmed string, or undefined when the value is not a non-blank string.
+ *
+ * Exported because the identity check in the daemon's tunnel probe compares an
+ * id recorded here against one an edge serves, and the two sides have to trim
+ * alike: a padded served id must read as a match, not as a different
+ * assistant.
+ */
+export function trimmedNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Records `vellum tunnel` leaves in the workspace config's `ingress` section.
+// The CLI writes them and the daemon reads them, and the two are separate
+// build units that cannot import each other, so the key names, the provider
+// allowlist, and the validation all live here rather than in a copy on each
+// side.
+
+/** Key under `ingress` holding the tunnel that most recently ran. */
+export const INGRESS_LAST_TUNNEL_KEY = "lastTunnel";
+
+/**
+ * Key under `ingress` holding a tunnel published for device pairing alone.
+ *
+ * A tailnet-only tunnel started while webhook integrations are configured
+ * cannot carry their callbacks, so it leaves `publicBaseUrl` (the callback
+ * base) as it is and records itself here. Readers that answer the pairing card
+ * prefer this address over `publicBaseUrl`; teardown drops the key.
+ */
+export const INGRESS_PAIRING_TUNNEL_KEY = "pairingTunnel";
+
+/** Key under `ingress` holding the assistant id that tunnel fronted. */
+export const INGRESS_ASSISTANT_ID_KEY = "assistantId";
+
+/**
+ * The local tunnel providers the CLI can start, in the order they are offered.
+ * `vellum tunnel`'s accepted `--provider` values and the persisted-record
+ * validation below both derive from it.
+ */
+export const TUNNEL_PROVIDERS = ["ngrok", "cloudflare", "tailscale"] as const;
+
+export type TunnelProviderName = (typeof TUNNEL_PROVIDERS)[number];
+
+/** A recorded tunnel, kept after teardown so UIs can name the command to restart. */
+export interface TunnelRecord {
+  provider: TunnelProviderName;
+  publicBaseUrl: string;
+}
+
+function isTunnelProviderName(value: unknown): value is TunnelProviderName {
+  return (
+    typeof value === "string" &&
+    (TUNNEL_PROVIDERS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Parse an `ingress.lastTunnel` or `ingress.pairingTunnel` value, or null when
+ * it is absent or malformed.
+ *
+ * A hand-edited config must not hand callers an unusable address or a provider
+ * name no command accepts: the provider is checked against the allowlist
+ * because readers render it into a restart command, and the URL faces the same
+ * absolute HTTP(S) constraint as every other public base URL. The URL comes
+ * back in the shape the validator produced, so readers never re-normalize it.
+ */
+export function parseTunnelRecord(value: unknown): TunnelRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { provider, publicBaseUrl } = value as Record<string, unknown>;
+  if (!isTunnelProviderName(provider)) {
+    return null;
+  }
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (normalized === undefined) {
+    return null;
+  }
+  return { provider, publicBaseUrl: normalized };
+}
+
+/**
+ * The tunnel a reader should offer to restart, given an `ingress` section, or
+ * null when it records none.
+ *
+ * A pairing-only record wins: it is written by a tunnel that deliberately left
+ * `publicBaseUrl` (and the `lastTunnel` beside it) pointing at an older public
+ * provider, so naming that older one would send the user to rebuild an ingress
+ * they are not using instead of the tunnel actually in front of them.
+ */
+export function selectRestartTunnelRecord(
+  ingress: unknown,
+): TunnelRecord | null {
+  if (typeof ingress !== "object" || ingress === null) {
+    return null;
+  }
+  const section = ingress as Record<string, unknown>;
+  return (
+    parseTunnelRecord(section[INGRESS_PAIRING_TUNNEL_KEY]) ??
+    parseTunnelRecord(section[INGRESS_LAST_TUNNEL_KEY])
+  );
+}
+
+/** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
+export function parseRecordedAssistantId(value: unknown): string | null {
+  return trimmedNonEmptyString(value) ?? null;
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/redacted-credential.ts

@@ -0,0 +1,226 @@
+/**
+ * Redacted-credential sentinel — the shared wire format for chat-persisted
+ * secret redactions.
+ *
+ * When the daemon persists a chat message containing a detected secret (and
+ * the `chat-credential-reveal` feature flag is on), the secret is replaced
+ * with a plain-text sentinel instead of the legacy `<redacted type="…" />`
+ * HTML marker. The sentinel is plain text on purpose: the chat markdown
+ * pipeline has no rehype-raw, so an HTML marker can never become an element —
+ * a text sentinel survives markdown parsing as an ordinary text node that a
+ * rehype plugin can match and upgrade into an interactive chip.
+ *
+ * Two shapes:
+ *   `〔redacted:TYPE〕`                — secret detected, vault identity unknown
+ *   `〔redacted:TYPE:SERVICE:FIELD〕`  — secret byte-matched to a stored credential
+ *
+ * The enriched shape is only emitted when the daemon has *proven* the match
+ * (exact plaintext comparison against a credential fetched for this turn) —
+ * never inferred. A wrong SERVICE:FIELD here would let the client reveal the
+ * wrong secret, so producers must treat enrichment as opt-in per proven match.
+ *
+ * The corner brackets (U+3014/U+3015) were chosen because they are not
+ * markdown syntax characters, never appear in the secret formats we detect,
+ * and are visually distinct if a client without chip support renders the raw
+ * sentinel.
+ *
+ * This module is shared by the daemon (producer) and clients/web (consumer)
+ * so the format can never drift between the two. It is intentionally
+ * dependency-free and data-only.
+ */
+
+export const REDACTED_SENTINEL_OPEN = "\u3014"; // 〔
+export const REDACTED_SENTINEL_CLOSE = "\u3015"; // 〕
+export const REDACTED_SENTINEL_TAG = "redacted";
+
+/**
+ * Version stamped as a `_redactionVersion` rider on daemon-persisted text
+ * blocks whose raw text passed through {@link neutralizeRedactedSentinels}
+ * before persistence. The daemon's history read boundary
+ * (`renderHistoryContent`) neutralizes text blocks WITHOUT this rider —
+ * rows persisted before the forgery guard existed — so a forged sentinel in
+ * old history can never reach a chip-enabled client surface. Internal to the
+ * daemon: the wire projection rebuilds blocks and never ships the rider.
+ */
+export const SENTINEL_REDACTION_VERSION = 2;
+
+/**
+ * Service/field segments are percent-encoded into the sentinel so arbitrary
+ * credential identifiers survive the colon-delimited format. The credential
+ * routes accept service/field as arbitrary strings — colon-qualified names
+ * exist in real vaults (migration `018-rekey-compound-credential-keys`
+ * produces `service = "integration:google"`), so a delimiter-collision
+ * charset restriction would silently downgrade proven reveals for those
+ * credentials to the non-revealable shape. Encoding keeps the common
+ * kebab/snake identifiers fully legible while making every other string
+ * representable.
+ *
+ * The encoded form contains only `[A-Za-z0-9_.%-]` — `encodeURIComponent`
+ * plus the characters it leaves bare that fall outside that set — so the
+ * sentinel regex stays unambiguous around its `:` delimiters and `〕` close.
+ */
+function encodeSentinelSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(
+    /[!'()*~]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * Inverse of {@link encodeSentinelSegment}. Returns undefined for malformed
+ * percent-escapes — daemon-encoded segments always decode, and forged
+ * sentinels are neutralized at persist time, so this path is defensive.
+ */
+function decodeSentinelSegment(segment: string): string | undefined {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Charset for the TYPE label. Pattern labels are our own
+ * (`secret-patterns.ts` / scanner-only patterns) and contain only words,
+ * spaces, and hyphens — but validate anyway so a future label containing a
+ * colon or bracket cannot silently corrupt the format.
+ */
+const TYPE_RE = /^[^:\u3014\u3015]+$/;
+
+export interface RedactedCredentialSentinel {
+  /** Human-readable secret type label, e.g. "Anthropic API Key". */
+  type: string;
+  /** Vault service namespace — present only when the match was proven. */
+  service?: string;
+  /** Vault field name — present only when the match was proven. */
+  field?: string;
+}
+
+/** True when the sentinel carries a proven vault identity. */
+export function isRevealableSentinel(
+  s: RedactedCredentialSentinel,
+): s is RedactedCredentialSentinel & { service: string; field: string } {
+  return s.service !== undefined && s.field !== undefined;
+}
+
+/**
+ * Build a sentinel string. Service/field are percent-encoded (see
+ * {@link encodeSentinelSegment}), so any non-empty identifier the credential
+ * routes accept — including colon-qualified names like `integration:google`
+ * — round-trips through the enriched shape. Empty segments fall back to the
+ * plain (non-revealable) shape; the function throws only if the type label
+ * itself is unusable (which would mean a broken pattern table).
+ */
+export function buildRedactedSentinel(
+  sentinel: RedactedCredentialSentinel,
+): string {
+  const { type, service, field } = sentinel;
+  if (!TYPE_RE.test(type)) {
+    throw new Error(`Invalid redacted-sentinel type label: ${type}`);
+  }
+  const base = `${REDACTED_SENTINEL_OPEN}${REDACTED_SENTINEL_TAG}:${type}`;
+  if (
+    service !== undefined &&
+    field !== undefined &&
+    service !== "" &&
+    field !== ""
+  ) {
+    const encService = encodeSentinelSegment(service);
+    const encField = encodeSentinelSegment(field);
+    return `${base}:${encService}:${encField}${REDACTED_SENTINEL_CLOSE}`;
+  }
+  return `${base}${REDACTED_SENTINEL_CLOSE}`;
+}
+
+/**
+ * Global-flag regex for locating sentinels inside a larger text. Callers must
+ * not share a single instance across concurrent iterations (stateful
+ * `lastIndex`); use {@link createRedactedSentinelRegex}.
+ */
+export function createRedactedSentinelRegex(): RegExp {
+  // 〔redacted:TYPE〕 or 〔redacted:TYPE:SERVICE:FIELD〕
+  // TYPE = anything except colon/brackets; SERVICE/FIELD = the
+  // percent-encoded segment charset (see encodeSentinelSegment). Capture
+  // groups carry the ENCODED segments — decode via decodeRedactedSentinelMatch.
+  return new RegExp(
+    `${REDACTED_SENTINEL_OPEN}${REDACTED_SENTINEL_TAG}:([^:\u3014\u3015]+?)(?::([A-Za-z0-9_.%-]+):([A-Za-z0-9_.%-]+))?${REDACTED_SENTINEL_CLOSE}`,
+    "g",
+  );
+}
+
+/**
+ * Global-flag regex for locating NEUTRALIZED sentinels — the word-joiner
+ * form {@link neutralizeRedactedSentinels} produces — inside a larger text.
+ * Renderers use this to show a defused redaction marker as an inert badge
+ * instead of leaking bare sentinel glyphs into the transcript. The capture
+ * groups mirror {@link createRedactedSentinelRegex}, but consumers must NOT
+ * trust them as vault coordinates: a neutralized span is by definition text
+ * the daemon refused to vouch for. Same statefulness caveat as the genuine
+ * regex — create a fresh instance per iteration.
+ */
+export function createNeutralizedSentinelRegex(): RegExp {
+  return new RegExp(
+    `${REDACTED_SENTINEL_OPEN}\\u2060${REDACTED_SENTINEL_TAG}:([^:\\u3014\\u3015]+?)(?::([A-Za-z0-9_.%-]+):([A-Za-z0-9_.%-]+))?${REDACTED_SENTINEL_CLOSE}`,
+    "g",
+  );
+}
+
+/**
+ * Map a {@link createRedactedSentinelRegex} match to a decoded sentinel.
+ * Shared by {@link parseRedactedSentinel} and the web rehype plugin so the
+ * segment decoding never drifts between consumers. A malformed
+ * percent-escape (unreachable for daemon-minted sentinels; forged ones are
+ * neutralized at persist) degrades to the plain non-revealable shape rather
+ * than surfacing bogus vault coordinates.
+ */
+export function decodeRedactedSentinelMatch(
+  m: RegExpExecArray,
+): RedactedCredentialSentinel {
+  const [, type, encService, encField] = m;
+  if (encService !== undefined && encField !== undefined) {
+    const service = decodeSentinelSegment(encService);
+    const field = decodeSentinelSegment(encField);
+    if (service !== undefined && field !== undefined) {
+      return { type, service, field };
+    }
+  }
+  return { type };
+}
+
+/**
+ * Neutralize sentinel-shaped strings that were NOT produced by the redactor.
+ *
+ * The sentinel is plain text, so any content source (model output quoting a
+ * transcript, fetched web content, a pasted message) could otherwise forge
+ * one and manufacture a reveal chip for an arbitrary stored credential.
+ * Producers must call this on raw text *before* inserting their own
+ * sentinels, so the only sentinels that survive persistence are the ones the
+ * redactor itself emitted from a detected secret.
+ *
+ * Neutralization inserts a word joiner (U+2060, zero-width, non-breaking)
+ * after the opening bracket — visually identical for a human reading a
+ * quoted sentinel, but the consumer regex no longer matches. Idempotent:
+ * after one pass the trigger prefix no longer occurs, so re-running is a
+ * no-op and never corrupts text further.
+ */
+export function neutralizeRedactedSentinels(text: string): string {
+  const trigger = `${REDACTED_SENTINEL_OPEN}${REDACTED_SENTINEL_TAG}:`;
+  if (!text.includes(trigger)) return text;
+  return text.replaceAll(
+    trigger,
+    `${REDACTED_SENTINEL_OPEN}\u2060${REDACTED_SENTINEL_TAG}:`,
+  );
+}
+
+/**
+ * Parse a single exact sentinel string (the whole input must be one
+ * sentinel). Returns undefined when the input is not a valid sentinel.
+ */
+export function parseRedactedSentinel(
+  text: string,
+): RedactedCredentialSentinel | undefined {
+  const re = createRedactedSentinelRegex();
+  const m = re.exec(text);
+  if (!m || m[0] !== text) return undefined;
+  return decodeRedactedSentinelMatch(m);
+}