feat: add scoped document API and resumable batch uploader

apps/docs/scripts/auth-cli.ts

@@ -18,6 +18,7 @@ import {
   totp,
   isLoginRedirect,
 } from "../src/lib/auth";
+import { createDocumentKey, revokeDocumentKey } from "../src/lib/document-keys";
 import { readDocument, saveDocument } from "../src/lib/docs";
 import { consumeCode, initializeStore } from "../src/lib/auth-store";
 
@@ -210,6 +211,7 @@ async function main() {
   assert.equal(raw.status, 200);
   assert.ok((await raw.text()).startsWith("# Endor"));
   if (process.env.DOCUMENT_SMOKE_TEST) {
+    if (command === "exercise") await exerciseDocumentApi(request, headers);
     const sourceSlug = "ci-live-document";
     const previous = readDocument(sourceSlug);
     if (command === "exercise") {
@@ -356,3 +358,42 @@ main().catch((error) => {
   );
   process.exitCode = 1;
 });
+
+async function exerciseDocumentApi(request: (path: string, init?: RequestInit) => Promise<Response>, session: Record<string, string>) {
+  const writer = createDocumentKey("isolated API smoke", "read-write", 1);
+  const reader = createDocumentKey("isolated read smoke", "read", 1);
+  const headers = { Authorization: "Bearer " + writer.token, "Content-Type": "application/json", "Idempotency-Key": "smoke-batch" };
+  const readHeaders = { Authorization: "Bearer " + reader.token, "Content-Type": "application/json" };
+  const make = (name: string) => ({ slug: `endor/${name}`, sourceSlug: name, title: "API smoke",
+    category: "Endor", collection: "Endor 文档", group: "CI", description: "Isolated API smoke",
+    draft: true, featured: false, content: "# API smoke", revision: 0 });
+  const payload = { documents: [make("ci-api-first"), make("ci-api-second")] };
+  try {
+    assert.equal((await request("/api/documents")).status, 401);
+    assert.equal((await request("/api/documents", { method: "POST", headers: { ...session, "Content-Type": "application/json" }, body: JSON.stringify(payload.documents[0]) })).status, 401);
+    assert.equal((await request("/api/research/ai-companies", { headers })).status, 401, "Document keys cannot read research");
+    assert.equal((await request("/api/search", { headers })).status, 401, "Document keys cannot authenticate other APIs");
+    assert.equal((await request("/api/documents/batch", { method: "POST", headers: readHeaders, body: JSON.stringify(payload) })).status, 403);
+    const saved = await request("/api/documents/batch", { method: "POST", headers, body: JSON.stringify(payload) });
+    assert.equal(saved.status, 200);
+    assert.equal((await saved.json()).documents.length, 2);
+    const replay = await request("/api/documents/batch", { method: "POST", headers, body: JSON.stringify(payload) });
+    assert.equal(replay.status, 200); assert.equal((await replay.json()).replayed, true);
+    const current = await request("/api/documents/item/endor/ci-api-first", { headers: readHeaders });
+    assert.equal(current.status, 200); assert.equal((await current.json()).revision, 1);
+    const page = await request("/api/documents?limit=1", { headers: readHeaders });
+    assert.equal(page.status, 200);
+    const listing = await page.json();
+    assert.equal(listing.documents.length, 1); assert.equal(listing.documents[0].content, undefined);
+    const bad = { documents: [{ ...payload.documents[0], revision: 1, content: "Must roll back" }, payload.documents[1]] };
+    const conflict = await request("/api/documents/batch", { method: "POST", headers: { ...headers, "Idempotency-Key": "smoke-conflict" }, body: JSON.stringify(bad) });
+    assert.equal(conflict.status, 409);
+    const unchanged = await request("/api/documents/item/endor/ci-api-first", { headers: readHeaders });
+    assert.equal((await unchanged.json()).content, "# API smoke");
+    const history = await request("/api/documents/item/endor/ci-api-first?history=1", { headers });
+    assert.equal(history.status, 200); assert.equal((await history.json()).total, 1);
+    revokeDocumentKey(writer.id);
+    assert.equal((await request("/api/documents", { headers })).status, 401);
+  } finally { revokeDocumentKey(writer.id); revokeDocumentKey(reader.id); }
+  console.log("Document API smoke passed: scoped keys, batch rollback, pagination, history, replay and revocation; no secrets displayed");
+}

apps/docs/scripts/docs-cli.ts

@@ -1,11 +1,37 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, openSync, closeSync, unlinkSync } from "node:fs";
+import { resolve, dirname, sep } from "node:path";
+import { createDocumentKey, listDocumentKeys, revokeDocumentKey, type DocumentKeyScope } from "../src/lib/document-keys";
 import { openSiteDatabase } from "../src/lib/site-database";
 import { allDocuments, readDocument, saveDocument, importDocuments, documentHistory } from "../src/lib/docs";
 
 process.umask(0o077);
-const [command, argument] = process.argv.slice(2);
+const [command, argument, ...extra] = process.argv.slice(2);
 try {
   switch (command) {
+    case "key-create": {
+      const authFile = process.env.AUTH_CONFIG_FILE;
+      if (!authFile || !argument || !extra[0]) throw Error("Usage: key-create <name> <private-file> [read|read-write] [days]");
+      const file = resolve(extra[0]);
+      const directory = resolve(dirname(authFile));
+      if (!file.startsWith(directory + sep)) throw Error("Key output must be inside the private authentication directory");
+      const fd = openSync(file, "wx", 0o600);
+      let created: { id: string } | undefined;
+      try {
+        const key = createDocumentKey(argument, (extra[1] ?? "read-write") as DocumentKeyScope, Number(extra[2] ?? 90));
+        created = key;
+        writeFileSync(fd, JSON.stringify(key) + "\n");
+        console.log(JSON.stringify({ id: key.id, scope: key.scope, expiresAt: key.expiresAt, saved: file }));
+      } catch (error) {
+        if (created) revokeDocumentKey(created.id);
+        unlinkSync(file);
+        throw error;
+      } finally { closeSync(fd); }
+      break;
+    }
+    case "key-list": console.log(JSON.stringify(listDocumentKeys(), null, 2)); break;
+    case "key-revoke":
+      if (!argument) throw Error("Provide key id");
+      revokeDocumentKey(argument); console.log("Document key revoked"); break;
     case "backup": {
       if (!argument) throw Error("Provide a private backup filename");
       const db = openSiteDatabase();
@@ -36,7 +62,7 @@ try {
         { flag: "wx", mode: 0o600 });
       console.log("Document export created; existing files are never overwritten"); break;
     }
-    default: throw Error("Usage: docs backup <private-file> | list | get <slug> | save < input.json | history <sourceSlug> | import [--if-empty] < export.json | export <private-file>");
+    default: throw Error("Usage: docs key-create <name> <private-file> [read|read-write] [days] | key-list | key-revoke <id> | backup <private-file> | list | get <slug> | save < input.json | history <sourceSlug> | import [--if-empty] < export.json | export <private-file>");
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : "Document operation failed");

apps/docs/scripts/test-docs.mjs

@@ -6,9 +6,8 @@ import { spawnSync } from "node:child_process";
 
 const dir = await mkdtemp(join(tmpdir(), "tabularium-docs-tests-"));
 try {
-  const file = join(dir, "docs.test.cjs");
-  await build({ entryPoints: ["tests/docs.test.ts"], bundle: true,
-    platform: "node", target: "node22", format: "cjs", outfile: file });
-  const result = spawnSync(process.execPath, ["--test", file], { stdio: "inherit" });
+  await build({ entryPoints: ["tests/docs.test.ts", "tests/documents-api.test.ts"], bundle: true,
+    platform: "node", target: "node22", format: "cjs", outdir: dir, outExtension: { ".js": ".cjs" } });
+  const result = spawnSync(process.execPath, ["--test", join(dir, "docs.test.cjs"), join(dir, "documents-api.test.cjs")], { stdio: "inherit" });
   process.exitCode = result.status ?? 1;
 } finally { await rm(dir, { recursive: true, force: true }); }