@knowttl/kubernetes-axi 0.0.0-stage → 0.1.0

package/dist/hosted-session.js

@@ -0,0 +1,201 @@
+import { Ajv } from 'ajv';
+import { createHash } from 'node:crypto';
+import { mkdir, open, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, posix, relative } from 'node:path';
+import { identity, validateEnvironment } from './credentials.js';
+import { Failure } from './errors.js';
+import { parse } from './grammar.js';
+import { preview } from './mutations.js';
+import { Redactor } from './redaction.js';
+import { readCluster } from './runner.js';
+import { readWorkspaceTar, relativeFile, workspaceTar } from './workspace-tar.js';
+const valid = new Ajv().compile({ type: 'object', additionalProperties: false, required: ['action'], properties: {
+        action: { enum: ['start', 'confirm'] },
+        args: { type: 'array', maxItems: 256, items: { type: 'string', maxLength: 8192 } },
+        digest: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+        stdinBase64: { type: 'string', maxLength: 4 * Math.ceil(100 * 1024 * 1024 / 3), pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' },
+        inputFile: { const: 'stdin.bin' },
+        timeoutMs: { type: 'integer', minimum: 1, maximum: 1800000 },
+    } });
+// A host-owned IPC worker keeps preview state and injected identity in one
+// private call directory. It has no network listener or ambient identity route.
+if (!process.send)
+    throw new Failure('PRIVATE_CHANNEL_REQUIRED', 'Launch bounded sessions through the authenticated host.');
+const send = async (message) => new Promise((resolve, reject) => {
+    if (!process.connected) {
+        reject(new Failure('CANCELLED', 'The host disconnected.'));
+        return;
+    }
+    process.send(message, undefined, undefined, (error) => error ? reject(error) : resolve());
+});
+const redactor = new Redactor();
+const controller = new AbortController();
+let busy = false;
+let started = false;
+let request;
+let expectedDigest;
+let input = Buffer.alloc(0);
+let timeoutMs = 300000;
+let selection;
+let copying;
+let downloadPath = '';
+let remoteName = '';
+let forwarding = false;
+let forwardingOutput = '';
+const forwards = new Map();
+const artifact = [];
+let artifactBytes = 0;
+const run = async (invocation) => {
+    await send({ event: 'running' });
+    const output = await readCluster(selection, invocation, redactor, { input, signal: controller.signal, timeoutMs,
+        ...(forwarding ? { controlStdout: true } : {}),
+        output: async (channel, bytes) => {
+            if (forwarding && channel === 'stdout') {
+                forwardingOutput += bytes.toString('utf8');
+                if (Buffer.byteLength(forwardingOutput) > 65536)
+                    throw new Failure('OUTPUT_LIMIT', 'Port forwarding diagnostics exceeded their bound.');
+                let newline;
+                while ((newline = forwardingOutput.indexOf('\n')) >= 0) {
+                    const line = forwardingOutput.slice(0, newline);
+                    forwardingOutput = forwardingOutput.slice(newline + 1);
+                    const match = /^Forwarding from 127\.0\.0\.1:([0-9]+) -> ([0-9]+)$/.exec(line);
+                    if (match) {
+                        forwards.set(Number(match[2]), Number(match[1]));
+                        await send({ event: 'ports', ports: [...forwards].map(([remote, local]) => ({ remote, local })) });
+                    }
+                }
+                return;
+            }
+            if (copying === 'download' && channel === 'stdout') {
+                artifactBytes += bytes.length;
+                if (artifactBytes > 250 * 1024 * 1024 + 102400)
+                    throw new Failure('TRANSFER_LIMIT', 'The artifact exceeds the workspace byte limit.');
+                artifact.push(bytes);
+            }
+            else
+                await send({ event: 'output', channel, base64: bytes.toString('base64') });
+        },
+    });
+    const native = output;
+    if (copying === 'download' && native.exitCode === 0) {
+        const files = readWorkspaceTar(Buffer.concat(artifact));
+        const manifest = [];
+        for (const file of files) {
+            if (file.path !== remoteName && !file.path.startsWith(remoteName + '/'))
+                throw new Failure('PATH_REFUSED', 'The archive does not match the selected container path.');
+            const name = downloadPath + file.path.slice(remoteName.length);
+            const path = join(process.env.TMPDIR, 'artifacts', name);
+            await mkdir(posix.dirname(path), { recursive: true, mode: 0o700 });
+            await writeFile(path, file.bytes, { mode: 0o600, flag: 'wx' });
+            manifest.push({ path: name, bytes: file.bytes.length, sha256: createHash('sha256').update(file.bytes).digest('hex') });
+        }
+        await send({ event: 'artifacts', files: manifest });
+    }
+    if (!native.native)
+        await send({ event: 'result', value: redactor.value(output) });
+    await send({ event: 'exit', exitCode: native.exitCode ?? Number(process.exitCode ?? 0), stdoutEOF: true, stderrEOF: true });
+    process.disconnect();
+};
+process.on('disconnect', () => { controller.abort(); });
+process.on('SIGTERM', () => { controller.abort(); });
+process.on('SIGINT', () => { controller.abort(); });
+process.on('message', (raw) => {
+    void (async () => {
+        if (!valid(raw))
+            throw new Failure('USAGE', 'The session message is invalid.', 2);
+        if (busy)
+            throw new Failure('USAGE', 'Wait for the current session operation.', 2);
+        busy = true;
+        if (raw.action === 'start') {
+            if (started || !raw.args)
+                throw new Failure('USAGE', 'Start a session once with ordered arguments.', 2);
+            started = true;
+            validateEnvironment();
+            timeoutMs = raw.timeoutMs ?? timeoutMs;
+            input = Buffer.from(raw.stdinBase64 ?? '', 'base64');
+            if (raw.inputFile) {
+                if (raw.stdinBase64 !== undefined)
+                    throw new Failure('USAGE', 'Select one session input channel.', 2);
+                const file = await open(join(process.env.TMPDIR, raw.inputFile), constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const info = await file.stat();
+                    if (!info.isFile() || info.size > 100 * 1024 * 1024)
+                        throw new Failure('TRANSFER_LIMIT', 'The input artifact exceeds the regular-file limit.');
+                    input = await file.readFile();
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            let args = raw.args;
+            if (args[0] === 'prepare' && args[1] === '--' && args[2] === 'cp') {
+                const cp = args.slice(3);
+                if (cp.length !== 2)
+                    throw new Failure('USAGE', 'Use cp <workspace-path> <pod:/absolute-path> or cp <pod:/absolute-path> <workspace-path>.', 2);
+                const from = cp[0];
+                const to = cp[1];
+                const remote = /^(?:([a-z0-9][a-z0-9.-]*)\/)?([a-z0-9][a-z0-9.-]*):\/(.+)$/;
+                const source = remote.exec(from);
+                const destination = remote.exec(to);
+                if (Boolean(source) === Boolean(destination))
+                    throw new Failure('USAGE', 'Copy between one workspace path and one named container path.', 2);
+                const selected = source ?? destination;
+                const path = relativeFile(selected[3]);
+                copying = source ? 'download' : 'upload';
+                const workspace = join(process.env.TMPDIR, 'workspace');
+                const local = source && to.startsWith('artifact:') ? to.slice('artifact:'.length) : relative(workspace, source ? to : from).split(posix.sep).join('/');
+                relativeFile(local);
+                remoteName = posix.basename(path);
+                downloadPath = local;
+                if (copying === 'upload')
+                    input = await workspaceTar(workspace, local, remoteName);
+                else if (input.length)
+                    throw new Failure('USAGE', 'A copy download accepts no stdin.', 2);
+                args = ['prepare', '--', 'exec', selected[2], ...(selected[1] ? ['--namespace', selected[1]] : []), ...(copying === 'upload' ? ['-i'] : []), '--', 'tar', copying === 'upload' ? 'xf' : 'cf', '-', '-C', '/' + posix.dirname(path), ...(copying === 'download' ? ['--', posix.basename(path)] : [])];
+            }
+            const invocation = parse(args, true);
+            forwarding = invocation.command.path === 'port-forward';
+            if (input.length)
+                invocation.inputSha256 = createHash('sha256').update(input).digest('hex');
+            if (invocation.nativeConfig || invocation.trustExec || invocation.config || invocation.profile || invocation.help)
+                throw new Failure('USAGE', 'Sessions use only the host-selected profile.', 2);
+            if (!['exec', 'attach', 'logs', 'get', 'port-forward'].includes(invocation.command.path) && invocation.command.effect !== 'clusterWrite')
+                throw new Failure('CAPABILITY_UNAVAILABLE', 'This command is outside the bounded session contract.');
+            selection = await identity();
+            redactor.register(selection.secret, selection.profile.clientCertificate);
+            if (invocation.workflow?.kind === 'prepare') {
+                const prepared = await readCluster(selection, invocation, redactor, { input, signal: controller.signal,
+                    timeoutMs: 15000, output: async () => { },
+                });
+                request = prepared.request;
+                const displayed = await preview(parse(['preview', request]));
+                expectedDigest = displayed.digest;
+                await send({ event: 'prepared', preview: redactor.value(displayed) });
+            }
+            else {
+                if (invocation.workflow)
+                    throw new Failure('USAGE', 'Start with prepare or a bounded read.', 2);
+                invocation.native = true;
+                await run(invocation);
+            }
+        }
+        else {
+            if (!request || !raw.digest || raw.digest !== expectedDigest)
+                throw new Failure('PREVIEW_MISMATCH', 'Confirm the exact session preview digest.');
+            const invocation = parse(['confirm', request, '--digest', raw.digest]);
+            request = undefined;
+            await run(invocation);
+        }
+        busy = false;
+    })().catch(async (error) => {
+        controller.abort();
+        const failure = error instanceof Failure ? error : new Failure('UPSTREAM_FAILED', 'The bounded session failed.');
+        if (process.connected) {
+            await send({ event: 'failed', code: failure.code, message: failure.message }).catch(() => { });
+            if (process.connected)
+                process.disconnect();
+        }
+        process.exitCode = 1;
+    });
+});

package/dist/metadata-pin.d.ts

@@ -0,0 +1,3 @@
+export declare const metadataSha256 = "b7ff45e522f0aa9b6d16b861cfcbf9414786b1f999bede2dcb1f628949c4fc49";
+export declare const executionLimit = "In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects. Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts. Bounded noninteractive execution and existing hosted bounded sessions remain supported. Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35.";
+export declare const guidance = "Read Kubernetes resources using isolated credentials and pinned kubectl v1.32.2.\nUse --profile <name> to select an AXI identity.\nUse native -- <kubectl arguments> for native output; native --profile is upstream profiling and is blocked because it writes files.\nReads are bounded; inspect complete, truncated and continue before treating output as complete.\nWrites default off. Explicitly enable KUBERNETES_AXI_READ_ONLY=false, then use prepare -- <mutation>, preview <request-key>, and confirm <request-key> --digest <preview-digest>.\nPreparation reads exact targets; local preview makes no API calls. Confirmation is one-shot and refuses stale or changed targets. Bulk deletion also requires KUBERNETES_AXI_COLLECTION_DELETE=true.\nUse server-dry-run -- <mutation> for explicit API validation without persistence.\nExec/attach and named debug mutations require preparation and confirmation. In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects. Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts. Bounded noninteractive execution and existing hosted bounded sessions remain supported. Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35. Native Windows support remains pending. Token issuance additionally requires KUBERNETES_AXI_ACQUIRE_CREDENTIAL=true, a duration of at most one hour, and --credential-fd <inherited-private-pipe> before confirm. Issued tokens are delivered once and never retained. Hosted workspace transfer, byte sessions, followed logs, watches and multi-port forwarding use caller-owned authenticated Artium sessions. In 0.1.x, run editors, plugins and external render/diff helpers outside the CLI, then prepare the resulting manifest or patch and confirm its preview. Their execution inside the CLI is refused before effects. Generic proxy listeners and credential overrides remain refused. Native completion, options, plugin list and version --client=true work without credentials.\nIn 0.1.x, run diff and its external helpers outside the CLI. Submit resulting changes through prepare, preview and confirm.\nRun kubernetes-axi --help for available commands and kubernetes-axi native -- <command> --help for generated upstream flags.\n";

package/dist/metadata-pin.js

@@ -0,0 +1,4 @@
+// Generated by scripts/generate-metadata.ts.
+export const metadataSha256 = 'b7ff45e522f0aa9b6d16b861cfcbf9414786b1f999bede2dcb1f628949c4fc49';
+export const executionLimit = "In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects. Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts. Bounded noninteractive execution and existing hosted bounded sessions remain supported. Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35.";
+export const guidance = "Read Kubernetes resources using isolated credentials and pinned kubectl v1.32.2.\nUse --profile <name> to select an AXI identity.\nUse native -- <kubectl arguments> for native output; native --profile is upstream profiling and is blocked because it writes files.\nReads are bounded; inspect complete, truncated and continue before treating output as complete.\nWrites default off. Explicitly enable KUBERNETES_AXI_READ_ONLY=false, then use prepare -- <mutation>, preview <request-key>, and confirm <request-key> --digest <preview-digest>.\nPreparation reads exact targets; local preview makes no API calls. Confirmation is one-shot and refuses stale or changed targets. Bulk deletion also requires KUBERNETES_AXI_COLLECTION_DELETE=true.\nUse server-dry-run -- <mutation> for explicit API validation without persistence.\nExec/attach and named debug mutations require preparation and confirmation. In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects. Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts. Bounded noninteractive execution and existing hosted bounded sessions remain supported. Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35. Native Windows support remains pending. Token issuance additionally requires KUBERNETES_AXI_ACQUIRE_CREDENTIAL=true, a duration of at most one hour, and --credential-fd <inherited-private-pipe> before confirm. Issued tokens are delivered once and never retained. Hosted workspace transfer, byte sessions, followed logs, watches and multi-port forwarding use caller-owned authenticated Artium sessions. In 0.1.x, run editors, plugins and external render/diff helpers outside the CLI, then prepare the resulting manifest or patch and confirm its preview. Their execution inside the CLI is refused before effects. Generic proxy listeners and credential overrides remain refused. Native completion, options, plugin list and version --client=true work without credentials.\nIn 0.1.x, run diff and its external helpers outside the CLI. Submit resulting changes through prepare, preview and confirm.\nRun kubernetes-axi --help for available commands and kubernetes-axi native -- <command> --help for generated upstream flags.\n";

package/dist/mutations.d.ts

@@ -0,0 +1,11 @@
+import type { Invocation } from './grammar.js';
+import type { Redactor } from './redaction.js';
+export declare function preview(invocation: Invocation): Promise<object>;
+export declare function mutationSession(configFile: string, invocation: Invocation, namespace: string, redactor: Redactor, signal: AbortSignal, compatibleVersion: (value: unknown) => void, nativeBinding?: string): Promise<{
+    config: object;
+    argv?: string[];
+    rawPath?: string;
+    prepared?: boolean;
+    finish: (success?: boolean) => Promise<object>;
+    close: () => Promise<void>;
+}>;