@synopackageland/cli 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # 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
+  (`ui/cgi/api.cgi`) as the package daemon with `args`, instead of a separate
+  `exec`. The binary keeps the route audit and build digests of the CGI
+  build. `targets` becomes optional; with `daemon.node` the CLI writes its
+  Node launcher and passes `SYNOPKGLAND_NODE` and
+  `SYNOPKGLAND_DAEMON_PAYLOAD` so the backend can start Node children itself.
+  It needs an SDK whose daemon controller supports backend daemons
+  (`STANDALONE_DAEMON_BUILD_FAILED` otherwise) and cannot be combined with
+  `identity_gateway`. `inspect` verifies the `backend` config and the
+  backend's mode.
+- New skill reference `daemon-mode`: when a resident backend daemon pays off
+  and when to stay with the CGI, with a decision table, the factors to
+  measure and decision steps.
+- The route audit accepts `api.ServeIngress` (SDK) like `cgi.Serve`: called
+  directly, and never with a private or raw HTTP handler.
+- Pin templates 0.35.0 and its SDK/App 0.37.0 defaults. `daemon.backend` and
+  `api.ServeIngress` need SDK/App 0.37.0.
+
 ## 0.39.0 (2026-10-29)
 
 - Add schema-2 `dependencies.packages` for DSM package dependencies independent

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.38.0 uses templates ~0.34.0, whose default SDK pin is 0.36.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,8 +93,8 @@ 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.38.0 depends on `~0.34.0`: npm installation or
-update can select the latest templates patch in the 0.34 minor line. Templates
+`@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;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.

package/assets/go/route-audit/main.go

@@ -600,6 +600,10 @@ func main() {
 					if !direct[selector] {
 						problem(selector.Pos(), "route constructor aliases cannot be audited; register methods directly")
 					}
+				case "ServeIngress":
+					if !direct[selector] {
+						problem(selector.Pos(), "ingress constructor aliases cannot be audited")
+					}
 				}
 			}
 			if module == "net/http" {
@@ -659,6 +663,10 @@ func main() {
 			if module == "net/http/cgi" && selector.Sel.Name == "Serve" && len(call.Args) > 0 && reusesBoundary(call.Args[0], src, sources, safe, map[ast.Node]bool{}) {
 				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
 			}
+			// The daemon ingress serves the same browser requests as cgi.Serve.
+			if module == sdkModule+"/api" && selector.Sel.Name == "ServeIngress" && len(call.Args) > 1 && reusesBoundary(call.Args[1], src, sources, safe, map[ast.Node]bool{}) {
+				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
+			}
 			if module == "github.com/synopackageland/syno-pkg-land-sdk/dsm" && selector.Sel.Name == "NewEntryGate" {
 				out.EntryGate = true
 			}

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/skill.js

@@ -57,6 +57,11 @@ const SKILL_CATALOG = [
         file: "reference/backup.md",
         when: "Change or opt out of Hyper Backup application backup",
     },
+    {
+        id: "daemon-mode",
+        file: "reference/daemon-mode.md",
+        when: "Decide whether the backend should run as a resident daemon (daemon.backend)",
+    },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
     {
         id: "diagnose",

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

@@ -7,8 +7,13 @@ import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface Daemon {
     /** Optional bounded recovery; omitted means off. SDK 0.26.0 or later. */
     restart?: DaemonRestart;
-    /** Fixed foreground executable relative to daemon/payload. */
+    /** Fixed foreground executable relative to daemon/payload; empty for a backend daemon. */
     exec: string;
+    /**
+     * The App's own audited backend (ui/cgi/api.cgi) runs as the daemon with
+     * `args`; `node`, if set, is then only a runtime for the backend's children.
+     */
+    backend?: true;
     /** Architecture-specific project directories, copied without links. */
     targets: Partial<Record<NativeArchFamily, string>>;
     args: string[];
@@ -56,6 +61,10 @@ export declare function daemonConfig(manifest: StandaloneManifest): string;
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export declare function runnableDaemon(pkg: string, daemon: Daemon): Daemon;
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export declare const backendNodeEnv: () => Record<string, string>;
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export declare function requireBackendDaemonSource(source: string, daemon: Daemon | undefined): void;
 export declare function buildDaemonControl(manifest: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<string | undefined>;
 export declare function copyDaemonPayload(manifest: StandaloneManifest, arch: NativeArchFamily, target: string, controller: string): void;
 /** Copies a bounded, link-free package-account payload tree. */

package/dist/standalone/daemon.js

@@ -1,6 +1,6 @@
 import { operationBudgetSeconds, runtimeBudgetSdkSupported } from "../runtime/runtime-budgets.js";
 import { goChildEnv } from "../runtime/go-env.js";
-import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem, } from "../build-spk/go-toolchain.js";
 import { sdkSource, appSdkVersion } from "../runtime/sdk-source.js";
@@ -35,6 +35,7 @@ exec "$node" "$@"
 }
 const fields = new Set([
     "exec",
+    "backend",
     "targets",
     "args",
     "env",
@@ -69,19 +70,25 @@ export function readDaemon(value, root, arches, fail) {
     const invalid = () => {
         fail({
             code: "STANDALONE_DAEMON_INVALID",
-            message: "daemon accepts only fixed exec, targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
+            message: "daemon accepts only fixed exec (or backend: true), targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
         });
         return undefined;
     };
     if (!record(value) || Object.keys(value).some((k) => !fields.has(k)))
         return invalid();
-    if (!(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+    const backend = value.backend === true;
+    if (value.backend !== undefined && !backend)
         return invalid();
-    if (!record(value.targets) ||
-        Object.keys(value.targets).length !== arches.length)
+    if (backend ? value.exec !== undefined : !(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+        return invalid();
+    // A backend daemon needs a payload only for its children's files.
+    const payload = !backend || value.targets !== undefined;
+    if (payload &&
+        (!record(value.targets) ||
+            Object.keys(value.targets).length !== arches.length))
         return invalid();
     const targets = {};
-    for (const arch of arches) {
+    for (const arch of payload ? arches : []) {
         const path = value.targets[arch];
         if (typeof path !== "string" ||
             !path.trim() ||
@@ -123,8 +130,11 @@ export function readDaemon(value, root, arches, fail) {
         return undefined;
     if (ingress && Object.keys(env).some((key) => key in ingressEnv("", ingress)))
         return invalid();
+    if (backend && node && Object.keys(env).some((key) => key in backendNodeEnv()))
+        return invalid();
     return {
-        exec: value.exec,
+        exec: backend ? "" : value.exec,
+        ...(backend ? { backend: true } : {}),
         targets,
         args,
         ...(uninstall ? { uninstall_args: uninstall } : {}),
@@ -171,7 +181,7 @@ export function daemonConfig(manifest) {
             : runnableDaemon(manifest.package, manifest.daemon);
     return (JSON.stringify({
         package: manifest.package,
-        exec,
+        ...(!manifest.compose && manifest.daemon?.backend ? { backend: true } : { exec }),
         args,
         ...(uninstall_args ? { uninstall_args } : {}),
         ...(restart ? { restart } : {}),
@@ -187,8 +197,12 @@ export function daemonConfig(manifest) {
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export function runnableDaemon(pkg, daemon) {
-    const entry = daemon.node && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
-    const env = daemon.ingress ? { ...daemon.env, ...ingressEnv(pkg, daemon.ingress) } : daemon.env;
+    const entry = daemon.node && !daemon.backend && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
+    const env = {
+        ...daemon.env,
+        ...(daemon.ingress ? ingressEnv(pkg, daemon.ingress) : {}),
+        ...(daemon.backend && daemon.node ? backendNodeEnv() : {}),
+    };
     return {
         ...daemon,
         ...(entry ? { exec: NODE_LAUNCHER, args: [...entry, ...daemon.args] } : {}),
@@ -196,6 +210,19 @@ export function runnableDaemon(pkg, daemon) {
         env: Object.fromEntries(Object.keys(env).sort().map((key) => [key, env[key]])),
     };
 }
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export const backendNodeEnv = () => ({
+    SYNOPKGLAND_DAEMON_PAYLOAD: "${SYNOPKG_PKGDEST}/daemon/payload",
+    SYNOPKGLAND_NODE: `\${SYNOPKG_PKGDEST}/daemon/payload/${NODE_LAUNCHER}`,
+});
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export function requireBackendDaemonSource(source, daemon) {
+    if (!daemon?.backend)
+        return;
+    const main = join(source, "daemonctl/main.go");
+    if (!existsSync(main) || !readFileSync(main, "utf8").includes("backendExecutable"))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_BUILD_FAILED", "daemon.backend needs an SDK whose daemon controller can run the backend (SDK/App 0.37.0 or later); upgrade the App SDK.");
+}
 export async function buildDaemonControl(manifest, arch, work, run) {
     if (!manifest.daemon && !(manifest.compose && manifest.identityGateway))
         return undefined;
@@ -203,6 +230,7 @@ export async function buildDaemonControl(manifest, arch, work, run) {
     const sdk = daemonSdkVersion(manifest);
     const source = runtimeBudgetSource(sdkSource(sdk).goDir, manifest);
     requireDaemonRestartSource(source, sdk, manifest.daemon?.restart);
+    requireBackendDaemonSource(source, manifest.daemon);
     const result = await run("go", [
         "build",
         "-trimpath",
@@ -233,16 +261,16 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         copyPayloadTree(manifest.root, source, join(target, "payload"));
     else
         mkdirSync(join(target, "payload"), { recursive: true });
-    if (!manifest.compose && manifest.daemon?.node) {
+    if (!manifest.compose && manifest.daemon?.backend) {
+        // The CLI installs the backend itself at ui/cgi/api.cgi.
+        if (manifest.daemon.node)
+            writeNodeLauncher(source, target, manifest.daemon.node);
+    }
+    else if (!manifest.compose && manifest.daemon?.node) {
         const exec = join(source, daemon.exec);
         if (!existsSync(exec) || !lstatSync(exec).isFile())
             throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `daemon.exec must name the Node entry file inside the payload: ${exec}`);
-        if (existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
-            throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
-        mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
-        chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
-        writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(manifest.daemon.node));
-        chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+        writeNodeLauncher(source, target, manifest.daemon.node);
     }
     else if (!manifest.compose) {
         const exec = join(source, daemon.exec);
@@ -257,6 +285,14 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         mode: 0o644,
     });
 }
+function writeNodeLauncher(source, target, node) {
+    if (source && existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
+    mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
+    chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
+    writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(node));
+    chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+}
 /** Copies a bounded, link-free package-account payload tree. */
 export function copyPayloadTree(root, source, target) {
     const invalid = (message) => {

package/dist/standalone/inspect-spk.js

@@ -24,7 +24,7 @@ import { familyOfArchToken, NATIVE_ARCH_FAMILIES, } from "../build-spk/dsm-arch.
 import { CONTAINER_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, PORTAL_MIN_DSM, PORTAL_MIN_DSM_REASON, } from "../build-spk/dsm-version.js";
 import { ELF_MACHINE } from "./binary.js";
 import { CGI_PAYLOAD_PATH, entryLauncherAccess } from "./dsm-window.js";
-import { daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
+import { backendNodeEnv, daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, daemonIngressMinDsmProblem, readDaemonIngress, renderDaemonIngressConfig } from "./daemon-ingress.js";
 import { daemonRestartSdkProblem, readDaemonRestart } from "./daemon-restart.js";
 import { ROOT_SCRIPT_HINTS } from "./root-ops.js";
@@ -970,6 +970,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             Object.keys(config).some((key) => ![
                 "package",
                 "exec",
+                "backend",
                 "args",
                 "env",
                 "timeouts",
@@ -981,8 +982,11 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("package/config mismatch");
         if (!isDeepStrictEqual(config.restart, extras.restart))
             throw new Error("daemon restart differs from its build declaration");
+        const backend = config.backend === true;
+        if (config.backend !== undefined && !backend)
+            throw new Error("invalid backend flag");
         const daemon = readDaemon({
-            exec: config.exec,
+            ...(backend ? { backend: true } : { exec: config.exec }),
             args: config.args,
             uninstall_args: config.uninstall_args,
             env: config.env,
@@ -994,6 +998,12 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("invalid config");
         // The packaged config already carries the launcher argv; only the launcher itself is checked here.
         if (extras.node &&
+            backend &&
+            (daemon.env.SYNOPKGLAND_NODE !== backendNodeEnv().SYNOPKGLAND_NODE ||
+                readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
+            throw new Error("Node launcher differs from its build declaration");
+        if (extras.node &&
+            !backend &&
             (daemon.exec !== NODE_LAUNCHER ||
                 !daemon.args[0]?.startsWith("${SYNOPKG_PKGDEST}/daemon/payload/") ||
                 readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
@@ -1007,7 +1017,8 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
                 JSON.stringify(daemon.args) !== '["run"]' ||
                 daemon.uninstall_args))
             throw new Error("compose gateway must run without a child");
-        if (payload.find((p) => p.path === `daemon/payload/${daemon.exec}`)?.mode !==
+        // A backend daemon runs the audited CGI binary.
+        if (payload.find((p) => p.path === (backend ? CGI_PAYLOAD_PATH : `daemon/payload/${daemon.exec}`))?.mode !==
             "0755")
             throw new Error("missing executable");
         const manifest = {

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

@@ -312,8 +312,8 @@ function readManifest(raw, c) {
         if (problem)
             c.fail("STANDALONE_DAEMON_RESTART_SDK_REQUIRED", problem);
     }
-    if ((daemon?.ingress || daemon?.node) && raw.identity_gateway !== undefined)
-        c.fail("STANDALONE_DAEMON_INVALID", "daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
+    if ((daemon?.ingress || daemon?.node || daemon?.backend) && raw.identity_gateway !== undefined)
+        c.fail("STANDALONE_DAEMON_INVALID", "daemon.backend, daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
     if (compose && identityGateway && compose.sdk !== identityGateway.sdk)
         c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose and identity_gateway must use the same SDK release.");
     if (compose &&
@@ -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.39.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": {
@@ -27,7 +28,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.34.0",
+    "@synopackageland/templates": "~0.35.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

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

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.34.0`. A templates patch needs only a
+The CLI installs templates through `~0.35.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -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.36.0 and CLI 0.38.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
@@ -118,6 +118,8 @@ entries are injected, and the declaration grants no private-data access.
 
 Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting; DSM 7.2-64570+ supports schema-2 Portal without an executor, while DSM 7.1 requires executor registration. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate native runtimes in @synopackageland/sdk/native; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
+Before choosing `daemon.backend` (the backend as a resident daemon behind `daemon.ingress`) for speed, read [reference/daemon-mode.md](reference/daemon-mode.md): measure the CGI first; the daemon pays off only for repeated, cacheable per-request work on a NAS with memory to spare.
+
 Read [reference/lifecycle.md](reference/lifecycle.md) before editing `dsm-scripts/` (preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status): the SDK runs them inside its generated scripts as the package account; never add root work or repeat SDK steps there.
 
 Native Apps appear in Hyper Backup as applications by default. Read [reference/backup.md](reference/backup.md) before changing `backup` in dsm-package.yaml (opt out with `hyper_backup: false`, online mode, data version, hook). Hyper Backup runs the generated `scripts/backup/` as root; it is a fixed template that only switches to the package account, so never add or edit files there.

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/`),

