@hivemagnus/magnus-server 0.0.0-stage → 1.0.2

package/dist/sdk/node-api-client.js

@@ -0,0 +1,474 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { MANAGED_CLAIM_HEADER, httpIdentity, httpReceiptBody, managedHttpRequestSchema } from '../security/managed-http.js';
+import { nativeCompletionDescriptor, nativeCompletionResourceKey } from '../security/native-completion-registry.js';
+import { COMMAND_COMPLETION_REGISTRY, COMMAND_COMPLETION_REGISTRY_SHA256, commandCompletionDescriptor } from '../security/command-completion-registry.js';
+import { commandReconciliationSchema } from '../schemas/command-reconciliation.js';
+import { admitResourceCommand, markResourceDispatched, failResourceCommand, settleResourceResult, settleResourceReconciliation } from '../services/command-resource-leases.js';
+import { commandFenceSchema, commandResultSchema } from '../schemas/node-responses.js';
+import { commandRequestDigest } from '../security/command-request.js';
+import ky from 'ky';
+import { HttpError } from '../middleware/error-handler.js';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { RESULT_SIGNING_PREVIOUS_SECRET, RESULT_SIGNING_SECRET } from '../utils/env.js';
+import { correlateSkillPublicationNoEffect } from '../services/skill-publication-settlement.js';
+import { commandResultSigningPayload, verifyCommandResultSignature, } from '../security/command-result-signature.js';
+/** Wire format shared with the node ledger; cross-wire tests guard canonicalization. */
+export { commandReconciliationSchema } from '../schemas/command-reconciliation.js';
+export function commandReconciliationSigningPayload(assertion) {
+    return JSON.stringify({ domain: 'magnus.command-reconciliation.v1', nodeFqdn: assertion.nodeFqdn,
+        commandId: assertion.commandId, requestSha256: assertion.requestSha256,
+        coordination: assertion.coordination ? { version: assertion.coordination.version,
+            resourceKey: assertion.coordination.resourceKey, fence: assertion.coordination.fence,
+            expiresAt: assertion.coordination.expiresAt } : null,
+        disposition: assertion.disposition, evidenceSha256: assertion.evidenceSha256,
+        approvalRef: assertion.approvalRef, decisionId: assertion.decisionId, expiresAt: assertion.expiresAt });
+}
+function verifiedReconciliation(raw, commandId, expected, fresh, nodeToken) {
+    const assertion = commandReconciliationSchema.parse(raw);
+    const secret = process.env['COMMAND_RECONCILIATION_SECRET'] ?? '';
+    if (!expected || !/^[a-f0-9]{64}$/.test(expected.requestSha256) || !expected.nodeFqdn
+        || secret.length < 32 || secret === RESULT_SIGNING_SECRET || secret === nodeToken
+        || assertion.commandId !== commandId || assertion.nodeFqdn !== expected.nodeFqdn
+        || assertion.requestSha256 !== expected.requestSha256
+        || (fresh && (assertion.expiresAt <= Date.now() || assertion.expiresAt > Date.now() + 300_000)))
+        throw new Error('Command reconciliation authority, expected node, digest, or validity differs');
+    const signature = createHmac('sha256', secret).update(commandReconciliationSigningPayload(assertion)).digest();
+    if (!timingSafeEqual(signature, Buffer.from(assertion.signature, 'hex')))
+        throw new Error('Command reconciliation signature verification failed');
+    return assertion;
+}
+/**
+ * An agent running with MAGNUS_AGENT_PRIVILEGED=false answers root-only routes
+ * (cron, users, system updates, Ardent actions) with 403 AGENT_NOT_PRIVILEGED.
+ * Surface that as a non-retryable "feature disabled on this node" error.
+ */
+export const AGENT_NOT_PRIVILEGED = 'AGENT_NOT_PRIVILEGED';
+async function rejectUnprivilegedAgent({ response }) {
+    if (response.status !== 403)
+        return;
+    let body;
+    try {
+        body = await response.clone().json();
+    }
+    catch {
+        return;
+    }
+    if (body?.error?.code !== AGENT_NOT_PRIVILEGED)
+        return;
+    const feature = typeof body.error.feature === 'string' ? body.error.feature.slice(0, 64) : 'feature';
+    throw new HttpError(409, AGENT_NOT_PRIVILEGED, `${feature} is disabled on this node: agent is not privileged (MAGNUS_AGENT_PRIVILEGED=false)`);
+}
+/** Whether an error means the target agent has the feature disabled. */
+export function isAgentNotPrivileged(error) {
+    return error instanceof HttpError && error.code === AGENT_NOT_PRIVILEGED;
+}
+export class NodeApiClient {
+    api;
+    nodeToken;
+    defaultTimeout;
+    resourceContext;
+    constructor(options) {
+        this.nodeToken = options.nodeToken;
+        this.defaultTimeout = options.timeout ?? 15_000;
+        if (options.resourceNodeId)
+            this.resourceContext = { nodeId: options.resourceNodeId,
+                actorId: options.resourceActorId ?? 'system:control-api', baseUrl: options.baseUrl,
+                ...(options.resourceScope ? { scope: options.resourceScope } : {}) };
+        this.api = ky.create({
+            prefix: `${options.baseUrl}/api/v1`,
+            timeout: options.timeout ?? 15_000,
+            headers: {
+                'x-node-token': options.nodeToken,
+            },
+            hooks: { afterResponse: [rejectUnprivilegedAgent] },
+        });
+    }
+    /** All finite native mutations use the same central owner and node execution slot. */
+    async mutateWithEvidence(method, path, body, timeout = this.defaultTimeout, commandId, skillPublication, requireManaged = false) {
+        if (!this.resourceContext)
+            throw new Error('Managed mutation requires canonical resource node identity');
+        const serialized = body === undefined ? '' : JSON.stringify(body);
+        const nativePath = '/' + path;
+        const requestedTimeoutSeconds = Math.ceil(timeout / 1000);
+        const timeoutSeconds = Math.min(3600, requestedTimeoutSeconds);
+        const descriptor = nativeCompletionDescriptor(method, nativePath);
+        const identity = httpIdentity(commandId ?? 'native-' + randomUUID(), method, nativePath, serialized, timeoutSeconds);
+        const admission = await admitResourceCommand(this.resourceContext, identity);
+        if (!admission && requireManaged)
+            throw new Error('This operation requires enrolled managed admission; direct node mutation is forbidden');
+        if (!admission)
+            return { response: await this.api(path, { method,
+                    ...(body === undefined ? {} : { body: serialized, headers: { 'content-type': 'application/json' } }), timeout, retry: 0 }).json() };
+        try {
+            if (!descriptor || descriptor.completionMode !== 'buffered-synchronous-http'
+                || requestedTimeoutSeconds > descriptor.timeoutCeilingSeconds)
+                throw new Error('This enrolled-node mutation lacks a reviewed completion boundary; not dispatched');
+            if (admission.payload.coordination?.resourceKey !== nativeCompletionResourceKey(descriptor, this.resourceContext.nodeId))
+                throw new Error('Native mutation resource classification differs from its lease');
+            const capability = await this.api.get('ping').json();
+            if (!capability.success || capability.data?.features?.managedMutations !== 1)
+                throw new Error('Node does not support managed mutations; operation not dispatched');
+            await markResourceDispatched(admission);
+            const managedRequest = managedHttpRequestSchema.parse({
+                claim: { leaseId: admission.leaseId, nodeId: admission.nodeId, nodeFqdn: admission.nodeFqdn },
+                commandId: admission.commandId, method, path: '/' + path, body: serialized,
+                timeoutSeconds: identity.timeoutSeconds, coordination: admission.payload.coordination,
+            });
+            const envelope = await this.api.post('commands/managed-http', { retry: 0, timeout: timeout + 5000,
+                json: managedRequest }).json();
+            if (!envelope.success)
+                throw new Error('Managed mutation response was unsuccessful');
+            const { response } = envelope.data;
+            const receipt = this.verifiedCommandResult(envelope.data.receipt, admission.commandId);
+            if (!Number.isInteger(response.status) || response.status < 100 || response.status > 599 || typeof response.body !== 'string'
+                || receipt.stdout !== httpReceiptBody(method, '/' + path, response.status, response.body))
+                throw new Error('Managed response body differs from signed receipt');
+            await settleResourceResult(admission.commandId, receipt);
+            if (response.status === 409 && skillPublication)
+                await correlateSkillPublicationNoEffect({
+                    commandId: admission.commandId, requestSha256: commandRequestDigest(admission.payload),
+                    skillName: skillPublication.skillName, version: skillPublication.version,
+                    bundleSha256: skillPublication.bundleSha256, responseBody: response.body,
+                });
+            if (response.status >= 400)
+                throw new Error(`Native mutation completed with HTTP ${response.status}`);
+            const commandSha256 = receipt.coordination?.requestSha256;
+            if (!commandSha256 || commandSha256 !== commandRequestDigest(admission.payload))
+                throw new Error('Managed mutation command evidence differs');
+            return { response: JSON.parse(response.body), evidence: { commandId: receipt.commandId,
+                    commandSha256, receiptSha256: createHash('sha256').update(JSON.stringify({
+                        payload: commandResultSigningPayload(receipt), signature: receipt.signature,
+                    })).digest('hex'),
+                    acknowledgedAt: new Date() } };
+        }
+        catch (error) {
+            await failResourceCommand(admission);
+            throw error;
+        }
+    }
+    async mutate(method, path, body, timeout = this.defaultTimeout) {
+        return (await this.mutateWithEvidence(method, path, body, timeout)).response;
+    }
+    async evidencedMutation(method, path, body, commandId) {
+        const result = await this.mutateWithEvidence(method, path, body, this.defaultTimeout, commandId);
+        if (!result.evidence)
+            throw new Error('Managed mutation acknowledgement requires a signed managed HTTP receipt');
+        return { response: result.response, evidence: result.evidence };
+    }
+    // ── Health ──
+    async collectHealth() {
+        return this.api.get('health/collect').json();
+    }
+    async enableSystemUpdates() {
+        return this.mutate('POST', 'health/system-updates/enable', undefined, 20 * 60_000);
+    }
+    // ── Commands ──
+    verifiedCommandResult(raw, commandId) {
+        const parsed = commandResultSchema.safeParse(raw);
+        if (!parsed.success || parsed.data.commandId !== commandId || !verifyCommandResultSignature(parsed.data, RESULT_SIGNING_SECRET, RESULT_SIGNING_PREVIOUS_SECRET))
+            throw new Error('Command result signature verification failed');
+        return parsed.data;
+    }
+    async executeCommand(payload) {
+        // Snapshot callers' mutable objects before any asynchronous admission check.
+        payload = structuredClone(payload);
+        if (!this.resourceContext)
+            throw new Error('Managed command requires canonical resource node identity');
+        const admission = await admitResourceCommand(this.resourceContext, payload);
+        if (admission)
+            payload = admission.payload;
+        try {
+            if (payload.coordination) {
+                commandFenceSchema.parse(payload.coordination);
+                const descriptor = commandCompletionDescriptor(payload);
+                const capability = await this.api.get('ping').json();
+                if (!capability.success || capability.data?.features?.commandFencing !== 1)
+                    throw new Error('Node does not support command fencing; command not dispatched');
+                if (admission && capability.data?.features?.managedMutations !== 1)
+                    throw new Error('Node does not support sticky managed mutation admission; command not dispatched');
+                if (descriptor && (capability.data?.features?.commandCompletionRegistry?.enabled !== 1
+                    || capability.data.features.commandCompletionRegistry.version !== COMMAND_COMPLETION_REGISTRY.version
+                    || capability.data.features.commandCompletionRegistry.sha256 !== COMMAND_COMPLETION_REGISTRY_SHA256))
+                    throw new Error('Node command completion registry differs; command not dispatched');
+                if (payload.coordination.expiresAt <= Date.now())
+                    throw new Error('Command lease expired; command not dispatched');
+            }
+            const timeout = (payload.timeoutSeconds + 5) * 1_000;
+            // A missing POST response is uncertain. Reconcile through the receipt API;
+            // never use transport retries to run an action again.
+            if (admission)
+                await markResourceDispatched(admission);
+            const response = await this.api.post('commands/execute', { json: payload, timeout, retry: 0, ...(admission ? { headers: { [MANAGED_CLAIM_HEADER]: JSON.stringify({ leaseId: admission.leaseId, nodeId: admission.nodeId, nodeFqdn: admission.nodeFqdn }) } } : {}) }).json();
+            const result = this.verifiedCommandResult(response?.data, payload.commandId);
+            const descriptor = commandCompletionDescriptor(payload);
+            if (descriptor && (result.completion?.registryVersion !== COMMAND_COMPLETION_REGISTRY.version
+                || result.completion.registrySha256 !== COMMAND_COMPLETION_REGISTRY_SHA256
+                || result.completion.descriptorId !== descriptor.id))
+                throw new Error('Command completion registry receipt differs');
+            if (!descriptor && result.completion !== undefined)
+                throw new Error('Unregistered command returned terminal registry evidence');
+            if (payload.coordination ? !result.coordination
+                || result.coordination.resourceKey !== payload.coordination.resourceKey
+                || result.coordination.fence !== payload.coordination.fence
+                || result.coordination.expiresAt !== payload.coordination.expiresAt
+                || result.coordination.requestSha256 !== commandRequestDigest(payload)
+                : result.coordination !== undefined)
+                throw new Error('Command result request/fence verification failed');
+            if (!response.success)
+                throw new Error('Command execution response was unsuccessful');
+            if (admission)
+                await settleResourceResult(payload.commandId, result);
+            return response;
+        }
+        catch (error) {
+            if (admission)
+                await failResourceCommand(admission);
+            throw error;
+        }
+    }
+    verifiedCommandReceipt(raw, commandId, expected) {
+        const parsed = z.object({ commandId: z.string(), requestSha256: z.string().regex(/^[a-f0-9]{64}$/),
+            state: z.enum(['running', 'unknown', 'completed', 'reconciled']), result: z.unknown().optional(),
+            reconciliation: z.unknown().optional(), coordination: commandFenceSchema.optional(),
+        }).safeParse(raw);
+        if (!parsed.success || parsed.data.commandId !== commandId
+            || (expected && parsed.data.requestSha256 !== expected.requestSha256))
+            throw new Error('Invalid command receipt');
+        const row = parsed.data;
+        if (row.state === 'reconciled') {
+            if (row.result !== undefined)
+                throw new Error('Reconciled receipt cannot contain a result');
+            const assertion = verifiedReconciliation(row.reconciliation, commandId, expected, false, this.nodeToken);
+            if (assertion.requestSha256 !== row.requestSha256
+                || JSON.stringify(row.coordination ?? null) !== JSON.stringify(assertion.coordination ?? null))
+                throw new Error('Reconciliation receipt request/fence binding differs');
+            return { commandId, requestSha256: row.requestSha256, state: 'reconciled', reconciliation: assertion };
+        }
+        if (row.reconciliation !== undefined)
+            throw new Error('Unreconciled receipt cannot contain an attestation');
+        if (row.state === 'completed') {
+            const result = this.verifiedCommandResult(row.result, commandId);
+            if (result.coordination && result.coordination.requestSha256 !== row.requestSha256)
+                throw new Error('Receipt request binding differs');
+            return { commandId, requestSha256: row.requestSha256, state: 'completed', result };
+        }
+        if (row.result !== undefined)
+            throw new Error('Nonterminal receipt cannot contain a result');
+        return { commandId, requestSha256: row.requestSha256, state: row.state };
+    }
+    async getCommandReceipt(commandId, expected) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(commandId))
+            throw new Error('Invalid command identifier');
+        expected = expected ? { ...expected } : undefined;
+        const response = await this.api.get(`commands/receipts/${encodeURIComponent(commandId)}`).json();
+        if (!response.success)
+            throw new Error('Command receipt response was unsuccessful');
+        const receipt = this.verifiedCommandReceipt(response.data, commandId, expected);
+        if (this.resourceContext && receipt.state === 'completed')
+            await settleResourceResult(commandId, receipt.result);
+        if (this.resourceContext && receipt.state === 'reconciled')
+            await settleResourceReconciliation(this.resourceContext.nodeId, receipt.reconciliation);
+        return receipt;
+    }
+    /** Submit only an already signed, explicitly reviewed assertion. This method
+     * neither signs a decision, runs a command, nor retries ambiguous mutations. */
+    async reconcileCommandReceipt(raw, expected) {
+        expected = { ...expected };
+        const assertion = verifiedReconciliation(raw, raw.commandId, expected, true, this.nodeToken);
+        const capability = await this.api.get('ping').json();
+        if (!capability.success || capability.data?.features?.commandReconciliation !== 1)
+            throw new Error('Node does not support explicit command reconciliation');
+        // A capability lookup may consume the assertion's remaining validity.
+        verifiedReconciliation(assertion, assertion.commandId, expected, true, this.nodeToken);
+        const response = await this.api.post(`commands/receipts/${encodeURIComponent(assertion.commandId)}/reconcile`, { json: assertion, retry: 0 }).json();
+        if (!response.success)
+            throw new Error('Command reconciliation response was unsuccessful');
+        const receipt = this.verifiedCommandReceipt(response.data, assertion.commandId, expected);
+        if (receipt.state !== 'reconciled' || receipt.reconciliation.signature !== assertion.signature)
+            throw new Error('Node did not acknowledge the exact reconciliation decision');
+        if (this.resourceContext)
+            await settleResourceReconciliation(this.resourceContext.nodeId, receipt.reconciliation);
+        return receipt;
+    }
+    // ── Cron ──
+    async listCronJobs() {
+        return this.api.get('cron').json();
+    }
+    async listAllUserCronJobs() {
+        return this.api.get('cron/all-users').json();
+    }
+    async syncManagedCronJob(data) {
+        return this.evidencedMutation('POST', 'cron/managed-sync', data);
+    }
+    /** Pre-enrollment conversion may only stage a disabled definition and remove
+     * its same-name legacy wake-up. It deliberately cannot return activation evidence. */
+    async stageManagedCronForEnrollment(data) {
+        return this.api.post('cron/enrollment-stage', { json: data, retry: 0 }).json();
+    }
+    async activateManagedCronJob(data) {
+        return this.evidencedMutation('POST', 'cron/managed-activate', data);
+    }
+    async revokeManagedCronJob(data) {
+        return this.evidencedMutation('POST', 'cron/managed-revoke', data);
+    }
+    /** Signed evidence reconciliation is an enrollment control message. It does
+     * not execute or mutate the observed foreign scheduler itself. */
+    async reconcileSchedulerSource(data) {
+        return this.api.post('cron/source-reconciliation', { json: data, retry: 0 }).json();
+    }
+    async syncCronJob(data) {
+        return this.mutate('POST', 'cron/sync', data);
+    }
+    async updateCronJob(name, data) {
+        return this.mutate('PATCH', `cron/${encodeURIComponent(name)}`, data);
+    }
+    async deleteCronJob(name) {
+        return this.mutate('DELETE', `cron/${encodeURIComponent(name)}`);
+    }
+    // ── Files ──
+    async readFile(filePath) {
+        return this.api.get('files/read', { searchParams: { filePath } }).json();
+    }
+    async writeFile(payload) {
+        return this.mutate('POST', 'files/write', payload);
+    }
+    // ── Skills ──
+    async listSkills() {
+        return this.api.get('skills').json();
+    }
+    async installSkill(payload) {
+        return this.mutate('POST', 'skills/install', payload);
+    }
+    async publishSkillBundle(payload, commandId) {
+        const result = await this.mutateWithEvidence('POST', 'skills/install', payload, this.defaultTimeout, commandId, payload);
+        if (!result.evidence)
+            throw new Error('Managed skill publication acknowledgement requires a signed receipt');
+        return { response: result.response, evidence: result.evidence };
+    }
+    /** Ask the node to recover only the retained result of the exact previously
+     * dispatched skill publication. The node's recovery-claim path cannot invoke
+     * the skill handler or create a new effect. */
+    async recoverSkillBundle(payload, ownership) {
+        if (!this.resourceContext || this.resourceContext.nodeId !== ownership.nodeId)
+            throw new Error('Skill recovery target differs from canonical node identity');
+        const serialized = JSON.stringify(payload);
+        const identity = { ...httpIdentity(ownership.commandId, 'POST', '/skills/install', serialized, ownership.timeoutSeconds),
+            coordination: ownership.coordination };
+        if (commandRequestDigest(identity) !== ownership.requestSha256)
+            throw new Error('Skill recovery request differs from retained workflow identity');
+        const managedRequest = managedHttpRequestSchema.parse({
+            claim: { leaseId: ownership.leaseId, nodeId: ownership.nodeId, nodeFqdn: ownership.nodeFqdn },
+            commandId: ownership.commandId, method: 'POST', path: '/skills/install', body: serialized,
+            timeoutSeconds: ownership.timeoutSeconds, coordination: ownership.coordination, recoveryOnly: true,
+        });
+        const envelope = await this.api.post('commands/managed-http', { retry: 0,
+            timeout: Math.max(this.defaultTimeout, ownership.timeoutSeconds * 1000) + 5000,
+            json: managedRequest }).json();
+        if (!envelope.success)
+            throw new Error('Skill publication recovery response was unsuccessful');
+        const receipt = this.verifiedCommandResult(envelope.data.receipt, ownership.commandId);
+        const response = envelope.data.response;
+        if (!Number.isInteger(response.status) || typeof response.body !== 'string'
+            || receipt.coordination?.requestSha256 !== ownership.requestSha256
+            || receipt.stdout !== httpReceiptBody('POST', '/skills/install', response.status, response.body))
+            throw new Error('Recovered skill publication differs from its signed workflow receipt');
+        await settleResourceResult(ownership.commandId, receipt);
+        if (response.status === 409) {
+            await correlateSkillPublicationNoEffect({ commandId: ownership.commandId,
+                requestSha256: ownership.requestSha256, skillName: payload.skillName, version: payload.version,
+                bundleSha256: payload.bundleSha256, responseBody: response.body });
+            throw new Error('Skill publication recovery proved that no effect was committed');
+        }
+        if (response.status >= 400)
+            throw new Error(`Skill publication recovery completed with HTTP ${response.status}`);
+        return { response: JSON.parse(response.body), evidence: { commandId: ownership.commandId, commandSha256: ownership.requestSha256,
+                receiptSha256: createHash('sha256').update(JSON.stringify({
+                    payload: commandResultSigningPayload(receipt), signature: receipt.signature,
+                })).digest('hex'), acknowledgedAt: new Date() } };
+    }
+    async removeSkill(skillName) {
+        return this.mutate('DELETE', `skills/${encodeURIComponent(skillName)}`);
+    }
+    // ── Self-update ──
+    async triggerUpdate(payload) {
+        return this.mutate('POST', 'update', payload);
+    }
+    // ── Ping ──
+    async ping() {
+        return this.api.get('ping').json();
+    }
+    // ── Hermes Agent runtime ──
+    async getHermesState(payload = {}) {
+        return this.api.get('hermes/state', { searchParams: payload }).json();
+    }
+    async installHermes(payload) {
+        return this.mutate('POST', 'hermes/install', payload, 20 * 60_000);
+    }
+    async configureHermes(payload) {
+        return this.mutate('POST', 'hermes/configure', payload, 60_000);
+    }
+    async updateHermes(payload) {
+        return this.mutate('POST', 'hermes/update', payload, 20 * 60_000);
+    }
+    async uninstallHermes(payload) {
+        return this.mutate('POST', 'hermes/uninstall', payload, 5 * 60_000);
+    }
+    // ── Codex CLI and ChatGPT OAuth ──
+    async getCodexState(refreshLatest = false) {
+        return this.api.get('codex/state', { searchParams: { refreshLatest }, timeout: 35_000 }).json();
+    }
+    // ── Ardent node-local runtime ──
+    async getArdentState(timeoutMs = 15_000) {
+        return this.api.get('ardent/state', { timeout: timeoutMs, retry: 0 }).json();
+    }
+    async getArdentProfileResource(profile, resource, query) {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(profile) || !/^[A-Za-z0-9_/-]{1,120}$/.test(resource))
+            throw new Error('Invalid Ardent profile resource');
+        return this.api.get(`ardent/profiles/${profile}/api/${resource}`, { ...(query ? { searchParams: query } : {}), timeout: 15_000 }).json();
+    }
+    async getArdentArtifact(profile, artifactId) {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(profile) || !/^[a-f0-9]{64}$/.test(artifactId))
+            throw new Error('Invalid Ardent artifact target');
+        const response = await this.api.get(`ardent/profiles/${profile}/api/artifacts/${artifactId}`, { timeout: 15_000 });
+        if (response.headers.get('content-type') !== 'application/octet-stream')
+            throw new Error('Ardent artifact response type differs');
+        const bytes = await response.arrayBuffer();
+        if (bytes.byteLength > 2 * 1024 * 1024)
+            throw new Error('Ardent artifact exceeds size limit');
+        return new Uint8Array(bytes);
+    }
+    async performArdentAction(profile, action, target, body) {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(profile) || !/^[a-z-]{1,32}$/.test(action)
+            || (target !== undefined && !/^[A-Za-z0-9_-]{1,128}$/.test(target)))
+            throw new Error('Invalid Ardent action target');
+        const timeout = action === 'package-install' ? 600_000 : action === 'profile-import-hermes' ? 90_000 : action.startsWith('service-') ? 115_000 : 45_000;
+        return this.mutate('POST', 'ardent/action', { profile, action, ...(target ? { target } : {}), body: body ?? {} }, timeout);
+    }
+    async updateCodex() {
+        return this.mutate('POST', 'codex/update', undefined, 11 * 60_000);
+    }
+    async logoutCodex() {
+        return this.mutate('POST', 'codex/logout', undefined, 35_000);
+    }
+    async startCodexDeviceAuth() {
+        return this.mutate('POST', 'codex/device-auth', undefined, 35_000);
+    }
+    async getCodexDeviceAuth(id) {
+        return this.api.get(`codex/device-auth/${encodeURIComponent(id)}`).json();
+    }
+    async cancelCodexDeviceAuth(id) {
+        return this.mutate('POST', `codex/device-auth/${encodeURIComponent(id)}/cancel`);
+    }
+    // ── User management ──
+    async listUsers() {
+        return this.api.get('users').json();
+    }
+    async provisionUser(payload) {
+        return this.mutate('POST', 'users/provision', payload);
+    }
+    async changeUserPassword(payload) {
+        return this.mutate('POST', 'users/change-password', payload);
+    }
+}
+//# sourceMappingURL=node-api-client.js.map

