@spacefast/common 0.0.13 → 0.0.17

package/dist/utils/pages.js

@@ -1,20 +1,10 @@
+import { defaultTreeAdapter, parse } from "parse5";
 import { SPACEFAST_WORDMARK_PATH } from "../brand-assets.js";
 import { CUSTOM_PAGE_IDS, PAGE_CATALOG, PAGE_ELEMENTS, PAGE_LAYOUT_FILE, PAGE_SOURCE_MAX_BYTES, SITE_PAGE_IDS, } from "../contracts/pages.js";
 import { SPACE_CONFIG_ACCEPTED_FILES } from "../contracts/space-config.js";
 import { derivePageColors, PAGE_COLOR_DEFAULTS } from "./page-colors.js";
 import { PAGE_EMBEDDED_FONT_FACES, PAGE_FONT_FACES } from "./page-fonts.js";
-/**
- * One URL, one representation. A file's bare path always serves its bytes;
- * the preview page is reachable only under this query flag. The alternative —
- * negotiating on `Accept` at the bare path — depends on `Vary`, which the edge
- * ignores, so whichever client arrived first pinned that representation for
- * everyone (an `<img>` could poison the human's link for a year).
- */
-export const PAGE_PREVIEW_QUERY = "spacefast_view";
-/** The preview page for a file whose bytes live at `fileHref`. */
-export function previewPageHref(fileHref) {
-    return `${fileHref}${fileHref.includes("?") ? "&" : "?"}${PAGE_PREVIEW_QUERY}=1`;
-}
+export { PAGE_PREVIEW_QUERY, previewPageHref } from "./page-preview.js";
 const encoder = new TextEncoder();
 const knownElements = new Set(PAGE_ELEMENTS);
 const customPageIds = new Set(CUSTOM_PAGE_IDS);
