@synopackageland/cli 0.14.1 → 0.15.1

package/dist/ctl/descriptor.js

@@ -0,0 +1,93 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { canonicalize } from 'json-canonicalize';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { CtlError } from './errors.js';
+export const DESCRIPTION_METHOD = 'synopkgland.describe';
+export const DESCRIPTION_FILE = 'synopkgland-api.json';
+export const ajv = new Ajv2020.default({ allErrors: true, strict: false, validateFormats: false, addUsedSchema: false });
+const descriptorSchema = ajv.compile(JSON.parse(readFileSync(new URL('../../schema/synopkgland-api-v1.schema.json', import.meta.url), 'utf8')));
+export function makeDescriptor(payload) { const value = { format: 'synopkgland.api', version: 1, payload }; return { ...value, sha256: createHash('sha256').update(canonicalize(value)).digest('hex') }; }
+export function validateDescriptor(value, id, version) {
+    const fail = (message) => { throw new CtlError('CTL_DESCRIPTOR_INVALID', message, 'run: synopkgland ctl list --refresh', 5); };
+    if (!value || value.format !== 'synopkgland.api' || value.version !== 1 || !value.payload || !/^([0-9a-f]{64})$/.test(value.sha256))
+        return fail('Unsupported API description format.');
+    if (!descriptorSchema(value))
+        return fail('API description schema validation failed.');
+    const p = value.payload;
+    if (p.package?.id !== id || p.package?.version !== version)
+        return fail('API description does not match installed package identity/version.');
+    if (typeof p.package.displayName !== 'string' || !Array.isArray(p.aliases) || p.aliases.some((a) => typeof a !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/i.test(a)))
+        return fail('Invalid App aliases.');
+    if (!['dsm-session', 'dsm-app-session'].includes(p.transport?.auth) || p.transport?.path !== `/webman/3rdparty/${id}/cgi/api.cgi`)
+        return fail('API endpoint must be the fixed CGI of its own package.');
+    if (!['admin-only', 'app-privilege', 'policy'].includes(p.entry) || !['synopkgland', 'third-party', 'unknown'].includes(p.provenance?.developedBy) || typeof p.provenance?.generator !== 'string')
+        return fail('Invalid API metadata.');
+    if (!p.commands || Array.isArray(p.commands) || typeof p.commands !== 'object' || Object.keys(p.commands).length < 1 || Object.keys(p.commands).length > 1024)
+        return fail('Invalid command allowlist.');
+    if (!p.bindings || typeof p.bindings !== 'object')
+        return fail('Missing internal method bindings.');
+    const paths = new Set();
+    for (const [method, raw] of Object.entries(p.commands)) {
+        const op = raw;
+        if (method.length > 128 || !/^([a-z][a-z0-9_]*\.)+[a-z][a-z0-9_]*$/.test(method) || !op || typeof op.summary !== 'string' || !['read', 'write', 'destructive'].includes(op.effect) || !['public', 'authenticated', 'administrators'].includes(op.permission) || !Array.isArray(op.cli) || !op.cli.length || op.cli.some(s => typeof s !== 'string' || !/^[a-z][a-z0-9-]*$/.test(s)))
+            return fail('Invalid command metadata.');
+        try {
+            validateFlow(op, p.bindings);
+        }
+        catch {
+            return fail('Invalid command flow or method bindings.');
+        }
+        const path = op.cli.join(' ');
+        if (paths.has(path))
+            return fail('Duplicate CLI command path.');
+        paths.add(path);
+        for (const schema of [op.paramsSchema, op.resultSchema])
+            if (schema) {
+                try {
+                    safeSchema(schema);
+                    ajv.compile(schema);
+                }
+                catch {
+                    return fail('Invalid or unsafe parameter/result schema.');
+                }
+            }
+    }
+    if (p.transport.auth === 'dsm-app-session' && (!p.bindings?.['identity.session'] || !p.bindings?.['identity.logout']))
+        return fail('Standalone session helpers must be allowlisted.');
+    if (makeDescriptor(p).sha256 !== value.sha256)
+        return fail('API description hash mismatch.');
+    return value;
+}
+export function safeSchema(schema, depth = 0) {
+    if (depth > 32)
+        throw Error('schema too deep');
+    if (schema && typeof schema === 'object')
+        for (const [key, value] of Object.entries(schema)) {
+            if ((key === '$ref' || key === '$dynamicRef') && (typeof value !== 'string' || !value.startsWith('#')))
+                throw Error('external schema reference');
+            if (key === '$schema' && value !== 'https://json-schema.org/draft/2020-12/schema')
+                throw Error('schema dialect');
+            safeSchema(value, depth + 1);
+        }
+}
+export function flowMethods(flow) { return flow.type === 'job' ? [flow.start, flow.poll, ...(flow.result ? [flow.result] : [])] : [flow.method]; }
+export function validateFlow(op, bindings) {
+    const flow = op.flow;
+    if (!flow || !['invoke', 'job', 'paginate', 'ndjson', 'upload'].includes(flow.type))
+        throw Error('unsupported flow');
+    const effects = { read: 0, write: 1, destructive: 2 };
+    for (const name of flowMethods(flow)) {
+        const b = bindings[name];
+        if (!b || !['public', 'authenticated', 'administrators'].includes(b.permission) || effects[op.effect] < effects[b.effect])
+            throw Error('binding/effect');
+    }
+    if (flow.type === 'job') {
+        if (!flow.jobId || !flow.idParam || !flow.state || !Array.isArray(flow.done) || !flow.done.length || !Array.isArray(flow.failed) || !Number.isInteger(flow.intervalMs) || flow.intervalMs < 10 || flow.intervalMs > 60000 || !Number.isInteger(flow.timeoutMs) || flow.timeoutMs < flow.intervalMs || flow.timeoutMs > 3600000 || bindings[flow.poll].effect !== 'read' || flow.result && bindings[flow.result].effect !== 'read')
+            throw Error('job contract');
+    }
+    if (flow.type === 'paginate' && (!flow.items || !flow.offsetParam || !flow.limitParam || !Number.isInteger(flow.pageSize) || flow.pageSize < 1 || flow.pageSize > 1000 || !Number.isInteger(flow.maxPages) || flow.maxPages < 1 || flow.maxPages > 1000 || op.effect !== 'read'))
+        throw Error('pagination contract');
+    if (flow.type === 'upload' && (op.effect === 'read' || ![flow.fileParam, flow.parentParam, flow.nameParam].every(Boolean)))
+        throw Error('upload contract');
+}

