@runneth/cli 0.0.0-sha.3142666bf4dc.production

package/dist/oauth.js

@@ -0,0 +1,592 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import process from "node:process";
+import { resolveRunnethCliHome } from "./paths.js";
+const CALLBACK_PATH = "/oauth/callback";
+const DEFAULT_CLIENT_NAME = "Runneth MCP";
+const DEFAULT_SCOPE = "openid profile email offline_access";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const LOOPBACK_HOST = "localhost";
+const OAUTH_CREDENTIAL_PATH_SEGMENT_LENGTH = 120;
+const TOKEN_REFRESH_BUFFER_MS = 60_000;
+const isRecord = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+const isErrnoCode = (error, code) => {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+};
+const parseStringField = (record, key) => {
+    const value = record[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+};
+const parseOptionalStringField = (record, key) => {
+    const value = record[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+};
+const parseOptionalNumberField = (record, key) => {
+    const value = record[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a finite number`);
+    }
+    return value;
+};
+const parseStringArrayField = (record, key) => {
+    const value = record[key];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${key} must be a non-empty string array`);
+    }
+    for (const item of value) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new Error(`${key} must contain non-empty strings`);
+        }
+    }
+    return value;
+};
+const parseTokenEndpointAuthMethod = (value) => {
+    switch (value) {
+        case "client_secret_basic":
+        case "client_secret_post":
+        case "none": {
+            return value;
+        }
+        default: {
+            throw new Error(`Unsupported token_endpoint_auth_method: ${value}`);
+        }
+    }
+};
+const toBase64Url = (buffer) => {
+    return buffer.toString("base64url");
+};
+const createPkcePair = () => {
+    const verifier = toBase64Url(randomBytes(32));
+    const challenge = toBase64Url(createHash("sha256").update(verifier).digest());
+    return { challenge, verifier };
+};
+const normalizeOAuthResourceUrl = (value) => {
+    const url = new URL(value);
+    url.hash = "";
+    url.search = "";
+    if (url.pathname !== "/") {
+        url.pathname = url.pathname.replace(/\/+$/u, "");
+    }
+    return url.toString();
+};
+const encodeOAuthCredentialPathSegments = (resourceUrl) => {
+    const encodedResourceUrl = Buffer.from(resourceUrl, "utf8").toString("base64url");
+    const segments = [];
+    for (let index = 0; index < encodedResourceUrl.length; index += OAUTH_CREDENTIAL_PATH_SEGMENT_LENGTH) {
+        segments.push(encodedResourceUrl.slice(index, index + OAUTH_CREDENTIAL_PATH_SEGMENT_LENGTH));
+    }
+    const fileName = segments.pop();
+    if (fileName === undefined) {
+        throw new Error("OAuth resource URL did not produce a credential path");
+    }
+    return [...segments, `${fileName}.json`];
+};
+const metadataPathForUrl = (value, metadataName) => {
+    const url = new URL(value);
+    const pathname = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "");
+    return `${url.origin}/.well-known/${metadataName}${pathname}`;
+};
+const fetchJsonObject = async (url, init, label) => {
+    const response = await fetch(url, init);
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`${label} failed with HTTP ${String(response.status)}: ${body}`);
+    }
+    const parsed = (await response.json());
+    if (!isRecord(parsed)) {
+        throw new Error(`${label} returned a non-object JSON response`);
+    }
+    return parsed;
+};
+const discoverProtectedResource = async (resourceUrl) => {
+    const metadataUrl = metadataPathForUrl(resourceUrl, "oauth-protected-resource");
+    const metadata = await fetchJsonObject(metadataUrl, {
+        headers: {
+            Accept: "application/json",
+        },
+    }, "OAuth protected resource metadata request");
+    return {
+        authorizationServers: parseStringArrayField(metadata, "authorization_servers"),
+        resource: parseStringField(metadata, "resource"),
+    };
+};
+const discoverAuthorizationServer = async (issuerUrl) => {
+    const metadataUrl = metadataPathForUrl(issuerUrl, "oauth-authorization-server");
+    const metadata = await fetchJsonObject(metadataUrl, {
+        headers: {
+            Accept: "application/json",
+        },
+    }, "OAuth authorization server metadata request");
+    return {
+        authorizationEndpoint: parseStringField(metadata, "authorization_endpoint"),
+        issuer: parseStringField(metadata, "issuer"),
+        registrationEndpoint: parseStringField(metadata, "registration_endpoint"),
+        tokenEndpoint: parseStringField(metadata, "token_endpoint"),
+    };
+};
+export const resolveOAuthCredentialPath = (input) => {
+    const homePath = input.homePath ?? resolveRunnethCliHome();
+    const resourceUrl = normalizeOAuthResourceUrl(input.resourceUrl);
+    return path.join(homePath, "oauth", ...encodeOAuthCredentialPathSegments(resourceUrl));
+};
+const writeOAuthCredential = async (input) => {
+    await mkdir(path.dirname(input.credentialPath), {
+        mode: 0o700,
+        recursive: true,
+    });
+    await writeFile(input.credentialPath, `${JSON.stringify(input.credential, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    if (process.platform !== "win32") {
+        await chmod(input.credentialPath, 0o600);
+    }
+};
+const parseStoredCredential = (value) => {
+    if (!isRecord(value)) {
+        throw new Error("Stored OAuth credential must be a JSON object");
+    }
+    if (value.version !== 1) {
+        throw new Error("Stored OAuth credential has an unsupported version");
+    }
+    const authorizationServerValue = value.authorizationServer;
+    const clientValue = value.client;
+    const tokenValue = value.token;
+    if (!isRecord(authorizationServerValue)) {
+        throw new Error("Stored OAuth credential authorizationServer must be an object");
+    }
+    if (!isRecord(clientValue)) {
+        throw new Error("Stored OAuth credential client must be an object");
+    }
+    if (!isRecord(tokenValue)) {
+        throw new Error("Stored OAuth credential token must be an object");
+    }
+    return {
+        authorizationServer: {
+            authorizationEndpoint: parseStringField(authorizationServerValue, "authorizationEndpoint"),
+            issuer: parseStringField(authorizationServerValue, "issuer"),
+            registrationEndpoint: parseStringField(authorizationServerValue, "registrationEndpoint"),
+            tokenEndpoint: parseStringField(authorizationServerValue, "tokenEndpoint"),
+        },
+        client: {
+            clientId: parseStringField(clientValue, "clientId"),
+            clientName: parseStringField(clientValue, "clientName"),
+            clientSecret: parseOptionalStringField(clientValue, "clientSecret"),
+            redirectUri: parseStringField(clientValue, "redirectUri"),
+            tokenEndpointAuthMethod: parseTokenEndpointAuthMethod(parseStringField(clientValue, "tokenEndpointAuthMethod")),
+        },
+        createdAt: parseStringField(value, "createdAt"),
+        requestedResourceUrl: parseStringField(value, "requestedResourceUrl"),
+        resource: parseStringField(value, "resource"),
+        scope: parseStringField(value, "scope"),
+        token: {
+            accessToken: parseStringField(tokenValue, "accessToken"),
+            expiresAt: parseOptionalStringField(tokenValue, "expiresAt"),
+            idToken: parseOptionalStringField(tokenValue, "idToken"),
+            refreshToken: parseOptionalStringField(tokenValue, "refreshToken"),
+            scope: parseOptionalStringField(tokenValue, "scope"),
+            tokenType: parseStringField(tokenValue, "tokenType"),
+        },
+        updatedAt: parseStringField(value, "updatedAt"),
+        version: 1,
+    };
+};
+export const readOAuthCredential = async (input) => {
+    const credentialPath = resolveOAuthCredentialPath(input);
+    try {
+        const raw = await readFile(credentialPath, "utf8");
+        return parseStoredCredential(JSON.parse(raw));
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            return null;
+        }
+        throw error;
+    }
+};
+export const readOAuthCredentialStatus = async (input) => {
+    const credentialPath = resolveOAuthCredentialPath(input);
+    const requestedResourceUrl = normalizeOAuthResourceUrl(input.resourceUrl);
+    const credential = await readOAuthCredential(input);
+    if (credential === null) {
+        return {
+            authenticated: false,
+            credentialPath,
+            requestedResourceUrl,
+        };
+    }
+    return {
+        authenticated: true,
+        clientId: credential.client.clientId,
+        credentialPath,
+        expiresAt: credential.token.expiresAt,
+        requestedResourceUrl,
+        resource: credential.resource,
+        scope: credential.token.scope ?? credential.scope,
+        tokenType: credential.token.tokenType,
+    };
+};
+export const logoutOAuthCredential = async (input) => {
+    const credentialPath = resolveOAuthCredentialPath(input);
+    await rm(credentialPath, { force: true });
+    return {
+        authenticated: false,
+        credentialPath,
+        requestedResourceUrl: normalizeOAuthResourceUrl(input.resourceUrl),
+    };
+};
+const startLoopbackCallbackServer = async () => {
+    let settleAuthorization;
+    let rejectAuthorization;
+    const waitForAuthorization = new Promise((resolve, reject) => {
+        settleAuthorization = resolve;
+        rejectAuthorization = reject;
+    });
+    const server = http.createServer((req, res) => {
+        const host = req.headers.host;
+        if (host === undefined || req.url === undefined) {
+            res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Invalid OAuth callback request.\n");
+            rejectAuthorization?.(new Error("Invalid OAuth callback request"));
+            return;
+        }
+        const callbackUrl = new URL(req.url, `http://${host}`);
+        if (callbackUrl.pathname !== CALLBACK_PATH) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("OAuth callback path not found.\n");
+            return;
+        }
+        const error = callbackUrl.searchParams.get("error");
+        if (error !== null) {
+            const description = callbackUrl.searchParams.get("error_description");
+            res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("OAuth authorization failed.\n");
+            rejectAuthorization?.(new Error(description === null
+                ? `OAuth authorization failed: ${error}`
+                : description));
+            return;
+        }
+        const code = callbackUrl.searchParams.get("code");
+        const state = callbackUrl.searchParams.get("state");
+        if (code === null || state === null) {
+            res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("OAuth callback is missing code or state.\n");
+            rejectAuthorization?.(new Error("OAuth callback is missing code or state"));
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("OAuth authorization complete. You can return to runneth-cli.\n");
+        settleAuthorization?.({
+            code,
+            issuer: callbackUrl.searchParams.get("iss") ?? undefined,
+            state,
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, LOOPBACK_HOST, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("OAuth callback server did not bind to a TCP port");
+    }
+    return {
+        close: async () => {
+            await closeServer(server);
+        },
+        redirectUri: `http://${LOOPBACK_HOST}:${String(address.port)}${CALLBACK_PATH}`,
+        waitForAuthorization,
+    };
+};
+const closeServer = async (server) => {
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+};
+const registerOAuthClient = async (input) => {
+    const response = await fetchJsonObject(input.metadata.registrationEndpoint, {
+        body: JSON.stringify({
+            client_name: input.clientName,
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [input.redirectUri],
+            response_types: ["code"],
+            scope: input.scope,
+            token_endpoint_auth_method: "none",
+            type: "native",
+        }),
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+    }, "OAuth dynamic client registration");
+    return {
+        clientId: parseStringField(response, "client_id"),
+        clientName: input.clientName,
+        clientSecret: parseOptionalStringField(response, "client_secret"),
+        redirectUri: input.redirectUri,
+        tokenEndpointAuthMethod: parseTokenEndpointAuthMethod(parseStringField(response, "token_endpoint_auth_method")),
+    };
+};
+const openSystemBrowser = async (url) => {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+};
+const buildAuthorizationUrl = (input) => {
+    const authorizationUrl = new URL(input.metadata.authorizationEndpoint);
+    authorizationUrl.searchParams.set("client_id", input.client.clientId);
+    authorizationUrl.searchParams.set("code_challenge", input.pkceChallenge);
+    authorizationUrl.searchParams.set("code_challenge_method", "S256");
+    authorizationUrl.searchParams.set("redirect_uri", input.client.redirectUri);
+    authorizationUrl.searchParams.set("response_type", "code");
+    authorizationUrl.searchParams.set("scope", input.scope);
+    authorizationUrl.searchParams.set("prompt", "consent");
+    authorizationUrl.searchParams.set("state", input.state);
+    return authorizationUrl.toString();
+};
+const waitForAuthorizationCallback = async (waitForAuthorization, timeoutMs) => {
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(`Timed out waiting for OAuth authorization after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([waitForAuthorization, timeoutPromise]);
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
+        }
+    }
+};
+const parseTokenResponse = (response, nowMs) => {
+    const rawToken = {
+        access_token: parseStringField(response, "access_token"),
+        expires_at: parseOptionalNumberField(response, "expires_at"),
+        expires_in: parseOptionalNumberField(response, "expires_in"),
+        id_token: parseOptionalStringField(response, "id_token"),
+        refresh_token: parseOptionalStringField(response, "refresh_token"),
+        scope: parseOptionalStringField(response, "scope"),
+        token_type: parseStringField(response, "token_type"),
+    };
+    const expiresAt = rawToken.expires_at === undefined
+        ? rawToken.expires_in === undefined
+            ? undefined
+            : new Date(nowMs + rawToken.expires_in * 1000).toISOString()
+        : new Date(rawToken.expires_at * 1000).toISOString();
+    return {
+        accessToken: rawToken.access_token,
+        expiresAt,
+        idToken: rawToken.id_token,
+        refreshToken: rawToken.refresh_token,
+        scope: rawToken.scope,
+        tokenType: rawToken.token_type,
+    };
+};
+const requestOAuthToken = async (input) => {
+    const body = new URLSearchParams({
+        client_id: input.client.clientId,
+        code: input.code,
+        code_verifier: input.codeVerifier,
+        grant_type: "authorization_code",
+        redirect_uri: input.redirectUri,
+        resource: input.resource,
+    });
+    if (input.client.clientSecret !== undefined) {
+        body.set("client_secret", input.client.clientSecret);
+    }
+    const response = await fetchJsonObject(input.metadata.tokenEndpoint, {
+        body,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        method: "POST",
+    }, "OAuth token request");
+    return parseTokenResponse(response, Date.now());
+};
+const refreshOAuthToken = async (input) => {
+    if (input.credential.token.refreshToken === undefined) {
+        throw new Error("Stored OAuth credential is expired and has no refresh token");
+    }
+    const body = new URLSearchParams({
+        client_id: input.credential.client.clientId,
+        grant_type: "refresh_token",
+        refresh_token: input.credential.token.refreshToken,
+        resource: input.credential.resource,
+        scope: input.credential.scope,
+    });
+    if (input.credential.client.clientSecret !== undefined) {
+        body.set("client_secret", input.credential.client.clientSecret);
+    }
+    const response = await fetchJsonObject(input.credential.authorizationServer.tokenEndpoint, {
+        body,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        method: "POST",
+    }, "OAuth refresh token request");
+    const refreshed = parseTokenResponse(response, Date.now());
+    return {
+        ...refreshed,
+        refreshToken: refreshed.refreshToken ?? input.credential.token.refreshToken,
+    };
+};
+const tokenIsFresh = (token) => {
+    if (token.expiresAt === undefined) {
+        return true;
+    }
+    return (new Date(token.expiresAt).getTime() - Date.now() > TOKEN_REFRESH_BUFFER_MS);
+};
+export const loginWithOAuth = async (options) => {
+    const requestedResourceUrl = normalizeOAuthResourceUrl(options.resourceUrl);
+    const scope = options.scope?.trim() || DEFAULT_SCOPE;
+    const clientName = options.clientName?.trim() || DEFAULT_CLIENT_NAME;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const callbackServer = await startLoopbackCallbackServer();
+    const credentialPath = resolveOAuthCredentialPath({
+        homePath: options.homePath,
+        resourceUrl: requestedResourceUrl,
+    });
+    try {
+        const protectedResource = await discoverProtectedResource(requestedResourceUrl);
+        const authorizationServer = await discoverAuthorizationServer(protectedResource.authorizationServers[0]);
+        const client = await registerOAuthClient({
+            clientName,
+            metadata: authorizationServer,
+            redirectUri: callbackServer.redirectUri,
+            scope,
+        });
+        const state = toBase64Url(randomBytes(32));
+        const pkce = createPkcePair();
+        const authorizationUrl = buildAuthorizationUrl({
+            client,
+            metadata: authorizationServer,
+            pkceChallenge: pkce.challenge,
+            scope,
+            state,
+        });
+        await options.authorizationUrlHandler?.(authorizationUrl);
+        if (options.openBrowser ?? true) {
+            await openSystemBrowser(authorizationUrl);
+        }
+        const authorization = await waitForAuthorizationCallback(callbackServer.waitForAuthorization, timeoutMs);
+        if (authorization.state !== state) {
+            throw new Error("OAuth callback state did not match the authorization request");
+        }
+        if (authorization.issuer !== undefined &&
+            authorization.issuer !== authorizationServer.issuer) {
+            throw new Error("OAuth callback issuer did not match the authorization server metadata");
+        }
+        const token = await requestOAuthToken({
+            client,
+            code: authorization.code,
+            codeVerifier: pkce.verifier,
+            metadata: authorizationServer,
+            redirectUri: callbackServer.redirectUri,
+            resource: protectedResource.resource,
+        });
+        const now = new Date().toISOString();
+        const credential = {
+            authorizationServer,
+            client,
+            createdAt: now,
+            requestedResourceUrl,
+            resource: protectedResource.resource,
+            scope,
+            token,
+            updatedAt: now,
+            version: 1,
+        };
+        await writeOAuthCredential({ credential, credentialPath });
+        return {
+            accessToken: token.accessToken,
+            credential,
+            credentialPath,
+            expiresAt: token.expiresAt,
+            tokenType: token.tokenType,
+        };
+    }
+    finally {
+        await callbackServer.close();
+    }
+};
+export const getOAuthAccessToken = async (input) => {
+    const credentialPath = resolveOAuthCredentialPath(input);
+    const credential = await readOAuthCredential(input);
+    if (credential === null) {
+        throw new Error("No OAuth credential is stored for this resource");
+    }
+    if (tokenIsFresh(credential.token)) {
+        return {
+            accessToken: credential.token.accessToken,
+            credential,
+            credentialPath,
+            expiresAt: credential.token.expiresAt,
+            tokenType: credential.token.tokenType,
+        };
+    }
+    const refreshedToken = await refreshOAuthToken({ credential });
+    const refreshedCredential = {
+        ...credential,
+        token: refreshedToken,
+        updatedAt: new Date().toISOString(),
+    };
+    await writeOAuthCredential({
+        credential: refreshedCredential,
+        credentialPath,
+    });
+    return {
+        accessToken: refreshedToken.accessToken,
+        credential: refreshedCredential,
+        credentialPath,
+        expiresAt: refreshedToken.expiresAt,
+        tokenType: refreshedToken.tokenType,
+    };
+};

package/dist/paths.d.ts

@@ -0,0 +1,2 @@
+export declare const resolveRunnethCliHome: () => string;
+export declare const resolveSocketPath: (homePath?: string) => string;

package/dist/paths.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+export const resolveRunnethCliHome = () => {
+    const configured = process.env.RUNNETH_CLI_HOME?.trim();
+    return path.resolve(configured && configured.length > 0
+        ? configured
+        : path.join(os.homedir(), ".runneth-cli"));
+};
+export const resolveSocketPath = (homePath = resolveRunnethCliHome()) => {
+    const configured = process.env.RUNNETH_CLI_SOCKET?.trim();
+    if (configured && configured.length > 0) {
+        return configured;
+    }
+    const digest = createHash("sha256")
+        .update(path.resolve(homePath))
+        .digest("hex")
+        .slice(0, 16);
+    if (process.platform === "win32") {
+        return `\\\\.\\pipe\\runneth-cli-${digest}`;
+    }
+    const uid = typeof process.getuid === "function" ? String(process.getuid()) : "user";
+    return path.join(os.tmpdir(), `runneth-cli-${uid}-${digest}.sock`);
+};

package/dist/skills.d.ts

@@ -0,0 +1,15 @@
+export type RunnethSkillAgent = "claude" | "codex";
+export type RunnethSkillInstallTarget = Readonly<{
+    agent: RunnethSkillAgent;
+    path: string;
+}>;
+export type RunnethSkillInstallOptions = Readonly<{
+    agents?: readonly RunnethSkillAgent[];
+}>;
+export type RunnethSkillInstallResult = Readonly<{
+    skillName: string;
+    sourcePath: string;
+    targets: readonly RunnethSkillInstallTarget[];
+}>;
+export declare const resolveBundledRunnethSkillPath: () => string;
+export declare const installRunnethSkills: (options?: RunnethSkillInstallOptions) => Promise<RunnethSkillInstallResult>;