@fgv/ts-extras 5.1.0-21 → 5.1.0-23

package/lib/packlets/ai-assist/jsonResponse.d.ts

@@ -0,0 +1,91 @@
+/**
+ * JSON-tolerant extraction and converters for LLM responses.
+ *
+ * Models commonly wrap JSON output in Markdown code fences, add a
+ * "Sure, here's the JSON:" preamble, or trail off with prose after the
+ * closing brace. These helpers normalize that quirk on the read side so every
+ * AiAssist consumer can reach a validated `T` from raw model text without
+ * reimplementing the same fence-stripping logic.
+ *
+ * Scope: strip wrappers (fences, prose, BOM, whitespace). Out of scope: repair
+ * malformed JSON (missing commas, unquoted keys, smart quotes, etc.).
+ *
+ * @packageDocumentation
+ */
+import { type Converter, Result, type Validator } from '@fgv/ts-utils';
+import { type JsonValue } from '@fgv/ts-json-base';
+/**
+ * A function that pulls a JSON-shaped substring out of arbitrary model text.
+ * Implementations strip whatever wrappers the model added (fences, preamble,
+ * trailing prose) and return the JSON-shaped substring ready for `JSON.parse`.
+ * @public
+ */
+export type JsonTextExtractor = (text: string) => Result<string>;
+/**
+ * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:
+ *
+ * - Leading/trailing whitespace and a leading byte-order mark.
+ * - Markdown code fences (with or without a language tag).
+ * - Conversational preamble before the first `{` or `[`.
+ * - Trailing prose after the matched closing `}` or `]`.
+ *
+ * Out of scope: repairing malformed JSON, handling smart quotes, etc.
+ *
+ * @param text - Raw model output.
+ * @returns A `Result<string>` containing the JSON-shaped substring, or a
+ * `Failure` if no JSON-shaped substring was found.
+ * @public
+ */
+export declare const extractJsonText: JsonTextExtractor;
+/**
+ * Options shared by every {@link AiAssist.fencedStringifiedJson} call.
+ * @public
+ */
+export interface IFencedStringifiedJsonExtractorOptions {
+    /**
+     * Optional pre-parse extractor. Defaults to {@link AiAssist.extractJsonText}.
+     * Provide a custom extractor to handle response shapes the default does not
+     * understand.
+     */
+    readonly extractor?: JsonTextExtractor;
+}
+/**
+ * Options for the validating overload of {@link AiAssist.fencedStringifiedJson}.
+ * `inner` is required so the typed `Converter<T>` return value can never lie
+ * about the runtime shape.
+ * @public
+ */
+export interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJsonExtractorOptions {
+    /** Inner converter or validator applied to the parsed JSON value. */
+    readonly inner: Converter<T> | Validator<T>;
+}
+/**
+ * Creates a `Converter` that accepts raw LLM response text, runs it through a
+ * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the
+ * extracted substring as JSON, and applies an optional inner converter or
+ * validator.
+ *
+ * @example
+ * ```ts
+ * const converter = fencedStringifiedJson({ inner: myShapeConverter });
+ * const result = converter.convert(llmText); // Result<MyShape>
+ * ```
+ *
+ * @param options - Optional extractor; omit to keep the default. Without an
+ * `inner` step, the converter resolves to the parsed `JsonValue`.
+ * @returns A `Converter<JsonValue>`.
+ * @public
+ */
+export declare function fencedStringifiedJson(options?: IFencedStringifiedJsonExtractorOptions): Converter<JsonValue>;
+/**
+ * Creates a `Converter` that accepts raw LLM response text, runs it through a
+ * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the
+ * extracted substring as JSON, and applies the supplied inner converter or
+ * validator.
+ *
+ * @param options - Required `inner` converter/validator and optional extractor.
+ * @returns A `Converter<T>`.
+ * @public
+ */
+export declare function fencedStringifiedJson<T>(options: IFencedStringifiedJsonOptions<T>): Converter<T>;
+//# sourceMappingURL=jsonResponse.d.ts.map

