chore(audit): execute 2026-06-05 (0914) audit — enforce no-as contract, dead-component guard, release-workflow least-privilege (#127)

* fix(ci): drop unused id-token:write from release workflows

Add github-actions-permissions guardrail flagging id-token: write with no OIDC consumer (cosign/sigstore or cloud OIDC auth), comment-scrubbed so a 'reserved for future' note can't mask it. Remove the reserved-but-unused grant from both release workflows.

Audit: F004

* fix(ui): make useFormField guards fire before context is consumed

Both form contexts default to {} (truthy), so the old !fieldContext guard never fired and ran after fieldContext.name was already used. Guard on .name/.id before consuming them, and add the missing <FormItem> guard.

Audit: F002

* fix(ui): validate API boundaries + enforce a real no-`as` ban repo-wide

Boundary parsers no longer trust casts: openapi error bodies validate `message` and copy only well-typed fields; the SSE parser uses a type-guard (no `as`).

The UI's `consistent-type-assertions` was set to assertionStyle "as" — which only enforces syntax, not a ban — so the merge-bar 'no `as`' contract was silently unenforced (the API uses "never"). Pinned the UI to "never", removed every production cast (logger mask, cursor pageParams via typed constants, Uint8Array web-push key, JSON.parse guards, and a sound Path<TForm> match in applyServerErrors), and relaxed only test files (documented, beside the existing no-unsafe-* test relaxations).

Added a lint-meta guardrail `eslint-ban-type-assertions` to BOTH apps: it fails if a config weakens assertionStyle away from "never" or disables the rule without an audited eslint-meta-allow-assertion-exemption marker — the anti-drift rule that would have caught the original gap. Exhaustively unit-tested.

Audit: F003

* fix(docs): add dead-component guard, delete 7 unused components

apps/docs had no dead-code detection (knip's Astro/MDX entry graph is brittle to configure). Added a source-level check-unused-components.mjs — the equivalent of the knip step api/ui run — wired into build:ci. It flagged 7 unreferenced components (the audit's manual grep had found only 4): DocFileTree, FaqGroup, FaqItem, and docs-kit's CommandRun/FeatureGrid/PageIntro/SignalGrid. All deleted; build:ci green.

Audit: F001

Author: agjs

.github/workflows/apps-api-release.yml

@@ -23,8 +23,6 @@ concurrency:
 permissions:
   contents: read
   packages: write
-  # Reserved for future cosign keyless signing; harmless when unused.
-  id-token: write
 
 jobs:
   build-and-push:

.github/workflows/apps-ui-release.yml

@@ -28,8 +28,6 @@ permissions:
   contents: write
   pull-requests: write
   packages: write
-  # Reserved for future cosign keyless signing.
-  id-token: write
 
 jobs:
   release:

apps/api/eslint.config.js

@@ -1241,7 +1241,7 @@ export default tseslint.config(
     // cast is at the storage boundary.
     files: ["src/lib/cache/providers/*.ts"],
     rules: {
-      "@typescript-eslint/consistent-type-assertions": "off",
+      "@typescript-eslint/consistent-type-assertions": "off", // eslint-meta-allow-assertion-exemption: generic <T> cache storage boundary
     },
   },
   {

apps/api/scripts/lint-meta/RULES.md

@@ -22,6 +22,7 @@ import { checkDependencyPairs } from "./rules/supply-chain/no-overlapping-libs";
 import { checkExactDependencyVersions } from "./rules/supply-chain/package-json-exact-deps";
 import { checkPackageOverrideParity } from "./rules/supply-chain/package-override-parity";
 import { checkSharedToolVersionParity } from "./rules/supply-chain/shared-tool-version-parity";
+import { checkEslintBanTypeAssertions } from "./rules/config/eslint-ban-type-assertions";
 import { checkEslintConfigNoWarn } from "./rules/config/eslint-config-no-warn";
 import { checkEslintOverridePathsExist } from "./rules/config/eslint-override-paths-exist";
 import { checkEslintPluginContractParity } from "./rules/config/eslint-plugin-contract-parity";
@@ -111,6 +112,7 @@ export {
   checkEnginePinParity,
   checkExactDependencyVersions,
   checkExternalClientTimeouts,
+  checkEslintBanTypeAssertions,
   checkEslintConfigNoWarn,
   checkEslintOverridePathsExist,
   checkEslintPluginContractParity,

apps/api/scripts/lint-meta/cli.ts

@@ -9,6 +9,7 @@ import { githubActionsServiceImageDigestPinRule } from "./rules/ci/github-action
 import { githubActionsTimeoutRequiredRule } from "./rules/ci/github-actions-timeout-required";
 import { prePushCiParityRule } from "./rules/ci/pre-push-ci-parity";
 import { tofuBootstrapHardeningRule } from "./rules/ci/tofu-bootstrap-hardening";
+import { eslintBanTypeAssertionsRule } from "./rules/config/eslint-ban-type-assertions";
 import { eslintConfigNoWarnRule } from "./rules/config/eslint-config-no-warn";
 import { eslintPluginContractParityRule } from "./rules/config/eslint-plugin-contract-parity";
 import { eslintOverridePathsExistRule } from "./rules/config/eslint-override-paths-exist";
@@ -60,6 +61,7 @@ export const META_RULES: readonly IMetaRule[] = [
   skippedTestsNeedTrackingRule,
   touchTestsTooRule,
   eslintConfigNoWarnRule,
+  eslintBanTypeAssertionsRule,
   eslintOverridePathsExistRule,
   tsconfigIncludePathsExistRule,
   eslintPluginContractParityRule,

apps/api/scripts/lint-meta/registry.ts

@@ -4,9 +4,30 @@ import type { IMetaRule, IViolation } from "../../types";
 
 const SHA_REGEX = /^[0-9a-f]{40}$/u;
 
+const ID_TOKEN_WRITE_REGEX = /^[ \t]*id-token:[ \t]*write\b/mu;
+
+/*
+ * `id-token: write` only does anything when a step exchanges the OIDC token —
+ * keyless signing (cosign/sigstore) or cloud OIDC auth. Granting it with no
+ * consumer hands every step in the job a needless token-minting capability.
+ * This allowlist names the consumers we recognise; extend it when adding a new
+ * OIDC integration so least-privilege stays enforced for template consumers.
+ */
+const OIDC_CONSUMER_REGEX =
+  /cosign|sigstore|configure-aws-credentials|google-github-actions\/auth|azure\/login|vault-action|ACTIONS_ID_TOKEN_REQUEST/iu;
+
+/*
+ * Drop YAML comments so a "reserved for future cosign" note can't masquerade
+ * as a real OIDC consumer.
+ */
+function stripYamlComments(text: string): string {
+  return text.replace(/(^|[ \t])#.*$/gmu, "");
+}
+
 export function checkWorkflowShas(file: string): IViolation[] {
   const violations: IViolation[] = [];
   const text = readFileSync(file, "utf8");
+  const scrubbed = stripYamlComments(text);
 
   if (!/^permissions\s*:/mu.test(text)) {
     violations.push({
@@ -16,6 +37,18 @@ export function checkWorkflowShas(file: string): IViolation[] {
     });
   }
 
+  if (
+    ID_TOKEN_WRITE_REGEX.test(scrubbed) &&
+    !OIDC_CONSUMER_REGEX.test(scrubbed)
+  ) {
+    violations.push({
+      file,
+      rule: "github-actions-permissions",
+      message:
+        "`id-token: write` is granted but no OIDC consumer (cosign/sigstore signing or cloud OIDC auth) uses it — drop the permission until a step needs it (least privilege).",
+    });
+  }
+
   const usesRegex = /^\s*-?\s*uses:\s*([^\s#]+)/gmu;
   let match: RegExpExecArray | null = usesRegex.exec(text);
 

apps/api/scripts/lint-meta/rules/ci/github-actions-permissions.ts

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { IMetaRule, IViolation } from "../../types";
+
+const RULE_ID = "eslint-ban-type-assertions";
+const CONFIG_NAMES = [
+  "eslint.config.mjs",
+  "eslint.config.js",
+  "eslint.config.mts",
+  "eslint.config.cjs",
+];
+const RULE_NAME = "@typescript-eslint/consistent-type-assertions";
+const EXEMPTION_MARKER = "eslint-meta-allow-assertion-exemption";
+
+/*
+ * `assertionStyle: "as" | "angle-bracket"` only enforces *which syntax* an
+ * assertion uses — it still permits them. Only "never" bans `as` outright.
+ * A config that drifts to "as" silently re-opens the hole (this is the exact
+ * bug that once let casts ship: the UI rule was set to "as", not "never").
+ */
+const ASSERTION_STYLE_RE =
+  /assertionStyle\s*:\s*["'](never|as|angle-bracket)["']/gu;
+const RULE_OFF_RE =
+  /["']@typescript-eslint\/consistent-type-assertions["']\s*:\s*["']off["']/u;
+
+// Strip a trailing line comment so a marker can't satisfy the style/off match.
+function stripLineComment(raw: string): string {
+  return raw.replace(/\/\/.*$/u, "");
+}
+
+function hasNeverPin(lines: readonly string[]): boolean {
+  return lines.some((raw) =>
+    [...stripLineComment(raw).matchAll(ASSERTION_STYLE_RE)].some(
+      (match) => match[1] === "never"
+    )
+  );
+}
+
+function lineViolations(
+  file: string,
+  raw: string,
+  lineNo: number
+): IViolation[] {
+  const out: IViolation[] = [];
+  const code = stripLineComment(raw);
+
+  for (const match of code.matchAll(ASSERTION_STYLE_RE)) {
+    if (match[1] !== "never") {
+      out.push({
+        file,
+        rule: RULE_ID,
+        message: `Line ${String(lineNo)}: \`assertionStyle: "${match[1] ?? ""}"\` still permits \`as\` casts — pin it to "never". A weaker style silently re-opens the type-assertion hole.`,
+      });
+    }
+  }
+
+  // The marker must sit on the same line as the off (raw still has comments).
+  if (RULE_OFF_RE.test(code) && !raw.includes(EXEMPTION_MARKER)) {
+    out.push({
+      file,
+      rule: RULE_ID,
+      message: `Line ${String(lineNo)}: \`${RULE_NAME}\` is disabled without justification — add \`// ${EXEMPTION_MARKER}: <reason>\` on the same line to sanction a genuine, audited type-boundary exemption.`,
+    });
+  }
+
+  return out;
+}
+
+function checkConfigFile(file: string): IViolation[] {
+  const lines = readFileSync(file, "utf8").split("\n");
+  const violations = lines.flatMap((raw, i) =>
+    lineViolations(file, raw, i + 1)
+  );
+
+  if (!hasNeverPin(lines)) {
+    violations.push({
+      file,
+      rule: RULE_ID,
+      message: `${file}: \`${RULE_NAME}\` must be pinned to \`assertionStyle: "never"\`. The no-\`as\` rule is a core merge-bar contract and must be enforced explicitly, never assumed.`,
+    });
+  }
+
+  return violations;
+}
+
+export function checkEslintBanTypeAssertions(root: string): IViolation[] {
+  return CONFIG_NAMES.map((name) => join(root, name))
+    .filter((full) => existsSync(full))
+    .flatMap(checkConfigFile);
+}
+
+/**
+ * Guards the guard: the no-`as` merge-bar contract is only real while the
+ * ESLint rule that enforces it stays pinned to `assertionStyle: "never"`. Fails
+ * if a config weakens the style or disables the rule without an audited
+ * `eslint-meta-allow-assertion-exemption` marker.
+ */
+export const eslintBanTypeAssertionsRule: IMetaRule = {
+  id: RULE_ID,
+  category: "config",
+  description:
+    'ESLint must pin @typescript-eslint/consistent-type-assertions to assertionStyle "never"; disabling it requires an audited eslint-meta-allow-assertion-exemption marker.',
+  run({ root }) {
+    return checkEslintBanTypeAssertions(root);
+  },
+};

apps/api/scripts/lint-meta/rules/config/eslint-ban-type-assertions.ts

@@ -0,0 +1,11 @@
+name: unused-id-token
+on: push
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: echo build

apps/api/tests/lint-meta/fixtures/workflows-id-token-unused/ci.yml

@@ -0,0 +1,11 @@
+name: used-id-token
+on: push
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  sign:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: cosign sign --yes "$IMAGE"