@sema-agent/connectors 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,122 @@ All notable changes to this package are documented here. Released sections are
 frozen: once a version is published its section is never edited again; new text
 goes into the next version's section.
 
+## 0.3.0 (2026-10-15)
+
+### Added
+
+- The default catalog seed (CN-009): `sema-connector seed --config-dir
+  <absolute path>`, the launcher's second command, and `seed({ configDir })`
+  mount every installed connector of the default catalog into
+  `config.d/mcp.json`. The catalog is `DEFAULT_CONNECTORS` (today `gitea` and
+  `github`, CN-044),
+  the one list of default connectors; `SEED_VERSION` is the newest version
+  that added a name. Each connector is resolved with the launcher's own rule
+  first (one that is not installed gets no entry) and mounted only through
+  `mount`, so another entry under its name is never overwritten.
+  `config.d/.sema-connector-seed.json` records what each name came to
+  (mounted, present, not installed): a name recorded as mounted or present is
+  never mounted again, so an entry a person removed stays removed; a conflict
+  or a refusal is not recorded and is tried again. Seeds on one directory
+  exclude each other with `config.d/.sema-connector-seed.json.lock` (a second
+  seed refuses as `locked`). One line per connector on stdout; exit 0 when
+  every connector is mounted, present or not installed, 1 otherwise. A marker
+  the seed cannot read refuses it before any mount; a marker write that fails
+  leaves the old marker as it was and the mounted entries in place.
+- `pinnedUpstream({ connector, upstream, lockFile, handles })` (CN-044): what
+  a connector that runs a third-party MCP server takes from the shared layer,
+  so that no connector package carries its own copy. `install(configDir)` is
+  the install subcommand: this platform's release archive from the source the
+  package's `binaries.lock.json` gives (`https`, redirects followed only to
+  `https`, or `file` for a local copy of the releases), its sha256 compared
+  with the lock before anything is written, then the archive and its
+  `upstream` entry kept in `<configuration directory>/connectors/<name>/bin/`
+  (directory 0700, program 0755), each file written whole before it replaces
+  the old one; nothing changes when the pinned build is there. `start(env)`
+  checks `CONNECTOR_DIR`, one `<NAME>_FILE` per handle naming a regular file
+  (not a symbolic link) inside it, and the pinned build in the bin directory
+  (the same check as install's), and refuses with a sentence naming what to
+  run; its `run(args, extra)` starts the program as the connector's child on
+  the same standard input, output and error, with the connector's environment
+  minus `CONNECTOR_DIR` and the handle paths plus `extra`, passes `SIGTERM`,
+  `SIGINT` and `SIGHUP` on, and ends as the program ends. The Gitea connector
+  is its first user (moved from its own package) and the GitHub connector its
+  second.
+
+### Changed
+
+- A launcher command line that starts with neither `run` nor `seed` is
+  refused with `expected the command "run" or "seed"` (exit 2, as before).
+- `readStdinJson` with one key names it as "the key" in its refusals
+  (`the object must have exactly the key token`); with two or more keys the
+  wording is as before.
+
+## 0.2.0 (2026-10-15)
+
+### Added
+
+- Handles that are not secrets (CN-038). `<handle>.meta.json` may say
+  `"secret": false`; such a handle is delivered to the connector like every
+  handle (a per-launch 0600 copy named by `<NAME>_FILE`), but the launcher
+  does not withhold its value and the status does not count it. Every other
+  handle is a secret, as before. `openFileSecrets().put(name, value,
+  { secret: false })` writes it, `SecretHandle.secret` reports it, and a
+  later `put` without it makes the handle a secret again.
+- `CONNECTOR_DIR` (CN-038): the launcher gives its connector the absolute path
+  of the connector's directory, `<configuration directory>/connectors/<name>`
+  (standalone; it may not exist), so a connector no longer infers it from the
+  path of a handle copy. A hosted connector, which has no configuration
+  directory and no handles in this release, gets a fresh path of its own that
+  does not exist. A `CONNECTOR_DIR` set for the launcher never reaches the
+  connector.
+- The lock of a connector's directory (CN-038), `.auth.lock`: every write of
+  the secrets backend and every launch's listing and copy of the handles hold
+  it, so a launch copies a group of writes before or after the group, never in
+  between. `openFileSecrets().withLock(fn)` holds it across several writes. A
+  taker waits up to 5 seconds for another holder, then refuses (the launcher
+  with exit 2 and `connector.internal`); only the holder removes the lock, and
+  one left by a process that died is removed by hand. `FileSecrets.directory`
+  names the connector's directory.
+- The connector CLI kit (CN-039): `connectorCli` runs a connector package's
+  bin (no arguments: the connector's server; `install`, `auth`, `mount`,
+  `status` without arguments on the configuration directory of
+  `resolveConfigDir`), `cliOutput`, `readStdinLine`, `readStdinJson` (one line
+  holding a JSON object with exactly the given keys, each named once, every
+  value a string), `mountCommand`, `statusCommand` (the status resource read
+  through the launcher within 10 seconds) and `isLoopbackHttpOrHttps`, the
+  one rule for an address a connector sends requests to (the rule of a key set
+  URL).
+- `writeAll(fd, data)` (CN-042): the one whole write. It writes every byte of
+  `data` into the empty file open at `fd` (a write that writes nothing or fails
+  ends it with an error), syncs the file and checks that its size is the number
+  of bytes, or throws. Every file this package writes goes through it, and a
+  connector package writes its own files with it.
+
+### Changed
+
+- The status counts secret handles only: a connector whose only handles are
+  not secrets is `unauthorized`, and the expiry of a handle that is not a
+  secret changes nothing (CN-038).
+- `<handle>.meta.json` must be a JSON object whose only keys are `expiresAt`
+  and `secret`, each named once; another key, a key named twice or a `secret`
+  that is not `true` or `false` makes the directory refused (another key used
+  to be ignored, and an object without `expiresAt` refused) (CN-038).
+
+### Fixed
+
+- A write cut short is no longer taken as done (CN-042). A write can stop short
+  without an error (a file size limit, a full disk); `mount` used to rename the
+  cut-short text over `mcp.json` and report it written, losing the other
+  entries, and `put` stored a cut-short value and reported success. Now nothing
+  is put in place before it is written whole: `mount` refuses with the new
+  reason `write_failed` and `put` throws, the temporary file is removed and the
+  old file (or its absence) stays as it was. The lock files and the per-launch
+  copies of the handles are written the same way.
+- The scope judge never grants the empty tool name (CN-036): a `tools/call`
+  whose name is `""` is refused with `connector.forbidden_scope` also under
+  `tool:*` (or a bare `tool:`), and a listed tool whose name is `""` is not
+  listed.
+
 ## 0.1.0 (2026-10-14)
 
 ### Added

package/dist/cli-kit.d.ts

@@ -0,0 +1,34 @@
+import { type Env } from './config-dir.js';
+export interface CliOutput {
+    readonly program: string;
+    say(line: string): void;
+    complain(line: string): void;
+}
+export declare function cliOutput(name: string): CliOutput;
+export interface ConnectorCommands {
+    readonly name: string;
+    readonly serve: (env: Env) => void | number | Promise<number>;
+    readonly install: (configDir: string) => number | Promise<number>;
+    readonly auth: (configDir: string) => number | Promise<number>;
+    readonly authReads: string;
+}
+export declare function connectorCli(commands: ConnectorCommands, argv: readonly string[], env: Env): Promise<number | undefined>;
+export type StdinLine = {
+    readonly ok: true;
+    readonly line: string;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare function readStdinLine(limit: number): Promise<StdinLine>;
+export type StdinJson = {
+    readonly ok: true;
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+export declare const listed: (keys: readonly string[]) => string;
+export declare function readStdinJson(limit: number, keys: readonly string[]): Promise<StdinJson>;
+export declare function mountCommand(name: string, configDir: string): number;
+export declare function statusCommand(name: string, configDir: string): Promise<number>;

package/dist/cli-kit.js

@@ -0,0 +1,224 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveConfigDir } from './config-dir.js';
+import { CONNECTOR_NAME } from './connector-name.js';
+import { hasRepeatedKey } from './json-text.js';
+import { mount } from './mount.js';
+export function cliOutput(name) {
+    if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
+        throw new Error('a connector name is lowercase letters and digits in hyphen-separated words');
+    const program = `sema-connector-${name}`;
+    return {
+        program,
+        say: (line) => void process.stdout.write(`${line}\n`),
+        complain: (line) => void process.stderr.write(`${program}: ${line}\n`),
+    };
+}
+const SUBCOMMANDS = ['install', 'auth', 'mount', 'status'];
+export async function connectorCli(commands, argv, env) {
+    const { complain, program } = cliOutput(commands.name);
+    const [command, ...rest] = argv;
+    if (command === undefined) {
+        const code = await commands.serve(env);
+        return typeof code === 'number' ? code : undefined;
+    }
+    const usage = `usage: ${program} [${SUBCOMMANDS.join(' | ')}]   (no argument: the connector's MCP stdio server; auth reads ${commands.authReads} from standard input)`;
+    if (!SUBCOMMANDS.includes(command)) {
+        complain(`unknown subcommand\n${usage}`);
+        return 2;
+    }
+    if (rest.length > 0) {
+        complain(`${command} takes no arguments${command === 'auth' ? ` (it reads ${commands.authReads} from standard input, never from an argument)` : ''}\n${usage}`);
+        return 2;
+    }
+    const config = resolveConfigDir(env);
+    if (!config.ok) {
+        complain(config.reason);
+        return 2;
+    }
+    if (command === 'install')
+        return commands.install(config.dir);
+    if (command === 'auth')
+        return commands.auth(config.dir);
+    if (command === 'mount')
+        return mountCommand(commands.name, config.dir);
+    return statusCommand(commands.name, config.dir);
+}
+export async function readStdinLine(limit) {
+    if (process.stdin.isTTY)
+        return { ok: false, problem: 'standard input is a terminal here; pipe the input in instead (a token typed on a terminal would be shown)' };
+    const parts = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += b.length;
+        if (size > limit)
+            return { ok: false, problem: `standard input holds more than ${limit} bytes; one line is read` };
+        parts.push(b);
+    }
+    const line = Buffer.concat(parts).toString('utf8').replace(/\r?\n$/, '');
+    if (/[\r\n]/.test(line))
+        return { ok: false, problem: 'standard input must hold exactly one line' };
+    return { ok: true, line };
+}
+export const listed = (keys) => (keys.length < 2 ? keys.join('') : `${keys.slice(0, -1).join(', ')} and ${keys[keys.length - 1]}`);
+export async function readStdinJson(limit, keys) {
+    const read = await readStdinLine(limit);
+    if (!read.ok)
+        return read;
+    const exactly = keys.length === 1 ? `exactly the key ${listed(keys)}` : `exactly the keys ${listed(keys)}`;
+    const shape = `standard input must be one JSON object with ${exactly}, ${keys.length === 1 ? 'a string' : 'each a string'}, on one line`;
+    let value;
+    try {
+        value = JSON.parse(read.line);
+    }
+    catch {
+        return { ok: false, problem: shape };
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return { ok: false, problem: shape };
+    if (hasRepeatedKey(read.line))
+        return { ok: false, problem: 'the object names a key more than once' };
+    const object = value;
+    const own = Object.keys(object);
+    if (own.length !== keys.length || !keys.every((k) => own.includes(k)))
+        return { ok: false, problem: `the object must have ${exactly}` };
+    if (!keys.every((k) => typeof object[k] === 'string'))
+        return { ok: false, problem: shape };
+    return { ok: true, values: Object.fromEntries(keys.map((k) => [k, object[k]])) };
+}
+export function mountCommand(name, configDir) {
+    const { say, complain } = cliOutput(name);
+    let r;
+    try {
+        r = mount({ name, configDir });
+    }
+    catch (e) {
+        complain(`mount failed: ${e instanceof Error ? e.message : 'unknown error'}`);
+        return 1;
+    }
+    if (!r.ok) {
+        complain(`mount refused (${r.reason}): ${r.message}`);
+        return 1;
+    }
+    say(r.changed ? `mounted connector ${name} in ${r.file}; restart the engine to apply` : `connector ${name} is already mounted in ${r.file}`);
+    return 0;
+}
+const PROTOCOL_VERSION = '2025-11-25';
+const STATUS_TIMEOUT_MS = 10_000;
+const KILL_GRACE_MS = 2_000;
+const SHOWN_LINES = 5;
+const RECEIPT_PREFIX = 'sema-connector: receipt ';
+function ownManifest() {
+    const url = new URL('../package.json', import.meta.url);
+    const manifest = JSON.parse(readFileSync(url, 'utf8'));
+    return { version: manifest.version, launcher: join(dirname(fileURLToPath(url)), manifest.bin['sema-connector'] ?? '') };
+}
+function lineReader(stream) {
+    const lines = [];
+    const waiters = [];
+    let rest = '';
+    let ended = false;
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        rest += chunk;
+        let at;
+        while ((at = rest.indexOf('\n')) !== -1) {
+            const line = rest.slice(0, at);
+            rest = rest.slice(at + 1);
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                lines.push(line);
+        }
+    });
+    stream.on('close', () => {
+        ended = true;
+        for (const waiter of waiters.splice(0))
+            waiter(null);
+    });
+    return () => {
+        const line = lines.shift();
+        if (line !== undefined)
+            return Promise.resolve(line);
+        if (ended)
+            return Promise.resolve(null);
+        return new Promise((resolve) => waiters.push(resolve));
+    };
+}
+export async function statusCommand(name, configDir) {
+    const { program, say, complain } = cliOutput(name);
+    const own = ownManifest();
+    const child = spawn(process.execPath, [own.launcher, 'run', name, '--mode', 'standalone', '--transport', 'stdio', '--config-dir', configDir], { stdio: ['pipe', 'pipe', 'pipe'] });
+    const exited = new Promise((resolve) => child.on('exit', (code) => resolve(code)));
+    const errors = [];
+    child.stderr.on('data', (d) => errors.push(d));
+    child.stdin.on('error', () => undefined);
+    const nextLine = lineReader(child.stdout);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.stdout.destroy();
+        child.stderr.destroy();
+        child.kill('SIGTERM');
+        setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS).unref();
+    }, STATUS_TIMEOUT_MS);
+    const write = (message) => void child.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n');
+    const reply = async (id, method, params) => {
+        write({ id, method, ...(params === undefined ? {} : { params }) });
+        for (;;) {
+            const line = await nextLine();
+            if (line === null)
+                return null;
+            try {
+                const m = JSON.parse(line);
+                if (m?.id === id)
+                    return m;
+            }
+            catch { }
+        }
+    };
+    let found = null;
+    let problem = null;
+    try {
+        const init = await reply(1, 'initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: program, version: own.version } });
+        if (init?.result === undefined)
+            problem = 'the launcher did not complete initialize';
+        else {
+            write({ method: 'notifications/initialized' });
+            const list = await reply(2, 'resources/list');
+            const entries = list?.result?.resources;
+            const uri = Array.isArray(entries) && entries.length === 1 ? entries[0]?.uri : undefined;
+            if (typeof uri !== 'string')
+                problem = 'the launcher did not list exactly one resource, its status';
+            else {
+                const read = await reply(3, 'resources/read', { uri });
+                const text = read?.result?.contents?.[0]?.text;
+                if (typeof text !== 'string')
+                    problem = `the status could not be read${typeof read?.error?.message === 'string' ? `: ${read.error.message}` : ''}`;
+                else
+                    found = JSON.parse(text);
+            }
+        }
+    }
+    catch {
+        problem = 'the launcher answered with something that is not JSON';
+    }
+    finally {
+        child.stdin.end();
+    }
+    const code = await exited;
+    clearTimeout(timer);
+    if (found !== null && !timedOut) {
+        say(JSON.stringify(found));
+        return 0;
+    }
+    complain(timedOut ? `the launcher did not answer within ${STATUS_TIMEOUT_MS} ms` : (problem ?? `the launcher exited with code ${String(code)}`));
+    const said = Buffer.concat(errors).toString('utf8').split('\n').filter((l) => l.trim() !== '' && !l.startsWith(RECEIPT_PREFIX));
+    for (const line of said.slice(-SHOWN_LINES))
+        complain(`the launcher said: ${line}`);
+    return 1;
+}

package/dist/index.d.ts

@@ -6,3 +6,11 @@ export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion }
 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 { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
+export type { DefaultConnector, SeedOptions, SeedReading, SeedRefusal, SeedResult } from './seed.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 { pinnedUpstream } from './pinned-upstream.js';
+export type { PinnedUpstream, PinnedUpstreamOptions, UpstreamStart } from './pinned-upstream.js';
+export { writeAll } from './write-all.js';

package/dist/index.js

@@ -2,3 +2,8 @@ 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 { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
+export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
+export { isLoopbackHttpOrHttps } from './jwks.js';
+export { pinnedUpstream } from './pinned-upstream.js';
+export { writeAll } from './write-all.js';

package/dist/jwks.d.ts

@@ -14,5 +14,6 @@ export type KeySet = {
     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

@@ -5,6 +5,9 @@ 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) {
@@ -24,7 +27,7 @@ export function keySetSource(env, issuer) {
     }
     if (url.username !== '' || url.password !== '')
         return `${from} carries credentials; a key set URL never does`;
-    if (url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK_HOSTS.includes(url.hostname)))
+    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`;
 }