package/lib/packlets/ai-assist/jsonResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonResponse.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/jsonResponse.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAQ,MAAM,EAAW,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAClG,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAErF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;AA+DjE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,EAAE,iBA6B7B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,sCAAsC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B,CAAC,CAAC,CAAE,SAAQ,sCAAsC;IAC9F,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sCAAsC,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;AAC9G;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC"}

package/lib/packlets/ai-assist/jsonResponse.js

@@ -0,0 +1,154 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractJsonText = void 0;
+exports.fencedStringifiedJson = fencedStringifiedJson;
+/**
+ * JSON-tolerant extraction and converters for LLM responses.
+ *
+ * Models commonly wrap JSON output in Markdown code fences, add a
+ * "Sure, here's the JSON:" preamble, or trail off with prose after the
+ * closing brace. These helpers normalize that quirk on the read side so every
+ * AiAssist consumer can reach a validated `T` from raw model text without
+ * reimplementing the same fence-stripping logic.
+ *
+ * Scope: strip wrappers (fences, prose, BOM, whitespace). Out of scope: repair
+ * malformed JSON (missing commas, unquoted keys, smart quotes, etc.).
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const FENCED_BLOCK = /```[A-Za-z0-9_-]*\s*\r?\n([\s\S]*?)\r?\n?```/;
+const BOM = /^\uFEFF/;
+// Full RFC 8259 grammar so the extractor only succeeds when the entire
+// candidate parses as a JSON primitive (instead of just starting like one).
+const JSON_NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+// eslint-disable-next-line no-control-regex
+const JSON_STRING = /^"(?:[^"\\\u0000-\u001F]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"$/;
+const JSON_KEYWORD = /^(?:true|false|null)$/;
+function stripBom(text) {
+    return text.replace(BOM, '');
+}
+function findBalancedJsonSubstring(text) {
+    // Walk the text once tracking string state. The first '{' or '[' that is
+    // *outside* a quoted string is the candidate start; from there, count
+    // matching close characters while ignoring delimiters that appear inside
+    // strings.
+    let inString = false;
+    let escape = false;
+    let start = -1;
+    let open = '';
+    let close = '';
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === '\\') {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (start < 0) {
+            if (ch === '{' || ch === '[') {
+                start = i;
+                open = ch;
+                close = ch === '{' ? '}' : ']';
+                depth = 1;
+            }
+            continue;
+        }
+        if (ch === open) {
+            depth++;
+        }
+        else if (ch === close) {
+            depth--;
+            if (depth === 0) {
+                return text.slice(start, i + 1);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:
+ *
+ * - Leading/trailing whitespace and a leading byte-order mark.
+ * - Markdown code fences (with or without a language tag).
+ * - Conversational preamble before the first `{` or `[`.
+ * - Trailing prose after the matched closing `}` or `]`.
+ *
+ * Out of scope: repairing malformed JSON, handling smart quotes, etc.
+ *
+ * @param text - Raw model output.
+ * @returns A `Result<string>` containing the JSON-shaped substring, or a
+ * `Failure` if no JSON-shaped substring was found.
+ * @public
+ */
+const extractJsonText = (text) => {
+    if (typeof text !== 'string') {
+        return (0, ts_utils_1.fail)('extractJsonText: input must be a string.');
+    }
+    const stripped = stripBom(text).trim();
+    if (stripped.length === 0) {
+        return (0, ts_utils_1.fail)('extractJsonText: input is empty.');
+    }
+    const fenced = FENCED_BLOCK.exec(stripped);
+    const candidate = fenced ? fenced[1].trim() : stripped;
+    if (candidate.length === 0) {
+        return (0, ts_utils_1.fail)('extractJsonText: no JSON content found.');
+    }
+    // Whole-candidate primitive check runs before the brace scan so that a
+    // valid JSON string containing braces (e.g. `"text with { }"`) is returned
+    // intact instead of being mangled into the first balanced `{ }` match.
+    if (JSON_KEYWORD.test(candidate) || JSON_NUMBER.test(candidate) || JSON_STRING.test(candidate)) {
+        return (0, ts_utils_1.succeed)(candidate);
+    }
+    const balanced = findBalancedJsonSubstring(candidate);
+    if (balanced !== undefined) {
+        return (0, ts_utils_1.succeed)(balanced);
+    }
+    return (0, ts_utils_1.fail)('extractJsonText: no JSON-shaped substring found.');
+};
+exports.extractJsonText = extractJsonText;
+function fencedStringifiedJson(options) {
+    var _a;
+    const extractor = (_a = options === null || options === void 0 ? void 0 : options.extractor) !== null && _a !== void 0 ? _a : exports.extractJsonText;
+    const inner = options === null || options === void 0 ? void 0 : options.inner;
+    const parser = inner !== undefined ? ts_json_base_1.Converters.stringifiedJson(inner) : ts_json_base_1.Converters.stringifiedJson();
+    return new ts_utils_1.Conversion.BaseConverter((from) => {
+        if (typeof from !== 'string') {
+            return (0, ts_utils_1.fail)('fencedStringifiedJson: input must be a string.');
+        }
+        return extractor(from).onSuccess((extracted) => parser.convert(extracted));
+    });
+}
+//# sourceMappingURL=jsonResponse.js.map

