@synopackageland/cli 0.6.0 → 0.7.0

package/dist/portal/package.js

@@ -0,0 +1,116 @@
+import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES, resolvedContractPortal } from "./alias.js";
+/** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
+export const PORTAL_JSON_RELPATH = "etc/portal.json";
+export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
+/** Install wizard key; DSM exports it to preinst/postinst. */
+export const PORTAL_INSTALL_KEY = "portal_alias";
+/** Package-owned install draft, never DSM's saved portal configuration. */
+export const PORTAL_DRAFT = "portal-install.json";
+/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
+export function contractPortal(contract) {
+    const portal = resolvedContractPortal(contract);
+    const packageId = String(contract.package);
+    return portal && { appId: packageId, application: String(contract.displayname ?? packageId), alias: portal.alias };
+}
+export function portalResource() {
+    return { "web-config": { "app-portal": { "json-relpath": PORTAL_JSON_RELPATH, "mustache-relpath": PORTAL_MUSTACHE_RELPATH } } };
+}
+/** Every field of DSM's own app.d files; the worker refuses a partial file (synopkg start 272). */
+export function renderPortalJson(portal) {
+    return `${JSON.stringify({
+        application: portal.application,
+        id: portal.appId,
+        alias: portal.alias,
+        fqdn: null,
+        alternatePort: {},
+        "x-accel": false,
+        include: [],
+        injectable: false,
+        ssl: { spdy: false, hsts: false },
+        index: "index.cgi",
+        root: "/usr/syno/synoman",
+        version: 2,
+    })}\n`;
+}
+/** DSM's CGI location: index.cgi launches the app id nginx passes as REWRITE_APP. */
+export function renderPortalMustache() {
+    return "{{> /usr/syno/share/nginx/cgi}}\n";
+}
+/** DSM renders wizard descriptions as HTML; "<alias>" would vanish as a tag. */
+function htmlText(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export function renderPortalWizardItems(t, alias) {
+    return [
+        { desc: htmlText(t("portal.notice")) },
+        {
+            type: "textfield",
+            desc: t("portal.alias"),
+            subitems: [{
+                    key: PORTAL_INSTALL_KEY,
+                    desc: t("portal.alias"),
+                    defaultValue: alias,
+                    validator: { allowBlank: false, regex: { expr: `/${PORTAL_ALIAS_PATTERN.source}/`, errorText: t("portal.aliasInvalid") } },
+                }],
+        },
+    ];
+}
+export function renderPortalWizardStep(t, alias) {
+    return { step_title: t("portal.step"), items: renderPortalWizardItems(t, alias) };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+const MARKER = "SYNOPKGLAND_PORTAL_ALIAS";
+/**
+ * preinst validates the wizard answer, postinst stores it and writes it as the
+ * default alias of the package's own portal.json, postupgrade restores it into
+ * the new payload. Activation stays an administrator's AppPortal set call.
+ */
+export function renderPortalLifecycle(name, portal) {
+    if (!["preinst", "postinst", "postupgrade"].includes(name))
+        return "";
+    const [prefix, suffix] = renderPortalJson({ ...portal, alias: MARKER }).trimEnd().split(MARKER);
+    const helpers = `synopkgland_portal_valid() {
+  case "$1" in ''|-*|*-|*[!a-z0-9-]*) return 1 ;; esac
+  [ "\${#1}" -le ${PORTAL_ALIAS_MAX} ] || return 1
+  case ' ${RESERVED_PORTAL_ALIASES.join(" ")} ' in *" $1 "*) return 1 ;; esac
+  return 0
+}
+synopkgland_portal_var="\${SYNOPKG_PKGVAR:-/var/packages/\${SYNOPKG_PKGNAME:-}/var}"
+synopkgland_portal_json="\${SYNOPKG_PKGDEST:-/var/packages/\${SYNOPKG_PKGNAME:-}/target}/${PORTAL_JSON_RELPATH}"
+synopkgland_portal_write() {
+  synopkgland_portal_tmp="$synopkgland_portal_json.$$"
+  printf '%s%s%s\\n' ${shellQuote(prefix)} "$1" ${shellQuote(suffix)} > "$synopkgland_portal_tmp" &&
+    chmod 644 "$synopkgland_portal_tmp" && mv -f "$synopkgland_portal_tmp" "$synopkgland_portal_json"
+}
+`;
+    const answer = `synopkgland_portal_alias="\${${PORTAL_INSTALL_KEY}:-${portal.alias}}"
+  if ! synopkgland_portal_valid "$synopkgland_portal_alias"; then
+    echo "Application Portal alias: use 1-64 lowercase letters, digits or -, not a DSM path." >&2
+    exit 1
+  fi
+`;
+    if (name === "preinst") {
+        return `${helpers}if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  ${answer}fi
+`;
+    }
+    if (name === "postinst") {
+        return `${helpers}if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  ${answer}  (umask 077 && mkdir -p "$synopkgland_portal_var" &&
+    printf '{"schema":1,"alias":"%s"}\\n' "$synopkgland_portal_alias" > "$synopkgland_portal_var/.${PORTAL_DRAFT}.$$" &&
+    mv -f "$synopkgland_portal_var/.${PORTAL_DRAFT}.$$" "$synopkgland_portal_var/${PORTAL_DRAFT}") || exit 1
+  synopkgland_portal_write "$synopkgland_portal_alias" || exit 1
+fi
+`;
+    }
+    return `${helpers}synopkgland_portal_draft="$synopkgland_portal_var/${PORTAL_DRAFT}"
+if [ -f "$synopkgland_portal_draft" ] && [ ! -L "$synopkgland_portal_draft" ]; then
+  synopkgland_portal_alias="$(head -c 128 "$synopkgland_portal_draft" | sed -n 's/^{"schema":1,"alias":"\\([a-z0-9-]*\\)"}$/\\1/p')"
+  if synopkgland_portal_valid "$synopkgland_portal_alias"; then
+    synopkgland_portal_write "$synopkgland_portal_alias" || exit 1
+  fi
+fi
+`;
+}

package/dist/runtime/delegate-contract.d.ts

@@ -0,0 +1,79 @@
+/** Frozen schema-2 / v1 extension. Definitions alone do not enable capabilities. */
+export declare const MOVE_FROM_STAGING: "files.moveFromStaging";
+export declare const DELEGATE_EXTENSION_OPERATIONS: readonly ["files.moveFromStaging", "files.operationStatus", "files.cancelOperation", "delegate.disable", "delegate.enable", "delegate.audit"];
+export declare const DELEGATE_OPERATION_STATES: readonly ["queued", "copying", "committed", "canceled", "interrupted", "uncertain"];
+export type DelegateOperationState = typeof DELEGATE_OPERATION_STATES[number];
+export interface LongRunningDelegateCapability {
+    scope: string;
+    operations: [typeof MOVE_FROM_STAGING];
+    destinations: string[];
+    lifetime: 'until-revoked';
+}
+export interface SelectDestination {
+    key: string;
+    path: string;
+}
+/** Protected executor selection, not the package-owned installer draft. */
+export interface ScopeSelection {
+    scope: string;
+    root: string;
+    generation: number;
+}
+export interface DestinationState {
+    key: string;
+    selection: ScopeSelection | null;
+    destination: DestinationGrant | null;
+    status: 'active' | 'missing' | 'reselection-required' | 'needs-scope-confirmation' | 'disabled';
+}
+export interface DestinationGrant {
+    id: string;
+    key: string;
+    path: string;
+    username: string;
+    lifetime: 'until-revoked';
+}
+/** Owner/UID/destination are resolved from the protected grant, never supplied here. */
+export interface MoveFromStaging {
+    delegation_id: string;
+    job_id: string;
+    staging: string;
+    name: string;
+    size: number;
+}
+export interface OperationRef {
+    delegation_id: string;
+    job_id: string;
+}
+export interface OperationResult {
+    job_id: string;
+    state: DelegateOperationState;
+    /** Only a committed executor receipt may supply a final destination path. */
+    receipt?: {
+        path: string;
+        size: number;
+    };
+    code?: string;
+    reason?: string;
+}
+export declare const DELEGATE_ROUTES: {
+    readonly 'delegate.example.export': "authenticated";
+    readonly 'delegate.destination': "authenticated";
+    readonly 'delegate.select_destination': "authenticated";
+    readonly 'delegate.move_from_staging': "authenticated";
+    readonly 'delegate.operations.get': "authenticated";
+    readonly 'delegate.operations.list': "authenticated";
+    readonly 'delegate.operations.cancel': "authenticated";
+    readonly 'delegate.disable': "administrators";
+    readonly 'delegate.enable': "administrators";
+    readonly 'delegate.audit': "authenticated";
+};
+/** Shared, explicit limits; legacy TTL/job limits remain separate. */
+export declare const DELEGATE_LIMITS: {
+    readonly maxFileBytes: number;
+    readonly maxQueued: 16;
+    readonly maxActive: 1;
+    readonly maxCopySeconds: 86400;
+    readonly maxOperationBytes: number;
+    readonly maxAuditBytes: number;
+    readonly revalidateSeconds: 5;
+};

package/dist/runtime/delegate-contract.js

@@ -0,0 +1,27 @@
+/** Frozen schema-2 / v1 extension. Definitions alone do not enable capabilities. */
+export const MOVE_FROM_STAGING = 'files.moveFromStaging';
+export const DELEGATE_EXTENSION_OPERATIONS = [
+    MOVE_FROM_STAGING, 'files.operationStatus', 'files.cancelOperation',
+    'delegate.disable', 'delegate.enable', 'delegate.audit',
+];
+export const DELEGATE_OPERATION_STATES = [
+    'queued', 'copying', 'committed', 'canceled', 'interrupted', 'uncertain',
+];
+export const DELEGATE_ROUTES = {
+    'delegate.example.export': 'authenticated',
+    'delegate.destination': 'authenticated',
+    'delegate.select_destination': 'authenticated',
+    'delegate.move_from_staging': 'authenticated',
+    'delegate.operations.get': 'authenticated',
+    'delegate.operations.list': 'authenticated',
+    'delegate.operations.cancel': 'authenticated',
+    'delegate.disable': 'administrators',
+    'delegate.enable': 'administrators',
+    'delegate.audit': 'authenticated',
+};
+/** Shared, explicit limits; legacy TTL/job limits remain separate. */
+export const DELEGATE_LIMITS = {
+    maxFileBytes: 16 * 1024 ** 3, maxQueued: 16, maxActive: 1,
+    maxCopySeconds: 86400, maxOperationBytes: 10 * 1024 ** 2,
+    maxAuditBytes: 50 * 1024 ** 2, revalidateSeconds: 5,
+};

package/dist/runtime/executor-build.d.ts

@@ -1,4 +1,4 @@
-import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import { type NativeArchFamily } from '../build-spk/dsm-arch.js';
 import type { CommandRunner } from '../standalone/build.js';
 import type { StandaloneManifest } from '../standalone/manifest.js';
 import { type ExecutorPolicy } from './executor-policy.js';

package/dist/runtime/executor-build.js

@@ -1,9 +1,10 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { templatesRoot } from '../template-paths.js';
+import { goBuildEnv } from '../build-spk/dsm-arch.js';
 import { StandaloneBuildError } from '../standalone/spk.js';
 import { checkCgiBinary } from '../standalone/binary.js';
-import { executorPolicy, sha256 } from './executor-policy.js';
+import { executorPolicy, executorPolicyText, sha256 } from './executor-policy.js';
 import { executorTasks } from './executor-tasks.js';
 export function buildExecutor(m, arch, work, run) {
     if (!m.capabilities.delegate && !m.capabilities.rootOps)
@@ -14,20 +15,20 @@ export function buildExecutor(m, arch, work, run) {
     if (!existsSync(join(source, 'go.mod')))
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', 'Executor sources are missing.');
     const binary = join(dir, 'executor');
-    const result = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, CGO_ENABLED: '0', GOOS: 'linux', GOARCH: arch === 'x86_64' ? 'amd64' : 'arm64' } });
+    const result = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, ...goBuildEnv(arch) } });
     if (result.missing || result.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor build failed (${arch}). ${result.stderr}`);
     const problem = checkCgiBinary(work, binary, arch);
     if (problem)
         throw new StandaloneBuildError(problem.code, problem.message);
     const lifecycleBinary = join(dir, 'lifecycle');
-    const lifecycleResult = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, CGO_ENABLED: '0', GOOS: 'linux', GOARCH: arch === 'x86_64' ? 'amd64' : 'arm64' } });
+    const lifecycleResult = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...goBuildEnv(arch) } });
     if (lifecycleResult.missing || lifecycleResult.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Lifecycle helper build failed (${arch}). ${lifecycleResult.stderr}`);
     const lifecycleProblem = checkCgiBinary(work, lifecycleBinary, arch);
     if (lifecycleProblem)
         throw new StandaloneBuildError(lifecycleProblem.code, lifecycleProblem.message);
