Warn before the client secret expires (SP_SECRET_EXPIRES)

Azure client secrets lapse silently into opaque 401s (AADSTS7000222). Add a self-reported expiry date (SP_SECRET_EXPIRES=YYYY-MM-DD) and a shared secretExpiryStatus() helper in graph.mjs; surface warnings <30 days out via the CLI (stderr on every command + test output), MCP server startup log, /health, and the sharepoint_test tool. Documented in both .env.examples, setup.md, and READMEs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/skills/sharepoint-lists/scripts/lib/graph.mjs

@@ -327,6 +327,49 @@ export class SharePointListsClient {
   }
 }
 
+/**
+ * Report how close the app's client secret is to expiring, so consumers can
+ * warn BEFORE auth starts failing with an opaque 401 (AADSTS7000222).
+ *
+ * Azure can't be queried for its own secret's expiry with app-only creds, so
+ * the date is self-reported: set SP_SECRET_EXPIRES=YYYY-MM-DD in .env when you
+ * create/rotate the secret (the Entra portal shows it in Certificates & secrets).
+ *
+ * @param {string} [expiresStr] The configured date; falsy → null (feature unused).
+ * @returns {null | { expiresAt: string, daysLeft: number, level: "ok"|"warning"|"expired", message: string|null }}
+ */
+export function secretExpiryStatus(expiresStr, { warnDays = 30 } = {}) {
+  if (!expiresStr) return null;
+  const exp = new Date(expiresStr);
+  if (Number.isNaN(exp.getTime())) {
+    return {
+      expiresAt: expiresStr,
+      daysLeft: NaN,
+      level: "warning",
+      message: `SP_SECRET_EXPIRES is set but unparseable ("${expiresStr}") — use YYYY-MM-DD.`,
+    };
+  }
+  const daysLeft = Math.floor((exp.getTime() - Date.now()) / 86_400_000);
+  const expiresAt = exp.toISOString().slice(0, 10);
+  if (daysLeft < 0) {
+    return {
+      expiresAt,
+      daysLeft,
+      level: "expired",
+      message: `Client secret EXPIRED ${-daysLeft} day(s) ago (${expiresAt}). Auth will fail with 401 — create a new secret in Entra (Certificates & secrets), update SP_CLIENT_SECRET and SP_SECRET_EXPIRES.`,
+    };
+  }
+  if (daysLeft <= warnDays) {
+    return {
+      expiresAt,
+      daysLeft,
+      level: "warning",
+      message: `Client secret expires in ${daysLeft} day(s) (${expiresAt}) — rotate it soon: new secret in Entra, then update SP_CLIENT_SECRET and SP_SECRET_EXPIRES.`,
+    };
+  }
+  return { expiresAt, daysLeft, level: "ok", message: null };
+}
+
 /** Flatten the Graph item shape into { id, fields, webUrl, ...meta }. */
 function simplifyItem(item) {
   if (!item) return item;

.claude/skills/sharepoint-lists/scripts/sp.mjs

@@ -25,7 +25,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { SharePointListsClient, GraphError } from "./lib/graph.mjs";
+import { SharePointListsClient, GraphError, secretExpiryStatus } from "./lib/graph.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -57,6 +57,11 @@ async function main() {
     clientSecret: env("SP_CLIENT_SECRET", "AZURE_CLIENT_SECRET"),
   });
 
+  // Nag (on stderr, so stdout stays clean JSON) when the client secret is
+  // close to its self-reported expiry — see secretExpiryStatus in graph.mjs.
+  const expiry = secretExpiryStatus(process.env.SP_SECRET_EXPIRES);
+  if (expiry?.message) process.stderr.write(`⚠ ${expiry.message}\n`);
+
   const site = flags.site || process.env.SP_SITE_URL;
   const needSite = () => {
     if (!site) throw new Error("Missing --site URL (or set SP_SITE_URL).");
@@ -75,6 +80,7 @@ async function main() {
   switch (command) {
     case "test":
       result = await client.test(site);
+      if (expiry) result.secretExpiry = expiry;
       break;
     case "lists":
       result = await client.listLists(await needSite());