@elinpf/dsh-ops-access-k8s 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-access-k8s"
+description:
+  zh: "ops-access 的 Kubernetes 凭证 provider — 校验 k8s 注册表条目并在保存时探测权限"
+  en: "Kubernetes credential provider for ops-access — validates k8s registry entries and probes permissions at save time"

package/README.md

@@ -0,0 +1,39 @@
+# @elinpf/dsh-ops-access-k8s
+
+The Kubernetes credential-kind provider for the ops-access capability seam — validates `k8s` registry entries, expands kubeconfig paths, and probes real permissions at save time.
+
+## What it does
+
+One provider per credential kind is the ops-access split rule: this package carries everything Kubernetes-specific and nothing else. It registers an `AccessProvider` (`kind: 'k8s'`) into `ctx.opsAccess` via the core package's `registerAccessProvider` helper — an effect, so fiber disposal/HMR unregisters it.
+
+- **Zod entry schema**: `{ kubeconfig }` — one path per profile.
+- **Field processing**: `~` expansion; the resolved field is `kubeconfigPath` (paths only — secret material never passes through any service).
+- **Save-time paste guard** (`validateContent`): structural YAML validation — clusters/contexts/users present, and `current-context` must name a defined context (the ops tools never pass `--context`, so a stale current-context breaks every call at runtime; catch it at save time).
+- **Save-time capability probe** (`kubectl auth can-i`): read = `get pods`, write = `create deployments`. `ro` verifies when reading works and writing is denied; `rw` verifies when both work. Unreachable cluster or missing kubectl degrades to `unverifiable`, never a silent "no". Facet checks (`services/proxy`, `pods/exec`) annotate the result but never gate it — subresource can-i verdicts can be wrong.
+- **Agent-facing docs**: `fieldsDoc` and `derivationDoc` feed `list_access` help — the latter is the ro self-derivation recipe (ServiceAccount `<id>-ro` + view ClusterRole + long-lived token, verified in both directions).
+
+## Design notes
+
+- The provider is a plain data object (`provider` export); `apply` only binds the configured probe timeouts and registers it. The pure verdict function `assessK8sTier` is exported and unit-tested directly, so the can-i matrix logic never needs a live cluster in tests.
+- kubectl stderr is never surfaced — it echoes the kubeconfig path in its errors.
+
+## Configuration
+
+```yaml
+- id: ops-access-k8s
+  name: '@elinpf/dsh-ops-access-k8s'
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `probeTimeoutMs` | `10000` | Timeout per `kubectl auth can-i` call (ms). Slow clusters may need more. |
+| `probeNamespace` | `default` | Namespace the can-i probe checks permissions in. |
+
+## Testing
+
+```sh
+npm run build
+npx vitest run
+```
+
+Unit tests cover schema accept/reject, `~` expansion, registration/disposal through a mock `opsAccess` context (effect cleanup actually removes the provider), the paste guard, and the pure `assessK8sTier` verdict matrix. The one live-kubectl test asserts degradation to `unverifiable` against a nonexistent kubeconfig.

package/README.zh.md

@@ -0,0 +1,39 @@
+# @elinpf/dsh-ops-access-k8s
+
+ops-access 能力缝的 Kubernetes 凭证种类 provider — 校验 `k8s` 注册表条目、展开 kubeconfig 路径，并在保存时探测真实权限。
+
+## 功能
+
+按 ops-access 的拆分规则，一种凭证一个 provider：本包只装 Kubernetes 专属的东西。它通过 core 包的 `registerAccessProvider` 帮助函数向 `ctx.opsAccess` 注册一个 `AccessProvider`（`kind: 'k8s'`）——注册走 effect，fiber 销毁 / HMR 时自动卸载。
+
+- **zod 条目 schema**：`{ kubeconfig }` — 一个 profile 一个路径。
+- **字段处理**：`~` 展开；解析后输出 `kubeconfigPath`（只有路径 — 机密材料从不经过任何 service）。
+- **保存时粘贴守卫**（`validateContent`）：结构化 YAML 校验 — clusters/contexts/users 必须存在，且 `current-context` 必须指向已定义的 context（ops 工具从不传 `--context`，current-context 失效会让运行时每次调用都挂，必须在保存时拦住）。
+- **保存时能力探测**（`kubectl auth can-i`）：读 = `get pods`，写 = `create deployments`。`ro` 在能读且不能写时验证通过；`rw` 在两者都行时通过。集群不可达或没有 kubectl 时降级为 `unverifiable`，绝不静默当作 "no"。facet 检查（`services/proxy`、`pods/exec`）只做标注不做门槛 — 子资源的 can-i 判定可能不准。
+- **面向 agent 的文档**：`fieldsDoc` 和 `derivationDoc` 喂给 `list_access` 的 help — 后者是 ro 自助派生配方（ServiceAccount `<id>-ro` + view ClusterRole + 长效 token，双向验证）。
+
+## 设计要点
+
+- provider 是纯数据对象（`provider` 导出）；`apply` 只做一件事：绑定配置里的探测超时并注册。纯判定函数 `assessK8sTier` 单独导出、直接单测，因此 can-i 矩阵逻辑在测试里不需要真实集群。
+- kubectl 的 stderr 从不外抛 — 它的报错里会带出 kubeconfig 路径。
+
+## 配置项
+
+```yaml
+- id: ops-access-k8s
+  name: '@elinpf/dsh-ops-access-k8s'
+```
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `probeTimeoutMs` | `10000` | 每次 `kubectl auth can-i` 调用的超时（毫秒）。慢集群可调大。 |
+| `probeNamespace` | `default` | can-i 探测权限所用的 namespace。 |
+
+## 测试方式
+
+```sh
+npm run build
+npx vitest run
+```
+
+单测覆盖：schema 接受/拒绝、`~` 展开、经 mock `opsAccess` 上下文的注册/卸载（effect 清理会真正把 provider 移除）、粘贴守卫、以及纯函数 `assessK8sTier` 的判定矩阵。唯一的 live-kubectl 测试断言对不存在的 kubeconfig 会降级为 `unverifiable`。

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Ops access provider for Kubernetes.
+ *
+ * Validates `k8s` registry entries (`{ kubeconfig }`) and expands the
+ * kubeconfig path, exposing it as `kubeconfigPath`. Registers into the
+ * ops-access capability seam (ctx.opsAccess).
+ *
+ * @module @elinpf/dsh-ops-access-k8s
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import type { AccessProvider } from '@elinpf/dsh-ops-access';
+export declare const name = "ops-access-k8s";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    /** Save-time probe: timeout per `kubectl auth can-i` call (ms). Slow clusters may need more. */
+    probeTimeoutMs: z<number, number>;
+    /** Namespace the can-i probe checks permissions in. */
+    probeNamespace: z<string, string>;
+}>, Schemastery.ObjectT<{
+    /** Save-time probe: timeout per `kubectl auth can-i` call (ms). Slow clusters may need more. */
+    probeTimeoutMs: z<number, number>;
+    /** Namespace the can-i probe checks permissions in. */
+    probeNamespace: z<string, string>;
+}>>;
+/** Zod schema for one k8s registry entry (excluding name and envelope fields). */
+export declare const entrySchema: zod.ZodObject<{
+    kubeconfig: zod.ZodString;
+}, zod.core.$strip>;
+export declare const provider: AccessProvider;
+/**
+ * Pure tier assessment from the can-i matrix (unit-tested directly):
+ * read = can-i get pods, write = can-i create deployments. ro verifies when
+ * reading works and writing is denied; rw verifies when both work.
+ */
+export type { K8sProbeFacets } from './types.js';
+import type { K8sProbeFacets } from './types.js';
+export declare function assessK8sTier(read: boolean, write: boolean, tier: 'ro' | 'rw', facets?: K8sProbeFacets): {
+    status: 'verified' | 'mismatch';
+    detail?: string;
+};
+export declare function apply(ctx: Context, config: {
+    probeTimeoutMs: number;
+    probeNamespace: string;
+}): void;

package/lib/index.js

@@ -0,0 +1,149 @@
+/**
+ * Ops access provider for Kubernetes.
+ *
+ * Validates `k8s` registry entries (`{ kubeconfig }`) and expands the
+ * kubeconfig path, exposing it as `kubeconfigPath`. Registers into the
+ * ops-access capability seam (ctx.opsAccess).
+ *
+ * @module @elinpf/dsh-ops-access-k8s
+ */
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import { parse as parseYaml } from 'yaml';
+import { execFile } from 'node:child_process';
+import { expandHome, registerAccessProvider } from '@elinpf/dsh-ops-access';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-access-k8s';
+export const inject = [];
+export const Config = z.object({
+    /** Save-time probe: timeout per `kubectl auth can-i` call (ms). Slow clusters may need more. */
+    probeTimeoutMs: z.number().default(10000),
+    /** Namespace the can-i probe checks permissions in. */
+    probeNamespace: z.string().default('default'),
+});
+// ── Provider ─────────────────────────────────────────────────────────────────
+/** Zod schema for one k8s registry entry (excluding name and envelope fields). */
+export const entrySchema = zod.object({
+    kubeconfig: zod.string(),
+});
+export const provider = {
+    kind: 'k8s',
+    schema: entrySchema,
+    fieldsDoc: 'kubeconfig: path to the kubeconfig file (~ is expanded)',
+    fileFields: ['kubeconfig'],
+    derivationDoc: "from the rw kubeconfig: create a ServiceAccount named <id>-ro (naming convention), bind it to the built-in view ClusterRole (read-most, no Secret contents), mint a long-lived token via a Secret of type kubernetes.io/service-account-token for the SA (kubectl create token output expires); extract the cluster server and CA with kubectl config view --raw (without --raw the CA shows as DATA+OMITTED); build the ro kubeconfig reusing the rw cluster entry, naming both context and user <id>-ro and setting current-context to <id>-ro (kubectl cannot select a context without it); register it via register_access; then verify BOTH directions — kubectl get pods must succeed and a write attempt (e.g. kubectl create configmap ro-write-check --dry-run=server) must be forbidden. If every rw call fails with 'context was not found', the rw kubeconfig's current-context is broken — report it to the operator instead of working around it with --context",
+    process(entry) {
+        const { kubeconfig } = entry;
+        return { kubeconfigPath: expandHome(kubeconfig) };
+    },
+    // Save-time guard against corrupt pastes: a kubeconfig must be a YAML
+    // mapping with clusters, contexts, and users. Structural only — no
+    // connectivity checks.
+    // Ticket 10: verify the credential's real permissions at save time.
+    probe: probeK8s,
+    validateContent(field, content) {
+        if (field !== 'kubeconfig')
+            return null;
+        let doc;
+        try {
+            doc = parseYaml(content);
+        }
+        catch (err) {
+            const first = String(err?.message ?? err).split('\n')[0];
+            return `not valid YAML: ${first}`;
+        }
+        if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+            return 'not a YAML mapping — paste the full kubeconfig file';
+        }
+        const d = doc;
+        if (!Array.isArray(d.clusters) || d.clusters.length === 0)
+            return 'no clusters defined — paste the full kubeconfig file';
+        if (!Array.isArray(d.contexts) || d.contexts.length === 0)
+            return 'no contexts defined — paste the full kubeconfig file';
+        if (!Array.isArray(d.users) || d.users.length === 0)
+            return 'no users (credentials) defined — paste the full kubeconfig file';
+        // current-context must name a defined context: the ops kubectl tool
+        // never passes --context, so a missing or stale current-context breaks
+        // EVERY call at runtime ("no context currently selected" / "context was
+        // not found"). Catch it at save time instead.
+        const contextNames = d.contexts
+            .map((c) => (typeof c === 'object' && c !== null ? c.name : undefined))
+            .filter((n) => typeof n === 'string');
+        const current = d['current-context'];
+        if (typeof current !== 'string' || current === '') {
+            return `no current-context — kubectl cannot select a context without one (the ops tools do not pass --context). Defined contexts: ${contextNames.join(', ') || '(none)'}`;
+        }
+        if (!contextNames.includes(current)) {
+            return `current-context "${current}" does not match any defined context (defined: ${contextNames.join(', ') || '(none)'}) — fix it before saving`;
+        }
+        return null;
+    },
+};
+function fmtVerdict(v) {
+    return v === null ? 'unknown' : v ? 'yes' : 'no';
+}
+export function assessK8sTier(read, write, tier, facets) {
+    // Facets ANNOTATE, never gate: subresource can-i verdicts can be wrong
+    // (the ticket-14 pods/portforward quirk), so they ride along as facts.
+    const facetNote = facets === undefined ? undefined : 'facets: services/proxy=' + fmtVerdict(facets.servicesProxy) + ', pods/exec=' + fmtVerdict(facets.podsExec);
+    const join = (base) => [base, facetNote].filter(Boolean).join(' · ') || undefined;
+    if (tier === 'ro') {
+        if (read && !write)
+            return { status: 'verified', ...(facetNote === undefined ? {} : { detail: facetNote }) };
+        if (write)
+            return { status: 'mismatch', detail: join('claims ro but can-i create deployments = yes — an over-privileged credential sits in the ro slot') };
+        return { status: 'mismatch', detail: join('claims ro but can-i get pods = no — the credential cannot even read') };
+    }
+    if (read && write)
+        return { status: 'verified', ...(facetNote === undefined ? {} : { detail: facetNote }) };
+    return { status: 'mismatch', detail: join('claims rw but can-i says: get pods=' + (read ? 'yes' : 'no') + ', create deployments=' + (write ? 'yes' : 'no')) };
+}
+/**
+ * One can-i verdict: true/false from kubectl's answer, null when the check
+ * itself could not run (unreachable cluster, missing binary). stderr is
+ * never surfaced — kubectl echoes the kubeconfig path in its errors.
+ */
+function canI(kubeconfig, verb, resource, timeoutMs, namespace) {
+    return new Promise((resolve) => {
+        execFile('kubectl', ['--kubeconfig', kubeconfig, 'auth', 'can-i', verb, resource, '-n', namespace], { timeout: timeoutMs }, (err, stdout) => {
+            if (err && err.code === 'ENOENT') {
+                resolve(null);
+                return;
+            }
+            const answer = (stdout ?? '').trim().toLowerCase();
+            if (answer.startsWith('yes')) {
+                resolve(true);
+                return;
+            }
+            if (answer.startsWith('no')) {
+                resolve(false);
+                return;
+            }
+            // kubectl exits 1 with the verdict on stdout for 'no', but a
+            // connection failure produces no verdict at all. Any answer that
+            // is not a clean yes/no verdict means the check itself failed —
+            // unverifiable, never a silent 'no' (review fix).
+            resolve(null);
+        });
+    });
+}
+async function probeK8s(fields, tier, timeoutMs = 10000, namespace = 'default') {
+    const kubeconfig = String(fields.kubeconfigPath ?? '');
+    const [read, write, servicesProxy, podsExec] = await Promise.all([
+        canI(kubeconfig, 'get', 'pods', timeoutMs, namespace),
+        canI(kubeconfig, 'create', 'deployments', timeoutMs, namespace),
+        canI(kubeconfig, 'get', 'services/proxy', timeoutMs, namespace),
+        canI(kubeconfig, 'create', 'pods/exec', timeoutMs, namespace),
+    ]);
+    if (read === null || write === null) {
+        return { status: 'unverifiable', detail: 'kubectl auth can-i could not run (cluster unreachable or kubectl missing)' };
+    }
+    return assessK8sTier(read, write, tier, { servicesProxy, podsExec });
+}
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    registerAccessProvider(ctx, {
+        ...provider,
+        probe: (fields, tier) => probeK8s(fields, tier, config.probeTimeoutMs, config.probeNamespace),
+    });
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-access-k8s.
+ *
+ * @module @elinpf/dsh-ops-access-k8s/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-access-k8s-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,27 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-access-k8s.
+ *
+ * @module @elinpf/dsh-ops-access-k8s/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-access-k8s';
+/** Cordis companion plugin name. */
+const name = 'ops-access-k8s-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this provider owns no session event types and no
+ * durable shape of its own. It contributes one credential-kind validator
+ * (schema + field processing + save-time probe) to the ops-access registry;
+ * the registry file on disk is owned — and re-validated on every resolve —
+ * by @elinpf/dsh-ops-access.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };

package/lib/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for the ops-access-k8s plugin.
+ *
+ * Types only — no runtime values live here.
+ *
+ * @module @elinpf/dsh-ops-access-k8s/types
+ */
+/** Live verdicts for the operationally interesting faces (ticket 10); null = the check could not run. */
+export interface K8sProbeFacets {
+    servicesProxy: boolean | null;
+    podsExec: boolean | null;
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the ops-access-k8s plugin.
+ *
+ * Types only — no runtime values live here.
+ *
+ * @module @elinpf/dsh-ops-access-k8s/types
+ */
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@elinpf/dsh-ops-access-k8s",
+  "version": "0.1.0",
+  "description": "Ops access provider for Kubernetes — validates k8s registry entries and expands kubeconfig paths.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "yaml": "^2.7.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@elinpf/dsh-ops-access": "^0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@types/node": "^22.0.0",
+    "@elinpf/dsh-ops-access": "0.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}