@synopackageland/templates 0.9.8 → 0.10.0

package/templates/native-node/backend/src/routes.ts

@@ -0,0 +1,97 @@
+// The App's methods. Register a method in build() and give it a rule in
+// app/permissions.json unless only administrators may call it: the runtime
+// has checked the DSM session, the entry gate and that rule before a handler
+// runs.
+import { randomUUID } from 'node:crypto'
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { App, AppError, type Context } from '@synopackageland/app'
+import * as delegate from './delegate.js'
+import * as jobs from './jobs.js'
+import { strings } from './params.js'
+import * as rootOps from './root-ops.js'
+
+/** Where the App's state lives; the runtime sets the environment. */
+export interface Config {
+  packageId: string
+  /** The package's own data directory (/var/packages/<package>/var), kept across upgrades. */
+  dataDir: string
+  packagesRoot: string
+}
+
+export function configFromEnv(): Config {
+  const env = process.env
+  return { packageId: env.SYNOPKGLAND_PACKAGE ?? '', dataDir: env.SYNOPKGLAND_DATA_DIR ?? '', packagesRoot: '/var/packages' }
+}
+
+export function build(cfg: Config): App {
+  const app = new App()
+  app.method('app.status', (ctx) => status(cfg, ctx))
+  app.method('greeting.get', () => getGreeting(cfg))
+  app.method('greeting.set', (ctx, params) => setGreeting(cfg, ctx, params))
+  // Each capability module is a stub until `synopkgland init --with` adds its example.
+  for (const capability of [jobs, rootOps, delegate]) capability.register(app, cfg)
+  return app
+}
+
+async function status(cfg: Config, ctx: Context) {
+  const result: Record<string, unknown> = {
+    package: cfg.packageId,
+    version: installedVersion(cfg),
+    user: ctx.user,
+    admin: ctx.admin,
+    process: { uid: process.getuid!(), gid: process.getgid!() },
+    language: `Node.js ${process.versions.node}`,
+    platform: `${process.platform}/${process.arch}`,
+    time: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+  }
+  try {
+    // Served only when dsm-package.yaml declares a portal.
+    result.portal = await ctx.runtime('portal.status')
+  } catch {
+    // No portal.
+  }
+  return result
+}
+
+/** The version in the package's INFO, or "" outside DSM. */
+function installedVersion(cfg: Config): string {
+  try {
+    const info = readFileSync(join(cfg.packagesRoot, cfg.packageId, 'INFO'), 'utf8')
+    return /^version="?([^"\n]*)"?$/m.exec(info)?.[1] ?? ''
+  } catch {
+    return ''
+  }
+}
+
+const greetingPath = (cfg: Config) => join(cfg.dataDir, 'greeting.json')
+
+function getGreeting(cfg: Config): unknown {
+  try {
+    return JSON.parse(readFileSync(greetingPath(cfg), 'utf8'))
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return { text: 'Hello' }
+    throw e
+  }
+}
+
+function setGreeting(cfg: Config, ctx: Context, params: unknown) {
+  const { text } = strings(params, 'text')
+  const length = [...text].length
+  if (length < 1 || length > 200) throw AppError.badRequest('text must be 1 to 200 characters')
+  const greeting = { text, updated_by: ctx.user }
+  writeFileAtomic(greetingPath(cfg), JSON.stringify(greeting))
+  return greeting
+}
+
+/** Replaces path in one rename, so readers never see half a file. */
+export function writeFileAtomic(path: string, data: string): void {
+  const tmp = join(dirname(path), `.tmp-${randomUUID()}`)
+  try {
+    writeFileSync(tmp, data, { flag: 'wx' })
+    renameSync(tmp, path)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* never written */ }
+    throw e
+  }
+}

package/templates/native-node/backend/src/service.ts

@@ -0,0 +1,22 @@
+// The runtime's services, with their refusals passed on to the browser.
+import { AppError, ServiceError, type Context } from '@synopackageland/app'
+
+/**
+ * ctx.runtime. A refusal the browser may see (limit_exceeded, read_failed,
+ * SCOPE_DENIED, ...) reaches it as the App's own error; any other code, such
+ * as the runtime's session_required, stays internal.
+ */
+export async function service<T>(ctx: Context, op: string, params: unknown = null): Promise<T> {
+  try {
+    return (await ctx.runtime(op, params)) as T
+  } catch (e) {
+    if (!(e instanceof ServiceError)) throw e
+    let passed: AppError
+    try {
+      passed = new AppError(e.code, e.message)
+    } catch {
+      throw e
+    }
+    throw passed
+  }
+}

