driggsby 0.0.1 → 0.1.2

package/dist/broker/remote-session.js

@@ -0,0 +1,103 @@
+import { fetchAuthorizationServerMetadata, } from "../auth/discovery.js";
+import { createDpopProof } from "../auth/dpop.js";
+import { refreshAccessToken } from "../auth/oauth.js";
+import { assertBrokerRemoteUrl } from "../auth/url-security.js";
+import { readBrokerDpopKeyPair } from "./installation.js";
+import { readBrokerRemoteSession, summarizeBrokerRemoteSession, writeBrokerRemoteSession, } from "./session.js";
+const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
+export class BrokerRemoteSessionManager {
+    brokerId;
+    fetchImpl;
+    runtimePaths;
+    secretStore;
+    refreshInFlight = null;
+    constructor(options) {
+        this.brokerId = options.brokerId;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.runtimePaths = options.runtimePaths;
+        this.secretStore = options.secretStore;
+    }
+    async ensureFreshSession() {
+        const session = await readBrokerRemoteSession(this.secretStore, this.brokerId);
+        if (session === null) {
+            throw new Error("The local Driggsby broker is not connected. Run `npx -y driggsby login` again.");
+        }
+        if (!sessionNeedsRefresh(session)) {
+            return session;
+        }
+        this.refreshInFlight ??= refreshRemoteSession(this.runtimePaths, this.secretStore, this.brokerId, session, this.fetchImpl).finally(() => {
+            this.refreshInFlight = null;
+        });
+        return await this.refreshInFlight;
+    }
+}
+export async function ensureFreshRemoteSession(options) {
+    const manager = new BrokerRemoteSessionManager(options);
+    return await manager.ensureFreshSession();
+}
+export async function inspectRemoteSessionReadiness(options) {
+    const session = await readBrokerRemoteSession(options.secretStore, options.brokerId);
+    if (session === null) {
+        return {
+            connected: false,
+            ready: false,
+        };
+    }
+    return {
+        connected: true,
+        ready: !sessionNeedsRefresh(session),
+        session: summarizeBrokerRemoteSession(session),
+    };
+}
+export function sessionNeedsRefresh(session, nowMs = Date.now()) {
+    const expiresAtMs = Date.parse(session.accessTokenExpiresAt);
+    if (!Number.isFinite(expiresAtMs)) {
+        return true;
+    }
+    return expiresAtMs - nowMs <= ACCESS_TOKEN_REFRESH_SKEW_MS;
+}
+async function refreshRemoteSession(runtimePaths, secretStore, brokerId, session, fetchImpl) {
+    assertBrokerRemoteUrl(session.issuer, "The Driggsby issuer URL");
+    let authorizationServerMetadata;
+    try {
+        authorizationServerMetadata = await fetchAuthorizationServerMetadata(session.issuer, fetchImpl);
+    }
+    catch {
+        throw new Error("Driggsby could not refresh the local broker session right now. Try again in a moment.");
+    }
+    let refreshedTokens;
+    try {
+        refreshedTokens = await refreshAccessToken({
+            clientId: session.clientId,
+            dpopProof: await refreshTokenDpopProof(runtimePaths, secretStore, brokerId, authorizationServerMetadata.token_endpoint),
+            metadata: authorizationServerMetadata,
+            refreshToken: session.refreshToken,
+            resource: session.resource,
+        }, fetchImpl);
+    }
+    catch {
+        throw new Error("The local Driggsby broker session expired. Run `npx -y driggsby login` again.");
+    }
+    const refreshedSession = {
+        ...session,
+        accessToken: refreshedTokens.accessToken,
+        accessTokenExpiresAt: refreshedTokens.accessTokenExpiresAt,
+        refreshToken: refreshedTokens.refreshToken,
+        scope: refreshedTokens.scope,
+        tokenType: refreshedTokens.tokenType,
+    };
+    await writeBrokerRemoteSession(secretStore, brokerId, refreshedSession);
+    return refreshedSession;
+}
+async function refreshTokenDpopProof(runtimePaths, secretStore, brokerId, tokenEndpoint) {
+    const dpopKeyPair = await readBrokerDpopKeyPair(runtimePaths, secretStore, brokerId);
+    if (dpopKeyPair === null) {
+        throw new Error("The local Driggsby broker key is missing. Run `npx -y driggsby login` again.");
+    }
+    return await createDpopProof({
+        httpMethod: "POST",
+        privateJwk: dpopKeyPair.privateJwk,
+        publicJwk: dpopKeyPair.publicJwk,
+        targetUrl: tokenEndpoint,
+    });
+}