package/dist/security/approval-assertion.js

@@ -0,0 +1,66 @@
+import { createHash, createPublicKey, timingSafeEqual, verify } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { HttpError } from '../middleware/error-handler.js';
+const identifier = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,159}$/);
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const payloadFields = {
+    proposal_id: identifier, proposal_revision: z.number().int().positive(),
+    plan_sha256: digest, decision: z.enum(['approve', 'reject']), decision_id: identifier,
+    decided_at: z.number().int().positive(), expires_at: z.number().int().positive(),
+    actor_binding_sha256: digest, execution_id: identifier.nullable(),
+};
+function validateBinding(p, context) {
+    if ((p.decision === 'approve') !== (p.execution_id !== null))
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'Approval execution binding is invalid' });
+}
+const v2PayloadSchema = z.object({ version: z.literal(2), ...payloadFields }).strict().superRefine(validateBinding);
+const v3PayloadSchema = z.object({
+    version: z.literal(3), source_channel: z.enum(['telegram', 'iphone']), ...payloadFields,
+}).strict().superRefine(validateBinding);
+export const approvalPayloadSchema = z.union([v2PayloadSchema, v3PayloadSchema]);
+export const approvalAssertionSchema = z.object({ payload: approvalPayloadSchema,
+    signature: z.string().regex(/^[A-Za-z0-9_-]{86}$/) }).strict();
+/** Python ensure_ascii=True compatible canonical JSON; order is deliberate. */
+export function approvalCanonicalJson(value) {
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, char => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+export function approvalPayloadCanonical(p) {
+    return approvalCanonicalJson({ version: p.version, ...(p.version === 3 ? { source_channel: p.source_channel } : {}), proposal_id: p.proposal_id, proposal_revision: p.proposal_revision,
+        plan_sha256: p.plan_sha256, decision: p.decision, decision_id: p.decision_id, decided_at: p.decided_at,
+        expires_at: p.expires_at, actor_binding_sha256: p.actor_binding_sha256, execution_id: p.execution_id });
+}
+export function approvalDigest(value) { return createHash('sha256').update(approvalCanonicalJson(value)).digest('hex'); }
+export function verifyApprovalAssertion(raw) {
+    const parsed = approvalAssertionSchema.safeParse(raw);
+    const channel = parsed.success && parsed.data.payload.version === 3 ? parsed.data.payload.source_channel : 'telegram';
+    const actor = process.env[channel === 'iphone' ? 'APPROVAL_IPHONE_ACTOR_SHA256' : 'APPROVAL_TELEGRAM_ACTOR_SHA256'] ?? '';
+    if (!parsed.success || !/^[a-f0-9]{64}$/.test(actor))
+        throw new HttpError(403, 'APPROVAL_ASSERTION_REQUIRED', 'A configured, signed approval decision is required');
+    const { payload, signature } = parsed.data;
+    const canonical = approvalPayloadCanonical(payload);
+    let valid = false;
+    try {
+        const inline = process.env['APPROVAL_SIGNER_PUBLIC_KEY_PEM'];
+        const encoded = process.env['APPROVAL_SIGNER_PUBLIC_KEY_B64'];
+        const path = process.env['APPROVAL_SIGNER_PUBLIC_KEY_PATH'];
+        if (!inline && !encoded && !path)
+            throw new Error('missing key');
+        const key = createPublicKey(inline ?? (encoded
+            ? { key: Buffer.from(encoded, 'base64'), format: 'der', type: 'spki' }
+            : readFileSync(path, 'utf8')));
+        valid = key.asymmetricKeyType === 'ed25519' && verify(null, Buffer.from(`magnus.approval-assertion.v${payload.version}\n` + canonical), key, Buffer.from(signature, 'base64url'));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid || !timingSafeEqual(Buffer.from(actor, 'hex'), Buffer.from(payload.actor_binding_sha256, 'hex')))
+        throw new HttpError(403, 'APPROVAL_ASSERTION_INVALID', 'Approval decision authentication failed');
+    return { payload, assertionSha256: createHash('sha256').update(canonical + '\n' + signature).digest('hex') };
+}
+export function requireFreshApproval(p, now = Date.now()) {
+    if (p.decided_at > now + 30_000 || p.expires_at <= now || p.decided_at >= p.expires_at
+        || p.expires_at - p.decided_at > 15 * 60_000)
+        throw new HttpError(409, 'APPROVAL_ASSERTION_EXPIRED', 'Approval decision is expired or has an invalid lifetime');
+}
+//# sourceMappingURL=approval-assertion.js.map

package/dist/security/command-completion-registry.js

@@ -0,0 +1,35 @@
+/** Must remain byte-identical to the node command-completion registry. */
+import { createHash } from 'node:crypto';
+export const COMMAND_COMPLETION_REGISTRY = {
+    version: 1,
+    descriptors: [{
+            id: 'diagnostics-uptime-v1',
+            command: '/usr/bin/uptime',
+            args: [],
+            environment: {},
+            workingDirectory: null,
+            timeoutSeconds: 60,
+            resourceKeyPattern: '^node:[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$',
+            completionMode: 'supervised-cgroup-empty',
+            participantAuthority: {
+                allowedKinds: ['ssh-command'],
+                effectSemantics: 'read-only-node-diagnostic',
+                effectBoundary: 'bounded-node-process',
+            },
+        }],
+};
+export const COMMAND_COMPLETION_REGISTRY_SHA256 = createHash('sha256')
+    .update(JSON.stringify(COMMAND_COMPLETION_REGISTRY)).digest('hex');
+export function commandCompletionDescriptor(input) {
+    const environment = input.environment ?? {};
+    return COMMAND_COMPLETION_REGISTRY.descriptors.find(descriptor => input.command === descriptor.command
+        && JSON.stringify(input.args) === JSON.stringify(descriptor.args)
+        && (input.workingDirectory ?? null) === descriptor.workingDirectory
+        && JSON.stringify(Object.fromEntries(Object.entries(environment).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)))
+            === JSON.stringify(descriptor.environment)
+        && input.timeoutSeconds === descriptor.timeoutSeconds
+        && input.coordination?.version === 1
+        && new RegExp(descriptor.resourceKeyPattern).test(input.coordination.resourceKey)
+        && /^[1-9][0-9]{0,18}$/.test(input.coordination.fence));
+}
+//# sourceMappingURL=command-completion-registry.js.map

