Implementation Notes: M3 Authenticated Distribution

2026-05-14

PR

• Ready PR opened against 2.0.0: https://github.com/wearedevpunks/harness-intelligence/pull/4
• Branch: team/stefan/m3-delivery-20260514

Inventory

• M3 milestone: M3 Authenticated Distribution
• Parents: IP-101, IP-102, IP-103
• Children: IP-122, IP-123, IP-124, IP-125, IP-126, IP-127
• Dependency order: CLI refactor -> IP-101/IP-103 -> IP-102

CLI Refactor Gate

• Added shared command helper apps/cli/src/cli/baseline-options.ts.
• Extracted required-tool installation/checking into apps/cli/src/core/tools.ts.
• Added direct boundary tests in apps/cli/src/core/tools.test.ts.
• Updated scaffold/update runners to import required-tool behavior from core/tools instead of scaffold/run.

Validation

• bun run test --filter=@punks/cli --filter=@punks/api: passed @punks/cli 71 tests and @punks/api 4 tests.
• bun run check-types --filter=@punks/cli --filter=@punks/api --filter=@punks/auth: passed 6 tasks.
• bun run check-types --filter=@punks/api --filter=@punks/cli: passed 4 tasks after IP-102 registry work.
• bun run test --filter=@punks/api: passed 6 tests after IP-102 registry work.
• bun run build --filter=@punks/cli: passed.
• DP_NO_UPDATE_CHECK=1 DP_NO_SKILL_UPDATE_CHECK=1 bun apps/cli/dist/index.js --help: passed and lists auth commands.
• punks auth status -> login --token -> status -> logout against a temp DP_AUTH_CONFIG_FILE: passed.
• git diff --check: passed.
• bun run check: passed after formatting generated scaffolded harness agent files.

IP-101 / IP-122 / IP-123

