mirror of
https://github.com/larksuite/cli.git
synced 2026-07-06 00:06:28 +08:00
99e314fe0b
Every failure on the authentication, authorization, and configuration
path now surfaces as a typed structured error instead of an ad-hoc
envelope. Users and scripts that consume CLI output get:
- a fixed nine-category taxonomy on the wire, each mapped to a
stable shell exit code (authentication/authorization/config = 3,
network = 4, internal = 5, policy = 6, confirmation = 10)
- identity-aware detail fields (missing_scopes, requested_scopes,
granted_scopes, console_url, log_id, retryable, hint) carried
uniformly on the envelope
- a single canonical policy envelope at exit 6; the legacy
auth_error carve-out is retired
- per-subtype canonical message + hint that preserves Lark's
diagnostic phrasing and routes recovery to the right actor:
app developer (app_scope_not_applied), user (missing_scope,
token_scope_insufficient, user_unauthorized), or tenant admin
(app_unavailable, app_disabled)
- wrong app credentials classify as config/invalid_client whether
surfaced by the Open API endpoint (99991543) or the tenant
access-token mint endpoint (10003 / 10014), instead of
collapsing to a transport error or api/unknown
- local shortcut scope preflight emits the same
authorization/missing_scope envelope (identity + deterministic
missing-scope set) used by the post-call permission path, so AI
consumers read the same structured shape from precheck and from
server-returned permission denial
- streaming download/upload failures keep the same network subtype
split (timeout / TLS / DNS / transport) as the non-stream path
instead of collapsing every cause to a generic transport failure
- console_url is carried only on the bot-perspective
app_scope_not_applied envelope (where the recovery action is
"developer applies the scope at the developer console"); the
user-perspective missing_scope envelope drops the field, since
the only actionable user recovery is `lark-cli auth login --scope`
and pointing an end user at a console they cannot modify is
misleading
- bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic
Type tags to wire 'config' with the original module name kept
as a metric label
All 10 typed errors are cause-bearing, nil-safe on .Error() and
.Unwrap(), and defensively clone slice setter inputs. Four lint
rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry
/ CheckBuildAPIErrorArms) lock these invariants on migrated paths.
112 lines
2.7 KiB
Go
112 lines
2.7 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package registry
|
|
|
|
// GetStrFromMap extracts a string value from map[string]interface{}.
|
|
func GetStrFromMap(m map[string]interface{}, key string) string {
|
|
if m == nil {
|
|
return ""
|
|
}
|
|
if v, ok := m[key]; ok {
|
|
if s, ok := v.(string); ok {
|
|
return s
|
|
}
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// GetStrSliceFromMap extracts a []string value from map[string]interface{}.
|
|
// Returns nil if the key is missing or the value is not a string slice.
|
|
func GetStrSliceFromMap(m map[string]interface{}, key string) []string {
|
|
if m == nil {
|
|
return nil
|
|
}
|
|
raw, ok := m[key].([]interface{})
|
|
if !ok {
|
|
return nil
|
|
}
|
|
result := make([]string, 0, len(raw))
|
|
for _, v := range raw {
|
|
if s, ok := v.(string); ok {
|
|
result = append(result, s)
|
|
}
|
|
}
|
|
if len(result) == 0 {
|
|
return nil
|
|
}
|
|
return result
|
|
}
|
|
|
|
// DeclaredScopesForMethod returns the scopes declared by a method's
|
|
// from_meta entry for the given identity. Prefers the explicit
|
|
// `requiredScopes` field when present; otherwise returns the single
|
|
// recommended scope from `scopes` (or the first scope as a final fallback).
|
|
// Returns nil when the method has no scope information.
|
|
func DeclaredScopesForMethod(method map[string]interface{}, identity string) []string {
|
|
if method == nil {
|
|
return nil
|
|
}
|
|
if requiredRaw, ok := method["requiredScopes"].([]interface{}); ok && len(requiredRaw) > 0 {
|
|
out := make([]string, 0, len(requiredRaw))
|
|
for _, v := range requiredRaw {
|
|
if s, ok := v.(string); ok && s != "" {
|
|
out = append(out, s)
|
|
}
|
|
}
|
|
if len(out) > 0 {
|
|
return out
|
|
}
|
|
}
|
|
rawScopes, _ := method["scopes"].([]interface{})
|
|
if len(rawScopes) == 0 {
|
|
return nil
|
|
}
|
|
recommended := SelectRecommendedScope(rawScopes, identity)
|
|
if recommended == "" {
|
|
for _, raw := range rawScopes {
|
|
if s, ok := raw.(string); ok && s != "" {
|
|
recommended = s
|
|
break
|
|
}
|
|
}
|
|
}
|
|
if recommended == "" {
|
|
return nil
|
|
}
|
|
return []string{recommended}
|
|
}
|
|
|
|
// SelectRecommendedScope selects the known scope with the highest priority score
|
|
// (higher = more recommended / least privilege).
|
|
// Scopes not in the priority table are skipped to avoid recommending invalid/unknown scopes.
|
|
func SelectRecommendedScope(scopes []interface{}, identity string) string {
|
|
priorities := LoadScopePriorities()
|
|
bestScore := -1
|
|
bestScope := ""
|
|
for _, s := range scopes {
|
|
str, ok := s.(string)
|
|
if !ok {
|
|
continue
|
|
}
|
|
score, exists := priorities[str]
|
|
if !exists {
|
|
continue // skip unknown scopes
|
|
}
|
|
if score > bestScore {
|
|
bestScore = score
|
|
bestScope = str
|
|
}
|
|
}
|
|
if bestScope != "" {
|
|
return bestScope
|
|
}
|
|
// Fallback: if no scope is in the priority table, return the first one.
|
|
if len(scopes) > 0 {
|
|
if s, ok := scopes[0].(string); ok {
|
|
return s
|
|
}
|
|
}
|
|
return ""
|
|
}
|