package/skills/reference/daemon-mode.md

@@ -0,0 +1,90 @@
+# When to run the backend as a daemon
+
+A native App's backend normally runs as a CGI: DSM starts `ui/cgi/api.cgi`
+for every request, and the process exits when the request ends. With
+`daemon.backend: true` and `daemon.ingress` ([docs/daemon.md](../../docs/daemon.md)),
+the same binary runs once as the package daemon and serves the pages through
+DSM's nginx. The CGI stays for integrations, transfers and fallback.
+
+Daemon mode is not the default recommendation. It removes work that repeats
+on every request. It does not make a single expensive request cheaper, and it
+costs memory for as long as the package runs. Measure first, then decide.
+
+## Decision table
+
+| Factor | Daemon helps | Stay with CGI |
+| --- | --- | --- |
+| Fixed cost per request | High: each request loads or compiles many definitions, opens several stores or runs sign-in checks that could be remembered | Low: the handler reads a row or two and returns |
+| Request rate | Pages send many calls; many users at once | A few calls per page; few users |
+| Repeated, cacheable work | Most of the time goes to work whose result does not change between requests (compiled definitions, permission answers, zone data) | Each request does new work (one-off reports, large exports) |
+| Long connections | Streams, server-sent events, long polling | None |
+| Background work | A tick, outbox sending or polling that should run within seconds | A scheduled task every few minutes is enough |
+| App size | Many Apps, large definitions | One small App |
+| NAS memory | Enough room for the base process plus a bounded cache | Small models (2–4 GB) that already swap; every resident MB competes with DSM and other packages |
+| Idle cost | Acceptable: the process stays up when nobody uses the App | Not acceptable: the App is opened rarely |
+
+The base process is usually small: an idle Go daemon is typically 10–30 MB
+RSS. Measure your own binary. The real variable is the cache, so give every
+cache an upper bound and measure it filled.
+
+## Factors and example numbers
+
+These numbers come from Studio Office. Use them as an example of what
+to measure, not as a budget.
+
+- **CGI cost per request.** On a DS SA3400 with 25 Apps, every Studio call
+  spent 100–140 ms before the handler did any work: process start, the DSM
+  sign-in check (`authenticate.cgi`), the App Privileges check and schema
+  checks. Recompiling App definitions on each request took about 70% of
+  `studio.apps.list`. Measure this on the NAS: time an empty call (for
+  example `app.status`) and the slowest common page calls.
+- **Resident memory.** Measured on macOS arm64 in a Go test process, not
+  on the NAS: 37 MB RSS with the routes built and the store opened, and
+  81 MB after 23 compiled template Apps were kept (about 1.1 MB of
+  heap per App).
+  The Node AI child has not been measured. Measure on the target NAS with your
+  real data before you choose cache sizes.
+- **Cache bounds.** Bound each cache by entry count (LRU) and derive the bound
+  from the measured size per entry. Studio keeps 32 compiled releases, about
+  35 MB at the measured size. Cache only results that are pure functions of
+  their key, such as compiled definitions keyed by a hash of the stored plan,
+  and cache only successes.
+- **Sign-in cache.** `dsm.CacheSessions` remembers verified sessions for a
+  TTL you choose (Studio: 10 minutes). The cost is staleness: a sign-out, a
+  disabled account or a lost administrator role takes effect up to the TTL
+  later. App Privileges keep their own 30-second check.
+- **Crash and restart.** The SDK daemon controller restarts the daemon
+  (`daemon.restart`). Children of the daemon, such as a Node service, are the
+  backend's own job: start them, restart them with backoff and stop them on
+  SIGTERM. Keep the CGI as fallback, so pages still work when the daemon is
+  down. Retry only reads automatically, plus calls the daemon cannot have seen.
+- **Upgrade.** DSM stops the old daemon and starts the new one. In-memory
+  caches start empty and fill on first use. Migrations still run at start.
+  The CGI is the same binary, so both paths always run the same version.
+- **Security boundary.** The daemon serves the same handler as the CGI. Origin,
+  App entry, DSM session and route permission are checked on every request.
+  The ingress socket is mode 0666 because nginx runs as another account, so
+  a local process can connect directly and choose `X-Real-IP`. A valid DSM
+  session is still required, but IP-based App Privileges rules can be
+  bypassed this way. The route audit treats `api.ServeIngress` like
+  `cgi.Serve`.
+
+## Decision steps
+
+1. Measure the CGI. Time an empty authenticated call and the 3–5 calls a
+   common page makes, on the target NAS, a few times each. Count how many
+   calls one page sends.
+2. Find where the time goes. Split fixed cost (process start, sign-in, entry
+   checks) from handler work. Then split handler work into repeated,
+   cacheable work and work that changes per request.
+3. Optimize inside the CGI first, if that is enough:
+   - Send fewer requests: batch reads, and return all items in one page instead
+     of serial paging.
+   - Use disk caches keyed by content hash (for example compiled definitions
+     next to the store).
+   - Avoid loading what the call does not use.
+4. Choose the daemon only when, after step 3, most of the remaining time is
+   fixed cost or cacheable repeated work, and the NAS has memory for the
+   measured base plus the bounded cache.
+5. After switching, measure idle RSS and RSS with a full cache on the NAS, and
+   the same page calls as in step 1. Write the numbers into the App's docs.