@taprootio/site-authoring 0.23.1 → 0.24.0

package/README.md

@@ -246,7 +246,9 @@ answers Not found like any site the account can no longer author, and the
 CLI adds a hint to run `use` again because the recording says the site was
 authorable before.
 
-`logout` discards the stored sign-in locally and revokes nothing; the
+`logout` discards only the stored account sign-in locally. Separately stored
+site legal draft grants remain; select each site and use
+`taproot-site --legal-drafts logout` to discard its grant. Logout revokes nothing; the
 credential stays valid until an owner revokes it under Account → Settings →
 API keys. The secret itself is never displayed, logged, or placed in any
 result: credentials are named by id and display prefix only.
@@ -396,6 +398,12 @@ the site's own document is kept as internal state under
 `.taproot-site-state/`, which is never a page source and never pushed. A page
 edited on the site since the last pull is a `pages.pull_conflict` refusal
 before anything under `pages/` changes, with both recovery paths named.
+Pull before creating a new JSON source. Once a new page is declared with a
+file, title or path but has no server page ID, save it with `pages push` before
+pulling again, or back up both the source and its manifest entry and move them
+out of the workspace. Pull refuses these pending entries rather than dropping
+their metadata. It also refuses an untracked legal or unreadable JSON source
+that would be replaced by a new remote page.
 
 Pages are not only free-form. A source chooses its template with `template:` in
 its front matter — `article`, `recipe`, `album` or `place-review`; free-form is
@@ -406,10 +414,25 @@ its original publication date) and `coverImage`, which the site requires to be a
 image the page itself uses (place it in the body too; `pages.cover_image_unused`). A page's template is fixed when
 it is created: a source for another template is refused with
 `pages.template_immutable`. `taproot-site help page <type>` gives each
-template's fields and one worked example. The structured legal page (a versioned
-privacy policy or terms with an effective date) is created and published in the
-app; the CLI records it as a metadata-only page, and `taproot-site help page
-legal` says what a site-authoring key can and cannot do with one.
+template's fields and one worked example. Pull includes structured legal pages and their
+bodies as `.pm.json` with the usual Content read permission. Create and update
+legal drafts in JSON only; Markdown conversion is not supported. The document
+key, role and path are immutable, and publication assigns the version, effective
+date and superseded version. See `taproot-site help page legal` for the fields.
+
+Select a standard site and run `taproot-site login --legal-drafts`; the owner
+reviews and approves a site-specific grant in the app, valid for at most 24
+hours. Ordinary account login stays separate. Use the global option before the
+verb, for example `taproot-site --legal-drafts pages push`,
+`taproot-site --legal-drafts plan`, or `taproot-site --legal-drafts apply`.
+It also selects the grant for `pull`, although ordinary Content access can read
+legal pages. Changed or new legal drafts require this grant before writes begin;
+unchanged legal pages do not block ordinary work. `TAPROOT_SITE_KEY` still takes
+precedence, and legal writes with an unclassified environment override are
+refused: unset it and use the explicit site login. Saving a draft does not
+approve it. Legal approval, deletion and deployment remain in the app. A bare
+`taproot-site approve` skips legal drafts and stages other tracked drafts; explicitly
+naming a legal page refuses the whole selection.
 A privacy policy or other legal page that names Taproot should link the first
 mention to <https://www.taproot.io>; `help page free-form` and `help page legal`
 give a sample sentence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/api.js

