@knowttl/technitium-axi 0.0.0-stage → 0.1.1

package/dist/archive-contract.js

@@ -0,0 +1,58 @@
+import { ToolError } from './errors.js';
+// Entry names and selection rules reviewed against the pinned vendor handlers.
+export const archiveContract = {
+    sourceRevision: '0dd592aad21eced4221a9a46204cb1a299972ca0',
+    sources: {
+        'DnsWebService.cs': '1e2f492baa3113d09704589bf0109fd4c9bbc05f65204918d0d485ba8ae5753e',
+        'WebServiceClusterApi.cs': '2bb0efaa14335f9bfa74844db917021a2d2869604d1531b2e85e3105cad1e6d5',
+        'Cluster/ClusterManager.cs': '787086de7f3a2b625e788042d4f8ef2aa8d6ef27c9d235be2ffc94922d4ff496',
+    },
+    backup: {
+        authConfig: ['auth.config'], clusterConfig: ['cluster.config'],
+        webServiceSettings: ['webservice.config', '<certificate-relative-path-within-config>'],
+        dnsSettings: ['dns.config', '<certificate-relative-path-within-config>'],
+        logSettings: ['log.config'], zones: ['zones/*.zone'], allowedZones: ['allowed.config'],
+        blockedZones: ['blocked.config'], blockLists: ['blocklist.config', 'blocklists/*'],
+        apps: ['apps/**/*'], scopes: ['scopes/*.scope'], stats: ['stats/*.stat', 'stats/*.dstat'], logs: ['logs/*.log'],
+    },
+    transfer: {
+        changedFiles: ['auth.config', 'dns.config', 'allowed.config', 'blocked.config', 'blocklist.config'],
+        excludedComponents: ['clusterConfig', 'webServiceSettings', 'logSettings', 'scopes', 'stats', 'logs'],
+        excludedEntries: ['zones/*.zone', 'blocklists/*', '<certificate-relative-path-within-config>'],
+        comparison: 'file mtime > If-Modified-Since; DNSSEC key StateChangedOn > If-Modified-Since',
+        keys: 'zones/<zone-name>.keys: signed Primary members of the cluster catalog; includeZones forces eligible selected names, changed unselected keys remain eligible',
+        appEntries: { unchanged: 'apps/<name>/.exists', package: 'apps/<name>/<name>.zip', config: 'apps/<name>/dnsApp.config' },
+        appMarker: 'Emit zero-byte .exists only when neither package nor config is newer; empty and key-only worlds have no app directories',
+        response: { status: 200, contentType: 'application/zip', lastModified: 'RFC 1123 GMT response time', emptyZip: 'valid protected result' },
+    },
+};
+export function validateUploadArchive(bytes) {
+    const invalid = () => { throw new ToolError('UPLOAD_INVALID', 'Upload must be a bounded ZIP with safe relative entry names and no links', 'Select a valid app package or settings backup'); };
+    if (bytes.length < 22)
+        invalid();
+    let end = bytes.length - 22;
+    const minimum = Math.max(0, end - 65535);
+    while (end >= minimum && bytes.readUInt32LE(end) !== 0x06054b50)
+        end--;
+    if (end < minimum || end + 22 + bytes.readUInt16LE(end + 20) !== bytes.length || bytes.readUInt16LE(end + 4) !== 0 || bytes.readUInt16LE(end + 6) !== 0)
+        invalid();
+    const count = bytes.readUInt16LE(end + 10);
+    let offset = bytes.readUInt32LE(end + 16);
+    const centralEnd = offset + bytes.readUInt32LE(end + 12);
+    if (count !== bytes.readUInt16LE(end + 8) || centralEnd !== end)
+        invalid();
+    for (let i = 0; i < count; i++) {
+        if (offset + 46 > centralEnd || bytes.readUInt32LE(offset) !== 0x02014b50)
+            invalid();
+        const length = bytes.readUInt16LE(offset + 28);
+        const next = offset + 46 + length + bytes.readUInt16LE(offset + 30) + bytes.readUInt16LE(offset + 32);
+        if (next > centralEnd)
+            invalid();
+        const name = bytes.subarray(offset + 46, offset + 46 + length).toString('utf8');
+        if (!name || /[\\\x00-\x1f]/.test(name) || name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.split('/').includes('..') || (bytes.readUInt32LE(offset + 38) >>> 16 & 0xf000) === 0xa000)
+            invalid();
+        offset = next;
+    }
+    if (offset !== centralEnd)
+        invalid();
+}

package/dist/catalogue.js

