@sakupa/mcp 0.7.41 → 0.7.42

package/dist/index.js

@@ -3,6 +3,7 @@ var SERVICE_DOMAIN = "sakupa.com";
 var DEFAULT_API_BASE_URL = "https://api.sakupa.com";
 var FREE_SITE_URL_SUFFIX = `.${SERVICE_DOMAIN}`;
 var TEST_ACCESS_HEADER = "x-sakupa-test-token";
+var CREDENTIAL_ROTATION_RECOMMEND_AFTER_SECONDS = 7 * 24 * 60 * 60;
 var FREE_SITE_TTL_HOURS = 24;
 var FREE_SITE_MAX_TOTAL_BYTES = 10 * 1024 * 1024;
 var FREE_ACTIVE_SITES_PER_IP = 3;
@@ -124,7 +125,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.41";
+var SAKUPA_MCP_VERSION = "0.7.42";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -678,6 +679,20 @@ var HttpApiClient = class {
       credential
     });
   }
+  async getCredentialStatus(siteId, credential) {
+    return this.call(
+      "GET",
+      `/v1/sites/${encodeURIComponent(siteId)}/credential`,
+      { credential }
+    );
+  }
+  async rotateCredential(siteId, credential, req) {
+    return this.call(
+      "POST",
+      `/v1/sites/${encodeURIComponent(siteId)}/credential/rotate`,
+      { credential, body: req }
+    );
+  }
   async getSiteArchive(siteId, credential) {
     return this.call(
       "GET",
@@ -786,10 +801,12 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  renameSync,
   rmdirSync,
   rmSync,
   writeFileSync
 } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 var SITE_DIR = ".sakupa";
 var SITE_FILE = "site.json";
@@ -900,12 +917,22 @@ function writeSiteFile(projectDir, file, opts = {}) {
   const dir = join(projectDir, SITE_DIR);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, SITE_FILE);
-  writeFileSync(path, `${JSON.stringify(file, null, 2)}
-`, "utf8");
+  const temporary = join(dir, `.site-${randomUUID()}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(file, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
   try {
-    chmodSync(path, 384);
+    chmodSync(temporary, 384);
   } catch {
   }
+  try {
+    renameSync(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
 }
 function deleteSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
@@ -1379,7 +1406,7 @@ import { fileURLToPath } from "node:url";
 import { resolve as resolve3 } from "node:path";
 
 // src/project-root.ts
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   chmodSync as chmodSync2,
   existsSync as existsSync2,
@@ -1387,7 +1414,7 @@ import {
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync2,
   realpathSync,
-  renameSync,
+  renameSync as renameSync2,
   rmdirSync as rmdirSync2,
   statSync,
   unlinkSync,
@@ -1470,7 +1497,7 @@ function initializeProject(projectDir) {
   }
   const marker = {
     schemaVersion: PROJECT_SCHEMA_VERSION,
-    projectId: randomUUID(),
+    projectId: randomUUID2(),
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   writeMarkerAtomically(canonical, marker);
@@ -1582,14 +1609,14 @@ function writeMarkerAtomically(projectDir, marker) {
   const dir = join3(projectDir, SAKUPA_DIR);
   mkdirSync2(dir, { recursive: true, mode: 448 });
   const path = projectMarkerPath(projectDir);
-  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const temporary = `${path}.${process.pid}.${randomUUID2()}.tmp`;
   try {
     writeFileSync2(temporary, `${JSON.stringify(marker, null, 2)}
 `, {
       encoding: "utf8",
       mode: 384
     });
-    renameSync(temporary, path);
+    renameSync2(temporary, path);
     try {
       chmodSync2(path, 384);
     } catch {
@@ -1899,7 +1926,7 @@ function structuredToolResult(envelope) {
 }
 
 // src/tools/context.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 var LocalGuidanceError = class extends SakupaError {
   constructor(code, message) {
     super(code, message);
@@ -1978,7 +2005,7 @@ function reportAuthorizationStore(ctx) {
   return store;
 }
 function issueReportAuthorization(ctx, failedTool) {
-  const token = randomUUID2();
+  const token = randomUUID3();
   reportAuthorizationStore(ctx).set(token, {
     failedTool,
     expiresAt: Date.now() + 10 * 60 * 1e3
@@ -2057,9 +2084,9 @@ function toolError(e) {
 }
 
 // src/tools/definitions.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 import { promises as fs2 } from "node:fs";
-import { join as join7, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
+import { join as join8, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
 import { z as z2 } from "zod";
 
 // src/recovery-archive.ts
@@ -2484,15 +2511,15 @@ function strFromU8(dat, latin1) {
 var slzh = function(d, b) {
   return b + 30 + b2(d, b + 26) + b2(d, b + 28);
 };
-var zh = function(d, b, z5) {
+var zh = function(d, b, z6) {
   var fnl = b2(d, b + 28), efl = b2(d, b + 30), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl;
-  var _a2 = z64hs(d, es, efl, z5, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
+  var _a2 = z64hs(d, es, efl, z6, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
   return [b2(d, b + 10), sc, su, fn, es + efl + b2(d, b + 32), off];
 };
-var z64hs = function(d, b, l, z5, sc, su, off) {
+var z64hs = function(d, b, l, z6, sc, su, off) {
   var nsc = sc == 4294967295, nsu = su == 4294967295, noff = off == 4294967295, e = b + l;
   var nf = nsc + nsu + noff;
-  if (z5 && nf) {
+  if (z6 && nf) {
     for (; b + 4 < e; b += 4 + b2(d, b + 2)) {
       if (b2(d, b) == 1) {
         return [
@@ -2503,7 +2530,7 @@ var z64hs = function(d, b, l, z5, sc, su, off) {
         ];
       }
     }
-    if (z5 < 2)
+    if (z6 < 2)
       err(13);
   }
   return [sc, su, off, 0];
@@ -2520,18 +2547,18 @@ function unzipSync(data, opts) {
   if (!c)
     return {};
   var o = b4(data, e + 16);
-  var z5 = b4(data, e - 20) == 117853008;
-  if (z5) {
+  var z6 = b4(data, e - 20) == 117853008;
+  if (z6) {
     var ze = b4(data, e - 12);
-    z5 = b4(data, ze) == 101075792;
-    if (z5) {
+    z6 = b4(data, ze) == 101075792;
+    if (z6) {
       c = b4(data, ze + 32);
       o = b4(data, ze + 48);
     }
   }
   var fltr = opts && opts.filter;
   for (var i = 0; i < c; ++i) {
-    var _a2 = zh(data, o, z5), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    var _a2 = zh(data, o, z6), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
     o = no;
     if (!fltr || fltr({
       name: fn,
@@ -3039,15 +3066,181 @@ ${diag.layers}
 ` + (diag.allOk ? "All required records are live; certificate issuance completes automatically \u2014 re-check in a few minutes until the binding is active." : `${fixTail} ${cadence}`);
 }
 
+// src/credential-rotation.ts
+import {
+  chmodSync as chmodSync3,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync4,
+  renameSync as renameSync3,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync5
+} from "node:fs";
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { join as join7 } from "node:path";
+var ROTATION_FILE = "rotation.json";
+function credentialRotationPath(projectDir) {
+  return join7(projectDir, ".sakupa", ROTATION_FILE);
+}
+function loadCredentialRotation(projectDir) {
+  const path = credentialRotationPath(projectDir);
+  if (!existsSync6(path)) return { kind: "absent" };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync4(path, "utf8"));
+  } catch (error) {
+    return {
+      kind: "corrupted",
+      problem: `the file cannot be read as JSON (${error instanceof Error ? error.message : String(error)})`
+    };
+  }
+  if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
+    return { kind: "corrupted", problem: "siteId is missing or empty" };
+  }
+  if (typeof parsed.candidateCredential !== "string" || !CREDENTIAL_PATTERN.test(parsed.candidateCredential)) {
+    return { kind: "corrupted", problem: "candidateCredential has an invalid shape" };
+  }
+  if (typeof parsed.createdAt !== "string" || !Number.isFinite(Date.parse(parsed.createdAt))) {
+    return { kind: "corrupted", problem: "createdAt is missing or invalid" };
+  }
+  if (typeof parsed.apiBaseUrl !== "string" || parsed.apiBaseUrl.length === 0) {
+    return { kind: "corrupted", problem: "apiBaseUrl is missing or empty" };
+  }
+  return {
+    kind: "ok",
+    file: {
+      siteId: parsed.siteId,
+      candidateCredential: parsed.candidateCredential,
+      createdAt: parsed.createdAt,
+      apiBaseUrl: parsed.apiBaseUrl
+    }
+  };
+}
+function writeCredentialRotation(projectDir, file) {
+  if (!CREDENTIAL_PATTERN.test(file.candidateCredential)) {
+    throw new Error("Refusing to persist an invalid credential rotation candidate.");
+  }
+  const current = loadCredentialRotation(projectDir);
+  if (current.kind === "corrupted") {
+    throw new Error(
+      `Refusing to overwrite damaged credential rotation state: ${current.problem}. Run help.`
+    );
+  }
+  if (current.kind === "ok") {
+    if (current.file.siteId === file.siteId && current.file.candidateCredential === file.candidateCredential && current.file.apiBaseUrl === file.apiBaseUrl) {
+      return;
+    }
+    throw new Error(
+      "A different credential rotation is already pending. Run rotate to resume it; no state was overwritten."
+    );
+  }
+  const directory = join7(projectDir, ".sakupa");
+  mkdirSync5(directory, { recursive: true, mode: 448 });
+  const target = credentialRotationPath(projectDir);
+  const temporary = join7(directory, `.rotation-${randomUUID4()}.tmp`);
+  writeFileSync5(temporary, `${JSON.stringify(file, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    chmodSync3(temporary, 384);
+  } catch {
+  }
+  try {
+    renameSync3(temporary, target);
+  } catch (error) {
+    rmSync2(temporary, { force: true });
+    throw error;
+  }
+}
+function deleteCredentialRotation(projectDir) {
+  rmSync2(credentialRotationPath(projectDir), { force: true });
+}
+function promoteRotatedCredential(projectDir, site, rotation, credentialCreatedAt) {
+  if (rotation.siteId !== site.siteId || rotation.apiBaseUrl !== site.apiBaseUrl) {
+    throw new Error(
+      "Credential rotation state belongs to a different site or Sakupa environment; no file was changed."
+    );
+  }
+  if (!Number.isFinite(Date.parse(credentialCreatedAt))) {
+    throw new Error(
+      "The server returned an invalid credential creation time; no file was changed."
+    );
+  }
+  const updated = {
+    ...site,
+    credential: rotation.candidateCredential,
+    createdAt: credentialCreatedAt
+  };
+  writeSiteFile(projectDir, updated);
+  deleteCredentialRotation(projectDir);
+  return updated;
+}
+async function resumeCredentialRotation(client, projectDir, site, apiBaseUrl) {
+  const state = loadCredentialRotation(projectDir);
+  if (state.kind === "absent") return null;
+  if (state.kind === "corrupted") {
+    throw new Error(
+      `Credential rotation state is damaged (${state.problem}). Nothing was overwritten; run help.`
+    );
+  }
+  const pending = state.file;
+  const siteEnvironment = site.apiBaseUrl || apiBaseUrl;
+  if (pending.siteId !== site.siteId || pending.apiBaseUrl !== apiBaseUrl || siteEnvironment !== apiBaseUrl) {
+    throw new Error(
+      "Credential rotation state belongs to a different site or Sakupa environment. Nothing was changed; run help."
+    );
+  }
+  try {
+    const status = await client.getCredentialStatus(site.siteId, pending.candidateCredential);
+    return {
+      site: promoteRotatedCredential(
+        projectDir,
+        { ...site, apiBaseUrl },
+        pending,
+        status.credentialCreatedAt
+      ),
+      status,
+      rotation: null,
+      resumed: true
+    };
+  } catch (error) {
+    if (!isSakupaError(error) || error.code !== "unauthorized") throw error;
+  }
+  try {
+    await client.getCredentialStatus(site.siteId, site.credential);
+  } catch (error) {
+    if (!isSakupaError(error) || error.code !== "unauthorized") throw error;
+    throw new Error(
+      "Neither the current nor pending credential is accepted. No local file was overwritten; run help before retrying."
+    );
+  }
+  const rotation = await client.rotateCredential(site.siteId, site.credential, {
+    newCredential: pending.candidateCredential
+  });
+  return {
+    site: promoteRotatedCredential(
+      projectDir,
+      { ...site, apiBaseUrl },
+      pending,
+      rotation.credentialCreatedAt
+    ),
+    status: rotation,
+    rotation,
+    resumed: true
+  };
+}
+
 // src/tools/definitions.ts
-function text(resultCode, t, data = {}, outcome = "completed") {
+function text(resultCode, t, data = {}, outcome = "completed", nextActions = []) {
   return structuredToolResult({
     schemaVersion: 1,
     outcome,
     resultCode,
     summary: t,
     data,
-    nextActions: []
+    nextActions
   });
 }
 function textJson(resultCode, header, obj, outcome = "completed") {
@@ -3115,7 +3308,7 @@ function ensureUploadSizeWithinLimits(manifest, isFirstFreeDeploy) {
 async function buildHashedManifest(files, outputAbs) {
   const manifest = [];
   for (const file of files) {
-    const bytes = new Uint8Array(await fs2.readFile(join7(outputAbs, file.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join8(outputAbs, file.path)));
     manifest.push({ path: file.path, size: file.size, contentHash: await sha256Hex(bytes) });
   }
   return manifest;
@@ -3134,7 +3327,7 @@ async function uploadAll(ctx, targets, files, outputAbs) {
         `No local file matches upload target "${target.path}"; aborting upload.`
       );
     }
-    const bytes = new Uint8Array(await fs2.readFile(join7(outputAbs, match.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join8(outputAbs, match.path)));
     if (bytes.byteLength !== match.size) {
       throw new SakupaError(
         "validation_failed",
@@ -3227,14 +3420,14 @@ function outputDirectoryChain(projectRoot, outputAbs) {
   const chain = [];
   let cursor = projectRoot;
   for (const part of rel.split(sep4).filter(Boolean)) {
-    cursor = join7(cursor, part);
+    cursor = join8(cursor, part);
     chain.push(cursor);
   }
   return chain;
 }
 async function sakupaDirectoryEntries(projectDir) {
   try {
-    return await fs2.readdir(join7(projectDir, ".sakupa"));
+    return await fs2.readdir(join8(projectDir, ".sakupa"));
   } catch (error) {
     const code = error.code;
     if (code === "ENOENT") return [];
@@ -3345,6 +3538,8 @@ Next action: ${analysis.suggestedNextAction}`,
         }
         let existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         let handoff = null;
+        let credentialSecurity = null;
+        let credentialRotationResumed = false;
         const resumedHandoffCleanup = existing ? resumeLocalSiteHandoff(ctx.projectDir, existing, Date.now()) : null;
         const credentialRelocatedFrom = [];
         const markerRelocatedFrom = [];
@@ -3382,8 +3577,8 @@ Next action: ${analysis.suggestedNextAction}`,
                 summary: `A nested Sakupa project marker exists at ${candidateDir}/.sakupa, but the active MCP Root is ${ctx.projectDir}. Nothing was moved or deployed. Show both paths to the user; after confirmation retry deploy with sakupaRelocationConfirmed:true. Sakupa will preserve credentials and refuse conflicts.`,
                 data: {
                   projectRoot: ctx.projectDir,
-                  misplacedSakupaDirectory: join7(candidateDir, ".sakupa"),
-                  targetSakupaDirectory: join7(ctx.projectDir, ".sakupa"),
+                  misplacedSakupaDirectory: join8(candidateDir, ".sakupa"),
+                  targetSakupaDirectory: join8(ctx.projectDir, ".sakupa"),
                   confirmationField: "sakupaRelocationConfirmed"
                 },
                 nextActions: [
@@ -3555,6 +3750,17 @@ Next action: ${analysis.suggestedNextAction}`,
               ctx.apiBaseUrl
             );
             releaseHandoffLock = acquireSiteHandoffLock(handoff.site.siteId);