package/dist/broker/secret-store.js

@@ -0,0 +1,30 @@
+import { AsyncEntry } from "@napi-rs/keyring";
+export class KeyringSecretStore {
+    serviceName;
+    constructor(serviceName = "driggsby.local-broker") {
+        this.serviceName = serviceName;
+    }
+    async setSecret(account, secret) {
+        await new AsyncEntry(this.serviceName, account).setPassword(secret);
+    }
+    async getSecret(account) {
+        const secret = await new AsyncEntry(this.serviceName, account).getPassword();
+        return secret ?? null;
+    }
+    async deleteSecret(account) {
+        return await new AsyncEntry(this.serviceName, account).deleteCredential();
+    }
+}
+export class MemorySecretStore {
+    secrets = new Map();
+    setSecret(account, secret) {
+        this.secrets.set(account, secret);
+        return Promise.resolve();
+    }
+    getSecret(account) {
+        return Promise.resolve(this.secrets.get(account) ?? null);
+    }
+    deleteSecret(account) {
+        return Promise.resolve(this.secrets.delete(account));
+    }
+}

package/dist/broker/server.js

@@ -0,0 +1,177 @@
+import { promises as fs } from "node:fs";
+import net from "node:net";
+import { ensureRuntimeDirectories } from "../lib/runtime-paths.js";
+import { acquireBrokerLock } from "./lock.js";
+import { decodeRequest, encodeResponse } from "./ipc.js";
+import { hashBrokerPayload, signBrokerProof } from "./authentication.js";
+export class LocalBrokerServer {
+    brokerId;
+    localAuthToken;
+    privateJwk;
+    runtimePaths;
+    statusProvider;
+    listToolsProvider;
+    callToolProvider;
+    lockLease = null;
+    server = null;
+    constructor(options) {
+        this.brokerId = options.brokerId;
+        this.localAuthToken = options.localAuthToken;
+        this.privateJwk = options.privateJwk;
+        this.runtimePaths = options.runtimePaths;
+        this.statusProvider = options.statusProvider;
+        this.listToolsProvider = options.listTools;
+        this.callToolProvider = options.callTool;
+    }
+    async listen() {
+        if (this.server !== null) {
+            return;
+        }
+        await ensureRuntimeDirectories(this.runtimePaths);
+        const lockLease = await acquireBrokerLock(this.runtimePaths.lockPath);
+        if (lockLease === null) {
+            throw new Error("The local Driggsby broker is already running.");
+        }
+        this.lockLease = lockLease;
+        if (process.platform !== "win32") {
+            await removeSocketIfPresent(this.runtimePaths.socketPath);
+        }
+        this.server = net.createServer((socket) => {
+            socket.setEncoding("utf8");
+            let buffer = "";
+            socket.on("data", (chunk) => {
+                buffer += chunk;
+                const newlineIndex = buffer.indexOf("\n");
+                if (newlineIndex < 0) {
+                    return;
+                }
+                const payload = buffer.slice(0, newlineIndex);
+                void this.handleRequest(payload, socket);
+            });
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                this.server?.once("error", reject);
+                this.server?.listen(this.runtimePaths.socketPath, resolve);
+            });
+        }
+        catch (error) {
+            await this.releaseLock();
+            throw error;
+        }
+        if (process.platform !== "win32") {
+            await fs.chmod(this.runtimePaths.socketPath, 0o600);
+        }
+    }
+    async close() {
+        if (this.server !== null) {
+            const server = this.server;
+            this.server = null;
+            await new Promise((resolve, reject) => {
+                server.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        }
+        if (process.platform !== "win32") {
+            await removeSocketIfPresent(this.runtimePaths.socketPath);
+        }
+        await this.releaseLock();
+    }
+    async handleRequest(payload, socket) {
+        let response;
+        try {
+            const request = decodeRequest(payload);
+            response = await this.dispatchRequest(request);
+        }
+        catch (error) {
+            response = await this.buildErrorResponse("unknown", "unknown", "unknown", error instanceof Error ? error.message : "Broker request failed.");
+        }
+        socket.end(encodeResponse(response));
+    }
+    async dispatchRequest(request) {
+        if (request.authToken !== this.localAuthToken) {
+            return await this.buildErrorResponse(request.id, request.method, request.challenge, "Broker authentication failed.");
+        }
+        switch (request.method) {
+            case "ping": {
+                const status = await this.statusProvider();
+                return await this.buildSuccessResponse(request, {
+                    ok: true,
+                    brokerId: status.brokerId ?? "unknown",
+                });
+            }
+            case "get_status":
+                return await this.buildSuccessResponse(request, {
+                    status: await this.statusProvider(),
+                });
+            case "shutdown":
+                setImmediate(() => {
+                    void this.close();
+                });
+                return await this.buildSuccessResponse(request, {
+                    stopped: true,
+                });
+            case "list_tools":
+                return await this.buildSuccessResponse(request, await this.listToolsProvider());
+            case "call_tool":
+                return await this.buildSuccessResponse(request, await this.callToolProvider(request.toolName, request.args));
+        }
+    }
+    async buildSuccessResponse(request, result) {
+        const payload = { ok: true, result };
+        return {
+            brokerProof: await signBrokerProof({
+                aud: "driggsby-local-shim",
+                challenge: request.challenge,
+                payloadSha256: hashBrokerPayload(payload),
+                requestId: request.id,
+                requestMethod: request.method,
+                sub: this.brokerId,
+            }, this.privateJwk),
+            id: request.id,
+            ok: true,
+            result,
+        };
+    }
+    async buildErrorResponse(requestId, requestMethod, challenge, error) {
+        const payload = { ok: false, error };
+        return {
+            brokerProof: await signBrokerProof({
+                aud: "driggsby-local-shim",
+                challenge,
+                payloadSha256: hashBrokerPayload(payload),
+                requestId,
+                requestMethod: requestMethod === "unknown" ? "ping" : requestMethod,
+                sub: this.brokerId,
+            }, this.privateJwk),
+            id: requestId,
+            ok: false,
+            error,
+        };
+    }
+    async releaseLock() {
+        if (this.lockLease === null) {
+            return;
+        }
+        const lease = this.lockLease;
+        this.lockLease = null;
+        await lease.release();
+    }
+}
+async function removeSocketIfPresent(socketPath) {
+    try {
+        await fs.rm(socketPath);
+    }
+    catch (error) {
+        if (!(error instanceof Error) ||
+            !("code" in error) ||
+            error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}

package/dist/broker/session.js

@@ -0,0 +1,31 @@
+const REMOTE_SESSION_ACCOUNT_SUFFIX = "remote-session";
+export async function readBrokerRemoteSession(secretStore, brokerId) {
+    const raw = await secretStore.getSecret(remoteSessionAccountName(brokerId));
+    if (raw === null) {
+        return null;
+    }
+    const parsed = JSON.parse(raw);
+    return {
+        ...parsed,
+        tokenType: parsed.tokenType ?? "Bearer",
+    };
+}
+export async function writeBrokerRemoteSession(secretStore, brokerId, session) {
+    await secretStore.setSecret(remoteSessionAccountName(brokerId), JSON.stringify(session));
+}
+export async function clearBrokerRemoteSession(secretStore, brokerId) {
+    await secretStore.deleteSecret(remoteSessionAccountName(brokerId));
+}
+export function summarizeBrokerRemoteSession(session) {
+    return {
+        accessTokenExpiresAt: session.accessTokenExpiresAt,
+        authenticatedAt: session.authenticatedAt,
+        clientId: session.clientId,
+        issuer: session.issuer,
+        resource: session.resource,
+        scope: session.scope,
+    };
+}
+function remoteSessionAccountName(brokerId) {
+    return `${brokerId}:${REMOTE_SESSION_ACCOUNT_SUFFIX}`;
+}

package/dist/broker/test-support.js

@@ -0,0 +1,258 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { decodeProtectedHeader, importJWK, jwtVerify, } from "jose";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+export async function makeBrokerRuntimePaths(prefix) {
+    const baseDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+    return {
+        configDir: path.join(baseDir, "config"),
+        stateDir: path.join(baseDir, "state"),
+        metadataPath: path.join(baseDir, "config", "broker-metadata.json"),
+        lockPath: path.join(baseDir, "state", "broker.lock"),
+        socketPath: path.join(baseDir, "state", "broker.sock"),
+    };
+}
+export async function startFakeRemoteService() {
+    let currentAccessToken = "refreshed-access-token";
+    let tokenRequestCount = 0;
+    let listToolsCount = 0;
+    let callToolCount = 0;
+    let exposeSavingsTool = false;
+    const server = http.createServer((request, response) => {
+        void handleRequest(request, response);
+    });
+    async function handleRequest(request, response) {
+        const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (request.method === "GET" &&
+            requestUrl.pathname === "/.well-known/oauth-authorization-server") {
+            response.setHeader("content-type", "application/json");
+            response.end(JSON.stringify({
+                issuer: originForServer(server),
+                authorization_endpoint: `${originForServer(server)}/authorize`,
+                token_endpoint: `${originForServer(server)}/token`,
+                registration_endpoint: `${originForServer(server)}/register`,
+                response_types_supported: ["code"],
+                grant_types_supported: ["authorization_code", "refresh_token"],
+                token_endpoint_auth_methods_supported: ["none"],
+                dpop_signing_alg_values_supported: ["ES256"],
+                code_challenge_methods_supported: ["S256"],
+                scopes_supported: ["driggsby.read"],
+            }));
+            return;
+        }
+        if (request.method === "POST" && requestUrl.pathname === "/token") {
+            tokenRequestCount += 1;
+            const body = await readRequestBody(request);
+            const params = new URLSearchParams(body);
+            assert.equal(params.get("client_id"), "client-123");
+            assert.equal(params.get("grant_type"), "refresh_token");
+            assert.equal(params.get("refresh_token"), "refresh-token-1");
+            assert.equal(params.get("resource"), `${originForServer(server)}/mcp`);
+            await assertDpopProof(request.headers["dpop"], {
+                authorizationHeader: undefined,
+                expectedMethod: "POST",
+                expectedUrl: `${originForServer(server)}/token`,
+            });
+            currentAccessToken = "refreshed-access-token";
+            response.setHeader("content-type", "application/json");
+            response.end(JSON.stringify({
+                access_token: currentAccessToken,
+                token_type: "DPoP",
+                expires_in: 3600,
+                refresh_token: "refresh-token-2",
+                scope: "driggsby.read",
+            }));
+            return;
+        }
+        if (requestUrl.pathname === "/mcp" && request.method === "GET") {
+            response.statusCode = 405;
+            response.setHeader("content-type", "application/json");
+            response.end(JSON.stringify({
+                error: {
+                    code: -32000,
+                    message: "Method not allowed.",
+                },
+                id: null,
+                jsonrpc: "2.0",
+            }));
+            return;
+        }
+        if (requestUrl.pathname === "/mcp" && request.method === "POST") {
+            if (request.headers.authorization !== `DPoP ${currentAccessToken}`) {
+                response.statusCode = 401;
+                response.end();
+                return;
+            }
+            await assertDpopProof(request.headers["dpop"], {
+                authorizationHeader: request.headers.authorization,
+                expectedMethod: "POST",
+                expectedUrl: `${originForServer(server)}/mcp`,
+            });
+            const mcpServer = new Server({
+                name: "fake-remote-mcp",
+                version: "0.1.0",
+            }, {
+                capabilities: {
+                    tools: {},
+                },
+            });
+            mcpServer.setRequestHandler(ListToolsRequestSchema, () => {
+                listToolsCount += 1;
+                return {
+                    tools: [
+                        {
+                            description: "Echo a balance amount back to the caller.",
+                            inputSchema: {
+                                additionalProperties: false,
+                                properties: {
+                                    amount: {
+                                        type: "string",
+                                    },
+                                },
+                                required: ["amount"],
+                                type: "object",
+                            },
+                            name: "echo_balance",
+                        },
+                        ...(exposeSavingsTool
+                            ? [
+                                {
+                                    description: "Project a savings target over time.",
+                                    inputSchema: {
+                                        additionalProperties: false,
+                                        properties: {},
+                                        type: "object",
+                                    },
+                                    name: "savings_projection",
+                                },
+                            ]
+                            : []),
+                    ],
+                };
+            });
+            mcpServer.setRequestHandler(CallToolRequestSchema, (mcpRequest) => {
+                callToolCount += 1;
+                const amount = readAmountArgument(mcpRequest.params.arguments);
+                return {
+                    content: [
+                        {
+                            text: `echoed ${amount}`,
+                            type: "text",
+                        },
+                    ],
+                };
+            });
+            const transport = new StreamableHTTPServerTransport({});
+            await mcpServer.connect(toTransport(transport));
+            await transport.handleRequest(request, response, await readJsonBody(request));
+            response.once("close", () => {
+                void transport.close();
+                void mcpServer.close();
+            });
+            return;
+        }
+        response.statusCode = 404;
+        response.end();
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    return {
+        async close() {
+            await new Promise((resolve, reject) => {
+                server.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        },
+        get callToolCount() {
+            return callToolCount;
+        },
+        get listToolsCount() {
+            return listToolsCount;
+        },
+        get origin() {
+            return originForServer(server);
+        },
+        setExposeSavingsTool(value) {
+            exposeSavingsTool = value;
+        },
+        get tokenRequestCount() {
+            return tokenRequestCount;
+        },
+    };
+}
+function readAmountArgument(argumentsValue) {
+    if (typeof argumentsValue !== "object" ||
+        argumentsValue === null ||
+        Array.isArray(argumentsValue)) {
+        throw new Error("Expected object arguments.");
+    }
+    const amount = argumentsValue["amount"];
+    if (typeof amount !== "string") {
+        throw new Error("Expected a string amount argument.");
+    }
+    return amount;
+}
+async function readJsonBody(request) {
+    const body = await readRequestBody(request);
+    if (body.length === 0) {
+        return undefined;
+    }
+    return JSON.parse(body);
+}
+async function assertDpopProof(proof, options) {
+    if (typeof proof !== "string") {
+        throw new Error("Expected a DPoP proof header.");
+    }
+    const protectedHeader = decodeProtectedHeader(proof);
+    const verificationKey = await importJWK(protectedHeader.jwk, "ES256");
+    const { payload } = await jwtVerify(proof, verificationKey, {
+        algorithms: ["ES256"],
+        typ: "dpop+jwt",
+    });
+    assert.equal(payload["htm"], options.expectedMethod);
+    assert.equal(payload["htu"], options.expectedUrl);
+    if (options.authorizationHeader !== undefined) {
+        const [, accessToken] = options.authorizationHeader.split(" ");
+        if (accessToken === undefined) {
+            throw new Error("Expected an access token in the authorization header.");
+        }
+        assert.ok(typeof payload["ath"] === "string");
+        assert.equal(payload["ath"], await sha256Base64Url(accessToken));
+    }
+}
+async function sha256Base64Url(value) {
+    return (await import("node:crypto"))
+        .createHash("sha256")
+        .update(value)
+        .digest("base64url");
+}
+async function readRequestBody(request) {
+    let body = "";
+    for await (const chunk of request) {
+        body += String(chunk);
+    }
+    return body;
+}
+function originForServer(server) {
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("Expected an HTTP server address.");
+    }
+    return `http://127.0.0.1:${address.port}`;
+}
+function toTransport(transport) {
+    return transport;
+}

package/dist/broker/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/broker-daemon.js

@@ -0,0 +1,4 @@
+import { runBrokerDaemon } from "../../broker/daemon.js";
+export async function runBrokerDaemonCommand(runtimePaths) {
+    await runBrokerDaemon(runtimePaths);
+}

package/dist/cli/commands/login.js

@@ -0,0 +1,31 @@
+import { loginBroker } from "../../auth/login.js";
+import { KeyringSecretStore } from "../../broker/secret-store.js";
+import { ensureRuntimeDirectories } from "../../lib/runtime-paths.js";
+export async function runLoginCommand(runtimePaths) {
+    await ensureRuntimeDirectories(runtimePaths);
+    const secretStore = new KeyringSecretStore();
+    process.stdout.write("Opening Driggsby sign-in in your browser...\n");
+    const result = await loginBroker(runtimePaths, {
+        onBrowserPrompt: ({ browserOpened, signInUrl }) => {
+            if (!browserOpened) {
+                process.stdout.write([
+                    "Your browser did not open automatically.",
+                    "Open this URL to finish connecting Driggsby:",
+                    signInUrl,
+                    "",
+                ].join("\n"));
+            }
+        },
+        secretStore,
+    });
+    process.stdout.write([
+        "Local Driggsby broker is connected.",
+        `broker id: ${result.brokerId}`,
+        `dpop thumbprint: ${result.dpopThumbprint}`,
+        `server: ${result.session.issuer}`,
+        `resource: ${result.session.resource}`,
+        `scope: ${result.session.scope}`,
+        `access token expires: ${result.session.accessTokenExpiresAt}`,
+        "",
+    ].join("\n"));
+}

package/dist/cli/commands/logout.js

@@ -0,0 +1,16 @@
+import { getBrokerStatus, shutdownBroker } from "../../broker/client.js";
+import { clearBrokerInstallation } from "../../broker/installation.js";
+import { KeyringSecretStore } from "../../broker/secret-store.js";
+export async function runLogoutCommand(runtimePaths) {
+    const secretStore = new KeyringSecretStore();
+    const clientOptions = {
+        runtimePaths,
+        secretStore,
+    };
+    const runningStatus = await getBrokerStatus(clientOptions);
+    if (runningStatus !== null && !(await shutdownBroker(clientOptions))) {
+        throw new Error("The local Driggsby broker did not shut down cleanly. Close active MCP sessions and try again.");
+    }
+    await clearBrokerInstallation(runtimePaths, secretStore);
+    process.stdout.write("Local Driggsby broker state cleared.\n");
+}

package/dist/cli/commands/status.js

@@ -0,0 +1,14 @@
+import { getBrokerStatus } from "../../broker/client.js";
+import { buildBrokerStatus } from "../../broker/installation.js";
+import { KeyringSecretStore } from "../../broker/secret-store.js";
+import { formatStatusText } from "../format.js";
+export async function runStatusCommand(runtimePaths) {
+    const secretStore = new KeyringSecretStore();
+    const liveStatus = await getBrokerStatus({
+        runtimePaths,
+        secretStore,
+    });
+    const status = liveStatus ??
+        (await buildBrokerStatus(runtimePaths, secretStore, false));
+    process.stdout.write(formatStatusText(status));
+}