@taprootio/site-authoring 0.23.1 → 0.26.0

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,
@@ -32,8 +33,11 @@ import {
   VERB_FORMS_PUSH,
   VERB_FORMS_VALIDATE,
   VERB_HELP,
+  VERB_LINK_BUILD,
   VERB_LOGIN,
   VERB_LOGOUT,
+  VERB_MARKETING_PULL,
+  VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
@@ -87,11 +91,15 @@ import {
   REFERENCE_VERSION,
 } from "./reference-help.js";
 import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
+import { LINK_SOURCES } from "./marketing-contract.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";
 
+const LINK_SOURCE_KEYS = LINK_SOURCES.map((source) => source.key);
+
 /**
  * The verbs the local version gate applies to (TR00703).
  *
@@ -161,8 +169,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 "
@@ -588,6 +597,45 @@ const VERBS = Object.freeze([
       + "that the caller may write forms. "
       + "See 'taproot-site help forms'.",
   },
+  {
+    name: VERB_MARKETING_PULL,
+    surface: SURFACE_STANDARD,
+    // Campaigns and placements ride the content capability, which carries the analytics-view permission that
+    // reads them and the publish permission that changes them (TR01301).
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "pull"],
+    summary: "Write the site's live campaigns and placements to marketing/ and record what was read.",
+    note: "Needs a pulled workspace ('pull' first). It replaces marketing/campaigns.json and marketing/placements.json "
+      + "with the site's records, each with its read-only state and the day its key was first counted from, and records "
+      + "a baseline that 'marketing push' fences against. Archived records are listed and not written. "
+      + "See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_MARKETING_PUSH,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "push"],
+    archiveOption: true,
+    summary: "Create, update and restore the campaigns and placements the marketing files name.",
+    note: "Every file is validated and compared with the site before anything is written. A key is public URL text "
+      + "and never changes, so a new key is a new record; a record the file leaves out is archived only with "
+      + "--archive, and only if this workspace pulled it. A file that names an archived key restores it. Creating or "
+      + "restoring a key queues the silent release that starts counting it; run 'marketing pull' later to see it live. "
+      + "A quota or key refusal is reported as Taproot returns it. See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_LINK_BUILD,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["link", "build"],
+    linkOptions: true,
+    summary: "Print one tracked address for a page, a source, and an optional campaign and placement.",
+    note: "Saves nothing. The medium is set by the source ('reader' is not offered: a published page's own share "
+      + "action sets it). The host is the signed-in site's public address; pass --domain when only a site credential "
+      + "is available. A campaign or placement is checked against marketing/*.json when the workspace has the file, "
+      + "and otherwise against the live site; one that is not live yet is allowed with a note that page views count "
+      + "under the source only until it is. See 'taproot-site help link'.",
+  },
   {
     name: VERB_THEME_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -847,7 +895,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,
@@ -971,6 +1023,17 @@ function verbHelp(verb) {
   const dryRunOption = verb.dryRun
     ? "\n  --dry-run        Read the site and report what a push would change, without writing."
     : "";
+  const archiveOption = verb.archiveOption
+    ? "\n  --archive        Archive a campaign or placement the file leaves out (never done without this)."
+    : "";
+  const linkOptions = verb.linkOptions
+    ? `\n  --path <page>        The page on this site; / or '' for the home page. A query or #fragment you add is kept (required).
+  --source <key>       Where you will post the link: ${LINK_SOURCE_KEYS.join(", ")} (required).
+  --campaign <key>     A campaign key to group links from one push (optional).
+  --placement <key>    A placement key naming the spot the link will appear (optional).
+                       Write --option=<value> for a value that starts with hyphens.
+  --domain <host>      The site's public host; for a site credential with no sign-in to read it from.`
+    : "";
   const planOption = verb.planHash
     ? "\n  --plan <hash>    The planHash 'plan' reported; required."
     : "";
@@ -1038,8 +1101,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.
@@ -1050,7 +1116,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${archiveOption}${linkOptions}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1067,6 +1133,39 @@ function matchVerb(arguments_) {
   return matched;
 }
 
+/** The `link build` options and the invocation field each fills. */
+const LINK_OPTION_FIELDS = Object.freeze({
+  "--path": "linkPath",
+  "--source": "linkSource",
+  "--campaign": "linkCampaign",
+  "--placement": "linkPlacement",
+  "--domain": "linkDomain",
+});
+
+/**
+ * The value after a `link build` option. An option-like value is refused so a missing value never swallows the
+ * next flag; only --path may be empty, which names the home page.
+ */
+function parseLinkOption(rest, index, argument) {
+  // `--campaign=--launch` is the one way to pass a value that starts with `--`, which a valid key may (a key may
+  // begin with a hyphen); a separated value that looks like an option is refused so a missing value never swallows
+  // the next flag.
+  const [name, inline] = argument.includes("=") ? [argument.slice(0, argument.indexOf("=")), argument.slice(argument.indexOf("=") + 1)] : [argument, undefined];
+  const value = inline ?? rest[index + 1];
+  const field = name.slice(2);
+  if (typeof value !== "string" || (inline === undefined && value.startsWith("--")) || (value === "" && name !== "--path")) {
+    throw usageError("cli.option_value", `${name} requires a value.`, { field });
+  }
+  if (Buffer.byteLength(value, "utf8") > LIMITS.configPathBytes || hasAsciiControl(value)) {
+    throw usageError(
+      "cli.option_value",
+      `${name} must be at most ${LIMITS.configPathBytes} bytes with no control characters.`,
+      { field },
+    );
+  }
+  return { name, value, consumed: inline === undefined ? 1 : 0 };
+}
+
 function usageError(code, message, options = {}) {
   return new SiteAuthoringError(code, message, { ...options, exitCode: 2 });
 }
@@ -1116,6 +1215,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "fixture"
       || topic === "redirects"
       || topic === "forms"
+      || topic === "marketing"
+      || topic === "link"
       || topic === "walkthrough"
       || topic === "delivery"
       || topic === "import"
@@ -1187,6 +1288,8 @@ function referenceResult(parsed) {
     case "nav":
     case "redirects":
     case "forms":
+    case "marketing":
+    case "link":
     case "media":
     case "preview":
     case "fixture":
@@ -1374,11 +1477,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 +1501,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",
@@ -1431,6 +1544,8 @@ function parseArguments(arguments_) {
   let fromSite = false;
   let keyName;
   let planHash;
+  let archive = false;
+  const linkValues = {};
   let metaTitle;
   let metaDescription;
   let metaAuthor;
@@ -1439,6 +1554,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;
@@ -1528,6 +1648,21 @@ function parseArguments(arguments_) {
       index += 1;
       continue;
     }
+    if (verb.archiveOption && argument === "--archive") {
+      if (archive) throw usageError("cli.duplicate_option", "--archive may be supplied only once.");
+      archive = true;
+      continue;
+    }
+    if (verb.linkOptions && Object.hasOwn(LINK_OPTION_FIELDS, argument.split("=")[0])) {
+      const { name, value, consumed } = parseLinkOption(rest, index, argument);
+      const field = LINK_OPTION_FIELDS[name];
+      if (linkValues[field] !== undefined) {
+        throw usageError("cli.duplicate_option", `${name} may be supplied only once.`, { field: name.slice(2) });
+      }
+      linkValues[field] = value;
+      index += consumed;
+      continue;
+    }
     if (verb.dryRun && argument === "--dry-run") {
       if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
       dryRun = true;
@@ -1718,6 +1853,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 +1888,7 @@ function parseArguments(arguments_) {
     surface: verb.surface,
     surfaceCapabilities: verb.surfaceCapabilities,
     configPath,
+    legalDrafts,
     quiet,
     deployTarget,
     allowFailedPreview,
@@ -1767,6 +1906,8 @@ function parseArguments(arguments_) {
     ...(themeContext === undefined ? {} : { themeContext }),
     ...(fromSite ? { fromSite } : {}),
     ...(planHash === undefined ? {} : { planHash }),
+    ...(archive ? { archive } : {}),
+    ...linkValues,
     ...(metaTitle === undefined ? {} : { metaTitle }),
     ...(metaDescription === undefined ? {} : { metaDescription }),
     ...(metaAuthor === undefined ? {} : { metaAuthor }),
@@ -1850,6 +1991,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 }),
@@ -1863,6 +2005,8 @@ export async function runCli({
       ...(parsed.themeContext === undefined ? {} : { themeContext: parsed.themeContext }),
       ...(parsed.fromSite === undefined ? {} : { fromSite: parsed.fromSite }),
       ...(parsed.planHash === undefined ? {} : { planHash: parsed.planHash }),
+      ...(parsed.archive ? { archive: true } : {}),
+      ...Object.fromEntries(Object.values(LINK_OPTION_FIELDS).filter((field) => parsed[field] !== undefined).map((field) => [field, parsed[field]])),
       // Only when given, like the other optional fields, so each verb keeps its default (TR00925).
       ...(parsed.deliveryUrl === undefined ? {} : { deliveryUrl: parsed.deliveryUrl }),
       ...(parsed.propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds: parsed.propagationWaitSeconds }),
@@ -1905,6 +2049,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;
 
@@ -94,6 +94,9 @@ export const VERB_REDIRECTS_PUSH = "redirects push";
 export const VERB_FORMS_PULL = "forms pull";
 export const VERB_FORMS_PUSH = "forms push";
 export const VERB_FORMS_VALIDATE = "forms validate";
+export const VERB_MARKETING_PULL = "marketing pull";
+export const VERB_MARKETING_PUSH = "marketing push";
+export const VERB_LINK_BUILD = "link build";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_THEME_RESOLVE = "theme resolve";
 export const VERB_FOOTER_PUSH = "footer push";

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 };