@symerian/symi 2.1.4 → 2.1.5

package/extensions/outlook/index.ts

@@ -0,0 +1,199 @@
+import { buildOauthProviderAuthResult, emptyPluginConfigSchema } from "symi/plugin-sdk";
+import type { AnyAgentTool, SymiPluginApi, ProviderAuthContext } from "../../src/plugins/types.js";
+import { loginOutlook } from "./src/auth.js";
+import { saveCredentials, loadCredentials, deleteCredentials } from "./src/store.js";
+import {
+  createOutlookListTool,
+  createOutlookReadTool,
+  createOutlookSendTool,
+  createOutlookReplyTool,
+  createOutlookSearchTool,
+  createOutlookFoldersTool,
+  createOutlookMoveTool,
+} from "./src/tools.js";
+
+const outlookPlugin = {
+  id: "outlook",
+  name: "Outlook 365",
+  description: "Outlook 365 email integration via Microsoft Graph API with OAuth2 PKCE",
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api: SymiPluginApi) {
+    // -------------------------------------------------------------------------
+    // Agent tools — available when Outlook is connected
+    // -------------------------------------------------------------------------
+    const tools = [
+      createOutlookListTool,
+      createOutlookReadTool,
+      createOutlookSendTool,
+      createOutlookReplyTool,
+      createOutlookSearchTool,
+      createOutlookFoldersTool,
+      createOutlookMoveTool,
+    ];
+
+    for (const createTool of tools) {
+      api.registerTool(createTool() as unknown as AnyAgentTool, { optional: true });
+    }
+
+    // -------------------------------------------------------------------------
+    // Provider — enables `symi models add --provider outlook --auth oauth`
+    // and stores credentials in the standard auth profile store.
+    // -------------------------------------------------------------------------
+    api.registerProvider({
+      id: "outlook-mail",
+      label: "Outlook 365 Mail",
+      docsPath: "/integrations/outlook",
+      aliases: ["outlook"],
+      auth: [
+        {
+          id: "oauth",
+          label: "Microsoft OAuth (sign in with your account)",
+          hint: "PKCE + localhost callback — uses your normal Microsoft credentials",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            const spin = ctx.prompter.progress("Starting Outlook OAuth...");
+            try {
+              const result = await loginOutlook({
+                isRemote: ctx.isRemote,
+                openUrl: ctx.openUrl,
+                prompt: async (message) => String(await ctx.prompter.text({ message })),
+                note: ctx.prompter.note,
+                log: (message) => ctx.runtime.log(message),
+                progress: spin,
+              });
+
+              // Persist to local credential store for the tools
+              saveCredentials({
+                access: result.access,
+                refresh: result.refresh,
+                expires: result.expires,
+                email: result.email,
+                displayName: result.displayName,
+              });
+
+              return buildOauthProviderAuthResult({
+                providerId: "outlook-mail",
+                defaultModel: "", // not an LLM provider
+                access: result.access,
+                refresh: result.refresh,
+                expires: result.expires,
+                email: result.email,
+                notes: [
+                  result.email
+                    ? `Connected as ${result.displayName ?? result.email}`
+                    : "Outlook connected.",
+                  "Email tools (outlook_list, outlook_send, outlook_search, etc.) are now available.",
+                  "Credentials stored in ~/.symi/credentials/outlook.json",
+                ],
+              });
+            } catch (err) {
+              spin.stop("Outlook OAuth failed");
+              throw err;
+            }
+          },
+        },
+      ],
+    });
+
+    // -------------------------------------------------------------------------
+    // CLI — `symi outlook login`, `symi outlook logout`, `symi outlook status`
+    // -------------------------------------------------------------------------
+    api.registerCli(
+      ({ program }) => {
+        const outlook = program.command("outlook").description("Outlook 365 email integration");
+
+        outlook
+          .command("login")
+          .description("Sign in with your Microsoft account")
+          .action(async () => {
+            const { loginOutlook: login } = await import("./src/auth.js");
+            const open = (await import("node:child_process")).execSync;
+
+            const result = await login({
+              isRemote: false,
+              openUrl: async (url) => {
+                const cmd =
+                  process.platform === "darwin"
+                    ? `open "${url}"`
+                    : process.platform === "win32"
+                      ? `start "" "${url}"`
+                      : `xdg-open "${url}" 2>/dev/null || echo "Open this URL: ${url}"`;
+                try {
+                  open(cmd, { stdio: "ignore" });
+                } catch {
+                  console.log(`Open this URL in your browser:\n${url}`);
+                }
+              },
+              prompt: async (message) => {
+                const readline = await import("node:readline");
+                const rl = readline.createInterface({
+                  input: process.stdin,
+                  output: process.stdout,
+                });
+                return new Promise((resolve) => {
+                  rl.question(message, (answer) => {
+                    rl.close();
+                    resolve(answer);
+                  });
+                });
+              },
+              note: async (message) => {
+                console.log(message);
+              },
+              log: (message) => console.log(message),
+              progress: {
+                update: (msg) => process.stderr.write(`\r${msg}`),
+                stop: (msg) => {
+                  if (msg) process.stderr.write(`\r${msg}\n`);
+                },
+              },
+            });
+
+            saveCredentials({
+              access: result.access,
+              refresh: result.refresh,
+              expires: result.expires,
+              email: result.email,
+              displayName: result.displayName,
+            });
+
+            console.log("");
+            console.log(
+              result.email
+                ? `Connected as ${result.displayName ?? result.email}`
+                : "Outlook connected.",
+            );
+            console.log("Email tools are now available to your agent.");
+          });
+
+        outlook
+          .command("logout")
+          .description("Disconnect Outlook and remove stored credentials")
+          .action(() => {
+            const removed = deleteCredentials();
+            console.log(removed ? "Outlook credentials removed." : "No credentials found.");
+          });
+
+        outlook
+          .command("status")
+          .description("Show Outlook connection status")
+          .action(() => {
+            const creds = loadCredentials();
+            if (!creds) {
+              console.log("Not connected. Run `symi outlook login` to sign in.");
+              return;
+            }
+            const expired = Date.now() >= creds.expires;
+            console.log(`Account: ${creds.email ?? "unknown"}`);
+            console.log(`Name: ${creds.displayName ?? "unknown"}`);
+            console.log(`Token: ${expired ? "expired (will auto-refresh)" : "valid"}`);
+            console.log(`Updated: ${creds.updatedAt ?? "unknown"}`);
+          });
+      },
+      { commands: ["outlook"] },
+    );
+  },
+};
+
+export default outlookPlugin;

