@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/secret-value-masking.d.ts

@@ -0,0 +1,299 @@
+import type { ResolvedSecretValue, SecretResolver } from "./secret-resolution.js";
+import { isBase64DataUrl, isTextMediaType, mapSecretMaskableStrings } from "./secret-mask-strings.js";
+import { type SecretShapeMatch } from "./secret-shape-masking.js";
+export { isBase64DataUrl, isTextMediaType, mapSecretMaskableStrings };
+/** Values shorter than this are not masked by default. Eight characters keeps
+ * PINs, one-time codes, ports and short words out while still covering real
+ * passwords, tokens and keys (which are almost always longer). */
+export declare const SECRET_VALUE_MASK_MIN_CHARS = 8;
+/** A text that ends (or reaches a truncation mark) partway through a value
+ * has that clipped start masked only when it is distinctive: at least this
+ * many characters... */
+export declare const SECRET_VALUE_CLIPPED_MIN_CHARS = 16;
+/** ...and at least this share of the value's form. A shared prefix (a URL
+ * scheme, a token's fixed header, `-----BEGIN`) is never enough on its own. */
+export declare const SECRET_VALUE_CLIPPED_MIN_SHARE = 0.5;
+/** Distinct values one memory keeps; the oldest drop first. */
+export declare const SECRET_VALUE_MEMORY_MAX_ENTRIES = 512;
+export type SecretValueMaskEntry = {
+    /** The plaintext to find. Never logged or returned by this module. */
+    value: string;
+    /** What replaces it: a reference or a fixed marker. Must be JSON- and URL-safe text. */
+    label: string;
+};
+export type SecretValueMaskOptions = {
+    /** Values (and derived forms) shorter than this are skipped. Default 8. */
+    minChars?: number;
+    /** Also search base64 forms. Default true. */
+    base64?: boolean;
+    /** Minimum characters for a clipped start (default 16, never below `minChars`). */
+    clippedMinChars?: number;
+    /** Minimum share of the form for a clipped start, 0 to 1 (default 0.5). */
+    clippedMinShare?: number;
+    /**
+     * The end of a text counts as a cut only when the text has at least this
+     * many characters (default 1,024: output clipped to a size). Truncation
+     * marks always count.
+     */
+    clippedTextEndMinChars?: number;
+    /**
+     * Lines of a multi-line value searched on their own. "key-material"
+     * (default): lines of at least 16 characters made only of base64 or hex
+     * characters (PEM body lines), so a structured value's ordinary lines
+     * (`NODE_ENV=production`) stay searchable text; "all": every line of at
+     * least `minChars`.
+     */
+    lines?: "key-material" | "all";
+    /**
+     * Which forms are indexed for clipped starts. "primary" (default): the
+     * value as written, trimmed and JSON-escaped once, which bounds memory for
+     * long values. "all": every form, including lines and percent-encoded
+     * forms (short typed values in browser and desktop results).
+     */
+    clippedForms?: "primary" | "all";
+    /**
+     * Object keys whose string values stay untouched (identifiers, digests).
+     * Binary payloads are always skipped: a string that is entirely a base64
+     * data URL (`data:<type>/<subtype>;base64,<base64>`) and the `data` of an
+     * object that also carries a MIME type (image and file content). Payloads
+     * of a text type are searched decoded and encoded again.
+     */
+    skipKey?: (key: string) => boolean;
+};
+export type SecretValueMaskDiagnostic = {
+    /** Where masking failed, for example `tool_result` or `event_writer`. */
+    stage: string;
+    /** The error's class name only; never its message, which could carry text. */
+    error: string;
+};
+export declare function secretCredentialMaskLabel(kind: string): string;
+/** Generic replacement when no usable reference exists. */
+export declare const SECRET_VALUE_GENERIC_MASK_LABEL = "[secret]";
+/**
+ * The label for a value a reference resolved to: the reference as written
+ * (a `secretfile` reference is shown as the equivalent `secret` reference,
+ * since what appears in text is the value, not the file path). A reference
+ * whose text is unsafe inside JSON (a name with a quote) is written in its ID
+ * form instead, which resolves to the same field.
+ */
+export declare function secretReferenceMaskLabel(input: {
+    raw: string;
+    itemId?: string | null;
+    fieldName?: string | null;
+}): string;
+export declare function isSecretReferenceMaskLabel(label: string): boolean;
+/**
+ * Every form of one value searched for in text, longest first. Forms shorter
+ * than `minChars` are dropped; a value shorter than it has no forms.
+ */
+export declare function secretValueForms(value: string, options?: SecretValueMaskOptions): string[];
+export type CompiledSecretValueMasks = {
+    readonly empty: boolean;
+    readonly minChars: number;
+    readonly skipKey: ((key: string) => boolean) | undefined;
+    /** Labels and markers kept as they are; null when there is nothing to search for. */
+    readonly pattern: RegExp | null;
+    readonly labels: ReadonlyMap<string, string>;
+    /** Forms longest first. */
+    readonly forms: readonly string[];
+    /** Forms by their first `minChars` characters, longest first. */
+    readonly byPrefix: ReadonlyMap<string, readonly string[]>;
+    /** The first two character codes of every form, as one number. */
+    readonly firstPairs: ReadonlySet<number>;
+    /** Clipped starts: at least this many characters... */
+    readonly clippedMinChars: number;
+    /** ...and at least this share of the form. */
+    readonly clippedMinShare: number;
+    /** The end of a text is a cut only for texts at least this long. */
+    readonly clippedTextEndMinChars: number;
+    /**
+     * Clipped starts of forms by their last `clippedMinChars` characters,
+     * longest first, so a cut needs one lookup.
+     */
+    readonly byClippedEnd: ReadonlyMap<string, readonly ClippedStart[]>;
+    readonly longestForm: number;
+};
+/** A distinctive start of a form: `form.slice(0, length)`. */
+type ClippedStart = {
+    form: string;
+    length: number;
+};
+/** The end of a text counts as a cut only for long texts (output clipped to a size). */
+export declare const SECRET_VALUE_CLIPPED_TEXT_END_MIN_CHARS = 1024;
+/** Compile entries once for repeated masking. A form keeps the label of the first entry that has it. */
+export declare function compileSecretValueMasks(entries: readonly SecretValueMaskEntry[], options?: SecretValueMaskOptions): CompiledSecretValueMasks;
+/** Mask one text with compiled entries. */
+export declare function maskSecretValuesInText(text: string, masks: CompiledSecretValueMasks): string;
+/**
+ * Deep copy of `value` with every known secret value replaced in every string
+ * (object keys are kept). Inputs that need no change keep their identity.
+ */
+export declare function maskSecretValues<T>(value: T, entries: readonly SecretValueMaskEntry[] | CompiledSecretValueMasks, options?: SecretValueMaskOptions): T;
+/**
+ * The MCP `_meta` key on a worker's call to Opengeni's own server that
+ * carries the values its arguments resolved to (with their references), so
+ * the server masks them in what it stores and returns. Never logged.
+ */
+export declare const FIRST_PARTY_SECRET_VALUES_META_KEY = "opengeniSecretValues";
+/** The resolved values a first-party call's `_meta` carries, if any. */
+export declare function firstPartySecretValuesFromMeta(meta: unknown): SecretValueMaskEntry[];
+/**
+ * Saves detected secret-shaped values somewhere they can be used by
+ * reference (the task vault) and returns, per value it saved, the reference
+ * to write instead. Values it leaves out are masked with a fixed marker.
+ */
+export type SecretShapeCapturer = (matches: readonly SecretShapeMatch[]) => Promise<ReadonlyMap<string, string>>;
+/** Distinct new values captured from one tool result; the rest get a marker. */
+export declare const SECRET_SHAPE_CAPTURES_PER_RESULT = 16;
+/**
+ * The secret values one owner (an agent attempt, a browser session) knows
+ * about, with their labels, and masking against all of them. Masking never
+ * throws: an internal failure returns the input unchanged and reports a
+ * metadata-only diagnostic.
+ */
+export declare class SecretValueMemory {
+    private readonly values;
+    private readonly operations;
+    private compiled;
+    /** Masks without values that only have a `[masked <kind>]` marker, by version. */
+    private compiledReferenced;
+    private changes;
+    private readonly options;
+    private readonly maxEntries;
+    private onDiagnostic;
+    private refresher;
+    /** Values an explicit, audited reveal (`secret_get`) handed to the agent. */
+    private readonly revealed;
+    private disposed;
+    /** Secret-shaped values seen in tool output, with what replaces them (any length). */
+    private readonly shapes;
+    private shapeCapturer;
+    constructor(options?: SecretValueMaskOptions & {
+        maxEntries?: number;
+        onDiagnostic?: (diagnostic: SecretValueMaskDiagnostic) => void;
+    });
+    /** Replace the diagnostic sink (for example once observability is ready). */
+    setDiagnosticSink(sink: ((diagnostic: SecretValueMaskDiagnostic) => void) | undefined): void;
+    /**
+     * Attach a loader that may remember more values (for example uses recorded
+     * by another process). It owns its own throttling.
+     */
+    setRefresher(refresher: (() => Promise<void>) | undefined): void;
+    /** Run the refresher, waiting at most `maxWaitMs`; never throws. */
+    refresh(maxWaitMs?: number): Promise<void>;
+    get minChars(): number;
+    get size(): number;
+    /** Increases whenever the searched values change (for memoized masking). */
+    get version(): number;
+    /**
+     * Remember a value. Returns whether it is searched for (false when shorter
+     * than the minimum). A value keeps its first reference label; a reference
+     * label replaces a credential marker, because it is the more useful name.
+     */
+    remember(value: string, label: string): boolean;
+    /**
+     * Over the limit, the oldest values go first, but Opengeni's own
+     * credentials (`[opengeni credential: …]`) stay while others can go.
+     */
+    private evict;
+    /**
+     * An explicit, audited plaintext read (`secret_get`) handed this value to
+     * the agent on purpose: it is not masked for the rest of this memory's
+     * life. Never throws.
+     */
+    reveal(value: string): void;
+    /**
+     * Whether `value` is, or lies within, a value `secret_get` revealed. Only a
+     * value of at least the minimum length counts as lying within one, so a
+     * short value is not released by a chance match.
+     */
+    private isRevealed;
+    /**
+     * Forget every value at the end of the owner's life (an attempt), so work
+     * that outlives it neither keeps the plaintext nor masks with it.
+     */
+    dispose(): void;
+    /**
+     * Remember a value and note that one tool call (its operation ID) used it,
+     * so the receiver of that call can mask its own stored text with exactly
+     * the values it was given.
+     */
+    rememberForOperation(operationId: string, value: string, label: string): boolean;
+    /** The values one tool call used (see `rememberForOperation`). */
+    operationEntries(operationId: string): SecretValueMaskEntry[];
+    /** Whether a value is remembered (for tests and dedupe; never exposes values). */
+    has(value: string): boolean;
+    entries(): SecretValueMaskEntry[];
+    private masks;
+    /** Deep copy with every remembered value replaced; never throws. */
+    mask<T>(value: T, stage?: string): T;
+    /** `mask` without the values whose label is only a `[masked <kind>]` marker. */
+    private maskReferenced;
+    /** Mask one text; never throws. */
+    maskText(text: string, stage?: string): string;
+    /** Mask with the remembered values plus, for this call only, extra ones. */
+    maskWith<T>(value: T, extra: readonly SecretValueMaskEntry[], stage?: string): T;
+    /**
+     * Attach the capturer that saves secret-shaped values found in tool output
+     * (normally into the task vault). Without one they are masked with a marker.
+     */
+    setShapeCapturer(capturer: SecretShapeCapturer | undefined): void;
+    /**
+     * Remember a secret-shaped value from tool output: it is replaced wherever
+     * a shape detector finds it, and (when long enough) searched for as a known
+     * value everywhere else. A reference replaces an earlier marker.
+     */
+    rememberShape(value: string, label: string, username?: string): void;
+    /**
+     * Find secret-shaped values in tool output that are not known yet and
+     * capture them, waiting at most `maxWaitMs`. Values the capturer does not
+     * return a reference for (or all of them, without a capturer or on any
+     * failure) are remembered with a `[masked <kind>]` marker. Never throws.
+     */
+    captureShapes(value: unknown, stage?: string, maxWaitMs?: number): Promise<void>;
+    /**
+     * Whether a detected part lies within a value `secret_get` revealed (as
+     * written or JSON-escaped), for example the password of a revealed URL.
+     */
+    private insideRevealed;
+    /** What replaces a detected shape: its capture, a known label, a marker, or nothing when revealed. */
+    private shapeLabel;
+    /**
+     * Mask tool output: known values first, then every secret-shaped part
+     * (with its captured reference, or a marker). Never throws.
+     */
+    maskToolOutput<T>(value: T, stage?: string): T;
+    /** `maskToolOutput` for one text. */
+    maskToolOutputText(text: string, stage?: string): string;
+    private report;
+}
+/**
+ * Mask an error's message, stack, causes and inner errors (`AggregateError`)
+ * in place with `memory` (bounded depth) and return it, so a rethrown error
+ * carries references, not values. In "tool_output" mode secret-shaped parts
+ * are masked too.
+ * Never throws: on failure the original error is returned as it is.
+ */
+export declare function maskSecretValuesInError<E>(error: E, memory: SecretValueMemory | null | undefined, mode?: "known" | "tool_output", depth?: number): E;
+/**
+ * Opengeni's audited plaintext read, which hands a value to the agent on
+ * purpose: exactly its own `secret_get` (as the agent sees it, bare or with
+ * the first-party prefix). A connector's tool of the same name is not one.
+ */
+export declare function isSecretRevealToolName(name: string): boolean;
+/**
+ * The values a `secret_get` result reveals (`{ value, encoding }`, possibly
+ * as JSON text). A base64 result reveals both the encoded text and the
+ * decoded UTF-8 text, since the memory holds the decoded value.
+ */
+export declare function secretGetRevealedValues(result: unknown, depth?: number): string[];
+/**
+ * When `toolName` is `secret_get`, mark what its result reveals as readable
+ * for the rest of the memory's life, so masking the result leaves it intact.
+ * Never throws.
+ */
+export declare function revealSecretGetResult(memory: SecretValueMemory | null | undefined, toolName: string, result: unknown): void;
+/** Remember what one resolver call returned, labelled by reference; never throws. */
+export declare function rememberResolvedSecretValues(memory: SecretValueMemory | null | undefined, resolved: ReadonlyMap<string, ResolvedSecretValue>, operationId?: string): void;
+/** The same resolver, remembering every value it returns in the memory `target` names at resolution time. */
+export declare function rememberingSecretResolver(resolver: SecretResolver, target: SecretValueMemory | (() => SecretValueMemory | null | undefined)): SecretResolver;