+            const resumedSourceRotation = await resumeCredentialRotation(
+              ctx.client,
+              handoff.sourceProjectDir,
+              handoff.site,
+              ctx.apiBaseUrl
+            );
+            if (resumedSourceRotation) {
+              handoff = { ...handoff, site: resumedSourceRotation.site };
+              credentialSecurity = resumedSourceRotation.status;
+              credentialRotationResumed = true;
+            }
             const cloud = await ctx.client.getSiteStatus(
               handoff.site.siteId,
               handoff.site.credential
@@ -3591,6 +3797,39 @@ Next action: ${analysis.suggestedNextAction}`,
             );
           }
         }
+        if (existing) {
+          try {
+            if (!handoff) {
+              const resumed = await resumeCredentialRotation(
+                ctx.client,
+                ctx.projectDir,
+                existing,
+                ctx.apiBaseUrl
+              );
+              if (resumed) {
+                existing = resumed.site;
+                credentialSecurity = resumed.status;
+                credentialRotationResumed = true;
+              }
+            }
+            credentialSecurity ??= await ctx.client.getCredentialStatus(
+              existing.siteId,
+              existing.credential
+            );
+          } catch (error) {
+            if (isSakupaError(error) && error.code === "unauthorized") {
+              return text(
+                "credential_mismatch",
+                `The server rejected the credential in .sakupa/site.json for site ${existing.siteId}.
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+                { siteId: existing.siteId },
+                "blocked"
+              );
+            }
+            throw error;
+          }
+        }
         ensureUploadSizeWithinLimits(manifest, !existing);
         if (!existing) {
           const created = await ctx.client.createSite({
@@ -3720,11 +3959,13 @@ Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
 ` + (finalized.expiresAt ? `Validity refreshed \u2014 expires at: ${finalized.expiresAt}
 ` : "") + (credentialRelocatedFrom.length > 0 ? `Credential binding relocated from ${credentialRelocatedFrom.join(", ")} to ${ctx.projectDir}/.sakupa; the existing site was preserved.
 ` : "") + (handoff ? `Reusable free-site slot transferred to the current project. The cloud site was NOT deleted; its content was replaced. Previous project: ${handoff.sourceProjectDir}. ` + (handoffCleanup?.sourceCredentialRemoved ? "Its matching .sakupa/site.json credential was removed. Do not use that previous project to manage this URL.\n" : handoffCleanup?.sourceRemovalState === "absent" ? "Its .sakupa/site.json credential was already absent. Do not use that previous project to manage this URL.\n" : `Its credential could not be safely removed because the file was ${handoffCleanup?.sourceRemovalState}. Do not use the previous project to manage this URL; run help before touching its .sakupa directory.
-`) : "") + (finalized.mode === "free" ? `
+`) : "") + (credentialRotationResumed ? "A previously confirmed credential rotation was resumed safely before this deploy; every older credential is revoked.\n" : "") + (finalized.mode === "free" ? `
 Reminder: free sites stay live for ${FREE_SITE_TTL_HOURS} hours after the last deploy or refresh call. Subscribing (subscribe) makes the site permanent.
 ` : "\nThis site is subscribed and permanent \u2014 no expiry.\n") + (finalized.warnings.length > 0 ? `
 Warnings:
-${JSON.stringify(finalized.warnings, null, 2)}` : ""),
+${JSON.stringify(finalized.warnings, null, 2)}` : "") + (credentialSecurity?.rotationRecommended ? `
+
+Optional security recommendation: this management credential was created at ${credentialSecurity.credentialCreatedAt} and is older than 7 days. The deploy SUCCEEDED and rotation is not required. Ask the user whether they want to rotate; call rotate without confirmed:true to show the exact revocation preview. Never rotate automatically.` : ""),
           {
             siteId: existing.siteId,
             url: finalized.url,
@@ -3735,6 +3976,13 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
             filesUploaded: uploaded,
             totalBytes: finalized.totalBytes,
             warnings: finalized.warnings,
+            credentialSecurity: credentialSecurity ? {
+              credentialCreatedAt: credentialSecurity.credentialCreatedAt,
+              ageSeconds: credentialSecurity.ageSeconds,
+              rotationRecommended: credentialSecurity.rotationRecommended,
+              optional: true,
+              resumedAfterInterruption: credentialRotationResumed
+            } : null,
             ...credentialRelocatedFrom.length > 0 ? { credentialRelocatedFrom } : {},
             ...handoff ? {
               handoff: {
@@ -3747,7 +3995,15 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
                 sourceRemovalState: handoffCleanup?.sourceRemovalState
               }
             } : {}
-          }
+          },
+          "completed",
+          credentialSecurity?.rotationRecommended ? [
+            {
+              tool: "rotate",
+              allowed: true,
+              reasonCode: "credential_older_than_seven_days_optional_rotation"
+            }
+          ] : []
         );
       } catch (e) {
         return toolError(e);
@@ -3840,7 +4096,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID3()
+            idempotencyKey: randomUUID5()
           },
           site.credential
         );