package/dist/ctl/dsm-auth.d.ts

@@ -0,0 +1,10 @@
+import { type DsmSession, type JsonRequest } from './transport.js';
+export interface LoginOptions {
+    remember?: boolean;
+    deviceId?: string;
+    otp: () => Promise<string>;
+    request?: JsonRequest;
+    ca?: string;
+}
+export declare function loginDsm(origin: string, username: string, password: string, options: LoginOptions): Promise<DsmSession>;
+export declare function logoutDsm(session: DsmSession, request?: JsonRequest): Promise<void>;

package/dist/ctl/dsm-auth.js

@@ -0,0 +1,30 @@
+import { CtlError } from './errors.js';
+import { createRequest } from './transport.js';
+export async function loginDsm(origin, username, password, options) {
+    const request = options.request ?? createRequest(origin, 30000, options.ca);
+    const form = new URLSearchParams({ api: 'SYNO.API.Auth', version: '7', method: 'login', account: username, passwd: password, session: 'DSM', format: 'cookie', enable_syno_token: 'yes', enable_device_token: options.remember === false ? 'no' : 'yes', device_name: 'synopkgland', device_id: options.deviceId ?? '' });
+    let result = await request('/webapi/entry.cgi', form);
+    if (result?.error?.code === 402) {
+        form.delete('session');
+        result = await request('/webapi/entry.cgi', form);
+    }
+    if (result?.error?.code === 403) {
+        const otp = await options.otp();
+        if (!/^\d{6}$/.test(otp))
+            throw new CtlError('CTL_OTP_INVALID', 'OTP must be six digits.', 'run: synopkgland ctl host login <name>', 2);
+        form.set('otp_code', otp);
+        result = await request('/webapi/entry.cgi', form);
+    }
+    if (result?.success !== true || typeof result.data?.sid !== 'string' || !result.data.sid || typeof result.data.synotoken !== 'string' || !result.data.synotoken)
+        throw new CtlError('CTL_AUTH_FAILED', `DSM login failed (${Number(result?.error?.code) || 'invalid response'}).`, 'run: synopkgland ctl host login <name>', 2);
+    if (/[;\r\n\x00]/.test(result.data.sid) || /[\r\n\x00]/.test(result.data.synotoken) || result.data.sid.length > 4096 || result.data.synotoken.length > 4096)
+        throw new CtlError('CTL_AUTH_FAILED', 'DSM returned invalid session carriers.', 'Check the DSM endpoint.', 2);
+    const returnedDevice = result.data.device_id || result.data.did || options.deviceId;
+    const deviceId = options.remember === false ? undefined : typeof returnedDevice === 'string' && returnedDevice.length <= 4096 && !/[\r\n\x00]/.test(returnedDevice) ? returnedDevice : undefined;
+    return { origin, username, cookie: `id=${result.data.sid}`, token: result.data.synotoken, ...(deviceId ? { deviceId } : {}) };
+}
+export async function logoutDsm(session, request = createRequest(session.origin)) {
+    const body = await request('/webapi/entry.cgi', new URLSearchParams({ api: 'SYNO.API.Auth', version: '7', method: 'logout', SynoToken: session.token }), session);
+    if (body?.success !== true)
+        throw new CtlError('CTL_LOGOUT_FAILED', 'DSM did not confirm logout.', 'Retry logout or revoke the NAS session.', 2);
+}

