@anchrd/intel-api 0.23.0 → 0.25.0

package/dist/adapters/db/db-grants.js

@@ -1,17 +1,82 @@
+export const grantColumns = (subjectColumn) => `id, ${subjectColumn} AS resource_id, principal_type, principal_id, verb, expires_at,
+  created_by, created_at`;
+export function mapGrant(row) {
+    let principal;
+    switch (row.principal_type) {
+        case "user":
+            principal = { type: "user", id: row.principal_id };
+            break;
+        case "email":
+            principal = { type: "email", email: row.principal_id };
+            break;
+        case "organization":
+            principal = { type: "organization" };
+            break;
+        default:
+            throw new Error("Unsupported grant principal type");
+    }
+    return {
+        id: row.id,
+        resourceId: row.resource_id,
+        principal,
+        verb: row.verb,
+        expiresAt: row.expires_at,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    };
+}
+// How a principal is written into the subject columns of both grant tables. An organization is the
+// literal `*` every reader above matches on; an email is folded to lower case on the way in so the
+// comparison there has one shape to worry about.
+export function principalColumns(principal) {
+    if (principal.type === "user")
+        return { type: "user", id: principal.id };
+    if (principal.type === "email")
+        return { type: "email", id: principal.email.toLowerCase() };
+    return { type: "organization", id: "*" };
+}
 const principalMatch = `(
   (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
   OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
   OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
 )`;
-function grantExists(nodeColumn) {
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/api/src` must find this line and nothing else.
+ */
+export const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
+/**
+ * One grant row that is in force, asked of one table.
+ *
+ * ⚠️ The table is a parameter and the rest is not, which is the whole reason #530 could give a flow
+ * its own grants without a second set of doors. `flow_grants` and `node_grants` differ in their
+ * subject column and in nothing else — same principal shapes, same verbs, same expiry — so a
+ * question asked of one is asked of the other by the same string. A hand-written copy for flows is
+ * how one of the two would eventually stop honouring `expires_at`.
+ */
+function grantExists(table, subjectColumn, targetColumn) {
     return `EXISTS (
-    SELECT 1 FROM node_grants grant_row
-    WHERE grant_row.node_id = ${nodeColumn}
+    SELECT 1 FROM ${table} grant_row
+    WHERE grant_row.${subjectColumn} = ${targetColumn}
       AND ${principalMatch}
       AND grant_row.verb = ?
-      AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+      AND ${grantInForce}
   )`;
 }
+const nodeGrantExists = (nodeColumn) => grantExists("node_grants", "node_id", nodeColumn);
+// A grant that sits on the flow itself (#530), beside whatever its folder already passes down. It
+// adds to the folder's reach and never replaces it, exactly as a grant on a document adds to its
+// folder's — the two are OR-ed everywhere this appears.
+const flowGrantExists = (flowColumn) => grantExists("flow_grants", "flow_id", flowColumn);
 // Bindings for one `grantExists`: principal (twice), verb, and the moment expiry is measured
 // against. Callers concatenate these in SQL order; the helpers below say which order that is.
 function grantBindings(actor, verb, now) {
@@ -29,7 +94,7 @@ function subtreeWalk(name) {
     FROM nodes seed
     WHERE ? = 1
        OR seed.owner_id = ?
-       OR ${grantExists("seed.id")}
+       OR ${nodeGrantExists("seed.id")}
     UNION
     SELECT child.id, child.parent_id
     FROM nodes child
@@ -70,14 +135,28 @@ export const readableOrRunnableCte = `WITH RECURSIVE ${subtreeWalk("readable")},
  * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
  * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
  * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
- * time. Its bindings follow the two CTEs' and are `flowInSubtreeBindings(actor)`.
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
  */
 export const flowCallable = `(
   ? = 1
   OR flow.owner_id = ?
   OR flow.parent_id IN (SELECT id FROM readable)
   OR flow.parent_id IN (SELECT id FROM runnable)
+  OR ${flowGrantExists("flow.id")}
+  OR ${flowGrantExists("flow.id")}
 )`;
+export function flowCallableBindings(actor, now) {
+    return [
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, "read", now),
+        ...grantBindings(actor, "execute", now),
+    ];
+}
 /**
  * The point check for one node: the node itself and every ancestor above it. Cheaper than
  * the subtree walk and the same answer, because a grant reaches down and never sideways.
@@ -99,16 +178,21 @@ export const nodeVerbQuery = `WITH RECURSIVE ancestors(id, parent_id, owner_id)
   FROM ancestors
   WHERE ? = 1
      OR owner_id = ?
-     OR ${grantExists("ancestors.id")}
+     OR ${nodeGrantExists("ancestors.id")}
   LIMIT 1`;
 export function nodeVerbBindings(nodeId, actor, verb, now) {
     return [nodeId, actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }
 /**
- * The same question for a flow. A flow carries no grant of its own any more: what reaches it is the
- * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a node's
- * owner keeps theirs — otherwise a flow at the root of the tree would be unreachable by the person
- * who created it. `UNION` for the same reason as above.
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
  */
 export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
     SELECT folder.id, folder.parent_id
