@knowttl/kubernetes-axi 0.0.0-stage → 0.1.0

package/dist/protobuf.d.ts

@@ -0,0 +1 @@
+export declare function decodeKubernetes(bytes: Buffer): unknown;

package/dist/protobuf.js

@@ -0,0 +1,67 @@
+import protobuf from 'protobufjs';
+import { protobufSchema } from './protobuf-schema.js';
+import { Failure } from './errors.js';
+const root = protobuf.Root.fromJSON(protobufSchema).resolveAll();
+const envelopeType = root.lookupType('k8s.io.apimachinery.pkg.runtime.Unknown');
+const groups = { v1: 'core.v1', 'apps/v1': 'apps.v1', 'certificates.k8s.io/v1': 'certificates.v1', 'authorization.k8s.io/v1': 'authorization.v1',
+    'authentication.k8s.io/v1': 'authentication.v1', 'autoscaling/v1': 'autoscaling.v1', 'autoscaling/v2': 'autoscaling.v2', 'policy/v1': 'policy.v1',
+    'rbac.authorization.k8s.io/v1': 'rbac.v1', 'batch/v1': 'batch.v1', 'networking.k8s.io/v1': 'networking.v1', 'scheduling.k8s.io/v1': 'scheduling.v1' };
+function normalize(type, message) {
+    const value = type.toObject(message, { longs: Number, bytes: String });
+    const name = type.fullName.split('.').at(-1);
+    if (name === 'Quantity' || name === 'QuantityValue')
+        return value.string ?? '0';
+    if (name === 'IntOrString')
+        return Number(value.type ?? 0) === 0 ? value.intVal ?? 0 : value.strVal ?? '';
+    if (name === 'Time' || name === 'MicroTime') {
+        if (!Object.hasOwn(value, 'seconds'))
+            return null;
+        const seconds = Number(value.seconds);
+        const nanos = Number(value.nanos ?? 0).toString().padStart(9, '0').replace(/0+$/, '');
+        return new Date(seconds * 1000).toISOString().replace('.000Z', `${nanos ? `.${nanos}` : ''}Z`);
+    }
+    if (name === 'RawExtension' || name === 'FieldsV1') {
+        const raw = name === 'FieldsV1' ? value.Raw : value.raw;
+        return raw ? JSON.parse(Buffer.from(String(raw), 'base64').toString()) : {};
+    }
+    if (name === 'ExtraValue')
+        return value.items ?? [];
+    const result = {};
+    for (const field of type.fieldsArray) {
+        if (!Object.hasOwn(value, field.name))
+            continue;
+        const original = message[field.name];
+        if (field.resolvedType instanceof protobuf.Type) {
+            const nested = field.resolvedType;
+            value[field.name] = field.map ? Object.fromEntries(Object.entries(original).map(([key, item]) => [key, normalize(nested, item)])) :
+                field.repeated ? original.map(item => normalize(nested, item)) : normalize(nested, original);
+        }
+        else if (typeof value[field.name] === 'number' && !Number.isSafeInteger(value[field.name]))
+            throw new Failure('UPSTREAM_INVALID', 'The protobuf body contains an integer outside the exact JSON range.');
+        const jsonName = field.getOption('kubernetesJsonName');
+        if (jsonName === undefined)
+            throw new Failure('PROTOBUF_UNSUPPORTED', 'The protobuf field has no pinned JSON contract.');
+        if (jsonName === '')
+            Object.assign(result, value[field.name]);
+        else if (jsonName !== '-')
+            result[jsonName] = value[field.name];
+    }
+    return result;
+}
+export function decodeKubernetes(bytes) {
+    if (!bytes.subarray(0, 4).equals(Buffer.from('k8s\0')))
+        throw new Failure('PROTOBUF_INVALID', 'Expected the Kubernetes protobuf envelope.');
+    const envelope = envelopeType.decode(bytes.subarray(4));
+    const version = envelope.typeMeta?.apiVersion ?? '';
+    const kind = envelope.typeMeta?.kind ?? '';
+    if (!groups[version] || !/^[A-Z][A-Za-z0-9]+$/.test(kind) || !envelope.raw || envelope.contentEncoding || envelope.contentType && envelope.contentType !== 'application/vnd.kubernetes.protobuf')
+        throw new Failure('PROTOBUF_UNSUPPORTED', 'The protobuf type or encoding is outside the pinned schemas; no request was forwarded.');
+    let type;
+    try {
+        type = root.lookupType(`k8s.io.api.${groups[version]}.${kind}`);
+    }
+    catch {
+        throw new Failure('PROTOBUF_UNSUPPORTED', 'Unknown Kubernetes protobuf type; no request was forwarded.');
+    }
+    return { ...normalize(type, type.decode(envelope.raw)), apiVersion: version, kind };
+}

