summer-engine 3.2.1 → 3.4.0

package/dist/core/oauth.js

@@ -0,0 +1,309 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { readStoreJson, writeStoreJson } from "./store.js";
+import { readJsonResponse } from "./util/http.js";
+/**
+ * The Summer store sign-in for local tools (summer_publish_build): OAuth 2.1
+ * authorization code + PKCE against the same Supabase authorization server
+ * and resource the hosted MCP uses (mcp.summerengine.com/mcp), with a
+ * loopback redirect (RFC 8252). The access token's audience is the MCP
+ * resource, the one token the creator store accepts for agents (creator
+ * publishing spec, part C.3).
+ *
+ * The Summer CLI is one public client (no secret; PKCE proves each login).
+ * The authorization server matches redirect URIs exactly, so the CLI listens
+ * on one of a few fixed loopback ports and registers its client once per
+ * machine with exactly those redirect URIs. Later logins and refreshes reuse
+ * that client id (~/.summer/oauth-client); only --force registers anew.
+ *
+ * The token is stored in ~/.summer/oauth-token (0600) with its refresh token,
+ * separate from the CLI JWT in auth-token: the engine reads that file and
+ * expects the summer-cli contract.
+ */
+export const OAUTH_TOKEN_FILE = "oauth-token";
+export const OAUTH_CLIENT_FILE = "oauth-client";
+/** Loopback ports the Summer CLI client is registered for, tried in order. */
+export const STORE_LOGIN_PORTS = [47615, 47616, 47617];
+export const DEFAULT_MCP_RESOURCE_URL = "https://mcp.summerengine.com/mcp";
+export const MCP_RESOURCE_ENV = "SUMMER_MCP_RESOURCE_URL";
+const SCOPES = ["openid", "email", "offline_access"];
+const REFRESH_MARGIN_MS = 60_000;
+const LOGIN_TIMEOUT_MS = 10 * 60_000;
+export class OAuthError extends Error {
+    code;
+    recovery;
+    constructor(code, message, recovery) {
+        super(`${message} ${recovery}`);
+        this.code = code;
+        this.recovery = recovery;
+        this.name = "OAuthError";
+    }
+}
+const defaultDependencies = {
+    fetch: (input, init) => globalThis.fetch(input, init),
+    now: Date.now,
+};
+function isSafeUrl(value) {
+    try {
+        const url = new URL(value);
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        return !url.username && !url.password && (url.protocol === "https:" || (loopback && url.protocol === "http:"));
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveMcpResourceUrl(env = process.env) {
+    const value = env[MCP_RESOURCE_ENV]?.trim() || DEFAULT_MCP_RESOURCE_URL;
+    if (!isSafeUrl(value)) {
+        throw new OAuthError("oauth_resource_invalid", `${MCP_RESOURCE_ENV} must be an https URL (http only for localhost).`, `Recovery: unset ${MCP_RESOURCE_ENV} to use ${DEFAULT_MCP_RESOURCE_URL}.`);
+    }
+    return value;
+}
+async function getJson(deps, url) {
+    try {
+        const response = await deps.fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            return null;
+        const { json, parsed } = await readJsonResponse(response);
+        return parsed && json && typeof json === "object" ? json : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** RFC 9728 resource metadata, then RFC 8414 server metadata (path-aware first). */
+export async function discoverAuthorizationServer(resource, deps = defaultDependencies) {
+    const resourceUrl = new URL(resource);
+    const resourcePath = resourceUrl.pathname === "/" ? "" : resourceUrl.pathname.replace(/\/$/, "");
+    const prm = (await getJson(deps, `${resourceUrl.origin}/.well-known/oauth-protected-resource${resourcePath}`)) ??
+        (await getJson(deps, `${resourceUrl.origin}/.well-known/oauth-protected-resource`));
+    const issuer = Array.isArray(prm?.authorization_servers) ? prm.authorization_servers[0] : undefined;
+    if (prm?.resource !== resource || typeof issuer !== "string" || !isSafeUrl(issuer)) {
+        throw new OAuthError("oauth_discovery_failed", `${resource} did not publish its sign-in server.`, "Recovery: check your network and retry; if it repeats, the hosted Summer MCP is not available yet.");
+    }
+    const issuerUrl = new URL(issuer);
+    const issuerPath = issuerUrl.pathname === "/" ? "" : issuerUrl.pathname.replace(/\/$/, "");
+    const metadata = (await getJson(deps, `${issuerUrl.origin}/.well-known/oauth-authorization-server${issuerPath}`)) ??
+        (await getJson(deps, `${issuer.replace(/\/$/, "")}/.well-known/oauth-authorization-server`)) ??
+        (await getJson(deps, `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`));
+    const endpoints = [metadata?.authorization_endpoint, metadata?.token_endpoint, metadata?.registration_endpoint];
+    if (metadata?.issuer !== issuer || !endpoints.every((value) => typeof value === "string" && isSafeUrl(value))) {
+        throw new OAuthError("oauth_discovery_failed", `The sign-in server ${issuer} did not publish usable OAuth metadata.`, "Recovery: retry later; if it repeats, report the Summer sign-in server as unhealthy.");
+    }
+    return {
+        issuer,
+        authorizationEndpoint: endpoints[0],
+        tokenEndpoint: endpoints[1],
+        registrationEndpoint: endpoints[2],
+    };
+}
+async function postForm(deps, url, form) {
+    let response;
+    try {
+        response = await deps.fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams(form).toString(),
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new OAuthError("oauth_network_failed", `The sign-in server did not answer: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: check your network and retry.");
+    }
+    const { json } = await readJsonResponse(response);
+    const body = (json && typeof json === "object" ? json : {});
+    if (!response.ok) {
+        const reason = typeof body.error === "string" ? body.error : `http_${response.status}`;
+        throw new OAuthError(reason === "invalid_grant" ? "oauth_grant_invalid" : "oauth_token_refused", `The sign-in server refused the token request (${reason}).`, 'Recovery: run "summer login --store --force" and approve access again.');
+    }
+    return body;
+}
+function tokenFromResponse(body, base, now, previousRefresh) {
+    if (typeof body.access_token !== "string" || !body.access_token) {
+        throw new OAuthError("oauth_token_invalid", "The sign-in server returned no access token.", 'Recovery: run "summer login --store --force" again.');
+    }
+    const expiresIn = typeof body.expires_in === "number" && body.expires_in > 0 ? body.expires_in : 3600;
+    const refreshToken = typeof body.refresh_token === "string" ? body.refresh_token : previousRefresh;
+    return {
+        ...base,
+        accessToken: body.access_token,
+        ...(refreshToken ? { refreshToken } : {}),
+        expiresAt: new Date(now + expiresIn * 1000).toISOString(),
+        ...(typeof body.scope === "string" ? { scope: body.scope } : {}),
+    };
+}
+function pkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+/** A one-shot loopback listener on 127.0.0.1 for the authorization code. */
+async function listenForCode(state, timeoutMs, ports) {
+    let settle;
+    const code = new Promise((resolve, reject) => (settle = { resolve, reject }));
+    // An unawaited rejection (timeout before anyone awaits) must not crash the process.
+    code.catch(() => undefined);
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/callback") {
+            response.writeHead(404).end();
+            return;
+        }
+        const error = url.searchParams.get("error");
+        const ok = !error && url.searchParams.get("state") === state && url.searchParams.get("code");
+        response.writeHead(ok ? 200 : 400, { "content-type": "text/html; charset=utf-8" });
+        response.end(ok
+            ? "<!doctype html><title>Summer</title><p>Signed in to Summer. You can close this tab.</p>"
+            : "<!doctype html><title>Summer</title><p>Sign-in did not finish. Return to the terminal.</p>");
+        if (ok)
+            settle.resolve(url.searchParams.get("code"));
+        else
+            settle.reject(new OAuthError(error === "access_denied" ? "oauth_access_denied" : "oauth_callback_invalid", error ? `Sign-in was not approved (${error}).` : "The sign-in answer did not match this login.", 'Recovery: run "summer login --store" again and approve access.'));
+    });
+    let port = 0;
+    for (const candidate of ports) {
+        const listening = await new Promise((resolve, reject) => {
+            const onError = (error) => error.code === "EADDRINUSE" || error.code === "EACCES" ? resolve(false) : reject(error);
+            server.once("error", onError);
+            server.listen(candidate, "127.0.0.1", () => {
+                server.off("error", onError);
+                resolve(true);
+            });
+        });
+        if (listening) {
+            port = candidate;
+            break;
+        }
+    }
+    if (!port) {
+        throw new OAuthError("oauth_ports_busy", `Sign-in needs one free local port (${ports.join(", ")}); all are in use.`, 'Recovery: close the program using them (or an earlier "summer login --store" still waiting), then retry.');
+    }
+    const timer = setTimeout(() => settle.reject(new OAuthError("oauth_timeout", `Sign-in did not finish within ${Math.round(timeoutMs / 60_000)} minutes.`, 'Recovery: run "summer login --store" again.')), timeoutMs);
+    return {
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        code,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+        },
+    };
+}
+async function readStoredOAuthClient(issuer, redirectUris) {
+    const client = await readStoreJson(OAUTH_CLIENT_FILE).catch(() => null);
+    const sameRedirects = Array.isArray(client?.redirectUris) &&
+        client.redirectUris.length === redirectUris.length &&
+        client.redirectUris.every((uri, index) => uri === redirectUris[index]);
+    return client?.schemaVersion === 1 && client.issuer === issuer && sameRedirects && typeof client.clientId === "string" && client.clientId
+        ? client.clientId
+        : null;
+}
+/** One registration per machine and authorization server: a public client for the fixed loopback redirects. */
+async function registerClient(deps, server, redirectUris) {
+    let registration;
+    try {
+        registration = await deps.fetch(server.registrationEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                client_name: "Summer CLI",
+                redirect_uris: redirectUris,
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+                scope: SCOPES.join(" "),
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new OAuthError("oauth_network_failed", `The sign-in server did not answer: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: check your network and retry.");
+    }
+    const { json } = await readJsonResponse(registration);
+    const clientId = json?.client_id;
+    if (!registration.ok || typeof clientId !== "string" || !clientId) {
+        throw new OAuthError("oauth_registration_failed", `The sign-in server did not register the Summer CLI (${registration.status}).`, "Recovery: retry; if it repeats, report the Summer sign-in server as unhealthy.");
+    }
+    const stored = { schemaVersion: 1, issuer: server.issuer, clientId, redirectUris };
+    await writeStoreJson(OAUTH_CLIENT_FILE, stored);
+    return clientId;
+}
+/** Browser sign-in (authorization code + PKCE) that stores ~/.summer/oauth-token. */
+export async function runStoreLogin(deps) {
+    const resource = resolveMcpResourceUrl();
+    const server = await discoverAuthorizationServer(resource, deps);
+    const state = randomBytes(16).toString("base64url");
+    const ports = deps.ports ?? STORE_LOGIN_PORTS;
+    const redirectUris = ports.map((port) => `http://127.0.0.1:${port}/callback`);
+    const callback = await listenForCode(state, deps.timeoutMs ?? LOGIN_TIMEOUT_MS, ports);
+    try {
+        const clientId = (!deps.newClient && (await readStoredOAuthClient(server.issuer, redirectUris))) ||
+            (await registerClient(deps, server, redirectUris));
+        const { verifier, challenge } = pkce();
+        const authorize = new URL(server.authorizationEndpoint);
+        for (const [key, value] of Object.entries({
+            response_type: "code",
+            client_id: clientId,
+            redirect_uri: callback.redirectUri,
+            scope: SCOPES.join(" "),
+            state,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+            resource,
+        })) {
+            authorize.searchParams.set(key, value);
+        }
+        deps.log(`Approve Summer store access in your browser: ${authorize}`);
+        try {
+            await deps.openUrl(authorize.toString());
+        }
+        catch {
+            deps.log("Could not open the browser. Copy the URL above and open it manually.");
+        }
+        const code = await callback.code;
+        const now = deps.now();
+        const body = await postForm(deps, server.tokenEndpoint, {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: callback.redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+            resource,
+        });
+        const token = tokenFromResponse(body, { schemaVersion: 1, resource, issuer: server.issuer, tokenEndpoint: server.tokenEndpoint, clientId }, now);
+        await writeStoreJson(OAUTH_TOKEN_FILE, token);
+        return token;
+    }
+    finally {
+        callback.close();
+    }
+}
+export async function readStoredOAuthToken() {
+    const token = await readStoreJson(OAUTH_TOKEN_FILE).catch(() => null);
+    return token && token.schemaVersion === 1 && typeof token.accessToken === "string" ? token : null;
+}
+/**
+ * A current store access token: the stored one, refreshed when it expires
+ * within a minute.
+ */
+export async function getStoreAccessToken(deps = defaultDependencies) {
+    const stored = await readStoredOAuthToken();
+    if (!stored) {
+        throw new OAuthError("store_login_required", "This machine is not signed in to the Summer store.", 'Recovery: run "summer login --store" in a terminal and approve access in the browser, then retry.');
+    }
+    if (Date.parse(stored.expiresAt) - deps.now() > REFRESH_MARGIN_MS)
+        return stored.accessToken;
+    if (!stored.refreshToken) {
+        throw new OAuthError("store_login_expired", "The Summer store sign-in expired.", 'Recovery: run "summer login --store --force", then retry.');
+    }
+    const now = deps.now();
+    const body = await postForm(deps, stored.tokenEndpoint, {
+        grant_type: "refresh_token",
+        refresh_token: stored.refreshToken,
+        client_id: stored.clientId,
+        resource: stored.resource,
+    });
+    const { accessToken: _a, refreshToken: _r, expiresAt: _e, scope: _s, ...base } = stored;
+    const next = tokenFromResponse(body, base, now, stored.refreshToken);
+    await writeStoreJson(OAUTH_TOKEN_FILE, next);
+    return next.accessToken;
+}

package/dist/core/util/zip-write.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Write a plain .zip (deflate, one entry per file) by streaming each file, so
+ * a large export never sits in memory. Sizes and CRCs go in a data descriptor
+ * after each entry (general purpose bit 3). Entries and archives over 4 GiB
+ * are refused: no zip64. Unix permissions are kept so an executable stays
+ * executable after unzip.
+ */
+export interface ZipWriteEntry {
+    /** Path inside the zip, "/"-separated. */
+    name: string;
+    /** File on disk. */
+    source: string;
+}
+export declare function crc32Update(crc: number, data: Uint8Array): number;
+export declare function writeZip(out: string, entries: ZipWriteEntry[]): Promise<{
+    entries: number;
+    bytes: number;
+}>;

package/dist/core/util/zip-write.js

@@ -0,0 +1,112 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { once } from "node:events";
+import { createDeflateRaw } from "node:zlib";
+const MAX_32 = 0xffffffff;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+export function crc32Update(crc, data) {
+    let c = ~crc >>> 0;
+    for (let i = 0; i < data.length; i++)
+        c = CRC_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    return ~c >>> 0;
+}
+function dosTime(date) {
+    const year = Math.max(1980, date.getFullYear());
+    return {
+        time: (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2),
+        date: ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
+    };
+}
+export async function writeZip(out, entries) {
+    const stream = createWriteStream(out);
+    let offset = 0;
+    const write = async (chunk) => {
+        offset += chunk.length;
+        if (!stream.write(chunk))
+            await once(stream, "drain");
+    };
+    const central = [];
+    try {
+        for (const entry of entries) {
+            const info = await stat(entry.source);
+            const name = Buffer.from(entry.name, "utf8");
+            const { time, date } = dosTime(info.mtime);
+            const headerOffset = offset;
+            const local = Buffer.alloc(30);
+            local.writeUInt32LE(0x04034b50, 0);
+            local.writeUInt16LE(20, 4);
+            local.writeUInt16LE(0x0808, 6); // data descriptor + UTF-8 names
+            local.writeUInt16LE(8, 8);
+            local.writeUInt16LE(time, 10);
+            local.writeUInt16LE(date, 12);
+            local.writeUInt16LE(name.length, 26);
+            await write(Buffer.concat([local, name]));
+            let crc = 0;
+            let size = 0;
+            const start = offset;
+            const deflate = createDeflateRaw({ level: 6 });
+            const pumped = (async () => {
+                for await (const chunk of deflate)
+                    await write(chunk);
+            })();
+            for await (const chunk of createReadStream(entry.source)) {
+                crc = crc32Update(crc, chunk);
+                size += chunk.length;
+                if (!deflate.write(chunk))
+                    await once(deflate, "drain");
+            }
+            deflate.end();
+            await pumped;
+            const compressed = offset - start;
+            if (size > MAX_32 || compressed > MAX_32 || offset > MAX_32) {
+                throw new Error(`${entry.name} is too large for a zip without zip64 (over 4 GiB).`);
+            }
+            const descriptor = Buffer.alloc(16);
+            descriptor.writeUInt32LE(0x08074b50, 0);
+            descriptor.writeUInt32LE(crc, 4);
+            descriptor.writeUInt32LE(compressed, 8);
+            descriptor.writeUInt32LE(size, 12);
+            await write(descriptor);
+            const header = Buffer.alloc(46);
+            header.writeUInt32LE(0x02014b50, 0);
+            header.writeUInt16LE((3 << 8) | 20, 4); // made by Unix, so the mode below counts
+            header.writeUInt16LE(20, 6);
+            header.writeUInt16LE(0x0808, 8);
+            header.writeUInt16LE(8, 10);
+            header.writeUInt16LE(time, 12);
+            header.writeUInt16LE(date, 14);
+            header.writeUInt32LE(crc, 16);
+            header.writeUInt32LE(compressed, 20);
+            header.writeUInt32LE(size, 24);
+            header.writeUInt16LE(name.length, 28);
+            header.writeUInt32LE((((info.mode & 0o777) | 0o100000) << 16) >>> 0, 38);
+            header.writeUInt32LE(headerOffset, 42);
+            central.push(header, name);
+        }
+        const directory = Buffer.concat(central);
+        const end = Buffer.alloc(22);
+        end.writeUInt32LE(0x06054b50, 0);
+        end.writeUInt16LE(entries.length, 8);
+        end.writeUInt16LE(entries.length, 10);
+        end.writeUInt32LE(directory.length, 12);
+        end.writeUInt32LE(offset, 16);
+        if (entries.length > 0xffff || offset + directory.length > MAX_32) {
+            throw new Error("The archive is too large for a zip without zip64.");
+        }
+        await write(Buffer.concat([directory, end]));
+    }
+    finally {
+        stream.end();
+        await once(stream, "close");
+    }
+    return { entries: entries.length, bytes: offset };
+}

package/dist/core/util/zip.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A minimal ZIP central-directory reader: entry names and sizes, plus small
+ * entries read whole (stored or deflated). Reads only the tail of the file
+ * and the bytes of the entries asked for, so a 40 GB export costs a few
+ * reads. ZIP64 sizes and offsets are honoured. No CRC check: the caller
+ * verifies content by hash where it matters.
+ */
+export interface ZipEntry {
+    name: string;
+    method: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    localHeaderOffset: number;
+    encrypted: boolean;
+}
+export declare class ZipReadError extends Error {
+    constructor(message: string);
+}
+/** Every entry in the zip's central directory. */
+export declare function readZipEntries(path: string): Promise<ZipEntry[]>;
+/** One entry's bytes, for small entries (manifests, configuration). */
+export declare function readZipEntry(path: string, entry: ZipEntry, maxBytes?: number): Promise<Buffer>;

package/dist/core/util/zip.js

@@ -0,0 +1,140 @@
+import { open } from "node:fs/promises";
+import { inflateRawSync } from "node:zlib";
+export class ZipReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ZipReadError";
+    }
+}
+const EOCD = 0x06054b50;
+const ZIP64_LOCATOR = 0x07064b50;
+const ZIP64_EOCD = 0x06064b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const MAX_TAIL = 0xffff + 22;
+const MAX_DIRECTORY_BYTES = 64 * 1024 * 1024;
+async function readAt(handle, position, length) {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, position);
+    if (bytesRead !== length)
+        throw new ZipReadError("The zip ends early.");
+    return buffer;
+}
+const u64 = (buffer, at) => Number(buffer.readBigUInt64LE(at));
+async function readDirectory(handle, size) {
+    const tailLength = Math.min(size, MAX_TAIL);
+    const tail = await readAt(handle, size - tailLength, tailLength);
+    let eocd = -1;
+    for (let at = tail.length - 22; at >= 0; at--) {
+        if (tail.readUInt32LE(at) === EOCD) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new ZipReadError("Not a zip file (no end of central directory).");
+    let count = tail.readUInt16LE(eocd + 10);
+    let directorySize = tail.readUInt32LE(eocd + 12);
+    let directoryOffset = tail.readUInt32LE(eocd + 16);
+    if (count === 0xffff || directorySize === 0xffffffff || directoryOffset === 0xffffffff) {
+        const locatorAt = eocd - 20;
+        if (locatorAt < 0 || tail.readUInt32LE(locatorAt) !== ZIP64_LOCATOR) {
+            throw new ZipReadError("The zip's ZIP64 locator is missing.");
+        }
+        const record = await readAt(handle, u64(tail, locatorAt + 8), 56);
+        if (record.readUInt32LE(0) !== ZIP64_EOCD)
+            throw new ZipReadError("The zip's ZIP64 record is damaged.");
+        count = u64(record, 32);
+        directorySize = u64(record, 40);
+        directoryOffset = u64(record, 48);
+    }
+    if (directorySize > MAX_DIRECTORY_BYTES || directoryOffset + directorySize > size) {
+        throw new ZipReadError("The zip's central directory is out of range.");
+    }
+    const directory = await readAt(handle, directoryOffset, directorySize);
+    const entries = [];
+    let at = 0;
+    for (let index = 0; index < count; index++) {
+        if (at + 46 > directory.length || directory.readUInt32LE(at) !== CENTRAL) {
+            throw new ZipReadError("The zip's central directory is damaged.");
+        }
+        const flags = directory.readUInt16LE(at + 8);
+        const method = directory.readUInt16LE(at + 10);
+        let compressedSize = directory.readUInt32LE(at + 20);
+        let uncompressedSize = directory.readUInt32LE(at + 24);
+        const nameLength = directory.readUInt16LE(at + 28);
+        const extraLength = directory.readUInt16LE(at + 30);
+        const commentLength = directory.readUInt16LE(at + 32);
+        let localHeaderOffset = directory.readUInt32LE(at + 42);
+        const name = directory.toString("utf8", at + 46, at + 46 + nameLength);
+        // ZIP64 extended information: only the fields that overflowed, in order.
+        let extra = at + 46 + nameLength;
+        const extraEnd = extra + extraLength;
+        while (extra + 4 <= extraEnd) {
+            const id = directory.readUInt16LE(extra);
+            const length = directory.readUInt16LE(extra + 2);
+            if (id === 0x0001) {
+                let field = extra + 4;
+                if (uncompressedSize === 0xffffffff) {
+                    uncompressedSize = u64(directory, field);
+                    field += 8;
+                }
+                if (compressedSize === 0xffffffff) {
+                    compressedSize = u64(directory, field);
+                    field += 8;
+                }
+                if (localHeaderOffset === 0xffffffff)
+                    localHeaderOffset = u64(directory, field);
+            }
+            extra += 4 + length;
+        }
+        entries.push({
+            name,
+            method,
+            compressedSize,
+            uncompressedSize,
+            localHeaderOffset,
+            encrypted: (flags & 1) !== 0,
+        });
+        at = extraEnd + commentLength;
+    }
+    return entries;
+}
+/** Every entry in the zip's central directory. */
+export async function readZipEntries(path) {
+    const handle = await open(path, "r");
+    try {
+        return await readDirectory(handle, (await handle.stat()).size);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** One entry's bytes, for small entries (manifests, configuration). */
+export async function readZipEntry(path, entry, maxBytes = 1024 * 1024) {
+    if (entry.encrypted)
+        throw new ZipReadError(`${entry.name} is encrypted.`);
+    if (entry.uncompressedSize > maxBytes || entry.compressedSize > maxBytes) {
+        throw new ZipReadError(`${entry.name} is larger than ${maxBytes} bytes.`);
+    }
+    const handle = await open(path, "r");
+    try {
+        const header = await readAt(handle, entry.localHeaderOffset, 30);
+        if (header.readUInt32LE(0) !== LOCAL)
+            throw new ZipReadError(`${entry.name} has a damaged local header.`);
+        const dataAt = entry.localHeaderOffset + 30 + header.readUInt16LE(26) + header.readUInt16LE(28);
+        const data = await readAt(handle, dataAt, entry.compressedSize);
+        if (entry.method === 0)
+            return data;
+        if (entry.method === 8) {
+            const inflated = inflateRawSync(data, { maxOutputLength: maxBytes });
+            if (inflated.length !== entry.uncompressedSize)
+                throw new ZipReadError(`${entry.name} did not inflate to its size.`);
+            return inflated;
+        }
+        throw new ZipReadError(`${entry.name} uses unsupported compression method ${entry.method}.`);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/mcp/hosted-mount.d.ts

@@ -0,0 +1,50 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type HostedClient, type HostedConnectDependencies } from "../core/hosted-mcp.js";
+export type { HostedClient };
+/**
+ * One Summer Engine MCP. The cloud tools a creator's agent needs to publish
+ * (projects, store page, build upload, submit for the owner's approval, the
+ * board, Grow) live on the hosted Summer Engine MCP at mcp.summerengine.com,
+ * the same server ChatGPT and Claude connect to. This module mounts them into
+ * the local MCP so a local agent sees one server: each hosted tool, prompt
+ * and resource is registered here under its own name and forwarded with the
+ * person's store sign-in ("summer login --store"; the token's audience is
+ * that server). A name the local MCP already has stays local (the engine and
+ * generation tools keep their CLI-token path).
+ *
+ * Mounting runs after connect. The first tools/list waits for a mount in
+ * progress (up to FIRST_LIST_WAIT_MS), so a host that lists tools once still
+ * sees the store tools; a slower mount adds them later (tools/list_changed).
+ * Without a store sign-in the mount fails at once, and one tool,
+ * summer_store_tools, says how to sign in and mounts on the next call.
+ */
+export declare const STORE_TOOLS_STATUS = "summer_store_tools";
+/** How long the first tools/list waits for a mount in progress, so hosts that list once see the store tools. */
+export declare const FIRST_LIST_WAIT_MS = 5000;
+export type HostedMountDependencies = HostedConnectDependencies;
+export declare const defaultHostedMountDependencies: HostedMountDependencies;
+export interface HostedMountState {
+    status: "idle" | "mounting" | "mounted" | "unavailable";
+    tools: string[];
+    prompts: string[];
+    resources: string[];
+    /** Hosted names the local MCP already defines (kept local). */
+    collisions: string[];
+    error?: {
+        code: string;
+        message: string;
+        recovery: string;
+    };
+}
+/**
+ * Get the server ready for hosted tools before the transport connects (the
+ * SDK fixes capabilities at connect): resource handlers exist, and tools/list
+ * reports each mounted tool's own JSON Schema rather than the passthrough one.
+ * Returns mount(), which callers run after connect without awaiting it.
+ */
+export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: {
+    firstListWaitMs?: number;
+}): {
+    mount: () => Promise<HostedMountState>;
+    state: HostedMountState;
+};