@@ -0,0 +1,40 @@
+import { readContracts } from './read-contracts.js';
+import { archiveContract } from './archive-contract.js';
+import { writeContracts, writeFlags, recordFamilies } from './write-contracts.js';
+import { settingsFields, dhcpFields, identityFields } from './configuration.js';
+import { routing } from './routing.js';
+export const readFlags = ['--json', '--help', '--config', '--profile', '--result-file', '--fields', '--full', '--max-bytes', '--max-requests', '--max-pages', '--max-elapsed-ms'];
+export const commands = [
+    { command: 'schema', description: 'Show the credential profile JSON Schema', effect: 'local', arguments: [], flags: ['--json', '--help'] },
+    { command: 'inventory', description: 'Show the packaged command inventory', effect: 'local', arguments: [], flags: ['--json', '--help'] },
+    { command: 'status', description: 'Read the selected server status without sending a credential', effect: 'read', operation: 'OP-001', arguments: [], flags: ['--json', '--help', '--config', '--profile'] },
+    { command: 'user session get', description: 'Read the selected session with a redacted projection and optional protected result file', effect: 'read', operation: 'OP-006', arguments: [], flags: ['--json', '--help', '--config', '--profile', '--result-file'] },
+    { command: 'auth status', description: 'Verify the selected credential and report its source without values', effect: 'local', arguments: [], flags: ['--json', '--help', '--config', '--profile'] },
+    ...['login', 'logout'].map(action => ({ command: `auth ${action}`, description: `Alias for user ${action}`, effect: 'write', arguments: [], flags: writeFlags })),
+    { command: 'profile list', description: 'List profile names from the selected config', effect: 'local', arguments: [], flags: ['--json', '--help', '--config'] },
+    { command: 'config path', description: 'Show the selected config path', effect: 'local', arguments: [], flags: ['--json', '--help', '--config'] },
+    { command: 'config import', description: 'Validate and atomically install a config containing SecretRefs', effect: 'local', arguments: [], flags: ['--json', '--help', '--config', '--input-file'] },
+    { command: 'doctor', description: 'Verify credential protection and perform one bounded session read', effect: 'read', arguments: [], flags: ['--json', '--help', '--config', '--profile'] },
+    ...readContracts.filter(item => !['OP-001', 'OP-006'].includes(item.id)).map(item => ({
+        command: item.command, description: `Read ${item.command}`, effect: 'read', operation: item.id, routing: routing(item.id),
+        arguments: item.parameters, flags: [...readFlags, ...item.parameters.map(parameter => parameter.flag)],
+        ...(['OP-084', 'OP-125'].includes(item.id) ? { archive: archiveContract } : {}),
+    })),
+    ...writeContracts.map(item => ({ command: item.command, description: `Preview or execute ${item.command}`, effect: item.id === 'OP-077' ? 'conditional' : 'write', operation: item.id,
+        arguments: [], flags: [...writeFlags, ...(['OP-119', 'OP-127'].includes(item.id) ? ['--reconcile-profile'] : [])], routing: routing(item.id), input: { envelope: ['parameters', 'baseline', 'upload'], fields: item.fields,
+            required: item.required, secrets: item.secrets ?? [], baseline: item.baselinePath ?? null,
+            ...(['OP-002', 'OP-003', 'OP-004', 'OP-009', 'OP-099'].includes(item.id) ? { resultPolicy: { classification: 'confidential-fields', ordinaryOutput: 'metadata and approved projection only', localResult: item.id === 'OP-002' ? 'issued Standard session stored privately; optional exact protected result' : 'required protected result file', hostedResult: 'caller and credential revision bound protected custody' } } : {}),
+            ...(['OP-022', 'OP-023'].includes(item.id) ? { upload: { file: 'protected absolute path', format: item.id === 'OP-023' ? ['multipart (default)', 'text'] : ['multipart'] } } : {}),
+            ...(['OP-072', 'OP-073', 'OP-085'].includes(item.id) ? { upload: { file: 'required protected absolute ZIP path', transport: 'multipart first binary file; parameters in query string' } } : {}),
+            ...(item.id === 'OP-076' ? { config: 'File SecretRef containing the exact opaque config string; never printed' } : {}),
+            ...(item.id === 'OP-029' ? { target: 'Exactly one of zone or nonempty zones array' } : {}),
+            ...(item.id === 'OP-034' ? { permissions: { userPermissions: ['username', 'canView', 'canModify', 'canDelete'], groupPermissions: ['name', 'canView', 'canModify', 'canDelete'], shape: 'Array of rows; permission flags are booleans; an empty user array clears user permissions; group replacements retain Administrators and DNS Administrators with all permissions' } } : {}),
+            ...(item.id === 'OP-113' ? { permissions: { userPermissions: ['username', 'canView', 'canModify', 'canDelete'], groupPermissions: ['name', 'canView', 'canModify', 'canDelete'], shape: 'Array of rows with boolean flags; empty arrays clear permissions; vendor retains Administrators, plus DNS Administrators for Zones or DHCP Administrators for DhcpServer; section writes require the primary' } } : {}),
+            ...(item.id === 'OP-080' ? { configuration: settingsFields, encoding: ['form', 'json'], secretRows: 'tsigKeys rows require a SecretRef for sharedSecret' } : {}),
+            ...(item.id === 'OP-092' ? { configuration: dhcpFields, target: 'Existing scope; baseline.newName is the current name when renaming; collections replace the selected collection' } : {}),
+            ...(['OP-115', 'OP-142', 'OP-143'].includes(item.id) ? { configuration: Object.fromEntries(item.fields.map(key => [key, identityFields[key]])), target: item.id === 'OP-143' ? 'Outbound LDAP bind using stored fields and explicit overrides; requires exact OP-143 write grant' : 'Only supplied fields change; scopes and group maps replace their selected collection', ...(item.id === 'OP-115' ? { scopesEncoding: 'pipe-delimited string array' } : {}) } : {}),
+            ...(item.command.startsWith('dhcp lease ') ? { target: 'Exactly one of clientIdentifier or hardwareAddress' } : {}),
+            ...(item.id === 'OP-077' ? { capabilities: ['OP-077.resolve', 'OP-077.import'] } : {}),
+            ...(['OP-049', 'OP-051', 'OP-052'].includes(item.id) ? { recordFamilies } : {}) } })),
+];
+export const inventory = { version: 1, tool: 'technitium-axi', commands, dhcpFields };

