@jini-ai/platform 0.5.9 → 0.5.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @jini-ai/platform
 
+## 0.5.10 — 2026-10-22
+
+- 2026-10-22: Mail: sender-identity resolver, payload hash covers the full delivery, rate-limit fixes, console preview; coverage.
+
+- `./mail`: email provider contract v1. `MailProviderModule` (id, credentialKeys, capabilities incl. rate limit, optional Svix-style feedback parser, `domainRequirements`/`domainStatus` → shared `DomainRequirement`) on the shared `createProviderRegistry`; `smtp` + `console` built-ins; explicit `mail.provider.{transactional,bulk}` setting with `initialMailProviderSetting` (keeps the effective provider on first boot; console/none = `unconfigured`) and `computeMailStatus`. `createMailDeliveryPolicy`: attachments/bulk-unsubscribe (RFC 8058) refusals, suppression by lane (hard bounce = all, complaint = bulk), test redirect/capture mode, per-provider token bucket with reserved transactional capacity, atomic reserve → send → mark ledger with an `unknown` outcome. `createMailFeedbackIngest`: body cap, unverified rate limit, rotating secrets, (provider, event) inbox dedup, one suppression writer. Breaking (unimplemented ports only): `MailSuppressionRepoPort` scopes are `all|bulk` keyed by lane; `MailSendDedupRepoPort` deprecated for `MailSendLedgerPort`. Additive: `MailerSendResult` failure `unknown`/`retryAfterMs`, feedback `eventId`/`recipient`.
+
 ## 0.5.9 — 2026-10-16
 
 - `fs`: best-effort directory fsync, so Windows site creation stops failing with EPERM (87720117).
@@ -47,6 +53,7 @@
 
 ## Unreleased
 
+- New `./object-store` (node): `createLocalFsObjectStore({ rootDir })` and `createLocalFsObjectStoreProvider()` — the default `local` provider for `@jini-ai/core/object-store`. Path formula `join(rootDir, key)`, byte-identical to cms `LocalFsBlobStore`; atomic `ifAbsent` via `wx`; keys escaping the root are refused.
 ### Compilation fixes
 
 - Omit an absent guarded HTTP abort signal to satisfy the canonical request contract.

package/dist/asset-cache.js