package/lib/packlets/ai-assist/jsonResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonResponse.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/jsonResponse.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * JSON-tolerant extraction and converters for LLM responses.\n *\n * Models commonly wrap JSON output in Markdown code fences, add a\n * \"Sure, here's the JSON:\" preamble, or trail off with prose after the\n * closing brace. These helpers normalize that quirk on the read side so every\n * AiAssist consumer can reach a validated `T` from raw model text without\n * reimplementing the same fence-stripping logic.\n *\n * Scope: strip wrappers (fences, prose, BOM, whitespace). Out of scope: repair\n * malformed JSON (missing commas, unquoted keys, smart quotes, etc.).\n *\n * @packageDocumentation\n */\n\nimport { Conversion, type Converter, fail, Result, succeed, type Validator } from '@fgv/ts-utils';\nimport { Converters as JsonBaseConverters, type JsonValue } from '@fgv/ts-json-base';\n\n/**\n * A function that pulls a JSON-shaped substring out of arbitrary model text.\n * Implementations strip whatever wrappers the model added (fences, preamble,\n * trailing prose) and return the JSON-shaped substring ready for `JSON.parse`.\n * @public\n */\nexport type JsonTextExtractor = (text: string) => Result<string>;\n\nconst FENCED_BLOCK: RegExp = /```[A-Za-z0-9_-]*\\s*\\r?\\n([\\s\\S]*?)\\r?\\n?```/;\nconst BOM: RegExp = /^\\uFEFF/;\n// Full RFC 8259 grammar so the extractor only succeeds when the entire\n// candidate parses as a JSON primitive (instead of just starting like one).\nconst JSON_NUMBER: RegExp = /^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$/;\n// eslint-disable-next-line no-control-regex\nconst JSON_STRING: RegExp = /^\"(?:[^\"\\\\\\u0000-\\u001F]|\\\\(?:[\"\\\\/bfnrt]|u[0-9a-fA-F]{4}))*\"$/;\nconst JSON_KEYWORD: RegExp = /^(?:true|false|null)$/;\n\nfunction stripBom(text: string): string {\n  return text.replace(BOM, '');\n}\n\nfunction findBalancedJsonSubstring(text: string): string | undefined {\n  // Walk the text once tracking string state. The first '{' or '[' that is\n  // *outside* a quoted string is the candidate start; from there, count\n  // matching close characters while ignoring delimiters that appear inside\n  // strings.\n  let inString = false;\n  let escape = false;\n  let start = -1;\n  let open = '';\n  let close = '';\n  let depth = 0;\n  for (let i = 0; i < text.length; i++) {\n    const ch = text.charAt(i);\n    if (inString) {\n      if (escape) {\n        escape = false;\n      } else if (ch === '\\\\') {\n        escape = true;\n      } else if (ch === '\"') {\n        inString = false;\n      }\n      continue;\n    }\n    if (ch === '\"') {\n      inString = true;\n      continue;\n    }\n    if (start < 0) {\n      if (ch === '{' || ch === '[') {\n        start = i;\n        open = ch;\n        close = ch === '{' ? '}' : ']';\n        depth = 1;\n      }\n      continue;\n    }\n    if (ch === open) {\n      depth++;\n    } else if (ch === close) {\n      depth--;\n      if (depth === 0) {\n        return text.slice(start, i + 1);\n      }\n    }\n  }\n  return undefined;\n}\n\n/**\n * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:\n *\n * - Leading/trailing whitespace and a leading byte-order mark.\n * - Markdown code fences (with or without a language tag).\n * - Conversational preamble before the first `{` or `[`.\n * - Trailing prose after the matched closing `}` or `]`.\n *\n * Out of scope: repairing malformed JSON, handling smart quotes, etc.\n *\n * @param text - Raw model output.\n * @returns A `Result<string>` containing the JSON-shaped substring, or a\n * `Failure` if no JSON-shaped substring was found.\n * @public\n */\nexport const extractJsonText: JsonTextExtractor = (text: string): Result<string> => {\n  if (typeof text !== 'string') {\n    return fail('extractJsonText: input must be a string.');\n  }\n  const stripped = stripBom(text).trim();\n  if (stripped.length === 0) {\n    return fail('extractJsonText: input is empty.');\n  }\n\n  const fenced = FENCED_BLOCK.exec(stripped);\n  const candidate = fenced ? fenced[1].trim() : stripped;\n\n  if (candidate.length === 0) {\n    return fail('extractJsonText: no JSON content found.');\n  }\n\n  // Whole-candidate primitive check runs before the brace scan so that a\n  // valid JSON string containing braces (e.g. `\"text with { }\"`) is returned\n  // intact instead of being mangled into the first balanced `{ }` match.\n  if (JSON_KEYWORD.test(candidate) || JSON_NUMBER.test(candidate) || JSON_STRING.test(candidate)) {\n    return succeed(candidate);\n  }\n\n  const balanced = findBalancedJsonSubstring(candidate);\n  if (balanced !== undefined) {\n    return succeed(balanced);\n  }\n\n  return fail('extractJsonText: no JSON-shaped substring found.');\n};\n\n/**\n * Options shared by every {@link AiAssist.fencedStringifiedJson} call.\n * @public\n */\nexport interface IFencedStringifiedJsonExtractorOptions {\n  /**\n   * Optional pre-parse extractor. Defaults to {@link AiAssist.extractJsonText}.\n   * Provide a custom extractor to handle response shapes the default does not\n   * understand.\n   */\n  readonly extractor?: JsonTextExtractor;\n}\n\n/**\n * Options for the validating overload of {@link AiAssist.fencedStringifiedJson}.\n * `inner` is required so the typed `Converter<T>` return value can never lie\n * about the runtime shape.\n * @public\n */\nexport interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJsonExtractorOptions {\n  /** Inner converter or validator applied to the parsed JSON value. */\n  readonly inner: Converter<T> | Validator<T>;\n}\n\n/**\n * Creates a `Converter` that accepts raw LLM response text, runs it through a\n * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the\n * extracted substring as JSON, and applies an optional inner converter or\n * validator.\n *\n * @example\n * ```ts\n * const converter = fencedStringifiedJson({ inner: myShapeConverter });\n * const result = converter.convert(llmText); // Result<MyShape>\n * ```\n *\n * @param options - Optional extractor; omit to keep the default. Without an\n * `inner` step, the converter resolves to the parsed `JsonValue`.\n * @returns A `Converter<JsonValue>`.\n * @public\n */\nexport function fencedStringifiedJson(options?: IFencedStringifiedJsonExtractorOptions): Converter<JsonValue>;\n/**\n * Creates a `Converter` that accepts raw LLM response text, runs it through a\n * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the\n * extracted substring as JSON, and applies the supplied inner converter or\n * validator.\n *\n * @param options - Required `inner` converter/validator and optional extractor.\n * @returns A `Converter<T>`.\n * @public\n */\nexport function fencedStringifiedJson<T>(options: IFencedStringifiedJsonOptions<T>): Converter<T>;\nexport function fencedStringifiedJson<T>(\n  options?: IFencedStringifiedJsonExtractorOptions | IFencedStringifiedJsonOptions<T>\n): Converter<T | JsonValue> {\n  const extractor: JsonTextExtractor = options?.extractor ?? extractJsonText;\n  const inner = (options as IFencedStringifiedJsonOptions<T> | undefined)?.inner;\n  const parser: Converter<T | JsonValue> =\n    inner !== undefined ? JsonBaseConverters.stringifiedJson<T>(inner) : JsonBaseConverters.stringifiedJson();\n\n  return new Conversion.BaseConverter<T | JsonValue>((from: unknown): Result<T | JsonValue> => {\n    if (typeof from !== 'string') {\n      return fail('fencedStringifiedJson: input must be a string.');\n    }\n    return extractor(from).onSuccess((extracted) => parser.convert(extracted));\n  });\n}\n"]}