package/extensions/outlook/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@symi/outlook",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Symi Outlook 365 email integration via Microsoft Graph API",
+  "type": "module",
+  "devDependencies": {
+    "@symerian/symi": "workspace:*"
+  },
+  "symi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/extensions/outlook/src/auth.ts

@@ -0,0 +1,362 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { isWSL2Sync } from "symi/plugin-sdk";
+
+// Microsoft OAuth 2.0 endpoints (multi-tenant: any Microsoft account)
+const AUTH_URL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize";
+const TOKEN_URL = "https://login.microsoftonline.com/common/oauth2/v2.0/token";
+const REDIRECT_URI = "http://localhost:51122/oauth-callback";
+
+// Scopes for Outlook mail access + offline refresh
+const SCOPES = [
+  "https://graph.microsoft.com/Mail.Read",
+  "https://graph.microsoft.com/Mail.Send",
+  "https://graph.microsoft.com/Mail.ReadWrite",
+  "https://graph.microsoft.com/User.Read",
+  "offline_access",
+];
+
+const RESPONSE_PAGE = `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Symi Outlook OAuth</title>
+    <style>
+      body { font-family: system-ui, sans-serif; display: flex; justify-content: center;
+             align-items: center; height: 100vh; margin: 0; background: #f5f5f5; }
+      main { text-align: center; padding: 2rem; background: white;
+             border-radius: 12px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+      h1 { color: #0078d4; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Outlook connected</h1>
+      <p>You can return to the terminal.</p>
+    </main>
+  </body>
+</html>`;
+
+// Symi's registered multi-tenant Azure AD app (public client, no secret needed).
+// Users can override with SYMI_OUTLOOK_CLIENT_ID if they have their own app registration.
+const DEFAULT_CLIENT_ID = "e24f680b-3fdd-4bce-a201-6bf547fe4735";
+
+function resolveClientId(): string {
+  return process.env.SYMI_OUTLOOK_CLIENT_ID?.trim() || DEFAULT_CLIENT_ID;
+}
+
+export function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+export function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+
+export function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const clientId = resolveClientId();
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+
+export function parseCallbackInput(
+  input: string,
+): { code: string; state: string } | { error: string } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { error: "No input provided" };
+  }
+  try {
+    const url = new URL(trimmed);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (!code) {
+      return { error: "Missing 'code' parameter in URL" };
+    }
+    if (!state) {
+      return { error: "Missing 'state' parameter in URL" };
+    }
+    return { code, state };
+  } catch {
+    return { error: "Paste the full redirect URL (not just the code)." };
+  }
+}
+
+export async function startCallbackServer(params: { timeoutMs: number }) {
+  const redirect = new URL(REDIRECT_URI);
+  const port = redirect.port ? Number(redirect.port) : 51122;
+
+  let settled = false;
+  let resolveCallback: (url: URL) => void;
+  let rejectCallback: (err: Error) => void;
+
+  const callbackPromise = new Promise<URL>((resolve, reject) => {
+    resolveCallback = (url) => {
+      if (settled) return;
+      settled = true;
+      resolve(url);
+    };
+    rejectCallback = (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+  });
+
+  const timeout = setTimeout(() => {
+    rejectCallback(new Error("Timed out waiting for OAuth callback"));
+  }, params.timeoutMs);
+  timeout.unref?.();
+
+  const server = createServer((request, response) => {
+    if (!request.url) {
+      response.writeHead(400, { "Content-Type": "text/plain" });
+      response.end("Missing URL");
+      return;
+    }
+
+    const url = new URL(request.url, `${redirect.protocol}//${redirect.host}`);
+    if (url.pathname !== redirect.pathname) {
+      response.writeHead(404, { "Content-Type": "text/plain" });
+      response.end("Not found");
+      return;
+    }
+
+    response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    response.end(RESPONSE_PAGE);
+    resolveCallback(url);
+
+    setImmediate(() => {
+      server.close();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (err: Error) => {
+      server.off("error", onError);
+      reject(err);
+    };
+    server.once("error", onError);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+
+  return {
+    waitForCallback: () => callbackPromise,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+}
+
+export async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const clientId = resolveClientId();
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: clientId,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed: ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+
+  const access = data.access_token?.trim();
+  const refresh = data.refresh_token?.trim();
+  const expiresIn = data.expires_in ?? 0;
+
+  if (!access) {
+    throw new Error("Token exchange returned no access_token");
+  }
+  if (!refresh) {
+    throw new Error("Token exchange returned no refresh_token (ensure offline_access scope)");
+  }
+
+  // 5-minute buffer before actual expiry (same as google-antigravity)
+  const expires = Date.now() + expiresIn * 1000 - 5 * 60 * 1000;
+  return { access, refresh, expires };
+}
+
+export async function refreshAccessToken(refreshToken: string): Promise<{
+  access: string;
+  refresh: string;
+  expires: number;
+}> {
+  const clientId = resolveClientId();
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: clientId,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      scope: SCOPES.join(" "),
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token refresh failed: ${text}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+
+  const access = data.access_token?.trim();
+  // Microsoft may or may not rotate the refresh token
+  const refresh = data.refresh_token?.trim() ?? refreshToken;
+  const expiresIn = data.expires_in ?? 0;
+
+  if (!access) {
+    throw new Error("Token refresh returned no access_token");
+  }
+
+  const expires = Date.now() + expiresIn * 1000 - 5 * 60 * 1000;
+  return { access, refresh, expires };
+}
+
+export async function fetchUserProfile(accessToken: string): Promise<{
+  email?: string;
+  displayName?: string;
+}> {
+  try {
+    const response = await fetch("https://graph.microsoft.com/v1.0/me", {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+      return {};
+    }
+    const data = (await response.json()) as {
+      mail?: string;
+      userPrincipalName?: string;
+      displayName?: string;
+    };
+    return {
+      email: data.mail || data.userPrincipalName,
+      displayName: data.displayName,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export async function loginOutlook(params: {
+  isRemote: boolean;
+  openUrl: (url: string) => Promise<void>;
+  prompt: (message: string) => Promise<string>;
+  note: (message: string, title?: string) => Promise<void>;
+  log: (message: string) => void;
+  progress: { update: (msg: string) => void; stop: (msg?: string) => void };
+}): Promise<{
+  access: string;
+  refresh: string;
+  expires: number;
+  email?: string;
+  displayName?: string;
+}> {
+  const { verifier, challenge } = generatePkce();
+  const state = randomBytes(16).toString("hex");
+  const authUrl = buildAuthUrl({ challenge, state });
+
+  let callbackServer: Awaited<ReturnType<typeof startCallbackServer>> | null = null;
+  const needsManual = shouldUseManualOAuthFlow(params.isRemote);
+  if (!needsManual) {
+    try {
+      callbackServer = await startCallbackServer({ timeoutMs: 5 * 60 * 1000 });
+    } catch {
+      callbackServer = null;
+    }
+  }
+
+  if (!callbackServer) {
+    await params.note(
+      [
+        "Open the URL in your local browser.",
+        "After signing in, copy the full redirect URL and paste it back here.",
+        "",
+        `Auth URL: ${authUrl}`,
+        `Redirect URI: ${REDIRECT_URI}`,
+      ].join("\n"),
+      "Outlook OAuth",
+    );
+    params.log("");
+    params.log("Copy this URL:");
+    params.log(authUrl);
+    params.log("");
+  }
+
+  if (!needsManual) {
+    params.progress.update("Opening Microsoft sign-in...");
+    try {
+      await params.openUrl(authUrl);
+    } catch {
+      // ignore
+    }
+  }
+
+  let code = "";
+  let returnedState = "";
+
+  if (callbackServer) {
+    params.progress.update("Waiting for OAuth callback...");
+    const callback = await callbackServer.waitForCallback();
+    code = callback.searchParams.get("code") ?? "";
+    returnedState = callback.searchParams.get("state") ?? "";
+    await callbackServer.close();
+  } else {
+    params.progress.update("Waiting for redirect URL...");
+    const input = await params.prompt("Paste the redirect URL: ");
+    const parsed = parseCallbackInput(input);
+    if ("error" in parsed) {
+      throw new Error(parsed.error);
+    }
+    code = parsed.code;
+    returnedState = parsed.state;
+  }
+
+  if (!code) {
+    throw new Error("Missing OAuth code");
+  }
+  if (returnedState !== state) {
+    throw new Error("OAuth state mismatch. Please try again.");
+  }
+
+  params.progress.update("Exchanging code for tokens...");
+  const tokens = await exchangeCode({ code, verifier });
+  const profile = await fetchUserProfile(tokens.access);
+
+  params.progress.stop("Outlook OAuth complete");
+  return { ...tokens, ...profile };
+}