chore: add PPE headers and pin miaoda-cli alpha for testing

* feat(apps): read LARKSUITE_CLI_AGENT env var and pass app_source in +create

* feat(apps): add queryAppMeta shared function for app_type/arch_type lookup

* feat(apps): skip scaffold for legacy html apps, pass app_type/arch_type for arch_type=4 html in +init

* feat(apps): add zip packaging for arch_type=4 html publish path

* feat(apps): add TOS upload path for arch_type=4 html in +html-publish with arch_type-based routing

* refactor(apps): replace appMeta struct with queryAppType string for simpler routing

* refactor(apps): simplify to source_agent in +create, unified scaffold in +init, revert html-publish changes

* feat(apps): add --source-path flag to +init for existing source file incorporation

* fix(apps): align queryAppType with actual API path and response structure

* refactor(apps): use appInfo struct to parse GET /apps/{id} response

* test(apps): add full_stack scaffold test case

* feat(apps): surface sync field in +release-create response

* refactor(apps): remove --template flag from +init, derive template from queryAppType with full_stack fallback

* style(apps): fix gofmt formatting in apps_init.go

* test(apps): improve coverage for sync field, queryAppType, and scaffoldInitArgs

* chore(apps): pin miaoda-cli to alpha version 0.1.20-alpha.dd573f8

* feat(apps): add modern_html enum and pass --app-type instead of --template to miaoda-cli

* chore: add global PPE headers for testing (x-use-ppe, x-tt-env)

* feat(apps): add TOS upload path in +html-publish for modern_html, add --tos-path to +release-create

* feat(apps): unify html-publish output structure with app_id for both html and modern_html

* fix(apps): use newFileTransferClient for TOS presigned upload to satisfy forbidigo lint

* test(apps): add coverage for runHTMLPublishTOS success, errors, and upload failures

* fix(apps): change pre_release API method from POST to GET

* fix(apps): adapt pre_release response from map to list<KV> format

* fix(apps): use PUT method and Content-Length for TOS presigned upload

* fix(apps): use tos_path instead of tosPath in release-create request body

* chore(apps): add npmmirror registry for npx miaoda-cli, fix TOS upload test to expect PUT

* refactor(apps): use envvars.AgentName() for source_agent in +create

* feat(apps): integrate release-create into html-publish for modern_html, auto-detect modern_html from doubao agent env

* refactor(apps): remove --tos-path flag from +release-create (now internal to html-publish)

* refactor(apps): remove app_id from html-publish output, update skill doc

* docs(apps): update html-publish description to reflect dual return values

* refactor(apps): remove doubao app_type conversion in +create, let server decide via source_agent

* feat(apps): skip env-pull for modern_html apps in +init

* test(apps): add tests for modern_html env-pull skip in +init

* refactor(apps): introduce appTypePolicy for init control points (skipInstall, skipEnvPull, skipSkillsSync)

* feat(apps): add init step timing and default git config for +init

* feat(apps): add +get shortcut to fetch single app detail by app_id

* chore(apps): remove init step timing (not ready for production)

* test(apps): add coverage for +get shortcut

* chore: remove PPE headers and revert miaoda-cli to @latest for production

* refactor(apps): extract shared prepareHTMLPublishTarball, fix stale comments, simplify queryAppType

* fix(apps): update html-publish dry-run desc, remove hardcoded API path

* fix(apps): use rctx.IO().ErrOut instead of os.Stderr, remove unused appInfo struct

* fix(apps): restore dry-run API path output for E2E compatibility

* refactor(apps): move --source-path control char validation to Validate for dry-run coverage

* fix(apps): update stale --template comments to --app-type in init tests

* test(apps): explicitly unset agent env var for test isolation

.github/workflows/ci.yml

@@ -86,8 +86,10 @@ jobs:
         run: echo "QUALITY_GATE_CHANGED_FROM=$(bash scripts/resolve-changed-from.sh)" >> "$GITHUB_ENV"
       - name: Run golangci-lint
         run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev="$QUALITY_GATE_CHANGED_FROM"
-      - name: Run errs/ lint guards (lintcheck)
+      - name: Run source-contract lint guards (lintcheck)
         run: go run -C lint . --changed-from "$QUALITY_GATE_CHANGED_FROM" ..
+      - name: Run lint module tests
+        run: go test -C lint ./... -count=1
 
   script-test:
     needs: fast-gate

.github/workflows/release.yml

@@ -9,11 +9,7 @@ permissions:
   contents: read
 
 jobs:
-  # 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
@@ -38,21 +34,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  # 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
-    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

.goreleaser.yml

@@ -5,63 +5,25 @@ before:
     - python3 scripts/fetch_meta.py
 
 builds:
-  # 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: .
+  - binary: lark-cli
     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:
-      - linux
-    goarch:
-      - amd64
-      - arm64
-      - riscv64
-  - id: windows
-    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:
-      - windows
-    goarch:
-      - amd64
-      - arm64
-  # 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
+      - linux
+      - windows
     goarch:
       - amd64
       - arm64
+      - riscv64
 
 archives:
   - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
     format_overrides:
       - goos: windows
-        formats: [zip]
+        format: zip
     files:
       - README.md
       - LICENSE

Makefile

@@ -34,11 +34,7 @@ build: fetch_meta
 	go build -trimpath -ldflags "$(LDFLAGS)" -o $(BINARY) .
 
 vet: fetch_meta
-	# -unsafeptr=false: the macOS keychain signer dereferences dylib data-symbol
-	# addresses from purego.Dlsym (uintptr->unsafe.Pointer over stable C memory) —
-	# safe FFI, but go vet's unsafeptr can't prove it and has no inline suppress.
-	# golangci-lint still runs full govet (honoring the //nolint:govet) in CI.
-	go vet -unsafeptr=false ./...
+	go vet ./...
 
 # fmt-check fails when any file would be reformatted by gofmt. Keep this
 # in sync with the fast-gate "Check formatting" step in CI.

cmd/auth/login.go

@@ -265,7 +265,7 @@ func authLoginRun(opts *LoginOptions) error {
 	if err != nil {
 		return err
 	}
-	authResp, err := larkauth.RequestDeviceAuthorization(opts.Ctx, httpClient, larkauth.ClientAuthFromConfig(config), config.Brand, finalScope, f.IOStreams.ErrOut)
+	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
 		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
 	}
@@ -325,7 +325,7 @@ func authLoginRun(opts *LoginOptions) error {
 
 	// Step 3: Poll for token
 	log(msg.WaitingAuth)
-	result := pollDeviceToken(opts.Ctx, httpClient, larkauth.ClientAuthFromConfig(config), config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
 		authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 
 	if !result.OK {
@@ -415,7 +415,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, larkauth.ClientAuthFromConfig(config), config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
 		opts.DeviceCode, 5, 600, f.IOStreams.ErrOut)
 
 	if !result.OK {

cmd/auth/login_test.go

@@ -847,7 +847,7 @@ func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {
 
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: true, Token: nil}
 	}
 
@@ -886,7 +886,7 @@ func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
 
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: false, Message: "user denied"}
 	}
 

cmd/build.go

@@ -25,8 +25,10 @@ import (
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -42,6 +44,18 @@ type buildConfig struct {
 	skipStrictMode bool
 	skipService    bool
 	serviceCatalog *apicatalog.Catalog
+	startupBrand   core.LarkBrand
+}
+
+// WithStartupBrand initializes the API registry with the given brand before
+// any command registration touches the runtime catalog. Without it the
+// registry's sync.Once locks onto the Feishu default at first catalog access,
+// long before the lazily-resolved config brand is known — see
+// ResolveStartupBrand for the caller-side resolution.
+func WithStartupBrand(brand core.LarkBrand) BuildOption {
+	return func(c *buildConfig) {
+		c.startupBrand = brand
+	}
 }
 
 // WithIO sets the IO streams for the CLI by wrapping raw reader/writers.
@@ -154,6 +168,12 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 		cfg.streams = cmdutil.SystemIO()
 	}
 
+	// Initialize the registry brand before anything touches the runtime
+	// catalog (its sync.Once would otherwise lock onto the Feishu default).
+	if cfg.startupBrand != "" {
+		registry.InitWithBrand(cfg.startupBrand)
+	}
+
 	f := cmdutil.NewDefault(cfg.streams, inv)
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain

cmd/config/bind.go

@@ -406,12 +406,6 @@ func priorLang(previousConfigBytes []byte) i18n.Lang {
 // usable.
 func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigBytes []byte, source, configPath string) error {
 	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}
-	if previousConfigBytes != nil {
-		var previous core.MultiAppConfig
-		if json.Unmarshal(previousConfigBytes, &previous) == nil {
-			multi.KeylessSignerCmd = previous.KeylessSignerCmd
-		}
-	}
 
 	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
 		return errs.NewInternalError(errs.SubtypeFileIO, "failed to create workspace directory: %v", err).WithCause(err)

cmd/config/bind_test.go

@@ -274,48 +274,6 @@ func TestConfigBindRun_OmitLangPreservesPrior(t *testing.T) {
 	}
 }
 
-func TestConfigBindRun_PreservesKeylessSignerCommand(t *testing.T) {
-	saveWorkspace(t)
-	configDir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
-	hermesHome := t.TempDir()
-	t.Setenv("HERMES_HOME", hermesHome)
-	if err := os.WriteFile(filepath.Join(hermesHome, ".env"), []byte("FEISHU_APP_ID=cli_abc\nFEISHU_APP_SECRET=test-secret"), 0600); err != nil {
-		t.Fatalf("write .env: %v", err)
-	}
-
-	hermesDir := filepath.Join(configDir, "hermes")
-	if err := os.MkdirAll(hermesDir, 0700); err != nil {
-		t.Fatalf("mkdir workspace config: %v", err)
-	}
-	previous := &core.MultiAppConfig{
-		KeylessSignerCmd: `/usr/local/bin/lark-keyless-signer`,
-		Apps: []core.AppConfig{{
-			AppId: "cli_old", AppSecret: core.PlainSecret("old-secret"), Brand: core.BrandFeishu,
-		}},
-	}
-	data, err := json.Marshal(previous)
-	if err != nil {
-		t.Fatalf("marshal previous config: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join(hermesDir, "config.json"), data, 0600); err != nil {
-		t.Fatalf("write previous config: %v", err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	if err := configBindRun(&BindOptions{Factory: f, Source: "hermes"}); err != nil {
-		t.Fatalf("configBindRun() error = %v", err)
-	}
-
-	multi, err := core.LoadMultiAppConfig()
-	if err != nil {
-		t.Fatalf("LoadMultiAppConfig() error = %v", err)
-	}
-	if multi.KeylessSignerCmd != previous.KeylessSignerCmd {
-		t.Fatalf("KeylessSignerCmd = %q, want preserved %q", multi.KeylessSignerCmd, previous.KeylessSignerCmd)
-	}
-}
-
 // TestPriorLang_RespectsCurrentApp guards against priorLang scanning all apps
 // and silently returning a non-current profile's Lang. In a multi-profile
 // workspace (set up via `profile add` before a re-bind), the active profile's
@@ -958,25 +916,6 @@ func TestReadDotenv_ValueWithEquals(t *testing.T) {
 	}
 }
 
-func TestNormalizeBrand(t *testing.T) {
-	tests := []struct {
-		input string
-		want  string
-	}{
-		{"", "feishu"},
-		{"feishu", "feishu"},
-		{"lark", "lark"},
-		{"LARK", "lark"},
-		{" lark ", "lark"},
-		{"Lark", "lark"},
-	}
-	for _, tt := range tests {
-		if got := normalizeBrand(tt.input); got != tt.want {
-			t.Errorf("normalizeBrand(%q) = %q, want %q", tt.input, got, tt.want)
-		}
-	}
-}
-
 func TestResolveOpenClawConfigPath_Overrides(t *testing.T) {
 	t.Run("OPENCLAW_CONFIG_PATH wins", func(t *testing.T) {
 		custom := filepath.Join(t.TempDir(), "custom.json")

cmd/config/binder.go

@@ -205,7 +205,7 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 	return &core.AppConfig{
 		AppId:     selected.AppID,
 		AppSecret: stored,
-		Brand:     core.LarkBrand(normalizeBrand(selected.Brand)),
+		Brand:     core.ParseBrand(selected.Brand),
 	}, nil
 }
 
@@ -261,7 +261,7 @@ func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 	return &core.AppConfig{
 		AppId:     appID,
 		AppSecret: stored,
-		Brand:     core.LarkBrand(normalizeBrand(b.envMap["FEISHU_DOMAIN"])),
+		Brand:     core.ParseBrand(b.envMap["FEISHU_DOMAIN"]),
 	}, nil
 }
 
@@ -326,7 +326,7 @@ func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 	return &core.AppConfig{
 		AppId:     appID,
 		AppSecret: stored,
-		Brand:     core.LarkBrand(normalizeBrand(b.cfg.Accounts.App.Tenant)),
+		Brand:     core.ParseBrand(b.cfg.Accounts.App.Tenant),
 	}, nil
 }
 
@@ -350,16 +350,6 @@ func sourceDisplayName(source string) string {
 	}
 }
 
-// normalizeBrand applies .strip().lower() and defaults to "feishu".
-// Aligns with Hermes gateway/platforms/feishu.py:1119 behavior.
-func normalizeBrand(raw string) string {
-	s := strings.TrimSpace(strings.ToLower(raw))
-	if s == "" {
-		return "feishu"
-	}
-	return s
-}
-
 // resolveHermesEnvPath returns the path to Hermes's .env file.
 // Respects HERMES_HOME override; defaults to ~/.hermes/.env.
 //

cmd/config/config_test.go

@@ -5,7 +5,6 @@ package config
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"io"
 	"os"
@@ -18,11 +17,9 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/vfs"
 )
 
 type noopConfigKeychain struct{}
@@ -68,39 +65,6 @@ 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,
@@ -229,7 +193,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, "", "", nil); err != nil {
+	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
 		t.Fatalf("saveInitConfig (no --lang): %v", err)
 	}
 
@@ -242,156 +206,6 @@ func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
 	}
 }
 
-func TestSaveInitConfig_SynchronizesKeylessSignerCommand(t *testing.T) {
-	tests := []struct {
-		name       string
-		previous   string
-		envValue   string
-		want       string
-		wantStored bool
-	}{
-		{name: "persists new value", envValue: "/new/helper", want: "/new/helper", wantStored: true},
-		{name: "replaces previous value", previous: "/old/helper", envValue: "/new/helper", want: "/new/helper", wantStored: true},
-		{name: "removes previous value when env is empty", previous: "/old/helper"},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-			t.Setenv(envvars.CliKeylessSignerCmd, tc.envValue)
-			f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-			existing := &core.MultiAppConfig{
-				CurrentApp: "keep",
-				Apps: []core.AppConfig{
-					{Name: "keep", AppId: "cli_keep", AppSecret: core.PlainSecret("keep-secret"), Brand: core.BrandFeishu},
-					{Name: "target", AppId: "cli_old", AppSecret: core.PlainSecret("old-secret"), Brand: core.BrandLark},
-				},
-			}
-			if err := core.SaveMultiAppConfig(existing); err != nil {
-				t.Fatalf("seed config: %v", err)
-			}
-			if tc.previous != "" {
-				setRawConfigField(t, "keylessSignerCmd", tc.previous)
-				var err error
-				existing, err = core.LoadMultiAppConfig()
-				if err != nil {
-					t.Fatalf("reload seeded config: %v", err)
-				}
-			}
-
-			if err := saveInitConfig("target", existing, f, "cli_new", core.PlainSecret("new-secret"), core.BrandFeishu, "", "", nil); err != nil {
-				t.Fatalf("saveInitConfig: %v", err)
-			}
-
-			raw := readRawConfig(t)
-			got, ok := raw["keylessSignerCmd"]
-			if ok != tc.wantStored {
-				t.Fatalf("keylessSignerCmd presence = %v, want %v; config=%v", ok, tc.wantStored, raw)
-			}
-			if tc.wantStored && got != tc.want {
-				t.Fatalf("keylessSignerCmd = %v, want %q", got, tc.want)
-			}
-
-			saved, err := core.LoadMultiAppConfig()
-			if err != nil {
-				t.Fatalf("LoadMultiAppConfig: %v", err)
-			}
-			if saved.CurrentApp != "keep" || len(saved.Apps) != 2 {
-				t.Fatalf("unrelated config changed: currentApp=%q apps=%d", saved.CurrentApp, len(saved.Apps))
-			}
-		})
-	}
-}
-
-func setRawConfigField(t *testing.T, key string, value any) {
-	t.Helper()
-	raw := readRawConfig(t)
-	raw[key] = value
-	data, err := json.MarshalIndent(raw, "", "  ")
-	if err != nil {
-		t.Fatalf("marshal config: %v", err)
-	}
-	if err := vfs.WriteFile(core.GetConfigPath(), append(data, '\n'), 0600); err != nil {
-		t.Fatalf("write config: %v", err)
-	}
-}
-
-func readRawConfig(t *testing.T) map[string]any {
-	t.Helper()
-	data, err := vfs.ReadFile(core.GetConfigPath())
-	if err != nil {
-		t.Fatalf("read config: %v", err)
-	}
-	var raw map[string]any
-	if err := json.Unmarshal(data, &raw); err != nil {
-		t.Fatalf("unmarshal config: %v", err)
-	}
-	return raw
-}
-
-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.)
@@ -574,7 +388,7 @@ func TestSaveAsProfile_RejectsProfileNameCollisionWithExistingAppID(t *testing.T
 		},
 	}
 
-	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en", "", nil)
+	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en")
 	if err == nil {
 		t.Fatal("expected conflict error")
 	}
@@ -613,46 +427,6 @@ 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",

cmd/config/init.go

@@ -17,11 +17,8 @@ import (
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
-	"github.com/larksuite/cli/internal/keylesshelper"
-	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -34,7 +31,6 @@ 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
@@ -43,8 +39,6 @@ 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
@@ -87,39 +81,17 @@ 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
-}
-
-func validateKeylessSignerEnvironment() error {
-	if !keylesshelper.ConfiguredFromEnvironment() {
-		return nil
-	}
-	if err := keylesshelper.ValidateConfigured(); err != nil {
-		return errs.NewConfigError(errs.SubtypeInvalidClient,
-			"invalid keyless signer command: %v", err).
-			WithCause(err).
-			WithHint("fix or unset %s before running config init", envvars.CliKeylessSignerCmd)
-	}
-	return nil
-}
-
 // printLangPreferenceConfirmation echoes the set preference to stderr, only
 // when --lang explicitly set a non-empty value.
 func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
@@ -160,7 +132,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.Restore || o.AppID != "" || o.AppSecretStdin
+	return o.New || o.AppID != "" || o.AppSecretStdin
 }
 
 // cleanupOldConfig clears keychain entries (AppSecret + UAT) for all apps in existing config except the app whose AppId equals skipAppID.
@@ -179,62 +151,22 @@ 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, authMethod string, keyRef *core.SecretRef) error {
+func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) 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 {
-	config.KeylessSignerCmd = strings.TrimSpace(os.Getenv(envvars.CliKeylessSignerCmd))
 	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.
-// 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 {
+func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmdutil.Factory, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	if profileName != "" {
-		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang, authMethod, keyRef)
+		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
 	}
 	cleanupOldConfig(existing, f, appId)
 	var prior i18n.Lang
@@ -243,7 +175,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 			prior = app.Lang
 		}
 	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)), authMethod, keyRef)
+	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
 }
 
 // wrapSaveConfigError passes an already-typed error (e.g. the --name conflict
@@ -263,7 +195,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, authMethod string, keyRef *core.SecretRef) error {
+func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, profileName, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
 	multi := existing
 	if multi == nil {
 		multi = &core.MultiAppConfig{}
@@ -282,8 +214,6 @@ 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,
@@ -292,17 +222,15 @@ 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{},
-			AuthMethod: authMethod,
-			KeyRef:     keyRef,
+			Name:      profileName,
+			AppId:     appId,
+			AppSecret: secret,
+			Brand:     brand,
+			Lang:      i18n.Lang(lang),
+			Users:     []core.AppUser{},
 		})
 	}
-	return saveMultiAppConfigForInit(multi)
+	return core.SaveMultiAppConfig(multi)
 }
 
 func findProfileIndexByName(multi *core.MultiAppConfig, profileName string) int {
@@ -374,139 +302,11 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 	app.AppId = appID
 	app.Brand = brand
 	app.Lang = preferredLang(i18n.Lang(lang), app.Lang)
-	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")
-	}
-
-	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)
+	return core.SaveMultiAppConfig(existing)
 }
 
 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")
-		}
-	}
-	if err := validateKeylessSignerEnvironment(); err != nil {
-		return err
-	}
 
 	// Read secret from stdin if --app-secret-stdin is set
 	if opts.AppSecretStdin {
@@ -535,26 +335,6 @@ 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)
@@ -562,7 +342,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, "", nil); err != nil {
+		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
 			return wrapSaveConfigError(err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
@@ -588,26 +368,34 @@ 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), requestedInitAuthMethod(opts), msg, "")
+		result, err := runCreateAppFlow(opts.Ctx, f, parseBrand(opts.Brand), msg)
 		if err != nil {
 			return err
 		}
 		if result == nil {
 			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
 		}
-		return persistAndProbeResult(opts, f, opts.ProfileName, 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
 	}
 
 	// Mode 4: Interactive TUI (terminal)
 	if !opts.hasAnyNonInteractiveFlag() && f.IOStreams.IsTerminal {
-		result, err := runInteractiveConfigInit(opts.Ctx, f, requestedInitAuthMethod(opts), msg)
+		result, err := runInteractiveConfigInit(opts.Ctx, f, msg)
 		if err != nil {
 			return err
 		}
@@ -616,21 +404,35 @@ func configInitRun(opts *ConfigInitOptions) error {
 				WithParam("--app-id")
 		}
 
-		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 {
+		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 {
 				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.AuthMethod != core.AuthMethodPrivateKeyJWT {
-			return probeInitResult(opts, f, result)
+		if result.AppSecret != "" {
+			if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
+				return err
+			}
 		}
 		return nil
 	}
@@ -715,7 +517,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, "", nil); err != nil {
+	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); 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

@@ -1,414 +0,0 @@
-// 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/envvars"
-	"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 TestResolveRegisterAuthMethod_PrivateKeyJWTAllowsKeylessHelper(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, "/helper")
-	prevSigner := keysigner.Active()
-	t.Cleanup(func() { keysigner.Register(prevSigner) })
-	keysigner.Register(nil)
-
-	m, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
-	if err != nil {
-		t.Fatalf("private_key_jwt with helper: %v", err)
-	}
-	if m != core.AuthMethodPrivateKeyJWT {
-		t.Fatalf("method = %q", m)
-	}
-}
-
-func TestResolveRegisterAuthMethod_PrivateKeyJWTConfigOnlyHelperFallsBackToPlatformSigner(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		KeylessSignerCmd: "/config/helper",
-		Apps: []core.AppConfig{{
-			AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-		}},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-
-	prevSigner := keysigner.Active()
-	t.Cleanup(func() { keysigner.Register(prevSigner) })
-	keysigner.Register(authMethodTestSigner{info: keysigner.HardwareInfo{Backend: "tpm2", Available: true}})
-
-	m, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
-	if err != nil {
-		t.Fatalf("private_key_jwt with platform signer: %v", err)
-	}
-	if m != core.AuthMethodPrivateKeyJWT {
-		t.Fatalf("method = %q, want %q", m, core.AuthMethodPrivateKeyJWT)
-	}
-}
-
-func TestResolveRegisterAuthMethod_PrivateKeyJWTConfigOnlyHelperWithoutPlatformSignerRejects(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		KeylessSignerCmd: "/config/helper",
-		Apps: []core.AppConfig{{
-			AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-		}},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-
-	prevSigner := keysigner.Active()
-	t.Cleanup(func() { keysigner.Register(prevSigner) })
-	keysigner.Register(nil)
-
-	_, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
-	if err == nil {
-		t.Fatal("expected private_key_jwt without a persistent signer to be rejected")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Subtype != errs.SubtypeInvalidClient {
-		t.Fatalf("error = %T %v, want typed invalid_client", err, err)
-	}
-}
-
-func TestResolveRegisterAuthMethod_PrivateKeyJWTRejectsInvalidKeylessHelper(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, `[""]`)
-	prevSigner := keysigner.Active()
-	t.Cleanup(func() { keysigner.Register(prevSigner) })
-	keysigner.Register(nil)
-
-	_, err := resolveRegisterAuthMethod(context.Background(), &cmdutil.Factory{}, core.AuthMethodPrivateKeyJWT)
-	if err == nil {
-		t.Fatal("expected invalid helper error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T %v", err, err)
-	}
-	if prob.Category != errs.CategoryConfig {
-		t.Fatalf("category = %q, want %q", prob.Category, errs.CategoryConfig)
-	}
-}
-
-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())
-			t.Setenv(envvars.CliKeylessSignerCmd, "/helper")
-			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 TestConfigInitRunRejectsInvalidKeylessSignerEnvironment(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, `[""]`)
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	err := configInitRun(&ConfigInitOptions{Factory: f, Ctx: context.Background()})
-	if err == nil {
-		t.Fatal("expected invalid keyless signer environment 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)
-	}
-	if !strings.Contains(problem.Message, "invalid keyless signer command") {
-		t.Fatalf("message = %q, want invalid signer command", problem.Message)
-	}
-}
-
-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

@@ -5,10 +5,9 @@ package config
 
 import (
 	"context"
+	"errors"
 	"fmt"
-	"slices"
-	"strings"
-	"time"
+	"net"
 
 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
@@ -16,27 +15,22 @@ 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/keylesshelper"
-	"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
-	AuthMethod string // "" == client_secret; core.AuthMethodPrivateKeyJWT
-	KeyLabel   string // TEE key handle when AuthMethod == private_key_jwt
+	Mode      string // "create" or "existing"
+	Brand     core.LarkBrand
+	AppID     string
+	AppSecret string
 }
 
 // runInteractiveConfigInit shows an interactive TUI for config init.
-func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, authMethodFlag string, msg *initMsg) (*configInitResult, error) {
+func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, msg *initMsg) (*configInitResult, error) {
 	// Phase 1: Choose mode
 	var mode string
 	form1 := huh.NewForm(
@@ -59,18 +53,14 @@ func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, authMetho
 	}
 
 	if mode == "existing" {
-		return runExistingAppForm(ctx, f, authMethodFlag, msg)
+		return runExistingAppForm(f, msg)
 	}
 
-	return runCreateAppFlow(ctx, f, "", authMethodFlag, msg, "")
-}
-
-func existingAppRequiresSecret(requestedAuthMethod string) bool {
-	return requestedAuthMethod != core.AuthMethodPrivateKeyJWT
+	return runCreateAppFlow(ctx, f, "", msg)
 }
 
 // runExistingAppForm shows a huh form for manually entering App ID / App Secret / Brand.
-func runExistingAppForm(ctx context.Context, f *cmdutil.Factory, requestedAuthMethod string, msg *initMsg) (*configInitResult, error) {
+func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, error) {
 	// Load existing config for defaults
 	existing, _ := core.LoadMultiAppConfig()
 	var firstApp *core.AppConfig
@@ -104,31 +94,19 @@ func runExistingAppForm(ctx context.Context, f *cmdutil.Factory, requestedAuthMe
 		brand = string(firstApp.Brand)
 	}
 
-	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())
-	}
+	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())
 
 	if err := form.Run(); err != nil {
 		if err == huh.ErrUserAborted {
@@ -141,13 +119,6 @@ func runExistingAppForm(ctx context.Context, f *cmdutil.Factory, requestedAuthMe
 	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{
@@ -177,55 +148,9 @@ func runExistingAppForm(ctx context.Context, f *cmdutil.Factory, requestedAuthMe
 	}, 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:
-		if keylesshelper.ConfiguredFromEnvironment() {
-			if err := validateKeylessSignerEnvironment(); err != nil {
-				return "", err
-			}
-			return core.AuthMethodPrivateKeyJWT, nil
-		}
-		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.
-// 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) {
+func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride core.LarkBrand, msg *initMsg) (*configInitResult, error) {
 	var larkBrand core.LarkBrand
 	if brandOverride != "" {
 		larkBrand = brandOverride
@@ -253,63 +178,17 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		larkBrand = parseBrand(brand)
 	}
 
-	authMethod, err := resolveRegisterAuthMethod(ctx, f, requestedAuthMethod)
-	if err != nil {
-		return nil, err
-	}
-
-	// Step 1: Request app registration (begin).
+	// 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)
-
-	// 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(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
-		var attestation string
-		var signErr error
-		if keylesshelper.ConfiguredFromEnvironment() {
-			attestation, signErr = keylesshelper.SignAttestation(ctx, keyLabel, initResp.Nonce)
-		} else {
-			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(httpClient, larkBrand, beginOpts, f.IOStreams.ErrOut)
+	authResp, err := larkauth.RequestAppRegistration(ctx, httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
+		return nil, classifyRegistrationBeginError(err)
 	}
 
 	// Step 2: Build and display verification URL + QR code
-	verificationURL := larkauth.BuildVerificationURL(authResp.VerificationUriComplete, build.Version, restoreAppID)
+	verificationURL := larkauth.BuildVerificationURL(authResp.VerificationUriComplete, build.Version)
 
 	// Branch on TTY: human-friendly copy in interactive terminals,
 	// preserve original copy for AI / non-interactive callers.
@@ -331,104 +210,61 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", verificationURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.WaitingForScanNonTTY)
 	}
-	result, err := larkauth.PollAppRegistration(ctx, httpClient, core.BrandFeishu, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
+	// Step 4: Poll for credentials (brand discovery lives in internal/auth);
+	// this layer only classifies the terminal error and saves the result.
+	result, finalBrand, err := larkauth.RegisterAppWithDiscovery(ctx, httpClient, authResp, f.IOStreams.ErrOut)
 	if err != nil {
-		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
+		return nil, classifyRegistrationError(err)
 	}
 
-	// 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)
-
-	// Lark brand special case (client_secret only): a lark-tenant app returns its
-	// secret only from the lark endpoint. private_key_jwt returns no secret, so
-	// this retry does not apply.
-	if finalMethod != core.AuthMethodPrivateKeyJWT && result.ClientSecret == "" && result.UserInfo != nil && result.UserInfo.TenantBrand == "lark" {
-		result, err = larkauth.PollAppRegistration(ctx, httpClient, core.BrandLark, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
-		if err != nil {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
-		}
-		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")
-	}
-
-	// Determine final brand from response
-	finalBrand := larkBrand
-	if result.UserInfo != nil && result.UserInfo.TenantBrand == "lark" {
-		finalBrand = core.BrandLark
-	} else if result.UserInfo != nil && result.UserInfo.TenantBrand == "feishu" {
-		finalBrand = core.BrandFeishu
-	}
-
-	// 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)
+	if result.ClientID == "" || result.ClientSecret == "" {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
 	}
 
 	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, // empty for private_key_jwt; real secret otherwise
-		AuthMethod: finalMethod,
-		KeyLabel:   keyToStore,
+		Mode:      "create",
+		Brand:     finalBrand,
+		AppID:     result.ClientID,
+		AppSecret: result.ClientSecret,
 	}, nil
 }
 
-// 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")
+// classifyRegistrationBeginError keeps transport/cancellation failures out of
+// the invalid-client category: the begin request sends no app credentials.
+func classifyRegistrationBeginError(err error) error {
+	switch {
+	case errors.Is(err, context.Canceled):
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "app registration cancelled").WithCause(err)
+	case errors.Is(err, context.DeadlineExceeded):
+		return errs.NewNetworkError(errs.SubtypeNetworkTimeout, "app registration begin timed out: %v", err).WithCause(err)
 	}
-	return nil
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		subtype := errs.SubtypeNetworkTransport
+		if netErr.Timeout() {
+			subtype = errs.SubtypeNetworkTimeout
+		}
+		return errs.NewNetworkError(subtype, "app registration begin failed: %v", err).WithCause(err)
+	}
+	return errs.NewAPIError(errs.SubtypeUnknown, "app registration begin failed: %v", err).WithCause(err)
 }
 
-// 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
+// classifyRegistrationError maps registration terminal outcomes to typed
+// errors, preserving causes.
+func classifyRegistrationError(err error) error {
+	switch {
+	case errors.Is(err, larkauth.ErrRegistrationDenied):
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).
+			WithHint("re-run `lark-cli config init --new` and approve the authorization request").
+			WithCause(err)
+	case errors.Is(err, larkauth.ErrRegistrationExpired), errors.Is(err, larkauth.ErrRegistrationTimedOut):
+		return errs.NewAuthenticationError(errs.SubtypeTokenExpired, "%v", err).
+			WithHint("re-run `lark-cli config init --new` and complete the scan before the code expires").
+			WithCause(err)
+	default:
+		return errs.NewAuthenticationError(errs.SubtypeUnknown, "app registration failed: %v", err).WithCause(err)
 	}
-	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_interactive_test.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"context"
+	"errors"
+	"net"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	larkauth "github.com/larksuite/cli/internal/auth"
+)
+
+func assertRegistrationProblem(t *testing.T, got, cause error, category errs.Category, subtype errs.Subtype) *errs.Problem {
+	t.Helper()
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("error %T is not typed: %v", got, got)
+	}
+	if p.Category != category || p.Subtype != subtype {
+		t.Errorf("problem = (%q, %q), want (%q, %q)", p.Category, p.Subtype, category, subtype)
+	}
+	if !errors.Is(got, cause) {
+		t.Errorf("error %v does not preserve cause %v", got, cause)
+	}
+	return p
+}
+
+func TestClassifyRegistrationBeginError(t *testing.T) {
+	tests := []struct {
+		name     string
+		err      error
+		category errs.Category
+		subtype  errs.Subtype
+	}{
+		{"cancelled", context.Canceled, errs.CategoryAuthentication, errs.SubtypeUnknown},
+		{"deadline", context.DeadlineExceeded, errs.CategoryNetwork, errs.SubtypeNetworkTimeout},
+		{"transport", &net.DNSError{Err: "lookup failed", Name: "accounts.example"}, errs.CategoryNetwork, errs.SubtypeNetworkTransport},
+		{"response", errors.New("response not JSON"), errs.CategoryAPI, errs.SubtypeUnknown},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assertRegistrationProblem(t, classifyRegistrationBeginError(tt.err), tt.err, tt.category, tt.subtype)
+		})
+	}
+}
+
+func TestClassifyRegistrationError(t *testing.T) {
+	tests := []struct {
+		name    string
+		err     error
+		subtype errs.Subtype
+		hint    bool
+	}{
+		{"denied", larkauth.ErrRegistrationDenied, errs.SubtypeUnknown, true},
+		{"expired", larkauth.ErrRegistrationExpired, errs.SubtypeTokenExpired, true},
+		{"timed-out", larkauth.ErrRegistrationTimedOut, errs.SubtypeTokenExpired, true},
+		{"cancelled", context.Canceled, errs.SubtypeUnknown, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			p := assertRegistrationProblem(t, classifyRegistrationError(tt.err), tt.err, errs.CategoryAuthentication, tt.subtype)
+			if (p.Hint != "") != tt.hint {
+				t.Errorf("hint = %q, want non-empty=%v", p.Hint, tt.hint)
+			}
+		})
+	}
+}

cmd/config/init_probe.go

@@ -16,8 +16,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/keylesshelper"
-	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // probeTimeout is the total wall-clock budget for the credential probe step
@@ -92,36 +90,3 @@ 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
-	}
-	helper, err := keylesshelper.Resolve()
-	if err != nil || (signer == nil && helper == nil) {
-		return nil
-	}
-	httpClient, err := factory.HttpClient()
-	if err != nil {
-		return nil
-	}
-
-	ctx, cancel := context.WithTimeout(parent, probeTimeout)
-	defer cancel()
-
-	if _, err := credential.FetchTATWithAssertionWithHelper(ctx, httpClient, brand, clientID, signer, helper, 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,11 +6,6 @@ package config
 import (
 	"bytes"
 	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	crand "crypto/rand"
-	"crypto/sha256"
 	"errors"
 	"io"
 	"net/http"
@@ -22,17 +17,14 @@ 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
 }
@@ -56,50 +48,10 @@ 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,
@@ -256,12 +208,10 @@ func TestRunProbe_TATSuccess_ProbeFails_Silent(t *testing.T) {
 	assertSilent(t, err, errBuf)
 }
 
-func TestProbeInitResult_ClientSecret(t *testing.T) {
+func TestRunProbe_TATSuccess_ProbeOK_Silent(t *testing.T) {
 	rt := &fakeRT{}
 	f, errBuf := fakeFactory(t, rt)
-	opts := &ConfigInitOptions{Ctx: context.Background()}
-	result := &configInitResult{AppID: "cli_x", AppSecret: "test-secret", Brand: core.BrandFeishu}
-	err := probeInitResult(opts, f, result)
+	err := runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu)
 	if rt.tatCalls != 1 || rt.probeCalls != 1 {
 		t.Errorf("expected 1/1 calls, got tat=%d probe=%d", rt.tatCalls, rt.probeCalls)
 	}
@@ -335,47 +285,3 @@ 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,25 +10,9 @@ 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,
@@ -135,58 +119,3 @@ 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/doctor/doctor.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"io"
 	"net/http"
 	"os"
 	"sync"
@@ -20,8 +19,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
-	"github.com/larksuite/cli/internal/keylesshelper"
-	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/update"
@@ -138,9 +135,6 @@ func doctorRun(opts *DoctorOptions) error {
 		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)...)
 
@@ -154,76 +148,6 @@ 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
-	helper, err := keylesshelper.Resolve()
-	if err != nil {
-		hint := fmt.Sprintf("fix the external keyless signer source, or re-run config init to replace/remove config.json keylessSignerCmd: %v", err)
-		if usesPKJWT {
-			return fail("tee_signer", "external keyless signer is misconfigured", hint)
-		}
-		return warn("tee_signer", "external keyless signer is misconfigured", hint)
-	}
-	if helper != nil {
-		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 misconfigured", 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 {
@@ -313,90 +237,14 @@ func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 		}
 	}
 