package/templates/native-node/backend/test/routes.test.ts

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { call } from './support.js'
+
+let root: string
+let cfg: Config
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: join(root, 'var'), packagesRoot: join(root, 'packages') }
+  mkdirSync(cfg.dataDir)
+})
+afterEach(() => rmSync(root, { recursive: true, force: true }))
+
+function writeInfo(text: string) {
+  mkdirSync(join(cfg.packagesRoot, 'ExampleApp'), { recursive: true })
+  writeFileSync(join(cfg.packagesRoot, 'ExampleApp', 'INFO'), text)
+}
+
+test('app.status reports the caller and the installed version', async () => {
+  writeInfo('package="ExampleApp"\nversion="0.1.0-0001"\n')
+  const reply = await call(build(cfg), 'app.status', null, { user: 'alice', admin: false })
+  assert.equal(reply.ok, true, JSON.stringify(reply.error))
+  const status = reply.data
+  assert.deepEqual([status.package, status.version, status.user, status.admin], ['ExampleApp', '0.1.0-0001', 'alice', false])
+  assert.deepEqual(status.process, { uid: process.getuid!(), gid: process.getgid!() })
+  assert.match(status.language, /^Node\.js \d+\./)
+  assert.match(status.platform, /^\w+\/\w+$/)
+  assert.match(status.time, /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/)
+})
+
+test('app.status without INFO has no version', async () => {
+  assert.equal((await call(build(cfg), 'app.status')).data.version, '')
+})
+
+test('app.status shows the portal when the runtime offers it', async () => {
+  const portal = { enabled: true, alias: 'example' }
+  const reply = await call(build(cfg), 'app.status', null, { services: { 'portal.status': () => portal } })
+  assert.deepEqual(reply.data.portal, portal)
+  assert.deepEqual(reply.services, [['portal.status', null]])
+})
+
+test('app.status without a portal leaves it out', async () => {
+  const reply = await call(build(cfg), 'app.status')
+  assert.equal(reply.ok, true, JSON.stringify(reply.error))
+  assert.equal('portal' in reply.data, false)
+})
+
+test('greeting.get defaults to Hello', async () => {
+  assert.deepEqual((await call(build(cfg), 'greeting.get')).data, { text: 'Hello' })
+})
+
+test('greeting.set stores the text and who set it', async () => {
+  const app = build(cfg)
+  const reply = await call(app, 'greeting.set', { text: 'Hi 👋' }, { user: 'alice' })
+  assert.deepEqual(reply.data, { text: 'Hi 👋', updated_by: 'alice' })
+  assert.deepEqual((await call(app, 'greeting.get')).data, { text: 'Hi 👋', updated_by: 'alice' })
+  assert.deepEqual(readdirSync(cfg.dataDir), ['greeting.json'])
+})
+
+test('greeting.set counts characters, not UTF-16 units', async () => {
+  assert.equal((await call(build(cfg), 'greeting.set', { text: '👋'.repeat(200) })).ok, true)
+})
+
+test('greeting.set refuses invalid params and keeps the old text', async () => {
+  for (const params of [null, [], {}, { text: '' }, { text: 'x'.repeat(201) }, { text: 5 }, { text: 'hi', extra: 1 }]) {
+    const reply = await call(build(cfg), 'greeting.set', params)
+    assert.equal(reply.error?.code, 'bad_request', JSON.stringify(params))
+  }
+  assert.deepEqual(readdirSync(cfg.dataDir), [])
+})

package/templates/native-node/backend/test/support.ts