@@ -126,17 +210,35 @@ export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
     AND (
       ? = 1
       OR flow.owner_id = ?
-      OR EXISTS (SELECT 1 FROM ancestors WHERE ${grantExists("ancestors.id")})
+      OR ${flowGrantExists("flow.id")}
+      OR EXISTS (SELECT 1 FROM ancestors WHERE ${nodeGrantExists("ancestors.id")})
     )
   LIMIT 1`;
 export function flowVerbBindings(flowId, actor, verb, now) {
-    return [flowId, flowId, actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
+    return [
+        flowId,
+        flowId,
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, verb, now),
+        ...grantBindings(actor, verb, now),
+    ];
 }
 /**
  * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
  * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
  */
-export const flowInSubtree = `(? = 1 OR flow.owner_id = ? OR flow.parent_id IN (SELECT id FROM allowed))`;
-export function flowInSubtreeBindings(actor) {
-    return [actor.isAdmin ? 1 : 0, actor.id];
+export const flowInSubtree = `(
+  ? = 1
+  OR flow.owner_id = ?
+  OR flow.parent_id IN (SELECT id FROM allowed)
+  OR ${flowGrantExists("flow.id")}
+)`;
+export function flowInSubtreeBindings(actor, verb, now) {
+    return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }

package/dist/adapters/db/db.js

@@ -1,8 +1,7 @@
-import { descendantsCte, nodeVerbBindings, nodeVerbQuery, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { descendantsCte, grantColumns as grantColumnsFor, grantInForce, mapGrant, nodeVerbBindings, nodeVerbQuery, principalColumns, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const versionColumns = `id, node_id, sequence, content_key, media_type, content_hash,
   size, segment, created_by, created_at`;
-const grantColumns = `id, node_id, principal_type, principal_id, verb, expires_at,
-  created_by, created_at`;
+const grantColumns = grantColumnsFor("node_id");
 const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
   link.origin, link.label, link.created_by, link.created_at`;
 // The first row of each node, in the order they arrive. A chunked kind — one whose index holds
@@ -47,31 +46,6 @@ function mapVersion(row) {
         createdAt: row.created_at,
     };
 }
