@intentius/chant-lexicon-k3s 0.44.3

package/src/lint/post-synth/k3s103.ts

@@ -0,0 +1,38 @@
+/**
+ * K3S103: an agent that joins nothing.
+ *
+ * An agent config without `server` is a node with no cluster to join —
+ * `k3s agent` refuses to start without it (or K3S_URL in the service
+ * environment). Declaring the agent while leaving the join out of band
+ * defeats the declaration, so this asks for it in the config.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { entitiesOfType } from "./k3s-helpers";
+
+export const k3s103: PostSynthCheck = {
+  id: "K3S103",
+  description: "An agent config declares no server to join",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const entity of entitiesOfType(ctx, "K3s::Agent")) {
+      const server = entity.props.server;
+      if (typeof server === "string" && server.length > 0) continue;
+      diagnostics.push({
+        checkId: "K3S103",
+        severity: "error",
+        message:
+          `"${entity.name}" declares no \`server\` — the agent has no cluster to join. ` +
+          "Set `server: https://<server-host>:6443` in the declaration.",
+        entity: entity.name,
+        lexicon: "k3s",
+      });
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/k3s104.ts

@@ -0,0 +1,44 @@
+/**
+ * K3S104: kubeconfig written wider than 0644.
+ *
+ * `write-kubeconfig-mode` widens /etc/rancher/k3s/k3s.yaml — the file
+ * carrying the cluster's admin credential. k3s's own default is 0600;
+ * 0644 is the documented convenience for a single-user host. Anything
+ * granting write to group/other, or beyond read to other, hands the
+ * admin kubeconfig to every local account.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { entitiesOfType } from "./k3s-helpers";
+
+export const k3s104: PostSynthCheck = {
+  id: "K3S104",
+  description: "write-kubeconfig-mode is wider than 0644",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+      const raw = entity.props["write-kubeconfig-mode"];
+      if (raw === undefined) continue;
+      const mode = parseInt(String(raw), 8);
+      if (Number.isNaN(mode)) continue;
+      // Bits outside rw-r--r-- mean group/other write, or execute anywhere.
+      if ((mode & ~0o644) !== 0) {
+        diagnostics.push({
+          checkId: "K3S104",
+          severity: "warning",
+          message:
+            `"${entity.name}" sets write-kubeconfig-mode ${String(raw)} — wider than 0644. ` +
+            "The kubeconfig carries the cluster admin credential; keep it 0600, or 0644 at most.",
+          entity: entity.name,
+          lexicon: "k3s",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/k3s105.ts

@@ -0,0 +1,52 @@
+/**
+ * K3S105: a registry mirror that skips TLS verification.
+ *
+ * `insecure_skip_verify: true` in registries.yaml turns every image pull
+ * through that registry into an unauthenticated trust decision. Legitimate
+ * for a lab pull-through cache; worth a flag anywhere, because the estate
+ * that sets it for the lab keeps it when the registry moves.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { entitiesOfType } from "./k3s-helpers";
+
+export const k3s105: PostSynthCheck = {
+  id: "K3S105",
+  description: "registries.yaml disables TLS verification for a registry",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const entity of entitiesOfType(ctx, "K3s::Registries")) {
+      const configs = entity.props.configs;
+      if (typeof configs !== "object" || configs === null) continue;
+      for (const [registry, config] of Object.entries(configs as Record<string, unknown>)) {
+        const tls = resolveProps(resolveProps(config)?.tls);
+        if (tls?.insecure_skip_verify === true) {
+          diagnostics.push({
+            checkId: "K3S105",
+            severity: "warning",
+            message:
+              `"${entity.name}" disables TLS verification for registry "${registry}" — ` +
+              "every pull through it is unauthenticated. Pin the registry CA via `ca_file` instead.",
+            entity: entity.name,
+            lexicon: "k3s",
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};
+
+function resolveProps(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.props === "object" && obj.props !== null && "entityType" in obj) {
+    return obj.props as Record<string, unknown>;
+  }
+  return obj;
+}

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { k3s101 } from "./k3s101";
+import { k3s102 } from "./k3s102";
+import { k3s103 } from "./k3s103";
+import { k3s104 } from "./k3s104";
+import { k3s105 } from "./k3s105";
+
+function makeCtx(entities: Record<string, { entityType: string; props: Record<string, unknown> }>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities: new Map(Object.entries(entities)),
+  } as unknown as PostSynthContext;
+}
+
+describe("K3S101: literal secret in a config entity", () => {
+  test("flags a literal token on a server", () => {
+    const diags = k3s101.check(
+      makeCtx({ cp: { entityType: "K3s::Server", props: { token: "hunter2" } } }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S101");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("flags an etcd S3 secret key", () => {
+    const diags = k3s101.check(
+      makeCtx({ cp: { entityType: "K3s::Server", props: { "etcd-s3-secret-key": "shh" } } }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("passes token-file and an agent token on the agent side", () => {
+    const diags = k3s101.check(
+      makeCtx({
+        cp: { entityType: "K3s::Server", props: { "token-file": "/etc/rancher/k3s/token" } },
+        worker: { entityType: "K3s::Agent", props: { server: "https://cp:6443", "token-file": "/t" } },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("K3S102: literal registry credential", () => {
+  test("flags a literal password", () => {
+    const diags = k3s102.check(
+      makeCtx({
+        registries: {
+          entityType: "K3s::Registries",
+          props: { configs: { "registry.example.com": { auth: { username: "u", password: "p" } } } },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S102");
+  });
+
+  test("passes username-only auth and TLS file paths", () => {
+    const diags = k3s102.check(
+      makeCtx({
+        registries: {
+          entityType: "K3s::Registries",
+          props: {
+            configs: { "registry.example.com": { auth: { username: "u" }, tls: { ca_file: "/ca" } } },
+          },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("K3S103: agent with no server", () => {
+  test("flags an agent that joins nothing", () => {
+    const diags = k3s103.check(makeCtx({ worker: { entityType: "K3s::Agent", props: {} } }));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S103");
+  });
+
+  test("passes an agent with a server, and ignores servers entirely", () => {
+    const diags = k3s103.check(
+      makeCtx({
+        worker: { entityType: "K3s::Agent", props: { server: "https://cp:6443" } },
+        cp: { entityType: "K3s::Server", props: {} },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("K3S104: kubeconfig mode wider than 0644", () => {
+  test("flags 0666", () => {
+    const diags = k3s104.check(
+      makeCtx({ cp: { entityType: "K3s::Server", props: { "write-kubeconfig-mode": "0666" } } }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("passes 0600, 0644, and an unset mode", () => {
+    const diags = k3s104.check(
+      makeCtx({
+        a: { entityType: "K3s::Server", props: { "write-kubeconfig-mode": "0600" } },
+        b: { entityType: "K3s::Server", props: { "write-kubeconfig-mode": "0644" } },
+        c: { entityType: "K3s::Server", props: {} },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("K3S105: TLS verification disabled for a registry", () => {
+  test("flags insecure_skip_verify", () => {
+    const diags = k3s105.check(
+      makeCtx({
+        registries: {
+          entityType: "K3s::Registries",
+          props: { configs: { "registry.example.com": { tls: { insecure_skip_verify: true } } } },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S105");
+  });
+
+  test("passes a pinned CA", () => {
+    const diags = k3s105.check(
+      makeCtx({
+        registries: {
+          entityType: "K3s::Registries",
+          props: { configs: { "registry.example.com": { tls: { ca_file: "/ca" } } } },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/index.ts

@@ -0,0 +1,7 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { tokenLiteralRule } from "./token-literal";
+
+export { tokenLiteralRule } from "./token-literal";
+
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules: LintRule[] = [tokenLiteralRule];

package/src/lint/rules/token-literal.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "vitest";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { tokenLiteralRule } from "./token-literal";
+
+function createContext(code: string, fileName = "cluster.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: fileName };
+}
+
+describe("K3S001: literal join token", () => {
+  test("flags a literal token inside new Server(...)", () => {
+    const diags = tokenLiteralRule.check(
+      createContext(`const s = new Server({ "cluster-init": true, token: "K10abc::server:secret" });`),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("K3S001");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("flags a quoted agent-token key inside Agent(...)", () => {
+    const diags = tokenLiteralRule.check(
+      createContext(`const a = Agent({ server: "https://cp:6443", "agent-token": \`secret\` });`),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag token-file", () => {
+    const diags = tokenLiteralRule.check(
+      createContext(`const s = new Server({ "token-file": "/etc/rancher/k3s/token" });`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a non-literal token", () => {
+    const diags = tokenLiteralRule.check(
+      createContext(`const s = new Server({ token: readTokenSomehow() });`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag tokens outside Server/Agent constructions", () => {
+    const diags = tokenLiteralRule.check(
+      createContext(`const config = { token: "not-k3s's-business" };`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag an empty literal", () => {
+    const diags = tokenLiteralRule.check(createContext(`const s = new Server({ token: "" });`));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/token-literal.ts

@@ -0,0 +1,87 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * K3S001: literal join token in source.
+ *
+ * `token` / `agent-token` are the cluster's shared join secret, and a
+ * committed config declaration is exactly the file that leaks it. The
+ * typed surface deliberately carries only the reference forms
+ * (`token-file`, `agent-token-file` — #1601), but nothing stops a raw
+ * object literal from writing the key anyway; this rule does.
+ *
+ * Flags a non-empty string-literal `token` / `agent-token` (identifier or
+ * quoted) inside a `Server(...)` / `Agent(...)` construction, with or
+ * without `new`. A bare `token:` elsewhere in the file is someone else's
+ * business.
+ */
+export const tokenLiteralRule: LintRule = {
+  id: "K3S001",
+  severity: "error",
+  category: "security",
+  description: "k3s join token declared as a string literal in source",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const flag = (node: ts.Node, key: string) => {
+      const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+      diagnostics.push({
+        ruleId: "K3S001",
+        severity: "error",
+        message:
+          `\`${key}\` is a literal in source — a committed k3s config is a leaked cluster join ` +
+          "secret. Point `token-file` at a path on the host, or supply K3S_TOKEN_FILE at " +
+          "install time; the value itself never belongs in the declaration.",
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+      });
+    };
+
+    const tokenLiteral = (
+      obj: ts.ObjectLiteralExpression,
+    ): { node: ts.Node; key: string } | undefined => {
+      for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const name = ts.isIdentifier(prop.name)
+          ? prop.name.text
+          : ts.isStringLiteral(prop.name)
+            ? prop.name.text
+            : undefined;
+        if (name !== "token" && name !== "agent-token") continue;
+        if (
+          (ts.isStringLiteral(prop.initializer) ||
+            ts.isNoSubstitutionTemplateLiteral(prop.initializer)) &&
+          prop.initializer.text.length > 0
+        ) {
+          return { node: prop.initializer, key: name };
+        }
+      }
+      return undefined;
+    };
+
+    const visit = (node: ts.Node) => {
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        const callee = node.expression;
+        const name = ts.isIdentifier(callee)
+          ? callee.text
+          : ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : undefined;
+        if (name === "Server" || name === "Agent") {
+          const arg = node.arguments?.[0];
+          if (arg && ts.isObjectLiteralExpression(arg)) {
+            const literal = tokenLiteral(arg);
+            if (literal) flag(literal.node, literal.key);
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("LSP completions", () => {
+  it("returns an array", () => {
+    // TODO: Replace with a real CompletionContext
+    const result = completions({} as any);
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,25 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import {
+  LexiconIndex,
+  lexiconCompletions,
+  type LexiconEntry,
+} from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-k3s.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide k3s completions based on context — Server, Agent, Registries and
+ * the registry property entities, from the generated registry.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "k3s entity");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("LSP hover", () => {
+  it("returns undefined for unknown context", () => {
+    // TODO: Replace with a real HoverContext
+    const result = hover({} as any);
+    expect(result).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,43 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import {
+  LexiconIndex,
+  lexiconHover,
+  type LexiconEntry,
+} from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-k3s.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for k3s entity types.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`k3s type: \`${entry.resourceType}\``);
+  lines.push("");
+  if (entry.kind === "resource") {
+    lines.push(
+      "*Resource entity — serialized as a file k3s consumes verbatim: " +
+        "config.yaml for Server/Agent, registries.yaml for Registries*",
+    );
+  } else {
+    lines.push("*Property entity — a nested value in a Registries declaration*");
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/package-cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-k3s.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(dirname(pkgDir), "dist");
+writeBundleSpec(spec, distDir);
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { k3sPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("k3s plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(k3sPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(k3sPlugin.name).toBe("k3s");
+  });
+
+  it("has a serializer", () => {
+    expect(k3sPlugin.serializer).toBeDefined();
+  });
+});