@@ -0,0 +1,67 @@
+// Calls an App method the way the runtime does: over a channel, with the
+// hello, the call, the services the method asks for and its result.
+import { PassThrough } from 'node:stream'
+import { createInterface } from 'node:readline'
+import type { App } from '@synopackageland/app'
+
+/** A service's refusal: the runtime answers the svc with this code. */
+export class Refusal extends Error {
+  constructor(readonly code: string, message = code) {
+    super(message)
+  }
+}
+
+/** Each op the method may ask for: returns the result or throws a Refusal. An op it lacks is unknown_service. */
+export type Services = Record<string, (params: unknown) => unknown>
+
+export interface Reply {
+  ok: boolean
+  data?: any
+  error?: { code: string; message: string }
+  /** The services the method asked for, in order. */
+  services: [string, unknown][]
+}
+
+export interface Caller {
+  user?: string
+  admin?: boolean
+  services?: Services
+}
+
+export async function call(app: App, method: string, params: unknown = null, caller: Caller = {}): Promise<Reply> {
+  const { user = 'admin', admin = true, services = {} } = caller
+  const toApp = new PassThrough()
+  const fromApp = new PassThrough()
+  const serving = app.serve(toApp, fromApp)
+  const send = (frame: object) => toApp.write(JSON.stringify(frame) + '\n')
+  const lines = createInterface({ input: fromApp })[Symbol.asyncIterator]()
+  send({ t: 'hello', versions: [1] })
+  await lines.next()
+  const ctx = { user, admin, locale: 'en', request_id: '0'.repeat(32), deadline_ms: 30000 }
+  send({ t: 'call', id: '1', method, params, ctx })
+  const asked: [string, unknown][] = []
+  try {
+    for (let line = await lines.next(); !line.done; line = await lines.next()) {
+      const frame = JSON.parse(line.value)
+      if (frame.t === 'result') return { ok: frame.ok, data: frame.data, error: frame.error, services: asked }
+      asked.push([frame.op, frame.params])
+      send(await answer(services, frame))
+    }
+    throw new Error('the App ended the channel without a result')
+  } finally {
+    toApp.end()
+    await serving
+  }
+}
+
+async function answer(services: Services, frame: { id: string; op: string; params: unknown }): Promise<object> {
+  const reply = { t: 'svc_result', id: frame.id }
+  try {
+    const service = services[frame.op]
+    if (!service) throw new Refusal('unknown_service', `no service ${frame.op}`)
+    return { ...reply, ok: true, result: await service(frame.params) }
+  } catch (e) {
+    if (!(e instanceof Refusal)) throw e
+    return { ...reply, ok: false, error: { code: e.code, message: e.message } }
+  }
+}

package/templates/native-node/backend/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "app"
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/native-node/backend/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/templates/native-node/dsm-package.yaml

@@ -0,0 +1,80 @@
+# Standalone native DSM package: an unsigned SPK that runs as its own package
+# `synopkgland build` reads this file.
+schema: 2
+
+# INFO.package: letters and digits, starting with a letter. It also names the
+# DSM app (SYNO.SDS.<package>) and the CGI URL /webman/3rdparty/<package>/.
+package: __PACKAGE__
+version: 0.1.0
+# Increase for every SPK you hand out with the same version (INFO 0.1.0-0001).
+build: 1
+displayname: __DISPLAY_NAME__
+description: A native DSM package with a Node.js backend and a DSM window UI.
+# Package Center and DSM window icon: a square PNG of at least 256x256, or a
+# folder of icon_<size>.png. Omit to use the SDK default icon.
+# icon: assets/icon.png
+maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
+os_min_ver: "7.1-42661"
+
+# One SPK per architecture. Supported: x86_64, aarch64, armv7 (add it here to
+# build it; armv7 is built but not NAS-verified).
+arches: [x86_64, aarch64]
+
+# The SDK's Go runtime is the CGI: it checks the DSM session, the entry gate
+# and app/permissions.json, then runs `node main.js` in backend/app as the
+# package account, once per call, with Package Center's Node.js (node.package
+# becomes an install dependency). backend/src compiles to backend/app: run
+# `npm ci` and `npm run build` in backend before check and build. sdk is the
+# SDK release whose runtime and Node SDK (node_modules/@synopackageland/app)
+# the build ships; the build reads the methods from `main.js --describe`.
+backend:
+  runtime: node
+  dir: backend/app
+  entry: main.js
+  sdk: 0.10.0
+  node: { package: Node.js_v20 }
+
+ui:
+  # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css
+  # are required; anything else (images, chunks) is copied as is.
+  dir: ui
+
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English). build checks
+# that every language has the en.json keys and placeholders, and that the keys
+# listed in the glossary use DSM's own wording.
+i18n:
+  messages: i18n/messages
+  glossary: i18n/glossary.json
+  # Package Center text per language (INFO displayname_<lang>/description_<lang>).
+  # English comes from displayname/description above.
+  info:
+    zh-TW: { description: 以 Node.js 後端與 DSM 視窗介面打造的原生 DSM 套件。 }
+    zh-CN: { description: 以 Node.js 后端与 DSM 窗口界面构建的原生 DSM 套件。 }
+    ja: { description: Node.js バックエンドと DSM ウィンドウ UI を備えたネイティブ DSM パッケージ。 }
+    ko: { description: Node.js 백엔드와 DSM 창 UI를 갖춘 네이티브 DSM 패키지. }
+    de: { description: Ein natives DSM-Paket mit Node.js-Backend und DSM-Fenster-Oberfläche. }
+    fr: { description: Un paquet DSM natif avec un backend Node.js et une interface en fenêtre DSM. }
+    es: { description: Un paquete nativo de DSM con backend en Node.js e interfaz en ventana de DSM. }
+    it: { description: Un pacchetto DSM nativo con backend Node.js e interfaccia in una finestra DSM. }
+
+# Optional SDK capabilities; delegate/rootOps share administrator-approved executor setup.
+capabilities: {}

