driggsby 0.0.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,8 @@
+UNLICENSED
+
+Copyright (c) The Good Software Company.
+All rights reserved.
+
+This package and its source are proprietary. No license rights are granted to
+use, copy, modify, or distribute this software except as otherwise agreed in
+writing by The Good Software Company.

package/README.md

@@ -0,0 +1,65 @@
+# driggsby
+
+`driggsby` installs the local Driggsby CLI and MCP broker.
+
+It gives local AI clients a single shared path into Driggsby:
+
+```text
+Codex / Claude Code / other local MCP client
+        |
+        v
+  driggsby mcp-server
+        |
+        v
+  shared local broker
+        |
+        v
+  remote Driggsby MCP
+```
+
+## Install
+
+```bash
+npm install -g driggsby
+```
+
+Node `20+` is required.
+
+## Commands
+
+```text
+driggsby login
+driggsby status
+driggsby mcp-server
+driggsby logout
+driggsby broker-daemon
+```
+
+Typical local setup:
+
+```bash
+driggsby login
+codex mcp add driggsby -- driggsby mcp-server
+```
+
+You can also use `npx -y driggsby ...` if you do not want a global install.
+
+## What It Does
+
+- opens a browser-based Driggsby sign-in flow
+- keeps one local broker session on the machine
+- exposes a local stdio MCP server for local AI clients
+- forwards supported Driggsby MCP tools through the broker
+
+## Security
+
+- publishes from GitHub Actions using npm trusted publishing and OIDC
+- does not require a long-lived npm publish token for releases
+- keeps local broker session material in the platform secret store
+
+## License
+
+This package is currently published as `UNLICENSED`.
+
+No license rights are granted beyond what The Good Software Company agrees to in
+writing.

