@anchrd/intel 0.59.0

package/dist/adapters/content/content.js

@@ -0,0 +1,128 @@
+import { IntelError } from "../../shared/intel-error/intel-error.js";
+import { reportUnexpectedError } from "../../shared/report-unexpected-error/report-unexpected-error.js";
+import { hexDigest } from "../../shared/sha256/sha256.js";
+// ⚠️ Both are workerd globals rather than imports, and they are read through a guard because a
+// missing one is a deployment fact, not a bug in the caller: without them this adapter can still
+// serve every other method, and the one that needs them says so instead of throwing a `TypeError`
+// out of a stream nobody is watching.
+function streaming() {
+    const fixedLength = globalThis
+        .FixedLengthStream;
+    const digestStream = crypto
+        .DigestStream;
+    if (!fixedLength || !digestStream) {
+        throw new IntelError(500, "streaming_unavailable", "This runtime cannot store a file without holding it in memory");
+    }
+    return { fixedLength, digestStream };
+}
+// The two halves of one pass over the bytes, named so that the promise of each can be held and
+// answered separately from the other.
+function hashed(content, hashing) {
+    return content.pipeTo(hashing.writable);
+}
+function written(hashing, body) {
+    return hashing.readable.pipeTo(body.writable);
+}
+export function createContentStore(bucket) {
+    return {
+        async get(key) {
+            return (await (await bucket.get(key))?.text()) ?? null;
+        },
+        async getBytes(key) {
+            return (await (await bucket.get(key))?.arrayBuffer()) ?? null;
+        },
+        async getStream(key) {
+            return (await bucket.get(key))?.body ?? null;
+        },
+        async put(key, content, mediaType) {
+            await bucket.put(key, content, { httpMetadata: { contentType: mediaType } });
+        },
+        async putBytes(key, content, mediaType) {
+            await bucket.put(key, content, { httpMetadata: { contentType: mediaType } });
+        },
+        /**
+         * The file into R2 and the hash out of it, in one pass over the bytes (#821).
+         *
+         * ⚠️ The `put` is started BEFORE the pipe is awaited, and the order is the whole of it: R2 pulls
+         * from `readable` while this writes into `writable`. Awaiting the write first would fill a
+         * stream nobody reads, and a 50 MB body would sit in memory — which is the state this method
+         * exists to prevent.
+         *
+         * ⚠️ Every chunk goes to the digest before it is passed on, so the hash covers exactly the bytes
+         * that were stored. Hashing a copy taken anywhere else would be a statement about a different
+         * stream.
+         */
+        async putStream(key, content, mediaType, size) {
+            const { fixedLength, digestStream } = streaming();
+            const digest = new digestStream("SHA-256");
+            const writer = digest.getWriter();
+            let counted = 0;
+            const hashing = new TransformStream({
+                async transform(chunk, controller) {
+                    counted += chunk.byteLength;
+                    await writer.write(chunk);
+                    controller.enqueue(chunk);
+                },
+                async flush() {
+                    await writer.close();
+                },
+            });
+            const body = new fixedLength(size);
+            const stored = bucket.put(key, body.readable, { httpMetadata: { contentType: mediaType } });
+            // ⚠️ **Nothing here is ever awaited on its own, and that is the whole shape of this method.**
+            // Three promises are in flight and each of them can be the one that fails: the source, the
+            // write into the store's body, and the store itself. Awaiting one of them first means waiting
+            // forever for the other two whenever THAT one is not the one that broke — a store which
+            // refuses before it reads leaves the pipe with no reader, and a source which dies leaves the
+            // store with no bytes. Both were measured as a 30 s hang rather than a refusal.
+            const pipes = Promise.all([hashed(content, hashing), written(hashing, body)]);
+            const outcome = await Promise.race([
+                pipes.then(() => ({ side: "piped" }), (cause) => ({ side: "body", cause })),
+                stored.then(() => ({ side: "stored" }), (cause) => ({ side: "store", cause })),
+            ]);
+            // The digest stream is closed by the transform's `flush` and by nothing else, so a run that
+            // ends any other way has to end it here or its `digest` never settles. Every promise gets a
+            // catch of its own for the same reason: a failure already answered must not surface a second
+            // time as an unhandled rejection.
+            const giveUp = (cause) => {
+                void writer.abort(cause).catch(() => undefined);
+                void digest.digest.catch(() => undefined);
+                void stored.catch(() => undefined);
+                void pipes.catch(() => undefined);
+            };
+            if (outcome.side === "body") {
+                giveUp(outcome.cause);
+                throw new IntelError(400, "upload_incomplete", "The upload ended before the body did");
+            }
+            if (outcome.side === "store") {
+                giveUp(outcome.cause);
+                // The reason goes to the log, the answer names only whose side failed: a store can quote
+                // what a peer sent, and that is not something a response may carry.
+                reportUnexpectedError(outcome.cause);
+                throw new IntelError(502, "content_store_failed", "The file could not be stored");
+            }
+            // ⚠️ The length is compared before the store is asked how it went. A body that simply stops
+            // carries fewer bytes without failing a single write — the `FixedLengthStream` notices only
+            // when the store reads it — so without this the caller's short body and a failure inside the
+            // store would arrive as one rejection and be answered with one sentence. They are opposite
+            // failures: one is the caller's, the other is ours, and a reader sent hunting through their
+            // own connection for our outage is what that costs.
+            if (counted !== size) {
+                giveUp(new Error("short body"));
+                throw new IntelError(400, "upload_incomplete", `The body carried ${counted} bytes, and ${size} were announced`);
+            }
+            let object;
+            try {
+                object = await stored;
+            }
+            catch (cause) {
+                reportUnexpectedError(cause);
+                throw new IntelError(502, "content_store_failed", "The file could not be stored");
+            }
+            return { size: object.size, hash: hexDigest(await digest.digest) };
+        },
+        async delete(key) {
+            await bucket.delete(key);
+        },
+    };
+}