-	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,
-		})
+	result := map[string]interface{}{
+		"ok":        allOK,
+		"workspace": core.CurrentWorkspace().Display(),
+		"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_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"net/http"
 	"strings"
 	"testing"
@@ -18,8 +17,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/keysigner"
 )
 
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
@@ -147,140 +144,6 @@ 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)
-			}
-		})
-	}
-}
-
-func TestTeeSignerCheck_InvalidKeylessHelperEnvFailsPKJWT(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, `[""]`)
-
-	got := teeSignerCheck(context.Background(), &core.CliConfig{AuthMethod: core.AuthMethodPrivateKeyJWT})
-	if got.Status != "fail" {
-		t.Fatalf("status = %q, want fail (msg=%q, hint=%q)", got.Status, got.Message, got.Hint)
-	}
-	if !strings.Contains(got.Hint, envvars.CliKeylessSignerCmd) {
-		t.Fatalf("hint = %q, want env var name", got.Hint)
-	}
-}
-
-func TestTeeSignerCheck_InvalidKeylessHelperConfigHasActionableHint(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		KeylessSignerCmd: `[""]`,
-		Apps: []core.AppConfig{{
-			AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-		}},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-
-	got := teeSignerCheck(context.Background(), &core.CliConfig{AuthMethod: core.AuthMethodPrivateKeyJWT})
-	if got.Status != "fail" {
-		t.Fatalf("status = %q, want fail (msg=%q, hint=%q)", got.Status, got.Message, got.Hint)
-	}
-	if !strings.Contains(got.Hint, "config init") || !strings.Contains(got.Hint, "keylessSignerCmd") {
-		t.Fatalf("hint = %q, want config init repair guidance", got.Hint)
-	}
-}
-
-// 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 {

cmd/root.go

@@ -107,6 +107,7 @@ func Execute() int {
 		ctx, inv,
 		WithIO(os.Stdin, os.Stdout, os.Stderr),
 		HideProfile(isSingleAppMode()),
+		WithStartupBrand(ResolveStartupBrand(inv.Profile)),
 	)
 
 	// --- Notices (non-blocking) ---

cmd/startup_brand.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"os"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/envvars"
+)
+
+// 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 {
+	if raw := os.Getenv(envvars.CliBrand); raw != "" {
+		return core.ParseBrand(raw)
+	}
+	if cfg, err := core.LoadMultiAppConfig(); err == nil {
+		if app := cfg.CurrentAppConfig(profile); app != nil {
+			return core.ParseBrand(string(app.Brand))
+		}
+	}
+	return core.BrandFeishu
+}