-function mapGrant(row) {
-    let principal;
-    switch (row.principal_type) {
-        case "user":
-            principal = { type: "user", id: row.principal_id };
-            break;
-        case "email":
-            principal = { type: "email", email: row.principal_id };
-            break;
-        case "organization":
-            principal = { type: "organization" };
-            break;
-        default:
-            throw new Error("Unsupported node grant principal type");
-    }
-    return {
-        id: row.id,
-        resourceId: row.node_id,
-        principal,
-        verb: row.verb,
-        expiresAt: row.expires_at,
-        createdBy: row.created_by,
-        createdAt: row.created_at,
-    };
-}
 function mapLink(row) {
     return {
         id: row.id,
@@ -1029,7 +1003,7 @@ export function createNodeRepository(deps) {
             (SELECT json_group_array(owner_id)
              FROM (SELECT DISTINCT owner_id FROM ancestors ORDER BY owner_id)) AS owner_ids_json,
             (SELECT json_group_array(json_object(
-               'id', id, 'node_id', node_id, 'principal_type', principal_type,
+               'id', id, 'resource_id', node_id, 'principal_type', principal_type,
                'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
                'created_by', created_by, 'created_at', created_at
              ))
@@ -1039,7 +1013,7 @@ export function createNodeRepository(deps) {
                  grant_row.created_by, grant_row.created_at
                FROM node_grants grant_row
                JOIN ancestors ON ancestors.id = grant_row.node_id
-               WHERE grant_row.expires_at IS NULL OR grant_row.expires_at > ?
+               WHERE ${grantInForce}
                ORDER BY grant_row.principal_type, grant_row.principal_id, grant_row.verb
              )) AS grants_json`)
                 .bind(resourceId, deps.now().toISOString())
@@ -1066,7 +1040,7 @@ export function createNodeRepository(deps) {
           WHERE grant_row.id <> ?
             AND grant_row.principal_type = 'organization'
             AND grant_row.verb = 'execute'
-            AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+            AND ${grantInForce}
           LIMIT 1`)
                 .bind(nodeId, exceptGrantId, deps.now().toISOString())
                 .first();
@@ -1173,12 +1147,7 @@ export function createNodeRepository(deps) {
         },
         async setGrant(input) {
             const grant = input.grant;
-            const principalType = grant.principal.type;
-            const principalId = grant.principal.type === "user"
-                ? grant.principal.id
-                : grant.principal.type === "email"
-                    ? grant.principal.email.toLowerCase()
-                    : "*";
+            const { type: principalType, id: principalId } = principalColumns(grant.principal);
             try {
                 await deps.db.batch([
                     deps.db

package/dist/auth/auth.js

@@ -218,28 +218,55 @@ export function createBrowserAuth(deps) {
                     ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
                     : withConnectError(pending.returnTo));
             }
-            const tokens = await deps.oauth.exchange({
-                issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
-                clientId: pending.clientId,
-                callbackUrl: requestUrl,
-                redirectUri,
-                resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
-                codeVerifier: pending.codeVerifier,
-                state: pending.state,
-            });
-            if (pending.kind === "connection-pending") {
-                await deps.portalTokens.write(pending.userId, {
-                    accessToken: tokens.accessToken,
-                    refreshToken: tokens.refreshToken ?? null,
-                    expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
-                    issuer: pending.issuer,
+            // ⚠️ Everything below runs with the handoff READ, and that is the whole difference between
+            // this catch and the one on the route (#444): here a failure knows where the person was
+            // going, and for a connection handoff it still holds their parked Intel session. The route
+            // can only send somebody to a decided screen, so whatever can be answered here is answered
+            // here — the token exchange, the portal token write and the sealing of the new session all
+            // used to end as a bare 500 in JSON, in the middle of a sign-in.
+            try {
+                const tokens = await deps.oauth.exchange({
+                    issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
                     clientId: pending.clientId,
-                    resource: pending.resource,
+                    callbackUrl: requestUrl,
+                    redirectUri,
+                    resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
+                    codeVerifier: pending.codeVerifier,
+                    state: pending.state,
                 });
-                return await restore(pending.user, pending.returnTo, pending.returnTo);
+                if (pending.kind === "connection-pending") {
+                    await deps.portalTokens.write(pending.userId, {
+                        accessToken: tokens.accessToken,
+                        refreshToken: tokens.refreshToken ?? null,
+                        expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+                        issuer: pending.issuer,
+                        clientId: pending.clientId,
+                        resource: pending.resource,
+                    });
+                    return await restore(pending.user, pending.returnTo, pending.returnTo);
+                }
+                const session = await userSession(pending.clientId, tokens);
+                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
+            }
+            catch (error) {
+                // The exception is the only thing that still holds the reason: what the reader gets is a
+                // fixed marker, and a marker names a KIND of failure, never its cause (#93).
+                reportUnexpectedError(error);
+                // `portal_sign_in_failed` is the marker `/auth/connect` already writes for exactly this
+                // situation, so nothing new is invented here and no screen has to learn a word. The Tools
+                // screen reads it as "the sign-in is broken", which is true of both handoffs — a Gate login
+                // that could not be exchanged is no more the reader's doing than a portal one.
+                if (pending.kind === "connection-pending") {
+                    // Every other way out of the callback puts the parked Intel session back, and so does
+                    // this one: the portal attempt must never cost somebody their Intel login.
+                    return await restore(pending.user, pending.returnTo, withConnectError(pending.returnTo, "portal_sign_in_failed"));
+                }
+                // A Gate login handoff parks nothing, so there is no session to put back — and the cookie
+                // is spent either way: its verifier belongs to an authorization code that has now been
+                // used. Clearing it is what makes the next attempt start a fresh one instead of replaying
+                // this one.
+                return redirect(withConnectError(pending.returnTo, "portal_sign_in_failed"), sessionCookie("", secure, 0));
             }
-            const session = await userSession(pending.clientId, tokens);
-            return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
         },
         logout() {
             return redirect("/", sessionCookie("", secure, 0));

package/dist/build/build.js

@@ -13,6 +13,42 @@ const IntelConfig = z.strictObject({
 const Catalog = z.record(z.string(), z.string());
 const defaultTheme = `/* Generated by \`intel build\`. Intel defaults are active. */\n`;
 const defaultLogo = `export const customLogoUrl: string | null = null;\n`;
+// The `_headers` file of Workers Assets, written INTO THE BUILD OUTPUT (#543, sibling of
+// anchrd/gate#329).
+//
+// Without it every asset answers with the platform default `public, max-age=0, must-revalidate`,
+// and `public` lets a browser store an ERROR answer too. A `403` that appears once during setup is
+// then replayed on every navigation WITHOUT a request leaving the browser — invisible in the worker
+// log, in the Cloudflare Access log, in the firewall and in Cloudflare Analytics, while `curl`
+// against the same address keeps answering `200`. The second rule matters more here than in Gate:
+// the UI ships 1.9 MB of fingerprinted assets that are revalidated on every navigation today.
+//
+// ⚠️ `! Cache-Control` is not decoration, and the naive two-rule form from the ticket is WRONG.
+// A request matching several rules inherits ALL their headers, and a header named twice is joined
+// with a comma. Measured against `wrangler dev` 4.112.0 with both spellings side by side:
+//   without the detach   /assets/app.js → `no-store, public, max-age=31536000, immutable`
+//   with the detach      /assets/app.js → `public, max-age=31536000, immutable`
+// The joined value carries `no-store`, so those 1.9 MB would never be cached at all — the exact
+// opposite of the second rule's purpose.
+//
+// ⚠️ It has to be written into the TEMPORARY directory, before `replaceDir`. The next run's
+// `--emptyOutDir` applies to that directory, so a file placed into the live outDir afterwards
+// survives exactly one build. And `packages/ui/public/` is no way either: the `files` field of
+// @anchrd/intel-ui does not list `public`, so the file would look right in the repository and never
+// reach a customer.
+//
+// The three `cache-control` writes in this package do not contradict it: `auth/auth.ts` (redirect),
+// `http/http.ts` (zipResponse, attachment bytes) all answer `no-store` under `/auth/*` and `/api/*`,
+// which the assets layer never sees. Nothing serves an SPA route under `/assets/`, so the
+// `immutable` rule cannot swallow one.
+const headersFile = `# Generated by \`intel build\` — do not edit by hand.
+/*
+  Cache-Control: no-store
+
+/assets/*
+  ! Cache-Control
+  Cache-Control: public, max-age=31536000, immutable
+`;
 // Customer paths from intel.json are written into generated CSS and TypeScript comments. A path
 // containing `*/` or a newline would close the comment early, leaving broken output or — in
 // custom-logo.ts — customer-controlled text outside the comment and inside the UI bundle.
@@ -130,6 +166,9 @@ export function createBuild(deps) {
                     deps.log(`Error: Intel UI build exited with ${exitCode}.`);
                     return 1;
                 }
+                // Into the temporary directory, not into outDir — see `headersFile`. Vite has just emptied
+                // and refilled this directory; anything written here travels with the swap.
+                await deps.writeTextFile(`${temporaryOutDir}/_headers`, headersFile);
                 await deps.replaceDir(temporaryOutDir, location.outDir);
                 deps.log(`Intel UI built at ${location.outDir}.`);
                 return 0;

package/dist/bundle/bundle.js

@@ -336,6 +336,15 @@ export function createBundle(deps) {
     }
     async function tableCsv(nodeId) {
         const keys = await deps.repository.listVersionContentKeys(nodeId);
+        // ⚠️ `some` on an empty list is false, so no segments at all used to walk past the guard below
+        // and return `[].join("")` — the empty string, written into the zip as a file of zero bytes
+        // (#534). A table that has never been defined no longer reaches this function at all: it has no
+        // current version, and `plannedNode` marks it absent instead. An empty list HERE therefore means
+        // something else — a current version whose segments are gone — which is the loss the guard below
+        // already names, and it deserves the same answer rather than a silently empty file.
+        if (keys.length === 0) {
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        }
         const segments = await Promise.all(keys.map(async (key) => await deps.content.get(key)));
         if (segments.some((segment) => segment === null)) {
             throw new IntelError(500, "content_missing", "Version content is missing");
@@ -351,6 +360,27 @@ export function createBundle(deps) {
             return body;
         };
     }
+    /**
+     * The bytes of an attachment version, or the same refusal the text path has always given (#560).
+     *
+     * ⚠️ A `contentKey` in the row and nothing behind it in R2 is data LOSS, and the attachment path
+     * was the one path that answered it with silence: `getStream` returned `null`, the zip got a file
+     * of zero bytes, and the export reported success. Whoever filed that zip away as a backup learns
+     * what it holds when they restore it — the one moment nothing can be done about it any more.
+     *
+     * This is deliberately NOT the `absence` answer. "Never uploaded" is a state of the node and
+     * travels in the manifest; "the object is gone" is a broken installation, and a bundle must not
+     * be able to describe it as if it were fine. Same distinction as `textLoader` and `tableCsv`.
+     */
+    function streamLoader(contentKey) {
+        return async () => {
+            const stream = await deps.content.getStream(contentKey);
+            if (stream === null) {
+                throw new IntelError(500, "content_missing", "Version content is missing");
+            }
+            return stream;
+        };
+    }
     function plannedNode(row, directory, used) {
         const { node, version } = row;
         const base = sanitizeName(node.title);
@@ -371,6 +401,30 @@ export function createBundle(deps) {
         }
         if (node.kind === "table") {
             const path = `${directory}${uniqueName(used, base, ".csv")}`;
+            // ⚠️ A table with no current version has never been given a header, and for a table the
+            // canonical content IS the CSV: there is nothing to write. It used to travel as a file of zero
+            // bytes, which the holder of the zip cannot tell apart from a table whose content was lost on
+            // the way — the very case `tableCsv` refuses as `content_missing`. One file, two meanings, no
+            // way to read which (#534).
+            //
+            // ⚠️ The entry STAYS in the manifest, and that is the half that matters: dropping it would
+            // take the node's title, its description and its place in the tree out of the backup too, and
+            // the import would recreate a subtree with a node missing from it without anybody noticing.
+            // What travels instead is the node without bytes, plus the word for what is not there.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "table",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: TableMediaType,
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
             return {
                 manifest: {
                     id: node.id,
@@ -387,19 +441,38 @@ export function createBundle(deps) {
             // Original bytes under the original name: an attachment's title IS its file name, so no
             // extension is imposed on it.
             const path = `${directory}${uniqueName(used, base, "")}`;
+            // ⚠️ An attachment with no current version was created and never uploaded to, and for an
+            // attachment the canonical content IS the bytes: there is nothing to write. It used to travel
+            // as a file of zero bytes — the same one file with two meanings the table branch above
+            // refuses, and here the second meaning is a lost R2 object (#560).
+            //
+            // ⚠️ The entry STAYS in the manifest for the same reason it does for a table: dropping it
+            // would take the node's title, its description and its place in the tree out of the backup,
+            // and the import would rebuild a subtree with a node missing from it and say nothing.
+            if (version === null) {
+                return {
+                    manifest: {
+                        id: node.id,
+                        kind: "attachment",
+                        title: node.title,
+                        description: node.description,
+                        mediaType: "application/octet-stream",
+                        path,
+                        absence: "no-content",
+                    },
+                    content: { type: "absent" },
+                };
+            }
             return {
                 manifest: {
                     id: node.id,
                     kind: "attachment",
                     title: node.title,
                     description: node.description,
-                    mediaType: version?.mediaType ?? "application/octet-stream",
+                    mediaType: version.mediaType ?? "application/octet-stream",
                     path,
                 },
-                content: {
-                    type: "stream",
-                    load: async () => version === null ? null : await deps.content.getStream(version.contentKey),
-                },
+                content: { type: "stream", load: streamLoader(version.contentKey) },
             };
         }
         // ⚠️ A row of a kind this build no longer makes — an `agent` or a `board` written before #390
@@ -574,18 +647,25 @@ export function createBundle(deps) {
                     await writer.ready;
                     continue;
                 }
+                // Nothing is written for it — not even an empty file, which is the whole point (#534). The
+                // manifest carries the node and says why its path is unoccupied.
+                if (entry.content.type === "absent")
+                    continue;
                 if (entry.content.type === "text") {
                     await pushText(entry.manifest.path, await entry.content.load());
                     continue;
                 }
+                // ⚠️ No `null` branch here any more, and its removal is the repair (#560): it wrote a file
+                // of zero bytes for "the loader has nothing", which was true both for an attachment nobody
+                // ever uploaded to and for one whose object had left R2. The first is now `absent` above
+                // and never reaches this loop; the second throws out of `load()` and aborts the whole zip,
+                // which is what a backup that cannot be written is supposed to do.
+                //
+                // The loader runs BEFORE the entry is added, so a refusal leaves no half-opened file
+                // behind in the zip that nothing will ever terminate.
+                const stream = await entry.content.load();
                 const file = new ZipPassThrough(entry.manifest.path);
                 zip.add(file);
-                const stream = await entry.content.load();
-                if (stream === null) {
-                    file.push(new Uint8Array(0), true);
-                    await writer.ready;
-                    continue;
-                }
                 const reader = stream.getReader();
                 for (;;) {
                     const { done, value } = await reader.read();
@@ -648,7 +728,11 @@ export function createBundle(deps) {
             if (isFolder)
                 folderIdByPath.set(entry.path.endsWith("/") ? entry.path : `${entry.path}/`, newId);
             let body = null;
-            if (!isFolder) {
+            // ⚠️ An entry that declares an `absence` names a path with nothing at it ON PURPOSE, so the
+            // zip is complete rather than broken (#534). Without this the export written by this very
+            // build would refuse its own import — and the node it describes arrives the way it left: a
+            // table with a title, a place in the tree and no content.
+            if (!isFolder && entry.absence === undefined) {
                 const found = files.get(entry.path);
                 if (found === undefined) {
                     throw new IntelError(400, "import_bundle_incomplete", `The manifest names a file the zip does not carry: ${entry.path}`);
@@ -933,9 +1017,14 @@ export function createBundle(deps) {
                      */
                     throw new IntelError(400, "import_kind_parked", `Bundle entry “${entry.path}” is a ${entry.kind}, and ${entry.kind}s are not part of this installation any more (anchrd/intel#385). The bundle was exported from a version that still had them; the code is on the branch parked/agents-and-board. Remove the entry from the bundle to import the rest.`);
                 }
-                else if (entry.kind === "attachment") {
-                    const bytes = entry.body ?? new Uint8Array(0);
-                    version = versionRowFor(entry, bytes, entry.mediaType ?? "application/octet-stream", await deps.hash(bytes), null);
+                else if (entry.kind === "attachment" && entry.body !== null) {
+                    // ⚠️ `entry.body === null` reaches here only for a manifest entry that declared an
+                    // absence — a naked folder always has the bytes of the file it names. It used to be read
+                    // as `new Uint8Array(0)` and given a version of zero bytes, which is a DIFFERENT node
+                    // from the one that was exported: the export said "never uploaded to", and the import
+                    // would answer with an upload of nothing. No version is what came out of that
+                    // installation and no version is what goes back in (#560).
+                    version = versionRowFor(entry, entry.body, entry.mediaType ?? "application/octet-stream", await deps.hash(entry.body), null);
                 }
                 if (version !== null)
                     versions.push(version);