package/dist/redaction.d.ts

@@ -0,0 +1,10 @@
+export declare class Redactor {
+    private readonly forms;
+    register(...secrets: (string | undefined)[]): void;
+    text(value: string): string;
+    value(data: unknown): unknown;
+    byteStream(): {
+        push: (bytes: Buffer) => Buffer;
+        end: () => Buffer;
+    };
+}

package/dist/redaction.js

@@ -0,0 +1,50 @@
+export class Redactor {
+    forms = new Set();
+    register(...secrets) {
+        for (const secret of secrets)
+            if (secret) {
+                const json = JSON.stringify(secret).slice(1, -1);
+                const goJson = json.replace(/[<>&\u2028\u2029]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+                const formEncoded = new URLSearchParams({ value: secret }).toString().slice('value='.length);
+                for (const form of [secret, json, goJson, encodeURIComponent(secret), formEncoded, Buffer.from(secret).toString('base64')]) {
+                    this.forms.add(form);
+                    this.forms.add(JSON.stringify(form).slice(1, -1));
+                }
+            }
+    }
+    text(value) {
+        for (const form of [...this.forms].sort((a, b) => b.length - a.length))
+            value = value.split(form).join('[REDACTED]');
+        return value.replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, '[REDACTED]')
+            .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED]')
+            .replace(/("(?:token|password|clientSecret|privateKey|client-key-data|authorization)"\s*:\s*)"(?:\\.|[^"\\])*"/gi, '$1"[REDACTED]"')
+            .replace(/^(\s*(?:token|password|clientSecret|privateKey|client-key-data|authorization)\s*:\s*).+$/gmi, '$1[REDACTED]')
+            .replace(/(?:AccountKey=|sig=)[^&\s]+/gi, '[REDACTED]');
+    }
+    value(data) {
+        if (typeof data === 'string')
+            return this.text(data);
+        if (Array.isArray(data))
+            return data.map(value => this.value(value));
+        if (data !== null && typeof data === 'object')
+            return Object.fromEntries(Object.entries(data).map(([key, value]) => [this.text(key), /^(token|password|clientSecret|privateKey|client-key-data|authorization)$/i.test(key) ? '[REDACTED]' : this.value(value)]));
+        return data;
+    }
+    byteStream() {
+        const patterns = [...this.forms].map(form => Buffer.from(form));
+        const hold = Math.max(0, ...patterns.map(pattern => pattern.length - 1));
+        let pending = Buffer.alloc(0);
+        return {
+            push: bytes => {
+                pending = Buffer.concat([pending, bytes]);
+                if (patterns.some(pattern => pending.includes(pattern)))
+                    throw new Error('protected binary output');
+                const count = Math.max(0, pending.length - hold);
+                const safe = Buffer.from(pending.subarray(0, count));
+                pending = Buffer.from(pending.subarray(count));
+                return safe;
+            },
+            end: () => { const safe = pending; pending = Buffer.alloc(0); return safe; },
+        };
+    }
+}

package/dist/remote-session.d.ts