@@ -158,9 +158,6 @@ export function createAssetCache(opts, options = {}) {
     const suppliedDispatcher = options.dispatcher ?? opts.dispatcher;
     const dispatcher = suppliedDispatcher ?? createAssetCacheDispatcher({}, opts.lookupImpl ? { lookupImpl: opts.lookupImpl } : {});
     const inflight = new Map();
-    function keyFor(rawUrl) {
-        return createHash('sha256').update(rawUrl).digest('hex');
-    }
     async function readFromDisk(key) {
         const blobPath = path.join(cacheDir, key);
         const metaPath = `${blobPath}.json`;
@@ -197,26 +194,18 @@ export function createAssetCache(opts, options = {}) {
             return guessed;
         throw new AssetCacheError(415, `unsupported content-type: ${header || 'unknown'}`);
     }
-    /** Drain the body, aborting the moment the accumulated size exceeds
-     *  `maxBytes`. A response without a trustworthy Content-Length must never be
-     *  fully buffered first — that would turn this caller-supplied proxy into a
-     *  memory-exhaustion path. */
-    async function readBodyCapped(response, controller) {
-        const body = response.body;
-        if (!body) {
-            const ab = await response.arrayBuffer();
-            if (ab.byteLength > maxBytes)
-                throw new AssetCacheError(413, 'asset exceeds size limit');
-            return Buffer.from(ab);
-        }
-        const reader = body.getReader();
+    function assertWithinLimit(total) {
+        if (total > maxBytes)
+            throw new AssetCacheError(413, 'asset exceeds size limit');
+    }
+    /** Pull chunks until done, failing as soon as the running total passes
+     *  `maxBytes`. Always releases the reader, even on the size-limit throw. */
+    async function drainCapped(reader, controller) {
         const chunks = [];
         let total = 0;
         try {
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
+            for (let next = await reader.read(); !next.done; next = await reader.read()) {
+                const value = next.value;
                 if (!value)
                     continue;
                 total += value.byteLength;
@@ -237,6 +226,18 @@ export function createAssetCache(opts, options = {}) {
         }
         return Buffer.concat(chunks);
     }
+    /** Drain the body, aborting the moment the accumulated size exceeds
+     *  `maxBytes`. A response without a trustworthy Content-Length must never be
+     *  fully buffered first — that would turn this caller-supplied proxy into a
+     *  memory-exhaustion path. */
+    async function readBodyCapped(response, controller) {
+        const body = response.body;
+        if (body)
+            return drainCapped(body.getReader(), controller);
+        const ab = await response.arrayBuffer();
+        assertWithinLimit(ab.byteLength);
+        return Buffer.from(ab);
+    }
     async function fetchAndStore(rawUrl, key) {
         const url = assertSafePublicUrl(rawUrl);
         const controller = new AbortController();
@@ -259,9 +260,8 @@ export function createAssetCache(opts, options = {}) {
                 throw new AssetCacheError(502, `upstream responded ${response.status}`);
             }
             const declaredLength = Number(response.headers.get('content-length') ?? '');
-            if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
-                throw new AssetCacheError(413, 'asset exceeds size limit');
-            }
+            if (Number.isFinite(declaredLength))
+                assertWithinLimit(declaredLength);
             const contentType = resolveContentType(response.headers.get('content-type'), url);
             const buf = await readBodyCapped(response, controller);
             const result = { buf, contentType };
@@ -281,14 +281,15 @@ export function createAssetCache(opts, options = {}) {
         if (!isCacheableExternalUrl(rawUrl)) {
             throw new AssetCacheError(400, 'url is not a cacheable external media url');
         }
-        const key = keyFor(rawUrl.trim());
+        const url = rawUrl.trim();
+        const key = assetCacheKey(url);
         const cached = await readFromDisk(key);
         if (cached)
             return cached;
         const existing = inflight.get(key);
         if (existing)
             return existing;
-        const pending = fetchAndStore(rawUrl.trim(), key).finally(() => {
+        const pending = fetchAndStore(url, key).finally(() => {
             inflight.delete(key);
         });
         inflight.set(key, pending);

package/dist/blob-storage.d.ts

@@ -81,8 +81,13 @@ export declare class S3BlobStorage implements BlobStorage {
     deleteFile(namespace: string, relpath: string): Promise<void>;
     statFile(namespace: string, relpath: string): Promise<BlobFileMeta | null>;
     listFiles(namespace: string): Promise<BlobFileMeta[]>;
-    /** Builds the canonical S3 key the impl uses. Exposed for tests so the prefix/namespace/relpath join is stable. */
-    keyFor(namespace: string, relpath: string): string;
+    /**
+     * Builds the canonical S3 key. Exposed for tests so the prefix/namespace/relpath join is stable.
+     * Listing explicitly opts into an empty prefix relpath; file operations never do.
+     */
+    keyFor(namespace: string, relpath: string, { allowPrefix }?: {
+        allowPrefix?: boolean;
+    }): string;
     private endpointBase;
     private signedRequest;
 }

package/dist/blob-storage.js

@@ -12,6 +12,10 @@
  * workspace id, a project id, whatever the host application scopes storage by) — this
  * module carries no domain meaning for what a namespace *is*, only that paths are
  * grouped and traversal-guarded underneath one.
+ *
+ * Superseded (2026-10-21) by the one object-storage contract, `@jini-ai/core/object-store`
+ * (`ObjectStore`, keyed providers, default `local`). New code uses `ObjectStore` (local default:
+ * `@jini-ai/platform/object-store`); this module stays for its existing adapter consumers.
  */
 import path from 'node:path';
 import { promises as fsp } from 'node:fs';
@@ -54,32 +58,21 @@ export class LocalBlobStorage {
         return { path: normalizeRel(relpath), size: stat.size, mtimeMs: stat.mtimeMs };
     }
     async listFiles(namespace) {
+        validateNamespace(namespace);
         const root = path.join(this.root, namespace);
         const out = [];
         const queue = [root];
         while (queue.length > 0) {
             const dir = queue.pop();
-            let entries;
-            try {
-                entries = await fsp.readdir(dir, { withFileTypes: true });
-            }
-            catch (err) {
-                if (err.code === 'ENOENT')
+            const entries = await readListedDirectory(dir);
+            // A missing namespace lists as empty; a subdirectory deleted mid-walk only drops its own entries.
+            if (!entries) {
+                if (dir === root)
                     return [];
-                throw new StorageError('IO', `list failed: ${err.message}`);
-            }
-            for (const entry of entries) {
-                const abs = path.join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    queue.push(abs);
-                    continue;
-                }
-                if (!entry.isFile())
-                    continue;
-                const stat = await fsp.stat(abs);
-                const rel = path.relative(root, abs).split(path.sep).join('/');
-                out.push({ path: rel, size: stat.size, mtimeMs: stat.mtimeMs });
+                continue;
             }
+            for (const entry of entries)
+                await collectListedEntry({ root, dir, entry, queue, out });
         }
         return out;
     }
@@ -105,15 +98,8 @@ export class LocalBlobStorage {
         }
     }
     resolvePath(namespace, relpath) {
-        if (!namespace || namespace.includes('/') || namespace.includes('\\') || namespace.includes('\0') || namespace.includes('..')) {
-            throw new StorageError('TRAVERSAL', `invalid namespace ${namespace}`);
-        }
-        const normalized = normalizeRel(relpath);
-        if (!normalized)
-            throw new StorageError('TRAVERSAL', 'empty relpath');
-        if (normalized.split('/').some((seg) => seg === '..' || seg === '.')) {
-            throw new StorageError('TRAVERSAL', `unsafe relpath ${relpath}`);
-        }
+        validateNamespace(namespace);
+        const normalized = validateRelpath(relpath);
         return path.join(this.root, namespace, ...normalized.split('/'));
     }
 }
@@ -171,55 +157,36 @@ export class S3BlobStorage {
         return {
             path: normalizeRel(relpath),
             size: Number.isFinite(contentLength) ? contentLength : 0,
-            mtimeMs: lastModified ? Date.parse(lastModified) : Date.now(),
+            mtimeMs: modificationTime(lastModified),
         };
     }
     async listFiles(namespace) {
-        const namespacePrefix = this.keyFor(namespace, '');
+        const namespacePrefix = `${this.keyFor(namespace, '', { allowPrefix: true })}/`;
         const out = [];
         let continuationToken;
         // Cap iterations so a hostile bucket can't loop forever.
         for (let pages = 0; pages < 1000; pages++) {
-            const params = [
-                ['list-type', '2'],
-                ['prefix', namespacePrefix],
-            ];
-            if (continuationToken)
-                params.push(['continuation-token', continuationToken]);
-            params.sort((a, b) => a[0].localeCompare(b[0]));
-            const query = params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+            const query = listObjectsV2Query({ prefix: namespacePrefix, continuationToken });
             const res = await this.signedRequest({ method: 'GET', key: '', extraQuery: query });
             if (!res.ok) {
                 throw new StorageError('IO', `S3 LIST ${namespacePrefix} → ${res.status} ${res.statusText}: ${await safeText(res)}`);
             }
             const xml = await res.text();
             const { entries, isTruncated, nextToken } = parseListBucketV2Xml(xml);
-            for (const e of entries) {
-                // Strip the per-bucket namespacePrefix to surface namespace-relative paths.
-                // `namespacePrefix` is `keyFor(namespace, '')`, which always includes at least the
-                // (non-empty, `keyFor`-validated) namespace segment and never a trailing slash — so it's
-                // always non-empty and the +1 separator always applies.
-                const relStart = namespacePrefix.length + 1;
-                const rel = e.key.slice(relStart).replace(/^\/+/, '');
-                if (!rel)
-                    continue; // skip the prefix marker itself
-                out.push({ path: rel, size: e.size, mtimeMs: e.lastModifiedMs });
-            }
+            out.push(...namespaceEntries(entries, namespacePrefix));
             if (!isTruncated || !nextToken)
                 break;
             continuationToken = nextToken;
         }
         return out;
     }
-    /** Builds the canonical S3 key the impl uses. Exposed for tests so the prefix/namespace/relpath join is stable. */
-    keyFor(namespace, relpath) {
-        if (!namespace || namespace.includes('/') || namespace.includes('\\') || namespace.includes('..')) {
-            throw new StorageError('TRAVERSAL', `invalid namespace ${namespace}`);
-        }
-        const normalized = relpath ? normalizeRel(relpath) : '';
-        if (normalized.split('/').some((seg) => seg === '..' || seg === '.')) {
-            throw new StorageError('TRAVERSAL', `unsafe relpath ${relpath}`);
-        }
+    /**
+     * Builds the canonical S3 key. Exposed for tests so the prefix/namespace/relpath join is stable.
+     * Listing explicitly opts into an empty prefix relpath; file operations never do.
+     */
+    keyFor(namespace, relpath, { allowPrefix = false } = {}) {
+        validateNamespace(namespace);
+        const normalized = validateRelpath(relpath, { allowPrefix });
         const segments = [this.options.prefix?.replace(/^\/+|\/+$/g, ''), namespace, normalized].filter((s) => typeof s === 'string' && s.length > 0);
         return segments.join('/');
     }
@@ -266,6 +233,17 @@ export class S3BlobStorage {
         return this.fetchFn(url, init);
     }
 }
+/** Builds the ListObjectsV2 query string with keys sorted, as SigV4's canonical query requires. */
+function listObjectsV2Query({ prefix, continuationToken }, _options = {}) {
+    const params = [
+        ['list-type', '2'],
+        ['prefix', prefix],
+    ];
+    if (continuationToken)
+        params.push(['continuation-token', continuationToken]);
+    params.sort((a, b) => a[0].localeCompare(b[0]));
+    return params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+}
 function parseListBucketV2Xml(xml) {
     const entries = [];
     // Lightweight XML scrape — accepts S3 / S3-compat shapes:
@@ -286,7 +264,7 @@ function parseListBucketV2Xml(xml) {
         entries.push({
             key,
             size: Number.isFinite(size) ? size : 0,
-            lastModifiedMs: lastModifiedRaw ? Date.parse(lastModifiedRaw) : Date.now(),
+            lastModifiedMs: modificationTime(lastModifiedRaw),
         });
     }
     const isTruncated = (pluckTag(xml, 'IsTruncated') ?? 'false').toLowerCase() === 'true';
@@ -312,4 +290,66 @@ function normalizeRel(relpath) {
         .replace(/[\\]+/g, '/')
         .replace(/\/+/g, '/');
 }
+/** Directory entries for a listing walk; null when the directory no longer exists. */
+async function readListedDirectory(dir) {
+    try {
+        return await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw new StorageError('IO', `list failed: ${err.message}`);
+    }
+}
+/** Queues a subdirectory or records a regular file; other entry types are skipped. */
+async function collectListedEntry({ root, dir, entry, queue, out }) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+        queue.push(abs);
+        return;
+    }
+    if (!entry.isFile())
+        return;
+    const stat = await fsp.stat(abs);
+    const rel = path.relative(root, abs).split(path.sep).join('/');
+    out.push({ path: rel, size: stat.size, mtimeMs: stat.mtimeMs });
+}
+/** Strips the per-bucket namespacePrefix to surface namespace-relative paths. */
+function namespaceEntries(entries, namespacePrefix) {
+    const out = [];
+    for (const e of entries) {
+        // It includes the non-empty, validated namespace and its trailing separator,
+        // so sibling namespaces (ns10 vs ns1) cannot leak into this listing.
+        if (!e.key.startsWith(namespacePrefix))
+            continue;
+        const rel = e.key.slice(namespacePrefix.length).replace(/^\/+/, '');
+        if (!rel)
+            continue; // skip the prefix marker itself
+        out.push({ path: rel, size: e.size, mtimeMs: e.lastModifiedMs });
+    }
+    return out;
+}
+/** One namespace guard for both backends and every operation, including listing. */
+function validateNamespace(namespace) {
+    if (!namespace || namespace === '.' || /[/\\\0]/.test(namespace) || namespace.includes('..')) {
+        throw new StorageError('TRAVERSAL', `invalid namespace ${namespace}`);
+    }
+}
+/** Shared key validation; only an explicit empty string may denote an S3 listing prefix. */
+function validateRelpath(relpath, { allowPrefix = false } = {}) {
+    if (allowPrefix && relpath === '')
+        return '';
+    const normalized = normalizeRel(relpath);
+    if (!normalized)
+        throw new StorageError('TRAVERSAL', 'empty relpath');
+    if (normalized.includes('\0') || normalized.split('/').some(seg => seg === '..' || seg === '.')) {
+        throw new StorageError('TRAVERSAL', `unsafe relpath ${relpath}`);
+    }
+    return normalized;
+}
+/** Missing or malformed remote timestamps use the same finite clock fallback. */
+function modificationTime(value) {
+    const parsed = value ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : Date.now();
+}
 //# sourceMappingURL=blob-storage.js.map

package/dist/child-environment.d.ts

@@ -15,4 +15,40 @@ export declare function omitEnvironmentKeys({ env, keys }: {
     env: Record<string, string | undefined>;
     omitted: string[];
 };
+/** Runs one bounded command and resolves its stdout; `execFile` semantics. */
+export type LoginShellCommandRunner = (required: {
+    file: string;
+    args: readonly string[];
+    env: Record<string, string>;
+    cwd: string | undefined;
+}, optional?: {}) => Promise<{
+    stdout: string;
+}>;
+/** Host process facts and the command runner the default login-environment reader uses. */
+export interface LoginShellPorts {
+    readonly platform: NodeJS.Platform;
+    /** The account's login shell; `null` where the OS has none (Windows). */
+    readonly userShell: () => string | null;
+    readonly runCommand: LoginShellCommandRunner;
+}
+/** The real host: this process's platform, the account's login shell and `execFile` (10 s, 1 MiB). */
+export declare function nodeLoginShellPorts(): LoginShellPorts;
+/** Read the operator's login environment from a clean baseline, never the daemon's secret bag.
+ * Only shell bootstrap keys reach the shell. Host-owned names are removed again after profiles
+ * load, before a CLI or its MCP children can inherit them. Profile failures reject the launch.
+ * `ports` replaces the host platform, login-shell lookup and command runner the default `read` uses.
+ * @complexity O(e * p) for e environment entries and p small host-selected exclusions; one bounded process.
+ */
+export declare function readLoginShellEnvironment(required: {
+    baseEnv: Readonly<Record<string, string | undefined>>;
+    excludedPrefixes: readonly string[];
+    excludedKeys: readonly string[];
+    excludedSuffixes?: readonly string[];
+}, optional?: {
+    read?: (input: {
+        shell: string;
+        env: Record<string, string>;
+    }, options?: {}) => Promise<Record<string, string>>;
+    ports?: LoginShellPorts;
+}): Promise<Record<string, string>>;
 //# sourceMappingURL=child-environment.d.ts.map

package/dist/child-environment.js

@@ -1,3 +1,6 @@
+import { execFile } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { promisify } from 'node:util';
 /** Environment isolation for child processes; hosts name the settings that belong to one run. */
 /**
  * Copy an environment without host-selected keys. Reports names only, never values; no I/O.
@@ -23,4 +26,69 @@ export function omitEnvironmentKeys({ env, keys }, { caseInsensitive = false } =
     }
     return { env: child, omitted: [...omitted] };
 }
+const LOGIN_SHELL_BOOTSTRAP_KEYS = ['PATH', 'HOME', 'USERPROFILE', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'TEMP', 'TMP',
+    'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'SSH_AUTH_SOCK', 'SystemRoot', 'windir', 'ComSpec', 'PATHEXT'];
+// Registry-backed machine/user environment, without inheriting the service's private values.
+const WINDOWS_ENVIRONMENT_SCRIPT = "$e=@{}; foreach($s in @('Machine','User')) { [Environment]::GetEnvironmentVariables($s).GetEnumerator() | ForEach-Object { $e[$_.Key]=$_.Value } }; $e | ConvertTo-Json -Compress";
+/** The real host: this process's platform, the account's login shell and `execFile` (10 s, 1 MiB). */
+export function nodeLoginShellPorts() {
+    const exec = promisify(execFile);
+    return {
+        platform: process.platform,
+        userShell: () => userInfo().shell,
+        runCommand: ({ file, args, env, cwd }) => exec(file, [...args], { env, timeout: 10_000, maxBuffer: 1024 * 1024, cwd }),
+    };
+}
+/** Parse `env -0` output, keeping only well-formed variable names.
+ * @complexity O(n) in the output length. */
+function parseNullSeparatedEnvironment({ stdout }) {
+    const entries = stdout.split('\0').flatMap(pair => {
+        const at = pair.indexOf('=');
+        return at > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(pair.slice(0, at)) ? [[pair.slice(0, at), pair.slice(at + 1)]] : [];
+    });
+    return Object.fromEntries(entries);
+}
+/** The default reader: the Windows registry environment, or the login shell's `env -0`. */
+async function readHostLoginEnvironment({ shell, env }, ports) {
+    if (ports.platform === 'win32') {
+        const { stdout } = await ports.runCommand({ file: 'powershell.exe', args: ['-NoLogo', '-NonInteractive', '-Command', WINDOWS_ENVIRONMENT_SCRIPT],
+            env, cwd: env.USERPROFILE });
+        return { ...env, ...JSON.parse(stdout) };
+    }
+    const { stdout } = await ports.runCommand({ file: shell, args: ['-ilc', 'exec /usr/bin/env -0'], env, cwd: env.HOME });
+    return parseNullSeparatedEnvironment({ stdout });
+}
+/** True when a host-owned name, prefix or suffix claims this key (case-insensitively). */
+function isExcludedEnvironmentKey({ key, required }) {
+    const upper = key.toUpperCase();
+    return required.excludedKeys.some(name => name.toUpperCase() === upper) ||
+        required.excludedPrefixes.some(prefix => upper.startsWith(prefix.toUpperCase())) ||
+        (required.excludedSuffixes ?? []).some(suffix => upper.endsWith(suffix.toUpperCase()));
+}
+/** Read the operator's login environment from a clean baseline, never the daemon's secret bag.
+ * Only shell bootstrap keys reach the shell. Host-owned names are removed again after profiles
+ * load, before a CLI or its MCP children can inherit them. Profile failures reject the launch.
+ * `ports` replaces the host platform, login-shell lookup and command runner the default `read` uses.
+ * @complexity O(e * p) for e environment entries and p small host-selected exclusions; one bounded process.
+ */
+export async function readLoginShellEnvironment(required, optional = {}) {
+    const baseline = {};
+    for (const key of LOGIN_SHELL_BOOTSTRAP_KEYS) {
+        const value = required.baseEnv[key];
+        if (value !== undefined)
+            baseline[key] = value;
+    }
+    const ports = optional.ports ?? nodeLoginShellPorts();
+    const shell = ports.userShell() || baseline.SHELL || '/bin/sh';
+    const read = optional.read ?? ((input) => readHostLoginEnvironment(input, ports));
+    let env;
+    try {
+        env = await read({ shell, env: baseline }, {});
+    }
+    catch {
+        throw new Error('Login shell environment unavailable');
+    }
+    return Object.fromEntries(Object.entries(env).filter(([key, value]) => typeof value === 'string' &&
+        !isExcludedEnvironmentKey({ key, required })));
+}
 //# sourceMappingURL=child-environment.js.map