• Added punks auth login/status/logout.
• Added Better Auth device authorization client for POST /device/code and POST /device/token.
• Added local-development --token login path for credential-unavailable environments.
• Stored credentials are read by baseline control-plane resolution when DP_CONTROL_PLANE_TOKEN is absent.
• Enabled Better Auth bearer() and deviceAuthorization() plugins in packages/auth.
• API bearer auth rejects missing/invalid credentials, fails closed when DP_API_CLI_TOKEN is absent, accepts explicitly configured local-development static tokens, and delegates real session bearers to Better Auth.
• /api/auth/* is routed to Better Auth so device authorization endpoints are available alongside the typed Harness API.
• Better Auth device authorization storage is modeled in packages/db through the device_code table.
• Device-token polling handles OAuth authorization_pending and slow_down errors returned as HTTP 400 bodies.

IP-103 / IP-126 / IP-127

• Base required tools are now agent-browser, opensrc, portless, and skills.
• Content tests pin the base required-tool set and selected-skill additions.
• Existing dp-cli skill startup verification remains advisory and non-blocking during command startup; setup/update now keep skills in the base toolchain and docs/runbook explain the provisioning path.

IP-102 / IP-124 / IP-125

• Added apps/api/src/baseline-registry.ts.
• Authenticated baseline resolution reads backend-owned metadata from DP_BASELINE_* environment variables.
• Authenticated artifact metadata endpoint returns backend-issued manifest/archive URLs and checksums.
• Unconfigured backend metadata still returns ControlPlaneUnavailable, preserving CLI fallback behavior.
• Vercel Blob is recorded as compatible with the artifact URL boundary; M3 keeps URLs storage-provider agnostic so GitHub Release assets can remain usable during migration.

Notes

• bun install was required because the worktree had no node_modules; generated unrelated bun.lock drift was restored.
• Pre-existing .codex/config.toml drift is preserved and unrelated to this implementation.

Review Fixes

• Review found three high-severity blockers: API auth failed open to a documented default token, device polling could not handle Better Auth pending errors, and Better Auth device storage/routes were not wired.
• Fixed by removing the default API token, mounting Better Auth routes, adding device-code schema support, and parsing device-token error bodies before deciding poll state.
• Focused validation after fixes:
  • bun run test --filter=@punks/api --filter=@punks/cli: passed @punks/api 8 tests and @punks/cli 72 tests.
  • bun run check-types --filter=@punks/api --filter=@punks/cli --filter=@punks/auth --filter=@punks/db: passed 6 tasks.

Docs Ingest

• Updated CLI bearer-auth concept and routed page.
• Updated control-plane baseline-resolution flow and routed page.
• Existing docs/README.md and docs/runbooks/dp-cli-scaffolding.md were updated with auth, baseline registry, and required-toolchain operator guidance.

Final Validation

• git diff --check: passed.
• bun run check: passed after formatting generated agent context files.
• bun run check-types: passed 8 tasks.
• bun run test: passed 4 tasks.
• bun run build --filter=@punks/cli: passed.
• Built CLI --help: passed.
• Built CLI auth status/login/status/logout smoke with a temp DP_AUTH_CONFIG_FILE: passed.

PR Review Debt

• Resolved Codex PR review finding: punks auth login no longer falls back to DP_CONTROL_PLANE_URL for Better Auth device-login endpoints.
• Resolved Codex PR review finding: browser auto-open failure now prints manual guidance and continues device-token polling.
• Debt record: docs/reference/tech-debt/cli/M3-authenticated-distribution/pr-4-auth-login-review-findings.md.
• Validation:
  • bun run test --filter=@punks/cli: passed 75 tests.
  • bun run check-types --filter=@punks/cli: passed 3 tasks.
  • bun run check: passed.
  • git diff --check: passed.
  • bun run build --filter=@punks/cli: passed.
  • Built CLI auth login --help: passed.

PR Review Auth Hardening Debt

• Resolved Codex PR review finding: empty --auth-url and DP_AUTH_URL values now normalize to missing auth configuration.
• Resolved Codex PR review finding: malformed stored auth credentials now read as unauthenticated instead of crashing status or baseline credential lookup.
• Debt record: docs/reference/tech-debt/cli/M3-authenticated-distribution/pr-4-auth-hardening-review-findings.md.
• Validation:
  • bun run test --filter=@punks/cli: passed 77 tests.
  • bun run check-types --filter=@punks/cli: passed 3 tasks.
  • bun run check: passed.
  • git diff --check: passed.
  • bun run build --filter=@punks/cli: passed.
  • Built CLI auth login --help: passed.

PR Review Empty Configuration Debt

• Resolved Codex PR review finding: blank punks auth login --token values now normalize to missing local-development tokens instead of persisting unusable credentials.
• Resolved Codex PR review finding: empty DP_BASELINE_* values now make the backend baseline registry unavailable instead of returning blank metadata.
• Debt record: docs/reference/tech-debt/cli/M3-authenticated-distribution/pr-4-empty-config-review-findings.md.
• Validation:
  • bun run test --filter=@punks/cli --filter=@punks/api: passed @punks/cli 78 tests and @punks/api 9 tests.
  • bun run check-types --filter=@punks/cli --filter=@punks/api: passed 6 tasks.
  • bun run check: passed.
  • git diff --check: passed.
  • bun run build --filter=@punks/cli: passed.
  • Built CLI auth login --help: passed.
  • Built CLI auth login --token "": failed with the intended non-empty token error and did not store credentials.

PR Review Device Flow Debt

• Resolved Codex PR review finding: Better Auth now advertises the served /api/auth/device verification route instead of the unmounted /device path.
• Resolved Codex PR review finding: CLI device-token polling now honors the server-issued device-code expires_in lifetime instead of always timing out after five minutes.
• Debt record: docs/reference/tech-debt/cli/M3-authenticated-distribution/pr-4-device-flow-review-findings.md.
• Validation:
  • bun run test --filter=@punks/cli --filter=@punks/api: passed @punks/cli 79 tests and @punks/api 10 tests.
  • bun run check-types --filter=@punks/cli --filter=@punks/api --filter=@punks/auth: passed 6 tasks.
  • bun run check: passed.
  • git diff --check: passed.
  • bun run build --filter=@punks/cli: passed.
  • Built CLI auth login --help: passed.
  • bun run test: passed 4 tasks.
  • bun run check-types: passed 8 tasks.