package/templates/native-node/gitignore

@@ -0,0 +1,4 @@
+dist/
+node_modules/
+backend/build/
+backend/app/*.js

package/templates/native-node-delegate/backend/src/delegate.ts

@@ -0,0 +1,35 @@
+// Saves to a user's destination: write a report and move it there.
+//
+// The browser picks the destination with the SDK's Background saves page and
+// sends its delegation ID; the executor checks that it is the caller's grant
+// and writes the file as the caller, never as root. A save that failed may be
+// repeated with the same job ID: the same file is sent again, and the executor
+// copies it at most once.
+import { mkdirSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { AppError, type App, type Context } from '@synopackageland/app'
+import { strings } from './params.js'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+const JOB_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/
+
+export function register(app: App, cfg: Config): void {
+  app.method('report.save', (ctx, params) => save(cfg, ctx, params))
+}
+
+function save(cfg: Config, ctx: Context, params: unknown) {
+  const { delegation_id, job_id } = strings(params, 'delegation_id', 'job_id')
+  if (!JOB_ID.test(job_id)) throw AppError.badRequest("job_id must be 1 to 128 letters, digits, '.', '_' or '-'")
+  const name = `report-${job_id}.txt`
+  // The runtime's delegate service moves files from here.
+  const staging = join(cfg.dataDir, 'executor-staging')
+  mkdirSync(staging, { recursive: true, mode: 0o700 })
+  const path = join(staging, name)
+  try {
+    writeFileSync(path, `Report for ${ctx.user}, ${new Date().toISOString().replace(/\.\d+Z$/, 'Z')}\n`, { flag: 'wx', mode: 0o600 })
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+  }
+  return service(ctx, 'delegate.move_from_staging', { delegation_id, job_id, staging: name, name, size: statSync(path).size })
+}

package/templates/native-node-delegate/backend/test/delegate.test.ts

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call, type Services } from './support.js'
+
+const SAVED = { state: 'queued' }
+let cfg: Config
+let staging: string
+
+beforeEach(() => {
+  const root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: root, packagesRoot: root }
+  staging = join(root, 'executor-staging')
+})
+afterEach(() => rmSync(cfg.dataDir, { recursive: true, force: true }))
+
+const save = (user = 'alice', move: Services[string] = () => SAVED) =>
+  call(build(cfg), 'report.save', { delegation_id: 'd1', job_id: 'job-1' }, { user, admin: false, services: { 'delegate.move_from_staging': move } })
+
+test('report.save moves a private report to the caller\'s destination', async () => {
+  const reply = await save()
+  assert.deepEqual(reply.data, SAVED)
+  const path = join(staging, 'report-job-1.txt')
+  assert.match(readFileSync(path, 'utf8'), /alice/)
+  assert.equal(statSync(path).mode & 0o777, 0o600)
+  const move = { delegation_id: 'd1', job_id: 'job-1', staging: 'report-job-1.txt', name: 'report-job-1.txt', size: statSync(path).size }
+  assert.deepEqual(reply.services, [['delegate.move_from_staging', move]])
+})
+
+test('a repeated report.save sends the same file again', async () => {
+  const first = (await save()).services
+  const report = readFileSync(join(staging, 'report-job-1.txt'), 'utf8')
+  assert.deepEqual((await save('bob')).services, first)
+  assert.equal(readFileSync(join(staging, 'report-job-1.txt'), 'utf8'), report)
+})
+
+test('report.save passes on the executor\'s refusal', async () => {
+  const reply = await save('alice', () => { throw new Refusal('DELEGATION_DENIED', 'The destination is no longer allowed.') })
+  assert.equal(reply.error?.code, 'DELEGATION_DENIED')
+})
+
+test('report.save refuses invalid params before writing', async () => {
+  for (const params of [null, { delegation_id: 'd1' }, { delegation_id: 'd1', job_id: '../x' }, { delegation_id: 'd1', job_id: '' }, { delegation_id: 1, job_id: 'j' }]) {
+    const reply = await call(build(cfg), 'report.save', params)
+    assert.deepEqual([reply.error?.code, reply.services], ['bad_request', []], JSON.stringify(params))
+  }
+  assert.equal(existsSync(staging), false)
+})

package/templates/native-node-jobs/backend/src/jobs.ts

@@ -0,0 +1,38 @@
+// Background jobs: hash a NAS file the caller may read.
+//
+// The SDK's worker runs each job as the package account: it hashes the job's
+// input (SHA-256) and keeps the result for the job's owner, the caller. The
+// runtime serves files.read with the caller's DSM session and bg.* for the
+// caller's own jobs only.
+import { copyFileSync, mkdirSync, unlinkSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { basename, join } from 'node:path'
+import { AppError, type App, type Context } from '@synopackageland/app'
+import { strings } from './params.js'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+/** A job's input is at most 512 KiB, copied into the job when it is submitted. */
+const MAX_INPUT = 512 * 1024
+
+export function register(app: App, cfg: Config): void {
+  app.method('hash.submit', (ctx, params) => submit(cfg, ctx, params))
+  app.method('hash.get', (ctx, params) => service(ctx, 'bg.get', strings(params, 'id')))
+  app.method('hash.cancel', (ctx, params) => service(ctx, 'bg.cancel', strings(params, 'id')))
+}
+
+async function submit(cfg: Config, ctx: Context, params: unknown) {
+  const { key, path } = strings(params, 'key', 'path')
+  const read = await service<{ path: string; size: number }>(ctx, 'files.read', { path })
+  if (read.size > MAX_INPUT) throw new AppError('limit_exceeded', 'The file is larger than allowed.')
+  // bg.submit takes its input from the data directory; the call's spool is elsewhere.
+  const inputs = join(cfg.dataDir, 'hash-inputs')
+  mkdirSync(inputs, { recursive: true, mode: 0o700 })
+  const input = join(inputs, randomUUID())
+  copyFileSync(read.path, input)
+  try {
+    return await service(ctx, 'bg.submit', { key, name: basename(path), input })
+  } finally {
+    unlinkSync(input)
+  }
+}

