@sema-agent/connectors 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.7.0 (2026-10-16)
+
+### Added
+
+- A standalone local per-tool policy (CN-054): a hand-written `connectors/<name>/tools.json`,
+  `{"allow": ["<tool name>", …]}` (exactly one key, a list of non-empty tool names with no whitespace, no control
+  character, no repeat and never the literal `*`, the scope judge's own wildcard token), read once with the
+  connector's secret handles (inside the same directory lock, with a non-blocking open so a FIFO in the file's
+  place cannot hang the launch) and returned as `LaunchCopy.policy`. `standaloneResolver(policy?)` takes it and
+  mints the standalone principal's scope from it instead of `tool:*` when it is given (one `tool:<name>` per
+  allowed name; an empty list grants none). Absent, a policy file this process cannot read, one of another
+  shape, or a symbolic link in its place, all stop the launcher before the connector starts (exit 2,
+  `connector.internal`, naming the file relative to the configuration directory, never its content); absent the
+  file, behaviour is exactly as before. No CLI subcommand writes this file. `tools/list`, the status resource's
+  `tools` and `tools/call` (with its receipt) already followed the one scope judge (`isGranted`); they need no
+  change to follow the narrower grant too. A parked session (CN-046) carries the same principal, so the scope
+  stage still refuses a tool outside the policy first, with `connector.forbidden_scope`, before the parked
+  `connector.auth_required` a tool inside it gets. Hosted mode never reads this file (its grant comes from the
+  assertion).
+
 ## 0.6.0 (2026-10-16)
 
 ### Changed (breaking)

package/dist/launcher.js

@@ -504,8 +504,8 @@ function parkedRun(session, connector, stdout, log) {
         }),
     };
 }