package/dist/secret-value-masking.js

@@ -0,0 +1,62 @@
+import {
+  FIRST_PARTY_SECRET_VALUES_META_KEY,
+  SECRET_SHAPE_CAPTURES_PER_RESULT,
+  SECRET_VALUE_CLIPPED_MIN_CHARS,
+  SECRET_VALUE_CLIPPED_MIN_SHARE,
+  SECRET_VALUE_CLIPPED_TEXT_END_MIN_CHARS,
+  SECRET_VALUE_GENERIC_MASK_LABEL,
+  SECRET_VALUE_MASK_MIN_CHARS,
+  SECRET_VALUE_MEMORY_MAX_ENTRIES,
+  SecretValueMemory,
+  compileSecretValueMasks,
+  firstPartySecretValuesFromMeta,
+  isSecretReferenceMaskLabel,
+  isSecretRevealToolName,
+  maskSecretValues,
+  maskSecretValuesInError,
+  maskSecretValuesInText,
+  rememberResolvedSecretValues,
+  rememberingSecretResolver,
+  revealSecretGetResult,
+  secretCredentialMaskLabel,
+  secretGetRevealedValues,
+  secretReferenceMaskLabel,
+  secretValueForms
+} from "./chunk-VLUKBV6Y.js";
+import {
+  isBase64DataUrl,
+  isTextMediaType,
+  mapSecretMaskableStrings
+} from "./chunk-BMUTAZX5.js";
+import "./chunk-G4RKARXZ.js";
+import "./chunk-AQYDZUJV.js";
+import "./chunk-56SNIMDO.js";
+export {
+  FIRST_PARTY_SECRET_VALUES_META_KEY,
+  SECRET_SHAPE_CAPTURES_PER_RESULT,
+  SECRET_VALUE_CLIPPED_MIN_CHARS,
+  SECRET_VALUE_CLIPPED_MIN_SHARE,
+  SECRET_VALUE_CLIPPED_TEXT_END_MIN_CHARS,
+  SECRET_VALUE_GENERIC_MASK_LABEL,
+  SECRET_VALUE_MASK_MIN_CHARS,
+  SECRET_VALUE_MEMORY_MAX_ENTRIES,
+  SecretValueMemory,
+  compileSecretValueMasks,
+  firstPartySecretValuesFromMeta,
+  isBase64DataUrl,
+  isSecretReferenceMaskLabel,
+  isSecretRevealToolName,
+  isTextMediaType,
+  mapSecretMaskableStrings,
+  maskSecretValues,
+  maskSecretValuesInError,
+  maskSecretValuesInText,
+  rememberResolvedSecretValues,
+  rememberingSecretResolver,
+  revealSecretGetResult,
+  secretCredentialMaskLabel,
+  secretGetRevealedValues,
+  secretReferenceMaskLabel,
+  secretValueForms
+};
+//# sourceMappingURL=secret-value-masking.js.map

package/dist/secret-value-masking.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/secret-value.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Schemas whose value is a secret: a password, key, token, or a bundle of
+ * credential headers or values. The action catalog generator reads this
+ * registry, so every action whose request or response carries such a field is
+ * marked as handling secrets wherever the schema is reused, whatever the
+ * field is called. Field names that already say "secret" ("apiKey",
+ * "clientSecret") are caught by name as well.
+ */
+export declare const secretValues: z.core.$ZodRegistry<{
+    secret: true;
+}, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+/**
+ * Mark a schema as holding a secret value. Pass the schema built for this
+ * field ("z.record(...)"), never a shared one such as a primitive: the mark
+ * belongs to the schema instance, so marking a shared one would mark every
+ * field that uses it.
+ */
+export declare function secretValue<Schema extends z.ZodType>(schema: Schema): Schema;