package/templates/native-node-jobs/backend/test/jobs.test.ts

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, sep } from 'node:path'
+import { afterEach, beforeEach, test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call } from './support.js'
+
+const JOB = { job: { id: 'j1', state: 'queued' }, duplicate: false }
+let root: string
+let cfg: Config
+let submitted: Record<string, unknown>[]
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: join(root, 'var'), packagesRoot: join(root, 'packages') }
+  mkdirSync(cfg.dataDir)
+  submitted = []
+})
+afterEach(() => rmSync(root, { recursive: true, force: true }))
+
+function spool(content: Buffer) {
+  const path = join(root, 'spool')
+  writeFileSync(path, content)
+  return { path, size: content.length }
+}
+
+// The runtime reads the input file while it answers bg.submit.
+function submit(params: unknown) {
+  const p = params as { input: string }
+  submitted.push({ ...p, content: readFileSync(p.input, 'utf8') })
+  return JOB
+}
+
+test('hash.submit hashes a copy of the caller\'s file', async () => {
+  const services = { 'files.read': () => spool(Buffer.from('hello')), 'bg.submit': submit }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/report.txt' }, { services })
+  assert.deepEqual(reply.data, JOB)
+  assert.deepEqual(reply.services.map(([op]) => op), ['files.read', 'bg.submit'])
+  assert.deepEqual(reply.services[0]![1], { path: '/home/report.txt' })
+  const [job] = submitted as [{ key: string; name: string; content: string; input: string }]
+  assert.deepEqual([job.key, job.name, job.content], ['k1', 'report.txt', 'hello'])
+  assert.ok(job.input.startsWith(cfg.dataDir + sep), job.input)
+  assert.equal(existsSync(job.input), false, 'the copy is removed once submitted')
+})
+
+test('hash.submit refuses a file over the job input limit', async () => {
+  const services = { 'files.read': () => spool(Buffer.alloc(512 * 1024 + 1)), 'bg.submit': submit }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/big.bin' }, { services })
+  assert.equal(reply.error?.code, 'limit_exceeded')
+  assert.deepEqual(submitted, [])
+})
+
+test('hash.submit passes on the runtime\'s refusal', async () => {
+  const services = { 'files.read': () => { throw new Refusal('read_failed', 'Unable to read the file.') } }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/a' }, { services })
+  assert.equal(reply.error?.code, 'read_failed')
+})
+
+test('hash.submit refuses invalid params before any service', async () => {
+  for (const params of [null, { key: 'k1' }, { key: 1, path: '/home/a' }, { key: 'k1', path: '/home/a', x: 1 }]) {
+    const reply = await call(build(cfg), 'hash.submit', params)
+    assert.deepEqual([reply.error?.code, reply.services], ['bad_request', []], JSON.stringify(params))
+  }
+})
+
+test('hash.get and hash.cancel act on the caller\'s job', async () => {
+  for (const [method, op] of [['hash.get', 'bg.get'], ['hash.cancel', 'bg.cancel']] as const) {
+    const reply = await call(build(cfg), method, { id: 'j1' }, { services: { [op]: () => JOB.job } })
+    assert.deepEqual([reply.data, reply.services], [JOB.job, [[op, { id: 'j1' }]]])
+    assert.equal((await call(build(cfg), method, {})).error?.code, 'bad_request')
+  }
+})

