@sema-agent/connectors 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,72 @@ 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.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,33 @@
+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 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,223 @@
+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 };
+}
+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 shape = `standard input must be one JSON object with exactly the keys ${listed(keys)}, 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 the keys ${listed(keys)}` };
+    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,7 @@ 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 { 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

@@ -2,3 +2,6 @@ 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/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`;
 }

package/dist/launcher.js

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { isIPv4, isIPv6 } from 'node:net';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { absoluteDir, given } from './config-dir.js';
 import { CONNECTOR_NAME } from './connector-name.js';
@@ -10,7 +11,7 @@ import { serveHttp } from './http.js';
 import { keySetSource, obtainKeySet } from './jwks.js';
 import { hostedResolver, standaloneResolver } from './principal.js';
 import { Scrubber, secretMatcher } from './redact.js';
-import { copyForLaunch, openFileSecrets } from './secrets.js';
+import { NO_HANDLES, copyForLaunch, handleDirectory } from './secrets.js';
 import { INSPECT_LIMIT_BYTES, Session } from './session.js';
 import { mintStatus } from './status.js';
 const EXIT = { ok: 0, guard: 2, notInstalled: 4, connectorFailed: 5 };
@@ -24,6 +25,7 @@ const PIECE_BYTES = 1024;
 const USAGE = 'usage: sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]';
 const FLAGS = ['--mode', '--transport', '--listen', '--config-dir'];
 const CHILD_ENV = ['HOME', 'LOGNAME', 'USER', 'PATH', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ'];
+const CONNECTOR_DIR = 'CONNECTOR_DIR';
 function guard(argv, env) {
     if (argv[0] !== 'run')
         return 'expected the command "run"';
@@ -369,17 +371,19 @@ function pump(src, dst, framing, also = [], passing, giveUp) {
         src.on('close', finish);
     });
 }
-function childEnvironment(env, secrets) {
+function childEnvironment(env, connectorDir, secrets) {
     const out = {};
     for (const name of CHILD_ENV) {
         const value = env[name];
         if (value !== undefined)
             out[name] = value;
     }
+    out[CONNECTOR_DIR] = connectorDir;
     for (const [name, path] of secrets.files)
         out[`${name}_FILE`] = path;
     return out;
 }
+const hostedConnectorDir = (name) => join(tmpdir(), `sema-connector-${randomUUID()}`, 'connectors', name);
 const describe = (o) => `connector process ${o.stalled ? `stopped reading its input (stalled input: none of it taken for ${STALL_MS / 1000} s) and ` : ''}${o.error ? `could not be started (${o.error.message})` : o.signal !== null ? `was terminated by signal ${o.signal}` : `exited with code ${String(o.code)}`}`;
 const abnormal = (o) => o.code !== 0 || o.stalled === true;
 function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
@@ -491,15 +495,14 @@ async function runStdio(packageName, binPath, childEnv, session, scrubber, stdou
     return EXIT.connectorFailed;
 }
 async function runHosted(plan, keys, packageName, binPath, env, log) {
-    const childEnv = childEnvironment(env, NO_SECRETS);
     const start = (deliver) => {
         const session = new Session({
             connector: plan.name,
-            status: (tools) => mintStatus({ handles: [], nowMs: Date.now(), tools }),
+            status: (tools) => mintStatus({ handles: NO_HANDLES.handles, nowMs: Date.now(), tools }),
             ownIdPrefix: `sema-connector/${randomUUID()}`,
-            withheld: secretMatcher(NO_SECRETS.values),
+            withheld: secretMatcher(NO_HANDLES.values),
         });
-        const run = startConnector(binPath, childEnv, session, new Scrubber(NO_SECRETS.values), (data) => deliver(String(data)), null, log, TEARDOWN_STEP_MS);
+        const run = startConnector(binPath, childEnvironment(env, hostedConnectorDir(plan.name), NO_HANDLES), session, new Scrubber(NO_HANDLES.values), (data) => deliver(String(data)), null, log, TEARDOWN_STEP_MS);
         return {
             send: (raw, principal) => run.fromUpstream(raw, principal),
             busy: () => run.toChild.behind(),
@@ -524,7 +527,6 @@ async function runHosted(plan, keys, packageName, binPath, env, log) {
     setTimeout(abandon, TEARDOWN_STEP_MS);
     return EXIT.ok;
 }
-const NO_SECRETS = { files: new Map(), values: [], remove: () => undefined };
 export async function main(argv, env) {
     const stdout = new Out(process.stdout);
     const log = new Log(new Out(process.stderr));
@@ -550,20 +552,18 @@ export async function main(argv, env) {
         }
         return finish(await runHosted(plan, keys.keys, resolved.packageName, resolved.binPath, env, log));
     }
-    const listing = openFileSecrets({ configDir: plan.configDir, connector: plan.name }).list();
-    if (!listing.ok) {
-        log.line(`sema-connector: ${INTERNAL}: ${listing.problem}\n`);
-        return finish(EXIT.guard);
-    }
-    const { handles } = listing;
     let secrets;
     try {
-        secrets = copyForLaunch(plan.configDir, plan.name, handles);
+        secrets = copyForLaunch(plan.configDir, plan.name);
     }
     catch {
         log.line(`sema-connector: ${INTERNAL}: connector ${plan.name}: its secrets cannot be read for this launch\n`);
         return finish(EXIT.guard);
     }
+    if (!secrets.ok) {
+        log.line(`sema-connector: ${INTERNAL}: ${secrets.problem}\n`);
+        return finish(EXIT.guard);
+    }
     const resolved = resolveConnector(plan.name);
     if ('reason' in resolved) {
         secrets.remove();
@@ -572,12 +572,12 @@ export async function main(argv, env) {
     }
     const session = new Session({
         connector: plan.name,
-        status: (tools) => mintStatus({ handles, nowMs: Date.now(), tools }),
+        status: (tools) => mintStatus({ handles: secrets.handles, nowMs: Date.now(), tools }),
         ownIdPrefix: `sema-connector/${randomUUID()}`,
         withheld: secretMatcher(secrets.values),
     });
     try {
-        return finish(await runStdio(resolved.packageName, resolved.binPath, childEnvironment(env, secrets), session, new Scrubber(secrets.values), stdout, log));
+        return finish(await runStdio(resolved.packageName, resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), stdout, log));
     }
     finally {
         secrets.remove();

package/dist/lock-file.d.ts

@@ -0,0 +1 @@
+export declare function takeLockFile(path: string): (() => void) | null;

package/dist/lock-file.js

@@ -0,0 +1,34 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, linkSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { writeAll } from './write-all.js';
+export function takeLockFile(path) {
+    const token = `${process.pid} ${randomBytes(12).toString('hex')}`;
+    const tmp = `${path}.${randomBytes(6).toString('hex')}`;
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+        try {
+            writeAll(fd, token);
+        }
+        finally {
+            closeSync(fd);
+        }
+        linkSync(tmp, path);
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            return null;
+        throw e;
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+    return () => {
+        let held = '';
+        try {
+            held = readFileSync(path, 'utf8');
+        }
+        catch { }
+        if (held === token)
+            rmSync(path, { force: true });
+    };
+}

package/dist/mount.d.ts

@@ -2,7 +2,7 @@ export interface MountOptions {
     readonly name: string;
     readonly configDir: string;
 }
-export type MountRefusal = 'config_dir' | 'invalid_name' | 'reserved_name' | 'unreadable' | 'unexpected_shape' | 'conflict' | 'locked' | 'changed_during_write';
+export type MountRefusal = 'config_dir' | 'invalid_name' | 'reserved_name' | 'unreadable' | 'unexpected_shape' | 'conflict' | 'locked' | 'changed_during_write' | 'write_failed';
 export type MountResult = {
     readonly ok: true;
     readonly changed: boolean;

package/dist/mount.js

@@ -1,9 +1,11 @@
-import { closeSync, fchmodSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs';
+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] } };
@@ -69,32 +71,10 @@ function plan(before, entry) {
     return { text };
 }
 const LOCK_FILE = '.mcp.json.lock';
-function lock(dir) {
-    const path = join(dir, LOCK_FILE);
-    const token = `${process.pid} ${randomBytes(12).toString('hex')}`;
-    const tmp = join(dir, `${LOCK_FILE}.${randomBytes(6).toString('hex')}`);
-    writeFileSync(tmp, token, { mode: 0o600, flag: 'wx' });
-    try {
-        linkSync(tmp, path);
-    }
-    catch (e) {
-        if (e.code === 'EEXIST')
-            return null;
-        throw e;
-    }
-    finally {
-        rmSync(tmp, { force: true });
-    }
-    return () => {
-        let held = '';
-        try {
-            held = readFileSync(path, 'utf8');
-        }
-        catch { }
-        if (held === token)
-            rmSync(path, { force: true });
-    };
-}
+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');
@@ -117,8 +97,14 @@ export function mount(options) {
         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');
-    mkdirSync(dir, { recursive: true });
-    const unlock = lock(dir);
+    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 {
@@ -155,8 +141,7 @@ function write(file, entry, refuse) {
         try {
             if (mode !== null)
                 fchmodSync(fd, mode);
-            writeSync(fd, text);
-            fsyncSync(fd);
+            writeAll(fd, text);
         }
         finally {
             closeSync(fd);
@@ -169,7 +154,7 @@ function write(file, entry, refuse) {
     }
     catch (e) {
         rmSync(tmp, { force: true });
-        throw e;
+        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/scope.js

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

package/dist/secrets.d.ts

@@ -2,6 +2,7 @@ export interface SecretHandle {
     readonly connector: string;
     readonly name: string;
     readonly source: 'file';
+    readonly secret: boolean;
     readonly expiresAt?: string;
 }
 export type SecretListing = {
@@ -13,21 +14,35 @@ export type SecretListing = {
 };
 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 declare function copyForLaunch(configDir: string, connector: string, handles: readonly SecretHandle[]): LaunchSecrets;
+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;

package/dist/secrets.js

@@ -1,12 +1,20 @@
 import { randomBytes } from 'node:crypto';
-import { closeSync, constants, fchmodSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { closeSync, constants, fchmodSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { CONNECTOR_NAME } from './connector-name.js';
+import { hasRepeatedKey } from './json-text.js';
+import { takeLockFile } from './lock-file.js';
+import { writeAll } from './write-all.js';
+export const isSecret = (handle) => handle.secret !== false;
 export const HANDLE_NAME = /^[A-Z][A-Z0-9_]*$/;
-const EXPIRY_SUFFIX = '.meta.json';
+const META_SUFFIX = '.meta.json';
+const META_KEYS = ['expiresAt', 'secret'];
 const TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$/;
 const FILE_MODE = 0o600;
 const DIRECTORY_MODE = 0o700;
+export const LOCK_FILE = '.auth.lock';
+export const LOCK_WAIT_MS = 5000;
+const LOCK_POLL_MS = 25;
 export function handleDirectory(configDir, connector) {
     return join(configDir, 'connectors', connector);
 }
@@ -22,22 +30,75 @@ export function readSecretValue(configDir, handle) {
         closeSync(fd);
     }
 }
-export function copyForLaunch(configDir, connector, handles) {
-    if (handles.length === 0)
-        return { files: new Map(), values: [], remove: () => undefined };
-    const dir = mkdtempSync(join(handleDirectory(configDir, connector), '.launch-'));
-    const remove = () => rmSync(dir, { recursive: true, force: true });
+const held = new Set();
+const pause = (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function locked(dir, connector, fn) {
+    const path = join(dir, LOCK_FILE);
+    if (held.has(path))
+        return { ok: true, value: fn() };
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let release = takeLockFile(path);
+    while (release === null) {
+        if (Date.now() >= deadline)
+            return { ok: false, problem: `connector ${connector}: another process held connectors/${connector}/${LOCK_FILE} for ${LOCK_WAIT_MS / 1000} s (an auth writing the handles, or a launch copying them); a lock left by a process that died is removed by hand` };
+        pause(LOCK_POLL_MS);
+        release = takeLockFile(path);
+    }
+    held.add(path);
+    try {
+        const value = fn();
+        if (typeof value?.then === 'function')
+            throw new Error('withLock runs a synchronous function: the lock is released as soon as it returns');
+        return { ok: true, value };
+    }
+    finally {
+        held.delete(path);
+        release();
+    }
+}
+export const NO_HANDLES = { handles: [], files: new Map(), values: [], remove: () => undefined };
+export function copyForLaunch(configDir, connector) {
+    const dir = handleDirectory(configDir, connector);
+    try {
+        lstatSync(dir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { ok: true, ...NO_HANDLES };
+        return { ok: false, problem: `connector ${connector}: the secrets directory cannot be read` };
+    }
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        return { ok: false, problem: `connector ${connector}: ${dirProblem}` };
+    const r = locked(dir, connector, () => copyHandles(configDir, dir, connector));
+    return r.ok ? r.value : r;
+}
+function copyHandles(configDir, dir, connector) {
+    const listing = listHandles(dir, connector);
+    if (!listing.ok)
+        return listing;
+    if (listing.handles.length === 0)
+        return { ok: true, ...NO_HANDLES };
+    const copies = mkdtempSync(join(dir, '.launch-'));
+    const remove = () => rmSync(copies, { recursive: true, force: true });
     try {
         const files = new Map();
         const values = [];
-        for (const handle of handles) {
+        for (const handle of listing.handles) {
             const bytes = readSecretValue(configDir, handle);
-            const path = join(dir, handle.name);
-            writeFileSync(path, bytes, { mode: FILE_MODE, flag: 'wx' });
+            const path = join(copies, handle.name);
+            const fd = openSync(path, 'wx', FILE_MODE);
+            try {
+                writeAll(fd, bytes);
+            }
+            finally {
+                closeSync(fd);
+            }
             files.set(handle.name, path);
-            values.push(bytes.toString('utf8'));
+            if (isSecret(handle))
+                values.push(bytes.toString('utf8'));
         }
-        return { files, values, remove };
+        return { ok: true, handles: listing.handles, files, values, remove };
     }
     catch (e) {
         remove();
@@ -45,6 +106,25 @@ export function copyForLaunch(configDir, connector, handles) {
     }
 }
 const validExpiry = (v) => typeof v === 'string' && TIMESTAMP.test(v) && Number.isFinite(Date.parse(v));
+function readMeta(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (v === null || typeof v !== 'object' || Array.isArray(v) || hasRepeatedKey(text))
+        return null;
+    const meta = v;
+    if (!Object.keys(meta).every((k) => META_KEYS.includes(k)))
+        return null;
+    if (Object.hasOwn(meta, 'expiresAt') && !validExpiry(meta.expiresAt))
+        return null;
+    if (Object.hasOwn(meta, 'secret') && typeof meta.secret !== 'boolean')
+        return null;
+    return { ...(validExpiry(meta.expiresAt) ? { expiresAt: meta.expiresAt } : {}), secret: meta.secret !== false };
+}
 function entryProblem(path, kind, label) {
     let st;
     try {
@@ -89,24 +169,24 @@ function listHandles(dir, connector) {
         const problem = entryProblem(join(dir, name), 'file', `secret file ${name}`);
         if (problem !== null)
             return refuse(problem);
-        const expiryFile = name + EXPIRY_SUFFIX;
-        if (!names.includes(expiryFile)) {
-            handles.push({ connector, name, source: 'file' });
+        const metaFile = name + META_SUFFIX;
+        if (!names.includes(metaFile)) {
+            handles.push({ connector, name, source: 'file', secret: true });
             continue;
         }
-        const expiryProblem = entryProblem(join(dir, expiryFile), 'file', `expiry file ${expiryFile}`);
-        if (expiryProblem !== null)
-            return refuse(expiryProblem);
-        let expiresAt;
+        const metaProblem = entryProblem(join(dir, metaFile), 'file', `metadata file ${metaFile}`);
+        if (metaProblem !== null)
+            return refuse(metaProblem);
+        let meta;
         try {
-            expiresAt = JSON.parse(readFileSync(join(dir, expiryFile), 'utf8')).expiresAt;
+            meta = readMeta(readFileSync(join(dir, metaFile), 'utf8'));
         }
         catch {
-            expiresAt = undefined;
+            meta = null;
         }
-        if (!validExpiry(expiresAt))
-            return refuse(`expiry file ${expiryFile} does not hold {"expiresAt": "<RFC 3339 UTC time>"}`);
-        handles.push({ connector, name, source: 'file', expiresAt });
+        if (meta === null)
+            return refuse(`metadata file ${metaFile} does not hold a JSON object whose only keys are "expiresAt" (an RFC 3339 UTC time) and "secret" (true or false), each named once`);
+        handles.push({ connector, name, source: 'file', ...meta });
     }
     return { ok: true, handles };
 }
@@ -116,8 +196,7 @@ function writePrivately(path, text) {
         const fd = openSync(tmp, 'wx', FILE_MODE);
         try {
             fchmodSync(fd, FILE_MODE);
-            writeSync(fd, text);
-            fsyncSync(fd);
+            writeAll(fd, text);
         }
         finally {
             closeSync(fd);
@@ -129,6 +208,25 @@ function writePrivately(path, text) {
         throw e;
     }
 }
+function ensureDirectory(dir, connector) {
+    mkdirSync(dir, { recursive: true, mode: DIRECTORY_MODE });
+    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
+    if (dirProblem !== null)
+        throw new Error(`connector ${connector}: ${dirProblem}`);
+}
+function writeHandle(dir, connector, name, value, options) {
+    const secret = options.secret !== false;
+    const expiry = options.expiresAt === undefined ? {} : { expiresAt: options.expiresAt };
+    const meta = { ...expiry, ...(secret ? {} : { secret: false }) };
+    const metaFile = join(dir, name + META_SUFFIX);
+    const writeMeta = () => (Object.keys(meta).length === 0 ? rmSync(metaFile, { force: true }) : writePrivately(metaFile, JSON.stringify(meta) + '\n'));
+    if (secret)
+        writeMeta();
+    writePrivately(join(dir, name), value);
+    if (!secret)
+        writeMeta();
+    return { connector, name, source: 'file', secret, ...expiry };
+}
 function putHandle(dir, connector, name, value, options) {
     if (!HANDLE_NAME.test(name))
         throw new Error('a handle name is upper-case letters, digits and underscores, starting with a letter');
@@ -136,18 +234,13 @@ function putHandle(dir, connector, name, value, options) {
         throw new Error('a secret value is a string');
     if (options.expiresAt !== undefined && !validExpiry(options.expiresAt))
         throw new Error('expiresAt must be an RFC 3339 UTC time ending in Z');
-    mkdirSync(dir, { recursive: true, mode: DIRECTORY_MODE });
-    const dirProblem = entryProblem(dir, 'directory', 'the secrets directory');
-    if (dirProblem !== null)
-        throw new Error(`connector ${connector}: ${dirProblem}`);
-    writePrivately(join(dir, name), value);
-    const expiryFile = join(dir, name + EXPIRY_SUFFIX);
-    if (options.expiresAt === undefined) {
-        rmSync(expiryFile, { force: true });
-        return { connector, name, source: 'file' };
-    }
-    writePrivately(expiryFile, JSON.stringify({ expiresAt: options.expiresAt }) + '\n');
-    return { connector, name, source: 'file', expiresAt: options.expiresAt };
+    if (options.secret !== undefined && typeof options.secret !== 'boolean')
+        throw new Error('secret must be true or false');
+    ensureDirectory(dir, connector);
+    const r = locked(dir, connector, () => writeHandle(dir, connector, name, value, options));
+    if (!r.ok)
+        throw new Error(r.problem);
+    return r.value;
 }
 export function openFileSecrets(options) {
     if (typeof options?.configDir !== 'string' || !isAbsolute(options.configDir))
@@ -157,7 +250,15 @@ export function openFileSecrets(options) {
     const { connector } = options;
     const dir = handleDirectory(options.configDir, connector);
     return {
+        directory: dir,
         list: () => listHandles(dir, connector),
         put: (name, value, putOptions = {}) => putHandle(dir, connector, name, value, putOptions),
+        withLock: (fn) => {
+            ensureDirectory(dir, connector);
+            const r = locked(dir, connector, fn);
+            if (!r.ok)
+                throw new Error(r.problem);
+            return r.value;
+        },
     };
 }

package/dist/status.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectorMintedStatus } from '@sema-agent/connectors-contract';
-import type { SecretHandle } from './secrets.js';
+import { type SecretHandle } from './secrets.js';
 export declare const STATUS_MIME_TYPE = "application/json";
 export declare const AUTHORIZE_URL_PATTERN: RegExp;
 export declare function statusUri(connector: string): string;

package/dist/status.js

@@ -1,3 +1,4 @@
+import { isSecret } from './secrets.js';
 export const STATUS_MIME_TYPE = 'application/json';
 export const AUTHORIZE_URL_PATTERN = /^https?:\/\//;
 export function statusUri(connector) {
@@ -13,7 +14,8 @@ export function statusResource(connector) {
     };
 }
 export function mintStatus(input) {
-    const state = input.handles.length === 0 ? 'unauthorized' : input.handles.some((h) => h.expiresAt !== undefined && Date.parse(h.expiresAt) <= input.nowMs) ? 'expired' : 'authorized';
+    const secrets = input.handles.filter(isSecret);
+    const state = secrets.length === 0 ? 'unauthorized' : secrets.some((h) => h.expiresAt !== undefined && Date.parse(h.expiresAt) <= input.nowMs) ? 'expired' : 'authorized';
     const link = state === 'unauthorized' && input.authorizeUrl !== undefined && AUTHORIZE_URL_PATTERN.test(input.authorizeUrl) ? { authorizeUrl: input.authorizeUrl } : {};
     return { state, tools: [...input.tools], ...link };
 }

package/dist/write-all.d.ts

@@ -0,0 +1 @@
+export declare function writeAll(fd: number, data: string | Uint8Array): void;

package/dist/write-all.js

@@ -0,0 +1,15 @@
+import { fstatSync, fsyncSync, writeSync } from 'node:fs';
+export function writeAll(fd, data) {
+    const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+    let written = 0;
+    while (written < bytes.length) {
+        const n = writeSync(fd, bytes, written, bytes.length - written, written);
+        if (n <= 0)
+            throw new Error(`a write stopped after ${written} of ${bytes.length} bytes`);
+        written += n;
+    }
+    fsyncSync(fd);
+    const size = fstatSync(fd).size;
+    if (size !== bytes.length)
+        throw new Error(`the file holds ${size} bytes after a write of ${bytes.length}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared connector layer and the sema-connector launcher (MCP stdio proxy with principal, scope, normalize, status and trace stages).",
   "license": "Apache-2.0",
   "type": "module",