Add counts, HTML preview, and a run-scoped workflow mount (CL-8188) (#10)

Closes the Workbench gap check: GET /artifacts/counts tallies a
host-supplied predicate/segment map over a full tenant walk, GET
/artifacts/:id/preview serves a sandboxed text/html body with the same
locked-down CSP Workbench's artifacts-hub used, and
mountWorkflowArtifacts adds a parallel bearer-token-authenticated mount
(create / recent / get / binary create) for workflow-run callers that
have no browser session. Per-run rate limiting stays host-side.

Author: TheGreatAxios

README.md

@@ -85,6 +85,44 @@ this module mounted and the acceptance suite pointed at it. Start there if you n
 whole `createApp` wiring, including host middleware that sets `tenant`/`principal` and
 a host-owned `RequireGrant`.
 
+## Run-scoped mount (workflow runs)
+
+`mountArtifacts` reads `tenant`/`principal` off a `TenantEnv` context — it has no
+bearer-token auth surface, and never will: mixing a browser-session convention and a
+sidecar-token convention into one mount would make each harder to reason about. A
+workflow run has no browser session, so it authenticates a different way (a sidecar
+bearer token + a run address header). `mountWorkflowArtifacts` is the parallel mount for
+that caller:
+
+```ts
+import { Hono } from "hono";
+import { InlineContentStore, mountWorkflowArtifacts } from "@corbits/artifacts";
+
+const workflowApi = new Hono();
+mountWorkflowArtifacts(workflowApi, {
+  db: hub.db,
+  contentStore: InlineContentStore,
+  // Host-owned: verify the sidecar's bearer token and run address however the
+  // host issues them, and return the run's tenant/principal/run id, or null.
+  resolveRunScope: async (bearerToken, runAddress) =>
+    hub.resolveWorkflowRun(bearerToken, runAddress),
+});
+app.route("/workflow-artifacts", workflowApi);
+```
+
+Routes: `POST /artifacts` (create), `GET /artifacts/recent`, `GET /artifacts/:id`
+(read-back — 404s a skill-draft or another tenant's row, same as `mountArtifacts`'
+detail route), and `POST /artifacts/binary` (base64 `contentBase64` body, for a render
+step that needs to persist bytes rather than text). Every route is behind
+`resolveRunScope`; there is no unauthenticated case here the way collection reads have
+one on the tenant-session mount, since a workflow run always presents credentials.
+
+**Rate limiting is host-side.** `mountWorkflowArtifacts` mints no per-run quota — a host
+that wants one wraps `resolveRunScope` (returning `null` to reject) or puts its own
+middleware in front of the mounted app. `maxContentChars` (default 64,000) and
+`maxBinaryBytes` (default `MAX_UPLOAD_BYTES`) are the two size ceilings this package
+does own, since they protect the same storage `mountArtifacts` protects.
+
 ## The options
 
 Three options have no sensible default; the rest fail closed and degrade a *feature*,
@@ -98,6 +136,7 @@ never safety.
 | `decorate` | no | No-op — rows carry no decoration. Display-only by contract, so it can never change what is returned or who sees it. Clients resolve display names from `ownerPrincipalId` when they need them. |
 | `onArtifactCreated` | no | No-op. Runs inside the same transaction as artifact creation, once per row — the seam a host uses to provision grants (e.g. a `creator`-origin grant on `artifact:<id>` for `write`/`archive`) for the row it just made. See `examples/reference-host`'s `grantOwnership` for a worked example against a real grant store. |
 | `uploadPolicy` | no | `ARTIFACT_UPLOAD_POLICY` — the standard document/image/spreadsheet allowlist. |
+| `countSegments` | no | `{}` — `GET /api/artifacts/counts` answers just `{ all }`. See [Counts](#counts). |
 
 Who the request runs as is **not** an option: the host's auth/tenant middleware puts
 `tenant` and `principal` on the `TenantEnv` context, and this package reads them. No
@@ -120,6 +159,8 @@ happen in major versions.
 | `GET`/`POST /api/artifacts/:id/versions` | Version history (paginated, no content bodies) and revision |
 | `POST /api/artifacts/:id/(un)archive` | Idempotent soft-hide |
 | `GET /api/artifacts/:id/download` | One path over three storage conventions |
+| `GET /api/artifacts/counts` | Per-segment counts over the tenant. See [Counts](#counts) |
+| `GET /api/artifacts/:id/preview` | Sandboxed `text/html`-only preview. See [Preview](#preview) |
 | `…/api/instances/:id/mail-attachments` | Artifact↔message associations |
 
 Every route carries `describeRoute`, so it appears in the host's `/openapi.json`.
@@ -232,6 +273,55 @@ suite. The contract owed to a parsing host is **parse before you store** — the
 failure leaves no orphan artifact and no orphan bytes, and a success writes bytes, row
 and version 1 in one transaction.
 
+## Counts
+
+`GET /api/artifacts/counts` answers `{ all, ...perSegmentCounts }` — a real walk over
+every page of the tenant's (non-archived) artifacts, bucketed by whichever predicates
+the host passes as `countSegments`. This package owns none of the segment taxonomy
+(what makes an artifact a "sheet" or a "routine" is entirely product-specific); it only
+walks the rows once and tallies:
+
+```ts
+mountArtifacts(app, {
+  db,
+  contentStore,
+  requireGrant,
+  countSegments: {
+    document: (row) => row.kind === "document",
+    sheet: (row) => row.kind === "sheet",
+    routine: (row) => row.kind === "routine",
+  },
+});
+// GET /api/artifacts/counts -> { all: 42, document: 30, sheet: 10, routine: 2 }
+```
+
+Omit `countSegments` and the route still answers with just the tenant-wide `all`. The
+walk caps at 200 pages (`MAX_COUNT_PAGES`, exported from the package) and throws
+`ArtifactCountsIncompleteError` — mapped to HTTP `503` — rather than ever returning a
+partial count as if it were the whole tenant. `countArtifactsBySegments` (also exported)
+is the underlying function, usable directly outside the mounted route.
+
+## Preview
+
+`GET /api/artifacts/:id/preview` serves an artifact's body as a **sandboxed HTML
+document** — for a self-contained page an artifact stores (a rendered report, a chart
+export) that a host wants to render visually without giving it any reach into the host's
+own origin. Only an artifact whose resolved content type is exactly `text/html` is
+previewable; anything else answers `415`. The response carries:
+
+```
+Content-Security-Policy: sandbox allow-scripts; default-src 'none'; style-src 'unsafe-inline'; img-src data:; script-src 'unsafe-inline'
+X-Content-Type-Options: nosniff
+```
+
+`sandbox allow-scripts` puts the document in an opaque unique origin — scripts may run,
+but there is no cookie/storage access, no same-origin fetch, no top-level navigation, no
+popups. `default-src 'none'` blocks any further network reach; `style-src`/`img-src
+data:`/`script-src 'unsafe-inline'` are exactly what a single-file page needs and no
+more. `X-Frame-Options` is deliberately never set, so the host's own canvas/iframe can
+still embed it. `resolveArtifactPreview` and `artifactPreviewHeaders` are exported
+directly for a host that wants to serve the same preview from its own route.
+
 ## ContentStore
 
 Where file bytes live is a port. Two impls ship and both pass the same suite:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corbits/artifacts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "LGPL-2.1-only",
   "description": "Artifacts, versions and uploads with a pluggable ContentStore, mountable onto any Interchange host. Requires @intx 0.2.2 or newer.",

src/counts.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ArtifactCountsIncompleteError,
+  countArtifactsBySegments,
+  MAX_COUNT_PAGES,
+} from "./counts.js";
+import { setArtifactArchived } from "./artifacts.js";
+import { seedArtifact, testDb } from "./test-helpers.js";
+import type { ArtifactDb } from "./db.js";
+import { listArtifacts } from "./artifacts.js";
+
+describe("countArtifactsBySegments", () => {
+  test("returns just `all` when no segments are supplied", async () => {
+    const db = await testDb();
+    await seedArtifact(db, { kind: "document" });
+    await seedArtifact(db, { kind: "document" });
+
+    const counts = await countArtifactsBySegments(db, "acme", {});
+    expect(counts).toEqual({ all: 2 });
+  });
+
+  test("tallies each row against every predicate", async () => {
+    const db = await testDb();
+    await seedArtifact(db, { kind: "document" });
+    await seedArtifact(db, { kind: "document" });
+    await seedArtifact(db, { kind: "sheet" });
+
+    const counts = await countArtifactsBySegments(db, "acme", {
+      document: (row) => row.kind === "document",
+      sheet: (row) => row.kind === "sheet",
+      routine: (row) => row.kind === "routine",
+    });
+    expect(counts).toEqual({ all: 3, document: 2, sheet: 1, routine: 0 });
+  });
+
+  // The walk pages at 100 rows/page — seed past that boundary so a passing
+  // test proves the cursor loop, not just a single-page happy path.
+  test("walks past a single page", async () => {
+    const db = await testDb();
+    await Promise.all(
+      Array.from({ length: 120 }, (_, i) =>
+        seedArtifact(db, { kind: "document", title: `doc-${i}` }),
+      ),
+    );
+
+    const counts = await countArtifactsBySegments(db, "acme", {
+      document: (row) => row.kind === "document",
+    });
+    expect(counts).toEqual({ all: 120, document: 120 });
+  });
+
+  test("never counts another tenant's artifacts", async () => {
+    const db = await testDb();
+    await seedArtifact(db, { tenantId: "acme" });
+    await seedArtifact(db, { tenantId: "other" });
+
+    const counts = await countArtifactsBySegments(db, "acme", {});
+    expect(counts).toEqual({ all: 1 });
+  });
+
+  test("excludes archived artifacts, matching GET /artifacts' default view", async () => {
+    const db = await testDb();
+    const row = await seedArtifact(db, { kind: "document" });
+    await seedArtifact(db, { kind: "document" });
+    await setArtifactArchived(db, row, true);
+
+    const counts = await countArtifactsBySegments(db, "acme", {});
+    expect(counts).toEqual({ all: 1 });
+  });
+
+});
+
+// `ArtifactCountsIncompleteError` and the page cap it backstops are exercised
+// end to end at the route level (mount.test.ts), where the honest-503
+// contract lives; the walk's cursor plumbing itself is real Postgres
+// pagination, not something worth faking a stalled cursor for here.
+test("MAX_COUNT_PAGES is the documented cap", () => {
+  expect(MAX_COUNT_PAGES).toBe(200);
+  expect(ArtifactCountsIncompleteError.prototype).toBeInstanceOf(Error);
+});
+
+// Sanity: countArtifactsBySegments' walk must agree with what GET /artifacts
+// itself would page through — same underlying listArtifacts call, same
+// exclusions.
+test("agrees with listArtifacts' own row set", async () => {
+  const db = await testDb();
+  await seedArtifact(db, { kind: "document" });
+  await seedArtifact(db, { kind: "sheet" });
+
+  const [counts, page] = await Promise.all([
+    countArtifactsBySegments(db, "acme", {}),
+    listArtifacts(db, "acme", {}),
+  ]);
+  expect(counts.all).toBe(page.rows.length);
+});

src/counts.ts

@@ -0,0 +1,86 @@
+import type { ArtifactDb } from "./db.js";
+import { listArtifacts, type ArtifactListRow } from "./artifacts.js";
+
+// Safety cap on the counts walk: 200 pages of MAX_LIST_LIMIT rows each is
+// tens of thousands of artifacts, far past any real tenant today. A tenant
+// that legitimately exceeds it — or a store whose cursor stops advancing —
+// gets an honest "can't count that" instead of a route that hangs or lies
+// with a partial total.
+export const MAX_COUNT_PAGES = 200;
+
+/** One page's worth of rows per walk step, matching `listArtifacts`' own cap. */
+const COUNT_PAGE_LIMIT = 100;
+
+/** Thrown when the counts walk cannot finish honestly — capped out or the
+ * underlying cursor stopped advancing — rather than ever returning a partial
+ * count as if it were the whole tenant. */
+export class ArtifactCountsIncompleteError extends Error {}
+
+/** A host-supplied predicate bucketing rows into a named segment. The
+ * segment taxonomy (what a "sheet" or "routine" artifact is) is entirely
+ * host-owned — this module only walks the tenant's artifacts once and tallies
+ * whichever predicates the host hands it. */
+export type ArtifactCountSegments = Readonly<
+  Record<string, (row: ArtifactListRow) => boolean>
+>;
+
+/** Per-segment counts plus the tenant total. Always includes `all`, plus one
+ * key per segment name passed to `countArtifactsBySegments`. */
+export type ArtifactCounts = { readonly all: number } & Readonly<
+  Record<string, number>
+>;
+
+/**
+ * Walks every page of a tenant's (non-archived) artifacts — the same rows
+ * `GET /artifacts` would page through, so a row is never double-counted or
+ * missed at a page boundary — and buckets each row by every predicate in
+ * `segments`. Real counts over the full tenant list, not an estimate from one
+ * page.
+ */
+export async function countArtifactsBySegments(
+  db: ArtifactDb,
+  tenantId: string,
+  segments: ArtifactCountSegments,
+): Promise<ArtifactCounts> {
+  let all = 0;
+  const bySegment: Record<string, number> = Object.fromEntries(
+    Object.keys(segments).map((name) => [name, 0]),
+  );
+
+  let cursor: string | undefined;
+  let pages = 0;
+  for (;;) {
+    const page = await listArtifacts(db, tenantId, {
+      limit: COUNT_PAGE_LIMIT,
+      ...(cursor !== undefined ? { cursor: parseCursor(cursor) } : {}),
+    });
+    pages += 1;
+    for (const row of page.rows) {
+      all += 1;
+      for (const [name, predicate] of Object.entries(segments)) {
+        if (predicate(row)) bySegment[name] += 1;
+      }
+    }
+    if (page.nextCursor === null) break;
+    if (page.nextCursor === cursor) {
+      throw new ArtifactCountsIncompleteError(
+        `Artifact list cursor for tenant ${tenantId} did not advance past page ${pages}`,
+      );
+    }
+    if (pages >= MAX_COUNT_PAGES) {
+      throw new ArtifactCountsIncompleteError(
+        `Artifact list for tenant ${tenantId} exceeds ${MAX_COUNT_PAGES} pages — counts would be incomplete`,
+      );
+    }
+    cursor = page.nextCursor;
+  }
+
+  return { all, ...bySegment };
+}
+
+/** `listArtifacts`' cursor filter wants `{ at, id }`, not the opaque
+ * `at__id` string it hands back — mirror its own encoding here. */
+function parseCursor(raw: string): { at: string; id: string } {
+  const sep = raw.lastIndexOf("__");
+  return { at: raw.slice(0, sep), id: raw.slice(sep + 2) };
+}

src/index.ts

@@ -2,6 +2,21 @@
 export { mountArtifacts } from "./mount.js";
 export type { MountArtifactsOpts } from "./mount.js";
 
+export { mountWorkflowArtifacts } from "./workflow-mount.js";
+export type {
+  CreatedWorkflowArtifact,
+  MountWorkflowArtifactsOpts,
+  ResolvedWorkflowRunScope,
+  WorkflowArtifactEnv,
+  WorkflowRunResolver,
+} from "./workflow-mount.js";
+
+export { ArtifactCountsIncompleteError, countArtifactsBySegments, MAX_COUNT_PAGES } from "./counts.js";
+export type { ArtifactCounts, ArtifactCountSegments } from "./counts.js";
+
+export { artifactPreviewHeaders, resolveArtifactPreview } from "./preview.js";
+export type { ArtifactPreviewResult } from "./preview.js";
+
 export { runArtifactMigrations, MigrationChecksumError, MigrationAdoptError } from "./migrations.js";
 export type { RunArtifactMigrationsOptions } from "./migrations.js";