@mcsherrylabs/evolver-mcp 0.11.0 → 0.13.0

package/dist/content-files.js

@@ -0,0 +1,79 @@
+// File-backed content is an explicit host-filesystem capability, never a model-context blob.
+// The SDK still owns HTTP and streaming transport. The file layer owns byte bounds, incremental
+// hashing and atomic output; neither this module nor the tools implement the node protocol.
+import { parseAccess, OPEN_NOTE, RESTRICTED_NOTE } from "./content.js";
+import { ContentHttpError } from "@mcsherrylabs/evolver-client";
+import { FileAccessError, fileName } from "./files.js";
+/** Deliberately do not echo exceptions/response text/host paths: a server can reflect content,
+ * and some TLS errors include certificate details. A completed HTTP refusal is not transport loss. */
+export function contentFileFailure(e, url, operation) {
+    const aftermath = operation === "publish" ? "upload storage is unconfirmed" : "no completed output metadata returned";
+    if (e instanceof FileAccessError && e.code === "publication_unknown")
+        return { kind: "partial", what: operation, cause: "file_publication_unknown; target may exist or have been visible; this is NOT a no-write refusal. Do not retry or automatically delete the final target; operator inspection is required." +
+                (e.cleanupWarning ? " staging_cleanup_failed; protected staging may also remain." : "") };
+    if (e instanceof FileAccessError && e.code !== "transfer_failed")
+        return { kind: "partial", what: operation, cause: `file_${e.code}; ${aftermath}` +
+                (e.cleanupWarning ? "; staging_cleanup_failed; operator inspection of protected staging may be required" : "") };
+    if (e instanceof Error && e.name === "AbortError")
+        return { kind: "partial", what: operation, cause: `cancelled; ${aftermath}` };
+    const message = e instanceof Error ? e.message : "";
+    const status = e instanceof ContentHttpError ? String(e.status) :
+        /^(?:postContent(?:Stream)?|getContentStream): HTTP ([1-5][0-9]{2})\b/.exec(message)?.[1];
+    if (status)
+        return { kind: "partial", what: operation,
+            cause: `content_http_${status}; not complete, not retried or republished open; ${aftermath}` };
+    return { kind: "unreachable", chain: url, cause: `content_transfer_failed; ${aftermath}` +
+            (e instanceof FileAccessError && e.cleanupWarning ? "; staging_cleanup_failed; operator inspection of protected staging may be required" : "") };
+}
+export const contentFileDisabled = () => ({ kind: "misconfigured", what: "file content access is disabled",
+    fix: "operator must opt in with EVOLVER_FILE_ROOT (dedicated server-local0700 directory) and reload; client roots do not authorize host access" });
+export async function publishFile(deps, req, signal) {
+    // Share the INLINE ACL parser; do not trim/filter a malformed grant into open publication.
+    const access = parseAccess(req.access, req.authorizedPrincipals);
+    if ("kind" in access)
+        return access;
+    if (!deps)
+        return contentFileDisabled();
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(files => files.withInput(file, async (input) => {
+            const result = await deps.client.postContentStream(input.stream, { size: input.size, signal: files.signal,
+                ...(access.mode === "restricted" ? { authorizedPrincipals: access.principals } : {}) });
+            const metadata = input.metadata();
+            if (result.size !== metadata.size || !/^[0-9a-f]{64}$/.test(result.key))
+                throw new FileAccessError("incomplete");
+            return { kind: "ok", value: { ...metadata, key: result.key, access: access.mode,
+                    ...(access.mode === "restricted" ? { authorizedPrincipals: access.principals } : {}),
+                    note: access.mode === "restricted" ? RESTRICTED_NOTE : OPEN_NOTE } };
+        }), signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "publish");
+    }
+}
+export async function fetchFile(deps, req, signal) {
+    if (!deps)
+        return contentFileDisabled();
+    if (typeof req.key !== "string" || !/^[0-9a-f]{64}$/.test(req.key))
+        return { kind: "partial", what: "key", cause: "a content key must be exactly64 lowercase hex characters" };
+    const key = req.key;
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(async (files) => {
+            const result = await deps.client.getContentStream(key, { signal: files.signal });
+            if (result === null)
+                return { kind: "ok", value: null };
+            // A full-file tool never silently treats a partial response as the complete object.
+            if (result.status !== 200 || result.range !== null) {
+                await result.stream.cancel().catch(() => undefined);
+                throw new FileAccessError("incomplete");
+            }
+            const metadata = await files.writeNew(file, result.stream, result.size);
+            return { kind: "ok", value: { ...metadata, key } };
+        }, signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "download");
+    }
+}
+//# sourceMappingURL=content-files.js.map