@@ -4568,7 +4824,7 @@ function registerBillingTools(server, baseCtx) {
 }
 
 // src/tools/help.ts
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 import { z as z4 } from "zod";
 var TOOL_TOPICS = [
   "init",
@@ -4576,6 +4832,7 @@ var TOOL_TOPICS = [
   "deploy",
   "refresh",
   "status",
+  "rotate",
   "plans",
   "subscribe",
   "bind",
@@ -4637,6 +4894,14 @@ var TOOL_MANUALS = {
     warnings: ["Billing truth comes from billing, not inferred status text."],
     nextStep: "Follow only the returned real tool names."
   },
+  rotate: {
+    purpose: "Replace the current site management credential after explicit confirmation.",
+    sideEffects: "Confirmed rotation revokes every previous credential for this site.",
+    preconditions: "A valid local site credential; preview is required before confirmation.",
+    parameters: "confirmed=true only from the exact preview resume arguments.",
+    warnings: ["Rotation is optional and never blocks deploy.", "Never expose credential values."],
+    nextStep: "Use the preview resumeWith arguments only after the user confirms."
+  },
   plans: {
     purpose: "Read the authoritative hosting plan catalog and rules.",
     sideEffects: "Read-only public API request.",
@@ -4741,7 +5006,7 @@ function registerHelpTools(server, baseCtx) {
           throw new Error("init postcondition failed: project marker missing");
         const site = loadSiteFile(ctx.projectDir);
         const recovery = loadRecoveryFile(ctx.projectDir);
-        const sakupaDirectory = join8(ctx.projectDir, ".sakupa");
+        const sakupaDirectory = join9(ctx.projectDir, ".sakupa");
         return structuredToolResult({
           schemaVersion: 1,
           outcome: "completed",
@@ -4815,12 +5080,26 @@ Next: ${manual.nextStep}`,
         const marker = selected ? loadProjectMarker(selected) : { kind: "absent" };
         const site = selected ? loadSiteFile(selected) : { kind: "absent" };
         let recoveryState = "absent";
+        let credentialRotationState = "absent";
+        let credentialRotationDetails;
         if (selected) {
           try {
             recoveryState = loadRecoveryFile(selected) === null ? "absent" : "ok";
           } catch {
             recoveryState = "corrupted";
           }
+          const rotation = loadCredentialRotation(selected);
+          if (rotation.kind === "ok") {
+            credentialRotationState = "pending";
+            credentialRotationDetails = {
+              siteId: rotation.file.siteId,
+              createdAt: rotation.file.createdAt,
+              apiBaseUrl: rotation.file.apiBaseUrl
+            };
+          } else if (rotation.kind === "corrupted") {
+            credentialRotationState = "corrupted";
+            credentialRotationDetails = { problem: rotation.problem };
+          }
         }
         const opaqueFailure = args.errorCode === "internal" || args.resultCode === "error_internal";
         const reportRecommended = opaqueFailure && (diagnosis.diagnosisCode === "project_bound" || diagnosis.diagnosisCode === "roots_request_failed");
@@ -4837,8 +5116,9 @@ Next: ${manual.nextStep}`,
             allowed: true,
             reasonCode: "help_confirmed_last_resort"
           }
-        ] : diagnosis.diagnosisCode === "workspace_not_initialized" ? [{ tool: "init", allowed: true, reasonCode: "initialize_active_root" }] : [];
-        const summary = `Help diagnosis: ${diagnosis.diagnosisCode}. ${diagnosis.guidance} MCP version: ${MCP_VERSION}. ` + (reportRecommended ? diagnosis.diagnosisCode === "project_bound" ? "Local project binding is healthy but the failure is an unclassified internal error. report is now available as the last resort; preview it before submission." : "The MCP Roots request itself failed with an unclassified internal error. report is now available as the last resort; preview it before submission." : "Do not submit report for this diagnosis; follow the guidance and retry help.");
+        ] : credentialRotationState === "pending" ? [{ tool: "rotate", allowed: true, reasonCode: "resume_confirmed_rotation" }] : diagnosis.diagnosisCode === "workspace_not_initialized" ? [{ tool: "init", allowed: true, reasonCode: "initialize_active_root" }] : [];
+        const rotationGuidance = credentialRotationState === "pending" ? "A previously confirmed credential rotation is pending; call rotate with no arguments to resume it. The candidate credential is intentionally hidden." : credentialRotationState === "corrupted" ? "The local credential rotation journal is damaged. Preserve .sakupa/rotation.json, do not print, edit or delete it, and do not retry deploy or rotate until the file is recovered from a trusted backup or Sakupa support confirms the recovery path." : "";
+        const summary = `Help diagnosis: ${diagnosis.diagnosisCode}. ${diagnosis.guidance} MCP version: ${MCP_VERSION}. ${rotationGuidance} ` + (reportRecommended ? diagnosis.diagnosisCode === "project_bound" ? "Local project binding is healthy but the failure is an unclassified internal error. report is now available as the last resort; preview it before submission." : "The MCP Roots request itself failed with an unclassified internal error. report is now available as the last resort; preview it before submission." : "Do not submit report for this diagnosis; follow the guidance and retry help.");
         return structuredToolResult({
           schemaVersion: 1,
           outcome: diagnosis.diagnosisCode === "project_bound" ? "completed" : "blocked",
@@ -4850,6 +5130,8 @@ Next: ${manual.nextStep}`,
             projectMarkerState: marker.kind,
             siteState: site.kind,
             recoveryState,
+            credentialRotationState,
+            ...credentialRotationDetails !== void 0 ? { credentialRotationDetails } : {},
             reportRecommended,
             ...helpAuthorization !== void 0 ? { helpAuthorization } : {},
             ...args.failedTool !== void 0 ? { failedTool: args.failedTool } : {},
@@ -4865,6 +5147,128 @@ Next: ${manual.nextStep}`,
   );
 }
 
+// src/tools/credential.ts
+import { z as z5 } from "zod";
+function registerCredentialTools(server, baseCtx) {
+  server.registerTool(
+    "rotate",
+    {
+      description: "Optionally replace this site management credential. The first call is a read-only preview. Only confirmed:true after explicit user approval installs a locally generated new credential and revokes every previous credential. Rotation is never required to deploy.",
+      inputSchema: {
+        confirmed: z5.boolean().optional().describe(
+          "True only after showing the rotate preview and the user explicitly approves revoking every old credential."
+        )
+      },
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      let releaseLock;
+      try {
+        const ctx = await withProjectDir(baseCtx);
+        let site = requireSiteFile(ctx);
+        const pending = loadCredentialRotation(ctx.projectDir);
+        if (pending.kind !== "absent" || args.confirmed === true) {
+          releaseLock = acquireSiteHandoffLock(site.siteId);
+        }
+        if (pending.kind !== "absent") {
+          const resumed = await resumeCredentialRotation(
+            ctx.client,
+            ctx.projectDir,
+            site,
+            ctx.apiBaseUrl
+          );
+          if (!resumed) throw new Error("Credential rotation resume state disappeared.");
+          site = resumed.site;
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "credential_rotation_resumed",
+            summary: `Credential rotation resumed and completed for ${site.url ?? site.siteId}. The new credential is stored only in this project .sakupa/site.json. Every previous credential is revoked; old project folders and backup copies can no longer manage this site. No credential value is shown.`,
+            data: {
+              siteId: site.siteId,
+              credentialCreatedAt: resumed.status.credentialCreatedAt,
+              rotationRecommended: false,
+              previousCredentialsRevoked: true,
+              resumedAfterInterruption: true,
+              credentialStoredLocally: true
+            },
+            nextActions: [{ tool: "status", allowed: true }]
+          });
+        }
+        const status = await ctx.client.getCredentialStatus(site.siteId, site.credential);
+        const confirmation = { confirmed: true };
+        if (args.confirmed !== true) {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "waiting_user",
+            resultCode: "credential_rotation_confirmation_required",
+            summary: `Nothing was changed. Rotating the management credential for ${site.url ?? site.siteId} will generate a new credential locally, replace the one in this project .sakupa/site.json, and revoke EVERY previous credential for this site\u2014including copies in old folders and backups. Rotation is optional and deploy remains available. Current credential created at: ${status.credentialCreatedAt}. Exact confirm arguments: ${JSON.stringify(confirmation)}. Ask the user for explicit approval; never expose credential values.`,
+            data: {
+              siteId: site.siteId,
+              credentialCreatedAt: status.credentialCreatedAt,
+              credentialAgeSeconds: status.ageSeconds,
+              rotationRecommended: status.rotationRecommended,
+              confirmation,
+              confirmArguments: confirmation,
+              previousCredentialsWillBeRevoked: true,
+              optional: true
+            },
+            userAction: {
+              type: "confirm_in_mcp",
+              provider: "sakupa",
+              expectedOutcome: "Generate one new local credential and revoke every previous credential for this site.",
+              resumeWith: { tool: "rotate", arguments: confirmation }
+            },
+            nextActions: [
+              {
+                tool: "rotate",
+                arguments: confirmation,
+                allowed: true,
+                reasonCode: "explicit_credential_rotation_confirmation"
+              }
+            ]
+          });
+        }
+        writeCredentialRotation(ctx.projectDir, {
+          siteId: site.siteId,
+          candidateCredential: generateCredential(),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          apiBaseUrl: ctx.apiBaseUrl
+        });
+        const completed = await resumeCredentialRotation(
+          ctx.client,
+          ctx.projectDir,
+          site,
+          ctx.apiBaseUrl
+        );
+        if (!completed) throw new Error("Credential rotation did not produce resumable state.");
+        site = completed.site;
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: "completed",
+          resultCode: "credential_rotated",
+          summary: `Management credential rotated for ${site.url ?? site.siteId}. The new credential is stored only in this project .sakupa/site.json. Every previous credential is revoked; old project folders and backup copies can no longer manage this site. No credential value is shown.`,
+          data: {
+            siteId: site.siteId,
+            credentialCreatedAt: completed.status.credentialCreatedAt,
+            rotationRecommended: false,
+            previousCredentialsRevoked: true,
+            revokedPreviousCredentials: completed.rotation?.revokedPreviousCredentials ?? null,
+            resumedAfterInterruption: false,
+            credentialStoredLocally: true
+          },
+          nextActions: [{ tool: "status", allowed: true }]
+        });
+      } catch (error) {
+        return toolError(error);
+      } finally {
+        releaseLock?.();
+      }
+    }
+  );
+}
+
 // src/server.ts
 import { resolve as resolve6 } from "node:path";
 var instructionsFor = (hostPattern) => `Sakupa publishes AI-made static websites. AI-made pages, live in seconds.
@@ -4877,7 +5281,9 @@ Workflow:
    site (public URL ${hostPattern}, valid 24 hours, free banner shown) and stores the
    management credential in .sakupa/site.json. Deploying again updates the site and refreshes
    its validity; refresh extends validity without uploading; status shows the
-   current deployment and serving state at any time.
+   current deployment and serving state at any time. Every update checks the credential's
+   server-side issue time. When it is older than 7 days, deploy succeeds and only SUGGESTS the
+   optional rotate tool; never rotate without the user's explicit confirmation.
 3. To make the site PERMANENT, subscribe it to a monthly hosting plan (plans
    shows the catalog; subscribe -> Stripe-hosted checkout;
    water/personal/share/business). Paying makes the
@@ -4945,6 +5351,9 @@ Safety boundaries:
 - Never repeat, echo, or memorize the credential value from .sakupa/site.json \u2014 quoting it
   into the conversation copies the site's only key outside the protected local file. Read it
   only through the tools.
+- rotate always previews first. confirmed:true revokes EVERY prior credential, including old
+  folders and backups. Show that consequence and obtain explicit user approval; rotation is
+  optional and never a condition for deploy.
 - Before deploying, if the entry HTML lacks a lang attribute, add one matching the content
   language (infer it from the content) and then deploy; only skip when the user explicitly
   wants no lang attribute.
@@ -4988,6 +5397,7 @@ function createSakupaMcpServer(opts) {
   };
   registerTools(server, ctx);
   registerBillingTools(server, ctx);
+  registerCredentialTools(server, ctx);
   registerHelpTools(server, ctx);
   return server;
 }