-    const policy = executorPolicy(m), policyText = JSON.stringify(policy) + '\n';
+    const policy = executorPolicy(m), policyText = executorPolicyText(policy);
     const pins = { package: m.package, executorDigest: sha256(readFileSync(binary)), policyDigest: sha256(policyText) };
     return { ...pins, binary, lifecycleBinary, policy, policyText, tasks: executorTasks(pins), implementation: 'executor' };
 }

package/dist/runtime/executor-inspect.d.ts

@@ -1,5 +1,8 @@
 import { type ExecutorPolicy } from './executor-policy.js';
 import { type ExecutorTask } from './executor-tasks.js';
+/** INFO key that anchors the executor digest; Package Center writes INFO as root. */
+export declare const EXECUTOR_ANCHOR = "synopkgland_executor_sha256";
+export declare function inspectExecutorAnchor(info: string, executorDigest: string): string[];
 export interface ExecutorInspection {
     executorDigest: string;
     policyDigest: string;

package/dist/runtime/executor-inspect.js

@@ -1,19 +1,25 @@
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { FILE_OPERATIONS, sha256 } from './executor-policy.js';
+import { validExecutorPolicy, sha256 } from './executor-policy.js';
+import { parseDocument } from 'yaml';
 import { executorTasks } from './executor-tasks.js';
 import { familyOfArchToken } from '../build-spk/dsm-arch.js';
 import { ELF_MACHINE } from '../standalone/binary.js';
+/** INFO key that anchors the executor digest; Package Center writes INFO as root. */
+export const EXECUTOR_ANCHOR = 'synopkgland_executor_sha256';
+export function inspectExecutorAnchor(info, executorDigest) {
+    const anchors = info.split('\n').filter(line => line.startsWith(`${EXECUTOR_ANCHOR}=`));
+    return anchors.length === 1 && anchors[0] === `${EXECUTOR_ANCHOR}="${executorDigest}"` ? [] : ['Executor INFO anchor must name the shipped executor digest exactly once.'];
+}
 export function inspectExecutor(dir, pkg, arch) {
     try {
         const binary = readFileSync(join(dir, 'executor/executor'));
-        if (!binary.subarray(0, 4).equals(Buffer.from([127, 69, 76, 70])) || binary.readUInt16LE(18) !== (familyOfArchToken(arch.split(' ')[0]) === 'aarch64' ? ELF_MACHINE.aarch64 : ELF_MACHINE.x86_64))
+        if (!binary.subarray(0, 4).equals(Buffer.from([127, 69, 76, 70])) || binary.readUInt16LE(18) !== ELF_MACHINE[familyOfArchToken(arch.split(' ')[0]) ?? 'x86_64'])
             throw new Error('Executor ELF architecture mismatch.');
         const text = readFileSync(join(dir, 'executor/policy.json'), 'utf8');
         const plan = JSON.parse(readFileSync(join(dir, 'executor/setup.json'), 'utf8'));
         const policy = JSON.parse(text);
-        const allowed = ['status', 'delegate.create', 'delegate.list', 'delegate.revoke', 'root.run', ...FILE_OPERATIONS];
-        if (policy.v !== 1 || policy.app !== `SYNO.SDS.${pkg}.Instance` || policy.package !== pkg || !Array.isArray(policy.operations) || !policy.operations.includes('status') || policy.operations.some(op => !allowed.includes(op)) || new Set(policy.operations).size !== policy.operations.length || !policy.root || typeof policy.root !== 'object' || Array.isArray(policy.root))
+        if (parseDocument(text, { uniqueKeys: true }).errors.length || !validExecutorPolicy(policy, pkg))
             throw new Error('Invalid executor policy.');
         for (const [name, digest] of Object.entries(policy.root)) {
             const path = `root/${name}.sh`;
@@ -21,7 +27,7 @@ export function inspectExecutor(dir, pkg, arch) {
                 throw new Error('Root script digest mismatch.');
         }
         const executorDigest = sha256(binary), policyDigest = sha256(text);
-        const tasks = executorTasks({ package: pkg, executorDigest, policyDigest });
+        const tasks = executorTasks({ package: pkg, policyDigest });
         if (plan.package !== pkg || plan.executorDigest !== executorDigest || plan.policyDigest !== policyDigest || JSON.stringify(plan.policy) !== JSON.stringify(policy) || JSON.stringify(plan.tasks) !== JSON.stringify(tasks) || plan.implementation !== 'executor')
             throw new Error('Executor pins or task binding mismatch.');
         return { executor: { executorDigest, policyDigest, policy, implementation: plan.implementation, tasks: tasks.map(task => ({ ...task, state: 'unknown' })) }, findings: [] };

package/dist/runtime/executor-policy.d.ts

@@ -1,25 +1,37 @@
 import type { RootOp } from '../standalone/root-ops.js';
+import type { EntryMode } from '../standalone/manifest.js';
 export declare const FILE_OPERATIONS: readonly ["files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write"];
 export interface DelegateCapability {
     operations: string[];
     scope: string;
+    destinations?: string[];
+    lifetime?: 'until-revoked';
 }
 export declare function validDelegate(value: unknown): value is DelegateCapability;
 export declare const sha256: (data: string | Buffer) => string;
 export interface ExecutorPolicy {
     v: 1;
     app: string;
+    /** Present only with a manifest `entry`; the executor then applies the same App Privileges rule offline. */
+    entry?: EntryMode;
     scope?: string;
+    destinations?: string[];
+    lifetime?: 'until-revoked';
     package: string;
     operations: string[];
     root: Record<string, string>;
 }
+/** The exact policy file bytes whose sha256 is the policy pin. */
+export declare const executorPolicyText: (policy: ExecutorPolicy) => string;
 /** Version-independent, sorted policy. Only §2.4 operation IDs are admitted. */
 export declare function executorPolicy(m: {
     package: string;
+    entry?: EntryMode;
     capabilities: {
         delegate?: DelegateCapability;
         rootOps?: true;
     };
     rootOps?: RootOp[];
 }): ExecutorPolicy;
+/** Inventory rejects malformed extensions even if a caller recomputes every pin. */
+export declare function validExecutorPolicy(value: unknown, pkg: string): value is ExecutorPolicy;

package/dist/runtime/executor-policy.js

@@ -1,24 +1,64 @@
 import { createHash } from 'node:crypto';
+import { MOVE_FROM_STAGING, DELEGATE_EXTENSION_OPERATIONS } from './delegate-contract.js';
 export const FILE_OPERATIONS = ['files.list', 'files.info', 'files.createFolder', 'files.checkPermission', 'files.write'];
 export function validDelegate(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
     const d = value;
-    return Object.keys(d).every(key => ['operations', 'scope'].includes(key)) && Array.isArray(d.operations) && d.operations.length > 0 && new Set(d.operations).size === d.operations.length && d.operations.every(op => FILE_OPERATIONS.includes(op)) && typeof d.scope === 'string' && (d.scope === 'home' || /^shared:[^/\\\x00-\x1f:]+$/.test(d.scope) && d.scope.slice(7).trim() === d.scope.slice(7) && !['.', '..'].includes(d.scope.slice(7)));
+    if (!Object.keys(d).every(key => ['operations', 'scope', 'destinations', 'lifetime'].includes(key)) || !Array.isArray(d.operations) || d.operations.length === 0 || new Set(d.operations).size !== d.operations.length || typeof d.scope !== 'string' || !(d.scope === 'home' || d.scope === 'install-selected' && d.lifetime === 'until-revoked' || /^shared:[^/\\\x00-\x1f:]+$/.test(d.scope) && d.scope.slice(7).trim() === d.scope.slice(7) && !['.', '..'].includes(d.scope.slice(7))))
+        return false;
+    if ('destinations' in d || 'lifetime' in d || d.operations.includes(MOVE_FROM_STAGING)) {
+        return d.lifetime === 'until-revoked' && d.operations.length === 1 && d.operations[0] === MOVE_FROM_STAGING
+            && Array.isArray(d.destinations) && d.destinations.length > 0 && d.destinations.length <= 64 && new Set(d.destinations).size === d.destinations.length
+            && d.destinations.every(key => typeof key === 'string' && /^[a-z][a-z0-9_-]{0,63}$/.exec(key)?.[0] === key);
+    }
+    return d.operations.every(op => FILE_OPERATIONS.includes(op));
 }
 export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+/** The exact policy file bytes whose sha256 is the policy pin. */
+export const executorPolicyText = (policy) => JSON.stringify(policy) + '\n';
 /** Version-independent, sorted policy. Only §2.4 operation IDs are admitted. */
 export function executorPolicy(m) {
     if (m.capabilities.delegate && !validDelegate(m.capabilities.delegate))
         throw new Error('[EXECUTOR_POLICY] Invalid delegate operations or scope.');
     const operations = ['status'];
-    if (m.capabilities.delegate)
+    if (m.capabilities.delegate) {
         operations.push('delegate.create', 'delegate.list', 'delegate.revoke', ...m.capabilities.delegate.operations);
+        if (m.capabilities.delegate.lifetime === 'until-revoked')
+            operations.push(...DELEGATE_EXTENSION_OPERATIONS);
+    }
     const root = {};
     if (m.capabilities.rootOps) {
         operations.push('root.run');
         for (const op of [...m.rootOps ?? []].sort((a, b) => a.name.localeCompare(b.name, 'en')))
             root[op.name] = sha256(op.body);
     }
-    return { v: 1, package: m.package, app: `SYNO.SDS.${m.package}.Instance`, ...(m.capabilities.delegate ? { scope: m.capabilities.delegate.scope } : {}), operations: [...new Set(operations)].sort(), root };
+    const d = m.capabilities.delegate;
+    return { v: 1, package: m.package, app: `SYNO.SDS.${m.package}.Instance`, ...(m.entry ? { entry: m.entry } : {}), ...(d ? { scope: d.scope } : {}),
+        ...(d?.lifetime ? { destinations: [...d.destinations].sort(), lifetime: d.lifetime } : {}),
+        operations: [...new Set(operations)].sort(), root };
+}
+/** Inventory rejects malformed extensions even if a caller recomputes every pin. */
+export function validExecutorPolicy(value, pkg) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const p = value;
+    if (Object.keys(p).some(key => !['v', 'package', 'app', 'entry', 'scope', 'destinations', 'lifetime', 'operations', 'root'].includes(key))
+        || p.v !== 1 || p.package !== pkg || p.app !== `SYNO.SDS.${pkg}.Instance`
+        || 'entry' in p && p.entry !== 'admin-only' && p.entry !== 'app-privilege'
+        || !Array.isArray(p.operations) || !p.operations.includes('status') || new Set(p.operations).size !== p.operations.length
+        || !p.root || typeof p.root !== 'object' || Array.isArray(p.root))
+        return false;
+    const base = ['status', 'root.run', 'delegate.create', 'delegate.list', 'delegate.revoke'];
+    if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS].includes(op)))
+        return false;
+    const delegated = p.operations.some(op => op.startsWith('files.') || op.startsWith('delegate.'));
+    if (!delegated)
+        return p.scope === undefined && p.lifetime === undefined && p.destinations === undefined;
+    const capability = { scope: p.scope, operations: p.operations.filter(op => FILE_OPERATIONS.includes(op) || op === MOVE_FROM_STAGING),
+        ...('lifetime' in p ? { lifetime: p.lifetime } : {}), ...('destinations' in p ? { destinations: p.destinations } : {}) };
+    if (!validDelegate(capability))
+        return false;
+    const expected = executorPolicy({ package: pkg, capabilities: { delegate: capability, ...(p.operations.includes('root.run') ? { rootOps: true } : {}) } }).operations;
+    return expected.length === p.operations.length && expected.every(op => p.operations.includes(op));
 }