package/dist/content-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-files.js","sourceRoot":"","sources":["../src/content-files.ts"],"names":[],"mappings":"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"}

package/dist/content-ranges.d.ts

@@ -0,0 +1,41 @@
+import type { FileContentDeps } from "./content-files.js";
+import type { FileCleanupWarning } from "./files.js";
+import type { ToolResult } from "./result.js";
+export interface ByteInterval {
+    readonly from: number;
+    readonly toInclusive: number;
+}
+export type FileRangeResult = {
+    readonly status: "range";
+    readonly key: string;
+    readonly file: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly hashScope: "served-range";
+    /** False refers to the ORIGINAL object, even if this interval happens to cover all of it. */
+    readonly complete: false;
+    readonly rangeComplete: true;
+    readonly fileComplete: true;
+    readonly requested: ByteInterval;
+    readonly served: ByteInterval & {
+        readonly totalSize: number;
+    };
+    readonly clipped: boolean;
+    readonly cleanupWarning?: FileCleanupWarning;
+} | {
+    readonly status: "unsatisfiable";
+    readonly key: string;
+    readonly requested: ByteInterval;
+    readonly totalSize: number | null;
+    readonly complete: false;
+    readonly rangeComplete: false;
+    readonly fileComplete: false;
+};
+export declare function byteInterval(from: unknown, toInclusive: unknown, maxBytes: number): ByteInterval | ToolResult<never>;
+export declare function fetchRangeFile(deps: FileContentDeps | undefined, req: {
+    key?: unknown;
+    file?: unknown;
+    from?: unknown;
+    toInclusive?: unknown;
+}, signal?: AbortSignal): Promise<ToolResult<FileRangeResult | null>>;
+//# sourceMappingURL=content-ranges.d.ts.map

package/dist/content-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-ranges.d.ts","sourceRoot":"","sources":["../src/content-ranges.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AACrF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAC5F,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;CAC9C,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACzF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC;CACvF,CAAC;AAGF,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,CAOpH;AAWD,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,GAAG,EAAE;IAC3E,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CACtE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAyCpE"}

package/dist/content-ranges.js

