@jini-ai/platform 0.5.9 → 0.5.10

package/dist/object-store/local-fs.js

@@ -0,0 +1,146 @@
+/**
+ * @file The default `local` object-store provider: keys are paths under one root directory.
+ *
+ * Path formula is `join(rootDir, key)` — byte-identical to `@jini-ai/cms`'s `LocalFsBlobStore`
+ * (`resolvePath`), so a host that moves its media from that class to this store reads every
+ * existing upload unchanged (no data migration). Unlike that class, keys here come from callers,
+ * so a key that would resolve outside `rootDir` (`..`, absolute) is refused before any syscall.
+ *
+ * Lexical containment alone is not enough: `<root>/link -> /elsewhere` makes `link/victim` look
+ * contained while every syscall follows the link out of the root. So each operation also checks
+ * the key's parent *physically* (realpath of its nearest existing ancestor against the realpath
+ * of the root), and the final component is opened with `O_NOFOLLOW` / `lstat`ed, so a symlink
+ * planted as the object itself is refused rather than followed.
+ */
+import { constants } from 'node:fs';
+import { lstat, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { providerOk } from '@jini-ai/core/provider-registry';
+/** Node's errno-carrying error, narrowed without a cast at each call site. */
+function errnoCode(error) {
+    return error?.code;
+}
+/**
+ * Resolves `key` under `rootDir`, refusing any key that escapes it.
+ * @throws {Error} The key is empty, absolute, or resolves outside the root.
+ * @complexity O(key length).
+ */
+function contained(required) {
+    const { rootDir, key } = required;
+    const path = join(rootDir, key);
+    const rel = relative(resolve(rootDir), resolve(path));
+    if (key === '' || isAbsolute(key) || rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`object key '${key}' is outside the store root`);
+    }
+    return path;
+}
+// `O_NOFOLLOW` makes the open itself fail (`ELOOP`) when the final component is a symlink, so a link
+// swapped in after the containment check cannot redirect the read/write. Where the platform lacks it
+// (Windows) the constant is undefined, which a bitwise OR coerces to 0 — degrading to the physical
+// parent check alone.
+const NOFOLLOW = constants.O_NOFOLLOW;
+const READ_FLAGS = constants.O_RDONLY | NOFOLLOW;
+const WRITE_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | NOFOLLOW;
+const CREATE_ONLY_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW;
+/**
+ * Realpath of `path`, or of its nearest existing ancestor with the missing tail re-appended.
+ * Recursion terminates because the filesystem root always exists; any fault other than absence
+ * (`ENOTDIR`, `EACCES`, `ELOOP`) rejects.
+ * @complexity O(depth) syscalls.
+ */
+async function realpathOfNearest(required) {
+    const { path } = required;
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (errnoCode(error) !== 'ENOENT')
+            throw error;
+        return join(await realpathOfNearest({ path: dirname(path) }), basename(path));
+    }
+}
+/**
+ * Resolves `key` lexically, then refuses it unless its parent directory is physically inside the
+ * root (so a directory symlink pointing out of the root cannot be traversed).
+ * @throws {Error} The key escapes the root lexically or through a symlinked ancestor.
+ * @complexity O(depth) syscalls.
+ */
+async function physicallyContained(required) {
+    const path = contained(required);
+    const realRoot = await realpathOfNearest({ path: resolve(required.rootDir) });
+    const rel = relative(realRoot, await realpathOfNearest({ path: dirname(resolve(path)) }));
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`object key '${required.key}' is outside the store root`);
+    }
+    return path;
+}
+/**
+ * Creates a local-filesystem `ObjectStore` rooted at `rootDir`.
+ * @complexity Each call is O(1) syscalls beyond the read/write itself.
+ */
+export function createLocalFsObjectStore(required, _optional = {}) {
+    const { rootDir } = required;
+    const pathOf = (key) => physicallyContained({ rootDir, key });
+    return {
+        async put({ key, bytes }, options = {}) {
+            const path = await pathOf(key);
+            await mkdir(dirname(path), { recursive: true });
+            if (!options.ifAbsent) {
+                await writeFile(path, bytes, { flag: WRITE_FLAGS });
+                return { written: true };
+            }
+            // `O_CREAT | O_EXCL` (`"wx"`) makes create-only a kernel-enforced atomic op: of two racing
+            // opens of the same path exactly one succeeds and the other gets `EEXIST`, so there is no
+            // window between "check" and "write" for a concurrent writer to land in.
+            try {
+                await writeFile(path, bytes, { flag: CREATE_ONLY_FLAGS });
+                return { written: true };
+            }
+            catch (error) {
+                if (errnoCode(error) === 'EEXIST')
+                    return { written: false };
+                throw error;
+            }
+        },
+        async get({ key }) {
+            try {
+                return new Uint8Array(await readFile(await pathOf(key), { flag: READ_FLAGS }));
+            }
+            catch (error) {
+                if (errnoCode(error) === 'ENOENT')
+                    return null;
+                throw error;
+            }
+        },
+        // Only ENOENT is absence; EACCES/ENOTDIR/EIO reject, so a caller never mistakes "this stat
+        // failed" for "the object was deleted". `lstat` (not `stat`) so a symlink is reported as a
+        // refusal instead of the size of whatever it points at.
+        async head({ key }) {
+            try {
+                const info = await lstat(await pathOf(key));
+                if (info.isSymbolicLink())
+                    throw new Error(`object key '${key}' is a symbolic link`);
+                return { size: info.size };
+            }
+            catch (error) {
+                if (errnoCode(error) === 'ENOENT')
+                    return null;
+                throw error;
+            }
+        },
+        // `rm` unlinks a final-component symlink itself and never its target; the physical parent check
+        // keeps it from deleting through a symlinked directory.
+        async delete({ key }) {
+            await rm(await pathOf(key), { force: true });
+        },
+    };
+}
+/**
+ * The `local` provider bound to one root directory (the host owns where bytes live; settings and
+ * credentials are ignored — local storage needs neither).
+ * @complexity O(1).
+ */
+export function createLocalFsObjectStoreProvider(required, _optional = {}) {
+    return { create: () => providerOk({ value: createLocalFsObjectStore({ rootDir: required.rootDir }) }) };
+}
+//# sourceMappingURL=local-fs.js.map