package/dist/runtime/executor-scope-task.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutorPins, ExecutorTask } from './executor-tasks.js';
+/** Self-contained: the same function is embedded in the DSM window. No draft
+ * files are read by this task; the confirmed scope is a literal pinned argument. */
+export declare function executorScopeTask(pins: ExecutorPins, scope: string, actor: string, expectedGeneration: number): ExecutorTask;

package/dist/runtime/executor-scope-task.js

@@ -0,0 +1,21 @@
+/** Self-contained: the same function is embedded in the DSM window. No draft
+ * files are read by this task; the confirmed scope is a literal pinned argument. */
+export function executorScopeTask(pins, scope, actor, expectedGeneration) {
+    const share = scope?.startsWith('shared:') ? scope.slice(7) : '';
+    if (!(/^[A-Za-z][A-Za-z0-9]{1,63}$/.exec(pins.package)?.[0] === pins.package)
+        || ![pins.executorDigest, pins.policyDigest].every(v => typeof v === 'string' && v.length === 64 && /^[a-f0-9]{64}$/.test(v))
+        || !(scope === 'home' || share && share.trim() === share && !/[\/\\:\x00-\x1f\x7f%]/.test(share) && !share.includes('..') && !['.', 'home', 'homes'].includes(share.toLowerCase()))
+        || !Number.isSafeInteger(expectedGeneration) || expectedGeneration < 0
+        || !actor || /[\x00-\x1f\x7f%]/.test(actor))
+        throw new Error('executor_scope_invalid');
+    const header = '#!/bin/sh\n# synopkgland executor selection\n';
+    const script = header + `set -eu
+export PATH=/usr/bin:/bin
+d=/usr/local/etc/synopkgland/${pins.package}/runtime
+{ echo ${pins.executorDigest}"  $d/executor"; echo ${pins.policyDigest}"  $d/policy.json"; }|sha256sum -c - >/dev/null
+exec "$d/executor" select-scope --package '${pins.package}' --scope '${scope.replaceAll("'", "'\\''")}' --actor '${actor.replaceAll("'", "'\\''")}' --expected-generation ${expectedGeneration}
+`;
+    if (new TextEncoder().encode(script).length > 6000)
+        throw new Error('executor_scope_invalid');
+    return { kind: 'control', name: pins.package + ' executor selection', header, script };
+}