@@ -0,0 +1,75 @@
+// Inclusive range semantics sit above the SDK's truthful HTTP metadata and reuse #11's
+// exact-byte, atomic no-overwrite file boundary. No headers, HTTP request or wire encoder here.
+import { contentFileDisabled, contentFileFailure } from "./content-files.js";
+import { fileName } from "./files.js";
+const nat = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function byteInterval(from, toInclusive, maxBytes) {
+    if (!nat(from) || !nat(toInclusive) || from > toInclusive)
+        return { kind: "partial", what: "range", cause: "invalid_range; inclusive bounds must be non-negative safe integers with from <= toInclusive" };
+    const count = toInclusive - from + 1;
+    if (!Number.isSafeInteger(count) || count > maxBytes)
+        return { kind: "partial", what: "range", cause: `range_too_large; requested inclusive interval must fit the ${maxBytes}-byte file bound` };
+    return { from, toInclusive };
+}
+/** SDK0.22 prerequisite: structured416, never regex-inferred from a transport exception.
+ * Unknown total stays null; malformed metadata is not an unsatisfiable interval result. */
+function unsatisfiable(e) {
+    if (!(e instanceof Error) || e.name !== "ContentRangeError")
+        return undefined;
+    const value = e;
+    if (value.status !== 416 || (value.totalSize !== null && !nat(value.totalSize)))
+        return undefined;
+    return { totalSize: value.totalSize };
+}
+export async function fetchRangeFile(deps, req, signal) {
+    if (!deps)
+        return contentFileDisabled();
+    if (typeof req.key !== "string" || !/^[0-9a-f]{64}$/.test(req.key))
+        return { kind: "partial", what: "key", cause: "a content key must be exactly 64 lowercase hex characters" };
+    const key = req.key;
+    const requested = byteInterval(req.from, req.toInclusive, deps.files.maxBytes);
+    if ("kind" in requested)
+        return requested;
+    try {
+        const file = fileName(req.file);
+        return await deps.files.transfer(async (files) => {
+            let result;
+            try {
+                result = await deps.client.getContentStream(key, { range: requested, signal: files.signal });
+            }
+            catch (e) {
+                const refusal = unsatisfiable(e);
+                if (!refusal)
+                    throw e;
+                return { kind: "ok", value: { status: "unsatisfiable", key, requested, totalSize: refusal.totalSize,
+                        complete: false, rangeComplete: false, fileComplete: false } };
+            }
+            if (result === null)
+                return { kind: "ok", value: null };
+            if (result.status === 200) {
+                await result.stream.cancel().catch(() => undefined);
+                return { kind: "partial", what: "range", cause: "range_ignored; server returned a full object, discarded without writing or retry" };
+            }
+            const served = result.range;
+            // The SDK validates headers. Also refuse a collaborator lacking/corrupting that contract;
+            // a stream alone can never prove the node honored the requested range.
+            if (result.status !== 206 || !served || !nat(served.from) || !nat(served.toInclusive) ||
+                !nat(served.totalSize) || served.from > served.toInclusive || served.toInclusive >= served.totalSize ||
+                served.from !== requested.from || served.toInclusive !== Math.min(requested.toInclusive, served.totalSize - 1) ||
+                !nat(result.size) || result.size !== served.toInclusive - served.from + 1) {
+                await result.stream.cancel().catch(() => undefined);
+                return { kind: "partial", what: "range", cause: "range_metadata_invalid; validated SDK206/served interval/total/byte-count metadata is required; no output" };
+            }
+            const metadata = await files.writeNew(file, result.stream, result.size);
+            return { kind: "ok", value: { status: "range", key, file: metadata.file, size: metadata.size,
+                    sha256: metadata.sha256, hashScope: "served-range", complete: false, rangeComplete: true, fileComplete: true,
+                    requested, served: { from: served.from, toInclusive: served.toInclusive, totalSize: served.totalSize },
+                    clipped: served.toInclusive !== requested.toInclusive,
+                    ...(metadata.cleanupWarning ? { cleanupWarning: metadata.cleanupWarning } : {}) } };
+        }, signal);
+    }
+    catch (e) {
+        return contentFileFailure(e, deps.contentUrl, "range");
+    }
+}
+//# sourceMappingURL=content-ranges.js.map

package/dist/content-ranges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-ranges.js","sourceRoot":"","sources":["../src/content-ranges.ts"],"names":[],"mappings":"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"}

package/dist/content.d.ts

@@ -1,7 +1,14 @@
 import type { ToolResult } from "./result.js";
