@sema-agent/connectors 0.0.0-stage → 0.2.0

package/dist/http.js

@@ -0,0 +1,264 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { INSPECT_LIMIT_BYTES, INTERNAL_ERROR, INVALID_REQUEST, STATUS_BEFORE_INITIALIZE, errorLine, idKey, isId, read } from './session.js';
+export const MCP_PATH = '/mcp';
+export const STATUS_PATH = '/status';
+const SESSION_HEADER = 'mcp-session-id';
+const VERSION_HEADER = 'mcp-protocol-version';
+const BAD_ASSERTION = 'connector.bad_assertion';
+const NOT_TAKEN = 'connector.forbidden_scope';
+const INTERNAL = 'connector.internal';
+class Live {
+    id = randomBytes(16).toString('hex');
+    waiting = new Map();
+    current = null;
+    initialized = false;
+    version = null;
+    ending = false;
+    link;
+    gone;
+    constructor(start, released) {
+        this.link = start((line) => this.deliver(line));
+        this.gone = this.link.gone.then(() => released(this));
+    }
+    deliver(line) {
+        let m;
+        try {
+            m = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (m === null || typeof m !== 'object' || Array.isArray(m) || 'method' in m || !('result' in m || 'error' in m))
+            return;
+        const id = m.id;
+        if (isId(id))
+            this.waiting.get(idKey(id))?.answer(line);
+        else if (id === null)
+            this.current?.answer(line);
+    }
+    end(signal) {
+        this.ending = true;
+        this.link.end(signal);
+        return this.gone;
+    }
+}
+const refusal = (status, message, dataCode = NOT_TAKEN) => [status, errorLine(null, INVALID_REQUEST, message, dataCode)];
+function reply(res, status, body, headers = {}) {
+    if (res.headersSent || res.writableEnded)
+        return;
+    const text = body === undefined ? undefined : body.endsWith('\n') ? body.slice(0, -1) : body;
+    res.writeHead(status, { ...(text !== undefined ? { 'content-type': 'application/json' } : {}), ...headers });
+    res.end(text);
+}
+function single(req, name) {
+    const values = req.headersDistinct[name];
+    if (values === undefined)
+        return undefined;
+    return values.length === 1 ? values[0] : null;
+}
+const sameId = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+function readBody(req) {
+    return new Promise((resolve) => {
+        const parts = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size <= INSPECT_LIMIT_BYTES)
+                parts.push(chunk);
+            else
+                parts.length = 0;
+        });
+        req.on('end', () => resolve(size > INSPECT_LIMIT_BYTES ? 'oversized' : Buffer.concat(parts)));
+        req.on('error', () => resolve(null));
+        req.on('close', () => resolve(null));
+    });
+}
+const isJsonMediaType = (value) => (value ?? '').split(';')[0]?.trim().toLowerCase() === 'application/json';
+export function serveHttp(options) {
+    let live = null;
+    let closing = false;
+    const open = new Set();
+    const released = (l) => {
+        if (live === l)
+            live = null;
+    };
+    const named = (req) => {
+        const sid = single(req, SESSION_HEADER);
+        if (sid === undefined)
+            return refusal(400, 'the request names no session: open one with initialize, then send its mcp-session-id with every request');
+        if (sid === null)
+            return refusal(400, 'mcp-session-id is given more than once');
+        if (live === null || !live.initialized || live.ending || !sameId(sid, live.id))
+            return refusal(404, 'no open session has this mcp-session-id');
+        return live;
+    };
+    const judge = (l, body, principal, res, opening) => {
+        const r = read(body);
+        const id = r.kind === 'message' && typeof r.m.method === 'string' && isId(r.m.id) ? r.m.id : null;
+        const key = id === null ? null : idKey(id);
+        if (key !== null && l.waiting.has(key)) {
+            reply(res, ...refusal(409, 'a request with this id is already waiting for its answer'));
+            return;
+        }
+        if (l.link.busy()) {
+            reply(res, ...refusal(503, 'the connector has not read its earlier input yet; send the request again later', INTERNAL));
+            return;
+        }
+        let answered = false;
+        const waiter = {
+            id: id ?? '',
+            answer: (line) => {
+                if (key !== null)
+                    l.waiting.delete(key);
+                if (answered)
+                    return;
+                answered = true;
+                const m = JSON.parse(line);
+                const headers = {};
+                if (opening) {
+                    if (m.result !== undefined && m.result !== null && !l.ending) {
+                        l.initialized = true;
+                        l.version = typeof m.result.protocolVersion === 'string' ? m.result.protocolVersion : null;
+                        headers[SESSION_HEADER] = l.id;
+                    }
+                    else
+                        void l.end();
+                }
+                reply(res, m.id === null ? 400 : 200, line, headers);
+            },
+        };
+        if (key !== null)
+            l.waiting.set(key, waiter);
+        res.on('close', () => {
+            if (answered)
+                return;
+            answered = true;
+            if (opening)
+                void l.end();
+        });
+        l.current = waiter;
+        try {
+            l.link.send(body, principal);
+        }
+        finally {
+            l.current = null;
+        }
+        if (!answered && key === null) {
+            answered = true;
+            if (opening)
+                void l.end();
+            reply(res, 202);
+        }
+    };
+    const post = async (req, res, principal) => {
+        if (!isJsonMediaType(req.headers['content-type']))
+            return reply(res, ...refusal(415, 'the body must be one JSON-RPC message with Content-Type application/json'));
+        const body = await readBody(req);
+        if (body === null)
+            return;
+        if (body === 'oversized')
+            return reply(res, ...refusal(413, `the body is over ${INSPECT_LIMIT_BYTES / (1024 * 1024)} MiB, more than the launcher reads to check a message against the granted scope`));
+        if (closing)
+            return reply(res, ...refusal(503, 'the launcher is stopping', INTERNAL));
+        const r = read(body);
+        if (r.kind === 'message' && r.m.method === 'initialize') {
+            if (live !== null)
+                return reply(res, ...refusal(409, 'a session is already open: the launcher serves one session at a time'));
+            live = new Live(options.start, released);
+            return judge(live, body, principal, res, true);
+        }
+        const l = named(req);
+        if (Array.isArray(l))
+            return reply(res, ...l);
+        const version = single(req, VERSION_HEADER);
+        if (version === null || (version !== undefined && version !== l.version))
+            return reply(res, ...refusal(400, 'mcp-protocol-version is not the version the connector answered initialize with'));
+        judge(l, body, principal, res, false);
+    };
+    const remove = async (req, res) => {
+        const l = named(req);
+        if (Array.isArray(l))
+            return reply(res, ...l);
+        await l.end();
+        reply(res, 204);
+    };
+    const status = (res, principal) => {
+        const l = live;
+        if (l === null || !l.initialized || l.ending)
+            return reply(res, 503, errorLine(null, INTERNAL_ERROR, STATUS_BEFORE_INITIALIZE, INTERNAL));
+        if (l.link.busy())
+            return reply(res, ...refusal(503, 'the connector has not read its earlier input yet; read the status again later', INTERNAL));
+        const id = `status/${randomUUID()}`;
+        const key = idKey(id);
+        const waiter = {
+            id,
+            answer: (line) => {
+                l.waiting.delete(key);
+                const m = JSON.parse(line);
+                const text = m.result?.contents?.[0]?.text;
+                if (typeof text === 'string')
+                    reply(res, 200, text);
+                else
+                    reply(res, 503, line);
+            },
+        };
+        l.waiting.set(key, waiter);
+        try {
+            l.link.readStatus(id, principal);
+        }
+        catch {
+            l.waiting.delete(key);
+            reply(res, 503, errorLine(id, INTERNAL_ERROR, 'the status could not be read', INTERNAL));
+        }
+    };
+    const failed = (res) => () => reply(res, 500, errorLine(null, INTERNAL_ERROR, 'the launcher could not handle this request', INTERNAL));
+    const handle = (req, res) => {
+        open.add(res);
+        res.on('close', () => open.delete(res));
+        if (closing)
+            return reply(res, ...refusal(503, 'the launcher is stopping', INTERNAL), { connection: 'close' });
+        const verdict = options.resolver.resolve({ headers: req.headersDistinct });
+        if (!verdict.ok)
+            return reply(res, ...refusal(401, verdict.reason, BAD_ASSERTION));
+        const path = new URL(req.url ?? '/', 'http://launcher.invalid').pathname;
+        if (path === STATUS_PATH) {
+            if (req.method === 'GET')
+                return status(res, verdict.principal);
+            return reply(res, ...refusal(405, '/status takes GET only'), { allow: 'GET' });
+        }
+        if (path !== MCP_PATH)
+            return reply(res, ...refusal(404, 'the launcher serves /mcp and /status only'));
+        if (req.method === 'POST')
+            return void post(req, res, verdict.principal).catch(failed(res));
+        if (req.method === 'DELETE')
+            return void remove(req, res).catch(failed(res));
+        return reply(res, ...refusal(405, '/mcp takes POST and DELETE: the evaluation form opens no stream (GET)'), { allow: 'POST, DELETE' });
+    };
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            try {
+                handle(req, res);
+            }
+            catch {
+                failed(res)();
+            }
+        });
+        server.once('error', (e) => resolve({ ok: false, code: e.code ?? 'unknown' }));
+        server.listen(options.port, options.host, () => {
+            resolve({
+                ok: true,
+                close: async (signal) => {
+                    closing = true;
+                    server.close();
+                    const l = live;
+                    if (l !== null)
+                        await l.end(signal);
+                    const finished = [...open].map((res) => new Promise((done) => (res.writableFinished ? done() : res.once('close', () => done()))));
+                    await Promise.race([Promise.all(finished), new Promise((done) => setTimeout(done, 1_000).unref())]);
+                    server.closeAllConnections();
+                },
+            });
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { resolveConfigDir } from './config-dir.js';
+export type { ConfigDirResolution, Env } from './config-dir.js';
+export { openFileSecrets } from './secrets.js';
+export type { FileSecrets, PutOptions, SecretHandle, SecretListing } from './secrets.js';
+export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion } from './principal.js';
+export type { AnonymousPrincipal, AssertionPrincipal, AssertionStep, Principal, PrincipalResolver, PrincipalResult, RequestContext, VerifyOptions, VerifyResult, } from './principal.js';
+export { mount } from './mount.js';
+export type { MountOptions, MountRefusal, MountResult } from './mount.js';
+export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
+export type { CliOutput, ConnectorCommands, StdinJson, StdinLine } from './cli-kit.js';
+export { isLoopbackHttpOrHttps } from './jwks.js';
+export { writeAll } from './write-all.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { resolveConfigDir } from './config-dir.js';
+export { openFileSecrets } from './secrets.js';
+export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion } from './principal.js';
+export { mount } from './mount.js';
+export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
+export { isLoopbackHttpOrHttps } from './jwks.js';
+export { writeAll } from './write-all.js';

