@sema-agent/connectors 0.0.0-stage → 0.2.0

package/dist/mount.js

@@ -0,0 +1,160 @@
+import { closeSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { absoluteDir } from './config-dir.js';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { skipWhitespace, spansOf } from './json-text.js';
+import { takeLockFile } from './lock-file.js';
+import { writeAll } from './write-all.js';
+const RESERVED_NAMES = ['sema-connector'];
+export function standaloneEntry(name, configDir) {
+    return { name, transport: { kind: 'stdio', command: 'sema-connector', args: ['run', name, '--mode', 'standalone', '--transport', 'stdio', '--config-dir', configDir] } };
+}
+function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    if (v !== null && typeof v === 'object') {
+        const o = v;
+        return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(v) ?? 'undefined';
+}
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+function plan(before, entry) {
+    if (before.trim() === '')
+        return { refusal: 'unreadable', message: 'config.d/mcp.json is empty' };
+    let doc;
+    try {
+        doc = JSON.parse(before);
+    }
+    catch {
+        return { refusal: 'unreadable', message: 'config.d/mcp.json is not valid JSON' };
+    }
+    if (!isObject(doc))
+        return { refusal: 'unexpected_shape', message: 'config.d/mcp.json must hold a JSON object' };
+    const open = skipWhitespace(before, 0);
+    const members = spansOf(before, open, true);
+    const serverMembers = members.filter((m) => m.key === 'servers');
+    if (serverMembers.length > 1)
+        return { refusal: 'unexpected_shape', message: 'config.d/mcp.json gives "servers" more than once' };
+    const servers = doc.servers;
+    if (servers !== undefined && !Array.isArray(servers))
+        return { refusal: 'unexpected_shape', message: '"servers" in config.d/mcp.json is not a list' };
+    const named = (servers ?? []).filter((s) => isObject(s) && s.name === entry.name);
+    if (named.length === 1 && canonical(named[0]) === canonical(entry))
+        return { unchanged: true };
+    if (named.length > 0)
+        return { refusal: 'conflict', message: `config.d/mcp.json already has another entry named ${entry.name}; mount does not overwrite it` };
+    const entryText = JSON.stringify(entry);
+    const insertAfter = (at, insertion) => before.slice(0, at) + insertion + before.slice(at);
+    let text;
+    const serversMember = serverMembers[0];
+    if (serversMember === undefined) {
+        const member = `"servers": [${entryText}]`;
+        const first = members[0];
+        const last = members[members.length - 1];
+        text = first === undefined || last === undefined ? insertAfter(open + 1, member) : insertAfter(last.valueEnd, ',' + before.slice(open + 1, first.start) + member);
+    }
+    else {
+        const arrayOpen = serversMember.valueStart;
+        const elements = spansOf(before, arrayOpen, false);
+        const first = elements[0];
+        const last = elements[elements.length - 1];
+        text = first === undefined || last === undefined ? insertAfter(arrayOpen + 1, entryText) : insertAfter(last.valueEnd, ',' + before.slice(arrayOpen + 1, first.start) + entryText);
+    }
+    const after = JSON.parse(text);
+    const { servers: newServers, ...newRest } = after;
+    const { servers: _old, ...oldRest } = doc;
+    if (canonical(newServers) !== canonical([...(servers ?? []), entry]) || canonical(newRest) !== canonical(oldRest)) {
+        throw new Error('mount planned a text that does not add exactly its entry; the file was not written');
+    }
+    return { text };
+}
+const LOCK_FILE = '.mcp.json.lock';
+const failure = (e) => {
+    const code = e?.code;
+    return typeof code === 'string' ? code : e instanceof Error ? e.message : 'unknown error';
+};
+const readOrNull = (file) => {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+};
+export function mount(options) {
+    const refuse = (reason, message) => ({ ok: false, reason, message });
+    const name = options?.name;
+    if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
+        return refuse('invalid_name', 'a connector name is lowercase letters and digits in hyphen-separated words');
+    if (RESERVED_NAMES.includes(name))
+        return refuse('reserved_name', `${name} is a reserved name`);
+    const configDir = absoluteDir(options.configDir);
+    if (configDir === null)
+        return refuse('config_dir', 'configDir must be the configuration directory as an absolute path; mount reads no environment variable and has no default');
+    const dir = join(configDir, 'config.d');
+    const file = join(dir, 'mcp.json');
+    let unlock;
+    try {
+        mkdirSync(dir, { recursive: true });
+        unlock = takeLockFile(join(dir, LOCK_FILE));
+    }
+    catch (e) {
+        return refuse('write_failed', `config.d or its lock could not be written (${failure(e)}); config.d/mcp.json was left as it was`);
+    }
+    if (unlock === null)
+        return refuse('locked', `another mount is writing config.d/mcp.json; try again, and if no mount is running remove config.d/${LOCK_FILE}`);
+    try {
+        return write(file, standaloneEntry(name, configDir), refuse);
+    }
+    finally {
+        unlock();
+    }
+}
+function write(file, entry, refuse) {
+    const dir = dirname(file);
+    let before;
+    try {
+        before = readOrNull(file);
+    }
+    catch {
+        return refuse('unreadable', 'config.d/mcp.json cannot be read');
+    }
+    let text;
+    if (before === null)
+        text = JSON.stringify({ servers: [entry] }, null, 2) + '\n';
+    else {
+        const p = plan(before, entry);
+        if ('refusal' in p)
+            return refuse(p.refusal, p.message);
+        if ('unchanged' in p)
+            return { ok: true, changed: false, file };
+        text = p.text;
+    }
+    const mode = before === null ? null : statSync(file).mode & 0o7777;
+    const tmp = join(dir, `.mcp.json.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        const fd = openSync(tmp, 'wx', 0o666);
+        try {
+            if (mode !== null)
+                fchmodSync(fd, mode);
+            writeAll(fd, text);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (readOrNull(file) !== before) {
+            rmSync(tmp, { force: true });
+            return refuse('changed_during_write', 'config.d/mcp.json changed while mount was writing it; nothing was written, run mount again');
+        }
+        renameSync(tmp, file);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        return refuse('write_failed', `config.d/mcp.json could not be written (${failure(e)}); it was left as it was and nothing else was written`);
+    }
+    return { ok: true, changed: true, file };
+}

package/dist/normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizeTool(tool: Readonly<Record<string, unknown>>): Record<string, unknown>;

package/dist/normalize.js

@@ -0,0 +1,19 @@
+const PASSABLE_HINTS = Object.freeze({ destructiveHint: true, idempotentHint: false, openWorldHint: true });
+export function normalizeTool(tool) {
+    const out = {};
+    for (const [key, value] of Object.entries(tool)) {
+        if (key !== 'annotations') {
+            out[key] = value;
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const kept = {};
+        for (const [hint, v] of Object.entries(value)) {
+            if (hint === 'title' || (Object.hasOwn(PASSABLE_HINTS, hint) && PASSABLE_HINTS[hint] === v))
+                kept[hint] = v;
+        }
+        out[key] = kept;
+    }
+    return out;
+}

package/dist/principal.d.ts

@@ -0,0 +1,50 @@
+export declare const ASSERTION_HEADER = "connector-assertion";
+export declare const SCOPE_PATTERN: RegExp;
+export type AssertionStep = 'decode' | 'algorithm' | 'key' | 'signature' | 'claims' | 'issuer' | 'audience' | 'expiry' | 'subject' | 'space' | 'scope';
+export interface AnonymousPrincipal {
+    readonly kind: 'anonymous';
+    readonly scope: readonly string[];
+}
+export interface AssertionPrincipal {
+    readonly kind: 'assertion';
+    readonly sub: string;
+    readonly space: string;
+    readonly scope: readonly string[];
+}
+export type Principal = AnonymousPrincipal | AssertionPrincipal;
+export interface VerifyOptions {
+    readonly issuer: string;
+    readonly audience: string;
+    readonly keys: unknown;
+    readonly now: number;
+}
+export type VerifyResult = {
+    readonly ok: true;
+    readonly principal: AssertionPrincipal;
+} | {
+    readonly ok: false;
+    readonly code: 'connector.bad_assertion';
+    readonly step: AssertionStep;
+};
+export declare function verifyAssertion(compactJws: string, options: VerifyOptions): VerifyResult;
+export interface RequestContext {
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+export type PrincipalResult = {
+    readonly ok: true;
+    readonly principal: Principal;
+} | {
+    readonly ok: false;
+    readonly code: 'connector.bad_assertion';
+    readonly reason: string;
+};
+export interface PrincipalResolver {
+    resolve(request: RequestContext): PrincipalResult;
+}
+export declare function standaloneResolver(): PrincipalResolver;
+export declare function hostedResolver(options: {
+    readonly issuer: string;
+    readonly audience: string;
+    readonly keys: unknown;
+    readonly clock?: () => number;
+}): PrincipalResolver;

package/dist/principal.js

@@ -0,0 +1,127 @@
+import { createPublicKey, verify } from 'node:crypto';
+export const ASSERTION_HEADER = 'connector-assertion';
+export const SCOPE_PATTERN = /^[!#-\[\]-~]+( [!#-\[\]-~]+)*$/;
+const EXPIRY_TOLERANCE_SECONDS = 30;
+const BAD_ASSERTION = 'connector.bad_assertion';
+const ALGORITHMS = {
+    EdDSA: { kty: 'OKP', crv: 'Ed25519', members: ['kty', 'crv', 'x'] },
+    ES256: { kty: 'EC', crv: 'P-256', members: ['kty', 'crv', 'x', 'y'] },
+};
+const REQUIRED_CLAIMS = Object.keys({ iss: 0, sub: 0, aud: 0, exp: 0, iat: 0, jti: 0, space: 0, scope: 0 });
+const B64URL = /^[A-Za-z0-9_-]*$/;
+function decodeSegment(segment) {
+    if (!B64URL.test(segment) || segment.length % 4 === 1)
+        return null;
+    const bytes = Buffer.from(segment, 'base64url');
+    return bytes.toString('base64url') === segment ? bytes : null;
+}
+function jsonObject(bytes) {
+    if (bytes === null)
+        return null;
+    try {
+        const v = JSON.parse(bytes.toString('utf8'));
+        return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function verifyAssertion(compactJws, options) {
+    if (typeof options?.issuer !== 'string' || options.issuer === '' || typeof options.audience !== 'string' || options.audience === '' || !Number.isFinite(options.now)) {
+        throw new TypeError('verifyAssertion needs a non-empty issuer and audience and a finite now (seconds since the epoch)');
+    }
+    const refuse = (step) => ({ ok: false, code: BAD_ASSERTION, step });
+    const segments = typeof compactJws === 'string' ? compactJws.split('.') : [];
+    if (segments.length !== 3)
+        return refuse('decode');
+    const [h = '', p = '', s = ''] = segments;
+    const header = jsonObject(decodeSegment(h));
+    const claims = jsonObject(decodeSegment(p));
+    const signature = decodeSegment(s);
+    if (header === null || claims === null || signature === null || 'crit' in header)
+        return refuse('decode');
+    const alg = header.alg;
+    if (typeof alg !== 'string' || !Object.hasOwn(ALGORITHMS, alg))
+        return refuse('algorithm');
+    const wanted = ALGORITHMS[alg];
+    const kid = header.kid;
+    if (typeof kid !== 'string' || kid === '')
+        return refuse('key');
+    const set = options.keys !== null && typeof options.keys === 'object' ? options.keys.keys : undefined;
+    if (!Array.isArray(set))
+        return refuse('key');
+    const found = set.filter((k) => k !== null && typeof k === 'object' && k.kid === kid);
+    if (found.length !== 1)
+        return refuse('key');
+    const jwk = found[0];
+    if (jwk.kty !== wanted.kty || jwk.crv !== wanted.crv || (jwk.alg !== undefined && jwk.alg !== alg))
+        return refuse('key');
+    let key;
+    try {
+        key = createPublicKey({ key: Object.fromEntries(wanted.members.map((m) => [m, jwk[m]])), format: 'jwk' });
+    }
+    catch {
+        return refuse('key');
+    }
+    const input = Buffer.from(`${h}.${p}`, 'ascii');
+    let valid = false;
+    try {
+        valid = alg === 'EdDSA' ? verify(null, input, key, signature) : signature.length === 64 && verify('sha256', input, { key, dsaEncoding: 'ieee-p1363' }, signature);
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return refuse('signature');
+    if (REQUIRED_CLAIMS.some((c) => !Object.hasOwn(claims, c)))
+        return refuse('claims');
+    const { iat, jti } = claims;
+    if (typeof iat !== 'number' || !Number.isInteger(iat) || iat < 0 || typeof jti !== 'string' || jti === '')
+        return refuse('claims');
+    if (claims.iss !== options.issuer)
+        return refuse('issuer');
+    if (claims.aud !== options.audience)
+        return refuse('audience');
+    const exp = claims.exp;
+    if (typeof exp !== 'number' || !Number.isInteger(exp) || exp < 0 || options.now >= exp + EXPIRY_TOLERANCE_SECONDS)
+        return refuse('expiry');
+    const { sub, space, scope } = claims;
+    if (typeof sub !== 'string' || sub === '')
+        return refuse('subject');
+    if (typeof space !== 'string' || space === '')
+        return refuse('space');
+    if (typeof scope !== 'string' || !SCOPE_PATTERN.test(scope))
+        return refuse('scope');
+    return { ok: true, principal: { kind: 'assertion', sub, space, scope: scope.split(' ') } };
+}
+const ANONYMOUS = Object.freeze({ kind: 'anonymous', scope: Object.freeze(['tool:*']) });
+export function standaloneResolver() {
+    return { resolve: () => ({ ok: true, principal: ANONYMOUS }) };
+}
+export function hostedResolver(options) {
+    if (typeof options?.issuer !== 'string' || options.issuer === '' || typeof options.audience !== 'string' || options.audience === '') {
+        throw new TypeError('hostedResolver needs a non-empty issuer and audience');
+    }
+    const clock = options.clock ?? (() => Math.floor(Date.now() / 1000));
+    const refuse = (reason) => ({ ok: false, code: BAD_ASSERTION, reason });
+    return {
+        resolve(request) {
+            const values = [];
+            for (const [name, value] of Object.entries(request?.headers ?? {})) {
+                if (name.toLowerCase() !== ASSERTION_HEADER || value === undefined)
+                    continue;
+                if (typeof value === 'string')
+                    values.push(value);
+                else
+                    for (const v of value)
+                        values.push(v);
+            }
+            if (values.length === 0)
+                return refuse(`the request carries no ${ASSERTION_HEADER} header; a principal is never taken from a name header`);
+            if (values.length > 1)
+                return refuse(`the ${ASSERTION_HEADER} header is given more than once`);
+            const verdict = verifyAssertion(values[0] ?? '', { issuer: options.issuer, audience: options.audience, keys: options.keys, now: clock() });
+            return verdict.ok ? { ok: true, principal: verdict.principal } : refuse(`the assertion was refused at the ${verdict.step} step`);
+        },
+    };
+}

package/dist/redact.d.ts

@@ -0,0 +1,18 @@
+export declare function plainValues(values: readonly string[]): string[];
+export declare function unescapeView(text: string, final: boolean): {
+    readonly decoded: string;
+    readonly starts: number[];
+    readonly end: number;
+};
+export declare function secretMatcher(values: readonly string[]): (line: Buffer, parsed: unknown) => boolean;
+export declare const REDACTED = "[redacted]";
+export declare class Scrubber {
+    private readonly plain;
+    private readonly keep;
+    private readonly decoder;
+    private held;
+    constructor(values: readonly string[]);
+    feed(chunk: Buffer): Buffer;
+    flush(): Buffer;
+    private scan;
+}

package/dist/redact.js

@@ -0,0 +1,121 @@
+import { StringDecoder } from 'node:string_decoder';
+export function plainValues(values) {
+    return [...new Set(values.flatMap((v) => [v, v.trim()]).filter((v) => v !== ''))];
+}
+const SIMPLE_ESCAPES = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+const HEX4 = /^[0-9a-fA-F]{4}$/;
+export function unescapeView(text, final) {
+    const starts = [];
+    let decoded = '';
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] === '\\') {
+            const c = text[i + 1];
+            if (c === undefined && !final)
+                break;
+            if (c === 'u') {
+                const hex = text.slice(i + 2, i + 6);
+                if (hex.length < 4 && !final)
+                    break;
+                if (HEX4.test(hex)) {
+                    starts.push(i);
+                    decoded += String.fromCharCode(parseInt(hex, 16));
+                    i += 6;
+                    continue;
+                }
+            }
+            else if (c !== undefined && Object.hasOwn(SIMPLE_ESCAPES, c)) {
+                starts.push(i);
+                decoded += SIMPLE_ESCAPES[c];
+                i += 2;
+                continue;
+            }
+        }
+        starts.push(i);
+        decoded += text[i];
+        i += 1;
+    }
+    starts.push(i);
+    return { decoded, starts, end: i };
+}
+function inDecodedJson(value, plain) {
+    const stack = [value];
+    while (stack.length > 0) {
+        const v = stack.pop();
+        if (typeof v === 'string') {
+            if (plain.some((p) => v.includes(p)))
+                return true;
+        }
+        else if (Array.isArray(v))
+            for (const x of v)
+                stack.push(x);
+        else if (v !== null && typeof v === 'object') {
+            for (const [k, x] of Object.entries(v)) {
+                if (plain.some((p) => k.includes(p)))
+                    return true;
+                stack.push(x);
+            }
+        }
+    }
+    return false;
+}
+export function secretMatcher(values) {
+    const plain = plainValues(values);
+    return (line, parsed) => {
+        if (plain.length === 0)
+            return false;
+        const text = line.toString('utf8');
+        const { decoded } = unescapeView(text, true);
+        return plain.some((p) => text.includes(p) || decoded.includes(p)) || inDecodedJson(parsed, plain);
+    };
+}
+export const REDACTED = '[redacted]';
+export class Scrubber {
+    plain;
+    keep;
+    decoder = new StringDecoder('utf8');
+    held = '';
+    constructor(values) {
+        this.plain = plainValues(values);
+        this.keep = this.plain.reduce((n, p) => Math.max(n, p.length - 1), 0);
+    }
+    feed(chunk) {
+        if (this.plain.length === 0)
+            return chunk;
+        return this.scan(this.held + this.decoder.write(chunk), false);
+    }
+    flush() {
+        if (this.plain.length === 0)
+            return Buffer.alloc(0);
+        return this.scan(this.held + this.decoder.end(), true);
+    }
+    scan(text, final) {
+        const view = unescapeView(text, final);
+        const spans = [];
+        for (const p of this.plain) {
+            for (let at = text.indexOf(p); at !== -1; at = text.indexOf(p, at + 1))
+                spans.push([at, at + p.length]);
+            for (let at = view.decoded.indexOf(p); at !== -1; at = view.decoded.indexOf(p, at + 1))
+                spans.push([view.starts[at] ?? 0, view.starts[at + p.length] ?? view.end]);
+        }
+        const units = view.starts.length - 1;
+        let cut = final ? text.length : (view.starts[Math.max(0, units - this.keep)] ?? view.end);
+        spans.sort((a, b) => a[0] - b[0]);
+        for (const [s, e] of spans)
+            if (s < cut && e > cut)
+                cut = e;
+        let out = '';
+        let at = 0;
+        for (const [s, e] of spans) {
+            if (s >= cut)
+                break;
+            if (e <= at)
+                continue;
+            out += text.slice(at, Math.max(at, s)) + REDACTED;
+            at = Math.max(at, e);
+        }
+        out += text.slice(at, cut);
+        this.held = text.slice(cut);
+        return Buffer.from(out, 'utf8');
+    }
+}

package/dist/scope.d.ts

@@ -0,0 +1 @@
+export declare function isGranted(scope: readonly string[], tool: string): boolean;

package/dist/scope.js

@@ -0,0 +1,5 @@
+export function isGranted(scope, tool) {
+    if (tool === '')
+        return false;
+    return scope.includes('tool:*') || scope.includes(`tool:${tool}`);
+}

package/dist/secrets.d.ts

@@ -0,0 +1,49 @@
+export interface SecretHandle {
+    readonly connector: string;
+    readonly name: string;
+    readonly source: 'file';
+    readonly secret: boolean;
+    readonly expiresAt?: string;
+}
+export type SecretListing = {
+    readonly ok: true;
+    readonly handles: readonly SecretHandle[];
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export interface PutOptions {
+    readonly expiresAt?: string;
+    readonly secret?: boolean;
+}
+export interface FileSecrets {
+    readonly directory: string;
+    list(): SecretListing;
+    put(name: string, value: string, options?: PutOptions): SecretHandle;
+    withLock<T>(fn: () => T): T;
+}
+export declare const isSecret: (handle: SecretHandle) => boolean;
+export declare const HANDLE_NAME: RegExp;
+export declare const LOCK_FILE = ".auth.lock";
+export declare const LOCK_WAIT_MS = 5000;
+export declare function handleDirectory(configDir: string, connector: string): string;
+export declare function handleFilePath(configDir: string, handle: SecretHandle): string;
+export declare function readSecretValue(configDir: string, handle: SecretHandle): Buffer;
+export interface LaunchSecrets {
+    readonly handles: readonly SecretHandle[];
+    readonly files: ReadonlyMap<string, string>;
+    readonly values: readonly string[];
+    remove(): void;
+}
+export type LaunchCopy = ({
+    readonly ok: true;
+} & LaunchSecrets) | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare const NO_HANDLES: LaunchSecrets;
+export declare function copyForLaunch(configDir: string, connector: string): LaunchCopy;
+export declare function openFileSecrets(options: {
+    readonly configDir: string;
+    readonly connector: string;
+}): FileSecrets;