package/lib/packlets/crypto-utils/keystore/keyStore.d.ts

@@ -1,6 +1,6 @@
 import { JsonValue } from '@fgv/ts-json-base';
 import { Result } from '@fgv/ts-utils';
-import { ICryptoProvider, IEncryptedFile, IEncryptionConfig, IEncryptionProvider, SecretProvider } from '../model';
+import { ICryptoProvider, IEncryptedFile, IEncryptionConfig, IEncryptionProvider, IKeyDerivationParams, SecretProvider } from '../model';
 import { IAddKeyPairOptions, IAddKeyPairResult, IAddSecretFromPasswordOptions, IAddSecretFromPasswordResult, IAddSecretOptions, IAddSecretResult, IImportKeyOptions, IImportSecretOptions, IKeyStoreCreateParams, IKeyStoreEntry, IKeyStoreFile, IKeyStoreOpenParams, IRemoveSecretResult, KeyStoreLockState, KeyStoreSecretType } from './model';
 /**
  * Password-protected key store for managing encryption secrets.
@@ -196,6 +196,41 @@ export declare class KeyStore implements IEncryptionProvider {
      * @public
      */
     addSecretFromPassword(name: string, password: string, options?: IAddSecretFromPasswordOptions): Promise<Result<IAddSecretFromPasswordResult>>;