package/dist/ctl/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class CtlError extends Error {
+    code: string;
+    hint: string;
+    exitCode: number;
+    allowed?: string[] | undefined;
+    plan?: unknown | undefined;
+    constructor(code: string, message: string, hint: string, exitCode?: number, allowed?: string[] | undefined, plan?: unknown | undefined);
+}
+export declare function ctlError(error: unknown): CtlError;
+export declare function errorData(error: unknown): {
+    plan?: {} | undefined;
+    allowed?: string[] | undefined;
+    code: string;
+    message: string;
+    hint: string;
+};
+export declare function choose(value: string, allowed: string[], what: string): never;

package/dist/ctl/errors.js

@@ -0,0 +1,32 @@
+export class CtlError extends Error {
+    code;
+    hint;
+    exitCode;
+    allowed;
+    plan;
+    constructor(code, message, hint, exitCode = 3, allowed, plan) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+        this.allowed = allowed;
+        this.plan = plan;
+    }
+}
+export function ctlError(error) {
+    return error instanceof CtlError ? error : new CtlError('CTL_INTERNAL', 'Operation failed.', 'run: synopkgland ctl --help', 1);
+}
+export function errorData(error) {
+    const e = ctlError(error);
+    return { code: e.code, message: e.message, hint: e.hint, ...(e.allowed ? { allowed: e.allowed } : {}), ...(e.plan ? { plan: e.plan } : {}) };
+}
+export function choose(value, allowed, what) {
+    const distance = (a, b) => { let row = Array.from({ length: b.length + 1 }, (_, i) => i); for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min(next[j - 1] + 1, row[j] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        row = next;
+    } return row[b.length]; };
+    const nearest = [...allowed].sort((a, b) => distance(value.toLowerCase(), a.toLowerCase()) - distance(value.toLowerCase(), b.toLowerCase()))[0];
+    throw new CtlError(`CTL_${what.toUpperCase()}_UNKNOWN`, `Unknown ${what}: ${value}.${nearest ? ` Did you mean ${nearest}?` : ''}`, nearest ? `run: synopkgland ctl ${what === 'host' ? `host show ${nearest}` : 'list --json'}` : 'run: synopkgland ctl host add <name> --url https://<nas>:5001', 3, allowed);
+}

package/dist/ctl/flows.d.ts

@@ -0,0 +1,11 @@
+import type { Flow } from './descriptor.js';
+export type Invoke = (method: string, params: Record<string, unknown>) => Promise<any>;
+export interface FlowOptions {
+    wait?: boolean;
+    timeoutMs?: number;
+    upload?: (method: string, params: Record<string, unknown>, flow: Extract<Flow, {
+        type: 'upload';
+    }>) => Promise<unknown>;
+    ndjson?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+}
+export declare function runFlow(flow: Flow, params: Record<string, unknown>, invoke: Invoke, options: FlowOptions): Promise<any>;

package/dist/ctl/flows.js

