@taprootio/site-authoring 0.23.0 → 0.24.0

package/src/transport.js

@@ -51,6 +51,10 @@ const IDEMPOTENT_METHODS = new Set(["GET"]);
 
 /** An exchanged credential is renewed once it is this close to expiring. */
 const CREDENTIAL_RENEWAL_MARGIN_MILLISECONDS = 5 * 60_000;
+const GATEWAY_UPLOAD_ATTEMPTS = 4;
+const GATEWAY_CAPACITY_WINDOW_MILLISECONDS = 15_000;
+const UPLOAD_CAPACITY_HEADER = "x-taproot-upload-admission";
+const UPLOAD_CAPACITY_REFUSAL = "capacity-before-claim";
 
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 const RETRYABLE_RESPONSE_ERRORS = new Set([
@@ -965,15 +969,16 @@ export class SiteApiClient {
   }
 
   /**
-   * Performs one presigned whole-object PUT. The signed headers are echoed
+   * Performs a whole-object PUT. Signed S3 headers are echoed
    * exactly as the server returned them and are never recomputed: the values
    * are covered by the SigV4 signature, so a "helpfully" regenerated
    * Content-Type or an added header turns into an opaque S3 403. The bearer is
    * never forwarded — the signature is the authorization, and sending the
    * site key to an object store would leak it outside the reviewed origin.
    *
-   * The PUT of an immutable object is idempotent, so this is the one mutation
-   * shape that may be replayed.
+   * S3 create-only uploads retain their existing retry contract. A gateway
+   * capability is consumed once before the body is read. Only an explicit
+   * capacity refusal before that claim permits a bounded retry.
    */
   async upload({ url: uploadUrl, requiredHeaders } = {}, bodyBytes) {
     // A video original is streamed from disk: `{ byteLength, stream, timeoutMilliseconds }`,
@@ -1040,7 +1045,8 @@ export class SiteApiClient {
       names.add(normalizedName);
       headers.set(name, value);
     }
-    if (!headers.has("content-type") || !headers.has("content-length")) {
+    const gateway = headers.has("x-taproot-upload-capability");
+    if (!headers.has("content-type") || (!gateway && !headers.has("content-length"))) {
       throw new SiteAuthoringError(
         "upload.headers_invalid",
         "The signed upload capability is missing required content headers.",
@@ -1049,31 +1055,48 @@ export class SiteApiClient {
     // The declared length is bound into the signature, so a body of any other
     // size cannot succeed. Failing here names the real problem instead of
     // surfacing an S3 signature error.
-    if (headers.get("content-length") !== String(bodyBytes.byteLength)) {
+    if (gateway && (
+      url.origin !== this.apiOrigin
+      || !url.pathname.startsWith(this.apiPathPrefix)
+      || !/^\/api\/v1\/images\/uploads\/[0-9a-f-]{36}\/content$/u.test(url.pathname)
+      || url.search !== ""
+    )) {
+      throw new SiteAuthoringError("upload.contract_invalid", "Taproot returned an invalid gateway URL.");
+    }
+    if (!gateway && headers.get("content-length") !== String(bodyBytes.byteLength)) {
       throw new SiteAuthoringError(
         "upload.content_length_invalid",
         "The signed upload content length does not match the bytes being uploaded.",
       );
     }
 
-    for (let attempt = 0; attempt < LIMITS.uploadAttempts; attempt += 1) {
+    const maximumAttempts = gateway ? GATEWAY_UPLOAD_ATTEMPTS : LIMITS.uploadAttempts;
+    const startedAt = this.now();
+    const uploadDeadline = startedAt + ((streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds);
+    for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
+      if (this.signal?.aborted) throw cancelledError(false);
+      const remaining = uploadDeadline - this.now();
+      if (gateway && remaining <= 0) {
+        throw new SiteAuthoringError("upload.capacity_exhausted", "The image upload exhausted its attempt window.");
+      }
       let response;
+      const attemptSignal = operationSignal(
+        this.signal,
+        gateway ? remaining : (streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds,
+        this.timeoutSignal,
+      );
       try {
-        response = await this.fetch(url, {
+        response = await awaitWithSignal(this.fetch(url, {
           method: "PUT",
           redirect: "error",
-          signal: operationSignal(
-            this.signal,
-            (streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds,
-            this.timeoutSignal,
-          ),
+          signal: attemptSignal,
           headers,
           ...(streamed
             ? { body: Readable.toWeb(bodyBytes.stream()), duplex: "half" }
             : { body: bodyBytes }),
-        });
+        }), attemptSignal);
       } catch {
-        if (attempt + 1 < LIMITS.uploadAttempts && !this.signal?.aborted) {
+        if (!gateway && attempt + 1 < maximumAttempts && !this.signal?.aborted) {
           await this.sleep(delayForAttempt(attempt), this.signal);
           continue;
         }
@@ -1082,14 +1105,29 @@ export class SiteApiClient {
           "The whole-object upload ended without an authoritative response.",
         );
       }
-      await cancelBody(response);
+      await cancelBody(response, attemptSignal);
       if (response.status >= 200 && response.status < 300 && !response.redirected) return;
-      if (RETRYABLE_STATUS.has(response.status) && attempt + 1 < LIMITS.uploadAttempts) {
+      const capacityRefused = gateway && !response.redirected && response.status === HTTP_TOO_MANY_REQUESTS
+        && response.headers.get(UPLOAD_CAPACITY_HEADER) === UPLOAD_CAPACITY_REFUSAL;
+      const retryAfter = response.headers.get("retry-after") ?? "";
+      if (capacityRefused && /^[1-5]$/u.test(retryAfter) && attempt + 1 < maximumAttempts) {
+        const delay = Number(retryAfter) * 1000;
+        const capacityRemaining = Math.min(uploadDeadline, startedAt + GATEWAY_CAPACITY_WINDOW_MILLISECONDS) - this.now();
+        if (delay < capacityRemaining) {
+          // TR01295: the server guarantees that this rejected PUT did not
+          // claim the capability. Network failures and 5xx never retry it.
+          await awaitWithSignal(this.sleep(delay, this.signal), operationSignal(
+            this.signal, capacityRemaining, this.timeoutSignal,
+          ));
+          if (this.now() - startedAt < GATEWAY_CAPACITY_WINDOW_MILLISECONDS) continue;
+        }
+      }
+      if (!gateway && RETRYABLE_STATUS.has(response.status) && attempt + 1 < maximumAttempts) {
         await this.sleep(delayForAttempt(attempt), this.signal);
         continue;
       }
       throw new SiteAuthoringError(
-        RETRYABLE_STATUS.has(response.status) ? "upload.ambiguous" : "upload.rejected",
+        RETRYABLE_STATUS.has(response.status) && !capacityRefused ? "upload.ambiguous" : "upload.rejected",
         `The whole-object upload was rejected with HTTP ${response.status}.`,
         { status: `http:${response.status}` },
       );

package/src/typed-page-reference.js

@@ -323,12 +323,6 @@ const TYPE_DETAILS = Object.freeze({
   },
 });
 
-/**
- * The legal page type (TR01221). It is described here and nowhere else in the
- * CLI: it has no template name in `typed-pages.js` because a site-authoring
- * key cannot author it, so `pull` records it as a metadata-only page and
- * `pages push` never sees a source for it.
- */
 export const LEGAL_PAGE_TYPE = "legal";
 
 export const TYPED_PAGE_TYPES = Object.freeze([...Object.keys(TYPE_DETAILS), LEGAL_PAGE_TYPE]);
@@ -355,15 +349,14 @@ function legalReference() {
     displayName: "Legal page",
     summary:
       "A versioned legal document such as a privacy policy or terms: an automatic h1, a version and effective date, and "
-      + "permanent links to each version. The CLI sees it as metadata only; it is created and published in the app.",
-    readOnly: true,
+      + "permanent links to each version. The CLI can edit drafts with an explicit site grant; approval and publication happen in the app.",
+    readOnly: false,
     workspace: Object.freeze({
       directory: `${PAGES_DIRECTORY}/`,
       templateType: "TEMPLATE_TYPE_LEGAL",
       sourceRule:
-        "A legal page has no source file. 'pull' lists it in .taproot-site-manifest.json with templateType "
-        + "TEMPLATE_TYPE_LEGAL and workspaceMode \"metadata-only\" and writes nothing under pages/ for it, so 'pages push' has "
-        + "nothing to send.",
+        "Pull writes a .pm.json source containing template legal and data with documentKey, documentRole, summaryOfChanges, material and body. "
+        + "Edit that source to change the draft; Markdown is not supported. To create one, add a .pm.json source and a manifest pages entry with file, title and path, without a pageId. Version, effectiveDate and supersedesVersion are assigned by Taproot and must not be authored.",
     }),
     fields: Object.freeze([
       Object.freeze({ name: "title", description: "The page title. It prints as the page's h1, so the body should not open with its own title." }),
@@ -374,13 +367,13 @@ function legalReference() {
       Object.freeze({
         name: "documentKey",
         description:
-          "The document's stable identity, set in the app. The permanent version address exists only once the page has "
+          "The document's stable identity, fixed after creation. The permanent version address exists only once the page has "
           + "a document key and a version.",
       }),
       Object.freeze({
         name: "documentRole",
         description:
-          "The typed purpose of the document, such as membership_terms or privacy_notice. Selected in the app; fixed for membership terms.",
+          "The typed purpose of the document, such as membership_terms or privacy_notice. Fixed after creation.",
       }),
       Object.freeze({ name: "summaryOfChanges", description: "A short note on what this version changed, written by the owner." }),
       Object.freeze({
@@ -402,14 +395,11 @@ function legalReference() {
     ]),
     authoring: Object.freeze({
       cli:
-        "Read-only. 'pull' records the page's identity, path, title and status. No verb creates, edits, converts, "
-        + "approves or publishes one. A bare 'approve' stages every tracked page with a draft, a pending legal draft "
-        + "included, and the request holding it is refused (up to 100 pages go in one request): name the pages ('approve <path>').",
+        "Pull reads legal pages with ordinary Content access. Run 'taproot-site login --legal-drafts', then "
+        + "'taproot-site --legal-drafts pages push' to create or edit legal drafts. Approval and deletion are refused by the CLI; use the app. A bare 'approve' skips legal drafts; naming a legal page refuses the whole selection.",
       key:
-        "A site-authoring key cannot create or publish a legal page, and a production deploy whose selected pages include "
-        + "one is refused for a key, because the permission that governs legal documents (site.legal_documents.manage) is "
-        + "outside the key's delegation.content, delegation.design and delegation.deployments capabilities. Until a "
-        + "person promotes an app-approved legal page, every production promotion of a release staged after that approval is refused. This is how keys work today; whether a key should ever author a legal page is an open owner decision.",
+        "Only an explicit site-specific legal-drafts grant can save legal drafts. It does not grant site.legal_documents.manage, "
+        + "and cannot approve, delete or deploy legal documents.",
       app:
         "A signed-in person who may manage the site's legal documents creates the page, writes its body, and publishes it "
         + "with a production deployment in the app. Taproot assigns the version and effective date at that point.",
@@ -421,18 +411,21 @@ function legalReference() {
       freeForm:
         "A free-form page is an ordinary page. It has no version history, no effective date, no permanent version "
         + "addresses and no automatic heading: open its Markdown with a '# ' line holding the title (see "
-        + `'${CLI_BINARY_NAME} help page free-form'). The CLI cannot author a legal page, so a policy written here is an ordinary `
-        + "page, free-form unless another template fits: put the date it was last updated in its text, and tell the owner it is not versioned.",
+        + `'${CLI_BINARY_NAME} help page free-form'). A policy written as free-form is an ordinary page; put its last-updated date in its text and tell the owner it is not versioned.`,
     }),
     platformLink: LEGAL_PLATFORM_LINK_GUIDANCE,
     workflow: Object.freeze([
       Object.freeze({
         command: `${CLI_BINARY_NAME} pull`,
-        result: "Records the page as metadata-only in the manifest; nothing to edit.",
+        result: "Writes the legal draft as a .pm.json source and records its identity in the manifest.",
+      }),
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} login --legal-drafts`,
+        result: "Request a site-specific grant; a person approves it in the app.",
       }),
       Object.freeze({
-        command: "the app",
-        result: "A person with the legal permission edits the draft and promotes it with a production deployment.",
+        command: `${CLI_BINARY_NAME} --legal-drafts pages push`,
+        result: "Saves changed legal drafts. A person approves and publishes them in the app.",
       }),
     ]),
   });
@@ -516,7 +509,7 @@ function formatField(field) {
 }
 
 function formatLegalReference(page) {
-  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n\nFields (set in the app):\n${
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n\nFields:\n${
     page.fields.map((field) => `  ${field.name}: ${field.description}`).join("\n")
   }\n\nHow it renders:\n${page.rendering.map((line) => `  - ${line}`).join("\n")}\n\nWho can author it:\n  CLI                   ${page.authoring.cli}\n  site-authoring key    ${page.authoring.key}\n  app                   ${page.authoring.app}\n\nLegal page or free-form page:\n  legal                 ${page.choosing.legal}\n  free-form             ${page.choosing.freeForm}\n\nLinking Taproot: ${page.platformLink.rule}\n  example               ${page.platformLink.example}\n\nWorkflow:\n${
     page.workflow.map((step) => `  ${step.command}: ${step.result}`).join("\n")

package/src/typed-pages.js

@@ -30,6 +30,7 @@ export const TEMPLATE_ARTICLE = "article";
 export const TEMPLATE_RECIPE = "recipe";
 export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
+export const TEMPLATE_LEGAL = "legal";
 /**
  * A page Taproot generates (a tag, a month, a folder). It is update-only: the
  * owner's title, breadcrumb, description and introduction are authored, and
@@ -44,6 +45,7 @@ export const PAGE_TEMPLATES = Object.freeze({
   [TEMPLATE_RECIPE]: Object.freeze({ wireType: "TEMPLATE_TYPE_RECIPE", dataKey: "recipeData" }),
   [TEMPLATE_ALBUM]: Object.freeze({ wireType: "TEMPLATE_TYPE_ALBUM", dataKey: "albumData" }),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze({ wireType: "TEMPLATE_TYPE_PLACE_REVIEW", dataKey: "placeReviewData" }),
+  [TEMPLATE_LEGAL]: Object.freeze({ wireType: "TEMPLATE_TYPE_LEGAL", dataKey: "legalDocumentData" }),
   [TEMPLATE_GENERATED]: Object.freeze({ wireType: "TEMPLATE_TYPE_GENERATED", dataKey: "generatedPageData" }),
 });
 
@@ -77,6 +79,7 @@ const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
   [TEMPLATE_PLACE_REVIEW]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "placeId", "rating"]),
   // Generated pages have no Markdown form.
   [TEMPLATE_GENERATED]: Object.freeze([]),
+  [TEMPLATE_LEGAL]: Object.freeze([]),
 });
 
 export const FRONT_MATTER_KEYS = Object.freeze(
@@ -172,7 +175,17 @@ export function isAuthorableTemplateType(wireType) {
   return templateNameForWireType(wireType) !== undefined;
 }
 
-/** Whether a wire `templateType` is a generated page. */
+/** Whether this wire template type is a legal document. */
+export function isLegalTemplateType(wireType) {
+  return wireType === PAGE_TEMPLATES[TEMPLATE_LEGAL].wireType;
+}
+
+/** The legal identity fields that remain fixed after creation. */
+export function legalIdentity(data) {
+  return { documentKey: data.documentKey, documentRole: data.documentRole };
+}
+
+/** Whether this wire template type is a generated page. */
 export function isGeneratedTemplateType(wireType) {
   return wireType === PAGE_TEMPLATES[TEMPLATE_GENERATED].wireType;
 }
@@ -342,6 +355,13 @@ function canonicalIngredient(value) {
  * server's JSON omits defaults and may gain fields).
  */
 const DATA_BUILDERS = Object.freeze({
+  [TEMPLATE_LEGAL]: (raw) => ({
+    documentKey: raw.documentKey ?? "",
+    documentRole: raw.documentRole ?? "",
+    summaryOfChanges: raw.summaryOfChanges ?? "",
+    material: raw.material === true,
+    body: raw.body,
+  }),
   [TEMPLATE_ARTICLE]: (raw) => definedEntries([["body", raw.body], ["place", raw.place]]),
   [TEMPLATE_PLACE_REVIEW]: (raw) => ({ placeId: raw.placeId, rating: raw.rating, body: raw.body }),
   // Defaults are written out, so a page with no custom title reads the same on every pull.
@@ -415,6 +435,16 @@ function optionalPlace(value, file, path) {
 /** Strict checks on a source document's `data`, returning it in canonical form. */
 function canonicalSourceData(template, data, file) {
   const path = "data";
+  if (template === TEMPLATE_LEGAL) {
+    requireKeys(data, ["documentKey", "documentRole", "summaryOfChanges", "material", "body"], file, path);
+    for (const key of ["documentKey", "documentRole", "summaryOfChanges"]) {
+      if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
+    }
+    if (data.material !== undefined && typeof data.material !== "boolean") {
+      throw fail("pages.document_shape", `'${file}' ${path}.material must be true or false.`, file);
+    }
+    return DATA_BUILDERS[template]({ ...data, body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }) });
+  }
   if (template === TEMPLATE_ARTICLE) {
     requireKeys(data, ["body", "place"], file, path);
     return DATA_BUILDERS[template]({
@@ -564,10 +594,10 @@ export function typedDocumentFromJson(parsed, file) {
       file,
     );
   }
-  if (template === TEMPLATE_GENERATED && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
+  if ((template === TEMPLATE_GENERATED || template === TEMPLATE_LEGAL) && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
     throw fail(
       "pages.document_shape",
-      `'${file}' is a generated page, which has no displayDate or coverImageId of its own: its document is `
+      `'${file}' is a ${template} page, which has no displayDate or coverImageId of its own: its document is `
         + "{ template, data }.",
       file,
     );
@@ -602,6 +632,16 @@ const pagePlaceId = (value) =>
 
 /** Lenient projections of what the site returned for each template's data. */
 const PAGE_PROJECTIONS = Object.freeze({
+  [TEMPLATE_LEGAL]: (raw) => {
+    const body = presentDocument(raw.body);
+    return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_LEGAL]({
+      documentKey: typeof raw.documentKey === "string" ? raw.documentKey : "",
+      documentRole: typeof raw.documentRole === "string" ? raw.documentRole : "",
+      summaryOfChanges: typeof raw.summaryOfChanges === "string" ? raw.summaryOfChanges : "",
+      material: raw.material === true,
+      body,
+    });
+  },
   [TEMPLATE_ARTICLE]: (raw) => {
     const body = presentDocument(raw.body);
     return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_ARTICLE]({ body, place: pagePlaceId(raw.place) });
@@ -666,7 +706,7 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   const data = PAGE_PROJECTIONS[name](raw);
   if (data === undefined) return undefined;
   // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
-  const generated = name === TEMPLATE_GENERATED;
+  const generated = name === TEMPLATE_GENERATED || name === TEMPLATE_LEGAL;
   return typedDocument(name, {
     displayDate: !generated && typeof page.displayDate === "string" && page.displayDate !== ""
       ? page.displayDate
@@ -705,7 +745,7 @@ export function contentDocuments(document_) {
 /** Whether a push sends `displayDate` for pages of this wire template type (every template but free-form). */
 export function sentDisplayDate(wireType) {
   const name = templateNameForWireType(wireType);
-  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED;
+  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED && name !== TEMPLATE_LEGAL;
 }
 
 // The nodes the API accepts in an album or recipe introduction and in a recipe
@@ -903,7 +943,7 @@ export function wireTemplate(document_) {
  * an update, and an empty string means "clear", which is what the API does.
  */
 export function wirePageFields(document_) {
-  if (documentTemplate(document_) === TEMPLATE_FREE_FORM) return {};
+  if ([TEMPLATE_FREE_FORM, TEMPLATE_LEGAL].includes(documentTemplate(document_))) return {};
   return definedEntries([
     ["displayDate", document_.displayDate],
     ["coverImageId", document_.coverImageId],
@@ -1111,6 +1151,10 @@ function parseFlag(fields, key, file) {
 }
 
 /** Generated pages are edited in their .pm.json source only. */
+export function legalMarkdownFault(file) {
+  return fail("pages.legal_markdown", `'${file}' declares the legal template, which has no Markdown form. Use a .pm.json document.`, file);
+}
+
 export function generatedMarkdownFault(file) {
   return fail(
     "pages.generated_markdown",
@@ -1149,6 +1193,7 @@ export function templateFrontMatterFault(template, fieldNames, file) {
  */
 export async function typedDocumentFromMarkdown({ template, fields, markdown, file, convert, resolveImage }) {
   if (template === TEMPLATE_GENERATED) throw generatedMarkdownFault(file);
+  if (template === TEMPLATE_LEGAL) throw legalMarkdownFault(file);
   const displayDate = fields.has("displayDate") ? requireDisplayDate(fields.get("displayDate"), file) : undefined;
   let coverImageId;
   if (fields.has("coverImage")) {

package/src/verbs/approve.js

@@ -8,6 +8,7 @@ import {
 import { VERB_APPROVE } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedByBytes, boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { isLegalTemplateType } from "../typed-pages.js";
 import { displayPagePath, normalizePagePath, readManifest, writeManifest } from "../workspace.js";
 
 /**
@@ -45,7 +46,7 @@ export async function approve(invocation) {
 
   // Positional arguments narrow the selection to those page paths; `cli.js`
   // hands them over as `pagePaths`, and a programmatic caller can supply the
-  // same key directly. With none, every draft the manifest tracks is staged.
+  // same key directly. With none, legal drafts are skipped and the other tracked drafts are staged.
   //
   // A path this CLI cannot use is refused by name rather than dropped. Dropping
   // it silently is the worst available outcome: the remaining selection would
@@ -80,16 +81,29 @@ export async function approve(invocation) {
       );
     }
     const pathOf = (summary) => normalizePagePath(summary.path) ?? summary.path;
-    const candidates = pages.filter((summary) =>
-      !isGonePage(summary)
-      && summary.hasDraft
-      && manifestByPageId.has(summary.pageId)
-      && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
+    const tracked = pages.filter((summary) => !isGonePage(summary) && manifestByPageId.has(summary.pageId));
+    const isLegal = (page) => isLegalTemplateType(page.templateType)
+      || isLegalTemplateType(manifestByPageId.get(page.pageId)?.templateType);
+    if (requestedPaths !== undefined && tracked.some((page) => requestedPaths.has(pathOf(page)) && isLegal(page))) {
+      throw new SiteAuthoringError("approve.legal_not_allowed", "Legal drafts must be approved in the app. Nothing was approved.", { field: "pages" });
+    }
+    const selected = tracked.filter((summary) =>
+      summary.hasDraft && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
+    const legalDrafts = requestedPaths === undefined ? selected.filter(isLegal) : [];
+    const candidates = selected.filter((page) => !isLegal(page));
 
     // A requested page with nothing to approve is reported, not refused, so
     // one already-approved path does not stop the rest of the batch. A path
     // that names no page this workspace tracks is still refused by name.
-    const skipped = [];
+    const skipped = legalDrafts.map((page) => ({
+      pageId: page.pageId,
+      path: displayPagePath(pathOf(page)),
+      status: page.status,
+      reason: "legal_requires_app",
+    }));
+    if (legalDrafts.length > 0) {
+      onProgress(`Skipping ${legalDrafts.length} legal draft${legalDrafts.length === 1 ? "" : "s"}; approve ${legalDrafts.length === 1 ? "it" : "them"} in the app.`);
+    }
     if (requestedPaths !== undefined) {
       const matched = new Set(candidates.map(pathOf));
       const unknown = [];
@@ -137,7 +151,9 @@ export async function approve(invocation) {
 
     if (candidates.length === 0) {
       onProgress(
-        skipped.length > 0
+        legalDrafts.length > 0
+          ? "No ordinary drafts to approve; approve the skipped legal drafts in the app."
+          : skipped.length > 0
           ? "Nothing to approve: the requested page(s) have no pending draft."
           : "No page in this workspace is carrying a draft; there is nothing to approve.",
       );
@@ -145,7 +161,7 @@ export async function approve(invocation) {
         approved: { total: 0, items: [] },
         ...skippedResult,
         stagedNotDeployed: true,
-        nextStep: "deploy --staging",
+        nextStep: legalDrafts.length > 0 ? "approve legal drafts in the app" : "deploy --staging",
       });
     }
 

package/src/verbs/login.js

@@ -22,6 +22,7 @@ import {
   VERB_LOGIN,
   VERB_LOGOUT,
   VERB_SITES,
+  SURFACE_STANDARD,
 } from "../constants.js";
 import { assertCredentialCapacity, credentialApiOrigin, saveCredential } from "../credentials.js";
 import { asSiteAuthoringError, hasControlCharacter, SiteAuthoringError } from "../errors.js";
@@ -156,7 +157,7 @@ function describeMinutes(milliseconds) {
  * revoked — named by its exact id and display prefix when the server supplied
  * them, and by its display name otherwise.
  */
-function terminalFailure(answer, keyName) {
+function terminalFailure(answer, keyName, loginCommand) {
   const status = answer.status;
   switch (status) {
     case CLI_AUTHORIZATION_CLAIM_STATUS_DENIED:
@@ -168,7 +169,7 @@ function terminalFailure(answer, keyName) {
     case CLI_AUTHORIZATION_CLAIM_STATUS_EXPIRED:
       return new SiteAuthoringError(
         "login.expired",
-        `The authorization expired before it was approved. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+        `The authorization expired before it was approved. Run '${loginCommand}' again.`,
         { status },
       );
     case CLI_AUTHORIZATION_CLAIM_STATUS_CONSUMED:
@@ -179,7 +180,7 @@ function terminalFailure(answer, keyName) {
             ? `Revoke the credential with id ${answer.keyId}`
             + (answer.keyPrefix === undefined ? "" : ` (display prefix ${answer.keyPrefix})`)
             : `Revoke the credential named '${keyName}'`)
-          + ` under Account -> Settings -> API keys, then run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+          + ` under Account -> Settings -> API keys, then run '${loginCommand}' again.`,
         { status },
       );
     default:
@@ -191,11 +192,11 @@ function terminalFailure(answer, keyName) {
   }
 }
 
-function translateClaimApiError(error) {
+function translateClaimApiError(error, loginCommand) {
   if (!(error instanceof ApiError) || error.httpStatus !== 404) return error;
   return new SiteAuthoringError(
     "login.unknown",
-    `Taproot does not recognize this authorization. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}' to start a new one.`,
+    `Taproot does not recognize this authorization. Run '${loginCommand}' to start a new one.`,
     { status: error.status },
   );
 }
@@ -222,13 +223,13 @@ function translateStartApiError(error) {
  * display prefix, never by value — and direct the owner to revoke it, because
  * silence here is a live credential the owner does not know exists.
  */
-function unstoredCredentialFailure(error, claimed) {
+function unstoredCredentialFailure(error, claimed, loginCommand) {
   const cause = asSiteAuthoringError(error);
   return new SiteAuthoringError(
     "login.credential_unstored",
     `A credential WAS issued (id ${claimed.keyId}, display prefix ${claimed.keyPrefix}) but could not `
       + `be stored: ${cause.message} Revoke it under Account -> Settings -> API keys, then run `
-      + `'${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+      + `'${loginCommand}' again.`,
     { ...(cause.status === undefined ? {} : { status: cause.status }) },
   );
 }
@@ -311,7 +312,12 @@ async function handOffToBrowser({ verificationUrl, userCode, onProgress, awaitEn
 
 export async function login(invocation) {
   const keyName = normalizeKeyName(invocation.keyName);
-  const { apiBaseUrl, client, now, onProgress } = await openAnonymousSession(invocation);
+  const { config, apiBaseUrl, client, now, onProgress } = await openAnonymousSession(invocation);
+  const legalDraftSiteId = invocation.legalDrafts ? config?.siteId : undefined;
+  if (invocation.legalDrafts && (!legalDraftSiteId || (config.authoringSurface !== undefined && config.authoringSurface !== SURFACE_STANDARD))) {
+    throw new SiteAuthoringError("auth.legal_site_required", "Select a standard site with taproot-site use before requesting legal draft access.");
+  }
+  const loginCommand = `${CLI_BINARY_NAME} ${VERB_LOGIN}${legalDraftSiteId === undefined ? "" : " --legal-drafts"}`;
   const environment = invocation.environment ?? process.env;
   const apiOrigin = credentialApiOrigin(apiBaseUrl);
 
@@ -323,11 +329,11 @@ export async function login(invocation) {
   // now rather than at the write, which is the same failure arriving after the
   // damage. A residual write failure can still happen (the disk can fill during
   // the poll), which is what `unstoredCredentialFailure` below is for.
-  await assertCredentialCapacity(environment, apiOrigin);
+  await assertCredentialCapacity(environment, apiOrigin, { siteId: legalDraftSiteId });
 
   let authorization;
   try {
-    authorization = await startCliAuthorization(client, { keyName });
+    authorization = await startCliAuthorization(client, { keyName, legalDraftSiteId });
   } catch (error) {
     // Announced only when the refusal survives translation: sign-in is the
     // earlier of the two calls that carry this CLI's version, so it is where
@@ -390,7 +396,7 @@ export async function login(invocation) {
       // total wall time.
       read: async () => {
         try {
-          return await claimCliAuthorization(client, authorization.deviceCode);
+          return await claimCliAuthorization(client, authorization.deviceCode, {}, { legalDraftSiteId, now });
         } catch (error) {
           // A throttle is the endpoint doing its job, not a verdict on this
           // authorization. Back off within the same deadline instead of
@@ -441,7 +447,7 @@ export async function login(invocation) {
             if (error.ambiguousMutation === true) claimResponseLost = true;
             throw error;
           }
-          throw translateClaimApiError(error);
+          throw translateClaimApiError(error, loginCommand);
         }
       },
       evaluate: (value) => {
@@ -464,7 +470,7 @@ export async function login(invocation) {
           // each line pushes the code the operator is still reading off screen.
           return { done: false };
         }
-        throw terminalFailure(value, keyName);
+        throw terminalFailure(value, keyName, loginCommand);
       },
       // A deadline reached after a lost answer cannot honestly say nothing was
       // issued: one of those lost checks may have consumed the approval and
@@ -477,12 +483,12 @@ export async function login(invocation) {
             "The polling deadline passed, and at least one check's answer was lost in transit — a credential "
               + `MAY have been issued without this command receiving it. Nothing was stored locally; check `
               + `Account -> Settings -> API keys for a credential named '${keyName}' and revoke it before running `
-              + `'${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+              + `'${loginCommand}' again.`,
           )
           : new SiteAuthoringError(
             "login.timeout",
             "The approval was not completed before this command's polling deadline. Nothing was stored; "
-              + `run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+              + `run '${loginCommand}' again.`,
           ),
     });
   } catch (error) {
@@ -498,9 +504,12 @@ export async function login(invocation) {
         "site.cancelled",
         "The login was cancelled after a claim's answer was lost — a credential MAY have been issued without "
           + `this command receiving it. Check Account -> Settings -> API keys for a credential named '${keyName}' `
-          + `and revoke it before running '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+          + `and revoke it before running '${loginCommand}' again.`,
       );
     }
+    if (error instanceof SiteAuthoringError && error.code === "site.cancelled" && legalDraftSiteId !== undefined) {
+      throw new SiteAuthoringError("site.cancelled", `${error.message} Run '${loginCommand}' again.`);
+    }
     throw error;
   }
 
@@ -510,6 +519,7 @@ export async function login(invocation) {
       environment,
       {
         apiOrigin,
+        ...(legalDraftSiteId === undefined ? {} : { purpose: claimed.purpose, siteId: claimed.siteId, capabilities: claimed.capabilities, legalDraftPlatformSite: claimed.legalDraftPlatformSite }),
         accountId: claimed.accountId,
         key: claimed.key,
         keyId: claimed.keyId,
@@ -519,7 +529,13 @@ export async function login(invocation) {
       { now },
     );
   } catch (error) {
-    throw unstoredCredentialFailure(error, claimed);
+    throw unstoredCredentialFailure(error, claimed, loginCommand);
+  }
+  if (legalDraftSiteId !== undefined) {
+    onProgress(`Stored legal draft access for site ${legalDraftSiteId} in ${credentialPath}. The credential itself is never displayed.`);
+    onProgress(`Use '${CLI_BINARY_NAME} --legal-drafts pages push' to save drafts; approve and publish them in Taproot.`);
+    onProgress(`Discard this local grant with '${CLI_BINARY_NAME} --legal-drafts ${VERB_LOGOUT}'; revoke it in Account -> Settings -> API keys.`);
+    return successResult(VERB_LOGIN, legalDraftSiteId, { accountId: claimed.accountId, keyId: claimed.keyId, keyPrefix: claimed.keyPrefix, keyExpiresAt: claimed.keyExpiresAt, userCode: authorization.userCode, verificationUrl, credentialPath, legalDrafts: true });
   }
   onProgress(`Stored the sign-in in ${credentialPath}. The credential itself is never displayed.`);
   onProgress(`Run '${CLI_BINARY_NAME} ${VERB_SITES}' to see the sites you can author.`);