@jitsusama/agentic-harness.core 0.1.0

package/dist/slack/auth/browser-extract.js

@@ -0,0 +1,201 @@
+/**
+ * Automatic Slack credential extraction via browser.
+ *
+ * Launches Chrome (non-headless, using the user's existing
+ * install), navigates to Slack, and polls localStorage and
+ * cookies for the xoxc- token and xoxd- cookie. Works with
+ * any Slack workspace; the user just needs to be logged in
+ * (or log in when the browser opens).
+ *
+ * Uses puppeteer-core (no bundled browser) for consistency
+ * with web-search-integration.
+ */
+import * as fs from "node:fs";
+import puppeteer from "puppeteer-core";
+/**
+ * Default Slack URL to navigate to: the dedicated sign-in entry
+ * point, not the marketing homepage. app.slack.com used to be here
+ * instead, and it lands on a cookie-consent marketing page with no
+ * sign-in link visible without scrolling - a real run needed a
+ * person to find and click their own way to sign-in from there,
+ * which is what this URL skips.
+ */
+const DEFAULT_SLACK_URL = "https://slack.com/signin";
+/** Guidance printed once the browser opens, before the wait begins. */
+const SIGN_IN_GUIDANCE = [
+    "Opening Slack sign-in. To finish:",
+    "  1. Sign in with your email (or SSO) as usual.",
+    "  2. If asked to pick a workspace, click into the one you want.",
+    '  3. If a screen offers "Open Slack" (desktop app) vs "use Slack',
+    '     in your browser", click "use Slack in your browser" - this',
+    "     tries that automatically, but don't wait on it if it's slow.",
+    "This can take a few minutes depending on your organization's sign-in flow.",
+].join("\n");
+/** How often to poll for credentials (milliseconds). */
+const POLL_INTERVAL_MS = 1000;
+/** Default timeout: 5 minutes to allow for SSO, 2FA, workspace selection. */
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+/** Paths where Chrome might be installed. */
+const CHROME_PATHS = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+];
+/** Find the Chrome executable on disk. */
+function findChrome() {
+    const envPath = process.env.CHROME_PATH;
+    if (envPath && fs.existsSync(envPath))
+        return envPath;
+    for (const p of CHROME_PATHS) {
+        try {
+            if (fs.existsSync(p))
+                return p;
+        }
+        catch {
+            // Not at this path, try next.
+        }
+    }
+    throw new Error("Chrome not found. Install Google Chrome or set CHROME_PATH.");
+}
+/**
+ * Launch Chrome, navigate to Slack, and extract credentials.
+ *
+ * Opens a visible browser window so the user can log in if
+ * needed. Polls localStorage for the xoxc- token and the
+ * browser's cookie jar for the xoxd- session cookie.
+ *
+ * @param slackUrl - Slack URL to navigate to (default: the sign-in
+ *   entry point, not a workspace or the marketing homepage)
+ * @param timeoutMs - How long to wait before giving up
+ * @param onStep - Called once, right after the browser opens, with
+ *   the guidance a person watching needs to actually finish sign-in.
+ *   Adapter-supplied rather than written straight to stderr here, so
+ *   a host that isn't a bare terminal can surface it its own way.
+ */
+export async function extractFromBrowser(slackUrl = DEFAULT_SLACK_URL, timeoutMs = DEFAULT_TIMEOUT_MS, onStep) {
+    const chromePath = findChrome();
+    const browser = await puppeteer.launch({
+        executablePath: chromePath,
+        headless: false,
+        args: ["--no-sandbox", "--disable-setuid-sandbox"],
+    });
+    try {
+        const context = browser.defaultBrowserContext();
+        const page = (await browser.pages())[0] ?? (await browser.newPage());
+        await page.goto(slackUrl, { waitUntil: "domcontentloaded" });
+        onStep?.(SIGN_IN_GUIDANCE);
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            // Grab the most recent page, since Slack and SSO flows may open
+            // new tabs or navigate, destroying the original context.
+            const pages = await browser.pages();
+            const activePage = pages[pages.length - 1] ?? page;
+            // A workspace's own SSB redirect page (cloud-native.slack.com/
+            // ssb/redirect, and its equivalents) defaults to prompting for
+            // the desktop app, with a "use Slack in your browser" link as
+            // the only way to reach the web client instead. Nothing here
+            // wants the desktop app, and nothing clicks that link on its
+            // own, so a real run sat on that splash page for the whole
+            // five-minute budget until this was added.
+            await clickUseInBrowser(activePage);
+            // The cookie lives in the browser context, not the page,
+            // so it survives navigations. Check it first.
+            const cookies = await context.cookies();
+            const dCookie = cookies.find((c) => c.name === "d" && c.domain.includes("slack.com"));
+            const cookie = dCookie?.value;
+            // Try to read the token from localStorage. This fails during
+            // navigations (context destroyed) and on non-Slack pages
+            // (SSO provider). Both are expected, so we just retry.
+            const token = await extractTokenFromPage(activePage);
+            if (token?.startsWith("xoxc-") && cookie?.startsWith("xoxd-")) {
+                return { token, cookie };
+            }
+            await sleep(POLL_INTERVAL_MS);
+        }
+        throw new Error("Timed out waiting for Slack credentials. " +
+            "Make sure you are logged into Slack in the browser window, " +
+            "and that you have clicked into a specific workspace: a fresh " +
+            "browser profile has no session yet, so app.slack.com shows a " +
+            "workspace picker after sign-in rather than opening one directly, " +
+            "and nothing here is extractable until a workspace is open.");
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * Click a "use Slack in your browser" link if the active page is
+ * showing one, so the desktop-app splash page a workspace redirect
+ * lands on doesn't sit there indefinitely. A no-op, never throwing,
+ * on any page that isn't showing one (mid-navigation, cross-origin,
+ * or just a different page entirely).
+ *
+ * Dispatches a real mouse click at the link's on-screen position
+ * rather than calling the DOM `.click()` method in-page: the latter
+ * produces a synthetic event (`isTrusted: false`), which this splash
+ * page's own handler silently ignores, exactly the "nothing changes"
+ * a real run showed before this was found. A CDP-level mouse click
+ * is indistinguishable from one a person made.
+ */
+async function clickUseInBrowser(page) {
+    try {
+        const center = await page.evaluate(() => {
+            const links = Array.from(document.querySelectorAll("a"));
+            const match = links.find((a) => /use slack in (your|the) browser/i.test(a.textContent ?? ""));
+            if (!match)
+                return null;
+            const rect = match.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0)
+                return null;
+            return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+        });
+        if (center)
+            await page.mouse.click(center.x, center.y);
+    }
+    catch {
+        // Execution context destroyed, page closed, or cross-origin
+        // frame. Same as extractTokenFromPage: all expected, so the
+        // next poll just tries again.
+    }
+}
+/**
+ * Try to extract the xoxc- token from a page's localStorage.
+ *
+ * Returns null if the page isn't on Slack yet, is mid-navigation,
+ * or the execution context was destroyed. All expected during
+ * SSO flows.
+ */
+async function extractTokenFromPage(page) {
+    try {
+        return await page.evaluate(() => {
+            try {
+                const raw = localStorage.getItem("localConfig_v2");
+                if (!raw)
+                    return null;
+                const config = JSON.parse(raw);
+                const teams = config?.teams;
+                if (!teams)
+                    return null;
+                for (const t of Object.values(teams)) {
+                    const tok = t?.token;
+                    if (tok?.startsWith("xoxc-"))
+                        return tok;
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        });
+    }
+    catch {
+        // Execution context destroyed (navigation), page closed, or
+        // cross-origin frame (SSO provider). All expected, so retry.
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/slack/auth/browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cross-platform URL opener. Launches the system default browser.
+ */
+/** Open a URL in the user's default browser. */
+export declare function openInBrowser(url: string): void;

package/dist/slack/auth/browser.js

@@ -0,0 +1,25 @@
+/**
+ * Cross-platform URL opener. Launches the system default browser.
+ */
+import { execFile } from "node:child_process";
+/** Open a URL in the user's default browser. */
+export function openInBrowser(url) {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        execFile("open", [url], ignoreError);
+    }
+    else if (platform === "win32") {
+        execFile("cmd", ["/c", "start", url], ignoreError);
+    }
+    else {
+        execFile("xdg-open", [url], ignoreError);
+    }
+}
+/**
+ * Browser launch is best-effort. If it fails (e.g. headless
+ * server, missing xdg-open), the user can still copy the URL
+ * shown in the terminal.
+ */
+function ignoreError(_error) {
+    // Intentionally empty: URL is displayed as fallback.
+}

package/dist/slack/auth/credentials.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Token management: storing and retrieving Slack OAuth tokens.
+ */
+import type { StoredToken } from "../types.js";
+export type { OAuthApp } from "../types.js";
+export { getOAuthApp, hasOAuthApp, storeOAuthApp } from "./oauth-app.js";
+/** Store a Slack token after successful authentication. */
+export declare function storeToken(token: StoredToken): void;
+/** Retrieve the stored Slack token. */
+export declare function getToken(): StoredToken | null;
+/** Check whether a valid token exists. */
+export declare function hasToken(): boolean;
+/** Clear all Slack configuration (OAuth app + token). */
+export declare function clearAllConfig(): void;

package/dist/slack/auth/credentials.js

@@ -0,0 +1,24 @@
+/**
+ * Token management: storing and retrieving Slack OAuth tokens.
+ */
+import { readFile, writeFile } from "./store.js";
+export { getOAuthApp, hasOAuthApp, storeOAuthApp } from "./oauth-app.js";
+/** Store a Slack token after successful authentication. */
+export function storeToken(token) {
+    const data = readFile();
+    data.token = token;
+    writeFile(data);
+}
+/** Retrieve the stored Slack token. */
+export function getToken() {
+    return readFile().token ?? null;
+}
+/** Check whether a valid token exists. */
+export function hasToken() {
+    const token = getToken();
+    return !!(token?.accessToken && token?.userId);
+}
+/** Clear all Slack configuration (OAuth app + token). */
+export function clearAllConfig() {
+    writeFile({ oauthApp: null, token: null });
+}

package/dist/slack/auth/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formatting a Slack auth failure for a tool result.
+ *
+ * Split out of the interactive auth orchestration (which needs a
+ * host's UI to run the OAuth flow and stays adapter-local) because
+ * this part is pure: an error in, a message out.
+ */
+/** Format an auth error for the tool result. */
+export declare function formatAuthError(error: unknown): string;

package/dist/slack/auth/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Formatting a Slack auth failure for a tool result.
+ *
+ * Split out of the interactive auth orchestration (which needs a
+ * host's UI to run the OAuth flow and stays adapter-local) because
+ * this part is pure: an error in, a message out.
+ */
+/** Format an auth error for the tool result. */
+export function formatAuthError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("cancelled")) {
+        return ("⚠️ Authentication required but was cancelled.\n\n" +
+            "Run /slack-auth to authenticate with Slack.");
+    }
+    // Errors from describeError() already have a "Slack API error:" prefix.
+    if (message.startsWith("Slack API error:"))
+        return message;
+    return `Slack API error: ${message}`;
+}

package/dist/slack/auth/extract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Extract Slack credentials from a curl command or raw values.
+ *
+ * When users copy "Copy as cURL" from browser DevTools on any
+ * Slack API request, the curl command contains both the xoxc-
+ * token and xoxd- cookie. This module extracts them.
+ */
+/** Extracted browser session credentials. */
+export interface BrowserCredentials {
+    token: string;
+    cookie: string;
+}
+/**
+ * Extract xoxc- token and xoxd- cookie from a curl command string.
+ *
+ * Looks for token patterns in the body/headers and cookie patterns
+ * in the Cookie header. Throws if either is missing.
+ */
+export declare function extractFromCurl(curlCommand: string): BrowserCredentials;
+/** Validate that a token looks like a Slack token. */
+export declare function isValidToken(token: string): boolean;
+/** Validate that a cookie looks like a Slack session cookie. */
+export declare function isValidCookie(cookie: string): boolean;

package/dist/slack/auth/extract.js

@@ -0,0 +1,44 @@
+/**
+ * Extract Slack credentials from a curl command or raw values.
+ *
+ * When users copy "Copy as cURL" from browser DevTools on any
+ * Slack API request, the curl command contains both the xoxc-
+ * token and xoxd- cookie. This module extracts them.
+ */
+/**
+ * Extract xoxc- token and xoxd- cookie from a curl command string.
+ *
+ * Looks for token patterns in the body/headers and cookie patterns
+ * in the Cookie header. Throws if either is missing.
+ */
+export function extractFromCurl(curlCommand) {
+    // Find xoxc- tokens anywhere in the command.
+    const tokenPattern = /\b(xoxc-[a-zA-Z0-9-]{20,})/g;
+    const tokens = Array.from(curlCommand.matchAll(tokenPattern), (m) => m[1]);
+    // Find xoxd- cookies (usually after d= in a Cookie header).
+    const cookiePattern = /\bd=(xoxd-[^;"\s&)}']+)/g;
+    const cookies = Array.from(curlCommand.matchAll(cookiePattern), (m) => m[1]);
+    // Also try bare xoxd- values not preceded by d=.
+    if (cookies.length === 0) {
+        const barePattern = /\b(xoxd-[a-zA-Z0-9%/+=_-]{20,})/g;
+        const bare = Array.from(curlCommand.matchAll(barePattern), (m) => m[1]);
+        cookies.push(...bare);
+    }
+    if (tokens.length === 0) {
+        throw new Error("No Slack token (xoxc-...) found in the curl command. " +
+            "Make sure you copied a request to api.slack.com or edgeapi.slack.com.");
+    }
+    if (cookies.length === 0) {
+        throw new Error("No Slack cookie (xoxd-...) found in the curl command. " +
+            "Make sure you copied the full curl command including headers.");
+    }
+    return { token: tokens[0], cookie: cookies[0] };
+}
+/** Validate that a token looks like a Slack token. */
+export function isValidToken(token) {
+    return /^xox[cpb]-/.test(token);
+}
+/** Validate that a cookie looks like a Slack session cookie. */
+export function isValidCookie(cookie) {
+    return cookie.startsWith("xoxd-");
+}

package/dist/slack/auth/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Slack authentication: credential state and error formatting.
+ *
+ * `ensureAuthenticated` itself, the interactive orchestration that
+ * runs the setup wizard and/or OAuth web redirect flow, needs a
+ * host's UI and stays adapter-local; everything it is built from
+ * (credential storage, the OAuth exchange, the callback server, the
+ * browser opener, error formatting) lives here.
+ */
+export type { OAuthApp, StoredToken } from "../types.js";
+export { clearAllConfig, getOAuthApp, getToken, hasOAuthApp, hasToken, storeOAuthApp, storeToken, } from "./credentials.js";
+export { formatAuthError } from "./errors.js";

package/dist/slack/auth/index.js

@@ -0,0 +1,11 @@
+/**
+ * Slack authentication: credential state and error formatting.
+ *
+ * `ensureAuthenticated` itself, the interactive orchestration that
+ * runs the setup wizard and/or OAuth web redirect flow, needs a
+ * host's UI and stays adapter-local; everything it is built from
+ * (credential storage, the OAuth exchange, the callback server, the
+ * browser opener, error formatting) lives here.
+ */
+export { clearAllConfig, getOAuthApp, getToken, hasOAuthApp, hasToken, storeOAuthApp, storeToken, } from "./credentials.js";
+export { formatAuthError } from "./errors.js";

package/dist/slack/auth/oauth-app.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OAuth app credential management: storing and retrieving
+ * the Slack app's client ID and secret.
+ */
+import type { OAuthApp } from "../types.js";
+/** Store OAuth app credentials. */
+export declare function storeOAuthApp(credentials: OAuthApp): void;
+/** Retrieve OAuth app credentials. */
+export declare function getOAuthApp(): OAuthApp | null;
+/** Check if OAuth app credentials are configured. */
+export declare function hasOAuthApp(): boolean;

package/dist/slack/auth/oauth-app.js

@@ -0,0 +1,20 @@
+/**
+ * OAuth app credential management: storing and retrieving
+ * the Slack app's client ID and secret.
+ */
+import { readFile, writeFile } from "./store.js";
+/** Store OAuth app credentials. */
+export function storeOAuthApp(credentials) {
+    const data = readFile();
+    data.oauthApp = credentials;
+    writeFile(data);
+}
+/** Retrieve OAuth app credentials. */
+export function getOAuthApp() {
+    return readFile().oauthApp ?? null;
+}
+/** Check if OAuth app credentials are configured. */
+export function hasOAuthApp() {
+    const creds = getOAuthApp();
+    return !!(creds?.clientId && creds?.clientSecret);
+}

package/dist/slack/auth/oauth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Slack OAuth2 flow: web redirect with localhost callback.
+ *
+ * Slack user tokens (xoxp-) are long-lived and don't expire
+ * unless explicitly revoked, so there's no refresh logic.
+ * The flow:
+ *   1. Redirect user to Slack's authorization URL
+ *   2. Slack redirects back to localhost with a code
+ *   3. Exchange code for an access token via oauth.v2.access
+ */
+import type { OAuthApp, StoredToken } from "../types.js";
+/** Port for the local OAuth callback server. */
+export declare const CALLBACK_PORT = 8766;
+/** Redirect URI for the OAuth flow. */
+export declare const REDIRECT_URI = "http://localhost:8766";
+/**
+ * OAuth scopes required for the extension.
+ *
+ * These are user-level scopes (requested via user_scope, not
+ * bot scope) so the token acts as the authenticated user.
+ */
+export declare const SCOPES: string[];
+/** Build the Slack OAuth authorization URL. */
+export declare function buildAuthUrl(app: OAuthApp, state: string): string;
+/**
+ * Exchange an authorization code for a user access token.
+ *
+ * Calls Slack's oauth.v2.access endpoint and extracts the
+ * user token from the authed_user field.
+ */
+export declare function exchangeCodeForToken(app: OAuthApp, code: string): Promise<StoredToken>;

package/dist/slack/auth/oauth.js

@@ -0,0 +1,82 @@
+/**
+ * Slack OAuth2 flow: web redirect with localhost callback.
+ *
+ * Slack user tokens (xoxp-) are long-lived and don't expire
+ * unless explicitly revoked, so there's no refresh logic.
+ * The flow:
+ *   1. Redirect user to Slack's authorization URL
+ *   2. Slack redirects back to localhost with a code
+ *   3. Exchange code for an access token via oauth.v2.access
+ */
+/** Port for the local OAuth callback server. */
+export const CALLBACK_PORT = 8766;
+/** Redirect URI for the OAuth flow. */
+export const REDIRECT_URI = `http://localhost:${CALLBACK_PORT}`;
+/**
+ * OAuth scopes required for the extension.
+ *
+ * These are user-level scopes (requested via user_scope, not
+ * bot scope) so the token acts as the authenticated user.
+ */
+export const SCOPES = [
+    "search:read",
+    "channels:read",
+    "channels:history",
+    "groups:read",
+    "groups:history",
+    "im:read",
+    "im:history",
+    "mpim:read",
+    "mpim:history",
+    "chat:write",
+    "users:read",
+    "users.profile:read",
+    "reactions:read",
+    "reactions:write",
+];
+/** Build the Slack OAuth authorization URL. */
+export function buildAuthUrl(app, state) {
+    const params = new URLSearchParams({
+        client_id: app.clientId,
+        user_scope: SCOPES.join(","),
+        redirect_uri: REDIRECT_URI,
+        state,
+    });
+    return `https://slack.com/oauth/v2/authorize?${params.toString()}`;
+}
+/**
+ * Exchange an authorization code for a user access token.
+ *
+ * Calls Slack's oauth.v2.access endpoint and extracts the
+ * user token from the authed_user field.
+ */
+export async function exchangeCodeForToken(app, code) {
+    const response = await fetch("https://slack.com/api/oauth.v2.access", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            client_id: app.clientId,
+            client_secret: app.clientSecret,
+            code,
+            redirect_uri: REDIRECT_URI,
+        }),
+    });
+    const body = (await response.json());
+    if (!body.ok) {
+        const error = body.error ?? "unknown_error";
+        throw new Error(`Slack OAuth token exchange failed: ${error}`);
+    }
+    const authedUser = body.authed_user;
+    if (!authedUser?.access_token) {
+        throw new Error("Slack OAuth response missing authed_user.access_token. " +
+            "Make sure your app requests user_scope, not bot scope.");
+    }
+    const team = body.team;
+    return {
+        accessToken: authedUser.access_token,
+        userId: authedUser.id,
+        teamId: team?.id ?? "",
+        teamName: team?.name ?? undefined,
+        scopes: authedUser.scope ?? SCOPES.join(","),
+    };
+}

package/dist/slack/auth/server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local HTTP server for the Slack OAuth2 callback.
+ */
+/** Result from the local OAuth2 callback: either an auth code or an error. */
+export interface OAuthCallbackResult {
+    code?: string;
+    state?: string;
+    error?: string;
+}
+/**
+ * Start a local server to handle the Slack OAuth callback.
+ * Resolves when the callback arrives or times out.
+ */
+export declare function waitForOAuthCallback(port: number): Promise<OAuthCallbackResult>;

package/dist/slack/auth/server.js

@@ -0,0 +1,75 @@
+/**
+ * Local HTTP server for the Slack OAuth2 callback.
+ */
+import * as http from "node:http";
+/** Timeout before the OAuth callback server gives up (5 minutes). */
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const PAGE_STYLES = `
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+  padding: 3rem 1rem;
+  text-align: center;
+  color: #1a1a1a;
+  background: #fafafa;
+}
+@media (prefers-color-scheme: dark) {
+  body { color: #e0e0e0; background: #1a1a1a; }
+}`;
+const SUCCESS_PAGE = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Slack Authentication Successful</title>
+  <style>${PAGE_STYLES}</style>
+</head>
+<body>
+  <h1>✓ Slack Authentication Successful</h1>
+  <p>You can close this tab and return to Pi.</p>
+  <script>setTimeout(() => window.close(), 1500)</script>
+</body>
+</html>`;
+function errorPage(error) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Slack Authentication Failed</title>
+  <style>${PAGE_STYLES}</style>
+</head>
+<body>
+  <h1>✗ Slack Authentication Failed</h1>
+  <p>Error: ${error || "Unknown error"}</p>
+  <p>Please try again.</p>
+</body>
+</html>`;
+}
+/**
+ * Start a local server to handle the Slack OAuth callback.
+ * Resolves when the callback arrives or times out.
+ */
+export function waitForOAuthCallback(port) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url || "", `http://localhost:${port}`);
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(code ? SUCCESS_PAGE : errorPage(error || ""));
+            server.close();
+            resolve({
+                code: code || undefined,
+                state: state || undefined,
+                error: error || undefined,
+            });
+        });
+        server.on("error", (err) => {
+            reject(err);
+        });
+        server.listen(port, "localhost");
+        setTimeout(() => {
+            server.close();
+            reject(new Error("OAuth callback timeout after 5 minutes"));
+        }, CALLBACK_TIMEOUT_MS);
+    });
+}

package/dist/slack/auth/store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * File-based persistence for Slack credentials.
+ *
+ * Provides shared read/write primitives used by credentials
+ * and OAuth app modules. The credentials file's location is
+ * decided by paths.ts.
+ */
+import type { OAuthApp, StoredToken } from "../types.js";
+/** Shape of the persisted credentials file. */
+export interface CredentialsFile {
+    oauthApp?: OAuthApp | null;
+    token?: StoredToken | null;
+}
+/** Read the credentials file, returning defaults if missing or corrupt. */
+export declare function readFile(filePath?: string): CredentialsFile;
+/** Write the credentials file atomically. */
+export declare function writeFile(data: CredentialsFile, filePath?: string): void;