feat: add auth broker p0 skeleton

scripts/auth-broker-contract-test.ts

@@ -1,4 +1,5 @@
-import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 
 type RunnerDisposition = "ready" | "infra-blocked" | "business-failed";
 
@@ -11,6 +12,9 @@ interface FailureContract {
 
 const docPath = "docs/reference/auth-broker.md";
 const doc = readFileSync(docPath, "utf8");
+const rustMainPath = "src/components/microservices/auth-broker/src/main.rs";
+const rustCargoPath = "src/components/microservices/auth-broker/Cargo.toml";
+const cliAdapterPath = "scripts/src/auth-broker.ts";
 
 function assertCondition(condition: unknown, message: string, detail: unknown = {}): void {
   if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
@@ -20,6 +24,44 @@ function assertDocContains(text: string): void {
   assertCondition(doc.includes(text), `missing auth broker doc text: ${text}`);
 }
 
+function runCli(args: string[], env: Record<string, string | undefined> = {}): Promise<{ status: number | null; stdout: string; stderr: string; json: Record<string, unknown> | null }> {
+  const childEnv = { ...process.env, ...env };
+  delete childEnv.GH_TOKEN;
+  delete childEnv.GITHUB_TOKEN;
+  delete childEnv.UNIDESK_AUTH_BROKER_URL;
+  delete childEnv.AUTH_BROKER_URL;
+  if (env.GH_TOKEN !== undefined) childEnv.GH_TOKEN = env.GH_TOKEN;
+  if (env.GITHUB_TOKEN !== undefined) childEnv.GITHUB_TOKEN = env.GITHUB_TOKEN;
+  if (env.UNIDESK_AUTH_BROKER_URL !== undefined) childEnv.UNIDESK_AUTH_BROKER_URL = env.UNIDESK_AUTH_BROKER_URL;
+  if (env.AUTH_BROKER_URL !== undefined) childEnv.AUTH_BROKER_URL = env.AUTH_BROKER_URL;
+  return new Promise((resolve, reject) => {
+    const child = spawn("bun", ["scripts/cli.ts", ...args], {
+      cwd: process.cwd(),
+      env: childEnv,
+    });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    child.stdout.on("data", (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on("error", reject);
+    child.on("close", (status) => {
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      let json: Record<string, unknown> | null = null;
+      try {
+        json = JSON.parse(stdout) as Record<string, unknown>;
+      } catch {
+        json = null;
+      }
+      resolve({ status, stdout, stderr: Buffer.concat(stderrChunks).toString("utf8"), json });
+    });
+  });
+}
+
+function dataOf(response: Record<string, unknown>): Record<string, unknown> {
+  assertCondition(typeof response.data === "object" && response.data !== null && !Array.isArray(response.data), "CLI response data should be object", response);
+  return response.data as Record<string, unknown>;
+}
+
 const requiredOperations = [
   "github.auth.status",
   "github.issue.list",
@@ -109,12 +151,15 @@ function walk(value: unknown, path: string[] = []): void {
   }
 }
 
-function main(): void {
+async function main(): Promise<void> {
   for (const heading of ["## Existing Paths", "## API", "## Permission Boundary", "## Audit Fields", "## Failure Semantics", "## D601 Dev Acceptance"]) {
     assertDocContains(heading);
   }
   for (const path of [
     "scripts/src/gh.ts",
+    "scripts/src/auth-broker.ts",
+    "src/components/microservices/auth-broker/Cargo.toml",
+    "src/components/microservices/auth-broker/src/main.rs",
     "scripts/code-queue-pr-preflight-example.ts",
     "src/components/microservices/code-queue/src/runtime-preflight.ts",
     "scripts/src/code-queue.ts",
@@ -138,9 +183,68 @@ function main(): void {
   assertCondition(samplePreflightResponse.prCapabilityContract.preflightMergesPr === false, "P0 preflight must not merge PRs", samplePreflightResponse.prCapabilityContract);
   walk(samplePreflightResponse);
 
+  for (const path of [rustCargoPath, rustMainPath, cliAdapterPath]) {
+    assertCondition(existsSync(path), `required auth broker implementation file is missing: ${path}`);
+  }
+  const rustMain = readFileSync(rustMainPath, "utf8");
+  const cliAdapter = readFileSync(cliAdapterPath, "utf8");
+  assertCondition(rustMain.includes("GET") && rustMain.includes("/health"), "Rust skeleton should expose GET /health", rustMainPath);
+  assertCondition(rustMain.includes("/v1/github/gh"), "Rust skeleton should expose credential-request endpoint", rustMainPath);
+  assertCondition(rustMain.includes("/v1/github/pr-preflight"), "Rust skeleton should expose pr-preflight endpoint", rustMainPath);
+  assertCondition(rustMain.includes("credential_value_printed: false"), "audit event must force credentialValuePrinted=false", rustMainPath);
+  assertCondition(!rustMain.includes("GH_TOKEN") && !rustMain.includes("GITHUB_TOKEN"), "Rust skeleton must not read runner token env keys", rustMainPath);
+  assertCondition(cliAdapter.includes("valuesRead: false") && cliAdapter.includes("valuesPrinted: false"), "CLI adapter must declare secret values unread/unprinted", cliAdapterPath);
+  assertCondition(cliAdapter.includes("broker-needed") && cliAdapter.includes("auth-missing"), "CLI adapter must expose broker-needed/auth-missing shape", cliAdapterPath);
+
+  const noToken = await runCli(["auth-broker", "pr-preflight", "--repo", "pikasTech/unidesk", "--base", "master", "--head", "feature/auth-broker", "--issue", "59", "--dry-run"]);
+  assertCondition(noToken.status === 1, "missing broker endpoint should exit 1", { status: noToken.status, stdout: noToken.stdout, stderr: noToken.stderr });
+  assertCondition(noToken.json?.ok === false, "missing token response envelope should fail", noToken.json);
+  const noTokenData = dataOf(noToken.json ?? {});
+  assertCondition(noTokenData.failureKind === "auth-missing", "missing token should classify as auth-missing", noTokenData);
+  assertCondition(noTokenData.degradedReason === "broker-needed", "missing token should classify as broker-needed", noTokenData);
+  assertCondition(noTokenData.brokerNeeded === true, "missing token should set brokerNeeded", noTokenData);
+  assertCondition(!noToken.stdout.includes("contract-secret-marker"), "missing-token response must not leak secret marker strings", noToken.stdout);
+
+  const brokerReady = await runCli([
+    "auth-broker",
+    "pr-preflight",
+    "--repo",
+    "pikasTech/unidesk",
+    "--base",
+    "master",
+    "--head",
+    "feature/auth-broker",
+    "--issue",
+    "59",
+    "--dry-run",
+    "--endpoint",
+    "http://user:pass@127.0.0.1:4291?credential=abc",
+  ]);
+  assertCondition(brokerReady.status === 0, "configured broker dry-run should exit 0", { status: brokerReady.status, stdout: brokerReady.stdout, stderr: brokerReady.stderr });
+  assertCondition(brokerReady.json?.ok === true, "configured broker dry-run envelope should succeed", brokerReady.json);
+  const readyData = dataOf(brokerReady.json ?? {});
+  const tokenCoverage = readyData.tokenCoverage as Record<string, unknown>;
+  const brokerCoverage = readyData.brokerCoverage as Record<string, unknown>;
+  const prCapability = readyData.prCapabilityContract as Record<string, unknown>;
+  const brokerProxy = prCapability.brokerProxy as Record<string, unknown>;
+  assertCondition(tokenCoverage.source === "auth-broker", "ready token coverage should come from broker", tokenCoverage);
+  assertCondition(tokenCoverage.runnerEnvTokenRequired === false, "ready token coverage should not require runner env token", tokenCoverage);
+  assertCondition(tokenCoverage.valuesPrinted === false, "ready token coverage must not print values", tokenCoverage);
+  assertCondition(String(brokerCoverage.endpoint).includes("http://***:***@127.0.0.1:4291/?..."), "endpoint should be sanitized", brokerCoverage);
+  assertCondition(prCapability.targetBranch === "master", "P0 capability should preserve target branch", prCapability);
+  assertCondition(prCapability.preflightCreatesPr === false && prCapability.preflightMergesPr === false, "P0 PR preflight must not write or merge", prCapability);
+  assertCondition(brokerProxy.writesRemote === false, "P0 broker proxy should not write remote", brokerProxy);
+  assertCondition(Array.isArray(brokerProxy.operations) && brokerProxy.operations.includes("github.pr.create"), "P0 broker proxy should include PR create dry-run operation", brokerProxy);
+  walk(readyData);
+
   process.stdout.write(`${JSON.stringify({
     ok: true,
     docPath,
+    implementation: {
+      rustMainPath,
+      rustCargoPath,
+      cliAdapterPath,
+    },
     operations: requiredOperations,
     failureKinds: failureContracts.map((item) => item.failureKind),
     p0Safety: {
@@ -152,4 +256,7 @@ function main(): void {
   }, null, 2)}\n`);
 }
 
-main();
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

scripts/cli.ts

@@ -18,6 +18,7 @@ import { ciHelp, runCiCommand } from "./src/ci";
 import { runSwapCommand } from "./src/swap";
 import { runDevEnvCommand } from "./src/dev-env";
 import { runArtifactRegistryCommand } from "./src/artifact-registry";
+import { runAuthBrokerCommand } from "./src/auth-broker";
 import { runGhCommand } from "./src/gh";
 import { runCommanderCommand } from "./src/commander";
 import { isHelpToken, rootHelp, serverHelp, sshHelp, staticNamespaceHelp } from "./src/help";
@@ -182,6 +183,14 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (top === "auth-broker") {
+    const result = runAuthBrokerCommand(args.slice(1));
+    const ok = (result as { ok?: unknown }).ok !== false;
+    emitJson(commandName, result, ok);
+    if (!ok) process.exitCode = 1;
+    return;
+  }
+
   if (top === "gh") {
     const result = await runGhCommand(args.slice(1));
     const ok = (result as { ok?: unknown }).ok !== false;

scripts/src/auth-broker.ts

@@ -0,0 +1,295 @@
+const DEFAULT_REPO = "pikasTech/unidesk";
+const DEFAULT_BASE = "master";
+const SECRET_ENV_KEYS = ["GH_TOKEN", "GITHUB_TOKEN"] as const;
+const BROKER_URL_ENV_KEYS = ["UNIDESK_AUTH_BROKER_URL", "AUTH_BROKER_URL"] as const;
+const DEFAULT_CAPABILITIES = [
+  "github.auth.status",
+  "github.issue.list",
+  "github.issue.read",
+  "github.pr.list",
+  "github.pr.read",
+  "github.pr.create",
+  "github.pr.comment.create",
+  "github.pr.preflight.dry-run",
+] as const;
+
+type BrokerCommand = "contract" | "credential-request" | "pr-preflight" | "health";
+type RunnerDisposition = "ready" | "infra-blocked" | "business-failed";
+
+interface BrokerAdapterOptions {
+  command: BrokerCommand;
+  repo: string;
+  operation: string;
+  dryRun: boolean;
+  endpoint: string | null;
+  base: string;
+  head: string;
+  issueNumber: number | null;
+}
+
+function hasEnvKey(name: string): boolean {
+  return Object.prototype.hasOwnProperty.call(process.env, name);
+}
+
+function stringOption(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (value === undefined || value.length === 0) throw new Error(`${name} requires a non-empty value`);
+  return value;
+}
+
+function sanitizeEndpoint(value: string): string {
+  try {
+    const parsed = new URL(value);
+    if (parsed.username.length > 0) parsed.username = "***";
+    if (parsed.password.length > 0) parsed.password = "***";
+    if (parsed.search.length > 0) parsed.search = "?...";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return value.includes("?") ? `${value.split("?")[0]}?...` : value;
+  }
+}
+
+function numberOption(args: string[], name: string): number | null {
+  const raw = stringOption(args, name);
+  if (raw === undefined) return null;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
+  return value;
+}
+
+function firstConfiguredBrokerUrl(): string | null {
+  for (const key of BROKER_URL_ENV_KEYS) {
+    if (hasEnvKey(key)) return `<${key}>`;
+  }
+  return null;
+}
+
+function parseOptions(args: string[]): BrokerAdapterOptions {
+  const rawCommand = args[0] ?? "contract";
+  if (!["contract", "credential-request", "pr-preflight", "health"].includes(rawCommand)) {
+    throw new Error(`unknown auth-broker command: ${rawCommand}`);
+  }
+  const command = rawCommand as BrokerCommand;
+  const endpoint = stringOption(args, "--endpoint");
+  return {
+    command,
+    repo: stringOption(args, "--repo") ?? DEFAULT_REPO,
+    operation: stringOption(args, "--operation") ?? (command === "pr-preflight" ? "github.pr.preflight.dry-run" : "github.auth.status"),
+    dryRun: args.includes("--dry-run") || command === "contract" || command === "credential-request" || command === "pr-preflight" || command === "health",
+    endpoint: endpoint === undefined ? firstConfiguredBrokerUrl() : sanitizeEndpoint(endpoint),
+    base: stringOption(args, "--base") ?? DEFAULT_BASE,
+    head: stringOption(args, "--head") ?? "<head-branch>",
+    issueNumber: numberOption(args, "--issue"),
+  };
+}
+
+function runnerEnvTokenCoverage(): Record<string, unknown> {
+  const present = SECRET_ENV_KEYS.filter((key) => hasEnvKey(key));
+  return {
+    ok: present.length > 0,
+    source: present.length > 0 ? "runner-env" : null,
+    checkedKeys: SECRET_ENV_KEYS,
+    presentKeys: present,
+    missingKeys: SECRET_ENV_KEYS.filter((key) => !present.includes(key)),
+    presenceOnly: true,
+    valuesRead: false,
+    valuesPrinted: false,
+  };
+}
+
+function brokerCoverage(endpoint: string | null): Record<string, unknown> {
+  return {
+    ok: endpoint !== null,
+    source: endpoint === null ? null : "auth-broker",
+    endpoint: endpoint ?? null,
+    credentialRef: endpoint === null ? null : "github:unidesk-dev",
+    scope: endpoint === null ? null : "broker-held-github-credential",
+    runnerEnvTokenRequired: false,
+    valuesRead: false,
+    valuesPrinted: false,
+  };
+}
+
+function brokerNeededResult(options: BrokerAdapterOptions): Record<string, unknown> {
+  return {
+    ok: false,
+    failureKind: "auth-missing",
+    degradedReason: "broker-needed",
+    runnerDisposition: "infra-blocked" as RunnerDisposition,
+    retryable: false,
+    brokerNeeded: true,
+    message: "No auth broker endpoint is configured for this dry-run contract; runner env token coverage is reported only for migration diagnostics.",
+    tokenCoverage: runnerEnvTokenCoverage(),
+    brokerCoverage: brokerCoverage(options.endpoint),
+    next: [
+      "configure UNIDESK_AUTH_BROKER_URL or AUTH_BROKER_URL for broker-backed runner auth",
+      "keep GH_TOKEN/GITHUB_TOKEN out of ordinary runner env once broker mode is enabled",
+    ],
+    redaction: {
+      valuesRead: false,
+      valuesPrinted: false,
+      forbiddenOutputKeys: ["token", "secret", "authorization", "cookie"],
+    },
+  };
+}
+
+function auditEventShape(options: BrokerAdapterOptions): Record<string, unknown> {
+  return {
+    requestId: "authbroker-contract-request",
+    observedAt: "ISO-8601 timestamp",
+    caller: { plane: "code-queue", taskId: null, queueId: null },
+    operation: options.operation,
+    repo: options.repo,
+    resource: options.command === "pr-preflight"
+      ? { base: options.base, head: options.head, issueNumber: options.issueNumber }
+      : null,
+    dryRun: true,
+    credentialRef: "github:unidesk-dev",
+    credentialKind: "github-rest-token-ref",
+    credentialValuePrinted: false,
+    upstream: { method: "planned", path: "planned GitHub REST path without query secrets" },
+    status: "HTTP status",
+    ok: "boolean",
+    failureKind: null,
+    degradedReason: null,
+    runnerDisposition: "ready|infra-blocked|business-failed",
+    retryable: "boolean",
+    durationMs: "integer",
+    redaction: { valuesPrinted: false },
+  };
+}
+
+function plannedCredentialRequest(options: BrokerAdapterOptions): Record<string, unknown> {
+  return {
+    requestId: "authbroker-cli-dry-run",
+    caller: { plane: "manual-cli" },
+    repo: options.repo,
+    operation: options.operation,
+    dryRun: true,
+    params: options.command === "pr-preflight"
+      ? { base: options.base, head: options.head, issueNumber: options.issueNumber }
+      : {},
+  };
+}
+
+function readyContract(options: BrokerAdapterOptions): Record<string, unknown> {
+  return {
+    ok: true,
+    runnerDisposition: "ready" as RunnerDisposition,
+    failureKind: null,
+    degradedReason: null,
+    brokerNeeded: false,
+    dryRun: true,
+    mutation: false,
+    capabilities: [...DEFAULT_CAPABILITIES],
+    tokenCoverage: {
+      ok: true,
+      source: "auth-broker",
+      scope: "broker-held-github-credential",
+      runnerEnvTokenRequired: false,
+      valuesRead: false,
+      valuesPrinted: false,
+    },
+    brokerCoverage: brokerCoverage(options.endpoint),
+    credentialRequest: plannedCredentialRequest(options),
+    auditEventShape: auditEventShape(options),
+    prCapabilityContract: {
+      targetBranch: options.base,
+      headBranch: options.head,
+      systemGhBinaryRequiredForWrites: false,
+      preflightCreatesPr: false,
+      preflightMergesPr: false,
+      brokerProxy: {
+        ok: true,
+        operations: ["github.auth.status", "github.issue.read", "github.pr.read", "github.pr.create"],
+        writesRemote: false,
+      },
+      pushDryRun: {
+        runnerLocal: true,
+        coveredByBroker: false,
+      },
+    },
+    redaction: {
+      valuesRead: false,
+      valuesPrinted: false,
+      secretKeysBlocked: ["token", "secret", "authorization", "cookie"],
+    },
+  };
+}
+
+function contractResult(options: BrokerAdapterOptions): Record<string, unknown> {
+  return {
+    ok: true,
+    service: "auth-broker",
+    phase: "p0",
+    commands: [
+      "bun scripts/cli.ts auth-broker contract",
+      "bun scripts/cli.ts auth-broker health --dry-run",
+      "bun scripts/cli.ts auth-broker credential-request --operation github.pr.create --repo pikasTech/unidesk --dry-run",
+      "bun scripts/cli.ts auth-broker pr-preflight --repo pikasTech/unidesk --base master --head <head-branch> --issue 59 --dry-run",
+    ],
+    capabilities: [...DEFAULT_CAPABILITIES],
+    permissionBoundary: {
+      allowedRepos: [DEFAULT_REPO],
+      liveGithubWrites: false,
+      arbitraryGhApi: false,
+      registryCredentials: false,
+      deployPermissions: false,
+    },
+    runnerNoTokenResult: brokerNeededResult({ ...options, endpoint: null }),
+    readyShape: readyContract({ ...options, endpoint: "<UNIDESK_AUTH_BROKER_URL>" }),
+  };
+}
+
+export function authBrokerHelp(): unknown {
+  return {
+    command: "auth-broker",
+    output: "json",
+    usage: [
+      "bun scripts/cli.ts auth-broker contract",
+      "bun scripts/cli.ts auth-broker health --dry-run [--endpoint URL]",
+      "bun scripts/cli.ts auth-broker credential-request --operation github.pr.create --repo pikasTech/unidesk --dry-run [--endpoint URL]",
+      "bun scripts/cli.ts auth-broker pr-preflight --repo pikasTech/unidesk --base master --head <head-branch> [--issue N] --dry-run [--endpoint URL]",
+    ],
+    boundary: [
+      "P0 adapter is contract/dry-run only and never starts a service.",
+      "GH_TOKEN and GITHUB_TOKEN values are not read or printed; only key presence is reported.",
+      "No dry-run command writes GitHub, registry, deploy, filesystem credential, or service state.",
+    ],
+    reference: "docs/reference/auth-broker.md",
+  };
+}
+
+export function runAuthBrokerCommand(args: string[]): Record<string, unknown> {
+  if (args.some((arg) => arg === "help" || arg === "--help" || arg === "-h")) return authBrokerHelp() as Record<string, unknown>;
+  const options = parseOptions(args);
+  if (options.command === "contract") return contractResult(options);
+
+  const envCoverage = runnerEnvTokenCoverage();
+  const broker = brokerCoverage(options.endpoint);
+  if (broker.ok !== true) return brokerNeededResult(options);
+
+  if (options.command === "health") {
+    return {
+      ok: true,
+      dryRun: true,
+      mutation: false,
+      service: "auth-broker",
+      phase: "p0",
+      brokerCoverage: broker,
+      tokenCoverage: envCoverage,
+      healthRequest: {
+        method: "GET",
+        path: "/health",
+        wouldCallBroker: false,
+      },
+      capabilities: [...DEFAULT_CAPABILITIES],
+      redaction: { valuesRead: false, valuesPrinted: false },
+    };
+  }
+
+  return readyContract(options);
+}

scripts/src/check.ts

@@ -14,6 +14,7 @@ const syntaxFiles = [
   "scripts/cli.ts",
   "scripts/src/check.ts",
   "scripts/src/artifact-registry.ts",
+  "scripts/src/auth-broker.ts",
   "scripts/src/code-queue.ts",
   "scripts/src/command.ts",
   "scripts/src/decision-center.ts",
@@ -27,6 +28,7 @@ const syntaxFiles = [
   "scripts/host-codex-commander-contract-test.ts",
   "scripts/host-codex-commander-no-daemon-smoke-contract-test.ts",
   "scripts/host-codex-commander-skeleton-contract-test.ts",
+  "scripts/auth-broker-contract-test.ts",
   "src/components/frontend/src/index.ts",
   "src/components/frontend/src/app.tsx",
   "src/components/frontend/src/decision-center.tsx",
@@ -271,6 +273,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
       fileItem("AGENTS.md"),
       fileItem("TEST.md"),
       fileItem("docs/reference/artifact-registry.md"),
+      fileItem("docs/reference/auth-broker.md"),
       fileItem("docker-compose.yml"),
       fileItem("src/components/backend-core/Cargo.toml"),
       fileItem("src/components/backend-core/Cargo.lock"),
@@ -314,6 +317,11 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
       fileItem("scripts/code-queue-pr-preflight-example.ts"),
       fileItem("scripts/schedule-cli-contract-test.ts"),
       fileItem("scripts/src/artifact-registry.ts"),
+      fileItem("scripts/src/auth-broker.ts"),
+      fileItem("scripts/auth-broker-contract-test.ts"),
+      fileItem("src/components/microservices/auth-broker/Cargo.toml"),
+      fileItem("src/components/microservices/auth-broker/Dockerfile"),
+      fileItem("src/components/microservices/auth-broker/src/main.rs"),
       fileItem("scripts/artifact-consumer-dry-run-matrix-test.ts"),
       fileItem("src/components/microservices/k3sctl-adapter/k3s/ci/unidesk-ci.pipeline.yaml"),
     );
@@ -342,6 +350,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(commandItem("schedule:cli-contract", ["bun", "scripts/schedule-cli-contract-test.ts"], 30_000));
     items.push(commandItem("gh:issue-guard-contract", ["bun", "scripts/gh-cli-issue-guard-contract-test.ts"], 30_000));
     items.push(commandItem("gh:pr-contract", ["bun", "scripts/gh-cli-pr-contract-test.ts"], 30_000));
+    items.push(commandItem("auth-broker:p0-contract", ["bun", "scripts/auth-broker-contract-test.ts"], 30_000));
   } else {
     items.push(skippedItem("typescript:scripts", "scripts TypeScript typecheck is opt-in", "--scripts-typecheck or --full"));
     items.push(skippedItem("code-queue:prompt-observation-contract", "prompt observation contract is opt-in with script checks", "--scripts-typecheck or --full"));
@@ -360,6 +369,7 @@ export function runChecks(config: UniDeskConfig, options: CheckOptions = default
     items.push(skippedItem("schedule:cli-contract", "Schedule CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("gh:issue-guard-contract", "GitHub issue CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
     items.push(skippedItem("gh:pr-contract", "GitHub PR CLI contract is opt-in with script checks", "--scripts-typecheck or --full"));
+    items.push(skippedItem("auth-broker:p0-contract", "Auth Broker P0 skeleton and CLI adapter contract is opt-in with script checks", "--scripts-typecheck or --full"));
   }
   if (options.logs) {
     items.push(unifiedLogRotationItem());

scripts/src/help.ts

@@ -1,4 +1,5 @@
 import { ghHelp } from "./gh";
+import { authBrokerHelp } from "./auth-broker";
 
 export function rootHelp(): unknown {
   return {
@@ -43,6 +44,7 @@ export function rootHelp(): unknown {
       { command: "deploy check|plan|apply [--file deploy.json|--env dev|prod] [--service id] [--commit full-sha] [--dry-run] [--force]", description: "Reconcile services from origin/master:deploy.json environments; --commit overrides one reviewed artifact consumer such as frontend for release/v1 validation or rollback. code-queue artifact consumption is dev-only." },
       { command: "dev-env validate|prewarm-images", description: "Validate D601 unidesk-dev guardrails or prewarm dev foundation images into native k3s containerd through a bounded async job." },
       { command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including D601 direct, k3s-managed, and code-queue dev-only consumers." },
+      { command: "auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run", description: "Inspect the P0 Rust auth broker and CLI adapter contract without reading token values, writing GitHub, or starting services." },
       { command: "gh auth|issue|pr", description: "Run safe GitHub issue and PR CRUD/lifecycle operations through REST with body-file update replace/append, comment delete, token diagnostics, hard delete unsupported, and merge blocked." },
       { command: "commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run", description: "Host Codex commander skeleton contract, no-daemon smoke plan, and dry-run preview; exposes local health, state, trace summary, and approval draft helpers without live bridges or message sends." },
       { command: "code-agent-sandbox", description: "Independent Code Agent Sandbox service skeleton for adapter, mode, and credential-boundary diagnostics." },
@@ -371,6 +373,7 @@ export function staticNamespaceHelp(args: string[]): unknown | null {
   if (top === "e2e") return e2eHelp();
   if (top === "dev-env") return devEnvHelp();
   if (top === "artifact-registry") return artifactRegistryHelp();
+  if (top === "auth-broker") return authBrokerHelp();
   if (top === "gh") return ghHelp();
   return null;
 }