@@ -25,6 +25,7 @@ import {
 // must equal acceptance on save — a prefix admitted here but refused there
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
+import { CAPABILITY_LEGAL_DRAFTS, SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 import { normalizeAuthorListing, parseAuthorReference } from "./authors-contract.js";
 import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
@@ -2238,7 +2239,7 @@ function requireBoundedSeconds(value, minimum, maximum, field) {
  * caller from the already-allowlisted API origin, so a compromised or
  * misconfigured server cannot steer the owner somewhere else to approve.
  */
-export async function startCliAuthorization(client, { keyName }, requestOptions = {}) {
+export async function startCliAuthorization(client, { keyName, legalDraftSiteId }, requestOptions = {}) {
   const response = requireObject(
     // No site: TR00645 made the account-level sign-in the front door, so the
     // CLI no longer has to know a site id before it can authorize at all.
@@ -2248,7 +2249,7 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
     await client.request(CLI_AUTHORIZATION_PATH, {
       ...requestOptions,
       method: "POST",
-      body: { keyName, cliVersion: CLI_VERSION },
+      body: { keyName, cliVersion: CLI_VERSION, ...(legalDraftSiteId === undefined ? {} : { legalDraftSiteId }) },
     }),
     "login.start_contract",
     "CLI authorization",
@@ -2263,9 +2264,13 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
       field: "userCode",
     });
   }
+  if (legalDraftSiteId !== undefined && response.legalDraftSiteId !== legalDraftSiteId) {
+    throw new SiteAuthoringError("login.start_contract", "Taproot did not confirm the selected legal draft site. Update the server and try again.", { field: "legalDraftSiteId" });
+  }
   return {
     deviceCode: response.deviceCode,
     userCode: response.userCode,
+    ...(legalDraftSiteId === undefined ? {} : { legalDraftSiteId }),
     expiresInSeconds: requireBoundedSeconds(
       response.expiresInSeconds,
       1,
@@ -2387,7 +2392,7 @@ export async function exchangeSiteAuthoringToken(client, { siteId, capabilities
   };
 }
 
-function normalizeIssuedCredential(response) {
+function normalizeIssuedCredential(response, legalDraftSiteId) {
   if (!isWellFormedCredential(response.rawKey)) {
     // The value is never quoted, here or anywhere: it is the secret.
     throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an invalid issued key.", {
@@ -2411,7 +2416,24 @@ function normalizeIssuedCredential(response) {
       || response.keyExpiresAt === ""
     ? undefined
     : requireCanonicalTimestamp(response.keyExpiresAt, "login.claim_unusable", "keyExpiresAt").value;
+  if (legalDraftSiteId !== undefined) {
+    const capabilities = response.capabilities;
+    if (response.legalDraftSiteId !== legalDraftSiteId || !Array.isArray(capabilities)
+      || capabilities.length !== SITE_AUTHORING_CAPABILITIES.length + 1
+      || new Set(capabilities).size !== capabilities.length
+      || ![...SITE_AUTHORING_CAPABILITIES, CAPABILITY_LEGAL_DRAFTS].every((value) => capabilities.includes(value))
+      || (response.legalDraftPlatformSite !== undefined && typeof response.legalDraftPlatformSite !== "boolean")
+      || keyExpiresAt === undefined) {
+      throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an invalid legal draft grant.");
+    }
+  } else if (response.legalDraftSiteId || (Array.isArray(response.capabilities) && response.capabilities.length > 0)) {
+    throw new SiteAuthoringError("login.claim_unusable", "Taproot returned an unexpected site grant.");
+  }
   return {
+    ...(legalDraftSiteId === undefined ? {} : {
+      purpose: "legal-drafts", siteId: legalDraftSiteId, capabilities: [...response.capabilities],
+      legalDraftPlatformSite: response.legalDraftPlatformSite ?? false,
+    }),
     key: response.rawKey,
     keyId,
     keyPrefix: response.keyPrefix,
@@ -2427,7 +2449,7 @@ function normalizeIssuedCredential(response) {
  * `..._CONSUMED`, and the caller reports the orphaned credential honestly
  * rather than hiding it behind a network error.
  */
-export async function claimCliAuthorization(client, deviceCode, requestOptions = {}) {
+export async function claimCliAuthorization(client, deviceCode, requestOptions = {}, { legalDraftSiteId } = {}) {
   // Every `login.claim_contract` raised here — a non-object envelope, an
   // absent status, a status string this vocabulary does not know — is an
   // answer this client could not read, not proof the claim was refused. A
@@ -2451,7 +2473,7 @@ export async function claimCliAuthorization(client, deviceCode, requestOptions =
     );
   }
   if (status === CLI_AUTHORIZATION_CLAIM_STATUS_ISSUED) {
-    return { status, credential: normalizeIssuedCredential(response) };
+    return { status, credential: normalizeIssuedCredential(response, legalDraftSiteId) };
   }
   if (status === CLI_AUTHORIZATION_CLAIM_STATUS_CONSUMED) {
     // A consumed answer names the credential an earlier claim minted, so the

package/src/capabilities.js

@@ -14,6 +14,7 @@
 export const CAPABILITY_CONTENT = "delegation.content";
 export const CAPABILITY_DESIGN = "delegation.design";
 export const CAPABILITY_DEPLOYMENTS = "delegation.deployments";
+export const CAPABILITY_LEGAL_DRAFTS = "delegation.legal-drafts";
 
 export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
   CAPABILITY_CONTENT,

package/src/changelog.json

@@ -1,5 +1,19 @@
 {
   "entries": [
+    {
+      "version": "0.24.0",
+      "note": "Site-specific consent enables legal draft authoring through JSON; legal approval and publication remain in the app.",
+      "behavior": [
+        "Select a standard site, then run login --legal-drafts and approve the pinned site grant in the app. It lasts at most 24 hours and is separate from ordinary account login. Use the global --legal-drafts option before pull, pages push, plan or apply to select that grant.",
+        "Pull includes legal bodies as .pm.json with ordinary Content read access. Legal create and update accept JSON only; document key, role and path are immutable, and version, effective date and superseded version are assigned by publication. A changed or new legal draft needs the explicit grant before writes begin.",
+        "TAPROOT_SITE_KEY takes precedence; legal writes with an unclassified environment key are refused. Legal approval, deletion and deployment remain app-only. Saving a draft does not approve it.",
+        "The help reference version is 42."
+      ],
+      "help": [
+        "page",
+        "pages"
+      ]
+    },
     {
       "version": "0.23.1",
       "note": "Image uploads support Taproot’s single-use upload gateway and send an operation key with each upload request.",

package/src/cli.js

@@ -14,6 +14,7 @@ import {
   LOGIN_KEY_NAME_MAXIMUM,
   PLAN_HASH,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_CREDENTIAL_REJECTED,
   RESULT_SCHEMA_VERSION,
   STAGING_REVIEW_SESSION_NOTE,
   SURFACE_DOCS_PRESENTATION,
@@ -88,6 +89,7 @@ import {
 } from "./reference-help.js";
 import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
 import { assertCliCurrent } from "./session.js";
+import { ApiError } from "./transport.js";
 import { formatThemeResolve } from "./theme-resolve.js";
 import { MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS } from "./theme-validation.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
@@ -161,8 +163,9 @@ const VERBS = Object.freeze([
     note: "Starts a device-authorization exchange, prints the approval URL and an eight-character code, and waits for "
       + "an owner to enter that code and approve in a browser they are already signed in to. Typing the code — rather "
       + "than following a prefilled link — is what proves the approver can see this terminal. "
-      + "It needs no site and no taproot-site.json: what it authorizes is the account, so it works in any directory "
+      + "Ordinary login needs no site and no taproot-site.json: what it authorizes is the account, so it works in any directory "
       + "immediately after install. Choose a site afterwards with 'sites' and 'use'. "
+      + "With --legal-drafts it requests a separate 24-hour grant for the selected standard site; use the global --legal-drafts option before site commands to select that grant. "
       + "The approval URL is composed from the reviewed API origin and is never taken from a response. "
       + "The issued sign-in is written to credentials.json under $XDG_CONFIG_HOME/taproot-site/ (falling back to "
       + "~/.config/taproot-site/), directory 0700 and file 0600, one per API origin, replacing any sign-in already "
@@ -847,7 +850,11 @@ The site credential is taken from ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} when it is
 set; otherwise it is minted for each run by exchanging the account sign-in that
 login stores outside the repository. There is no flag for either. The sign-in
 authorizes nothing on any site: it lists sites and buys short-lived site
-credentials, and it expires 24 hours after it is issued.
+credentials, and it expires 24 hours after it is issued. To edit legal drafts,
+run 'login --legal-drafts' for the selected standard site, then put
+'--legal-drafts' before pull, pages push, plan, or apply. This selects a
+separate site grant that expires within 24 hours. Legal approval and publishing
+remain in the app.
 
 Verbs write one JSON result to stdout and human progress to stderr. validate,
 help, whoami, and env are offline and read-only. login, logout, sites, use,
@@ -1038,8 +1045,11 @@ function verbHelp(verb) {
     // contradicts the note two paragraphs below it is worse than either alone.
     ? `Options:
   --config <path>  Place before the verb; bypass parent discovery.
+  --legal-drafts   Authorize a separate, short-lived grant for the selected standard site.
   --help           Show this help.
   --version        Show the package version.`
+    : ["logout", "whoami", "pull", "pages push", "plan", "apply"].includes(verb.name)
+    ? COMMON_OPTIONS.replace("  --quiet", "  --legal-drafts   Use the selected site's legal draft grant (before the verb).\n  --quiet")
     : COMMON_OPTIONS;
   const deliveryTargetOption = verb.deliveryOptions
     ? `\n  --staging        Check the staging target.
@@ -1374,11 +1384,20 @@ function parseArguments(arguments_) {
   if (arguments_.length === 1 && arguments_[0] === "--version") return { mode: "version" };
 
   let configPath;
-  let commandArguments = arguments_;
-  if (arguments_[0] === "--config") {
-    configPath = parseConfigOption(arguments_, 0);
-    commandArguments = arguments_.slice(2);
+  let legalDrafts = false;
+  let globalIndex = 0;
+  while (arguments_[globalIndex] === "--config" || arguments_[globalIndex] === "--legal-drafts") {
+    if (arguments_[globalIndex] === "--config") {
+      if (configPath !== undefined) throw usageError("cli.duplicate_option", "--config may be supplied only once.");
+      configPath = parseConfigOption(arguments_, globalIndex);
+      globalIndex += 2;
+    } else {
+      if (legalDrafts) throw usageError("cli.duplicate_option", "--legal-drafts may be supplied only once.");
+      legalDrafts = true;
+      globalIndex += 1;
+    }
   }
+  const commandArguments = arguments_.slice(globalIndex);
 
   const verb = matchVerb(commandArguments);
   if (!verb) {
@@ -1389,6 +1408,7 @@ function parseArguments(arguments_) {
   }
   const rest = commandArguments.slice(verb.tokens.length);
   if (verb.name === VERB_HELP) {
+    if (legalDrafts) throw usageError("cli.legal_option", "--legal-drafts applies only to site authoring commands.");
     if (configPath !== undefined) {
       throw usageError("cli.config_option", "--config applies only to operational verbs.", {
         field: "configPath",
@@ -1439,6 +1459,11 @@ function parseArguments(arguments_) {
   const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
+    if (verb.name === VERB_LOGIN && argument === "--legal-drafts") {
+      if (legalDrafts) throw usageError("cli.duplicate_option", "--legal-drafts may be supplied only once.");
+      legalDrafts = true;
+      continue;
+    }
     if (verb.name === VERB_VALIDATE && argument === "--init") {
       if (init) throw usageError("cli.duplicate_option", "--init may be supplied only once.");
       init = true;
@@ -1718,6 +1743,9 @@ function parseArguments(arguments_) {
       field: "planHash",
     });
   }
+  if (legalDrafts && !["login", "logout", "whoami", "pull", "pages push", "plan", "apply"].includes(verb.name)) {
+    throw usageError("cli.legal_option", "--legal-drafts applies to login, logout, whoami, pull, pages push, plan, or apply.");
+  }
   if (quiet && verb.name === VERB_LOGIN) {
     // The approval URL and user code reach the operator only as progress
     // lines, and the JSON result is serialized only after polling ends — so a
@@ -1750,6 +1778,7 @@ function parseArguments(arguments_) {
     surface: verb.surface,
     surfaceCapabilities: verb.surfaceCapabilities,
     configPath,
+    legalDrafts,
     quiet,
     deployTarget,
     allowFailedPreview,
@@ -1850,6 +1879,7 @@ export async function runCli({
       cwd,
       environment,
       configPath: parsed.configPath,
+      legalDrafts: parsed.legalDrafts,
       deployTarget: parsed.deployTarget,
       allowFailedPreview: parsed.allowFailedPreview,
       ...(parsed.handoff === undefined ? {} : { handoff: parsed.handoff }),
@@ -1905,6 +1935,10 @@ export async function runCli({
     return 0;
   } catch (unknownError) {
     progress?.stop();
+    if (parsed?.legalDrafts && unknownError instanceof ApiError
+      && unknownError.refusalKind() === REFUSAL_CREDENTIAL_REJECTED) {
+      stderr.write(`The legal draft grant was rejected. Run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' again.\n`);
+    }
     const error = asSiteAuthoringError(unknownError);
     if (completedPreviewRecovery) error.withPreviewRecovery(completedPreviewRecovery);
     const result = failureResult(error);

package/src/constants.js

@@ -49,7 +49,7 @@ export const CREDENTIAL_FILE_NAME = "credentials.json";
 // store is refused with a message naming `login` rather than migrated —
 // the CLI is unpublished, so the only v1 stores are in this repository, and
 // a migration path would be code that exists for nobody.
-export const CREDENTIAL_STORE_VERSION = 2;
+export const CREDENTIAL_STORE_VERSION = 3;
 export const CREDENTIAL_DIRECTORY_MODE = 0o700;
 export const CREDENTIAL_FILE_MODE = 0o600;
 

package/src/credentials.js

@@ -5,7 +5,7 @@ import path from "node:path";
 
 import { atomicWriteFile } from "./atomic-file.js";
 import { readBoundedFile } from "./bounded-file.js";
-import { SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
+import { CAPABILITY_LEGAL_DRAFTS, SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
 import { parseCliVersion } from "./cli-release.js";
 
 import {
@@ -172,8 +172,30 @@ function normalizeEntry(entry) {
           || parseCliVersion(entry.lastExchange.latestCliVersion) !== undefined)),
     "A stored credential record has an invalid lastExchange.",
   );
+  const legal = entry.purpose === "legal-drafts";
+  const legalExpiry = legal && typeof entry.keyExpiresAt === "string" ? Date.parse(entry.keyExpiresAt) : Number.NaN;
+  requireStoreShape(entry.purpose === undefined || legal, "A stored credential record has an invalid purpose.");
+  requireStoreShape(legal
+    ? isCanonicalUuid(entry.siteId)
+      && typeof entry.legalDraftPlatformSite === "boolean"
+      && entry.keyExpiresAt !== undefined
+      && Number.isFinite(legalExpiry)
+      && new Date(legalExpiry).toISOString().slice(0, 19) === entry.keyExpiresAt.slice(0, 19)
+      && Array.isArray(entry.capabilities)
+      && entry.capabilities.length === SITE_AUTHORING_CAPABILITIES.length + 1
+      && new Set(entry.capabilities).size === entry.capabilities.length
+      && [...SITE_AUTHORING_CAPABILITIES, CAPABILITY_LEGAL_DRAFTS].every((value) => entry.capabilities.includes(value))
+      && entry.lastExchange === undefined
+    : entry.siteId === undefined && entry.capabilities === undefined && entry.legalDraftPlatformSite === undefined,
+  "A stored credential record has invalid scope.");
   return Object.freeze({
     apiOrigin: entry.apiOrigin,
+    ...(legal ? {
+      purpose: entry.purpose,
+      siteId: entry.siteId,
+      capabilities: Object.freeze([...entry.capabilities]),
+      legalDraftPlatformSite: entry.legalDraftPlatformSite,
+    } : {}),
     accountId: entry.accountId,
     key: entry.key,
     keyId: entry.keyId,
@@ -262,14 +284,22 @@ export async function readCredentialStore(environment = {}) {
       parsed !== null && typeof parsed === "object" && !Array.isArray(parsed),
       "The stored credential file is not a JSON object.",
     );
-    if (parsed.schemaVersion !== CREDENTIAL_STORE_VERSION) {
+    if (parsed.schemaVersion !== CREDENTIAL_STORE_VERSION && parsed.schemaVersion !== 2) {
       throw new SiteAuthoringError(
         "credentials.unsupported_version",
         `The stored credential file must declare schemaVersion ${CREDENTIAL_STORE_VERSION}.`,
       );
     }
     requireStoreShape(Array.isArray(parsed.credentials), "The stored credential file has no credentials array.");
-    return { path: filePath, credentials: parsed.credentials.map(normalizeEntry) };
+    if (parsed.schemaVersion === 2) {
+      requireStoreShape(parsed.credentials.every((entry) => entry && entry.purpose === undefined
+        && entry.siteId === undefined && entry.capabilities === undefined && entry.legalDraftPlatformSite === undefined),
+      "An older credential store has an invalid scope.");
+    }
+    const credentials = parsed.credentials.map(normalizeEntry);
+    const identities = credentials.map((entry) => JSON.stringify([entry.apiOrigin, entry.purpose ?? "account", entry.siteId ?? ""]));
+    requireStoreShape(new Set(identities).size === identities.length, "The stored credential file has duplicate records.");
+    return { path: filePath, credentials };
   } catch (error) {
     throw namedStoreFailure(error, filePath);
   }
@@ -283,13 +313,18 @@ export async function readCredentialStore(environment = {}) {
  * site; the sign-in credential authorizes an account, and an operator has one
  * of those per Taproot they use.
  */
-export function selectCredential(credentials, apiOrigin) {
-  return credentials.find((entry) => entry.apiOrigin === apiOrigin);
+export function selectCredential(credentials, apiOrigin, { siteId } = {}) {
+  return credentials.find((entry) => entry.apiOrigin === apiOrigin
+    && (siteId === undefined ? entry.purpose === undefined : entry.purpose === "legal-drafts" && entry.siteId === siteId));
+}
+
+function sameCredentialScope(left, right) {
+  return left.apiOrigin === right.apiOrigin && left.purpose === right.purpose && left.siteId === right.siteId;
 }
 
-export async function findCredential(environment, apiOrigin) {
+export async function findCredential(environment, apiOrigin, scope = {}) {
   const store = await readCredentialStore(environment);
-  return { path: store.path, credential: selectCredential(store.credentials, apiOrigin) };
+  return { path: store.path, credential: selectCredential(store.credentials, apiOrigin, scope) };
 }
 
 /**
@@ -486,7 +521,7 @@ async function withStoreLock(filePath, action, { sleep = defaultLockSleep } = {}
  * someone with a nearly full store to log out of a Taproot they no longer use;
  * under-refusing means orphaning a credential. The asymmetry picks the side.
  */
-export async function assertCredentialCapacity(environment, apiOrigin) {
+export async function assertCredentialCapacity(environment, apiOrigin, { siteId } = {}) {
   const store = await readCredentialStore(environment);
   const projected = normalizeEntry({
     apiOrigin,
@@ -494,7 +529,7 @@ export async function assertCredentialCapacity(environment, apiOrigin) {
     key: "k".repeat(MAXIMUM_TOKEN_LENGTH),
     keyId: PROJECTION_UUID,
     keyPrefix: "p".repeat(PROJECTION_KEY_PREFIX_LENGTH),
-    keyExpiresAt: PROJECTION_TIMESTAMP,
+    keyExpiresAt: siteId === undefined ? PROJECTION_TIMESTAMP : "2000-01-02T00:00:00.000Z",
     lastExchange: {
       siteId: PROJECTION_UUID,
       capabilities: [...SITE_AUTHORING_CAPABILITIES],
@@ -505,9 +540,14 @@ export async function assertCredentialCapacity(environment, apiOrigin) {
       externalWritesEnabled: false,
       latestCliVersion: PROJECTION_LATEST_CLI_VERSION,
     },
+    ...(siteId === undefined ? {} : {
+      purpose: "legal-drafts", siteId, legalDraftPlatformSite: false,
+      capabilities: [...SITE_AUTHORING_CAPABILITIES, CAPABILITY_LEGAL_DRAFTS],
+      lastExchange: undefined,
+    }),
     createdAt: PROJECTION_TIMESTAMP,
   });
-  const others = store.credentials.filter((entry) => entry.apiOrigin !== apiOrigin);
+  const others = store.credentials.filter((entry) => !sameCredentialScope(entry, projected));
   requireStoreFits(serializeStore([...others, projected]));
   return store.path;
 }
@@ -525,7 +565,7 @@ export async function saveCredential(environment, credential, { now = Date.now,
   const filePath = credentialStorePath(environment);
   return withStoreLock(filePath, async () => {
     const store = await readCredentialStore(environment);
-    const others = store.credentials.filter((entry) => entry.apiOrigin !== record.apiOrigin);
+    const others = store.credentials.filter((entry) => !sameCredentialScope(entry, record));
     const ordered = [...others, record].sort((left, right) => left.apiOrigin.localeCompare(right.apiOrigin));
     await writeCredentialStore(store.path, ordered);
     return store.path;
@@ -554,7 +594,7 @@ export async function updateCredentialMetadata(environment, apiOrigin, keyId, me
     if (current === undefined || current.keyId !== keyId) return false;
 
     const updated = normalizeEntry({ ...current, ...metadata });
-    const others = store.credentials.filter((entry) => entry.apiOrigin !== apiOrigin);
+    const others = store.credentials.filter((entry) => !sameCredentialScope(entry, current));
     const ordered = [...others, updated].sort((left, right) => left.apiOrigin.localeCompare(right.apiOrigin));
     await writeCredentialStore(store.path, ordered);
     return true;
@@ -567,11 +607,12 @@ export async function updateCredentialMetadata(environment, apiOrigin, keyId, me
  * asked for is the state they end up in. The read-modify-write runs under the
  * same store lock the save takes.
  */
-export async function removeCredential(environment, apiOrigin, { sleep } = {}) {
+export async function removeCredential(environment, apiOrigin, { sleep, siteId } = {}) {
   const filePath = credentialStorePath(environment);
   return withStoreLock(filePath, async () => {
     const store = await readCredentialStore(environment);
-    const remaining = store.credentials.filter((entry) => entry.apiOrigin !== apiOrigin);
+    const current = selectCredential(store.credentials, apiOrigin, { siteId });
+    const remaining = store.credentials.filter((entry) => current === undefined || !sameCredentialScope(entry, current));
     if (remaining.length === store.credentials.length) return { path: store.path, removed: false };
     await writeCredentialStore(store.path, remaining);
     return { path: store.path, removed: true };

package/src/reference-help.js

@@ -88,7 +88,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 41;
+export const REFERENCE_VERSION = 42;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -389,7 +389,7 @@ export function getDesignBlueprint(type) {
   return DESIGN_BLUEPRINTS.find((blueprint) => blueprint.type === type);
 }
 export const REFERENCE_TOPICS = Object.freeze([
-  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List page types: free-form, article, recipe, album, place-review, generated, and the read-only legal page." }),
+  Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List page types: free-form, article, recipe, album, place-review, generated, and legal draft pages." }),
   Object.freeze({
     name: "page",
     usage: `${CLI_BINARY_NAME} help page <page-type>`,
@@ -1728,7 +1728,7 @@ const FREE_FORM_REFERENCE = Object.freeze({
     legalAndPrivacyPages: Object.freeze({
       ...LEGAL_PLATFORM_LINK_GUIDANCE,
       choosing:
-        `A policy that needs a version and an effective date is a legal page, which the CLI cannot author: see '${CLI_BINARY_NAME} help page legal'.`,
+        `A policy that needs a version and an effective date is a legal page; see '${CLI_BINARY_NAME} help page legal' for draft editing and app approval.`,
     }),
     componentNode: Object.freeze({
       type: "componentBlock",

package/src/session.js

@@ -11,6 +11,7 @@ import {
   ROLLOUT_REFUSAL_FIELD,
   VERB_LOGIN,
   VERB_USE,
+  SURFACE_STANDARD,
 } from "./constants.js";
 import { loadSiteConfig } from "./config.js";
 import { cliOutdatedError, compareCliVersions, isBehindLatest } from "./cli-release.js";
@@ -219,6 +220,7 @@ export async function resolveApiBaseUrl(environment) {
 }
 
 export async function openSession(invocation = {}) {
+  if (invocation.resolvedSession !== undefined) return invocation.resolvedSession;
   const environment = invocation.environment ?? process.env;
   const onProgress = progressSink(invocation);
   const now = invocation.now ?? Date.now;
@@ -231,6 +233,9 @@ export async function openSession(invocation = {}) {
   // at all.
   const environmentToken = environment?.[PUBLISH_KEY_ENVIRONMENT_VARIABLE];
   if (environmentToken !== undefined) {
+    if (invocation.legalDrafts) {
+      throw new SiteAuthoringError("auth.legal_environment_override", `Unset ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} and run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' to use the selected site's legal draft grant.`);
+    }
     const apiBaseUrl = await resolveApiBaseUrl(environment);
     const config = await loadConfig(invocation);
     if (!config.siteId) throw siteMissingError();
@@ -244,6 +249,7 @@ export async function openSession(invocation = {}) {
     return {
       config,
       client,
+      legalDrafts: false,
       siteId: config.siteId,
       surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
@@ -253,6 +259,32 @@ export async function openSession(invocation = {}) {
     };
   }
 
+  if (invocation.legalDrafts) {
+    const apiBaseUrl = await resolveApiBaseUrl(environment);
+    const config = await loadConfig(invocation);
+    if (!config.siteId) throw siteMissingError();
+    if (config.authoringSurface !== undefined && config.authoringSurface !== SURFACE_STANDARD) {
+      throw new SiteAuthoringError("auth.legal_site_required", "Legal draft access requires a standard site.");
+    }
+    requireRecordedSurface(invocation, config);
+    const store = await readCredentialStore(environment);
+    const credential = selectCredential(store.credentials, credentialApiOrigin(apiBaseUrl), { siteId: config.siteId });
+    if (credential === undefined) {
+      throw new SiteAuthoringError("auth.legal_grant_missing", `Legal draft access is missing. Run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' again.`);
+    }
+    if (Date.parse(credential.keyExpiresAt) <= now()) {
+      onProgress(
+        `The stored legal draft grant expired at ${credential.keyExpiresAt}. `
+          + `If Taproot refuses it, run '${CLI_BINARY_NAME} ${VERB_LOGIN} --legal-drafts' again.`,
+      );
+    }
+    return {
+      config, client: invocation.client ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, credential.key)),
+      legalDrafts: true, siteId: config.siteId, surface: config.authoringSurface,
+      platform: UNKNOWN_PLATFORM, release: UNKNOWN_CLI_RELEASE, now, onProgress,
+    };
+  }
+
   let config;
   let apiBaseUrl;
   const signIn = await requireSignIn(environment, async () => {
@@ -280,6 +312,7 @@ export async function openSession(invocation = {}) {
     return {
       config,
       client: invocation.client,
+      legalDrafts: false,
       siteId: config.siteId,
       surface: config.authoringSurface,
       platform: UNKNOWN_PLATFORM,
@@ -403,6 +436,7 @@ export async function openSession(invocation = {}) {
     config,
     client,
     siteId: config.siteId,
+    legalDrafts: false,
     surface: exchanged.authoringSurface,
     exchanged: {
       keyId: exchanged.keyId,