PRO-1042: route Claude plugin login through typed CLI auth

[rares04]

Summary

• Keep working credentials from LUA_API_KEY, ~/.lua-cli/credentials, and .env unchanged. This includes non-dotted legacy keys.
• Send new login to lua auth configure in a private terminal. lua-cli 3.28.0 and later issue a typed personal credential after the user selects an organization, one or more agents, and a role. Builder remains the default role.
• Stop collecting email addresses, OTPs, and raw credentials in the Claude conversation. A hook and the permission template deny model-run lua auth configure, and lua auth key* remains denied.
• Identify direct MCP HTTP requests as claude-plugin/1.1.0. Calls that spawn lua-cli use the CLI's own versioned identity.
• Update the setup guide, security contract, troubleshooting guide, and MCP examples. A lint rejects the old secret-bearing auth commands.
• Release Claude plugin 1.1.0 on merge. A consistency lint keeps the package, marketplace, manifest, MCP, and telemetry versions aligned.

Source-derived caller inventory

The inventory came from a repository-wide rg before editing.

• commands/lua-auth.md, commands/lua-doctor.md, and the auth preflight in commands/lua-init.md own setup.
• lib/credentials.mjs and mcp/lua-platform/src/auth.mjs resolve LUA_API_KEY, the CLI credentials file, and .env. This PR does not change their order or formats.
• mcp/lua-platform/src/tools/list-agents.mjs and get-agent.mjs spawn lua agents --json. Those requests use cli/<version>.
• mcp/lua-platform/src/api-client.mjs owns direct Lua API requests for deployment status, primitive versions, and logs. Those requests now use claude-plugin/1.1.0, which lua-core-services #2183 recognizes as a bounded family.

Merge gate

Merge only after npm view lua-cli version reports 3.28.0 or later. The current PR head must also have green CI and current-head approval.

This PR does not rotate, revoke, rewrite, or invalidate an existing credential. It does not use work from the closed #2008 prototype.

Verification

• npm run lint
• npm test -- --coverage (223 tests)
• node scripts/check-coverage.mjs
• MCP npm test (83 tests)
• MCP npm run build
• node scripts/check-bundle-size.mjs

Linear: PRO-1042

[rares04]

Dependency update: lua-core-services #2183 must merge and deploy before this draft can release. Direct api-client.mjs requests now identify as claude-plugin/<package version>; Lua CLI subprocesses keep cli/<lua-cli version>. Focused tests also fail if a new raw HTTP caller bypasses the identified wrapper.

[richard-lua]

Code review — MEDIUM risk

The security direction here is right: new-login auth moves out of the model conversation into lua-cli's private lua auth configure, backed by a PreToolUse block hook and permission-template deny rules, with docs/lints/tests updated consistently. Existing credentials are preserved and nothing is rotated or exposed. One concrete correctness bug should be fixed before merge, plus a few advisory edge cases; the PR's own "keep in draft until the release gate clears" note is correct process guidance.

Major

• plugins/lua-agent-builder/mcp/lua-platform/src/api-client.mjs:38 — X-Lua-Client is hardcoded to 'claude-plugin/1.0.1', but the new test api-client.test.mjs asserts it equals claude-plugin/${package.json version}. This only passes at version 1.0.1; the PR's release gate requires a version bump, which will make the header stale and break the test. Derive the version from package.json and format as claude-plugin/${version}.

Minor

• plugins/lua-agent-builder/hooks/block-auth-configure.mjs:5 — The block hook + Bash(*lua auth configure*) if gate are substring/pattern-based and evadable (e.g. sh -c, aliases). The authoritative control is the permission-template deny; SECURITY.md's "deny model-run login" wording overstates the hook's guarantee. Treat the hook as best-effort defense-in-depth and lean on the permission deny.
• plugins/lua-agent-builder/scripts/lint-cli-flags.mjs:26 — Auth-doc scanning is inconsistent on missing paths: a missing AUTH_DOC_FILES entry throws a raw ENOENT (uncaught), while a relocated AUTH_DOC_DIRS entry silently scans nothing. Wrap the file scan in try/catch with a clear message and assert at least one auth doc was scanned so the guard can't silently no-op.
• plugins/lua-agent-builder/mcp/lua-platform/tests/api-client.test.mjs:72 — The "only api-client.mjs calls fetch" static guard is useful but brittle to lexical form (prefetch(, comments, globalThis.fetch). Tighten the regex and add a rationale comment.

---

_{PR Risk Reviewer — automated senior review of dfba757 · risk: medium · confidence: 0.78}

[richard-lua]

Code review — LOW risk

Previously flagged

• X-Lua-Client version hardcoded / drifts from package version — resolved. The header is now claude-plugin/1.1.0 (mcp/lua-platform/src/api-client.mjs:38), all metadata surfaces bumped to 1.1.0, and the new scripts/lint-release-version.mjs fails CI if the header, plugin.json, marketplace.json, MCP package.json, or server.mjs version strings diverge from package.json. The api-client test now derives the expected version from package.json instead of asserting a fixed value, so it stays green across future bumps.
• Block hook is defense-in-depth only — resolved (as documentation). SECURITY.md and README now describe the permission-template deny as the primary gate with the hook as an additional block, matching the actual guarantee. The hook remains substring/regex-based and evadable by shell tricks, which is acceptable for defense-in-depth.
• Auth-flow lint scans a fixed doc file list and can silently no-op — still open. scripts/lint-cli-flags.mjs still passes AUTH_DOC_FILES directly to readFile (uncaught ENOENT on a relocated doc) and walks AUTH_DOC_DIRS with no minimum-scanned assertion. Minor.
• Static 'only api-client calls fetch' guard is brittle — mitigated. The regex was tightened to \b(?:fetch|fetchFn)\s*\( and the test now enumerates src/ recursively; still lexical, but tighter and with clearer intent. Acceptable.

The version-consistency work closes the one blocking correctness issue from the prior review. The change is well-tested and the PR's own "keep in draft until the release gate (lua-core-services #2183, published lua-cli 3.28.0) clears" note remains the correct process guidance. Remaining findings are advisory.

Minor

• scripts/lint-release-version.mjs:22 — The lint asserts exact source substrings ('X-Lua-Client': 'claude-plugin/${v}', plugin_version: '${v}') with exact occurrence counts, coupling the guard to source quoting/spacing and blocking any move to deriving the version from package.json at runtime. Consider having the runtime read the version from package.json and asserting the resolved value, or tolerate quote/whitespace variants.
• scripts/lint-cli-flags.mjs:26 — AUTH_DOC_FILES are read without try/catch (a relocated README.md/SECURITY.md throws an uncaught ENOENT), and no minimum-scanned count is asserted, so a moved AUTH_DOC_DIRS entry silently scans nothing. Wrap the file scan with a clear failure message and assert at least one auth doc was scanned.

---

_{PR Risk Reviewer — automated senior review of 28eda77 · risk: low · confidence: 0.82 · re-review}