cmd/startup_brand_test.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/registry"
+)
+
+func TestResolveStartupBrand_Precedence(t *testing.T) {
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+	t.Setenv("LARKSUITE_CLI_BRAND", "")
+	os.Unsetenv("LARKSUITE_CLI_BRAND")
+
+	// No config at all → default brand.
+	if got := ResolveStartupBrand(""); got != core.BrandFeishu {
+		t.Errorf("empty state brand = %q, want feishu", got)
+	}
+
+	// Raw config supplies the active profile's brand — no keychain involved.
+	raw := `{"currentApp":"feishu-app","apps":[` +
+		`{"name":"feishu-app","appId":"cli_f","appSecret":"test-secret","brand":"feishu","users":[]},` +
+		`{"name":"lark-prof","appId":"cli_l","appSecret":"test-secret","brand":"LARK","users":[]}]}`
+	if err := os.WriteFile(filepath.Join(tmp, "config.json"), []byte(raw), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if got := ResolveStartupBrand(""); got != core.BrandFeishu {
+		t.Errorf("default profile brand = %q, want feishu", got)
+	}
+	if got := ResolveStartupBrand("lark-prof"); got != core.BrandLark {
+		t.Errorf("lark profile brand = %q, want lark (normalized)", got)
+	}
+
+	// Environment wins over the config file.
+	t.Setenv("LARKSUITE_CLI_BRAND", "lark")
+	if got := ResolveStartupBrand(""); got != core.BrandLark {
+		t.Errorf("env brand = %q, want lark", got)
+	}
+}
+
+// TestStartupBrandReachesRegistry_RealStartupOrder proves the fix for the
+// production startup sequence: building the command tree locks the registry's
+// sync.Once, so the brand must be injected before the first catalog access.
+// It runs in a subprocess because the registry is process-global.
+func TestStartupBrandReachesRegistry_RealStartupOrder(t *testing.T) {
+	if os.Getenv("GO_TEST_STARTUP_BRAND_HELPER") == "1" {
+		// Helper: replicate Execute()'s build wiring with a lark config.
+		buildInternal(
+			context.Background(), cmdutil.InvocationContext{},
+			WithIO(strings.NewReader(""), os.Stdout, os.Stderr),
+			WithStartupBrand(ResolveStartupBrand("")),
+		)
+		fmt.Printf("CONFIGURED_BRAND=%s\n", registry.ConfiguredBrand())
+		os.Exit(0)
+	}
+
+	tmp := t.TempDir()
+	raw := `{"apps":[{"appId":"cli_l","appSecret":"test-secret","brand":"lark","users":[]}]}`
+	if err := os.WriteFile(filepath.Join(tmp, "config.json"), []byte(raw), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	cmd := exec.Command(os.Args[0], "-test.run", "TestStartupBrandReachesRegistry_RealStartupOrder")
+	cmd.Env = append(os.Environ(),
+		"GO_TEST_STARTUP_BRAND_HELPER=1",
+		"LARKSUITE_CLI_CONFIG_DIR="+tmp,
+		"LARKSUITE_CLI_REMOTE_META=off", // no network during the subprocess build
+	)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("subprocess failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "CONFIGURED_BRAND=lark") {
+		t.Errorf("registry brand after real startup order = %s, want lark", out)
+	}
+}

cmd/update/update.go

@@ -5,6 +5,7 @@ package cmdupdate
 
 import (
 	"fmt"
+	stdio "io"
 	"runtime"
 	"strings"
 
@@ -13,6 +14,7 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
 	"github.com/larksuite/cli/internal/skillscheck"
@@ -125,13 +127,15 @@ func updateRun(opts *UpdateOptions) error {
 	io := opts.Factory.IOStreams
 	cur := currentVersion()
 	updater := newUpdater()
-
+	// Brand only steers skills sync. updateRun skips that resolution in --check,
+	// where the Updater's zero-value brand retains the Feishu default.
 	if !opts.Check {
+		updater.Brand = resolveSkillsBrand(opts.Factory, io.ErrOut)
 		updater.CleanupStaleFiles()
 	}
 	output.PendingNotice = nil
 
-	// 1. Fetch latest version
+	// 1. Fetch latest version.
 	latest, err := fetchLatest()
 	if err != nil {
 		return reportError(opts, io, "network",
@@ -153,7 +157,7 @@ func updateRun(opts *UpdateOptions) error {
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
 
-	// 4. Detect installation method
+	// 4. Detect installation method.
 	detect := updater.DetectInstallMethod()
 
 	// 5. --check
@@ -168,6 +172,22 @@ func updateRun(opts *UpdateOptions) error {
 	return doAutoUpdate(opts, io, cur, latest, detect, updater)
 }
 
+// resolveSkillsBrand returns the skills-source brand: resolved config first,
+// then the active profile's raw config entry (the brand is not a secret; a
+// locked keychain must not flip the source), then the default with a notice.
+func resolveSkillsBrand(f *cmdutil.Factory, errOut stdio.Writer) core.LarkBrand {
+	if cfg, err := f.Config(); err == nil && cfg != nil {
+		return core.ParseBrand(string(cfg.Brand))
+	}
+	if raw, err := core.LoadMultiAppConfig(); err == nil {
+		if app := raw.CurrentAppConfig(f.Invocation.Profile); app != nil {
+			return core.ParseBrand(string(app.Brand))
+		}
+	}
+	fmt.Fprintf(errOut, "note: could not resolve the configured brand; syncing skills from the default source\n")
+	return core.BrandFeishu
+}
+
 // --- Output helpers ---
 
 // reportError emits the failure on the requested surface: JSON mode prints the

cmd/update/update_test.go

@@ -9,7 +9,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -1731,3 +1733,64 @@ func containsString(values []string, target string) bool {
 	}
 	return false
 }
+
+func TestResolveSkillsBrand_LayeredFallback(t *testing.T) {
+	// Layer 1: resolved config wins.
+	var errBuf bytes.Buffer
+	f := &cmdutil.Factory{Config: func() (*core.CliConfig, error) {
+		return &core.CliConfig{Brand: core.LarkBrand(" LARK ")}, nil
+	}}
+	if got := resolveSkillsBrand(f, &errBuf); got != core.BrandLark {
+		t.Errorf("resolved-config brand = %q, want lark", got)
+	}
+
+	// Layer 2: credential resolution fails, raw config file still supplies the
+	// brand (a locked keychain must not flip a Lark profile to Feishu).
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+	raw := `{"apps":[{"appId":"cli_x","appSecret":"test-secret","brand":"lark","users":[]}]}`
+	if err := os.WriteFile(filepath.Join(tmp, "config.json"), []byte(raw), 0600); err != nil {
+		t.Fatal(err)
+	}
+	f = &cmdutil.Factory{Config: func() (*core.CliConfig, error) { return nil, errors.New("keychain locked") }}
+	errBuf.Reset()
+	if got := resolveSkillsBrand(f, &errBuf); got != core.BrandLark {
+		t.Errorf("raw-config brand = %q, want lark", got)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("unexpected notice when raw config supplied the brand: %q", errBuf.String())
+	}
+
+	// Layer 3: nothing readable → default brand with a notice.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	errBuf.Reset()
+	if got := resolveSkillsBrand(f, &errBuf); got != core.BrandFeishu {
+		t.Errorf("fallback brand = %q, want feishu", got)
+	}
+	if !strings.Contains(errBuf.String(), "could not resolve the configured brand") {
+		t.Errorf("expected fallback notice, got %q", errBuf.String())
+	}
+}
+
+// The raw-config fallback must read the active profile, not the default one.
+func TestResolveSkillsBrand_RespectsActiveProfile(t *testing.T) {
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+	raw := `{"currentApp":"feishu-app","apps":[` +
+		`{"name":"feishu-app","appId":"cli_f","appSecret":"test-secret","brand":"feishu","users":[]},` +
+		`{"name":"lark-prof","appId":"cli_l","appSecret":"test-secret","brand":"lark","users":[]}]}`
+	if err := os.WriteFile(filepath.Join(tmp, "config.json"), []byte(raw), 0600); err != nil {
+		t.Fatal(err)
+	}
+	f := &cmdutil.Factory{
+		Invocation: cmdutil.InvocationContext{Profile: "lark-prof"},
+		Config:     func() (*core.CliConfig, error) { return nil, errors.New("keychain locked") },
+	}
+	var errBuf bytes.Buffer
+	if got := resolveSkillsBrand(f, &errBuf); got != core.BrandLark {
+		t.Errorf("brand = %q, want lark (the active profile's brand)", got)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("unexpected notice: %q", errBuf.String())
+	}
+}

extension/credential/env/env.go

@@ -9,6 +9,7 @@ import (
 	"os"
 
 	"github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 )
 
@@ -41,10 +42,7 @@ func (p *Provider) ResolveAccount(ctx context.Context) (*credential.Account, err
 			Reason:   envvars.CliAppID + " is set but no app secret or access token is available",
 		}
 	}
-	brand := credential.Brand(os.Getenv(envvars.CliBrand))
-	if brand == "" {
-		brand = credential.BrandFeishu
-	}
+	brand := credential.Brand(core.ParseBrand(os.Getenv(envvars.CliBrand)))
 	acct := &credential.Account{AppID: appID, AppSecret: appSecret, Brand: brand}
 
 	switch id := credential.Identity(os.Getenv(envvars.CliDefaultAs)); id {

extension/credential/env/env_test.go

@@ -22,13 +22,13 @@ func TestProvider_Name(t *testing.T) {
 func TestResolveAccount_BothSet(t *testing.T) {
 	t.Setenv(envvars.CliAppID, "cli_test")
 	t.Setenv(envvars.CliAppSecret, "secret_test")
-	t.Setenv(envvars.CliBrand, "feishu")
+	t.Setenv(envvars.CliBrand, " LARK ")
 
 	acct, err := (&Provider{}).ResolveAccount(context.Background())
 	if err != nil {
 		t.Fatal(err)
 	}
-	if acct.AppID != "cli_test" || acct.AppSecret != "secret_test" || acct.Brand != "feishu" {
+	if acct.AppID != "cli_test" || acct.AppSecret != "secret_test" || acct.Brand != "lark" {
 		t.Errorf("unexpected: %+v", acct)
 	}
 }

extension/credential/sidecar/provider.go

@@ -16,6 +16,7 @@ import (
 	"os"
 
 	"github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/sidecar"
 )
@@ -58,10 +59,7 @@ func (p *Provider) ResolveAccount(ctx context.Context) (*credential.Account, err
 		}
 	}
 
-	brand := credential.Brand(os.Getenv(envvars.CliBrand))
-	if brand == "" {
-		brand = credential.BrandFeishu
-	}
+	brand := credential.Brand(core.ParseBrand(os.Getenv(envvars.CliBrand)))
 
 	acct := &credential.Account{
 		AppID:     appID,

extension/credential/sidecar/provider_test.go

@@ -56,7 +56,7 @@ func TestResolveAccount_Active(t *testing.T) {
 	setEnv(t, envvars.CliAuthProxy, "http://127.0.0.1:16384")
 	setEnv(t, envvars.CliProxyKey, "test-key")
 	setEnv(t, envvars.CliAppID, "cli_test123")
-	setEnv(t, envvars.CliBrand, "lark")
+	setEnv(t, envvars.CliBrand, " LARK ")
 	unsetEnv(t, envvars.CliDefaultAs)
 	unsetEnv(t, envvars.CliStrictMode)
 

go.mod

@@ -7,8 +7,6 @@ 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
@@ -29,10 +27,7 @@ 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
@@ -47,21 +42,12 @@ 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
@@ -71,12 +57,10 @@ 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,8 +2,6 @@ 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=
@@ -52,42 +50,14 @@ 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=
@@ -100,8 +70,6 @@ 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=
@@ -129,8 +97,6 @@ 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=
@@ -171,8 +137,6 @@ 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=
@@ -190,7 +154,6 @@ 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

@@ -6,6 +6,7 @@ package auth
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -16,6 +17,46 @@ import (
 	"github.com/larksuite/cli/internal/core"
 )
 
+// Terminal registration outcomes, exposed for typed classification by callers.
+var (
+	ErrRegistrationDenied   = errors.New("app registration denied by user")
+	ErrRegistrationExpired  = errors.New("device code expired, please try again")
+	ErrRegistrationTimedOut = errors.New("app registration timed out, please try again")
+)
+
+// Protocol defaults, mirroring the official SDK registration flow.
+const (
+	registrationBootstrapBrand = core.BrandFeishu
+	defaultPollIntervalSeconds = 5
+	defaultExpireInSeconds     = 600
+	beginRequestTimeout        = 30 * time.Second
+	maxPollIntervalSeconds     = 60
+)
+
+// normalizedInterval clamps a non-positive poll interval to the protocol default.
+func normalizedInterval(v int) int {
+	if v <= 0 {
+		return defaultPollIntervalSeconds
+	}
+	return v
+}
+
+// normalizedExpireIn clamps a non-positive expiry budget to the protocol default.
+func normalizedExpireIn(v int) int {
+	if v <= 0 {
+		return defaultExpireInSeconds
+	}
+	return v
+}
+
+// registrationContextError maps a done context to its terminal reason, keeping the cause.
+func registrationContextError(ctx context.Context) error {
+	if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+		return fmt.Errorf("%w: %w", ErrRegistrationTimedOut, ctx.Err())
+	}
+	return fmt.Errorf("app registration cancelled: %w", ctx.Err())
+}
+
 // AppRegistrationResponse is the response from the app registration begin endpoint.
 type AppRegistrationResponse struct {
 	DeviceCode              string
@@ -31,11 +72,6 @@ type AppRegistrationResult struct {
 	ClientID     string
 	ClientSecret string
 	UserInfo     *AppRegUserInfo
-	// AuthMethods is the authoritative auth method(s) the app must use, as
-	// decided by the user/admin at confirmation (20260409 `auth_method` field).
-	// It may differ from what the client requested — e.g. selecting an existing
-	// client_secret app. Empty on older servers.
-	AuthMethods []string
 }
 
 // AppRegUserInfo contains user info returned from app registration.
@@ -44,109 +80,32 @@ type AppRegUserInfo struct {
 	TenantBrand string // "feishu" or "lark"
 }
 
-// AppRegistrationInit is the response from the app registration init endpoint.
-type AppRegistrationInit struct {
-	Nonce                string
-	SupportedAuthMethods []string // e.g. ["client_secret", "private_key_jwt"]
+// appRegistrationEndpoint returns the brand's accounts registration endpoint.
+func appRegistrationEndpoint(brand core.LarkBrand) string {
+	return core.ResolveEndpoints(brand).Accounts + PathAppRegistration
 }
 
-// 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(httpClient *http.Client) (*AppRegistrationInit, error) {
-	// Registration always begins against the feishu accounts host (mirrors begin).
-	endpoint := core.ResolveEndpoints(core.BrandFeishu).Accounts + PathAppRegistration
-
-	form := url.Values{}
-	form.Set("action", "init")
-	form.Set("archetype", "PersonalAgent")
-
-	req, err := http.NewRequest("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")}
-	if methods, ok := data["supported_auth_methods"].([]interface{}); ok {
-		for _, m := range methods {
-			if s, ok := m.(string); ok {
-				out.SupportedAuthMethods = append(out.SupportedAuthMethods, s)
-			}
-		}
-	}
-	if out.Nonce == "" {
-		return nil, fmt.Errorf("app registration init failed: server returned no nonce")
-	}
-	return out, nil
-}
-
-// RequestAppRegistration initiates the app registration device flow (begin step).
-func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, opts AppRegistrationBeginOptions, errOut io.Writer) (*AppRegistrationResponse, error) {
+// 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) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
 
-	ep := core.ResolveEndpoints(brand)
-	regEp := core.ResolveEndpoints(core.BrandFeishu) // registration begin always uses feishu
-	endpoint := regEp.Accounts + PathAppRegistration
+	ctx, cancel := context.WithTimeout(ctx, beginRequestTimeout)
+	defer cancel()
 
-	authMethod := opts.AuthMethod
-	if authMethod == "" {
-		authMethod = core.AuthMethodClientSecret
-	}
+	ep := core.ResolveEndpoints(brand)
+	endpoint := appRegistrationEndpoint(registrationBootstrapBrand)
 
 	form := url.Values{}
 	form.Set("action", "begin")
 	form.Set("archetype", "PersonalAgent")
-	form.Set("auth_method", authMethod)
+	form.Set("auth_method", "client_secret")
 	form.Set("request_user_info", "open_id tenant_brand")
-	if opts.AuthAttestation != "" {
-		form.Set("auth_attestation", opts.AuthAttestation)
-	}
-	// Restore flow: carry the existing app id so the server re-registers it
-	// rather than creating a new app.
-	if opts.RestoreAppID != "" {
-		form.Set("app_id", opts.RestoreAppID)
-	}
 
-	req, err := http.NewRequest("POST", endpoint, strings.NewReader(form.Encode()))
+	req, err := http.NewRequestWithContext(ctx, "POST", endpoint, strings.NewReader(form.Encode()))
 	if err != nil {
 		return nil, err
 	}
@@ -161,7 +120,7 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, opts
 
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return nil, fmt.Errorf("app registration failed: read body: %v", err)
+		return nil, fmt.Errorf("app registration failed: read body: %w", err)
 	}
 
 	var data map[string]interface{}
@@ -181,32 +140,26 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, opts
 		return nil, fmt.Errorf("app registration failed: %s", msg)
 	}
 
-	expiresIn := getInt(data, "expires_in", 300)
-	interval := getInt(data, "interval", 5)
+	// The protocol field is expire_in; accept the legacy expires_in spelling,
+	// then normalize to protocol defaults.
+	expiresIn := getInt(data, "expire_in", 0)
+	if expiresIn <= 0 {
+		expiresIn = getInt(data, "expires_in", 0)
+	}
+	expiresIn = normalizedExpireIn(expiresIn)
+	interval := normalizedInterval(getInt(data, "interval", 0))
+
+	deviceCode := getStr(data, "device_code")
+	if deviceCode == "" {
+		return nil, fmt.Errorf("app registration failed: response missing device_code")
+	}
 
 	userCode := getStr(data, "user_code")
 	verificationUri := getStr(data, "verification_uri")
-	// 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)
-	}
+	verificationUriComplete := fmt.Sprintf("%s/page/cli?user_code=%s", ep.Open, userCode)
 
 	return &AppRegistrationResponse{
-		DeviceCode:              getStr(data, "device_code"),
+		DeviceCode:              deviceCode,
 		UserCode:                getStr(data, "user_code"),
 		VerificationUri:         verificationUri,
 		VerificationUriComplete: verificationUriComplete,
@@ -215,135 +168,111 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, opts
 	}, 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
-	}
-}
-
 // BuildVerificationURL appends CLI tracking parameters to the verification URL.
-// 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 {
+func BuildVerificationURL(baseURL, cliVersion string) string {
 	sep := "&"
 	if !strings.Contains(baseURL, "?") {
 		sep = "?"
 	}
-	out := baseURL + sep + "lpv=" + url.QueryEscape(cliVersion) +
+	return 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
 }
 
-// PollAppRegistration polls the app registration endpoint until the app is created or the flow times out.
-// If the result has ClientSecret == "" and UserInfo.TenantBrand == "lark", the caller should
-// retry with BrandLark to get the secret from accounts.larksuite.com.
-func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) (*AppRegistrationResult, error) {
+// pollOnce performs one ctx-bound poll request and decodes the payload.
+func pollOnce(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, deviceCode string) (map[string]interface{}, error) {
+	form := url.Values{}
+	form.Set("action", "poll")
+	form.Set("device_code", deviceCode)
+
+	req, err := http.NewRequestWithContext(ctx, "POST", appRegistrationEndpoint(brand), strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("poll request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("poll network error: %w", err)
+	}
+	defer resp.Body.Close()
+	logHTTPResponse(resp)
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("poll read error: %w", err)
+	}
+	var data map[string]interface{}
+	if err := json.Unmarshal(body, &data); err != nil {
+		return nil, fmt.Errorf("poll parse error: %w", err)
+	}
+	return data, nil
+}
+
+// RegisterAppWithDiscovery polls for credentials, mirroring the official SDK
+// flow: the first poll and the (at most one) cross-brand switch are immediate,
+// non-error responses without complete credentials keep polling, and one
+// deadline from the begin expiry bounds all waits and in-flight requests.
+// The returned brand is the one the credentials were issued on.
+func RegisterAppWithDiscovery(ctx context.Context, httpClient *http.Client, resp *AppRegistrationResponse, errOut io.Writer) (*AppRegistrationResult, core.LarkBrand, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
 
-	const maxPollInterval = 60
-	const maxPollAttempts = 200
+	// Interval and expiry arrive normalized from begin-response parsing
+	// (normalizedInterval floors them there); the loop trusts them as-is.
+	interval := resp.Interval
+	ctx, cancel := context.WithDeadline(ctx,
+		time.Now().Add(time.Duration(resp.ExpiresIn)*time.Second))
+	defer cancel()
 
-	ep := core.ResolveEndpoints(brand)
-	endpoint := ep.Accounts + PathAppRegistration
-	deadline := time.Now().Add(time.Duration(expiresIn) * time.Second)
-	currentInterval := interval
-	attempts := 0
+	currentBrand := registrationBootstrapBrand
+	effectiveBrand := currentBrand
+	switched := false
+	waitBeforePoll := false
 
-	for time.Now().Before(deadline) && attempts < maxPollAttempts {
-		attempts++
+	for {
+		if waitBeforePoll {
+			select {
+			case <-time.After(time.Duration(interval) * time.Second):
+			case <-ctx.Done():
+				return nil, effectiveBrand, registrationContextError(ctx)
+			}
+		}
+		waitBeforePoll = true
 		if ctx.Err() != nil {
-			return nil, fmt.Errorf("polling was cancelled")
+			return nil, effectiveBrand, registrationContextError(ctx)
 		}
 
-		select {
-		case <-time.After(time.Duration(currentInterval) * time.Second):
-		case <-ctx.Done():
-			return nil, fmt.Errorf("polling was cancelled")
-		}
-
-		form := url.Values{}
-		form.Set("action", "poll")
-		form.Set("device_code", deviceCode)
-
-		req, err := http.NewRequest("POST", endpoint, strings.NewReader(form.Encode()))
+		data, err := pollOnce(ctx, httpClient, currentBrand, resp.DeviceCode)
 		if err != nil {
-			continue
-		}
-		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-
-		resp, err := httpClient.Do(req)
-		if err != nil {
-			fmt.Fprintf(errOut, "[lark-cli] [WARN] app-registration: poll network error: %v\n", err)
-			currentInterval = minInt(currentInterval+1, maxPollInterval)
-			continue
-		}
-		logHTTPResponse(resp)
-
-		body, err := io.ReadAll(resp.Body)
-		resp.Body.Close()
-		if err != nil {
-			fmt.Fprintf(errOut, "[lark-cli] [WARN] app-registration: poll read error: %v\n", err)
-			currentInterval = minInt(currentInterval+1, maxPollInterval)
+			fmt.Fprintf(errOut, "[lark-cli] [WARN] app-registration: %v\n", err)
+			interval = minInt(interval+1, maxPollIntervalSeconds)
 			continue
 		}
 
-		var data map[string]interface{}
-		if err := json.Unmarshal(body, &data); err != nil {
-			fmt.Fprintf(errOut, "[lark-cli] [WARN] app-registration: poll parse error: %v\n", err)
-			currentInterval = minInt(currentInterval+1, maxPollInterval)
-			continue
+		// A cross-brand tenant report switches the polled domain (once,
+		// immediately) regardless of the accompanying status — the signal can
+		// arrive alongside authorization_pending, mirroring the official SDK.
+		if !switched {
+			if userInfoRaw, ok := data["user_info"].(map[string]interface{}); ok {
+				if tb := getStr(userInfoRaw, "tenant_brand"); tb != "" {
+					if actual := core.ParseBrand(tb); actual != currentBrand {
+						currentBrand = actual
+						effectiveBrand = actual
+						switched = true
+						waitBeforePoll = false
+						continue
+					}
+				}
+			}
 		}
 
 		errStr := getStr(data, "error")
-
-		// Success: app id present (server field is named client_id).
-		if errStr == "" && getStr(data, "client_id") != "" {
+		if errStr == "" {
 			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{
@@ -351,34 +280,37 @@ func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand cor
 					TenantBrand: getStr(userInfoRaw, "tenant_brand"),
 				}
 			}
-			return result, nil
+
+			if result.ClientID != "" && result.ClientSecret != "" {
+				// 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 != "" &&
+					core.ParseBrand(result.UserInfo.TenantBrand) != effectiveBrand {
+					return nil, effectiveBrand, fmt.Errorf("app registration returned credentials with a contradictory tenant brand %q", result.UserInfo.TenantBrand)
+				}
+				return result, effectiveBrand, nil
+			}
+			// Incomplete credentials without an error: keep polling.
+			continue
 		}
 
 		switch errStr {
 		case "authorization_pending":
 			continue
 		case "slow_down":
-			currentInterval = minInt(currentInterval+5, maxPollInterval)
-			fmt.Fprintf(errOut, "[lark-cli] app-registration: slow_down, interval increased to %ds\n", currentInterval)
+			interval = minInt(interval+5, maxPollIntervalSeconds)
+			fmt.Fprintf(errOut, "[lark-cli] app-registration: slow_down, interval increased to %ds\n", interval)
 			continue
 		case "access_denied":
-			return nil, fmt.Errorf("app registration denied by user")
+			return nil, effectiveBrand, ErrRegistrationDenied
 		case "expired_token", "invalid_grant":
-			return nil, fmt.Errorf("device code expired, please try again")
+			return nil, effectiveBrand, ErrRegistrationExpired
 		}
 
 		desc := getStr(data, "error_description")
 		if desc == "" {
 			desc = errStr
 		}
-		if desc == "" {
-			desc = "Unknown error"
-		}
-		return nil, fmt.Errorf("app registration failed: %s", desc)
+		return nil, effectiveBrand, fmt.Errorf("app registration failed: %s", desc)
 	}
-
-	if attempts >= maxPollAttempts {
-		fmt.Fprintf(errOut, "[lark-cli] [WARN] app-registration: max poll attempts (%d) reached\n", maxPollAttempts)
-	}
-	return nil, fmt.Errorf("app registration timed out, please try again")
 }

internal/auth/app_registration_test.go

@@ -4,29 +4,36 @@
 package auth
 
 import (
+	"context"
+	"errors"
 	"io"
 	"net/http"
-	"net/url"
-	"slices"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/core"
 	"github.com/smartystreets/goconvey/convey"
 )
 
+// jsonResponse builds a canned registration response (transport fakes reuse
+// roundTripFunc from device_flow_test.go).
+func jsonResponse(body string) *http.Response {
+	return &http.Response{
+		StatusCode: http.StatusOK,
+		Body:       io.NopCloser(strings.NewReader(body)),
+		Header:     make(http.Header),
+	}
+}
+
 // Test_BuildVerificationURL verifies that tracking parameters are correctly appended.
 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(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.ShouldContainSubstring, "?lpv=1.0.0")
+			convey.So(result, convey.ShouldContainSubstring, "&ocv=1.0.0")
+			convey.So(result, convey.ShouldContainSubstring, "&from=cli")
 			convey.So(result, convey.ShouldStartWith, "https://example.com/verify?")
 		})
 	})
@@ -40,232 +47,359 @@ 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(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(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(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(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 app_id.
-	if body.Has("app_id") {
-		t.Errorf("app_id should be absent when RestoreAppID is empty, got %q", body.Get("app_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(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("app_id") != "cli_restore_me" {
-		t.Errorf("app_id = %q, want cli_restore_me", body.Get("app_id"))
-	}
-}
-
-func TestRequestAppRegistration_VerificationURICompleteFallback(t *testing.T) {
+func TestAppRegistrationEndpoint(t *testing.T) {
 	cases := []struct {
-		name string
-		resp string
-		want string
+		brand core.LarkBrand
+		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",
-		},
+		{core.BrandFeishu, "https://accounts.feishu.cn" + PathAppRegistration},
+		{core.BrandLark, "https://accounts.larksuite.com" + PathAppRegistration},
 	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			var body url.Values
-			hc := captureClient(&body, tc.resp)
-			got, err := RequestAppRegistration(hc, core.BrandFeishu, AppRegistrationBeginOptions{}, nil)
+	for _, c := range cases {
+		if got := appRegistrationEndpoint(c.brand); got != c.want {
+			t.Errorf("brand %q: endpoint = %q, want %q", c.brand, got, c.want)
+		}
+	}
+}
+
+func TestRequestAppRegistration_UsesFeishuBootstrapAndConfiguredVerificationBrand(t *testing.T) {
+	cases := []struct {
+		brand            core.LarkBrand
+		verificationHost string
+	}{
+		{core.BrandFeishu, "open.feishu.cn"},
+		{core.BrandLark, "open.larksuite.com"},
+	}
+	for _, c := range cases {
+		t.Run(string(c.brand), func(t *testing.T) {
+			client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				if got, want := r.URL.Host, "accounts.feishu.cn"; got != want {
+					t.Errorf("begin host = %q, want bootstrap host %q", got, want)
+				}
+				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)
 			if err != nil {
-				t.Fatal(err)
+				t.Fatalf("RequestAppRegistration(%q) error = %v", c.brand, err)
 			}
-			if got.VerificationUriComplete != tc.want {
-				t.Errorf("VerificationUriComplete = %q, want %q", got.VerificationUriComplete, tc.want)
+			if !strings.HasPrefix(resp.VerificationUriComplete, "https://"+c.verificationHost+"/page/cli?") {
+				t.Errorf("verification URL = %q, want host %q", resp.VerificationUriComplete, c.verificationHost)
 			}
 		})
 	}
 }
 
-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)
+// Full Lark routing contract: Lark selects the Lark verification page, while
+// registration bootstraps on Feishu and switches only after the tenant signal.
+// The Lark credential response omits user_info, so the effective domain must
+// still determine the saved brand.
+func TestRegisterAppWithDiscovery_LarkFlowUsesProtocolBootstrap(t *testing.T) {
+	var calls []string
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		if err := r.ParseForm(); err != nil {
+			t.Fatalf("parse form: %v", err)
+		}
+		action := r.Form.Get("action")
+		calls = append(calls, action+"@"+r.URL.Host)
+		if action == "begin" {
+			return jsonResponse(`{"device_code":"device","user_code":"TEST-CODE","expire_in":60,"interval":0}`), nil
+		}
+		switch r.URL.Host {
+		case "accounts.feishu.cn":
+			return jsonResponse(`{"user_info":{"open_id":"ou_x","tenant_brand":"lark"}}`), nil
+		case "accounts.larksuite.com":
+			return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret"}`), nil
+		}
+		t.Errorf("unexpected host polled: %s", r.URL.Host)
+		return jsonResponse(`{}`), nil
+	})}
+	resp, err := RequestAppRegistration(context.Background(), client, core.BrandLark, io.Discard)
+	if err != nil {
+		t.Fatalf("RequestAppRegistration error = %v", err)
 	}
-	if got := parseAuthMethods("client_secret private_key_jwt"); len(got) != 2 || got[1] != "private_key_jwt" {
-		t.Errorf("string form = %v", got)
+	if got, want := resp.VerificationUriComplete, "https://open.larksuite.com/page/cli?user_code=TEST-CODE"; got != want {
+		t.Errorf("verification URL = %q, want %q", got, want)
 	}
-	if got := parseAuthMethods(nil); got != nil {
-		t.Errorf("nil form = %v, want nil", got)
+
+	result, finalBrand, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
+	}
+	if finalBrand != core.BrandLark {
+		t.Errorf("finalBrand = %q, want %q (credentials were issued on the lark domain)", finalBrand, core.BrandLark)
+	}
+	if result.ClientID != "cli_x" || result.ClientSecret != "test-secret" {
+		t.Errorf("credentials = (%q, %q), want (cli_x, test-secret)", result.ClientID, result.ClientSecret)
+	}
+	want := []string{"begin@accounts.feishu.cn", "poll@accounts.feishu.cn", "poll@accounts.larksuite.com"}
+	if len(calls) != len(want) {
+		t.Fatalf("calls = %v, want %v", calls, want)
+	}
+	for i := range want {
+		if calls[i] != want[i] {
+			t.Errorf("calls = %v, want %v", calls, want)
+			break
+		}
 	}
 }
 
-func TestRequestAppRegistration_BeginPrivateKeyJWT(t *testing.T) {
-	var body url.Values
-	hc := captureClient(&body, beginRespJSON)
+// Plain path: the bootstrap domain can return complete Feishu credentials in
+// one poll, even when user_info is absent.
+func TestRegisterAppWithDiscovery_BootstrapBrandSinglePoll(t *testing.T) {
+	polls := 0
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		polls++
+		if got, want := r.URL.Host, "accounts.feishu.cn"; got != want {
+			t.Errorf("poll host = %q, want %q", got, want)
+		}
+		return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret"}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 5}
 
-	opts := AppRegistrationBeginOptions{
-		AuthMethod:      core.AuthMethodPrivateKeyJWT,
-		AuthAttestation: "header.claims.sig",
+	_, finalBrand, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
 	}
-	if _, err := RequestAppRegistration(hc, core.BrandFeishu, opts, nil); err != nil {
-		t.Fatal(err)
+	if finalBrand != core.BrandFeishu {
+		t.Errorf("finalBrand = %q, want %q", finalBrand, core.BrandFeishu)
 	}
-	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 polls != 1 {
+		t.Errorf("polls = %d, want 1", polls)
 	}
 }
 
-func TestRequestAppRegistration_BeginPrivateKeyJWTExistingAppID(t *testing.T) {
-	var body url.Values
-	hc := captureClient(&body, beginRespJSON)
+// The discovery deadline must cancel in-flight requests: the fake transport
+// hangs until the request context is done.
+func TestRegisterAppWithDiscovery_DeadlineBoundsInFlightRequests(t *testing.T) {
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		<-r.Context().Done()
+		return nil, r.Context().Err()
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 1}
 
-	opts := AppRegistrationBeginOptions{
-		AuthMethod:      core.AuthMethodPrivateKeyJWT,
-		AuthAttestation: "header.claims.sig",
-		RestoreAppID:    "cli_existing",
+	start := time.Now()
+	_, _, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err == nil {
+		t.Fatal("expected timeout error, got nil")
 	}
-	if _, err := RequestAppRegistration(hc, core.BrandFeishu, opts, nil); err != nil {
-		t.Fatal(err)
+	if !strings.Contains(err.Error(), "timed out") {
+		t.Errorf("error = %v, want a timed-out terminal reason", 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("app_id") != "cli_existing" {
-		t.Errorf("app_id = %q, want cli_existing", body.Get("app_id"))
+	if elapsed := time.Since(start); elapsed > 3*time.Second {
+		t.Errorf("discovery not bounded by its deadline: took %v", elapsed)
 	}
 }
+
+// Empty payloads and incomplete same-brand responses are not terminal.
+func TestRegisterAppWithDiscovery_PollsUntilCredentials(t *testing.T) {
+	responses := []string{
+		`{}`,
+		`{"client_id":"cli_x","user_info":{"open_id":"ou_x","tenant_brand":"feishu"}}`,
+		`{"client_id":"cli_x","client_secret":"test-secret","user_info":{"open_id":"ou_x","tenant_brand":"feishu"}}`,
+	}
+	polls := 0
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		body := responses[polls]
+		polls++
+		return jsonResponse(body), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 5}
+
+	result, finalBrand, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
+	}
+	if polls != 3 {
+		t.Errorf("polls = %d, want 3", polls)
+	}
+	if result.ClientSecret != "test-secret" || finalBrand != core.BrandFeishu {
+		t.Errorf("result = (%q, %q), want (test-secret, feishu)", result.ClientSecret, finalBrand)
+	}
+}
+
+// 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) {
+	var polledHosts []string
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		polledHosts = append(polledHosts, r.URL.Host)
+		if r.URL.Host == "accounts.feishu.cn" {
+			return jsonResponse(`{"user_info":{"open_id":"ou_x","tenant_brand":"lark"}}`), nil
+		}
+		return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret"}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 5, ExpiresIn: 60}
+
+	start := time.Now()
+	result, finalBrand, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
+	}
+	if elapsed := time.Since(start); elapsed > 2*time.Second {
+		t.Errorf("discovery waited an interval somewhere: took %v", elapsed)
+	}
+	if finalBrand != core.BrandLark || result.ClientSecret != "test-secret" {
+		t.Errorf("result = (%q, %q), want (test-secret, lark)", result.ClientSecret, finalBrand)
+	}
+	want := []string{"accounts.feishu.cn", "accounts.larksuite.com"}
+	if len(polledHosts) != 2 || polledHosts[0] != want[0] || polledHosts[1] != want[1] {
+		t.Errorf("polled hosts = %v, want %v", polledHosts, want)
+	}
+}
+
+// Denial and expiry map to sentinels; cancellation preserves its cause.
+func TestRegisterAppWithDiscovery_TerminalSentinels(t *testing.T) {
+	deny := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		return jsonResponse(`{"error":"access_denied"}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 5}
+	_, _, err := RegisterAppWithDiscovery(context.Background(), deny, resp, io.Discard)
+	if !errors.Is(err, ErrRegistrationDenied) {
+		t.Errorf("denied err = %v, want ErrRegistrationDenied", err)
+	}
+
+	expired := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		return jsonResponse(`{"error":"expired_token"}`), nil
+	})}
+	_, _, err = RegisterAppWithDiscovery(context.Background(), expired, resp, io.Discard)
+	if !errors.Is(err, ErrRegistrationExpired) {
+		t.Errorf("expired err = %v, want ErrRegistrationExpired", err)
+	}
+
+	cancelledCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, _, err = RegisterAppWithDiscovery(cancelledCtx, deny, resp, io.Discard)
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("cancelled err = %v, want a context.Canceled cause", err)
+	}
+}
+
+// Begin parsing: expire_in (legacy expires_in fallback), normalization, and
+// required device_code.
+func TestRequestAppRegistration_ProtocolFields(t *testing.T) {
+	serve := func(body string) *http.Client {
+		return &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+			return jsonResponse(body), nil
+		})}
+	}
+
+	resp, err := RequestAppRegistration(context.Background(),
+		serve(`{"device_code":"d","expire_in":60,"interval":3}`), core.BrandFeishu, io.Discard)
+	if err != nil {
+		t.Fatalf("begin error = %v", err)
+	}
+	if resp.ExpiresIn != 60 || resp.Interval != 3 {
+		t.Errorf("parsed (expire=%d, interval=%d), want (60, 3)", resp.ExpiresIn, resp.Interval)
+	}
+
+	resp, err = RequestAppRegistration(context.Background(),
+		serve(`{"device_code":"d","expires_in":45}`), core.BrandFeishu, io.Discard)
+	if err != nil {
+		t.Fatalf("legacy begin error = %v", err)
+	}
+	if resp.ExpiresIn != 45 || resp.Interval != 5 {
+		t.Errorf("legacy parsed (expire=%d, interval=%d), want (45, 5 — normalized default)", resp.ExpiresIn, resp.Interval)
+	}
+
+	resp, err = RequestAppRegistration(context.Background(),
+		serve(`{"device_code":"d","interval":0}`), core.BrandFeishu, io.Discard)
+	if err != nil {
+		t.Fatalf("defaults begin error = %v", err)
+	}
+	if resp.ExpiresIn != 600 || resp.Interval != 5 {
+		t.Errorf("defaults parsed (expire=%d, interval=%d), want (600, 5)", resp.ExpiresIn, resp.Interval)
+	}
+
+	if _, err := RequestAppRegistration(context.Background(),
+		serve(`{"interval":5}`), core.BrandFeishu, io.Discard); err == nil {
+		t.Error("missing device_code: expected error, got nil")
+	}
+}
+
+// A tenant signal arriving alongside authorization_pending must still switch
+// the polled domain (the official SDK checks the signal before the error).
+func TestRegisterAppWithDiscovery_PendingWithTenantSignalSwitches(t *testing.T) {
+	var polledHosts []string
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		polledHosts = append(polledHosts, r.URL.Host)
+		if r.URL.Host == "accounts.feishu.cn" {
+			return jsonResponse(`{"error":"authorization_pending","user_info":{"tenant_brand":"lark"}}`), nil
+		}
+		return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret"}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 5}
+
+	result, finalBrand, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil", err)
+	}
+	if finalBrand != core.BrandLark || result.ClientSecret != "test-secret" {
+		t.Errorf("result = (%q, %q), want (test-secret, lark)", result.ClientSecret, finalBrand)
+	}
+	want := []string{"accounts.feishu.cn", "accounts.larksuite.com"}
+	if len(polledHosts) != 2 || polledHosts[0] != want[0] || polledHosts[1] != want[1] {
+		t.Errorf("polled hosts = %v, want %v", polledHosts, want)
+	}
+}
+
+// Polling has no attempt cap: only the expiry budget terminates the loop.
+func TestRegisterAppWithDiscovery_NoAttemptCap(t *testing.T) {
+	polls := 0
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		polls++
+		if polls <= 250 {
+			return jsonResponse(`{"error":"authorization_pending"}`), nil
+		}
+		return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret"}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 30}
+
+	result, _, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err != nil {
+		t.Fatalf("RegisterAppWithDiscovery error = %v, want nil (no attempts cap)", err)
+	}
+	if polls != 251 || result.ClientSecret != "test-secret" {
+		t.Errorf("polls = %d (want 251), secret = %q", polls, result.ClientSecret)
+	}
+}
+
+// A final tenant report contradicting the issuing domain is a protocol
+// violation, not a brand override: the saved brand must never diverge from
+// the domain that issued the credentials.
+func TestRegisterAppWithDiscovery_ContradictoryFinalBrandFails(t *testing.T) {
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		if r.URL.Host == "accounts.feishu.cn" {
+			return jsonResponse(`{"error":"authorization_pending","user_info":{"tenant_brand":"lark"}}`), nil
+		}
+		// The lark domain issues credentials but reports a feishu tenant.
+		return jsonResponse(`{"client_id":"cli_x","client_secret":"test-secret","user_info":{"tenant_brand":"feishu"}}`), nil
+	})}
+	resp := &AppRegistrationResponse{DeviceCode: "device", Interval: 0, ExpiresIn: 5}
+
+	_, _, err := RegisterAppWithDiscovery(context.Background(), client, resp, io.Discard)
+	if err == nil || !strings.Contains(err.Error(), "contradictory tenant brand") {
+		t.Errorf("err = %v, want contradictory-tenant-brand protocol error", err)
+	}
+}
+
+// A cancelled body read during begin must keep its context cause so the
+// command layer classifies it as a cancellation, not an API failure.
+func TestRequestAppRegistration_BodyReadCancelKeepsCause(t *testing.T) {
+	client := &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body:       io.NopCloser(&errReader{err: context.Canceled}),
+			Header:     make(http.Header),
+		}, nil
+	})}
+	_, err := RequestAppRegistration(context.Background(), client, core.BrandFeishu, io.Discard)
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("err = %v, want a context.Canceled cause", err)
+	}
+}
+
+type errReader struct{ err error }
+
+func (r *errReader) Read([]byte) (int, error) { return 0, r.err }

internal/auth/client_auth.go

@@ -1,78 +0,0 @@
-// 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/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
-}
-
-// 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,
-		Signer:     keysigner.Active(),
-	}
-}
-
-func (c ClientAuth) isPrivateKeyJWT() bool { return c.AuthMethod == core.AuthMethodPrivateKeyJWT }
-
-// 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
-	}
-	helper, err := keylesshelper.Resolve()
-	if err != nil {
-		return false, err
-	}
-	if helper == nil && c.Signer == nil {
-		return false, fmt.Errorf("private_key_jwt requires a key signer, but none is available on this build")
-	}
-	assertionType, assertion, err := SignClientAssertion(ctx, c.Signer, helper, 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

@@ -1,190 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/sha256"
-	"encoding/json"
-	"net/url"
-	"os"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/auth/jwt"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/keylesshelper"
-	"github.com/larksuite/cli/internal/keysigner"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// fakeAuthSigner is a real in-memory ECDSA P-256 signer for client-auth tests.
-type fakeAuthSigner struct{ key *ecdsa.PrivateKey }
-
-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_MalformedConfigDoesNotFallback(t *testing.T) {
-	signer := newFakeAuthSigner(t)
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := vfs.WriteFile(core.GetConfigPath(), []byte("{not-json"), 0600); err != nil {
-		t.Fatalf("write malformed config: %v", err)
-	}
-
-	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT, Signer: signer, KeyLabel: "k"}
-	form := url.Values{}
-	used, err := ca.applyClientAssertion(context.Background(), form, "aud")
-	if err == nil {
-		t.Fatal("expected malformed config error instead of platform-signer fallback")
-	}
-	if used || form.Has("client_assertion") {
-		t.Fatalf("malformed config used fallback signer: used=%v form=%v", used, form)
-	}
-	if !strings.Contains(err.Error(), "config.json keylessSignerCmd") || !strings.Contains(err.Error(), core.GetConfigPath()) {
-		t.Fatalf("error = %q, want signer source and config path", err)
-	}
-}
-
-func TestSignClientAssertion_KeylessHelper(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, keylessHelperTestCommand(t))
-	t.Setenv("LARKSUITE_CLI_KEYLESS_HELPER_ASSERT", `{"op":"sign-assertion","keyRef":"agent-key","clientId":"cli_a","aud":"aud"}`)
-
-	helper, err := keylesshelper.Resolve()
-	if err != nil {
-		t.Fatal(err)
-	}
-	assertionType, assertion, err := SignClientAssertion(context.Background(), nil, helper, "agent-key", "cli_a", "aud")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if assertionType != jwt.ClientAssertionType || assertion != "helper.jwt" {
-		t.Fatalf("assertion = (%q, %q)", assertionType, assertion)
-	}
-}
-
-func keylessHelperTestCommand(t *testing.T) string {
-	t.Helper()
-	argv, err := json.Marshal([]string{os.Args[0], "-test.run=TestKeylessHelperProcess", "--"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	return string(argv)
-}
-
-func TestKeylessHelperProcess(t *testing.T) {
-	want := os.Getenv("LARKSUITE_CLI_KEYLESS_HELPER_ASSERT")
-	if want == "" {
-		return
-	}
-	var got map[string]any
-	if err := json.NewDecoder(os.Stdin).Decode(&got); err != nil {
-		t.Fatal(err)
-	}
-	var expected map[string]any
-	if err := json.Unmarshal([]byte(want), &expected); err != nil {
-		t.Fatal(err)
-	}
-	for k, v := range expected {
-		if got[k] != v {
-			t.Fatalf("%s = %v, want %v; request=%v", k, got[k], v, got)
-		}
-	}
-	_ = json.NewEncoder(os.Stdout).Encode(map[string]any{
-		"ok":                    true,
-		"client_assertion_type": jwt.ClientAssertionType,
-		"client_assertion":      "helper.jwt",
-	})
-	os.Exit(0)
-}
-
-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(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
+func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -77,26 +77,18 @@ func RequestDeviceAuthorization(ctx context.Context, httpClient *http.Client, ca
 		}
 	}
 
+	basicAuth := base64.StdEncoding.EncodeToString([]byte(appId + ":" + appSecret))
+
 	form := url.Values{}
-	form.Set("client_id", ca.AppID)
+	form.Set("client_id", appId)
 	form.Set("scope", scope)
 
-	// 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()))
+	req, err := http.NewRequest("POST", endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
 	if err != nil {
 		return nil, err
 	}
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	if !usedAssertion {
-		basicAuth := base64.StdEncoding.EncodeToString([]byte(ca.AppID + ":" + ca.AppSecret))
-		req.Header.Set("Authorization", "Basic "+basicAuth)
-	}
+	req.Header.Set("Authorization", "Basic "+basicAuth)
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
@@ -147,7 +139,7 @@ func RequestDeviceAuthorization(ctx context.Context, httpClient *http.Client, ca
 }
 
 // PollDeviceToken polls the token endpoint until authorization completes or times out.
-func PollDeviceToken(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
+func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -179,16 +171,10 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, ca ClientAuth
 		form := url.Values{}
 		form.Set("grant_type", "urn:ietf:params:oauth:grant-type:device_code")
 		form.Set("device_code", deviceCode)
-		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)
-		}
+		form.Set("client_id", appId)
+		form.Set("client_secret", appSecret)
 
-		req, err := http.NewRequestWithContext(ctx, "POST", endpoints.Token, strings.NewReader(form.Encode()))
+		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
 		if err != nil {
 			continue
 		}

internal/auth/device_flow_test.go

@@ -7,10 +7,8 @@ import (
 	"bytes"
 	"context"
 	"fmt"
-	"io"
 	"log"
 	"net/http"
-	"net/url"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -85,7 +83,7 @@ func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
 	})
 	t.Cleanup(restore)
 
-	_, err := RequestDeviceAuthorization(context.Background(), httpmock.NewClient(reg), ClientAuth{AppID: "cli_a", AppSecret: "test-secret"}, core.BrandFeishu, "", nil)
+	_, err := RequestDeviceAuthorization(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "", nil)
 	if err != nil {
 		t.Fatalf("RequestDeviceAuthorization() error: %v", err)
 	}
@@ -108,66 +106,6 @@ 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{
@@ -267,7 +205,7 @@ func TestPollDeviceToken_DefaultsZeroIntervalToFiveSeconds(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 	t.Cleanup(cancel)
 
-	result := PollDeviceToken(ctx, client, ClientAuth{AppID: "cli_a", AppSecret: "test-secret"}, core.BrandFeishu, "device-code", 0, 10, nil)
+	result := PollDeviceToken(ctx, client, "cli_a", "secret_b", core.BrandFeishu, "device-code", 0, 10, nil)
 	if result == nil {
 		t.Fatal("PollDeviceToken() returned nil result")
 	}

internal/auth/jwt/jwt.go

@@ -1,153 +0,0 @@
-// 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": the server's client_assertion generalizedValidation
-// REQUIRES `typ == "JWT"` (rejects otherwise with "malformed client assertion
-// jwt"), even though the spec examples (§8.1/§8.2) 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

@@ -1,254 +0,0 @@
-// 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 (server generalizedValidation requires typ)", 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,7 +21,6 @@ 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"
 )
 
@@ -38,10 +37,7 @@ type UATCallOptions struct {
 	AppId      string
 	AppSecret  string
 	Domain     core.LarkBrand
-	AuthMethod string           // "" == client_secret; core.AuthMethodPrivateKeyJWT
-	KeyLabel   string           // TEE key handle for private_key_jwt
-	Signer     keysigner.Signer // active signer for private_key_jwt
-	ErrOut     io.Writer        // diagnostic/status output (caller injects f.IOStreams.ErrOut)
+	ErrOut     io.Writer // diagnostic/status output (caller injects f.IOStreams.ErrOut)
 }
 
 // UATStatus represents the status of a user access token.
@@ -65,9 +61,6 @@ func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions {
 		AppId:      cfg.AppID,
 		AppSecret:  cfg.AppSecret,
 		Domain:     cfg.Brand,
-		AuthMethod: cfg.AuthMethod,
-		KeyLabel:   cfg.KeyLabel,
-		Signer:     keysigner.Active(),
 		ErrOut:     errOut,
 	}
 }
@@ -200,14 +193,7 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 		form.Set("grant_type", "refresh_token")
 		form.Set("refresh_token", stored.RefreshToken)
 		form.Set("client_id", opts.AppId)
-		ca := ClientAuth{AppID: opts.AppId, AppSecret: opts.AppSecret, AuthMethod: opts.AuthMethod, Signer: opts.Signer, KeyLabel: opts.KeyLabel}
-		usedAssertion, caErr := ca.applyClientAssertion(context.Background(), form, core.OpenAPIAudience(opts.Domain))
-		if caErr != nil {
-			return nil, caErr
-		}
-		if !usedAssertion {
-			form.Set("client_secret", opts.AppSecret)
-		}
+		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,23 +38,3 @@ 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",
-	}
-	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)
-	}
-}

internal/core/config.go

@@ -36,14 +36,6 @@ type AppUser struct {
 	UserName   string `json:"userName"`
 }
 
-// Auth methods for app credentials. An empty AppConfig.AuthMethod means the
-// default, client_secret.
-const (
-	AuthMethodClientSecret  = "client_secret"   // app_id + app_secret
-	authMethodPKJWTValue    = "private_key_jwt" // TEE-signed client_assertion; no app secret
-	AuthMethodPrivateKeyJWT = authMethodPKJWTValue
-)
-
 // AppConfig is a per-app configuration entry (stored format — secrets may be unresolved).
 type AppConfig struct {
 	Name       string      `json:"name,omitempty"`
@@ -54,15 +46,6 @@ type AppConfig struct {
 	DefaultAs  Identity    `json:"defaultAs,omitempty"` // AsUser | AsBot | AsAuto
 	StrictMode *StrictMode `json:"strictMode,omitempty"`
 	Users      []AppUser   `json:"users"`
-
-	// AuthMethod selects how tokens are minted. Empty == AuthMethodClientSecret
-	// (back-compat). AuthMethodPrivateKeyJWT uses a TEE-held key (see KeyRef) to
-	// sign client_assertion JWTs instead of sending an app secret.
-	AuthMethod string `json:"authMethod,omitempty"`
-	// KeyRef references the non-exportable signing key for private_key_jwt.
-	// Source is "tee" and ID is the backend key label; the actual key never
-	// leaves the secure backend, so this is a handle, not secret material.
-	KeyRef *SecretRef `json:"keyRef,omitempty"`
 }
 
 // ProfileName returns the display name for this app config.
@@ -76,11 +59,10 @@ func (a *AppConfig) ProfileName() string {
 
 // MultiAppConfig is the multi-app config file format.
 type MultiAppConfig struct {
-	StrictMode       StrictMode  `json:"strictMode,omitempty"`
-	CurrentApp       string      `json:"currentApp,omitempty"`
-	PreviousApp      string      `json:"previousApp,omitempty"`
-	KeylessSignerCmd string      `json:"keylessSignerCmd,omitempty"`
-	Apps             []AppConfig `json:"apps"`
+	StrictMode  StrictMode  `json:"strictMode,omitempty"`
+	CurrentApp  string      `json:"currentApp,omitempty"`
+	PreviousApp string      `json:"previousApp,omitempty"`
+	Apps        []AppConfig `json:"apps"`
 }
 
 // CurrentAppConfig returns the currently active app config.
@@ -179,9 +161,7 @@ type CliConfig struct {
 	UserOpenId          string
 	UserName            string
 	Lang                i18n.Lang
-	SupportedIdentities uint8  `json:"-"` // bitflag: 1=user, 2=bot; set by credential provider
-	AuthMethod          string // "" == client_secret; AuthMethodPrivateKeyJWT
-	KeyLabel            string // resolved TEE key handle for private_key_jwt
+	SupportedIdentities uint8 `json:"-"` // bitflag: 1=user, 2=bot; set by credential provider
 }
 
 // identityBotBit is the bit flag for bot identity in SupportedIdentities.
@@ -267,58 +247,31 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 			WithHint("available profiles: %s", formatProfileNames(raw.ProfileNames()))
 	}
 
-	// Validate the auth method first so a malformed profile fails here rather
-	// than silently degrading to client_secret (unknown method) or failing later
-	// at token-signing. Empty stays empty — downstream treats it as client_secret
-	// (back-compat).
-	switch app.AuthMethod {
-	case "", AuthMethodClientSecret, AuthMethodPrivateKeyJWT:
-	default:
-		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "unknown authMethod %q", app.AuthMethod).
-			WithHint("supported: %s, %s (empty defaults to %s)", AuthMethodClientSecret, AuthMethodPrivateKeyJWT, AuthMethodClientSecret)
+	if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
+		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "appId and appSecret keychain key are out of sync").
+			WithHint("%s", err.Error()).
+			WithCause(err)
 	}
 
-	// private_key_jwt carries no secret: validate the key handle and skip secret
-	// resolution entirely, so a stale/broken AppSecret ref never produces a
-	// confusing secret-resolution error for an otherwise-valid pkjwt profile.
-	var secret string
-	if app.AuthMethod == AuthMethodPrivateKeyJWT {
-		if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID == "" {
-			return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "private_key_jwt requires a key handle (keyRef) but none is configured").
-				WithHint("re-run: lark-cli config init --new --private-key-jwt")
+	secret, err := ResolveSecretInput(app.AppSecret, kc)
+	if err != nil {
+		if errs.IsTyped(err) {
+			return nil, err
 		}
-	} else {
-		if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
-			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "appId and appSecret keychain key are out of sync").
-				WithHint("%s", err.Error()).
-				WithCause(err)
-		}
-		var resolveErr error
-		secret, resolveErr = ResolveSecretInput(app.AppSecret, kc)
-		if resolveErr != nil {
-			if errs.IsTyped(resolveErr) {
-				return nil, resolveErr
-			}
-			subtype := errs.SubtypeNotConfigured
-			if isMalformedConfigError(resolveErr) {
-				subtype = errs.SubtypeInvalidConfig
-			}
-			return nil, errs.NewConfigError(subtype, "%s", resolveErr.Error()).WithCause(resolveErr)
+		subtype := errs.SubtypeNotConfigured
+		if isMalformedConfigError(err) {
+			subtype = errs.SubtypeInvalidConfig
 		}
+		return nil, errs.NewConfigError(subtype, "%s", err.Error()).WithCause(err)
 	}
-
 	cfg := &CliConfig{
 		ProfileName: app.ProfileName(),
 		AppID:       app.AppId,
 		AppSecret:   secret,
-		Brand:       app.Brand,
+		Brand:       ParseBrand(string(app.Brand)),
 		Lang:        app.Lang,
-		AuthMethod:  app.AuthMethod,
 		DefaultAs:   app.DefaultAs,
 	}
-	if app.KeyRef != nil {
-		cfg.KeyLabel = app.KeyRef.ID
-	}
 	if len(app.Users) > 0 {
 		cfg.UserOpenId = app.Users[0].UserOpenId
 		cfg.UserName = app.Users[0].UserName

internal/core/config_test.go

@@ -133,108 +133,6 @@ func TestResolveConfigFromMulti_AcceptsPlainSecret(t *testing.T) {
 	}
 }
 
-// TestResolveConfigFromMulti_RejectsUnknownAuthMethod ensures an unsupported
-// authMethod fails at resolution rather than silently degrading to client_secret.
-func TestResolveConfigFromMulti_RejectsUnknownAuthMethod(t *testing.T) {
-	raw := &MultiAppConfig{
-		Apps: []AppConfig{
-			{
-				AppId:      "cli_abc",
-				AppSecret:  PlainSecret("my-secret"),
-				Brand:      BrandFeishu,
-				AuthMethod: "bogus_method",
-			},
-		},
-	}
-
-	_, err := ResolveConfigFromMulti(raw, nil, "")
-	if err == nil {
-		t.Fatal("expected error for unknown authMethod")
-	}
-	var cfgErr *errs.ConfigError
-	if !errors.As(err, &cfgErr) {
-		t.Fatalf("expected ConfigError, got %T: %v", err, err)
-	}
-}
-
-// TestResolveConfigFromMulti_PrivateKeyJWTRequiresKeyRef ensures private_key_jwt
-// without a key handle fails at resolution rather than later at token-signing.
-func TestResolveConfigFromMulti_PrivateKeyJWTRequiresKeyRef(t *testing.T) {
-	raw := &MultiAppConfig{
-		Apps: []AppConfig{
-			{
-				AppId:      "cli_abc",
-				AppSecret:  SecretInput{}, // private_key_jwt carries no app secret
-				Brand:      BrandFeishu,
-				AuthMethod: AuthMethodPrivateKeyJWT,
-				// KeyRef intentionally nil
-			},
-		},
-	}
-
-	_, err := ResolveConfigFromMulti(raw, nil, "")
-	if err == nil {
-		t.Fatal("expected error for private_key_jwt without keyRef")
-	}
-	var cfgErr *errs.ConfigError
-	if !errors.As(err, &cfgErr) {
-		t.Fatalf("expected ConfigError, got %T: %v", err, err)
-	}
-
-	// Control: same config WITH a keyRef resolves cleanly and sets KeyLabel.
-	raw.Apps[0].KeyRef = &SecretRef{Source: "tee", ID: "larksuite-cli-agent"}
-	cfg, err := ResolveConfigFromMulti(raw, nil, "")
-	if err != nil {
-		t.Fatalf("unexpected error with keyRef present: %v", err)
-	}
-	if cfg.KeyLabel != "larksuite-cli-agent" {
-		t.Errorf("KeyLabel = %q, want larksuite-cli-agent", cfg.KeyLabel)
-	}
-}
-
-// TestResolveConfigFromMulti_PKJWTSkipsSecretResolution ensures a private_key_jwt
-// profile that carries a stale/broken AppSecret ref still resolves cleanly: the
-// auth method is judged before any secret handling, so the stale ref is ignored
-// instead of producing a confusing secret-resolution failure.
-func TestResolveConfigFromMulti_PKJWTSkipsSecretResolution(t *testing.T) {
-	raw := &MultiAppConfig{
-		Apps: []AppConfig{{
-			AppId: "cli_pk",
-			// Stale keychain ref whose ID does not match appId — would trip
-			// ValidateSecretKeyMatch / ResolveSecretInput if it were reached.
-			AppSecret:  SecretInput{Ref: &SecretRef{Source: "keychain", ID: "appsecret:cli_OTHER"}},
-			Brand:      BrandFeishu,
-			AuthMethod: AuthMethodPrivateKeyJWT,
-			KeyRef:     &SecretRef{Source: "tee", ID: "agent-key"},
-			Users:      []AppUser{},
-		}},
-	}
-	cfg, err := ResolveConfigFromMulti(raw, stubKeychain{}, "")
-	if err != nil {
-		t.Fatalf("pkjwt with stale secret ref must skip secret resolution, got %v", err)
-	}
-	if cfg.AuthMethod != AuthMethodPrivateKeyJWT || cfg.KeyLabel != "agent-key" {
-		t.Errorf("got authMethod=%q keyLabel=%q", cfg.AuthMethod, cfg.KeyLabel)
-	}
-}
-
-// TestResolveConfigFromMulti_PKJWTRejectsBadKeyRef ensures the stricter keyRef
-// check (Source=="tee" && ID!="") rejects malformed handles.
-func TestResolveConfigFromMulti_PKJWTRejectsBadKeyRef(t *testing.T) {
-	for i, ref := range []*SecretRef{
-		{Source: "keychain", ID: "x"}, // wrong source
-		{Source: "tee", ID: ""},       // empty id
-	} {
-		raw := &MultiAppConfig{Apps: []AppConfig{{
-			AppId: "cli_pk", Brand: BrandFeishu,
-			AuthMethod: AuthMethodPrivateKeyJWT, KeyRef: ref, Users: []AppUser{},
-		}}}
-		if _, err := ResolveConfigFromMulti(raw, stubKeychain{}, ""); err == nil {
-			t.Errorf("case %d: expected ConfigError for bad keyRef", i)
-		}
-	}
-}
-
 func TestResolveConfigFromMulti_CarriesLang(t *testing.T) {
 	raw := &MultiAppConfig{
 		Apps: []AppConfig{
@@ -332,3 +230,20 @@ func TestCliConfig_CanBot(t *testing.T) {
 		})
 	}
 }
+
+// Runtime configs must never carry raw brand casing: the config ingress
+// normalizes it, so downstream equality checks see canonical values.
+func TestResolveConfigFromMulti_NormalizesBrand(t *testing.T) {
+	multi := &MultiAppConfig{Apps: []AppConfig{{
+		AppId:     "cli_x",
+		AppSecret: PlainSecret("test-secret"),
+		Brand:     LarkBrand(" LARK "),
+	}}}
+	cfg, err := ResolveConfigFromMulti(multi, nil, "")
+	if err != nil {
+		t.Fatalf("ResolveConfigFromMulti error = %v", err)
+	}
+	if cfg.Brand != BrandLark {
+		t.Errorf("Brand = %q, want %q (normalized at ingress)", cfg.Brand, BrandLark)
+	}
+}

internal/core/types.go

@@ -7,7 +7,7 @@ import "strings"
 
 // LarkBrand represents the Lark platform brand.
 // "feishu" targets China-mainland, "lark" targets international.
-// Any other string is treated as a custom base URL.
+// ParseBrand and ResolveEndpoints map unrecognized values to BrandFeishu.
 type LarkBrand string
 
 const (
@@ -15,10 +15,10 @@ const (
 	BrandLark   LarkBrand = "lark"
 )
 
-// ParseBrand normalizes a brand string to a LarkBrand constant.
-// Unrecognized values default to BrandFeishu.
+// ParseBrand normalizes a brand string (case-insensitive, whitespace-tolerant);
+// anything other than "lark" normalizes to BrandFeishu.
 func ParseBrand(value string) LarkBrand {
-	if value == "lark" {
+	if strings.ToLower(strings.TrimSpace(value)) == "lark" {
 		return BrandLark
 	}
 	return BrandFeishu
@@ -38,9 +38,10 @@ type Endpoints struct {
 	AppLink  string // e.g. "https://applink.feishu.cn"
 }
 
-// ResolveEndpoints resolves endpoint URLs based on brand.
+// ResolveEndpoints resolves endpoint URLs for the brand, normalizing its
+// input so stored values with unusual casing still resolve correctly.
 func ResolveEndpoints(brand LarkBrand) Endpoints {
-	switch brand {
+	switch ParseBrand(string(brand)) {
 	case BrandLark:
 		return Endpoints{
 			Open:     "https://open.larksuite.com",
@@ -62,10 +63,3 @@ func ResolveEndpoints(brand LarkBrand) Endpoints {
 func ResolveOpenBaseURL(brand LarkBrand) string {
 	return ResolveEndpoints(brand).Open
 }
-
-// OpenAPIAudience returns the client_assertion `aud` value for the brand: the
-// bare Open API host per the App Authentication JWT spec — "open.feishu.cn" or
-// "open.larksuite.com" — not the full token endpoint URL.
-func OpenAPIAudience(brand LarkBrand) string {
-	return strings.TrimPrefix(ResolveOpenBaseURL(brand), "https://")
-}

internal/core/types_test.go

@@ -58,11 +58,36 @@ func TestResolveOpenBaseURL(t *testing.T) {
 	}
 }
 
-func TestOpenAPIAudience(t *testing.T) {
-	if got := OpenAPIAudience(BrandFeishu); got != "open.feishu.cn" {
-		t.Errorf("OpenAPIAudience(feishu) = %q, want open.feishu.cn", got)
+func TestParseBrand(t *testing.T) {
+	cases := []struct {
+		in   string
+		want LarkBrand
+	}{
+		{"", BrandFeishu},
+		{"feishu", BrandFeishu},
+		{"lark", BrandLark},
+		{"LARK", BrandLark},
+		{" lark ", BrandLark},
+		{"Lark", BrandLark},
+		{"xyz", BrandFeishu},
 	}
-	if got := OpenAPIAudience(BrandLark); got != "open.larksuite.com" {
-		t.Errorf("OpenAPIAudience(lark) = %q, want open.larksuite.com", got)
+	for _, c := range cases {
+		if got := ParseBrand(c.in); got != c.want {
+			t.Errorf("ParseBrand(%q) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// TestResolveEndpoints_NormalizesBrand locks the boundary invariant: the
+// resolver normalizes its brand input, so historical config values with
+// unusual casing or whitespace still resolve to their intended endpoints.
+func TestResolveEndpoints_NormalizesBrand(t *testing.T) {
+	for _, raw := range []string{"LARK", " lark ", "Lark"} {
+		if got := ResolveEndpoints(LarkBrand(raw)).Open; got != "https://open.larksuite.com" {
+			t.Errorf("ResolveEndpoints(%q).Open = %q, want the lark endpoint", raw, got)
+		}
+	}
+	if got := ResolveEndpoints(LarkBrand("unexpected")).Open; got != "https://open.feishu.cn" {
+		t.Errorf("ResolveEndpoints(unexpected).Open = %q, want the feishu default", got)
 	}
 }

internal/credential/default_provider.go

@@ -17,7 +17,6 @@ import (
 	"github.com/larksuite/cli/internal/keychain"
 
 	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // classifyTATResponseCode wraps a deterministic (non-transient) failure from the
@@ -176,18 +175,6 @@ func (p *DefaultTokenProvider) doResolveTAT(ctx context.Context) (*TokenResult,
 	if err != nil {
 		return nil, err
 	}
-
-	// private_key_jwt apps have no app secret: mint via the jwt-bearer grant
-	// using a TEE-signed client_assertion instead.
-	if acct.AuthMethod == core.AuthMethodPrivateKeyJWT {
-		signer := keysigner.Active()
-		token, err := FetchTATWithAssertion(ctx, httpClient, acct.Brand, acct.AppID, signer, acct.KeyLabel)
-		if err != nil {
-			return nil, err
-		}
-		return &TokenResult{Token: token}, nil
-	}
-
 	token, err := FetchTAT(ctx, httpClient, acct.Brand, acct.AppID, acct.AppSecret)
 	if err != nil {
 		return nil, err

internal/credential/tat_fetch.go

@@ -12,11 +12,7 @@ import (
 	"net/url"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/keylesshelper"
-	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // FetchTAT performs a single HTTP POST to mint a tenant access token via the
@@ -104,108 +100,3 @@ func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand
 	}
 	return "", classifyTATResponseCode(result.Code, result.Error, desc, string(brand), appID)
 }
-
-// FetchTATWithAssertion mints a tenant access token for a private_key_jwt app via
-// the RFC 7523 jwt-bearer grant: it signs a short-lived client_assertion with the
-// TEE-held key and posts it to the unified OAuth token endpoint, replacing the
-// app_secret entirely.
-//
-// The unified v2 token endpoint returns the minted token as access_token
-// (tenant_access_token is accepted as a fallback).
-func FetchTATWithAssertion(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, clientID string, signer keysigner.Signer, keyLabel string) (string, error) {
-	helper, err := keylesshelper.Resolve()
-	if err != nil {
-		return "", err
-	}
-	return FetchTATWithAssertionWithHelper(ctx, httpClient, brand, clientID, signer, helper, keyLabel)
-}
-
-// FetchTATWithAssertionWithHelper is the single-resolution variant used when
-// the caller must make a preflight decision from the same helper snapshot.
-func FetchTATWithAssertionWithHelper(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, clientID string, signer keysigner.Signer, helper *keylesshelper.Command, keyLabel string) (string, error) {
-	if signer == nil && helper == nil {
-		return "", errs.NewConfigError(errs.SubtypeInvalidClient,
-			"profile uses private_key_jwt but no TEE key signer is available on this build").
-			WithHint("install a build with the platform key-signer extension, configure an external keyless signer, or reconfigure the app to use an app secret")
-	}
-	ep := core.ResolveEndpoints(brand)
-	endpoint := ep.Open + auth.PathOAuthTokenV2
-
-	assertionType, assertion, err := auth.SignClientAssertion(ctx, signer, helper, keyLabel, clientID, core.OpenAPIAudience(brand))
-	if err != nil {
-		return "", err
-	}
-
-	form := url.Values{}
-	form.Set("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer")
-	form.Set("client_id", clientID)
-	form.Set("client_assertion_type", assertionType)
-	form.Set("client_assertion", assertion)
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-
-	resp, err := httpClient.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if err != nil {
-		return "", fmt.Errorf("read token response: %w", err)
-	}
-
-	var result struct {
-		Code              int    `json:"code"`
-		Msg               string `json:"msg"`
-		Error             string `json:"error"`
-		ErrorDescription  string `json:"error_description"`
-		AccessToken       string `json:"access_token"`
-		TenantAccessToken string `json:"tenant_access_token"`
-	}
-	_ = json.Unmarshal(body, &result) // best-effort; error body may not be JSON
-
-	token := result.AccessToken
-	if token == "" {
-		token = result.TenantAccessToken
-	}
-	if resp.StatusCode == http.StatusOK && token != "" && result.Error == "" && result.Code == 0 {
-		return token, nil
-	}
-
-	// Surface the server's reason, preferring the OAuth `error` code (e.g.
-	// unauthorized_client) which is more diagnostic than the description alone.
-	detail := result.ErrorDescription
-	if detail == "" {
-		detail = result.Msg
-	}
-	if detail == "" {
-		detail = strings.TrimSpace(string(body))
-	}
-	if result.Error != "" {
-		return "", classifyAssertionError(result.Error, resp.StatusCode, detail)
-	}
-	return "", fmt.Errorf("token endpoint HTTP %d (code=%d): %s", resp.StatusCode, result.Code, detail)
-}
-
-// classifyAssertionError maps the OAuth token endpoint's `error` field to a
-// typed or untyped error. Only deterministic client-credential rejections get a
-// typed errs.ConfigError (so runProbePKJWT can tell "this key is not bound to
-// this app" apart from upstream noise); every other error (e.g.
-// temporarily_unavailable) stays untyped and is swallowed by the probe. detail
-// carries only the server's error_description / msg / body text — it never
-// echoes the client_assertion or private key (the assertion lives only in the
-// request form).
-func classifyAssertionError(oauthError string, httpStatus int, detail string) error {
-	switch oauthError {
-	case "invalid_client", "unauthorized_client", "invalid_grant":
-		return errs.NewConfigError(errs.SubtypeInvalidClient,
-			"token endpoint rejected the key (%s): %s", oauthError, detail)
-	default:
-		return fmt.Errorf("token endpoint HTTP %d (%s): %s", httpStatus, oauthError, detail)
-	}
-}

internal/credential/tat_fetch_test.go

@@ -5,22 +5,15 @@ package credential
 
 import (
 	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/sha256"
 	"errors"
 	"io"
 	"net/http"
 	"net/http/httptest"
-	"net/url"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // stubRoundTripper lets us assert request shape and return canned responses.
@@ -314,141 +307,3 @@ func (r *urlRewriteRT) RoundTrip(req *http.Request) (*http.Response, error) {
 	req2.Header = req.Header
 	return http.DefaultTransport.RoundTrip(req2)
 }
-
-// fakeTATSigner is a real in-memory ECDSA P-256 signer for assertion tests.
-type fakeTATSigner struct{ key *ecdsa.PrivateKey }
-
-func newFakeTATSigner(t *testing.T) *fakeTATSigner {
-	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 &fakeTATSigner{key: k}
-}
-
-func (f *fakeTATSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
-	return f.key.Public(), nil
-}
-func (f *fakeTATSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
-	return f.key.Public(), nil
-}
-func (f *fakeTATSigner) 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 TestFetchTATWithAssertion_Success(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 200, respBody: `{"access_token":"test-token","token_type":"Bearer","expires_in":7200}`}
-	hc := &http.Client{Transport: rt}
-
-	token, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "agent-key")
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if token != "test-token" {
-		t.Errorf("token = %q, want test-token", token)
-	}
-	if rt.gotReq.URL.String() != "https://open.feishu.cn/open-apis/authen/v2/oauth/token" {
-		t.Errorf("url = %s", rt.gotReq.URL.String())
-	}
-
-	form, err := url.ParseQuery(rt.gotBody)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if form.Get("grant_type") != "urn:ietf:params:oauth:grant-type:jwt-bearer" {
-		t.Errorf("grant_type = %q", form.Get("grant_type"))
-	}
-	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.Get("client_assertion") == "" {
-		t.Error("client_assertion is empty")
-	}
-	if form.Has("client_secret") {
-		t.Error("client_secret must NOT be sent for private_key_jwt")
-	}
-	if form.Get("client_id") != "cli_app" {
-		t.Errorf("client_id = %q", form.Get("client_id"))
-	}
-}
-
-func TestFetchTATWithAssertion_NilSigner(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	hc := &http.Client{Transport: &stubRoundTripper{respCode: 200, respBody: `{}`}}
-	if _, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", nil, "k"); err == nil {
-		t.Fatal("expected error when signer is nil")
-	}
-}
-
-func TestFetchTATWithAssertion_ServerError(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 200, respBody: `{"error":"invalid_client","error_description":"unknown key"}`}
-	hc := &http.Client{Transport: rt}
-	if _, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k"); err == nil {
-		t.Fatal("expected error for invalid_client response")
-	}
-}
-
-func TestFetchTATWithAssertion_LimitsErrorBody(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 502, respBody: strings.Repeat("x", 2<<20)}
-	hc := &http.Client{Transport: rt}
-
-	_, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k")
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	if len(err.Error()) > (1<<20)+512 {
-		t.Fatalf("error length = %d, want bounded", len(err.Error()))
-	}
-}
-
-// Deterministic OAuth client rejections must be typed (ConfigError /
-// SubtypeInvalidClient) so runProbePKJWT can tell "the key is not bound to this
-// app" apart from transport noise.
-func TestFetchTATWithAssertion_DeterministicReject_Typed(t *testing.T) {
-	for _, oauthErr := range []string{"invalid_client", "unauthorized_client", "invalid_grant"} {
-		rt := &stubRoundTripper{respCode: 401, respBody: `{"error":"` + oauthErr + `","error_description":"bad key"}`}
-		hc := &http.Client{Transport: rt}
-		_, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k")
-		if err == nil {
-			t.Fatalf("%s: expected error", oauthErr)
-		}
-		if !errs.IsTyped(err) {
-			t.Errorf("%s: must be typed, got %T", oauthErr, err)
-		}
-		var cfgErr *errs.ConfigError
-		if !errors.As(err, &cfgErr) || cfgErr.Subtype != errs.SubtypeInvalidClient {
-			t.Errorf("%s: want ConfigError/InvalidClient, got %T %v", oauthErr, err, err)
-		}
-	}
-}
-
-// Unrecognized OAuth errors and non-payload noise stay UNTYPED so the probe
-// treats them as upstream noise and stays silent.
-func TestFetchTATWithAssertion_AmbiguousError_Untyped(t *testing.T) {
-	cases := []string{
-		`{"error":"temporarily_unavailable","error_description":"retry"}`,
-		`{"code":99999,"msg":"weird"}`,
-		`not json`,
-	}
-	for _, body := range cases {
-		rt := &stubRoundTripper{respCode: 503, respBody: body}
-		hc := &http.Client{Transport: rt}
-		_, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k")
-		if err == nil {
-			t.Fatalf("body %q: expected error", body)
-		}
-		if errs.IsTyped(err) {
-			t.Errorf("body %q: must be UNTYPED, got typed %T", body, err)
-		}
-	}
-}

internal/credential/types.go

@@ -26,8 +26,6 @@ type Account struct {
 	UserName            string
 	Lang                i18n.Lang
 	SupportedIdentities uint8
-	AuthMethod          string // "" == client_secret; core.AuthMethodPrivateKeyJWT
-	KeyLabel            string // resolved TEE key handle for private_key_jwt
 }
 
 const runtimePlaceholderAppSecret = "__LARKSUITE_CLI_TOKEN_ONLY__"
@@ -71,12 +69,11 @@ func AccountFromCliConfig(cfg *core.CliConfig) *Account {
 		UserName:            cfg.UserName,
 		Lang:                cfg.Lang,
 		SupportedIdentities: cfg.SupportedIdentities,
-		AuthMethod:          cfg.AuthMethod,
-		KeyLabel:            cfg.KeyLabel,
 	}
 }
 
-// ToCliConfig copies the credential-layer account into the downstream config shape.
+// ToCliConfig copies the credential-layer account into the downstream config
+// shape, normalizing the brand so runtime consumers never see raw casing.
 func (a *Account) ToCliConfig() *core.CliConfig {
 	if a == nil {
 		return nil
@@ -85,14 +82,12 @@ func (a *Account) ToCliConfig() *core.CliConfig {
 		ProfileName:         a.ProfileName,
 		AppID:               a.AppID,
 		AppSecret:           normalizeAccountAppSecret(a.AppSecret),
-		Brand:               a.Brand,
+		Brand:               core.ParseBrand(string(a.Brand)),
 		DefaultAs:           a.DefaultAs,
 		UserOpenId:          a.UserOpenId,
 		UserName:            a.UserName,
 		Lang:                a.Lang,
 		SupportedIdentities: a.SupportedIdentities,
-		AuthMethod:          a.AuthMethod,
-		KeyLabel:            a.KeyLabel,
 	}
 }
 

internal/credential/types_test.go

@@ -130,3 +130,11 @@ func TestRuntimeAppSecret_TokenOnlyUsesPlaceholder(t *testing.T) {
 		t.Fatalf("RuntimeAppSecret(real) = %q, want %q", got, "secret-1")
 	}
 }
+
+// The credential-layer ingress normalizes brand casing for all runtime consumers.
+func TestToCliConfig_NormalizesBrand(t *testing.T) {
+	acct := &Account{AppID: "cli_x", Brand: " LARK "}
+	if got := acct.ToCliConfig().Brand; got != core.BrandLark {
+		t.Errorf("Brand = %q, want %q", got, core.BrandLark)
+	}
+}

internal/envvars/envvars.go

@@ -25,7 +25,4 @@ const (
 	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"
 	CliProxyAddress = "LARKSUITE_CLI_PROXY_ADDRESS"
 	CliCAPath       = "LARKSUITE_CLI_CA_PATH"
-
-	// External keyless signer helper for private_key_jwt flows.
-	CliKeylessSignerCmd = "LARKSUITE_CLI_KEYLESS_SIGNER_CMD"
 )

internal/identitydiag/diagnostics.go

@@ -202,9 +202,7 @@ func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, v
 			Hint:    "check strict mode or the active credential provider",
 		}
 	}
-	// private_key_jwt apps have no app secret — the bot/tenant token is minted via
-	// a TEE-signed client_assertion — so absence of a secret is NOT "unconfigured".
-	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) && cfg.AuthMethod != core.AuthMethodPrivateKeyJWT {
+	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) {
 		return Identity{
 			Status:  StatusNotConfigured,
 			Message: "Bot identity: not configured (missing app secret or bot token)",

internal/keylesshelper/helper.go

@@ -1,288 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package keylesshelper invokes an external lark-keyless-signer-compatible
-// helper configured by environment or config.json.
-package keylesshelper
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-	"os/exec"
-	"strings"
-
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/keysigner"
-)
-
-const helperOutputLimit = 1 << 20
-
-type request struct {
-	Op       string `json:"op"`
-	KeyRef   string `json:"keyRef,omitempty"`
-	Nonce    string `json:"nonce,omitempty"`
-	ClientID string `json:"clientId,omitempty"`
-	Audience string `json:"aud,omitempty"`
-}
-
-type response struct {
-	OK                  bool           `json:"ok"`
-	Error               *protocolError `json:"error,omitempty"`
-	Attestation         string         `json:"attestation,omitempty"`
-	ClientAssertionType string         `json:"client_assertion_type,omitempty"`
-	ClientAssertion     string         `json:"client_assertion,omitempty"`
-}
-
-type protocolError struct {
-	Type    string `json:"type"`
-	Message string `json:"message"`
-}
-
-type runner func(context.Context, []string, request) (response, error)
-
-var run runner = runCommand
-
-// Command is one resolved helper command. It pins the environment/config
-// snapshot used by an operation so a concurrent atomic config replacement
-// cannot switch signing backends between the configured check and execution.
-type Command struct {
-	argv []string
-}
-
-// ConfiguredFromEnvironment reports whether the current process explicitly
-// supplied an external helper command. Config init uses this distinction
-// because it removes a config-only command when the environment is absent.
-func ConfiguredFromEnvironment() bool {
-	return strings.TrimSpace(os.Getenv(envvars.CliKeylessSignerCmd)) != ""
-}
-
-// ValidateConfigured reports whether the configured helper command can be parsed.
-func ValidateConfigured() error {
-	helper, err := Resolve()
-	if err != nil {
-		return err
-	}
-	if helper == nil {
-		return fmt.Errorf("%s is not set", envvars.CliKeylessSignerCmd)
-	}
-	return nil
-}
-
-// Resolve loads and validates the external helper once. A nil command and nil
-// error means neither the environment nor config.json configured a helper.
-// Missing config is treated as unconfigured; malformed or unreadable config
-// fails closed with the config source and path preserved in the error.
-func Resolve() (*Command, error) {
-	raw, source, err := configuredCommand()
-	if err != nil {
-		return nil, err
-	}
-	if raw == "" {
-		return nil, nil
-	}
-	argv, err := parseCommandFromSource(raw, source)
-	if err != nil {
-		return nil, err
-	}
-	return &Command{argv: argv}, nil
-}
-
-// Probe asks this resolved helper for its public key.
-func (c *Command) Probe(ctx context.Context, keyRef string) error {
-	resp, err := run(ctx, c.argv, request{
-		Op:     "pubkey",
-		KeyRef: defaultKeyRef(keyRef),
-	})
-	if err != nil {
-		return err
-	}
-	return validateResponse(resp)
-}
-
-// SignAttestation asks the helper to mint a registration attestation JWT.
-func SignAttestation(ctx context.Context, keyRef, nonce string) (string, error) {
-	helper, err := Resolve()
-	if err != nil {
-		return "", err
-	}
-	if helper == nil {
-		return "", fmt.Errorf("%s is not set", envvars.CliKeylessSignerCmd)
-	}
-	return helper.SignAttestation(ctx, keyRef, nonce)
-}
-
-// SignAttestation asks this resolved helper to mint a registration attestation JWT.
-func (c *Command) SignAttestation(ctx context.Context, keyRef, nonce string) (string, error) {
-	resp, err := run(ctx, c.argv, request{
-		Op:     "sign-attestation",
-		KeyRef: defaultKeyRef(keyRef),
-		Nonce:  nonce,
-	})
-	if err != nil {
-		return "", err
-	}
-	if err := validateResponse(resp); err != nil {
-		return "", err
-	}
-	if resp.Attestation == "" {
-		return "", fmt.Errorf("keyless helper returned empty attestation")
-	}
-	return resp.Attestation, nil
-}
-
-// SignClientAssertion asks this resolved helper to mint a token-endpoint client_assertion.
-func (c *Command) SignClientAssertion(ctx context.Context, keyRef, clientID, audience string) (string, string, error) {
-	resp, err := run(ctx, c.argv, request{
-		Op:       "sign-assertion",
-		KeyRef:   defaultKeyRef(keyRef),
-		ClientID: clientID,
-		Audience: audience,
-	})
-	if err != nil {
-		return "", "", err
-	}
-	if err := validateResponse(resp); err != nil {
-		return "", "", err
-	}
-	if resp.ClientAssertionType == "" {
-		return "", "", fmt.Errorf("keyless helper returned empty client_assertion_type")
-	}
-	if resp.ClientAssertion == "" {
-		return "", "", fmt.Errorf("keyless helper returned empty client_assertion")
-	}
-	return resp.ClientAssertionType, resp.ClientAssertion, nil
-}
-
-func validateResponse(resp response) error {
-	if resp.Error != nil {
-		return fmt.Errorf("keyless helper %s: %s", resp.Error.Type, resp.Error.Message)
-	}
-	if !resp.OK {
-		return fmt.Errorf("keyless helper returned ok=false")
-	}
-	return nil
-}
-
-func defaultKeyRef(keyRef string) string {
-	if keyRef != "" {
-		return keyRef
-	}
-	return keysigner.DefaultKeyLabel
-}
-
-func configuredCommand() (string, string, error) {
-	if raw := strings.TrimSpace(os.Getenv(envvars.CliKeylessSignerCmd)); raw != "" {
-		return raw, envvars.CliKeylessSignerCmd, nil
-	}
-	config, err := core.LoadMultiAppConfig()
-	if err != nil {
-		if errors.Is(err, os.ErrNotExist) {
-			return "", "config.json keylessSignerCmd", nil
-		}
-		return "", "config.json keylessSignerCmd", fmt.Errorf("load config.json keylessSignerCmd from %s: %w", core.GetConfigPath(), err)
-	}
-	if config == nil {
-		return "", "config.json keylessSignerCmd", nil
-	}
-	return strings.TrimSpace(config.KeylessSignerCmd), "config.json keylessSignerCmd", nil
-}
-
-// parseCommand accepts either a direct helper path or a JSON argv array. The
-// resulting argv is executed directly, never through a shell.
-func parseCommand(raw string) ([]string, error) {
-	return parseCommandFromSource(raw, envvars.CliKeylessSignerCmd)
-}
-
-func parseCommandFromSource(raw, source string) ([]string, error) {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return nil, fmt.Errorf("%s is not set", source)
-	}
-	if strings.HasPrefix(raw, "[") {
-		var argv []string
-		if err := json.Unmarshal([]byte(raw), &argv); err != nil {
-			return nil, fmt.Errorf("parse %s JSON argv: %w", source, err)
-		}
-		return validateArgv(argv, source)
-	}
-	return validateArgv([]string{raw}, source)
-}
-
-func validateArgv(argv []string, source string) ([]string, error) {
-	if len(argv) == 0 || strings.TrimSpace(argv[0]) == "" {
-		return nil, fmt.Errorf("%s must name a helper binary", source)
-	}
-	for i, arg := range argv {
-		if arg == "" {
-			return nil, fmt.Errorf("%s argv[%d] is empty", source, i)
-		}
-	}
-	return argv, nil
-}
-
-func runCommand(ctx context.Context, argv []string, req request) (response, error) {
-	body, err := json.Marshal(req)
-	if err != nil {
-		return response{}, fmt.Errorf("marshal keyless helper request: %w", err)
-	}
-	body = append(body, '\n')
-
-	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
-	cmd.Stdin = bytes.NewReader(body)
-	stdout := &limitedBuffer{limit: helperOutputLimit}
-	stderr := &limitedBuffer{limit: helperOutputLimit}
-	cmd.Stdout = stdout
-	cmd.Stderr = stderr
-
-	runErr := cmd.Run()
-	var resp response
-	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
-		if runErr != nil {
-			return response{}, helperRunError(runErr, stderr.String())
-		}
-		return response{}, fmt.Errorf("keyless helper produced invalid JSON: %w", err)
-	}
-	if runErr != nil && resp.Error == nil {
-		return response{}, helperRunError(runErr, stderr.String())
-	}
-	return resp, nil
-}
-
-func helperRunError(runErr error, stderr string) error {
-	if strings.TrimSpace(stderr) != "" {
-		return fmt.Errorf("keyless helper failed: %w (stderr omitted)", runErr)
-	}
-	return fmt.Errorf("keyless helper failed: %w", runErr)
-}
-
-type limitedBuffer struct {
-	buf   bytes.Buffer
-	limit int
-}
-
-func (b *limitedBuffer) Write(p []byte) (int, error) {
-	if b.limit <= 0 {
-		return len(p), nil
-	}
-	remaining := b.limit - b.buf.Len()
-	if remaining > 0 {
-		if len(p) < remaining {
-			remaining = len(p)
-		}
-		_, _ = b.buf.Write(p[:remaining])
-	}
-	return len(p), nil
-}
-
-func (b *limitedBuffer) Bytes() []byte {
-	return b.buf.Bytes()
-}
-
-func (b *limitedBuffer) String() string {
-	return b.buf.String()
-}

internal/keylesshelper/helper_test.go

@@ -1,303 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package keylesshelper
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/auth/jwt"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-func TestParseCommand(t *testing.T) {
-	cases := []struct {
-		name string
-		raw  string
-		want []string
-	}{
-		{name: "plain path", raw: "/opt/lark-keyless-signer", want: []string{"/opt/lark-keyless-signer"}},
-		{name: "json argv", raw: `["/opt/lark-keyless-signer","--mode","local"]`, want: []string{"/opt/lark-keyless-signer", "--mode", "local"}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			got, err := parseCommand(tc.raw)
-			if err != nil {
-				t.Fatalf("parseCommand: %v", err)
-			}
-			if !reflect.DeepEqual(got, tc.want) {
-				t.Fatalf("argv = %#v, want %#v", got, tc.want)
-			}
-		})
-	}
-}
-
-func TestValidateConfiguredRejectsInvalidJSONArgv(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, `[""]`)
-
-	err := ValidateConfigured()
-	if err == nil {
-		t.Fatal("ValidateConfigured() error = nil, want invalid argv error")
-	}
-	if !strings.Contains(err.Error(), "must name a helper binary") {
-		t.Fatalf("ValidateConfigured() error = %q", err)
-	}
-}
-
-func TestResolveFromConfig(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	seedKeylessSignerConfig(t, "/config/helper")
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatalf("Resolve() error = %v", err)
-	}
-	if helper == nil {
-		t.Fatal("Resolve() = nil, want config.json helper")
-	}
-	if err := ValidateConfigured(); err != nil {
-		t.Fatalf("ValidateConfigured() error = %v", err)
-	}
-}
-
-func TestCommandResolutionUsesConfigJSONArgv(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	seedKeylessSignerConfig(t, `["/config/helper","--mode","config"]`)
-	prev := run
-	t.Cleanup(func() { run = prev })
-
-	run = func(_ context.Context, argv []string, _ request) (response, error) {
-		want := []string{"/config/helper", "--mode", "config"}
-		if !reflect.DeepEqual(argv, want) {
-			t.Fatalf("argv = %#v, want %#v", argv, want)
-		}
-		return response{OK: true}, nil
-	}
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := helper.Probe(context.Background(), "agent-key"); err != nil {
-		t.Fatalf("Probe() error = %v", err)
-	}
-}
-
-func TestCommandResolutionPrefersEnvironment(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "/env/helper")
-	seedKeylessSignerConfig(t, "/config/helper")
-	prev := run
-	t.Cleanup(func() { run = prev })
-
-	run = func(_ context.Context, argv []string, _ request) (response, error) {
-		if !reflect.DeepEqual(argv, []string{"/env/helper"}) {
-			t.Fatalf("argv = %#v, want environment helper", argv)
-		}
-		return response{OK: true}, nil
-	}
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := helper.Probe(context.Background(), "agent-key"); err != nil {
-		t.Fatalf("Probe() error = %v", err)
-	}
-}
-
-func TestCommandResolutionInvalidEnvironmentShadowsConfig(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, `[""]`)
-	seedKeylessSignerConfig(t, "/config/helper")
-
-	err := ValidateConfigured()
-	if err == nil || !strings.Contains(err.Error(), "must name a helper binary") {
-		t.Fatalf("ValidateConfigured() error = %v, want invalid environment command", err)
-	}
-}
-
-func TestCommandResolutionInvalidConfigNamesConfigSource(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	seedKeylessSignerConfig(t, `[""]`)
-
-	err := ValidateConfigured()
-	if err == nil {
-		t.Fatal("ValidateConfigured() error = nil, want invalid config command")
-	}
-	if !strings.Contains(err.Error(), "config.json keylessSignerCmd") {
-		t.Fatalf("ValidateConfigured() error = %q, want config source", err)
-	}
-}
-
-func TestResolveUnconfigured(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatalf("Resolve() error = %v", err)
-	}
-	if helper != nil {
-		t.Fatal("Resolve() != nil, want no helper without env or config")
-	}
-}
-
-func TestResolveFailsClosedWhenConfigMalformed(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := vfs.WriteFile(core.GetConfigPath(), []byte("{not-json"), 0600); err != nil {
-		t.Fatalf("write malformed config: %v", err)
-	}
-
-	helper, err := Resolve()
-	if err == nil {
-		t.Fatalf("Resolve() = %v, nil; want config load error", helper)
-	}
-	if !strings.Contains(err.Error(), "config.json keylessSignerCmd") || !strings.Contains(err.Error(), core.GetConfigPath()) {
-		t.Fatalf("Resolve() error = %q, want signer source and config path", err)
-	}
-}
-
-func TestResolveFailsClosedWhenConfigUnreadable(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	if err := vfs.MkdirAll(core.GetConfigPath(), 0700); err != nil {
-		t.Fatalf("create directory at config path: %v", err)
-	}
-
-	helper, err := Resolve()
-	if err == nil {
-		t.Fatalf("Resolve() = %v, nil; want config load error", helper)
-	}
-	if !strings.Contains(err.Error(), "config.json keylessSignerCmd") || !strings.Contains(err.Error(), core.GetConfigPath()) {
-		t.Fatalf("Resolve() error = %q, want signer source and config path", err)
-	}
-}
-
-func TestResolvePinsSingleConfigSnapshot(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv(envvars.CliKeylessSignerCmd, "")
-	seedKeylessSignerConfig(t, "/first/helper")
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatalf("Resolve() error = %v", err)
-	}
-	if helper == nil {
-		t.Fatal("Resolve() = nil, want configured helper")
-	}
-
-	// A concurrent atomic config replacement after resolution must not change
-	// the command used by this operation.
-	seedKeylessSignerConfig(t, "/second/helper")
-	prev := run
-	t.Cleanup(func() { run = prev })
-	run = func(_ context.Context, argv []string, _ request) (response, error) {
-		if !reflect.DeepEqual(argv, []string{"/first/helper"}) {
-			t.Fatalf("argv = %#v, want command from the resolved snapshot", argv)
-		}
-		return response{OK: true}, nil
-	}
-
-	if err := helper.Probe(context.Background(), "agent-key"); err != nil {
-		t.Fatalf("Probe() error = %v", err)
-	}
-}
-
-func seedKeylessSignerConfig(t *testing.T, command string) {
-	t.Helper()
-	err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		KeylessSignerCmd: command,
-		Apps: []core.AppConfig{{
-			AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
-		}},
-	})
-	if err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-}
-
-func TestSignAttestationUsesConfiguredHelper(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, `["/helper"]`)
-	prev := run
-	t.Cleanup(func() { run = prev })
-
-	var got request
-	run = func(ctx context.Context, argv []string, req request) (response, error) {
-		got = req
-		if !reflect.DeepEqual(argv, []string{"/helper"}) {
-			t.Fatalf("argv = %#v", argv)
-		}
-		return response{OK: true, Attestation: "att.jwt"}, nil
-	}
-
-	att, err := SignAttestation(context.Background(), "agent-key", "nonce-1")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if att != "att.jwt" {
-		t.Fatalf("attestation = %q", att)
-	}
-	if got.Op != "sign-attestation" || got.KeyRef != "agent-key" || got.Nonce != "nonce-1" {
-		t.Fatalf("request = %+v", got)
-	}
-}
-
-func TestSignClientAssertionUsesConfiguredHelper(t *testing.T) {
-	t.Setenv(envvars.CliKeylessSignerCmd, `/helper`)
-	prev := run
-	t.Cleanup(func() { run = prev })
-
-	var got request
-	run = func(ctx context.Context, argv []string, req request) (response, error) {
-		got = req
-		return response{
-			OK:                  true,
-			ClientAssertionType: jwt.ClientAssertionType,
-			ClientAssertion:     "client.jwt",
-		}, nil
-	}
-
-	helper, err := Resolve()
-	if err != nil {
-		t.Fatal(err)
-	}
-	typ, assertion, err := helper.SignClientAssertion(context.Background(), "agent-key", "cli_app", "open.feishu.cn")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if typ != jwt.ClientAssertionType || assertion != "client.jwt" {
-		t.Fatalf("got (%q, %q)", typ, assertion)
-	}
-	if got.Op != "sign-assertion" || got.KeyRef != "agent-key" || got.ClientID != "cli_app" || got.Audience != "open.feishu.cn" {
-		t.Fatalf("request = %+v", got)
-	}
-}
-
-func TestRunCommandOmitsStderrOnFailure(t *testing.T) {
-	err := helperRunError(errors.New("exit status 1"), "secret.jwt")
-	if err == nil {
-		t.Fatal("helperRunError() error = nil")
-	}
-	if strings.Contains(err.Error(), "secret.jwt") {
-		t.Fatalf("error leaked stderr: %q", err)
-	}
-}
-
-func TestHelperRunErrorPreservesCause(t *testing.T) {
-	cause := errors.New("boom")
-	err := helperRunError(cause, "")
-	if !errors.Is(err, cause) {
-		t.Fatalf("errors.Is(err, cause) = false; err=%v", err)
-	}
-}

internal/keysigner/keysigner.go

@@ -1,212 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package keysigner defines the pluggable signing abstraction used by the
-// private_key_jwt registration and authentication flow.
-//
-// The open-source core only declares the Signer interface and pure-stdlib key
-// helpers. The platform implementations that hold a non-exportable private key
-// (TPM 2.0 via facebookincubator/sks on Linux/Windows, a non-extractable
-// Keychain key on macOS) live OUTSIDE this core — in a build-tagged module or
-// extension — and register themselves via Register from init(). This keeps
-// CGO-heavy and license-sensitive dependencies out of the open-source build.
-package keysigner
-
-import (
-	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rsa"
-	"crypto/x509"
-	"encoding/asn1"
-	"encoding/base64"
-	"errors"
-	"fmt"
-	"math/big"
-	"strings"
-)
-
-// KeyRef identifies a non-exportable signing key held by a backend
-// (TEE/TPM/Keychain). It is a stable handle (label), never the key material.
-type KeyRef struct {
-	// Label is the backend key label/tag (e.g. "larksuite-cli-agent").
-	Label string
-}
-
-// Signer signs JWS signing inputs with a non-exportable key.
-type Signer interface {
-	// EnsureKey returns the public key for ref, creating the key if absent.
-	EnsureKey(ctx context.Context, ref KeyRef) (crypto.PublicKey, error)
-	// PublicKey returns the public key for ref without creating it.
-	PublicKey(ctx context.Context, ref KeyRef) (crypto.PublicKey, error)
-	// Sign signs signingInput and returns a JOSE-format signature plus the JWS
-	// alg ("ES256"/"RS256"). Implementations apply the alg's hash and, for
-	// ECDSA, MUST return the fixed-width r||s form required by RFC 7518 §3.4
-	// (not ASN.1 DER), because the backend (TPM/Keychain) typically yields DER.
-	Sign(ctx context.Context, ref KeyRef, signingInput []byte) (sig []byte, alg string, err error)
-}
-
-// Supported JWS algorithms.
-const (
-	AlgES256 = "ES256"
-	AlgRS256 = "RS256"
-)
-
-// DefaultKeyLabel is the backend key label lark-cli uses for its device signing
-// key. One non-exportable key is created on first private_key_jwt registration
-// and reused across subsequent app registrations on the same device.
-const DefaultKeyLabel = "larksuite-cli-agent"
-
-// HardwareInfo describes the secure hardware backing a Signer, as reported by a
-// HardwareProber. It is advisory/diagnostic: it tells a user whether
-// private_key_jwt can use a real TEE on this device.
-type HardwareInfo struct {
-	Backend    string // backing technology, e.g. "tpm2" or "keychain"
-	Available  bool   // the hardware is present and usable for signing
-	VendorName string // hardware vendor/manufacturer, when known
-	VendorInfo string // additional vendor detail, when known
-	Reason     string // when Available is false, a human-readable cause
-}
-
-// HardwareProber is an optional capability a Signer may implement to report on
-// the secure hardware backing it (TPM/TEE vendor and availability) WITHOUT
-// creating or using a key. Probing never mutates key state.
-type HardwareProber interface {
-	ProbeHardware(ctx context.Context) (HardwareInfo, error)
-}
-
-// ProbeActiveHardware probes the active signer's secure hardware. ok is false
-// when there is no active signer or it does not implement HardwareProber — in
-// which case private_key_jwt is unsupported on this build. When ok is true, info
-// reports availability and, if unavailable, info.Reason explains why.
-func ProbeActiveHardware(ctx context.Context) (info HardwareInfo, ok bool, err error) {
-	return probeHardware(ctx, Active())
-}
-
-// probeHardware is the registry-independent core of ProbeActiveHardware, so it
-// can be unit-tested without touching the global signer.
-func probeHardware(ctx context.Context, s Signer) (HardwareInfo, bool, error) {
-	p, ok := s.(HardwareProber)
-	if !ok {
-		return HardwareInfo{}, false, nil
-	}
-	info, err := p.ProbeHardware(ctx)
-	return info, true, err
-}
-
-// cleanProbeError renders err's message with redundant re-wraps collapsed. Some
-// backends (e.g. facebookincubator/sks) wrap an error twice with the SAME "%w"
-// prefix, yielding "P: P: cause"; this peels each outer layer whose only
-// contribution is to repeat the prefix already present in the wrapped error,
-// leaving a single "P: cause". A layer that adds genuinely new context is kept.
-func cleanProbeError(err error) string {
-	if err == nil {
-		return ""
-	}
-	msg := err.Error()
-	for {
-		inner := errors.Unwrap(err)
-		if inner == nil {
-			break
-		}
-		innerMsg := inner.Error()
-		prefix, ok := strings.CutSuffix(msg, innerMsg)
-		if !ok || prefix == "" || !strings.HasPrefix(innerMsg, prefix) {
-			break
-		}
-		msg, err = innerMsg, inner
-	}
-	return msg
-}
-
-// AlgForKey returns the JWS alg for a public key: EC P-256 -> ES256, RSA -> RS256.
-// The signer backend chooses the key type (the macOS keychain signer uses an
-// RSA-2048 key, hence RS256).
-func AlgForKey(pub crypto.PublicKey) (string, error) {
-	switch k := pub.(type) {
-	case *ecdsa.PublicKey:
-		if k.Curve == elliptic.P256() {
-			return AlgES256, nil
-		}
-		return "", fmt.Errorf("keysigner: unsupported EC curve %q (only P-256/ES256)", k.Curve.Params().Name)
-	case *rsa.PublicKey:
-		return AlgRS256, nil
-	default:
-		return "", fmt.Errorf("keysigner: unsupported public key type %T", pub)
-	}
-}
-
-// ecdsaDERToJOSE converts an ASN.1 DER-encoded ECDSA signature — the form most
-// TEE/TPM backends emit (e.g. facebookincubator/sks marshals the TPM's r,s with
-// asn1.Marshal) — into the fixed-width r||s form JWS requires for ES256
-// (RFC 7518 §3.4). byteLen is the curve coordinate size (32 for P-256), so the
-// result is exactly 2*byteLen bytes with r and s each left-zero-padded.
-//
-// This is intentionally part of the pure-stdlib core (not a platform signer) so
-// it can be unit-tested with a software key on any machine, including TPM-less CI.
-func ecdsaDERToJOSE(der []byte, byteLen int) ([]byte, error) {
-	var sig struct{ R, S *big.Int }
-	rest, err := asn1.Unmarshal(der, &sig)
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: parse ECDSA DER signature: %w", err)
-	}
-	if len(rest) != 0 {
-		return nil, fmt.Errorf("keysigner: %d trailing byte(s) after ECDSA DER signature", len(rest))
-	}
-	if sig.R == nil || sig.S == nil || sig.R.Sign() <= 0 || sig.S.Sign() <= 0 {
-		return nil, fmt.Errorf("keysigner: ECDSA signature has non-positive r/s")
-	}
-	// Guard before FillBytes, which panics if the scalar does not fit in byteLen.
-	if sig.R.BitLen() > byteLen*8 || sig.S.BitLen() > byteLen*8 {
-		return nil, fmt.Errorf("keysigner: ECDSA r/s exceeds %d-byte coordinate", byteLen)
-	}
-	out := make([]byte, 2*byteLen)
-	sig.R.FillBytes(out[:byteLen])
-	sig.S.FillBytes(out[byteLen:])
-	return out, nil
-}
-
-// EncodePublicKey marshals pub to PKIX DER and base64-encodes it (std encoding),
-// matching the public-key form the registration backend binds to the app.
-func EncodePublicKey(pub crypto.PublicKey) (string, error) {
-	der, err := x509.MarshalPKIXPublicKey(pub)
-	if err != nil {
-		return "", fmt.Errorf("keysigner: encode public key: %w", err)
-	}
-	return base64.StdEncoding.EncodeToString(der), nil
-}
-
-// PublicKeyJWK returns the RFC 7517 JSON Web Key for pub, used to embed the
-// public key in the attestation JWT's "jwk" header so the registration backend
-// can bind it to the app. EC keys use base64url fixed-width coordinates
-// (RFC 7518 §6.2.1); RSA keys use base64url-encoded modulus and exponent.
-func PublicKeyJWK(pub crypto.PublicKey) (map[string]any, error) {
-	switch k := pub.(type) {
-	case *ecdsa.PublicKey:
-		if k.Curve != elliptic.P256() {
-			return nil, fmt.Errorf("keysigner: JWK supports EC P-256 only, got %q", k.Curve.Params().Name)
-		}
-		const coordLen = 32 // P-256 field element size
-		x := make([]byte, coordLen)
-		y := make([]byte, coordLen)
-		k.X.FillBytes(x)
-		k.Y.FillBytes(y)
-		return map[string]any{
-			"use": "sig",
-			"kty": "EC",
-			"crv": "P-256",
-			"x":   base64.RawURLEncoding.EncodeToString(x),
-			"y":   base64.RawURLEncoding.EncodeToString(y),
-		}, nil
-	case *rsa.PublicKey:
-		return map[string]any{
-			"use": "sig",
-			"kty": "RSA",
-			"n":   base64.RawURLEncoding.EncodeToString(k.N.Bytes()),
-			"e":   base64.RawURLEncoding.EncodeToString(big.NewInt(int64(k.E)).Bytes()),
-		}, nil
-	default:
-		return nil, fmt.Errorf("keysigner: unsupported public key type %T for JWK", pub)
-	}
-}

internal/keysigner/keysigner_test.go

@@ -1,240 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package keysigner
-
-import (
-	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/elliptic"
-	"crypto/rand"
-	"crypto/rsa"
-	"crypto/sha256"
-	"crypto/x509"
-	"encoding/base64"
-	"errors"
-	"fmt"
-	"math/big"
-	"reflect"
-	"testing"
-)
-
-func TestAlgForKey(t *testing.T) {
-	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if alg, err := AlgForKey(ec.Public()); err != nil || alg != AlgES256 {
-		t.Errorf("P-256: alg=%q err=%v, want ES256/nil", alg, err)
-	}
-
-	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if alg, err := AlgForKey(rsaKey.Public()); err != nil || alg != AlgRS256 {
-		t.Errorf("RSA: alg=%q err=%v, want RS256/nil", alg, err)
-	}
-
-	ec384, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := AlgForKey(ec384.Public()); err == nil {
-		t.Error("P-384: expected unsupported-curve error")
-	}
-
-	if _, err := AlgForKey("not a key"); err == nil {
-		t.Error("string: expected unsupported-type error")
-	}
-}
-
-func TestEncodePublicKeyRoundTrip(t *testing.T) {
-	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	enc, err := EncodePublicKey(ec.Public())
-	if err != nil {
-		t.Fatal(err)
-	}
-	der, err := base64.StdEncoding.DecodeString(enc)
-	if err != nil {
-		t.Fatalf("not valid base64: %v", err)
-	}
-	pub, err := x509.ParsePKIXPublicKey(der)
-	if err != nil {
-		t.Fatalf("not valid PKIX: %v", err)
-	}
-	if !reflect.DeepEqual(pub, ec.Public()) {
-		t.Error("public key did not round-trip")
-	}
-}
-
-func TestPublicKeyJWK_EC(t *testing.T) {
-	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	jwk, err := PublicKeyJWK(ec.Public())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if jwk["kty"] != "EC" || jwk["crv"] != "P-256" {
-		t.Errorf("jwk = %v, want kty=EC crv=P-256", jwk)
-	}
-	if jwk["use"] != "sig" {
-		t.Errorf("jwk use = %v, want sig", jwk["use"])
-	}
-	x, _ := jwk["x"].(string)
-	xb, err := base64.RawURLEncoding.DecodeString(x)
-	if err != nil || len(xb) != 32 {
-		t.Errorf("x = %q (decoded %d bytes), want 32-byte base64url", x, len(xb))
-	}
-	if _, ok := jwk["y"].(string); !ok {
-		t.Error("jwk missing y")
-	}
-}
-
-func TestPublicKeyJWK_RSA(t *testing.T) {
-	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
-	if err != nil {
-		t.Fatal(err)
-	}
-	jwk, err := PublicKeyJWK(rsaKey.Public())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if jwk["kty"] != "RSA" || jwk["n"] == "" || jwk["e"] == "" {
-		t.Errorf("jwk = %v, want kty=RSA with n,e", jwk)
-	}
-	if jwk["use"] != "sig" {
-		t.Errorf("jwk use = %v, want sig", jwk["use"])
-	}
-}
-
-func TestPublicKeyJWK_UnsupportedCurve(t *testing.T) {
-	ec384, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := PublicKeyJWK(ec384.Public()); err == nil {
-		t.Error("P-384: expected error")
-	}
-}
-
-func TestECDSADERToJOSE(t *testing.T) {
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	// Iterate so we hit signatures whose r or s has its high bit set (ASN.1 pads
-	// those with a leading 0x00) and whose scalars are short (need left-zero
-	// padding) — verifying fixed-width conversion in both directions.
-	for i := 0; i < 64; i++ {
-		digest := sha256.Sum256([]byte{byte(i), byte(i >> 8), 'j', 'w', 't'})
-		der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
-		if err != nil {
-			t.Fatal(err)
-		}
-		jose, err := ecdsaDERToJOSE(der, 32)
-		if err != nil {
-			t.Fatalf("iter %d: %v", i, err)
-		}
-		if len(jose) != 64 {
-			t.Fatalf("iter %d: len(jose)=%d, want 64 (fixed-width r||s)", i, len(jose))
-		}
-		r := new(big.Int).SetBytes(jose[:32])
-		s := new(big.Int).SetBytes(jose[32:])
-		if !ecdsa.Verify(&key.PublicKey, digest[:], r, s) {
-			t.Fatalf("iter %d: converted r||s did not verify against the public key", i)
-		}
-	}
-}
-
-func TestECDSADERToJOSE_Errors(t *testing.T) {
-	if _, err := ecdsaDERToJOSE([]byte{0x01, 0x02, 0x03}, 32); err == nil {
-		t.Error("garbage DER: expected error")
-	}
-	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	digest := sha256.Sum256([]byte("trailing"))
-	der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := ecdsaDERToJOSE(append(der, 0x00), 32); err == nil {
-		t.Error("DER with trailing byte: expected error")
-	}
-}
-
-type stubSigner struct{}
-
-func (stubSigner) EnsureKey(context.Context, KeyRef) (crypto.PublicKey, error)  { return nil, nil }
-func (stubSigner) PublicKey(context.Context, KeyRef) (crypto.PublicKey, error)  { return nil, nil }
-func (stubSigner) Sign(context.Context, KeyRef, []byte) ([]byte, string, error) { return nil, "", nil }
-
-func TestCleanProbeError(t *testing.T) {
-	cause := errors.New("open /dev/tpmrm0: permission denied")
-	const p = "sks: error fetching Secure Hardware Vendor Data: "
-
-	// sks double-wraps with the same %w prefix → collapse to a single prefix.
-	doubled := fmt.Errorf(p+"%w", fmt.Errorf(p+"%w", cause))
-	if got, want := cleanProbeError(doubled), p+cause.Error(); got != want {
-		t.Errorf("doubled: got %q, want %q", got, want)
-	}
-	// Triple wrap collapses too.
-	if got, want := cleanProbeError(fmt.Errorf(p+"%w", doubled)), p+cause.Error(); got != want {
-		t.Errorf("tripled: got %q, want %q", got, want)
-	}
-	// A layer adding genuinely new context is preserved.
-	if got, want := cleanProbeError(fmt.Errorf("load: %w", cause)), "load: "+cause.Error(); got != want {
-		t.Errorf("distinct prefix: got %q, want %q", got, want)
-	}
-	// nil and unwrapped-leaf cases.
-	if got := cleanProbeError(nil); got != "" {
-		t.Errorf("nil: got %q, want empty", got)
-	}
-	if got := cleanProbeError(cause); got != cause.Error() {
-		t.Errorf("leaf: got %q, want %q", got, cause.Error())
-	}
-}
-
-type proberSigner struct {
-	stubSigner
-	info HardwareInfo
-}
-
-func (p proberSigner) ProbeHardware(context.Context) (HardwareInfo, error) { return p.info, nil }
-
-func TestProbeHardware(t *testing.T) {
-	// nil signer and a signer that does not implement HardwareProber both yield ok=false.
-	if _, ok, _ := probeHardware(context.Background(), nil); ok {
-		t.Error("nil signer: ok should be false")
-	}
-	if _, ok, _ := probeHardware(context.Background(), stubSigner{}); ok {
-		t.Error("non-prober signer: ok should be false")
-	}
-
-	want := HardwareInfo{Backend: "tpm2", Available: true, VendorName: "ACME"}
-	info, ok, err := probeHardware(context.Background(), proberSigner{info: want})
-	if err != nil || !ok {
-		t.Fatalf("prober: ok=%v err=%v, want true/nil", ok, err)
-	}
-	if info != want {
-		t.Errorf("info = %+v, want %+v", info, want)
-	}
-}
-
-func TestRegistry(t *testing.T) {
-	if Active() != nil {
-		t.Skip("a signer is already registered in this build")
-	}
-	Register(stubSigner{})
-	if _, ok := Active().(stubSigner); !ok {
-		t.Error("Active did not return the registered signer")
-	}
-}

internal/keysigner/registry.go

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package keysigner
-
-import "sync"
-
-var (
-	mu     sync.RWMutex
-	active Signer
-)
-
-// Register sets the active Signer. It is typically called from the init() of a
-// build-tagged or extension package that provides the platform TEE/Keychain
-// implementation. The last registration wins (one backend per platform).
-func Register(s Signer) {
-	mu.Lock()
-	defer mu.Unlock()
-	active = s
-}
-
-// Active returns the registered Signer, or nil if none is available — in which
-// case private_key_jwt is unsupported on this build and only client_secret auth
-// can be used.
-func Active() Signer {
-	mu.RLock()
-	defer mu.RUnlock()
-	return active
-}

internal/keysigner/signer_keychain_darwin.go

@@ -1,606 +0,0 @@
-//go:build darwin
-
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// macOS non-exportable Keychain signer (compiled into every darwin build).
-//
-// It does NOT use the Secure Enclave / hardware TEE (which would require
-// code-signing entitlements that are unfriendly to open source). Instead it
-// generates an RSA-2048 key in software, imports it into a dedicated app
-// keychain as NON-EXTRACTABLE (`security import -x`), then deletes the software
-// copy — so the private key can sign but can never be exported. Signing is
-// RSASSA-PKCS1v15-SHA256 (RS256).
-//
-// Unlike the original revision, this implementation calls the Security and
-// CoreFoundation frameworks via RUNTIME FFI (github.com/ebitengine/purego)
-// instead of cgo. The security model is identical (the private key is still a
-// non-extractable keychain key and every signature is produced by the OS via
-// SecKeyCreateSignature), but the binary builds with CGO_ENABLED=0 and can be
-// cross-compiled for darwin from any host — so release binaries no longer
-// require a native macOS build runner.
-//
-// Build with:  go build   (cgo-free; compiled into every darwin build, no tag)
-package keysigner
-
-import (
-	"context"
-	"crypto"
-	"crypto/rand"
-	"crypto/rsa"
-	"crypto/sha1"
-	"crypto/sha256"
-	"crypto/x509"
-	"encoding/base64"
-	"encoding/hex"
-	"encoding/json"
-	"encoding/pem"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"unsafe"
-
-	"github.com/ebitengine/purego"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// ---- Security / CoreFoundation runtime bindings (purego, no cgo) ----
-
-const (
-	cfFrameworkPath  = "/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation"
-	secFrameworkPath = "/System/Library/Frameworks/Security.framework/Security"
-
-	// kCFStringEncodingUTF8 (CFStringBuiltInEncodings).
-	cfStringEncodingUTF8 = 0x08000100
-
-	// OSStatus values.
-	errSecSuccess = 0
-)
-
-var (
-	ffiOnce sync.Once
-	ffiErr  error
-
-	cfDataCreate          func(alloc uintptr, bytes *byte, length int) uintptr
-	cfDataGetLength       func(d uintptr) int
-	cfDataGetBytePtr      func(d uintptr) unsafe.Pointer
-	cfStringCreate        func(alloc uintptr, cstr *byte, encoding uint32) uintptr
-	cfArrayCreate         func(alloc uintptr, values *uintptr, numValues int, cb uintptr) uintptr
-	cfDictCreateMutable   func(alloc uintptr, capacity int, keyCB, valCB uintptr) uintptr
-	cfDictSetValue        func(dict, key, val uintptr)
-	cfRelease             func(ref uintptr)
-	cfErrorGetCode        func(e uintptr) int
-	secKeychainOpen       func(path *byte, out *uintptr) int32
-	secItemCopyMatching   func(query uintptr, result *uintptr) int32
-	secItemUpdate         func(query, attrs uintptr) int32
-	secKeyCreateSignature func(key, algo, data uintptr, errOut *uintptr) uintptr
-
-	// CFTypeRef data-symbol constants (deref to obtain the held ref value).
-	kSecClass                uintptr
-	kSecClassKey             uintptr
-	kSecAttrKeyClass         uintptr
-	kSecAttrKeyClassPrivate  uintptr
-	kSecAttrKeyType          uintptr
-	kSecAttrKeyTypeRSA       uintptr
-	kSecAttrApplicationLabel uintptr
-	kSecReturnRef            uintptr
-	kSecMatchSearchList      uintptr
-	kSecAttrLabel            uintptr
-	kCFBooleanTrue           uintptr
-	algRSAPKCS1SHA256        uintptr
-
-	// Struct-symbol constants (passed BY ADDRESS, not dereferenced).
-	cbTypeArray uintptr
-	cbDictKey   uintptr
-	cbDictValue uintptr
-)
-
-// loadFFI resolves the framework functions and constants once. Any failure
-// (framework missing, symbol absent) is returned to every caller so signing
-// fails cleanly rather than crashing.
-func loadFFI() error {
-	ffiOnce.Do(func() {
-		cf, err := purego.Dlopen(cfFrameworkPath, purego.RTLD_NOW|purego.RTLD_GLOBAL)
-		if err != nil {
-			ffiErr = fmt.Errorf("keysigner: dlopen CoreFoundation: %w", err)
-			return
-		}
-		sec, err := purego.Dlopen(secFrameworkPath, purego.RTLD_NOW|purego.RTLD_GLOBAL)
-		if err != nil {
-			ffiErr = fmt.Errorf("keysigner: dlopen Security: %w", err)
-			return
-		}
-
-		purego.RegisterLibFunc(&cfDataCreate, cf, "CFDataCreate")
-		purego.RegisterLibFunc(&cfDataGetLength, cf, "CFDataGetLength")
-		purego.RegisterLibFunc(&cfDataGetBytePtr, cf, "CFDataGetBytePtr")
-		purego.RegisterLibFunc(&cfStringCreate, cf, "CFStringCreateWithCString")
-		purego.RegisterLibFunc(&cfArrayCreate, cf, "CFArrayCreate")
-		purego.RegisterLibFunc(&cfDictCreateMutable, cf, "CFDictionaryCreateMutable")
-		purego.RegisterLibFunc(&cfDictSetValue, cf, "CFDictionarySetValue")
-		purego.RegisterLibFunc(&cfRelease, cf, "CFRelease")
-		purego.RegisterLibFunc(&cfErrorGetCode, cf, "CFErrorGetCode")
-		purego.RegisterLibFunc(&secKeychainOpen, sec, "SecKeychainOpen")
-		purego.RegisterLibFunc(&secItemCopyMatching, sec, "SecItemCopyMatching")
-		purego.RegisterLibFunc(&secItemUpdate, sec, "SecItemUpdate")
-		purego.RegisterLibFunc(&secKeyCreateSignature, sec, "SecKeyCreateSignature")
-
-		// CFStringRef/CFBooleanRef constants: Dlsym gives the address of the
-		// exported variable; deref once to read the ref it holds.
-		derefs := []struct {
-			dst    *uintptr
-			handle uintptr
-			name   string
-		}{
-			{&kSecClass, sec, "kSecClass"},
-			{&kSecClassKey, sec, "kSecClassKey"},
-			{&kSecAttrKeyClass, sec, "kSecAttrKeyClass"},
-			{&kSecAttrKeyClassPrivate, sec, "kSecAttrKeyClassPrivate"},
-			{&kSecAttrKeyType, sec, "kSecAttrKeyType"},
-			{&kSecAttrKeyTypeRSA, sec, "kSecAttrKeyTypeRSA"},
-			{&kSecAttrApplicationLabel, sec, "kSecAttrApplicationLabel"},
-			{&kSecReturnRef, sec, "kSecReturnRef"},
-			{&kSecMatchSearchList, sec, "kSecMatchSearchList"},
-			{&kSecAttrLabel, sec, "kSecAttrLabel"},
-			{&kCFBooleanTrue, cf, "kCFBooleanTrue"},
-			{&algRSAPKCS1SHA256, sec, "kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256"},
-		}
-		for _, d := range derefs {
-			sym, e := purego.Dlsym(d.handle, d.name)
-			if e != nil {
-				ffiErr = fmt.Errorf("keysigner: dlsym %s: %w", d.name, e)
-				return
-			}
-			if sym == 0 {
-				ffiErr = fmt.Errorf("keysigner: dlsym %s returned zero address", d.name)
-				return
-			}
-			// deref of a stable dylib data-symbol address (not Go-managed memory), so safe.
-			*d.dst = *(*uintptr)(unsafe.Pointer(sym)) //nolint:govet // unsafeptr: see comment above
-		}
-
-		// Callback structs are passed by address (no deref).
-		addrs := []struct {
-			dst    *uintptr
-			handle uintptr
-			name   string
-		}{
-			{&cbTypeArray, cf, "kCFTypeArrayCallBacks"},
-			{&cbDictKey, cf, "kCFTypeDictionaryKeyCallBacks"},
-			{&cbDictValue, cf, "kCFTypeDictionaryValueCallBacks"},
-		}
-		for _, a := range addrs {
-			sym, e := purego.Dlsym(a.handle, a.name)
-			if e != nil {
-				ffiErr = fmt.Errorf("keysigner: dlsym %s: %w", a.name, e)
-				return
-			}
-			if sym == 0 {
-				ffiErr = fmt.Errorf("keysigner: dlsym %s returned zero address", a.name)
-				return
-			}
-			*a.dst = sym
-		}
-	})
-	return ffiErr
-}
-
-// cstr returns a pointer to a NUL-terminated copy of s. The backing array stays
-// alive while the returned pointer is reachable.
-func cstr(s string) *byte {
-	b := append([]byte(s), 0)
-	return &b[0]
-}
-
-// cfBytes wraps Go bytes in a CFData (CFDataCreate copies the bytes). Caller
-// releases the returned CFDataRef.
-func cfBytes(b []byte) uintptr {
-	var p *byte
-	if len(b) > 0 {
-		p = &b[0]
-	}
-	d := cfDataCreate(0, p, len(b))
-	runtime.KeepAlive(b)
-	return d
-}
-
-// keychainSearchArray opens the dedicated keychain file and wraps it in a
-// CFArray for kSecMatchSearchList. Caller releases the returned array.
-//
-// NOTE: SecKeychainOpen / the file-based keychain are deprecated by Apple in
-// favor of the data-protection keychain. They still function on current macOS;
-// migrating off them is tracked separately and is independent of the cgo→purego
-// change (the original cgo version used the same APIs).
-func keychainSearchArray(keychainPath string) (uintptr, error) {
-	var kc uintptr
-	if st := secKeychainOpen(cstr(keychainPath), &kc); st != errSecSuccess {
-		return 0, keychainError("open keychain", int(st))
-	}
-	vals := [1]uintptr{kc}
-	arr := cfArrayCreate(0, &vals[0], 1, cbTypeArray)
-	cfRelease(kc) // the array retains it
-	if arr == 0 {
-		return 0, fmt.Errorf("keysigner: CFArrayCreate(search list) failed")
-	}
-	return arr, nil
-}
-
-// findPrivateKey locates the non-extractable private key by its application
-// label within the dedicated keychain. Caller releases the returned SecKeyRef.
-func findPrivateKey(appLabel []byte, keychainPath string) (uintptr, error) {
-	search, err := keychainSearchArray(keychainPath)
-	if err != nil {
-		return 0, err
-	}
-	defer cfRelease(search)
-
-	labelData := cfBytes(appLabel)
-	defer cfRelease(labelData)
-
-	q := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
-	if q == 0 {
-		return 0, fmt.Errorf("keysigner: CFDictionaryCreateMutable(query) failed")
-	}
-	defer cfRelease(q)
-	cfDictSetValue(q, kSecClass, kSecClassKey)
-	cfDictSetValue(q, kSecAttrKeyClass, kSecAttrKeyClassPrivate)
-	cfDictSetValue(q, kSecAttrKeyType, kSecAttrKeyTypeRSA)
-	cfDictSetValue(q, kSecAttrApplicationLabel, labelData)
-	cfDictSetValue(q, kSecReturnRef, kCFBooleanTrue)
-	cfDictSetValue(q, kSecMatchSearchList, search)
-
-	var keyRef uintptr
-	if st := secItemCopyMatching(q, &keyRef); st != errSecSuccess {
-		return 0, keychainError("find private key", int(st))
-	}
-	return keyRef, nil
-}
-
-// securityBin is invoked by absolute path so a poisoned PATH cannot hijack it.
-const securityBin = "/usr/bin/security"
-
-// keychainSigner implements Signer using a macOS non-exportable Keychain key.
-type keychainSigner struct{}
-
-func init() { Register(keychainSigner{}) }
-
-// ProbeHardware reports the macOS Keychain backend backing this signer. The
-// keychain signer is compiled into every darwin build and needs no special
-// hardware, so it reports available whenever the Security tooling is present.
-// It performs no key access, so it never prompts. Implementing HardwareProber
-// is what lets `doctor` report the signer as present rather than treating the
-// (prober-less) signer as "no TEE signer in this build".
-func (keychainSigner) ProbeHardware(_ context.Context) (HardwareInfo, error) {
-	info := HardwareInfo{Backend: "keychain", VendorName: "macOS Keychain"}
-	// A missing security tool is a status (Available=false via Reason), not a
-	// probe error — so we deliberately return a nil error here.
-	if _, err := vfs.Stat(securityBin); err != nil {
-		info.Reason = securityBin + " not found"
-		return info, nil //nolint:nilerr // absence is reported via Reason, not as an error
-	}
-	info.Available = true
-	return info, nil
-}
-
-func (keychainSigner) EnsureKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
-	if md, err := readKeyMetadata(ref.Label); err == nil {
-		return decodePublicKey(md.PublicKey)
-	} else if !os.IsNotExist(err) {
-		return nil, err
-	}
-	return createKeychainKey(ref.Label)
-}
-
-func (keychainSigner) PublicKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
-	md, err := readKeyMetadata(ref.Label)
-	if err != nil {
-		return nil, err
-	}
-	return decodePublicKey(md.PublicKey)
-}
-
-func (keychainSigner) Sign(_ context.Context, ref KeyRef, signingInput []byte) ([]byte, string, error) {
-	if err := loadFFI(); err != nil {
-		return nil, "", err
-	}
-	md, err := readKeyMetadata(ref.Label)
-	if err != nil {
-		return nil, "", err
-	}
-	appLabel, err := hex.DecodeString(md.AppLabel)
-	if err != nil {
-		return nil, "", fmt.Errorf("keysigner: decode app label: %w", err)
-	}
-	if len(appLabel) == 0 {
-		// Guard the &appLabel[0] pointer below against corrupted metadata.
-		return nil, "", fmt.Errorf("keysigner: key metadata for %q has empty app label", ref.Label)
-	}
-	keychain, err := ensureKeychain()
-	if err != nil {
-		return nil, "", err
-	}
-
-	keyRef, err := findPrivateKey(appLabel, keychain)
-	if err != nil {
-		return nil, "", err
-	}
-	defer cfRelease(keyRef)
-
-	digest := sha256.Sum256(signingInput)
-	digestData := cfBytes(digest[:])
-	defer cfRelease(digestData)
-
-	var errRef uintptr
-	sigRef := secKeyCreateSignature(keyRef, algRSAPKCS1SHA256, digestData, &errRef)
-	if sigRef == 0 {
-		code := 0
-		if errRef != 0 {
-			code = cfErrorGetCode(errRef)
-			cfRelease(errRef)
-		}
-		return nil, "", fmt.Errorf("keysigner: SecKeyCreateSignature failed (CFError %d)", code)
-	}
-	defer cfRelease(sigRef)
-
-	n := cfDataGetLength(sigRef)
-	bp := cfDataGetBytePtr(sigRef)
-	out := make([]byte, n)
-	copy(out, unsafe.Slice((*byte)(bp), n))
-	// RS256: the SecKey PKCS1v15-SHA256 signature is the JOSE signature as-is.
-	return out, AlgRS256, nil
-}
-
-// keyMetadata records the public key + the keychain application-label used to
-// locate the non-extractable private key.
-type keyMetadata struct {
-	PublicKey string `json:"public_key"` // PKIX DER, std base64 (see EncodePublicKey)
-	AppLabel  string `json:"app_label"`  // hex(sha1(PKCS1 public key))
-}
-
-func createKeychainKey(label string) (crypto.PublicKey, error) {
-	metadataPath, err := keyMetadataPath(label)
-	if err != nil {
-		return nil, err
-	}
-
-	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: generate RSA key: %w", err)
-	}
-	appLabel := sha1.Sum(x509.MarshalPKCS1PublicKey(&privateKey.PublicKey))
-
-	pemFile, err := vfs.CreateTemp("", "lark-keysigner-*.pem")
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: temp key file: %w", err)
-	}
-	pemPath := pemFile.Name()
-	defer vfs.Remove(pemPath)
-	if err := pemFile.Chmod(0600); err != nil {
-		pemFile.Close()
-		return nil, err
-	}
-	der := x509.MarshalPKCS1PrivateKey(privateKey)
-	if err := pem.Encode(pemFile, &pem.Block{Type: "RSA PRIVATE KEY", Bytes: der}); err != nil {
-		pemFile.Close()
-		return nil, err
-	}
-	if err := pemFile.Close(); err != nil {
-		return nil, err
-	}
-
-	executable, err := vfs.Executable()
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: resolve executable: %w", err)
-	}
-	keychain, err := ensureKeychain()
-	if err != nil {
-		return nil, err
-	}
-	// -x: import as NON-EXTRACTABLE; the software copy (pemPath) is then removed.
-	importCmd := exec.Command(securityBin, "import", pemPath, "-k", keychain, "-t", "priv", "-f", "openssl", "-x", "-A", "-T", executable)
-	if out, err := importCmd.CombinedOutput(); err != nil {
-		return nil, fmt.Errorf("keysigner: import non-extractable key: %w: %s", err, summarizeCmdOutput(out))
-	}
-	if err := setKeychainKeyLabel(appLabel[:], keychain, label); err != nil {
-		return nil, err
-	}
-
-	encodedPub, err := EncodePublicKey(&privateKey.PublicKey)
-	if err != nil {
-		return nil, err
-	}
-	if err := writeKeyMetadata(metadataPath, keyMetadata{PublicKey: encodedPub, AppLabel: hex.EncodeToString(appLabel[:])}); err != nil {
-		return nil, err
-	}
-	return &privateKey.PublicKey, nil
-}
-
-func setKeychainKeyLabel(appLabel []byte, keychain, label string) error {
-	if err := loadFFI(); err != nil {
-		return err
-	}
-	search, err := keychainSearchArray(keychain)
-	if err != nil {
-		return err
-	}
-	defer cfRelease(search)
-
-	labelData := cfBytes(appLabel)
-	defer cfRelease(labelData)
-
-	q := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
-	if q == 0 {
-		return fmt.Errorf("keysigner: CFDictionaryCreateMutable(query) failed")
-	}
-	defer cfRelease(q)
-	cfDictSetValue(q, kSecClass, kSecClassKey)
-	cfDictSetValue(q, kSecAttrKeyClass, kSecAttrKeyClassPrivate)
-	cfDictSetValue(q, kSecAttrKeyType, kSecAttrKeyTypeRSA)
-	cfDictSetValue(q, kSecAttrApplicationLabel, labelData)
-	cfDictSetValue(q, kSecMatchSearchList, search)
-
-	cfLabel := cfStringCreate(0, cstr(label), cfStringEncodingUTF8)
-	if cfLabel == 0 {
-		return fmt.Errorf("keysigner: CFStringCreateWithCString failed")
-	}
-	defer cfRelease(cfLabel)
-	attrs := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
-	if attrs == 0 {
-		return fmt.Errorf("keysigner: CFDictionaryCreateMutable(attrs) failed")
-	}
-	defer cfRelease(attrs)
-	cfDictSetValue(attrs, kSecAttrLabel, cfLabel)
-
-	if st := secItemUpdate(q, attrs); st != errSecSuccess {
-		return keychainError("set keychain key label", int(st))
-	}
-	return nil
-}
-
-func decodePublicKey(encoded string) (crypto.PublicKey, error) {
-	der, err := base64.StdEncoding.DecodeString(encoded)
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: decode public key: %w", err)
-	}
-	return x509.ParsePKIXPublicKey(der)
-}
-
-func readKeyMetadata(label string) (*keyMetadata, error) {
-	path, err := keyMetadataPath(label)
-	if err != nil {
-		return nil, err
-	}
-	data, err := vfs.ReadFile(path)
-	if err != nil {
-		return nil, err // preserves os.ErrNotExist for EnsureKey
-	}
-	var md keyMetadata
-	if err := json.Unmarshal(data, &md); err != nil {
-		return nil, fmt.Errorf("keysigner: parse key metadata: %w", err)
-	}
-	return &md, nil
-}
-
-func writeKeyMetadata(path string, md keyMetadata) error {
-	if err := vfs.MkdirAll(filepath.Dir(path), 0700); err != nil {
-		return err
-	}
-	data, err := json.MarshalIndent(md, "", "  ")
-	if err != nil {
-		return err
-	}
-	return vfs.WriteFile(path, data, 0600)
-}
-
-func ensureKeychain() (string, error) {
-	keychainPath, err := keychainFilePath()
-	if err != nil {
-		return "", err
-	}
-	password, err := keychainPassword()
-	if err != nil {
-		return "", err
-	}
-	if _, err := vfs.Stat(keychainPath); err != nil {
-		if !os.IsNotExist(err) {
-			return "", fmt.Errorf("keysigner: stat keychain: %w", err)
-		}
-		if err := vfs.MkdirAll(filepath.Dir(keychainPath), 0700); err != nil {
-			return "", err
-		}
-		for _, args := range [][]string{
-			{"create-keychain", "-p", password, keychainPath},
-			{"set-keychain-settings", keychainPath},
-			{"unlock-keychain", "-p", password, keychainPath},
-		} {
-			if out, err := exec.Command(securityBin, args...).CombinedOutput(); err != nil {
-				return "", fmt.Errorf("keysigner: security %s: %w: %s", args[0], err, summarizeCmdOutput(out))
-			}
-		}
-	}
-	return keychainPath, nil
-}
-
-func keysignerDir() (string, error) {
-	configDir, err := os.UserConfigDir()
-	if err != nil {
-		return "", fmt.Errorf("keysigner: resolve config dir: %w", err)
-	}
-	return filepath.Join(configDir, "lark-cli", "keysigner"), nil
-}
-
-func keychainFilePath() (string, error) {
-	dir, err := keysignerDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(dir, "lark-cli.keychain"), nil
-}
-
-func keychainPassword() (string, error) {
-	dir, err := keysignerDir()
-	if err != nil {
-		return "", err
-	}
-	path := filepath.Join(dir, "keychain.pass")
-	if data, err := vfs.ReadFile(path); err == nil {
-		if pw := strings.TrimSpace(string(data)); pw != "" {
-			return pw, nil
-		}
-		return "", fmt.Errorf("keysigner: empty keychain password")
-	} else if !os.IsNotExist(err) {
-		return "", err
-	}
-	buf := make([]byte, 32)
-	if _, err := rand.Read(buf); err != nil {
-		return "", err
-	}
-	pw := hex.EncodeToString(buf)
-	if err := vfs.MkdirAll(filepath.Dir(path), 0700); err != nil {
-		return "", err
-	}
-	if err := vfs.WriteFile(path, []byte(pw+"\n"), 0600); err != nil {
-		return "", err
-	}
-	return pw, nil
-}
-
-func keyMetadataPath(label string) (string, error) {
-	dir, err := keysignerDir()
-	if err != nil {
-		return "", err
-	}
-	id := sha256.Sum256([]byte(label))
-	return filepath.Join(dir, "keys", hex.EncodeToString(id[:])+".json"), nil
-}
-
-// summarizeCmdOutput bounds external command output before it is embedded in
-// an error: first line only, capped at 200 chars.
-func summarizeCmdOutput(out []byte) string {
-	s := strings.TrimSpace(string(out))
-	if i := strings.IndexByte(s, '\n'); i >= 0 {
-		s = strings.TrimSpace(s[:i])
-	}
-	const maxLen = 200
-	if len(s) > maxLen {
-		s = s[:maxLen] + "..."
-	}
-	return s
-}
-
-func keychainError(operation string, status int) error {
-	switch status {
-	case -25299:
-		return fmt.Errorf("keysigner: %s: key already exists", operation)
-	case -25300:
-		return fmt.Errorf("keysigner: %s: key not found", operation)
-	case -2:
-		return fmt.Errorf("keysigner: %s: allocation failed", operation)
-	default:
-		return fmt.Errorf("keysigner: %s: Security framework status %d", operation, status)
-	}
-}

internal/keysigner/signer_keychain_darwin_test.go

@@ -1,62 +0,0 @@
-//go:build darwin
-
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package keysigner
-
-import (
-	"context"
-	"crypto"
-	"crypto/rsa"
-	"crypto/sha256"
-	"os"
-	"testing"
-)
-
-// TestKeychainSignerRegistered confirms the keychain_signer build self-registers
-// (init → Register), so keysigner.Active() is non-nil. No keychain access.
-func TestKeychainSignerRegistered(t *testing.T) {
-	if _, ok := Active().(keychainSigner); !ok {
-		t.Fatalf("Active() = %T, want keychainSigner (keychain_signer build must self-register)", Active())
-	}
-}
-
-// TestKeychainSignerRoundTrip creates a real non-extractable RSA key, signs, and
-// verifies RS256 against the returned public key. Gated by LARK_KEYCHAIN_IT
-// because it mutates the dedicated lark-cli keychain store. The signer is now
-// cgo-free (purego runtime FFI), so it runs with CGO_ENABLED=0. Run with:
-//
-//	LARK_KEYCHAIN_IT=1 go test -run RoundTrip ./internal/keysigner/
-func TestKeychainSignerRoundTrip(t *testing.T) {
-	if os.Getenv("LARK_KEYCHAIN_IT") == "" {
-		t.Skip("set LARK_KEYCHAIN_IT=1 to run (mutates the macOS keychain)")
-	}
-	s := keychainSigner{}
-	ref := KeyRef{Label: "lark-cli-keychain-it"}
-
-	pub, err := s.EnsureKey(context.Background(), ref)
-	if err != nil {
-		t.Fatalf("EnsureKey: %v", err)
-	}
-	rsaPub, ok := pub.(*rsa.PublicKey)
-	if !ok {
-		t.Fatalf("public key = %T, want *rsa.PublicKey", pub)
-	}
-	if alg, err := AlgForKey(pub); err != nil || alg != AlgRS256 {
-		t.Fatalf("AlgForKey = %q, %v; want RS256", alg, err)
-	}
-
-	input := []byte("header.payload")
-	sig, alg, err := s.Sign(context.Background(), ref, input)
-	if err != nil {
-		t.Fatalf("Sign: %v", err)
-	}
-	if alg != AlgRS256 {
-		t.Errorf("Sign alg = %q, want RS256", alg)
-	}
-	h := sha256.Sum256(input)
-	if err := rsa.VerifyPKCS1v15(rsaPub, crypto.SHA256, h[:], sig); err != nil {
-		t.Errorf("RS256 signature did not verify: %v", err)
-	}
-}

internal/keysigner/signer_sks.go

@@ -1,135 +0,0 @@
-//go:build linux || (windows && amd64)
-
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// TPM 2.0 signer (compiled into every linux and windows/amd64 build, no build
-// tag required), backed by github.com/facebookincubator/sks.
-//
-// sks holds a non-exportable ECDSA P-256 key in the platform TPM and signs
-// SHA-256 digests. On Linux it talks to /dev/tpmrm0; on Windows it uses the
-// Microsoft Platform Crypto Provider (CNG). Both backends return an ASN.1 DER
-// ECDSA signature, which we convert to the fixed-width r||s form JWS requires for
-// ES256 (see ecdsaDERToJOSE). One key is created on the first private_key_jwt
-// registration (DefaultKeyLabel) and reused for subsequent app registrations and
-// every client_assertion on the same device.
-//
-// Excluded from windows/arm64: the sks Windows dependency stack (go-ole) has no
-// arm64 VARIANT and fails to compile, so windows/arm64 falls back to
-// client_secret only (keysigner.Active() is nil). On darwin the keychain signer
-// is used instead. CGO is never required.
-package keysigner
-
-import (
-	"context"
-	"crypto"
-	"crypto/ecdsa"
-	"crypto/sha256"
-	"fmt"
-	"io"
-
-	"github.com/facebookincubator/flog"
-	"github.com/facebookincubator/sks"
-)
-
-// p256ByteLen is the P-256 coordinate width. sks regular keys are always ECDSA
-// P-256, so ES256 signatures are 2*p256ByteLen bytes of r||s.
-const p256ByteLen = 32
-
-// keyTag is the sks key tag. Both the Linux and Windows sks backends address
-// keys by label and ignore the tag, but the macOS backend uses it, so we set a
-// stable namespaced value for forward compatibility.
-const keyTag = "com.larksuite.cli"
-
-// sksSigner implements Signer (and HardwareProber) using a non-exportable
-// TPM 2.0 ECDSA key via sks.
-type sksSigner struct{}
-
-func init() {
-	Register(sksSigner{})
-	// This sks version logs verbose TPM-operation chatter to stderr via flog (a
-	// glog fork it owns exclusively) — e.g. "Loaded TPM device", "Found handle
-	// for key" on every sign. The CLI does not use flog, so silence it
-	// process-wide here; real failures are returned as errors, never relied upon
-	// from these logs. (Newer sks switched to slog, but that lands only on its
-	// go-1.24 line, which we avoid to keep the module on go 1.23.)
-	flog.SetOutput(io.Discard)
-}
-
-// EnsureKey returns the public key for ref, creating the TPM key if absent.
-// sks.NewKey is find-or-create: it returns the existing key when one is present.
-func (sksSigner) EnsureKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
-	key, err := sks.NewKey(ref.Label, keyTag, false, true, nil)
-	if err != nil {
-		return nil, fmt.Errorf("keysigner: ensure TPM key %q: %w", ref.Label, err)
-	}
-	defer key.Close()
-	return ecdsaPublic(ref.Label, key.Public())
-}
-
-// PublicKey returns the public key for ref without creating it. FromLabelTag does
-// not touch the TPM until Public() loads the sealed key; a missing key yields a
-// nil public key, which we surface as an error — at runtime the key MUST already
-// exist (it was bound to the app at registration), so we never silently mint a
-// new, unbound one here.
-func (sksSigner) PublicKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
-	pub := sks.FromLabelTag(ref.Label).Public()
-	if pub == nil {
-		return nil, fmt.Errorf("keysigner: TPM key %q not found", ref.Label)
-	}
-	return ecdsaPublic(ref.Label, pub)
-}
-
-// Sign signs signingInput with the TPM key and returns a JOSE-format ES256
-// signature (fixed-width r||s) plus its alg.
-func (sksSigner) Sign(_ context.Context, ref KeyRef, signingInput []byte) ([]byte, string, error) {
-	key, err := sks.NewKey(ref.Label, keyTag, false, true, nil)
-	if err != nil {
-		return nil, "", fmt.Errorf("keysigner: load TPM key %q: %w", ref.Label, err)
-	}
-	defer key.Close()
-
-	// ES256 signs the SHA-256 digest of the JWS signing input.
-	digest := sha256.Sum256(signingInput)
-	der, err := key.Sign(nil, digest[:], crypto.SHA256)
-	if err != nil {
-		return nil, "", fmt.Errorf("keysigner: TPM sign with key %q: %w", ref.Label, err)
-	}
-	// Both sks backends emit ASN.1 DER; JWS ES256 requires fixed-width r||s
-	// (RFC 7518 §3.4).
-	rs, err := ecdsaDERToJOSE(der, p256ByteLen)
-	if err != nil {
-		return nil, "", err
-	}
-	return rs, AlgES256, nil
-}
-
-// ProbeHardware reports on the TPM backing this signer without touching any key.
-// A failure to reach the TPM (no device, permission denied, not TPM 2.0) is
-// reported as Available=false with Reason set, NOT as a Go error — the probe
-// still succeeded in determining that the TEE is currently unusable.
-func (sksSigner) ProbeHardware(_ context.Context) (HardwareInfo, error) {
-	info := HardwareInfo{Backend: "tpm2"}
-	data, err := sks.GetSecureHardwareVendorData()
-	if err != nil {
-		info.Reason = cleanProbeError(err)
-		return info, nil
-	}
-	info.VendorName = data.VendorName
-	info.VendorInfo = data.VendorInfo
-	info.Available = data.IsTPM20CompliantDevice
-	if !info.Available {
-		info.Reason = "secure hardware is not a TPM 2.0 compliant device"
-	}
-	return info, nil
-}
-
-// ecdsaPublic asserts that an sks public key is an ECDSA key (it always is for
-// regular sks keys) so the caller gets the concrete type AlgForKey/PublicKeyJWK expect.
-func ecdsaPublic(label string, pub crypto.PublicKey) (*ecdsa.PublicKey, error) {
-	ecPub, ok := pub.(*ecdsa.PublicKey)
-	if !ok {
-		return nil, fmt.Errorf("keysigner: TPM key %q public is %T, want *ecdsa.PublicKey", label, pub)
-	}
-	return ecPub, nil
-}

internal/keysigner/signer_sks_test.go

@@ -1,122 +0,0 @@
-//go:build linux || (windows && amd64)
-
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package keysigner
-
-import (
-	"bytes"
-	"context"
-	"crypto/ecdsa"
-	"crypto/sha256"
-	"io"
-	"math/big"
-	"strings"
-	"testing"
-
-	"github.com/facebookincubator/flog"
-	"github.com/facebookincubator/sks"
-)
-
-// TestFlogSilenced verifies the mechanism init() relies on to keep sks's flog
-// TPM chatter off the CLI's stderr: SetOutput redirects flog, and io.Discard
-// drops it. Cleanup restores io.Discard so init()'s silencing holds for the
-// rest of the package's tests.
-func TestFlogSilenced(t *testing.T) {
-	var buf bytes.Buffer
-	flog.SetOutput(&buf)
-	t.Cleanup(func() { flog.SetOutput(io.Discard) })
-
-	flog.Info("captured-line")
-	if !strings.Contains(buf.String(), "captured-line") {
-		t.Fatalf("flog.SetOutput(buffer) did not capture output: %q", buf.String())
-	}
-
-	flog.SetOutput(io.Discard)
-	buf.Reset()
-	flog.Info("should-be-discarded")
-	if buf.Len() != 0 {
-		t.Errorf("flog output not discarded: %q", buf.String())
-	}
-}
-
-// requireTEE skips the test unless the TPM is present and usable. On a Linux
-// machine with a TPM but a restrictive device owner (`/dev/tpmrm0` is `tss:tss`
-// by default), grant access with `sudo usermod -aG tss $USER` then re-login, or
-// run the test under sudo.
-func requireTEE(t *testing.T) {
-	t.Helper()
-	info, err := sksSigner{}.ProbeHardware(context.Background())
-	if err != nil || !info.Available {
-		reason := info.Reason
-		if err != nil {
-			reason = err.Error()
-		}
-		t.Skipf("TEE not available (%s)", reason)
-	}
-}
-
-// TestSKSSignerRoundTrip exercises the full registration→assertion contract
-// against the real TPM: create the key, read it back without creating, derive
-// the JWS alg + JWK, sign, and verify the fixed-width r||s output.
-func TestSKSSignerRoundTrip(t *testing.T) {
-	requireTEE(t)
-
-	var s sksSigner
-	ctx := context.Background()
-	ref := KeyRef{Label: "larksuite-cli-test"}
-
-	// Best-effort cleanup so the test key does not linger in the TPM-sealed store.
-	t.Cleanup(func() {
-		if k, err := sks.NewKey(ref.Label, keyTag, false, true, nil); err == nil {
-			_ = k.Remove()
-			_ = k.Close()
-		}
-	})
-
-	pub, err := s.EnsureKey(ctx, ref)
-	if err != nil {
-		t.Fatalf("EnsureKey: %v", err)
-	}
-	ecPub, ok := pub.(*ecdsa.PublicKey)
-	if !ok {
-		t.Fatalf("EnsureKey returned %T, want *ecdsa.PublicKey", pub)
-	}
-
-	// PublicKey (no-create) must return the same key bound at EnsureKey.
-	pub2, err := s.PublicKey(ctx, ref)
-	if err != nil {
-		t.Fatalf("PublicKey: %v", err)
-	}
-	if !ecPub.Equal(pub2) {
-		t.Fatal("PublicKey returned a different key than EnsureKey")
-	}
-
-	// The JWT layer derives alg + JWK from the public key; both must work.
-	if alg, err := AlgForKey(pub); err != nil || alg != AlgES256 {
-		t.Fatalf("AlgForKey = %q, %v; want ES256", alg, err)
-	}
-	if _, err := PublicKeyJWK(pub); err != nil {
-		t.Fatalf("PublicKeyJWK: %v", err)
-	}
-
-	// Sign a representative JWS signing input and verify the converted r||s.
-	input := []byte("eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJjbGkifQ")
-	sig, alg, err := s.Sign(ctx, ref, input)
-	if err != nil {
-		t.Fatalf("Sign: %v", err)
-	}
-	if alg != AlgES256 {
-		t.Fatalf("Sign alg = %q, want ES256", alg)
-	}
-	if len(sig) != 2*p256ByteLen {
-		t.Fatalf("len(sig) = %d, want %d (fixed-width r||s)", len(sig), 2*p256ByteLen)
-	}
-	digest := sha256.Sum256(input)
-	r := new(big.Int).SetBytes(sig[:p256ByteLen])
-	ss := new(big.Int).SetBytes(sig[p256ByteLen:])
-	if !ecdsa.Verify(ecPub, digest[:], r, ss) {
-		t.Fatal("TPM signature did not verify against the public key")
-	}
-}

internal/qualitygate/cmd/semantic-review/main_test.go

@@ -9,12 +9,15 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/qualitygate/facts"
 	"github.com/larksuite/cli/internal/qualitygate/semantic"
 )
 
 func TestRunLoadsPolicyAndWaivers(t *testing.T) {
+	freezeNow(t, time.Date(2026, 6, 12, 0, 0, 0, 0, time.UTC))
+
 	repo := t.TempDir()
 	writeSemanticConfig(t, repo, `{
 	  "schema_version": 1,
@@ -65,6 +68,8 @@ func TestRunLoadsPolicyAndWaivers(t *testing.T) {
 }
 
 func TestRunLoadsWaiversFromOverrideFile(t *testing.T) {
+	freezeNow(t, time.Date(2026, 6, 12, 0, 0, 0, 0, time.UTC))
+
 	repo := t.TempDir()
 	writeSemanticConfig(t, repo, `{
 	  "schema_version": 1,
@@ -370,6 +375,13 @@ func writeSemanticConfig(t *testing.T, repo, policy, models, waivers string) {
 	}
 }
 
+func freezeNow(t *testing.T, fixed time.Time) {
+	t.Helper()
+	original := now
+	now = func() time.Time { return fixed }
+	t.Cleanup(func() { now = original })
+}
+
 func readDecision(t *testing.T, path string) semantic.Decision {
 	t.Helper()
 	data, err := os.ReadFile(path)

internal/registry/loader.go

@@ -69,6 +69,12 @@ func Init() {
 	InitWithBrand(core.BrandFeishu)
 }
 
+// ConfiguredBrand reports the brand the registry was initialized with
+// (empty before initialization). Diagnostics and startup-order tests use it.
+func ConfiguredBrand() core.LarkBrand {
+	return configuredBrand
+}
+
 // InitWithBrand initializes the registry by loading embedded data and optionally
 // overlaying cached remote data. The brand determines which remote API host to use.
 // It is safe to call multiple times (sync.Once).

internal/registry/remote.go

@@ -75,13 +75,7 @@ func remoteMetaURL(version string) string {
 	if testMetaURL != "" {
 		return testMetaURL
 	}
-	var base string
-	switch configuredBrand {
-	case core.BrandLark:
-		base = "https://open.larksuite.com/api/tools/open/api_definition"
-	default:
-		base = "https://open.feishu.cn/api/tools/open/api_definition"
-	}
+	base := core.ResolveEndpoints(configuredBrand).Open + "/api/tools/open/api_definition"
 	q := "protocol=meta&client_version=" + url.QueryEscape(build.Version)
 	if version != "" {
 		q += "&data_version=" + url.QueryEscape(version)

internal/selfupdate/updater.go

@@ -16,6 +16,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -49,7 +50,9 @@ const (
 
 var (
 	skillsIndexFetchTimeout = 10 * time.Second
-	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
+	// officialSkillsIndexURL overrides the brand-derived skills index URL in
+	// tests; empty in production.
+	officialSkillsIndexURL = ""
 )
 
 // DetectResult holds installation detection results.
@@ -101,6 +104,9 @@ func (r *NpmResult) CombinedOutput() string {
 // Override DetectOverride / NpmInstallOverride / SkillsCommandOverride / VerifyOverride
 // / RestoreAvailableOverride for testing.
 type Updater struct {
+	// Brand selects the skills index/source endpoints (zero value = feishu).
+	Brand core.LarkBrand
+
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
 	PnpmInstallOverride      func(version string) *NpmResult
@@ -129,6 +135,19 @@ type Updater struct {
 // New creates an Updater with default (real) behavior.
 func New() *Updater { return &Updater{} }
 
+// skillsIndexURL returns the brand's well-known skills index URL.
+func (u *Updater) skillsIndexURL() string {
+	if officialSkillsIndexURL != "" {
+		return officialSkillsIndexURL
+	}
+	return core.ResolveEndpoints(u.Brand).Open + "/.well-known/skills/index.json"
+}
+
+// skillsSource returns the brand's skills source host for `npx skills add`.
+func (u *Updater) skillsSource() string {
+	return core.ResolveEndpoints(u.Brand).Open
+}
+
 // DetectInstallMethod determines how the CLI was installed and whether the
 // owning package manager is available for auto-update.
 func (u *Updater) DetectInstallMethod() DetectResult {
@@ -258,7 +277,7 @@ func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 	ctx, cancel := context.WithTimeout(context.Background(), skillsIndexFetchTimeout)
 	defer cancel()
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, officialSkillsIndexURL, nil)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.skillsIndexURL(), nil)
 	if err != nil {
 		r.Err = err
 		return r
@@ -297,7 +316,7 @@ func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 }
 
 func (u *Updater) ListOfficialSkills() *NpmResult {
-	r := u.runSkillsListOfficial("https://open.feishu.cn")
+	r := u.runSkillsListOfficial(u.skillsSource())
 	if r.Err != nil {
 		r = u.runSkillsListOfficial("larksuite/cli")
 	}
@@ -313,7 +332,7 @@ func (u *Updater) ListGlobalSkillsJSON() *NpmResult {
 }
 
 func (u *Updater) InstallSkill(nameList []string) *NpmResult {
-	r := u.runSkillsInstall("https://open.feishu.cn", nameList)
+	r := u.runSkillsInstall(u.skillsSource(), nameList)
 	if r.Err != nil {
 		r = u.runSkillsInstall("larksuite/cli", nameList)
 	}
@@ -321,7 +340,7 @@ func (u *Updater) InstallSkill(nameList []string) *NpmResult {
 }
 
 func (u *Updater) InstallAllSkills() *NpmResult {
-	r := u.runSkillsAdd("https://open.feishu.cn")
+	r := u.runSkillsAdd(u.skillsSource())
 	if r.Err != nil {
 		r = u.runSkillsAdd("larksuite/cli")
 	}

internal/selfupdate/updater_test.go

@@ -17,6 +17,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -515,3 +516,23 @@ func TestDetectInstallMethod_Caches(t *testing.T) {
 		t.Errorf("expected cached pnpm result to be returned, got %+v", got)
 	}
 }
+
+func TestSkillsBrandHosts(t *testing.T) {
+	cases := []struct {
+		brand      core.LarkBrand
+		wantIndex  string
+		wantSource string
+	}{
+		{core.BrandFeishu, "https://open.feishu.cn/.well-known/skills/index.json", "https://open.feishu.cn"},
+		{core.BrandLark, "https://open.larksuite.com/.well-known/skills/index.json", "https://open.larksuite.com"},
+	}
+	for _, c := range cases {
+		u := &Updater{Brand: c.brand}
+		if got := u.skillsIndexURL(); got != c.wantIndex {
+			t.Errorf("brand %q: skillsIndexURL = %q, want %q", c.brand, got, c.wantIndex)
+		}
+		if got := u.skillsSource(); got != c.wantSource {
+			t.Errorf("brand %q: skillsSource = %q, want %q", c.brand, got, c.wantSource)
+		}
+	}
+}

lint/README.md

@@ -30,8 +30,42 @@ lint/
     ├── rule_subtype_classifier.go
     ├── rule_typed_error_completeness.go
     └── *_test.go
+└── domaincontract/     # endpoint domain contract: no hardcoded resolver hosts
+    ├── scan.go         # ScanRepo(root) ([]lintapi.Violation, error)  ← public entry
+    └── scan_test.go
 ```
 
+## Endpoint domain contract (`domaincontract`)
+
+`domaincontract` is a syntax-level regression guard for the resolver-owned
+Open, Accounts, MCP, and AppLink hosts used by the Go CLI. In production `.go`
+files it rejects:
+
+- string literals containing a resolver-owned host FQDN
+  (`{open,accounts,mcp,applink}.{feishu.cn,larksuite.com}`), and
+- direct references to the SDK base-URL globals (`FeishuBaseUrl` / `LarkBaseUrl`)
+  selected off an import of the SDK root package, which pick a host without
+  going through the resolver. Unrelated identifiers sharing the name are not
+  flagged.
+
+Host literals are permitted only inside the resolver's `ResolveEndpoints`
+function body (`internal/core/types.go`) and in this rule's own host list
+(`lint/domaincontract/scan.go`); a helper elsewhere in the resolver file
+returning a hardcoded host is still rejected. Comments and `_test.go` files
+are not scanned. Literals are unquoted before matching (escape sequences
+cannot hide a host) and match case-insensitively, and dot-imports of the SDK
+root package are rejected outright (they would hide the globals from this
+parse-level guard). The forbidden-host list is bound to the resolver source by
+`TestForbiddenHostsMatchResolver`, so adding a resolver domain without updating
+the guard fails the lint module's tests.
+
+This is not a general outbound-URL or data-flow analyzer. It does not inspect
+non-Go assets, hosts assembled from string fragments, SDK constructor option
+flow, or previously unknown Feishu/Lark hosts. The literal rule and code review
+remain the backstop for those cases.
+
+To add or change an outbound endpoint, edit the resolver — never hardcode a host.
+
 ## Running
 
 ```bash
@@ -42,7 +76,7 @@ go run -C lint . ..
 `-C lint` switches Go's working directory to `lint/`; the `..` argument
 is the repo root to scan (relative to `lint/`).
 
-CI: `.github/workflows/ci.yml` step `Run errs/ lint guards (lintcheck)`.
+CI: `.github/workflows/ci.yml` step `Run source-contract lint guards (lintcheck)`.
 
 Exit codes follow `lint/main.go`:
 

lint/domaincontract/enforce_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestLintcheckExitCode proves the guard gates CI end to end: a violating
+// fixture must make the lintcheck binary exit 1, and a clean tree exit 0.
+func TestLintcheckExitCode(t *testing.T) {
+	if testing.Short() {
+		t.Skip("compiles the lintcheck binary")
+	}
+	dirty := t.TempDir()
+	writeFile(t, dirty, "internal/x/x.go", "package x\n\nvar h = \"https://open.feishu.cn\"\n")
+
+	run := func(dir string) (string, error) {
+		cmd := exec.Command("go", "run", "..", dir)
+		cmd.Dir = "." // lint/domaincontract — `..` is the lintcheck main package
+		cmd.Env = os.Environ()
+		out, err := cmd.CombinedOutput()
+		return string(out), err
+	}
+
+	out, err := run(dirty)
+	if err == nil || !strings.Contains(out, "no-hardcoded-endpoint") {
+		t.Fatalf("violating fixture: err=%v out=%s (want exit 1 with a no-hardcoded-endpoint REJECT)", err, out)
+	}
+	var exitErr *exec.ExitError
+	if !errors.As(err, &exitErr) || exitErr.ExitCode() != 1 {
+		t.Fatalf("violating fixture exit = %v, want 1", err)
+	}
+
+	clean := t.TempDir()
+	writeFile(t, clean, "internal/x/x.go", "package x\n\nvar ok = 1\n")
+	if out, err := run(clean); err != nil {
+		t.Fatalf("clean fixture: err=%v out=%s (want exit 0)", err, out)
+	}
+}

lint/domaincontract/scan.go

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package domaincontract guards the Go CLI against direct reuse of the current
+// resolver-owned host FQDNs outside core.ResolveEndpoints.
+package domaincontract
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/lint/lintapi"
+)
+
+// forbiddenHosts are the resolver-owned FQDNs. They may only appear as string
+// literals in the allowlisted resolver source.
+var forbiddenHosts = []string{
+	"open.feishu.cn", "accounts.feishu.cn", "mcp.feishu.cn", "applink.feishu.cn",
+	"open.larksuite.com", "accounts.larksuite.com", "mcp.larksuite.com", "applink.larksuite.com",
+}
+
+// forbiddenIdents are the SDK root package's base-URL globals; referencing
+// them picks a host without the resolver. Matched as selectors on an SDK root
+// import, so unrelated same-name identifiers are not flagged.
+var forbiddenIdents = map[string]bool{
+	"FeishuBaseUrl": true,
+	"LarkBaseUrl":   true,
+}
+
+// sdkModulePrefix identifies imports of the Lark OAPI SDK.
+const sdkModulePrefix = "github.com/larksuite/oapi-sdk-go/"
+
+// sdkImportAliases returns the file's local names for the SDK root package
+// (subpackages do not export the base-URL globals).
+func sdkImportAliases(file *ast.File) map[string]bool {
+	aliases := map[string]bool{}
+	for _, imp := range file.Imports {
+		path, err := strconv.Unquote(imp.Path.Value)
+		if err != nil || !strings.HasPrefix(path, sdkModulePrefix) {
+			continue
+		}
+		if strings.Contains(strings.TrimPrefix(path, sdkModulePrefix), "/") {
+			continue // subpackage, not the root
+		}
+		name := "lark" // the SDK root package's package name
+		if imp.Name != nil {
+			name = imp.Name.Name
+		}
+		aliases[name] = true
+	}
+	return aliases
+}
+
+// allowlist holds the only file allowed to carry the literals wholesale:
+// this rule's own host list. The resolver file is scoped per-function instead
+// (see resolverPath).
+var allowlist = map[string]bool{
+	filepath.FromSlash("lint/domaincontract/scan.go"): true,
+}
+
+// resolverPath is the resolver source; host literals are permitted only
+// inside its ResolveEndpoints function body.
+var resolverPath = filepath.FromSlash("internal/core/types.go")
+
+func skipDir(name string) bool {
+	switch name {
+	case "vendor", "testdata", "node_modules", ".git", ".claude":
+		return true
+	}
+	return false
+}
+
+// ScanRepo walks production .go files under root and flags string literals
+// containing a forbidden resolver host outside the allowlist. Comments and
+// _test.go files are not scanned.
+func ScanRepo(root string) ([]lintapi.Violation, error) {
+	var out []lintapi.Violation
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			if skipDir(d.Name()) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		rel, relErr := filepath.Rel(root, path)
+		if relErr == nil && allowlist[rel] {
+			return nil
+		}
+		fset := token.NewFileSet()
+		file, perr := parser.ParseFile(fset, path, nil, 0)
+		if perr != nil {
+			return nil // unparseable file: not our concern
+		}
+		display := path
+		if relErr == nil {
+			display = rel
+		}
+		var allowedFrom, allowedTo token.Pos
+		if relErr == nil && rel == resolverPath {
+			for _, d := range file.Decls {
+				if fd, ok := d.(*ast.FuncDecl); ok && fd.Recv == nil && fd.Name.Name == "ResolveEndpoints" && fd.Body != nil {
+					allowedFrom, allowedTo = fd.Body.Pos(), fd.Body.End()
+					break
+				}
+			}
+		}
+		inResolverBody := func(p token.Pos) bool {
+			return allowedFrom != token.NoPos && p >= allowedFrom && p <= allowedTo
+		}
+		// Dot-imports of the SDK root would hide its globals from this
+		// parse-level guard, so the import form itself is rejected.
+		for _, imp := range file.Imports {
+			path, uerr := strconv.Unquote(imp.Path.Value)
+			if uerr != nil || imp.Name == nil || imp.Name.Name != "." {
+				continue
+			}
+			if strings.HasPrefix(path, sdkModulePrefix) &&
+				!strings.Contains(strings.TrimPrefix(path, sdkModulePrefix), "/") {
+				pos := fset.Position(imp.Pos())
+				out = append(out, lintapi.Violation{
+					Rule:       "no-hardcoded-endpoint",
+					Action:     lintapi.ActionReject,
+					File:       display,
+					Line:       pos.Line,
+					Message:    "dot-import of the SDK root package defeats the endpoint guard",
+					Suggestion: "import the SDK with a package name",
+				})
+			}
+		}
+		sdkAliases := sdkImportAliases(file)
+		ast.Inspect(file, func(n ast.Node) bool {
+			switch node := n.(type) {
+			case *ast.SelectorExpr:
+				pkg, ok := node.X.(*ast.Ident)
+				if ok && pkg.Obj == nil && forbiddenIdents[node.Sel.Name] && sdkAliases[pkg.Name] {
+					pos := fset.Position(node.Pos())
+					out = append(out, lintapi.Violation{
+						Rule:       "no-hardcoded-endpoint",
+						Action:     lintapi.ActionReject,
+						File:       display,
+						Line:       pos.Line,
+						Message:    "SDK base-URL global " + pkg.Name + "." + node.Sel.Name + " bypasses the resolver — use core.ResolveEndpoints",
+						Suggestion: "derive the host from core.ResolveEndpoints(brand) instead of the SDK global",
+					})
+				}
+			case *ast.BasicLit:
+				if node.Kind != token.STRING {
+					return true
+				}
+				if inResolverBody(node.Pos()) {
+					return true
+				}
+				// Unquote and lowercase so escapes or casing cannot hide a host.
+				value := node.Value
+				if v, err := strconv.Unquote(value); err == nil {
+					value = v
+				}
+				lower := strings.ToLower(value)
+				for _, host := range forbiddenHosts {
+					if strings.Contains(lower, host) {
+						pos := fset.Position(node.Pos())
+						out = append(out, lintapi.Violation{
+							Rule:       "no-hardcoded-endpoint",
+							Action:     lintapi.ActionReject,
+							File:       display,
+							Line:       pos.Line,
+							Message:    "hardcoded resolver host " + host + " — outbound domains must come from core.ResolveEndpoints",
+							Suggestion: "use core.ResolveEndpoints(brand) instead of a literal host",
+						})
+						return true
+					}
+				}
+			}
+			return true
+		})
+		return nil
+	})
+	return out, err
+}

lint/domaincontract/scan_test.go

@@ -0,0 +1,231 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/lint/lintapi"
+)
+
+// requireEnforced pins every violation to the rejecting rule: a regression
+// that downgrades the guard to an advisory action must fail here.
+func requireEnforced(t *testing.T, vs []lintapi.Violation) {
+	t.Helper()
+	for _, v := range vs {
+		if v.Rule != "no-hardcoded-endpoint" || v.Action != lintapi.ActionReject {
+			t.Fatalf("violation not CI-enforced: rule=%q action=%q (%s:%d)", v.Rule, v.Action, v.File, v.Line)
+		}
+	}
+}
+
+func writeFile(t *testing.T, root, rel, content string) {
+	t.Helper()
+	p := filepath.Join(root, rel)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestScanRepo(t *testing.T) {
+	root := t.TempDir()
+	// Negative: the resolver may hold the literals inside ResolveEndpoints.
+	writeFile(t, root, "internal/core/types.go", "package core\n\nfunc ResolveEndpoints(b string) string {\n\treturn \"https://open.feishu.cn\"\n}\n")
+	// Negative: non-resolver hosts + a comment reference must not trip the guard.
+	writeFile(t, root, "shortcuts/x/display.go", "package x\n\n// see https://open.feishu.cn/document/foo\nvar h = \"https://www.feishu.cn\"\nvar e = \"https://example.feishu.cn\"\nvar r = \"https://registry.npmjs.org/pkg\"\n")
+	// Negative: _test.go files may assert literals.
+	writeFile(t, root, "internal/y/y_test.go", "package y\n\nvar w = \"https://open.larksuite.com\"\n")
+	// Positive: production literal outside the allowlist.
+	writeFile(t, root, "internal/z/z.go", "package z\n\nvar bad = \"https://accounts.larksuite.com/oauth\"\n")
+
+	vs, err := ScanRepo(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	requireEnforced(t, vs)
+	if len(vs) != 1 {
+		t.Fatalf("got %d violations, want 1: %+v", len(vs), vs)
+	}
+	if filepath.Base(vs[0].File) != "z.go" {
+		t.Errorf("violation in %q, want z.go", vs[0].File)
+	}
+}
+
+// SDK base-URL globals are rejected only when selected off an SDK root
+// import; same-name identifiers elsewhere pass.
+func TestScanRepoSDKConstants(t *testing.T) {
+	root := t.TempDir()
+	// Positive: default and renamed imports of the SDK root package.
+	writeFile(t, root, "shortcuts/x/ws.go",
+		"package x\n\nimport \"github.com/larksuite/oapi-sdk-go/v3\"\n\nvar d = lark.FeishuBaseUrl\n")
+	writeFile(t, root, "shortcuts/x/ws2.go",
+		"package x\n\nimport sdk \"github.com/larksuite/oapi-sdk-go/v3\"\n\nvar e = sdk.LarkBaseUrl\n")
+	// Negative: test file may reference the globals.
+	writeFile(t, root, "shortcuts/x/ws_test.go",
+		"package x\n\nimport lark \"github.com/larksuite/oapi-sdk-go/v3\"\n\nvar p = lark.LarkBaseUrl\n")
+	// Negative: same-name local identifier without the SDK import.
+	writeFile(t, root, "shortcuts/y/local.go",
+		"package y\n\nvar FeishuBaseUrl = \"local\"\nvar q = FeishuBaseUrl\n")
+	// Negative: same-name symbol from an unrelated package.
+	writeFile(t, root, "shortcuts/z/other.go",
+		"package z\n\nimport other \"example.com/other\"\n\nvar r = other.FeishuBaseUrl\n")
+	// Negative: SDK subpackage import does not export the globals.
+	writeFile(t, root, "shortcuts/w/sub.go",
+		"package w\n\nimport larkws \"github.com/larksuite/oapi-sdk-go/v3/ws\"\n\nvar s = larkws.FeishuBaseUrl\n")
+	// Negative: a local value shadowing the SDK import alias is not the package.
+	writeFile(t, root, "shortcuts/v/shadow.go",
+		"package v\n\nimport lark \"github.com/larksuite/oapi-sdk-go/v3\"\n\ntype endpoint struct { FeishuBaseUrl string }\nvar _ *lark.Client\nfunc local() string { lark := endpoint{}; return lark.FeishuBaseUrl }\n")
+
+	vs, err := ScanRepo(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	requireEnforced(t, vs)
+	if len(vs) != 2 {
+		t.Fatalf("got %d violations, want 2: %+v", len(vs), vs)
+	}
+	files := map[string]bool{}
+	for _, v := range vs {
+		files[filepath.Base(v.File)] = true
+	}
+	if !files["ws.go"] || !files["ws2.go"] {
+		t.Errorf("violations in %v, want ws.go and ws2.go", files)
+	}
+}
+
+// forbiddenHosts must equal the https hosts in the resolver source, both ways;
+// a resolver domain change without a guard update fails here.
+func TestForbiddenHostsMatchResolver(t *testing.T) {
+	src := filepath.Join("..", "..", "internal", "core", "types.go")
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, src, nil, 0)
+	if err != nil {
+		t.Fatalf("parse resolver source: %v", err)
+	}
+	// Walk only the receiverless ResolveEndpoints body — the same scope the
+	// production scanner exempts — so unrelated URLs in the file cannot skew
+	// the parity check.
+	var resolverBody ast.Node
+	for _, d := range file.Decls {
+		if fd, ok := d.(*ast.FuncDecl); ok && fd.Recv == nil && fd.Name.Name == "ResolveEndpoints" && fd.Body != nil {
+			resolverBody = fd.Body
+			break
+		}
+	}
+	if resolverBody == nil {
+		t.Fatal("ResolveEndpoints function not found in resolver source")
+	}
+	resolverHosts := map[string]bool{}
+	ast.Inspect(resolverBody, func(n ast.Node) bool {
+		lit, ok := n.(*ast.BasicLit)
+		if !ok || lit.Kind != token.STRING {
+			return true
+		}
+		v, err := strconv.Unquote(lit.Value)
+		if err != nil || !strings.HasPrefix(v, "https://") {
+			return true
+		}
+		// Parse instead of prefix-stripping so a resolver URL that ever gains a
+		// path component still compares by bare host against forbiddenHosts.
+		u, err := url.Parse(v)
+		if err != nil || u.Host == "" {
+			return true
+		}
+		resolverHosts[u.Host] = true
+		return true
+	})
+
+	guardHosts := map[string]bool{}
+	for _, h := range forbiddenHosts {
+		guardHosts[h] = true
+	}
+	for h := range resolverHosts {
+		if !guardHosts[h] {
+			t.Errorf("resolver host %q is not in the guard's forbidden list", h)
+		}
+	}
+	for h := range guardHosts {
+		if !resolverHosts[h] {
+			t.Errorf("guard forbids %q which the resolver does not define", h)
+		}
+	}
+}
+
+// Dot-import rejection and case-insensitive literal matching.
+func TestScanRepoDotImportAndCase(t *testing.T) {
+	root := t.TempDir()
+	// Positive: dot-import of the SDK root package.
+	writeFile(t, root, "shortcuts/a/dot.go",
+		"package a\n\nimport . \"github.com/larksuite/oapi-sdk-go/v3\"\n\nvar d = FeishuBaseUrl\n")
+	// Positive: uppercase host literal.
+	writeFile(t, root, "shortcuts/b/upper.go",
+		"package b\n\nvar u = \"https://OPEN.FEISHU.CN/api\"\n")
+	// Negative: dot-import of an SDK subpackage is out of the globals' scope.
+	writeFile(t, root, "shortcuts/c/sub.go",
+		"package c\n\nimport . \"github.com/larksuite/oapi-sdk-go/v3/ws\"\n\nvar s = 1\n")
+
+	vs, err := ScanRepo(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	requireEnforced(t, vs)
+	if len(vs) != 2 {
+		t.Fatalf("got %d violations, want 2: %+v", len(vs), vs)
+	}
+	files := map[string]bool{}
+	for _, v := range vs {
+		files[filepath.Base(v.File)] = true
+	}
+	if !files["dot.go"] || !files["upper.go"] {
+		t.Errorf("violations in %v, want dot.go and upper.go", files)
+	}
+}
+
+// The resolver file is scoped per-function: a hardcoded host outside the
+// ResolveEndpoints body is rejected.
+func TestScanRepoResolverFunctionScope(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "internal/core/types.go",
+		"package core\n\nfunc ResolveEndpoints(b string) string {\n\treturn \"https://open.feishu.cn\"\n}\n\nfunc bypass() string { return \"https://open.feishu.cn\" }\n\ntype localResolver struct{}\nfunc (localResolver) ResolveEndpoints() string { return \"https://open.feishu.cn\" }\n")
+
+	vs, err := ScanRepo(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(vs) != 2 {
+		t.Fatalf("got %d violations, want 2 (helper and receiver method): %+v", len(vs), vs)
+	}
+	for _, v := range vs {
+		if filepath.Base(v.File) != "types.go" {
+			t.Errorf("violation in %q, want types.go", v.File)
+		}
+	}
+}
+
+// Escape sequences cannot hide a host: literals are unquoted before matching.
+func TestScanRepoEscapedLiteral(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "internal/e/e.go",
+		"package e\n\nvar h = \"https://open.feishu\\u002ecn\"\n")
+
+	vs, err := ScanRepo(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	requireEnforced(t, vs)
+	if len(vs) != 1 {
+		t.Fatalf("got %d violations, want 1: %+v", len(vs), vs)
+	}
+}

lint/main.go

@@ -1,10 +1,9 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-// Command lintcheck runs the source-level errs/ contract guards (all four checks).
-// The fifth contract rule (business path must use typed errors) lives in
-// .golangci.yml as a forbidigo entry; the four checks here are AST-level
-// guards that golangci-lint cannot express.
+// Command lintcheck runs repository source-contract guards that golangci-lint
+// cannot express directly. It currently covers typed-error contracts and the
+// resolver-owned endpoint contract.
 //
 // lintcheck lives in its own Go module under lint/ so its build-time
 // dependency on golang.org/x/tools/go/packages does not leak into the
@@ -30,6 +29,7 @@ import (
 	"fmt"
 	"os"
 
+	"github.com/larksuite/cli/lint/domaincontract"
 	"github.com/larksuite/cli/lint/errscontract"
 	"github.com/larksuite/cli/lint/lintapi"
 )
@@ -43,6 +43,9 @@ type scanner struct {
 
 var scanners = []scanner{
 	{name: "errscontract", fn: errscontract.ScanRepoWithOptions},
+	{name: "domaincontract", fn: func(root string, _ errscontract.ScanOptions) ([]lintapi.Violation, error) {
+		return domaincontract.ScanRepo(root)
+	}},
 }
 
 func main() {

release_config_test.go

@@ -1,49 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package main
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/vfs"
-	"gopkg.in/yaml.v3"
-)
-
-func TestGoReleaserPlatformMatrix(t *testing.T) {
-	data, err := vfs.ReadFile(".goreleaser.yml")
-	if err != nil {
-		t.Fatalf("read .goreleaser.yml: %v", err)
-	}
-
-	var config struct {
-		Builds []struct {
-			ID     string   `yaml:"id"`
-			GOArch []string `yaml:"goarch"`
-		} `yaml:"builds"`
-	}
-	if err := yaml.Unmarshal(data, &config); err != nil {
-		t.Fatalf("parse .goreleaser.yml: %v", err)
-	}
-
-	builds := make(map[string][]string, len(config.Builds))
-	for _, build := range config.Builds {
-		builds[build.ID] = build.GOArch
-	}
-
-	if !contains(builds["linux"], "riscv64") {
-		t.Errorf("linux release matrix must include riscv64; got %v", builds["linux"])
-	}
-	if contains(builds["darwin"], "riscv64") {
-		t.Errorf("darwin release matrix must not include unsupported riscv64; got %v", builds["darwin"])
-	}
-}
-
-func contains(values []string, target string) bool {
-	for _, value := range values {
-		if value == target {
-			return true
-		}
-	}
-	return false
-}

scripts/build-pkg-pr-new.sh

@@ -24,10 +24,6 @@ build_target() {
     ext=".exe"
   fi
 
-  # The platform key signers are compiled in by build constraint, no tags:
-  # darwin keychain (//go:build darwin) and linux/windows-amd64 TPM
-  # (//go:build linux || (windows && amd64)). windows/arm64 arch-excludes the TPM
-  # signer (go-ole has no arm64) and falls back to client_secret only.
   local output="$OUT_DIR/bin/lark-cli-${goos}-${goarch}${ext}"
   echo "Building ${goos}/${goarch} -> ${output}"
   CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -trimpath -ldflags "$LDFLAGS" -o "$output" ./main.go

shortcuts/apps/apps_create.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -61,6 +62,7 @@ func buildAppsCreateBody(rctx *common.RuntimeContext) map[string]interface{} {
 	// --app-type is constrained to the lowercase enum (html / full_stack) by the
 	// flag's Enum, so send it through verbatim. Legacy uppercase compatibility is
 	// a server concern and is intentionally not surfaced by the CLI.
+	agent := envvars.AgentName()
 	body := map[string]interface{}{
 		"name":     strings.TrimSpace(rctx.Str("name")),
 		"app_type": rctx.Str("app-type"),
@@ -71,5 +73,8 @@ func buildAppsCreateBody(rctx *common.RuntimeContext) map[string]interface{} {
 	if icon := strings.TrimSpace(rctx.Str("icon-url")); icon != "" {
 		body["icon_url"] = icon
 	}
+	if agent != "" {
+		body["source_agent"] = agent
+	}
 	return body
 }

shortcuts/apps/apps_create_test.go

@@ -273,3 +273,93 @@ func TestAppsCreate_FullstackDryRun(t *testing.T) {
 		t.Fatalf("dry-run should not contain message: %s", got)
 	}
 }
+
+func TestAppsCreate_WithAgentEnvVar(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_AGENT_NAME", "doubao")
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{"app_id": "app_d", "name": "Demo"},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	if err := runAppsShortcut(t, AppsCreate,
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if sent["source_agent"] != "doubao" {
+		t.Fatalf("body.source_agent = %v, want doubao", sent["source_agent"])
+	}
+}
+
+func TestAppsCreate_WithoutAgentEnvVar(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_AGENT_NAME", "")
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{"app_id": "app_d", "name": "Demo"},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	if err := runAppsShortcut(t, AppsCreate,
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if _, present := sent["source_agent"]; present {
+		t.Fatalf("source_agent should not be present when env var is empty: %v", sent)
+	}
+}
+
+func TestAppsCreate_AgentEnvVarNotSet(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_AGENT_NAME", "")
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{"app_id": "app_d", "name": "Demo"},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	if err := runAppsShortcut(t, AppsCreate,
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if _, present := sent["source_agent"]; present {
+		t.Fatalf("source_agent should not be present when env var is unset: %v", sent)
+	}
+}

shortcuts/apps/apps_errors.go

@@ -44,8 +44,9 @@ func appsExternalToolError(err error, format string, args ...any) *errs.Internal
 	return errs.NewInternalError(errs.SubtypeExternalTool, format, args...).WithCause(err)
 }
 
-// appsSubprocessEnvelopeError classifies a malformed or failed envelope from a
-// lark-cli subprocess (+git-credential-init / +env-pull) as internal/invalid_response.
+// appsSubprocessEnvelopeError classifies a malformed or unexpected response
+// structure as internal/invalid_response. Used for subprocess envelopes
+// (+git-credential-init / +env-pull) and server responses (e.g. pre_release).
 func appsSubprocessEnvelopeError(format string, args ...any) *errs.InternalError {
 	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...)
 }

shortcuts/apps/apps_get.go

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsGet fetches a single app's detail by app ID.
+var AppsGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+get",
+	Description: "Get a single app's detail by app ID (returns app_type, name, description, publish status, etc.)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +get --app-id <app_id>",
+		"Example: lark-cli apps +get --app-id <app_id> --dry-run",
+		"Tip: extract app type with --jq '.data.app.app_type'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "app ID", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if strings.TrimSpace(rctx.Str("app-id")) == "" {
+			return appsValidationParamError("--app-id", "--app-id is required")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID := strings.TrimSpace(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(fmt.Sprintf("%s/apps/%s", apiBasePath, validate.EncodePathSegment(appID))).
+			Desc("Get app detail (returns app_id, app_type, name, description, icon_url, created_at, updated_at, is_published)")
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID := strings.TrimSpace(rctx.Str("app-id"))
+		data, err := rctx.CallAPITyped("GET", fmt.Sprintf("%s/apps/%s", apiBasePath, validate.EncodePathSegment(appID)), nil, nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			app, _ := data["app"].(map[string]interface{})
+			if app == nil {
+				return
+			}
+			fmt.Fprintf(w, "app_id: %v\n", app["app_id"])
+			fmt.Fprintf(w, "app_type: %v\n", app["app_type"])
+			fmt.Fprintf(w, "name: %v\n", app["name"])
+			if desc, ok := app["description"].(string); ok && desc != "" {
+				fmt.Fprintf(w, "description: %s\n", desc)
+			}
+			fmt.Fprintf(w, "is_published: %v\n", app["is_published"])
+			fmt.Fprintf(w, "updated_at: %v\n", app["updated_at"])
+		})
+		return nil
+	},
+}

shortcuts/apps/apps_get_test.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAppsGet_Success(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_test",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":       "app_test",
+					"app_type":     "html",
+					"name":         "TestApp",
+					"description":  "A test application",
+					"icon_url":     "https://example.com/icon.svg",
+					"is_published": true,
+					"created_at":   "2026-05-18T10:00:00Z",
+					"updated_at":   "2026-06-01T12:00:00Z",
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsGet,
+		[]string{"+get", "--app-id", "app_test", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "app_test") {
+		t.Fatalf("stdout missing app_id: %s", got)
+	}
+	if !strings.Contains(got, "html") {
+		t.Fatalf("stdout missing app_type: %s", got)
+	}
+}
+
+func TestAppsGet_RequiresAppID(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsGet,
+		[]string{"+get", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "app-id") {
+		t.Fatalf("expected app-id required error, got %v", err)
+	}
+}
+
+func TestAppsGet_EmptyAppID(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsGet,
+		[]string{"+get", "--app-id", "", "--as", "user"}, factory, stdout)
+	requireAppsValidationProblem(t, err)
+}
+
+func TestAppsGet_DryRun(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsGet,
+		[]string{"+get", "--app-id", "app_test", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "/open-apis/spark/v1/apps/app_test") {
+		t.Fatalf("dry-run missing API path: %s", got)
+	}
+}
+
+func TestAppsGet_PrettyOutput(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_test",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":       "app_test",
+					"app_type":     "html",
+					"name":         "PrettyApp",
+					"description":  "A pretty test app",
+					"is_published": true,
+					"updated_at":   "2026-06-01T12:00:00Z",
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsGet,
+		[]string{"+get", "--app-id", "app_test", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"app_id:", "app_type:", "name:", "is_published:"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("pretty output missing %q: %s", want, got)
+		}
+	}
+}

shortcuts/apps/apps_html_publish.go

@@ -4,29 +4,32 @@
 package apps
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"io"
+	"net/http"
 	"path/filepath"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsHTMLPublish packs --path as tar.gz and uploads + publishes via one multipart POST.
+// AppsHTMLPublish packs --path as tar.gz and publishes an HTML app.
 var AppsHTMLPublish = common.Shortcut{
 	Service:     appsService,
 	Command:     "+html-publish",
-	Description: "Publish HTML to an app (single multipart POST returns the access URL)",
+	Description: "Publish HTML to an app (returns url or release_id depending on app type)",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +html-publish --app-id <app_id> --path ./dist",
 		"Example: lark-cli apps +html-publish --app-id <app_id> --path ./site --dry-run",
 	},
-	Scopes:    []string{"spark:app:write"},
+	Scopes:    []string{"spark:app:write", "spark:app:read"},
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
@@ -70,7 +73,7 @@ var AppsHTMLPublish = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		path := strings.TrimSpace(rctx.Str("path"))
 		dry := common.NewDryRunAPI()
-		dry.Desc("Upload tar.gz + publish HTML (multipart, returns url)")
+		dry.Desc("Pack tar.gz and publish HTML app (actual API path determined at runtime by app type; returns url or release_id)")
 		dry.POST(fmt.Sprintf("%s/apps/%s/upload_and_release_html_code", apiBasePath, validate.EncodePathSegment(appID))).
 			Set("content_type", "multipart/form-data")
 
@@ -119,8 +122,17 @@ var AppsHTMLPublish = common.Shortcut{
 			AppID: strings.TrimSpace(rctx.Str("app-id")),
 			Path:  strings.TrimSpace(rctx.Str("path")),
 		}
-		client := appsHTMLPublishAPI{runtime: rctx}
-		out, err := runHTMLPublish(ctx, rctx.FileIO(), client, spec)
+
+		appType := queryAppType(ctx, rctx, spec.AppID)
+
+		var out map[string]interface{}
+		var err error
+		if appType == "modern_html" {
+			out, err = runHTMLPublishTOS(ctx, rctx, spec)
+		} else {
+			client := appsHTMLPublishAPI{runtime: rctx}
+			out, err = runHTMLPublish(ctx, rctx.FileIO(), client, spec)
+		}
 		if err != nil {
 			return err
 		}
@@ -128,6 +140,9 @@ var AppsHTMLPublish = common.Shortcut{
 			if url, ok := out["url"].(string); ok && url != "" {
 				fmt.Fprintf(w, "url: %s\n", url)
 			}
+			if rid, ok := out["release_id"].(string); ok && rid != "" {
+				fmt.Fprintf(w, "release_id: %s\n", rid)
+			}
 		})
 		return nil
 	},
@@ -214,8 +229,11 @@ func ensureIndexHTML(candidates []htmlPublishCandidate) error {
 		WithHint("index.html is the app entrypoint; for a directory put index.html at the root, or pass a single file named index.html")
 }
 
-func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPublishClient, spec appsHTMLPublishSpec) (map[string]interface{}, error) {
-	candidates, err := walkHTMLPublishCandidates(fio, spec.Path)
+// prepareHTMLPublishTarball validates candidates under path and builds a
+// tar.gz payload ready for upload. Shared by runHTMLPublish and
+// runHTMLPublishTOS.
+func prepareHTMLPublishTarball(fio fileio.FileIO, path string) (*htmlPublishTarball, error) {
+	candidates, err := walkHTMLPublishCandidates(fio, path)
 	if err != nil {
 		return nil, err
 	}
@@ -238,12 +256,19 @@ func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPu
 	if err != nil {
 		return nil, err
 	}
-
 	if tarball.Size > maxHTMLPublishTarballBytes {
 		return nil, appsValidationParamError("--path",
 			"packed tar.gz size %d bytes exceeds %d bytes limit", tarball.Size, maxHTMLPublishTarballBytes).
 			WithHint("reduce --path contents, remove unrelated large files, then retry")
 	}
+	return tarball, nil
+}
+
+func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPublishClient, spec appsHTMLPublishSpec) (map[string]interface{}, error) {
+	tarball, err := prepareHTMLPublishTarball(fio, spec.Path)
+	if err != nil {
+		return nil, err
+	}
 
 	resp, err := publisher.HTMLPublish(ctx, spec.AppID, tarball)
 	if err != nil {
@@ -256,3 +281,74 @@ func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPu
 	}
 	return out, nil
 }
+
+// runHTMLPublishTOS handles the modern_html publish path: validate → tar.gz →
+// call pre_release to get TOS upload URL → upload tar.gz to TOS → return
+// tos_path for +release-create --tos-path.
+func runHTMLPublishTOS(ctx context.Context, rctx *common.RuntimeContext, spec appsHTMLPublishSpec) (map[string]interface{}, error) {
+	tarball, err := prepareHTMLPublishTarball(rctx.FileIO(), spec.Path)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 1: call pre_release to get TOS upload URL and tos_path.
+	preReleasePath := fmt.Sprintf("%s/apps/%s/pre_release", apiBasePath, validate.EncodePathSegment(spec.AppID))
+	preData, err := rctx.CallAPITyped("GET", preReleasePath, nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	kvs, _ := preData["kvs"].([]interface{})
+	if len(kvs) == 0 {
+		return nil, appsSubprocessEnvelopeError("pre_release returned no kvs")
+	}
+	kvm := make(map[string]string, len(kvs))
+	for _, item := range kvs {
+		kv, _ := item.(map[string]interface{})
+		if kv == nil {
+			continue
+		}
+		k, _ := kv["key"].(string)
+		v, _ := kv["value"].(string)
+		if k != "" {
+			kvm[k] = v
+		}
+	}
+	uploadURL := kvm["upload_url"]
+	tosPath := kvm["tos_path"]
+	if uploadURL == "" || tosPath == "" {
+		return nil, appsSubprocessEnvelopeError("pre_release kvs missing upload_url or tos_path")
+	}
+
+	// Step 2: upload tar.gz to TOS via presigned URL (bypasses Lark gateway).
+	//nolint:forbidigo // presigned TOS upload bypasses the Lark gateway — raw http is required; not a Lark API call, so RuntimeContext.DoAPI does not apply.
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, uploadURL, bytes.NewReader(tarball.Body))
+	if err != nil {
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "build TOS upload request").WithCause(err)
+	}
+	req.ContentLength = tarball.Size
+	req.Header.Set("Content-Type", "application/gzip")
+	resp, err := newFileTransferClient().Do(req) //nolint:forbidigo // presigned TOS upload, see above.
+	if err != nil {
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "TOS upload failed").WithCause(err).WithRetryable()
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		if resp.StatusCode >= 500 {
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkServer, "TOS upload failed: HTTP %d", resp.StatusCode).WithRetryable()
+		}
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "TOS upload failed: HTTP %d", resp.StatusCode)
+	}
+
+	// Step 3: call release-create with tos_path to trigger deployment.
+	releasePath := fmt.Sprintf(releaseCreatePath, validate.EncodePathSegment(spec.AppID))
+	releaseData, err := rctx.CallAPITyped("POST", releasePath, nil, map[string]interface{}{
+		"tos_path": tosPath,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return map[string]interface{}{
+		"release_id": common.GetString(releaseData, "release_id"),
+	}, nil
+}

shortcuts/apps/apps_html_publish_test.go

@@ -6,10 +6,21 @@ package apps
 import (
 	"context"
 	"errors"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
 )
 
 type fakeAppsHTMLPublishClient struct {
@@ -53,7 +64,7 @@ func TestRunHTMLPublish_HappyPath(t *testing.T) {
 }
 
 func TestRunHTMLPublish_OnlyURLInEnvelope(t *testing.T) {
-	// Pin 概要设计 §5.3 不变量 4 "同步语义不会变成异步":
+	// Pin 概要设计 §5.3 不变量 4 "同步语义不会变成异步" (legacy html path only):
 	// envelope 只含 url，未来若有人加 status / release_id 字段会被这个测试拦截。
 	site := writeAppsSampleSite(t)
 	fake := &fakeAppsHTMLPublishClient{
@@ -582,3 +593,226 @@ func TestRunHTMLPublish_IgnoresOversizeNonHTML(t *testing.T) {
 		t.Fatalf("client should be called; calls=%v", fake.calls)
 	}
 }
+
+// ── runHTMLPublishTOS tests ──
+
+// permissiveFIOProvider wraps permissiveFIO as a fileio.Provider for tests
+// that call runHTMLPublishTOS (which obtains FileIO via rctx.FileIO()).
+type permissiveFIOProvider struct{}
+
+func (permissiveFIOProvider) Name() string                                { return "test-permissive" }
+func (permissiveFIOProvider) ResolveFileIO(context.Context) fileio.FileIO { return permissiveFIO{} }
+
+// newTOSTestRuntime builds a RuntimeContext with httpmock registry and a
+// permissive FileIO provider, ready for runHTMLPublishTOS unit tests.
+func newTOSTestRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
+	t.Helper()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := &core.CliConfig{
+		AppID:      "test-app-" + strings.ToLower(t.Name()),
+		AppSecret:  "test-secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_test",
+	}
+	factory, _, _, reg := cmdutil.TestFactory(t, cfg)
+	factory.FileIOProvider = permissiveFIOProvider{}
+	rt := common.TestNewRuntimeContextForAPI(
+		context.Background(),
+		&cobra.Command{Use: "+tos-test"},
+		cfg, factory, core.AsUser,
+	)
+	return rt, reg
+}
+
+func TestRunHTMLPublishTOS_Success(t *testing.T) {
+	site := writeAppsSampleSite(t)
+	rt, reg := newTOSTestRuntime(t)
+
+	// Start httptest server to accept the TOS upload.
+	tosServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			t.Errorf("TOS upload method = %s, want PUT", r.Method)
+		}
+		if ct := r.Header.Get("Content-Type"); ct != "application/gzip" {
+			t.Errorf("TOS upload Content-Type = %s, want application/gzip", ct)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer tosServer.Close()
+
+	// Register pre_release API stub.
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_tos/pre_release",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"kvs": []interface{}{
+					map[string]interface{}{"key": "upload_url", "value": tosServer.URL},
+					map[string]interface{}{"key": "tos_path", "value": "tos://bucket/key"},
+				},
+			},
+		},
+	})
+
+	// Register release-create API stub.
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_tos/releases",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"release_id": "rel_123",
+				"status":     "publishing",
+			},
+		},
+	})
+
+	out, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  site,
+	})
+	if err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	if out["release_id"] != "rel_123" {
+		t.Fatalf("release_id=%v, want rel_123", out["release_id"])
+	}
+}
+
+func TestRunHTMLPublishTOS_MissingIndexHTML(t *testing.T) {
+	dir := t.TempDir()
+	// Create a file that is NOT named index.html.
+	if err := os.WriteFile(filepath.Join(dir, "foo.html"), []byte("<html></html>"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	rt, _ := newTOSTestRuntime(t)
+	_, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  dir,
+	})
+	if err == nil {
+		t.Fatalf("expected error for missing index.html")
+	}
+	if !strings.Contains(err.Error(), "index.html") {
+		t.Fatalf("error should mention index.html, got: %v", err)
+	}
+}
+
+func TestRunHTMLPublishTOS_PreReleaseError(t *testing.T) {
+	site := writeAppsSampleSite(t)
+	rt, reg := newTOSTestRuntime(t)
+
+	// Register pre_release API stub that returns an error code.
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_tos/pre_release",
+		Body: map[string]interface{}{
+			"code": float64(99999),
+			"msg":  "internal server error",
+		},
+	})
+
+	_, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  site,
+	})
+	if err == nil {
+		t.Fatalf("expected error from pre_release API failure")
+	}
+}
+
+func TestRunHTMLPublishTOS_MissingParams(t *testing.T) {
+	site := writeAppsSampleSite(t)
+	rt, reg := newTOSTestRuntime(t)
+
+	// Register pre_release API stub that returns empty kvs list.
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_tos/pre_release",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"kvs": []interface{}{},
+			},
+		},
+	})
+
+	_, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  site,
+	})
+	if err == nil {
+		t.Fatalf("expected error for empty kvs")
+	}
+	problem := requireAppsProblem(t, err, errs.CategoryInternal)
+	if !strings.Contains(problem.Message, "no kvs") {
+		t.Fatalf("error should mention 'no kvs', got: %q", problem.Message)
+	}
+}
+
+func TestRunHTMLPublishTOS_MissingParamsObject(t *testing.T) {
+	site := writeAppsSampleSite(t)
+	rt, reg := newTOSTestRuntime(t)
+
+	// Register pre_release API stub that returns no kvs key at all.
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_tos/pre_release",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{},
+		},
+	})
+
+	_, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  site,
+	})
+	if err == nil {
+		t.Fatalf("expected error for missing kvs")
+	}
+	problem := requireAppsProblem(t, err, errs.CategoryInternal)
+	if !strings.Contains(problem.Message, "no kvs") {
+		t.Fatalf("error should mention 'no kvs', got: %q", problem.Message)
+	}
+}
+
+func TestRunHTMLPublishTOS_UploadFails(t *testing.T) {
+	site := writeAppsSampleSite(t)
+	rt, reg := newTOSTestRuntime(t)
+
+	// Start httptest server that returns 500.
+	tosServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer tosServer.Close()
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_tos/pre_release",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"kvs": []interface{}{
+					map[string]interface{}{"key": "upload_url", "value": tosServer.URL},
+					map[string]interface{}{"key": "tos_path", "value": "tos://bucket/key"},
+				},
+			},
+		},
+	})
+
+	_, err := runHTMLPublishTOS(context.Background(), rt, appsHTMLPublishSpec{
+		AppID: "app_tos",
+		Path:  site,
+	})
+	if err == nil {
+		t.Fatalf("expected error from TOS upload failure")
+	}
+	problem := requireAppsProblem(t, err, errs.CategoryNetwork)
+	if !strings.Contains(problem.Message, "500") {
+		t.Fatalf("error should mention HTTP 500, got: %q", problem.Message)
+	}
+}

shortcuts/apps/apps_init.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+
 	"strings"
 	"unicode"
 
@@ -38,17 +39,58 @@ const (
 )
 
 const (
-	miaodaCLIPkg    = "@lark-apaas/miaoda-cli@latest"
-	defaultTemplate = "nestjs-react-fullstack"
+	miaodaCLIPkg    = "@lark-apaas/miaoda-cli@0.1.20-alpha.dd573f8"
+	npmRegistry     = "https://registry.npmmirror.com"
 	metaRelPath     = ".spark/meta.json"
 	steeringRelPath = ".agent/skills/steering"
 	seedReadme      = "README.md"
 )
 
+// Fallback committer identity written to the cloned repo's LOCAL git config when
+// no user.name/user.email is resolvable (from local, global, or system config).
+// The scaffold's `git commit` would otherwise fail with "please tell me who you
+// are"; an existing identity (e.g. the developer's global config) is respected.
+const (
+	defaultGitUserName  = "lark-cli-bot"
+	defaultGitUserEmail = "lark-cli-bot@miaoda.com"
+)
+
 // initRunner is the commandRunner used by +init. Package-level so unit tests
 // can swap in a fakeCommandRunner. Production uses execCommandRunner.
 var initRunner commandRunner = execCommandRunner{}
 
+// appTypePolicy captures the per-app-type control points +init toggles, keeping
+// each knob out of the inline `appType == "..."` checks that would otherwise be
+// scattered through the flow. Add a field here (and set it in appTypePolicies)
+// for each new control point rather than threading another type comparison
+// through appsInitExecute.
+type appTypePolicy struct {
+	// skipInstall passes --skip-install to `npx ... app init`, so scaffolding
+	// runs no dependency install.
+	skipInstall bool
+	// skipEnvPull skips the post-init `+env-pull` step, on both the fresh-init
+	// tail and the already-initialized refresh path.
+	skipEnvPull bool
+	// skipSkillsSync skips the conditional `npx ... skills sync --local` step on
+	// the non-empty (`app sync`) scaffold path.
+	skipSkillsSync bool
+}
+
+// appTypePolicies maps an app_type to its +init control strategy. Types absent
+// from the map get the zero-value policy (install runs, env is pulled, skills
+// are synced).
+var appTypePolicies = map[string]appTypePolicy{
+	// modern_html is a static HTML site: no dependencies to install, no startup
+	// env vars to pull, and no steering skills to sync.
+	"modern_html": {skipInstall: true, skipEnvPull: true, skipSkillsSync: true},
+}
+
+// policyForAppType returns the +init control strategy for appType. Unlisted
+// types (including "") get the zero-value policy.
+func policyForAppType(appType string) appTypePolicy {
+	return appTypePolicies[appType]
+}
+
 // AppsInit initializes an app's code and local development environment.
 var AppsInit = common.Shortcut{
 	Service:     appsService,
@@ -59,13 +101,15 @@ var AppsInit = common.Shortcut{
 		"Example: lark-cli apps +init --app-id <app_id> --dir <dir>",
 		"Example: lark-cli apps +init --app-id <app_id> --dir <dir> --dry-run",
 	},
-	// +init makes no direct lark API calls (it shells out to the
-	// +git-credential-init subprocess, which enforces its own scopes), so it
-	// declares no scopes of its own. Explicit []string{} (not nil) per the
-	// convention enforced by TestAllShortcutsScopesNotNil.
-	Scopes:    []string{},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
+	// +init calls queryAppType (GET /apps/{id}) which requires spark:app:read;
+	// the scope is declared as conditional since the call is non-fatal.
+	// The git credential subprocess enforces its own scopes independently.
+	// Explicit []string{} (not nil) per the convention enforced by
+	// TestAllShortcutsScopesNotNil.
+	Scopes:            []string{},
+	ConditionalScopes: []string{"spark:app:read"},
+	AuthTypes:         []string{"user"},
+	HasFormat:         true,
 	Flags: []common.Flag{
 		// NOTE: --app-id is intentionally NOT Required:true. The framework maps
 		// Required:true to cobra's MarkFlagRequired, whose error is plain-text
@@ -75,24 +119,28 @@ var AppsInit = common.Shortcut{
 		// check lives in Validate (typed validation error -> exit 2).
 		{Name: "app-id", Desc: "app ID"},
 		{Name: "dir", Desc: "clone target directory; absolute or relative path (default ./<app-id>)"},
-		{Name: "template", Desc: "code-init template for an empty repo; optional — if omitted, derived from the app's tech stack"},
+		{Name: "source-path", Desc: "path to existing source files (e.g. HTML output from an agent) to incorporate into the initialized project"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
 			return appsValidationParamError("--app-id", "--app-id is required")
 		}
+		if sp := strings.TrimSpace(rctx.Str("source-path")); sp != "" {
+			if err := charcheck.RejectControlChars(sp, "--source-path"); err != nil {
+				return appsValidationParamError("--source-path", "%v", err).WithCause(err)
+			}
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID := strings.TrimSpace(rctx.Str("app-id"))
-		template := resolveTemplate(rctx, appID)
 		dry := common.NewDryRunAPI().
 			Desc("Initialize app code (credential-init, clone, checkout, npx code-init, optional commit/push)").
 			Set("credential_init", fmt.Sprintf("apps +git-credential-init --app-id %s --format json", appID)).
 			Set("checkout", "git checkout "+defaultInitBranch).
-			Set("scaffold", fmt.Sprintf("empty repo: npx -y --prefer-online %s app init --template %s --app-id %s; non-empty: npx -y --prefer-online %s app sync + .spark/meta.json app_id patch + conditional skills sync --local", miaodaCLIPkg, template, appID, miaodaCLIPkg)).
+			Set("scaffold", fmt.Sprintf("empty repo: npx -y --prefer-online %s app init --app-type <appType> --app-id %s; non-empty: npx -y --prefer-online %s app sync + .spark/meta.json app_id patch + conditional skills sync --local", miaodaCLIPkg, appID, miaodaCLIPkg)).
 			Set("commit_push", "conditional: git add -A + commit + push origin "+defaultInitBranch+" when the working tree has changes").
-			Set("template", template).
+			Set("template", "derived from queryAppType (fallback: full_stack)").
 			Set("env_pull", fmt.Sprintf("apps +env-pull --app-id %s --project-path <clone_path> --format json (after successful init)", appID))
 		dir, err := resolveTargetPath(rctx, appID)
 		if err != nil {
@@ -122,20 +170,6 @@ func defaultCloneDir(appID string) string {
 	return filepath.Join(".", appID)
 }
 
-// resolveTemplate returns the scaffold template for an empty-repo `app init`.
-// An explicit --template wins. When omitted, it should be derived from the
-// app's tech stack.
-// TODO(apps-init): look up the app by appID via the apps API (e.g. `apps +list`
-// or a get-app endpoint), read its tech stack, and map tech-stack -> template
-// through a (future) enum. Until that lands, fall back to defaultTemplate.
-func resolveTemplate(rctx *common.RuntimeContext, appID string) string {
-	if t := strings.TrimSpace(rctx.Str("template")); t != "" {
-		return t
-	}
-	// TODO(apps-init): derive from app tech stack (apps API + enum mapping).
-	return defaultTemplate
-}
-
 // initLogf writes a one-line progress message to stderr. stdout stays reserved
 // for the structured JSON envelope, so progress never pollutes it. Callers must
 // never pass a raw repository_url (it may embed a token) — pass step names,
@@ -294,6 +328,34 @@ func ensureMetaAppID(dir, appID string) error {
 	return nil
 }
 
+// ensureGitIdentity guarantees the cloned repo has a committer identity so the
+// scaffold's `git commit` cannot fail with "please tell me who you are". It sets
+// the repo-LOCAL user.name/user.email to the lark-cli-bot defaults ONLY when
+// each is not already resolvable from local/global/system config, so a
+// developer's existing identity is never overwritten. Each key is handled
+// independently (a machine with only user.name set still gets a default email).
+func ensureGitIdentity(ctx context.Context, dir string) error {
+	if err := ensureGitConfigValue(ctx, dir, "user.name", defaultGitUserName); err != nil {
+		return err
+	}
+	return ensureGitConfigValue(ctx, dir, "user.email", defaultGitUserEmail)
+}
+
+// ensureGitConfigValue sets <key>=fallback in the repo-local git config when key
+// resolves to no value. `git config --get` exits non-zero (or prints nothing)
+// when the key is unset at every scope; any resolved value (including one
+// inherited from global/system) is left untouched.
+func ensureGitConfigValue(ctx context.Context, dir, key, fallback string) error {
+	stdout, _, err := initRunner.Run(ctx, dir, "git", "config", "--get", key)
+	if err == nil && strings.TrimSpace(stdout) != "" {
+		return nil // already configured at some scope — respect it
+	}
+	if _, stderr, e := initRunner.Run(ctx, dir, "git", "config", key, fallback); e != nil {
+		return appsExternalToolError(e, "git config %s failed: %s", key, gitErr(stderr, e))
+	}
+	return nil
+}
+
 // hasSteeringSkills reports whether <dir>/.agent/skills/steering exists as a dir.
 func hasSteeringSkills(dir string) bool {
 	info, err := os.Stat(filepath.Join(dir, steeringRelPath)) //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); path is under the validated clone dir, and FileIO.Stat rejects absolute paths.
@@ -326,34 +388,54 @@ func isEmptyRepo(ctx context.Context, dir string) (bool, error) {
 // runScaffold runs the npx scaffolding step inside the cloned repo (cwd=dir).
 // Empty repo -> `app init`; non-empty -> `app sync` + meta app_id patch +
 // conditional `skills sync`. Returns "init" or "upgrade".
-func runScaffold(ctx context.Context, dir, appID, template string) (string, error) {
+func runScaffold(ctx context.Context, dir, appID, appType, sourcePath string) (string, error) {
 	empty, err := isEmptyRepo(ctx, dir)
 	if err != nil {
 		return "", err
 	}
 	if empty {
-		// isEmptyRepo treats a repo with no tracked files — or only the backend's
-		// seed README.md — as empty. If other seed files (e.g. .gitignore) can
-		// appear, extend isEmptyRepo's allow-list accordingly.
-		if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--template", template, "--app-id", appID); err != nil {
+		args := scaffoldInitArgs(appType, appID, sourcePath)
+		if _, stderr, err := initRunner.Run(ctx, dir, "npx", args...); err != nil {
 			return "", appsExternalToolError(err, "npx app init failed: %s", gitErr(stderr, err))
 		}
 		return scaffoldKindInit, nil
 	}
-	if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "app", "sync"); err != nil {
+	if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", "--registry", npmRegistry, miaodaCLIPkg, "app", "sync"); err != nil {
 		return "", appsExternalToolError(err, "npx app sync failed: %s", gitErr(stderr, err))
 	}
 	if err := ensureMetaAppID(dir, appID); err != nil {
 		return "", err
 	}
-	if !hasSteeringSkills(dir) {
-		if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "skills", "sync", "--local"); err != nil {
+	if !policyForAppType(appType).skipSkillsSync && !hasSteeringSkills(dir) {
+		if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", "--registry", npmRegistry, miaodaCLIPkg, "skills", "sync", "--local"); err != nil {
 			return "", appsExternalToolError(err, "npx skills sync failed: %s", gitErr(stderr, err))
 		}
 	}
 	return scaffoldKindUpgrade, nil
 }
 
+// scaffoldInitArgs builds the npx argument list for `app init`.
+// appType from queryAppType is passed as --app-type; falls back to "full_stack"
+// when empty. sourcePath is appended as --source-path when non-empty.
+// --skip-install is appended per the app_type's policy (see appTypePolicy):
+// types whose policy sets skipInstall (e.g. modern_html) skip the dependency
+// install; others run it as usual.
+func scaffoldInitArgs(appType, appID, sourcePath string) []string {
+	base := []string{"-y", "--prefer-online", "--registry", npmRegistry, miaodaCLIPkg, "app", "init"}
+	at := appType
+	if at == "" {
+		at = "full_stack"
+	}
+	base = append(base, "--app-type", at, "--app-id", appID)
+	if sourcePath != "" {
+		base = append(base, "--source-path", sourcePath)
+	}
+	if policyForAppType(appType).skipInstall {
+		base = append(base, "--skip-install")
+	}
+	return base
+}
+
 // parseRepoURLFromEnvelope extracts data.repository_url from a lark-cli JSON
 // envelope ({"ok":true,"data":{"repository_url":"..."}}). The field name
 // matches the contract emitted by `apps +git-credential-init`.
@@ -445,6 +527,9 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 		return err
 	}
 
+	appType := queryAppType(ctx, rctx, appID)
+	policy := policyForAppType(appType)
+
 	// Already-initialized short-circuit: a dir containing .spark/meta.json is an
 	// initialized app repo -> skip clone/scaffold/commit, but still refresh
 	// the local env so a re-run picks up the latest startup env vars.
@@ -457,6 +542,19 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 			"committed":  false,
 			"pushed":     false,
 		}
+		if appType != "" {
+			out["app_type"] = appType
+		}
+		if policy.skipEnvPull {
+			out["env_pulled"] = false
+			out["env_pull_skipped"] = true
+			out["message"] = "Repository already initialized. You can start developing."
+			rctx.OutFormat(out, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "✓ Already initialized at %s\n", dir)
+				fmt.Fprintln(w, "仓库已初始化完成，可以开始开发了。")
+			})
+			return nil
+		}
 		initLogf(rctx, "Pulling local environment variables...")
 		envFile, envPullErr := pullEnv(ctx, rctx, appID, dir)
 		envPulled := envPullErr == ""
@@ -514,8 +612,21 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 		return appsExternalToolError(err, "git checkout %s failed: %s", defaultInitBranch, gitErr(stderr, err))
 	}
 
+	// Ensure a committer identity exists before the scaffold commit; only sets
+	// repo-local defaults when none is configured (existing identity is kept).
+	if err := ensureGitIdentity(ctx, dir); err != nil {
+		return err
+	}
+
 	initLogf(rctx, "Initializing app code (running miaoda-cli)...")
-	scaffold, err := runScaffold(ctx, dir, appID, resolveTemplate(rctx, appID))
+	sourcePath := strings.TrimSpace(rctx.Str("source-path"))
+	if sourcePath != "" {
+		sourcePath, err = filepath.Abs(sourcePath) //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); sourcePath is control-char-validated in Validate.
+		if err != nil {
+			return appsValidationParamError("--source-path", "--source-path cannot be resolved: %v", err)
+		}
+	}
+	scaffold, err := runScaffold(ctx, dir, appID, appType, sourcePath)
 	if err != nil {
 		return err
 	}
@@ -530,15 +641,6 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 		initLogf(rctx, "Working tree clean — skipped commit/push")
 	}
 
-	initLogf(rctx, "Pulling local environment variables...")
-	envFile, envPullErr := pullEnv(ctx, rctx, appID, dir)
-	envPulled := envPullErr == ""
-	if envPulled {
-		initLogf(rctx, "Local environment written to %s", envFile)
-	} else {
-		initLogf(rctx, "Could not pull local env vars: %s", envPullErr)
-	}
-
 	out := map[string]interface{}{
 		"app_id":         appID,
 		"repository_url": redactURLCredentials(repoURL),
@@ -547,21 +649,38 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 		"scaffold":       scaffold,
 		"committed":      committed,
 		"pushed":         pushed,
-		"env_pulled":     envPulled,
 		"message":        "Repository initialized. You can start developing.",
 	}
-	if envPulled {
-		out["env_file"] = envFile
-	} else {
-		out["env_pull_error"] = envPullErr
-		out["message"] = fmt.Sprintf("Repository initialized. Could not pull local env vars automatically — run `lark-cli apps +env-pull --app-id %s` to retry.", appID)
+	if appType != "" {
+		out["app_type"] = appType
 	}
+
+	if policy.skipEnvPull {
+		out["env_pulled"] = false
+		out["env_pull_skipped"] = true
+	} else {
+		initLogf(rctx, "Pulling local environment variables...")
+		envFile, envPullErr := pullEnv(ctx, rctx, appID, dir)
+		envPulled := envPullErr == ""
+		out["env_pulled"] = envPulled
+		if envPulled {
+			initLogf(rctx, "Local environment written to %s", envFile)
+			out["env_file"] = envFile
+		} else {
+			initLogf(rctx, "Could not pull local env vars: %s", envPullErr)
+			out["env_pull_error"] = envPullErr
+			out["message"] = fmt.Sprintf("Repository initialized. Could not pull local env vars automatically — run `lark-cli apps +env-pull --app-id %s` to retry.", appID)
+		}
+	}
+
 	rctx.OutFormat(out, nil, func(w io.Writer) {
 		fmt.Fprintf(w, "✓ Repository initialized at %s\n", dir)
 		fmt.Fprintf(w, "  branch: %s\n  scaffold: %s\n", defaultInitBranch, scaffold)
-		if envPulled {
-			fmt.Fprintf(w, "✓ Local environment written to %s\n", envFile)
-		} else {
+		if policy.skipEnvPull {
+			fmt.Fprintln(w, "  (env pull skipped)")
+		} else if envPulled, _ := out["env_pulled"].(bool); envPulled {
+			fmt.Fprintf(w, "✓ Local environment written to %s\n", out["env_file"])
+		} else if envPullErr, ok := out["env_pull_error"].(string); ok {
 			fmt.Fprintf(w, "⚠ Could not pull local env vars: %s\n", envPullErr)
 			fmt.Fprintf(w, "  run `lark-cli apps +env-pull --app-id %s` to retry\n", appID)
 		}

shortcuts/apps/apps_init_test.go

@@ -20,46 +20,20 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 // testRuntimeWithDir builds a *common.RuntimeContext whose backing cobra command
-// has string flags "dir" (=dirFlag) and "template" (=defaultTemplate) registered,
-// mirroring how +init reads them at runtime via rctx.Str.
+// has a string flag "dir" (=dirFlag) registered, mirroring how +init reads it
+// at runtime via rctx.Str.
 func testRuntimeWithDir(t *testing.T, dirFlag string) *common.RuntimeContext {
 	t.Helper()
 	cmd := &cobra.Command{Use: "init"}
 	cmd.Flags().String("dir", dirFlag, "")
-	cmd.Flags().String("template", defaultTemplate, "")
 	return common.TestNewRuntimeContext(cmd, nil)
 }
 
-// testRuntimeWithTemplate builds a *common.RuntimeContext with "dir" and
-// "template" string flags registered, mirroring +init's runtime flag set. The
-// template flag is registered with an empty default (matching the real flag,
-// which no longer carries Default: defaultTemplate); pass tpl="" to model an
-// omitted --template and a non-empty tpl to model an explicit one.
-func testRuntimeWithTemplate(t *testing.T, dirFlag, tpl string) *common.RuntimeContext {
-	t.Helper()
-	cmd := &cobra.Command{Use: "init"}
-	cmd.Flags().String("dir", dirFlag, "")
-	cmd.Flags().String("template", tpl, "")
-	return common.TestNewRuntimeContext(cmd, nil)
-}
-
-func TestResolveTemplate(t *testing.T) {
-	if got := resolveTemplate(testRuntimeWithTemplate(t, "", "foo"), "app_x"); got != "foo" {
-		t.Errorf("explicit --template = %q, want foo", got)
-	}
-	if got := resolveTemplate(testRuntimeWithTemplate(t, "", ""), "app_x"); got != defaultTemplate {
-		t.Errorf("omitted --template = %q, want fallback %q", got, defaultTemplate)
-	}
-	// Whitespace-only --template is treated as omitted -> fallback.
-	if got := resolveTemplate(testRuntimeWithTemplate(t, "", "   "), "app_x"); got != defaultTemplate {
-		t.Errorf("whitespace --template = %q, want fallback %q", got, defaultTemplate)
-	}
-}
-
 func TestResolveTargetPath(t *testing.T) {
 	got, err := resolveTargetPath(testRuntimeWithDir(t, ""), "app_x")
 	if err != nil {
@@ -261,12 +235,12 @@ func TestRunScaffold_EmptyRepo(t *testing.T) {
 		t.Run("ls="+ls, func(t *testing.T) {
 			f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: ls}}}
 			withFakeRunner(t, f)
-			kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "nestjs-react-fullstack")
+			kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "", "")
 			if err != nil || kind != "init" {
 				t.Fatalf("ls=%q kind=%q err=%v, want init", ls, kind, err)
 			}
 			c := findCall(f.calls, "npx", "-y")
-			if c == nil || !containsAll(c, "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--template", "nestjs-react-fullstack", "--app-id", "app_x") {
+			if c == nil || !containsAll(c, "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--app-type", "full_stack", "--app-id", "app_x") {
 				t.Errorf("app init not invoked with expected args: %v", f.calls)
 			}
 			if c != nil && containsAll(c, "--local") {
@@ -280,7 +254,7 @@ func TestRunScaffold_NonEmpty_SyncsWhenNoSteering(t *testing.T) {
 	dir := t.TempDir() // no steering dir, no meta.json
 	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: "src/x.ts\n"}}}
 	withFakeRunner(t, f)
-	kind, err := runScaffold(context.Background(), dir, "app_x", "nestjs-react-fullstack")
+	kind, err := runScaffold(context.Background(), dir, "app_x", "", "")
 	if err != nil || kind != "upgrade" {
 		t.Fatalf("kind=%q err=%v, want upgrade", kind, err)
 	}
@@ -294,12 +268,24 @@ func TestRunScaffold_NonEmpty_SyncsWhenNoSteering(t *testing.T) {
 	}
 }
 
+func TestRunScaffold_NonEmpty_ModernHTML_SkipsSyncEvenWithoutSteering(t *testing.T) {
+	dir := t.TempDir() // no steering dir → sync would run for non-modern_html
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: "src/x.ts\n"}}}
+	withFakeRunner(t, f)
+	if _, err := runScaffold(context.Background(), dir, "app_x", "modern_html", ""); err != nil {
+		t.Fatal(err)
+	}
+	if findCallArg(f.calls, "npx", "skills", "sync") != nil {
+		t.Error("skills sync must be skipped for modern_html regardless of steering dir")
+	}
+}
+
 func TestRunScaffold_NonEmpty_SkipsSyncWhenSteeringExists(t *testing.T) {
 	dir := t.TempDir()
 	os.MkdirAll(filepath.Join(dir, steeringRelPath), 0o755)
 	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: "src/x.ts\n"}}}
 	withFakeRunner(t, f)
-	if _, err := runScaffold(context.Background(), dir, "app_x", "nestjs-react-fullstack"); err != nil {
+	if _, err := runScaffold(context.Background(), dir, "app_x", "", ""); err != nil {
 		t.Fatal(err)
 	}
 	if findCallArg(f.calls, "npx", "skills", "sync") != nil {
@@ -313,7 +299,7 @@ func TestRunScaffold_AppInitFailure(t *testing.T) {
 		"npx -y":       {stderr: "boom", err: errors.New("exit 1")},
 	}}
 	withFakeRunner(t, f)
-	if _, err := runScaffold(context.Background(), t.TempDir(), "app_x", "nestjs-react-fullstack"); err == nil {
+	if _, err := runScaffold(context.Background(), t.TempDir(), "app_x", "", ""); err == nil {
 		t.Error("app init failure must propagate")
 	}
 }
@@ -342,13 +328,13 @@ func TestAppsInit_EmptyRepo_EndToEnd(t *testing.T) {
 	if _, ok := data["npx_skipped"]; ok {
 		t.Error("npx_skipped must be removed")
 	}
-	// --template is omitted here, so resolveTemplate falls back to
-	// defaultTemplate and `app init` must still receive --template nestjs-react-fullstack.
+	// appType is empty, so scaffoldInitArgs falls back to "full_stack"
+	// and `app init` must still receive --app-type full_stack.
 	c := findCall(f.calls, "npx", "-y")
 	if c == nil {
 		t.Error("npx scaffold not invoked")
-	} else if !containsAll(c, "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--template", defaultTemplate, "--app-id", "app_x") {
-		t.Errorf("app init missing expected --template fallback args: %v", c)
+	} else if !containsAll(c, "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--app-type", "full_stack", "--app-id", "app_x") {
+		t.Errorf("app init missing expected --app-type fallback args: %v", c)
 	} else if containsAll(c, "--local") {
 		t.Errorf("app init must NOT carry --local: %v", c)
 	}
@@ -751,22 +737,6 @@ func newAppsExecuteFactoryWithStderr(t *testing.T) (*cmdutil.Factory, *bytes.Buf
 }
 
 func TestAppsInit_Req1_Wording(t *testing.T) {
-	var tmpl *common.Flag
-	for i := range AppsInit.Flags {
-		if AppsInit.Flags[i].Name == "template" {
-			tmpl = &AppsInit.Flags[i]
-		}
-	}
-	if tmpl == nil {
-		t.Fatal("--template flag missing")
-	}
-	if strings.Contains(strings.ToLower(tmpl.Desc), "scaffold") {
-		t.Errorf("--template Desc still mentions scaffold: %q", tmpl.Desc)
-	}
-	if !strings.Contains(strings.ToLower(tmpl.Desc), "code-init") {
-		t.Errorf("--template Desc should use code-init wording: %q", tmpl.Desc)
-	}
-
 	// The --dry-run output is a flat object (DryRunAPI marshals to top-level keys
 	// description/scaffold/api/...), NOT wrapped in {"data":...}, so parse stdout
 	// directly rather than via parseEnvelopeData.
@@ -787,9 +757,8 @@ func TestAppsInit_Req1_Wording(t *testing.T) {
 		t.Error("dry-run must keep machine-contract key `scaffold`")
 	} else if !strings.Contains(scaffold, "skills sync --local") {
 		t.Errorf("dry-run scaffold string must show --local on skills sync: %q", scaffold)
-	} else if strings.Contains(scaffold, "app init --template nestjs-react-fullstack --app-id app_x --local") ||
-		strings.Contains(scaffold, "app sync --local") {
-		t.Errorf("dry-run scaffold string must NOT show --local on app init / app sync: %q", scaffold)
+	} else if strings.Contains(scaffold, "app sync --local") {
+		t.Errorf("dry-run scaffold string must NOT show --local on app sync: %q", scaffold)
 	}
 
 	f := &fakeCommandRunner{results: map[string]fakeCallResult{
@@ -1250,7 +1219,7 @@ func TestRunScaffold_NonEmpty_SyncFailure(t *testing.T) {
 		"git ls-files": {stdout: "src/x.ts\n"},
 		"npx -y":       {err: errors.New("sync boom")},
 	}})
-	if _, err := runScaffold(context.Background(), t.TempDir(), "app_x", "tpl"); err == nil {
+	if _, err := runScaffold(context.Background(), t.TempDir(), "app_x", "", ""); err == nil {
 		t.Error("npx app sync failure must surface as an error")
 	}
 }
@@ -1630,7 +1599,7 @@ func TestRunScaffold_SubprocessFailureIsExternalTool(t *testing.T) {
 		"git ls-files": {stderr: "fatal: not a git repository", err: cause},
 	}}
 	withFakeRunner(t, f)
-	_, err := runScaffold(context.Background(), t.TempDir(), "app_x", "nestjs-react-fullstack")
+	_, err := runScaffold(context.Background(), t.TempDir(), "app_x", "", "")
 	if err == nil {
 		t.Fatalf("expected error from failing git subprocess")
 	}
@@ -1645,3 +1614,368 @@ func TestRunScaffold_SubprocessFailureIsExternalTool(t *testing.T) {
 		t.Fatalf("cause chain not preserved: %v", err)
 	}
 }
+
+func TestRunScaffold_HtmlPassesTemplate(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: ""}}}
+	withFakeRunner(t, f)
+	kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "html", "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if kind != scaffoldKindInit {
+		t.Errorf("kind = %q, want %q", kind, scaffoldKindInit)
+	}
+	c := findCall(f.calls, "npx", "-y")
+	if c == nil {
+		t.Fatal("npx not called")
+	}
+	if !containsAll(c, "--app-type", "html") {
+		t.Errorf("expected --app-type html in args: %v", c)
+	}
+}
+
+func TestRunScaffold_ModernHtmlPassesTemplate(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: ""}}}
+	withFakeRunner(t, f)
+	kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "modern_html", "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if kind != scaffoldKindInit {
+		t.Errorf("kind = %q, want %q", kind, scaffoldKindInit)
+	}
+	c := findCall(f.calls, "npx", "-y")
+	if c == nil {
+		t.Fatal("npx not called")
+	}
+	if !containsAll(c, "--app-type", "modern_html") {
+		t.Errorf("expected --app-type modern_html in args: %v", c)
+	}
+}
+
+func TestRunScaffold_EmptyAppTypeFallback(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: ""}}}
+	withFakeRunner(t, f)
+	kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "", "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if kind != scaffoldKindInit {
+		t.Errorf("kind = %q, want %q", kind, scaffoldKindInit)
+	}
+	c := findCall(f.calls, "npx", "-y")
+	if c == nil {
+		t.Fatal("npx not called")
+	}
+	if !containsAll(c, "--app-type", "full_stack") {
+		t.Errorf("expected --app-type full_stack in args: %v", c)
+	}
+}
+
+func TestRunScaffold_FullStackPassesTemplate(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"git ls-files": {stdout: ""}}}
+	withFakeRunner(t, f)
+	kind, err := runScaffold(context.Background(), t.TempDir(), "app_x", "full_stack", "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if kind != scaffoldKindInit {
+		t.Errorf("kind = %q, want %q", kind, scaffoldKindInit)
+	}
+	c := findCall(f.calls, "npx", "-y")
+	if c == nil {
+		t.Fatal("npx not called")
+	}
+	if !containsAll(c, "--app-type", "full_stack") {
+		t.Errorf("expected --app-type full_stack in args: %v", c)
+	}
+}
+
+func TestScaffoldInitArgs_WithAppType(t *testing.T) {
+	args := scaffoldInitArgs("modern_html", "app_x", "")
+	if !containsAll(args, "--app-type", "modern_html", "--app-id", "app_x") {
+		t.Errorf("expected --app-type modern_html --app-id app_x, got %v", args)
+	}
+	// modern_html skips dependency install.
+	if !containsAll(args, "--skip-install") {
+		t.Errorf("expected --skip-install for modern_html, got %v", args)
+	}
+	for _, a := range args {
+		if a == "--source-path" {
+			t.Errorf("--source-path must not appear when sourcePath is empty: %v", args)
+		}
+	}
+}
+
+func TestPolicyForAppType(t *testing.T) {
+	// modern_html decouples all control points: skip install, env-pull, skills sync.
+	if p := policyForAppType("modern_html"); !p.skipInstall || !p.skipEnvPull || !p.skipSkillsSync {
+		t.Errorf("modern_html policy = %+v, want all skip flags set", p)
+	}
+	// Unlisted types (including "") get the zero-value policy: everything runs.
+	for _, at := range []string{"full_stack", "", "backend"} {
+		if p := policyForAppType(at); p.skipInstall || p.skipEnvPull || p.skipSkillsSync {
+			t.Errorf("policy for %q = %+v, want zero value", at, p)
+		}
+	}
+}
+
+func TestScaffoldInitArgs_SkipInstallOnlyForModernHTML(t *testing.T) {
+	// Non-modern_html types run the install step (no --skip-install).
+	for _, at := range []string{"full_stack", "", "backend"} {
+		args := scaffoldInitArgs(at, "app_x", "")
+		for _, a := range args {
+			if a == "--skip-install" {
+				t.Errorf("--skip-install must not appear for app-type %q: %v", at, args)
+			}
+		}
+	}
+}
+
+func TestScaffoldInitArgs_EmptyFallback(t *testing.T) {
+	args := scaffoldInitArgs("", "app_x", "")
+	if !containsAll(args, "--app-type", "full_stack", "--app-id", "app_x") {
+		t.Errorf("expected --app-type full_stack fallback, got %v", args)
+	}
+}
+
+func TestScaffoldInitArgs_WithSourcePath(t *testing.T) {
+	args := scaffoldInitArgs("modern_html", "app_x", "/path/to/src")
+	if !containsAll(args, "--app-type", "modern_html", "--app-id", "app_x", "--source-path", "/path/to/src") {
+		t.Errorf("expected --source-path /path/to/src, got %v", args)
+	}
+}
+
+// configSetValue finds a `git config <key> <value>` SET call (not a `--get`)
+// in the recorded fake calls and returns its value.
+func configSetValue(calls [][]string, key string) (string, bool) {
+	for _, c := range calls {
+		if len(c) >= 5 && c[1] == "git" && c[2] == "config" && c[3] == key {
+			return c[4], true
+		}
+	}
+	return "", false
+}
+
+func TestEnsureGitIdentity_SetsDefaultsWhenUnset(t *testing.T) {
+	f := &fakeCommandRunner{} // no "git config" result → `--get` returns empty stdout
+	withFakeRunner(t, f)
+	if err := ensureGitIdentity(context.Background(), "/repo"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if v, ok := configSetValue(f.calls, "user.name"); !ok || v != defaultGitUserName {
+		t.Errorf("user.name set = (%q,%v), want %q", v, ok, defaultGitUserName)
+	}
+	if v, ok := configSetValue(f.calls, "user.email"); !ok || v != defaultGitUserEmail {
+		t.Errorf("user.email set = (%q,%v), want %q", v, ok, defaultGitUserEmail)
+	}
+}
+
+func TestEnsureGitIdentity_RespectsExisting(t *testing.T) {
+	// `git config --get` returns a value → identity resolvable, nothing is set.
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{
+		"git config": {stdout: "Existing Dev\n"},
+	}}
+	withFakeRunner(t, f)
+	if err := ensureGitIdentity(context.Background(), "/repo"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := configSetValue(f.calls, "user.name"); ok {
+		t.Error("user.name must not be overwritten when already configured")
+	}
+	if _, ok := configSetValue(f.calls, "user.email"); ok {
+		t.Error("user.email must not be overwritten when already configured")
+	}
+}
+
+func TestEnsureGitIdentity_SetFailurePropagates(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{
+		"git config": {stderr: "boom", err: errors.New("exit 1")},
+	}}
+	withFakeRunner(t, f)
+	if err := ensureGitIdentity(context.Background(), "/repo"); err == nil {
+		t.Error("expected error when git config set fails")
+	}
+}
+
+func TestAppsInit_WithAppType_FreshClone(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{
+		"credential-init": credInitOK("http://u:t@h/app_typed.git"),
+		"git clone":       {},
+		"git checkout":    {},
+		"git ls-files":    {stdout: ""},
+		"git status":      {stdout: " A src/app.ts\n"},
+	}}
+	withFakeRunner(t, f)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+
+	// Register a meta mock so queryAppType returns "modern_html"
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_typed",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_typed",
+					"app_type": "MODERN_HTML",
+				},
+			},
+		},
+	})
+
+	dir := relCloneDir(t)
+	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_typed", "--dir", dir, "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := parseEnvelopeData(t, stdout)
+	if data["app_type"] != "modern_html" {
+		t.Errorf("app_type = %v, want modern_html", data["app_type"])
+	}
+	// Verify the scaffold used --app-type modern_html
+	c := findCall(f.calls, "npx", "-y")
+	if c == nil {
+		t.Fatal("npx not called")
+	}
+	if !containsAll(c, "--app-type", "modern_html") {
+		t.Errorf("expected --app-type modern_html, got %v", c)
+	}
+}
+
+func TestAppsInit_ModernHtml_SkipsEnvPull(t *testing.T) {
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{
+		"credential-init": credInitOK("https://git.test/app_mh.git"),
+		"git clone":       {},
+		"git checkout":    {},
+		"git ls-files":    {stdout: ""},
+		"npx -y":          {},
+		"git status":      {stdout: ""},
+	}}
+	withFakeRunner(t, f)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_mh",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_mh",
+					"app_type": "MODERN_HTML",
+				},
+			},
+		},
+	})
+
+	dir := relCloneDir(t)
+	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_mh", "--dir", dir, "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := parseEnvelopeData(t, stdout)
+	if data["env_pull_skipped"] != true {
+		t.Errorf("env_pull_skipped = %v, want true", data["env_pull_skipped"])
+	}
+	if data["env_pulled"] != false {
+		t.Errorf("env_pulled = %v, want false", data["env_pulled"])
+	}
+	// Verify env-pull was NOT called
+	for _, c := range f.calls {
+		if len(c) >= 3 && c[2] == "apps" && len(c) >= 4 && c[3] == "+env-pull" {
+			t.Fatal("env-pull should not be called for modern_html")
+		}
+	}
+}
+
+func TestAppsInit_AlreadyInitialized_ModernHtml_SkipsEnvPull(t *testing.T) {
+	dir := relCloneDir(t)
+	abs, err := filepath.Abs(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(abs, ".spark"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(abs, metaRelPath), []byte(`{"app_id":"app_mh2"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	f := &fakeCommandRunner{}
+	withFakeRunner(t, f)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_mh2",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_mh2",
+					"app_type": "MODERN_HTML",
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_mh2", "--dir", dir, "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := parseEnvelopeData(t, stdout)
+	if data["scaffold"] != "already_initialized" {
+		t.Errorf("scaffold = %v, want already_initialized", data["scaffold"])
+	}
+	if data["env_pull_skipped"] != true {
+		t.Errorf("env_pull_skipped = %v, want true", data["env_pull_skipped"])
+	}
+	if len(f.calls) != 0 {
+		t.Errorf("no commands should be called for already-initialized modern_html, got %v", f.calls)
+	}
+}
+
+func TestAppsInit_WithAppType_AlreadyInitialized(t *testing.T) {
+	dir := relCloneDir(t)
+	abs, err := filepath.Abs(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(abs, ".spark"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(abs, metaRelPath), []byte(`{"app_id":"app_typed2"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	envFile := filepath.Join(abs, ".env.local")
+	f := &fakeCommandRunner{results: map[string]fakeCallResult{"env-pull": envPullOK(envFile)}}
+	withFakeRunner(t, f)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+
+	// Register meta mock so queryAppType returns "html"
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_typed2",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_typed2",
+					"app_type": "HTML",
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_typed2", "--dir", dir, "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := parseEnvelopeData(t, stdout)
+	if data["scaffold"] != "already_initialized" {
+		t.Errorf("scaffold = %v, want already_initialized", data["scaffold"])
+	}
+	if data["app_type"] != "html" {
+		t.Errorf("app_type = %v, want html", data["app_type"])
+	}
+}

shortcuts/apps/apps_meta.go

@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// queryAppType fetches the app's type string from the server via
+// GET /open-apis/spark/v1/apps/{appID}. The server returns uppercase
+// values ("HTML", "FULL_STACK", "MODERN_HTML"); this function normalizes
+// to lowercase. Returns "" when the API is unavailable or returns an
+// error — callers fall back to legacy behavior.
+func queryAppType(ctx context.Context, rctx *common.RuntimeContext, appID string) string {
+	path := fmt.Sprintf("%s/apps/%s", apiBasePath, validate.EncodePathSegment(appID))
+	data, err := rctx.CallAPITyped("GET", path, nil, nil)
+	if err != nil {
+		fmt.Fprintf(rctx.IO().ErrOut, "→ Could not query app type: %v\n", err)
+		return ""
+	}
+	appRaw, _ := data["app"].(map[string]interface{})
+	if appRaw == nil {
+		fmt.Fprintf(rctx.IO().ErrOut, "→ Could not query app type: response missing app object\n")
+		return ""
+	}
+	appType, _ := appRaw["app_type"].(string)
+	return strings.ToLower(appType)
+}

shortcuts/apps/apps_meta_test.go

@@ -0,0 +1,148 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newMetaTestRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
+	t.Helper()
+	cfg := &core.CliConfig{Brand: core.BrandFeishu, AppID: "cli_meta_test"}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	rt := common.TestNewRuntimeContextForAPI(
+		context.Background(),
+		&cobra.Command{Use: "+meta-test"},
+		cfg, f, core.AsUser,
+	)
+	return rt, reg
+}
+
+func TestQueryAppType_Success(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_test",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_test",
+					"app_type": "MODERN_HTML",
+				},
+			},
+		},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_test")
+	if result != "modern_html" {
+		t.Errorf("queryAppType = %q, want modern_html", result)
+	}
+}
+
+func TestQueryAppType_FullStack(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_fs",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_fs",
+					"app_type": "FULL_STACK",
+				},
+			},
+		},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_fs")
+	if result != "full_stack" {
+		t.Errorf("queryAppType = %q, want full_stack", result)
+	}
+}
+
+func TestQueryAppType_Html(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_html",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_html",
+					"app_type": "HTML",
+				},
+			},
+		},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_html")
+	if result != "html" {
+		t.Errorf("queryAppType = %q, want html", result)
+	}
+}
+
+func TestQueryAppType_APIError(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_bad",
+		Status: 500,
+		Body:   map[string]interface{}{"code": float64(99999), "msg": "internal error"},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_bad")
+	if result != "" {
+		t.Errorf("queryAppType = %q, want empty on error", result)
+	}
+}
+
+func TestQueryAppType_MissingAppObject(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_no",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{},
+		},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_no")
+	if result != "" {
+		t.Errorf("queryAppType = %q, want empty when app object missing", result)
+	}
+}
+
+func TestQueryAppType_EmptyAppType(t *testing.T) {
+	rt, reg := newMetaTestRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_empty",
+		Body: map[string]interface{}{
+			"code": float64(0),
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{
+					"app_id":   "app_empty",
+					"app_type": "",
+				},
+			},
+		},
+	})
+
+	result := queryAppType(context.Background(), rt, "app_empty")
+	if result != "" {
+		t.Errorf("queryAppType = %q, want empty when app_type is empty", result)
+	}
+}

shortcuts/apps/apps_release_create.go

@@ -56,9 +56,10 @@ var AppsReleaseCreate = common.Shortcut{
 		out := map[string]interface{}{
 			"release_id": common.GetString(data, "release_id"),
 			"status":     common.GetString(data, "status"),
+			"sync":       common.GetBool(data, "sync"),
 		}
 		rctx.OutFormat(out, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "release_id: %s\nstatus: %s\n", out["release_id"], out["status"])
+			fmt.Fprintf(w, "release_id: %s\nstatus: %s\nsync: %v\n", out["release_id"], out["status"], out["sync"])
 		})
 		return nil
 	},

shortcuts/apps/apps_release_create_test.go

@@ -105,3 +105,45 @@ func TestAppsReleaseCreateExecute_Success(t *testing.T) {
 		t.Errorf("status = %v, want publishing", env.Data["status"])
 	}
 }
+
+func TestAppsReleaseCreate_SyncField(t *testing.T) {
+	rctx, stdoutBuf, reg := newReleaseCreateRuntimeContext(t, "app_sync", "main")
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_sync/releases",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "",
+			"data": map[string]interface{}{
+				"release_id": "456",
+				"status":     "publishing",
+				"sync":       true,
+			},
+		},
+	})
+
+	err := AppsReleaseCreate.Execute(context.Background(), rctx)
+	if err != nil {
+		t.Fatalf("Execute() = %v", err)
+	}
+
+	var env struct {
+		OK   bool                   `json:"ok"`
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(stdoutBuf.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal output: %v\nraw: %s", err, stdoutBuf.String())
+	}
+	if !env.OK {
+		t.Fatalf("expected ok=true, got: %s", stdoutBuf.String())
+	}
+	if env.Data["release_id"] != "456" {
+		t.Errorf("release_id = %v, want 456", env.Data["release_id"])
+	}
+	if env.Data["status"] != "publishing" {
+		t.Errorf("status = %v, want publishing", env.Data["status"])
+	}
+	if env.Data["sync"] != true {
+		t.Errorf("sync = %v, want true", env.Data["sync"])
+	}
+}

shortcuts/apps/shortcuts.go

@@ -12,6 +12,7 @@ func Shortcuts() []common.Shortcut {
 
 	return []common.Shortcut{
 		AppsCreate,
+		AppsGet,
 		AppsUpdate,
 		AppsList,
 		AppsAccessScopeSet,

shortcuts/apps/shortcuts_test.go

@@ -21,10 +21,10 @@ import (
 //   - 5 session（create/list/get/stop/chat）+ 1 session-messages-list
 //   - 8 openapi-key（list/get/create/update/enable/disable/delete/reset）
 //   - 3 plugin（install/uninstall/list）= 63。
-func TestAppsShortcuts_Returns63(t *testing.T) {
+func TestAppsShortcuts_Returns64(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 63 {
-		t.Fatalf("Shortcuts() returned %d entries, want 63", len(got))
+	if len(got) != 64 {
+		t.Fatalf("Shortcuts() returned %d entries, want 64", len(got))
 	}
 }
 

shortcuts/common/runner.go

@@ -431,6 +431,11 @@ func (ctx *RuntimeContext) buildRequest(method, url string, params map[string]in
 	if optFn := cmdutil.ShortcutHeaderOpts(ctx.ctx); optFn != nil {
 		req.ExtraOpts = append(req.ExtraOpts, optFn)
 	}
+	// TODO: remove PPE headers once testing is complete and promoted to production.
+	ppeHeaders := http.Header{}
+	ppeHeaders.Set("x-use-ppe", "1")
+	ppeHeaders.Set("x-tt-env", "ppe_miaoda_lark_cli")
+	req.ExtraOpts = append(req.ExtraOpts, larkcore.WithHeaders(ppeHeaders))
 	return req
 }
 

shortcuts/event/subscribe.go

@@ -21,7 +21,6 @@ import (
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 
-	lark "github.com/larksuite/oapi-sdk-go/v3"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 	larkevent "github.com/larksuite/oapi-sdk-go/v3/event"
 	"github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
@@ -247,10 +246,7 @@ var EventSubscribe = common.Shortcut{
 		}
 
 		// --- WebSocket ---
-		domain := lark.FeishuBaseUrl
-		if runtime.Config.Brand == core.BrandLark {
-			domain = lark.LarkBaseUrl
-		}
+		domain := core.ResolveEndpoints(runtime.Config.Brand).Open
 
 		info(fmt.Sprintf("%sConnecting to Lark event WebSocket...%s", output.Cyan, output.Reset))
 		if eventTypeFilter != nil {

shortcuts/event/subscribe_test.go

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+	lark "github.com/larksuite/oapi-sdk-go/v3"
+)
+
+// The resolver's Open host must equal the SDK's per-brand WS base URL;
+// fails if the SDK constants ever drift from the resolver.
+func TestWSDomainMatchesResolver(t *testing.T) {
+	if got, want := core.ResolveEndpoints(core.BrandFeishu).Open, lark.FeishuBaseUrl; got != want {
+		t.Errorf("feishu WS domain = %q, want SDK %q", got, want)
+	}
+	if got, want := core.ResolveEndpoints(core.BrandLark).Open, lark.LarkBaseUrl; got != want {
+		t.Errorf("lark WS domain = %q, want SDK %q", got, want)
+	}
+}

sidecar/server-multi-tenant-demo/auth_bridge.go

@@ -204,7 +204,7 @@ func (ab *authBridge) handleLogin(w http.ResponseWriter, _ *http.Request, body [
 		len(strings.Fields(scope)), req.Domains, clientID)
 
 	authResp, err := larkauth.RequestDeviceAuthorization(
-		context.Background(), ab.httpCl, larkauth.ClientAuth{AppID: ab.appID, AppSecret: ab.appSecret}, ab.brand, scope, io.Discard,
+		ab.httpCl, ab.appID, ab.appSecret, ab.brand, scope, io.Discard,
 	)
 	if err != nil {
 		jsonError(w, http.StatusBadGateway, "device authorization failed: "+err.Error())
@@ -255,7 +255,7 @@ func (ab *authBridge) handlePoll(w http.ResponseWriter, r *http.Request, body []
 	}()
 
 	result := larkauth.PollDeviceToken(
-		ctx, ab.httpCl, larkauth.ClientAuth{AppID: ab.appID, AppSecret: ab.appSecret}, ab.brand,
+		ctx, ab.httpCl, ab.appID, ab.appSecret, ab.brand,
 		req.DeviceCode, 5, 600, io.Discard,
 	)
 

skills/lark-apps/SKILL.md

@@ -30,6 +30,7 @@ lark-cli auth login --domain apps
 |---|---|---|
 | 创建**新**应用资产、拿 app_id | `+create` | [`lark-apps-create.md`](references/lark-apps-create.md) |
 | 找已有 app_id、按名字过滤应用 | `+list --keyword <name>` | [`lark-apps-list.md`](references/lark-apps-list.md) |
+| 查单个应用详情（类型、名称、发布状态等） | `+get --app-id <app_id>` | [`lark-apps-get.md`](references/lark-apps-get.md) |
 | 改应用名或描述 | `+update` | [`lark-apps-update.md`](references/lark-apps-update.md) |
 | 发布本地 `index.html` 或静态目录为可访问 URL | `+html-publish` | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
 | 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)，含端到端流程和领域规则 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |

skills/lark-apps/references/lark-apps-get.md

@@ -0,0 +1,43 @@
+# apps +get
+
+按 app_id 查询单个应用详情。运行时命令事实以 `lark-cli apps +get --help` 为准。
+
+## 何时用
+
+需要查看一个应用的类型、名称、描述、发布状态等详情时使用。如果只是按应用名模糊搜索定位 app_id，用 `+list --keyword`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 返回应用的完整信息：`app_id`、`app_type`、`name`、`description`、`icon_url`、`created_at`、`updated_at`、`is_published`。
+
+## 示例
+
+```bash
+lark-cli apps +get --app-id app_xxx
+lark-cli apps +get --app-id app_xxx --dry-run
+lark-cli apps +get --app-id app_xxx -q '.data.app.app_type'
+```
+
+## 输出契约
+
+- 成功读取 `data.app` 对象，包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `app_id` | string | 应用唯一标识 |
+| `app_type` | string | 应用类型（如 HTML、FULL_STACK、MODERN_HTML） |
+| `name` | string | 应用显示名称 |
+| `description` | string | 应用功能说明 |
+| `icon_url` | string | 应用图标 URL |
+| `created_at` | string | 创建时间（ISO 8601 UTC） |
+| `updated_at` | string | 最后更新时间（ISO 8601 UTC） |
+| `is_published` | boolean | 是否已发布 |
+
+- pretty 输出展示核心字段：`app_id`、`app_type`、`name`、`is_published`、`updated_at`。
+- `is_published=true` 只代表应用历史上有发布版本，不代表最新代码已部署。
+
+## Agent 规则
+
+- 用户已有 `app_id` 想查看详情时用 `+get`；只有应用名时用 `+list --keyword`。
+- 不要把 `cli_` 开头的飞书应用 ID 传给 `+get`，只接受 `app_` 开头的应用 ID。

skills/lark-apps/references/lark-apps-html-publish.md

@@ -23,8 +23,13 @@ lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
 
 ## 输出契约
 
-- 成功默认 JSON envelope 只关心 `data.url`；这是本轮 HTML 发布后的发布态访问链接。
-- pretty 输出为 `url: <url>`，适合人看；自动化取字段用 JSON 或 `--jq '.data.url'`。
+根据应用类型，输出字段不同：
+
+- **静态 HTML 应用**：`data.url` 是本轮发布后的访问链接，一步完成发布。
+- **其他 HTML 应用**：`data.release_id` 是发布标识，命令内部已完成产物上传和发布创建。用 `+release-get --app-id <app_id> --release-id <release_id>` 轮询发布状态直到 `finished`。
+
+判断走哪条路径：有 `url` 字段说明已直接发布完成；有 `release_id` 字段说明需要用 `+release-get` 轮询。
+
 - 业务失败如构建失败、应用不存在通常带 `error.hint`；优先转述 hint。网络/服务端失败则建议稍后重试。
 
 ## 链接边界

skills/lark-apps/references/lark-apps-init.md

@@ -10,7 +10,6 @@
 
 - 必填：`--app-id`。
 - 可选：`--dir`，clone 目标目录；省略时默认 `./<app-id>`。
-- 可选：`--template`，空仓库脚手架模板；省略时当前回退 `nestjs-react-fullstack`。
 - 固定 checkout 分支：`sprint/default`。
 - `+init` 会初始化 Git 凭证、clone 仓库、切到工作分支并生成/同步本地项目。
 
@@ -18,7 +17,7 @@
 
 ```bash
 lark-cli apps +init --app-id app_xxx --dir ./my-app
-lark-cli apps +init --app-id app_xxx --dir /absolute/path/my-app --template nestjs-react-fullstack
+lark-cli apps +init --app-id app_xxx --dir /absolute/path/my-app
 lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
 ```
 

skills/lark-apps/references/lark-apps-release-create.md

@@ -21,8 +21,10 @@ lark-cli apps +release-create --app-id app_xxx --branch sprint/default --dry-run
 
 ## 输出契约
 
-- 成功读取 `data.release_id` 和 `data.status`；`release_id` 是后续 `+release-get` 的入参。
+- 成功读取 `data.release_id`、`data.status` 和 `data.sync`；`release_id` 是后续 `+release-get` 的入参。
+- `sync=true` 表示同步部署（服务端等待部署完成后才返回），`sync=false` 或缺失表示异步部署。
 - `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
+- `status=finished` 表示部署已完成（同步部署时可能直接返回此状态）。
 - `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。
 
 ## Agent 规则