+    /**
+     * Verifies that a candidate password derives the same key material currently
+     * stored under `name`, using the supplied
+     * {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     *
+     * The keystore does not persist per-slot key derivation parameters with the
+     * entry — callers receive them from `addSecretFromPassword` and store them
+     * alongside the encrypted artifact (or wherever else makes sense). Pass
+     * those same parameters here for verification.
+     *
+     * Re-derives a key from `password` + `keyDerivation`, then compares it to
+     * the stored key material in constant time. Restricted to entries of type
+     * `'encryption-key'` — the type produced by `addSecretFromPassword`. Other
+     * symmetric types (`'api-key'`) and asymmetric entries are rejected so
+     * the boolean result reflects "this slot accepts this password" rather
+     * than an incidental byte-equality match against unrelated material.
+     *
+     * Note: the keystore does not currently flag whether an `'encryption-key'`
+     * entry was actually password-derived (vs. random via `addSecret` or raw
+     * via `importSecret`). A `true` result therefore means "the candidate
+     * password produces the same 32 bytes currently stored", which is what
+     * the equivalent consumer-side helper (`verifyGatePassword`) already
+     * implies for entries it manages.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param keyDerivation - The key derivation parameters returned by
+     * `addSecretFromPassword` when the secret was created. Only
+     * `kdf: 'pbkdf2'` is supported.
+     * @returns Success(true) when the candidate matches the stored key,
+     * Success(false) when it does not, Failure if locked, secret missing,
+     * wrong type, unsupported `kdf`, or key derivation fails
+     * @public
+     */
+    verifySecretFromPassword(name: string, password: string, keyDerivation: IKeyDerivationParams): Promise<Result<boolean>>;
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
@@ -342,6 +377,13 @@ export declare class KeyStore implements IEncryptionProvider {
      * @returns A warning string if storage cleanup failed, otherwise undefined.
      */
     private _releaseEntryResources;
+    /**
+     * Constant-time byte comparison. Returns false immediately for length
+     * mismatch (length is not secret); for equal-length inputs, walks the full
+     * buffer accumulating differences via XOR so the running time does not leak
+     * the position of the first differing byte.
+     */
+    private static _timingSafeEqual;
     /**
      * Mints a fresh UUID v4 storage handle using the crypto provider's
      * {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes}.

package/lib/packlets/crypto-utils/keystore/keyStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyStore.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/keyStore.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAuB,MAAM,EAAW,MAAM,eAAe,CAAC;AAGrE,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAGL,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EAEpB,qBAAqB,EACrB,cAAc,EAEd,aAAa,EACb,mBAAmB,EAGnB,mBAAmB,EAEnB,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,SAAS,CAAC;AAejB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,QAAS,YAAW,mBAAmB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,MAAM,CAAU;IAExB,OAAO;IAoBP;;;;;;OAMG;WACW,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAAC,QAAQ,CAAC;IAUrE;;;;;;OAMG;WACW,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC;IAiBjE;;;;;;;OAOG;IACU,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IA0BpE;;;;;;OAMG;IACU,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IA8BhE;;;;;;;;;;;;;OAaG;IACU,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAkB7E;;;;;OAKG;IACI,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;IA0B9C;;;OAGG;IACH,IAAW,UAAU,IAAI,OAAO,CAE/B;IAED;;;OAGG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;;OAKG;IACH,IAAW,KAAK,IAAI,OAAO,CAE1B;IAED;;;OAGG;IACH,IAAW,KAAK,IAAI,iBAAiB,CAEpC;IAED;;;;OAIG;IACH,IAAW,cAAc,IAAI,eAAe,CAE3C;IAMD;;;;OAIG;IACI,WAAW,IAAI,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC;IAO/C;;;;;;;OAOG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC;IAWtD;;;;;;;OAOG;IACI,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;IAcxD;;;;;OAKG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAO/C;;;;;;OAMG;IACU,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAgCpG;;;;;;;;;;;;;OAaG;IACU,YAAY,CACvB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,UAAU,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IA+BpC;;;;;;;;;;;;;OAaG;IACU,qBAAqB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC;IAwDhD;;;;;;;;;OASG;IACU,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAmB7E;;;;;;;;OAQG;IACU,YAAY,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAgCpC;;;;;;OAMG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAmB9C;;;;;;;;;;;;;;;;;;OAkBG;IACU,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IA+DtG;;;;;;;;;;OAUG;IACU,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,UAAU,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IA6BvG;;;;;OAKG;IACI,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,SAAS,MAAM,EAAE,CAAC;IAa7E;;;;;;OAMG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC;IAmC7E;;;;;;OAMG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAkBnE;;;;;;;;;;;;OAYG;IACU,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAWhF;;;;;;;OAOG;IACU,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAuEpG,sDAAsD;IACzC,aAAa,CAAC,SAAS,GAAG,SAAS,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,EAClB,QAAQ,CAAC,EAAE,SAAS,GACnB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;IAwB7C;;;;;OAKG;IACI,iBAAiB,IAAI,MAAM,CAAC,cAAc,CAAC;IAoBlD;;;;OAIG;IACI,mBAAmB,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,gBAAgB,CAAC,CAAC;IAgBlG;;;OAGG;YACW,aAAa;IAqE3B;;;OAGG;YACW,aAAa;IA4F3B;;;;;;;;;OASG;YACW,sBAAsB;IAepC;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAkBpB"}
+{"version":3,"file":"keyStore.d.ts","sourceRoot":"","sources":["../../../../src/packlets/crypto-utils/keystore/keyStore.ts"],"names":[],"mappings":"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"}

package/lib/packlets/crypto-utils/keystore/keyStore.js

@@ -505,6 +505,68 @@ class KeyStore {
             }
         });
     }
+    /**
+     * Verifies that a candidate password derives the same key material currently
+     * stored under `name`, using the supplied
+     * {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.
+     *
+     * The keystore does not persist per-slot key derivation parameters with the
+     * entry — callers receive them from `addSecretFromPassword` and store them
+     * alongside the encrypted artifact (or wherever else makes sense). Pass
+     * those same parameters here for verification.
+     *
+     * Re-derives a key from `password` + `keyDerivation`, then compares it to
+     * the stored key material in constant time. Restricted to entries of type
+     * `'encryption-key'` — the type produced by `addSecretFromPassword`. Other
+     * symmetric types (`'api-key'`) and asymmetric entries are rejected so
+     * the boolean result reflects "this slot accepts this password" rather
+     * than an incidental byte-equality match against unrelated material.
+     *
+     * Note: the keystore does not currently flag whether an `'encryption-key'`
+     * entry was actually password-derived (vs. random via `addSecret` or raw
+     * via `importSecret`). A `true` result therefore means "the candidate
+     * password produces the same 32 bytes currently stored", which is what
+     * the equivalent consumer-side helper (`verifyGatePassword`) already
+     * implies for entries it manages.
+     *
+     * @param name - Name of the secret to verify against
+     * @param password - Candidate password to test
+     * @param keyDerivation - The key derivation parameters returned by
+     * `addSecretFromPassword` when the secret was created. Only
+     * `kdf: 'pbkdf2'` is supported.
+     * @returns Success(true) when the candidate matches the stored key,
+     * Success(false) when it does not, Failure if locked, secret missing,
+     * wrong type, unsupported `kdf`, or key derivation fails
+     * @public
+     */
+    async verifySecretFromPassword(name, password, keyDerivation) {
+        if (!this._secrets) {
+            return (0, ts_utils_1.fail)('Key store is locked');
+        }
+        if (!password || password.length === 0) {
+            return (0, ts_utils_1.fail)('Password cannot be empty');
+        }
+        if (keyDerivation.kdf !== 'pbkdf2') {
+            return (0, ts_utils_1.fail)(`Unsupported kdf '${keyDerivation.kdf}' (expected 'pbkdf2')`);
+        }
+        const entry = this._secrets.get(name);
+        if (!entry) {
+            return (0, ts_utils_1.fail)(`Secret '${name}' not found`);
+        }
+        if (entry.type !== 'encryption-key') {
+            return (0, ts_utils_1.fail)(`Secret '${name}' is not a password-verifiable encryption key (type: ${entry.type})`);
+        }
+        const saltResult = this._cryptoProvider.fromBase64(keyDerivation.salt);
+        if (saltResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Invalid salt: ${saltResult.message}`);
+        }
+        const derivedResult = await this._cryptoProvider.deriveKey(password, saltResult.value, keyDerivation.iterations);
+        /* c8 ignore next 3 - crypto provider errors covered in nodeCryptoProvider tests */
+        if (derivedResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Key derivation failed: ${derivedResult.message}`);
+        }
+        return (0, ts_utils_1.succeed)(KeyStore._timingSafeEqual(derivedResult.value, entry.key));
+    }
     /**
      * Removes a secret by name. Vault-first: the in-memory vault entry is dropped
      * before any storage cleanup runs. For asymmetric-keypair entries, best-effort
@@ -1085,6 +1147,25 @@ class KeyStore {
         entry.key.fill(0);
         return undefined;
     }
+    /**
+     * Constant-time byte comparison. Returns false immediately for length
+     * mismatch (length is not secret); for equal-length inputs, walks the full
+     * buffer accumulating differences via XOR so the running time does not leak
+     * the position of the first differing byte.
+     */
+    static _timingSafeEqual(a, b) {
+        /* c8 ignore next 3 - defensive: callers in this class only compare
+           PBKDF2-derived 32-byte keys against encryption-key entries (also 32 bytes) */
+        if (a.length !== b.length) {
+            return false;
+        }
+        let diff = 0;
+        for (let i = 0; i < a.length; i++) {
+            // eslint-disable-next-line no-bitwise
+            diff |= a[i] ^ b[i];
+        }
+        return diff === 0;
+    }
     /**
      * Mints a fresh UUID v4 storage handle using the crypto provider's
      * {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes}.