@sema-agent/connectors 0.1.0 → 0.3.0

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/seed.d.ts

@@ -0,0 +1,35 @@
+import { type MountRefusal } from './mount.js';
+export interface DefaultConnector {
+    readonly name: string;
+    readonly since: number;
+}
+export declare const DEFAULT_CONNECTORS: readonly DefaultConnector[];
+export declare const SEED_VERSION: number;
+export interface SeedOptions {
+    readonly configDir: string;
+}
+export type SeedReading = {
+    readonly name: string;
+    readonly outcome: 'mounted' | 'present' | 'conflict';
+} | {
+    readonly name: string;
+    readonly outcome: 'not_installed';
+    readonly message: string;
+} | {
+    readonly name: string;
+    readonly outcome: 'refused';
+    readonly reason: MountRefusal;
+    readonly message: string;
+};
+export type SeedRefusal = 'config_dir' | 'locked' | 'unreadable' | 'unexpected_shape' | 'write_failed';
+export type SeedResult = {
+    readonly ok: true;
+    readonly readings: readonly SeedReading[];
+    readonly marker: string;
+} | {
+    readonly ok: false;
+    readonly reason: SeedRefusal;
+    readonly message: string;
+    readonly readings: readonly SeedReading[];
+};
+export declare function seed(options: SeedOptions): SeedResult;

package/dist/seed.js

@@ -0,0 +1,134 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { absoluteDir } from './config-dir.js';
+import { hasRepeatedKey } from './json-text.js';
+import { mount, nameRefusal } from './mount.js';
+import { takeLockFile } from './lock-file.js';
+import { resolveConnector } from './resolve-connector.js';
+import { writeFailure, writeAll } from './write-all.js';
+export const DEFAULT_CONNECTORS = Object.freeze([Object.freeze({ name: 'gitea', since: 1 }), Object.freeze({ name: 'github', since: 1 })]);
+export const SEED_VERSION = newestVersion(DEFAULT_CONNECTORS);
+function newestVersion(catalog) {
+    const names = new Set();
+    for (const c of catalog) {
+        const refusal = nameRefusal(c.name);
+        if (refusal !== null)
+            throw new Error(`the default catalog names a connector mount refuses (${refusal.reason})`);
+        if (names.has(c.name))
+            throw new Error(`the default catalog names ${c.name} twice`);
+        names.add(c.name);
+        if (!Number.isSafeInteger(c.since) || c.since < 1)
+            throw new Error(`the default catalog gives ${c.name} a since that is not a positive integer`);
+    }
+    if (catalog.length === 0)
+        throw new Error('the default catalog is empty');
+    return Math.max(...catalog.map((c) => c.since));
+}
+const MARKER_FILE = '.sema-connector-seed.json';
+const SEED_LOCK_FILE = `${MARKER_FILE}.lock`;
+const RECORDED = ['mounted', 'present', 'not_installed'];
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+function readMarker(file) {
+    const where = `config.d/${MARKER_FILE}`;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { marker: null };
+        return { refusal: 'unreadable', message: `${where} cannot be read` };
+    }
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        return { refusal: 'unreadable', message: `${where} is not valid JSON` };
+    }
+    const shape = `${where} must be one JSON object {"version": <a positive integer>, "entries": {"<name>": "mounted" | "present" | "not_installed"}}`;
+    if (!isObject(doc) || Object.keys(doc).sort().join() !== 'entries,version' || hasRepeatedKey(text))
+        return { refusal: 'unexpected_shape', message: shape };
+    const { version, entries } = doc;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1 || !isObject(entries))
+        return { refusal: 'unexpected_shape', message: shape };
+    for (const [name, value] of Object.entries(entries)) {
+        if (nameRefusal(name) !== null || typeof value !== 'string' || !RECORDED.includes(value))
+            return { refusal: 'unexpected_shape', message: shape };
+    }
+    return { marker: { version, entries: entries } };
+}
+export function seed(options) {
+    const configDir = absoluteDir(options?.configDir);
+    if (configDir === null)
+        return { ok: false, reason: 'config_dir', message: 'configDir must be the configuration directory as an absolute path; the seed reads no environment variable and has no default', readings: [] };
+    const dir = join(configDir, 'config.d');
+    let unlock;
+    try {
+        mkdirSync(dir, { recursive: true });
+        unlock = takeLockFile(join(dir, SEED_LOCK_FILE));
+    }
+    catch (e) {
+        return { ok: false, reason: 'write_failed', message: `config.d or the seed's lock could not be written (${writeFailure(e)}); nothing was mounted`, readings: [] };
+    }
+    if (unlock === null)
+        return { ok: false, reason: 'locked', message: `another seed is running on this directory; nothing was mounted: try again, and if no seed is running remove config.d/${SEED_LOCK_FILE}`, readings: [] };
+    try {
+        return seedLocked(configDir, dir);
+    }
+    finally {
+        unlock();
+    }
+}
+function seedLocked(configDir, dir) {
+    const file = join(dir, MARKER_FILE);
+    const read = readMarker(file);
+    if ('refusal' in read)
+        return { ok: false, reason: read.refusal, message: `${read.message}; nothing was mounted`, readings: [] };
+    const before = read.marker;
+    const entries = { ...before?.entries };
+    const readings = [];
+    for (const { name } of DEFAULT_CONNECTORS) {
+        const recorded = before !== null && Object.hasOwn(before.entries, name) ? before.entries[name] : undefined;
+        if (recorded === 'mounted' || recorded === 'present') {
+            readings.push({ name, outcome: 'present' });
+            continue;
+        }
+        const resolved = resolveConnector(name);
+        if ('reason' in resolved) {
+            readings.push({ name, outcome: 'not_installed', message: `package ${resolved.packageName} ${resolved.reason}` });
+            entries[name] = 'not_installed';
+            continue;
+        }
+        const r = mount({ name, configDir });
+        if (r.ok) {
+            const outcome = r.changed ? 'mounted' : 'present';
+            readings.push({ name, outcome });
+            entries[name] = outcome;
+        }
+        else if (r.reason === 'conflict')
+            readings.push({ name, outcome: 'conflict' });
+        else
+            readings.push({ name, outcome: 'refused', reason: r.reason, message: r.message });
+    }
+    const after = { version: SEED_VERSION, entries };
+    if (before === null || JSON.stringify(after) !== JSON.stringify(before)) {
+        const tmp = join(dir, `${MARKER_FILE}.${randomBytes(6).toString('hex')}.tmp`);
+        try {
+            const fd = openSync(tmp, 'wx', 0o666);
+            try {
+                writeAll(fd, JSON.stringify(after, null, 2) + '\n');
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(tmp, file);
+        }
+        catch (e) {
+            rmSync(tmp, { force: true });
+            return { ok: false, reason: 'write_failed', message: `config.d/${MARKER_FILE} could not be written (${writeFailure(e)}); it was left as it was, and the entries mounted stay mounted`, readings };
+        }
+    }
+    return { ok: true, readings, marker: file };
+}

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,2 @@
+export declare function writeAll(fd: number, data: string | Uint8Array): void;
+export declare function writeFailure(e: unknown): string;

package/dist/write-all.js

@@ -0,0 +1,19 @@
+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}`);
+}
+export function writeFailure(e) {
+    const code = e?.code;
+    return typeof code === 'string' ? code : e instanceof Error ? e.message : 'unknown error';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connectors",
-  "version": "0.1.0",
+  "version": "0.3.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",