package/dist/json-text.d.ts

@@ -0,0 +1,11 @@
+export declare function skipWhitespace(t: string, i: number): number;
+export declare function endOfString(t: string, i: number): number;
+export declare function endOfValue(t: string, i: number): number;
+export interface Span {
+    readonly key: string;
+    readonly start: number;
+    readonly valueStart: number;
+    readonly valueEnd: number;
+}
+export declare function spansOf(t: string, open: number, keyed: boolean): Span[];
+export declare function hasRepeatedKey(t: string): boolean;

package/dist/json-text.js

@@ -0,0 +1,93 @@
+const WHITESPACE = ' \t\n\r';
+export function skipWhitespace(t, i) {
+    while (i < t.length && WHITESPACE.includes(t.charAt(i)))
+        i++;
+    return i;
+}
+export function endOfString(t, i) {
+    for (i++; i < t.length; i++) {
+        if (t[i] === '\\')
+            i++;
+        else if (t[i] === '"')
+            return i + 1;
+    }
+    return t.length;
+}
+export function endOfValue(t, i) {
+    if (t[i] === '"')
+        return endOfString(t, i);
+    if (t[i] === '{' || t[i] === '[') {
+        let depth = 0;
+        while (i < t.length) {
+            const c = t[i];
+            if (c === '"') {
+                i = endOfString(t, i);
+                continue;
+            }
+            if (c === '{' || c === '[')
+                depth++;
+            else if ((c === '}' || c === ']') && --depth === 0)
+                return i + 1;
+            i++;
+        }
+        return t.length;
+    }
+    while (i < t.length && !',}]'.includes(t.charAt(i)) && !WHITESPACE.includes(t.charAt(i)))
+        i++;
+    return i;
+}
+export function spansOf(t, open, keyed) {
+    const close = keyed ? '}' : ']';
+    const spans = [];
+    let i = skipWhitespace(t, open + 1);
+    while (i < t.length && t[i] !== close) {
+        const start = i;
+        let key = '';
+        if (keyed) {
+            const keyEnd = endOfString(t, i);
+            key = JSON.parse(t.slice(i, keyEnd));
+            i = skipWhitespace(t, skipWhitespace(t, keyEnd) + 1);
+        }
+        const valueStart = i;
+        const valueEnd = endOfValue(t, i);
+        spans.push({ key, start, valueStart, valueEnd });
+        i = skipWhitespace(t, valueEnd);
+        if (t[i] === ',')
+            i = skipWhitespace(t, i + 1);
+    }
+    return spans;
+}
+export function hasRepeatedKey(t) {
+    const objects = [];
+    let expectKey = false;
+    for (let i = 0; i < t.length; i++) {
+        const c = t[i];
+        if (c === '"') {
+            const end = endOfString(t, i);
+            const top = objects[objects.length - 1];
+            if (expectKey && top instanceof Set) {
+                const key = JSON.parse(t.slice(i, end));
+                if (top.has(key))
+                    return true;
+                top.add(key);
+                expectKey = false;
+            }
+            i = end - 1;
+        }
+        else if (c === '{') {
+            objects.push(new Set());
+            expectKey = true;
+        }
+        else if (c === '[') {
+            objects.push(null);
+            expectKey = false;
+        }
+        else if (c === '}' || c === ']') {
+            objects.pop();
+            expectKey = false;
+        }
+        else if (c === ',')
+            expectKey = objects[objects.length - 1] instanceof Set;
+    }
+    return false;
+}