package/dist/runtime/executor-tasks.d.ts

@@ -11,6 +11,7 @@ export interface ExecutorTask {
     script: string;
 }
 export declare function validateTaskScript(script: string, limit: number): string;
-export declare function executorTasks(pins: ExecutorPins): ExecutorTask[];
+/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
+export declare function executorTasks(pins: Pick<ExecutorPins, 'package' | 'policyDigest'>): ExecutorTask[];
 export declare function bootDefinition(task: ExecutorTask): Record<string, unknown>;
 export declare function controlDefinition(task: ExecutorTask): Record<string, unknown>;

package/dist/runtime/executor-tasks.js

@@ -8,15 +8,15 @@ export function validateTaskScript(script, limit) {
         throw new Error('[EXECUTOR_TASK_LENGTH] Task script exceeds DSM byte limit.');
     return script;
 }
+/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
 export function executorTasks(pins) {
     if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(pins.package))
         throw new Error('[EXECUTOR_PACKAGE] Invalid package identity.');
-    for (const digest of [pins.executorDigest, pins.policyDigest])
-        if (!/^[a-f0-9]{64}$/.test(digest))
-            throw new Error('[EXECUTOR_DIGEST] Invalid sha256 pin.');
+    if (!/^[a-f0-9]{64}$/.test(pins.policyDigest))
+        throw new Error('[EXECUTOR_DIGEST] Invalid sha256 pin.');
     return ['boot', 'control'].map(kind => {
         const script = readFileSync(join(templatesRoot(), '_executor', 'internal', 'taskscript', `${kind}.sh`), 'utf8')
-            .replaceAll('@PACKAGE@', pins.package).replaceAll('@EXECUTOR_DIGEST@', pins.executorDigest).replaceAll('@POLICY_DIGEST@', pins.policyDigest);
+            .replaceAll('@PACKAGE@', pins.package).replaceAll('@POLICY_DIGEST@', pins.policyDigest);
         return { kind, name: `${pins.package} executor ${kind}`, header: `#!/bin/sh\n# synopkgland executor ${kind}\n`, script: validateTaskScript(script, kind === 'boot' ? 1024 : 6000) };
     });
 }

