@synopackageland/cli 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.41.0 (2026-10-29)
+
+- Add generic `ctl external --protocol <id> --host <profile> --input - --json`
+  for local MCP bridges. Apps opt in with `ctl.external` and a dedicated
+  administrator RPC entry. Each request checks the stored login, pinned host,
+  installed package and fresh description; calls also check the current catalog
+  revision and schema. The App verifies pins/revision at dispatch and creates
+  caller authority and MCP provenance. Ordinary ctl cannot invoke the external
+  entry. Lost mutation replies are never retried. See
+  [the external contract](docs/ctl-external.md) for App integration requirements.
+
 ## 0.40.0 (2026-10-29)
 
 - `daemon.backend: true` runs the App's own native backend

package/README.md

@@ -61,6 +61,10 @@ from `target/app` as the package account for each request (see `skills/reference
 Application Privileges admission, explicit method policies, gateway conflicts and
 the build-bound SDK checks.
 
+[External callers](docs/ctl-external.md) describes the local MCP bridge command,
+App-declared protocols and required trusted administrator entry. This opt-in
+contract does not add an MCP server or automatically wire an App's tool Engine.
+
 ## SDK and templates
 
 The CLI packages, deploys and checks. The app-side code is the SDK
@@ -78,7 +82,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.40.0 uses templates ~0.35.0, whose default SDK pin is 0.37.0. Compose import and SDK defaults
+CLI 0.41.0 uses templates ~0.35.0, whose default SDK pin is 0.37.0. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -89,7 +93,7 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.40.0 depends on `~0.35.0`: npm installation or
+`@synopackageland/templates`. CLI 0.41.0 depends on `~0.35.0`: npm installation or
 update can select the latest templates patch in the 0.35 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;

package/dist/cli.js

@@ -297,6 +297,10 @@ async function containerBuild(project, arches, options) {
 }
 /** Resolves after dispatch; commands may set process.exitCode. Rejections are failures. */
 export async function runCli(argv) {
+    if (argv[2] === 'ctl' && argv[3] === 'external') {
+        const { runCtl } = await import('./ctl/cli.js');
+        return runCtl(argv.slice(3));
+    }
     const { args, options } = nasFlags(argv, argv[2] !== "ctl");
     return withNasOptions(options, () => runCliWithin(args));
 }

package/dist/ctl/cli.d.ts

@@ -10,17 +10,6 @@ export interface CtlIO {
     requestFor?: (host: Host) => JsonRequest;
 }
 export declare function listView(host: string, apps: Descriptor[]): {
-    host: string;
-    package: {
-        id: string;
-        version: string;
-        displayName: string;
-    };
-    aliases: string[];
-    protocolVersion: 1;
-    developedBy: string;
-    provenance: string;
-    hash: string;
     commands: {
         parameters: string | Record<string, any>;
         examples: string[];
@@ -33,5 +22,19 @@ export declare function listView(host: string, apps: Descriptor[]): {
         flow: import("./descriptor.js").Flow;
         id: string;
     }[];
+    external?: Record<string, {
+        method: string;
+    }> | undefined;
+    host: string;
+    package: {
+        id: string;
+        version: string;
+        displayName: string;
+    };
+    aliases: string[];
+    protocolVersion: 1;
+    developedBy: string;
+    provenance: string;
+    hash: string;
 }[];
 export declare function runCtl(argv: string[], io?: CtlIO): Promise<void>;

package/dist/ctl/cli.js

@@ -10,6 +10,7 @@ import { selectHosts, selectApp, selectOperation, flagName, RESERVED_FLAGS } fro
 import { canonicalOrigin, CTL_TIMEOUT_MS, createRequest } from './transport.js';
 import { loginDsm, logoutDsm } from './dsm-auth.js';
 import { publicOperation } from './redaction.js';
+import { runExternal } from './external.js';
 const USAGE = 'synopkgland host add|list|show|login|logout|remove|revoke|default|trust; ctl list [--host a,b|--all-hosts] [--app pkg] [--refresh]; ctl <alias|package> <command...> [typed flags|--input file|-] [--dry-run] [--yes]; NAS HTTPS accepts any certificate by default; --strict-tls or --ca <file> opts into verification';
 async function prompt(message, secret = false) {
     if (!process.stdin.isTTY)
@@ -59,8 +60,10 @@ function example(host, app, op) {
         return `printf '%s' ${q(JSON.stringify(params))} | ${base} --input -` + (op.effect === 'read' ? '' : ' --yes');
     });
 }
-export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', examples: example(host, app, op) }; }) })); }
+export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, ...(app.payload.external ? { external: app.payload.external } : {}), commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', examples: example(host, app, op) }; }) })); }
 export async function runCtl(argv, io = {}) {
+    if (argv[0] === 'external')
+        return runExternal(argv.slice(1), io);
     try {
         const { args, options } = nasFlags(argv);
         return await withNasOptions({ ...options, warn: io.err ?? console.error }, () => runCtlWithin(args, io));

package/dist/ctl/descriptor.d.ts

@@ -66,6 +66,9 @@ export interface ApiPayload {
     };
     commands: Record<string, Operation>;
     bindings: Record<string, Binding>;
+    external?: Record<string, {
+        method: string;
+    }>;
 }
 export interface Descriptor {
     format: 'synopkgland.api';

package/dist/ctl/descriptor.js

@@ -27,6 +27,13 @@ export function validateDescriptor(value, id, version) {
         return fail('Invalid command allowlist.');
     if (!p.bindings || typeof p.bindings !== 'object')
         return fail('Missing internal method bindings.');
+    const externalMethods = new Set();
+    for (const entry of Object.values(p.external ?? {})) {
+        const binding = p.bindings[entry.method];
+        if (!binding || binding.permission !== 'administrators' || binding.effect !== 'destructive' || entry.method.startsWith('identity.') || entry.method === DESCRIPTION_METHOD)
+            return fail('External entries require dedicated administrator bindings.');
+        externalMethods.add(entry.method);
+    }
     const paths = new Set();
     for (const [method, raw] of Object.entries(p.commands)) {
         const op = raw;
@@ -38,6 +45,8 @@ export function validateDescriptor(value, id, version) {
         catch {
             return fail('Invalid command flow or method bindings.');
         }
+        if (externalMethods.has(method) || flowMethods(op.flow).some(name => externalMethods.has(name)))
+            return fail('External entries cannot be ordinary commands or flow helpers.');
         const path = op.cli.join(' ');
         if (paths.has(path))
             return fail('Duplicate CLI command path.');

package/dist/ctl/external.d.ts

@@ -0,0 +1,27 @@
+import { CtlStore, type Host } from './store.js';
+import { type JsonRequest } from './transport.js';
+import type { CtlIO } from './cli.js';
+type Describe = {
+    protocol: string;
+    action: 'describe';
+};
+type Call = {
+    protocol: string;
+    action: 'call';
+    revision: string;
+    method: string;
+    arguments: Record<string, unknown>;
+};
+export type ExternalRequest = Describe | Call;
+export declare function parseExternalRequest(raw: string, protocol: string): ExternalRequest;
+/** A separate entry, never an ordinary ctl flow with relabeled provenance. */
+export declare class ExternalClient {
+    private readonly store;
+    private readonly host;
+    private readonly request;
+    private readonly deadline;
+    constructor(store: CtlStore, host: Host, request?: JsonRequest);
+    execute(protocol: string, input: ExternalRequest): Promise<unknown>;
+}
+export declare function runExternal(argv: string[], io?: CtlIO): Promise<void>;
+export {};

package/dist/ctl/external.js

@@ -0,0 +1,195 @@
+import { CtlError, ctlError } from './errors.js';
+import { readBounded, strictJson } from './json.js';
+import { ajv, safeSchema, validateDescriptor } from './descriptor.js';
+import { CtlStore } from './store.js';
+import { CtlClient } from './service.js';
+import { canonicalOrigin, createRequest } from './transport.js';
+import { nasOptions } from '../nas/options.js';
+import { SensitiveOutput } from './redaction.js';
+const LIMIT = 1048576;
+const PROTOCOL = /^[a-z][a-z0-9-]{0,63}$/;
+const METHOD = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const AUTHORITY_KEYS = ['actor', 'via', 'allowMutation', 'allow_mutation', 'host'];
+const USAGE = 'synopkgland ctl external --protocol <declared-protocol> --host <profile> --input - --json';
+const HINT = 'Check local login, administrator access, App approval and tool revision. Query original state before repeating a mutation.';
+function fail(code, message, exit = 4) { throw new CtlError(code, message, HINT, exit); }
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function revision(value) { return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value); }
+export function parseExternalRequest(raw, protocol) {
+    try {
+        if (!PROTOCOL.test(protocol) || Buffer.byteLength(raw) > LIMIT)
+            throw Error();
+        const value = strictJson(raw);
+        if (!object(value) || value.protocol !== protocol)
+            throw Error();
+        const keys = value.action === 'describe' ? ['protocol', 'action'] : ['protocol', 'action', 'revision', 'method', 'arguments'];
+        if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key)))
+            throw Error();
+        if (value.action === 'describe')
+            return value;
+        if (value.action !== 'call' || !revision(value.revision) || typeof value.method !== 'string' || value.method.length > 128 || !METHOD.test(value.method) || !object(value.arguments) || AUTHORITY_KEYS.some(key => Object.hasOwn(value.arguments, key)))
+            throw Error();
+        return value;
+    }
+    catch {
+        return fail('CTL_EXTERNAL_INPUT', 'Invalid external request.', 3);
+    }
+}
+function validateCatalog(value) {
+    if (!object(value) || !revision(value.revision) || !Array.isArray(value.tools) || value.tools.length > 1024)
+        return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool catalog.', 5);
+    const methods = new Set(), names = new Set();
+    for (const tool of value.tools) {
+        if (!object(tool) || typeof tool.name !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(tool.name) ||
+            !object(tool._meta) || typeof tool._meta.method !== 'string' || tool._meta.method.length > 128 || !METHOD.test(tool._meta.method) ||
+            methods.has(tool._meta.method) || names.has(tool.name) || !object(tool.inputSchema) || !object(tool.outputSchema))
+            return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool metadata.', 5);
+        methods.add(tool._meta.method);
+        names.add(tool.name);
+        try {
+            for (const schema of [tool.inputSchema, tool.outputSchema]) {
+                safeSchema(schema);
+                ajv.compile(schema);
+            }
+        }
+        catch {
+            return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool schema.', 5);
+        }
+    }
+    return value;
+}
+/** A separate entry, never an ordinary ctl flow with relabeled provenance. */
+export class ExternalClient {
+    store;
+    host;
+    request;
+    deadline = performance.now() + 30000;
+    constructor(store, host, request) {
+        this.store = store;
+        this.host = host;
+        this.request = request ?? createRequest(host.origin, () => Math.max(0, this.deadline - performance.now()), undefined, { ...store.trust(host), expectedFingerprint: host.fingerprint });
+    }
+    async execute(protocol, input) {
+        input = parseExternalRequest(JSON.stringify(input), protocol);
+        // Ambient credentials and URL overrides are for ordinary automation only.
+        if (this.host.ephemeral || canonicalOrigin(this.host.origin, !!this.host.tunnel) !== this.host.origin ||
+            this.host.origin.startsWith('https:') && !/^[a-f0-9]{64}$/.test(this.host.fingerprint ?? ''))
+            fail('CTL_EXTERNAL_HOST', 'External callers require a registered, pinned host.');
+        const snapshot = JSON.stringify(this.host);
+        const session = await this.store.session(this.host, { storedOnly: true });
+        const assertCurrent = async () => {
+            if (JSON.stringify(this.store.get(this.host.name)) !== snapshot)
+                fail('CTL_EXTERNAL_PINS_CHANGED', 'Host or App approval changed.');
+            const current = await this.store.session(this.host, { storedOnly: true });
+            if (current.cookie !== session.cookie || current.token !== session.token)
+                fail('CTL_NOT_AUTHENTICATED', 'Stored login changed.', 2);
+        };
+        await assertCurrent();
+        const packages = await new CtlClient(this.store, this.host, this.request).inventory(session);
+        // Cached descriptors select an already approved credential recipient only.
+        // Neither cached schemas nor a new package may establish external authority.
+        const candidates = packages.filter(pkg => {
+            const approval = this.host.approved[pkg.id], cached = this.store.cache(this.host, pkg.id, pkg.version);
+            return approval?.version === pkg.version && approval.hash && cached?.hash === approval.hash &&
+                Object.hasOwn(cached.description?.payload?.external ?? {}, protocol);
+        });
+        if (candidates.length !== 1)
+            fail('CTL_EXTERNAL_PROTOCOL', 'Protocol must match exactly one pinned App.');
+        const pkg = candidates[0], approval = this.host.approved[pkg.id];
+        await assertCurrent();
+        const path = `/webman/3rdparty/${pkg.id}/cgi/api.cgi`;
+        const described = await this.request(path, { method: 'synopkgland.describe', params: {} }, session);
+        if (described?.success !== true)
+            fail('CTL_EXTERNAL_DENIED', 'App description refused.');
+        const app = validateDescriptor(described.data, pkg.id, pkg.version);
+        if (app.sha256 !== approval.hash)
+            fail('CTL_DESCRIPTION_CHANGED', 'Pinned App description changed.');
+        const entry = app.payload.external?.[protocol];
+        if (!entry)
+            fail('CTL_EXTERNAL_PROTOCOL', 'App does not declare this protocol.');
+        if (app.payload.transport.auth !== 'dsm-session')
+            fail('CTL_EXTERNAL_TRANSPORT', 'External callers require the DSM session transport.');
+        const pins = { package: { id: pkg.id, version: pkg.version }, descriptionSha256: app.sha256 };
+        const output = new SensitiveOutput({ carriers: [session.token, session.cookie, ...session.cookie.split(';').map(part => part.slice(part.indexOf('=') + 1).trim())] }, { type: 'object', properties: { carriers: { writeOnly: true } } });
+        const invoke = async (request) => {
+            await assertCurrent();
+            // The App must verify these pins and revision in its dispatch boundary,
+            // freshly authenticate an administrator and derive authority server-side.
+            const reply = await this.request(path, { method: entry.method, params: { ...request, ...pins } }, session);
+            if (reply?.success !== true)
+                fail('CTL_EXTERNAL_DENIED', 'Trusted external entry refused.');
+            const proof = reply.data?.verified;
+            if (!object(proof) || proof.protocol !== protocol || proof.package?.id !== pkg.id || proof.package?.version !== pkg.version ||
+                proof.descriptionSha256 !== app.sha256 || proof.user !== session.username || proof.administrator !== true ||
+                !revision(proof.revision) || request.action === 'call' && proof.revision !== request.revision ||
+                request.action === 'describe' && proof.revision !== reply.data?.data?.revision)
+                fail('CTL_EXTERNAL_VERIFICATION', 'External verification did not match the pinned request.', 5);
+            return reply.data.data;
+        };
+        const catalog = validateCatalog(await invoke({ protocol, action: 'describe' }));
+        if (input.action === 'describe')
+            return output.clean(catalog);
+        if (catalog.revision !== input.revision)
+            fail('CTL_EXTERNAL_REVISION', 'External tool revision changed.');
+        const tool = catalog.tools.find(tool => tool._meta.method === input.method);
+        if (!tool)
+            fail('CTL_EXTERNAL_METHOD', 'Method is not an external tool.');
+        if (!ajv.validate(tool.inputSchema, input.arguments))
+            fail('CTL_EXTERNAL_INPUT', 'Arguments do not match the current tool schema.', 3);
+        const sensitive = new SensitiveOutput(input.arguments, tool.inputSchema);
+        // Exactly one call attempt. Errors, lost replies and invalid results never replay it.
+        const result = await invoke(input);
+        if (!ajv.validate(tool.outputSchema, result))
+            fail('CTL_EXTERNAL_RESULT', 'External result does not match its schema.', 5);
+        return output.clean(sensitive.clean(result, tool.outputSchema));
+    }
+}
+export async function runExternal(argv, io = {}) {
+    const out = io.out ?? console.log;
+    try {
+        if (argv.length === 1 && argv[0] === '--help') {
+            out(JSON.stringify({ ok: true, data: { usage: USAGE } }));
+            return;
+        }
+        const values = new Map();
+        for (let i = 0; i < argv.length; i++) {
+            const flag = argv[i], key = flag.split('=')[0];
+            if (!['--protocol', '--host', '--input', '--json'].includes(key) || values.has(key))
+                fail('CTL_EXTERNAL_FLAGS', 'Invalid external options.', 3);
+            if (key === '--json') {
+                if (flag !== key)
+                    fail('CTL_EXTERNAL_FLAGS', 'Invalid JSON option.', 3);
+                values.set(key, 'true');
+                continue;
+            }
+            const value = flag.includes('=') ? flag.slice(key.length + 1) : argv[++i];
+            if (!value || value.startsWith('--'))
+                fail('CTL_EXTERNAL_FLAGS', 'Missing external option value.', 3);
+            values.set(key, value);
+        }
+        const protocol = values.get('--protocol'), hostName = values.get('--host');
+        if (values.size !== 4 || !protocol || !PROTOCOL.test(protocol) || !hostName || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(hostName) ||
+            values.get('--input') !== '-' || nasOptions().url || nasOptions().ca || nasOptions().strictTls)
+            fail('CTL_EXTERNAL_FLAGS', 'Use the fixed external command contract.', 3);
+        let raw;
+        try {
+            raw = readBounded(0);
+        }
+        catch {
+            return fail('CTL_EXTERNAL_INPUT', 'Cannot read bounded UTF-8 stdin.', 3);
+        }
+        const input = parseExternalRequest(raw, protocol);
+        const store = io.store ?? new CtlStore(), host = store.get(hostName);
+        const data = await new ExternalClient(store, host, io.requestFor?.(host)).execute(protocol, input);
+        const line = JSON.stringify({ ok: true, data });
+        if (Buffer.byteLength(line + '\n') > LIMIT)
+            fail('CTL_EXTERNAL_OUTPUT', 'External output exceeds 1 MiB.', 5);
+        out(line);
+    }
+    catch (error) {
+        const e = ctlError(error);
+        // Never echo upstream messages, input, session carriers or exception text.
+        out(JSON.stringify({ ok: false, error: { code: e.code, message: 'External request refused.', hint: HINT } }));
+        process.exitCode = e.exitCode;
+    }
+}

package/dist/nas/store.d.ts

@@ -44,7 +44,9 @@ export declare class CtlStore {
     save(host: Host): void;
     add(host: Host, session: DsmSession): Promise<void>;
     trust(host: Host): HostTls;
-    session(host: Host): Promise<DsmSession>;
+    session(host: Host, options?: {
+        storedOnly?: boolean;
+    }): Promise<DsmSession>;
     cacheRoot(host: Host): string;
     cacheFile(host: Host, pkg: string, version: string): string;
     cache(host: Host, pkg: string, version: string): any | null;

package/dist/nas/store.js

@@ -94,9 +94,9 @@ export class CtlStore {
             } },
             record: (fingerprint) => { host.fingerprint = fingerprint; this.save(host); }, warn: override.warn };
     }
-    async session(host) {
+    async session(host, options = {}) {
         let session;
-        if (process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
+        if (!options.storedOnly && process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
             if (process.env.DSM_USERNAME !== host.username)
                 throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Automation account differs from the registered host.', 'Use the registered account or a separately named host.', 2);
             session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, 30000, undefined, this.trust(host)) });

package/dist/standalone/api-description.js

@@ -34,6 +34,7 @@ export async function buildApiDescription(m, bridgeMethods, run) {
         throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Invalid registry snapshot.');
     const registry = new Map(methods.map(item => [item.method, item.permission]));
     const rawHTTP = new Set(methods.filter(item => item.kind === 'http').map(item => item.method));
+    const nonRPC = new Set(methods.filter(item => item.kind && item.kind !== 'json').map(item => item.method));
     // Identity transport routes are outside the business registry but have immutable SDK ownership.
     if (m.capabilities.identity) {
         registry.set('identity.session', 'public');
@@ -41,6 +42,16 @@ export async function buildApiDescription(m, bridgeMethods, run) {
     }
     const bindings = {};
     const commands = {};
+    if (m.ctl.external) {
+        if (m.capabilities.identity)
+            throw new StandaloneBuildError('CTL_EXTERNAL_TRANSPORT', 'External entries require the DSM session transport.');
+        for (const entry of Object.values(m.ctl.external)) {
+            if (!entry || typeof entry.method !== 'string' || !registry.has(entry.method) || nonRPC.has(entry.method) || m.entry !== 'admin-only' && registry.get(entry.method) !== 'administrators')
+                throw new StandaloneBuildError('CTL_EXTERNAL_ENTRY', 'External entries require registered administrator RPC methods.');
+            registry.set(entry.method, 'administrators');
+            bindings[entry.method] = { permission: 'administrators', effect: 'destructive' };
+        }
+    }
     const weights = { read: 0, write: 1, destructive: 2 };
     for (const [id, declared] of Object.entries(m.ctl.commands)) {
         const command = structuredClone(declared);
@@ -66,7 +77,7 @@ export async function buildApiDescription(m, bridgeMethods, run) {
         for (const method of ['identity.session', 'identity.logout'])
             bindings[method] = { permission: 'public', effect: 'write' };
     }
-    const description = makeDescriptor({ package: { id: m.package, version: m.spkVersion, displayName: m.displayname }, aliases: m.ctl.aliases ?? [m.package.toLowerCase()], provenance: { developedBy: m.ctl.developedBy ?? 'unknown', generator: 'synopkgland-cli' }, entry: m.entry ?? 'policy', transport: { path: `/webman/3rdparty/${m.package}/cgi/api.cgi`, auth: m.capabilities.identity ? 'dsm-app-session' : 'dsm-session' }, commands, bindings });
+    const description = makeDescriptor({ package: { id: m.package, version: m.spkVersion, displayName: m.displayname }, aliases: m.ctl.aliases ?? [m.package.toLowerCase()], provenance: { developedBy: m.ctl.developedBy ?? 'unknown', generator: 'synopkgland-cli' }, entry: m.entry ?? 'policy', transport: { path: `/webman/3rdparty/${m.package}/cgi/api.cgi`, auth: m.capabilities.identity ? 'dsm-app-session' : 'dsm-session' }, commands, bindings, ...(m.ctl.external ? { external: m.ctl.external } : {}) });
     try {
         return { description: validateDescriptor(description, m.package, m.spkVersion), registry: Object.fromEntries(registry) };
     }

package/dist/standalone/manifest.d.ts

@@ -50,6 +50,7 @@ export interface StandaloneManifest {
         aliases?: string[];
         developedBy?: string;
         commands: Record<string, import("../ctl/descriptor.js").Operation>;
+        external?: import("../ctl/descriptor.js").ApiPayload['external'];
     };
     metadata?: PackageMetadata;
     dependencies?: PackageDependencies;

package/dist/standalone/manifest.js

@@ -495,6 +495,16 @@ function readManifest(raw, c) {
         c.fail("CTL_DECLARATION_INVALID", "ctl requires enabled and explicit commands.");
         return undefined;
     }
+    if (isRecord(raw.ctl) && raw.ctl.external !== undefined) {
+        const external = raw.ctl.external;
+        if (!isRecord(external) || Object.keys(external).length < 1 || Object.keys(external).length > 16 ||
+            Object.entries(external).some(([protocol, entry]) => !/^[a-z][a-z0-9-]{0,63}$/.test(protocol) ||
+                !isRecord(entry) || Object.keys(entry).length !== 1 || typeof entry.method !== 'string' ||
+                entry.method.length > 128 || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(entry.method))) {
+            c.fail('CTL_EXTERNAL_DECLARATION_INVALID', 'ctl.external requires protocol names and fixed RPC methods.');
+            return undefined;
+        }
+    }
     return {
         ...(raw.ctl ? { ctl: raw.ctl } : {}),
         root: c.root,

package/docs/ctl-external.md

@@ -0,0 +1,212 @@
+# Local external callers for MCP
+
+The CLI supplies a generic local bridge transport:
+
+```text
+synopkgland ctl external --protocol example-external-v1 --host controller --input - --json
+```
+
+It accepts one UTF-8 JSON object from stdin and emits exactly one compact
+`{ok:true,data:...}` or `{ok:false,error:{code,message,hint}}` object on stdout.
+Input and output, including the final newline, are bounded to 1 MiB. Requests
+have a shared 30-second network budget. A bridge should also bound the child
+process lifetime, stdin and stderr. Invalid/duplicate options and duplicate JSON
+keys are refused. Business arguments never belong in argv.
+
+This command is implemented in the CLI. Apps must implement the trusted entry
+below; the CLI does not create an MCP server, HTTP listener, shared service or
+tool Engine. Apps without that entry remain unsupported. No SDK change or
+automatic App upgrade is included.
+
+## App declaration and approval
+
+An App may declare up to 16 lowercase protocol IDs (1–64 letters/digits/dashes,
+starting with a letter). There is no App-specific protocol dispatch. For a native
+App with explicit ordinary ctl commands, extend `dsm-package.yaml`:
+
+```yaml
+ctl:
+  enabled: true
+  # Keep the App's existing aliases, developedBy and commands here.
+  external:
+    example-external-v1:
+      method: bridge.external
+```
+
+The existing route registry must export `bridge.external` as an administrator
+RPC method (or have an administrator-only App entry). Build rejects missing,
+nonadministrator and raw HTTP routes. The generated v1 API descriptor adds:
+
+```json
+{
+  "external": {"example-external-v1": {"method": "bridge.external"}}
+}
+```
+
+This is a field of `payload`, included in its existing canonical SHA-256.
+`payload.bindings["bridge.external"]` is
+`{"effect":"destructive","permission":"administrators"}` as a conservative
+transport classification. The external method cannot appear as a command ID or
+any ordinary command's invoke, job, pagination, streaming or upload helper.
+`ctl list` displays declarations separately from ordinary commands.
+App-owned runtime descriptors may produce this same extension. Keep their
+packaged descriptor, permissions and registry in agreement with the live one.
+
+The operator must first register/sign in locally, then explicitly approve the
+specific App's fresh description with ordinary discovery, for example:
+
+```sh
+synopkgland host login controller
+synopkgland ctl list --host controller --app Example --refresh --approve-installed --json
+```
+
+Approval authorizes sending the DSM session to that installed App's fixed CGI.
+Obtain the user's authorization before approving an App. External calls cannot
+approve Apps or update description pins. They match the protocol against cached
+descriptors of approved installed package versions, then reread and verify the
+selected live descriptor against its approved hash. Zero or multiple matching
+Apps refuse; revoke the unwanted approval or use distinct protocol IDs. A cache
+is only a recipient selector and never grants tool authority.
+
+Only a named, registered host and its OS-stored session are used. Ambient
+`DSM_*` credentials/URL cannot create or replace this login. HTTPS requires the
+stored SHA-256 certificate pin and refuses rotation before sending HTTP headers,
+including under ordinary ctl's permissive TLS default. Registered strict-TLS/CA
+settings still apply. A registered explicit loopback SSH tunnel is also accepted.
+No default-host fallback, multi-host mode, URL/TLS override, `--yes`, `--via` or
+automatic login is available. Reapprove intentional changes outside the bridge.
+
+## Local stdin/stdout contract
+
+Describe input has exactly these fields:
+
+```json
+{"protocol":"example-external-v1","action":"describe"}
+```
+
+Success data is the App's current Catalog, with a revision binding the entire
+tool set:
+
+```json
+{"ok":true,"data":{"revision":"r1","tools":[{"name":"notes__list","description":"notes.list","inputSchema":{"type":"object","additionalProperties":false},"outputSchema":{"type":"object"},"_meta":{"method":"notes.list"}}]}}
+```
+
+Catalog revisions contain 1–128 letters/digits/underscores/dashes. At most 1024
+tools fit within the output budget. Each tool has a unique MCP-compatible `name`
+(1–128 letters/digits/underscores/dashes), unique original dotted method in
+`_meta.method`, and self-contained JSON Schema 2020-12 input/output objects.
+Other App metadata is preserved. Schema references must be local. The App owns
+tool eligibility, effect, schema hashes and revision construction; the bridge
+may additionally compare these against its matching built-in OpSpecs.
+
+Call input has exactly these fields:
+
+```json
+{"protocol":"example-external-v1","action":"call","revision":"r1","method":"notes.list","arguments":{}}
+```
+
+The CLI fetches a fresh Catalog through the trusted entry, refuses stale
+revisions/unknown methods, and validates arguments against that tool's current
+input schema. Success data is the App's tool Result, validated against the
+tool's output schema. The CLI never starts an ordinary ctl flow for this call.
+`actor`, `via`, `allowMutation`, `allow_mutation` and `host` are forbidden as
+request fields and root argument fields. They cannot establish authority through
+nested business data either: App handlers must derive transport authority from
+the verified server context. Model arguments are business data only.
+
+## Trusted App RPC contract
+
+Both actions enter only the declared method at the package's existing fixed
+`/webman/3rdparty/<package>/cgi/api.cgi`, using the stored DSM session and
+SynoToken. This initial implementation requires `dsm-session`; Apps using
+`dsm-app-session` cannot declare external entries in generated descriptions.
+
+The CLI adds installed-package and approved-description pins to RPC `params`:
+
+```json
+{"method":"bridge.external","params":{"protocol":"example-external-v1","action":"call","revision":"r1","method":"notes.list","arguments":{},"package":{"id":"Example","version":"1"},"descriptionSha256":"<approved 64-hex hash>"}}
+```
+
+Describe has the same pins plus `protocol` and `action`, without call fields.
+The App must strictly decode this envelope and, for **both** actions:
+
+1. Authenticate the current DSM session and SynoToken, require a current
+   administrator, and establish the verified user from the SDK Caller.
+2. Verify the protocol, installed package/version and current descriptor hash.
+   Do not echo unverified request values as evidence.
+3. Derive MCP provenance from this dedicated entry. Never take actor, provenance,
+   scope authority or mutation intent from request JSON. Ordinary ctl must keep
+   its existing provenance and must not expose this entry as a normal tool.
+4. Describe the eligible shared Engine tool set. For calls, atomically compare
+   revision and pins with the tool set being dispatched, before any effect.
+   CLI preflight cannot close a server-side revision race.
+5. Resolve scope/targets, enforce explicit server-authorized mutation intent,
+   draft/selection gates and budgets, then execute the shared Engine. Human-only
+   methods must refuse guessed names; sensitive adapters return existing cards.
+
+Use the ordinary SDK `{success,data|error}` RPC envelope. On success, `data` is:
+
+```json
+{
+  "verified": {
+    "protocol": "example-external-v1",
+    "package": {"id": "Example", "version": "1"},
+    "descriptionSha256": "<verified 64-hex hash>",
+    "user": "<verified DSM username>",
+    "administrator": true,
+    "revision": "r1"
+  },
+  "data": {"revision":"r1","tools":[]}
+}
+```
+
+For calls the inner `data` is the tool Result and the verified revision must
+equal the requested revision. The CLI verifies all evidence against its pins,
+stored username and Catalog revision, then unwraps only the inner data for the
+local bridge. Evidence is an assertion by the approved authenticated App, not
+a signed delegation token. The server must perform these checks before dispatch;
+returning evidence afterward cannot undo an unauthorized effect.
+
+## Failure and verification boundary
+
+The CLI rereads local session/host/approval state before each external RPC. It
+does not refresh expired sessions. All errors return bounded generic text;
+upstream messages, request arguments and exception text are never echoed.
+Session carriers and schema-marked sensitive call values are redacted from
+results. The App remains responsible for its own secret-free Catalog and Result.
+Authentication failures exit 2, invalid input/options 3, trust/permission/revision
+refusals 4, contract failures 5 and network failures 6.
+
+There is exactly one mutation dispatch attempt. Timeout, interruption, invalid
+evidence/schema or oversized output may follow a committed mutation; none
+causes a retry. Query the original receipt/Operation or current state before any
+further action. Killing the CLI stops observation and does not cancel an App
+Operation.
+
+Tests exercise compiled CLI subprocesses and a local TLS fixture, including
+fresh administrator checks, revision races, lost replies and certificate
+rotation. They do not establish any App's installed or deployed readiness.
+
+## Syngle I-B / K9 integration checklist
+
+- Keep the existing bridge argv and stdin/stdout shapes, with
+  `syngle-external-v1` declared under `ctl.external`; no protocol-ID rename is
+  needed. Select a fixed administrator RPC method such as `mcp.external`.
+- Register that exact RPC in CGI and worker route composition and digest-bound
+  administrator permissions. Align generated/static and runtime descriptors,
+  their canonical hashes and package version. Keep it out of ordinary ctl flows.
+- Strictly decode the trusted RPC params and implement the evidence envelope
+  above. Generate Describe data with the current exact `mcpbridge.NewCatalog`.
+  Compare revision/pins at the shared Engine dispatch boundary, not after effects.
+- Construct `aitools.NewExternal(Config)` per verified Caller, preserving the
+  scope resolver, mutation-intent gate, selection/DraftGate and read-NAS budgets.
+  Keep `Authority.AllowMutation` server-authorized; do not enable it because the
+  request uses this transport. Return the original `aitools.Result` for Call.
+- After the coordinator releases a compatible CLI, update the distribution pin
+  and setup guidance. Login alone is insufficient: include explicit App
+  discovery/approval. Preserve the bridge's exact OpSpec comparison, cancellation
+  semantics, output budget and refusal to retry lost mutations.
+- Run composed App/bridge acceptance for expired/nonadmin sessions, forged
+  authority, stale/racing revisions, human-only guesses, ordinary `via=ctl`,
+  trusted `via=mcp`, AI disabled and lost mutation replies. Until then, report
+  Syngle end-to-end integration as pending.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "assets",
     "CHANGELOG.md",
     "schema",
+    "docs/ctl-external.md",
     "skills"
   ],
   "scripts": {

package/schema/synopkgland-api-v1.schema.json

@@ -397,6 +397,29 @@
               "flow"
             ]
           }
+        },
+        "external": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 16,
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,63}$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "method": {
+                "type": "string",
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+              }
+            },
+            "required": [
+              "method"
+            ]
+          }
         }
       },
       "required": [

package/skills/SKILL.md

@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.37.0 and CLI 0.40.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.37.0 and CLI 0.41.0 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read

package/skills/reference/ctl.md

@@ -16,6 +16,27 @@ Use `host show nas` to inspect approvals/pins, `host revoke nas PackageID` to re
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.
 
+## Local MCP external callers
+
+`synopkgland ctl external --protocol <declared-id> --host <profile> --input - --json`
+accepts one strict JSON `describe` or revision-bound `call` on stdin and emits one
+`{ok,data|error}` object. This requires an App-declared `ctl.external` protocol,
+an approved package/version/description pin from ordinary discovery, and a stored
+local login. The CLI rereads the installed inventory and descriptor and verifies
+the App's fresh administrator evidence. HTTPS uses the registered certificate
+pin even when ordinary NAS commands accept certificate changes. Environment
+passwords never log in this caller; model input cannot choose the host, actor,
+provenance or mutation authority. No `--yes`, multi-host selection, credential,
+URL or TLS override is accepted. A lost mutation reply is never retried; query
+the original operation/state first.
+
+Read [the App contract](../../docs/ctl-external.md) before implementing an adapter.
+The trusted App entry must atomically verify revision/pins, authenticate the
+administrator and derive `via=mcp` and mutation authority server-side. Ordinary
+ctl cannot invoke this entry through command flows. A protocol declaration alone
+does not implement these checks or make an App MCP-ready. `syngle-external-v1`
+works as a declared protocol; the CLI has no App-specific protocol branch.
+
 ## Plan command coverage
 
 For packaging an upstream open-source App (including forks with `synology/`),