feat(config): bind OpenClaw keyless credentials

.github/CODEOWNERS

@@ -1,7 +1,4 @@
-/go.mod @liangshuo-1
-/go.sum @liangshuo-1
 /internal/ @liangshuo-1
-/shortcuts/common/ @liangshuo-1
 
 # Last match wins: existing domains below are exempt, only new skills/ entries need review.
 /skills/ @liangshuo-1

.github/workflows/ci.yml

@@ -82,56 +82,6 @@ jobs:
       - name: Run sidecar tag build + HMAC round-trip
         run: make sidecar-test
 
-  extended-integration:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.x'
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-      - name: Build both editions and verify identity
-        run: |
-          set -euo pipefail
-          go build -o /tmp/lark-cli-standard .
-          go build -tags extended -o /tmp/lark-cli-extended .
-          test "$(/tmp/lark-cli-standard version --json | jq -r .edition)" = "standard"
-          test "$(/tmp/lark-cli-extended version --json | jq -r .edition)" = "extended"
-          test "$(/tmp/lark-cli-extended version --json | jq -r '.capabilities[]')" = "external-credential-platform"
-      - name: Cross-compile Extended platform-specific security code
-        run: |
-          set -euo pipefail
-          GOOS=darwin GOARCH=arm64 go build -tags extended -o /tmp/lark-cli-extended-darwin .
-          GOOS=windows GOARCH=amd64 go build -tags extended -o /tmp/lark-cli-extended-windows.exe .
-      - name: Verify edition source isolation
-        run: go test -count=1 ./internal/externalcredential -run '^TestEditionSourceIsolation$'
-      - name: Run Extended tests
-        run: make extended-test
-
-  extended-platform-security:
-    needs: fast-gate
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [macos-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - name: Run native helper isolation and path trust tests
-        run: go test -tags extended -count=1 ./internal/externalcredential -run '^(TestNativeAdminControlledPath|TestCredentialProcessEnvironmentUsesExplicitAllowlist|TestCredentialProcessCommandRunsWithIsolatedEnvironment)$'
-
   # ── Layer 2: Quality Gate ──────────────────────────────────────────
   unit-test:
     needs: fast-gate
@@ -192,28 +142,6 @@ jobs:
           node-version: '22'
       - name: Run script tests
         run: make script-test
-      - name: Install GoReleaser
-        uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
-        with:
-          version: '~> v2'
-          install-only: true
-      - name: Validate GoReleaser configuration
-        run: goreleaser check
-      - name: Check Extended installer syntax
-        shell: pwsh
-        run: |
-          sh -n scripts/install-extended.sh
-          $tokens = $null
-          $errors = $null
-          [System.Management.Automation.Language.Parser]::ParseFile(
-            (Resolve-Path scripts/install-extended.ps1),
-            [ref]$tokens,
-            [ref]$errors
-          ) | Out-Null
-          if ($errors.Count -ne 0) {
-            $errors | ForEach-Object { Write-Error $_ }
-            exit 1
-          }
 
   deterministic-gate:
     needs: fast-gate
@@ -288,20 +216,16 @@ jobs:
           # second time here — and, crucially, so an observe-only suite's failure
           # can never block merges through coverage's spot in the results loop.
           packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/')
-          go test -race -coverprofile=coverage-standard.txt -covermode=atomic $packages
-          # Extended implementation files are selected by build tags and would
-          # otherwise be absent from the uploaded report. Their race-enabled
-          # suite runs in extended-integration; this pass contributes coverage.
-          go test -tags extended -coverprofile=coverage-extended.txt -covermode=atomic $packages
+          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
       - name: Upload coverage to Codecov
         if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
         uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
         with:
-          files: coverage-standard.txt,coverage-extended.txt
+          files: coverage.txt
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Check coverage threshold
         run: |
-          total=$(go tool cover -func=coverage-standard.txt | grep total | awk '{print $3}' | tr -d '%')
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | tr -d '%')
           threshold=40
           echo "Coverage: ${total}% (threshold: ${threshold}%)"
           if (( $(echo "$total < $threshold" | bc -l) )); then
@@ -311,31 +235,21 @@ jobs:
       - name: Coverage summary
         if: ${{ !cancelled() }}
         run: |
+          if [ ! -f coverage.txt ]; then
+            echo "No coverage data available" >> $GITHUB_STEP_SUMMARY
+            exit 0
+          fi
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
           echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          report_coverage() {
-            profile="$1"
-            label="$2"
-            echo "### ${label} edition" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-            if [ ! -f "$profile" ]; then
-              echo "No ${label} coverage data available." >> $GITHUB_STEP_SUMMARY
-              echo "" >> $GITHUB_STEP_SUMMARY
-              return
-            fi
-            total=$(go tool cover -func="$profile" | grep total | awk '{print $3}')
-            echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo '```' >> $GITHUB_STEP_SUMMARY
-            go tool cover -func="$profile" >> $GITHUB_STEP_SUMMARY
-            echo '```' >> $GITHUB_STEP_SUMMARY
-            echo "</details>" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-          }
-          report_coverage coverage-standard.txt Standard
-          report_coverage coverage-extended.txt Extended
+          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
 
   deadcode:
     needs: fast-gate
@@ -606,7 +520,7 @@ jobs:
   # ── Results Gate (single required check for branch protection) ─────
   results:
     if: ${{ always() }}
-    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header, plugin-integration, sidecar-integration, extended-integration, extended-platform-security]
+    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header, plugin-integration, sidecar-integration]
     runs-on: ubuntu-latest
     steps:
       - name: Evaluate results
@@ -628,8 +542,6 @@ jobs:
           echo "| L4 | license-header | ${{ needs.license-header.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L4 | plugin-integration (observe-only) | ${{ needs.plugin-integration.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L4 | sidecar-integration (observe-only) | ${{ needs.sidecar-integration.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L4 | extended-integration | ${{ needs.extended-integration.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L4 | extended-platform-security | ${{ needs.extended-platform-security.result }} |" >> $GITHUB_STEP_SUMMARY
 
           # Any failure or cancellation in any job blocks the merge.
           # Legitimately skipped jobs (deadcode on push, e2e-live when not
@@ -653,9 +565,7 @@ jobs:
             "${{ needs.e2e-dry-run.result }}" \
             "${{ needs.e2e-live.result }}" \
             "${{ needs.security.result }}" \
-            "${{ needs.license-header.result }}" \
-            "${{ needs.extended-integration.result }}" \
-            "${{ needs.extended-platform-security.result }}"; do
+            "${{ needs.license-header.result }}"; do
             if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
               FAILED=1
             fi

.github/workflows/release.yml

@@ -9,45 +9,14 @@ permissions:
   contents: read
 
 jobs:
-  preflight:
-    runs-on: ubuntu-22.04
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
-        with:
-          node-version: '22.14.0'
-
-      - name: Validate tag and commit
-        env:
-          TAG: ${{ github.ref_name }}
-        run: |
-          set -euo pipefail
-          node scripts/release-preflight.js --tag "$TAG"
-          git fetch origin main
-          HEAD_SHA="$(git rev-parse --verify 'HEAD^{commit}')"
-          MAIN_SHA="$(git rev-parse --verify 'FETCH_HEAD^{commit}')"
-          TAG_SHA="$(git rev-parse --verify "refs/tags/${TAG}^{commit}")"
-          if [[ "$TAG_SHA" != "$HEAD_SHA" ]]; then
-            echo "Tag ${TAG} does not resolve to the checked-out HEAD commit." >&2
-            exit 1
-          fi
-          if ! git merge-base --is-ancestor "$HEAD_SHA" "$MAIN_SHA"; then
-            echo "Tag ${TAG} does not point to a commit contained in origin/main." >&2
-            exit 1
-          fi
-
-  build-release:
-    needs: preflight
+  # All platforms (incl. darwin keychain_signer) are CGO-free and cross-compiled
+  # on a single ubuntu runner in one goreleaser run (one checksums.txt). The
+  # darwin signer's runtime FFI is validated separately by the signer-test job.
+  goreleaser:
+    needs: signer-test-macos
     runs-on: ubuntu-22.04
     permissions:
       contents: write
-      id-token: write
-      attestations: write
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -61,176 +30,50 @@ jobs:
         with:
           python-version: '3.x'
 
-      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
-        with:
-          node-version: '22.14.0'
-          registry-url: 'https://registry.npmjs.org'
-          package-manager-cache: false
-
-      - name: Install pinned npm
-        run: npm install --global npm@11.16.0
-
-      - name: Build and upload draft release with GoReleaser
+      - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
         with:
           version: '~> v2'
           args: release --clean
         env:
-          GITHUB_TOKEN: ${{ github.token }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Include release checksums
-        run: |
-          set -euo pipefail
-          test -s dist/checksums.txt
-          cp scripts/install-extended.sh scripts/install-extended.ps1 dist/
-          (cd dist && sha256sum --check checksums.txt)
-          cp dist/checksums.txt checksums.txt
-
-      - name: Verify release edition identities
-        run: |
-          set -euo pipefail
-          mkdir -p /tmp/lark-cli-standard /tmp/lark-cli-extended
-          tar -xzf "dist/lark-cli-${GITHUB_REF_NAME#v}-linux-amd64.tar.gz" -C /tmp/lark-cli-standard lark-cli
-          tar -xzf "dist/lark-cli-extended-${GITHUB_REF_NAME#v}-linux-amd64.tar.gz" -C /tmp/lark-cli-extended lark-cli
-          test "$(/tmp/lark-cli-standard/lark-cli version --json | jq -r .edition)" = "standard"
-          test "$(/tmp/lark-cli-extended/lark-cli version --json | jq -r .edition)" = "extended"
-          test "$(/tmp/lark-cli-standard/lark-cli version --json | jq -r .version)" = "${GITHUB_REF_NAME#v}"
-          test "$(/tmp/lark-cli-extended/lark-cli version --json | jq -r .version)" = "${GITHUB_REF_NAME#v}"
-
-      - name: Verify release platform asset matrix
-        run: bash scripts/verify-release-assets.sh dist "${GITHUB_REF_NAME#v}"
-
-      - name: Attest release archives
-        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
-        with:
-          subject-path: |
-            dist/*.tar.gz
-            dist/*.zip
-            dist/checksums.txt
-            dist/install-extended.sh
-            dist/install-extended.ps1
-
-      - name: Collect release asset
-        run: |
-          set -euo pipefail
-          mkdir npm-publish-asset
-          cp dist/*.tar.gz dist/*.zip dist/checksums.txt \
-            dist/install-extended.sh dist/install-extended.ps1 \
-            npm-publish-asset/
-
-      - name: Upload release asset
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: npm-publish-asset-${{ github.run_id }}
-          path: npm-publish-asset/
-          if-no-files-found: error
-          overwrite: true
-
-      - name: Publish verified GitHub release
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        env:
-          RELEASE_TAG: ${{ github.ref_name }}
-        with:
-          github-token: ${{ github.token }}
-          script: |
-            const crypto = require("node:crypto");
-            const fs = require("node:fs");
-            const tag = process.env.RELEASE_TAG;
-            const { owner, repo } = context.repo;
-            const releases = await github.paginate(github.rest.repos.listReleases, {
-              owner,
-              repo,
-              per_page: 100,
-            });
-            const matches = releases.filter((release) => release.tag_name === tag);
-            if (matches.length !== 1) {
-              throw new Error(`expected exactly one draft release for ${tag}, found ${matches.length}`);
-            }
-            const release = matches[0];
-            if (!release.draft) {
-              throw new Error(`release ${tag} became public before verification completed`);
-            }
-
-            const checksumPath = "dist/checksums.txt";
-            const checksumBody = fs.readFileSync(checksumPath, "utf8");
-            const expectedDigests = new Map();
-            for (const line of checksumBody.split(/\r?\n/)) {
-              if (!line.trim()) continue;
-              const match = line.match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
-              if (!match) throw new Error(`invalid checksums.txt line: ${line}`);
-              const name = match[2];
-              if (expectedDigests.has(name)) {
-                throw new Error(`duplicate checksums.txt entry: ${name}`);
-              }
-              expectedDigests.set(name, `sha256:${match[1].toLowerCase()}`);
-            }
-            expectedDigests.set(
-              "checksums.txt",
-              `sha256:${crypto.createHash("sha256").update(checksumBody).digest("hex")}`,
-            );
-
-            const actualNames = release.assets.map((asset) => asset.name).sort();
-            const expectedNames = [...expectedDigests.keys()].sort();
-            if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {
-              throw new Error(
-                `draft release asset set mismatch: expected ${expectedNames.join(", ")}, got ${actualNames.join(", ")}`,
-              );
-            }
-            for (const asset of release.assets) {
-              const expected = expectedDigests.get(asset.name);
-              if (!asset.digest) {
-                throw new Error(`GitHub did not report a digest for draft asset ${asset.name}`);
-              }
-              if (asset.digest.toLowerCase() !== expected) {
-                throw new Error(
-                  `draft asset digest mismatch for ${asset.name}: expected ${expected}, got ${asset.digest}`,
-                );
-              }
-            }
-
-            await github.rest.repos.updateRelease({
-              owner,
-              repo,
-              release_id: release.id,
-              draft: false,
-              make_latest: "true",
-            });
-
-  publish-npm:
-    needs: build-release
-    runs-on: ubuntu-22.04
-    environment: npm-production
+  # Validate the macOS keychain signer on real hardware. The release binaries are
+  # cross-compiled on ubuntu (CGO-free purego FFI), so this is the only step that
+  # needs a Mac — and it gates the release rather than producing it.
+  signer-test-macos:
+    runs-on: macos-latest
     permissions:
       contents: read
-      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version: '1.23'
+      - name: Keychain signer round-trip (CGO-free purego FFI)
+        run: LARK_KEYCHAIN_IT=1 CGO_ENABLED=0 go test -tags keychain_signer -run Keychain -v ./internal/keysigner/
+
+  publish-npm:
+    needs: goreleaser
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
-      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: '22.14.0'
+          node-version: '20'
           registry-url: 'https://registry.npmjs.org'
-          package-manager-cache: false
 
-      - name: Install pinned npm
-        run: npm install --global npm@11.16.0
-
-      - name: Download release asset
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
-        with:
-          name: npm-publish-asset-${{ github.run_id }}
-          path: npm-publish-asset
-
-      - name: Verify npm publish asset
+      - name: Download checksums from release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -euo pipefail
-          (cd npm-publish-asset && sha256sum --check checksums.txt)
-          cp npm-publish-asset/checksums.txt checksums.txt
-          PACK_JSON="$(npm pack --ignore-scripts --json)"
-          PACK_FILE="$(node -e 'const p=JSON.parse(process.argv[1]); if(p.length!==1 || !p[0].filename) process.exit(1); process.stdout.write(p[0].filename)' "$PACK_JSON")"
-          test -s "$PACK_FILE"
-          tar -tzf "$PACK_FILE" | grep -qx 'package/checksums.txt'
-          rm "$PACK_FILE"
+          TAG="${GITHUB_REF_NAME}"
+          gh release download "${TAG}" --pattern checksums.txt --dir .
+          test -s checksums.txt || { echo "checksums.txt missing or empty for ${TAG}"; exit 1; }
 
       - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm publish --access public

.github/workflows/semantic-review.yml

@@ -25,16 +25,19 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            const workflowId = Number(run.workflow_id || 0);
-            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-            const { data: workflow } = await github.rest.actions.getWorkflow({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              workflow_id: workflowId,
-            });
-            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
-            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
-            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
+            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
+            let workflowPath = run.path || "";
+            if (!workflowPath) {
+              const workflowId = Number(run.workflow_id || 0);
+              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+              const { data: workflow } = await github.rest.actions.getWorkflow({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                workflow_id: workflowId,
+              });
+              workflowPath = workflow.path || "";
+            }
+            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");
             if (run.repository.full_name !== context.payload.repository.full_name) throw new Error("repository name mismatch");
@@ -250,16 +253,19 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            const workflowId = Number(run.workflow_id || 0);
-            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-            const { data: workflow } = await github.rest.actions.getWorkflow({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              workflow_id: workflowId,
-            });
-            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
-            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
-            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
+            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
+            let workflowPath = run.path || "";
+            if (!workflowPath) {
+              const workflowId = Number(run.workflow_id || 0);
+              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+              const { data: workflow } = await github.rest.actions.getWorkflow({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                workflow_id: workflowId,
+              });
+              workflowPath = workflow.path || "";
+            }
+            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.conclusion !== "success") throw new Error(`unexpected conclusion: ${run.conclusion}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");

.goreleaser.yml

@@ -5,68 +5,63 @@ before:
     - python3 scripts/fetch_meta.py
 
 builds:
-  - id: standard
+  # Linux & Windows: pure-Go TPM 2.0 signer is compiled in by default (no build
+  # tag), cross-compiled with CGO disabled — the binaries ship the platform key
+  # signer for private_key_jwt. windows/arm64 is the one exception: the sks
+  # Windows dependency stack (go-ole) has no arm64 support, so the signer file is
+  # arch-excluded there and that binary falls back to client_secret only.
+  - id: linux
     binary: lark-cli
+    main: .
     env:
       - CGO_ENABLED=0
+    flags:
+      - -trimpath
     ldflags:
       - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
     goos:
-      - darwin
       - linux
-      - windows
     goarch:
       - amd64
       - arm64
       - riscv64
-    ignore:
-      - goos: darwin
-        goarch: riscv64
-      - goos: windows
-        goarch: riscv64
-  - id: extended
+  - id: windows
     binary: lark-cli
-    tags:
-      - extended
+    main: .
     env:
       - CGO_ENABLED=0
+    flags:
+      - -trimpath
     ldflags:
       - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
     goos:
-      - darwin
-      - linux
       - windows
     goarch:
       - amd64
       - arm64
-      - riscv64
-    ignore:
-      - goos: darwin
-        goarch: riscv64
-      - goos: windows
-        goarch: riscv64
+  # macOS: the keychain signer calls Security.framework via runtime FFI (purego),
+  # so it is CGO-free, compiled into every darwin build (no build tag), and
+  # cross-compiles from the same ubuntu runner as linux/windows.
+  - id: darwin
+    binary: lark-cli
+    main: .
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
+    goos:
+      - darwin
+    goarch:
+      - amd64
+      - arm64
 
 archives:
-  - id: standard
-    ids:
-      - standard
-    name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
+  - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
     format_overrides:
       - goos: windows
-        formats:
-          - zip
-    files:
-      - README.md
-      - LICENSE
-      - CHANGELOG.md
-  - id: extended
-    ids:
-      - extended
-    name_template: "lark-cli-extended-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
-    format_overrides:
-      - goos: windows
-        formats:
-          - zip
+        formats: [zip]
     files:
       - README.md
       - LICENSE
@@ -74,18 +69,6 @@ archives:
 
 checksum:
   name_template: checksums.txt
-  extra_files:
-    - glob: ./scripts/install-extended.sh
-    - glob: ./scripts/install-extended.ps1
-
-release:
-  # Keep assets undiscoverable by releases/latest until the workflow has
-  # independently verified checksums, edition identity, and platform coverage.
-  draft: true
-  replace_existing_draft: true
-  extra_files:
-    - glob: ./scripts/install-extended.sh
-    - glob: ./scripts/install-extended.ps1
 
 changelog:
   sort: asc

CHANGELOG.md

@@ -2,120 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.80] - 2026-07-29
-
-### Features
-
-- **drive**: add +member-list shortcut (#1795)
-- **drive**: add +permission-get-setting shortcut (#1738)
-- propagate invocation metadata (#2097)
-
-### Documentation
-
-- **slides**: 补齐 shortcut 参数说明，修正 +xml-get --output 必填标注 (#2088)
-- **slides**: +create 的参数下沉到 create.md，主 skill 只留路由 (#2096)
-
-### Tests
-
-- **e2e**: wait for base role update visibility (#2087)
-
-### Misc
-
-- Feat/detect line text overlap (#2069)
-
-## [v1.0.79] - 2026-07-28
-
-### Features
-
-- **slides**: update xsd (#2067)
-
-### Bug Fixes
-
-- **ci**: validate static workflow identity (#2015)
-- **sheets**: recognize OFL0X local office tokens (#2063)
-
-### Documentation
-
-- **calendar**: clarify identity selection by event ownership (#2071)
-- **slides**: add formula inline element syntax to quick-ref (#2077)
-
-## [v1.0.78] - 2026-07-27
-
-### Features
-
-- event description support rich text (#1975)
-
-### Bug Fixes
-
-- **slides**: restrict canvas overflow checks
-- **slides**: upgrade text overflow to error above 10px threshold
-- **slides**: detect letterSpacing-driven text overflow
-- **slides**: downgrade background-decoration text overflow to info
-- **slides**: allow chartParsedValues roundtrip tag
-- refine character width estimation for lark-slides text lint
-- **slides**: preserve info lint severity
-- **slides**: text may over flow shape
-- exempt ghost text from slides lint
-
-## [v1.0.77] - 2026-07-24
-
-### Features
-
-- introducing official card icon (#1973)
-- **apps**: validate +file-list --page-size against server (0, 200] range (#2007)
-- **apps**: support absolute and relative upload paths (#2005)
-- **slides**: fill xml-schema-quick-ref gaps that forced XSD fallback (#2026)
-- **slides**: add layout density lint for sparse/empty containers (#2022)
-- add risk-control protection (#1910)
-
-### Bug Fixes
-
-- **slides**: normalize presentation flag aliases (#2032)
-- **base**: classify +form-submit as high-risk-write (#1969)
-- **slides**: declare screenshot scope
-- **slides**: support CSV multi-value for --slide-id in screenshot (#2047)
-
-### Documentation
-
-- **skill**: clarify scope handling for query expansion (#2030)
-- **base**: clarify complete and partial updates (#1993)
-- **skills**: clarify callout child rules (#2048)
-
-### Misc
-
-- fix/task id handling (#2023)
-- fix/task search pagination (#2041)
-
-## [v1.0.75] - 2026-07-22
-
-### Features
-
-- add okr single create shortcut & skill text opti (#1941)
-- **calendar**: auto-add bot self as attendee and note user-only search (#1991)
-
-### Bug Fixes
-
-- **base**: improve table shortcut behavior & guidance (#1803)
-- issue#1935 & whiteboard shortcut reformat (#1980)
-- remove legacy shortcut (#1997)
-- **e2e**: inject shared credentials by identity (#1995)
-
-### Documentation
-
-- **skill**: describe html5 block xml usage (#1380)
-- clarify fetch metadata and user cites (#1981)
-- add topic move collector workflow (#1473)
-- update lark doc HTML size limit (#2001)
-- **base**: align record write schema guidance (#2000)
-
-### Tests
-
-- **e2e**: declare request identities explicitly (#2004)
-
-### Misc
-
-- harden npm release publishing (#1918)
-
 ## [v1.0.74] - 2026-07-21
 
 ### Features
@@ -1722,11 +1608,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.80]: https://github.com/larksuite/cli/releases/tag/v1.0.80
-[v1.0.79]: https://github.com/larksuite/cli/releases/tag/v1.0.79
-[v1.0.78]: https://github.com/larksuite/cli/releases/tag/v1.0.78
-[v1.0.77]: https://github.com/larksuite/cli/releases/tag/v1.0.77
-[v1.0.75]: https://github.com/larksuite/cli/releases/tag/v1.0.75
 [v1.0.74]: https://github.com/larksuite/cli/releases/tag/v1.0.74
 [v1.0.73]: https://github.com/larksuite/cli/releases/tag/v1.0.73
 [v1.0.72]: https://github.com/larksuite/cli/releases/tag/v1.0.72

Makefile

@@ -23,7 +23,7 @@ PREFIX   ?= /usr/local
 TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
 RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
 
-.PHONY: all build vet fmt-check script-test test unit-test live-skills-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks sidecar-test extended-test
+.PHONY: all build vet fmt-check script-test test unit-test live-skills-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks sidecar-test
 
 all: test
 
@@ -50,9 +50,8 @@ fmt-check:
 script-test:
 	bash scripts/resolve-changed-from.test.sh
 	bash scripts/ci-workflow.test.sh
-	bash scripts/release-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
-	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/release-preflight.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
+	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
@@ -122,12 +121,6 @@ sidecar-test:
 	go test $(RACE_FLAG) -count=1 -tags authsidecar_demo ./sidecar/server-demo/
 	go test $(RACE_FLAG) -count=1 -tags authsidecar ./tests/sidecar_e2e/
 
-# extended-test compiles and exercises the separately distributed Extended
-# edition. The default build remains the Standard npm/npx binary.
-extended-test:
-	go build -tags extended -o /dev/null .
-	go test $(RACE_FLAG) -count=1 -tags extended ./cmd/... ./internal/... ./shortcuts/... ./extension/... ./tests/externalcredential_e2e
-
 # Run secret-leak checks locally before pushing.
 # Step 1: check-doc-tokens catches realistic-looking example tokens in reference
 #         docs and asks you to use _EXAMPLE_TOKEN placeholders instead.

README.md

@@ -285,29 +285,6 @@ To reduce these risks, the tool enables default security protections at multiple
 
 We recommend using the Lark/Feishu bot integrated with this tool as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.
 
-To reduce the security risks associated with access token theft, the CLI sends a minimal set of risk-control signals with OpenAPI requests made to exact official Feishu/Lark HTTPS domains. These signals are used to help identify anomalous API activity. This protection is enabled by default. The information sent is limited to:
-
-- Operating system type: macOS, Windows, or Linux
-- Device hardware model: for example, Mac17,9
-
-To disable this protection for the current workspace, run:
-
-```bash
-lark-cli config risk-control off
-```
-
-To enable this protection for the current workspace, run:
-
-```bash
-lark-cli config risk-control on
-```
-
-To restore the default policy for the current workspace, run:
-
-```bash
-lark-cli config risk-control default
-```
-
 Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.
 
 ## Star History

README.zh.md

@@ -286,29 +286,6 @@ lark-cli schema im.messages.delete
 
 我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
 
-为降低访问令牌被盗用后的安全风险，CLI 在向飞书/Lark 官方 HTTPS 精确域名发起 OpenAPI 请求时，会随请求发送一组最小化的风控信号，用于辅助识别异常调用行为。该保护默认开启，发送的信息仅包括：
-
-- 操作系统类型：macOS、Windows 或 Linux
-- 设备的硬件产品型号：例如 Mac17,9
-
-如需让当前 workspace 退出该保护，可执行以下命令：
-
-```bash
-lark-cli config risk-control off
-```
-
-如需开启当前 workspace 的保护，可执行以下命令：
-
-```bash
-lark-cli config risk-control on
-```
-
-恢复当前 workspace 默认策略可执行：
-
-```bash
-lark-cli config risk-control default
-```
-
 请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
 
 ## Star History

affordance/contact.md

@@ -23,41 +23,6 @@ lark-cli contact +search-user --query "alice" --as user
 lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
 ```
 
-## +search-bot
-Search bots (apps) by keyword. Pass `--query` or `--queries`; use `--chat-ids` to search within specific chats.
-
-### Skills
-- lark-contact/references/lark-contact-search-bot.md
-
-### Avoid when
-- Looking for a person rather than a bot → use [[+search-user]]
-- Running as a bot — this shortcut is user-only
-
-### Tips
-- `has_more=true` means the search is incomplete; refine the keyword or search scope instead of paginating
-
-### Examples
-
-**Find bots by keyword**
-```bash
-lark-cli contact +search-bot --query "会议助手" --as user
-```
-
-**Search inside one chat**
-```bash
-lark-cli contact +search-bot --query "助手" --chat-ids "oc_3a8b****6a7b" --as user
-```
-
-**Find bots you've chatted with**
-```bash
-lark-cli contact +search-bot --query "助手" --has-chatted --as user
-```
-
-**Search several bot keywords in one call**
-```bash
-lark-cli contact +search-bot --queries "会议助手,日报助手,审批助手" --as user
-```
-
 ## +get-user
 Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
 

cmd/auth/auth.go

@@ -18,7 +18,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 // NewCmdAuth creates the auth command with subcommands.
@@ -31,23 +30,21 @@ func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
 			// PersistentPreRun[E] found walking up the chain, so the root-level
 			// SilenceUsage=true would be skipped without this line.
 			cmd.SilenceUsage = true
-			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
+			// cmd.Name() returns the subcommand name (e.g. "login"), not "auth".
+			// Pass "auth" as a literal so the error message reads
+			// `"auth" is not supported: ...`
+			return f.RequireBuiltinCredentialProvider(cmd.Context(), "auth")
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalCredentialManagement)
 
-	login := NewCmdAuthLogin(f, nil)
-	logout := NewCmdAuthLogout(f, nil)
-	status := NewCmdAuthStatus(f, nil)
-	scopes := NewCmdAuthScopes(f, nil)
-	list := NewCmdAuthList(f, nil)
-	check := NewCmdAuthCheck(f, nil)
-	qrcode := NewCmdAuthQRCode(f, nil)
-	for _, diagnostic := range []*cobra.Command{status, scopes, check, qrcode} {
-		cmdutil.SetRuntimeCapabilities(diagnostic)
-	}
-	cmd.AddCommand(login, logout, status, scopes, list, check, qrcode)
+	cmd.AddCommand(NewCmdAuthLogin(f, nil))
+	cmd.AddCommand(NewCmdAuthLogout(f, nil))
+	cmd.AddCommand(NewCmdAuthStatus(f, nil))
+	cmd.AddCommand(NewCmdAuthScopes(f, nil))
+	cmd.AddCommand(NewCmdAuthList(f, nil))
+	cmd.AddCommand(NewCmdAuthCheck(f, nil))
+	cmd.AddCommand(NewCmdAuthQRCode(f, nil))
 	return cmd
 }
 

cmd/auth/auth_test.go

@@ -530,7 +530,10 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 	}{
 		{"login", []string{"login"}},
 		{"logout", []string{"logout"}},
+		{"status", []string{"status"}},
+		{"check", []string{"check", "--scope", "calendar:read"}}, // --scope is required
 		{"list", []string{"list"}},
+		{"scopes", []string{"scopes"}},
 	}
 
 	for _, tt := range tests {
@@ -555,19 +558,3 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 		})
 	}
 }
-
-func TestAuthReadOnlyCommandsAllowedByExternalProvider(t *testing.T) {
-	f := newFactoryWithExternalProvider(t)
-	for _, name := range []string{"status", "check", "scopes", "qrcode"} {
-		t.Run(name, func(t *testing.T) {
-			cmd := NewCmdAuth(f)
-			matched, _, err := cmd.Find([]string{name})
-			if err != nil {
-				t.Fatal(err)
-			}
-			if err := cmd.PersistentPreRunE(matched, nil); err != nil {
-				t.Fatalf("read-only command blocked: %v", err)
-			}
-		})
-	}
-}

cmd/auth/check.go

@@ -4,7 +4,6 @@
 package auth
 
 import (
-	"context"
 	"fmt"
 	"strings"
 
@@ -13,7 +12,6 @@ import (
 	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -35,7 +33,7 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.
 			if runF != nil {
 				return runF(opts)
 			}
-			return authCheckRunContext(cmd.Context(), opts)
+			return authCheckRun(opts)
 		},
 	}
 
@@ -48,10 +46,6 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.
 }
 
 func authCheckRun(opts *CheckOptions) error {
-	return authCheckRunContext(context.Background(), opts)
-}
-
-func authCheckRunContext(ctx context.Context, opts *CheckOptions) error {
 	f := opts.Factory
 
 	required := strings.Fields(opts.Scope)
@@ -63,74 +57,18 @@ func authCheckRunContext(ctx context.Context, opts *CheckOptions) error {
 	if err != nil {
 		return err
 	}
-	if f.Credential == nil {
-		return errs.NewInternalError(errs.SubtypeUnknown, "credential inspection is unavailable")
-	}
-
-	inspection, err := f.Credential.InspectToken(ctx, credential.TokenInspectionRequest{
-		TokenSpec: credential.TokenSpec{
-			Type:  credential.TokenTypeUAT,
-			AppID: config.AppID,
-		},
-		IncludeScopes: true,
-	})
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return err
-		}
-		return errs.NewInternalError(errs.SubtypeUnknown,
-			"failed to inspect user authorization: %v", err).
-			WithCause(err)
-	}
-	if inspection == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"credential source returned no authorization inspection")
-	}
-
-	if inspection.Status == credential.TokenInspectionNotLoggedIn && !inspection.Source.Managed {
+	if config.UserOpenId == "" {
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": false, "error": "not_logged_in", "missing": required})
 		return output.ErrBare(1)
 	}
-	if !inspection.Present {
-		if inspection.Source.Managed {
-			return errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-				"credential source %q did not provide a user access token", inspection.Source.Name).
-				WithHint("authorize the user through the selected credential source")
-		}
+
+	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
+	if stored == nil {
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": false, "error": "no_token", "missing": required})
 		return output.ErrBare(1)
 	}
 
-	switch inspection.ScopeState {
-	case credential.ScopeUnsupported:
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"auth check is unsupported by credential source %q because granted scopes are unavailable", inspection.Source.Name).
-			WithHint("the credential source must expose trusted scope metadata before `auth check` can evaluate --scope")
-	case credential.ScopeUnknown:
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"auth check result is unknown because credential source %q returned no scope metadata", inspection.Source.Name).
-			WithHint("configure the credential source to return trusted scopes for user access tokens")
-	case credential.ScopeKnown:
-		// Continue below.
-	default:
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"credential source %q returned invalid scope inspection state %q", inspection.Source.Name, inspection.ScopeState)
-	}
-
-	suggestion := ""
-	missing := larkauth.MissingScopes(inspection.Scopes, required)
-	if inspection.Source.Managed {
-		if len(missing) > 0 {
-			suggestion = fmt.Sprintf("grant these scopes through credential source %s: %s", inspection.Source.Name, strings.Join(missing, " "))
-		}
-	} else {
-		suggestion = fmt.Sprintf(`lark-cli auth login --scope "%s"`, strings.Join(missing, " "))
-	}
-	return writeAuthCheckResult(f, required, inspection.Scopes, suggestion)
-}
-
-func writeAuthCheckResult(f *cmdutil.Factory, required []string, availableScopes, suggestion string) error {
-	missing := larkauth.MissingScopes(availableScopes, required)
+	missing := larkauth.MissingScopes(stored.Scope, required)
 	missingSet := make(map[string]bool, len(missing))
 	for _, s := range missing {
 		missingSet[s] = true
@@ -144,8 +82,8 @@ func writeAuthCheckResult(f *cmdutil.Factory, required []string, availableScopes
 
 	ok := len(missing) == 0
 	result := map[string]interface{}{"ok": ok, "granted": granted, "missing": missing}
-	if len(missing) > 0 && suggestion != "" {
-		result["suggestion"] = suggestion
+	if len(missing) > 0 {
+		result["suggestion"] = fmt.Sprintf(`lark-cli auth login --scope "%s"`, strings.Join(missing, " "))
 	}
 	output.PrintJson(f.IOStreams.Out, result)
 	if !ok {

cmd/auth/check_test.go

@@ -4,20 +4,14 @@
 package auth
 
 import (
-	"bytes"
-	"context"
 	"encoding/json"
 	"errors"
-	"strings"
 	"testing"
 	"time"
 
-	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/zalando/go-keyring"
 )
@@ -152,128 +146,6 @@ func TestAuthCheckRun_ScopedTokenPresent_ExitZero(t *testing.T) {
 	}
 }
 
-type authCheckExternalProvider struct {
-	token        *extcred.Token
-	capabilities credential.ProviderCapabilities
-	resolveCalls int
-}
-
-func (p *authCheckExternalProvider) Name() string { return "external-check-test" }
-
-func (p *authCheckExternalProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
-	return &extcred.Account{AppID: "test-app", Brand: extcred.BrandFeishu}, nil
-}
-
-func (p *authCheckExternalProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
-	p.resolveCalls++
-	return p.token, nil
-}
-
-func (p *authCheckExternalProvider) CredentialCapabilities() credential.ProviderCapabilities {
-	return p.capabilities
-}
-
-func externalAuthCheckFactory(t *testing.T, canInspectScopes bool, token *extcred.Token) (*cmdutil.Factory, *authCheckExternalProvider) {
-	t.Helper()
-	cfg := &core.CliConfig{
-		AppID: "test-app",
-		Brand: core.BrandFeishu,
-	}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	provider := &authCheckExternalProvider{
-		token: token,
-		capabilities: credential.ProviderCapabilities{
-			ProvidesOnDemandAuth: true,
-			CanInspectScopes:     canInspectScopes,
-		},
-	}
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{provider},
-		nil,
-		nil,
-		nil,
-	)
-	return f, provider
-}
-
-func TestAuthCheckRun_ExternalDirectUsesProviderScopes(t *testing.T) {
-	f, provider := externalAuthCheckFactory(t, true, &extcred.Token{
-		Value:  "external-uat",
-		Scopes: "im:message docx:document",
-	})
-	stdout := f.IOStreams.Out.(*bytes.Buffer)
-
-	err := authCheckRun(&CheckOptions{
-		Factory: f,
-		Scope:   "im:message",
-	})
-	if err != nil {
-		t.Fatalf("authCheckRun() error = %v", err)
-	}
-	if provider.resolveCalls != 1 {
-		t.Fatalf("ResolveToken calls = %d, want 1", provider.resolveCalls)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Fatalf("stdout.ok = %v, want true; payload=%v", payload["ok"], payload)
-	}
-	granted, ok := payload["granted"].([]any)
-	if !ok || len(granted) != 1 || granted[0] != "im:message" {
-		t.Fatalf("stdout.granted = %v, want [im:message]", payload["granted"])
-	}
-}
-
-func TestAuthCheckRun_ExternalProxyReturnsTypedUnknown(t *testing.T) {
-	f, provider := externalAuthCheckFactory(t, false, &extcred.Token{
-		Value: "proxy-placeholder",
-	})
-
-	err := authCheckRun(&CheckOptions{
-		Factory: f,
-		Scope:   "im:message",
-	})
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error = %T %v, want typed error", err, err)
-	}
-	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("problem = %#v, want validation/failed_precondition", problem)
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) || !strings.Contains(problem.Message, "unsupported") || validation.Param != "" || problem.Hint == "" {
-		t.Fatalf("problem = %#v, want explicit unsupported result with actionable hint and no param", problem)
-	}
-	if provider.resolveCalls != 0 {
-		t.Fatalf("ResolveToken calls = %d, want 0 for proxy scope check", provider.resolveCalls)
-	}
-}
-
-func TestAuthCheckRun_ExternalDirectWithoutScopeMetadataReturnsTypedUnknown(t *testing.T) {
-	f, _ := externalAuthCheckFactory(t, true, &extcred.Token{
-		Value: "external-uat",
-	})
-
-	err := authCheckRun(&CheckOptions{
-		Factory: f,
-		Scope:   "im:message",
-	})
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error = %T %v, want typed error", err, err)
-	}
-	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("problem = %#v, want validation/failed_precondition", problem)
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) || !strings.Contains(problem.Message, "unknown") || validation.Param != "" || problem.Hint == "" {
-		t.Fatalf("problem = %#v, want explicit unknown result with actionable hint and no param", problem)
-	}
-}
-
 func TestAuthCheckRun_EmptyScopeIsValidationError(t *testing.T) {
 	// Scope validation is a real input error, not a predicate negative
 	// answer — it must surface as a typed ValidationError with the normal

cmd/auth/login.go

@@ -40,6 +40,10 @@ type LoginOptions struct {
 
 var pollDeviceToken = larkauth.PollDeviceToken
 
+var resolveLoginClientAuth = func(ctx context.Context, cfg *core.CliConfig) (larkauth.ClientAuth, error) {
+	return larkauth.ClientAuthFromConfig(cfg).ResolveSigner(ctx)
+}
+
 // NewCmdAuthLogin creates the auth login subcommand.
 func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Command {
 	opts := &LoginOptions{Factory: f}
@@ -265,7 +269,11 @@ func authLoginRun(opts *LoginOptions) error {
 	if err != nil {
 		return err
 	}
-	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
+	clientAuth, err := resolveLoginClientAuth(opts.Ctx, config)
+	if err != nil {
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
+	}
+	authResp, err := larkauth.RequestDeviceAuthorization(opts.Ctx, httpClient, clientAuth, config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
 		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
 	}
@@ -325,7 +333,7 @@ func authLoginRun(opts *LoginOptions) error {
 
 	// Step 3: Poll for token
 	log(msg.WaitingAuth)
-	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, clientAuth, config.Brand,
 		authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 
 	if !result.OK {
@@ -398,6 +406,10 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 	if err != nil {
 		return err
 	}
+	clientAuth, err := resolveLoginClientAuth(opts.Ctx, config)
+	if err != nil {
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "authorization failed: %v", err).WithCause(err)
+	}
 	requestedScope, err := loadLoginRequestedScope(opts.DeviceCode)
 	if err != nil {
 		fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to load cached requested scopes: %v\n", err)
@@ -415,7 +427,7 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)
-	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, clientAuth, config.Brand,
 		opts.DeviceCode, 5, 600, f.IOStreams.ErrOut)
 
 	if !result.OK {

cmd/auth/login_test.go

@@ -716,6 +716,14 @@ func TestAuthLoginRun_DeviceCodeUsesCachedRequestedScopes(t *testing.T) {
 	setupLoginConfigDir(t)
 	t.Setenv("HOME", t.TempDir())
 
+	originalResolve := resolveLoginClientAuth
+	resolveCalls := 0
+	resolveLoginClientAuth = func(_ context.Context, cfg *core.CliConfig) (larkauth.ClientAuth, error) {
+		resolveCalls++
+		return larkauth.ClientAuthFromConfig(cfg), nil
+	}
+	t.Cleanup(func() { resolveLoginClientAuth = originalResolve })
+
 	multi := &core.MultiAppConfig{
 		CurrentApp: "default",
 		Apps: []core.AppConfig{
@@ -778,6 +786,9 @@ func TestAuthLoginRun_DeviceCodeUsesCachedRequestedScopes(t *testing.T) {
 	if err != nil {
 		t.Fatalf("no-wait authLoginRun() error = %v", err)
 	}
+	if resolveCalls != 1 {
+		t.Fatalf("no-wait client auth preparations = %d, want 1", resolveCalls)
+	}
 	if got, err := loadLoginRequestedScope("device-code"); err != nil || got != "im:message:send" {
 		t.Fatalf("loadLoginRequestedScope() = (%q, %v), want requested scope", got, err)
 	}
@@ -793,6 +804,9 @@ func TestAuthLoginRun_DeviceCodeUsesCachedRequestedScopes(t *testing.T) {
 	if err != nil {
 		t.Fatalf("device-code authLoginRun() error = %v", err)
 	}
+	if resolveCalls != 2 {
+		t.Fatalf("split-flow client auth preparations = %d, want one per invocation", resolveCalls)
+	}
 	got := stderr.String()
 	for _, want := range []string{
 		"OK: 授权成功! 用户: tester (ou_user)",
@@ -847,7 +861,7 @@ func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {
 
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: true, Token: nil}
 	}
 
@@ -884,9 +898,17 @@ func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
 	keyring.MockInit()
 	setupLoginConfigDir(t)
 
+	originalResolve := resolveLoginClientAuth
+	resolveCalls := 0
+	resolveLoginClientAuth = func(_ context.Context, cfg *core.CliConfig) (larkauth.ClientAuth, error) {
+		resolveCalls++
+		return larkauth.ClientAuthFromConfig(cfg), nil
+	}
+	t.Cleanup(func() { resolveLoginClientAuth = originalResolve })
+
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: false, Message: "user denied"}
 	}
 
@@ -919,6 +941,9 @@ func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for aborted authorization")
 	}
+	if resolveCalls != 1 {
+		t.Fatalf("blocking-flow client auth preparations = %d, want 1", resolveCalls)
+	}
 	if gotCode := output.ExitCodeOf(err); gotCode != output.ExitAuth {
 		t.Fatalf("exit code = %d, want %d", gotCode, output.ExitAuth)
 	}

cmd/auth/qrcode.go

@@ -56,7 +56,6 @@ For ASCII output, the result is printed to stdout with fixed size.`,
 	cmd.Flags().IntVar(&opts.Size, "size", 256, "Size of the QR code image in pixels (default: 256, for PNG mode only)")
 	cmd.Flags().BoolVar(&opts.ASCII, "ascii", false, "Output ASCII QR code to stdout")
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "Output file path for PNG image (relative path within current directory, required for non-ASCII mode)")
-	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
 }

cmd/auth/status.go

@@ -44,10 +44,6 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 
 func authStatusRun(opts *StatusOptions) error {
 	f := opts.Factory
-	editionStatus, err := inspectEditionStatus(f)
-	if err != nil {
-		return err
-	}
 
 	config, err := f.Config()
 	if err != nil {
@@ -68,9 +64,7 @@ func authStatusRun(opts *StatusOptions) error {
 	result["identities"] = diagnostics
 	result["identity"] = effectiveIdentity(diagnostics)
 	addEffectiveVerification(result, diagnostics)
-	if !applyEditionStatus(result, diagnostics, editionStatus) {
-		addStatusNote(result, diagnostics)
-	}
+	addStatusNote(result, diagnostics)
 
 	output.PrintJson(f.IOStreams.Out, result)
 	return nil

cmd/auth/status_edition_extended.go

@@ -1,58 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package auth
-
-import (
-	"context"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/identitydiag"
-)
-
-type editionStatusState struct {
-	provider string
-	variant  string
-}
-
-func inspectEditionStatus(f *cmdutil.Factory) (editionStatusState, error) {
-	if f == nil || f.Credential == nil {
-		return editionStatusState{}, nil
-	}
-	source, err := f.Credential.InspectSource(context.Background())
-	if err != nil {
-		return editionStatusState{}, err
-	}
-	if source == nil || !source.Managed {
-		return editionStatusState{}, nil
-	}
-	state := editionStatusState{provider: source.Name}
-	description := f.RuntimeDescription()
-	if description.Managed {
-		state.variant = description.Variant
-	}
-	return state, nil
-}
-
-func applyEditionStatus(result map[string]interface{}, diagnostics identitydiag.Result, state editionStatusState) bool {
-	if state.provider == "" {
-		return false
-	}
-	result["source"] = "external"
-	result["credentialProvider"] = state.provider
-	if state.variant != "" {
-		result["externalCredentialMode"] = state.variant
-	}
-	switch {
-	case !diagnostics.User.Available && diagnostics.Bot.Available:
-		result["note"] = "User identity is " + identitydiag.StatusMessage(diagnostics.User.Status) +
-			"; bot identity is ready. Update authorization through external credential provider " + state.provider + "."
-	case diagnostics.User.Status == identitydiag.StatusNeedsRefresh:
-		result["note"] = "User identity needs refresh. Check external credential provider " + state.provider + "."
-	case !diagnostics.User.Available && !diagnostics.Bot.Available:
-		result["note"] = "No usable identity is available. Check external credential provider " + state.provider + "."
-	}
-	return true
-}

cmd/auth/status_edition_extended_test.go

@@ -1,54 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package auth
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/runtimeplan"
-)
-
-func TestExtendedAuthStatusReportsManagedSource(t *testing.T) {
-	cfg := &core.CliConfig{
-		AppID: "cli_env", Brand: core.BrandFeishu, DefaultAs: core.AsBot,
-		SupportedIdentities: uint8(extcred.SupportsBot),
-	}
-	f, stdout, _, _ := cmdutil.TestFactory(t, cfg)
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{&stubExternalProvider{name: "env"}},
-		nil, nil, f.HttpClient,
-	)
-	cmdutil.TestSetRuntimePlan(t, f, runtimeplan.New(runtimeplan.Options{
-		Description: runtimeplan.Description{
-			Managed: true,
-			Variant: "managed-test",
-		},
-	}))
-
-	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
-		t.Fatal(err)
-	}
-	var got map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	if got["source"] != "external" ||
-		got["credentialProvider"] != "env" ||
-		got["externalCredentialMode"] != "managed-test" ||
-		got["identity"] != "bot" {
-		t.Fatalf("output = %#v", got)
-	}
-	if note, _ := got["note"].(string); strings.Contains(note, "auth login") ||
-		!strings.Contains(note, "external credential provider env") {
-		t.Fatalf("note = %q", note)
-	}
-}

cmd/auth/status_edition_standard.go

@@ -1,21 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package auth
-
-import (
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/identitydiag"
-)
-
-type editionStatusState struct{}
-
-func inspectEditionStatus(*cmdutil.Factory) (editionStatusState, error) {
-	return editionStatusState{}, nil
-}
-
-func applyEditionStatus(map[string]interface{}, identitydiag.Result, editionStatusState) bool {
-	return false
-}

cmd/auth/status_edition_standard_test.go

@@ -1,49 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package auth
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-func TestStandardAuthStatusPreservesExistingProjection(t *testing.T) {
-	cfg := &core.CliConfig{
-		AppID: "cli_env", Brand: core.BrandFeishu, DefaultAs: core.AsBot,
-		SupportedIdentities: uint8(extcred.SupportsBot),
-	}
-	f, stdout, _, _ := cmdutil.TestFactory(t, cfg)
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{&stubExternalProvider{name: "env"}},
-		nil, nil, f.HttpClient,
-	)
-
-	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
-		t.Fatal(err)
-	}
-	var got map[string]json.RawMessage
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	for _, field := range []string{"source", "credentialProvider", "externalCredentialMode"} {
-		if _, exists := got[field]; exists {
-			t.Fatalf("Standard auth status contains edition field %q: %s", field, stdout.String())
-		}
-	}
-	var note string
-	if err := json.Unmarshal(got["note"], &note); err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(note, "lark-cli auth login") {
-		t.Fatalf("Standard note = %q, want established login guidance", note)
-	}
-}

cmd/auth/status_test.go

@@ -35,15 +35,6 @@ func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
 	if got.Identities.User.Status != "missing" || got.Identities.User.Available {
 		t.Fatalf("user = %#v, want missing and unavailable", got.Identities.User)
 	}
-	var raw map[string]json.RawMessage
-	if err := json.Unmarshal(stdout.Bytes(), &raw); err != nil {
-		t.Fatalf("json.Unmarshal(raw) error = %v", err)
-	}
-	for _, field := range []string{"source", "credentialProvider", "externalCredentialMode"} {
-		if _, exists := raw[field]; exists {
-			t.Fatalf("local auth status unexpectedly contains edition field %q: %s", field, stdout.String())
-		}
-	}
 }
 
 func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {

cmd/build.go

@@ -29,7 +29,6 @@ import (
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/internal/runtimebootstrap"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -46,7 +45,6 @@ type buildConfig struct {
 	skipService    bool
 	serviceCatalog *apicatalog.Catalog
 	startupBrand   core.LarkBrand
-	runtime        *runtimebootstrap.Result
 }
 
 // WithStartupBrand initializes the API registry with the given brand before
@@ -60,14 +58,6 @@ func WithStartupBrand(brand core.LarkBrand) BuildOption {
 	}
 }
 
-// withRuntimeBootstrap shares one invocation snapshot across registry,
-// credentials, transports, and command capabilities.
-func withRuntimeBootstrap(runtime *runtimebootstrap.Result) BuildOption {
-	return func(c *buildConfig) {
-		c.runtime = runtime
-	}
-}
-
 // WithIO sets the IO streams for the CLI by wrapping raw reader/writers.
 // Terminal detection is delegated to cmdutil.NewIOStreams.
 func WithIO(in io.Reader, out, errOut io.Writer) BuildOption {
@@ -153,9 +143,9 @@ func Build(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOpti
 	return rootCmd
 }
 
-// buildInternal assembles the command tree from one immutable startup
-// configuration snapshot. Profile selection happens before any registry
-// network decision and the same result is passed to the Factory.
+// buildInternal is a pure assembly function: it wires the command tree from
+// inv and BuildOptions alone. Any state-dependent decision (disk, network,
+// env) belongs in the caller and must be threaded in via BuildOption.
 //
 // Returns (factory, rootCmd, registry). The registry is nil when plugin
 // install failed (FailClosed guard installed) or when no plugin produced
@@ -178,29 +168,13 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 		cfg.streams = cmdutil.SystemIO()
 	}
 
-	startup := cfg.runtime
-	if startup == nil {
-		startup = runtimebootstrap.Resolve(inv.Profile)
-	}
-
 	// Initialize the registry brand before anything touches the runtime
 	// catalog (its sync.Once would otherwise lock onto the Feishu default).
-	// Runtime policy can close direct metadata egress before any command is
-	// registered, without exposing a concrete credential mode here.
-	registryBrand := cfg.startupBrand
-	if registryBrand == "" {
-		registryBrand = resolveStartupBrandFromConfig(inv.Profile, startup.ProfileConfig)
-	}
-	if !startup.Plan.AllowsRemoteMetadata() {
-		if registryBrand == "" {
-			registryBrand = core.BrandFeishu
-		}
-		registry.InitEmbeddedWithBrand(registryBrand)
-	} else if registryBrand != "" {
-		registry.InitWithBrand(registryBrand)
+	if cfg.startupBrand != "" {
+		registry.InitWithBrand(cfg.startupBrand)
 	}
 
-	f := cmdutil.NewDefaultWithRuntimePlan(cfg.streams, inv, startup.ProfileConfig, startup.Plan)
+	f := cmdutil.NewDefault(cfg.streams, inv)
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
@@ -246,7 +220,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
-	registerEditionCommands(rootCmd, f)
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
 	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	if !cfg.skipService {

cmd/build_workspace_test.go

@@ -1,176 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"io"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
-)
-
-func TestStartupProfileSnapshotUsesDetectedWorkspace(t *testing.T) {
-	previousWorkspace := core.CurrentWorkspace()
-	t.Cleanup(func() { core.SetCurrentWorkspace(previousWorkspace) })
-
-	tests := []struct {
-		name          string
-		workspace     core.Workspace
-		signalName    string
-		signalValue   string
-		expectedAppID string
-		expectedBrand core.LarkBrand
-	}{
-		{
-			name:          "local",
-			workspace:     core.WorkspaceLocal,
-			expectedAppID: "cli_local",
-			expectedBrand: core.BrandFeishu,
-		},
-		{
-			name:          "openclaw",
-			workspace:     core.WorkspaceOpenClaw,
-			signalName:    "OPENCLAW_CLI",
-			signalValue:   "1",
-			expectedAppID: "cli_openclaw",
-			expectedBrand: core.BrandLark,
-		},
-		{
-			name:          "hermes",
-			workspace:     core.WorkspaceHermes,
-			signalName:    "HERMES_HOME",
-			signalValue:   "/managed/hermes",
-			expectedAppID: "cli_hermes",
-			expectedBrand: core.BrandLark,
-		},
-		{
-			name:          "lark_channel",
-			workspace:     core.WorkspaceLarkChannel,
-			signalName:    "LARK_CHANNEL",
-			signalValue:   "1",
-			expectedAppID: "cli_lark_channel",
-			expectedBrand: core.BrandLark,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			clearWorkspaceSignals(t)
-			clearCredentialSignals(t)
-			configRoot := t.TempDir()
-			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configRoot)
-			t.Setenv(envvars.CliExternalCredentialConfig,
-				filepath.Join(configRoot, "missing-external-credential.json"))
-			t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-			if tt.signalName != "" {
-				t.Setenv(tt.signalName, tt.signalValue)
-			}
-
-			writeWorkspaceProfile(t, core.WorkspaceLocal, "local", "cli_local", core.BrandFeishu)
-			if !tt.workspace.IsLocal() {
-				writeWorkspaceProfile(t, tt.workspace, tt.name, tt.expectedAppID, tt.expectedBrand)
-			}
-
-			// Execute resolves the registry brand before entering
-			// buildInternal. Pin that ordering independently.
-			core.SetCurrentWorkspace(core.WorkspaceLocal)
-			if got := selectInvocationWorkspace(); got != tt.workspace {
-				t.Fatalf("selected workspace = %q, want %q", got, tt.workspace)
-			}
-			if got := ResolveStartupBrand(""); got != tt.expectedBrand {
-				t.Fatalf("startup brand = %q, want %q", got, tt.expectedBrand)
-			}
-
-			// Build/buildInternal is also a public construction path. Reset the
-			// process state to local so the test proves it establishes the
-			// workspace before SelectProfile captures the immutable snapshot.
-			core.SetCurrentWorkspace(core.WorkspaceLocal)
-			factory, _, _ := buildInternal(
-				context.Background(),
-				cmdutil.InvocationContext{},
-				WithIO(strings.NewReader(""), io.Discard, io.Discard),
-				WithoutPlugins(),
-				WithoutServiceCommands(),
-			)
-			if got := core.CurrentWorkspace(); got != tt.workspace {
-				t.Fatalf("workspace after build = %q, want %q", got, tt.workspace)
-			}
-			config, err := factory.Config()
-			if err != nil {
-				t.Fatalf("Factory.Config() error = %v", err)
-			}
-			if config.AppID != tt.expectedAppID || config.Brand != tt.expectedBrand {
-				t.Fatalf("resolved config = app %q (%s), want app %q (%s)",
-					config.AppID, config.Brand, tt.expectedAppID, tt.expectedBrand)
-			}
-		})
-	}
-}
-
-func clearWorkspaceSignals(t *testing.T) {
-	t.Helper()
-	for _, name := range []string{
-		"OPENCLAW_CLI",
-		"OPENCLAW_HOME",
-		"OPENCLAW_STATE_DIR",
-		"OPENCLAW_CONFIG_PATH",
-		"OPENCLAW_SERVICE_MARKER",
-		"OPENCLAW_SERVICE_VERSION",
-		"OPENCLAW_GATEWAY_PORT",
-		"OPENCLAW_SHELL",
-		"HERMES_HOME",
-		"HERMES_QUIET",
-		"HERMES_EXEC_ASK",
-		"HERMES_GATEWAY_TOKEN",
-		"HERMES_SESSION_KEY",
-		"LARK_CHANNEL",
-	} {
-		t.Setenv(name, "")
-	}
-}
-
-func clearCredentialSignals(t *testing.T) {
-	t.Helper()
-	for _, name := range []string{
-		envvars.CliAppID,
-		envvars.CliAppSecret,
-		envvars.CliBrand,
-		envvars.CliUserAccessToken,
-		envvars.CliTenantAccessToken,
-		envvars.CliDefaultAs,
-		envvars.CliStrictMode,
-	} {
-		t.Setenv(name, "")
-	}
-}
-
-func writeWorkspaceProfile(
-	t *testing.T,
-	workspace core.Workspace,
-	name string,
-	appID string,
-	brand core.LarkBrand,
-) {
-	t.Helper()
-	previous := core.CurrentWorkspace()
-	core.SetCurrentWorkspace(workspace)
-	defer core.SetCurrentWorkspace(previous)
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		CurrentApp: name,
-		Apps: []core.AppConfig{{
-			Name:      name,
-			AppId:     appID,
-			AppSecret: core.PlainSecret("test-secret-" + name),
-			Brand:     brand,
-			Users:     []core.AppUser{},
-		}},
-	}); err != nil {
-		t.Fatalf("save %s workspace profile: %v", workspace.Display(), err)
-	}
-}

cmd/config/bind.go

@@ -4,12 +4,18 @@
 package config
 
 import (
+	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/charmbracelet/huh"
+	"github.com/gofrs/flock"
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/errs"
@@ -22,9 +28,14 @@ import (
 	"github.com/larksuite/cli/internal/vfs"
 )
 
+const bindCommitLockTimeout = 5 * time.Second
+
+var bindCommitMu sync.Mutex
+
 // BindOptions holds all inputs for config bind.
 type BindOptions struct {
 	Factory *cmdutil.Factory
+	Ctx     context.Context
 	Source  string
 	AppID   string
 	// Identity selects one of two presets — "bot-only" or "user-default" —
@@ -94,6 +105,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
   # Interactive (terminal user) — TUI prompts for everything:
   lark-cli config bind`,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
 			if runF != nil {
 				return runF(opts)
@@ -139,10 +151,11 @@ func configBindRun(opts *BindOptions) error {
 		return nil
 	}
 
-	appConfig, err := resolveAccount(opts, source)
+	result, err := resolveAccount(opts, source)
 	if err != nil {
 		return err
 	}
+	appConfig := result.AppConfig
 	opts.Brand = string(appConfig.Brand)
 
 	if err := resolveIdentity(opts); err != nil {
@@ -151,10 +164,20 @@ func configBindRun(opts *BindOptions) error {
 	if err := warnIdentityEscalation(opts, existing.ConfigBytes); err != nil {
 		return err
 	}
-	applyPreferences(appConfig, opts, priorLang(existing.ConfigBytes))
+	if err := validateBindResult(bindContext(opts), opts, result); err != nil {
+		return err
+	}
+	applyPreferences(appConfig, opts, priorLangForApp(existing.ConfigBytes, appConfig.AppId))
 	noticeUserDefaultRisk(opts)
 
-	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
+	return commitBinding(opts, result, existing.ConfigBytes, source, targetConfigPath)
+}
+
+func bindContext(opts *BindOptions) context.Context {
+	if opts != nil && opts.Ctx != nil {
+		return opts.Ctx
+	}
+	return context.Background()
 }
 
 // existingBinding is the outcome of checking whether a workspace was already
@@ -239,9 +262,15 @@ func finalizeSource(opts *BindOptions) (string, error) {
 // notice on success so the caller still sees that a rebind happened.
 // See existingBinding for the returned fields.
 func reconcileExistingBinding(opts *BindOptions, source, configPath string) (existingBinding, error) {
-	oldConfigData, _ := vfs.ReadFile(configPath)
-	if oldConfigData == nil {
-		return existingBinding{}, nil
+	oldConfigData, err := vfs.ReadFile(configPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return existingBinding{}, nil
+		}
+		return existingBinding{}, errs.NewConfigError(errs.SubtypeInvalidConfig,
+			"cannot read existing workspace config %s: %v", configPath, err).
+			WithHint("fix the file permissions or I/O error before binding").
+			WithCause(err)
 	}
 
 	if opts.IsTUI {
@@ -264,7 +293,7 @@ func reconcileExistingBinding(opts *BindOptions, source, configPath string) (exi
 // enumerate candidates, pick one via the shared decision layer, and build a
 // ready-to-persist AppConfig. Adding a new bind source only requires
 // implementing SourceBinder — none of the logic below needs to change.
-func resolveAccount(opts *BindOptions, source string) (*core.AppConfig, error) {
+func resolveAccount(opts *BindOptions, source string) (*BindResult, error) {
 	binder, err := newBinder(source, opts)
 	if err != nil {
 		return nil, err
@@ -278,7 +307,7 @@ func resolveAccount(opts *BindOptions, source string) (*core.AppConfig, error) {
 	if err != nil {
 		return nil, err
 	}
-	return binder.Build(picked.AppID)
+	return binder.Build(bindContext(opts), *picked)
 }
 
 // resolveIdentity ensures opts.Identity is set before applyPreferences runs.
@@ -389,10 +418,21 @@ func applyPreferences(appConfig *core.AppConfig, opts *BindOptions, prior i18n.L
 // wrong profile's preference into a re-bind when the workspace holds multiple
 // named profiles and the active one disagrees with Apps[0].
 func priorLang(previousConfigBytes []byte) i18n.Lang {
+	return priorLangForApp(previousConfigBytes, "")
+}
+
+func priorLangForApp(previousConfigBytes []byte, appID string) i18n.Lang {
 	var multi core.MultiAppConfig
 	if json.Unmarshal(previousConfigBytes, &multi) != nil {
 		return ""
 	}
+	if appID != "" {
+		for i := range multi.Apps {
+			if multi.Apps[i].AppId == appID {
+				return multi.Apps[i].Lang
+			}
+		}
+	}
 	if app := multi.CurrentAppConfig(""); app != nil {
 		return app.Lang
 	}
@@ -400,12 +440,16 @@ func priorLang(previousConfigBytes []byte) i18n.Lang {
 }
 
 // commitBinding finalizes the bind: atomic write of the new workspace config,
-// best-effort cleanup of stale keychain entries from the previous binding (if
-// any), and a JSON success envelope. Cleanup runs only after the new config
-// is durably written — if anything fails earlier, the old workspace stays
-// usable.
-func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigBytes []byte, source, configPath string) error {
-	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}
+// deferred provider-manifest commit for keyless binds, and a JSON success
+// envelope. The write and provider commit are serialized across CLI processes;
+// if the provider commit fails, the workspace write is rolled back before any
+// success output so an existing binding remains usable.
+func commitBinding(opts *BindOptions, result *BindResult, previousConfigBytes []byte, source, configPath string) error {
+	appConfig := result.AppConfig
+	multi, err := mergeBoundApp(appConfig, previousConfigBytes, opts.langExplicit)
+	if err != nil {
+		return err
+	}
 
 	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
 		return errs.NewInternalError(errs.SubtypeFileIO, "failed to create workspace directory: %v", err).WithCause(err)
@@ -414,9 +458,38 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	if err != nil {
 		return errs.NewInternalError(errs.SubtypeStorage, "failed to marshal config: %v", err).WithCause(err)
 	}
-	if err := validate.AtomicWrite(configPath, append(data, '\n'), 0600); err != nil {
+	releaseCommitLock, err := acquireBindCommitLock(opts)
+	if err != nil {
+		return err
+	}
+	commitLockHeld := true
+	defer func() {
+		if commitLockHeld {
+			releaseCommitLock()
+		}
+	}()
+	if err := ensureBindingSnapshotUnchanged(configPath, previousConfigBytes); err != nil {
+		return err
+	}
+	newConfigBytes := append(data, '\n')
+	if err := validate.AtomicWrite(configPath, newConfigBytes, 0600); err != nil {
 		return errs.NewInternalError(errs.SubtypeStorage, "failed to write config %s: %v", configPath, err).WithCause(err)
 	}
+	if result.commitProviderManifest != nil {
+		if err := result.commitProviderManifest(); err != nil {
+			rollbackErr := rollbackBindingConfig(configPath, previousConfigBytes, newConfigBytes)
+			if rollbackErr != nil {
+				return errs.NewInternalError(errs.SubtypeStorage,
+					"failed to persist keyless signer provider: %v; failed to restore workspace config: %v", err, rollbackErr).
+					WithCause(err)
+			}
+			return errs.NewInternalError(errs.SubtypeStorage,
+				"failed to persist keyless signer provider (workspace config restored): %v", err).
+				WithCause(err)
+		}
+	}
+	releaseCommitLock()
+	commitLockHeld = false
 
 	replaced := previousConfigBytes != nil
 	// uiMsg renders human-facing TUI text (stderr success banner). Follows
@@ -425,10 +498,6 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	uiMsg := getBindMsg(opts.UILang)
 	display := sourceDisplayName(source)
 
-	if replaced {
-		cleanupKeychainFromData(opts.Factory.Keychain, previousConfigBytes, appConfig)
-	}
-
 	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
 		fmt.Sprintf(uiMsg.BindSuccessHeader, display)+"\n"+uiMsg.BindSuccessNotice)
 
@@ -470,6 +539,133 @@ func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigB
 	return nil
 }
 
+func acquireBindCommitLock(opts *BindOptions) (func(), error) {
+	bindCommitMu.Lock()
+	lockDir := filepath.Join(core.GetBaseConfigDir(), "locks")
+	if err := vfs.MkdirAll(lockDir, 0700); err != nil {
+		bindCommitMu.Unlock()
+		return nil, errs.NewInternalError(errs.SubtypeStorage,
+			"failed to create bind lock directory: %v", err).WithCause(err)
+	}
+	fileLock := flock.New(filepath.Join(lockDir, "config-bind.lock"))
+	ctx, cancel := context.WithTimeout(bindContext(opts), bindCommitLockTimeout)
+	locked, err := fileLock.TryLockContext(ctx, 50*time.Millisecond)
+	cancel()
+	if err != nil || !locked {
+		bindCommitMu.Unlock()
+		if err == nil {
+			err = context.DeadlineExceeded
+		}
+		return nil, errs.NewInternalError(errs.SubtypeStorage,
+			"failed to acquire config bind lock: %v", err).WithCause(err)
+	}
+	return func() {
+		_ = fileLock.Unlock()
+		bindCommitMu.Unlock()
+	}, nil
+}
+
+func ensureBindingSnapshotUnchanged(configPath string, previousConfigBytes []byte) error {
+	current, err := vfs.ReadFile(configPath)
+	if err != nil {
+		if os.IsNotExist(err) && previousConfigBytes == nil {
+			return nil
+		}
+		return errs.NewInternalError(errs.SubtypeStorage,
+			"failed to recheck workspace config %s before binding: %v", configPath, err).WithCause(err)
+	}
+	if previousConfigBytes != nil && bytes.Equal(current, previousConfigBytes) {
+		return nil
+	}
+	return errs.NewConfigError(errs.SubtypeInvalidConfig,
+		"workspace config %s changed while the bind was being validated", configPath).
+		WithHint("retry config bind using the latest workspace state")
+}
+
+func rollbackBindingConfig(configPath string, previousConfigBytes, writtenConfigBytes []byte) error {
+	current, err := vfs.ReadFile(configPath)
+	if err != nil {
+		if os.IsNotExist(err) && previousConfigBytes == nil {
+			return nil
+		}
+		//nolint:forbidigo // intermediate rollback diagnostic; commitBinding wraps it into a typed storage error
+		return fmt.Errorf("recheck workspace config before rollback: %w", err)
+	}
+	if !bytes.Equal(current, writtenConfigBytes) {
+		//nolint:forbidigo // intermediate rollback diagnostic; commitBinding wraps it into a typed storage error
+		return fmt.Errorf("workspace config changed after the bind write; refusing to overwrite it during rollback")
+	}
+	if previousConfigBytes != nil {
+		return validate.AtomicWrite(configPath, previousConfigBytes, 0600)
+	}
+	if err := vfs.Remove(configPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// mergeBoundApp upserts by unique appId and activates the target while
+// preserving every non-target profile and root policy.
+func mergeBoundApp(incoming *core.AppConfig, previousBytes []byte, langExplicit bool) (*core.MultiAppConfig, error) {
+	if incoming == nil || strings.TrimSpace(incoming.AppId) == "" {
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "config bind produced an empty app")
+	}
+	if previousBytes == nil {
+		return &core.MultiAppConfig{Apps: []core.AppConfig{*incoming}, CurrentApp: incoming.ProfileName()}, nil
+	}
+
+	var multi core.MultiAppConfig
+	if err := json.Unmarshal(previousBytes, &multi); err != nil {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig,
+			"cannot update malformed workspace config: %v", err).WithCause(err)
+	}
+	match := -1
+	for i := range multi.Apps {
+		if multi.Apps[i].AppId != incoming.AppId {
+			continue
+		}
+		if match >= 0 {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidConfig,
+				"appId %s appears in multiple CLI profiles", incoming.AppId).
+				WithHint("remove the duplicate profile before binding")
+		}
+		match = i
+	}
+
+	oldActive := ""
+	if active := multi.CurrentAppConfig(""); active != nil {
+		oldActive = active.ProfileName()
+	}
+	if match >= 0 {
+		old := multi.Apps[match]
+		incoming.Name = old.Name
+		incoming.Users = old.Users
+		if !langExplicit {
+			incoming.Lang = old.Lang
+		}
+		multi.Apps[match] = *incoming
+	} else {
+		for i := range multi.Apps {
+			if multi.Apps[i].Name != "" && multi.Apps[i].Name == incoming.AppId {
+				return nil, errs.NewConfigError(errs.SubtypeInvalidConfig,
+					"new appId %s conflicts with existing profile name", incoming.AppId).
+					WithHint("rename the existing profile before binding")
+			}
+		}
+		incoming.Name = ""
+		incoming.Users = []core.AppUser{}
+		multi.Apps = append(multi.Apps, *incoming)
+		match = len(multi.Apps) - 1
+	}
+
+	targetName := multi.Apps[match].ProfileName()
+	if oldActive != targetName {
+		multi.PreviousApp = oldActive
+		multi.CurrentApp = targetName
+	}
+	return &multi, nil
+}
+
 // cleanupKeychainFromData removes keychain entries referenced by a previous
 // config snapshot, skipping any entry whose keychain ID is still in use by
 // the new app config. This prevents rebinding the same appId from deleting

cmd/config/bind_test.go

@@ -84,6 +84,21 @@ func saveWorkspace(t *testing.T) {
 	t.Cleanup(func() { core.SetCurrentWorkspace(orig) })
 }
 
+func TestReconcileExistingBinding_ReadFailureIsNotTreatedAsMissing(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	if err := os.Mkdir(configPath, 0700); err != nil {
+		t.Fatal(err)
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	_, err := reconcileExistingBinding(&BindOptions{Factory: f}, "openclaw", configPath)
+	if err == nil || !strings.Contains(err.Error(), "cannot read existing workspace config") {
+		t.Fatalf("reconcileExistingBinding error = %v", err)
+	}
+	if info, statErr := os.Stat(configPath); statErr != nil || !info.IsDir() {
+		t.Fatalf("unreadable existing config was changed: info=%v error=%v", info, statErr)
+	}
+}
+
 // ── Command flag parsing tests (aligned with config_test.go pattern) ──
 
 func TestConfigBindCmd_FlagParsing(t *testing.T) {
@@ -1497,7 +1512,11 @@ func assertPresetApplied(t *testing.T, configPath string, wantStrict core.Strict
 	if len(multi.Apps) == 0 {
 		t.Fatalf("no apps in %s", configPath)
 	}
-	app := multi.Apps[0]
+	appPtr := multi.CurrentAppConfig("")
+	if appPtr == nil {
+		t.Fatalf("no current app in %s", configPath)
+	}
+	app := *appPtr
 	if app.StrictMode == nil || *app.StrictMode != wantStrict {
 		t.Errorf("StrictMode = %v, want %q", app.StrictMode, wantStrict)
 	}

cmd/config/binder.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -23,6 +24,19 @@ type Candidate struct {
 	Label string
 }
 
+// BindResult carries the selected app. External signer configuration is the
+// logical provider on AppConfig.KeyRef; bind never persists executable paths.
+type BindResult struct {
+	AppConfig *core.AppConfig
+
+	// commitProviderManifest is populated only after a keyless bind probe has
+	// authenticated successfully. commitBinding runs it after the workspace
+	// config write and rolls that write back if the global provider index cannot
+	// be committed, so a failed bind never changes the signer used by existing
+	// applications.
+	commitProviderManifest func() error
+}
+
 // SourceBinder abstracts a bind source (openclaw / hermes / future sources).
 // Implementations only list candidates and build an AppConfig for a chosen
 // candidate — they stay out of mode (TUI vs flag) and orchestration concerns.
@@ -34,9 +48,9 @@ type SourceBinder interface {
 	// ListCandidates enumerates bindable accounts from the source config.
 	// An empty slice is valid (selectCandidate will turn it into a typed error).
 	ListCandidates() ([]Candidate, error)
-	// Build resolves secrets, persists to keychain, and returns a ready AppConfig
-	// for the chosen candidate AppID. Must be called after ListCandidates succeeds.
-	Build(appID string) (*core.AppConfig, error)
+	// Build resolves credentials and returns the app plus any signer command
+	// needed by the workspace. Must be called after ListCandidates succeeds.
+	Build(ctx context.Context, candidate Candidate) (*BindResult, error)
 }
 
 // newBinder constructs the SourceBinder for the given source name.
@@ -93,11 +107,21 @@ func selectCandidate(
 	}
 
 	if appIDFlag != "" {
+		var matches []Candidate
 		for i := range candidates {
 			if candidates[i].AppID == appIDFlag {
-				return &candidates[i], nil
+				matches = append(matches, candidates[i])
 			}
 		}
+		if len(matches) == 1 {
+			return &matches[0], nil
+		}
+		if len(matches) > 1 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"--app-id %q matches multiple accounts in %s", appIDFlag, cfgBase).
+				WithHint("run 'lark-cli config bind' interactively to choose an account, or configure unique app IDs:\n  %s", formatCandidates(matches)).
+				WithParam("--app-id")
+		}
 		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id %q not found in %s", appIDFlag, cfgBase).
 			WithHint("available app IDs:\n  %s", formatCandidates(candidates)).
 			WithParam("--app-id")
@@ -168,20 +192,48 @@ func (b *openclawBinder) ListCandidates() ([]Candidate, error) {
 	return result, nil
 }
 
-func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
+func (b *openclawBinder) Build(_ context.Context, candidate Candidate) (*BindResult, error) {
 	if b.cfg == nil {
 		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
 
 	var selected *binding.CandidateApp
 	for i := range b.rawApps {
-		if b.rawApps[i].AppID == appID {
+		if b.rawApps[i].AppID == candidate.AppID && b.rawApps[i].Label == candidate.Label {
 			selected = &b.rawApps[i]
 			break
 		}
 	}
 	if selected == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError,
+			"internal: account %q (appID %q) not in candidates", candidate.Label, candidate.AppID)
+	}
+	if selected.AuthMethod != "" && selected.AuthMethod != "app_secret" && selected.AuthMethod != binding.AuthMethodPrivateKeyJWT {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "unknown authMethod %q for app %s in %s", selected.AuthMethod, selected.AppID, b.path).
+			WithHint("supported values are app_secret and private_key_jwt")
+	}
+
+	// openclaw-lark deliberately gives appSecret precedence when both shapes
+	// are present. Reproduce that behavior so bind never changes the effective
+	// credential type merely because authMethod was left stale.
+	if selected.AppSecret.IsZero() && selected.AuthMethod == binding.AuthMethodPrivateKeyJWT {
+		if strings.TrimSpace(selected.KeyRef) == "" {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidConfig,
+				"private_key_jwt app %s in %s is missing keyRef", selected.AppID, b.path).
+				WithHint("re-run OpenClaw onboarding so the keyless account records its signer keyRef")
+		}
+		return &BindResult{
+			AppConfig: &core.AppConfig{
+				AppId:      selected.AppID,
+				Brand:      core.ParseBrand(selected.Brand),
+				AuthMethod: core.AuthMethodPrivateKeyJWT,
+				KeyRef: &core.SecretRef{
+					Source:   core.SecretSourceTEE,
+					Provider: core.KeylessProviderLarkSuite,
+					ID:       strings.TrimSpace(selected.KeyRef),
+				},
+			},
+		}, nil
 	}
 
 	if selected.AppSecret.IsZero() {
@@ -202,11 +254,11 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 			WithCause(err)
 	}
 
-	return &core.AppConfig{
+	return &BindResult{AppConfig: &core.AppConfig{
 		AppId:     selected.AppID,
 		AppSecret: stored,
 		Brand:     core.ParseBrand(selected.Brand),
-	}, nil
+	}}, nil
 }
 
 // ──────────────────────────────────────────────────────────────
@@ -238,7 +290,8 @@ func (b *hermesBinder) ListCandidates() ([]Candidate, error) {
 	return []Candidate{{AppID: appID, Label: "default"}}, nil
 }
 
-func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
+func (b *hermesBinder) Build(_ context.Context, candidate Candidate) (*BindResult, error) {
+	appID := candidate.AppID
 	if b.envMap == nil {
 		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
@@ -258,11 +311,11 @@ func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 			WithCause(err)
 	}
 
-	return &core.AppConfig{
+	return &BindResult{AppConfig: &core.AppConfig{
 		AppId:     appID,
 		AppSecret: stored,
 		Brand:     core.ParseBrand(b.envMap["FEISHU_DOMAIN"]),
-	}, nil
+	}}, nil
 }
 
 // ──────────────────────────────────────────────────────────────
@@ -295,7 +348,8 @@ func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {
 	return []Candidate{{AppID: cfg.Accounts.App.ID, Label: "default"}}, nil
 }
 
-func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
+func (b *larkChannelBinder) Build(_ context.Context, candidate Candidate) (*BindResult, error) {
+	appID := candidate.AppID
 	if b.cfg == nil {
 		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
@@ -323,11 +377,11 @@ func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 			WithCause(err)
 	}
 
-	return &core.AppConfig{
+	return &BindResult{AppConfig: &core.AppConfig{
 		AppId:     appID,
 		AppSecret: stored,
 		Brand:     core.ParseBrand(b.cfg.Accounts.App.Tenant),
-	}, nil
+	}}, nil
 }
 
 // ──────────────────────────────────────────────────────────────

cmd/config/binder_test.go

@@ -4,10 +4,12 @@
 package config
 
 import (
+	"context"
 	"path/filepath"
 	"reflect"
 	"testing"
 
+	"github.com/larksuite/cli/internal/binding"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -20,10 +22,10 @@ type fakeBinder struct {
 	path string
 }
 
-func (b *fakeBinder) Name() string                                { return b.name }
-func (b *fakeBinder) ConfigPath() string                          { return b.path }
-func (b *fakeBinder) ListCandidates() ([]Candidate, error)        { return nil, nil }
-func (b *fakeBinder) Build(appID string) (*core.AppConfig, error) { return nil, nil }
+func (b *fakeBinder) Name() string                                          { return b.name }
+func (b *fakeBinder) ConfigPath() string                                    { return b.path }
+func (b *fakeBinder) ListCandidates() ([]Candidate, error)                  { return nil, nil }
+func (b *fakeBinder) Build(context.Context, Candidate) (*BindResult, error) { return nil, nil }
 
 // tuiUnreachable is a tuiPrompt that fails the test if called. It's the
 // guardrail that proves the non-TUI decision paths really do stay out of the
@@ -107,6 +109,20 @@ func TestSelectCandidate_AppIDFlag_NoMatch(t *testing.T) {
 	})
 }
 
+func TestSelectCandidate_AppIDFlag_RejectsDuplicateInheritedAppID(t *testing.T) {
+	b := &fakeBinder{name: "openclaw", path: "/tmp/openclaw.json"}
+	candidates := []Candidate{
+		{AppID: "cli_shared", Label: "work"},
+		{AppID: "cli_shared", Label: "personal"},
+	}
+	_, err := selectCandidate(b, candidates, "cli_shared", false, tuiUnreachable(t))
+	assertExitError(t, err, output.ExitValidation, wantErrDetail{
+		Type:    "validation",
+		Message: `--app-id "cli_shared" matches multiple accounts in openclaw.json`,
+		Hint:    "run 'lark-cli config bind' interactively to choose an account, or configure unique app IDs:\n  cli_shared (work)\n  cli_shared (personal)",
+	})
+}
+
 func TestSelectCandidate_MultiCandidate_NoFlag_NonTUI(t *testing.T) {
 	// Flag-mode with multiple candidates and no --app-id must produce a
 	// validation error and the candidate list, never an interactive prompt.
@@ -175,6 +191,27 @@ func TestSelectCandidate_AppIDFlag_WinsOverTUI(t *testing.T) {
 	assertCandidate(t, got, Candidate{AppID: "cli_b"})
 }
 
+func TestOpenClawBuildUsesSelectedLabelWhenAppIDIsShared(t *testing.T) {
+	b := &openclawBinder{
+		cfg: &binding.OpenClawRoot{},
+		rawApps: []binding.CandidateApp{
+			{Label: "work", AppID: "cli_shared", AuthMethod: binding.AuthMethodPrivateKeyJWT, KeyRef: "work-key"},
+			{Label: "personal", AppID: "cli_shared", AuthMethod: binding.AuthMethodPrivateKeyJWT, KeyRef: "personal-key"},
+		},
+	}
+
+	result, err := b.Build(context.Background(), Candidate{AppID: "cli_shared", Label: "personal"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.AppConfig.KeyRef == nil || result.AppConfig.KeyRef.ID != "personal-key" {
+		t.Fatalf("keyRef = %#v, want personal-key", result.AppConfig.KeyRef)
+	}
+	if result.AppConfig.KeyRef.Provider != core.KeylessProviderLarkSuite {
+		t.Fatalf("provider = %q, want %q", result.AppConfig.KeyRef.Provider, core.KeylessProviderLarkSuite)
+	}
+}
+
 func TestResolveLarkChannelConfigPath_Default(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)

cmd/config/config.go

@@ -6,7 +6,6 @@ package config
 import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/runtimeplan"
 	"github.com/spf13/cobra"
 )
 
@@ -20,38 +19,21 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 			// PersistentPreRun[E] found walking up the chain, so the root-level
 			// SilenceUsage=true would be skipped without this line.
 			cmd.SilenceUsage = true
-			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
+			// Pass "config" as a literal — cmd.Name() would return the subcommand name.
+			return f.RequireBuiltinCredentialProvider(cmd.Context(), "config")
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalCredentialManagement)
 
-	initCmd := NewCmdConfigInit(f, nil)
-	bind := NewCmdConfigBind(f, nil)
-	remove := NewCmdConfigRemove(f, nil)
-	show := NewCmdConfigShow(f, nil)
-	defaultAs := NewCmdConfigDefaultAs(f)
-	strictMode := NewCmdConfigStrictMode(f)
-	riskControl := NewCmdConfigRiskControl(f)
-	policy := NewCmdConfigPolicy(f)
-	plugins := NewCmdConfigPlugins(f)
-	keychainDowngrade := NewCmdConfigKeychainDowngrade(f)
-	// Identity preferences live in the Profile, but external providers have
-	// historically treated these config commands as credential management.
-	// Check Profile ownership first so a managed runtime gives the actionable
-	// deployment-managed Profile error, then retain the credential capability
-	// so Standard external-provider behavior stays unchanged.
-	for _, identitySetting := range []*cobra.Command{defaultAs, strictMode} {
-		cmdutil.SetRuntimeCapabilities(
-			identitySetting,
-			runtimeplan.CapabilityLocalProfileMutation,
-			runtimeplan.CapabilityLocalCredentialManagement,
-		)
-	}
-	for _, sourceNeutral := range []*cobra.Command{show, riskControl, policy, plugins} {
-		cmdutil.SetRuntimeCapabilities(sourceNeutral)
-	}
-	cmd.AddCommand(initCmd, bind, remove, show, defaultAs, strictMode, riskControl, policy, plugins, keychainDowngrade)
+	cmd.AddCommand(NewCmdConfigInit(f, nil))
+	cmd.AddCommand(NewCmdConfigBind(f, nil))
+	cmd.AddCommand(NewCmdConfigRemove(f, nil))
+	cmd.AddCommand(NewCmdConfigShow(f, nil))
+	cmd.AddCommand(NewCmdConfigDefaultAs(f))
+	cmd.AddCommand(NewCmdConfigStrictMode(f))
+	cmd.AddCommand(NewCmdConfigPolicy(f))
+	cmd.AddCommand(NewCmdConfigPlugins(f))
+	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))
 	return cmd
 }
 

cmd/config/config_test.go

@@ -20,7 +20,6 @@ import (
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 type noopConfigKeychain struct{}
@@ -66,6 +65,39 @@ func TestConfigInitCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestConfigInitCmd_PrivateKeyJWTFlag(t *testing.T) {
+	clearAgentEnv(t) // assumes local workspace; guard refuses init in agent contexts
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *ConfigInitOptions
+	cmd := NewCmdConfigInit(f, func(opts *ConfigInitOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--new", "--private-key-jwt"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !gotOpts.PrivateKeyJWT {
+		t.Error("PrivateKeyJWT = false, want true")
+	}
+}
+
+func TestConfigInitCmd_AuthMethodFlagRemoved(t *testing.T) {
+	clearAgentEnv(t) // assumes local workspace; guard refuses init in agent contexts
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdConfigInit(f, func(opts *ConfigInitOptions) error { return nil })
+	cmd.SetArgs([]string{"--new", "--auth-method", core.AuthMethodPrivateKeyJWT})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected unknown flag error")
+	}
+	if !strings.Contains(err.Error(), "unknown flag: --auth-method") {
+		t.Fatalf("error = %v, want unknown --auth-method flag", err)
+	}
+}
+
 func TestConfigShowCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -194,7 +226,7 @@ func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
 		t.Fatalf("seed config: %v", err)
 	}
 
-	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
+	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, "", "", nil); err != nil {
 		t.Fatalf("saveInitConfig (no --lang): %v", err)
 	}
 
@@ -207,6 +239,68 @@ func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
 	}
 }
 
+func TestKeyRefFromResult_PrivateKeyJWT(t *testing.T) {
+	ref := keyRefFromResult(&configInitResult{
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel:   "lark-cli-default",
+	})
+	if ref == nil {
+		t.Fatal("keyRefFromResult returned nil")
+	}
+	if ref.Source != "tee" || ref.ID != "lark-cli-default" {
+		t.Fatalf("key ref = %#v, want tee/lark-cli-default", ref)
+	}
+
+	if ref := keyRefFromResult(&configInitResult{AuthMethod: core.AuthMethodPrivateKeyJWT}); ref != nil {
+		t.Fatalf("missing key label should not persist key ref, got %#v", ref)
+	}
+	if ref := keyRefFromResult(&configInitResult{AuthMethod: core.AuthMethodClientSecret, KeyLabel: "ignored"}); ref != nil {
+		t.Fatalf("client_secret should not persist key ref, got %#v", ref)
+	}
+	if ref := keyRefFromResult(nil); ref != nil {
+		t.Fatalf("nil result should not persist key ref, got %#v", ref)
+	}
+}
+
+func TestPersistInitResult_PrivateKeyJWT(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		profile string
+		brand   core.LarkBrand
+	}{
+		{name: "single app", brand: core.BrandFeishu},
+		{name: "named profile", profile: "prod", brand: core.BrandLark},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			opts := &ConfigInitOptions{Factory: f, Ctx: context.Background(), Lang: "en_us"}
+			result := &configInitResult{
+				Brand: tc.brand, AppID: "cli_pkjwt",
+				AuthMethod: core.AuthMethodPrivateKeyJWT, KeyLabel: "lark-cli-default",
+			}
+			if err := persistInitResult(opts, f, tc.profile, result); err != nil {
+				t.Fatal(err)
+			}
+
+			got, err := core.LoadMultiAppConfig()
+			if err != nil {
+				t.Fatal(err)
+			}
+			app := got.CurrentAppConfig(tc.profile)
+			if app == nil || app.AppId != "cli_pkjwt" || app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+				t.Fatalf("saved app = %#v", app)
+			}
+			if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID != "lark-cli-default" {
+				t.Fatalf("KeyRef = %#v, want tee/lark-cli-default", app.KeyRef)
+			}
+			if !app.AppSecret.IsZero() {
+				t.Fatalf("private_key_jwt config must stay secretless, AppSecret value %#v", app.AppSecret)
+			}
+		})
+	}
+}
+
 // TestConfigInitCmd_InvalidLang verifies a non-empty --lang on config init is
 // strictly validated the same way bind validates: wrong-case / typo / removed
 // codes / hyphen form all exit with ExitValidation. (Empty is a no-op.)
@@ -389,7 +483,7 @@ func TestSaveAsProfile_RejectsProfileNameCollisionWithExistingAppID(t *testing.T
 		},
 	}
 
-	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en")
+	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en", "", nil)
 	if err == nil {
 		t.Fatal("expected conflict error")
 	}
@@ -428,6 +522,46 @@ func TestWrapSaveConfigError_PassesTypedValidationThrough(t *testing.T) {
 	}
 }
 
+func TestSaveAsProfile_UpdatePersistsPrivateKeyJWT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	existing := &core.MultiAppConfig{
+		Apps: []core.AppConfig{{
+			Name:      "prod",
+			AppId:     "cli_prod",
+			AppSecret: core.PlainSecret("old-secret"),
+			Brand:     core.BrandFeishu,
+			Users:     []core.AppUser{{UserOpenId: "ou_1", UserName: "User"}},
+		}},
+	}
+	keyRef := &core.SecretRef{Source: "tee", ID: "lark-cli-default"}
+
+	if err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "prod", "cli_prod", core.SecretInput{}, core.BrandLark, "en_us", core.AuthMethodPrivateKeyJWT, keyRef); err != nil {
+		t.Fatalf("saveAsProfile update private_key_jwt: %v", err)
+	}
+
+	got, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	app := got.FindApp("prod")
+	if app == nil {
+		t.Fatalf("profile prod not saved: %#v", got.Apps)
+	}
+	if app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Fatalf("AuthMethod = %q, want private_key_jwt", app.AuthMethod)
+	}
+	if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID != "lark-cli-default" {
+		t.Fatalf("KeyRef = %#v, want tee/lark-cli-default", app.KeyRef)
+	}
+	if app.AppSecret.Ref != nil || app.AppSecret.Plain != "" {
+		t.Fatalf("private_key_jwt update must stay secretless, AppSecret value %#v", app.AppSecret)
+	}
+	if len(app.Users) != 1 || app.Users[0].UserOpenId != "ou_1" {
+		t.Fatalf("same-app update should preserve users, Users=%#v", app.Users)
+	}
+}
+
 func TestUpdateExistingProfileWithoutSecret_RejectsAppIDChange(t *testing.T) {
 	multi := &core.MultiAppConfig{
 		CurrentApp: "prod",
@@ -453,16 +587,10 @@ func TestUpdateExistingProfileWithoutSecret_RejectsAppIDChange(t *testing.T) {
 }
 
 // stubConfigExtProvider simulates env/sidecar credential mode for config guard tests.
-type stubConfigExtProvider struct {
-	name string
-	err  error
-}
+type stubConfigExtProvider struct{ name string }
 
 func (s *stubConfigExtProvider) Name() string { return s.name }
 func (s *stubConfigExtProvider) ResolveAccount(_ context.Context) (*extcred.Account, error) {
-	if s.err != nil {
-		return nil, s.err
-	}
 	return &extcred.Account{AppID: "test-app"}, nil
 }
 func (s *stubConfigExtProvider) ResolveToken(_ context.Context, _ extcred.TokenSpec) (*extcred.Token, error) {
@@ -488,6 +616,7 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 	}{
 		{"init", []string{"init", "--app-id", "x", "--app-secret-stdin"}},
 		{"remove", []string{"remove"}},
+		{"show", []string{"show"}},
 		{"default-as", []string{"default-as", "user"}},
 		{"strict-mode", []string{"strict-mode", "off"}},
 	}
@@ -515,63 +644,6 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 	}
 }
 
-func TestConfigIdentityCommandsCheckProfileOwnershipBeforeCredentialOwnership(t *testing.T) {
-	profileDenied := errors.New("Profile identity settings are deployment-managed")
-	credentialChecks := 0
-	plan := runtimeplan.New(runtimeplan.Options{
-		Capabilities: func(capability runtimeplan.Capability) error {
-			switch capability {
-			case runtimeplan.CapabilityLocalProfileMutation:
-				return profileDenied
-			case runtimeplan.CapabilityLocalCredentialManagement:
-				credentialChecks++
-			}
-			return nil
-		},
-	})
-
-	for _, args := range [][]string{
-		{"default-as", "bot"},
-		{"strict-mode", "bot"},
-	} {
-		t.Run(args[0], func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
-			cmd := NewCmdConfig(f)
-			cmd.SetArgs(args)
-
-			err := cmd.Execute()
-			if !errors.Is(err, profileDenied) {
-				t.Fatalf("Execute(%v) error = %v, want Profile ownership denial", args, err)
-			}
-		})
-	}
-	if credentialChecks != 0 {
-		t.Fatalf("credential capability checked %d times after Profile denial, want 0", credentialChecks)
-	}
-}
-
-func TestConfigIdentityCommandsRetainCredentialOwnershipCapability(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	root := NewCmdConfig(f)
-
-	for _, name := range []string{"default-as", "strict-mode"} {
-		t.Run(name, func(t *testing.T) {
-			leaf, _, err := root.Find([]string{name})
-			if err != nil {
-				t.Fatal(err)
-			}
-			got := cmdutil.GetRuntimeCapabilities(leaf)
-			want := []runtimeplan.Capability{
-				runtimeplan.CapabilityLocalProfileMutation,
-				runtimeplan.CapabilityLocalCredentialManagement,
-			}
-			if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
-				t.Fatalf("%s capabilities = %v, want %v", name, got, want)
-			}
-		})
-	}
-}
-
 // TestValidateInitLang covers the --lang contract: empty (omitted or explicit)
 // is a no-op leaving Lang unset; a short code or Feishu locale canonicalizes to
 // the same locale; an unrecognized value errors.

cmd/config/init.go

@@ -19,6 +19,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -31,6 +32,7 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
+	PrivateKeyJWT  bool // --private-key-jwt: request private_key_jwt instead of the default client_secret
 
 	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
 	langExplicit bool   // true when --lang was explicitly passed
@@ -39,6 +41,8 @@ type ConfigInitOptions struct {
 
 	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
 
+	Restore bool // Restore re-registers the app already in config to recover a lost credential
+
 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
 	// at config bind — which is what AI agents almost always want. Manual
@@ -81,17 +85,26 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	}
 
 	cmd.Flags().BoolVar(&opts.New, "new", false, "create a new app directly (skip mode selection)")
+	cmd.Flags().BoolVar(&opts.PrivateKeyJWT, "private-key-jwt", false, "create a new app with private_key_jwt (signed by a platform key, no app secret)")
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
 	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
+	cmd.Flags().BoolVar(&opts.Restore, "restore", false, "re-register the app already in config to recover a lost credential (keychain key / app secret); reuses the stored app ID and auth method")
 	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
 }
 
+func requestedInitAuthMethod(opts *ConfigInitOptions) string {
+	if opts.PrivateKeyJWT {
+		return core.AuthMethodPrivateKeyJWT
+	}
+	return core.AuthMethodClientSecret
+}
+
 // printLangPreferenceConfirmation echoes the set preference to stderr, only
 // when --lang explicitly set a non-empty value.
 func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
@@ -132,7 +145,7 @@ func guardAgentWorkspace(opts *ConfigInitOptions) error {
 
 // hasAnyNonInteractiveFlag returns true if any non-interactive flag is set.
 func (o *ConfigInitOptions) hasAnyNonInteractiveFlag() bool {
-	return o.New || o.AppID != "" || o.AppSecretStdin
+	return o.New || o.Restore || o.AppID != "" || o.AppSecretStdin
 }
 
 // cleanupOldConfig clears keychain entries (AppSecret + UAT) for all apps in existing config except the app whose AppId equals skipAppID.
@@ -151,22 +164,61 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 	}
 }
 
+// removeStaleSecretForPKJWT clears a secret left in the keychain when the SAME
+// appId is migrated from client_secret to private_key_jwt. cleanupOldConfig
+// explicitly skips a matching appId, and saveAsProfile only cleans up on an
+// appId change, so a same-appId migration would orphan the old secret. This
+// fills that gap. RemoveSecretStore only deletes Source=="keychain" entries, so
+// the new pkjwt tee key handle is never touched.
+func removeStaleSecretForPKJWT(existing *core.MultiAppConfig, profileName, appID string, kc keychain.KeychainAccess) {
+	if existing == nil {
+		return
+	}
+	var prior *core.AppConfig
+	if profileName != "" {
+		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
+			prior = &existing.Apps[idx]
+		}
+	} else {
+		prior = existing.CurrentAppConfig("")
+	}
+	if prior != nil && prior.AppId == appID && !prior.AppSecret.IsZero() {
+		core.RemoveSecretStore(prior.AppSecret, kc)
+	}
+}
+
+// keyRefFromResult builds the TEE key reference to persist for a private_key_jwt
+// registration result, or nil for client_secret.
+func keyRefFromResult(r *configInitResult) *core.SecretRef {
+	if r != nil && r.AuthMethod == core.AuthMethodPrivateKeyJWT && r.KeyLabel != "" {
+		return &core.SecretRef{Source: "tee", ID: r.KeyLabel}
+	}
+	return nil
+}
+
 // saveAsOnlyApp overwrites config.json with a single-app config.
-func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
 			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
+			AuthMethod: authMethod, KeyRef: keyRef,
 		}},
 	}
+	return saveMultiAppConfigForInit(config)
+}
+
+func saveMultiAppConfigForInit(config *core.MultiAppConfig) error {
 	return core.SaveMultiAppConfig(config)
 }
 
 // saveInitConfig saves a new/updated app config, respecting --profile mode.
 // With profileName: appends or updates the named profile (preserves other profiles).
 // Without profileName: cleans up old config and saves as the only app.
-func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmdutil.Factory, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+// authMethod/keyRef carry the credential type: ("", nil) for client_secret,
+// (private_key_jwt, &{tee,label}) for the secretless TEE flow.
+func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmdutil.Factory, appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	if profileName != "" {
-		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
+		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang, authMethod, keyRef)
 	}
 	cleanupOldConfig(existing, f, appId)
 	var prior i18n.Lang
@@ -175,7 +227,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 			prior = app.Lang
 		}
 	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
+	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)), authMethod, keyRef)
 }
 
 // wrapSaveConfigError passes an already-typed error (e.g. the --name conflict
@@ -195,7 +247,7 @@ func wrapSaveConfigError(err error) error {
 // saveAsProfile appends or updates a named profile in the config.
 // If a profile with the same name exists, it updates it; otherwise appends.
 // When updating, cleans up old keychain secrets if AppId changed.
-func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, profileName, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, profileName, appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	multi := existing
 	if multi == nil {
 		multi = &core.MultiAppConfig{}
@@ -214,6 +266,8 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
 		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
+		multi.Apps[idx].AuthMethod = authMethod
+		multi.Apps[idx].KeyRef = keyRef
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument,
@@ -222,15 +276,17 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 		}
 		// Append new profile
 		multi.Apps = append(multi.Apps, core.AppConfig{
-			Name:      profileName,
-			AppId:     appId,
-			AppSecret: secret,
-			Brand:     brand,
-			Lang:      i18n.Lang(lang),
-			Users:     []core.AppUser{},
+			Name:       profileName,
+			AppId:      appId,
+			AppSecret:  secret,
+			Brand:      brand,
+			Lang:       i18n.Lang(lang),
+			Users:      []core.AppUser{},
+			AuthMethod: authMethod,
+			KeyRef:     keyRef,
 		})
 	}
-	return core.SaveMultiAppConfig(multi)
+	return saveMultiAppConfigForInit(multi)
 }
 
 func findProfileIndexByName(multi *core.MultiAppConfig, profileName string) int {
@@ -302,12 +358,141 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 	app.AppId = appID
 	app.Brand = brand
 	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
-	return core.SaveMultiAppConfig(existing)
+	return saveMultiAppConfigForInit(existing)
+}
+
+func persistInitResult(opts *ConfigInitOptions, f *cmdutil.Factory, profileName string, result *configInitResult) error {
+	existing, _ := core.LoadMultiAppConfig()
+
+	switch {
+	case result.AuthMethod == core.AuthMethodPrivateKeyJWT:
+		if err := saveInitConfig(profileName, existing, f, result.AppID, core.SecretInput{}, result.Brand, opts.Lang, result.AuthMethod, keyRefFromResult(result)); err != nil {
+			return wrapSaveConfigError(err)
+		}
+		removeStaleSecretForPKJWT(existing, profileName, result.AppID, f.Keychain)
+		return nil
+	case result.AppSecret != "":
+		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
+		if err != nil {
+			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+		}
+		if err := saveInitConfig(profileName, existing, f, result.AppID, secret, result.Brand, opts.Lang, "", nil); err != nil {
+			return wrapSaveConfigError(err)
+		}
+		return nil
+	case result.Mode == "existing" && result.AppID != "":
+		return wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, profileName, result.AppID, result.Brand, opts.Lang))
+	default:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").WithParam("--app-id")
+	}
+}
+
+func probeInitResult(opts *ConfigInitOptions, f *cmdutil.Factory, result *configInitResult) error {
+	if result.AuthMethod == core.AuthMethodPrivateKeyJWT {
+		return runProbePKJWT(opts.Ctx, f, result.Brand, result.AppID, keysigner.Active(), result.KeyLabel)
+	}
+	if result.AppSecret != "" {
+		return runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand)
+	}
+	return nil
+}
+
+// persistAndProbeResult saves a registration/restore result into profileName and
+// runs the post-registration probe. profileName == "" replaces the single app
+// (legacy); a named profile is updated in place. Shared by --new and --restore.
+func persistAndProbeResult(opts *ConfigInitOptions, f *cmdutil.Factory, profileName string, result *configInitResult) error {
+	if err := persistInitResult(opts, f, profileName, result); err != nil {
+		return err
+	}
+	printLangPreferenceConfirmation(opts)
+	if result.AuthMethod == core.AuthMethodPrivateKeyJWT {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "authMethod": result.AuthMethod, "brand": result.Brand})
+	} else {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
+	}
+	return probeInitResult(opts, f, result)
+}
+
+// runRestoreFlow re-registers the app already in config to recover a lost
+// credential (deleted keychain key / lost app secret). It reads the existing
+// app id + auth method + brand from config (no secret needed — that's the lost
+// part) and re-runs the device-flow registration with the app id sent on begin,
+// so the server re-registers that app instead of creating a new one. The
+// re-issued credential is written back to the same profile.
+func runRestoreFlow(opts *ConfigInitOptions, existing *core.MultiAppConfig, f *cmdutil.Factory, msg *initMsg) error {
+	if existing == nil {
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "nothing to restore: no config found").
+			WithHint("run: lark-cli config init")
+	}
+	app := existing.CurrentAppConfig(opts.ProfileName)
+	if app == nil || app.AppId == "" {
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "nothing to restore: no app id in config%s", profileSuffix(opts.ProfileName)).
+			WithHint("run: lark-cli config init")
+	}
+	if app.KeyRef != nil && strings.TrimSpace(app.KeyRef.Provider) != "" {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"config init --restore does not manage external signer provider %q", app.KeyRef.Provider).
+			WithHint("repair the OpenClaw provider with onboarding doctor --fix, then run config bind again")
+	}
+
+	restoreAppID := app.AppId
+	// Reuse the stored auth method authoritatively — never prompt. Empty on disk
+	// means client_secret (omitempty back-compat); pass it explicitly so restore
+	// preserves the existing credential type.
+	authMethod := app.AuthMethod
+	if authMethod == "" {
+		authMethod = core.AuthMethodClientSecret
+	}
+	result, err := runCreateAppFlow(opts.Ctx, f, app.Brand, authMethod, msg, restoreAppID)
+	if err != nil {
+		return err
+	}
+	if result == nil {
+		return errs.NewInternalError(errs.SubtypeSDKError, "app restore returned no result")
+	}
+
+	// Safety: if the server did not honor app_id (e.g. not yet supported), it may
+	// have created a NEW app instead of restoring. Warn so the user is not silently
+	// switched to a different app id.
+	if result.AppID != restoreAppID {
+		fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] restore: server returned app %s, expected %s — it may have created a new app instead of restoring\n", result.AppID, restoreAppID)
+	}
+
+	// Write back to the profile we restored: an explicit --name, else the resolved
+	// app's own name. Empty name => legacy single-app replace.
+	saveProfile := opts.ProfileName
+	if saveProfile == "" {
+		saveProfile = app.Name
+	}
+	return persistAndProbeResult(opts, f, saveProfile, result)
+}
+
+// profileSuffix renders " (profile %q)" for error messages, or "" when unnamed.
+func profileSuffix(profileName string) string {
+	if profileName == "" {
+		return ""
+	}
+	return fmt.Sprintf(" (profile %q)", profileName)
 }
 
 func configInitRun(opts *ConfigInitOptions) error {
 	f := opts.Factory
-
+	if opts.PrivateKeyJWT {
+		switch {
+		case opts.Restore:
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"--private-key-jwt cannot be combined with --restore; restore preserves the stored auth method").
+				WithParam("--private-key-jwt")
+		case opts.AppID != "":
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"--private-key-jwt cannot be combined with --app-id; use --new to register a private_key_jwt app").
+				WithParam("--private-key-jwt")
+		case opts.AppSecretStdin:
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"--private-key-jwt cannot be combined with --app-secret-stdin; private_key_jwt does not use an app secret").
+				WithParam("--private-key-jwt")
+		}
+	}
 	// Read secret from stdin if --app-secret-stdin is set
 	if opts.AppSecretStdin {
 		scanner := bufio.NewScanner(f.IOStreams.In)
@@ -335,6 +520,26 @@ func configInitRun(opts *ConfigInitOptions) error {
 		}
 	}
 
+	// --restore recovers an existing app; it is incompatible with creating a new
+	// app (--new) or importing one non-interactively (--app-id / stdin secret).
+	if opts.Restore {
+		if opts.New {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--restore cannot be combined with --new").WithParam("--restore")
+		}
+		if opts.AppID != "" || opts.AppSecretStdin {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--restore cannot be combined with --app-id / --app-secret-stdin").WithParam("--restore")
+		}
+	}
+
+	// A user who explicitly asks for private_key_jwt needs immediate feedback
+	// before any interactive prompt. Otherwise unsupported machines enter the
+	// TUI and fail only after the user chooses a create flow.
+	if opts.PrivateKeyJWT && !opts.New && !opts.Restore {
+		if _, err := resolveRegisterAuthMethod(opts.Ctx, f, core.AuthMethodPrivateKeyJWT); err != nil {
+			return err
+		}
+	}
+
 	// Mode 1: Non-interactive
 	if opts.AppID != "" && opts.appSecret != "" {
 		brand := parseBrand(opts.Brand)
@@ -342,7 +547,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 		if err != nil {
 			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 		}
-		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
+		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang, "", nil); err != nil {
 			return wrapSaveConfigError(err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
@@ -368,34 +573,26 @@ func configInitRun(opts *ConfigInitOptions) error {
 
 	msg := getInitMsg(opts.UILang)
 
+	// Mode: Restore (--restore) — re-register the app already in config.
+	if opts.Restore {
+		return runRestoreFlow(opts, existing, f, msg)
+	}
+
 	// Mode 3: Create new app directly (--new)
 	if opts.New {
-		result, err := runCreateAppFlow(opts.Ctx, f, parseBrand(opts.Brand), msg)
+		result, err := runCreateAppFlow(opts.Ctx, f, parseBrand(opts.Brand), requestedInitAuthMethod(opts), msg, "")
 		if err != nil {
 			return err
 		}
 		if result == nil {
 			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
 		}
-		existing, _ := core.LoadMultiAppConfig()
-		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
-		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
-		}
-		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return wrapSaveConfigError(err)
-		}
-		printLangPreferenceConfirmation(opts)
-		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
-		if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-			return err
-		}
-		return nil
+		return persistAndProbeResult(opts, f, opts.ProfileName, result)
 	}
 
 	// Mode 4: Interactive TUI (terminal)
 	if !opts.hasAnyNonInteractiveFlag() && f.IOStreams.IsTerminal {
-		result, err := runInteractiveConfigInit(opts.Ctx, f, msg)
+		result, err := runInteractiveConfigInit(opts.Ctx, f, requestedInitAuthMethod(opts), msg)
 		if err != nil {
 			return err
 		}
@@ -404,35 +601,21 @@ func configInitRun(opts *ConfigInitOptions) error {
 				WithParam("--app-id")
 		}
 
-		existing, _ := core.LoadMultiAppConfig()
-
-		if result.AppSecret != "" {
-			// New secret provided (either from "create" or "existing" with input)
-			secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
-			if err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
-			}
-			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-				return wrapSaveConfigError(err)
-			}
-		} else if result.Mode == "existing" && result.AppID != "" {
-			// Existing app with unchanged secret — update app ID and brand only
-			if err := wrapUpdateExistingProfileErr(updateExistingProfileWithoutSecret(existing, opts.ProfileName, result.AppID, result.Brand, opts.Lang)); err != nil {
+		if err := persistInitResult(opts, f, opts.ProfileName, result); err != nil {
+			return err
+		}
+		if result.AuthMethod == core.AuthMethodPrivateKeyJWT {
+			if err := probeInitResult(opts, f, result); err != nil {
 				return err
 			}
-		} else {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID and App Secret cannot be empty").
-				WithParam("--app-id")
 		}
 
 		if result.Mode == "existing" {
 			output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.ConfigSaved, result.AppID))
 		}
 		printLangPreferenceConfirmation(opts)
-		if result.AppSecret != "" {
-			if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-				return err
-			}
+		if result.AuthMethod != core.AuthMethodPrivateKeyJWT {
+			return probeInitResult(opts, f, result)
 		}
 		return nil
 	}
@@ -517,7 +700,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	if err != nil {
 		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 	}
-	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
+	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang, "", nil); err != nil {
 		return wrapSaveConfigError(err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))

cmd/config/init_auth_method_test.go

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"context"
+	"crypto"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+type authMethodTestSigner struct {
+	info     keysigner.HardwareInfo
+	probeErr error
+}
+
+func (authMethodTestSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return nil, nil
+}
+
+func (authMethodTestSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return nil, nil
+}
+
+func (authMethodTestSigner) Sign(context.Context, keysigner.KeyRef, []byte) ([]byte, string, error) {
+	return nil, "", nil
+}
+
+func (s authMethodTestSigner) ProbeHardware(context.Context) (keysigner.HardwareInfo, error) {
+	return s.info, s.probeErr
+}
+
+// TestResolveRegisterAuthMethod covers the non-interactive gating paths. The
+// darwin keychain signer is compiled into every build, so the test cannot rely
+// on the binary lacking a signer — it forces a known no-signer state for the
+// rejection cases, then registers a stub for the success case.
+func TestResolveRegisterAuthMethod(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f := &cmdutil.Factory{}
+	ctx := context.Background()
+
+	prevSigner := keysigner.Active()
+	t.Cleanup(func() { keysigner.Register(prevSigner) })
+	keysigner.Register(nil)
+
+	if m, err := resolveRegisterAuthMethod(ctx, f, core.AuthMethodClientSecret); err != nil || m != core.AuthMethodClientSecret {
+		t.Errorf("client_secret: got (%q, %v), want (client_secret, nil)", m, err)
+	}
+
+	if m, err := resolveRegisterAuthMethod(ctx, f, ""); err != nil || m != core.AuthMethodClientSecret {
+		t.Errorf("default: got (%q, %v), want (client_secret, nil)", m, err)
+	}
+
+	if _, err := resolveRegisterAuthMethod(ctx, f, "bogus"); err == nil {
+		t.Error("bogus auth-method: expected error")
+	}
+
+	if _, err := resolveRegisterAuthMethod(ctx, f, core.AuthMethodPrivateKeyJWT); err == nil {
+		t.Error("private_key_jwt without a signer: expected error")
+	}
+
+	keysigner.Register(authMethodTestSigner{info: keysigner.HardwareInfo{Backend: "tpm2", Available: true}})
+
+	if m, err := resolveRegisterAuthMethod(ctx, f, core.AuthMethodPrivateKeyJWT); err != nil || m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("private_key_jwt with signer: got (%q, %v), want (private_key_jwt, nil)", m, err)
+	}
+
+	f.IOStreams = &cmdutil.IOStreams{IsTerminal: true}
+	if m, err := resolveRegisterAuthMethod(ctx, f, ""); err != nil || m != core.AuthMethodClientSecret {
+		t.Errorf("default with terminal signer: got (%q, %v), want (client_secret, nil)", m, err)
+	}
+}
+
+func TestConfigInitRunRejectsPrivateKeyJWTIncompatibleModes(t *testing.T) {
+	tests := []struct {
+		name       string
+		configure  func(*ConfigInitOptions, *cmdutil.Factory)
+		wantTarget string
+	}{
+		{
+			name: "app id import",
+			configure: func(opts *ConfigInitOptions, _ *cmdutil.Factory) {
+				opts.AppID = "cli_test"
+			},
+			wantTarget: "--app-id",
+		},
+		{
+			name: "app secret stdin import",
+			configure: func(opts *ConfigInitOptions, f *cmdutil.Factory) {
+				opts.AppSecretStdin = true
+				f.IOStreams.In = strings.NewReader("secret\n")
+			},
+			wantTarget: "--app-secret-stdin",
+		},
+		{
+			name: "restore",
+			configure: func(opts *ConfigInitOptions, _ *cmdutil.Factory) {
+				opts.Restore = true
+			},
+			wantTarget: "--restore",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			opts := &ConfigInitOptions{
+				Factory:       f,
+				Ctx:           context.Background(),
+				PrivateKeyJWT: true,
+			}
+			tc.configure(opts, f)
+
+			err := configInitRun(opts)
+			if err == nil {
+				t.Fatal("expected incompatible mode error")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %[1]v", err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("error = %T, want *errs.ValidationError", err)
+			}
+			if validationErr.Param != "--private-key-jwt" {
+				t.Fatalf("param = %q, want --private-key-jwt", validationErr.Param)
+			}
+			if !strings.Contains(problem.Message, tc.wantTarget) {
+				t.Fatalf("message = %q, want %s", problem.Message, tc.wantTarget)
+			}
+		})
+	}
+}
+
+func TestResolveRegisterAuthMethod_PrivateKeyJWTRejectsUnavailableHardware(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	prevSigner := keysigner.Active()
+	t.Cleanup(func() { keysigner.Register(prevSigner) })
+	keysigner.Register(authMethodTestSigner{info: keysigner.HardwareInfo{
+		Backend: "tpm2",
+		Reason:  "open /dev/tpmrm0: permission denied",
+	}})
+
+	_, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
+	if err == nil {
+		t.Fatal("private_key_jwt with unavailable signer hardware: expected error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error is not typed: %T %[1]v", err)
+	}
+	if problem.Category != errs.CategoryConfig || problem.Subtype != errs.SubtypeInvalidClient {
+		t.Fatalf("problem = %s/%s, want config/invalid_client", problem.Category, problem.Subtype)
+	}
+	wantMessage := "this machine does not support --private-key-jwt"
+	if problem.Message != wantMessage {
+		t.Fatalf("message = %q, want %q", problem.Message, wantMessage)
+	}
+	if strings.Contains(problem.Message, "sks") || strings.Contains(problem.Message, "/dev/tpm") || strings.Contains(problem.Message, "tpm") || strings.Contains(problem.Message, "TEE") || strings.Contains(problem.Message, "Keychain") {
+		t.Fatalf("message exposes backend detail: %q", problem.Message)
+	}
+	if !strings.Contains(problem.Hint, "omit --private-key-jwt") {
+		t.Fatalf("hint = %q, want guidance to omit --private-key-jwt", problem.Hint)
+	}
+	if strings.Contains(problem.Hint, "fix the local signer") {
+		t.Fatalf("hint exposes unnecessary signer recovery: %q", problem.Hint)
+	}
+}
+
+func TestResolveRegisterAuthMethod_PrivateKeyJWTRejectsProbeError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	probeErr := errors.New("probe exploded")
+	prevSigner := keysigner.Active()
+	t.Cleanup(func() { keysigner.Register(prevSigner) })
+	keysigner.Register(authMethodTestSigner{
+		info:     keysigner.HardwareInfo{Backend: "keychain"},
+		probeErr: probeErr,
+	})
+
+	_, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
+	if err == nil {
+		t.Fatal("private_key_jwt with probe error: expected error")
+	}
+	if !errors.Is(err, probeErr) {
+		t.Fatalf("error does not preserve probe cause: %v", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error is not typed: %T %[1]v", err)
+	}
+	if problem.Category != errs.CategoryConfig || problem.Subtype != errs.SubtypeInvalidClient {
+		t.Fatalf("problem = %s/%s, want config/invalid_client", problem.Category, problem.Subtype)
+	}
+	wantMessage := "this machine does not support --private-key-jwt"
+	if problem.Message != wantMessage {
+		t.Fatalf("message = %q, want %q", problem.Message, wantMessage)
+	}
+	if strings.Contains(problem.Message, "probe") || strings.Contains(problem.Message, "keychain signer") {
+		t.Fatalf("message exposes probe detail: %q", problem.Message)
+	}
+	if !strings.Contains(problem.Hint, "omit --private-key-jwt") {
+		t.Fatalf("hint = %q, want guidance to omit --private-key-jwt", problem.Hint)
+	}
+	if strings.Contains(problem.Hint, "fix the local signer") {
+		t.Fatalf("hint exposes unnecessary signer recovery: %q", problem.Hint)
+	}
+}
+
+func TestConfigInitRun_PrivateKeyJWTRejectsBeforeInteractiveMode(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	prevSigner := keysigner.Active()
+	t.Cleanup(func() { keysigner.Register(prevSigner) })
+	keysigner.Register(authMethodTestSigner{info: keysigner.HardwareInfo{
+		Backend: "tpm2",
+		Reason:  "not available",
+	}})
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	f.IOStreams.IsTerminal = true
+	opts := &ConfigInitOptions{
+		Factory:       f,
+		Ctx:           context.Background(),
+		PrivateKeyJWT: true,
+		Lang:          "zh_cn",
+		UILang:        "zh_cn",
+	}
+
+	err := configInitRun(opts)
+	if err == nil {
+		t.Fatal("config init --private-key-jwt on unsupported machine: expected error before interactive mode")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error is not typed: %T %[1]v", err)
+	}
+	if problem.Category != errs.CategoryConfig || problem.Subtype != errs.SubtypeInvalidClient {
+		t.Fatalf("problem = %s/%s, want config/invalid_client", problem.Category, problem.Subtype)
+	}
+	if problem.Message != "this machine does not support --private-key-jwt" {
+		t.Fatalf("message = %q", problem.Message)
+	}
+}
+
+func TestExistingAppRequiresSecret(t *testing.T) {
+	if !existingAppRequiresSecret(core.AuthMethodClientSecret) {
+		t.Error("client_secret existing app should require App Secret")
+	}
+	if existingAppRequiresSecret("") != true {
+		t.Error("default existing app should require App Secret")
+	}
+	if existingAppRequiresSecret(core.AuthMethodPrivateKeyJWT) {
+		t.Error("private_key_jwt existing app should not require App Secret")
+	}
+}
+
+// TestValidatePKJWTKeyBinding covers the guard that rejects a registration
+// resolving to private_key_jwt with no signing key bound (e.g. an existing
+// secret-based app was selected on the confirm page).
+func TestValidatePKJWTKeyBinding(t *testing.T) {
+	if err := validatePKJWTKeyBinding(core.AuthMethodPrivateKeyJWT, ""); err == nil {
+		t.Error("pkjwt with empty keyLabel: expected error")
+	}
+	if err := validatePKJWTKeyBinding(core.AuthMethodPrivateKeyJWT, "agent-key"); err != nil {
+		t.Errorf("pkjwt with keyLabel: expected nil, got %v", err)
+	}
+	if err := validatePKJWTKeyBinding(core.AuthMethodClientSecret, ""); err != nil {
+		t.Errorf("client_secret: expected nil, got %v", err)
+	}
+}
+
+// TestResolveFinalAuthMethod locks the authoritative-method logic. The 2nd case
+// is the real bug: we requested private_key_jwt but the server resolved to an
+// existing client_secret app — we must persist client_secret, not pkjwt.
+func TestResolveFinalAuthMethod(t *testing.T) {
+	if m := resolveFinalAuthMethod([]string{"client_secret", "private_key_jwt"}, core.AuthMethodClientSecret); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("prefers private_key_jwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod([]string{"client_secret"}, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodClientSecret {
+		t.Errorf("server client_secret must override requested pkjwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod(nil, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("fallback to requested when server is silent: got %q", m)
+	}
+	// Explicit empty slice (not just nil) also falls back to requested — the same
+	// len()==0 back-compat allowance the init guard relies on to let private_key_jwt
+	// proceed against an older server (see internal/auth
+	// TestRequestAppRegistrationInit_EmptySupportedAuthMethods).
+	if m := resolveFinalAuthMethod([]string{}, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("empty []string should fall back to requested private_key_jwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod(nil, ""); m != core.AuthMethodClientSecret {
+		t.Errorf("default to client_secret: got %q", m)
+	}
+}

cmd/config/init_interactive.go

@@ -8,6 +8,9 @@ import (
 	"errors"
 	"fmt"
 	"net"
+	"slices"
+	"strings"
+	"time"
 
 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
@@ -15,22 +18,26 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/auth/jwt"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
 type configInitResult struct {
-	Mode      string // "create" or "existing"
-	Brand     core.LarkBrand
-	AppID     string
-	AppSecret string
+	Mode       string // "create" or "existing"
+	Brand      core.LarkBrand
+	AppID      string
+	AppSecret  string
+	AuthMethod string // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	KeyLabel   string // TEE key handle when AuthMethod == private_key_jwt
 }
 
 // runInteractiveConfigInit shows an interactive TUI for config init.
-func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, msg *initMsg) (*configInitResult, error) {
+func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, authMethodFlag string, msg *initMsg) (*configInitResult, error) {
 	// Phase 1: Choose mode
 	var mode string
 	form1 := huh.NewForm(
@@ -53,14 +60,18 @@ func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, msg *init
 	}
 
 	if mode == "existing" {
-		return runExistingAppForm(f, msg)
+		return runExistingAppForm(ctx, f, authMethodFlag, msg)
 	}
 
-	return runCreateAppFlow(ctx, f, "", msg)
+	return runCreateAppFlow(ctx, f, "", authMethodFlag, msg, "")
+}
+
+func existingAppRequiresSecret(requestedAuthMethod string) bool {
+	return requestedAuthMethod != core.AuthMethodPrivateKeyJWT
 }
 
 // runExistingAppForm shows a huh form for manually entering App ID / App Secret / Brand.
-func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, error) {
+func runExistingAppForm(ctx context.Context, f *cmdutil.Factory, requestedAuthMethod string, msg *initMsg) (*configInitResult, error) {
 	// Load existing config for defaults
 	existing, _ := core.LoadMultiAppConfig()
 	var firstApp *core.AppConfig
@@ -94,19 +105,31 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 		brand = string(firstApp.Brand)
 	}
 
-	form := huh.NewForm(
-		huh.NewGroup(
-			appIDInput,
-			appSecretInput,
-			huh.NewSelect[string]().
-				Title(msg.Platform).
-				Options(
-					huh.NewOption(msg.Feishu, "feishu"),
-					huh.NewOption("Lark", "lark"),
-				).
-				Value(&brand),
-		),
-	).WithTheme(cmdutil.ThemeFeishu())
+	brandSelect := huh.NewSelect[string]().
+		Title(msg.Platform).
+		Options(
+			huh.NewOption(msg.Feishu, "feishu"),
+			huh.NewOption("Lark", "lark"),
+		).
+		Value(&brand)
+
+	var form *huh.Form
+	if existingAppRequiresSecret(requestedAuthMethod) {
+		form = huh.NewForm(
+			huh.NewGroup(
+				appIDInput,
+				appSecretInput,
+				brandSelect,
+			),
+		).WithTheme(cmdutil.ThemeFeishu())
+	} else {
+		form = huh.NewForm(
+			huh.NewGroup(
+				appIDInput,
+				brandSelect,
+			),
+		).WithTheme(cmdutil.ThemeFeishu())
+	}
 
 	if err := form.Run(); err != nil {
 		if err == huh.ErrUserAborted {
@@ -119,6 +142,13 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 	if appID == "" && firstApp != nil {
 		appID = firstApp.AppId
 	}
+	if !existingAppRequiresSecret(requestedAuthMethod) {
+		if appID == "" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "App ID cannot be empty").
+				WithParam("--app-id")
+		}
+		return runCreateAppFlow(ctx, f, parseBrand(brand), core.AuthMethodPrivateKeyJWT, msg, appID)
+	}
 	if appSecret == "" && firstApp != nil && !firstApp.AppSecret.IsZero() {
 		// Keep existing secret - caller will handle
 		return &configInitResult{
@@ -148,9 +178,49 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 	}, nil
 }
 
+// resolveRegisterAuthMethod decides the auth method for a new-app registration.
+// An explicit private_key_jwt request wins; otherwise the default is
+// client_secret with no extra prompt.
+func resolveRegisterAuthMethod(ctx context.Context, _ *cmdutil.Factory, requested string) (string, error) {
+	const pkjwtUnsupportedMessage = "this machine does not support --private-key-jwt"
+
+	switch requested {
+	case core.AuthMethodPrivateKeyJWT:
+		info, ok, err := keysigner.ProbeActiveHardware(ctx)
+		if !ok {
+			return "", errs.NewConfigError(errs.SubtypeInvalidClient,
+				pkjwtUnsupportedMessage).
+				WithHint("omit --private-key-jwt to register with an app secret")
+		}
+		if err != nil {
+			return "", errs.NewConfigError(errs.SubtypeInvalidClient,
+				pkjwtUnsupportedMessage).
+				WithCause(err).
+				WithHint("omit --private-key-jwt to register with an app secret")
+		}
+		if !info.Available {
+			return "", errs.NewConfigError(errs.SubtypeInvalidClient,
+				pkjwtUnsupportedMessage).
+				WithHint("omit --private-key-jwt to register with an app secret")
+		}
+		return core.AuthMethodPrivateKeyJWT, nil
+	case core.AuthMethodClientSecret:
+		return core.AuthMethodClientSecret, nil
+	case "":
+		return core.AuthMethodClientSecret, nil
+	default:
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"unknown auth method %q (use client_secret or private_key_jwt)", requested)
+	}
+}
+
 // runCreateAppFlow runs the "create new app" flow via OpenClaw device flow.
 // If brandOverride is non-empty, skip the interactive brand selection.
-func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride core.LarkBrand, msg *initMsg) (*configInitResult, error) {
+// requestedAuthMethod is the requested auth method; empty means client_secret.
+// restoreAppID, when non-empty, is sent on the registration begin request so the
+// server re-registers that existing app (credential recovery) instead of creating
+// a new one. Empty preserves the normal new-app flow.
+func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride core.LarkBrand, requestedAuthMethod string, msg *initMsg, restoreAppID string) (*configInitResult, error) {
 	var larkBrand core.LarkBrand
 	if brandOverride != "" {
 		larkBrand = brandOverride
@@ -178,17 +248,57 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		larkBrand = parseBrand(brand)
 	}
 
-	// Step 1: Request app registration (begin)
+	authMethod, err := resolveRegisterAuthMethod(ctx, f, requestedAuthMethod)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 1: Request app registration (begin).
 	// Use the shared proxy-plugin-aware transport so registration traffic is not
 	// a bypass of proxy plugin mode.
 	httpClient := transport.NewHTTPClient(0)
-	authResp, err := larkauth.RequestAppRegistration(ctx, httpClient, larkBrand, f.IOStreams.ErrOut)
+
+	// For private_key_jwt: init to obtain a nonce, then sign a TEE attestation
+	// (carrying the public key in its jwk header) to send with begin.
+	beginOpts := larkauth.AppRegistrationBeginOptions{}
+	keyLabel := ""
+	if authMethod == core.AuthMethodPrivateKeyJWT {
+		initResp, initErr := larkauth.RequestAppRegistrationInit(ctx, httpClient)
+		if initErr != nil {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration init failed: %v", initErr).WithCause(initErr)
+		}
+		// An empty SupportedAuthMethods is intentionally treated as "older server /
+		// unknown": len()==0 makes this guard false, so the requested
+		// private_key_jwt proceeds. This mirrors resolveFinalAuthMethod's
+		// back-compat fallback to the requested method. Only an explicit list that
+		// omits private_key_jwt rejects here.
+		if len(initResp.SupportedAuthMethods) > 0 && !slices.Contains(initResp.SupportedAuthMethods, core.AuthMethodPrivateKeyJWT) {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient,
+				"server does not support private_key_jwt for this app type (supported: %s)", strings.Join(initResp.SupportedAuthMethods, ", ")).
+				WithHint("omit --private-key-jwt to register with an app secret instead")
+		}
+		keyLabel = keysigner.DefaultKeyLabel
+		signer := keysigner.Active() // non-nil, guaranteed by resolveRegisterAuthMethod
+		attestation, signErr := jwt.SignAttestation(ctx, signer, keysigner.KeyRef{Label: keyLabel}, initResp.Nonce, time.Now())
+		if signErr != nil {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to sign registration attestation: %v", signErr).WithCause(signErr)
+		}
+		beginOpts = larkauth.AppRegistrationBeginOptions{
+			AuthMethod:      core.AuthMethodPrivateKeyJWT,
+			AuthAttestation: attestation,
+		}
+	}
+
+	// Restore flow: re-register the existing app instead of creating a new one.
+	beginOpts.RestoreAppID = restoreAppID
+
+	authResp, err := larkauth.RequestAppRegistration(ctx, httpClient, larkBrand, beginOpts, f.IOStreams.ErrOut)
 	if err != nil {
 		return nil, classifyRegistrationBeginError(err)
 	}
 
 	// Step 2: Build and display verification URL + QR code
-	verificationURL := larkauth.BuildVerificationURL(authResp.VerificationUriComplete, build.Version)
+	verificationURL := larkauth.BuildVerificationURL(authResp.VerificationUriComplete, build.Version, restoreAppID)
 
 	// Branch on TTY: human-friendly copy in interactive terminals,
 	// preserve original copy for AI / non-interactive callers.
@@ -217,18 +327,42 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		return nil, classifyRegistrationError(err)
 	}
 
-	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
+	// The final auth method is decided by the user/admin at confirmation and
+	// returned by poll — NOT necessarily what we requested. Selecting an existing
+	// client_secret app, for example, yields client_secret even though we sent
+	// private_key_jwt. Trust the result so we persist the truth.
+	finalMethod := resolveFinalAuthMethod(result.AuthMethods, authMethod)
+
+	if result.ClientID == "" {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing app_id")
+	}
+	if finalMethod != core.AuthMethodPrivateKeyJWT && result.ClientSecret == "" {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_secret")
 	}
 
+	// Surface a downgrade: requested private_key_jwt but the app resolved to a
+	// secret-based method (e.g. an existing app was selected). The key was NOT
+	// bound, so we must store the secret method, not private_key_jwt.
+	if authMethod == core.AuthMethodPrivateKeyJWT && finalMethod != core.AuthMethodPrivateKeyJWT {
+		fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] note: requested private_key_jwt, but the app uses %q (e.g. an existing app was selected); storing %q.\n", finalMethod, finalMethod)
+	}
 	fmt.Fprintln(f.IOStreams.ErrOut)
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.AppCreated, result.ClientID))
 
+	keyToStore := ""
+	if finalMethod == core.AuthMethodPrivateKeyJWT {
+		keyToStore = keyLabel
+	}
+	if err := validatePKJWTKeyBinding(finalMethod, keyToStore); err != nil {
+		return nil, err
+	}
 	return &configInitResult{
-		Mode:      "create",
-		Brand:     finalBrand,
-		AppID:     result.ClientID,
-		AppSecret: result.ClientSecret,
+		Mode:       "create",
+		Brand:      finalBrand,
+		AppID:      result.ClientID,
+		AppSecret:  result.ClientSecret, // empty for private_key_jwt; real secret otherwise
+		AuthMethod: finalMethod,
+		KeyLabel:   keyToStore,
 	}, nil
 }
 
@@ -268,3 +402,41 @@ func classifyRegistrationError(err error) error {
 		return errs.NewAuthenticationError(errs.SubtypeUnknown, "app registration failed: %v", err).WithCause(err)
 	}
 }
+
+// validatePKJWTKeyBinding rejects a registration that resolved to
+// private_key_jwt without a signing key bound to it. keyLabel is non-empty only
+// when the local flow chose private_key_jwt and signed a TEE attestation; a
+// resolved method of private_key_jwt with no key handle would save an unusable
+// config (rejected later at config load, surfacing as "saved OK, fails on first
+// use"), so it is caught here at registration time instead.
+func validatePKJWTKeyBinding(finalMethod, keyLabel string) error {
+	if finalMethod == core.AuthMethodPrivateKeyJWT && keyLabel == "" {
+		return errs.NewConfigError(errs.SubtypeInvalidClient,
+			"registration resolved to private_key_jwt but no signing key was bound to this app (an existing secret-based app may have been selected)").
+			WithHint("re-register with: lark-cli config init --new --private-key-jwt")
+	}
+	return nil
+}
+
+// resolveFinalAuthMethod picks the authoritative method from the poll result,
+// preferring private_key_jwt, then client_secret. It falls back to the requested
+// method when the server returns nothing (older servers).
+func resolveFinalAuthMethod(serverMethods []string, requested string) string {
+	if len(serverMethods) == 0 {
+		if requested == "" {
+			return core.AuthMethodClientSecret
+		}
+		return requested
+	}
+	for _, m := range serverMethods {
+		if m == core.AuthMethodPrivateKeyJWT {
+			return core.AuthMethodPrivateKeyJWT
+		}
+	}
+	for _, m := range serverMethods {
+		if m == core.AuthMethodClientSecret {
+			return core.AuthMethodClientSecret
+		}
+	}
+	return serverMethods[0]
+}

cmd/config/init_probe.go

@@ -16,6 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // probeTimeout is the total wall-clock budget for the credential probe step
@@ -90,3 +91,35 @@ func runProbe(parent context.Context, factory *cmdutil.Factory, appID, appSecret
 	_, _ = io.Copy(io.Discard, resp.Body)
 	return nil
 }
+
+// runProbePKJWT does a best-effort key-binding validation after a private_key_jwt
+// config is saved: it signs a client_assertion with the local platform key and
+// mints a token. A typed error (a deterministic server rejection — e.g. the key
+// is not bound to this app) is propagated so `config init` exits non-zero with
+// the canonical envelope; untyped errors (transport / HTTP / parse / timeout)
+// are swallowed (return nil). The mint itself is the probe — no second call.
+func runProbePKJWT(parent context.Context, factory *cmdutil.Factory, brand core.LarkBrand, clientID string, signer keysigner.Signer, keyLabel string) error {
+	if factory == nil {
+		return nil
+	}
+	if signer == nil {
+		return nil
+	}
+	httpClient, err := factory.HttpClient()
+	if err != nil {
+		return nil
+	}
+
+	ctx, cancel := context.WithTimeout(parent, probeTimeout)
+	defer cancel()
+
+	if _, err := credential.FetchTATWithAssertion(ctx, httpClient, brand, clientID, signer, keyLabel); err != nil {
+		// Typed = deterministic credential rejection → propagate. Untyped
+		// (transport / HTTP / parse / timeout) is ambiguous → stay silent.
+		if errs.IsTyped(err) {
+			return err
+		}
+		return nil
+	}
+	return nil
+}

cmd/config/init_probe_test.go

@@ -6,6 +6,11 @@ package config
 import (
 	"bytes"
 	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	crand "crypto/rand"
+	"crypto/sha256"
 	"errors"
 	"io"
 	"net/http"
@@ -17,14 +22,17 @@ import (
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // fakeRT routes requests to per-path handlers and records what it saw.
 type fakeRT struct {
 	tatHandler   func(req *http.Request) (*http.Response, error)
 	probeHandler func(req *http.Request) (*http.Response, error)
+	oauthHandler func(req *http.Request) (*http.Response, error)
 	tatCalls     int
 	probeCalls   int
+	oauthCalls   int
 	probeReq     *http.Request
 	probeBody    string
 }
@@ -48,10 +56,50 @@ func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
 			return jsonResp(200, `{"code":0,"data":{},"msg":"success"}`), nil
 		}
 		return f.probeHandler(req)
+	case strings.HasSuffix(req.URL.Path, "/authen/v2/oauth/token"):
+		f.oauthCalls++
+		if f.oauthHandler == nil {
+			return jsonResp(200, `{"access_token":"test-token"}`), nil
+		}
+		return f.oauthHandler(req)
 	}
 	return nil, errors.New("unexpected URL: " + req.URL.String())
 }
 
+// probeTestSigner is an in-memory real ECDSA P-256 signer used to sign the
+// client_assertion in runProbePKJWT tests (authMethodTestSigner returns a nil
+// key and cannot sign).
+type probeTestSigner struct{ key *ecdsa.PrivateKey }
+
+func newProbeTestSigner(t *testing.T) *probeTestSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), crand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &probeTestSigner{key: k}
+}
+
+func (p *probeTestSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return p.key.Public(), nil
+}
+
+func (p *probeTestSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return p.key.Public(), nil
+}
+
+func (p *probeTestSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(crand.Reader, p.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
 func jsonResp(code int, body string) *http.Response {
 	return &http.Response{
 		StatusCode: code,
@@ -208,10 +256,12 @@ func TestRunProbe_TATSuccess_ProbeFails_Silent(t *testing.T) {
 	assertSilent(t, err, errBuf)
 }
 
-func TestRunProbe_TATSuccess_ProbeOK_Silent(t *testing.T) {
+func TestProbeInitResult_ClientSecret(t *testing.T) {
 	rt := &fakeRT{}
 	f, errBuf := fakeFactory(t, rt)
-	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
+	opts := &ConfigInitOptions{Ctx: context.Background()}
+	result := &configInitResult{AppID: "cli_x", AppSecret: "test-secret", Brand: core.BrandFeishu}
+	err := probeInitResult(opts, f, result)
 	if rt.tatCalls != 1 || rt.probeCalls != 1 {
 		t.Errorf("expected 1/1 calls, got tat=%d probe=%d", rt.tatCalls, rt.probeCalls)
 	}
@@ -285,3 +335,47 @@ func TestRunProbe_TimeoutHonored(t *testing.T) {
 	// must stay silent and not block.
 	assertSilent(t, err, errBuf)
 }
+
+// runProbePKJWT: a deterministic server rejection (invalid_client) is propagated
+// as a typed ConfigError so config init exits non-zero.
+func TestRunProbePKJWT_DeterministicReject_Propagates(t *testing.T) {
+	rt := &fakeRT{oauthHandler: func(*http.Request) (*http.Response, error) {
+		return jsonResp(401, `{"error":"invalid_client","error_description":"unknown key"}`), nil
+	}}
+	f, errBuf := fakeFactory(t, rt)
+	err := runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", newProbeTestSigner(t), "agent-key")
+	if err == nil || !errs.IsTyped(err) {
+		t.Fatalf("expected propagated typed error, got %T %v", err, err)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("runProbePKJWT must not write stderr, got %q", errBuf.String())
+	}
+}
+
+// runProbePKJWT: ambiguous upstream noise (HTTP 503) is swallowed — silent, exit 0.
+func TestRunProbePKJWT_Ambiguous_Silent(t *testing.T) {
+	rt := &fakeRT{oauthHandler: func(*http.Request) (*http.Response, error) {
+		return jsonResp(503, `unavailable`), nil
+	}}
+	f, errBuf := fakeFactory(t, rt)
+	assertSilent(t, runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", newProbeTestSigner(t), "agent-key"), errBuf)
+}
+
+// probeInitResult dispatches private_key_jwt to the assertion-backed probe.
+func TestProbeInitResult_PrivateKeyJWT(t *testing.T) {
+	rt := &fakeRT{} // default oauth handler returns 200 + access_token
+	f, errBuf := fakeFactory(t, rt)
+	previous := keysigner.Active()
+	keysigner.Register(newProbeTestSigner(t))
+	t.Cleanup(func() { keysigner.Register(previous) })
+	opts := &ConfigInitOptions{Ctx: context.Background()}
+	result := &configInitResult{AppID: "cli_x", AuthMethod: core.AuthMethodPrivateKeyJWT, KeyLabel: "agent-key", Brand: core.BrandFeishu}
+	assertSilent(t, probeInitResult(opts, f, result), errBuf)
+}
+
+// runProbePKJWT: a nil signer is a defensive no-op (should not be reached, must
+// not panic).
+func TestRunProbePKJWT_NilSigner_Silent(t *testing.T) {
+	f, errBuf := fakeFactory(t, &fakeRT{})
+	assertSilent(t, runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", nil, "k"), errBuf)
+}

cmd/config/init_test.go

@@ -10,9 +10,25 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
 
+// TestRunRestoreFlow_NothingToRestore covers the early guards that return before
+// any network/registration call: no config at all, and a config whose resolved
+// app has no app id (nothing to send on begin).
+func TestRunRestoreFlow_NothingToRestore(t *testing.T) {
+	// No config on disk.
+	if err := runRestoreFlow(&ConfigInitOptions{}, nil, nil, nil); err == nil {
+		t.Fatal("expected error when there is no config to restore")
+	}
+	// Config present but the resolved app has no app id.
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: ""}}}
+	if err := runRestoreFlow(&ConfigInitOptions{}, existing, nil, nil); err == nil {
+		t.Fatal("expected error when the resolved app has no app id")
+	}
+}
+
 // updateExistingProfileWithoutSecret guards four blank-input scenarios. Each
 // must surface as *ValidationError(SubtypeInvalidArgument) per RFC 6749 §5.2:
 // SubtypeInvalidClient is reserved for IAM rejection of malformed credentials,
@@ -119,3 +135,58 @@ func assertValidationParam(t *testing.T, err error, wantParam string) {
 		t.Errorf("Param = %q, want %q", valErr.Param, wantParam)
 	}
 }
+
+// countingKeychain is an in-memory KeychainAccess that records whether Remove
+// was invoked, so the stale-secret cleanup can be asserted without a real OS
+// keychain.
+type countingKeychain struct {
+	store        map[string]string
+	removeCalled bool
+}
+
+func newCountingKeychain() *countingKeychain {
+	return &countingKeychain{store: map[string]string{}}
+}
+
+func (k *countingKeychain) Get(service, account string) (string, error) {
+	v, ok := k.store[service+"/"+account]
+	if !ok {
+		return "", keychain.ErrNotFound
+	}
+	return v, nil
+}
+
+func (k *countingKeychain) Set(service, account, value string) error {
+	k.store[service+"/"+account] = value
+	return nil
+}
+
+func (k *countingKeychain) Remove(service, account string) error {
+	k.removeCalled = true
+	delete(k.store, service+"/"+account)
+	return nil
+}
+
+func TestRemoveStaleSecretForPKJWT_SameAppID(t *testing.T) {
+	kc := newCountingKeychain()
+	ref, err := core.ForStorage("cli_same", core.PlainSecret("old-secret"), kc) // → Source:"keychain"
+	if err != nil {
+		t.Fatal(err)
+	}
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: "cli_same", AppSecret: ref}}}
+	removeStaleSecretForPKJWT(existing, "", "cli_same", kc)
+	if !kc.removeCalled {
+		t.Error("same appId with keychain secret: expected kc.Remove to be invoked")
+	}
+}
+
+func TestRemoveStaleSecretForPKJWT_DifferentAppID(t *testing.T) {
+	kc := newCountingKeychain()
+	ref, _ := core.ForStorage("cli_old", core.PlainSecret("old-secret"), kc)
+	kc.removeCalled = false // ForStorage does not call Remove, but reset to be safe
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: "cli_old", AppSecret: ref}}}
+	removeStaleSecretForPKJWT(existing, "", "cli_new", kc)
+	if kc.removeCalled {
+		t.Error("different appId: must NOT remove")
+	}
+}

cmd/config/keyless_bind.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/keylessprovider"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+const keylessBindProbeTimeout = 12 * time.Second
+
+var fetchTATForBind = fetchTATForFreshBind
+
+func fetchTATForFreshBind(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, clientID string, signer keysigner.Signer, provider, keyRef string) (string, func() error, error) {
+	helper, commitProviderManifest, err := keylessprovider.PrepareRefresh(ctx, provider)
+	if err != nil {
+		return "", nil, err
+	}
+	token, err := credential.FetchTATWithAssertionWithHelper(ctx, httpClient, brand, clientID, signer, helper, keyRef)
+	if err != nil {
+		return "", nil, err
+	}
+	return token, commitProviderManifest, nil
+}
+
+// validateBindResult proves that an OpenClaw keyless account can be used by
+// the exact helper/keyRef/appID tuple that will be persisted. Minting a TAT is
+// intentional: pubkey alone only proves that the helper runs (and some signer
+// implementations create a missing key during pubkey); a successful token mint
+// proves that this public key is already registered to the selected app, so no
+// attach flow or second user authorization is needed.
+func validateBindResult(parent context.Context, opts *BindOptions, result *BindResult) error {
+	if result == nil || result.AppConfig == nil {
+		return errs.NewInternalError(errs.SubtypeSDKError, "config bind produced no app configuration")
+	}
+	app := result.AppConfig
+	if app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		return nil
+	}
+	if app.KeyRef == nil || app.KeyRef.ID == "" {
+		return errs.NewConfigError(errs.SubtypeInvalidConfig,
+			"private_key_jwt bind for app %s is missing keyRef", app.AppId)
+	}
+	if strings.TrimSpace(app.KeyRef.Provider) != core.KeylessProviderLarkSuite {
+		return errs.NewConfigError(errs.SubtypeInvalidClient,
+			"OpenClaw private_key_jwt bind for app %s did not select provider %s", app.AppId, core.KeylessProviderLarkSuite)
+	}
+	if opts == nil || opts.Factory == nil || opts.Factory.HttpClient == nil {
+		return errs.NewInternalError(errs.SubtypeSDKError, "cannot validate keyless bind without an HTTP client")
+	}
+	httpClient, err := opts.Factory.HttpClient()
+	if err != nil {
+		return errs.NewNetworkError(errs.SubtypeNetworkTransport,
+			"cannot create HTTP client for keyless bind validation: %v", err).WithCause(err)
+	}
+
+	ctx, cancel := context.WithTimeout(parent, keylessBindProbeTimeout)
+	defer cancel()
+	_, commitProviderManifest, err := fetchTATForBind(
+		ctx, httpClient, app.Brand, app.AppId, keysigner.Active(), app.KeyRef.Provider, app.KeyRef.ID,
+	)
+	if err != nil {
+		if errs.IsTyped(err) {
+			return err
+		}
+		return errs.NewConfigError(errs.SubtypeInvalidClient,
+			"OpenClaw signer could not authenticate app %s: %v", app.AppId, err).
+			WithHint("repair or reinstall the OpenClaw Feishu plugin and its platform signer dependency, verify the keyless account, then retry config bind").
+			WithCause(err)
+	}
+	if commitProviderManifest == nil {
+		return errs.NewInternalError(errs.SubtypeStorage,
+			"OpenClaw signer validation did not produce a provider manifest commit")
+	}
+	result.commitProviderManifest = commitProviderManifest
+	return nil
+}

cmd/config/keyless_bind_test.go

@@ -0,0 +1,438 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/i18n"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+func TestConfigBindRun_OpenClawKeylessWritesProviderWithoutPath(t *testing.T) {
+	saveWorkspace(t)
+	clearAgentEnv(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeOpenClawKeylessConfig(t, "cli_keyless", "openclaw-lark")
+
+	var gotProvider, gotKeyRef, gotClientID string
+	var providerCommits int
+	var providerCommitSawWorkspace bool
+	replaceBindProbe(t, func(_ context.Context, _ *http.Client, _ core.LarkBrand, clientID string, _ keysigner.Signer, provider, keyRef string) (string, func() error, error) {
+		gotClientID, gotProvider, gotKeyRef = clientID, provider, keyRef
+		return "tat-ok", func() error {
+			providerCommits++
+			data, err := os.ReadFile(core.GetConfigPath())
+			if err != nil {
+				return err
+			}
+			providerCommitSawWorkspace = strings.Contains(string(data), "cli_keyless")
+			return nil
+		}, nil
+	})
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", Identity: "bot-only"}); err != nil {
+		t.Fatalf("configBindRun: %v", err)
+	}
+	if gotClientID != "cli_keyless" || gotProvider != core.KeylessProviderLarkSuite || gotKeyRef != "openclaw-lark" {
+		t.Fatalf("probe route = client %q provider %q keyRef %q", gotClientID, gotProvider, gotKeyRef)
+	}
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	app := multi.CurrentAppConfig("")
+	if app == nil || app.AuthMethod != core.AuthMethodPrivateKeyJWT || app.KeyRef == nil ||
+		app.KeyRef.Provider != core.KeylessProviderLarkSuite || app.KeyRef.ID != "openclaw-lark" || !app.AppSecret.IsZero() {
+		t.Fatalf("persisted app = %#v", app)
+	}
+	if stdout.Len() == 0 {
+		t.Fatal("bind did not emit success envelope")
+	}
+	if providerCommits != 1 {
+		t.Fatalf("provider manifest commits = %d, want 1", providerCommits)
+	}
+	if !providerCommitSawWorkspace {
+		t.Fatal("provider manifest committed before the workspace config became readable")
+	}
+}
+
+func TestConfigBindRun_OpenClawOptionalSignerClosedLoop(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("test helper uses a POSIX shebang; Windows resolution is compile-checked separately")
+	}
+	saveWorkspace(t)
+	clearAgentEnv(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	signerPath := installOpenClawOptionalSigner(t)
+	writeOpenClawKeylessConfig(t, "cli_keyless_optional", "openclaw-lark")
+
+	f, _, _, registry := cmdutil.TestFactory(t, nil)
+	registry.Register(&httpmock.Stub{
+		Method: http.MethodPost,
+		URL:    auth.PathOAuthTokenV2,
+		Body:   map[string]any{"code": 0, "access_token": "tat-from-optional-signer"},
+		BodyFilter: func(body []byte) bool {
+			form, err := url.ParseQuery(string(body))
+			return err == nil &&
+				form.Get("client_id") == "cli_keyless_optional" &&
+				form.Get("client_assertion_type") == "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" &&
+				form.Get("client_assertion") == "optional.jwt" &&
+				!form.Has("client_secret")
+		},
+	})
+
+	if err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", Identity: "bot-only"}); err != nil {
+		t.Fatalf("configBindRun: %v", err)
+	}
+	data, err := os.ReadFile(core.GetConfigPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasSuffix(string(data), "\n") || !strings.Contains(string(data), "\n  \"apps\": [") {
+		t.Fatalf("config is not formatted JSON with a trailing newline:\n%s", data)
+	}
+	if strings.Contains(string(data), signerPath) {
+		t.Fatalf("config persisted the discovered signer executable path:\n%s", data)
+	}
+	providerData, err := os.ReadFile(filepath.Join(core.GetBaseConfigDir(), "signing-providers.json"))
+	if err != nil {
+		t.Fatalf("read global signer manifest: %v", err)
+	}
+	if !strings.Contains(string(providerData), signerPath) {
+		t.Fatalf("global signer manifest did not record the verified executable")
+	}
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	app := multi.CurrentAppConfig("")
+	if app == nil || app.AppId != "cli_keyless_optional" || app.KeyRef == nil ||
+		app.KeyRef.Provider != core.KeylessProviderLarkSuite || app.KeyRef.ID != "openclaw-lark" || !app.AppSecret.IsZero() {
+		t.Fatalf("resolved config = %#v", app)
+	}
+}
+
+func TestConfigBindRun_OpenClawKeylessProbeFailureDoesNotWrite(t *testing.T) {
+	saveWorkspace(t)
+	clearAgentEnv(t)
+	base := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", base)
+	writeOpenClawKeylessConfig(t, "cli_wrong_key", "openclaw-lark")
+	replaceBindProbe(t, func(context.Context, *http.Client, core.LarkBrand, string, keysigner.Signer, string, string) (string, func() error, error) {
+		return "", nil, errs.NewConfigError(errs.SubtypeInvalidClient, "public key is not bound")
+	})
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", Identity: "bot-only"}); err == nil {
+		t.Fatal("expected probe error")
+	}
+	if _, err := os.Stat(filepath.Join(base, "openclaw", "config.json")); !os.IsNotExist(err) {
+		t.Fatalf("config must not be written; stat error = %v", err)
+	}
+}
+
+func TestConfigBindRun_OpenClawKeylessMissingProviderCommitFailsClosed(t *testing.T) {
+	saveWorkspace(t)
+	clearAgentEnv(t)
+	base := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", base)
+	writeOpenClawKeylessConfig(t, "cli_missing_commit", "openclaw-lark")
+	replaceBindProbe(t, func(context.Context, *http.Client, core.LarkBrand, string, keysigner.Signer, string, string) (string, func() error, error) {
+		return "tat-ok", nil, nil
+	})
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", Identity: "bot-only"})
+	if err == nil || !strings.Contains(err.Error(), "did not produce a provider manifest commit") {
+		t.Fatalf("configBindRun error = %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(base, "openclaw", "config.json")); !os.IsNotExist(statErr) {
+		t.Fatalf("config must not be written; stat error = %v", statErr)
+	}
+}
+
+func TestCommitBinding_ProviderManifestFailureRestoresWorkspace(t *testing.T) {
+	saveWorkspace(t)
+	base := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", base)
+	core.SetCurrentWorkspace(core.WorkspaceOpenClaw)
+	configPath := core.GetConfigPath()
+	if err := os.MkdirAll(filepath.Dir(configPath), 0700); err != nil {
+		t.Fatal(err)
+	}
+	previous := []byte("{\n  \"current_app\": \"old\",\n  \"apps\": [{\"name\": \"old\", \"app_id\": \"cli_old\", \"app_secret\": \"keep\"}]\n}\n")
+	if err := os.WriteFile(configPath, previous, 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	commitCalls := 0
+	result := &BindResult{
+		AppConfig: &core.AppConfig{AppId: "cli_new", Brand: core.BrandFeishu},
+		commitProviderManifest: func() error {
+			commitCalls++
+			return errors.New("manifest write failed")
+		},
+	}
+	err := commitBinding(&BindOptions{Factory: f, Identity: "bot-only"}, result, previous, "openclaw", configPath)
+	if err == nil || !strings.Contains(err.Error(), "workspace config restored") {
+		t.Fatalf("commitBinding error = %v", err)
+	}
+	if commitCalls != 1 {
+		t.Fatalf("provider manifest commits = %d, want 1", commitCalls)
+	}
+	got, readErr := os.ReadFile(configPath)
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	if string(got) != string(previous) {
+		t.Fatalf("workspace was not restored:\n%s", got)
+	}
+	if stdout.Len() != 0 || stderr.Len() != 0 {
+		t.Fatalf("failed bind emitted success output: stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+}
+
+func TestCommitBinding_ProviderManifestFailureRemovesNewWorkspace(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	core.SetCurrentWorkspace(core.WorkspaceOpenClaw)
+	configPath := core.GetConfigPath()
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	result := &BindResult{
+		AppConfig: &core.AppConfig{AppId: "cli_new", Brand: core.BrandFeishu},
+		commitProviderManifest: func() error {
+			return errors.New("manifest write failed")
+		},
+	}
+	err := commitBinding(&BindOptions{Factory: f, Identity: "bot-only"}, result, nil, "openclaw", configPath)
+	if err == nil || !strings.Contains(err.Error(), "workspace config restored") {
+		t.Fatalf("commitBinding error = %v", err)
+	}
+	if _, statErr := os.Stat(configPath); !os.IsNotExist(statErr) {
+		t.Fatalf("new workspace config was not removed; stat error = %v", statErr)
+	}
+	if stdout.Len() != 0 || stderr.Len() != 0 {
+		t.Fatalf("failed bind emitted success output: stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+}
+
+func TestCommitBinding_WorkspaceWriteFailureDoesNotCommitProvider(t *testing.T) {
+	saveWorkspace(t)
+	base := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", base)
+	core.SetCurrentWorkspace(core.WorkspaceOpenClaw)
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	providerCommitted := false
+	result := &BindResult{
+		AppConfig: &core.AppConfig{AppId: "cli_new", Brand: core.BrandFeishu},
+		commitProviderManifest: func() error {
+			providerCommitted = true
+			return nil
+		},
+	}
+	configPath := filepath.Join(base, "missing-parent", "config.json")
+	if err := commitBinding(&BindOptions{Factory: f, Identity: "bot-only"}, result, nil, "openclaw", configPath); err == nil {
+		t.Fatal("expected workspace write failure")
+	}
+	if providerCommitted {
+		t.Fatal("provider manifest was committed before the workspace config write succeeded")
+	}
+}
+
+func TestCommitBinding_ConcurrentWorkspaceChangeFailsBeforeProviderCommit(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	core.SetCurrentWorkspace(core.WorkspaceOpenClaw)
+	configPath := core.GetConfigPath()
+	if err := os.MkdirAll(filepath.Dir(configPath), 0700); err != nil {
+		t.Fatal(err)
+	}
+	previous := []byte(`{"apps":[{"app_id":"cli_old","app_secret":"old"}]}`)
+	concurrent := []byte(`{"apps":[{"app_id":"cli_other","app_secret":"newer"}]}`)
+	if err := os.WriteFile(configPath, concurrent, 0600); err != nil {
+		t.Fatal(err)
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	providerCommitted := false
+	result := &BindResult{
+		AppConfig: &core.AppConfig{AppId: "cli_new", Brand: core.BrandFeishu},
+		commitProviderManifest: func() error {
+			providerCommitted = true
+			return nil
+		},
+	}
+	err := commitBinding(&BindOptions{Factory: f, Identity: "bot-only"}, result, previous, "openclaw", configPath)
+	if err == nil || !strings.Contains(err.Error(), "changed while the bind was being validated") {
+		t.Fatalf("commitBinding error = %v", err)
+	}
+	if providerCommitted {
+		t.Fatal("provider manifest was committed after a concurrent workspace change")
+	}
+	got, readErr := os.ReadFile(configPath)
+	if readErr != nil || string(got) != string(concurrent) {
+		t.Fatalf("concurrent workspace was overwritten: %q, %v", got, readErr)
+	}
+}
+
+func TestCommitBinding_ProviderFailureDoesNotOverwriteConcurrentWriter(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	core.SetCurrentWorkspace(core.WorkspaceOpenClaw)
+	configPath := core.GetConfigPath()
+	if err := os.MkdirAll(filepath.Dir(configPath), 0700); err != nil {
+		t.Fatal(err)
+	}
+	previous := []byte(`{"apps":[{"app_id":"cli_old","app_secret":"old"}]}`)
+	concurrent := []byte(`{"apps":[{"app_id":"cli_other","app_secret":"newer"}]}`)
+	if err := os.WriteFile(configPath, previous, 0600); err != nil {
+		t.Fatal(err)
+	}
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	result := &BindResult{
+		AppConfig: &core.AppConfig{AppId: "cli_new", Brand: core.BrandFeishu},
+		commitProviderManifest: func() error {
+			if err := os.WriteFile(configPath, concurrent, 0600); err != nil {
+				return err
+			}
+			return errors.New("manifest write failed")
+		},
+	}
+	err := commitBinding(&BindOptions{Factory: f, Identity: "bot-only"}, result, previous, "openclaw", configPath)
+	if err == nil || !strings.Contains(err.Error(), "refusing to overwrite") {
+		t.Fatalf("commitBinding error = %v", err)
+	}
+	got, readErr := os.ReadFile(configPath)
+	if readErr != nil || string(got) != string(concurrent) {
+		t.Fatalf("concurrent workspace was overwritten: %q, %v", got, readErr)
+	}
+	if stdout.Len() != 0 || stderr.Len() != 0 {
+		t.Fatalf("failed bind emitted success output: stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+}
+
+func TestMergeBoundApp_UpsertsAndActivatesWithoutClobberingSiblings(t *testing.T) {
+	lang := "en_us"
+	previous := &core.MultiAppConfig{
+		StrictMode: core.StrictModeUser,
+		CurrentApp: "other",
+		Apps: []core.AppConfig{
+			{Name: "bound", AppId: "cli_target", Brand: core.BrandLark, Lang: coreLang(lang), Users: []core.AppUser{{UserOpenId: "ou_1", UserName: "alice"}}},
+			{Name: "other", AppId: "cli_other", AppSecret: core.PlainSecret("keep"), Brand: core.BrandFeishu, Users: []core.AppUser{}},
+		},
+	}
+	beforeSibling := previous.Apps[1]
+	data := mustJSON(t, previous)
+	incoming := &core.AppConfig{AppId: "cli_target", Brand: core.BrandFeishu, AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyRef: &core.SecretRef{Source: core.SecretSourceTEE, Provider: core.KeylessProviderLarkSuite, ID: "openclaw-lark"}}
+
+	got, err := mergeBoundApp(incoming, data, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Apps) != 2 || got.CurrentApp != "bound" || got.PreviousApp != "other" || got.StrictMode != previous.StrictMode {
+		t.Fatalf("merged root = %#v", got)
+	}
+	if !reflect.DeepEqual(got.Apps[1], beforeSibling) {
+		t.Fatalf("sibling changed: got %#v want %#v", got.Apps[1], beforeSibling)
+	}
+	if got.Apps[0].Name != "bound" || got.Apps[0].Lang != coreLang(lang) || !reflect.DeepEqual(got.Apps[0].Users, previous.Apps[0].Users) {
+		t.Fatalf("target-owned fields were lost: %#v", got.Apps[0])
+	}
+}
+
+func writeOpenClawKeylessConfig(t *testing.T, appID, keyRef string) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "openclaw.json")
+	data := []byte(`{"channels":{"feishu":{"appId":"` + appID + `","authMethod":"private_key_jwt","keyRef":"` + keyRef + `","domain":"feishu"}}}`)
+	if err := os.WriteFile(path, data, 0600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("OPENCLAW_CONFIG_PATH", path)
+}
+
+func replaceBindProbe(t *testing.T, fn func(context.Context, *http.Client, core.LarkBrand, string, keysigner.Signer, string, string) (string, func() error, error)) {
+	t.Helper()
+	previous := fetchTATForBind
+	fetchTATForBind = fn
+	t.Cleanup(func() { fetchTATForBind = previous })
+}
+
+func mustJSON(t *testing.T, value any) []byte {
+	t.Helper()
+	data, err := json.Marshal(value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return data
+}
+
+func coreLang(value string) i18n.Lang { return i18n.Lang(value) }
+
+func installOpenClawOptionalSigner(t *testing.T) string {
+	t.Helper()
+	// This closure specifically exercises the no-inspect compatibility path;
+	// keylessprovider tests separately cover authoritative managed-project
+	// discovery from `openclaw plugins inspect`.
+	t.Setenv("PATH", "")
+	type signerPackage struct {
+		name, npmOS, npmCPU, binary string
+	}
+	packages := map[string]signerPackage{
+		"darwin/arm64": {"@larksuite/lark-keyless-signer-darwin-arm64", "darwin", "arm64", "lark-keyless-signer"},
+		"darwin/amd64": {"@larksuite/lark-keyless-signer-darwin-x64", "darwin", "x64", "lark-keyless-signer"},
+		"linux/arm64":  {"@larksuite/lark-keyless-signer-linux-arm64", "linux", "arm64", "lark-keyless-signer"},
+		"linux/amd64":  {"@larksuite/lark-keyless-signer-linux-x64", "linux", "x64", "lark-keyless-signer"},
+	}
+	spec, ok := packages[runtime.GOOS+"/"+runtime.GOARCH]
+	if !ok {
+		t.Skipf("no optional signer package for %s/%s", runtime.GOOS, runtime.GOARCH)
+		return ""
+	}
+
+	stateDir := filepath.Join(t.TempDir(), "openclaw state")
+	packageDir := filepath.Join(
+		stateDir, "extensions", "openclaw-lark", "node_modules", "@larksuite", strings.TrimPrefix(spec.name, "@larksuite/"),
+	)
+	binDir := filepath.Join(packageDir, "bin")
+	if err := os.MkdirAll(binDir, 0700); err != nil {
+		t.Fatal(err)
+	}
+	packageJSON, err := json.MarshalIndent(map[string]any{
+		"name": spec.name, "version": "1.2.3", "os": []string{spec.npmOS}, "cpu": []string{spec.npmCPU},
+	}, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(packageDir, "package.json"), append(packageJSON, '\n'), 0600); err != nil {
+		t.Fatal(err)
+	}
+	script := "#!/bin/sh\n" +
+		"IFS= read -r request\n" +
+		"printf '%s\\n' '{\"ok\":true,\"client_assertion_type\":\"urn:ietf:params:oauth:client-assertion-type:jwt-bearer\",\"client_assertion\":\"optional.jwt\"}'\n"
+	signerPath := filepath.Join(binDir, spec.binary)
+	if err := os.WriteFile(signerPath, []byte(script), 0700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("OPENCLAW_STATE_DIR", stateDir)
+	t.Setenv("PATH", "")
+	return signerPath
+}

cmd/config/plugins.go

@@ -27,6 +27,13 @@ func NewCmdConfigPlugins(f *cmdutil.Factory) *cobra.Command {
 		Use:    "plugins",
 		Hidden: true, // diagnostic-only; kept callable, omitted from --help so it stays out of AI-agent context
 		Short:  "Inspect installed plugins and their hook contributions",
+		// Same leaf-level no-op as config policy: the parent `config`
+		// group's PersistentPreRunE requires builtin credential, but
+		// this is a read-only diagnostic that must work everywhere.
+		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
+			c.SilenceUsage = true
+			return nil
+		},
 	}
 	cmd.AddCommand(newCmdConfigPluginsShow(f))
 	return cmd

cmd/config/policy.go

@@ -16,6 +16,12 @@ func NewCmdConfigPolicy(f *cmdutil.Factory) *cobra.Command {
 		Use:    "policy",
 		Hidden: true,
 		Short:  "Inspect the user-layer command policy",
+		// Override parent's RequireBuiltinCredentialProvider check; this
+		// group is read-only diagnostic and must work under any provider.
+		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
+			c.SilenceUsage = true
+			return nil
+		},
 	}
 	cmd.AddCommand(newCmdConfigPolicyShow(f))
 	return cmd

cmd/config/policy_test.go

@@ -132,16 +132,19 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	}
 }
 
-// The policy group explicitly overrides the config parent's local credential
-// management capability because it is source-neutral diagnostics.
-func TestConfigPolicyOverridesCredentialManagementCapability(t *testing.T) {
+// Regression: the parent `config` command declares a PersistentPreRunE
+// that calls RequireBuiltinCredentialProvider; env credentials cause
+// it to return external_provider. `config policy` is a diagnostic
+// group that must not be blocked by that check. The group declares
+// its own no-op PersistentPreRunE so cobra's "first walking up from
+// leaf" picks ours over the config parent's.
+func TestConfigPolicy_BypassesConfigParentPersistentPreRunE(t *testing.T) {
 	f, _, _ := newPolicyTestFactory()
-	root := NewCmdConfig(f)
-	leaf, _, err := root.Find([]string{"policy", "show"})
-	if err != nil {
-		t.Fatal(err)
+	group := NewCmdConfigPolicy(f)
+	if group.PersistentPreRunE == nil {
+		t.Fatal("config policy group must declare its own PersistentPreRunE to win over config parent")
 	}
-	if capabilities := cmdutil.GetRuntimeCapabilities(leaf); len(capabilities) != 0 {
-		t.Fatalf("policy capabilities = %v, want source-neutral", capabilities)
+	if err := group.PersistentPreRunE(group, nil); err != nil {
+		t.Errorf("config policy PersistentPreRunE should be no-op, got %v", err)
 	}
 }

cmd/config/risk_control.go

@@ -1,75 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// NewCmdConfigRiskControl creates the workspace risk-control policy command.
-func NewCmdConfigRiskControl(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "risk-control [on|off|default]",
-		Short: "Manage workspace account-protection policy",
-		Long: `View or set the account-protection risk-control policy for this workspace.
-
-Account protection is on by default. Use off to opt this workspace out, on to
-opt it back in explicitly, or default to remove the explicit preference.`,
-		Args: cobra.MaximumNArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			config, err := core.LoadOrNotConfigured()
-			if err != nil {
-				return err
-			}
-			if len(args) == 0 {
-				printRiskControl(f, config)
-				return nil
-			}
-
-			switch args[0] {
-			case "on":
-				enabled := true
-				config.RiskControl = &enabled
-			case "off":
-				enabled := false
-				config.RiskControl = &enabled
-			case "default":
-				config.RiskControl = nil
-			default:
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"invalid risk-control value %q, valid values: on | off | default", args[0])
-			}
-
-			if err := core.SaveMultiAppConfig(config); err != nil {
-				return errs.NewInternalError(errs.SubtypeStorage,
-					"failed to save risk-control policy: %v", err).WithCause(err)
-			}
-			fmt.Fprintf(f.IOStreams.ErrOut, "Risk control set to %s (workspace)\n", args[0])
-			return nil
-		},
-	}
-	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
-	return cmd
-}
-
-func printRiskControl(f *cmdutil.Factory, config *core.MultiAppConfig) {
-	source := "default"
-	if config.RiskControl != nil {
-		source = "workspace"
-	}
-	fmt.Fprintf(f.IOStreams.Out, "risk-control: %s (source: %s)\n", riskControlState(config.RiskControlEnabled()), source)
-}
-
-func riskControlState(enabled bool) string {
-	if enabled {
-		return "on"
-	}
-	return "off"
-}

cmd/config/risk_control_test.go

@@ -1,130 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package config
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-func TestRiskControlWorkspacePolicy(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
-		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-	}}}
-	if err := core.SaveMultiAppConfig(config); err != nil {
-		t.Fatal(err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	cmd := NewCmdConfigRiskControl(f)
-	cmd.SetArgs([]string{"off"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("set off: %v", err)
-	}
-	loaded, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if loaded.RiskControl == nil || *loaded.RiskControl {
-		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
-	}
-	if !strings.Contains(stderr.String(), "set to off") {
-		t.Fatalf("stderr = %q", stderr.String())
-	}
-
-	stdout.Reset()
-	cmd = NewCmdConfigRiskControl(f)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("show: %v", err)
-	}
-	if got := stdout.String(); got != "risk-control: off (source: workspace)\n" {
-		t.Fatalf("stdout = %q", got)
-	}
-
-	cmd = NewCmdConfigRiskControl(f)
-	cmd.SetArgs([]string{"on"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("set on: %v", err)
-	}
-	loaded, err = core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if loaded.RiskControl == nil || !*loaded.RiskControl {
-		t.Fatalf("RiskControl = %v, want explicit true", loaded.RiskControl)
-	}
-
-	cmd = NewCmdConfigRiskControl(f)
-	cmd.SetArgs([]string{"default"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("reset default: %v", err)
-	}
-	loaded, err = core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if loaded.RiskControl != nil {
-		t.Fatalf("RiskControl = %v, want nil", loaded.RiskControl)
-	}
-
-	stdout.Reset()
-	cmd = NewCmdConfigRiskControl(f)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("show default: %v", err)
-	}
-	if got := stdout.String(); got != "risk-control: on (source: default)\n" {
-		t.Fatalf("stdout = %q", got)
-	}
-}
-
-func TestRiskControlWorkspacePolicyRejectsInvalidValue(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{Apps: []core.AppConfig{{
-		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-	}}}); err != nil {
-		t.Fatal(err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	cmd := NewCmdConfigRiskControl(f)
-	cmd.SetArgs([]string{"invalid"})
-	err := cmd.Execute()
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("error = %T %v, want *errs.ValidationError", err, err)
-	}
-	if validationErr.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want %q", validationErr.Subtype, errs.SubtypeInvalidArgument)
-	}
-}
-
-func TestRiskControlWorkspacePolicyAllowedWithExternalCredentials(t *testing.T) {
-	f := newConfigFactoryWithExternalProvider(t)
-	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
-		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-	}}}
-	if err := core.SaveMultiAppConfig(config); err != nil {
-		t.Fatal(err)
-	}
-
-	cmd := NewCmdConfig(f)
-	cmd.SetArgs([]string{"risk-control", "off"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("set off with external credentials: %v", err)
-	}
-
-	loaded, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if loaded.RiskControl == nil || *loaded.RiskControl {
-		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
-	}
-}

cmd/config/show.go

@@ -42,16 +42,6 @@ func NewCmdConfigShow(f *cmdutil.Factory, runF func(*ConfigShowOptions) error) *
 
 func configShowRun(opts *ConfigShowOptions) error {
 	f := opts.Factory
-	// config show describes the effective invocation configuration, not merely
-	// the bytes in config.json. Preserve the typed bootstrap failure so a
-	// Standard binary cannot present a local Profile as active when the system
-	// requires Extended runtime support.
-	if startupErr := f.RuntimeStartupError(); startupErr != nil {
-		return startupErr
-	}
-	if handled, editionErr := showEditionConfig(f); handled {
-		return editionErr
-	}
 
 	config, err := core.LoadMultiAppConfig()
 	if err != nil {

cmd/config/show_edition_extended.go

@@ -1,73 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package config
-
-import (
-	"context"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-type editionConfigShowResult struct {
-	Source                 string  `json:"source"`
-	CredentialProvider     string  `json:"credentialProvider"`
-	Manageable             bool    `json:"manageable"`
-	Workspace              string  `json:"workspace"`
-	AppID                  string  `json:"appId"`
-	Brand                  string  `json:"brand"`
-	DefaultAs              string  `json:"defaultAs"`
-	Profile                *string `json:"profile,omitempty"`
-	ExternalCredentialMode *string `json:"externalCredentialMode,omitempty"`
-	RemoteEndpoint         *string `json:"remoteEndpoint,omitempty"`
-}
-
-func showEditionConfig(f *cmdutil.Factory) (bool, error) {
-	if f == nil || f.Credential == nil {
-		return false, nil
-	}
-	source, err := f.Credential.InspectSource(context.Background())
-	if err != nil {
-		return true, typedEditionProviderError("determine the active credential provider", err)
-	}
-	if source == nil || !source.Managed {
-		return false, nil
-	}
-	if source.AppID == "" {
-		return true, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"external credential provider %q returned no account", source.Name)
-	}
-	result := editionConfigShowResult{
-		Source:             "external",
-		CredentialProvider: source.Name,
-		Manageable:         false,
-		Workspace:          core.CurrentWorkspace().Display(),
-		AppID:              source.AppID,
-		Brand:              string(source.Brand),
-		DefaultAs:          string(source.DefaultAs),
-	}
-	description := f.RuntimeDescription()
-	if source.ProfileName != "" {
-		result.Profile = &source.ProfileName
-	}
-	if description.Managed && description.Variant != "" {
-		result.ExternalCredentialMode = &description.Variant
-		if description.ProxiesRequests {
-			result.RemoteEndpoint = &description.DataPlaneEndpoint
-		}
-	}
-	output.PrintJson(f.IOStreams.Out, result)
-	return true, nil
-}
-
-func typedEditionProviderError(action string, err error) error {
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	return errs.NewInternalError(errs.SubtypeUnknown, "failed to %s: %v", action, err).WithCause(err)
-}

cmd/config/show_edition_extended_test.go

@@ -1,93 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package config
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/runtimeplan"
-)
-
-func TestExtendedConfigShowAllowedWithManagedSource(t *testing.T) {
-	f := newConfigFactoryWithExternalProvider(t)
-	cmd := NewCmdConfig(f)
-	matched, _, err := cmd.Find([]string{"show"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := cmd.PersistentPreRunE(matched, nil); err != nil {
-		t.Fatalf("config show blocked: %v", err)
-	}
-}
-
-func TestExtendedConfigShowProjectsManagedSource(t *testing.T) {
-	f := newConfigFactoryWithExternalProvider(t)
-	var stdout bytes.Buffer
-	f.IOStreams.Out = &stdout
-	cmdutil.TestSetRuntimePlan(t, f, runtimeplan.New(runtimeplan.Options{
-		Description: runtimeplan.Description{
-			Managed:           true,
-			Variant:           "managed-test",
-			ProxiesRequests:   true,
-			DataPlaneEndpoint: "https://managed.example.test",
-		},
-	}))
-
-	if err := configShowRun(&ConfigShowOptions{Factory: f}); err != nil {
-		t.Fatalf("configShowRun() error = %v", err)
-	}
-	var got editionConfigShowResult
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	if got.Source != "external" ||
-		got.CredentialProvider != "env" ||
-		got.Manageable ||
-		got.AppID != "test-app" ||
-		got.ExternalCredentialMode == nil ||
-		*got.ExternalCredentialMode != "managed-test" ||
-		got.RemoteEndpoint == nil ||
-		*got.RemoteEndpoint != "https://managed.example.test" {
-		t.Fatalf("output = %#v", got)
-	}
-	var fields map[string]json.RawMessage
-	if err := json.Unmarshal(stdout.Bytes(), &fields); err != nil {
-		t.Fatal(err)
-	}
-	if _, ok := fields["appSecret"]; ok {
-		t.Fatalf("managed output must not invent appSecret: %s", stdout.String())
-	}
-	if _, ok := fields["users"]; ok {
-		t.Fatalf("managed output must not invent users: %s", stdout.String())
-	}
-}
-
-func TestExtendedConfigShowTypesManagedSourceFailure(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	providerErr := errors.New("provider failed")
-	cred := credential.NewCredentialProvider(
-		[]extcred.Provider{&stubConfigExtProvider{name: "broken", err: providerErr}},
-		nil, nil, nil,
-	)
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	f.Credential = cred
-
-	err := configShowRun(&ConfigShowOptions{Factory: f})
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeUnknown {
-		t.Fatalf("error = %#v, want internal/unknown", err)
-	}
-	if !errors.Is(err, providerErr) {
-		t.Fatalf("error does not preserve provider failure: %v", err)
-	}
-}

cmd/config/show_edition_standard.go

@@ -1,12 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package config
-
-import "github.com/larksuite/cli/internal/cmdutil"
-
-func showEditionConfig(*cmdutil.Factory) (bool, error) {
-	return false, nil
-}

cmd/config/show_edition_standard_test.go

@@ -1,54 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package config
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/runtimeplan"
-)
-
-func TestStandardConfigShowPreservesLocalConfigPath(t *testing.T) {
-	f := newConfigFactoryWithExternalProvider(t)
-
-	err := configShowRun(&ConfigShowOptions{Factory: f})
-	problem, ok := errs.ProblemOf(err)
-	if !ok ||
-		problem.Category != errs.CategoryConfig ||
-		problem.Subtype != errs.SubtypeNotConfigured {
-		t.Fatalf("error = %#v, want established config/not_configured result", err)
-	}
-}
-
-func TestStandardConfigShowReturnsTypedRuntimeStartupError(t *testing.T) {
-	startupErr := errs.NewValidationError(
-		errs.SubtypeFailedPrecondition,
-		"system external credential configuration requires the lark-cli Extended edition",
-	).WithHint("install lark-cli Extended or ask the administrator to remove external-credential.json")
-	f, stdout, _, _ := cmdutil.TestFactoryWithRuntimePlan(
-		t,
-		nil,
-		runtimeplan.Failed(startupErr, runtimeplan.MetadataEmbeddedOnly),
-	)
-
-	err := configShowRun(&ConfigShowOptions{Factory: f})
-	if !errors.Is(err, startupErr) {
-		t.Fatalf("config show error = %v, want original startup error", err)
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok ||
-		problem.Category != errs.CategoryValidation ||
-		problem.Subtype != errs.SubtypeFailedPrecondition ||
-		problem.Message != "system external credential configuration requires the lark-cli Extended edition" {
-		t.Fatalf("config show problem = %#v, want typed Extended-required startup failure", problem)
-	}
-	if stdout.Len() != 0 {
-		t.Fatalf("config show wrote local Profile after bootstrap failure: %s", stdout.String())
-	}
-}

cmd/doctor/doctor.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
 	"os"
 	"sync"
@@ -19,6 +20,8 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/keylessprovider"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/update"
@@ -84,10 +87,6 @@ func doctorRun(opts *DoctorOptions) error {
 		checks = append(checks, checkCLIUpdate()...)
 	}
 
-	if handled, editionErr := runEditionDoctor(opts, checks); handled {
-		return editionErr
-	}
-
 	// ── 1. Config file ──
 	_, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -134,10 +133,14 @@ func doctorRun(opts *DoctorOptions) error {
 		checks = append(checks, pass("identity_ready", "at least one identity is available"))
 	} else {
 		// No hint: this only summarizes the two checks above, which already carry
-		// the source-appropriate remediation. A command here would be redundant.
+		// the source-appropriate remediation. A command here would be redundant,
+		// or wrong (`auth status` is blocked under an external provider).
 		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
 	}
 
+	// ── 3b. private_key_jwt / TEE signer (local; runs even with --offline) ──
+	checks = append(checks, teeSignerCheck(opts.Ctx, cfg))
+
 	// ── 4 & 5. Endpoint reachability ──
 	checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
 
@@ -151,6 +154,73 @@ func identityCheck(name string, id identitydiag.Identity) checkResult {
 	return warn(name, id.Message, id.Hint)
 }
 
+const teeUnavailableHint = "ensure the device secure hardware is accessible (Linux TPM: add your user to the 'tss' group or run with sufficient privileges)"
+
+// teeSignerCheck reports the private_key_jwt signing backend (TEE/TPM) status.
+// The probe is local hardware only (no network), so it runs even with --offline;
+// in a build without a TEE signer it short-circuits without touching any
+// hardware. It is a hard requirement for private_key_jwt apps and purely
+// informational for client_secret apps.
+func teeSignerCheck(ctx context.Context, cfg *core.CliConfig) checkResult {
+	usesPKJWT := cfg != nil && cfg.AuthMethod == core.AuthMethodPrivateKeyJWT
+	if usesPKJWT && cfg.KeyProvider != "" {
+		helper, err := keylessprovider.Resolve(ctx, cfg.KeyProvider)
+		if err != nil {
+			return fail("tee_signer", "external keyless signer is unavailable",
+				fmt.Sprintf("repair or reinstall the OpenClaw Feishu plugin and its platform signer dependency: %v", err))
+		}
+		keyLabel := ""
+		if cfg != nil {
+			keyLabel = cfg.KeyLabel
+		}
+		if err := helper.Probe(ctx, keyLabel); err != nil {
+			hint := fmt.Sprintf("fix the configured external keyless signer, or re-run config init to replace/remove it: %v", err)
+			if usesPKJWT {
+				return fail("tee_signer", "external keyless signer is unavailable", hint)
+			}
+			return warn("tee_signer", "external keyless signer is misconfigured", hint)
+		}
+		return pass("tee_signer", "external keyless signer available")
+	}
+	info, ok, err := keysigner.ProbeActiveHardware(ctx)
+	return teeCheckResult(info, ok, err, usesPKJWT)
+}
+
+// teeCheckResult maps a hardware probe to a doctor check. Split out from
+// teeSignerCheck so the full matrix is unit-testable without a TPM.
+func teeCheckResult(info keysigner.HardwareInfo, ok bool, probeErr error, usesPKJWT bool) checkResult {
+	const name = "tee_signer"
+
+	// No signer registered → private_key_jwt is unsupported on this build.
+	if !ok {
+		if usesPKJWT {
+			return fail(name,
+				"app uses private_key_jwt but this build has no TEE key signer",
+				"the platform key signer ships by default on macOS, Linux, and Windows/amd64; this platform (e.g. Windows/arm64) has none — use a supported platform or re-register without --private-key-jwt")
+		}
+		return skip(name, "no TEE signer in this build (only private_key_jwt is affected; client_secret is unaffected)")
+	}
+
+	backend := info.Backend
+	if backend == "" {
+		backend = "tee"
+	}
+
+	switch {
+	case probeErr != nil:
+		return warn(name, fmt.Sprintf("%s signer present but probe errored: %s", backend, probeErr), "")
+	case info.Available:
+		if info.VendorName != "" {
+			return pass(name, fmt.Sprintf("%s TEE available (%s)", backend, info.VendorName))
+		}
+		return pass(name, fmt.Sprintf("%s TEE available", backend))
+	case usesPKJWT:
+		return fail(name, fmt.Sprintf("%s signer present but TEE unavailable: %s", backend, info.Reason), teeUnavailableHint)
+	default:
+		return warn(name, fmt.Sprintf("%s signer present but TEE unavailable: %s", backend, info.Reason), teeUnavailableHint)
+	}
+}
+
 // networkChecks probes Open API and MCP endpoints concurrently.
 func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints) []checkResult {
 	if opts.Offline {
@@ -218,7 +288,7 @@ func probeEndpoint(ctx context.Context, client *http.Client, url string) error {
 // Unlike the root-level async check, this does a synchronous fetch with timeout
 // and works regardless of build version (dev builds included).
 func checkCLIUpdate() []checkResult {
-	latest, err := fetchLatestForEdition()
+	latest, err := update.FetchLatest()
 	if err != nil {
 		return []checkResult{warn("cli_update", "check failed: "+err.Error(), "")}
 	}
@@ -240,14 +310,90 @@ func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 		}
 	}
 
-	result := map[string]interface{}{
-		"ok":        allOK,
-		"workspace": core.CurrentWorkspace().Display(),
-		"checks":    checks,
+	workspace := core.CurrentWorkspace().Display()
+	// A terminal on STDOUT gets a readable report; pipes, redirects, scripts and
+	// tests keep the stable JSON contract (NO_COLOR disables ANSI styling).
+	// OutIsTerminal checks stdout specifically — IOStreams.IsTerminal reflects
+	// stdin, which would wrongly send the human report into `doctor | jq`.
+	if f.IOStreams.OutIsTerminal {
+		renderDoctorHuman(f.IOStreams.Out, workspace, checks, allOK, os.Getenv("NO_COLOR") == "")
+	} else {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+			"ok":        allOK,
+			"workspace": workspace,
+			"checks":    checks,
+		})
 	}
-	output.PrintJson(f.IOStreams.Out, result)
 	if !allOK {
 		return output.ErrBare(1)
 	}
 	return nil
 }
+
+// renderDoctorHuman writes a readable health report: one aligned line per check
+// with a colored status tag, an indented hint when present, and a summary line.
+func renderDoctorHuman(w io.Writer, workspace string, checks []checkResult, allOK, color bool) {
+	const (
+		green  = "\033[32m"
+		yellow = "\033[33m"
+		red    = "\033[31m"
+		gray   = "\033[90m"
+		bold   = "\033[1m"
+		reset  = "\033[0m"
+	)
+	colorOf := map[string]string{"pass": green, "warn": yellow, "fail": red, "skip": gray}
+	tagOf := map[string]string{"pass": "PASS", "warn": "WARN", "fail": "FAIL", "skip": "SKIP"}
+	paint := func(code, s string) string {
+		if !color || code == "" {
+			return s
+		}
+		return code + s + reset
+	}
+
+	nameW := 0
+	for _, c := range checks {
+		if len(c.Name) > nameW {
+			nameW = len(c.Name)
+		}
+	}
+
+	fmt.Fprintf(w, "\n%s  (workspace: %s)\n\n", paint(bold, "lark-cli doctor"), workspace)
+
+	var passN, warnN, failN, skipN int
+	for _, c := range checks {
+		tag := tagOf[c.Status]
+		if tag == "" {
+			tag = "????"
+		}
+		fmt.Fprintf(w, "  %s  %-*s  %s\n", paint(colorOf[c.Status], "["+tag+"]"), nameW, c.Name, c.Message)
+		if c.Hint != "" {
+			fmt.Fprintf(w, "         %-*s  %s\n", nameW, "", paint(gray, "↳ "+c.Hint))
+		}
+		switch c.Status {
+		case "pass":
+			passN++
+		case "warn":
+			warnN++
+		case "fail":
+			failN++
+		case "skip":
+			skipN++
+		}
+	}
+
+	headline := paint(green, "healthy")
+	if !allOK {
+		headline = paint(red, "problems found")
+	}
+	fmt.Fprintf(w, "\n  %s — %d passed", headline, passN)
+	if warnN > 0 {
+		fmt.Fprintf(w, ", %d warning(s)", warnN)
+	}
+	if failN > 0 {
+		fmt.Fprintf(w, ", %d failed", failN)
+	}
+	if skipN > 0 {
+		fmt.Fprintf(w, ", %d skipped", skipN)
+	}
+	fmt.Fprintln(w)
+}

cmd/doctor/doctor_edition_extended.go

@@ -1,94 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package doctor
-
-import (
-	"errors"
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/identitydiag"
-)
-
-func runEditionDoctor(opts *DoctorOptions, checks []checkResult) (bool, error) {
-	f := opts.Factory
-	if f == nil || f.Credential == nil {
-		return false, nil
-	}
-	source, err := f.Credential.InspectSource(opts.Ctx)
-	if err != nil {
-		checks = append(checks, fail("credential_source", err.Error(), editionDiagnosticErrorHint(err)))
-		return true, finishDoctor(f, checks)
-	}
-	if source == nil || !source.Managed {
-		return false, nil
-	}
-
-	provider := source.Name
-	cfg, err := f.Config()
-	if err != nil {
-		checks = append(checks,
-			fail("credential_source", err.Error(), editionDiagnosticErrorHint(err)),
-			skip("config_file", fmt.Sprintf("local credentials are not used; source is %s", provider)),
-		)
-		return true, finishDoctor(f, checks)
-	}
-	checks = append(checks, pass("credential_source",
-		fmt.Sprintf("credentials provided by %s (app %s; token not verified by this check)", provider, cfg.AppID)))
-
-	description := f.RuntimeDescription()
-	if description.Managed {
-		checks = append(checks, pass("config_file", "config.json found (system external credential mode)"))
-	} else {
-		checks = append(checks, skip("config_file",
-			fmt.Sprintf("local config not used; credentials provided by %s", provider)))
-	}
-	checks = append(checks, pass("app_resolved", fmt.Sprintf("app: %s (%s)", cfg.AppID, cfg.Brand)))
-
-	diagnostics := identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline)
-	checks = append(checks,
-		identityCheck("bot_identity", diagnostics.Bot),
-		identityCheck("user_identity", diagnostics.User),
-	)
-	if diagnostics.Bot.Available || diagnostics.User.Available {
-		checks = append(checks, pass("identity_ready", "at least one identity is available"))
-	} else {
-		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
-	}
-
-	if description.ProxiesRequests {
-		checks = append(checks, editionProxyNetworkCheck(opts, description.DataPlaneEndpoint, diagnostics))
-	} else {
-		checks = append(checks, networkChecks(opts.Ctx, opts, core.ResolveEndpoints(cfg.Brand))...)
-	}
-	return true, finishDoctor(f, checks)
-}
-
-func editionDiagnosticErrorHint(err error) string {
-	var blockErr *extcred.BlockError
-	if errors.As(err, &blockErr) {
-		return blockErr.Reason
-	}
-	var cfgErr *errs.ConfigError
-	if errors.As(err, &cfgErr) {
-		return cfgErr.Hint
-	}
-	return ""
-}
-
-func editionProxyNetworkCheck(opts *DoctorOptions, endpoint string, diagnostics identitydiag.Result) checkResult {
-	if opts.Offline {
-		return skip("endpoint_external_platform", "skipped (--offline)")
-	}
-	verified := func(id identitydiag.Identity) bool { return id.Verified != nil && *id.Verified }
-	if verified(diagnostics.User) || verified(diagnostics.Bot) {
-		return pass("endpoint_external_platform", endpoint+" reachable through an authenticated API request")
-	}
-	return fail("endpoint_external_platform", endpoint+" could not complete an authenticated API request",
-		"check the external credential program and platform logs")
-}

cmd/doctor/doctor_edition_extended_test.go

@@ -1,75 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package doctor
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/identitydiag"
-)
-
-func TestExtendedProxyNetworkCheckUsesAuthenticatedDiagnostics(t *testing.T) {
-	verified := true
-	endpoint := "https://credentials.example.com"
-	got := editionProxyNetworkCheck(&DoctorOptions{}, endpoint, identitydiag.Result{
-		User: identitydiag.Identity{Verified: &verified},
-	})
-	if got.Status != "pass" || got.Name != "endpoint_external_platform" {
-		t.Fatalf("check = %#v", got)
-	}
-
-	got = editionProxyNetworkCheck(&DoctorOptions{}, endpoint, identitydiag.Result{})
-	if got.Status != "fail" {
-		t.Fatalf("unverified check = %#v, want fail", got)
-	}
-}
-
-func TestExtendedDoctorManagedSourceDoesNotRequireLocalConfig(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	cfg := &core.CliConfig{
-		AppID: "cli_env", Brand: core.BrandFeishu,
-		SupportedIdentities: uint8(extcred.SupportsBot), DefaultAs: core.AsBot,
-	}
-	f, out, _, _ := cmdutil.TestFactory(t, cfg)
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{&fakeExtProvider{
-			name: "env",
-			account: &extcred.Account{
-				AppID:               "cli_env",
-				SupportedIdentities: extcred.SupportsBot,
-			},
-		}},
-		nil, nil, nil,
-	)
-
-	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err != nil {
-		t.Fatalf("doctorRun() error = %v", err)
-	}
-	var got struct {
-		OK     bool          `json:"ok"`
-		Checks []checkResult `json:"checks"`
-	}
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	if !got.OK {
-		t.Fatalf("checks = %#v", got.Checks)
-	}
-	assertCheck(t, got.Checks, "credential_source", "pass")
-	configCheck := findCheck(t, got.Checks, "config_file")
-	if configCheck.Status != "skip" ||
-		!strings.Contains(configCheck.Message, "local config") ||
-		strings.Contains(configCheck.Message, "config init") {
-		t.Fatalf("config_file = %#v", configCheck)
-	}
-}

cmd/doctor/doctor_edition_standard.go

@@ -1,24 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package doctor
-
-import "github.com/larksuite/cli/errs"
-
-func runEditionDoctor(opts *DoctorOptions, checks []checkResult) (bool, error) {
-	if opts == nil || opts.Factory == nil {
-		return false, nil
-	}
-	startupErr := opts.Factory.RuntimeStartupError()
-	if startupErr == nil {
-		return false, nil
-	}
-	hint := ""
-	if problem, ok := errs.ProblemOf(startupErr); ok {
-		hint = problem.Hint
-	}
-	checks = append(checks, fail("credential_source", startupErr.Error(), hint))
-	return true, finishDoctor(opts.Factory, checks)
-}

cmd/doctor/doctor_edition_standard_test.go

@@ -1,52 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package doctor
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-func TestStandardDoctorPreservesConfigFirstDiagnostics(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	cfg := &core.CliConfig{
-		AppID: "cli_env", Brand: core.BrandFeishu,
-		SupportedIdentities: uint8(extcred.SupportsBot), DefaultAs: core.AsBot,
-	}
-	f, out, _, _ := cmdutil.TestFactory(t, cfg)
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{&fakeExtProvider{
-			name: "env",
-			account: &extcred.Account{
-				AppID:               "cli_env",
-				SupportedIdentities: extcred.SupportsBot,
-			},
-		}},
-		nil, nil, nil,
-	)
-
-	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
-		t.Fatal("doctorRun() = nil, want established missing-config failure")
-	}
-	var got struct {
-		Checks []checkResult `json:"checks"`
-	}
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	assertCheck(t, got.Checks, "config_file", "fail")
-	for _, check := range got.Checks {
-		if check.Name == "credential_source" {
-			t.Fatalf("Standard doctor exposed edition diagnostic: %#v", got.Checks)
-		}
-	}
-}

cmd/doctor/doctor_test.go

@@ -4,8 +4,10 @@
 package doctor
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 	"testing"
@@ -16,6 +18,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
@@ -143,6 +146,107 @@ func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
 	assertCheck(t, got.Checks, "identity_ready", "pass")
 }
 
+func TestTeeCheckResult(t *testing.T) {
+	avail := keysigner.HardwareInfo{Backend: "tpm2", Available: true, VendorName: "ACME"}
+	unavail := keysigner.HardwareInfo{Backend: "tpm2", Reason: "open /dev/tpmrm0: permission denied"}
+
+	cases := []struct {
+		name     string
+		info     keysigner.HardwareInfo
+		ok       bool
+		probeErr error
+		pkjwt    bool
+		want     string
+	}{
+		{"no signer + private_key_jwt → fail", keysigner.HardwareInfo{}, false, nil, true, "fail"},
+		{"no signer + client_secret → skip", keysigner.HardwareInfo{}, false, nil, false, "skip"},
+		{"available + private_key_jwt → pass", avail, true, nil, true, "pass"},
+		{"available + client_secret → pass", avail, true, nil, false, "pass"},
+		{"unavailable + private_key_jwt → fail", unavail, true, nil, true, "fail"},
+		{"unavailable + client_secret → warn", unavail, true, nil, false, "warn"},
+		{"probe error → warn", keysigner.HardwareInfo{Backend: "tpm2"}, true, errors.New("boom"), true, "warn"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := teeCheckResult(tc.info, tc.ok, tc.probeErr, tc.pkjwt)
+			if got.Name != "tee_signer" {
+				t.Errorf("name = %q, want tee_signer", got.Name)
+			}
+			if got.Status != tc.want {
+				t.Errorf("status = %q, want %q (msg=%q)", got.Status, tc.want, got.Message)
+			}
+		})
+	}
+}
+
+// TestDoctorRun_TeeSignerWired proves the tee_signer check is part of doctorRun.
+// It asserts the build-independent invariant (a client_secret app must never
+// FAIL on TEE) so the test passes whether or not a signer is compiled in.
+func TestDoctorRun_TeeSignerWired(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{{
+			Name: "default", AppId: "test-app",
+			AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+		}},
+	}); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err != nil {
+		t.Fatalf("doctorRun() error = %v", err)
+	}
+	var got struct {
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	var c *checkResult
+	for i := range got.Checks {
+		if got.Checks[i].Name == "tee_signer" {
+			c = &got.Checks[i]
+		}
+	}
+	if c == nil {
+		t.Fatalf("tee_signer check not present in doctor output: %#v", got.Checks)
+	}
+	if c.Status == "fail" {
+		t.Errorf("tee_signer = fail for a client_secret app; want skip/warn/pass (msg=%q)", c.Message)
+	}
+}
+
+func TestRenderDoctorHuman(t *testing.T) {
+	var buf bytes.Buffer
+	checks := []checkResult{
+		pass("cli_version", "1.0.50"),
+		warn("tee_signer", "tpm2 signer present but TEE unavailable", "add your user to the 'tss' group"),
+		fail("identity_ready", "no usable identity", "run: lark-cli auth status --verify"),
+		skip("endpoint_open", "skipped (--offline)"),
+	}
+	renderDoctorHuman(&buf, "local", checks, false, false)
+	out := buf.String()
+
+	for _, want := range []string{
+		"lark-cli doctor", "workspace: local",
+		"[PASS]", "cli_version", "1.0.50",
+		"[WARN]", "tee_signer", "↳ add your user to the 'tss' group",
+		"[FAIL]", "identity_ready", "↳ run: lark-cli auth status --verify",
+		"[SKIP]", "endpoint_open",
+		"problems found", "1 passed", "1 warning(s)", "1 failed", "1 skipped",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output missing %q\n---\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "\033[") {
+		t.Errorf("color=false but ANSI escapes present:\n%s", out)
+	}
+}
+
 func assertCheck(t *testing.T, checks []checkResult, name, status string) {
 	t.Helper()
 	if got := findCheck(t, checks, name); got.Status != status {
@@ -174,44 +278,6 @@ func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*ext
 	return nil, nil
 }
 
-type failingDefaultAccountResolver struct {
-	err error
-}
-
-func (r *failingDefaultAccountResolver) ResolveAccount(context.Context) (*credential.Account, error) {
-	return nil, r.err
-}
-
-func TestDoctor_DefaultResolutionFailurePreservesConfigFileCheck(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, out, _, _ := cmdutil.TestFactory(t, nil)
-	f.Credential = credential.NewCredentialProvider(
-		nil,
-		&failingDefaultAccountResolver{err: core.NotConfiguredError()},
-		nil,
-		nil,
-	)
-
-	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
-		t.Fatal("doctorRun() = nil, want not-configured failure")
-	}
-	var got struct {
-		Checks []checkResult `json:"checks"`
-	}
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v\n%s", err, out.String())
-	}
-	configCheck := findCheck(t, got.Checks, "config_file")
-	if configCheck.Status != "fail" {
-		t.Fatalf("config_file = %#v, want fail", configCheck)
-	}
-	for _, check := range got.Checks {
-		if check.Name == "credential_source" {
-			t.Fatalf("default source resolution replaced the legacy config check: %#v", got.Checks)
-		}
-	}
-}
-
 // Under an external credential provider with no usable identity, the
 // identity_ready hint must not point at `auth status` (blocked there); the
 // per-identity checks already carry the source-appropriate escalation.
@@ -232,8 +298,12 @@ func TestDoctor_ExternalProvider_IdentityReadyHintNotBlockedCommand(t *testing.T
 		nil, nil,
 		func() (*http.Client, error) { return nil, nil },
 	)
-	f, out, _, _ := cmdutil.TestFactory(t, cfg)
-	f.Credential = cred
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{
+		Config:     func() (*core.CliConfig, error) { return cfg, nil },
+		Credential: cred,
+		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
+	}
 
 	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
 		t.Fatalf("doctorRun() = nil, want failure when no identity is available")

cmd/doctor/update_extended.go

@@ -1,12 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package doctor
-
-import "github.com/larksuite/cli/internal/extendedupdate"
-
-func fetchLatestForEdition() (string, error) {
-	return extendedupdate.FetchLatest()
-}

cmd/doctor/update_standard.go

@@ -1,12 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package doctor
-
-import "github.com/larksuite/cli/internal/update"
-
-func fetchLatestForEdition() (string, error) {
-	return update.FetchLatest()
-}

cmd/doctor_startup_standard_test.go

@@ -1,74 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package cmd
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-func TestStandardDoctorReportsEditionSentinelWithoutLocalProfile(t *testing.T) {
-	clearWorkspaceSignals(t)
-	clearCredentialSignals(t)
-	configDir := t.TempDir()
-	systemPath := filepath.Join(configDir, "external-credential.json")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-	t.Setenv(envvars.CliExternalCredentialConfig, systemPath)
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
-	t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
-	if err := vfs.WriteFile(systemPath, []byte("sentinel-only"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-
-	var stdout, stderr bytes.Buffer
-	root := Build(
-		context.Background(),
-		cmdutil.InvocationContext{},
-		WithIO(strings.NewReader(""), &stdout, &stderr),
-		WithoutPlugins(),
-		WithoutServiceCommands(),
-	)
-	root.SetArgs([]string{"doctor", "--offline"})
-	if err := root.ExecuteContext(context.Background()); err == nil {
-		t.Fatal("doctor returned nil, want failed diagnostic result")
-	}
-
-	var report struct {
-		Checks []struct {
-			Name    string `json:"name"`
-			Status  string `json:"status"`
-			Message string `json:"message"`
-			Hint    string `json:"hint"`
-		} `json:"checks"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &report); err != nil {
-		t.Fatalf("decode doctor output: %v\nstdout: %s\nstderr: %s", err, stdout.String(), stderr.String())
-	}
-	for _, check := range report.Checks {
-		if check.Name != "credential_source" {
-			continue
-		}
-		if check.Status != "fail" ||
-			check.Message != "system external credential configuration requires the lark-cli Extended edition" ||
-			!strings.Contains(check.Hint, "install lark-cli Extended") {
-			t.Fatalf("credential_source check = %#v", check)
-		}
-		if strings.Contains(stdout.String(), "config init") {
-			t.Fatalf("doctor suggested local credential bootstrap for an edition sentinel: %s", stdout.String())
-		}
-		return
-	}
-	t.Fatalf("doctor did not report the edition sentinel: %s", stdout.String())
-}

cmd/edition_commands_extended.go

@@ -1,17 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package cmd
-
-import (
-	cmdversion "github.com/larksuite/cli/cmd/version"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-// registerEditionCommands owns the Extended-only command surface.
-func registerEditionCommands(root *cobra.Command, f *cmdutil.Factory) {
-	root.AddCommand(cmdversion.NewCmdVersion(f))
-}

cmd/edition_commands_extended_test.go

@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package cmd
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-func TestExtendedRegistersVersionCommand(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	root := &cobra.Command{Use: "lark-cli"}
-
-	registerEditionCommands(root, f)
-
-	commands := root.Commands()
-	if len(commands) != 1 || commands[0].Name() != "version" {
-		t.Fatalf("Extended edition commands = %v, want [version]", commands)
-	}
-	if commands[0].Hidden {
-		t.Fatal("Extended version command must be visible")
-	}
-}

cmd/edition_commands_standard.go

@@ -1,20 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package cmd
-
-import (
-	cmdversion "github.com/larksuite/cli/cmd/version"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-// registerEditionCommands keeps the release identity probe callable in
-// Standard while cmd/version hides it from help. This preserves the ordinary
-// command surface and gives installers/CI one edition-neutral verification
-// contract.
-func registerEditionCommands(root *cobra.Command, f *cmdutil.Factory) {
-	root.AddCommand(cmdversion.NewCmdVersion(f))
-}

cmd/edition_commands_standard_test.go

@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package cmd
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-func TestStandardRegistersHiddenVersionCommand(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	root := &cobra.Command{Use: "lark-cli"}
-
-	registerEditionCommands(root, f)
-
-	commands := root.Commands()
-	if len(commands) != 1 || commands[0].Name() != "version" {
-		t.Fatalf("Standard edition commands = %v, want [version]", commands)
-	}
-	if !commands[0].Hidden {
-		t.Fatal("Standard version command must remain hidden")
-	}
-}

cmd/event/event.go

@@ -7,7 +7,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 func NewCmdEvents(f *cmdutil.Factory) *cobra.Command {
@@ -17,31 +16,14 @@ func NewCmdEvents(f *cmdutil.Factory) *cobra.Command {
 		Long:  `Unified event consumption system. Use 'event consume <EventKey>' to start consuming events.`,
 		// Without SilenceUsage, RunE errors print the full flag help banner.
 		SilenceUsage: true,
-		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
-			cmd.SilenceUsage = true
-			// This hook shadows root's PersistentPreRun, so preserve the matched
-			// command for structured error and declared-scope hints.
-			f.CurrentCommand = cmd
-			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
-		},
 	}
-	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityRealtimeEvents)
 
-	consume := NewCmdConsume(f)
-	bus := NewCmdBus(f)
-	list := NewCmdList(f)
-	schema := NewCmdSchema(f)
-	status := NewCmdStatus(f)
-	stop := NewCmdStop(f)
-	for _, local := range []*cobra.Command{list, schema, status, stop} {
-		cmdutil.SetRuntimeCapabilities(local)
-	}
-	cmd.AddCommand(consume)
-	cmd.AddCommand(list)
-	cmd.AddCommand(schema)
-	cmd.AddCommand(status)
-	cmd.AddCommand(stop)
-	cmd.AddCommand(bus)
+	cmd.AddCommand(NewCmdConsume(f))
+	cmd.AddCommand(NewCmdList(f))
+	cmd.AddCommand(NewCmdSchema(f))
+	cmd.AddCommand(NewCmdStatus(f))
+	cmd.AddCommand(NewCmdStop(f))
+	cmd.AddCommand(NewCmdBus(f))
 
 	return cmd
 }

cmd/event/external_credential_guard_test.go

@@ -1,146 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"errors"
-	"io/fs"
-	"path/filepath"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/runtimeplan"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-func TestEventCommandsRejectDeniedRuntimeCapability(t *testing.T) {
-	cfg := &core.CliConfig{
-		AppID:     "cli_runtime_event_test",
-		AppSecret: "must-not-be-used",
-		Brand:     core.BrandFeishu,
-	}
-	denied := errs.NewValidationError(errs.SubtypeFailedPrecondition,
-		"real-time events are unavailable in this runtime").
-		WithHint("use a runtime that supports real-time events")
-	plan := runtimeplan.New(runtimeplan.Options{
-		Capabilities: func(capability runtimeplan.Capability) error {
-			if capability == runtimeplan.CapabilityRealtimeEvents {
-				return denied
-			}
-			return nil
-		},
-	})
-
-	t.Run("consume", func(t *testing.T) {
-		f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, cfg, plan)
-		cmd := NewCmdEvents(f)
-		args := []string{"consume", "guarded-before-event-lookup"}
-		matched, _, err := cmd.Find(args)
-		if err != nil {
-			t.Fatalf("Find() error = %v", err)
-		}
-		cmd.SetArgs(args)
-		requireExternalEventGuard(t, cmd.Execute())
-		if f.CurrentCommand != matched {
-			t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
-		}
-	})
-
-	t.Run("bus", func(t *testing.T) {
-		configDir := t.TempDir()
-		t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-		f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, cfg, plan)
-		cmd := NewCmdEvents(f)
-		args := []string{"_bus"}
-		matched, _, err := cmd.Find(args)
-		if err != nil {
-			t.Fatalf("Find() error = %v", err)
-		}
-		cmd.SetArgs(args)
-		requireExternalEventGuard(t, cmd.Execute())
-		if f.CurrentCommand != matched {
-			t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
-		}
-		if _, err := vfs.Stat(filepath.Join(configDir, "events")); !errors.Is(err, fs.ErrNotExist) {
-			t.Fatalf("event bus created runtime files before guard: %v", err)
-		}
-	})
-}
-
-func TestEventCommandRuntimeCapabilityMatrix(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	cmd := NewCmdEvents(f)
-
-	parentCapabilities := cmdutil.GetRuntimeCapabilities(cmd)
-	if len(parentCapabilities) != 1 || parentCapabilities[0] != runtimeplan.CapabilityRealtimeEvents {
-		t.Fatalf("event capabilities = %v, want [%s]", parentCapabilities, runtimeplan.CapabilityRealtimeEvents)
-	}
-
-	wantRealtime := map[string]bool{
-		"_bus":    true,
-		"consume": true,
-		"list":    false,
-		"schema":  false,
-		"status":  false,
-		"stop":    false,
-	}
-	children := make(map[string]*cobra.Command, len(wantRealtime))
-	for _, child := range cmd.Commands() {
-		name := child.Name()
-		want, ok := wantRealtime[name]
-		if !ok {
-			t.Fatalf("event command %q is missing from the runtime capability matrix", name)
-		}
-		children[name] = child
-		got := cmdutil.GetRuntimeCapabilities(child)
-		if want {
-			if len(got) != 1 || got[0] != runtimeplan.CapabilityRealtimeEvents {
-				t.Errorf("event %s capabilities = %v, want [%s]", name, got, runtimeplan.CapabilityRealtimeEvents)
-			}
-			continue
-		}
-		if len(got) != 0 {
-			t.Errorf("event %s capabilities = %v, want source-neutral local command", name, got)
-		}
-	}
-	if len(children) != len(wantRealtime) {
-		t.Fatalf("event command matrix covered %d commands, want %d", len(children), len(wantRealtime))
-	}
-
-	// Clearing the parent declaration must also clear both consumers. This
-	// proves they inherit the fail-closed default instead of duplicating a
-	// leaf annotation that future event commands could forget.
-	cmdutil.SetRuntimeCapabilities(cmd)
-	for _, name := range []string{"consume", "_bus"} {
-		if got := cmdutil.GetRuntimeCapabilities(children[name]); len(got) != 0 {
-			t.Errorf("event %s capabilities after clearing parent = %v, want inherited empty declaration", name, got)
-		}
-	}
-}
-
-func requireExternalEventGuard(t *testing.T, err error) {
-	t.Helper()
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error = %T %v, want typed problem", err, err)
-	}
-	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("problem = %s/%s, want %s/%s",
-			problem.Category, problem.Subtype, errs.CategoryValidation, errs.SubtypeFailedPrecondition)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("error = %T, want *errs.ValidationError", err)
-	}
-	if validationErr.Param != "" {
-		t.Fatalf("param = %q, want empty", validationErr.Param)
-	}
-	if problem.Hint == "" {
-		t.Fatal("hint is empty")
-	}
-}

cmd/profile/profile.go

@@ -7,7 +7,6 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 // NewCmdProfile creates the profile command with subcommands.
@@ -15,26 +14,13 @@ func NewCmdProfile(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "profile",
 		Short: "Manage configuration profiles",
-		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
-			// A child PersistentPreRunE shadows root's PersistentPreRun, so retain
-			// the invocation state used by structured error hints here.
-			cmd.SilenceUsage = true
-			f.CurrentCommand = cmd
-			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
-		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalProfileMutation)
 	cmdutil.SetTips(cmd, []string{
 		"AI agents: Do NOT switch or remove profiles unless the user explicitly asks.",
 	})
 
-	list := NewCmdProfileList(f)
-	// Listing profiles is read-only and remains useful for diagnostics under a
-	// managed credential runtime. Every other profile subcommand mutates local
-	// profile selection, config, or keychain state and inherits the parent gate.
-	cmdutil.SetRuntimeCapabilities(list)
-	cmd.AddCommand(list)
+	cmd.AddCommand(NewCmdProfileList(f))
 	cmd.AddCommand(NewCmdProfileUse(f))
 	cmd.AddCommand(NewCmdProfileAdd(f))
 	cmd.AddCommand(NewCmdProfileRemove(f))

cmd/profile/runtime_capabilities_test.go

@@ -1,222 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package profile
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/runtimeplan"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-type recordingProfileKeychain struct {
-	gets    int
-	sets    int
-	removes int
-}
-
-func (k *recordingProfileKeychain) Get(_, _ string) (string, error) {
-	k.gets++
-	return "", nil
-}
-
-func (k *recordingProfileKeychain) Set(_, _, _ string) error {
-	k.sets++
-	return nil
-}
-
-func (k *recordingProfileKeychain) Remove(_, _ string) error {
-	k.removes++
-	return nil
-}
-
-func TestProfileMutationCommandsAreDeniedBeforeLocalStateChanges(t *testing.T) {
-	denied := errs.NewValidationError(
-		errs.SubtypeFailedPrecondition,
-		"local credential management is unavailable in this runtime",
-	).WithHint("manage credentials through the active provider")
-	plan := runtimeplan.New(runtimeplan.Options{
-		Capabilities: func(capability runtimeplan.Capability) error {
-			if capability == runtimeplan.CapabilityLocalProfileMutation {
-				return denied
-			}
-			return nil
-		},
-	})
-
-	tests := []struct {
-		name string
-		args []string
-	}{
-		{
-			name: "add",
-			args: []string{"add", "--name", "new", "--app-id", "app-new", "--app-secret-stdin"},
-		},
-		{
-			name: "use",
-			args: []string{"use", "target"},
-		},
-		{
-			name: "rename",
-			args: []string{"rename", "target", "renamed"},
-		},
-		{
-			name: "remove",
-			args: []string{"remove", "target"},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			configDir := setupProfileConfigDir(t)
-			saveManagedGateFixture(t)
-			configPath := filepath.Join(configDir, "config.json")
-			before, err := vfs.ReadFile(configPath)
-			if err != nil {
-				t.Fatalf("ReadFile(before) error = %v", err)
-			}
-
-			f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
-			f.IOStreams.In = strings.NewReader("must-not-be-read\n")
-			keychain := &recordingProfileKeychain{}
-			f.Keychain = keychain
-
-			cmd := NewCmdProfile(f)
-			cmd.SetArgs(tt.args)
-			err = cmd.Execute()
-			if !errors.Is(err, denied) {
-				t.Fatalf("Execute() error = %v, want denied runtime error", err)
-			}
-
-			after, readErr := vfs.ReadFile(configPath)
-			if readErr != nil {
-				t.Fatalf("ReadFile(after) error = %v", readErr)
-			}
-			if !bytes.Equal(after, before) {
-				t.Fatalf("config changed despite runtime denial:\nbefore: %s\nafter:  %s", before, after)
-			}
-			if keychain.gets != 0 || keychain.sets != 0 || keychain.removes != 0 {
-				t.Fatalf("keychain calls = get:%d set:%d remove:%d, want none",
-					keychain.gets, keychain.sets, keychain.removes)
-			}
-		})
-	}
-}
-
-func TestProfileListRemainsAvailableWhenLocalMutationIsDenied(t *testing.T) {
-	setupProfileConfigDir(t)
-	saveManagedGateFixture(t)
-	plan := runtimeplan.New(runtimeplan.Options{
-		Capabilities: func(capability runtimeplan.Capability) error {
-			if capability == runtimeplan.CapabilityLocalProfileMutation {
-				return errs.NewValidationError(
-					errs.SubtypeFailedPrecondition,
-					"local credential management is unavailable in this runtime",
-				)
-			}
-			return nil
-		},
-	})
-	f, stdout, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
-
-	cmd := NewCmdProfile(f)
-	cmd.SetArgs([]string{"list"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("profile list was blocked by mutation capability: %v", err)
-	}
-	if !strings.Contains(stdout.String(), `"name": "default"`) {
-		t.Fatalf("profile list output = %s, want default profile", stdout.String())
-	}
-}
-
-func TestProfileMutationCommandsRemainAvailableByDefault(t *testing.T) {
-	setupProfileConfigDir(t)
-	saveManagedGateFixture(t)
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	// origin/main allows Profile preparation while an environment/extension
-	// provider is active. The managed runtime blocks this through its explicit
-	// plan policy; generic provider ownership must not change Standard.
-	f.Credential = credential.NewCredentialProvider(
-		[]extcred.Provider{profileEnvironmentProvider{}},
-		nil,
-		nil,
-		nil,
-	)
-
-	cmd := NewCmdProfile(f)
-	args := []string{"use", "target"}
-	matched, _, err := cmd.Find(args)
-	if err != nil {
-		t.Fatalf("Find() error = %v", err)
-	}
-	cmd.SetArgs(args)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("profile use with default runtime plan error = %v", err)
-	}
-	if f.CurrentCommand != matched {
-		t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
-	}
-
-	saved, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig() error = %v", err)
-	}
-	if saved.CurrentApp != "target" || saved.PreviousApp != "default" {
-		t.Fatalf("selection = current:%q previous:%q, want target/default",
-			saved.CurrentApp, saved.PreviousApp)
-	}
-}
-
-type profileEnvironmentProvider struct{}
-
-func (profileEnvironmentProvider) Name() string { return "env" }
-
-func (profileEnvironmentProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
-	return &extcred.Account{
-		AppID:               "cli_environment",
-		Brand:               extcred.BrandFeishu,
-		SupportedIdentities: extcred.SupportsAll,
-	}, nil
-}
-
-func (profileEnvironmentProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
-	return &extcred.Token{Value: "environment-token"}, nil
-}
-
-func saveManagedGateFixture(t *testing.T) {
-	t.Helper()
-	multi := &core.MultiAppConfig{
-		CurrentApp: "default",
-		Apps: []core.AppConfig{
-			{
-				Name:      "default",
-				AppId:     "app-default",
-				AppSecret: core.PlainSecret("secret-default"),
-				Brand:     core.BrandFeishu,
-			},
-			{
-				Name:  "target",
-				AppId: "app-target",
-				AppSecret: core.SecretInput{Ref: &core.SecretRef{
-					Source: "keychain",
-					ID:     "appsecret:app-target",
-				}},
-				Brand: core.BrandLark,
-			},
-		},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-}

cmd/root.go

@@ -21,7 +21,6 @@ import (
 	"github.com/larksuite/cli/internal/deprecation"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/runtimebootstrap"
 	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/suggest"
 	"github.com/larksuite/cli/internal/update"
@@ -101,12 +100,6 @@ func Execute() int {
 		fmt.Fprintln(os.Stderr, "Error:", err)
 		return 1
 	}
-	// Resolve all startup state from the detected workspace. This must happen
-	// before ResolveStartupBrand, isSingleAppMode, or buildInternal reads
-	// workspace-scoped configuration.
-	selectInvocationWorkspace()
-	startup := runtimebootstrap.Resolve(inv.Profile)
-	startupBrand := resolveStartupBrandFromConfig(inv.Profile, startup.ProfileConfig)
 	configureFlagCompletions(os.Args)
 
 	ctx := context.Background()
@@ -114,8 +107,7 @@ func Execute() int {
 		ctx, inv,
 		WithIO(os.Stdin, os.Stdout, os.Stderr),
 		HideProfile(isSingleAppMode()),
-		WithStartupBrand(startupBrand),
-		withRuntimeBootstrap(startup),
+		WithStartupBrand(ResolveStartupBrand(inv.Profile)),
 	)
 
 	// --- Notices (non-blocking) ---
@@ -145,7 +137,7 @@ func Execute() int {
 // or both may be present in any given envelope.
 func setupNotices() {
 	// Binary update — synchronous cache check + async refresh
-	if info := checkCachedEditionUpdate(build.Version); info != nil {
+	if info := update.CheckCached(build.Version); info != nil {
 		update.SetPending(info)
 	}
 	ver := build.Version
@@ -155,9 +147,9 @@ func setupNotices() {
 				fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
 			}
 		}()
-		refreshEditionUpdateCache(ver)
+		update.RefreshCache(ver)
 		if update.GetPending() == nil {
-			if info := checkCachedEditionUpdate(ver); info != nil {
+			if info := update.CheckCached(ver); info != nil {
 				update.SetPending(info)
 			}
 		}

cmd/root_test.go

@@ -18,7 +18,6 @@ import (
 	cmdconfig "github.com/larksuite/cli/cmd/config"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -436,25 +435,6 @@ func TestHandleRootError_LeakedUntypedErrorBecomesInternal(t *testing.T) {
 	}
 }
 
-func TestHandleRootError_BlockErrorPreservesUntypedFallback(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	errOut := &bytes.Buffer{}
-	f.IOStreams.ErrOut = errOut
-	blockErr := &extcred.BlockError{Provider: "env", Reason: "LARKSUITE_CLI_APP_ID is missing"}
-
-	exit := handleRootError(f, blockErr)
-	errObj := decodeErrorEnvelope(t, errOut.Bytes())
-	if errObj["type"] != "internal" || errObj["subtype"] != "unknown" {
-		t.Fatalf("error = %#v", errObj)
-	}
-	if errObj["message"] != "blocked by env: LARKSUITE_CLI_APP_ID is missing" {
-		t.Fatalf("error.message = %v", errObj["message"])
-	}
-	if exit != int(output.ExitInternal) {
-		t.Fatalf("exit = %d, want %d", exit, output.ExitInternal)
-	}
-}
-
 // TestHandleRootError_PartialWritePreservesExitCode pins that when the
 // stderr write fails mid-envelope, handleRootError still returns the typed
 // exit code (ExitAuth=3 for AuthenticationError), not fall through to the

cmd/root_upgrade.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 )
 
@@ -57,10 +58,10 @@ func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command) {
 	if !ios.IsTerminal || !ios.OutIsTerminal || !ios.StderrIsTerminal {
 		return
 	}
-	// Gate 4: cached newer version from this binary's release channel.
-	// Standard reads the npm-backed cache; Extended reads its separate
-	// GitHub-release cache.
-	info := checkCachedEditionUpdate(build.Version)
+	// Gate 4: cached newer version. CheckCached applies opt-out (shouldSkip)
+	// and the IsNewer/semver validation chain; it reads the on-disk cache that
+	// the 24h-throttled RefreshCache maintains (CheckCached itself has no TTL).
+	info := update.CheckCached(build.Version)
 	if info == nil {
 		return
 	}

cmd/root_upgrade_test.go

@@ -6,6 +6,7 @@ package cmd
 import (
 	"bytes"
 	"fmt"
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -14,21 +15,13 @@ import (
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/vfs"
 	"github.com/spf13/cobra"
 )
 
-func updateStateFileForEdition(edition string) string {
-	if edition == "extended" {
-		return "update-state-extended.json"
-	}
-	return "update-state.json"
-}
-
-func writeUpdateState(t *testing.T, dir, edition, latest string) {
+func writeUpdateState(t *testing.T, dir, latest string) {
 	t.Helper()
 	data := fmt.Sprintf(`{"latest_version":%q,"checked_at":%d}`, latest, time.Now().Unix())
-	if err := vfs.WriteFile(filepath.Join(dir, updateStateFileForEdition(edition)), []byte(data), 0o600); err != nil {
+	if err := os.WriteFile(filepath.Join(dir, "update-state.json"), []byte(data), 0o644); err != nil {
 		t.Fatal(err)
 	}
 }
@@ -112,7 +105,7 @@ func TestOfferRootUpgrade(t *testing.T) {
 			t.Setenv("RUN_ID", "")
 			t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
 			if tc.latest != "" {
-				writeUpdateState(t, dir, build.Edition, tc.latest)
+				writeUpdateState(t, dir, tc.latest)
 			}
 			if tc.optOut {
 				t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
@@ -142,53 +135,6 @@ func TestOfferRootUpgrade(t *testing.T) {
 	}
 }
 
-func TestOfferRootUpgradeIgnoresOtherEditionCache(t *testing.T) {
-	origV := build.Version
-	build.Version = "1.0.0"
-	t.Cleanup(func() { build.Version = origV })
-
-	origRun := runRootUpgrade
-	t.Cleanup(func() { runRootUpgrade = origRun })
-
-	origWS := core.CurrentWorkspace()
-	t.Cleanup(func() { core.SetCurrentWorkspace(origWS) })
-	core.SetCurrentWorkspace(core.WorkspaceLocal)
-
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	t.Setenv("CI", "")
-	t.Setenv("BUILD_NUMBER", "")
-	t.Setenv("RUN_ID", "")
-	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
-
-	otherEdition := "extended"
-	if build.Edition == "extended" {
-		otherEdition = "standard"
-	}
-	writeUpdateState(t, dir, otherEdition, "9.0.0")
-
-	called := false
-	runRootUpgrade = func(*cobra.Command) { called = true }
-	var errBuf bytes.Buffer
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
-		In:               strings.NewReader("y\n"),
-		Out:              &bytes.Buffer{},
-		ErrOut:           &errBuf,
-		IsTerminal:       true,
-		OutIsTerminal:    true,
-		StderrIsTerminal: true,
-	}}
-
-	offerRootUpgrade(f, &cobra.Command{})
-
-	if strings.Contains(errBuf.String(), "available") {
-		t.Fatalf("%s prompt consumed %s cache: %q", build.Edition, otherEdition, errBuf.String())
-	}
-	if called {
-		t.Fatalf("%s upgrade ran from %s cache", build.Edition, otherEdition)
-	}
-}
-
 func TestInstallRootUpgradePromptPreservesInner(t *testing.T) {
 	orig := rawInvocationArgs
 	t.Cleanup(func() { rawInvocationArgs = orig })

cmd/startup_brand.go

@@ -10,34 +10,17 @@ import (
 	"github.com/larksuite/cli/internal/envvars"
 )
 
-// selectInvocationWorkspace establishes the workspace before any startup
-// consumer reads workspace-scoped configuration. Execute needs this before
-// resolving the registry brand, while Build/buildInternal needs it before
-// capturing the immutable Profile snapshot passed to the Factory.
-func selectInvocationWorkspace() core.Workspace {
-	workspace := core.DetectWorkspaceFromEnv(os.Getenv)
-	core.SetCurrentWorkspace(workspace)
-	return workspace
-}
-
 // ResolveStartupBrand resolves the brand before the command tree is built, so
 // the registry's remote metadata overlay uses the configured brand from the
 // first catalog access. It mirrors the credential chain's brand precedence —
 // environment, then the active profile's raw config entry — without touching
 // the keychain (no secrets are needed to know the brand).
 func ResolveStartupBrand(profile string) core.LarkBrand {
-	config, _ := core.LoadMultiAppConfig()
-	return resolveStartupBrandFromConfig(profile, config)
-}
-
-// resolveStartupBrandFromConfig keeps registry routing on the same immutable
-// Profile snapshot used by credentials and runtime policy.
-func resolveStartupBrandFromConfig(profile string, config *core.MultiAppConfig) core.LarkBrand {
 	if raw := os.Getenv(envvars.CliBrand); raw != "" {
 		return core.ParseBrand(raw)
 	}
-	if config != nil {
-		if app := config.CurrentAppConfig(profile); app != nil {
+	if cfg, err := core.LoadMultiAppConfig(); err == nil {
+		if app := cfg.CurrentAppConfig(profile); app != nil {
 			return core.ParseBrand(string(app.Brand))
 		}
 	}

cmd/update/edition_extended.go

@@ -1,100 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package cmdupdate
-
-import (
-	"errors"
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/extendedupdate"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/skillscheck"
-	"github.com/larksuite/cli/internal/update"
-)
-
-var (
-	fetchExtendedLatest = extendedupdate.FetchLatest
-	installExtended     = extendedupdate.Install
-)
-
-func updateLongDescription() string {
-	return `Update lark-cli Extended from the matching GitHub Release.
-
-The command downloads the lark-cli-extended asset for the current platform,
-verifies its SHA-256 checksum and compiled edition identity, then replaces the
-current binary. It never installs the Standard npm/npx edition.
-
-Use --json for structured output (for AI agents and scripts).
-Use --check to only check for updates without installing.`
-}
-
-func runEditionUpdate(opts *UpdateOptions) (bool, error) {
-	io := opts.Factory.IOStreams
-	cur := currentVersion()
-	updater := newUpdater()
-	if !opts.Check {
-		updater.Brand = resolveSkillsBrand(opts.Factory, io.ErrOut)
-		updater.CleanupStaleFiles()
-	}
-	output.PendingNotice = nil
-
-	latest, err := fetchExtendedLatest()
-	if err != nil {
-		var typed errs.TypedError
-		if errors.As(err, &typed) {
-			return true, reportError(opts, io, "network", typed)
-		}
-		return true, reportError(opts, io, "network",
-			errs.NewNetworkError(errs.SubtypeNetworkTransport,
-				"failed to check the latest Extended version: %v", err).WithCause(err))
-	}
-	if update.ParseVersion(latest) == nil {
-		return true, reportError(opts, io, "update_error",
-			errs.NewInternalError(errs.SubtypeInvalidResponse,
-				"invalid Extended version from GitHub Releases: %s", latest))
-	}
-	if !opts.Force && !update.IsNewer(latest, cur) {
-		var skillsResult *skillscheck.SyncResult
-		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
-		}
-		return true, reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
-	}
-	if opts.Check {
-		return true, reportCheckResult(opts, io, cur, latest, true)
-	}
-	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli Extended %s %s %s from GitHub Releases ...\n", cur, symArrow(), latest)
-	}
-	if err := installExtended(latest); err != nil {
-		var typed errs.TypedError
-		if errors.As(err, &typed) {
-			return true, reportError(opts, io, "update_error", typed)
-		}
-		return true, reportError(opts, io, "update_error",
-			errs.NewInternalError(errs.SubtypeUnknown,
-				"failed to install lark-cli Extended: %v", err).WithCause(err))
-	}
-
-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
-	if opts.JSON {
-		result := map[string]interface{}{
-			"ok": true, "previous_version": cur, "current_version": latest,
-			"latest_version": latest, "edition": build.Edition, "action": "updated",
-			"message": fmt.Sprintf("lark-cli Extended updated from %s to %s", cur, latest),
-			"url":     releaseURL(latest), "changelog": changelogURL(),
-		}
-		applySkillsResult(result, skillsResult)
-		output.PrintJson(io.Out, result)
-		return true, nil
-	}
-	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli Extended from %s to %s\n", symOK(), cur, latest)
-	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	emitSkillsTextHints(io, skillsResult)
-	return true, nil
-}

cmd/update/edition_extended_test.go

@@ -1,80 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package cmdupdate
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/selfupdate"
-	"github.com/larksuite/cli/internal/skillscheck"
-)
-
-func TestExtendedUpdateUsesExtendedReleaseInstaller(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	oldFetch, oldInstall := fetchExtendedLatest, installExtended
-	oldVersion, oldUpdater, oldSync := currentVersion, newUpdater, syncSkills
-	t.Cleanup(func() {
-		fetchExtendedLatest, installExtended = oldFetch, oldInstall
-		currentVersion, newUpdater, syncSkills = oldVersion, oldUpdater, oldSync
-	})
-	fetchExtendedLatest = func() (string, error) { return "1.2.4", nil }
-	currentVersion = func() string { return "1.2.3" }
-	installed := ""
-	installExtended = func(version string) error {
-		installed = version
-		return nil
-	}
-	newUpdater = func() *selfupdate.Updater {
-		return &selfupdate.Updater{DetectOverride: func() selfupdate.DetectResult {
-			return selfupdate.DetectResult{Method: selfupdate.InstallManual}
-		}}
-	}
-	syncSkills = func(skillscheck.SyncOptions) *skillscheck.SyncResult { return &skillscheck.SyncResult{} }
-
-	var out, errOut bytes.Buffer
-	f := cmdutil.NewDefault(cmdutil.NewIOStreams(nil, &out, &errOut), cmdutil.InvocationContext{})
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json"})
-	if err := cmd.ExecuteContext(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if installed != "1.2.4" {
-		t.Fatalf("installed version = %q, want 1.2.4", installed)
-	}
-	var result map[string]interface{}
-	if err := json.Unmarshal(out.Bytes(), &result); err != nil {
-		t.Fatal(err)
-	}
-	if result["edition"] != "extended" || result["action"] != "updated" {
-		t.Fatalf("result = %#v", result)
-	}
-}
-
-func TestExtendedUpdateCheckDoesNotInstall(t *testing.T) {
-	oldFetch, oldInstall := fetchExtendedLatest, installExtended
-	oldVersion := currentVersion
-	t.Cleanup(func() {
-		fetchExtendedLatest, installExtended = oldFetch, oldInstall
-		currentVersion = oldVersion
-	})
-	fetchExtendedLatest = func() (string, error) { return "1.2.4", nil }
-	currentVersion = func() string { return "1.2.3" }
-	installExtended = func(string) error {
-		t.Fatal("installer called during --check")
-		return nil
-	}
-	var out bytes.Buffer
-	f := cmdutil.NewDefault(cmdutil.NewIOStreams(nil, &out, &bytes.Buffer{}), cmdutil.InvocationContext{})
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json", "--check"})
-	if err := cmd.ExecuteContext(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-}

cmd/update/edition_standard.go

@@ -1,20 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package cmdupdate
-
-func runEditionUpdate(*UpdateOptions) (bool, error) { return false, nil }
-
-func updateLongDescription() string {
-	return `Update lark-cli to the latest version.
-
-Detects the installation method automatically:
-  - npm install:  runs npm install -g @larksuite/cli@<version>
-  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
-  - manual/other: shows GitHub Releases download URL
-
-Use --json for structured output (for AI agents and scripts).
-Use --check to only check for updates without installing.`
-}

cmd/update/update.go

@@ -101,7 +101,15 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update",
 		Short: "Update lark-cli to the latest version",
-		Long:  updateLongDescription(),
+		Long: `Update lark-cli to the latest version.
+
+Detects the installation method automatically:
+  - npm install:  runs npm install -g @larksuite/cli@<version>
+  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
+  - manual/other: shows GitHub Releases download URL
+
+Use --json for structured output (for AI agents and scripts).
+Use --check to only check for updates without installing.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return updateRun(opts)
 		},
@@ -116,9 +124,6 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 }
 
 func updateRun(opts *UpdateOptions) error {
-	if handled, err := runEditionUpdate(opts); handled {
-		return err
-	}
 	io := opts.Factory.IOStreams
 	cur := currentVersion()
 	updater := newUpdater()

cmd/update/update_test.go

@@ -1,8 +1,6 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-//go:build !extended
-
 package cmdupdate
 
 import (

cmd/update_notice_extended.go

@@ -1,19 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package cmd
-
-import (
-	"github.com/larksuite/cli/internal/extendedupdate"
-	"github.com/larksuite/cli/internal/update"
-)
-
-func checkCachedEditionUpdate(currentVersion string) *update.UpdateInfo {
-	return extendedupdate.CheckCached(currentVersion)
-}
-
-func refreshEditionUpdateCache(currentVersion string) {
-	extendedupdate.RefreshCache(currentVersion)
-}

cmd/update_notice_standard.go

@@ -1,16 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package cmd
-
-import "github.com/larksuite/cli/internal/update"
-
-func checkCachedEditionUpdate(currentVersion string) *update.UpdateInfo {
-	return update.CheckCached(currentVersion)
-}
-
-func refreshEditionUpdateCache(currentVersion string) {
-	update.RefreshCache(currentVersion)
-}

cmd/version/version.go

@@ -1,56 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package version
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/spf13/cobra"
-)
-
-type options struct {
-	factory *cmdutil.Factory
-	json    bool
-}
-
-type versionReport struct {
-	Version      string   `json:"version"`
-	Edition      string   `json:"edition"`
-	Capabilities []string `json:"capabilities"`
-}
-
-// NewCmdVersion reports the immutable edition identity compiled into the
-// binary. Root --version remains unchanged for compatibility.
-func NewCmdVersion(f *cmdutil.Factory) *cobra.Command {
-	opts := &options{factory: f}
-	cmd := &cobra.Command{
-		Use:    "version",
-		Short:  "Show version and edition information",
-		Hidden: hideVersionCommand(),
-		Args:   cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if opts.json {
-				output.PrintJson(opts.factory.IOStreams.Out, versionReport{
-					Version:      build.Version,
-					Edition:      build.Edition,
-					Capabilities: build.Capabilities(),
-				})
-				return nil
-			}
-			_, err := fmt.Fprintf(opts.factory.IOStreams.Out, "lark-cli version %s (%s)\n", build.Version, build.Edition)
-			if err != nil {
-				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write version output: %v", err).WithCause(err)
-			}
-			return nil
-		},
-	}
-	cmd.Flags().BoolVar(&opts.json, "json", false, "structured JSON output")
-	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.SetRisk(cmd, "read")
-	return cmd
-}

cmd/version/version_test.go

@@ -1,67 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package version
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-func TestVersionJSONReportsCompiledEdition(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, out, _, _ := cmdutil.TestFactory(t, nil)
-	cmd := NewCmdVersion(f)
-	cmd.SetArgs([]string{"--json"})
-	if err := cmd.ExecuteContext(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	var got struct {
-		Version      string   `json:"version"`
-		Edition      string   `json:"edition"`
-		Capabilities []string `json:"capabilities"`
-	}
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatal(err)
-	}
-	if got.Version != build.Version || got.Edition != build.Edition || !reflect.DeepEqual(got.Capabilities, build.Capabilities()) {
-		t.Fatalf("version output = %#v, want version=%q edition=%q", got, build.Version, build.Edition)
-	}
-}
-
-func TestVersionVisibilityPreservesStandardHelpSurface(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	cmd := NewCmdVersion(f)
-	wantHidden := build.Edition == "standard"
-	if cmd.Hidden != wantHidden {
-		t.Fatalf("version command hidden = %v, want %v for %s", cmd.Hidden, wantHidden, build.Edition)
-	}
-}
-
-type failingWriter struct{ err error }
-
-func (w failingWriter) Write([]byte) (int, error) { return 0, w.err }
-
-func TestVersionTextWriteFailureIsTyped(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	writeErr := errors.New("write failed")
-	f.IOStreams.Out = failingWriter{err: writeErr}
-
-	cmd := NewCmdVersion(f)
-	err := cmd.ExecuteContext(context.Background())
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeSDKError {
-		t.Fatalf("error = %#v, want internal/sdk_error", err)
-	}
-	if !errors.Is(err, writeErr) {
-		t.Fatalf("error does not preserve write failure: %v", err)
-	}
-}

cmd/version/visibility_extended.go

@@ -1,8 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build extended
-
-package version
-
-func hideVersionCommand() bool { return false }

cmd/version/visibility_standard.go

@@ -1,10 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build !extended
-
-package version
-
-// Standard keeps its historical help surface unchanged. The command remains
-// directly callable for release identity verification.
-func hideVersionCommand() bool { return true }

errs/ERROR_CONTRACT.md

@@ -62,8 +62,6 @@ Typed errors render to **stderr** as one JSON object per process exit:
 | `error.message` | informational | not safe to branch on |
 | `error.hint` | informational | actionable recovery guidance |
 | `error.log_id` | informational | upstream request id (server-side trace) |
-| `error.origin` | informational | Extended producer: `cli`, `credential_process`, `proxy`, or `lark`; omitted by Standard to preserve its existing envelope; consumers must tolerate absence and unknown future values |
-| `error.proxy_request_id` | informational | external credential platform trace id; never stored in `log_id` |
 | `error.retryable` | wire-stable | `true` when present; omitted when `false` |
 | `error.param` | per-Subtype-stable | single offending parameter (`ValidationError`); see **Validation parameters** |
 | `error.params` | per-Subtype-stable | per-parameter validation detail array (`ValidationError`); see **Validation parameters** |
@@ -106,7 +104,7 @@ already succeeded).
 | `config` | local config missing / unbound | 3 | `ConfigError` |
 | `network` | DNS, refused, timeout, transport | 4 | `NetworkError` |
 | `api` | server-side Lark error w/o specific bucket | 1 | `APIError` |
-| `policy` | security policy denial/challenge, including content safety | 6 | `SecurityPolicyError`, `ContentSafetyError` |
+| `policy` | content safety / security challenge | 6 | `SecurityPolicyError`, `ContentSafetyError` |
 | `internal` | SDK contract violation / decode failure | 5 | `InternalError` |
 | `confirmation` | high-risk action needs `--yes` | 10 | `ConfirmationRequiredError` |
 
@@ -274,7 +272,7 @@ legal for framework dynamic paths (e.g. classifier fanout) but the lint
 | Login required | `errs.NewAuthenticationError(errs.SubtypeTokenMissing, msg)` |
 | Token lacks scope | `errclass.BuildAPIError(resp, ctx)` |
 | Local config missing | `errs.NewConfigError(errs.SubtypeNotConfigured, msg)` |
-| Transport or external dependency failure | `errs.NewNetworkError(subtype, msg).WithCause(err)` (subtype: `timeout` / `tls` / `dns` / `server_error` / `transport` / `credential_source_unavailable` / `upstream_unavailable`) |
+| Transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTimeout, msg).WithCause(err)` (subtype: `timeout` / `tls` / `dns` / `server_error` / `transport`) |
 | Lark API error | `errclass.BuildAPIError(resp, ctx)` |
 | SDK / decode bug | `errs.NewInternalError(errs.SubtypeSDKError, msg).WithCause(err)` |
 | Policy block | `errs.NewSecurityPolicyError(subtype, msg).WithChallengeURL(url)` or `errs.NewContentSafetyError(subtype, msg).WithRules(...)` |
@@ -515,11 +513,7 @@ Rare; the existing structs cover the 9 Categories with room. If you must:
 `CheckProblemEmbed` enforces the `Problem` embed at lint time. New
 top-level wire fields are forbidden — per-Subtype data goes into the
 typed struct as a documented extension field, not into the envelope's
-top level. The external credential platform contract is the single explicit
-exception: `origin` and `proxy_request_id` are shared across several error
-categories and therefore live in `Problem`. Both fields are optional, and
-consumers must ignore them when absent or unknown. Any further shared field
-still requires an explicit contract revision and wire-format pin.
+top level.
 
 ## CI guards
 

errs/diagnostic_metadata.go

@@ -1,134 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errs
-
-import (
-	"encoding/json"
-)
-
-// DiagnosticMetadata carries optional producer diagnostics without changing
-// the field layout of Problem or any concrete typed error. Keeping this
-// metadata in a wrapper preserves source compatibility for callers that use
-// positional literals of the existing exported error structs.
-type DiagnosticMetadata struct {
-	Origin         string
-	ProxyRequestID string
-}
-
-type diagnosticMetadataWrapper struct {
-	err      error
-	typed    error
-	metadata DiagnosticMetadata
-}
-
-func (e *diagnosticMetadataWrapper) Error() string {
-	if e == nil || e.err == nil {
-		return ""
-	}
-	return e.err.Error()
-}
-
-func (e *diagnosticMetadataWrapper) Unwrap() error {
-	if e == nil {
-		return nil
-	}
-	return e.err
-}
-
-func (e *diagnosticMetadataWrapper) ProblemDetail() *Problem {
-	if e == nil {
-		return nil
-	}
-	problem, _ := ProblemOf(e.typed)
-	return problem
-}
-
-func (e *diagnosticMetadataWrapper) DiagnosticMetadata() DiagnosticMetadata {
-	if e == nil {
-		return DiagnosticMetadata{}
-	}
-	return e.metadata
-}
-
-// MarshalJSON preserves the concrete typed error's extension fields and adds
-// the optional diagnostics as sibling fields in the existing error object.
-func (e *diagnosticMetadataWrapper) MarshalJSON() ([]byte, error) {
-	raw, err := json.Marshal(e.typed)
-	if err != nil {
-		return nil, err
-	}
-
-	var object map[string]json.RawMessage
-	if err := json.Unmarshal(raw, &object); err != nil {
-		return nil, err
-	}
-	if e.metadata.Origin != "" {
-		origin, err := json.Marshal(e.metadata.Origin)
-		if err != nil {
-			return nil, err
-		}
-		object["origin"] = origin
-	}
-	if e.metadata.ProxyRequestID != "" {
-		requestID, err := json.Marshal(e.metadata.ProxyRequestID)
-		if err != nil {
-			return nil, err
-		}
-		object["proxy_request_id"] = requestID
-	}
-	return json.Marshal(object)
-}
-
-// WithDiagnosticMetadata attaches optional wire diagnostics to a typed error.
-// Empty metadata is a no-op. The returned wrapper still participates in
-// errors.Is/errors.As and TypedError routing through Unwrap and ProblemDetail.
-func WithDiagnosticMetadata(err error, metadata DiagnosticMetadata) error {
-	if err == nil || (metadata.Origin == "" && metadata.ProxyRequestID == "") {
-		return err
-	}
-
-	typed, ok := UnwrapTypedError(err)
-	if !ok {
-		return err
-	}
-	if existing, ok := diagnosticMetadataWrapperForProducer(typed); ok {
-		merged := existing.metadata
-		if metadata.Origin != "" {
-			merged.Origin = metadata.Origin
-		}
-		if metadata.ProxyRequestID != "" {
-			merged.ProxyRequestID = metadata.ProxyRequestID
-		}
-		return &diagnosticMetadataWrapper{err: err, typed: existing.typed, metadata: merged}
-	}
-	return &diagnosticMetadataWrapper{err: err, typed: typed, metadata: metadata}
-}
-
-// DiagnosticMetadataOf returns optional diagnostics attached to the first
-// typed producer in err's wrap chain. Metadata on a typed cause belongs to
-// that inner producer and must not be projected onto an outer typed error.
-func DiagnosticMetadataOf(err error) (DiagnosticMetadata, bool) {
-	typed, ok := UnwrapTypedError(err)
-	if !ok {
-		return DiagnosticMetadata{}, false
-	}
-	carrier, ok := diagnosticMetadataWrapperForProducer(typed)
-	if !ok {
-		return DiagnosticMetadata{}, false
-	}
-	metadata := carrier.DiagnosticMetadata()
-	if metadata.Origin == "" && metadata.ProxyRequestID == "" {
-		return DiagnosticMetadata{}, false
-	}
-	return metadata, true
-}
-
-// diagnosticMetadataWrapperForProducer deliberately checks only the selected
-// typed producer. errors.As must not be used here because it would traverse
-// into an inner typed cause and associate that cause's metadata with the outer
-// producer.
-func diagnosticMetadataWrapperForProducer(typed error) (*diagnosticMetadataWrapper, bool) {
-	wrapper, ok := typed.(*diagnosticMetadataWrapper) //nolint:errorlint // Exact producer identity is the invariant being enforced.
-	return wrapper, ok
-}

errs/diagnostic_metadata_test.go

@@ -1,118 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errs
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"testing"
-)
-
-func TestDiagnosticMetadataPreservesTypedErrorContract(t *testing.T) {
-	permission := NewPermissionError(SubtypeMissingScope, "missing scope").
-		WithMissingScopes("im:message")
-	wrapped := WithDiagnosticMetadata(permission, DiagnosticMetadata{
-		Origin:         "proxy",
-		ProxyRequestID: "proxy_req_1",
-	})
-
-	var gotPermission *PermissionError
-	if !errors.As(wrapped, &gotPermission) || gotPermission != permission {
-		t.Fatalf("errors.As() = %p, want original permission error %p", gotPermission, permission)
-	}
-	problem, ok := ProblemOf(wrapped)
-	if !ok || problem != &permission.Problem {
-		t.Fatalf("ProblemOf() = (%p, %v), want original Problem %p", problem, ok, &permission.Problem)
-	}
-	metadata, ok := DiagnosticMetadataOf(wrapped)
-	if !ok || metadata.Origin != "proxy" || metadata.ProxyRequestID != "proxy_req_1" {
-		t.Fatalf("DiagnosticMetadataOf() = (%#v, %v)", metadata, ok)
-	}
-
-	raw, err := json.Marshal(wrapped)
-	if err != nil {
-		t.Fatal(err)
-	}
-	var object map[string]any
-	if err := json.Unmarshal(raw, &object); err != nil {
-		t.Fatal(err)
-	}
-	if object["origin"] != "proxy" || object["proxy_request_id"] != "proxy_req_1" {
-		t.Fatalf("metadata missing from JSON: %s", raw)
-	}
-	missingScopes, ok := object["missing_scopes"].([]any)
-	if !ok || len(missingScopes) != 1 || missingScopes[0] != "im:message" {
-		t.Fatalf("typed extension fields missing from JSON: %s", raw)
-	}
-}
-
-func TestDiagnosticMetadataMergesWithoutMutatingExistingWrapper(t *testing.T) {
-	typed := NewNetworkError(SubtypeUpstreamUnavailable, "unavailable")
-	withOrigin := WithDiagnosticMetadata(typed, DiagnosticMetadata{Origin: "proxy"})
-	withRequestID := WithDiagnosticMetadata(withOrigin, DiagnosticMetadata{ProxyRequestID: "proxy_req_2"})
-
-	original, _ := DiagnosticMetadataOf(withOrigin)
-	if original.ProxyRequestID != "" {
-		t.Fatalf("existing wrapper was mutated: %#v", original)
-	}
-	merged, ok := DiagnosticMetadataOf(withRequestID)
-	if !ok || merged.Origin != "proxy" || merged.ProxyRequestID != "proxy_req_2" {
-		t.Fatalf("merged metadata = (%#v, %v)", merged, ok)
-	}
-}
-
-func TestDiagnosticMetadataPreservesOuterErrorContext(t *testing.T) {
-	cause := errors.New("transport failed")
-	typed := NewNetworkError(SubtypeNetworkTransport, "request failed").WithCause(cause)
-	outer := fmt.Errorf("fetch document: %w", typed)
-
-	wrapped := WithDiagnosticMetadata(outer, DiagnosticMetadata{Origin: "proxy"})
-	if got, want := wrapped.Error(), outer.Error(); got != want {
-		t.Fatalf("Error() = %q, want %q", got, want)
-	}
-	if !errors.Is(wrapped, cause) {
-		t.Fatal("metadata wrapper lost the original cause chain")
-	}
-	var gotTyped *NetworkError
-	if !errors.As(wrapped, &gotTyped) || gotTyped != typed {
-		t.Fatalf("errors.As() = %p, want original typed error %p", gotTyped, typed)
-	}
-}
-
-func TestDiagnosticMetadataDoesNotCrossTypedProducerBoundary(t *testing.T) {
-	inner := NewNetworkError(SubtypeUpstreamUnavailable, "proxy unavailable")
-	annotatedInner := WithDiagnosticMetadata(inner, DiagnosticMetadata{
-		Origin:         "proxy",
-		ProxyRequestID: "proxy_req_inner",
-	})
-	outer := NewInternalError(SubtypeUnknown, "business reclassified failure").
-		WithCause(annotatedInner)
-
-	if metadata, ok := DiagnosticMetadataOf(outer); ok {
-		t.Fatalf("outer typed producer inherited inner metadata: %#v", metadata)
-	}
-
-	wrapped := WithDiagnosticMetadata(outer, DiagnosticMetadata{Origin: "cli"})
-	problem, ok := ProblemOf(wrapped)
-	if !ok || problem != &outer.Problem {
-		t.Fatalf("ProblemOf() = (%p, %v), want outer Problem %p", problem, ok, &outer.Problem)
-	}
-	if problem.Category != CategoryInternal ||
-		problem.Subtype != SubtypeUnknown ||
-		problem.Message != "business reclassified failure" {
-		t.Fatalf("outer typed identity changed: %#v", problem)
-	}
-	metadata, ok := DiagnosticMetadataOf(wrapped)
-	if !ok || metadata.Origin != "cli" || metadata.ProxyRequestID != "" {
-		t.Fatalf("outer metadata = (%#v, %v), want cli without inner request id", metadata, ok)
-	}
-
-	innerMetadata, ok := DiagnosticMetadataOf(annotatedInner)
-	if !ok ||
-		innerMetadata.Origin != "proxy" ||
-		innerMetadata.ProxyRequestID != "proxy_req_inner" {
-		t.Fatalf("inner metadata was mutated: (%#v, %v)", innerMetadata, ok)
-	}
-}

errs/marshal_test.go

@@ -27,11 +27,7 @@ func TestPermissionError_MarshalJSON_HasAllWireFields(t *testing.T) {
 		Identity:      "user",
 		ConsoleURL:    "https://example",
 	}
-	withMetadata := WithDiagnosticMetadata(pe, DiagnosticMetadata{
-		Origin:         "proxy",
-		ProxyRequestID: "proxy_req_123",
-	})
-	b, err := json.Marshal(withMetadata)
+	b, err := json.Marshal(pe)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -43,8 +39,6 @@ func TestPermissionError_MarshalJSON_HasAllWireFields(t *testing.T) {
 		`"message":"x"`,
 		`"hint":"y"`,
 		`"log_id":"lg"`,
-		`"origin":"proxy"`,
-		`"proxy_request_id":"proxy_req_123"`,
 		`"missing_scopes":["docx:document"]`,
 		`"identity":"user"`,
 		`"console_url":"https://example"`,

errs/subtypes.go

@@ -48,13 +48,11 @@ const (
 
 // CategoryNetwork subtypes
 const (
-	SubtypeNetworkTransport            Subtype = "transport"                     // fallback when no more-specific network subtype matches
-	SubtypeNetworkTimeout              Subtype = "timeout"                       // dial / read timeout
-	SubtypeNetworkTLS                  Subtype = "tls"                           // TLS handshake / cert failure
-	SubtypeNetworkDNS                  Subtype = "dns"                           // DNS resolution failure
-	SubtypeNetworkServer               Subtype = "server_error"                  // upstream HTTP 5xx
-	SubtypeCredentialSourceUnavailable Subtype = "credential_source_unavailable" // external credential program or identity service is temporarily unavailable
-	SubtypeUpstreamUnavailable         Subtype = "upstream_unavailable"          // external proxy cannot reach the requested upstream service
+	SubtypeNetworkTransport Subtype = "transport"    // fallback when no more-specific network subtype matches
+	SubtypeNetworkTimeout   Subtype = "timeout"      // dial / read timeout
+	SubtypeNetworkTLS       Subtype = "tls"          // TLS handshake / cert failure
+	SubtypeNetworkDNS       Subtype = "dns"          // DNS resolution failure
+	SubtypeNetworkServer    Subtype = "server_error" // upstream HTTP 5xx
 )
 
 // CategoryAPI subtypes

go.mod

@@ -7,6 +7,8 @@ require (
 	github.com/bmatcuk/doublestar/v4 v4.10.0
 	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/facebookincubator/flog v0.0.0-20190930132826-d2511d0ce33c
+	github.com/facebookincubator/sks v0.0.0-20251112220143-6823f23937b4
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
@@ -27,7 +29,10 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 )
 
+require github.com/ebitengine/purego v0.10.1
+
 require (
+	github.com/StackExchange/wmi v1.2.1 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
@@ -42,12 +47,21 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/go-ole/go-ole v1.2.5 // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/btree v1.1.2 // indirect
+	github.com/google/certificate-transparency-go v1.1.8 // indirect
+	github.com/google/certtostore v1.0.6 // indirect
+	github.com/google/deck v0.0.0-20230104221208-105ad94aa8ae // indirect
+	github.com/google/go-attestation v0.5.1 // indirect
+	github.com/google/go-tpm v0.9.0 // indirect
+	github.com/google/go-tspi v0.3.0 // indirect
 	github.com/gopherjs/gopherjs v1.17.2 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/itchyny/timefmt-go v0.1.6 // indirect
+	github.com/jgoguen/go-utils v0.0.0-20200211015258-b42ad41486fd // indirect
 	github.com/jtolds/gls v4.20.0+incompatible // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -57,10 +71,12 @@ require (
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/peterbourgon/diskv v2.0.1+incompatible // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/smarty/assertions v1.15.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/crypto v0.31.0 // indirect
 )

go.sum

@@ -2,6 +2,8 @@ github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ
 github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/StackExchange/wmi v1.2.1 h1:VIkavFPXSjcnS+O8yTq7NI32k0R5Aj+v39y29VYDOSA=
+github.com/StackExchange/wmi v1.2.1/go.mod h1:rcmrprowKIVzvc+NUiLncP2uuArMWLCbu9SBzvHz7e8=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
@@ -50,14 +52,42 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/facebookincubator/flog v0.0.0-20190930132826-d2511d0ce33c h1:KqlxcP2nuOcMjudCvK0qME2K/aFBDH+xcvYv7HYQaYc=
+github.com/facebookincubator/flog v0.0.0-20190930132826-d2511d0ce33c/go.mod h1:QGzNH9ujQ2ZUr/CjDGZGWeDAVStrWNjHeEcjJL96Nuk=
+github.com/facebookincubator/sks v0.0.0-20251112220143-6823f23937b4 h1:z9oNXvtDZv73Rg8UjFhu+wMtDvGkhLm1NMTwZQ68gOM=
+github.com/facebookincubator/sks v0.0.0-20251112220143-6823f23937b4/go.mod h1:FEWpPBUpkMwxqAbprURvgWgdwjeGkge5QFDaZBsfRHQ=
+github.com/go-ole/go-ole v1.2.5 h1:t4MGB5xEDZvXI+0rMjjsfBsD7yAgp/s9ZDkL1JndXwY=
+github.com/go-ole/go-ole v1.2.5/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
 github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 github.com/gofrs/flock v0.8.1 h1:+gYjHKf32LDeiEEFhQaotPbLuUXjY5ZqxKgXy7n59aw=
 github.com/gofrs/flock v0.8.1/go.mod h1:F1TvTiK9OcQqauNUHlbJvyl9Qa1QvF/gOUDKA14jxHU=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/google/btree v1.0.0/go.mod h1:lNA+9X1NB3Zf8V7Ke586lFgjr2dZNuvo3lPJSGZ5JPQ=
+github.com/google/btree v1.1.2 h1:xf4v41cLI2Z6FxbKm+8Bu+m8ifhj15JuZ9sa0jZCMUU=
+github.com/google/btree v1.1.2/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
+github.com/google/certificate-transparency-go v1.0.21/go.mod h1:QeJfpSbVSfYc7RgB3gJFj9cbuQMMchQxrWXz8Ruopmg=
+github.com/google/certificate-transparency-go v1.1.8 h1:LGYKkgZF7satzgTak9R4yzfJXEeYVAjV6/EAEJOf1to=
+github.com/google/certificate-transparency-go v1.1.8/go.mod h1:bV/o8r0TBKRf1X//iiiSgWrvII4d7/8OiA+3vG26gI8=
+github.com/google/certtostore v1.0.6 h1:LlCIgyTvDxTlcncMPTSYZGo6lCsiHzO6Dy7ff6ltk/0=
+github.com/google/certtostore v1.0.6/go.mod h1:2N0ZPLkGvQWhYvXaiBGq02r71fnSLfq78VKIWQHr1wo=
+github.com/google/deck v0.0.0-20230104221208-105ad94aa8ae h1:Iy1Ad7L9qPtNAFJad+Ch2kwDXrcwu7QUBR0bfChjnEM=
+github.com/google/deck v0.0.0-20230104221208-105ad94aa8ae/go.mod h1:DoDv8G58DuLNZF0KysYn0bA/6ZWhmRW3fZE2VnGEH0w=
+github.com/google/go-attestation v0.5.1 h1:jqtOrLk5MNdliTKjPbIPrAaRKJaKW+0LIU2n/brJYms=
+github.com/google/go-attestation v0.5.1/go.mod h1:KqGatdUhg5kPFkokyzSBDxwSCFyRgIgtRkMp6c3lOBQ=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-tpm v0.9.0 h1:sQF6YqWMi+SCXpsmS3fd21oPy/vSddwZry4JnmltHVk=
+github.com/google/go-tpm v0.9.0/go.mod h1:FkNVkc6C+IsvDI9Jw1OveJmxGZUUaKxtrpOS47QWKfU=
+github.com/google/go-tpm-tools v0.4.2 h1:iyaCPKt2N5Rd0yz0G8ANa022SgCNZkMpp+db6QELtvI=
+github.com/google/go-tpm-tools v0.4.2/go.mod h1:fGUDZu4tw3V4hUVuFHmiYgRd0c58/IXivn9v3Ea/ck4=
+github.com/google/go-tspi v0.3.0 h1:ADtq8RKfP+jrTyIWIZDIYcKOMecRqNJFOew2IT0Inus=
+github.com/google/go-tspi v0.3.0/go.mod h1:xfMGI3G0PhxCdNVcYr1C4C+EizojDg/TXuX5by8CiHI=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gopherjs/gopherjs v1.17.2 h1:fQnZVsXk8uxXIStYb0N4bGk7jeyTalG/wsZjQ25dO0g=
@@ -70,6 +100,8 @@ github.com/itchyny/gojq v0.12.17 h1:8av8eGduDb5+rvEdaOO+zQUjA04MS0m3Ps8HiD+fceg=
 github.com/itchyny/gojq v0.12.17/go.mod h1:WBrEMkgAfAGO1LUcGOckBl5O726KPp+OlkKug0I/FEY=
 github.com/itchyny/timefmt-go v0.1.6 h1:ia3s54iciXDdzWzwaVKXZPbiXzxxnv1SPGFfM/myJ5Q=
 github.com/itchyny/timefmt-go v0.1.6/go.mod h1:RRDZYC5s9ErkjQvTvvU7keJjxUYzIISJGxm9/mAERQg=
+github.com/jgoguen/go-utils v0.0.0-20200211015258-b42ad41486fd h1:E3y4CkzAXArgOQAw9gzW0Exe7XQqF4MYH3rCYprAj+Q=
+github.com/jgoguen/go-utils v0.0.0-20200211015258-b42ad41486fd/go.mod h1:ayRB9iNq3dqzUb9oW2JkoVQkDBkJ88NJb66OH13CKSk=
 github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
 github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
@@ -97,6 +129,8 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/peterbourgon/diskv v2.0.1+incompatible h1:UBdAOUP5p4RWqPBg048CAvpKN+vxiaj6gdUUzhl4XmI=
+github.com/peterbourgon/diskv v2.0.1+incompatible/go.mod h1:uqqh8zWWbv1HBMNONnaR/tNboyR3/BZd58JJSHlUSCU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
@@ -137,6 +171,8 @@ go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
+golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
@@ -154,6 +190,7 @@ golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
 golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

internal/auth/app_registration.go

@@ -65,6 +65,7 @@ type AppRegistrationResponse struct {
 	VerificationUriComplete string
 	ExpiresIn               int
 	Interval                int
+	RequestedAuthMethod     string
 }
 
 // AppRegistrationResult is the result of a successful app registration poll.
@@ -72,6 +73,11 @@ type AppRegistrationResult struct {
 	ClientID     string
 	ClientSecret string
 	UserInfo     *AppRegUserInfo
+	// AuthMethods is the authoritative auth method(s) the app must use, as
+	// returned by the registration service after user/admin confirmation. It may
+	// differ from what the client requested, for example when selecting an
+	// existing client_secret app. Empty is accepted for compatible older servers.
+	AuthMethods []string
 }
 
 // AppRegUserInfo contains user info returned from app registration.
@@ -85,10 +91,81 @@ func appRegistrationEndpoint(brand core.LarkBrand) string {
 	return core.ResolveEndpoints(brand).Accounts + PathAppRegistration
 }
 
+// AppRegistrationInit is the response from the app registration init endpoint.
+type AppRegistrationInit struct {
+	Nonce                string
+	SupportedAuthMethods []string // e.g. ["client_secret", "private_key_jwt"]
+}
+
+// AppRegistrationBeginOptions parametrizes the registration begin request.
+// A zero value selects the legacy client_secret flow, preserving prior behavior.
+type AppRegistrationBeginOptions struct {
+	AuthMethod      string // "" => client_secret; core.AuthMethodPrivateKeyJWT
+	AuthAttestation string // private_key_jwt: the TEE-signed attestation JWT
+	RestoreAppID    string // when set, asks the server to re-register this existing app
+}
+
+// RequestAppRegistrationInit performs the init step of the registration flow,
+// returning a server nonce (to be embedded in a TEE-signed attestation JWT) and
+// the auth methods the server supports for this archetype.
+func RequestAppRegistrationInit(ctx context.Context, httpClient *http.Client) (*AppRegistrationInit, error) {
+	// Registration always begins against the Feishu accounts host (mirrors begin).
+	endpoint := appRegistrationEndpoint(registrationBootstrapBrand)
+	ctx, cancel := context.WithTimeout(ctx, beginRequestTimeout)
+	defer cancel()
+
+	form := url.Values{}
+	form.Set("action", "init")
+	form.Set("archetype", "PersonalAgent")
+
+	req, err := http.NewRequestWithContext(ctx, "POST", endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	logHTTPResponse(resp)
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("app registration init failed: read body: %w", err)
+	}
+
+	var data map[string]interface{}
+	if err := json.Unmarshal(body, &data); err != nil {
+		return nil, fmt.Errorf("app registration init failed: HTTP %d – response not JSON", resp.StatusCode)
+	}
+
+	if _, hasError := data["error"]; resp.StatusCode >= 400 || hasError {
+		msg := getStr(data, "error_description")
+		if msg == "" {
+			msg = getStr(data, "error")
+		}
+		if msg == "" {
+			msg = "Unknown error"
+		}
+		return nil, fmt.Errorf("app registration init failed: %s", msg)
+	}
+
+	out := &AppRegistrationInit{
+		Nonce:                getStr(data, "nonce"),
+		SupportedAuthMethods: parseAuthMethods(data["supported_auth_methods"]),
+	}
+	if out.Nonce == "" {
+		return nil, fmt.Errorf("app registration init failed: server returned no nonce")
+	}
+	return out, nil
+}
+
 // RequestAppRegistration initiates the device flow. The registration protocol
 // always bootstraps on Feishu; brand selects the user-facing verification host.
 // The request is bounded by ctx and a begin timeout.
-func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, errOut io.Writer) (*AppRegistrationResponse, error) {
+func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, opts AppRegistrationBeginOptions, errOut io.Writer) (*AppRegistrationResponse, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -99,11 +176,25 @@ func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand
 	ep := core.ResolveEndpoints(brand)
 	endpoint := appRegistrationEndpoint(registrationBootstrapBrand)
 
+	authMethod := opts.AuthMethod
+	if authMethod == "" {
+		authMethod = core.AuthMethodClientSecret
+	}
+
 	form := url.Values{}
 	form.Set("action", "begin")
 	form.Set("archetype", "PersonalAgent")
-	form.Set("auth_method", "client_secret")
+	form.Set("auth_method", authMethod)
 	form.Set("request_user_info", "open_id tenant_brand")
+	if opts.AuthAttestation != "" {
+		form.Set("auth_attestation", opts.AuthAttestation)
+	}
+	// Restore flow: the registration service accepts the existing OAuth client
+	// identifier under client_id. The launcher URL still uses app_id; these are
+	// separate contracts and must not be changed together.
+	if opts.RestoreAppID != "" {
+		form.Set("client_id", opts.RestoreAppID)
+	}
 
 	req, err := http.NewRequestWithContext(ctx, "POST", endpoint, strings.NewReader(form.Encode()))
 	if err != nil {
@@ -156,7 +247,24 @@ func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand
 
 	userCode := getStr(data, "user_code")
 	verificationUri := getStr(data, "verification_uri")
-	verificationUriComplete := fmt.Sprintf("%s/page/cli?user_code=%s", ep.Open, userCode)
+	// Prefer the server-provided complete URL (currently /page/launcher); fall
+	// back to building it from verification_uri, then to /page/launcher. The old
+	// hard-coded /page/cli is stale — the server now returns /page/launcher.
+	verificationUriComplete := getStr(data, "verification_uri_complete")
+	if verificationUriComplete == "" {
+		base := verificationUri
+		if base == "" {
+			base = ep.Open + "/page/launcher"
+		}
+		// The server may return verification_uri with its own query (e.g.
+		// app_id when registering against an existing app), so join with
+		// the same ?/& logic as BuildVerificationURL.
+		sep := "?"
+		if strings.Contains(base, "?") {
+			sep = "&"
+		}
+		verificationUriComplete = base + sep + "user_code=" + url.QueryEscape(userCode)
+	}
 
 	return &AppRegistrationResponse{
 		DeviceCode:              deviceCode,
@@ -165,18 +273,91 @@ func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand
 		VerificationUriComplete: verificationUriComplete,
 		ExpiresIn:               expiresIn,
 		Interval:                interval,
+		RequestedAuthMethod:     authMethod,
 	}, nil
 }
 
+// parseAuthMethods normalizes the poll response `auth_method` field, which the
+// server returns as a JSON array of strings (e.g. ["private_key_jwt"]) — or, on
+// some variants, a single space-separated string.
+func parseAuthMethods(v interface{}) []string {
+	switch t := v.(type) {
+	case []interface{}:
+		out := make([]string, 0, len(t))
+		for _, m := range t {
+			if s, ok := m.(string); ok && s != "" {
+				out = append(out, s)
+			}
+		}
+		return out
+	case string:
+		return strings.Fields(t)
+	default:
+		return nil
+	}
+}
+
+func containsAuthMethod(methods []string, target string) bool {
+	for _, method := range methods {
+		if method == target {
+			return true
+		}
+	}
+	return false
+}
+
+func registrationResultComplete(result *AppRegistrationResult, requestedAuthMethod string) bool {
+	if result.ClientID == "" {
+		return false
+	}
+	if result.ClientSecret != "" {
+		return true
+	}
+	if len(result.AuthMethods) > 0 {
+		return containsAuthMethod(result.AuthMethods, core.AuthMethodPrivateKeyJWT)
+	}
+	// Older servers may omit auth_method. In that case only a begin request
+	// explicitly made as private_key_jwt may complete without a client secret.
+	return requestedAuthMethod == core.AuthMethodPrivateKeyJWT
+}
+
 // BuildVerificationURL appends CLI tracking parameters to the verification URL.
-func BuildVerificationURL(baseURL, cliVersion string) string {
+// When targetAppID is non-empty, it is also included so the launcher can lock
+// authorization to that existing app.
+func BuildVerificationURL(baseURL, cliVersion string, targetAppID ...string) string {
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		return appendVerificationURLFallback(baseURL, cliVersion, targetAppID...)
+	}
+	q := u.Query()
+	if q.Get("lpv") == "" {
+		q.Set("lpv", cliVersion)
+	}
+	if q.Get("ocv") == "" {
+		q.Set("ocv", cliVersion)
+	}
+	if q.Get("from") == "" {
+		q.Set("from", "cli")
+	}
+	if len(targetAppID) > 0 && targetAppID[0] != "" && q.Get("app_id") == "" {
+		q.Set("app_id", targetAppID[0])
+	}
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+func appendVerificationURLFallback(baseURL, cliVersion string, targetAppID ...string) string {
 	sep := "&"
 	if !strings.Contains(baseURL, "?") {
 		sep = "?"
 	}
-	return baseURL + sep + "lpv=" + url.QueryEscape(cliVersion) +
+	out := baseURL + sep + "lpv=" + url.QueryEscape(cliVersion) +
 		"&ocv=" + url.QueryEscape(cliVersion) +
 		"&from=cli"
+	if len(targetAppID) > 0 && targetAppID[0] != "" && !strings.Contains(baseURL, "app_id=") {
+		out += "&app_id=" + url.QueryEscape(targetAppID[0])
+	}
+	return out
 }
 
 // pollOnce performs one ctx-bound poll request and decodes the payload.
@@ -273,6 +454,7 @@ func RegisterAppWithDiscovery(ctx context.Context, httpClient *http.Client, resp
 			result := &AppRegistrationResult{
 				ClientID:     getStr(data, "client_id"),
 				ClientSecret: getStr(data, "client_secret"),
+				AuthMethods:  parseAuthMethods(data["auth_method"]),
 			}
 			if userInfoRaw, ok := data["user_info"].(map[string]interface{}); ok {
 				result.UserInfo = &AppRegUserInfo{
@@ -281,7 +463,7 @@ func RegisterAppWithDiscovery(ctx context.Context, httpClient *http.Client, resp
 				}
 			}
 
-			if result.ClientID != "" && result.ClientSecret != "" {
+			if registrationResultComplete(result, resp.RequestedAuthMethod) {
 				// The issuing domain is authoritative; a contradictory final
 				// tenant report is a protocol violation, not a brand override.
 				if result.UserInfo != nil && result.UserInfo.TenantBrand != "" &&

internal/auth/app_registration_test.go

@@ -8,6 +8,8 @@ import (
 	"errors"
 	"io"
 	"net/http"
+	"net/url"
+	"slices"
 	"strings"
 	"testing"
 	"time"
@@ -30,10 +32,14 @@ func jsonResponse(body string) *http.Response {
 func Test_BuildVerificationURL(t *testing.T) {
 	t.Run("URL不含问号则添加?分隔符", func(t *testing.T) {
 		result := BuildVerificationURL("https://example.com/verify", "1.0.0")
+		got, err := url.Parse(result)
+		if err != nil {
+			t.Fatal(err)
+		}
 		convey.Convey("should add ? separator", t, func() {
-			convey.So(result, convey.ShouldContainSubstring, "?lpv=1.0.0")
-			convey.So(result, convey.ShouldContainSubstring, "&ocv=1.0.0")
-			convey.So(result, convey.ShouldContainSubstring, "&from=cli")
+			convey.So(got.Query().Get("lpv"), convey.ShouldEqual, "1.0.0")
+			convey.So(got.Query().Get("ocv"), convey.ShouldEqual, "1.0.0")
+			convey.So(got.Query().Get("from"), convey.ShouldEqual, "cli")
 			convey.So(result, convey.ShouldStartWith, "https://example.com/verify?")
 		})
 	})
@@ -47,6 +53,237 @@ func Test_BuildVerificationURL(t *testing.T) {
 			convey.So(result, convey.ShouldNotContainSubstring, "?lpv=")
 		})
 	})
+
+	t.Run("指定已有应用时添加app_id", func(t *testing.T) {
+		result := BuildVerificationURL("https://example.com/verify?user_code=abc", "2.0.0", "cli_existing")
+		got, err := url.Parse(result)
+		if err != nil {
+			t.Fatal(err)
+		}
+		convey.Convey("should include target app_id", t, func() {
+			convey.So(got.Query().Get("app_id"), convey.ShouldEqual, "cli_existing")
+			convey.So(got.Query().Get("client_id"), convey.ShouldEqual, "")
+			convey.So(got.Query().Get("lpv"), convey.ShouldEqual, "2.0.0")
+		})
+	})
+
+	t.Run("服务端已返回app_id时不覆盖", func(t *testing.T) {
+		result := BuildVerificationURL("https://example.com/verify?app_id=cli_server&user_code=abc", "2.0.0", "cli_existing")
+		got, err := url.Parse(result)
+		if err != nil {
+			t.Fatal(err)
+		}
+		convey.Convey("should keep server app_id", t, func() {
+			convey.So(got.Query().Get("app_id"), convey.ShouldEqual, "cli_server")
+		})
+	})
+}
+
+// captureClient returns an http.Client that records the last request's form body
+// and replies with the given JSON payload.
+func captureClient(gotBody *url.Values, respJSON string) *http.Client {
+	return &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			if req.Body != nil {
+				b, _ := io.ReadAll(req.Body)
+				v, _ := url.ParseQuery(string(b))
+				*gotBody = v
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     make(http.Header),
+				Body:       io.NopCloser(strings.NewReader(respJSON)),
+			}, nil
+		}),
+	}
+}
+
+func TestRequestAppRegistrationInit_ParsesNonceAndMethods(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"nonce":"n-123","supported_auth_methods":["client_secret","private_key_jwt"]}`)
+
+	out, err := RequestAppRegistrationInit(context.Background(), hc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Nonce != "n-123" {
+		t.Errorf("nonce = %q, want n-123", out.Nonce)
+	}
+	if len(out.SupportedAuthMethods) != 2 || out.SupportedAuthMethods[1] != "private_key_jwt" {
+		t.Errorf("methods = %v", out.SupportedAuthMethods)
+	}
+	if body.Get("action") != "init" {
+		t.Errorf("action = %q, want init", body.Get("action"))
+	}
+}
+
+func TestRequestAppRegistrationInit_ErrorOnMissingNonce(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"supported_auth_methods":["client_secret"]}`)
+	if _, err := RequestAppRegistrationInit(context.Background(), hc); err == nil {
+		t.Fatal("expected error when server returns no nonce")
+	}
+}
+
+// TestRequestAppRegistrationInit_EmptySupportedAuthMethods covers the older-server
+// back-compat path: an empty supported_auth_methods array parses to an empty
+// slice, so the init guard in cmd/config/init_interactive.go
+// (`len(SupportedAuthMethods) > 0 && !slices.Contains(...)`) stays false and does
+// NOT reject the requested private_key_jwt. This aligns with
+// resolveFinalAuthMethod(nil/[], private_key_jwt) == private_key_jwt
+// (see cmd/config TestResolveFinalAuthMethod).
+func TestRequestAppRegistrationInit_EmptySupportedAuthMethods(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"nonce":"n-1","supported_auth_methods":[]}`)
+
+	out, err := RequestAppRegistrationInit(context.Background(), hc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Nonce != "n-1" {
+		t.Errorf("nonce = %q, want n-1", out.Nonce)
+	}
+	if len(out.SupportedAuthMethods) != 0 {
+		t.Errorf("SupportedAuthMethods = %v, want empty", out.SupportedAuthMethods)
+	}
+	// Reproduce the init guard expression on the real parsed result: an empty
+	// slice must NOT reject private_key_jwt.
+	rejected := len(out.SupportedAuthMethods) > 0 &&
+		!slices.Contains(out.SupportedAuthMethods, core.AuthMethodPrivateKeyJWT)
+	if rejected {
+		t.Error("empty SupportedAuthMethods must allow private_key_jwt (older-server back-compat)")
+	}
+}
+
+const beginRespJSON = `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`
+
+func TestRequestAppRegistration_BeginDefaultsToClientSecret(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	if _, err := RequestAppRegistration(context.Background(), hc, core.BrandFeishu, AppRegistrationBeginOptions{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("action") != "begin" {
+		t.Errorf("action = %q", body.Get("action"))
+	}
+	if body.Get("auth_method") != "client_secret" {
+		t.Errorf("auth_method = %q, want client_secret (default)", body.Get("auth_method"))
+	}
+	if body.Has("auth_attestation") {
+		t.Errorf("auth_attestation should be absent for client_secret, got %q", body.Get("auth_attestation"))
+	}
+	// Normal (non-restore) begin must NOT carry client_id.
+	if body.Has("client_id") {
+		t.Errorf("client_id should be absent when RestoreAppID is empty, got %q", body.Get("client_id"))
+	}
+}
+
+// TestRequestAppRegistration_BeginRestoreAppID verifies the restore flow sends the
+// existing app id on begin so the server re-registers that app.
+func TestRequestAppRegistration_BeginRestoreAppID(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	opts := AppRegistrationBeginOptions{RestoreAppID: "cli_restore_me"}
+	if _, err := RequestAppRegistration(context.Background(), hc, core.BrandFeishu, opts, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("action") != "begin" {
+		t.Errorf("action = %q, want begin", body.Get("action"))
+	}
+	if body.Get("client_id") != "cli_restore_me" {
+		t.Errorf("client_id = %q, want cli_restore_me", body.Get("client_id"))
+	}
+	if body.Has("app_id") {
+		t.Errorf("begin form app_id must be absent, got %q", body.Get("app_id"))
+	}
+}
+
+func TestRequestAppRegistration_VerificationURICompleteFallback(t *testing.T) {
+	cases := []struct {
+		name string
+		resp string
+		want string
+	}{
+		{
+			name: "bare verification_uri",
+			resp: `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`,
+			want: "https://example/verify?user_code=uc",
+		},
+		{
+			name: "verification_uri with existing query",
+			resp: `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify?app_id=cli_x","expires_in":300,"interval":5}`,
+			want: "https://example/verify?app_id=cli_x&user_code=uc",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var body url.Values
+			hc := captureClient(&body, tc.resp)
+			got, err := RequestAppRegistration(context.Background(), hc, core.BrandFeishu, AppRegistrationBeginOptions{}, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.VerificationUriComplete != tc.want {
+				t.Errorf("VerificationUriComplete = %q, want %q", got.VerificationUriComplete, tc.want)
+			}
+		})
+	}
+}
+
+func TestParseAuthMethods(t *testing.T) {
+	if got := parseAuthMethods([]interface{}{"private_key_jwt", "client_secret"}); len(got) != 2 || got[0] != "private_key_jwt" {
+		t.Errorf("array form = %v", got)
+	}
+	if got := parseAuthMethods("client_secret private_key_jwt"); len(got) != 2 || got[1] != "private_key_jwt" {
+		t.Errorf("string form = %v", got)
+	}
+	if got := parseAuthMethods(nil); got != nil {
+		t.Errorf("nil form = %v, want nil", got)
+	}
+}
+
+func TestRequestAppRegistration_BeginPrivateKeyJWT(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	opts := AppRegistrationBeginOptions{
+		AuthMethod:      core.AuthMethodPrivateKeyJWT,
+		AuthAttestation: "header.claims.sig",
+	}
+	if _, err := RequestAppRegistration(context.Background(), hc, core.BrandFeishu, opts, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("auth_method") != "private_key_jwt" {
+		t.Errorf("auth_method = %q, want private_key_jwt", body.Get("auth_method"))
+	}
+	if body.Get("auth_attestation") != "header.claims.sig" {
+		t.Errorf("auth_attestation = %q", body.Get("auth_attestation"))
+	}
+}
+
+func TestRequestAppRegistration_BeginPrivateKeyJWTExistingAppID(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	opts := AppRegistrationBeginOptions{
+		AuthMethod:      core.AuthMethodPrivateKeyJWT,
+		AuthAttestation: "header.claims.sig",
+		RestoreAppID:    "cli_existing",
+	}
+	if _, err := RequestAppRegistration(context.Background(), hc, core.BrandFeishu, opts, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("auth_method") != "private_key_jwt" {
+		t.Errorf("auth_method = %q, want private_key_jwt", body.Get("auth_method"))
+	}
+	if body.Get("auth_attestation") != "header.claims.sig" {
+		t.Errorf("auth_attestation = %q", body.Get("auth_attestation"))
+	}
+	if body.Get("client_id") != "cli_existing" {
+		t.Errorf("client_id = %q, want cli_existing", body.Get("client_id"))
+	}
 }
 
 func TestAppRegistrationEndpoint(t *testing.T) {
@@ -80,11 +317,11 @@ func TestRequestAppRegistration_UsesFeishuBootstrapAndConfiguredVerificationBran
 				}
 				return jsonResponse(`{"device_code":"d","user_code":"TEST-CODE","expire_in":60,"interval":5}`), nil
 			})}
-			resp, err := RequestAppRegistration(context.Background(), client, c.brand, io.Discard)
+			resp, err := RequestAppRegistration(context.Background(), client, c.brand, AppRegistrationBeginOptions{}, io.Discard)
 			if err != nil {
 				t.Fatalf("RequestAppRegistration(%q) error = %v", c.brand, err)
 			}
-			if !strings.HasPrefix(resp.VerificationUriComplete, "https://"+c.verificationHost+"/page/cli?") {
+			if !strings.HasPrefix(resp.VerificationUriComplete, "https://"+c.verificationHost+"/page/launcher?") {
 				t.Errorf("verification URL = %q, want host %q", resp.VerificationUriComplete, c.verificationHost)
 			}
 		})
@@ -115,11 +352,11 @@ func TestRegisterAppWithDiscovery_LarkFlowUsesProtocolBootstrap(t *testing.T) {
 		t.Errorf("unexpected host polled: %s", r.URL.Host)
 		return jsonResponse(`{}`), nil
 	})}
-	resp, err := RequestAppRegistration(context.Background(), client, core.BrandLark, io.Discard)
+	resp, err := RequestAppRegistration(context.Background(), client, core.BrandLark, AppRegistrationBeginOptions{}, io.Discard)
 	if err != nil {
 		t.Fatalf("RequestAppRegistration error = %v", err)
 	}
-	if got, want := resp.VerificationUriComplete, "https://open.larksuite.com/page/cli?user_code=TEST-CODE"; got != want {
+	if got, want := resp.VerificationUriComplete, "https://open.larksuite.com/page/launcher?user_code=TEST-CODE"; got != want {
 		t.Errorf("verification URL = %q, want %q", got, want)
 	}
 
@@ -219,6 +456,51 @@ func TestRegisterAppWithDiscovery_PollsUntilCredentials(t *testing.T) {
 	}
 }
 
+func TestRegisterAppWithDiscovery_KeylessCompletesWithoutSecret(t *testing.T) {
+	tests := []struct {
+		name                string
+		response            string
+		requestedAuthMethod string
+	}{
+		{
+			name:     "server explicitly returns private_key_jwt",
+			response: `{"client_id":"cli_keyless","auth_method":["private_key_jwt"]}`,
+		},
+		{
+			name:                "older server omits auth_method for a keyless begin",
+			response:            `{"client_id":"cli_keyless"}`,
+			requestedAuthMethod: core.AuthMethodPrivateKeyJWT,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			polls := 0
+			client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				polls++
+				return jsonResponse(tt.response), nil
+			})}
+			resp := &AppRegistrationResponse{
+				DeviceCode:          "device",
+				Interval:            0,
+				ExpiresIn:           5,
+				RequestedAuthMethod: tt.requestedAuthMethod,
+			}
+
+			result, _, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+			if err != nil {
+				t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
+			}
+			if polls != 1 {
+				t.Errorf("polls = %d, want 1", polls)
+			}
+			if result.ClientID != "cli_keyless" || result.ClientSecret != "" {
+				t.Errorf("result = (%q, %q), want (cli_keyless, empty secret)", result.ClientID, result.ClientSecret)
+			}
+		})
+	}
+}
+
 // Neither the first poll nor the cross-brand switch waits out the interval
 // (a 5s interval would blow the elapsed bound).
 func TestRegisterAppWithDiscovery_ImmediateFirstPollAndSwitch(t *testing.T) {
@@ -286,7 +568,7 @@ func TestRequestAppRegistration_ProtocolFields(t *testing.T) {
 	}
 
 	resp, err := RequestAppRegistration(context.Background(),
-		serve(`{"device_code":"d","expire_in":60,"interval":3}`), core.BrandFeishu, io.Discard)
+		serve(`{"device_code":"d","expire_in":60,"interval":3}`), core.BrandFeishu, AppRegistrationBeginOptions{}, io.Discard)
 	if err != nil {
 		t.Fatalf("begin error = %v", err)
 	}
@@ -295,7 +577,7 @@ func TestRequestAppRegistration_ProtocolFields(t *testing.T) {
 	}
 
 	resp, err = RequestAppRegistration(context.Background(),
-		serve(`{"device_code":"d","expires_in":45}`), core.BrandFeishu, io.Discard)
+		serve(`{"device_code":"d","expires_in":45}`), core.BrandFeishu, AppRegistrationBeginOptions{}, io.Discard)
 	if err != nil {
 		t.Fatalf("legacy begin error = %v", err)
 	}
@@ -304,7 +586,7 @@ func TestRequestAppRegistration_ProtocolFields(t *testing.T) {
 	}
 
 	resp, err = RequestAppRegistration(context.Background(),
-		serve(`{"device_code":"d","interval":0}`), core.BrandFeishu, io.Discard)
+		serve(`{"device_code":"d","interval":0}`), core.BrandFeishu, AppRegistrationBeginOptions{}, io.Discard)
 	if err != nil {
 		t.Fatalf("defaults begin error = %v", err)
 	}
@@ -313,7 +595,7 @@ func TestRequestAppRegistration_ProtocolFields(t *testing.T) {
 	}
 
 	if _, err := RequestAppRegistration(context.Background(),
-		serve(`{"interval":5}`), core.BrandFeishu, io.Discard); err == nil {
+		serve(`{"interval":5}`), core.BrandFeishu, AppRegistrationBeginOptions{}, io.Discard); err == nil {
 		t.Error("missing device_code: expected error, got nil")
 	}
 }
@@ -394,7 +676,7 @@ func TestRequestAppRegistration_BodyReadCancelKeepsCause(t *testing.T) {
 			Header:     make(http.Header),
 		}, nil
 	})}
-	_, err := RequestAppRegistration(context.Background(), client, core.BrandFeishu, io.Discard)
+	_, err := RequestAppRegistration(context.Background(), client, core.BrandFeishu, AppRegistrationBeginOptions{}, io.Discard)
 	if !errors.Is(err, context.Canceled) {
 		t.Errorf("err = %v, want a context.Canceled cause", err)
 	}

internal/auth/client_auth.go

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"time"
+
+	"github.com/larksuite/cli/internal/auth/jwt"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keylesshelper"
+	"github.com/larksuite/cli/internal/keylessprovider"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// ClientAuth describes how to authenticate the OAuth client at the token
+// endpoint: with a client_secret (default) or a TEE-signed client_assertion
+// (private_key_jwt).
+type ClientAuth struct {
+	AppID       string
+	AppSecret   string
+	AuthMethod  string // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	Signer      keysigner.Signer
+	KeyLabel    string
+	KeyProvider string
+
+	// externalSigner is a verified provider snapshot prepared once for a
+	// multi-request operation (for example a device-flow poll loop). The helper
+	// still re-verifies its binary and mints a fresh assertion on every call.
+	externalSigner clientAssertionSigner
+}
+
+type clientAssertionSigner interface {
+	SignClientAssertion(context.Context, string, string, string) (string, string, error)
+}
+
+var resolveExternalAssertionSigner = func(ctx context.Context, provider string) (clientAssertionSigner, error) {
+	return keylessprovider.Resolve(ctx, provider)
+}
+
+// ClientAuthFromConfig builds a ClientAuth from resolved config, picking up the
+// active key signer for private_key_jwt apps.
+func ClientAuthFromConfig(cfg *core.CliConfig) ClientAuth {
+	if cfg == nil {
+		return ClientAuth{}
+	}
+	return ClientAuth{
+		AppID:       cfg.AppID,
+		AppSecret:   cfg.AppSecret,
+		AuthMethod:  cfg.AuthMethod,
+		KeyLabel:    cfg.KeyLabel,
+		KeyProvider: cfg.KeyProvider,
+		Signer:      keysigner.Active(),
+	}
+}
+
+func (c ClientAuth) isPrivateKeyJWT() bool { return c.AuthMethod == core.AuthMethodPrivateKeyJWT }
+
+// ResolveSigner prepares the external private_key_jwt signer for reuse within
+// one operation and returns the prepared copy. Built-in signers and
+// client_secret authentication need no provider discovery. Keeping the
+// resolved helper on ClientAuth separates expensive provider discovery from
+// assertion minting: callers may reuse the returned value, while every call to
+// applyClientAssertion still asks the signer for a fresh assertion.
+func (c ClientAuth) ResolveSigner(ctx context.Context) (ClientAuth, error) {
+	if !c.isPrivateKeyJWT() || c.KeyProvider == "" || c.externalSigner != nil {
+		return c, nil
+	}
+	helper, err := resolveExternalAssertionSigner(ctx, c.KeyProvider)
+	if err != nil {
+		return c, err
+	}
+	if helper == nil {
+		return c, fmt.Errorf("private_key_jwt provider %q resolved without a signer", c.KeyProvider)
+	}
+	c.externalSigner = helper
+	return c, nil
+}
+
+// SignClientAssertion signs with a resolved external helper when present,
+// otherwise with the platform signer.
+func SignClientAssertion(ctx context.Context, signer keysigner.Signer, helper *keylesshelper.Command, keyLabel, clientID, audience string) (string, string, error) {
+	if helper != nil {
+		return helper.SignClientAssertion(ctx, keyLabel, clientID, audience)
+	}
+	assertion, err := jwt.SignClientAssertion(ctx, signer, keysigner.KeyRef{Label: keyLabel}, clientID, audience, time.Now())
+	return jwt.ClientAssertionType, assertion, err
+}
+
+// applyClientAssertion adds client_assertion(+type) to a token-endpoint form for
+// private_key_jwt and returns true. For client_secret it returns false, leaving
+// the caller to apply its own secret-based authentication. audience is the token
+// endpoint URL (the assertion's aud claim).
+func (c ClientAuth) applyClientAssertion(ctx context.Context, form url.Values, audience string) (bool, error) {
+	if !c.isPrivateKeyJWT() {
+		return false, nil
+	}
+	var err error
+	if c.KeyProvider != "" {
+		c, err = c.ResolveSigner(ctx)
+		if err != nil {
+			return false, err
+		}
+	}
+	helper := c.externalSigner
+	if helper == nil && c.Signer == nil {
+		return false, fmt.Errorf("private_key_jwt requires a key signer, but none is available on this build")
+	}
+	var assertionType, assertion string
+	if helper != nil {
+		assertionType, assertion, err = helper.SignClientAssertion(ctx, c.KeyLabel, c.AppID, audience)
+	} else {
+		assertionType, assertion, err = SignClientAssertion(ctx, c.Signer, nil, c.KeyLabel, c.AppID, audience)
+	}
+	if err != nil {
+		return false, err
+	}
+	form.Set("client_assertion_type", assertionType)
+	form.Set("client_assertion", assertion)
+	return true, nil
+}

internal/auth/client_auth_test.go

@@ -0,0 +1,227 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"fmt"
+	"net/url"
+	"testing"
+
+	"github.com/larksuite/cli/internal/auth/jwt"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// fakeAuthSigner is a real in-memory ECDSA P-256 signer for client-auth tests.
+type fakeAuthSigner struct{ key *ecdsa.PrivateKey }
+
+type fakeExternalAssertionSigner struct {
+	keyRef, clientID, audience string
+	calls                      int
+}
+
+func (f *fakeExternalAssertionSigner) SignClientAssertion(_ context.Context, keyRef, clientID, audience string) (string, string, error) {
+	f.keyRef, f.clientID, f.audience = keyRef, clientID, audience
+	f.calls++
+	return jwt.ClientAssertionType, fmt.Sprintf("external.jwt.%d", f.calls), nil
+}
+
+func newFakeAuthSigner(t *testing.T) *fakeAuthSigner {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &fakeAuthSigner{key: k}
+}
+
+func (f *fakeAuthSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeAuthSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeAuthSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(rand.Reader, f.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
+func TestClientAuth_applyClientAssertion_ClientSecret(t *testing.T) {
+	ca := ClientAuth{AppID: "cli_a", AppSecret: "test-secret"} // AuthMethod "" => client_secret
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "https://aud/token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if used {
+		t.Error("client_secret must not produce a client_assertion")
+	}
+	if form.Has("client_assertion") || form.Has("client_assertion_type") {
+		t.Errorf("form should be untouched, got %v", form)
+	}
+}
+
+func TestClientAuth_applyClientAssertion_PrivateKeyJWT(t *testing.T) {
+	ca := ClientAuth{
+		AppID:      "cli_a",
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		Signer:     newFakeAuthSigner(t),
+		KeyLabel:   "k",
+	}
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "https://accounts.feishu.cn/open-apis/authen/v2/oauth/token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !used {
+		t.Fatal("expected client_assertion to be applied")
+	}
+	if form.Get("client_assertion_type") != jwt.ClientAssertionType {
+		t.Errorf("client_assertion_type = %q", form.Get("client_assertion_type"))
+	}
+	if form.Get("client_assertion") == "" {
+		t.Error("client_assertion is empty")
+	}
+	if form.Has("client_secret") {
+		t.Error("client_secret must NOT be present for private_key_jwt")
+	}
+}
+
+func TestClientAuth_applyClientAssertion_NilSigner(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT} // Signer nil
+	if _, err := ca.applyClientAssertion(context.Background(), url.Values{}, "aud"); err == nil {
+		t.Fatal("expected error when private_key_jwt has no signer")
+	}
+}
+
+func TestClientAuth_applyClientAssertion_UnknownProviderFailsClosed(t *testing.T) {
+	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT, Signer: newFakeAuthSigner(t), KeyLabel: "k", KeyProvider: "evil.provider"}
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "aud")
+	if err == nil || used || form.Has("client_assertion") {
+		t.Fatalf("unknown provider must fail closed: used=%v form=%v err=%v", used, form, err)
+	}
+}
+
+func TestClientAuth_applyClientAssertion_NilExternalProviderDoesNotFallback(t *testing.T) {
+	previous := resolveExternalAssertionSigner
+	resolveExternalAssertionSigner = func(context.Context, string) (clientAssertionSigner, error) {
+		return nil, nil
+	}
+	t.Cleanup(func() { resolveExternalAssertionSigner = previous })
+
+	ca := ClientAuth{
+		AppID: "cli_a", AppSecret: "must-not-send", AuthMethod: core.AuthMethodPrivateKeyJWT,
+		Signer: newFakeAuthSigner(t), KeyLabel: "k", KeyProvider: core.KeylessProviderLarkSuite,
+	}
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "aud")
+	if err == nil || used || form.Has("client_assertion") || form.Has("client_secret") {
+		t.Fatalf("nil external provider must fail closed: used=%v form=%v err=%v", used, form, err)
+	}
+}
+
+func TestClientAuth_applyClientAssertion_ExplicitProviderDoesNotUseBuiltinOrSecret(t *testing.T) {
+	fake := &fakeExternalAssertionSigner{}
+	previous := resolveExternalAssertionSigner
+	resolveExternalAssertionSigner = func(_ context.Context, provider string) (clientAssertionSigner, error) {
+		if provider != core.KeylessProviderLarkSuite {
+			t.Fatalf("provider = %q", provider)
+		}
+		return fake, nil
+	}
+	t.Cleanup(func() { resolveExternalAssertionSigner = previous })
+
+	ca := ClientAuth{
+		AppID: "cli_external", AppSecret: "must-not-send", AuthMethod: core.AuthMethodPrivateKeyJWT,
+		Signer: newFakeAuthSigner(t), KeyLabel: "openclaw-lark", KeyProvider: core.KeylessProviderLarkSuite,
+	}
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "open.feishu.cn")
+	if err != nil || !used {
+		t.Fatalf("applyClientAssertion = used %v err %v", used, err)
+	}
+	if form.Get("client_assertion") != "external.jwt.1" || form.Has("client_secret") ||
+		fake.keyRef != "openclaw-lark" || fake.clientID != "cli_external" || fake.audience != "open.feishu.cn" {
+		t.Fatalf("form=%v signer=(%q,%q,%q)", form, fake.keyRef, fake.clientID, fake.audience)
+	}
+}
+
+func TestClientAuth_ResolveSignerPreparedCopyReusesResolutionAndRemintsAssertions(t *testing.T) {
+	fake := &fakeExternalAssertionSigner{}
+	resolveCalls := 0
+	previous := resolveExternalAssertionSigner
+	resolveExternalAssertionSigner = func(_ context.Context, provider string) (clientAssertionSigner, error) {
+		resolveCalls++
+		if provider != core.KeylessProviderLarkSuite {
+			t.Fatalf("provider = %q", provider)
+		}
+		return fake, nil
+	}
+	t.Cleanup(func() { resolveExternalAssertionSigner = previous })
+
+	original := ClientAuth{
+		AppID: "cli_external", AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel: "openclaw-lark", KeyProvider: core.KeylessProviderLarkSuite,
+	}
+	prepared, err := original.ResolveSigner(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if original.externalSigner != nil {
+		t.Fatal("ResolveSigner must return a prepared copy without mutating the original")
+	}
+
+	forms := []url.Values{{}, {}}
+	for _, form := range forms {
+		used, err := prepared.applyClientAssertion(context.Background(), form, "open.feishu.cn")
+		if err != nil || !used {
+			t.Fatalf("applyClientAssertion = used %v err %v", used, err)
+		}
+	}
+
+	if resolveCalls != 1 {
+		t.Fatalf("provider resolution calls = %d, want 1", resolveCalls)
+	}
+	if fake.calls != 2 {
+		t.Fatalf("assertion signing calls = %d, want 2", fake.calls)
+	}
+	first := forms[0].Get("client_assertion")
+	second := forms[1].Get("client_assertion")
+	if first == "" || second == "" || first == second {
+		t.Fatalf("assertions = (%q, %q), want two fresh values", first, second)
+	}
+	for _, form := range forms {
+		if form.Has("client_secret") {
+			t.Fatalf("private_key_jwt form leaked client_secret: %v", form)
+		}
+	}
+}
+
+func TestClientAuthFromConfig(t *testing.T) {
+	ca := ClientAuthFromConfig(&core.CliConfig{
+		AppID:      "cli_x",
+		AppSecret:  "test-secret",
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel:   "label-1",
+	})
+	if ca.AppID != "cli_x" || ca.AppSecret != "test-secret" || ca.AuthMethod != core.AuthMethodPrivateKeyJWT || ca.KeyLabel != "label-1" {
+		t.Errorf("ClientAuth = %+v", ca)
+	}
+}

internal/auth/device_flow.go

@@ -62,7 +62,7 @@ func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints {
 }
 
 // RequestDeviceAuthorization requests a device authorization code.
-func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
+func RequestDeviceAuthorization(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -77,18 +77,26 @@ func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string
 		}
 	}
 
-	basicAuth := base64.StdEncoding.EncodeToString([]byte(appId + ":" + appSecret))
-
 	form := url.Values{}
-	form.Set("client_id", appId)
+	form.Set("client_id", ca.AppID)
 	form.Set("scope", scope)
 
-	req, err := http.NewRequest("POST", endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
+	// private_key_jwt authenticates the client with a signed assertion in the
+	// body; client_secret uses HTTP Basic.
+	usedAssertion, err := ca.applyClientAssertion(ctx, form, core.OpenAPIAudience(brand))
+	if err != nil {
+		return nil, err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
 	if err != nil {
 		return nil, err
 	}
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Authorization", "Basic "+basicAuth)
+	if !usedAssertion {
+		basicAuth := base64.StdEncoding.EncodeToString([]byte(ca.AppID + ":" + ca.AppSecret))
+		req.Header.Set("Authorization", "Basic "+basicAuth)
+	}
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
@@ -139,7 +147,7 @@ func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string
 }
 
 // PollDeviceToken polls the token endpoint until authorization completes or times out.
-func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
+func PollDeviceToken(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -171,10 +179,16 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 		form := url.Values{}
 		form.Set("grant_type", "urn:ietf:params:oauth:grant-type:device_code")
 		form.Set("device_code", deviceCode)
-		form.Set("client_id", appId)
-		form.Set("client_secret", appSecret)
+		form.Set("client_id", ca.AppID)
+		usedAssertion, caErr := ca.applyClientAssertion(ctx, form, core.OpenAPIAudience(brand))
+		if caErr != nil {
+			return &DeviceFlowResult{OK: false, Error: "invalid_client", Message: caErr.Error()}
+		}
+		if !usedAssertion {
+			form.Set("client_secret", ca.AppSecret)
+		}
 
-		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
+		req, err := http.NewRequestWithContext(ctx, "POST", endpoints.Token, strings.NewReader(form.Encode()))
 		if err != nil {
 			continue
 		}

internal/auth/device_flow_test.go

@@ -7,8 +7,10 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"io"
 	"log"
 	"net/http"
+	"net/url"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -83,7 +85,7 @@ func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
 	})
 	t.Cleanup(restore)
 
-	_, err := RequestDeviceAuthorization(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "", nil)
+	_, err := RequestDeviceAuthorization(context.Background(), httpmock.NewClient(reg), ClientAuth{AppID: "cli_a", AppSecret: "test-secret"}, core.BrandFeishu, "", nil)
 	if err != nil {
 		t.Fatalf("RequestDeviceAuthorization() error: %v", err)
 	}
@@ -106,6 +108,66 @@ func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
 	}
 }
 
+// captureRT records the last request + body and returns a canned device-auth response.
+func captureDeviceAuthClient(gotReq **http.Request, gotBody *string, respJSON string) *http.Client {
+	return &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		*gotReq = req
+		if req.Body != nil {
+			b, _ := io.ReadAll(req.Body)
+			*gotBody = string(b)
+		}
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader(respJSON)),
+		}, nil
+	})}
+}
+
+const deviceAuthRespJSON = `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`
+
+func TestRequestDeviceAuthorization_PrivateKeyJWT_UsesAssertionNotBasic(t *testing.T) {
+	var req *http.Request
+	var body string
+	client := captureDeviceAuthClient(&req, &body, deviceAuthRespJSON)
+
+	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT, Signer: newFakeAuthSigner(t), KeyLabel: "k"}
+	if _, err := RequestDeviceAuthorization(context.Background(), client, ca, core.BrandFeishu, "im:message:send", nil); err != nil {
+		t.Fatal(err)
+	}
+	if req.Header.Get("Authorization") != "" {
+		t.Errorf("private_key_jwt must NOT send Basic auth, got %q", req.Header.Get("Authorization"))
+	}
+	form, _ := url.ParseQuery(body)
+	if form.Get("client_assertion") == "" {
+		t.Error("missing client_assertion")
+	}
+	if form.Get("client_assertion_type") != "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" {
+		t.Errorf("client_assertion_type = %q", form.Get("client_assertion_type"))
+	}
+	if form.Has("client_secret") {
+		t.Error("client_secret must not be present for private_key_jwt")
+	}
+}
+
+func TestRequestDeviceAuthorization_ClientSecret_UsesBasic(t *testing.T) {
+	var req *http.Request
+	var body string
+	client := captureDeviceAuthClient(&req, &body, deviceAuthRespJSON)
+
+	ca := ClientAuth{AppID: "cli_a", AppSecret: "test-secret"} // client_secret
+	if _, err := RequestDeviceAuthorization(context.Background(), client, ca, core.BrandFeishu, "", nil); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(req.Header.Get("Authorization"), "Basic ") {
+		t.Errorf("client_secret should use Basic auth, got %q", req.Header.Get("Authorization"))
+	}
+	form, _ := url.ParseQuery(body)
+	if form.Has("client_assertion") {
+		t.Error("client_secret must not send a client_assertion")
+	}
+}
+
 // TestFormatAuthCmdline_TruncatesExtraArgs verifies that long command lines are truncated.
 func TestFormatAuthCmdline_TruncatesExtraArgs(t *testing.T) {
 	got := keychain.FormatAuthCmdline([]string{
@@ -205,7 +267,7 @@ func TestPollDeviceToken_DefaultsZeroIntervalToFiveSeconds(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 	t.Cleanup(cancel)
 
-	result := PollDeviceToken(ctx, client, "cli_a", "secret_b", core.BrandFeishu, "device-code", 0, 10, nil)
+	result := PollDeviceToken(ctx, client, ClientAuth{AppID: "cli_a", AppSecret: "test-secret"}, core.BrandFeishu, "device-code", 0, 10, nil)
 	if result == nil {
 		t.Fatal("PollDeviceToken() returned nil result")
 	}

internal/auth/jwt/jwt.go

@@ -0,0 +1,152 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package jwt builds compact JWS tokens signed by a keysigner.Signer.
+//
+// It deliberately depends only on the standard library plus the existing
+// google/uuid dependency — no third-party JWT library is introduced, keeping
+// go.mod free of new dependencies. The actual signing (and, for ECDSA, the
+// ASN.1->r||s conversion) is delegated to the Signer implementation.
+package jwt
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+// buildSignedJWT builds a compact JWS:
+//
+//	base64url(header).base64url(claims).base64url(signature)
+//
+// alg is written into the header (it is part of the signed input) and verified
+// against the alg the signer reports, guarding against a header/key mismatch.
+// typ defaults to "JWT" because the client-assertion endpoint requires that
+// protected-header value, even though some protocol examples show only alg.
+func buildSignedJWT(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, alg string, header, claims map[string]any) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	if header == nil {
+		header = map[string]any{}
+	}
+	header["alg"] = alg
+	if _, ok := header["typ"]; !ok {
+		header["typ"] = "JWT"
+	}
+
+	hb, err := json.Marshal(header)
+	if err != nil {
+		return "", fmt.Errorf("jwt: marshal header: %w", err)
+	}
+	cb, err := json.Marshal(claims)
+	if err != nil {
+		return "", fmt.Errorf("jwt: marshal claims: %w", err)
+	}
+
+	signingInput := b64(hb) + "." + b64(cb)
+	sig, gotAlg, err := signer.Sign(ctx, ref, []byte(signingInput))
+	if err != nil {
+		return "", fmt.Errorf("jwt: sign: %w", err)
+	}
+	if gotAlg != alg {
+		return "", fmt.Errorf("jwt: signer alg %q does not match header alg %q", gotAlg, alg)
+	}
+	return signingInput + "." + b64(sig), nil
+}
+
+// newJTI returns a random unique token identifier.
+func newJTI() string { return uuid.NewString() }
+
+// attestationTTL bounds the attestation JWT's lifetime. The init nonce (60s,
+// single-use) is the real anti-replay constraint; this is a modest margin for
+// clock skew on top of the immediate init→sign→begin round-trip.
+const attestationTTL = 2 * time.Minute
+
+// attestationClaims builds the registration attestation claim set per the App
+// Registration JWT spec: jti, iat, exp (all required) and the init-issued nonce.
+func attestationClaims(nonce string, now time.Time) map[string]any {
+	return map[string]any{
+		"jti":   newJTI(),
+		"iat":   now.Unix(),
+		"exp":   now.Add(attestationTTL).Unix(),
+		"nonce": nonce,
+	}
+}
+
+// clientAssertionClaims builds an RFC 7523 client_assertion claim set used to
+// mint tokens in place of client_secret. aud is the brand's token endpoint URL.
+func clientAssertionClaims(clientID, aud string, now time.Time, ttl time.Duration) map[string]any {
+	return map[string]any{
+		"iss": clientID,
+		"sub": clientID,
+		"aud": aud,
+		"iat": now.Unix(),
+		"exp": now.Add(ttl).Unix(),
+		"jti": newJTI(),
+	}
+}
+
+// ClientAssertionType is the RFC 7523 client_assertion_type value used for JWT
+// bearer client authentication at the token endpoint.
+const ClientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+// defaultAssertionTTL bounds a client_assertion's lifetime.
+const defaultAssertionTTL = 5 * time.Minute
+
+// SignAttestation signs the registration attestation JWT. The public key is
+// embedded in the JWS "jwk" header so the registration backend can bind it to
+// the app during action=begin; the claims carry the server nonce as a
+// proof-of-possession challenge.
+func SignAttestation(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, nonce string, now time.Time) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	pub, err := signer.EnsureKey(ctx, ref)
+	if err != nil {
+		return "", fmt.Errorf("jwt: ensure key: %w", err)
+	}
+	alg, err := keysigner.AlgForKey(pub)
+	if err != nil {
+		return "", err
+	}
+	jwk, err := keysigner.PublicKeyJWK(pub)
+	if err != nil {
+		return "", err
+	}
+	return buildSignedJWT(ctx, signer, ref, alg, map[string]any{"jwk": jwk}, attestationClaims(nonce, now))
+}
+
+// SignClientAssertion mints a short-lived RFC 7523 client_assertion: it reads the
+// registered key (it must already exist — bound at registration; a missing key is
+// an error, not a reason to create a new unbound one), derives the JWS alg from
+// the public key, and signs an assertion whose audience is the brand's Open API
+// host. The server, holding the public key bound at registration, verifies it in
+// place of client_secret. The assertion header carries only alg (no jwk/kid);
+// the server locates the key via iss/sub = client_id.
+//
+// This is the model-independent glue: the assertion JWT is identical whether the
+// server augments an existing grant (device_code/refresh_token) with client
+// authentication or uses a dedicated jwt-bearer grant — only where the caller
+// attaches it differs.
+func SignClientAssertion(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, clientID, audience string, now time.Time) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	pub, err := signer.PublicKey(ctx, ref)
+	if err != nil {
+		return "", fmt.Errorf("jwt: public key: %w", err)
+	}
+	alg, err := keysigner.AlgForKey(pub)
+	if err != nil {
+		return "", err
+	}
+	return buildSignedJWT(ctx, signer, ref, alg, map[string]any{}, clientAssertionClaims(clientID, audience, now, defaultAssertionTTL))
+}

internal/auth/jwt/jwt_test.go

@@ -0,0 +1,254 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package jwt
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"math/big"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// fakeSigner is a real in-memory ECDSA P-256 signer, so tests exercise the full
+// JWS path and the produced token is actually cryptographically verifiable.
+type fakeSigner struct{ key *ecdsa.PrivateKey }
+
+func newFakeSigner(t *testing.T) *fakeSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &fakeSigner{key: k}
+}
+
+func (f *fakeSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(rand.Reader, f.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	// JOSE ES256: fixed-width big-endian r||s (32 bytes each for P-256).
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
+func TestBuildSignedJWT_VerifiableES256(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+
+	tok, err := buildSignedJWT(context.Background(), f, keysigner.KeyRef{Label: "x"}, keysigner.AlgES256,
+		map[string]any{}, clientAssertionClaims("cli_app", "https://accounts.example/token", now, 5*time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 JWS parts, got %d", len(parts))
+	}
+
+	hb, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		t.Fatalf("header not base64url: %v", err)
+	}
+	var hdr map[string]any
+	if err := json.Unmarshal(hb, &hdr); err != nil {
+		t.Fatal(err)
+	}
+	if hdr["alg"] != "ES256" || hdr["typ"] != "JWT" {
+		t.Errorf("header = %v, want alg=ES256 typ=JWT", hdr)
+	}
+
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["iss"] != "cli_app" || claims["sub"] != "cli_app" || claims["aud"] != "https://accounts.example/token" {
+		t.Errorf("claims = %v", claims)
+	}
+
+	// Cryptographically verify the signature against the signing input.
+	sig, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil {
+		t.Fatalf("sig not base64url: %v", err)
+	}
+	if len(sig) != 64 {
+		t.Fatalf("ES256 sig len = %d, want 64", len(sig))
+	}
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("signature did not verify")
+	}
+}
+
+func TestBuildSignedJWT_NilSigner(t *testing.T) {
+	if _, err := buildSignedJWT(context.Background(), nil, keysigner.KeyRef{}, "ES256", nil, nil); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestBuildSignedJWT_AlgMismatch(t *testing.T) {
+	f := newFakeSigner(t) // always reports ES256
+	if _, err := buildSignedJWT(context.Background(), f, keysigner.KeyRef{}, keysigner.AlgRS256, nil, nil); err == nil {
+		t.Fatal("expected error when header alg != signer alg")
+	}
+}
+
+func TestBuildSignedJWT_MarshalErrors(t *testing.T) {
+	f := newFakeSigner(t)
+	ctx := context.Background()
+
+	_, err := buildSignedJWT(ctx, f, keysigner.KeyRef{}, keysigner.AlgES256,
+		map[string]any{"bad": func() {}}, nil)
+	if err == nil || !strings.Contains(err.Error(), "jwt: marshal header") {
+		t.Fatalf("header marshal error = %v, want prefix %q", err, "jwt: marshal header")
+	}
+
+	_, err = buildSignedJWT(ctx, f, keysigner.KeyRef{}, keysigner.AlgES256,
+		nil, map[string]any{"bad": make(chan int)})
+	if err == nil || !strings.Contains(err.Error(), "jwt: marshal claims") {
+		t.Fatalf("claims marshal error = %v, want prefix %q", err, "jwt: marshal claims")
+	}
+}
+
+func TestSignClientAssertion(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+	const aud = "https://accounts.feishu.cn/open-apis/authen/v2/oauth/token"
+
+	tok, err := SignClientAssertion(context.Background(), f, keysigner.KeyRef{Label: "k"}, "cli_app", aud, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 parts, got %d", len(parts))
+	}
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["iss"] != "cli_app" || claims["aud"] != aud {
+		t.Errorf("claims = %v", claims)
+	}
+
+	// Signature must verify against the key's public half.
+	sig, _ := base64.RawURLEncoding.DecodeString(parts[2])
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("client_assertion signature did not verify")
+	}
+}
+
+func TestSignClientAssertion_NilSigner(t *testing.T) {
+	if _, err := SignClientAssertion(context.Background(), nil, keysigner.KeyRef{}, "cli_app", "aud", time.Unix(0, 0)); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestSignAttestation(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+
+	tok, err := SignAttestation(context.Background(), f, keysigner.KeyRef{Label: "k"}, "nonce-abc", now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 parts, got %d", len(parts))
+	}
+
+	hb, _ := base64.RawURLEncoding.DecodeString(parts[0])
+	var hdr map[string]any
+	if err := json.Unmarshal(hb, &hdr); err != nil {
+		t.Fatal(err)
+	}
+	jwk, ok := hdr["jwk"].(map[string]any)
+	if !ok {
+		t.Fatalf("attestation header missing jwk: %v", hdr)
+	}
+	if jwk["kty"] != "EC" || jwk["crv"] != "P-256" || jwk["use"] != "sig" {
+		t.Errorf("jwk = %v", jwk)
+	}
+
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["nonce"] != "nonce-abc" {
+		t.Errorf("nonce = %v", claims["nonce"])
+	}
+	// jti, iat, exp are all required by the attestation spec.
+	iat, iatOK := claims["iat"].(float64)
+	exp, expOK := claims["exp"].(float64)
+	if !iatOK || !expOK || exp <= iat {
+		t.Errorf("claims iat/exp invalid: iat=%v exp=%v", claims["iat"], claims["exp"])
+	}
+	if jti, _ := claims["jti"].(string); jti == "" {
+		t.Error("claims jti empty")
+	}
+
+	// Signature verifies against the embedded key.
+	sig, _ := base64.RawURLEncoding.DecodeString(parts[2])
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("attestation signature did not verify")
+	}
+}
+
+func TestSignAttestation_NilSigner(t *testing.T) {
+	if _, err := SignAttestation(context.Background(), nil, keysigner.KeyRef{}, "n", time.Unix(0, 0)); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestClaimFactories(t *testing.T) {
+	now := time.Unix(1700000000, 0)
+
+	a := attestationClaims("nonce-xyz", now)
+	if a["nonce"] != "nonce-xyz" || a["iat"] != now.Unix() {
+		t.Errorf("attestation claims = %v", a)
+	}
+	if a["exp"] != now.Add(attestationTTL).Unix() {
+		t.Errorf("attestation exp = %v, want %v", a["exp"], now.Add(attestationTTL).Unix())
+	}
+	if jti, _ := a["jti"].(string); jti == "" {
+		t.Error("attestation jti empty")
+	}
+
+	c := clientAssertionClaims("cli_app", "aud", now, time.Minute)
+	if c["exp"].(int64) != now.Add(time.Minute).Unix() {
+		t.Errorf("client_assertion exp = %v", c["exp"])
+	}
+}

internal/auth/uat_client.go

@@ -21,6 +21,7 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/errclass"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -33,11 +34,15 @@ func sanitizeID(id string) string {
 
 // UATCallOptions contains options for UAT API calls.
 type UATCallOptions struct {
-	UserOpenId string
-	AppId      string
-	AppSecret  string
-	Domain     core.LarkBrand
-	ErrOut     io.Writer // diagnostic/status output (caller injects f.IOStreams.ErrOut)
+	UserOpenId  string
+	AppId       string
+	AppSecret   string
+	Domain      core.LarkBrand
+	AuthMethod  string           // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	KeyLabel    string           // TEE key handle for private_key_jwt
+	KeyProvider string           // empty == built-in signer; explicit external route otherwise
+	Signer      keysigner.Signer // active signer for private_key_jwt
+	ErrOut      io.Writer        // diagnostic/status output (caller injects f.IOStreams.ErrOut)
 }
 
 // UATStatus represents the status of a user access token.
@@ -57,11 +62,15 @@ func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions {
 		errOut = os.Stderr
 	}
 	return UATCallOptions{
-		UserOpenId: cfg.UserOpenId,
-		AppId:      cfg.AppID,
-		AppSecret:  cfg.AppSecret,
-		Domain:     cfg.Brand,
-		ErrOut:     errOut,
+		UserOpenId:  cfg.UserOpenId,
+		AppId:       cfg.AppID,
+		AppSecret:   cfg.AppSecret,
+		Domain:      cfg.Brand,
+		AuthMethod:  cfg.AuthMethod,
+		KeyLabel:    cfg.KeyLabel,
+		KeyProvider: cfg.KeyProvider,
+		Signer:      keysigner.Active(),
+		ErrOut:      errOut,
 	}
 }
 
@@ -187,13 +196,31 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 	}
 
 	endpoints := ResolveOAuthEndpoints(opts.Domain)
+	clientAuth := ClientAuth{
+		AppID:       opts.AppId,
+		AppSecret:   opts.AppSecret,
+		AuthMethod:  opts.AuthMethod,
+		Signer:      opts.Signer,
+		KeyLabel:    opts.KeyLabel,
+		KeyProvider: opts.KeyProvider,
+	}
+	clientAuth, err := clientAuth.ResolveSigner(context.Background())
+	if err != nil {
+		return nil, err
+	}
 
 	callEndpoint := func() (map[string]interface{}, error) {
 		form := url.Values{}
 		form.Set("grant_type", "refresh_token")
 		form.Set("refresh_token", stored.RefreshToken)
 		form.Set("client_id", opts.AppId)
-		form.Set("client_secret", opts.AppSecret)
+		usedAssertion, caErr := clientAuth.applyClientAssertion(context.Background(), form, core.OpenAPIAudience(opts.Domain))
+		if caErr != nil {
+			return nil, caErr
+		}
+		if !usedAssertion {
+			form.Set("client_secret", opts.AppSecret)
+		}
 
 		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
 		if err != nil {

internal/auth/uat_client_options_test.go

@@ -38,3 +38,27 @@ func TestNewUATCallOptions(t *testing.T) {
 		t.Error("ErrOut not set correctly")
 	}
 }
+
+// TestNewUATCallOptions_PrivateKeyJWT verifies the auth-method fields propagate
+// so the refresh path can mint a client_assertion instead of sending a secret.
+func TestNewUATCallOptions_PrivateKeyJWT(t *testing.T) {
+	cfg := &core.CliConfig{
+		AppID:       "cli_pk",
+		Brand:       core.BrandFeishu,
+		UserOpenId:  "ou_test",
+		AuthMethod:  core.AuthMethodPrivateKeyJWT,
+		KeyLabel:    "agent-key",
+		KeyProvider: core.KeylessProviderLarkSuite,
+	}
+	opts := NewUATCallOptions(cfg, &bytes.Buffer{})
+
+	if opts.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("AuthMethod = %q, want private_key_jwt", opts.AuthMethod)
+	}
+	if opts.KeyLabel != "agent-key" {
+		t.Errorf("KeyLabel = %q, want agent-key", opts.KeyLabel)
+	}
+	if opts.KeyProvider != core.KeylessProviderLarkSuite {
+		t.Errorf("KeyProvider = %q, want %q", opts.KeyProvider, core.KeylessProviderLarkSuite)
+	}
+}

internal/auth/uat_client_test.go

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/auth/jwt"
+	"github.com/larksuite/cli/internal/core"
+)
+
+type uatRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (fn uatRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
+type retryExternalAssertionSigner struct {
+	calls int
+}
+
+func (s *retryExternalAssertionSigner) SignClientAssertion(_ context.Context, _, _, _ string) (string, string, error) {
+	s.calls++
+	return jwt.ClientAssertionType, fmt.Sprintf("refresh.jwt.%d", s.calls), nil
+}
+
+func TestDoRefreshToken_PrivateKeyJWTRetryResolvesOnceAndRemintsAssertion(t *testing.T) {
+	signer := &retryExternalAssertionSigner{}
+	resolveCalls := 0
+	previous := resolveExternalAssertionSigner
+	resolveExternalAssertionSigner = func(_ context.Context, provider string) (clientAssertionSigner, error) {
+		resolveCalls++
+		if provider != core.KeylessProviderLarkSuite {
+			t.Fatalf("provider = %q", provider)
+		}
+		return signer, nil
+	}
+	t.Cleanup(func() { resolveExternalAssertionSigner = previous })
+
+	var forms []url.Values
+	httpClient := &http.Client{Transport: uatRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		body, err := io.ReadAll(req.Body)
+		if err != nil {
+			return nil, err
+		}
+		form, err := url.ParseQuery(string(body))
+		if err != nil {
+			return nil, err
+		}
+		forms = append(forms, form)
+
+		responseBody := `{"code":20050,"error":"server_error","error_description":"retry"}`
+		if len(forms) == 2 {
+			// A success-shaped response without a token lets the test exercise the
+			// retry without writing platform keychain state.
+			responseBody = `{"code":0}`
+		}
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader(responseBody)),
+			Request:    req,
+		}, nil
+	})}
+
+	now := time.Now().UnixMilli()
+	stored := &StoredUAToken{
+		UserOpenId:       "ou_test",
+		AppId:            "cli_external",
+		RefreshToken:     "refresh-token",
+		RefreshExpiresAt: now + int64(time.Hour/time.Millisecond),
+		Scope:            "offline_access",
+		GrantedAt:        now,
+	}
+	opts := UATCallOptions{
+		UserOpenId:  stored.UserOpenId,
+		AppId:       stored.AppId,
+		Domain:      core.BrandFeishu,
+		AuthMethod:  core.AuthMethodPrivateKeyJWT,
+		KeyLabel:    "openclaw-lark",
+		KeyProvider: core.KeylessProviderLarkSuite,
+		ErrOut:      io.Discard,
+	}
+
+	updated, err := doRefreshToken(httpClient, opts, stored)
+	if err == nil || !strings.Contains(err.Error(), "no access_token") {
+		t.Fatalf("doRefreshToken error = %v, want missing access_token after retry", err)
+	}
+	if updated != nil {
+		t.Fatalf("updated token = %#v, want nil", updated)
+	}
+	if resolveCalls != 1 {
+		t.Fatalf("provider resolution calls = %d, want 1", resolveCalls)
+	}
+	if signer.calls != 2 {
+		t.Fatalf("assertion signing calls = %d, want 2", signer.calls)
+	}
+	if len(forms) != 2 {
+		t.Fatalf("token endpoint requests = %d, want 2", len(forms))
+	}
+	first := forms[0].Get("client_assertion")
+	second := forms[1].Get("client_assertion")
+	if first == "" || second == "" || first == second {
+		t.Fatalf("assertions = (%q, %q), want two fresh values", first, second)
+	}
+	for _, form := range forms {
+		if form.Get("grant_type") != "refresh_token" {
+			t.Fatalf("grant_type = %q, want refresh_token", form.Get("grant_type"))
+		}
+		if form.Has("client_secret") {
+			t.Fatalf("private_key_jwt form leaked client_secret: %v", form)
+		}
+	}
+}