package/dist/adapters/content/content.types.d.ts

@@ -0,0 +1,38 @@
+export interface R2ObjectBody {
+    body: ReadableStream<Uint8Array>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface R2PutResult {
+    size: number;
+}
+export interface R2Bucket {
+    get(key: string): Promise<R2ObjectBody | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream<Uint8Array>, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+    }): Promise<R2PutResult>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * The two workerd streams this adapter needs, declared rather than imported (#821).
+ *
+ * ⚠️ `FixedLengthStream` is why a stream can reach R2 at all: a `put` needs to know how long the
+ * body is, and everything piped through a `TransformStream` has lost that. It carries the length
+ * with it and fails the write when the bytes disagree — the same guard, one layer lower.
+ *
+ * ⚠️ `crypto.DigestStream` is the hash of a file nobody holds. `crypto.subtle.digest` wants the
+ * whole buffer, which is the memory this path exists to avoid.
+ */
+export interface FixedLengthStreamConstructor {
+    new (length: number): {
+        readable: ReadableStream<Uint8Array>;
+        writable: WritableStream<Uint8Array>;
+    };
+}
+export interface DigestStreamConstructor {
+    new (algorithm: string): WritableStream<Uint8Array> & {
+        digest: Promise<ArrayBuffer>;
+    };
+}

package/dist/adapters/content/content.types.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/db/db-audit.d.ts

@@ -0,0 +1,62 @@
+import type { AuditRepository } from "../../audit/audit.types.js";
+import type { D1Database } from "./db.types.js";
+/**
+ * The journal, cut down to the rows this actor may see, continued from a stable position.
+ *
+ * ⚠️ **The visibility check is a JOIN against `allowed`, evaluated on every call.** `allowed` is
+ * the same tree walk `nodes` reads through (`db-grants.ts`), so an event about a node is visible
+ * exactly when the node is — no second rule that could drift from the first. It runs per row and
+ * per request; nothing here is cached, so a grant revoked a second ago is gone from the next
+ * answer.
+ *
+ * ⚠️ It filters the EXISTENCE of the row, not only its contents. That is deliberate and it is
+ * the stricter reading: that something is moving inside a customer's folder is itself
+ * information, so an actor who may not read the node learns nothing at all — not an id, not a
+ * count, not a timestamp.
+ *
+ * ⚠️ **An event about a purged node is therefore unreachable, for everybody.** `allowed` walks
+ * `nodes`, and after `node.purge` that row is gone, so the join finds nothing. This is not an
+ * oversight and it cannot be fixed without giving up the check: at a deleted row there is no
+ * longer anything against which a claim to have been allowed to read it could be tested. Hiding
+ * is the safe direction. A consumer learns about creation, change, moves and archiving — never
+ * about final deletion (#620).
+ *
+ * ⚠️ **`ORDER BY` and the cursor comparison must name BOTH columns, in the same order.** Two
+ * events in the same millisecond are the normal case in a batch, not the exception; on
+ * `occurred_at` alone the second one is skipped in silence — no error, no log, just an event
+ * that never arrived. The tuple comparison below is written out by hand because SQLite has no
+ * row-value comparison here: "later timestamp, OR same timestamp and larger id".
+ */
+export declare const auditFeedQuery: string;
+/**
+ * The same journal about FLOWS (#774).
+ *
+ * ⚠️ **A separate statement rather than a widened one, and that is the decision.** The three kinds
+ * do not differ in a value but in the QUESTION they ask: a node is visible when the node is in
+ * `allowed`, a flow when its folder is or it carries a grant of its own, a run one join further on.
+ * Written as one query with three branches, every caller would pay all three joins to read one
+ * kind — and `audit_list` names exactly one kind per call, so there is nothing to gain from it.
+ * The feed is the opposite case and rightly written the opposite way: it reads all three at once.
+ *
+ * ⚠️ **`INNER JOIN flows`, so an event about a purged flow is unreachable** — the same shape the
+ * node half has carried since #620, and for the same reason: at a deleted row there is nothing left
+ * against which a claim to have been allowed to read it could be tested. Hiding is the safe
+ * direction. The feed differs deliberately (it falls back on the purge's own metadata) because a
+ * card that says "deleted" is the whole point there; a journal consumer gets the deletion through
+ * the parent folder's events instead.
+ */
+export declare const auditFlowFeedQuery: string;
+/**
+ * And about RUNS, which is the walk one join further: run → flow → folder (#774).
+ *
+ * ⚠️ The alias is `run_flow` and it is handed to `flowInSubtreeOver` explicitly. Until #767 that
+ * guard had `flow` hard-wired, and against a flow reached through a second join every branch but
+ * the folder one compared NULL — a flow somebody OWNS but that hangs at the top level answered "not
+ * visible" to its own owner. It fails in the safe direction, which is exactly why it needs a test
+ * that seeds a run of a flow at the ROOT rather than in a folder.
+ */
+export declare const auditRunFeedQuery: string;
+export declare function createAuditRepository(deps: {
+    db: D1Database;
+    now(): Date;
+}): AuditRepository;

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

@@ -0,0 +1,150 @@
+import { flowInSubtree, flowInSubtreeBindings, flowInSubtreeOver, subtreeBindings, subtreeCte, } from "./db-grants.js";
+function mapEvent(row, resourceType) {
+    let metadata = {};
+    // The column is `NOT NULL DEFAULT '{}'`, but it is written by 11 call sites over
+    // `JSON.stringify` on whatever each one had at hand. A row that cannot be parsed, or that parses
+    // to something other than an object, must not take the whole page down with it: the reader would
+    // then be stuck at that cursor forever with no way past. An unreadable payload becomes `{}` and
+    // the event itself still arrives — the fact that something happened is the part a change feed
+    // cannot afford to lose.
+    try {
+        const parsed = JSON.parse(row.metadata_json);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            metadata = parsed;
+        }
+    }
+    catch {
+        metadata = {};
+    }
+    return {
+        id: row.id,
+        actorId: row.actor_id,
+        action: row.action,
+        // ⚠️ Taken from the QUESTION, not from the row. Each statement names exactly one
+        // `resource_type` in its `WHERE`, so the answer cannot carry another — and reading the column
+        // back would add a second truth about the same thing (#774).
+        resourceType,
+        resourceId: row.resource_id,
+        metadata,
+        occurredAt: row.occurred_at,
+    };
+}
+/**
+ * The journal, cut down to the rows this actor may see, continued from a stable position.
+ *
+ * ⚠️ **The visibility check is a JOIN against `allowed`, evaluated on every call.** `allowed` is
+ * the same tree walk `nodes` reads through (`db-grants.ts`), so an event about a node is visible
+ * exactly when the node is — no second rule that could drift from the first. It runs per row and
+ * per request; nothing here is cached, so a grant revoked a second ago is gone from the next
+ * answer.
+ *
+ * ⚠️ It filters the EXISTENCE of the row, not only its contents. That is deliberate and it is
+ * the stricter reading: that something is moving inside a customer's folder is itself
+ * information, so an actor who may not read the node learns nothing at all — not an id, not a
+ * count, not a timestamp.
+ *
+ * ⚠️ **An event about a purged node is therefore unreachable, for everybody.** `allowed` walks
+ * `nodes`, and after `node.purge` that row is gone, so the join finds nothing. This is not an
+ * oversight and it cannot be fixed without giving up the check: at a deleted row there is no
+ * longer anything against which a claim to have been allowed to read it could be tested. Hiding
+ * is the safe direction. A consumer learns about creation, change, moves and archiving — never
+ * about final deletion (#620).
+ *
+ * ⚠️ **`ORDER BY` and the cursor comparison must name BOTH columns, in the same order.** Two
+ * events in the same millisecond are the normal case in a batch, not the exception; on
+ * `occurred_at` alone the second one is skipped in silence — no error, no log, just an event
+ * that never arrived. The tuple comparison below is written out by hand because SQLite has no
+ * row-value comparison here: "later timestamp, OR same timestamp and larger id".
+ */
+export const auditFeedQuery = `${subtreeCte}
+    SELECT e.id, e.actor_id, e.action, e.resource_id, e.metadata_json, e.occurred_at
+    FROM audit_events e
+    JOIN allowed ON allowed.id = e.resource_id
+    WHERE e.resource_type = 'node'
+      AND (
+        ? IS NULL
+        OR e.occurred_at > ?
+        OR (e.occurred_at = ? AND e.id > ?)
+      )
+    ORDER BY e.occurred_at ASC, e.id ASC
+    LIMIT ?`;
+/**
+ * The same journal about FLOWS (#774).
+ *
+ * ⚠️ **A separate statement rather than a widened one, and that is the decision.** The three kinds
+ * do not differ in a value but in the QUESTION they ask: a node is visible when the node is in
+ * `allowed`, a flow when its folder is or it carries a grant of its own, a run one join further on.
+ * Written as one query with three branches, every caller would pay all three joins to read one
+ * kind — and `audit_list` names exactly one kind per call, so there is nothing to gain from it.
+ * The feed is the opposite case and rightly written the opposite way: it reads all three at once.
+ *
+ * ⚠️ **`INNER JOIN flows`, so an event about a purged flow is unreachable** — the same shape the
+ * node half has carried since #620, and for the same reason: at a deleted row there is nothing left
+ * against which a claim to have been allowed to read it could be tested. Hiding is the safe
+ * direction. The feed differs deliberately (it falls back on the purge's own metadata) because a
+ * card that says "deleted" is the whole point there; a journal consumer gets the deletion through
+ * the parent folder's events instead.
+ */
+export const auditFlowFeedQuery = `${subtreeCte}
+    SELECT e.id, e.actor_id, e.action, e.resource_id, e.metadata_json, e.occurred_at
+    FROM audit_events e
+    JOIN flows flow ON flow.id = e.resource_id
+    WHERE e.resource_type = 'flow'
+      AND ${flowInSubtree}
+      AND (
+        ? IS NULL
+        OR e.occurred_at > ?
+        OR (e.occurred_at = ? AND e.id > ?)
+      )
+    ORDER BY e.occurred_at ASC, e.id ASC
+    LIMIT ?`;
+/**
+ * And about RUNS, which is the walk one join further: run → flow → folder (#774).
+ *
+ * ⚠️ The alias is `run_flow` and it is handed to `flowInSubtreeOver` explicitly. Until #767 that
+ * guard had `flow` hard-wired, and against a flow reached through a second join every branch but
+ * the folder one compared NULL — a flow somebody OWNS but that hangs at the top level answered "not
+ * visible" to its own owner. It fails in the safe direction, which is exactly why it needs a test
+ * that seeds a run of a flow at the ROOT rather than in a folder.
+ */
+export const auditRunFeedQuery = `${subtreeCte}
+    SELECT e.id, e.actor_id, e.action, e.resource_id, e.metadata_json, e.occurred_at
+    FROM audit_events e
+    JOIN flow_runs run ON run.id = e.resource_id
+    JOIN flows run_flow ON run_flow.id = run.flow_id
+    WHERE e.resource_type = 'flow-run'
+      AND ${flowInSubtreeOver("run_flow.parent_id", "run_flow")}
+      AND (
+        ? IS NULL
+        OR e.occurred_at > ?
+        OR (e.occurred_at = ? AND e.id > ?)
+      )
+    ORDER BY e.occurred_at ASC, e.id ASC
+    LIMIT ?`;
+export function createAuditRepository(deps) {
+    return {
+        async listEvents(actor, query) {
+            const after = query.after ?? null;
+            const now = deps.now().toISOString();
+            // ⚠️ One reading of the clock for the whole call. Both guards measure grant expiry against
+            // it, and two `now()` readings could straddle the moment a grant runs out.
+            const guard = query.resourceType === "node"
+                ? { page: auditFeedQuery, bindings: subtreeBindings(actor, "read", now) }
+                : {
+                    page: query.resourceType === "flow" ? auditFlowFeedQuery : auditRunFeedQuery,
+                    // The flow walks need the CTE's bindings and the guard's, in that order — the guard
+                    // is written into the statement after the CTE.
+                    bindings: [
+                        ...subtreeBindings(actor, "read", now),
+                        ...flowInSubtreeBindings(actor, "read", now),
+                    ],
+                };
+            const result = await deps.db
+                .prepare(guard.page)
+                .bind(...guard.bindings, after === null ? null : after.occurredAt, after === null ? null : after.occurredAt, after === null ? null : after.occurredAt, after === null ? null : after.id, query.limit)
+                .all();
+            const rows = result.results ?? [];
+            return { events: rows.map((row) => mapEvent(row, query.resourceType)) };
+        },
+    };
+}

package/dist/adapters/db/db-boards.d.ts

@@ -0,0 +1,6 @@
+import type { BoardRepository } from "../../boards/boards.types.js";
+import type { D1Database } from "./db.types.js";
+export declare function createBoardRepository(deps: {
+    db: D1Database;
+    now(): Date;
+}): BoardRepository;