package/templates/native-node-root-ops/backend/src/root-ops.ts

@@ -0,0 +1,16 @@
+// Root operations: run root/whoami.sh as root.
+//
+// The executor runs only the root programs an administrator approved, and
+// checks the caller's DSM session and Application Privileges itself; the App
+// names the program and never runs anything as root.
+import { AppError, type App } from '@synopackageland/app'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+export function register(app: App, _cfg: Config): void {
+  app.method('whoami.run', (ctx, params) => {
+    const none = params === null || (typeof params === 'object' && !Array.isArray(params) && Object.keys(params).length === 0)
+    if (!none) throw AppError.badRequest('whoami.run takes no params')
+    return service(ctx, 'root.run', { name: 'whoami' })
+  })
+}

package/templates/native-node-root-ops/backend/test/root-ops.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call } from './support.js'
+
+const cfg: Config = { packageId: 'ExampleApp', dataDir: '/nonexistent', packagesRoot: '/nonexistent' }
+
+test('whoami.run runs the approved root program', async () => {
+  const output = { exit_code: 0, stdout: '0\n', stderr: '' }
+  for (const params of [null, {}]) {
+    const reply = await call(build(cfg), 'whoami.run', params, { services: { 'root.run': () => output } })
+    assert.deepEqual([reply.data, reply.services], [output, [['root.run', { name: 'whoami' }]]])
+  }
+})
+
+test('whoami.run passes on the executor\'s refusal', async () => {
+  const services = { 'root.run': () => { throw new Refusal('EXECUTOR_PAUSED', 'The executor is paused.') } }
+  assert.equal((await call(build(cfg), 'whoami.run', {}, { services })).error?.code, 'EXECUTOR_PAUSED')
+})
+
+test('whoami.run takes no params', async () => {
+  assert.equal((await call(build(cfg), 'whoami.run', { name: 'other' })).error?.code, 'bad_request')
+})