mercury-agent 0.23.2 → 0.24.0

package/examples/extensions/office-365-mail/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Office 365 Mail — host-side capability broker extension over Microsoft Graph.
+ *
+ * Third `mercury.capability()` adopter (rung 4 of the secrets ladder, see
+ * docs/ideas/container-egress-unrestricted.md) after yahoo-mail and morning.
+ * The Entra client id, the seed refresh token and every rotated successor stay
+ * in the Mercury host process; the agent container invokes named verbs via
+ * `mrctl capability office-365-mail <action> '<json>'` and no `M365_*` value
+ * ever enters a container. The verbs live in `lib/graph.ts`.
+ */
+
+type ConnectionCategory =
+  | "email"
+  | "drive"
+  | "calendar"
+  | "finance"
+  | "messaging"
+  | "docs"
+  | "workspace"
+  | "other";
+
+type ConnectionAuthType =
+  | "oauth2"
+  | "apikey"
+  | "app-password"
+  | "credentials-file"
+  | "custom";
+
+type ConnectionStatus = "connected" | "needs-reauth" | "broken" | "unknown";
+
+/** Structural copy of `ConnectionHealthCheck` in src/extensions/types.ts. */
+type ConnectionHealthCheck = {
+  recovery: string;
+  timeoutMs?: number;
+  source?: string;
+  run(ctx: ExtContext): Promise<CredentialProbeResult>;
+};
+
+/** The slice of `MercuryExtensionContext` this extension reads. */
+type ExtContext = {
+  db: {
+    getExtState(ext: string, key: string): string | null;
+    setExtState(ext: string, key: string, value: string): void;
+    deleteExtState(ext: string, key: string): boolean;
+  };
+};
+
+/** Structural match for `MercuryExtensionAPI` (avoid package subpath imports). */
+type MercuryExt = {
+  permission(opts: { defaultRoles: string[] }): void;
+  env(def: { from: string; as?: string; hostOnly: boolean }): void;
+  skill(relativePath: string): void;
+  connection(def: {
+    displayName: string;
+    iconUrl?: string;
+    category: ConnectionCategory;
+    authType: ConnectionAuthType;
+    credentialEnvVar?: string;
+    scopes?: string[];
+    statusCheck?: (
+      ctx: ExtContext,
+    ) => Promise<{ status: ConnectionStatus; detail?: string }>;
+    healthCheck?: ConnectionHealthCheck;
+  }): void;
+  capability(
+    name: string,
+    handler: (
+      req: {
+        name: string;
+        action: string;
+        callerId: string;
+        spaceId: string;
+        body: unknown;
+      },
+      ctx: ExtContext,
+    ) => Promise<{ status?: number; data: unknown }>,
+  ): void;
+};
+
+import {
+  type CredentialProbeResult,
+  dbTokenStore,
+  M365_ENV,
+  M365_EXT,
+  MailBroker,
+  STATE_KEYS,
+} from "./lib/graph.js";
+
+export const LOGIN_HINT =
+  "run `bun .mercury/extensions/office-365-mail/scripts/login.ts --client-id <id>` on the host, put the printed MERCURY_M365_* lines in .env, then restart Mercury";
+
+/**
+ * One broker per host process: it owns the in-memory access token and the
+ * single-flight refresh, and every caller (verbs, statusCheck, the daily
+ * probe) must share it or the token store gets two writers.
+ */
+let broker: MailBroker | undefined;
+function brokerFor(ctx: ExtContext): MailBroker {
+  if (!broker) broker = new MailBroker({ store: dbTokenStore(ctx.db) });
+  return broker;
+}
+
+/** Test seam: drop the process-wide broker so each test starts cold. */
+export function resetBrokerForTests(): void {
+  broker = undefined;
+}
+
+export default function (mercury: MercuryExt) {
+  mercury.permission({ defaultRoles: ["admin"] });
+
+  // hostOnly, and the claims must STAY: the loader rejects a
+  // connection.credentialEnvVar that no mercury.env() declares, and an
+  // UNCLAIMED MERCURY_* var falls through the blunt passthrough into every
+  // container under env_passthrough: "all". hostOnly is what keeps the client
+  // id, the seed and the tenant out of containers on both paths.
+  mercury.env({ from: M365_ENV.clientId, hostOnly: true });
+  mercury.env({ from: M365_ENV.refreshToken, hostOnly: true });
+  mercury.env({ from: M365_ENV.tenant, hostOnly: true });
+
+  mercury.connection({
+    displayName: "Office 365 Mail",
+    category: "email",
+    authType: "oauth2",
+    // The CLIENT ID gates loading, not the seed: the seed may be removed from
+    // .env once a rotated successor is in the store, and that must not unload
+    // a working mailbox connection.
+    credentialEnvVar: M365_ENV.clientId,
+    scopes: [
+      "https://graph.microsoft.com/Mail.ReadWrite",
+      "https://graph.microsoft.com/Mail.Send",
+      "https://graph.microsoft.com/User.Read",
+      "offline_access",
+    ],
+    // Side-effect free and fast: reports from env presence and stored state,
+    // never mints a token. Validity is the healthCheck's question.
+    statusCheck: async (ctx) => {
+      const authError = ctx.db.getExtState(M365_EXT, STATE_KEYS.authError);
+      if (authError) {
+        return { status: "needs-reauth", detail: authError };
+      }
+      const seed = process.env[M365_ENV.refreshToken]?.trim();
+      const stored = ctx.db.getExtState(M365_EXT, STATE_KEYS.refreshToken);
+      if (!seed && !stored) {
+        return {
+          status: "unknown",
+          detail: `no refresh token yet — ${LOGIN_HINT}`,
+        };
+      }
+      return { status: "connected" };
+    },
+    // The daily validity probe (src/core/connection-health.ts): one forced
+    // exchange through the broker's single-flight path, so the rotated token
+    // it receives is persisted by the same code the verbs use.
+    healthCheck: {
+      source: M365_ENV.refreshToken,
+      timeoutMs: 20_000,
+      recovery: LOGIN_HINT,
+      run: (ctx) => brokerFor(ctx).probeCredential(),
+    },
+  });
+
+  // All errors come back as data (runAction never throws) — the capability
+  // route would mask a thrown error behind a generic 500 and the model needs
+  // Graph's real message to report the cause.
+  mercury.capability(M365_EXT, async (req, ctx) => {
+    return brokerFor(ctx).runAction(req.action, req.body);
+  });
+
+  mercury.skill("./skill");
+}