package/dist/cli.js

@@ -0,0 +1,157 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { encode } from '@toon-format/toon';
+import { commands, inventory } from './catalogue.js';
+import { acquisitionKey, configPath, loadConfig, selectProfile } from './credentials.js';
+import { ToolError } from './errors.js';
+import { PrivateFiles } from './private-file.js';
+import { Redactor, saveResult, vendorRead } from './vendor.js';
+import { readContracts } from './read-contracts.js';
+import { readInputs, readOperation } from './reads.js';
+import { writeContracts } from './write-contracts.js';
+import { writeInput, writeOperation } from './writes.js';
+const help = {
+    description: 'Manage Technitium DNS Server through one selected credential profile', commands,
+    flags: ['--help', '--version', '-v', '-V', '--json', '--config', '--profile'],
+    examples: ['technitium-axi status --profile <name>', 'technitium-axi schema --json', 'technitium-axi user session get'],
+};
+export async function main(args) {
+    const redactor = new Redactor();
+    const json = args.includes('--json');
+    const print = (value) => { console.log(redactor.text(json ? JSON.stringify(value) : encode(value))); };
+    try {
+        const options = {};
+        const readOptions = {};
+        const valueFlags = new Set(['--config', '--profile', '--result-file', '--input-file', '--fields', '--max-bytes', '--max-requests', '--max-pages', '--max-elapsed-ms',
+            '--confirm', '--reconcile', '--reconcile-profile',
+            ...readContracts.flatMap(item => item.parameters.map(parameter => parameter.flag))]);
+        const positional = [];
+        const flags = new Set();
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (!arg.startsWith('-')) {
+                positional.push(arg);
+                continue;
+            }
+            if (flags.has(arg))
+                throw new ToolError('USAGE', 'Repeated flag', 'Provide each flag once');
+            flags.add(arg);
+            if (valueFlags.has(arg)) {
+                const value = args[++i];
+                if (value === undefined || value.startsWith('-') || (value === '' && ['--config', '--profile', '--result-file', '--input-file'].includes(arg)))
+                    throw new ToolError('USAGE', 'Flag requires a value', `Use ${arg} <value>`);
+                if (arg === '--config')
+                    options.config = value;
+                else if (arg === '--profile')
+                    options.profile = value;
+                else if (arg === '--result-file')
+                    options.resultFile = value;
+                else if (arg === '--input-file')
+                    options.inputFile = value;
+                else
+                    readOptions[arg] = value;
+            }
+        }
+        const requestedCommand = positional.join(' ');
+        const command = requestedCommand === 'auth login' ? 'user login' : requestedCommand === 'auth logout' ? 'user logout' : requestedCommand;
+        // A stray value after an unknown flag extends the positionals, so match the longest command prefix to keep the command's own flag list in the error.
+        const selected = commands.filter(item => requestedCommand === item.command || requestedCommand.startsWith(`${item.command} `)).sort((a, b) => b.command.length - a.command.length)[0];
+        const allowed = selected ? [...selected.flags, '--version', '-v', '-V'] : help.flags;
+        if ([...flags].some(flag => !allowed.includes(flag)))
+            throw new ToolError('USAGE', 'Unknown or prohibited flag', `Valid flags: ${allowed.join(', ')}`);
+        if (command && selected?.command !== requestedCommand)
+            throw new ToolError('USAGE', 'Unknown command or unexpected argument', 'Run technitium-axi --help');
+        if (args.some(arg => ['--version', '-v', '-V'].includes(arg))) {
+            console.log(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version);
+            return;
+        }
+        if (flags.has('--help')) {
+            print(selected ? { command: selected.command, description: selected.description, flags: selected.flags, arguments: selected.arguments,
+                examples: [`technitium-axi ${selected.command}`, `technitium-axi ${selected.command} --json`] } : help);
+            return;
+        }
+        if (command === 'schema') {
+            print(JSON.parse(await readFile(new URL('../axi-credential.schema.json', import.meta.url), 'utf8')));
+            return;
+        }
+        if (command === 'inventory') {
+            print(inventory);
+            return;
+        }
+        if (command === 'config path') {
+            print({ config: configPath(options.config) });
+            return;
+        }
+        if (command === 'config import') {
+            if (!options.inputFile)
+                throw new ToolError('USAGE', 'Config input is required', 'Use config import --input-file <file>');
+            const config = await loadConfig(resolve(options.inputFile), true);
+            await new PrivateFiles().write(configPath(options.config), JSON.stringify(config));
+            print({ config: configPath(options.config), profiles: Object.keys(config.profiles).length });
+            return;
+        }
+        if (command === 'profile list') {
+            const config = await loadConfig(configPath(options.config), options.config !== undefined || process.env.TECHNITIUM_AXI_CONFIG !== undefined);
+            const profiles = Object.keys(config.profiles).sort().map(name => ({ name, default: name === config.defaultProfile }));
+            print({ count: profiles.length, profiles, help: ['Run technitium-axi auth status --profile <name>'] });
+            return;
+        }
+        if (options.resultFile && !isAbsolute(options.resultFile))
+            throw new ToolError('USAGE', 'Result file must be absolute', 'Use --result-file <absolute-path>');
+        const readContract = readContracts.find(item => item.command === command);
+        if (readContract)
+            readInputs(readContract, readOptions);
+        const writeContract = writeContracts.find(item => item.command === command);
+        const input = writeContract ? await writeInput(writeContract, options.inputFile) : undefined;
+        if (writeContract && ['OP-003', 'OP-004', 'OP-009', 'OP-099'].includes(writeContract.id) && flags.has('--execute') && !options.resultFile)
+            throw new ToolError('USAGE', 'A protected result destination is required', 'Use --result-file <absolute-path>');
+        if (writeContract && options.resultFile && flags.has('--execute'))
+            await new PrivateFiles().destination(options.resultFile);
+        const credential = await selectProfile(options);
+        let reconciliation;
+        if (readOptions['--reconcile-profile']) {
+            if (!readOptions['--reconcile'] || flags.has('--execute') || !['OP-119', 'OP-127'].includes(writeContract?.id ?? ''))
+                throw new ToolError('USAGE', 'A replacement profile is supported only when reconciling cluster init or init-join', 'Supply --reconcile <audit-id> and --reconcile-profile <trusted-profile>');
+            const replacement = await selectProfile({ ...options, profile: readOptions['--reconcile-profile'] });
+            const replacementToken = await replacement.token();
+            redactor.add(replacementToken);
+            reconciliation = { profile: replacement.profile, token: replacementToken, name: replacement.name };
+        }
+        let token;
+        const acquisition = writeContract?.id === 'OP-002' || writeContract?.id === 'OP-003' && input?.parameters.pass !== undefined;
+        if (acquisition)
+            token = await acquisitionKey();
+        else if (command && command !== 'status') {
+            token = await credential.token();
+            redactor.add(token);
+        }
+        if (command === 'auth status') {
+            print({ profile: credential.name, source: credential.source, origin: credential.profile.origin,
+                tokenKind: credential.profile.tokenKind, tokenSource: credential.tokenSource });
+            return;
+        }
+        const result = writeContract && input ? await writeOperation(writeContract, input, credential.profile, credential.name, token, { execute: flags.has('--execute'), ...(readOptions['--confirm'] ? { confirm: readOptions['--confirm'] } : {}),
+            ...(readOptions['--reconcile'] ? { reconcile: readOptions['--reconcile'] } : {}), ...(reconciliation ? { reconciliation } : {}) }, redactor)
+            : readContract && !['OP-001', 'OP-006'].includes(readContract.id)
+                ? await readOperation(credential.profile, command, token, readOptions, flags.has('--full'))
+                : await vendorRead(credential.profile, command === '' || command === 'status' ? 'status' : 'user session get', token);
+        if ('secret' in result && typeof result.secret === 'string')
+            redactor.add(result.secret);
+        let reference;
+        if (options.resultFile) {
+            await saveResult(options.resultFile, result.bytes);
+            reference = { path: options.resultFile, bytes: result.bytes.length, sha256: createHash('sha256').update(result.bytes).digest('hex') };
+        }
+        const executable = resolve(process.argv[1] ?? 'bin/technitium-axi.js');
+        const home = homedir();
+        print({ ...(command === '' ? { bin: executable.startsWith(`${home}/`) ? `~${executable.slice(home.length)}` : executable, description: help.description } : {}),
+            ...result.projection, ...(reference ? { result: reference } : {}) });
+    }
+    catch (error) {
+        const failure = error instanceof ToolError ? error : new ToolError('CONFIG_INVALID', 'Unable to read the selected configuration or protected file', 'Check config path, SecretRef, ownership and file permissions');
+        print({ error: { code: failure.code, message: failure.message }, help: [failure.hint] });
+        process.exitCode = failure.exitCode;
+    }
+}

