@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.1 → 1.0.0

package/dist/cjs/shared/logging/redaction.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactSecrets = redactSecrets;
+exports.redactLogger = redactLogger;
+exports.walkObject = walkObject;
+const errors_js_1 = require("../errors/errors.js");
+const collaborators_js_1 = require("../validation/collaborators.js");
+const option_shape_js_1 = require("../validation/option-shape.js");
+const primitives_js_1 = require("../validation/primitives.js");
+const logger_js_1 = require("./logger.js");
+const secret_patterns_js_1 = require("./secret-patterns.js");
+const UNREDACTABLE = '[UNREDACTABLE]';
+function assertRegExpArray(value, field) {
+    if (!Array.isArray(value) || value.some((entry) => !(0, secret_patterns_js_1.isRegExp)(entry))) {
+        throw (0, errors_js_1.validationError)(`${field} must be an array of RegExp`, field);
+    }
+}
+function assertKeyPatterns(value, field) {
+    (0, primitives_js_1.assertStringArray)(value, field);
+    if (value.some((entry) => (0, secret_patterns_js_1.normaliseKey)(entry) === '')) {
+        throw (0, errors_js_1.validationError)(`${field} must name a letter or digit in every entry`, field);
+    }
+}
+function redactSecrets(value, patterns = secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS, valuePatterns = secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS) {
+    assertKeyPatterns(patterns, 'patterns');
+    assertRegExpArray(valuePatterns, 'valuePatterns');
+    const keyPatterns = patterns.map(secret_patterns_js_1.normaliseKey);
+    const walking = new WeakSet();
+    const done = new WeakMap();
+    const walk = (current) => {
+        if (typeof current === 'string')
+            return (0, secret_patterns_js_1.redactText)(current, valuePatterns);
+        if (current === null || typeof current !== 'object')
+            return current;
+        if (done.has(current))
+            return done.get(current);
+        if (walking.has(current))
+            return '[Circular]';
+        walking.add(current);
+        try {
+            const redacted = walkObject(current, { keyPatterns, valuePatterns, walk });
+            done.set(current, redacted);
+            return redacted;
+        }
+        finally {
+            walking.delete(current);
+        }
+    };
+    try {
+        return walk(value);
+    }
+    catch {
+        return UNREDACTABLE;
+    }
+}
+function assertRedactionOptions(options) {
+    (0, option_shape_js_1.assertObjectShape)(options, 'options');
+    if (options.extraKeys !== undefined)
+        assertKeyPatterns(options.extraKeys, 'extraKeys');
+    if (options.extraValuePatterns !== undefined) {
+        assertRegExpArray(options.extraValuePatterns, 'extraValuePatterns');
+    }
+}
+function redactLogger(inner, options = {}) {
+    (0, collaborators_js_1.assertMembers)(inner, collaborators_js_1.LOGGER_MEMBERS, 'logger');
+    assertRedactionOptions(options);
+    const patterns = options.extraKeys
+        ? [...secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS, ...options.extraKeys.map(secret_patterns_js_1.normaliseKey)]
+        : secret_patterns_js_1.DEFAULT_SECRET_KEY_PATTERNS;
+    const valuePatterns = options.extraValuePatterns
+        ? [...secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS, ...options.extraValuePatterns]
+        : secret_patterns_js_1.DEFAULT_SECRET_VALUE_PATTERNS;
+    const deliver = (method) => (message, ...args) => (0, logger_js_1.absorbLoggerFailure)(() => inner[method](message, ...args.map((arg) => redactSecrets(arg, patterns, valuePatterns))));
+    return {
+        info: deliver('info'),
+        warn: deliver('warn'),
+        error: deliver('error'),
+        debug: deliver('debug'),
+    };
+}
+function isSetValue(value) {
+    return Object.prototype.toString.call(value) === '[object Set]';
+}
+function isMapValue(value) {
+    return Object.prototype.toString.call(value) === '[object Map]';
+}
+function isErrorValue(value) {
+    const tag = Object.prototype.toString.call(value);
+    return tag === '[object Error]' || tag === '[object DOMException]';
+}
+function isOpaqueValue(value) {
+    const tag = Object.prototype.toString.call(value);
+    return tag === '[object Date]' || tag === '[object RegExp]';
+}
+function redactEntries(entries, keyPatterns, walk) {
+    const out = {};
+    for (const [key, value] of entries) {
+        Object.defineProperty(out, key, {
+            value: (0, secret_patterns_js_1.isSecretKey)(key, keyPatterns) ? secret_patterns_js_1.REDACTED : walk(value),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return out;
+}
+function redactMap(value, deps) {
+    const entries = [...value].map(([key, entry]) => {
+        const keyText = key;
+        return [String(keyText), entry];
+    });
+    return redactEntries(entries, deps.keyPatterns, deps.walk);
+}
+function redactError(current, entries, deps) {
+    const text = (0, secret_patterns_js_1.redactErrorText)(current, deps.valuePatterns);
+    const aggregated = current.errors;
+    const bare = entries.length === 0 && current.cause === undefined && aggregated === undefined;
+    if (bare && !text.changed)
+        return current;
+    const out = redactEntries(entries, deps.keyPatterns, deps.walk);
+    out.name = text.name;
+    out.message = text.message;
+    out.stack = text.stack;
+    if (current.cause !== undefined)
+        out.cause = deps.walk(current.cause);
+    if (Array.isArray(aggregated))
+        out.errors = deps.walk(aggregated);
+    return out;
+}
+function walkObject(current, deps) {
+    if (Array.isArray(current))
+        return current.map(deps.walk);
+    if (ArrayBuffer.isView(current))
+        return (0, secret_patterns_js_1.binaryLabel)(current);
+    if (isOpaqueValue(current))
+        return current;
+    if (isSetValue(current))
+        return [...current].map(deps.walk);
+    if (isMapValue(current))
+        return redactMap(current, deps);
+    const entries = Object.entries(current);
+    if (isErrorValue(current))
+        return redactError(current, entries, deps);
+    return redactEntries(entries, deps.keyPatterns, deps.walk);
+}

package/dist/cjs/shared/logging/secret-patterns.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Hides what a secret looks like.
+ *
+ * Which key names mark their value as a secret, which credential formats are
+ * recognised in free text, how a match is replaced while the field's name is
+ * kept, and how a caught value's message is redacted before another error
+ * quotes it are decided here. The redacting logger and every error that
+ * quotes its cause share these rules, so a new credential shape is one edit.
+ */
+/** Marker substituted for anything recognised as secret. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Key names whose value is a secret. Each entry is a *normalised* name — see
+ * {@link normaliseKey} — and matches a key whose normalised form equals it or
+ * ends with it. Suffix matching is what catches `secretAccessKey`, `x-api-key`,
+ * `client_secret` and `AUTH_TOKEN`; requiring the pattern to be a suffix, not a
+ * substring, is what spares `maxTokens`, `total_tokens`, `tokenizer` and
+ * `secretary` — a bare substring match would redact all four for merely
+ * containing `token` or `secret`.
+ */
+export declare const DEFAULT_SECRET_KEY_PATTERNS: readonly string[];
+/**
+ * Canonical form of a key name for matching.
+ *
+ * Accepts: any key name, in any case and with any separators.
+ *
+ * Returns: it lower-cased with every character that is not a letter or digit
+ * removed, so `api_key`, `x-api-key`, `ApiKey` and `API KEY` all become
+ * `apikey` and one pattern covers every spelling.
+ *
+ * Throws: nothing.
+ */
+export declare function normaliseKey(key: string): string;
+/**
+ * Secret shapes recognisable in free text, where key-name matching cannot
+ * reach: an error's `message`/`stack`, or any other string value. Deliberately
+ * high-confidence — each pattern describes a credential *format* rather than a
+ * word that merely sounds sensitive — so ordinary operational text survives
+ * redaction unchanged.
+ *
+ * The credential-pair pattern (last) tolerates a **closing quote after the
+ * keyword**, because that is what `JSON.stringify` produces
+ * (`{"password":"…"}`), and a backslash before that quote, because a JSON body
+ * quoted inside another JSON string — the shape a logged HTTP error carries —
+ * reads `{\"password\":\"…\"}`; requiring the separator to follow the bare
+ * keyword would match nothing in either, a silent, complete bypass on the
+ * most common shapes a downstream error arrives in. Its keywords include the
+ * hyphenated and spaced spellings of an API key (`x-api-key`, `api key`), a
+ * secret key and a client secret. Its group 1 is the keyword and separator,
+ * preserved by {@link redactText}.
+ *
+ * Its value side tries four shapes, and their order is load-bearing:
+ * 1. a fully-quoted span that consumes escapes, so `{"password":"a\"b"}` is
+ *    redacted whole. Ending the span at the escaped quote stopped the
+ *    redaction short and printed the rest of the secret verbatim.
+ * 1b. a span quoted with escaped quotes, `\"…\"`, the doubly encoded form of
+ *    the first; it ends at the next quote, so a quote inside such a secret
+ *    leaves its tail in the clear, and the sibling fields after it stay
+ *    intact where the line-end fallback would take them too.
+ * 2. an unquoted JSON scalar — number, `true`, `false`, `null` — required to
+ *    end at a real delimiter — `,`, `}`, `]` or end of input, optionally
+ *    preceded by whitespace. Without this alternative,
+ *    `{"apiKey":123,"region":"us-east-1"}` fell through to the fallback below,
+ *    which then destroyed every sibling field after the secret. The lookahead
+ *    is what stops the alternative truncating a value it does not fully
+ *    describe, such as `token=123abc`, and leaking the tail it left behind.
+ *    Whitespace alone does not end a scalar: treating a space as a delimiter
+ *    made `api_key: 5 items` redact to `api_key: [REDACTED] items`, which
+ *    reads as a partial redaction of a value the pattern never described.
+ * 3. the rest of the line, so a multi-word secret is redacted whole instead of
+ *    up to its first space. Trying the two precise shapes first is what keeps
+ *    this fallback from over-redacting sibling JSON fields.
+ *
+ * The JWT pattern (third) must scan in linear time, because these patterns
+ * run on text a caller controls — anything passed to `redactSecrets` or
+ * `redactLogger`, and an error's whole message before `redactedMessage` cuts
+ * it. A token's header segment is therefore not allowed to run across a `-`
+ * that opens another `eyJ`: written as `eyJ[A-Za-z0-9_-]+`, every `-eyJ` in a
+ * long run of token characters started a fresh scan to the end of the run, so
+ * 400 KB of `-eyJ` held the event loop for about 13 seconds. The only output
+ * this changes is a token whose header segment itself contains `-eyJ`: it is
+ * redacted from that point on, which can leave part of the header — never the
+ * payload or the signature — in the clear.
+ */
+export declare const DEFAULT_SECRET_VALUE_PATTERNS: readonly RegExp[];
+/**
+ * Whether a key name says its value is a secret.
+ *
+ * Accepts: `key` — any name. `patterns` — already-normalised names; an empty
+ * list matches nothing, which is how a caller turns key matching off.
+ *
+ * Returns: whether the normalised key equals or *ends with* a pattern. Suffix,
+ * not substring: that is what catches `secretAccessKey` and `x-api-key` while
+ * sparing `maxTokens`, `tokenizer` and `secretary`.
+ *
+ * Throws: nothing.
+ */
+export declare function isSecretKey(key: string, patterns: readonly string[]): boolean;
+/**
+ * An error's message with recognised credential shapes redacted.
+ *
+ * Accepts: any error — and, since this is what a `catch` block binds, any
+ * other value a `throw` can produce: `null`, `undefined`, a string, a number,
+ * a symbol, a plain object. Such a value is described through {@link toError}
+ * first and the description is what is redacted, so a secret it carries in its
+ * own text is still caught.
+ *
+ * Returns: the message, redacted with the default value patterns and then
+ * bounded by `truncateRelayedText` — for embedding in another error's
+ * message, since a wrapper that quotes its cause must not leak a `password=`
+ * or token the cause happened to carry. That text reaches `err.message`, which
+ * an application may print without a redacting logger.
+ *
+ * The bound is here rather than at the sites that quote the result, so no call
+ * site can get it wrong and no future one has to remember: a `RETRY_EXHAUSTED`
+ * report, a wrapped AWS failure, a compensation failure and both S3 transfer
+ * errors all inherit it from this one line. Redaction runs **before** the cut,
+ * because cutting first could split a credential shape past the pattern that
+ * would have caught it. Its own cap rather than the identifier cap: this is
+ * prose, and `MAX_RELAYED_MESSAGE_CHARS` records what that number is
+ * measured against. The value worth bounding is not the AWS SDK's own text but
+ * a **caller's** — a `serde` refusal or a `vectorBackend` rejection, whose
+ * length the caller controls entirely and which some paths quote once per row.
+ *
+ * Throws: **nothing**, for any value. Reading `.message` off a thrown
+ * primitive yielded `undefined` and the redaction then raised a `TypeError` —
+ * from inside the `catch` that was reporting the real failure, and from the
+ * one function a static guard funnels every one of this package's `catch`
+ * blocks into. Its promise has to hold for what a `catch` actually binds, or
+ * the guard concentrates every site into a function that is not safe.
+ */
+export declare function redactedMessage(error: Error): string;
+/**
+ * Whether `value` is a regular expression.
+ *
+ * Accepts: anything, including a `RegExp` from another realm.
+ *
+ * Returns: whether its tag says so. By tag rather than `instanceof`, which is
+ * banned repo-wide because it answers "no" across a realm or a duplicated
+ * module.
+ *
+ * Throws: nothing.
+ */
+export declare function isRegExp(value: RegExp): boolean;
+/**
+ * Replace every recognised secret shape inside `value` with {@link REDACTED},
+ * leaving the surrounding text intact so a redacted message stays readable.
+ *
+ * Accepts: `value` — any text. `patterns` — applied in order, each against the
+ * result of the last; an empty list returns the text unchanged. An entry that
+ * is not a `RegExp` is skipped: reading `.source` off one produced
+ * `new RegExp(undefined)` — that is `/(?:)/`, which matches the empty string
+ * and prefixed the marker to every value while catching no secret at all.
+ * Both public entry points — `redactSecrets` and {@link redactLogger} — now
+ * refuse such an entry where it is supplied, since a skipped pattern protects
+ * nothing while its caller believes it does; skipping remains the last-ditch
+ * guard for a list this package assembles internally.
+ *
+ * Returns: the text with every match replaced. A pattern may capture a leading
+ * group it wants **preserved**: only the rest of the match is replaced, which
+ * keeps `apiKey=[REDACTED]` saying which field was redacted instead of
+ * collapsing to a bare marker. A pattern with no group is replaced whole.
+ * `String.prototype.replace` passes the match *offset* — a number — as the
+ * second callback argument when the pattern has no group, hence the `typeof`
+ * test rather than an `undefined` check.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: every pattern is applied globally and from a fresh copy, so
+ * neither a missing `g` flag nor a leftover `lastIndex` can leave a later
+ * occurrence in the clear.
+ */
+export declare function redactText(value: string, patterns: readonly RegExp[]): string;
+/**
+ * A short label for a binary view.
+ *
+ * Accepts: any `ArrayBufferView`.
+ *
+ * Returns: its type and byte length, e.g. `[Uint8Array(4096)]`. Recursing into
+ * one would explode it into a per-index numeric map, both unreadable and far
+ * larger than the value itself — and a payload is exactly the thing a log must
+ * not carry.
+ *
+ * Throws: nothing.
+ */
+export declare function binaryLabel(value: ArrayBufferView): string;
+/** An Error's redacted non-enumerable text, plus whether redaction changed it. */
+export interface RedactedErrorText {
+    name: string;
+    message: string;
+    stack: string | undefined;
+    changed: boolean;
+}
+/**
+ * Redact an Error's `name`, `message` and `stack`.
+ *
+ * Accepts: `error` — any error; a missing `stack` stays missing. Any other
+ * value a `throw` can produce is described through {@link toError} first, on
+ * the same reasoning as {@link redactedMessage}: the walk that calls this only
+ * reaches it for a value whose tag says `Error`, but the promise below is
+ * written in this function's own contract and is this function's to keep.
+ *
+ * Returns: the redacted text, plus `changed`: whether any secret was actually
+ * found. That flag is what decides between passing a bare Error through by
+ * reference — preserving its identity and stack trace — and rebuilding it so
+ * the secret cannot escape. It compares against the described error, so a
+ * value that had no text of its own is never reported as changed by the
+ * describing.
+ *
+ * None of the three is cut, and that is a decision rather than an omission.
+ * The rule that bounds unchecked text bounds what *this package* writes into
+ * its own `err.message` and its own log lines — `redactedMessage` is that
+ * funnel. This function is on the other side of the boundary: it rebuilds an
+ * Error the **consumer** handed to `redactSecrets`, or to the logger
+ * `redactLogger` wrapped, on the way to the consumer's own transport. Cutting
+ * there would change what their transport receives, for a value this package
+ * neither produced nor quotes, and the caller asked for redaction rather than
+ * for truncation. A consumer who wants a bound has their own transport to put
+ * one in.
+ *
+ * Throws: **nothing**, for any value: a `name` or `stack` that cannot be read
+ * — a getter of the consumer's own that throws, a `name` whose `toString`
+ * throws — is reported as `[unreadable name]` or `[unreadable stack]`, since
+ * the one thing this must not do on the way to the consumer's transport is
+ * fail.
+ */
+export declare function redactErrorText(error: Error, patterns: readonly RegExp[]): RedactedErrorText;

package/dist/cjs/shared/logging/secret-patterns.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SECRET_VALUE_PATTERNS = exports.DEFAULT_SECRET_KEY_PATTERNS = exports.REDACTED = void 0;
+exports.normaliseKey = normaliseKey;
+exports.isSecretKey = isSecretKey;
+exports.redactedMessage = redactedMessage;
+exports.isRegExp = isRegExp;
+exports.redactText = redactText;
+exports.binaryLabel = binaryLabel;
+exports.redactErrorText = redactErrorText;
+const base_error_js_1 = require("../errors/base-error.js");
+const truncate_js_1 = require("./truncate.js");
+exports.REDACTED = '[REDACTED]';
+exports.DEFAULT_SECRET_KEY_PATTERNS = [
+    'accesskey',
+    'accesskeyid',
+    'secret',
+    'sessiontoken',
+    'securitytoken',
+    'authorization',
+    'password',
+    'passwd',
+    'passphrase',
+    'apikey',
+    'bearer',
+    'token',
+    'privatekey',
+    'secretkey',
+];
+function normaliseKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+exports.DEFAULT_SECRET_VALUE_PATTERNS = [
+    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+    /\beyJ(?:[A-Za-z0-9_]|-(?!eyJ))+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+    /((?:aws_)?(?:secret_access_key|secretaccesskey|secret_?key|client_?secret|password|passwd|api[-_ ]?key|token)(?:\\?["'])?\s*[=:]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\\"[^"\r\n]*\\"|\\'[^'\r\n]*\\'|(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]]|\s*$)|[^\r\n]+)/gi,
+];
+function isSecretKey(key, patterns) {
+    const normalised = normaliseKey(key);
+    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
+}
+function redactedMessage(error) {
+    return (0, truncate_js_1.truncateRelayedText)(redactText((0, base_error_js_1.toError)(error).message, exports.DEFAULT_SECRET_VALUE_PATTERNS));
+}
+function globalCopyOf(pattern) {
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    return new RegExp(pattern.source, flags);
+}
+function isRegExp(value) {
+    return Object.prototype.toString.call(value) === '[object RegExp]';
+}
+function redactText(value, patterns) {
+    return patterns.reduce((text, pattern) => {
+        if (!isRegExp(pattern))
+            return text;
+        return text.replace(globalCopyOf(pattern), (_match, prefix) => typeof prefix === 'string' ? `${prefix}${exports.REDACTED}` : exports.REDACTED);
+    }, value);
+}
+function binaryLabel(value) {
+    return `[${value.constructor.name}(${value.byteLength})]`;
+}
+function redactErrorText(error, patterns) {
+    const described = (0, base_error_js_1.toError)(error);
+    const rawName = nameOf(described);
+    const rawStack = stackOf(described);
+    const name = redactText(rawName, patterns);
+    const message = redactText(described.message, patterns);
+    const stack = rawStack === undefined ? undefined : redactText(rawStack, patterns);
+    return {
+        name,
+        message,
+        stack,
+        changed: name !== rawName || message !== described.message || stack !== rawStack,
+    };
+}
+function nameOf(error) {
+    try {
+        return String(error.name);
+    }
+    catch {
+        return '[unreadable name]';
+    }
+}
+function stackOf(error) {
+    try {
+        const { stack } = error;
+        return stack === undefined ? undefined : String(stack);
+    }
+    catch {
+        return '[unreadable stack]';
+    }
+}

package/dist/cjs/shared/logging/truncate.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Hides how much of an unchecked string a line may quote.
+ *
+ * A log line or public error message that quotes a string this package did
+ * not length-check passes it through here. The caps for an identifier, for a
+ * relayed cause's prose and for a list of labels, and the mark that states a
+ * cut value's real length, are chosen here, so a call site says what kind of
+ * value it quotes and never how many characters it keeps.
+ */
+/**
+ * Characters of an unchecked string one log line or one public error message
+ * carries, past which it is cut and marked with its real length.
+ *
+ * Most of what these lines quote is a row's sort key or an offloaded object's
+ * S3 key, so the service already caps each at 1024 bytes — the cost is not one
+ * long line but many. `list: skipped a row that is not a checkpoint meta item`
+ * and `left a foreign row in place` fire once per row, and those passes walk a
+ * whole partition, up to `MAX_TOTAL_ROWS_IN_MEMORY`
+ * (`src/shared/dynamodb/paginate.ts`) rows: one call on a shared table could
+ * write megabytes of log. A consumer's `VectorBackend` carries no such service
+ * cap at all.
+ *
+ * 256 is `MAX_KEY_SEGMENT_BYTES` (`src/shared/dynamodb/table-schema.ts`), this
+ * package's own budget for one identifier inside a key, so any key composed
+ * from identifiers it validated is quoted whole in the common case and only a
+ * foreign row, a hand-written one or a backend's own answer — exactly the
+ * cases these lines report — is cut. Nothing is lost by cutting: the line's
+ * job is to say which row to go and look at, and the row holds the rest.
+ */
+export declare const MAX_LOGGED_VALUE_CHARS = 256;
+/**
+ * Labels of an unchecked `string[]` one log line or one public error message
+ * carries, past which the rest are dropped and the real depth is stated.
+ *
+ * An array is two unbounded things — how many labels there are and how long
+ * each one is — so a bound on the labels alone is not a bound: a backend
+ * answering with one label of a megabyte and one answering with a million
+ * labels of a character cost the same line. {@link MAX_LOGGED_VALUE_CHARS}
+ * covers the first, this covers the second.
+ *
+ * 8 is a budget rather than a rule about namespaces: a store namespace is a
+ * path, what identifies which path is its leading labels, and every namespace
+ * this package's own documentation forms is two or three deep. The marker
+ * states the depth it really had, so a deeper one is cut without being
+ * misreported.
+ *
+ * A `namespace` and `key` pair that passed `parseStoreAddress` needs none of
+ * this and goes in whole: that check measures the sort key they *compose*, so
+ * it bounds how many labels there are as well as how long each one is. A
+ * search or listing **prefix** passes no such check — nothing composes it into
+ * a key — so its depth is unchecked however carefully each label was checked,
+ * and a backend's own answer is unchecked in both.
+ */
+export declare const MAX_LOGGED_LABELS = 8;
+/**
+ * Characters of a relayed *cause's* text one public error message or one log
+ * line carries, past which it is cut and marked with its real length.
+ *
+ * Its own cap rather than {@link MAX_LOGGED_VALUE_CHARS} because the two bound
+ * different things. That one bounds an **identifier** — a sort key, an S3
+ * object key, a namespace label — and 256 is this package's own budget for one
+ * identifier inside a key, so a value past it is already abnormal and the line
+ * only has to say which row to go and look at. This one bounds **prose**: the
+ * sentence an AWS SDK error, a consumer's `VectorBackend` or a caller's own
+ * `serde` wrote to explain a failure, which `redactedMessage` relays into
+ * `err.message`. Cutting that at an identifier's budget would throw away the
+ * half of a diagnostic that says what to do about it, and a diagnostic is the
+ * entire value of relaying it at all.
+ *
+ * 1024 is measured against the longest text this package actually relays: an
+ * IAM `AccessDenied`, which names the calling principal's ARN, the action and
+ * the resource ARN and then says why no policy allows it, runs to the mid
+ * hundreds of characters, and a role ARN with a long path and a session name
+ * pushes it further. 1024 clears that whole, so the case an operator most
+ * needs to read arrives intact.
+ *
+ * What it is *for* is the other direction. `redactedMessage` also relays a
+ * **caller's own** thrown error — a `serde` refusing a value, a `vectorBackend`
+ * rejecting a query — whose length the caller controls entirely, and those
+ * messages are quoted once per row on paths that walk a whole prefix or table.
+ * Unbounded, one such error fills a log; at 1024 a thousand of them are a
+ * megabyte rather than an unbounded amount.
+ *
+ * Its own literal at the same value as `MAX_SORT_KEY_BYTES`
+ * (`src/shared/dynamodb/table-schema.ts`) and `MAX_S3_KEY_BYTES`
+ * (`src/shared/codec/s3/config.ts`) rather than an alias of either, for the
+ * reason `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)
+ * records: aliasing two caps would move one whenever the other is retuned,
+ * and these three answer unrelated questions.
+ */
+export declare const MAX_RELAYED_MESSAGE_CHARS = 1024;
+/**
+ * Bound a string this package did not length-check.
+ *
+ * **The rule, in one sentence:** a string goes through here before a log line
+ * or a public error message quotes it, unless this package composed it from
+ * identifiers it length-checked. Where the string came from does not decide
+ * it — a row, a bucket's own configuration, a consumer's `VectorBackend` and
+ * an object the caller handed in are the same thing here, which is that
+ * nothing bounded them. A caller's `sessionId`, `threadId`, `namespace` and
+ * `key`, and every key built from them, are capped by
+ * `MAX_PARTITION_ID_BYTES`, `MAX_KEY_SEGMENT_BYTES` and `MAX_SORT_KEY_BYTES`
+ * before a request is made, so those go in as they are; a row's own `SK`, an
+ * offloaded object's key, a descriptor's `location`, a backend's `namespace`
+ * and `key`, a lifecycle rule's scope and a stored message's `type` are
+ * bounded by nothing this package ran.
+ *
+ * **It says "or a public error message" for one reason:** one value must not
+ * get two answers. An `s3Key` off a row was cut for the `warn` that reports
+ * refusing to delete the object and quoted whole by the error that refuses to
+ * read it — one package, one value, two answers. An error's text is not the
+ * compatibility surface (the README tells callers to branch on `code`, `name`
+ * and the structured fields, never on text) and the `context` those errors
+ * carry keeps the value whole, so what reads an error as data loses nothing
+ * by this.
+ *
+ * Accepts: `value` — the string as whatever produced it carried it. Declared
+ * `string` because a table's own key attributes always are, and because the
+ * interfaces a consumer implements say so; anything else is returned
+ * untouched rather than coerced or refused, since a report of a value that is
+ * already wrong is the last place to raise a `TypeError` of its own.
+ *
+ * Returns: the value unchanged at or under {@link MAX_LOGGED_VALUE_CHARS}
+ * characters, otherwise that many characters followed by `…(len N)` giving the
+ * length it really had. The mark is what keeps a cut value honest: without it
+ * a truncated key reads as a key that simply ends there.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a cut never falls between the halves of a surrogate pair, so a
+ * well-formed value stays well-formed. A lone surrogate is what
+ * `assertWellFormed` exists to keep out of this package's strings, and a JSON
+ * log transport rewrites one to U+FFFD without saying so.
+ */
+export declare function truncateForLog(value: string): string;
+/**
+ * Bound the **prose** of a relayed cause, which takes its own cap.
+ *
+ * {@link truncateForLog} bounds an identifier, where 256 characters is this
+ * package's own budget for one and anything past it is already abnormal. The
+ * text an AWS SDK error, a consumer's `VectorBackend` or a caller's own
+ * `serde` wrote is a sentence rather than a name: cut at an identifier's
+ * budget it loses the half that says what to do, which is the only reason to
+ * relay it. {@link MAX_RELAYED_MESSAGE_CHARS} records what the larger number
+ * is measured against, and why the two differ.
+ *
+ * It has exactly one caller — `redactedMessage`, the funnel every `catch` in
+ * this package goes through — so no call site can get the cap wrong and no
+ * future one has to remember it. That also means a site must not cut the
+ * result again: a second cut marks the length of the first cut's output rather
+ * than of the original, which is the one thing the mark exists to prevent.
+ *
+ * Accepts: `value` — the redacted text. Redaction runs first, so a credential
+ * shape can never be half-cut past the pattern that would have caught it.
+ *
+ * Returns: the value unchanged at or under the cap, otherwise that many
+ * characters followed by `…(len N)`.
+ *
+ * Throws: nothing.
+ */
+export declare function truncateRelayedText(value: string): string;
+/**
+ * Bound a list of labels — a store `namespace`, a list of channel names — the
+ * same rule reaches.
+ *
+ * An array is two unbounded things, how many labels it holds and how long each
+ * one is, so a bound on one of them is not a bound. {@link truncateForLog}
+ * covers the labels; the count is covered here.
+ *
+ * A `namespace` and `key` pair that passed `parseStoreAddress` is already
+ * bounded in both — that check measures the sort key they compose — and goes
+ * in whole. A search or listing prefix is not: nothing composes it into a key,
+ * so however carefully each label was checked, how many there are was not.
+ *
+ * The labels stay a list rather than being joined into one string, for two
+ * reasons. A structured transport already carries the field as a list and the
+ * README's Logging table documents it as one, so joining would change the
+ * shape of a line rather than only its size. And a label nothing validated may
+ * hold the `#` a join would put between labels, so a joined line cannot say
+ * whether the backend answered with one label or with two — which is the very
+ * thing these lines report.
+ *
+ * Accepts: `labels` — as the row, the backend or the caller gave it. Declared
+ * `string[]` because that is what the interfaces say; anything else is
+ * returned untouched, for the reason {@link truncateForLog} gives, and that
+ * case is reached rather than defensive — a `namespace` that is not an array
+ * is one of the things `parseStoreAddress` refuses, and the line reporting the
+ * refusal quotes what was refused.
+ *
+ * Returns: at most {@link MAX_LOGGED_LABELS} labels, each bounded by
+ * {@link truncateForLog}, with one further label reading `…(len N)` when some
+ * were dropped, giving the depth the list really had. A list within both
+ * bounds comes back as an equal list.
+ *
+ * Throws: nothing.
+ */
+export declare function truncateLabelsForLog(labels: string[]): string[];