package/dist/security/command-request.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+// Canonical wire digest mirrored by the independently packaged node agent.
+// Cross-package fixtures guard compatibility without a runtime workspace import.
+export function commandRequestDigest(input) {
+    return createHash('sha256').update(JSON.stringify({ commandId: input.commandId, command: input.command, args: input.args,
+        workingDirectory: input.workingDirectory ?? null,
+        environment: Object.fromEntries(Object.entries(input.environment ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)),
+        timeoutSeconds: input.timeoutSeconds, coordination: input.coordination ? {
+            version: 1, resourceKey: input.coordination.resourceKey, fence: input.coordination.fence, expiresAt: input.coordination.expiresAt,
+        } : null })).digest('hex');
+}
+//# sourceMappingURL=command-request.js.map

package/dist/security/command-result-signature.js

@@ -0,0 +1,34 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+export function commandResultSigningPayload(result) {
+    return JSON.stringify({
+        version: result.completion ? 3 : result.coordination ? 2 : 1,
+        commandId: result.commandId,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        stdoutSha256: createHash('sha256').update(result.stdout).digest('hex'),
+        stderrSha256: createHash('sha256').update(result.stderr).digest('hex'),
+        truncated: result.truncated,
+        ...(result.coordination ? { coordination: {
+                version: result.coordination.version, resourceKey: result.coordination.resourceKey,
+                fence: result.coordination.fence, expiresAt: result.coordination.expiresAt,
+                requestSha256: result.coordination.requestSha256,
+            } } : {}),
+        ...(result.completion ? { completion: { registryVersion: result.completion.registryVersion,
+                registrySha256: result.completion.registrySha256, descriptorId: result.completion.descriptorId } } : {}),
+    });
+}
+export function verifyCommandResultSignature(result, activeSecret, previousSecret = '') {
+    if (activeSecret.length < 32 || !/^[a-f0-9]{64}$/i.test(result.signature))
+        return false;
+    const actual = Buffer.from(result.signature, 'hex');
+    const candidates = [activeSecret, ...(previousSecret.length >= 32 ? [previousSecret] : [])];
+    let matched = false;
+    for (const secret of candidates) {
+        const expected = createHmac('sha256', secret)
+            .update(commandResultSigningPayload(result))
+            .digest();
+        matched = (actual.length === expected.length && timingSafeEqual(actual, expected)) || matched;
+    }
+    return matched;
+}
+//# sourceMappingURL=command-result-signature.js.map