-async function runStdio(packageName, run, session, stdout, log) {
-    const resolution = standaloneResolver().resolve({ headers: {} });
+async function runStdio(packageName, run, session, stdout, log, policy) {
+    const resolution = standaloneResolver(policy).resolve({ headers: {} });
     if (!resolution.ok)
         throw new Error('the standalone principal cannot be refused');
     const anonymous = resolution.principal;
@@ -628,7 +628,7 @@ export async function main(argv, env) {
         const run = parked
             ? parkedRun(session, plan.name, stdout, log)
             : startConnector(resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), (data) => stdout.write(data), stdout, log);
-        return finish(await runStdio(resolved.packageName, run, session, stdout, log));
+        return finish(await runStdio(resolved.packageName, run, session, stdout, log, secrets.policy));
     }
     finally {
         secrets.remove();

package/dist/principal.d.ts

@@ -41,7 +41,7 @@ export type PrincipalResult = {
 export interface PrincipalResolver {
     resolve(request: RequestContext): PrincipalResult;
 }
-export declare function standaloneResolver(): PrincipalResolver;
+export declare function standaloneResolver(policy?: readonly string[] | null): PrincipalResolver;
 export declare function hostedResolver(options: {
     readonly issuer: string;
     readonly audience: string;

package/dist/principal.js

@@ -95,8 +95,11 @@ export function verifyAssertion(compactJws, options) {
     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 standaloneResolver(policy) {
+    if (policy === null || policy === undefined)
+        return { resolve: () => ({ ok: true, principal: ANONYMOUS }) };
+    const principal = Object.freeze({ kind: 'anonymous', scope: Object.freeze(policy.map((name) => `tool:${name}`)) });
+    return { resolve: () => ({ ok: true, principal }) };
 }
 export function hostedResolver(options) {
     if (typeof options?.issuer !== 'string' || options.issuer === '' || typeof options.audience !== 'string' || options.audience === '') {

package/dist/secrets.d.ts

@@ -34,6 +34,7 @@ export interface LaunchSecrets {
     readonly handles: readonly SecretHandle[];
     readonly files: ReadonlyMap<string, string>;
     readonly values: readonly string[];
+    readonly policy: readonly string[] | null;
     remove(): void;
 }
 export type LaunchCopy = ({
@@ -44,6 +45,14 @@ export type LaunchCopy = ({
 };
 export declare const NO_HANDLES: LaunchSecrets;
 export declare function copyForLaunch(configDir: string, connector: string): LaunchCopy;
+export declare const POLICY_FILE = "tools.json";
+export type PolicyReading = {
+    readonly ok: true;
+    readonly policy: readonly string[] | null;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
 export declare function openFileSecrets(options: {
     readonly configDir: string;
     readonly connector: string;

package/dist/secrets.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { closeSync, constants, fchmodSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { closeSync, constants, fchmodSync, fstatSync, 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';
@@ -56,7 +56,7 @@ function locked(dir, connector, fn) {
         release();
     }
 }
-export const NO_HANDLES = { handles: [], files: new Map(), values: [], remove: () => undefined };
+export const NO_HANDLES = { handles: [], files: new Map(), values: [], policy: null, remove: () => undefined };
 export function copyForLaunch(configDir, connector) {
     const dir = handleDirectory(configDir, connector);
     try {
@@ -74,11 +74,15 @@ export function copyForLaunch(configDir, connector) {
     return r.ok ? r.value : r;
 }
 function copyHandles(configDir, dir, connector) {
+    const policyReading = readToolPolicy(dir, connector);
+    if (!policyReading.ok)
+        return policyReading;
+    const { policy } = policyReading;
     const listing = listHandles(dir, connector);
     if (!listing.ok)
         return listing;
     if (listing.handles.length === 0)
-        return { ok: true, ...NO_HANDLES };
+        return { ok: true, ...NO_HANDLES, policy };
     const copies = mkdtempSync(join(dir, '.launch-'));
     const remove = () => rmSync(copies, { recursive: true, force: true });
     try {
@@ -98,7 +102,7 @@ function copyHandles(configDir, dir, connector) {
             if (isSecret(handle))
                 values.push(bytes.toString('utf8'));
         }
-        return { ok: true, handles: listing.handles, files, values, remove };
+        return { ok: true, handles: listing.handles, files, values, policy, remove };
     }
     catch (e) {
         remove();
@@ -142,6 +146,64 @@ function entryProblem(path, kind, label) {
         return `${label} has permissions wider than ${kind === 'directory' ? '0700' : '0600'}`;
     return null;
 }
+export const POLICY_FILE = 'tools.json';
+const ALLOW_NAME = /^[^\s\x00-\x1F\x7F]+$/;
+function validAllowList(v) {
+    if (!Array.isArray(v))
+        return false;
+    const seen = new Set();
+    for (const name of v) {
+        if (typeof name !== 'string' || name === '*' || !ALLOW_NAME.test(name) || seen.has(name))
+            return false;
+        seen.add(name);
+    }
+    return true;
+}
+function readToolPolicy(dir, connector) {
+    const relative = `connectors/${connector}/${POLICY_FILE}`;
+    const refuse = (problem) => ({ ok: false, problem: `connector ${connector}: ${problem}` });
+    const malformed = () => refuse(`${relative} does not hold a JSON object whose only key is "allow", a list of non-empty tool names with no whitespace, no control character and no repeat`);
+    let fd;
+    try {
+        fd = openSync(join(dir, POLICY_FILE), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return { ok: true, policy: null };
+        if (code === 'ELOOP')
+            return refuse(`${relative} is a symbolic link`);
+        return refuse(`${relative} cannot be read`);
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return refuse(`${relative} is not a regular file`);
+        let text;
+        try {
+            text = readFileSync(fd, 'utf8');
+        }
+        catch {
+            return refuse(`${relative} cannot be read`);
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            return malformed();
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value) || hasRepeatedKey(text))
+            return malformed();
+        const keys = Object.keys(value);
+        if (keys.length !== 1 || keys[0] !== 'allow')
+            return malformed();
+        const allow = value.allow;
+        return validAllowList(allow) ? { ok: true, policy: allow } : malformed();
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 function listHandles(dir, connector) {
     const refuse = (problem) => ({ ok: false, problem: `connector ${connector}: ${problem}` });
     try {

package/package.json

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