package/dist/cluster.js

@@ -0,0 +1,129 @@
+import { X509Certificate } from 'node:crypto';
+import { isIP } from 'node:net';
+import { ToolError } from './errors.js';
+import { vendorRequest, checkStatus } from './vendor.js';
+export const clusterTimers = ['heartbeatRefreshIntervalSeconds', 'heartbeatRetryIntervalSeconds', 'configRefreshIntervalSeconds', 'configRetryIntervalSeconds'];
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (message) => { throw new ToolError('USAGE', message, 'Use the cluster input contract shown in inventory'); };
+export function validateCluster(parameters) {
+    for (const [key, value] of Object.entries(parameters)) {
+        if (key.endsWith('IpAddresses') || key === 'ipAddresses') {
+            if (!Array.isArray(value) || value.length === 0 || value.some(ip => typeof ip !== 'string' || !isIP(ip)))
+                fail(`${key} requires a nonempty array of IP addresses`);
+        }
+        else if (key.endsWith('NodeId')) {
+            if (!Number.isInteger(value) || Number(value) < -2147483648 || Number(value) > 2147483647)
+                fail(`${key} requires a signed 32-bit integer`);
+        }
+        else if (key.endsWith('NodeUrl')) {
+            let url;
+            try {
+                url = new URL(String(value));
+            }
+            catch {
+                fail(`${key} requires an HTTPS URL`);
+            }
+            if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+                fail(`${key} requires an HTTPS origin without credentials`);
+        }
+        else if (key === 'primaryNodeIpAddress' && (typeof value !== 'string' || !isIP(value)))
+            fail('primaryNodeIpAddress requires an IP address');
+        else if (key === 'secondaryNodeCertificate') {
+            if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(value))
+                fail('secondaryNodeCertificate requires a base64url DER certificate');
+            try {
+                new X509Certificate(Buffer.from(value, 'base64url'));
+            }
+            catch {
+                fail('secondaryNodeCertificate requires a base64url DER certificate');
+            }
+        }
+        else if (clusterTimers.includes(key)) {
+            const min = key.startsWith('heartbeat') ? 10 : 30;
+            const max = key.startsWith('heartbeat') ? 300 : 3600;
+            if (!Number.isInteger(value) || Number(value) < min || Number(value) > max)
+                fail(`${key} must be between ${min} and ${max}`);
+        }
+    }
+}
+export async function clusterState(profile, token, node) {
+    const body = node === undefined ? '' : new URLSearchParams({ node: String(node) }).toString();
+    const result = await vendorRequest(profile, '/api/admin/cluster/state', body, token, {}, { bytes: 1024 * 1024, elapsedMs: 10000 });
+    if (result.status !== 200 || result.contentType !== 'application/json')
+        throw new ToolError('UPSTREAM_INVALID', 'Cluster state read failed', 'Read cluster state using an explicitly trusted profile', 1);
+    const value = JSON.parse(result.bytes.toString());
+    checkStatus(value);
+    const state = value.response;
+    if (!object(state) || typeof state.clusterInitialized !== 'boolean' || state.clusterInitialized && (!Array.isArray(state.clusterNodes) || state.clusterNodes.some(row => !object(row) || !Number.isInteger(row.id) || typeof row.name !== 'string' || typeof row.url !== 'string' || !['Primary', 'Secondary'].includes(String(row.type)) || typeof row.state !== 'string' || !Array.isArray(row.ipAddresses) || row.ipAddresses.some(ip => typeof ip !== 'string' || !isIP(ip))))) {
+        throw new ToolError('UPSTREAM_INVALID', 'Invalid cluster state', 'Check the selected server API version', 1);
+    }
+    // Heartbeats and synchronization timestamps change independently of the topology being approved.
+    return { clusterInitialized: state.clusterInitialized,
+        ...(state.clusterInitialized ? { clusterDomain: String(state.clusterDomain), ...Object.fromEntries(clusterTimers.map(key => [key, state[key]])) } : {}),
+        clusterNodes: state.clusterInitialized ? state.clusterNodes.map(row => ({ id: row.id, name: row.name, url: row.url, ipAddresses: row.ipAddresses, type: row.type, state: row.state === 'Self' ? 'Self' : 'Remote' })).sort((a, b) => a.id - b.id) : [] };
+}
+export function clusterPreview(id, p, before) {
+    const effects = {
+        'OP-119': 'Initialize the selected node as primary; TLS listeners and identity may change',
+        'OP-120': 'Delete selected primary cluster configuration; remote nodes are not reset',
+        'OP-121': 'Add secondary membership and notify replicated configuration',
+        'OP-122': 'Ask the selected secondary to leave; remote completion requires a separate trusted read',
+        'OP-123': 'Delete primary membership only; the removed secondary is not reset',
+        'OP-124': 'Replace selected secondary address and certificate; notify replicated configuration',
+        'OP-126': 'Change cluster timers; omitted timers remain unchanged',
+        'OP-127': 'Join selected node as secondary and replace replicated configuration; TLS identity may change',
+        'OP-128': 'Leave selected secondary; force can leave stale primary membership',
+        'OP-129': 'Update primary identity and schedule configuration synchronization',
+        'OP-130': 'Trigger asynchronous configuration and cluster secondary zone resync',
+        'OP-131': 'Update primary address on selected secondary; replacement origin is not automatically trusted',
+        'OP-132': 'Promote selected secondary and remove old primary membership; force skips old primary synchronization and deletion',
+        'OP-133': 'Update selected node addresses; TLS trust remains unchanged',
+    };
+    return { scope: p.node === undefined ? 'selected node' : 'named node via vendor proxy', effects: effects[id],
+        affectedNodes: before.clusterNodes.map(({ id, name, type }) => ({ id, name, type })),
+        completion: ['OP-129', 'OP-130'].includes(id) ? 'scheduled, not synchronized' : 'selected-node state only',
+        ...(id === 'OP-127' ? { primaryNodeUrl: p.primaryNodeUrl, ignoreCertificateErrors: p.ignoreCertificateErrors ?? false } : {}),
+        ...(p.forceLeave || p.forceDeletePrimary || p.forceDelete ? { uncertainty: 'Remote nodes may retain cluster configuration; verify them with explicit trusted profiles' } : {}) };
+}
+export function clusterMatches(id, p, before, after) {
+    const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    const self = after.clusterNodes.find(row => row.state === 'Self');
+    const oldSelf = before.clusterNodes.find(row => row.state === 'Self');
+    const primary = after.clusterNodes.find(row => row.type === 'Primary');
+    const oldPrimary = before.clusterNodes.find(row => row.type === 'Primary');
+    if (['OP-120', 'OP-128'].includes(id))
+        return !after.clusterInitialized;
+    if (!after.clusterInitialized)
+        return false;
+    if (id === 'OP-119')
+        return after.clusterDomain === String(p.clusterDomain).replace(/\.+$/, '') && self?.type === 'Primary' && same(self.ipAddresses, p.primaryNodeIpAddresses);
+    if (id === 'OP-127')
+        return self?.type === 'Secondary' && same(self.ipAddresses, p.secondaryNodeIpAddresses) && primary?.url === p.primaryNodeUrl;
+    if (after.clusterDomain !== before.clusterDomain)
+        return false;
+    let expected = structuredClone(before.clusterNodes);
+    if (['OP-122', 'OP-123'].includes(id))
+        expected = expected.filter(row => row.id !== p.secondaryNodeId);
+    else if (['OP-121', 'OP-124'].includes(id)) {
+        const selected = after.clusterNodes.find(row => row.id === p.secondaryNodeId);
+        if (!selected || selected.type !== 'Secondary' || selected.url !== p.secondaryNodeUrl || !same(selected.ipAddresses, p.secondaryNodeIpAddresses))
+            return false;
+        expected = [...expected.filter(row => row.id !== p.secondaryNodeId), selected].sort((a, b) => a.id - b.id);
+    }
+    else if (['OP-129', 'OP-131'].includes(id)) {
+        const selected = id === 'OP-129' && Number(p.primaryNodeId) >= 0 ? expected.find(row => row.id === p.primaryNodeId) : oldPrimary;
+        if (!oldPrimary || !selected || selected.state === 'Self')
+            return false;
+        if (selected.id !== oldPrimary.id)
+            expected = expected.filter(row => row.id !== oldPrimary.id);
+        expected = expected.map(row => row.id === selected.id ? { ...row, name: new URL(String(p.primaryNodeUrl)).hostname.toLowerCase(), type: 'Primary', url: String(p.primaryNodeUrl), ipAddresses: p.primaryNodeIpAddresses ?? primary?.ipAddresses } : row);
+    }
+    else if (id === 'OP-132') {
+        if (!oldSelf || !oldPrimary || oldSelf.type !== 'Secondary')
+            return false;
+        expected = expected.filter(row => row.id !== oldPrimary.id).map(row => row.id === oldSelf.id ? { ...row, type: 'Primary' } : row);
+    }
+    else if (id === 'OP-133')
+        expected = expected.map(row => row.state === 'Self' ? { ...row, ipAddresses: p.ipAddresses } : row);
+    return same(after.clusterNodes, expected) && clusterTimers.every(key => after[key] === (id === 'OP-126' ? p[key] ?? before[key] : before[key]));
+}