@@ -0,0 +1,52 @@
+import { CtlError } from './errors.js';
+function field(value, path) { for (const key of path.split('.')) {
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, key))
+        return undefined;
+    value = value[key];
+} return value; }
+export async function runFlow(flow, params, invoke, options) {
+    if (flow.type === 'invoke')
+        return invoke(flow.method, params);
+    if (flow.type === 'upload') {
+        if (!options.upload)
+            throw new CtlError('CTL_FLOW_UNSUPPORTED', 'Upload transport unavailable.', 'Use a compatible CLI.', 5);
+        return options.upload(flow.method, params, flow);
+    }
+    if (flow.type === 'ndjson') {
+        if (!options.ndjson)
+            throw new CtlError('CTL_FLOW_UNSUPPORTED', 'NDJSON transport unavailable.', 'Use a compatible CLI.', 5);
+        return options.ndjson(flow.method, params);
+    }
+    if (flow.type === 'paginate') {
+        const items = [];
+        for (let page = 0; page < flow.maxPages; page++) {
+            const response = await invoke(flow.method, { ...params, [flow.offsetParam]: page * flow.pageSize, [flow.limitParam]: flow.pageSize });
+            const rows = field(response, flow.items);
+            if (!Array.isArray(rows))
+                throw new CtlError('CTL_FLOW_RESPONSE', 'Pagination result has no items array.', 'Check command metadata.', 5);
+            if (items.length + rows.length > 100000)
+                throw new CtlError('CTL_FLOW_LIMIT', 'Pagination item limit exceeded.', 'Narrow the query.', 5);
+            items.push(...rows);
+            if (rows.length < flow.pageSize)
+                return { items };
+        }
+        throw new CtlError('CTL_FLOW_LIMIT', 'Pagination page limit reached; result is incomplete.', 'Narrow the query.', 5);
+    }
+    const accepted = await invoke(flow.start, params);
+    if (options.wait === false)
+        return { accepted: true, job: accepted };
+    const id = field(accepted, flow.jobId);
+    if (!['string', 'number'].includes(typeof id))
+        throw new CtlError('CTL_FLOW_RESPONSE', 'Start response has no job ID.', 'Check command metadata; start is not retried.', 5);
+    const until = performance.now() + Math.min(options.timeoutMs ?? flow.timeoutMs, 3600000);
+    while (performance.now() < until) {
+        const poll = await invoke(flow.poll, { [flow.idParam]: id });
+        const state = field(poll, flow.state);
+        if (flow.failed.includes(state))
+            throw new CtlError('CTL_JOB_FAILED', `Job ${id} failed (${state}).`, 'Inspect the job in the App; start was not retried.', 5);
+        if (flow.done.includes(state))
+            return flow.result ? invoke(flow.result, { [flow.idParam]: id }) : poll;
+        await new Promise(resolve => setTimeout(resolve, Math.min(flow.intervalMs, Math.max(0, until - performance.now()))));
+    }
+    throw new CtlError('CTL_JOB_TIMEOUT', `Wait timed out; job ${id} may still be running.`, 'Query the job status; do not repeat the start blindly.', 6);
+}

package/dist/ctl/input.d.ts

@@ -0,0 +1,20 @@
+import { type Descriptor, type Operation } from './descriptor.js';
+export declare function selectHosts(names: string[], selected?: string, all?: boolean): string[];
+export declare function selectApp(apps: Descriptor[], name: string): Descriptor;
+export declare function selectOperation(app: Descriptor, path: string[]): {
+    id: string;
+    operation: Operation;
+};
+export declare const RESERVED_FLAGS: Set<string>;
+export declare function flagName(key: string): string;
+export declare function operationInput(op: Operation, args: string[], stdin?: string, helpHint?: string): Record<string, unknown>;
+export declare function requestPlan(app: Descriptor, id: string, params: Record<string, unknown>): {
+    package: string;
+    version: string;
+    path: string;
+    command: string;
+    flow: import("./descriptor.js").Flow;
+    params: Record<string, unknown>;
+    effect: "read" | "write" | "destructive";
+};
+export declare function confirmOperation(op: Operation, yes: boolean, dryRun: boolean, plan: unknown): void;

package/dist/ctl/input.js