package/dist/skill.js

@@ -7,6 +7,7 @@ const SKILL_CATALOG = [
     { id: "wrap", file: "reference/wrap.md", when: "已有 Compose 或要補契約" },
     { id: "identity", file: "reference/identity.md", when: "需要 DSM 登入者" },
     { id: "files", file: "reference/files.md", when: "需要 NAS 檔案" },
+    { id: "portal", file: "reference/portal.md", when: "需要 DSM Application Portal 別名連結" },
     { id: "ui-vue", file: "reference/ui-vue.md", when: "編寫／檢查 Vue UI" },
     { id: "ui-json", file: "reference/ui-json.md", when: "產生／檢查 JSON UI" },
     { id: "deploy", file: "reference/deploy.md", when: "要放到 NAS" },

package/dist/standalone/api-permissions.d.ts

@@ -14,5 +14,15 @@ export declare function readApiPermissions(backendDir: string, capabilities?: Ca
     digest: string;
     sdkDigest: string;
 };
+/**
+ * `entry: admin-only` makes administrators the floor of every route. App
+ * routes that would admit anyone else are returned as conflicts; SDK routes a
+ * capability added are raised, except the public login ceremony of
+ * `identity: standalone`, which admits no one by itself.
+ */
+export declare function floorAtAdministrators(policy: ApiPermissions): {
+    policy: ApiPermissions;
+    widened: string[];
+};
 /** Launcher access is derived from the same API policy; no second setting. */
 export declare function permitsOrdinaryUsers(policy?: ApiPermissions): boolean;

package/dist/standalone/api-permissions.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { templatesRoot } from "../template-paths.js";
 import { parseDocument } from "yaml";
 export const API_PERMISSIONS_FILE = "internal/api/permissions.json";
+const SDK_PERMISSIONS_TEMPLATE = "native-go/backend/internal/api/sdk-permissions.json";
 export const MAX_PERMISSIONS_BYTES = 65536;
 export const MAX_PERMISSION_METHODS = 1024;
 export function parseApiPermissions(raw) {
@@ -37,7 +38,7 @@ export function readApiPermissions(backendDir, capabilities = {}) {
         throw new Error("permissions must be a regular bounded JSON file");
     const raw = readFileSync(file);
     const policy = parseApiPermissions(raw);
-    const sdkRaw = readFileSync(join(templatesRoot(), 'native-go/backend/internal/api/sdk-permissions.json'));
+    const sdkRaw = readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE));
     const sdkFile = join(backendDir, 'internal/api/sdk-permissions.json');
     if (existsSync(sdkFile)) {
         const sdkStat = lstatSync(sdkFile);
@@ -45,7 +46,7 @@ export function readApiPermissions(backendDir, capabilities = {}) {
             throw new Error('SDK route policy differs from the CLI policy; restore the SDK-owned file');
         }
     }
-    const sdk = JSON.parse(sdkRaw.toString('utf8'));
+    const sdk = readSdkPermissions();
     for (const methods of Object.values(sdk))
         for (const method of Object.keys(methods)) {
             if (Object.hasOwn(policy.methods, method))
@@ -57,6 +58,22 @@ export function readApiPermissions(backendDir, capabilities = {}) {
     }
     return { policy, sdkDigest: createHash("sha256").update(sdkRaw).digest("hex"), digest: createHash("sha256").update(raw).digest("hex") };
 }
+/**
+ * `entry: admin-only` makes administrators the floor of every route. App
+ * routes that would admit anyone else are returned as conflicts; SDK routes a
+ * capability added are raised, except the public login ceremony of
+ * `identity: standalone`, which admits no one by itself.
+ */
+export function floorAtAdministrators(policy) {
+    const sdk = new Set(Object.values(readSdkPermissions()).flatMap(methods => Object.keys(methods)));
+    const methods = Object.fromEntries(Object.entries(policy.methods)
+        .map(([method, permission]) => [method, sdk.has(method) && permission === "public" ? permission : "administrators"]));
+    const widened = Object.entries(policy.methods).filter(([method, permission]) => !sdk.has(method) && permission !== "administrators").map(([method]) => method);
+    return { policy: { ...policy, methods }, widened };
+}
+function readSdkPermissions() {
+    return JSON.parse(readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE), 'utf8'));
+}
 /** Launcher access is derived from the same API policy; no second setting. */
 export function permitsOrdinaryUsers(policy) {
     return policy !== undefined && Object.values(policy.methods).some(permission => permission !== "administrators");

package/dist/standalone/background.d.ts

@@ -17,5 +17,21 @@ export declare function readBackground(value: unknown, fail: (error: StandaloneE
 /** `conf/resource`: only the official user-unit resource. */
 export declare function renderBackgroundResource(): string;
 export declare function renderBackgroundUnit(pkg: string): string;
+/** Shell function that stops the worker in lifecycle hooks; call it as `stop_background_worker`. */
+export declare function renderBackgroundWorkerStop(pkg: string): string;
+/**
+ * Shell function for `prestart`, which DSM runs before its systemd-user-unit
+ * acquire: call it as `recover_user_manager`.
+ *
+ * On a restart under load, pkgctl's `Requires=user@UID` can start the package
+ * user's new manager in the old runtime dir just before logind removes it.
+ * That manager stays active without its private socket, so every later
+ * synosystemctl call fails with "Failed to get D-Bus connection" until it
+ * exits. Stop only such a manager, as the package user; the acquire that
+ * follows then starts a fresh one.
+ */
+export declare function renderUserManagerRecovery(): string;
+/** Shell function that starts the worker and names the failed step; call it as `start_background_worker`. */
+export declare function renderBackgroundWorkerStart(pkg: string): string;
 /** Package Center's start/stop/status map straight onto the user unit. */
 export declare function renderBackgroundControl(pkg: string): string;