package/dist/auth/browser.js

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+export async function openBrowserUrl(url) {
+    const command = browserCommandForPlatform(process.platform, url);
+    if (command === null) {
+        return false;
+    }
+    return await new Promise((resolve) => {
+        const child = spawn(command.file, command.args, {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.once("error", () => {
+            resolve(false);
+        });
+        child.once("spawn", () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}
+function browserCommandForPlatform(platform, url) {
+    switch (platform) {
+        case "darwin":
+            return { file: "open", args: [url] };
+        case "win32":
+            return { file: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { file: "xdg-open", args: [url] };
+    }
+}

package/dist/auth/config.js

@@ -0,0 +1,23 @@
+import { assertBrokerRemoteUrl } from "./url-security.js";
+const DEFAULT_REMOTE_BASE_URL = "https://app.driggsby.com";
+const DEFAULT_SCOPE = "driggsby.read";
+const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1_000;
+const DEFAULT_CLIENT_NAME = "Driggsby Local Broker";
+export function resolveBrokerAuthConfig(env = process.env) {
+    const remoteBaseUrl = normalizeBaseUrl(env["DRIGGSBY_REMOTE_BASE_URL"] ?? DEFAULT_REMOTE_BASE_URL);
+    return {
+        clientName: DEFAULT_CLIENT_NAME,
+        loginTimeoutMs: DEFAULT_LOGIN_TIMEOUT_MS,
+        protectedResourceMetadataUrl: new URL("/.well-known/oauth-protected-resource", remoteBaseUrl).toString(),
+        requestedScope: DEFAULT_SCOPE,
+        remoteBaseUrl,
+    };
+}
+function normalizeBaseUrl(rawValue) {
+    const parsed = new URL(rawValue);
+    assertBrokerRemoteUrl(parsed.toString(), "The Driggsby remote base URL");
+    parsed.pathname = "/";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, "");
+}

package/dist/auth/discovery.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+const protectedResourceMetadataSchema = z.object({
+    authorization_server: z.url(),
+    authorization_servers: z.array(z.url()),
+    resource: z.url(),
+    scopes_supported: z.array(z.string().min(1)),
+});
+const authorizationServerMetadataSchema = z.object({
+    authorization_endpoint: z.url(),
+    code_challenge_methods_supported: z.array(z.string().min(1)),
+    dpop_signing_alg_values_supported: z.array(z.string().min(1)),
+    grant_types_supported: z.array(z.string().min(1)),
+    issuer: z.url(),
+    registration_endpoint: z.url(),
+    response_types_supported: z.array(z.string().min(1)),
+    scopes_supported: z.array(z.string().min(1)),
+    token_endpoint: z.url(),
+    token_endpoint_auth_methods_supported: z.array(z.string().min(1)),
+});
+export async function fetchProtectedResourceMetadata(url, fetchImpl = fetch) {
+    const response = await fetchImpl(url, {
+        headers: {
+            accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error("Driggsby sign-in could not load the protected-resource metadata.");
+    }
+    return protectedResourceMetadataSchema.parse(await response.json());
+}
+export async function fetchAuthorizationServerMetadata(issuer, fetchImpl = fetch) {
+    const url = new URL("/.well-known/oauth-authorization-server", issuer).toString();
+    const response = await fetchImpl(url, {
+        headers: {
+            accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error("Driggsby sign-in could not load the authorization-server metadata.");
+    }
+    return authorizationServerMetadataSchema.parse(await response.json());
+}

package/dist/auth/dpop.js

@@ -0,0 +1,44 @@
+import { calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK, SignJWT, } from "jose";
+import { createHash, randomUUID } from "node:crypto";
+export async function generateDpopKeyMaterial() {
+    const { privateKey, publicKey } = await generateKeyPair("ES256", {
+        extractable: true,
+    });
+    const privateJwk = await exportJWK(privateKey);
+    const publicJwk = await exportJWK(publicKey);
+    const thumbprint = await calculateJwkThumbprint(publicJwk, "sha256");
+    return {
+        algorithm: "ES256",
+        createdAt: new Date().toISOString(),
+        privateJwk,
+        publicJwk,
+        thumbprint,
+    };
+}
+export async function createDpopProof(options) {
+    const signingKey = await importJWK(options.privateJwk, "ES256");
+    const payload = {
+        htm: options.httpMethod.toUpperCase(),
+        htu: normalizeDpopTargetUrl(options.targetUrl),
+    };
+    if (options.accessToken !== undefined) {
+        payload["ath"] = createHash("sha256")
+            .update(options.accessToken)
+            .digest("base64url");
+    }
+    return await new SignJWT(payload)
+        .setProtectedHeader({
+        alg: "ES256",
+        typ: "dpop+jwt",
+        jwk: options.publicJwk,
+    })
+        .setIssuedAt()
+        .setJti(randomUUID())
+        .sign(signingKey);
+}
+export function normalizeDpopTargetUrl(targetUrl) {
+    const url = new URL(targetUrl);
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}

package/dist/auth/login.js

@@ -0,0 +1,125 @@
+import { writeBrokerRemoteSession, } from "../broker/session.js";
+import { ensureBrokerInstallation, readBrokerDpopKeyPair, } from "../broker/installation.js";
+import { openBrowserUrl } from "./browser.js";
+import { resolveBrokerAuthConfig, } from "./config.js";
+import { fetchAuthorizationServerMetadata, fetchProtectedResourceMetadata, } from "./discovery.js";
+import { createDpopProof } from "./dpop.js";
+import { startLoopbackAuthListener } from "./loopback.js";
+import { buildAuthorizationUrl, createOAuthState, exchangeAuthorizationCode, registerBrokerClient, } from "./oauth.js";
+import { generatePkcePair } from "./pkce.js";
+import { assertBrokerRemoteUrl } from "./url-security.js";
+export async function loginBroker(runtimePaths, dependencies) {
+    const config = dependencies.config ?? resolveBrokerAuthConfig();
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const openUrl = dependencies.openUrl ?? openBrowserUrl;
+    const metadata = await ensureBrokerInstallation(runtimePaths, dependencies.secretStore);
+    const protectedResourceMetadata = await fetchProtectedResourceMetadata(config.protectedResourceMetadataUrl, fetchImpl);
+    const authorizationServerMetadata = await fetchAuthorizationServerMetadata(protectedResourceMetadata.authorization_server, fetchImpl);
+    validateRemoteMetadata(authorizationServerMetadata, protectedResourceMetadata);
+    const listener = await startLoopbackAuthListener(config.loginTimeoutMs);
+    try {
+        const registration = await registerBrokerClient({
+            clientName: config.clientName,
+            dpopBoundAccessTokens: true,
+            metadata: authorizationServerMetadata,
+            redirectUri: listener.redirectUri,
+            requestedScope: config.requestedScope,
+        }, fetchImpl);
+        const pkce = generatePkcePair();
+        const state = createOAuthState();
+        const signInUrl = buildAuthorizationUrl({
+            clientId: registration.clientId,
+            metadata: authorizationServerMetadata,
+            pkceChallenge: pkce.challenge,
+            redirectUri: listener.redirectUri,
+            requestedScope: config.requestedScope,
+            resource: protectedResourceMetadata,
+            state,
+        });
+        const browserOpened = await openUrl(signInUrl);
+        dependencies.onBrowserPrompt?.({
+            browserOpened,
+            signInUrl,
+        });
+        const callback = await listener.waitForResult();
+        if (!callback.ok) {
+            throw new Error(callback.value.errorDescription ??
+                "Driggsby sign-in was not completed.");
+        }
+        if (callback.value.state !== state) {
+            throw new Error("Driggsby sign-in returned an invalid state value. Try again.");
+        }
+        const tokenPair = await exchangeAuthorizationCode({
+            clientId: registration.clientId,
+            code: callback.value.code,
+            codeVerifier: pkce.verifier,
+            dpopProof: await tokenEndpointDpopProof(runtimePaths, dependencies.secretStore, metadata.brokerId, authorizationServerMetadata.token_endpoint),
+            metadata: authorizationServerMetadata,
+            redirectUri: listener.redirectUri,
+            resource: protectedResourceMetadata,
+        }, fetchImpl);
+        const session = {
+            schemaVersion: 1,
+            accessToken: tokenPair.accessToken,
+            accessTokenExpiresAt: tokenPair.accessTokenExpiresAt,
+            authenticatedAt: new Date().toISOString(),
+            clientId: registration.clientId,
+            issuer: authorizationServerMetadata.issuer,
+            redirectUri: listener.redirectUri,
+            refreshToken: tokenPair.refreshToken,
+            resource: protectedResourceMetadata.resource,
+            scope: tokenPair.scope,
+            tokenType: tokenPair.tokenType,
+        };
+        await writeBrokerRemoteSession(dependencies.secretStore, metadata.brokerId, session);
+        return {
+            browserOpened,
+            brokerId: metadata.brokerId,
+            dpopThumbprint: metadata.dpop.thumbprint,
+            session,
+            signInUrl,
+        };
+    }
+    finally {
+        await listener.close();
+    }
+}
+function validateRemoteMetadata(authorizationServerMetadata, protectedResourceMetadata) {
+    assertBrokerRemoteUrl(protectedResourceMetadata.authorization_server, "The Driggsby authorization server URL");
+    assertBrokerRemoteUrl(protectedResourceMetadata.resource, "The Driggsby MCP resource URL");
+    assertBrokerRemoteUrl(authorizationServerMetadata.issuer, "The Driggsby issuer URL");
+    assertBrokerRemoteUrl(authorizationServerMetadata.authorization_endpoint, "The Driggsby authorization endpoint");
+    assertBrokerRemoteUrl(authorizationServerMetadata.registration_endpoint, "The Driggsby registration endpoint");
+    assertBrokerRemoteUrl(authorizationServerMetadata.token_endpoint, "The Driggsby token endpoint");
+    if (!authorizationServerMetadata.code_challenge_methods_supported.includes("S256")) {
+        throw new Error("Driggsby sign-in requires S256 PKCE support.");
+    }
+    if (!authorizationServerMetadata.dpop_signing_alg_values_supported.includes("ES256")) {
+        throw new Error("Driggsby sign-in requires ES256 DPoP support.");
+    }
+    if (!authorizationServerMetadata.grant_types_supported.includes("authorization_code")) {
+        throw new Error("Driggsby sign-in requires authorization code grant support.");
+    }
+    if (!authorizationServerMetadata.response_types_supported.includes("code")) {
+        throw new Error("Driggsby sign-in requires code response support.");
+    }
+    if (!authorizationServerMetadata.token_endpoint_auth_methods_supported.includes("none")) {
+        throw new Error("Driggsby sign-in requires public client token exchange support.");
+    }
+    if (!authorizationServerMetadata.scopes_supported.includes("driggsby.read") ||
+        !protectedResourceMetadata.scopes_supported.includes("driggsby.read")) {
+        throw new Error("Driggsby sign-in requires the driggsby.read scope to be available.");
+    }
+}
+async function tokenEndpointDpopProof(runtimePaths, secretStore, brokerId, tokenEndpoint) {
+    const dpopKeyPair = await readBrokerDpopKeyPair(runtimePaths, secretStore, brokerId);
+    if (dpopKeyPair === null) {
+        throw new Error("The local broker DPoP key is missing. Run `npx -y driggsby login` again.");
+    }
+    return await createDpopProof({
+        httpMethod: "POST",
+        privateJwk: dpopKeyPair.privateJwk,
+        publicJwk: dpopKeyPair.publicJwk,
+        targetUrl: tokenEndpoint,
+    });
+}

package/dist/auth/loopback.js

@@ -0,0 +1,157 @@
+import http from "node:http";
+export async function startLoopbackAuthListener(timeoutMs) {
+    let settled = false;
+    let resolveResult = null;
+    let rejectResult = null;
+    const sockets = new Set();
+    const resultPromise = new Promise((resolve, reject) => {
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    const server = http.createServer((request, response) => {
+        if (request.url === undefined) {
+            respondWithHtml(response, "Driggsby sign-in failed.", false);
+            settleError({
+                error: "invalid_request",
+                errorDescription: "The browser callback was missing a request URL.",
+            });
+            return;
+        }
+        const callbackUrl = new URL(request.url, "http://127.0.0.1");
+        const code = callbackUrl.searchParams.get("code");
+        const state = callbackUrl.searchParams.get("state");
+        const error = callbackUrl.searchParams.get("error");
+        const errorDescription = callbackUrl.searchParams.get("error_description");
+        if (error !== null) {
+            respondWithHtml(response, "Driggsby sign-in was not completed. You can close this tab.", false);
+            const authorizationError = {
+                error,
+            };
+            if (errorDescription !== null) {
+                Object.assign(authorizationError, {
+                    errorDescription,
+                });
+            }
+            if (state !== null) {
+                Object.assign(authorizationError, {
+                    state,
+                });
+            }
+            settleError(authorizationError);
+            return;
+        }
+        if (code === null || state === null) {
+            respondWithHtml(response, "Driggsby sign-in failed.", false);
+            settleError({
+                error: "invalid_request",
+                errorDescription: "The browser callback was missing the authorization code or state.",
+            });
+            return;
+        }
+        respondWithHtml(response, "Driggsby is connected. You can return to your MCP client now.", true);
+        settleSuccess({
+            code,
+            state,
+        });
+    });
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.on("close", () => {
+            sockets.delete(socket);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server, sockets);
+        throw new Error("Driggsby could not start the local login callback listener.");
+    }
+    const timeoutHandle = setTimeout(() => {
+        void closeServer(server, sockets);
+        rejectResult?.(new Error("Driggsby sign-in timed out before the browser finished connecting."));
+    }, timeoutMs);
+    timeoutHandle.unref();
+    return {
+        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        async close() {
+            clearTimeoutIfPresent(timeoutHandle);
+            await closeServer(server, sockets);
+        },
+        async waitForResult() {
+            return await resultPromise;
+        },
+    };
+    function settleSuccess(value) {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeoutIfPresent(timeoutHandle);
+        void closeServer(server, sockets);
+        resolveResult?.({
+            ok: true,
+            value,
+        });
+    }
+    function settleError(value) {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeoutIfPresent(timeoutHandle);
+        void closeServer(server, sockets);
+        resolveResult?.({
+            ok: false,
+            value,
+        });
+    }
+}
+async function closeServer(server, sockets) {
+    if (!server.listening) {
+        destroyTrackedSockets(sockets);
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+        server.closeIdleConnections();
+        destroyTrackedSockets(sockets);
+    });
+}
+function destroyTrackedSockets(sockets) {
+    for (const socket of sockets) {
+        socket.destroy();
+    }
+    sockets.clear();
+}
+function clearTimeoutIfPresent(timeoutHandle) {
+    if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+    }
+}
+function respondWithHtml(response, message, success) {
+    response.statusCode = success ? 200 : 400;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    response.end(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Driggsby</title>
+  </head>
+  <body>
+    <main>
+      <h1>${success ? "Driggsby connected" : "Driggsby sign-in stopped"}</h1>
+      <p>${message}</p>
+    </main>
+  </body>
+</html>`);
+}

package/dist/auth/oauth.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+const registrationResponseSchema = z.object({
+    client_id: z.string().min(1),
+    scope: z.string().min(1),
+});
+const tokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    expires_in: z.number().int().positive(),
+    refresh_token: z.string().min(1).optional(),
+    scope: z.string().min(1),
+    token_type: z.enum(["Bearer", "DPoP"]),
+});
+export async function registerBrokerClient(options, fetchImpl = fetch) {
+    const response = await fetchImpl(options.metadata.registration_endpoint, {
+        body: JSON.stringify({
+            client_name: options.clientName,
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [options.redirectUri],
+            response_types: ["code"],
+            scope: options.requestedScope,
+            dpop_bound_access_tokens: options.dpopBoundAccessTokens,
+            token_endpoint_auth_method: "none",
+        }),
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        method: "POST",
+    });
+    if (!response.ok) {
+        throw new Error("Driggsby sign-in could not register the local broker with the remote service.");
+    }
+    const parsed = registrationResponseSchema.parse(await response.json());
+    return {
+        clientId: parsed.client_id,
+        scope: parsed.scope,
+    };
+}
+export function buildAuthorizationUrl(options) {
+    const url = new URL(options.metadata.authorization_endpoint);
+    url.searchParams.set("client_id", options.clientId);
+    url.searchParams.set("redirect_uri", options.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", options.requestedScope);
+    url.searchParams.set("resource", options.resource.resource);
+    url.searchParams.set("state", options.state);
+    url.searchParams.set("code_challenge", options.pkceChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return url.toString();
+}
+export async function exchangeAuthorizationCode(options, fetchImpl = fetch) {
+    const response = await fetchImpl(options.metadata.token_endpoint, {
+        body: new URLSearchParams({
+            client_id: options.clientId,
+            code: options.code,
+            code_verifier: options.codeVerifier,
+            grant_type: "authorization_code",
+            redirect_uri: options.redirectUri,
+            resource: options.resource.resource,
+        }),
+        headers: {
+            accept: "application/json",
+            "content-type": "application/x-www-form-urlencoded",
+            DPoP: options.dpopProof,
+        },
+        method: "POST",
+    });
+    if (!response.ok) {
+        throw new Error("Driggsby sign-in could not exchange the authorization code for tokens.");
+    }
+    return parseTokenExchangeResult(await response.json(), true);
+}
+export async function refreshAccessToken(options, fetchImpl = fetch) {
+    const response = await fetchImpl(options.metadata.token_endpoint, {
+        body: new URLSearchParams({
+            client_id: options.clientId,
+            grant_type: "refresh_token",
+            refresh_token: options.refreshToken,
+            resource: options.resource,
+        }),
+        headers: {
+            accept: "application/json",
+            "content-type": "application/x-www-form-urlencoded",
+            DPoP: options.dpopProof,
+        },
+        method: "POST",
+    });
+    if (!response.ok) {
+        throw new Error("Driggsby could not refresh the broker session with the remote service.");
+    }
+    const refreshedTokens = parseTokenExchangeResult(await response.json(), false);
+    return {
+        ...refreshedTokens,
+        refreshToken: refreshedTokens.refreshToken || options.refreshToken,
+    };
+}
+export function createOAuthState() {
+    return randomUUID();
+}
+function parseTokenExchangeResult(payload, requireRefreshToken) {
+    const parsed = tokenResponseSchema.parse(payload);
+    if (requireRefreshToken && parsed.refresh_token === undefined) {
+        throw new Error("Driggsby could not continue because the remote service did not return a refresh token.");
+    }
+    return {
+        accessToken: parsed.access_token,
+        accessTokenExpiresAt: new Date(Date.now() + parsed.expires_in * 1_000).toISOString(),
+        refreshToken: parsed.refresh_token ?? "",
+        scope: parsed.scope,
+        tokenType: parsed.token_type,
+    };
+}

package/dist/auth/pkce.js

@@ -0,0 +1,12 @@
+import { createHash, randomBytes } from "node:crypto";
+export function generatePkcePair() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256")
+        .update(verifier)
+        .digest("base64url");
+    return {
+        challenge,
+        method: "S256",
+        verifier,
+    };
+}

package/dist/auth/url-security.js

@@ -0,0 +1,16 @@
+export function assertBrokerRemoteUrl(rawUrl, context) {
+    const url = new URL(rawUrl);
+    if (url.protocol === "https:") {
+        return;
+    }
+    if (url.protocol === "http:" && isLoopbackHostname(url.hostname)) {
+        return;
+    }
+    throw new Error(`${context} must use https, except for local loopback development.`);
+}
+function isLoopbackHostname(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "::1" ||
+        hostname === "[::1]" ||
+        hostname.startsWith("127."));
+}