@@ -0,0 +1,128 @@
+import { readBounded, strictJson } from './json.js';
+import { ajv } from './descriptor.js';
+import { CtlError, choose } from './errors.js';
+import { redactValue } from './redaction.js';
+export function selectHosts(names, selected, all = false) {
+    if (selected && all)
+        throw new CtlError('CTL_ARGUMENT_INVALID', 'Use --host or --all-hosts, not both.', 'run: synopkgland ctl host list');
+    if (!names.length)
+        throw new CtlError('CTL_NOT_AUTHENTICATED', 'No hosts registered.', 'run: synopkgland ctl host add <name> --url https://<nas>:5001', 2);
+    if (all)
+        return names;
+    if (!selected) {
+        if (names.length === 1)
+            return names;
+        throw new CtlError('CTL_HOST_REQUIRED', 'Choose explicit hosts; no current context is stored.', `run: synopkgland ctl list --host ${names[0]}`, 3, names);
+    }
+    const hosts = selected.split(',');
+    for (const name of hosts)
+        if (!names.includes(name))
+            choose(name, names, 'host');
+    return [...new Set(hosts)];
+}
+export function selectApp(apps, name) {
+    const found = apps.filter(a => [a.payload.package.id, ...a.payload.aliases].some(s => s.toLowerCase() === name.toLowerCase()));
+    if (found.length > 1)
+        throw new CtlError('CTL_APP_AMBIGUOUS', 'Alias matches multiple packages.', 'Use an exact DSM package ID.', 3, found.map(a => a.payload.package.id));
+    if (found.length === 1)
+        return found[0];
+    return choose(name, apps.flatMap(a => [a.payload.package.id, ...a.payload.aliases]), 'app');
+}
+export function selectOperation(app, path) {
+    const found = Object.entries(app.payload.commands).find(([, op]) => op.cli.join(' ') === path.join(' '));
+    if (found)
+        return { id: found[0], operation: found[1] };
+    return choose(path.join(' '), Object.values(app.payload.commands).map(op => op.cli.join(' ')), 'command');
+}
+export const RESERVED_FLAGS = new Set(['host', 'all-hosts', 'json', 'app', 'refresh', 'yes', 'dry-run', 'approve-installed', 'help', 'input', 'wait', 'no-wait', 'timeout']);
+export function flagName(key) { return key.replace(/[A-Z]/g, c => '-' + c.toLowerCase()).replaceAll('_', '-'); }
+export function operationInput(op, args, stdin, helpHint) {
+    const fail = (message, allowed) => { throw new CtlError('CTL_PARAMS_INVALID', message, helpHint ?? ('run: synopkgland ctl <package> ' + op.cli.join(' ') + ' --help'), 3, allowed); };
+    const inputIndex = args.indexOf('--input');
+    let params = {};
+    if (inputIndex >= 0) {
+        if (args.length !== 2 || inputIndex !== 0 || !args[1])
+            return fail('Use --input <file|-> alone for complex parameters.');
+        let raw;
+        try {
+            raw = args[1] === '-' ? (stdin ?? readBounded(0)) : readBounded(args[1]);
+        }
+        catch {
+            return fail('Cannot read parameter input.');
+        }
+        if (Buffer.byteLength(raw) > 1048576)
+            return fail('Parameter input exceeds 1 MiB.');
+        try {
+            params = strictJson(raw);
+        }
+        catch {
+            return fail('Parameter input is not valid JSON.');
+        }
+    }
+    else {
+        if (!op.paramsSchema)
+            return fail('Undescribed parameters: use --input <file> or --input -.');
+        const properties = op.paramsSchema.properties ?? {};
+        if (Object.keys(properties).some(key => RESERVED_FLAGS.has(flagName(key))))
+            return fail('Parameter names conflict with CLI control flags: use --input.');
+        const fields = new Map();
+        for (const [key, schema] of Object.entries(properties)) {
+            const flag = '--' + flagName(key);
+            if (fields.has(flag))
+                return fail('Parameter names collide as CLI flags; use --input.');
+            fields.set(flag, [key, schema]);
+        }
+        for (let i = 0; i < args.length; i++) {
+            const split = args[i].indexOf('=');
+            const flag = split > 0 ? args[i].slice(0, split) : args[i];
+            const field = fields.get(flag);
+            if (!field)
+                return fail('Unknown parameter flag.', [...fields.keys()]);
+            const [key, schema] = field;
+            if (Object.hasOwn(params, key))
+                return fail(`Duplicate parameter flag ${flag}.`);
+            if (!['string', 'integer', 'number', 'boolean'].includes(schema.type))
+                return fail(`Complex parameter ${flag}: use --input.`);
+            let value = split > 0 ? args[i].slice(split + 1) : undefined;
+            if (value === undefined && schema.type === 'boolean' && (!args[i + 1] || args[i + 1].startsWith('--')))
+                value = 'true';
+            else if (value === undefined)
+                value = args[++i];
+            if (value === undefined)
+                return fail(`Missing parameter value for ${flag}.`);
+            if (schema.type === 'integer') {
+                if (!/^-?\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+                    return fail(`Parameter ${flag} must be a safe integer.`);
+                params[key] = Number(value);
+            }
+            else if (schema.type === 'number') {
+                if (!value.trim() || !Number.isFinite(Number(value)))
+                    return fail(`Parameter ${flag} must be a number.`);
+                params[key] = Number(value);
+            }
+            else if (schema.type === 'boolean') {
+                if (!['true', 'false'].includes(value))
+                    return fail(`Parameter ${flag} must be true or false.`);
+                params[key] = value === 'true';
+            }
+            else
+                params[key] = value;
+        }
+    }
+    if (!params || Array.isArray(params) || typeof params !== 'object')
+        return fail('Parameters must be a JSON object.');
+    if (op.paramsSchema) {
+        for (const [key, schema] of Object.entries(op.paramsSchema.properties ?? {}))
+            if (!Object.hasOwn(params, key) && Object.hasOwn(schema, 'default'))
+                params[key] = structuredClone(schema.default);
+        const validator = ajv.compile(op.paramsSchema);
+        if (!validator(params))
+            return fail('Invalid parameters: values do not match the command schema.');
+    }
+    return params;
+}
+export function requestPlan(app, id, params) { return { package: app.payload.package.id, version: app.payload.package.version, path: app.payload.transport.path, command: id, flow: app.payload.commands[id].flow, params: redactValue(params, app.payload.commands[id].paramsSchema), effect: app.payload.commands[id].effect }; }
+export function confirmOperation(op, yes, dryRun, plan) {
+    if (!dryRun && op.effect !== 'read' && !yes)
+        throw new CtlError('CTL_CONFIRM_REQUIRED', 'State-changing operation requires --yes.', 'Inspect with --dry-run, then repeat the same command with --yes.', 7, undefined, plan);
+}

package/dist/ctl/json.d.ts

@@ -0,0 +1,2 @@
+export declare function strictJson(raw: Uint8Array | string): any;
+export declare function readBounded(file: string | number, limit?: number): string;

package/dist/ctl/json.js

@@ -0,0 +1,38 @@
+import { openSync, closeSync, readSync } from 'node:fs';
+import { parseDocument } from 'yaml';
+export function strictJson(raw) {
+    const text = typeof raw === 'string' ? raw : new TextDecoder('utf-8', { fatal: true }).decode(raw);
+    const value = JSON.parse(text);
+    if (parseDocument(text, { uniqueKeys: true }).errors.length)
+        throw Error('Duplicate JSON properties');
+    const check = (v, depth) => { if (depth > 32)
+        throw Error('JSON too deep'); if (typeof v === 'number' && !Number.isFinite(v))
+        throw Error('Invalid number'); if (typeof v === 'string' && /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v))
+        throw Error('Invalid Unicode'); if (v && typeof v === 'object')
+        for (const x of Object.values(v))
+            check(x, depth + 1); };
+    check(value, 0);
+    return value;
+}
+export function readBounded(file, limit = 1048576) {
+    const fd = typeof file === 'number' ? file : openSync(file, 'r');
+    const chunks = [];
+    let count = 0;
+    try {
+        while (count <= limit) {
+            const chunk = Buffer.alloc(Math.min(65536, limit + 1 - count));
+            const read = readSync(fd, chunk, 0, chunk.length, null);
+            if (!read)
+                break;
+            count += read;
+            if (count > limit)
+                throw Error('Input too large');
+            chunks.push(chunk.subarray(0, read));
+        }
+        return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    finally {
+        if (typeof file !== 'number')
+            closeSync(fd);
+    }
+}

package/dist/ctl/redaction.d.ts

@@ -0,0 +1,15 @@
+import type { Descriptor, Operation } from './descriptor.js';
+import { CtlError } from './errors.js';
+type Schema = Record<string, any> | boolean | undefined;
+export declare const REDACTED = "<redacted>";
+export declare function redactValue<T>(value: T, schema: Schema, root?: Schema, onSecret?: (value: unknown) => void): T;
+export declare function publicOperation(operation: Operation): Operation;
+export declare function publicDescriptor(description: Descriptor): Descriptor;
+export declare class SensitiveOutput {
+    private readonly secrets;
+    constructor(params: unknown, schema: Schema);
+    private remember;
+    clean<T>(value: T, schema?: Schema): T;
+    error(error: unknown): CtlError;
+}
+export {};