@@ -0,0 +1,22 @@
+export interface RemoteConfig {
+    'current-context'?: string;
+    clusters: {
+        cluster: {
+            server: string;
+            'certificate-authority-data': string;
+            'tls-server-name'?: string;
+        };
+    }[];
+    users: {
+        user: {
+            token?: string;
+            'client-certificate-data'?: string;
+            'client-key-data'?: string;
+            exec?: object;
+        };
+    }[];
+}
+export declare function remoteSession(config: RemoteConfig, namespace: string, target: string, route: string, query: string, signal: AbortSignal): Promise<{
+    config: object;
+    close: () => Promise<void>;
+}>;

package/dist/remote-session.js

@@ -0,0 +1,90 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { request } from 'node:https';
+import { Failure } from './errors.js';
+// Only the frozen pod and command can be reached, with credentials held by the parent.
+export async function remoteSession(config, namespace, target, route, query, signal) {
+    const cluster = config.clusters[0].cluster;
+    const user = config.users[0].user;
+    if (user.exec)
+        throw new Failure('CAPABILITY_UNAVAILABLE', 'Helper-backed execution requires a reviewed containment boundary.');
+    const capability = randomBytes(32).toString('hex');
+    const sockets = new Set();
+    const server = createServer();
+    server.on('upgrade', (incoming, downstream, head) => {
+        const url = new URL(incoming.url, 'http://local');
+        const expected = new URLSearchParams(query);
+        const actual = new URLSearchParams(url.search);
+        expected.sort();
+        actual.sort();
+        if (!['GET', 'POST'].includes(incoming.method) || url.pathname !== `/${capability}${route}` || expected.toString() !== actual.toString()) {
+            downstream.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        sockets.add(downstream);
+        downstream.once('close', () => sockets.delete(downstream));
+        const call = request(cluster.server.replace(/\/$/, '') + route + url.search, {
+            method: incoming.method, signal, ca: Buffer.from(cluster['certificate-authority-data'], 'base64'),
+            ...(cluster['tls-server-name'] ? { servername: cluster['tls-server-name'] } : {}),
+            ...(user['client-certificate-data'] ? { cert: Buffer.from(user['client-certificate-data'], 'base64') } : {}),
+            ...(user['client-key-data'] ? { key: Buffer.from(user['client-key-data'], 'base64') } : {}),
+            headers: { ...incoming.headers, host: new URL(cluster.server).host, ...(user.token ? { authorization: `Bearer ${user.token}` } : {}) },
+        });
+        call.on('upgrade', (reply, upstream, upstreamHead) => {
+            sockets.add(upstream);
+            upstream.once('close', () => sockets.delete(upstream));
+            upstream.once('error', () => downstream.destroy());
+            downstream.once('close', () => upstream.destroy());
+            downstream.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(reply.headers).map(([name, value]) => `${name}: ${Array.isArray(value) ? value.join(', ') : value}`).join('\r\n')}\r\n\r\n`);
+            if (upstreamHead.length)
+                downstream.write(upstreamHead);
+            if (head.length)
+                upstream.write(head);
+            downstream.pipe(upstream).pipe(downstream);
+        });
+        call.on('response', reply => {
+            // A rejected WebSocket handshake must reach kubectl so it can try SPDY.
+            downstream.end(`HTTP/1.1 ${reply.statusCode} Rejected\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+            reply.resume();
+        });
+        call.on('error', () => downstream.destroy());
+        downstream.once('close', () => call.destroy());
+        call.setTimeout(5000, () => call.destroy());
+        call.end();
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Failure('CONFIG_INVALID', 'Cannot open the bounded execution channel.');
+    const close = async () => {
+        for (const socket of sockets)
+            socket.destroy();
+        server.closeAllConnections();
+        await new Promise(resolve => server.close(() => resolve()));
+    };
+    signal.addEventListener('abort', () => { for (const socket of sockets)
+        socket.destroy(); }, { once: true });
+    // Native kubectl still reads its target pod before opening the stream.
+    server.removeAllListeners('request');
+    server.on('request', (incoming, response) => {
+        const path = incoming.url?.startsWith(`/${capability}/`) ? incoming.url.slice(capability.length + 1) : '';
+        const pathname = path.split('?')[0];
+        const discovery = /^\/(?:api(?:\/v[0-9]+)?|apis(?:\/[a-z0-9.-]+\/v[0-9]+(?:(?:alpha|beta)[0-9]+)?)?)$/.test(pathname);
+        if (incoming.method !== 'GET' || !(pathname === target || discovery)) {
+            response.writeHead(403).end();
+            return;
+        }
+        const call = request(cluster.server.replace(/\/$/, '') + path, {
+            ca: Buffer.from(cluster['certificate-authority-data'], 'base64'), signal,
+            ...(cluster['tls-server-name'] ? { servername: cluster['tls-server-name'] } : {}),
+            ...(user['client-certificate-data'] ? { cert: Buffer.from(user['client-certificate-data'], 'base64') } : {}),
+            ...(user['client-key-data'] ? { key: Buffer.from(user['client-key-data'], 'base64') } : {}),
+            headers: { accept: 'application/json', ...(user.token ? { authorization: `Bearer ${user.token}` } : {}) },
+        }, reply => { response.writeHead(reply.statusCode ?? 502, { 'content-type': 'application/json' }); reply.pipe(response); });
+        call.on('error', () => response.destroy());
+        call.setTimeout(5000, () => call.destroy());
+        call.end();
+    });
+    return { config: { apiVersion: 'v1', kind: 'Config', clusters: [{ name: 'selected', cluster: { server: `http://127.0.0.1:${address.port}/${capability}` } }],
+            users: [{ name: 'selected', user: {} }], contexts: [{ name: 'selected', context: { cluster: 'selected', user: 'selected', namespace } }], 'current-context': 'selected' }, close };
+}

package/dist/route-policy.d.ts

@@ -0,0 +1 @@
+export declare function routeEffect(method: string, path: string): 'read' | 'clusterWrite' | 'execution' | 'connection' | 'credentials';

package/dist/route-policy.js

@@ -0,0 +1,19 @@
+import { Failure } from './errors.js';
+export function routeEffect(method, path) {
+    if (!path.startsWith('/') || /\.\.|\/\/|%2f|%2e|%5c|\\/i.test(path))
+        throw new Failure('EFFECT_UNCLASSIFIED', 'Use an unambiguous absolute Kubernetes API route.');
+    const url = new URL(path, 'http://local');
+    if (/\/(?:proxy|portforward)(?:\/|$)/.test(url.pathname))
+        return 'connection';
+    if (/\/(?:exec|attach)(?:\/|$)/.test(url.pathname))
+        return 'execution';
+    if (/\/token(?:\/|$)/.test(url.pathname))
+        return 'credentials';
+    if (['watch', 'follow'].some(name => url.searchParams.has(name) && !/^(false|0)$/i.test(url.searchParams.get(name))) || /^\/api(?:s)?\/[^?]*\/watch\//.test(url.pathname))
+        return 'connection';
+    if (!['GET', 'HEAD'].includes(method))
+        return 'clusterWrite';
+    if (/^\/(?:version|api|apis)$/.test(url.pathname) || /^\/(?:api\/v[0-9]+|apis\/[a-z0-9.-]+\/v[0-9]+(?:(?:alpha|beta)[0-9]+)?)(?:\/(?:namespaces\/[a-z0-9.-]+\/)?[a-z0-9.-]+(?:\/[a-z0-9.-]+(?:\/(?:log|status|scale))?)?)?$/.test(url.pathname))
+        return 'read';
+    throw new Failure('EFFECT_UNCLASSIFIED', 'The raw route has no reviewed effect classification.');
+}

package/dist/runner.d.ts

@@ -0,0 +1,11 @@
+import type { Identity } from './credentials.js';
+import type { Invocation } from './grammar.js';
+import type { Redactor } from './redaction.js';
+import { type ByteExecution } from './byte-process.js';
+export interface NativeOutput {
+    native: true;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function readCluster(identity: Identity | undefined, invocation: Invocation, redactor: Redactor, byteExecution?: ByteExecution): Promise<object | NativeOutput>;