+/** Inline bound on ORIGINAL (decoded) bytes, for both PUT and GET: 256 KiB. */
+export declare const CONTENT_MAX_BYTES = 262144;
+/** Longest canonical base64 accepted/returned for `CONTENT_MAX_BYTES` bytes (349 528 chars). */
+export declare const CONTENT_MAX_BASE64_CHARS: number;
+/** Most principal names one restricted publication may grant. */
+export declare const CONTENT_MAX_PRINCIPALS = 32;
 /** Only what the content verbs need from a client. `NodeClient` satisfies it structurally, which
  *  is what lets the rules be exercised against a fake — a rule only checked against a live node
- *  is a rule that drifts. */
+ *  is a rule that drifts. The GET goes through the stream so the declared size is checked BEFORE
+ *  any body is buffered (the SDK's `getContent` buffers an object of any size). */
 export interface ContentClient {
     postContent(bytes: Uint8Array, opts?: {
         authorizedPrincipals?: string[];
@@ -9,7 +16,10 @@ export interface ContentClient {
         key: string;
         size: number;
     }>;
-    getContent(key: string): Promise<Uint8Array | null>;
+    getContentStream(key: string): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        size: number;
+    } | null>;
 }
 /** What the content verbs need from the world: the SEPARATE content client (built against
  *  `contentBaseUrl`, never the chain client) plus that content endpoint name for refusals.
@@ -19,33 +29,66 @@ export interface ContentDeps {
     readonly client: ContentClient;
     readonly contentUrl: string;
 }
-/** What a successful publish answers: the node's key and size, plus a locally-computed sha256
- *  over the exact published bytes. No `txId` — content has nothing to submit later. */
+/** What a publish is asked to do. Raw tool parameters: every field is validated here, never coerced. */
+export interface PublishRequest {
+    readonly access?: unknown;
+    readonly authorizedPrincipals?: unknown;
+    readonly text?: unknown;
+    readonly base64?: unknown;
+}
+/** What a successful publish answers: the node's key, the ORIGINAL byte size, a locally-computed
+ *  sha256 over those bytes, and the access actually requested. No `txId` — content has nothing to
+ *  submit later. */
 export interface Published {
     readonly key: string;
     readonly size: number;
     readonly sha256: string;
+    readonly encoding: "text" | "base64";
+    readonly access: "open" | "restricted";
+    readonly authorizedPrincipals?: readonly string[];
+    readonly note: string;
 }
-/** What a successful fetch answers: the key, size, locally-recomputed sha256, and the bytes
- *  decoded to UTF-8 `text`. The raw `bytes` field is DROPPED — never surfaced to the model
- *  (Pitfall 5). `null` is the DEFINITIVE "no reachable holder" negative (Pitfall 3). */
-export interface Fetched {
+/** What a successful fetch answers: always the COMPLETE object (`complete: true`), its size and
+ *  locally-recomputed sha256, and EXACTLY ONE of `text` (strict, lossless UTF-8) or `base64` (the
+ *  actual fetched bytes). `null` is the DEFINITIVE "no reachable holder" negative (Pitfall 3). */
+export type Fetched = {
     readonly key: string;
     readonly size: number;
     readonly sha256: string;
+    readonly complete: true;
+} & ({
+    readonly encoding: "text";
     readonly text: string;
-}
+} | {
+    readonly encoding: "base64";
+    readonly base64: string;
+});
 /** SHA-256 of the given bytes, hex-encoded. Computed locally via Web Crypto — never trusted from
  *  the node (T-5-04). */
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
-/** Publish UTF-8 text to the content cache (READ-11). OPEN-only publish for v1: no
- *  `authorizedPrincipals` is exposed, closing the blank-grant-list footgun (Pitfall 4). Empty or
- *  blank text is refused locally as `partial` BEFORE any call. Returns `{ key, size, sha256 }`
- *  with the sha256 computed locally over the exact bytes published. */
-export declare function publishBytes(deps: ContentDeps, text: string): Promise<ToolResult<Published>>;
-/** Fetch content from the cache by key and decode it to text (READ-10). Empty/blank key refused
- *  locally as `partial` BEFORE any call. A `null` from the SDK is the DEFINITIVE negative — no
- *  reachable holder — surfaced as `ok { value: null }`, NOT `not_found` (Pitfall 3); a throw is
- *  `unreachable`. Raw bytes are decoded to `text` and dropped (Pitfall 5). */
-export declare function fetchBytes(deps: ContentDeps, key: string): Promise<ToolResult<Fetched | null>>;
+export declare const OPEN_NOTE: string;
+export declare const RESTRICTED_NOTE: string;
+type Access = {
+    readonly mode: "open";
+} | {
+    readonly mode: "restricted";
+    readonly principals: string[];
+};
+/** The access the caller DELIBERATELY asked for, or a refusal. Nothing is trimmed, filtered or
+ *  defaulted: an entry the node would reinterpret (blank, whitespace, comma-joined) is refused,
+ *  because the alternative is publishing to a set the caller did not name. */
+export declare function parseAccess(access: unknown, grants: unknown): Access | ToolResult<never>;
+/** Publish text or binary to the content cache (READ-11, #8). `access` must be stated; a
+ *  restricted publication forwards its grants through the SDK's `authorizedPrincipals`. Every
+ *  refusal happens BEFORE any call. A node answer that is not 201 (e.g. HTTP 400 for an unknown
+ *  principal) is `partial publish` naming the node's answer — never `ok`, and never retried open;
+ *  a transport throw is `unreachable`. */
+export declare function publishBytes(deps: ContentDeps, req: PublishRequest): Promise<ToolResult<Published>>;
+/** Fetch content from the cache by key (READ-10, #8), returning the COMPLETE object as strict
+ *  UTF-8 `text` (default) or `base64` of the actual bytes. Empty/blank key or unknown encoding is
+ *  refused locally BEFORE any call. `null` is the DEFINITIVE negative (Pitfall 3); a throw or a
+ *  short/overlong transfer is `unreachable`. Over `CONTENT_MAX_BYTES`, or not valid UTF-8 in text
+ *  mode, answers `partial` with NO content — never a preview, never a lossy decode. */
+export declare function fetchBytes(deps: ContentDeps, key: string, encoding?: unknown): Promise<ToolResult<Fetched | null>>;
+export {};
 //# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;6BAE6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CACrD;AAED;;;0CAG0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;uFACuF;AACvF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;wFAEwF;AACxF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;yBACyB;AACzB,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlE;AAED;;;uEAGuE;AACvE,wBAAsB,YAAY,CAChC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAchC;AAED;;;8EAG8E;AAC9E,wBAAsB,UAAU,CAC9B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAYrC"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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"}

package/dist/content.js

@@ -1,18 +1,38 @@
 // The content cache is a SECOND non-signing verb family, alongside `claimIdentity` (SIGN-08): it
-// is a DIRECT node call through `NodeClient.postContent`/`getContent`, because the MCP holds no
-// key for the content it publishes or fetches — content is a loopback byte store on its OWN
+// is a DIRECT node call through `NodeClient.postContent`/`getContentStream`, because the MCP holds
+// no key for the content it publishes or fetches — content is a loopback byte store on its OWN
 // listener (a different port from the chain API), and reaching that listener is the entire
 // authorization. Nothing is recorded in the session stores, no `txId` is returned, and nothing
 // reaches `evolver_submit`.
 //
 // The digest is NEVER trusted from the node: `sha256Hex` is computed locally over the exact
-// bytes, so a reader verifies against what the PUBLISHER asserted, not against what the node
-// claims (a node-trusted digest would verify the node against itself — T-5-04).
+// ORIGINAL bytes (never a base64 transport string), so a reader verifies against what the
+// PUBLISHER asserted, not against what the node claims (a node-trusted digest would verify the
+// node against itself — T-5-04).
 //
 // A GET that returns `null` is a DEFINITIVE negative ("no reachable holder had it" — the node
 // walked the overlay on a miss), NOT a throw: a throw is `unreachable` (transport failure), and
 // the two are never collapsed (Pitfall 3).
+//
+// ⚠️ READ GRANTS (#8). `access` is REQUIRED and never inferred: "open" sends no grant, "restricted"
+// sends `authorizedPrincipals` through the SDK's own grant header. Every malformed/blank/oversized
+// grant list is refused BEFORE the node is asked, so an intended restriction can never become an
+// open publish. The grant governs which authenticated remote peer NODE may read on the node's
+// peer route — not the MCP signer, not the trusted local listener this module talks to — and it
+// is a serving control, not encryption. Grants on identical bytes merge by union on the node, so a
+// narrower re-publication cannot retract an earlier wider one.
+//
+// ⚠️ BOUNDS. Everything is inline in model context, so both directions are capped at
+// `CONTENT_MAX_BYTES` of ORIGINAL bytes. An over-bound GET returns NO content: there is no preview
+// and no truncated object reported as complete. Streaming/range reads are a follow-up.
+import { ContentHttpError, isValidPrincipalName } from "@mcsherrylabs/evolver-client";
 import { unreachableFrom } from "./result.js";
+/** Inline bound on ORIGINAL (decoded) bytes, for both PUT and GET: 256 KiB. */
+export const CONTENT_MAX_BYTES = 262_144;
+/** Longest canonical base64 accepted/returned for `CONTENT_MAX_BYTES` bytes (349 528 chars). */
+export const CONTENT_MAX_BASE64_CHARS = 4 * Math.ceil(CONTENT_MAX_BYTES / 3);
+/** Most principal names one restricted publication may grant. */
+export const CONTENT_MAX_PRINCIPALS = 32;
 /** SHA-256 of the given bytes, hex-encoded. Computed locally via Web Crypto — never trusted from
  *  the node (T-5-04). */
 export async function sha256Hex(bytes) {
@@ -21,40 +41,175 @@ export async function sha256Hex(bytes) {
         .map((b) => b.toString(16).padStart(2, "0"))
         .join("");
 }
-/** Publish UTF-8 text to the content cache (READ-11). OPEN-only publish for v1: no
- *  `authorizedPrincipals` is exposed, closing the blank-grant-list footgun (Pitfall 4). Empty or
- *  blank text is refused locally as `partial` BEFORE any call. Returns `{ key, size, sha256 }`
- *  with the sha256 computed locally over the exact bytes published. */
-export async function publishBytes(deps, text) {
-    const textStr = String(text ?? "");
-    if (textStr.trim().length === 0)
-        return { kind: "partial", what: "text", cause: "publishing empty content is refused — write something first" };
-    const bytes = new TextEncoder().encode(textStr);
+export const OPEN_NOTE = "OPEN: any peer node that can reach this node's content peer route and knows the key may read it. " +
+    "Not encryption; there is no retraction.";
+export const RESTRICTED_NOTE = "RESTRICTED: remote reads are served only to authenticated peer NODES matching a granted identity, " +
+    "or currently in/owning a granted group. The trusted local content listener is NOT restricted, the " +
+    "storage operator and prior recipients are not excluded, and grants on identical bytes merge by union — " +
+    "an earlier open or wider publication is not narrowed. Not encryption, not an availability guarantee.";
+/** Canonical, padded, standard-alphabet base64 — no whitespace, no URL-safe alphabet. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** A lone UTF-16 surrogate cannot be UTF-8 encoded losslessly (TextEncoder writes U+FFFD). */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** The access the caller DELIBERATELY asked for, or a refusal. Nothing is trimmed, filtered or
+ *  defaulted: an entry the node would reinterpret (blank, whitespace, comma-joined) is refused,
+ *  because the alternative is publishing to a set the caller did not name. */
+export function parseAccess(access, grants) {
+    if (access === "open") {
+        if (grants !== undefined)
+            return { kind: "partial", what: "authorizedPrincipals",
+                cause: 'access "open" takes no authorizedPrincipals — use access "restricted" to grant read access' };
+        return { mode: "open" };
+    }
+    if (access !== "restricted")
+        return { kind: "partial", what: "access",
+            cause: 'say access "open" (any peer with the key may read) or "restricted" (with authorizedPrincipals) — it is never inferred' };
+    if (!Array.isArray(grants) || grants.length === 0)
+        return { kind: "partial", what: "authorizedPrincipals",
+            cause: 'access "restricted" needs a non-empty list of identity/group names — nothing was published' };
+    if (grants.length > CONTENT_MAX_PRINCIPALS)
+        return { kind: "partial", what: "authorizedPrincipals",
+            cause: `at most ${CONTENT_MAX_PRINCIPALS} principals per publication — nothing was published` };
+    const principals = [];
+    for (const g of grants) {
+        if (typeof g !== "string" || !isValidPrincipalName(g))
+            return { kind: "partial", what: "authorizedPrincipals",
+                cause: `${JSON.stringify(g).slice(0, 80)} is not a principal name (1-128 of A-Z a-z 0-9 . _ -, no spaces or commas) — nothing was published` };
+        if (!principals.includes(g))
+            principals.push(g);
+    }
+    return { mode: "restricted", principals };
+}
+/** The ORIGINAL bytes to publish from exactly one of `text` / `base64`, or a refusal. */
+function parsePayload(text, base64) {
+    if ((text === undefined) === (base64 === undefined))
+        return { kind: "partial", what: "content", cause: "give exactly one of `text` (UTF-8) or `base64` (binary)" };
+    if (text !== undefined) {
+        if (typeof text !== "string" || text.trim().length === 0)
+            return { kind: "partial", what: "text", cause: "publishing empty content is refused — write something first" };
+        if (LONE_SURROGATE.test(text))
+            return { kind: "partial", what: "text", cause: "text contains an unpaired surrogate that UTF-8 cannot carry losslessly — use `base64`" };
+        const bytes = new TextEncoder().encode(text);
+        if (bytes.length > CONTENT_MAX_BYTES)
+            return { kind: "partial", what: "text", cause: `${bytes.length} UTF-8 bytes exceeds the ${CONTENT_MAX_BYTES}-byte inline bound` };
+        return { bytes, encoding: "text" };
+    }
+    if (typeof base64 !== "string" || base64.length === 0)
+        return { kind: "partial", what: "base64", cause: "publishing empty content is refused — give non-empty base64" };
+    if (base64.length > CONTENT_MAX_BASE64_CHARS)
+        return { kind: "partial", what: "base64",
+            cause: `${base64.length} base64 characters exceeds the ${CONTENT_MAX_BASE64_CHARS}-character bound (${CONTENT_MAX_BYTES} bytes)` };
+    const buf = BASE64.test(base64) ? Buffer.from(base64, "base64") : undefined;
+    // Round-trip equality rejects non-zero pad bits, so exactly one string names each byte sequence.
+    if (buf === undefined || buf.toString("base64") !== base64)
+        return { kind: "partial", what: "base64",
+            cause: "not canonical standard base64 (A-Z a-z 0-9 + /, `=` padding, no whitespace or URL-safe alphabet)" };
+    if (buf.length > CONTENT_MAX_BYTES)
+        return { kind: "partial", what: "base64", cause: `${buf.length} bytes exceeds the ${CONTENT_MAX_BYTES}-byte inline bound` };
+    return { bytes: new Uint8Array(buf), encoding: "base64" };
+}
+/** Publish text or binary to the content cache (READ-11, #8). `access` must be stated; a
+ *  restricted publication forwards its grants through the SDK's `authorizedPrincipals`. Every
+ *  refusal happens BEFORE any call. A node answer that is not 201 (e.g. HTTP 400 for an unknown
+ *  principal) is `partial publish` naming the node's answer — never `ok`, and never retried open;
+ *  a transport throw is `unreachable`. */
+export async function publishBytes(deps, req) {
+    const access = parseAccess(req.access, req.authorizedPrincipals);
+    if ("kind" in access)
+        return access;
+    const payload = parsePayload(req.text, req.base64);
+    if ("kind" in payload)
+        return payload;
+    const { bytes, encoding } = payload;
+    let r;
+    let sha256;
     try {
-        const sha256 = await sha256Hex(bytes);
-        const r = await deps.client.postContent(bytes);
-        return { kind: "ok", value: { key: r.key, size: r.size, sha256 } };
+        sha256 = await sha256Hex(bytes);
+        r = access.mode === "restricted"
+            ? await deps.client.postContent(bytes, { authorizedPrincipals: access.principals })
+            : await deps.client.postContent(bytes);
     }
     catch (e) {
-        return unreachableFrom(e, deps.contentUrl);
+        const message = e instanceof Error ? e.message : String(e);
+        const status = e instanceof ContentHttpError ? String(e.status) : /^postContent(?:Stream)?: HTTP (\d{3})\b/.exec(message)?.[1];
+        if (status === undefined)
+            return unreachableFrom(e, deps.contentUrl);
+        return {
+            kind: "partial",
+            what: "publish",
+            cause: status.startsWith("4")
+                ? `the content node refused it (${message}) — nothing was stored; an unknown principal name is answered HTTP 400. Not retried, never re-sent open.`
+                : `the content node answered ${message} — NOT a successful publication, and storage is unconfirmed. Not retried.`,
+        };
     }
+    if (r.size !== bytes.length)
+        return { kind: "partial", what: "publish",
+            cause: `the node reported ${r.size} bytes for key ${r.key} but ${bytes.length} were sent — treat this publication as unverified` };
+    return {
+        kind: "ok",
+        value: access.mode === "restricted"
+            ? { key: r.key, size: bytes.length, sha256, encoding, access: "restricted", authorizedPrincipals: access.principals, note: RESTRICTED_NOTE }
+            : { key: r.key, size: bytes.length, sha256, encoding, access: "open", note: OPEN_NOTE },
+    };
 }
-/** Fetch content from the cache by key and decode it to text (READ-10). Empty/blank key refused
- *  locally as `partial` BEFORE any call. A `null` from the SDK is the DEFINITIVE negative — no
- *  reachable holder — surfaced as `ok { value: null }`, NOT `not_found` (Pitfall 3); a throw is
- *  `unreachable`. Raw bytes are decoded to `text` and dropped (Pitfall 5). */
-export async function fetchBytes(deps, key) {
+/** Fetch content from the cache by key (READ-10, #8), returning the COMPLETE object as strict
+ *  UTF-8 `text` (default) or `base64` of the actual bytes. Empty/blank key or unknown encoding is
+ *  refused locally BEFORE any call. `null` is the DEFINITIVE negative (Pitfall 3); a throw or a
+ *  short/overlong transfer is `unreachable`. Over `CONTENT_MAX_BYTES`, or not valid UTF-8 in text
+ *  mode, answers `partial` with NO content — never a preview, never a lossy decode. */
+export async function fetchBytes(deps, key, encoding = "text") {
     const k = String(key ?? "").trim();
     if (k.length === 0)
         return { kind: "partial", what: "key", cause: "which content? a non-empty key is required" };
+    if (encoding !== "text" && encoding !== "base64")
+        return { kind: "partial", what: "encoding", cause: 'encoding is "text" (strict UTF-8) or "base64"' };
+    let bytes;
     try {
-        const bytes = await deps.client.getContent(k);
-        if (bytes === null)
+        const got = await deps.client.getContentStream(k);
+        if (got === null)
             return { kind: "ok", value: null };
-        return { kind: "ok", value: { key: k, size: bytes.length, sha256: await sha256Hex(bytes), text: new TextDecoder().decode(bytes) } };
+        if (got.size > CONTENT_MAX_BYTES) {
+            await got.stream.cancel().catch(() => undefined);
+            return { kind: "partial", what: "content",
+                cause: `the object is ${got.size} bytes, over the ${CONTENT_MAX_BYTES}-byte inline bound — nothing returned (no preview); streaming/range reads are not exposed` };
+        }
+        const reader = got.stream.getReader();
+        const parts = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.length;
+            if (total > got.size) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error(`content transfer overran its declared ${got.size} bytes — discarded`);
+            }
+            parts.push(value);
+        }
+        // The SDK errors the stream on a short read, so reaching here means exactly `got.size` bytes.
+        bytes = new Uint8Array(total);
+        let off = 0;
+        for (const p of parts) {
+            bytes.set(p, off);
+            off += p.length;
+        }
     }
     catch (e) {
         return unreachableFrom(e, deps.contentUrl);
     }
+    const sha256 = await sha256Hex(bytes);
+    if (encoding === "base64")
+        return { kind: "ok", value: { key: k, size: bytes.length, sha256, complete: true, encoding: "base64", base64: Buffer.from(bytes).toString("base64") } };
+    let text;
+    try {
+        // fatal: refuse rather than substitute U+FFFD; ignoreBOM: keep a leading BOM as content.
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return { kind: "partial", what: "text",
+            cause: `the object (${bytes.length} bytes, sha256 ${sha256}) is not valid UTF-8 — nothing lossy is returned; fetch with encoding "base64"` };
+    }
+    return { kind: "ok", value: { key: k, size: bytes.length, sha256, complete: true, encoding: "text", text } };
 }
 //# sourceMappingURL=content.js.map