package/dist/jwks.d.ts

@@ -0,0 +1,19 @@
+import { type Env } from './config-dir.js';
+export type KeySetSource = {
+    readonly kind: 'inline';
+    readonly text: string;
+} | {
+    readonly kind: 'url';
+    readonly from: string;
+    readonly url: URL;
+};
+export type KeySet = {
+    readonly ok: true;
+    readonly keys: unknown;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function isLoopbackHttpOrHttps(url: URL): boolean;
+export declare function keySetSource(env: Env, issuer: string): KeySetSource | string;
+export declare function obtainKeySet(source: KeySetSource): Promise<KeySet>;

package/dist/jwks.js

@@ -0,0 +1,81 @@
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import { given } from './config-dir.js';
+const INLINE = 'CONNECTOR_ASSERTION_JWKS';
+const OVERRIDE = 'CONNECTOR_ASSERTION_JWKS_URL';
+const WELL_KNOWN = '/.well-known/jwks.json';
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost'];
+export function isLoopbackHttpOrHttps(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK_HOSTS.includes(url.hostname));
+}
+const FETCH_LIMIT_BYTES = 1024 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+export function keySetSource(env, issuer) {
+    const inline = env[INLINE];
+    const override = env[OVERRIDE];
+    if (given(override) && given(inline))
+        return `both ${OVERRIDE} and ${INLINE} are set; the key set must have one source`;
+    if (given(inline))
+        return { kind: 'inline', text: inline };
+    const from = given(override) ? OVERRIDE : `the default key set location (CONNECTOR_ASSERTION_ISSUER followed by ${WELL_KNOWN})`;
+    let url;
+    try {
+        url = new URL(given(override) ? override : issuer.replace(/\/+$/, '') + WELL_KNOWN);
+    }
+    catch {
+        return `${from} is not a URL`;
+    }
+    if (url.username !== '' || url.password !== '')
+        return `${from} carries credentials; a key set URL never does`;
+    if (isLoopbackHttpOrHttps(url))
+        return { kind: 'url', from, url };
+    return `${from} must be an https URL, or an http URL on 127.0.0.1 or localhost`;
+}
+const isKeySet = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && Array.isArray(v.keys);
+export async function obtainKeySet(source) {
+    const what = source.kind === 'inline' ? INLINE : `the key set from ${source.from}`;
+    let text;
+    if (source.kind === 'inline')
+        text = source.text;
+    else {
+        const fetched = await fetchOnce(source.url);
+        if (!fetched.ok)
+            return { ok: false, problem: `${what} could not be fetched: ${fetched.why}` };
+        text = fetched.text;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, problem: `${what} is not JSON` };
+    }
+    return isKeySet(value) ? { ok: true, keys: value } : { ok: false, problem: `${what} is not a JSON Web Key Set (an object with a keys list)` };
+}
+function fetchOnce(url) {
+    return new Promise((resolve) => {
+        const get = url.protocol === 'https:' ? httpsGet : httpGet;
+        const req = get(url, { agent: false, headers: { accept: 'application/json' } }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve({ ok: false, why: `it answered HTTP ${String(res.statusCode)}` });
+                return;
+            }
+            const parts = [];
+            let size = 0;
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > FETCH_LIMIT_BYTES) {
+                    req.destroy();
+                    resolve({ ok: false, why: `its answer is over ${FETCH_LIMIT_BYTES / (1024 * 1024)} MiB` });
+                }
+                else
+                    parts.push(chunk);
+            });
+            res.on('end', () => resolve({ ok: true, text: Buffer.concat(parts).toString('utf8') }));
+            res.on('error', () => resolve({ ok: false, why: 'its answer broke off' }));
+        });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => req.destroy(Object.assign(new Error('timeout'), { code: 'ETIMEDOUT' })));
+        req.on('error', (e) => resolve({ ok: false, why: `the request failed (${e.code ?? 'no answer'})` }));
+    });
+}

package/dist/launcher.d.ts

@@ -0,0 +1,2 @@
+import { type Env } from './config-dir.js';
+export declare function main(argv: readonly string[], env: Env): Promise<number>;