package/dist/process.js

@@ -229,6 +229,7 @@ function parsePsOutput(stdout) {
 /** @internal Enumerate process snapshots on POSIX via `ps`. */
 async function listPosixProcessSnapshots() {
     const stdout = await new Promise((resolveList, rejectList) => {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed process-enumeration utility intentionally uses the trusted host PATH; command and argv are code-owned.
         execFile("ps", ["-axo", "pid=,ppid=,command="], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (error, out) => {
             if (error)
                 rejectList(error);
@@ -245,6 +246,7 @@ async function listWindowsProcessSnapshots() {
         "Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId, CommandLine | ConvertTo-Json -Compress",
     ].join("; ");
     const stdout = await new Promise((resolveList, rejectList) => {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed process-enumeration utility intentionally uses the trusted host PATH; command and argv are code-owned.
         execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (error, out) => {
             if (error)
                 rejectList(error);

package/dist/proxy-env.js

@@ -60,21 +60,7 @@ function setCanonicalProxyEnvValue(env, canonicalKey, value, platform) {
 export function mergeProxyAwareEnv(platform, ...sources) {
     const merged = {};
     for (const source of sources) {
-        const proxyEntries = new Map();
-        for (const [key, value] of Object.entries(source)) {
-            if (value == null)
-                continue;
-            const canonicalKey = canonicalProxyEnvKey(key);
-            if (canonicalKey) {
-                const current = proxyEntries.get(canonicalKey);
-                const preferLowercase = key === key.toLowerCase();
-                if (!current || preferLowercase || !current.preferLowercase) {
-                    proxyEntries.set(canonicalKey, { preferLowercase, value });
-                }
-                continue;
-            }
-            merged[key] = value;
-        }
+        const proxyEntries = collectSourceProxyEntries({ merged, source });
         for (const [canonicalKey, entry] of proxyEntries) {
             setCanonicalProxyEnvValue(merged, canonicalKey, entry.value, platform);
         }
@@ -84,6 +70,26 @@ export function mergeProxyAwareEnv(platform, ...sources) {
     }
     return merged;
 }
+/** @internal Copy one source's non-proxy keys into `merged` and return its proxy values keyed by canonical name,
+ *  preferring a lowercase spelling when a source carries several case-variants of the same variable. */
+function collectSourceProxyEntries(input) {
+    const proxyEntries = new Map();
+    for (const [key, value] of Object.entries(input.source)) {
+        if (value == null)
+            continue;
+        const canonicalKey = canonicalProxyEnvKey(key);
+        if (!canonicalKey) {
+            input.merged[key] = value;
+            continue;
+        }
+        const current = proxyEntries.get(canonicalKey);
+        const preferLowercase = key === key.toLowerCase();
+        if (!current || preferLowercase || !current.preferLowercase) {
+            proxyEntries.set(canonicalKey, { preferLowercase, value });
+        }
+    }
+    return proxyEntries;
+}
 /** @internal Whether `env` already contains any case-variant of the given canonical proxy key. */
 function hasCanonicalProxyEnv(env, canonicalKey) {
     return Object.keys(env).some((key) => key.toLowerCase() === canonicalKey.toLowerCase());
@@ -179,29 +185,28 @@ function normalizeHostPortProxyUrl(host, port, scheme) {
         : trimmedHost;
     return normalizeProxyUrl(`${normalizedHost}:${trimmedPort}`, scheme);
 }
+/** @internal The NO_PROXY value for a system proxy: a preserved wildcard, else the bypass list plus loopback hosts. */
+function systemNoProxyValue(noProxy) {
+    return (preserveWildcardNoProxyValue(noProxy) ??
+        buildNoProxyValue([...(noProxy ? noProxy.split(",") : []), "localhost", "127.0.0.1", "[::1]"]));
+}
 /** @internal Assemble the final proxy env from parsed values, adding loopback bypasses and the `NODE_USE_ENV_PROXY` flag. */
 function finalizeSystemProxyEnv(values, platform) {
-    const hasProxy = Boolean(values.httpProxy || values.httpsProxy || values.allProxy);
-    const noProxy = hasProxy
-        ? preserveWildcardNoProxyValue(values.noProxy) ??
-            buildNoProxyValue([
-                ...(values.noProxy ? values.noProxy.split(",") : []),
-                "localhost",
-                "127.0.0.1",
-                "[::1]",
-            ])
-        : null;
     const env = {};
-    if (values.httpProxy)
-        addProxyEnvValue(env, "HTTP_PROXY", values.httpProxy, platform);
-    if (values.httpsProxy)
-        addProxyEnvValue(env, "HTTPS_PROXY", values.httpsProxy, platform);
-    if (values.allProxy)
-        addProxyEnvValue(env, "ALL_PROXY", values.allProxy, platform);
-    if (noProxy)
-        addProxyEnvValue(env, "NO_PROXY", noProxy, platform);
-    if (hasProxy)
-        env.NODE_USE_ENV_PROXY = "1";
+    const hasProxy = Boolean(values.httpProxy || values.httpsProxy || values.allProxy);
+    if (!hasProxy)
+        return env;
+    const entries = [
+        ["HTTP_PROXY", values.httpProxy],
+        ["HTTPS_PROXY", values.httpsProxy],
+        ["ALL_PROXY", values.allProxy],
+        ["NO_PROXY", systemNoProxyValue(values.noProxy)],
+    ];
+    for (const [key, value] of entries) {
+        if (value)
+            addProxyEnvValue(env, key, value, platform);
+    }
+    env.NODE_USE_ENV_PROXY = "1";
     return env;
 }
 /**
@@ -214,55 +219,84 @@ function finalizeSystemProxyEnv(values, platform) {
  * @returns A normalized proxy environment (empty when no proxy is enabled).
  */
 export function parseMacosScutilProxyOutput(stdout, platform = "darwin") {
-    const scalars = new Map();
-    const exceptions = [];
-    let inExceptions = false;
-    for (const rawLine of stdout.split(/\r?\n/)) {
-        const line = rawLine.trim();
-        if (!line)
-            continue;
-        if (/^ExceptionsList\s*:\s*<array>\s*\{$/.test(line)) {
-            inExceptions = true;
-            continue;
-        }
-        if (inExceptions) {
-            if (line === "}") {
-                inExceptions = false;
-                continue;
-            }
-            const match = line.match(/^\d+\s*:\s*(.+)$/);
-            if (match)
-                exceptions.push(match[1].trim());
-            continue;
-        }
-        const match = line.match(/^([A-Za-z][A-Za-z0-9]*)\s*:\s*(.+)$/);
-        if (match)
-            scalars.set(match[1], match[2].trim());
-    }
-    const httpProxy = scalars.get("HTTPEnable") === "1"
-        ? normalizeHostPortProxyUrl(scalars.get("HTTPProxy"), scalars.get("HTTPPort"), "http")
-        : null;
-    const httpsProxy = scalars.get("HTTPSEnable") === "1"
-        ? normalizeHostPortProxyUrl(scalars.get("HTTPSProxy"), scalars.get("HTTPSPort"), "http")
-        : null;
-    const allProxy = scalars.get("SOCKSEnable") === "1"
-        ? normalizeHostPortProxyUrl(scalars.get("SOCKSProxy"), scalars.get("SOCKSPort"), "socks5")
-        : null;
+    const { exceptions, scalars } = parseScutilLines(stdout);
     return finalizeSystemProxyEnv({
-        allProxy,
-        httpProxy,
-        httpsProxy,
+        allProxy: scutilEnabledProxy({ prefix: "SOCKS", scalars, scheme: "socks5" }),
+        httpProxy: scutilEnabledProxy({ prefix: "HTTP", scalars, scheme: "http" }),
+        httpsProxy: scutilEnabledProxy({ prefix: "HTTPS", scalars, scheme: "http" }),
         noProxy: buildNoProxyValue([
             ...exceptions,
             ...(scalars.get("ExcludeSimpleHostnames") === "1" ? ["<local>"] : []),
         ]),
     }, platform);
 }
+/** @internal Split `scutil --proxy` output into its `Name : value` scalars and its `ExceptionsList` array entries. */
+function parseScutilLines(stdout) {
+    const scalars = new Map();
+    const exceptions = [];
+    let inExceptions = false;
+    // Blank lines need no explicit skip: they match neither the array-entry nor
+    // the scalar pattern, and are not the closing `}`.
+    for (const line of stdout.split(/\r?\n/).map((rawLine) => rawLine.trim())) {
+        if (/^ExceptionsList\s*:\s*<array>\s*\{$/.test(line))
+            inExceptions = true;
+        else if (inExceptions)
+            inExceptions = collectScutilException(line, exceptions);
+        else
+            collectScutilScalar(line, scalars);
+    }
+    return { exceptions, scalars };
+}
+/** @internal Record one `N : value` ExceptionsList entry; returns whether the array is still open (false on `}`). */
+function collectScutilException(line, exceptions) {
+    const match = line.match(/^\d+\s*:\s*(.+)$/);
+    if (match)
+        exceptions.push(match[1].trim());
+    return line !== "}";
+}
+/** @internal Record one top-level `Name : value` scutil scalar, ignoring lines of any other shape. */
+function collectScutilScalar(line, scalars) {
+    const match = line.match(/^([A-Za-z][A-Za-z0-9]*)\s*:\s*(.+)$/);
+    if (match)
+        scalars.set(match[1], match[2].trim());
+}
+/** @internal The `<prefix>Proxy`/`<prefix>Port` URL when `<prefix>Enable` is `1`, else `null`. */
+function scutilEnabledProxy(input) {
+    const { prefix, scalars, scheme } = input;
+    if (scalars.get(`${prefix}Enable`) !== "1")
+        return null;
+    return normalizeHostPortProxyUrl(scalars.get(`${prefix}Proxy`), scalars.get(`${prefix}Port`), scheme);
+}
 /** @internal Extract a `reg query` value line (`Name REG_TYPE value`) for the named value, or `null` if absent. */
 function parseRegistryValue(stdout, valueName) {
     const match = stdout.match(new RegExp(`^\\s*${valueName}\\s+REG_\\w+\\s+(.+)$`, "m"));
     return match ? match[1].trim() : null;
 }
+/** @internal Per-protocol `ProxyServer` kinds mapped to the env slot and default scheme they fill. */
+const WINDOWS_PROXY_KINDS = new Map([
+    ["http", { scheme: "http", slot: "httpProxy" }],
+    ["https", { scheme: "http", slot: "httpsProxy" }],
+    ["socks", { scheme: "socks5", slot: "allProxy" }],
+]);
+/** @internal Parse the per-protocol `http=…;https=…;socks=…` `ProxyServer` form; later segments win, unknown kinds are skipped. */
+function parsePerProtocolProxyServer(proxyServer) {
+    const proxies = {};
+    for (const segment of proxyServer.split(";")) {
+        const [kind, rawValue] = segment.split("=", 2);
+        const value = rawValue?.trim();
+        if (!kind || !value)
+            continue;
+        const target = WINDOWS_PROXY_KINDS.get(kind.trim().toLowerCase());
+        if (target)
+            proxies[target.slot] = normalizeAuthorityProxyUrl(value, target.scheme);
+    }
+    return proxies;
+}
+/** @internal The single-endpoint `ProxyServer` form, shared by HTTP and HTTPS. */
+function sharedProxyServer(proxyServer) {
+    const shared = normalizeAuthorityProxyUrl(proxyServer, "http");
+    return { httpProxy: shared, httpsProxy: shared };
+}
 /**
  * Parse Windows Internet Settings proxy registry output into a normalized proxy
  * environment. Handles both the per-protocol (`http=…;https=…`) and shared
@@ -280,36 +314,16 @@ export function parseWindowsInternetSettingsProxyOutput(input, platform = "win32
     const proxyOverride = parseRegistryValue(input.proxyOverride ?? "", "ProxyOverride") ?? "";
     if (!proxyServer.trim())
         return {};
-    let httpProxy = null;
-    let httpsProxy = null;
-    let allProxy = null;
-    if (proxyServer.includes("=")) {
-        for (const segment of proxyServer.split(";")) {
-            const [kind, rawValue] = segment.split("=", 2);
-            const value = rawValue?.trim();
-            if (!kind || !value)
-                continue;
-            const lowerKind = kind.trim().toLowerCase();
-            if (lowerKind === "http")
-                httpProxy = normalizeAuthorityProxyUrl(value, "http");
-            else if (lowerKind === "https")
-                httpsProxy = normalizeAuthorityProxyUrl(value, "http");
-            else if (lowerKind === "socks")
-                allProxy = normalizeAuthorityProxyUrl(value, "socks5");
-        }
-    }
-    else {
-        const shared = normalizeAuthorityProxyUrl(proxyServer, "http");
-        httpProxy = shared;
-        httpsProxy = shared;
-    }
+    const proxies = proxyServer.includes("=")
+        ? parsePerProtocolProxyServer(proxyServer)
+        : sharedProxyServer(proxyServer);
     return finalizeSystemProxyEnv({
-        allProxy,
-        httpProxy,
-        httpsProxy,
+        ...proxies,
         noProxy: buildNoProxyValue(proxyOverride.split(/[;,]/)),
     }, platform);
 }
+/** @internal Registry key holding the current user's Internet Settings proxy values. */
+const WINDOWS_INTERNET_SETTINGS_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings";
 /**
  * Resolve the OS-level proxy configuration into a normalized proxy environment.
  * Shells out to `scutil` on macOS and `reg query` on Windows (swallowing per-
@@ -321,6 +335,16 @@ export function parseWindowsInternetSettingsProxyOutput(input, platform = "win32
 export function resolveSystemProxyEnv(options = {}) {
     const platform = options.platform ?? process.platform;
     const runCommand = options.runCommand ?? defaultSystemProxyCommandRunner;
+    // No outer try/catch around the parse calls below (a former defense-in-depth
+    // catch was removed as unreachable): `tryRun` already swallows every
+    // `runCommand` failure, and neither parse
+    // function (`parseMacosScutilProxyOutput` / the Windows one) nor
+    // anything they call performs any operation that can throw for a
+    // string input — no `new URL`, no `JSON.parse`, no fixed-pattern
+    // `RegExp` construction from untrusted input. Empirically re-verified
+    // this session: 200k fuzzed `stdout`/registry-value strings (control
+    // characters, huge lengths, null bytes) through both parse functions,
+    // zero throws — see archived provenance ledger's 2026-07-22 entry.
     const tryRun = (command, args) => {
         try {
             return runCommand(command, args);
@@ -329,44 +353,16 @@ export function resolveSystemProxyEnv(options = {}) {
             return "";
         }
     };
-    try {
-        if (platform === "darwin") {
-            return parseMacosScutilProxyOutput(tryRun("scutil", ["--proxy"]), platform);
-        }
-        if (platform === "win32") {
-            return parseWindowsInternetSettingsProxyOutput({
-                proxyEnable: tryRun("reg", [
-                    "query",
-                    "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings",
-                    "/v",
-                    "ProxyEnable",
-                ]),
-                proxyOverride: tryRun("reg", [
-                    "query",
-                    "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings",
-                    "/v",
-                    "ProxyOverride",
-                ]),
-                proxyServer: tryRun("reg", [
-                    "query",
-                    "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings",
-                    "/v",
-                    "ProxyServer",
-                ]),
-            }, platform);
-        }
+    const regQuery = (valueName) => tryRun("reg", ["query", WINDOWS_INTERNET_SETTINGS_KEY, "/v", valueName]);
+    if (platform === "darwin") {
+        return parseMacosScutilProxyOutput(tryRun("scutil", ["--proxy"]), platform);
     }
-    catch {
-        // Defense-in-depth, not reachable through any real call path: `tryRun`
-        // already swallows every `runCommand` failure, and neither parse
-        // function (`parseMacosScutilProxyOutput` / the Windows one) nor
-        // anything they call performs any operation that can throw for a
-        // string input — no `new URL`, no `JSON.parse`, no fixed-pattern
-        // `RegExp` construction from untrusted input. Empirically re-verified
-        // this session: 200k fuzzed `stdout`/registry-value strings (control
-        // characters, huge lengths, null bytes) through both parse functions,
-        // zero throws — see archived provenance ledger's 2026-07-22 entry.
-        return {};
+    if (platform === "win32") {
+        return parseWindowsInternetSettingsProxyOutput({
+            proxyEnable: regQuery("ProxyEnable"),
+            proxyOverride: regQuery("ProxyOverride"),
+            proxyServer: regQuery("ProxyServer"),
+        }, platform);
     }
     return {};
 }

package/dist/secrets/credential-sets/contracts.d.ts

@@ -3,4 +3,5 @@
  * @example import { VaultError, type VaultRepoPort } from "@jini-ai/platform/secrets/credential-sets/contracts";
  */
 export * from "./vault.types.js";
+export { suggestCredentialWorksFor } from "./provider-matches.js";
 //# sourceMappingURL=contracts.d.ts.map

package/dist/secrets/credential-sets/contracts.js

@@ -3,4 +3,5 @@
  * @example import { VaultError, type VaultRepoPort } from "@jini-ai/platform/secrets/credential-sets/contracts";
  */
 export * from "./vault.types.js";
+export { suggestCredentialWorksFor } from "./provider-matches.js";
 //# sourceMappingURL=contracts.js.map

package/dist/secrets/credential-sets/index.d.ts

@@ -4,4 +4,5 @@ export { buildVaultAad } from "./vault.aad.js";
 export { createVaultMetaParsers, isCopyableKind } from "./vault.meta.js";
 export { SecretsVaultService, type VaultServiceDeps, type VaultPutInput, type VaultCopyInput } from "./vault.service.js";
 export { InMemoryVaultRepo } from "./vault.repo.memory.js";
+export { matchingCredentialProviderIds, selectCredentialForProvider, suggestCredentialWorksFor, normalizeCredentialWorksFor, type CredentialProviderDescriptor, type MatchableCredential } from "./provider-matches.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/secrets/credential-sets/index.js

@@ -3,4 +3,5 @@ export { buildVaultAad } from "./vault.aad.js";
 export { createVaultMetaParsers, isCopyableKind } from "./vault.meta.js";
 export { SecretsVaultService } from "./vault.service.js";
 export { InMemoryVaultRepo } from "./vault.repo.memory.js";
+export { matchingCredentialProviderIds, selectCredentialForProvider, suggestCredentialWorksFor, normalizeCredentialWorksFor } from "./provider-matches.js";
 //# sourceMappingURL=index.js.map

package/dist/secrets/credential-sets/provider-matches.d.ts

@@ -0,0 +1,61 @@
+import { type VaultOptions } from "./vault.types.js";
+/** Host-supplied catalog identity and accepted payload shape; catalogs never live in the vault. */
+export interface CredentialProviderDescriptor {
+    id: string;
+    vendorId: string;
+    acceptsCustomToken: boolean;
+}
+/** Safe metadata needed for matching. Labels and provider groups never imply compatibility. */
+export interface MatchableCredential {
+    kind: string;
+    provider: string | null;
+    meta: {
+        credentialType?: unknown;
+        worksFor?: unknown;
+    };
+}
+/** Validate and canonicalize explicit compatibility IDs without consulting a catalog.
+ * @throws VaultError for non-array, non-string, empty or whitespace-bearing IDs.
+ * @complexity O(total ID characters) time and space; does not mutate the supplied array.
+ * @example normalizeCredentialWorksFor({ value: ["GitHub", "github"] }); // ["github"]
+ */
+export declare function normalizeCredentialWorksFor({ value }: {
+    value: unknown;
+}, _options?: VaultOptions): string[];
+/** Return compatible host IDs from saved metadata, respecting the consumer's payload shape.
+ * Historical custom-kind rows use the same parsed metadata until migration. Unknown kinds and
+ * malformed metadata are ineligible. Performs no inference or I/O.
+ * @complexity O(worksFor + providers) time, O(worksFor + matches) space.
+ * @example matchingCredentialProviderIds({ credential, providers });
+ */
+export declare function matchingCredentialProviderIds({ credential, providers }: {
+    credential: MatchableCredential;
+    providers: readonly CredentialProviderDescriptor[];
+}, _options?: VaultOptions): string[];
+/** Select an eligible explicit ID, the descriptor's provider-group default, or a sole candidate.
+ * Missing IDs and unresolved ambiguity return null; custom-group defaults do not rank candidates.
+ * @complexity O(credentials * average worksFor) time, O(credentials) candidate space.
+ * @example selectCredentialForProvider({ credentials, provider, id: selectedId });
+ */
+export declare function selectCredentialForProvider<T extends MatchableCredential & {
+    id: string;
+    isDefault: boolean;
+}>({ credentials, provider, id, }: {
+    credentials: readonly T[];
+    provider: CredentialProviderDescriptor;
+    id?: string;
+}, _options?: VaultOptions): T | null;
+/** Suggest one explicit ID for create-time prefill only, using an injected catalog.
+ * Matches exact spelling ignoring case; whitespace/substrings are never normalized. A spelling
+ * shared by conflicting vendor groups is ambiguous, while repeated hosts in one group are safe.
+ * @complexity O(providers) time, O(matching vendor groups) space; no mutation or I/O.
+ * @example suggestCredentialWorksFor({ label: "GitHub", providers }); // ["github"]
+ */
+export declare function suggestCredentialWorksFor({ label, providers }: {
+    label: string;
+    providers: readonly {
+        id: string;
+        vendorId: string;
+    }[];
+}, _options?: VaultOptions): string[];
+//# sourceMappingURL=provider-matches.d.ts.map

package/dist/secrets/credential-sets/provider-matches.js

@@ -0,0 +1,61 @@
+import { VaultError } from "./vault.types.js";
+/** Validate and canonicalize explicit compatibility IDs without consulting a catalog.
+ * @throws VaultError for non-array, non-string, empty or whitespace-bearing IDs.
+ * @complexity O(total ID characters) time and space; does not mutate the supplied array.
+ * @example normalizeCredentialWorksFor({ value: ["GitHub", "github"] }); // ["github"]
+ */
+export function normalizeCredentialWorksFor({ value }, _options = {}) {
+    if (!Array.isArray(value))
+        throw new VaultError({ code: "invalid-meta" });
+    const ids = new Set();
+    for (const id of value) {
+        if (typeof id !== "string" || !id || /\s/.test(id))
+            throw new VaultError({ code: "invalid-meta" });
+        ids.add(id.toLowerCase());
+    }
+    return [...ids];
+}
+/** Return compatible host IDs from saved metadata, respecting the consumer's payload shape.
+ * Historical custom-kind rows use the same parsed metadata until migration. Unknown kinds and
+ * malformed metadata are ineligible. Performs no inference or I/O.
+ * @complexity O(worksFor + providers) time, O(worksFor + matches) space.
+ * @example matchingCredentialProviderIds({ credential, providers });
+ */
+export function matchingCredentialProviderIds({ credential, providers }, _options = {}) {
+    const { credentialType, worksFor } = credential.meta;
+    if ((credential.kind !== "vendor" && credential.kind !== "custom") ||
+        (credential.kind === "custom" && credentialType !== "custom") || (credentialType !== "vendor" && credentialType !== "custom") ||
+        !Array.isArray(worksFor) || Array.from(worksFor).some(id => typeof id !== "string" || !id || id !== id.toLowerCase() || /\s/.test(id)))
+        return [];
+    const ids = new Set(worksFor);
+    return providers.filter(provider => (credentialType !== "custom" || provider.acceptsCustomToken) &&
+        (ids.has(provider.id.toLowerCase()) || ids.has(provider.vendorId.toLowerCase())))
+        .map(provider => provider.id);
+}
+/** Select an eligible explicit ID, the descriptor's provider-group default, or a sole candidate.
+ * Missing IDs and unresolved ambiguity return null; custom-group defaults do not rank candidates.
+ * @complexity O(credentials * average worksFor) time, O(credentials) candidate space.
+ * @example selectCredentialForProvider({ credentials, provider, id: selectedId });
+ */
+export function selectCredentialForProvider({ credentials, provider, id, }, _options = {}) {
+    const candidates = credentials.filter(credential => matchingCredentialProviderIds({ credential, providers: [provider] }).length > 0);
+    if (id !== undefined)
+        return candidates.find(credential => credential.id === id) ?? null;
+    const defaults = candidates.filter(credential => credential.provider === provider.vendorId && credential.isDefault);
+    if (defaults.length === 1)
+        return defaults[0];
+    return candidates.length === 1 ? candidates[0] : null;
+}
+/** Suggest one explicit ID for create-time prefill only, using an injected catalog.
+ * Matches exact spelling ignoring case; whitespace/substrings are never normalized. A spelling
+ * shared by conflicting vendor groups is ambiguous, while repeated hosts in one group are safe.
+ * @complexity O(providers) time, O(matching vendor groups) space; no mutation or I/O.
+ * @example suggestCredentialWorksFor({ label: "GitHub", providers }); // ["github"]
+ */
+export function suggestCredentialWorksFor({ label, providers }, _options = {}) {
+    const identity = label.toLowerCase();
+    const vendors = new Set(providers.filter(provider => provider.id.toLowerCase() === identity ||
+        provider.vendorId.toLowerCase() === identity).map(provider => provider.vendorId.toLowerCase()));
+    return identity && vendors.size === 1 ? [identity] : [];
+}
+//# sourceMappingURL=provider-matches.js.map