@mcsherrylabs/evolver-mcp 0.11.0 → 0.12.0

package/deploy/release.json

@@ -1,5 +1,5 @@
 {
-  "nodeImage": "nexus.mcsherrylabs.com/evolver-node:v0.26.0",
+  "nodeImage": "nexus.mcsherrylabs.com/evolver-node:v0.26.1",
   "images": {
     "processor": "evolver-mcp-processor",
     "node": "evolver-mcp-node",

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,53 @@ 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>>;
+/** 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>>;
 //# 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":"AA8BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,SAAU,CAAC;AACzC,gGAAgG;AAChG,eAAO,MAAM,wBAAwB,QAAuC,CAAC;AAC7E,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;mFAGmF;AACnF,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,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACrG;AAED;;;0CAG0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;oBAEoB;AACpB,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IACvC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;kGAEkG;AAClG,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACzB,GAAG,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEtH;yBACyB;AACzB,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlE;AA4ED;;;;0CAI0C;AAC1C,wBAAsB,YAAY,CAChC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAmChC;AAED;;;;uFAIuF;AACvF,wBAAsB,UAAU,CAC9B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,OAAgB,GACzB,OAAO,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAiDrC"}

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 { 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);
+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.";
+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. */
+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 = /^postContent: 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

package/dist/content.js.map

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

package/dist/group-ownership.d.ts

@@ -0,0 +1,78 @@
+import type { Signer } from "@mcsherrylabs/evolver-client";
+import type { ChainReads } from "./read.js";
+import type { ToolResult } from "./result.js";
+import type { SignedGroup } from "./write.js";
+export interface OwnershipDeps {
+    readonly identity: string;
+    readonly signer: Signer;
+    readonly reads: ChainReads;
+}
+/** Rounds of life for a two-party transfer. Longer than `DEFAULT_TTL_OFFSET` (50, sized for no
+ *  human wait) because a second party must act, but never beyond the node's default
+ *  `max-ttl-offset` (RoutingConfig.DefaultMaxTtlOffset = 100): a longer ttl is `ttl_too_far`, and
+ *  a long-lived co-signed envelope is a bearer artefact. The default stays 10 rounds inside that
+ *  bound so the two parties' nodes may disagree slightly about the tip. Expiry is final. */
+export declare const OWNERSHIP_TTL_MAX = 100;
+export declare const OWNERSHIP_TTL_DEFAULT = 90;
+/** The one key type whose consent can be verified with a published SDK primitive. */
+export declare const CONSENT_KEY_TYPE = "Ed25519";
+export declare const INTENT_KIND = "evolver.group_ownership_intent.v1";
+export declare const CONSENT_KIND = "evolver.group_ownership_consent.v1";
+declare const PURPOSE = "AUTHORIZE";
+export interface OwnershipIntent {
+    readonly kind: typeof INTENT_KIND;
+    readonly txId: string;
+    readonly ledgerId: string;
+    readonly groupName: string;
+    readonly outgoingOwner: string;
+    readonly incomingOwner: string;
+    readonly expiresAtRound: number;
+    readonly preparedAtRound: number;
+    readonly maxToll: "0";
+    readonly next: string;
+}
+export interface OwnershipConsent {
+    readonly kind: typeof CONSENT_KIND;
+    readonly txId: string;
+    readonly ledgerId: string;
+    readonly groupName: string;
+    readonly outgoingOwner: string;
+    readonly incomingOwner: string;
+    readonly expiresAtRound: number;
+    readonly maxToll: "0";
+    readonly auth: {
+        readonly nodeId: string;
+        readonly keyType: string;
+        readonly keyLabel: string;
+        readonly purpose: typeof PURPOSE;
+        readonly signatureHex: string;
+    };
+    readonly next: string;
+}
+/**
+ * PREPARE (outgoing owner). Signs nothing; returns the public intent for the incoming owner.
+ */
+export declare function prepareOwnershipTransfer(deps: OwnershipDeps, params: {
+    groupName: unknown;
+    incomingOwner: unknown;
+    ttlRounds?: unknown;
+}): Promise<ToolResult<OwnershipIntent>>;
+/**
+ * CONSENT (incoming owner). Recomputes the intent's txId and signs it with THIS session's key.
+ */
+export declare function consentOwnershipTransfer(deps: OwnershipDeps, params: {
+    txId: unknown;
+    groupName: unknown;
+    outgoingOwner: unknown;
+    incomingOwner: unknown;
+    expiresAtRound: unknown;
+}): Promise<ToolResult<OwnershipConsent>>;
+/**
+ * FINALIZE (outgoing owner). Verifies the consent, signs as sender, assembles both auths, records.
+ */
+export declare function finalizeOwnershipTransfer(deps: OwnershipDeps, params: {
+    txId: unknown;
+    consent: unknown;
+}): Promise<ToolResult<SignedGroup>>;
+export {};
+//# sourceMappingURL=group-ownership.d.ts.map

package/dist/group-ownership.d.ts.map

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