@@ -102,6 +92,10 @@ function renderElement(element, context) {
             return context.content ?? "";
         case "sf-denial-context":
             return runtimeSlot("denial", '<p class="sf-copy">This page is private.</p>');
+        case "sf-access-status":
+            return runtimeSlot("access-status", "");
+        case "sf-access-lanes":
+            return runtimeSlot("access-lanes", '<p class="sf-copy">This page is private.</p>');
         case "sf-page-path":
             return context.displayPath
                 ? escapePageHtml(context.displayPath)
@@ -150,6 +144,35 @@ function foundElements(source) {
         result.add((match[1] ?? "").toLowerCase());
     return [...result];
 }
+function accessCspBlocksForms(source) {
+    const documentNodes = [...parse(source).childNodes];
+    const head = documentNodes
+        .flatMap((node) => defaultTreeAdapter.isElementNode(node) && node.tagName === "html" ? node.childNodes : [])
+        .find((node) => defaultTreeAdapter.isElementNode(node) && node.tagName === "head");
+    if (!head || !defaultTreeAdapter.isElementNode(head))
+        return false;
+    const pending = [...head.childNodes];
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (!node || !defaultTreeAdapter.isElementNode(node))
+            continue;
+        if (node.tagName === "meta") {
+            const attributes = new Map(node.attrs.map(({ name, value }) => [name, value]));
+            if (attributes.get("http-equiv")?.trim().toLowerCase() === "content-security-policy") {
+                const policy = (attributes.get("content") ?? "")
+                    .split(";")
+                    .map((directive) => directive.trim().split(/\s+/))
+                    .filter((directive) => directive[0]);
+                const formAction = policy.find((directive) => directive[0]?.toLowerCase() === "form-action");
+                if (formAction &&
+                    !formAction.slice(1).some((expression) => expression.toLowerCase() === "'self'"))
+                    return true;
+            }
+        }
+        pending.push(...node.childNodes);
+    }
+    return false;
+}
 export function validatePageSources(input) {
     const diagnostics = [];
     for (const [sourcePath, source] of Object.entries(input.pages)) {
@@ -193,6 +216,7 @@ export function validatePageSources(input) {
                 element === "sf-spacefast-branding" ||
                 (id === "404" && element === "sf-page-path") ||
                 (id === "denied" && element === "sf-denial-context") ||
+                (id === "access" && (element === "sf-access-status" || element === "sf-access-lanes")) ||
                 (id === "index" &&
                     (element === "sf-files" ||
                         element === "sf-page-path" ||
@@ -215,7 +239,23 @@ export function validatePageSources(input) {
                 message: "The index page does not render <sf-files>.",
                 path,
             });
-        if (id === "denied" &&
+        // Without the lane slot the runtime has nowhere to inject the working
+        // sign-in/password/request blocks and the template ships a dead gate.
+        if (id === "access" && !/<\s*sf-access-lanes\b/i.test(source))
+            diagnostics.push({
+                severity: "error",
+                code: "access_lanes_missing",
+                message: "The access page must render <sf-access-lanes> so visitors keep a way in.",
+                path,
+            });
+        if (id === "access" && accessCspBlocksForms(source))
+            diagnostics.push({
+                severity: "error",
+                code: "access_csp_form_action_missing_self",
+                message: "The access page CSP must allow its runtime forms: use form-action 'self' when declaring form-action.",
+                path,
+            });
+        if ((id === "denied" || id === "access") &&
             /<\s*meta\b[^>]*\bname\s*=\s*["']robots["'][^>]*\bcontent\s*=\s*["'][^"']*\bindex\b/i.test(source))
             diagnostics.push({
                 severity: "warning",
@@ -322,15 +362,19 @@ export function defaultPageBody(id) {
 // themes, so buttons and links remain readable for every accepted accent.
 const defaultPageColors = derivePageColors({});
 const sharedCss = `/*sf-default-fonts*/:root{color-scheme:light dark;--sf-accent:${PAGE_COLOR_DEFAULTS.accent};--sf-bg:${PAGE_COLOR_DEFAULTS.bg};--sf-fg:${PAGE_COLOR_DEFAULTS.fg};--sf-muted:${PAGE_COLOR_DEFAULTS.muted};--sf-card:${PAGE_COLOR_DEFAULTS.card};--sf-border:${PAGE_COLOR_DEFAULTS.border};--sf-link:${defaultPageColors.link};--sf-on-accent:${defaultPageColors.onAccent};--sf-error:#a82d1a;--sf-font:"Haskoy",-apple-system,BlinkMacSystemFont,ui-sans-serif,"Segoe UI",sans-serif;--sf-display-font:"Merriweather",Georgia,serif;--sf-mono:ui-monospace,"SF Mono",Menlo,Consolas,monospace}*{box-sizing:border-box}html{min-width:320px;background:var(--sf-bg);-webkit-font-smoothing:antialiased}body{margin:0;min-height:100vh;background:var(--sf-bg);color:var(--sf-fg);font:14px/1.65 var(--sf-font)}a{color:inherit}.sf-page{min-height:100vh;display:flex;flex-direction:column;padding:clamp(22px,4vw,44px)}.sf-header{display:flex;align-items:center;min-height:32px}.sf-page-center .sf-header{justify-content:center}.sf-brand{display:inline-flex;min-width:0;align-items:center;gap:10px;color:var(--sf-fg);text-decoration:none}.sf-brand-mark{width:7px;height:7px;flex:none;background:var(--sf-accent)}.sf-logo{width:28px;height:28px;flex:none;object-fit:contain}.sf-brand strong{min-width:0;overflow-wrap:anywhere;font-size:13px;font-weight:600}.sf-main{flex:1;width:100%;padding:clamp(34px,9vh,84px) 0}.sf-page-plain .sf-main{max-width:680px}.sf-page-center .sf-main{max-width:620px;margin:auto;display:flex;flex-direction:column;align-items:center;text-align:center}.sf-eyebrow{margin:0 0 14px;color:var(--sf-muted);font:500 11px/1.5 var(--sf-mono);letter-spacing:.12em;text-transform:uppercase;overflow-wrap:anywhere}.sf-page-center .sf-eyebrow{margin-bottom:16px}h1{max-width:20ch;margin:0 0 12px;color:var(--sf-fg);font:430 clamp(1.9rem,5vw,2.8rem)/1.22 var(--sf-display-font);letter-spacing:-.012em;text-wrap:balance}.sf-copy,.sf-sub{max-width:52ch;margin:0;color:var(--sf-muted);text-wrap:pretty}.sf-inline-path{font-family:var(--sf-mono);font-size:.9em;color:var(--sf-fg);overflow-wrap:anywhere}.sf-actions{display:flex;flex-wrap:wrap;align-items:center;gap:14px;margin-top:22px}.sf-page-center .sf-actions{justify-content:center}.sf-button{display:inline-flex;min-height:44px;align-items:center;justify-content:center;border:0;background:var(--sf-accent);color:var(--sf-on-accent);padding:10px 16px;font:600 13px/1.4 var(--sf-font);text-decoration:none;cursor:pointer}.sf-ghost{color:var(--sf-muted);text-underline-offset:3px}.sf-button:hover{filter:brightness(1.06)}a:focus-visible,button:focus-visible{outline:2px solid var(--sf-link);outline-offset:2px}.sf-copy+.sf-copy{margin-top:12px}.sf-files{width:100%;margin:24px 0 0;padding:0;list-style:none}.sf-files li{display:flex;min-width:0;align-items:baseline;gap:18px;border-bottom:1px solid var(--sf-border)}.sf-files a{min-width:0;flex:1;padding:10px 2px;color:var(--sf-fg);font-weight:500;text-decoration:none}.sf-files a:hover{color:var(--sf-link)}.sf-file-name{overflow-wrap:anywhere}.sf-file-size{flex:none;padding:10px 2px;color:var(--sf-muted);font:12px/1.5 var(--sf-mono);white-space:nowrap}.sf-empty{max-width:420px;margin:24px 0 0;border:1px dashed var(--sf-border);padding:18px 20px;color:var(--sf-muted)}.sf-preview-wrap{width:min(100%,560px);aspect-ratio:16/9;margin:10px 0 18px;overflow:hidden;background:#fff;outline:1px solid color-mix(in srgb,var(--sf-fg) 10%,transparent);outline-offset:-1px}.sf-preview{display:block;width:100%;height:100%;border:0;object-fit:contain}.sf-file-meta{width:min(100%,560px);margin:0}.sf-file-meta div{display:flex;min-width:0;justify-content:space-between;gap:20px;border-bottom:1px solid var(--sf-border);padding:9px 2px}.sf-file-meta dt{color:var(--sf-fg);font-weight:600}.sf-file-meta dd{min-width:0;margin:0;color:var(--sf-muted);font-family:var(--sf-mono);overflow-wrap:anywhere;text-align:right}.sf-colophon{display:flex;flex-direction:column;align-items:center;gap:10px;padding:44px 0 26px;margin-top:auto;color:var(--sf-muted)}.sf-page-plain .sf-colophon{align-items:flex-start}.sf-colophon-row{display:flex;align-items:center;gap:20px;flex-wrap:wrap}.sf-powered{display:inline-flex;align-items:center;gap:10px;cursor:pointer;outline:none}.sf-powered-line{display:none;font-size:12px;color:var(--sf-muted)}.sf-powered:hover .sf-powered-line,.sf-powered:focus .sf-powered-line,.sf-powered:focus-within .sf-powered-line{display:inline}.sf-powered-line a{color:var(--sf-link);text-decoration:underline;text-underline-offset:3px}.sf-help{font-size:12px;color:var(--sf-muted);text-decoration:underline;text-underline-offset:3px}.sf-help:hover{color:var(--sf-fg)}.sf-wordmark{display:block;flex:none;width:auto;height:11px}.sf-wordmark-shadow{fill:var(--sf-accent)}.sf-wordmark-plate{fill:#141419}.sf-wordmark-paper{fill:#fbf8f1}@media(max-width:520px){.sf-page{padding:20px}.sf-button{min-height:48px}.sf-file-meta div{flex-direction:column;gap:2px}.sf-file-meta dd{text-align:left}.sf-colophon{padding-top:32px}}@media(prefers-color-scheme:dark){:root{--sf-bg:${PAGE_COLOR_DEFAULTS.darkBg};--sf-fg:${PAGE_COLOR_DEFAULTS.darkFg};--sf-muted:${PAGE_COLOR_DEFAULTS.darkMuted};--sf-card:${PAGE_COLOR_DEFAULTS.darkCard};--sf-border:${PAGE_COLOR_DEFAULTS.darkBorder};--sf-link:${defaultPageColors.linkDark};--sf-error:#ff8a7a}.sf-preview-wrap{outline-color:#ffffff1a}}@media(forced-colors:active){.sf-brand-mark{background:CanvasText}.sf-button{border:1px solid ButtonText}.sf-powered:focus{outline:1px solid CanvasText;outline-offset:3px}}`;
+const accessCss = `.sf-page.access .sf-main{max-width:26rem;padding:clamp(42px,8vh,72px) 0}.sf-page.access h1{max-width:18ch;margin-bottom:14px;font:600 clamp(2rem,7vw,2.65rem)/1.12 var(--sf-font);letter-spacing:-.035em}.sf-page.access .sf-copy{font-size:15px;line-height:1.6}.sf-access-default{display:flex;width:100%;flex-direction:column;align-items:center}.sf-access-status{padding:10px 12px;border:1px solid color-mix(in srgb,var(--sf-fg) 10%,transparent);border-radius:8px;background:color-mix(in srgb,var(--sf-fg) 4%,transparent);color:var(--sf-fg)}.sf-access-lanes{display:flex;flex-direction:column;gap:16px;width:min(23rem,100%);margin-top:30px;text-align:left}.sf-access-lanes form{display:flex;flex-direction:column;gap:14px;margin:0}.sf-input{box-sizing:border-box;width:100%;min-height:46px;padding:11px 12px;border:1px solid color-mix(in srgb,var(--sf-fg) 18%,transparent);border-radius:8px;outline:2px solid transparent;outline-offset:-1px;background:color-mix(in srgb,var(--sf-bg) 92%,var(--sf-fg));color:var(--sf-fg);font:500 15px/1.45 var(--sf-font);appearance:none}.sf-input::placeholder{color:color-mix(in srgb,var(--sf-muted) 82%,transparent);font:inherit}.sf-input:hover{border-color:color-mix(in srgb,var(--sf-fg) 34%,transparent)}.sf-input:focus-visible{border-color:var(--sf-accent);outline-color:var(--sf-accent)}textarea.sf-input{min-height:92px;resize:vertical}.sf-label{color:var(--sf-fg);font:600 13px/1.4 var(--sf-font)}.sf-access-lanes .sf-button{width:100%;min-height:46px;border-radius:8px}.sf-access-or{display:flex;align-items:center;gap:12px;color:var(--sf-muted);font-size:13px}.sf-access-or:before,.sf-access-or:after{content:"";flex:1;border-top:1px solid color-mix(in srgb,var(--sf-fg) 12%,transparent)}.sf-error{margin:0;color:var(--sf-error);font-size:14px}.sf-access-password-row{display:flex;gap:8px}.sf-access-password-row .sf-input{min-width:0;flex:1}.sf-access-password-row .sf-button{width:auto;flex:none}.sf-access-request{padding-top:2px}.sf-access-request summary{padding:4px 0;cursor:pointer;color:var(--sf-muted);font:550 14px/1.5 var(--sf-font)}.sf-access-request summary:hover{color:var(--sf-fg)}.sf-access-request[open] summary{color:var(--sf-fg)}.sf-access-request form{margin-top:16px}@media(max-width:520px){.sf-page.access .sf-main{padding:38px 0}.sf-page.access h1{font-size:2rem}.sf-page.access .sf-copy{font-size:16px}.sf-input{min-height:48px;font-size:16px}.sf-access-lanes .sf-button{min-height:48px}.sf-access-password-row{flex-direction:column}.sf-access-password-row .sf-button{width:100%}}@media(prefers-color-scheme:dark){.sf-access-status{background:color-mix(in srgb,var(--sf-fg) 5%,transparent)}}`;
 const pageHeader = '<header class="sf-header"><a class="sf-brand" href="/" aria-label="Homepage"><span class="sf-brand-mark" aria-hidden="true"></span><sf-logo></sf-logo><strong><sf-name></sf-name></strong></a></header>';
 const pageFooter = "<sf-spacefast-branding></sf-spacefast-branding>";
 function document(id, title, body, layout) {
     const noindex = PAGE_CATALOG[id].noindex ? '<meta name="robots" content="noindex">' : "";
-    return `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${noindex}<title>${title}</title><style>${sharedCss}</style></head>\n<body><div class="sf-page sf-page-${layout}">${pageHeader}<main class="sf-main">${body}</main>${pageFooter}</div></body>\n</html>\n`;
+    const accessClass = id === "access" ? " access" : "";
+    const pageCss = id === "access" ? sharedCss + accessCss : sharedCss;
+    return `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${noindex}<title>${title}</title><style>${pageCss}</style></head>\n<body><div class="sf-page${accessClass} sf-page-${layout}">${pageHeader}<main class="sf-main">${body}</main>${pageFooter}</div></body>\n</html>\n`;
 }
 export const DEFAULT_PAGE_TEMPLATES = {
     "404": document("404", "Page not found", '<p class="sf-eyebrow">404 · Not Found</p><h1>Page not found</h1><p class="sf-copy">There’s nothing at <span class="sf-inline-path"><sf-page-path></sf-page-path></span>.</p><div class="sf-actions"><a class="sf-button" href="/">Go to the homepage</a></div>', "center"),
     denied: document("denied", "Access denied", "<h1>Access denied</h1><sf-denial-context></sf-denial-context>", "center"),
+    access: document("access", "This space is private", '<h1>This space is private</h1><div class="sf-access-default"><sf-access-status></sf-access-status><sf-access-lanes></sf-access-lanes></div>', "center"),
     index: document("index", "<sf-page-title></sf-page-title>", '<p class="sf-eyebrow"><sf-page-path></sf-page-path></p><h1><sf-page-title></sf-page-title></h1><p class="sf-sub"><sf-page-summary></sf-page-summary></p><sf-files></sf-files>', "plain"),
     preview: document("preview", "<sf-page-title></sf-page-title>", '<p class="sf-eyebrow"><sf-page-path></sf-page-path></p><h1><sf-page-title></sf-page-title></h1><sf-file></sf-file>', "plain"),
 };

package/dist/utils/publish-form-data.d.ts

@@ -0,0 +1,22 @@
+export type DirectPublishUpload = {
+    kind: "archive";
+    name: string;
+    bytes: Uint8Array;
+    contentType: string;
+} | {
+    kind: "files";
+    files: Array<{
+        path: string;
+        bytes: Uint8Array;
+        contentType?: string | undefined;
+    }>;
+};
+/** Build the canonical multipart body used by direct one-shot publish clients. */
+export declare function createPublishFormData(input: {
+    upload: DirectPublishUpload;
+    clientAttribution: string;
+    spaceId?: string | undefined;
+    slug?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+}): FormData;

package/dist/utils/publish-form-data.js

@@ -0,0 +1,26 @@
+/** Build the canonical multipart body used by direct one-shot publish clients. */
+export function createPublishFormData(input) {
+    const form = new FormData();
+    if (input.spaceId)
+        form.append("spaceId", input.spaceId);
+    if (input.description)
+        form.append("description", input.description);
+    if (input.slug || input.title) {
+        form.append("space", JSON.stringify({
+            ...(input.slug ? { slug: input.slug } : {}),
+            ...(input.title ? { title: input.title } : {}),
+        }));
+    }
+    form.append("clientAttribution", input.clientAttribution);
+    form.append("source", JSON.stringify({ kind: "agent", client: input.clientAttribution }));
+    if (input.upload.kind === "archive") {
+        form.append("archive", new File([Uint8Array.from(input.upload.bytes)], input.upload.name, {
+            type: input.upload.contentType,
+        }));
+        return form;
+    }
+    for (const file of input.upload.files.toSorted((left, right) => left.path.localeCompare(right.path))) {
+        form.append("files", new File([Uint8Array.from(file.bytes)], file.path, file.contentType ? { type: file.contentType } : undefined));
+    }
+    return form;
+}

package/dist/utils/publish-policy.js

@@ -1,6 +1,7 @@
 import { BRAND } from "../brand.js";
 import { WORST_CASE_QUOTAS } from "../contracts/quotas.js";
 import { SPACE_CONFIG_PRIVATE_FILES } from "../contracts/space-config.js";
+import { ZERO_RUNTIME_DEPLOY_PATH } from "../contracts/zero.js";
 // The ONE static publish policy (internal-docs/platform.md "Upload Contract"):
 // path denials, manifest scale caps, plan caps, duplicate detection, and the
 // free-plan content rules live here. Consumed by API manifest validation, CLI
@@ -95,8 +96,22 @@ export function normalizePublishPath(relativePath) {
  * could mint its own tokens.
  */
 const PUBLISHABLE_BUILD_ARTIFACT_PREFIX = "__spacefast/functions/bundles/";
-function isPublishableBuildArtifactPath(lowerPath) {
-    return lowerPath.startsWith(PUBLISHABLE_BUILD_ARTIFACT_PREFIX);
+/**
+ * The one FILE inside the control prefix a publish may write.
+ *
+ * A Zero capsule's compiled server travels as version metadata, not content, so
+ * a server-only change ships a byte-identical app shell and the version intent's
+ * manifest comparison reads it as "no changes". `sf publish` writes the deploy's
+ * digest here so the manifest moves whenever the deploy does — same reasoning as
+ * the Functions bundle above, same channel.
+ *
+ * One exact path, not a prefix: its siblings under `__spacefast/zero/` are the
+ * runtime's own artifact, config and binary, and a publish that could overwrite
+ * those would be a publish that could replace the runtime.
+ */
+function isPublishableBuildArtifactPath(normalizedPath, lowerPath) {
+    return (lowerPath.startsWith(PUBLISHABLE_BUILD_ARTIFACT_PREFIX) ||
+        normalizedPath === ZERO_RUNTIME_DEPLOY_PATH);
 }
 export function publishPathIgnored(relativePath) {
     const path = normalizePublishPath(relativePath);
@@ -104,7 +119,8 @@ export function publishPathIgnored(relativePath) {
     // (space.json). Drop only those files at any depth so a checkout archived one
     // level too high never ships a claim token — but keep serving legitimate
     // content in the same dirs (e.g. the legacy .stattic/routes.json convention).
-    if (/(?:^|\/)\.(?:spacefast|stattic)\/(?:state|space)\.json$/.test(path)) {
+    if (/(?:^|\/)\.(?:spacefast|stattic)\/(?:state|space)\.json$/.test(path) ||
+        /(?:^|\/)\.spacefast-(?:[0-9a-f-]{36}\.(?:tmp|rollback|retired)|[0-9a-f]{24}\.lock)$/.test(path)) {
         return true;
     }
     if (IGNORED_EXACT_PATHS.has(path) || /(?:^|\/)\.next\/cache(?:\/|$)/.test(path)) {
@@ -209,7 +225,7 @@ export function staticUploadPathViolation(path, options = {}) {
         const lowerSegment = segment.toLowerCase();
         return STATIC_RUNTIME_CONTROL_SEGMENT_PREFIXES.some((prefix) => lowerSegment.startsWith(prefix));
     });
-    if (controlSegment && !isPublishableBuildArtifactPath(lowerPath)) {
+    if (controlSegment && !isPublishableBuildArtifactPath(normalizedPath, lowerPath)) {
         return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
     }
     if (STATIC_RUNTIME_CONTROL_PREFIXES.some((prefix) => lowerPath === prefix || lowerPath.startsWith(`${prefix}/`))) {

package/dist/utils/query-keys.d.ts

@@ -8,7 +8,6 @@ export declare const qk: {
     agentAccounts: (teamId: string) => readonly ["agent-accounts", string];
     myShelf: () => readonly ["my-shelf"];
     mcpDashboard: (teamId: string) => readonly ["mcp", "dashboard", string];
-    mcpApproval: (teamId: string, id: string) => readonly ["mcp", "approval", string, string];
     teams: () => readonly ["teams", "list"];
     team: (ref: string) => readonly ["teams", "by-ref", string];
     teamMembers: (id: string) => readonly ["teams", string, "members"];
@@ -53,7 +52,6 @@ export declare const qk: {
     spaceVersionComments: (id: string, versionId: string, status?: string) => readonly ["spaces", string, "versions", string, "comments"] | readonly ["spaces", string, "versions", string, "comments", string];
     spaceVersionFiles: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "files"];
     spaceVersionFile: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string];
-    spaceVersionFileDirectUrl: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string, "direct-url"];
     spaceVersionFileUrlPreview: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string, "url-preview"];
     spaceVersionFileDiff: (id: string, versionId: string, baseVersionId?: string) => readonly ["spaces", string, "versions", string, "files", "diff", string];
     spaceVersionConventionArtifacts: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "convention-artifacts"];
@@ -63,9 +61,11 @@ export declare const qk: {
     spaceDomains: (id: string) => readonly ["spaces", string, "domains"];
     spaceRuntimeStatus: (id: string) => readonly ["spaces", string, "runtime"];
     spaceApplyState: (id: string) => readonly ["spaces", string, "apply-state"];
-    spaceZeroDb: (id: string) => readonly ["spaces", string, "zero", "db"];
+    spaceDatabase: (id: string) => readonly ["spaces", string, "db"];
+    spaceDatabaseDump: (id: string, table: string | undefined, limit: number) => readonly ["spaces", string, "db", "dump", string, number];
+    spaceStorage: (id: string) => readonly ["spaces", string, "storage"];
     spaceRuntimeLogs: (id: string, limit: number) => readonly ["spaces", string, "logs", "runtime", number];
-    spaceZeroRealtimeEvents: (id: string, limit: number) => readonly ["spaces", string, "zero", "realtime", "events", number];
+    spaceRuntimeRealtimeEvents: (id: string, limit: number) => readonly ["spaces", string, "runtime", "realtime", "events", number];
     spaceVariables: (id: string) => readonly ["spaces", string, "variables"];
     spaceCertificates: (id: string) => readonly ["spaces", string, "runtime", "certificates"];
     spaceLogs: (id: string, kind: "build" | "access" | "runtime") => readonly ["spaces", string, "logs", "build" | "runtime" | "access"];
@@ -79,4 +79,7 @@ export declare const qk: {
     domainDnsOperations: (domainId: string) => readonly ["domains", string, "dns", "operations"];
     domainActions: (domainId: string) => readonly ["domains", string, "actions"];
     domainProviderConnections: (teamId: string) => readonly ["domains", "provider-connections", string];
+    notifications: () => readonly ["notifications"];
+    notificationsList: (unreadOnly: boolean) => readonly ["notifications", "list", boolean];
+    notificationsUnreadCount: () => readonly ["notifications", "unread-count"];
 };

package/dist/utils/query-keys.js

@@ -10,7 +10,6 @@ export const qk = {
     agentAccounts: (teamId) => ["agent-accounts", teamId],
     myShelf: () => ["my-shelf"],
     mcpDashboard: (teamId) => ["mcp", "dashboard", teamId],
-    mcpApproval: (teamId, id) => ["mcp", "approval", teamId, id],
     // The teams LIST gets its own leaf so invalidating it never cascades into
     // ["teams", id, ...] resource queries (members, spaces, domains, ...).
     teams: () => ["teams", "list"],
@@ -71,7 +70,6 @@ export const qk = {
         : ["spaces", id, "versions", versionId, "comments", status],
     spaceVersionFiles: (id, versionId) => ["spaces", id, "versions", versionId, "files"],
     spaceVersionFile: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path],
-    spaceVersionFileDirectUrl: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "direct-url"],
     spaceVersionFileUrlPreview: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "url-preview"],
     spaceVersionFileDiff: (id, versionId, baseVersionId) => ["spaces", id, "versions", versionId, "files", "diff", baseVersionId ?? ""],
     spaceVersionConventionArtifacts: (id, versionId) => ["spaces", id, "versions", versionId, "convention-artifacts"],
@@ -81,9 +79,15 @@ export const qk = {
     spaceDomains: (id) => ["spaces", id, "domains"],
     spaceRuntimeStatus: (id) => ["spaces", id, "runtime"],
     spaceApplyState: (id) => ["spaces", id, "apply-state"],
-    spaceZeroDb: (id) => ["spaces", id, "zero", "db"],
+    // A space has one database, whichever runtime claims it — the key says `db`,
+    // not `zero`, for the same reason the route does.
+    spaceDatabase: (id) => ["spaces", id, "db"],
+    // Row reads are per table and per page size; the bare prefix above sweeps
+    // every dump alongside the schema read.
+    spaceDatabaseDump: (id, table, limit) => [...qk.spaceDatabase(id), "dump", table ?? "", limit],
+    spaceStorage: (id) => ["spaces", id, "storage"],
     spaceRuntimeLogs: (id, limit) => ["spaces", id, "logs", "runtime", limit],
-    spaceZeroRealtimeEvents: (id, limit) => ["spaces", id, "zero", "realtime", "events", limit],
+    spaceRuntimeRealtimeEvents: (id, limit) => [...qk.spaceRuntimeStatus(id), "realtime", "events", limit],
     spaceVariables: (id) => ["spaces", id, "variables"],
     spaceCertificates: (id) => ["spaces", id, "runtime", "certificates"],
     spaceLogs: (id, kind) => ["spaces", id, "logs", kind],
@@ -97,4 +101,9 @@ export const qk = {
     domainDnsOperations: (domainId) => ["domains", domainId, "dns", "operations"],
     domainActions: (domainId) => ["domains", domainId, "actions"],
     domainProviderConnections: (teamId) => ["domains", "provider-connections", teamId],
+    // The shell's notification bell. The bare prefix is the invalidate-all sweep
+    // that a "mark read" performs across both the count and every list view.
+    notifications: () => ["notifications"],
+    notificationsList: (unreadOnly) => ["notifications", "list", unreadOnly],
+    notificationsUnreadCount: () => ["notifications", "unread-count"],
 };

package/dist/utils/runtime-paths.d.ts

@@ -2,5 +2,8 @@ export declare const SPACEFAST_RUNTIME_NAMESPACE: "/__spacefast";
 export declare const RUNTIME_MANAGEMENT_API_PATH: "/__spacefast/api.php";
 export declare const RUNTIME_UPLOAD_API_PATH: "/__spacefast/upload.php";
 export declare const RUNTIME_HEALTH_PATH: "/__spacefast/health.php";
+export declare const RUNTIME_COMMENTS_CONFIG_PATH: "/__spacefast/comments/config";
+export declare const RUNTIME_COMMENTS_TICKET_PATH: "/__spacefast/comments/ticket";
+export declare const RUNTIME_COMMENTS_VERSION_URLS_PATH: "/__spacefast/comments/version-urls";
 export declare function runtimeManagementPath(suffix: string): string;
 export declare function runtimeUploadPath(params: URLSearchParams | Record<string, string>): string;

package/dist/utils/runtime-paths.js

@@ -2,6 +2,13 @@ export const SPACEFAST_RUNTIME_NAMESPACE = "/__spacefast";
 export const RUNTIME_MANAGEMENT_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/api.php`;
 export const RUNTIME_UPLOAD_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/upload.php`;
 export const RUNTIME_HEALTH_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/health.php`;
+// Same-origin Comments exchange paths served on every published host. The PHP
+// mirror is SPACEFAST_COMMENTS_*_PATH in runtime/engine/shared/context.php;
+// runtime/tests/spacefast-sdk.test.ts pins the PHP side and
+// packages/collab-sdk/test/entry.test.ts pins the SDK side to these literals.
+export const RUNTIME_COMMENTS_CONFIG_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/config`;
+export const RUNTIME_COMMENTS_TICKET_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/ticket`;
+export const RUNTIME_COMMENTS_VERSION_URLS_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/comments/version-urls`;
 export function runtimeManagementPath(suffix) {
     const route = normalizeRuntimeRoute(suffix);
     if (route === "/") {

package/dist/utils/secure-local-file.d.ts

@@ -0,0 +1,73 @@
+import { type FileHandle } from "node:fs/promises";
+export declare class SecureLocalFileError extends Error {
+    name: string;
+}
+export declare class SecureLocalFileConflictError extends SecureLocalFileError {
+    name: string;
+}
+export type SecureWriteOptions = {
+    root: string;
+    relativePath: string;
+    data?: Uint8Array | string;
+    write?: (file: FileHandle) => Promise<void>;
+    overwrite?: boolean;
+    mode?: number;
+    rootMode?: number;
+    expectedContent?: Uint8Array | string | null;
+    beforeCommit?: () => void | Promise<void>;
+    /** Fault-injection hook after rollback custody exists but before the atomic rename. */
+    afterBackup?: () => void | Promise<void>;
+};
+export type SecureReadOptions = {
+    root: string;
+    relativePath: string;
+    encoding?: BufferEncoding;
+};
+export type SecureDirectoryOptions = {
+    root: string;
+    relativePath: string;
+    mode?: number;
+};
+export type SecureLocalEntryIdentity = {
+    ctimeNs: bigint;
+    dev: bigint;
+    ino: bigint;
+    mode: bigint;
+};
+export type SecureRemoveOptions = {
+    root: string;
+    relativePath: string;
+    expectedIdentity: SecureLocalEntryIdentity;
+};
+export type SecureCreatedDirectory = {
+    path: string;
+    validate: () => Promise<void>;
+    commit: () => Promise<void>;
+    rollback: () => Promise<void>;
+};
+export declare function secureOutputLocation(trustedPath: string, outputPath: string): {
+    root: string;
+    relativePath: string;
+};
+/**
+ * Writes beneath an explicitly trusted root without following output-tree
+ * symlinks. Linux uses descriptor-relative operations; other supported
+ * platforms use exclusive staging plus before-and-after ancestor identity
+ * validation and fail closed if any binding changes.
+ */
+export declare function secureWriteFile(options: SecureWriteOptions): Promise<void>;
+export declare function secureReadFile(options: SecureReadOptions & {
+    encoding: BufferEncoding;
+}): Promise<string>;
+export declare function secureReadFile(options: SecureReadOptions): Promise<Buffer>;
+/**
+ * Removes only the exact non-directory leaf identity previously inspected.
+ * The same leaf lock used by secureWriteFile covers the identity check and
+ * rename, so a cooperating writer cannot replace the leaf between them.
+ */
+export declare function secureRemoveLocalEntry(options: SecureRemoveOptions): Promise<boolean>;
+/**
+ * Creates one new directory leaf beneath a trusted root. The returned rollback
+ * removes only the exact directory inode created by this call.
+ */
+export declare function secureCreateDirectory(options: SecureDirectoryOptions): Promise<SecureCreatedDirectory>;