package/dist/configuration.js

@@ -0,0 +1,163 @@
+import { ToolError } from './errors.js';
+import { isAbsolute } from 'node:path';
+import { isIP } from 'node:net';
+const words = (text) => text.split(' ');
+const group = (type, text) => Object.fromEntries(words(text).map(key => [key, { type }]));
+// Reviewed against DNS Server 0dd592aad21eced4221a9a46204cb1a299972ca0.
+export const settingsFields = {
+    ...group('string', 'dnsServerDomain defaultResponsiblePerson ipv6Mode eDnsClientSubnetIpv4Override eDnsClientSubnetIpv6Override webServiceHttpUnixSocket webServiceTlsUnixSocket webServiceTlsCertificatePath webServiceRealIpHeader webServiceCspFrameAncestorsHeader dnsOverHttpUnixSocket dnsOverHttpsUnixSocket dnsTlsCertificatePath dnsOverHttpRealIpHeader recursion blockingType proxyType proxyAddress proxyUsername forwarderProtocol loggingType logFolder'),
+    ...group('boolean', 'useSoaSerialDateScheme dnsServerEnableCheckForUpdate dnsAppsEnableAutomaticUpdate enableUdpSocketPool dnssecValidation eDnsClientSubnet webServiceEnableHttpUnixSocket webServiceEnableTlsUnixSocket webServiceEnableTls webServiceEnableHttp3 webServiceHttpToTlsRedirect webServiceUseSelfSignedTlsCertificate enableEDnsClientSubnetSourceAddress enableDnsOverUdpProxy enableDnsOverTcpProxy enableDnsOverHttp enableDnsOverHttpUnixSocket enableDnsOverHttpsUnixSocket enableDnsOverTls enableDnsOverHttps enableDnsOverHttp3 enableDnsOverQuic enableDnsOverHttpHelpRedirect randomizeName qnameMinimization locallyServedDnsZones saveCache serveStale enableCachePrefetch enableBlocking allowTxtBlockingReport concurrentForwarding enableLogging ignoreResolverLogs logQueries noStackTrace useLocalTime enableInMemoryStats preferIPv6'),
+    ...group('integer', 'defaultRecordTtl defaultNsRecordTtl defaultSoaRecordTtl minSoaRefresh minSoaRetry udpPayloadSize eDnsClientSubnetIPv4PrefixLength eDnsClientSubnetIPv6PrefixLength qpmLimitSampleMinutes qpmLimitUdpTruncationPercentage clientTimeout tcpSendTimeout tcpReceiveTimeout quicIdleTimeout quicMaxInboundStreams listenBacklog udpSendBufferSizeKB udpReceiveBufferSizeKB maxConcurrentResolutionsPerCore webServiceHttpPort webServiceTlsPort dnsOverUdpProxyPort dnsOverTcpProxyPort dnsOverHttpPort dnsOverTlsPort dnsOverHttpsPort dnsOverQuicPort resolverRetries resolverTimeout resolverConcurrency resolverMaxStackCount serveStaleTtl serveStaleAnswerTtl serveStaleResetTtl serveStaleMaxWaitTime cacheMaximumEntries cacheMinimumRecordTtl cacheMaximumRecordTtl cacheNegativeRecordTtl cacheFailureRecordTtl cachePrefetchEligibility cachePrefetchTrigger blockingAnswerTtl blockListUpdateIntervalHours proxyPort forwarderRetries forwarderTimeout forwarderConcurrency maxLogFileDays maxStatFileDays'),
+    ...group('list', 'dnsServerLocalEndPoints dnsServerIPv4SourceAddresses dnsServerIPv6SourceAddresses zoneTransferAllowedNetworks notifyAllowedNetworks qpmLimitBypassList webServiceLocalAddresses webServiceReverseProxyAddresses dnsReverseProxyNetworkACL reverseProxyNetworkACL recursionNetworkACL blockingBypassList customBlockingAddresses blockListUrls proxyBypass forwarders'),
+    socketPoolExcludedPorts: { type: 'ports' },
+    qpmPrefixLimitsIPv4: { type: 'rows', columns: ['prefix', 'udpLimit', 'tcpLimit'] },
+    qpmPrefixLimitsIPv6: { type: 'rows', columns: ['prefix', 'udpLimit', 'tcpLimit'] },
+    tsigKeys: { type: 'rows', columns: ['keyName', 'sharedSecret', 'algorithmName'] },
+    webServiceTlsCertificatePassword: { type: 'string', secret: true },
+    dnsTlsCertificatePassword: { type: 'string', secret: true },
+    proxyPassword: { type: 'string', secret: true },
+};
+for (const key of ['Type', 'Address', 'Port', 'Username', 'Password', 'Bypass'])
+    settingsFields[`proxy${key}`].read = `proxy.${key === 'Bypass' ? 'bypass' : key.toLowerCase()}`;
+settingsFields.reverseProxyNetworkACL.read = 'dnsReverseProxyNetworkACL';
+export const dhcpFields = {
+    ...group('string', 'name newName startingAddress endingAddress subnetMask domainName serverAddress serverHostName bootFileName routerAddress'),
+    ...group('integer', 'leaseTimeDays leaseTimeHours leaseTimeMinutes offerDelayTime pingCheckTimeout pingCheckRetries dnsTtl'),
+    ...group('boolean', 'pingCheckEnabled dnsUpdates dnsOverwriteForDynamicLease useThisDnsServer allowOnlyReservedLeases blockLocallyAdministeredMacAddresses ignoreClientIdentifierOption'),
+    ...group('list', 'domainSearchList dnsServers winsServers ntpServers ntpServerDomainNames capwapAcIpAddresses tftpServerAddresses'),
+    staticRoutes: { type: 'rows', columns: ['destination', 'subnetMask', 'router'] },
+    vendorInfo: { type: 'rows', columns: ['identifier', 'information'] },
+    genericOptions: { type: 'rows', columns: ['code', 'value'] },
+    exclusions: { type: 'rows', columns: ['startingAddress', 'endingAddress'] },
+    reservedLeases: { type: 'rows', columns: ['hostName', 'hardwareAddress', 'address', 'comments'] },
+};
+export const identityFields = {
+    ...group('string', 'ssoAuthority ssoClientId ssoMetadataAddress ldapServer ldapSslOption ldapBindUsername ldapSearchBase ldapUserSearchFilter ldapGroupAttribute'),
+    ...group('boolean', 'ssoEnabled ssoAllowSignup ssoAllowSignupOnlyForMappedUsers ldapEnabled ldapIgnoreSslErrors ldapAllowSignup ldapAllowSignupOnlyForMappedUsers'),
+    ldapPort: { type: 'integer' },
+    ssoScopes: { type: 'list' },
+    ssoGroupMap: { type: 'rows', columns: ['remoteGroup', 'localGroup'] },
+    ldapGroupMap: { type: 'rows', columns: ['remoteGroup', 'localGroup'] },
+    ssoClientSecret: { type: 'string', secret: true },
+    ldapBindPassword: { type: 'string', secret: true },
+};
+export function validateIdentity(key, value, resolved = false) {
+    validateConfiguration(identityFields[key], value, resolved);
+    if (key === 'ssoScopes' && value.some(scope => /[|]/.test(scope)))
+        invalid();
+    if (key === 'ldapPort' && Number(value) > 65535)
+        invalid();
+    if (key === 'ldapSslOption' && !['None', 'LDAPS', 'StartTLS'].includes(String(value)))
+        invalid();
+    if (identityFields[key].secret && resolved && value === '************')
+        invalid();
+}
+export function dhcpValue(key, value) {
+    const field = dhcpFields[key];
+    if (value == null && ['list', 'rows'].includes(field.type))
+        return [];
+    if (value == null && field.type === 'string')
+        return '';
+    if (['genericOptions', 'vendorInfo'].includes(key) && Array.isArray(value)) {
+        const column = key === 'genericOptions' ? 'value' : 'information';
+        return value.map(row => ({ ...row, [column]: typeof row?.[column] === 'string' && /^(?:[\da-fA-F]{2})+$/.test(row[column].replace(/:/g, ''))
+                ? row[column].replace(/:/g, '').toUpperCase().match(/../g).join(':') : row?.[column] }));
+    }
+    if (key === 'reservedLeases' && Array.isArray(value))
+        return value.map(row => !object(row) ? row : ({ ...row,
+            hardwareAddress: typeof row.hardwareAddress === 'string' ? row.hardwareAddress.replace(/[:-]/g, '').toUpperCase().match(/../g)?.join('-') ?? '' : row.hardwareAddress,
+            hostName: row.hostName ?? '', comments: row.comments ?? '' })).sort((a, b) => String(a?.address).localeCompare(String(b?.address), 'en', { numeric: true }));
+    return value;
+}
+export function validateDhcp(key, value) {
+    validateConfiguration(dhcpFields[key], value);
+    const maximum = { leaseTimeDays: 65535, leaseTimeHours: 23, leaseTimeMinutes: 59,
+        offerDelayTime: 65535, pingCheckTimeout: 65535, pingCheckRetries: 255, dnsTtl: 4294967295 };
+    if (maximum[key] !== undefined && Number(value) > maximum[key])
+        invalid();
+    if (['name', 'newName'].includes(key) && value === '')
+        invalid();
+    if (['startingAddress', 'endingAddress', 'subnetMask', 'serverAddress', 'routerAddress'].includes(key) && value !== '' && isIP(String(value)) !== 4)
+        invalid();
+    if (['dnsServers', 'winsServers', 'ntpServers', 'capwapAcIpAddresses', 'tftpServerAddresses'].includes(key) && value.some(address => isIP(address) !== 4))
+        invalid();
+    if (['genericOptions', 'vendorInfo'].includes(key))
+        for (const row of value) {
+            const hex = row[key === 'genericOptions' ? 'value' : 'information'];
+            if (typeof hex !== 'string' || !/^(?:[\da-fA-F]{2})+$/.test(hex.replace(/:/g, '')) || key === 'genericOptions' && Number(row.code) > 255)
+                invalid();
+        }
+}
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+function invalid() { throw new ToolError('USAGE', 'Invalid configuration field value', 'Use the configuration field types and row columns shown in inventory'); }
+export function validateConfiguration(field, value, resolved = false) {
+    if (field.secret && !resolved) {
+        if (!object(value) || Object.keys(value).length !== 1 || !(typeof value.env === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value.env) || typeof value.file === 'string' && isAbsolute(value.file)))
+            invalid();
+        return;
+    }
+    if (field.type === 'boolean') {
+        if (typeof value !== 'boolean')
+            invalid();
+    }
+    else if (field.type === 'integer') {
+        if (!Number.isSafeInteger(value) || Number(value) < 0)
+            invalid();
+    }
+    else if (field.type === 'string') {
+        if (typeof value !== 'string' || /[\x00\r]/.test(value) || value === '[REDACTED]')
+            invalid();
+    }
+    else {
+        if (!Array.isArray(value))
+            invalid();
+        for (const item of value) {
+            if (field.type === 'ports') {
+                if (!Number.isInteger(item) || item < 0 || item > 65535)
+                    invalid();
+            }
+            else if (field.type === 'list') {
+                if (typeof item !== 'string' || /[\x00-\x1f\x7f,]/.test(item) || item === '[REDACTED]')
+                    invalid();
+            }
+            else {
+                if (!object(item) || Object.keys(item).length !== field.columns.length)
+                    invalid();
+                for (const column of field.columns) {
+                    if (column === 'sharedSecret' && !resolved) {
+                        validateConfiguration({ type: 'string', secret: true }, item[column]);
+                        continue;
+                    }
+                    if (['prefix', 'udpLimit', 'tcpLimit', 'code'].includes(column)) {
+                        if (!Number.isSafeInteger(item[column]) || Number(item[column]) < 0)
+                            invalid();
+                    }
+                    else if (typeof item[column] !== 'string' || /[|\x00-\x1f\x7f]/.test(item[column]) || item[column] === '[REDACTED]')
+                        invalid();
+                }
+            }
+        }
+    }
+}
+export function configurationForm(field, value) {
+    if (field?.type === 'rows')
+        return value.flatMap(row => field.columns.map(column => String(row[column]))).join('|');
+    return Array.isArray(value) ? value.join(',') : String(value);
+}
+export function settingValue(response, key) {
+    if (key.startsWith('proxy') && response.proxy === null)
+        return key === 'proxyType' ? 'None' : key === 'proxyPort' ? 0 : key === 'proxyBypass' ? [] : '';
+    if (key === 'enableLogging' && response.enableLogging === undefined)
+        return response.loggingType !== 'None';
+    const path = (settingsFields[key]?.read ?? key).split('.');
+    let value = response;
+    for (const part of path)
+        value = object(value) ? value[part] : undefined;
+    if (['proxyUsername', 'proxyPassword'].includes(key) && value == null)
+        return '';
+    if (key === 'proxyBypass' && value == null)
+        return [];
+    if (value === null && ['list', 'ports', 'rows'].includes(settingsFields[key]?.type ?? ''))
+        return [];
+    return value;
+}