flowchart TB
    subgraph "HTTP/RPC 层"
        API[HTTP API<br>/v1/acl/*]
        RPC[RPC ACL Endpoint]
    end
    
    subgraph "ACL 核心模块"
        direction TB
        Bootstrap[Bootstrap 初始化]
        TokenMgr[Token 管理器]
        PolicyMgr[Policy 管理器]
        RoleMgr[Role 管理器]
        BindingMgr[BindingRule 管理器]
        AuthMethodMgr[AuthMethod 管理器]
        Login[Login/Logout 登录]
        
        Resolver[ACL Resolver<br>Token+Policy缓存]
        Authorizer[Authorizer<br>权限决策引擎]
    end
    
    subgraph "权限执行点"
        CatalogAuth[Catalog 权限检查]
        KVAuth[KV 权限检查]
        ServiceAuth[Service 权限检查]
        NodeAuth[Node 权限检查]
        OtherAuth[其他模块检查]
    end
    
    subgraph "数据存储"
        FSM[FSM 状态机]
        State[State Store<br>Memdb]
        Raft[Raft 共识]
    end
    
    subgraph "跨DC复制"
        ReplicatorToken[Token Replicator]
        ReplicatorPolicy[Policy Replicator]
    end
    
    API --> RPC
    RPC --> Bootstrap
    RPC --> TokenMgr
    RPC --> PolicyMgr
    RPC --> RoleMgr
    RPC --> BindingMgr
    RPC --> AuthMethodMgr
    RPC --> Login
    
    TokenMgr --> Resolver
    PolicyMgr --> Resolver
    RoleMgr --> Resolver
    Login --> AuthMethodMgr
    Login --> TokenMgr
    
    Resolver --> Authorizer
    
    CatalogAuth --> Authorizer
    KVAuth --> Authorizer
    ServiceAuth --> Authorizer
    NodeAuth --> Authorizer
    OtherAuth --> Authorizer
    
    TokenMgr --> FSM
    PolicyMgr --> FSM
    RoleMgr --> FSM
    BindingMgr --> FSM
    AuthMethodMgr --> FSM
    
    FSM --> Raft
    Raft --> State
    
    State --> ReplicatorToken
    State --> ReplicatorPolicy
    ReplicatorToken --> RPC
    ReplicatorPolicy --> RPC

classDiagram
    class ACLToken {
        +string AccessorID
        +string SecretID
        +string Description
        +[]ACLTokenPolicyLink Policies
        +[]ACLTokenRoleLink Roles
        +[]ACLServiceIdentity ServiceIdentities
        +[]ACLNodeIdentity NodeIdentities
        +bool Local
        +time.Time CreateTime
        +time.Time ExpirationTime
        +string AuthMethod
        +Hash() []byte
    }
    
    class ACLPolicy {
        +string ID
        +string Name
        +string Description
        +string Rules
        +string Datacenters
        +Hash() []byte
    }
    
    class ACLRole {
        +string ID
        +string Name
        +string Description
        +[]ACLRolePolicyLink Policies
        +[]ACLServiceIdentity ServiceIdentities
        +[]ACLNodeIdentity NodeIdentities
        +Hash() []byte
    }
    
    class ACLBindingRule {
        +string ID
        +string Description
        +string AuthMethod
        +string Selector
        +string BindType
        +string BindName
    }
    
    class ACLAuthMethod {
        +string Name
        +string Type
        +string Description
        +string DisplayName
        +int MaxTokenTTL
        +map Config
    }
    
    class Authorizer {
        <<interface>>
        +ACLRead(ctx) EnforcementDecision
        +ACLWrite(ctx) EnforcementDecision
        +ServiceRead(name, ctx) EnforcementDecision
        +ServiceWrite(name, ctx) EnforcementDecision
        +NodeRead(name, ctx) EnforcementDecision
        +NodeWrite(name, ctx) EnforcementDecision
        +KeyRead(key, ctx) EnforcementDecision
        +KeyWrite(key, ctx) EnforcementDecision
    }
    
    class PolicyAuthorizer {
        +Policy defaultPolicy
        +[]Policy policies
        +AgentRead(name, ctx)
        +AgentWrite(name, ctx)
        +ServiceRead(name, ctx)
        +ServiceWrite(name, ctx)
        +NodeRead(name, ctx)
        +NodeWrite(name, ctx)
        +KeyRead(key, ctx)
        +KeyWrite(key, ctx)
    }
    
    class ACLResolver {
        +resolveToken(secretID) Authorizer
        +resolvePolicies(policyIDs) []Policy
        +cache *lru.TwoQueueCache
        +fetchFromBackend(id)
    }
    
    ACLToken --> ACLPolicy : policies
    ACLToken --> ACLRole : roles
    ACLRole --> ACLPolicy : policies
    ACLBindingRule --> ACLAuthMethod : references
    ACLResolver --> ACLToken : resolves
    ACLResolver --> Authorizer : returns
    PolicyAuthorizer ..|> Authorizer : implements
    ACLToken --> PolicyAuthorizer : compiles to

# 允许读取所有服务
service_prefix "" {
  policy = "read"
}

# 允许写入 web 服务
service "web" {
  policy = "write"
  intentions = "write"
}

# 允许读取 KV 前缀
key_prefix "config/" {
  policy = "read"
}

# 拒绝删除 KV
key_prefix "config/production/" {
  policy = "deny"
}

# 允许节点注册
node_prefix "" {
  policy = "write"
}

type Authorizer interface {
    // ACL 管理权限
    ACLRead(*AuthorizerContext) EnforcementDecision
    ACLWrite(*AuthorizerContext) EnforcementDecision
    
    // 服务权限
    ServiceRead(name string, ctx *AuthorizerContext) EnforcementDecision
    ServiceWrite(name string, ctx *AuthorizerContext) EnforcementDecision
    
    // 节点权限
    NodeRead(name string, ctx *AuthorizerContext) EnforcementDecision
    NodeWrite(name string, ctx *AuthorizerContext) EnforcementDecision
    
    // KV 权限
    KeyRead(key string, ctx *AuthorizerContext) EnforcementDecision
    KeyWrite(key string, ctx *AuthorizerContext) EnforcementDecision
    KeyList(prefix string, ctx *AuthorizerContext) EnforcementDecision
    
    // 其他权限（省略详细列表）
    EventRead(name string, ctx *AuthorizerContext) EnforcementDecision
    IntentionRead(name string, ctx *AuthorizerContext) EnforcementDecision
    SessionRead(node string, ctx *AuthorizerContext) EnforcementDecision
    PreparedQueryRead(name string, ctx *AuthorizerContext) EnforcementDecision
    // ...
}

type EnforcementDecision int
const (
    Deny    EnforcementDecision = iota  // 明确拒绝
    Allow                                // 明确允许
    Default                              // 无明确规则，使用默认策略
)

type ACLInitialTokenBootstrapRequest struct {
    BootstrapSecret string // 可选的预定义 SecretID
    Datacenter      string // 目标数据中心
    QueryOptions           // 查询选项（Token、Consistency等）
}

type ACLToken struct {
    AccessorID  string
    SecretID    string
    Description string
    Policies    []ACLTokenPolicyLink
    Local       bool
    CreateTime  time.Time
    // 其他字段见数据结构章节
}

func (a *ACL) BootstrapTokens(
    args *structs.ACLInitialTokenBootstrapRequest,
    reply *structs.ACLToken,
) error {
    // 1. 前置校验
    if !a.srv.config.ACLsEnabled {
        return acl.ErrDisabled
    }
    
    // 2. 转发到 Leader（如非 Leader）
    if done, err := a.srv.ForwardRPC("ACL.BootstrapTokens", args, reply); done {
        return err
    }
    
    // 3. 验证是否可以 Bootstrap
    state := a.srv.fsm.State()
    allowed, resetIdx, err := state.CanBootstrapACLToken()
    if !allowed {
        // 检查是否有 Reset Index 文件
        specifiedIndex := a.fileBootstrapResetIndex()
        if specifiedIndex != resetIdx {
            return fmt.Errorf("ACL bootstrap no longer allowed (reset index: %d)", resetIdx)
        }
    }
    
    // 4. 生成 Token
    accessor, _ := lib.GenerateUUID(a.srv.checkTokenUUID)
    secret := args.BootstrapSecret
    if secret == "" {
        secret, _ = lib.GenerateUUID(a.srv.checkTokenUUID)
    }
    
    token := &structs.ACLToken{
        AccessorID:  accessor,
        SecretID:    secret,
        Description: "Bootstrap Token (Global Management)",
        Policies: []structs.ACLTokenPolicyLink{
            {ID: structs.ACLPolicyGlobalManagementID}, // builtin/global-management
        },
        CreateTime: time.Now(),
        Local:      false,
    }
    
    // 5. 通过 Raft Apply 持久化
    req := &structs.ACLTokenBootstrapRequest{
        Token:      *token,
        ResetIndex: resetIdx,
    }
    
    resp, err := a.srv.raftApply(structs.ACLBootstrapRequestType, req)
    if err != nil {
        return err
    }
    
    // 6. 删除 Reset Index 文件（防止重复 Bootstrap）
    a.removeBootstrapResetFile()
    
    *reply = *token
    return nil
}

HTTP PUT /v1/acl/bootstrap
  ↓
agent/http/acl.go: aclBootstrapHandler()
  ↓
agent/rpc.go: RPC("ACL.BootstrapTokens", ...)
  ↓
agent/consul/acl_endpoint.go: ACL.BootstrapTokens()
  ↓
agent/consul/server.go: raftApply(ACLBootstrapRequestType, ...)
  ↓
agent/consul/fsm/fsm.go: FSM.Apply()
  ↓
agent/consul/fsm/acl.go: applyACLTokenBootstrap()
  ↓
agent/consul/state/acl.go: ACLBootstrap()
  ↓
State Store 更新 BootstrapIndex 和 Token 表

sequenceDiagram
    autonumber
    participant Client as 管理员
    participant HTTP as HTTP API
    participant RPC as ACL RPC Endpoint
    participant Leader as Raft Leader
    participant FSM as FSM 状态机
    participant State as State Store

    Note over Client,State: Bootstrap 初始化流程
    
    Client->>HTTP: PUT /v1/acl/bootstrap
    HTTP->>RPC: ACL.BootstrapTokens()
    
    alt 非 Leader
        RPC->>Leader: 转发到 Leader
    end
    
    RPC->>State: CanBootstrapACLToken()
    State-->>RPC: allowed=true/false, resetIdx
    
    alt Bootstrap 已执行
        RPC->>RPC: 检查 Reset Index 文件
        alt Reset Index 不匹配
            RPC-->>Client: 错误：Bootstrap 不再允许
        end
    end
    
    RPC->>RPC: 生成 AccessorID 和 SecretID
    RPC->>RPC: 构造 Token（关联 global-management 策略）
    
    RPC->>Leader: raftApply(ACLBootstrapRequestType, token)
    Leader->>FSM: Apply Raft Log
    FSM->>State: ACLBootstrap(token)
    State->>State: 更新 BootstrapIndex<br>插入 Token 到 tokens 表
    State-->>FSM: 成功
    FSM-->>Leader: 成功
    Leader-->>RPC: 成功
    
    RPC->>RPC: 删除 Reset Index 文件
    RPC-->>HTTP: 返回 Token
    HTTP-->>Client: 200 OK + Token JSON
    
    Note over Client: 使用 SecretID 进行后续操作

type ACLTokenSetRequest struct {
    ACLToken   ACLToken // Token 对象（包含所有字段）
    Create     bool     // true=创建，false=更新
    Datacenter string   // 目标数据中心
    WriteRequest        // Token、Namespace 等
}

type ACLToken struct {
    AccessorID     string
    SecretID       string
    Description    string
    Policies       []ACLTokenPolicyLink
    Roles          []ACLTokenRoleLink
    Local          bool
    CreateTime     time.Time
    ExpirationTime time.Time
    Hash           []byte
    CreateIndex    uint64
    ModifyIndex    uint64
}

func (a *ACL) TokenSet(
    args *structs.ACLTokenSetRequest,
    reply *structs.ACLToken,
) error {
    // 1. 前置校验
    if err := a.aclPreCheck(); err != nil {
        return err
    }
    
    // 2. 权限校验：需要 acl:write 权限
    authz, err := a.srv.ResolveTokenAndDefaultMeta(args.Token, &args.ACLToken.EnterpriseMeta, nil)
    if err != nil {
        return err
    }
    if authz.ACLWrite(nil) != acl.Allow {
        return acl.ErrPermissionDenied
    }
    
    // 3. 转发到 Leader
    if done, err := a.srv.ForwardRPC("ACL.TokenSet", args, reply); done {
        return err
    }
    
    // 4. 验证 Token 字段
    if args.Create {
        // 创建时生成 ID
        if args.ACLToken.AccessorID == "" {
            accessor, _ := lib.GenerateUUID(a.srv.checkTokenUUID)
            args.ACLToken.AccessorID = accessor
        }
        if args.ACLToken.SecretID == "" {
            secret, _ := lib.GenerateUUID(a.srv.checkTokenUUID)
            args.ACLToken.SecretID = secret
        }
        args.ACLToken.CreateTime = time.Now()
    } else {
        // 更新时验证 AccessorID 存在
        if args.ACLToken.AccessorID == "" {
            return fmt.Errorf("AccessorID is required for token update")
        }
        // 从 State Store 读取旧 Token
        state := a.srv.fsm.State()
        _, existing, err := state.ACLTokenGetByAccessor(nil, args.ACLToken.AccessorID, nil)
        if err != nil || existing == nil {
            return fmt.Errorf("Token not found")
        }
        // 保留 CreateTime 和 SecretID
        args.ACLToken.CreateTime = existing.CreateTime
        if args.ACLToken.SecretID == "" {
            args.ACLToken.SecretID = existing.SecretID
        }
    }
    
    // 5. 处理 ExpirationTTL（转换为 ExpirationTime）
    if args.ACLToken.ExpirationTTL != 0 {
        args.ACLToken.ExpirationTime = time.Now().Add(args.ACLToken.ExpirationTTL)
    }
    
    // 6. 验证 Policy/Role 引用存在
    if err := a.validateTokenLinks(&args.ACLToken); err != nil {
        return err
    }
    
    // 7. 通过 Raft Apply
    req := &structs.ACLTokenBatchSetRequest{
        Tokens: structs.ACLTokens{&args.ACLToken},
        CAS:    false,
    }
    
    resp, err := a.srv.raftApply(structs.ACLTokenSetRequestType, req)
    if err != nil {
        return err
    }
    
    // 8. 刷新 ACL Resolver 缓存
    if _, token, err := a.srv.fsm.State().ACLTokenGetByAccessor(nil, args.ACLToken.AccessorID, nil); err == nil && token != nil {
        *reply = *token
    }
    
    return nil
}

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant HTTP as HTTP API
    participant RPC as ACL RPC Endpoint
    participant Resolver as ACL Resolver
    participant Leader as Raft Leader
    participant FSM as FSM
    participant State as State Store

    Client->>HTTP: PUT /v1/acl/token<br>{"Description": "App Token", "Policies": [...]}
    HTTP->>RPC: ACL.TokenSet(request)
    
    RPC->>Resolver: ResolveToken(请求者 Token)
    Resolver-->>RPC: Authorizer
    RPC->>RPC: 检查 acl:write 权限
    
    alt 权限不足
        RPC-->>Client: 403 Permission Denied
    end
    
    RPC->>RPC: 生成 AccessorID, SecretID<br>设置 CreateTime
    RPC->>State: 验证 Policy/Role 引用存在
    State-->>RPC: OK
    
    RPC->>Leader: raftApply(ACLTokenSetRequestType, token)
    Leader->>FSM: Apply Log
    FSM->>State: ACLTokenSet(token)
    State->>State: 插入/更新 tokens 表<br>更新索引
    State-->>FSM: 成功
    FSM-->>Leader: 成功
    Leader-->>RPC: 成功
    
    RPC->>State: ACLTokenGetByAccessor(AccessorID)
    State-->>RPC: 完整 Token（含 Index）
    
    RPC-->>HTTP: Token
    HTTP-->>Client: 200 OK + Token JSON
    
    Note over Resolver: 后台任务：Token 进入缓存

type ACLTokenGetRequest struct {
    TokenID     string         // AccessorID 或 SecretID
    TokenIDType ACLTokenIDType // "accessor" 或 "secret"
    Expanded    bool           // 是否展开 Policy 内容
    Datacenter  string
    acl.EnterpriseMeta
    QueryOptions
}

func (a *ACL) TokenRead(
    args *structs.ACLTokenGetRequest,
    reply *structs.ACLTokenResponse,
) error {
    // 1. 权限校验：读取自己的 Token 或具有 acl:read 权限
    authz, err := a.srv.ResolveTokenAndDefaultMeta(args.Token, &args.EnterpriseMeta, nil)
    if err != nil {
        return err
    }
    
    // 2. 从 State Store 读取
    state := a.srv.fsm.State()
    var token *structs.ACLToken
    
    if args.TokenIDType == structs.ACLTokenAccessor {
        _, token, err = state.ACLTokenGetByAccessor(nil, args.TokenID, &args.EnterpriseMeta)
    } else {
        _, token, err = state.ACLTokenGetBySecret(nil, args.TokenID, &args.EnterpriseMeta)
    }
    
    if err != nil || token == nil {
        return acl.ErrNotFound
    }
    
    // 3. 权限判定：读取他人 Token 需要 acl:read
    if args.Token != token.SecretID && authz.ACLRead(nil) != acl.Allow {
        return acl.ErrPermissionDenied
    }
    
    // 4. 如果 Expanded=true，填充 Policy 内容
    if args.Expanded {
        for i := range token.Policies {
            _, policy, _ := state.ACLPolicyGetByID(nil, token.Policies[i].ID, &args.EnterpriseMeta)
            if policy != nil {
                token.Policies[i].Policy = policy
            }
        }
    }
    
    reply.Token = token
    reply.Index = token.ModifyIndex
    return nil
}

type ACLTokenDeleteRequest struct {
    TokenID    string // Token 的 AccessorID
    Datacenter string
    acl.EnterpriseMeta
    WriteRequest
}

func (a *ACL) TokenDelete(
    args *structs.ACLTokenDeleteRequest,
    reply *string,
) error {
    // 1. 权限校验：acl:write
    authz, err := a.srv.ResolveTokenAndDefaultMeta(args.Token, &args.EnterpriseMeta, nil)
    if authz.ACLWrite(nil) != acl.Allow {
        return acl.ErrPermissionDenied
    }
    
    // 2. 禁止删除内置 Token
    if args.TokenID == structs.ACLTokenAnonymousID {
        return fmt.Errorf("Cannot delete anonymous token")
    }
    
    // 3. 通过 Raft Apply 删除
    req := &structs.ACLTokenBatchDeleteRequest{
        TokenIDs: []string{args.TokenID},
    }
    
    _, err = a.srv.raftApply(structs.ACLTokenDeleteRequestType, req)
    if err != nil {
        return err
    }
    
    // 4. 刷新 Resolver 缓存
    a.srv.ACLResolver.cache.Remove(args.TokenID)
    
    *reply = args.TokenID
    return nil
}

type ACLLoginRequest struct {
    Auth       *ACLLoginParams // 认证参数
    Datacenter string
    WriteRequest
}

type ACLLoginParams struct {
    AuthMethod  string            // Auth Method 名称
    BearerToken string            // JWT/OIDC Token
    Meta        map[string]string // 附加元数据
    acl.EnterpriseMeta
}

type ACLToken struct {
    AccessorID  string
    SecretID    string
    Description string
    AuthMethod  string // 设置为登录的 Auth Method
    Roles       []ACLTokenRoleLink // 根据 BindingRule 匹配的 Role
    Local       bool   // true（Auth Method Token 始终是 Local）
    ExpirationTime time.Time // 根据 AuthMethod.MaxTokenTTL 设置
    // ...
}

func (a *ACL) Login(
    args *structs.ACLLoginRequest,
    reply *structs.ACLToken,
) error {
    // 1. 前置校验
    if !a.srv.LocalTokensEnabled() {
        return errAuthMethodsRequireTokenReplication
    }
    
    // 2. 加载 Auth Method 配置
    authMethod, validator, err := a.srv.loadAuthMethod(
        args.Auth.AuthMethod,
        &args.Auth.EnterpriseMeta,
    )
    if err != nil {
        return err
    }
    
    // 3. 验证 Bearer Token
    verifiedIdentity, err := validator.ValidateLogin(
        context.Background(),
        args.Auth.BearerToken,
    )
    if err != nil {
        return fmt.Errorf("Auth failed: %w", err)
    }
    
    // 4. 查询匹配的 Binding Rules
    state := a.srv.fsm.State()
    _, rules, err := state.ACLBindingRuleList(nil, args.Auth.AuthMethod, &args.Auth.EnterpriseMeta)
    if err != nil {
        return err
    }
    
    var roleLinks []structs.ACLTokenRoleLink
    for _, rule := range rules {
        // 使用 Selector 表达式匹配 Identity 字段
        if matches, _ := evaluateSelector(rule.Selector, verifiedIdentity); matches {
            if rule.BindType == "role" {
                roleLinks = append(roleLinks, structs.ACLTokenRoleLink{
                    Name: interpolate(rule.BindName, verifiedIdentity),
                })
            }
        }
    }
    
    if len(roleLinks) == 0 {
        return fmt.Errorf("No matching binding rules")
    }
    
    // 5. 创建 Token
    accessor, _ := lib.GenerateUUID(a.srv.checkTokenUUID)
    secret, _ := lib.GenerateUUID(a.srv.checkTokenUUID)
    
    description := fmt.Sprintf("token created via login: %s", args.Auth.AuthMethod)
    if len(args.Auth.Meta) > 0 {
        description += fmt.Sprintf(" (%v)", args.Auth.Meta)
    }
    
    token := &structs.ACLToken{
        AccessorID:  accessor,
        SecretID:    secret,
        Description: description,
        Roles:       roleLinks,
        AuthMethod:  args.Auth.AuthMethod,
        Local:       true, // Auth Method Token 始终是 Local
        CreateTime:  time.Now(),
    }
    
    // 6. 设置过期时间
    if authMethod.MaxTokenTTL > 0 {
        token.ExpirationTime = time.Now().Add(authMethod.MaxTokenTTL)
    }
    
    // 7. Raft Apply
    req := &structs.ACLTokenBatchSetRequest{
        Tokens: structs.ACLTokens{token},
    }
    _, err = a.srv.raftApply(structs.ACLTokenSetRequestType, req)
    if err != nil {
        return err
    }
    
    *reply = *token
    return nil
}

sequenceDiagram
    autonumber
    participant Client as 应用/用户
    participant HTTP as HTTP API
    participant RPC as ACL RPC Endpoint
    participant AuthMethod as Auth Method 验证器
    participant State as State Store
    participant Leader as Raft Leader
    participant FSM as FSM

    Client->>HTTP: POST /v1/acl/login<br>{"AuthMethod": "k8s-auth", "BearerToken": "..."}
    HTTP->>RPC: ACL.Login(request)
    
    RPC->>State: 读取 Auth Method 配置
    State-->>RPC: AuthMethod + Config
    
    RPC->>AuthMethod: ValidateLogin(BearerToken)
    AuthMethod->>AuthMethod: 验证 JWT 签名<br>提取 Claims
    AuthMethod-->>RPC: VerifiedIdentity (claims)
    
    RPC->>State: ACLBindingRuleList(AuthMethod)
    State-->>RPC: BindingRules[]
    
    loop 每个 Binding Rule
        RPC->>RPC: 评估 Selector 表达式<br>匹配 Identity 字段
        alt Selector 匹配
            RPC->>RPC: 插值 BindName（如 "web-${serviceaccount.name}"）<br>生成 Role 引用
        end
    end
    
    RPC->>RPC: 生成 Token<br>关联匹配的 Roles<br>设置 ExpirationTime
    
    RPC->>Leader: raftApply(ACLTokenSetRequestType, token)
    Leader->>FSM: Apply Log
    FSM->>State: ACLTokenSet(token)
    State-->>FSM: 成功
    FSM-->>RPC: 成功
    
    RPC-->>HTTP: Token (AccessorID + SecretID)
    HTTP-->>Client: 200 OK + Token JSON
    
    Note over Client: 使用 SecretID 调用 Consul API

{
  "Name": "k8s-auth",
  "Type": "kubernetes",
  "Description": "Kubernetes Service Account Auth",
  "MaxTokenTTL": "8h",
  "Config": {
    "Host": "https://kubernetes.default.svc",
    "CACert": "<base64-ca-cert>",
    "ServiceAccountJWT": "<token-reviewer-jwt>"
  }
}

{
  "AuthMethod": "k8s-auth",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "role",
  "BindName": "web-role"
}

# 1. Kubernetes Pod 内获取 Service Account Token
K8S_TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)

# 2. 调用 Consul Login
curl -X POST http://consul:8500/v1/acl/login \
  -d '{
    "AuthMethod": "k8s-auth",
    "BearerToken": "'$K8S_TOKEN'"
  }'

# 响应：
{
  "AccessorID": "xxxx-xxxx-xxxx-xxxx",
  "SecretID": "yyyy-yyyy-yyyy-yyyy",
  "Description": "token created via login: k8s-auth",
  "Roles": [
    {"ID": "...", "Name": "web-role"}
  ],
  "AuthMethod": "k8s-auth",
  "Local": true,
  "ExpirationTime": "2024-10-26T08:00:00Z"
}

# 3. 使用 SecretID 调用其他 API
curl -H "X-Consul-Token: yyyy-yyyy-yyyy-yyyy" \
  http://consul:8500/v1/catalog/services

sequenceDiagram
    autonumber
    participant Client as 客户端请求
    participant RPC as RPC Endpoint
    participant Resolver as ACL Resolver
    participant Cache as Token Cache
    participant State as State Store
    participant Authorizer as Authorizer

    Client->>RPC: RPC 请求 (携带 Token)
    RPC->>Resolver: ResolveToken(secretID)
    
    Resolver->>Cache: 查询缓存 (key=secretID)
    
    alt 缓存命中
        Cache-->>Resolver: Authorizer (cached)
    else 缓存未命中
        Resolver->>State: ACLTokenGetBySecret(secretID)
        State-->>Resolver: Token + Policies + Roles
        
        Resolver->>State: 批量读取 Policy 内容
        State-->>Resolver: Policy Rules (HCL)
        
        Resolver->>Resolver: 编译 Policy 为规则树
        Resolver->>Authorizer: 创建 PolicyAuthorizer
        
        Resolver->>Cache: 存入缓存 (TTL=30s)
    end
    
    Resolver-->>RPC: Authorizer
    
    RPC->>Authorizer: ServiceWrite("web", ctx)
    Authorizer->>Authorizer: 查找 "web" 的 service 规则<br>评估 Policy（Deny > Write > Read）
    Authorizer-->>RPC: Allow / Deny
    
    alt 权限不足
        RPC-->>Client: 403 Permission Denied
    else 权限充足
        RPC->>RPC: 执行业务逻辑
        RPC-->>Client: 200 OK + 响应数据
    end

sequenceDiagram
    autonumber
    participant PrimaryDC as 主数据中心
    participant PrimaryState as 主 DC State Store
    participant ReplicatorToken as Token Replicator<br>(从DC)
    participant ReplicatorPolicy as Policy Replicator<br>(从DC)
    participant SecondaryRPC as 从 DC RPC
    participant SecondaryState as 从 DC State Store

    Note over PrimaryDC,SecondaryState: 初始化：从 DC 启动复制任务
    
    ReplicatorPolicy->>PrimaryDC: RPC ACL.PolicyList (blocking query)
    PrimaryDC->>PrimaryState: 读取所有 Policy (Index > lastIndex)
    PrimaryState-->>PrimaryDC: Policies[]
    PrimaryDC-->>ReplicatorPolicy: Policies[] + Index
    
    ReplicatorPolicy->>ReplicatorPolicy: 对比本地 Policy<br>计算差异（新增、更新、删除）
    
    loop 批量写入（100条/批次）
        ReplicatorPolicy->>SecondaryRPC: raftApply(ACLPolicyBatchSetRequest, policies)
        SecondaryRPC->>SecondaryState: 批量插入/更新 Policy
    end
    
    ReplicatorPolicy->>ReplicatorPolicy: 更新 lastIndex<br>休眠 1s 后继续
    
    Note over PrimaryDC,SecondaryState: Token 复制（仅 Global Token）
    
    ReplicatorToken->>PrimaryDC: RPC ACL.TokenList (IncludeGlobal=true, Index > lastIndex)
    PrimaryDC->>PrimaryState: 读取 Global Token (Local=false)
    PrimaryState-->>PrimaryDC: Tokens[]
    PrimaryDC-->>ReplicatorToken: Tokens[] + Index
    
    ReplicatorToken->>ReplicatorToken: 对比本地 Token<br>计算差异
    
    loop 批量写入
        ReplicatorToken->>SecondaryRPC: raftApply(ACLTokenBatchSetRequest, tokens)
        SecondaryRPC->>SecondaryState: 批量插入/更新 Token
    end
    
    ReplicatorToken->>ReplicatorToken: 更新 lastIndex<br>休眠 1s 后继续
    
    Note over PrimaryDC,SecondaryState: 持续循环直到进程终止

type ACLResolver struct {
    config    ACLResolverConfig
    logger    hclog.Logger
    delegate  ACLResolverBackend // State Store 的抽象接口
    aclConf   *acl.Config
    
    // Token 缓存：SecretID -> Authorizer
    cache *lru.TwoQueueCache
    
    // Identity 缓存：AccessorID -> Identity
    identityCache *lru.TwoQueueCache
    
    // Policy 缓存：PolicyID -> ParsedPolicy
    policyCache *lru.TwoQueueCache
    
    // Role 缓存：RoleID -> Role
    roleCache *lru.TwoQueueCache
    
    // Sentinel值：匿名Token、已删除Token等
    sentinel map[string]*authorizerCacheEntry
}

type authorizerCacheEntry struct {
    authorizer  acl.Authorizer
    token       *structs.ACLToken
    expiresAt   time.Time
    fetchedAt   time.Time
}

func (r *ACLResolver) ResolveToken(secretID string) (acl.Authorizer, error) {
    // 1. 检查是否为匿名 Token
    if secretID == "" || secretID == acl.AnonymousTokenSecret {
        return r.anonymousAuthorizer()
    }
    
    // 2. 查询缓存
    if entry, ok := r.cache.Get(secretID); ok {
        cached := entry.(*authorizerCacheEntry)
        
        // 检查是否过期
        if time.Now().Before(cached.expiresAt) {
            return cached.authorizer, nil
        }
        
        // 缓存过期，移除
        r.cache.Remove(secretID)
    }
    
    // 3. 从 Backend 读取 Token
    token, err := r.delegate.ACLTokenGetBySecret(secretID)
    if err != nil {
        return nil, err
    }
    if token == nil {
        return nil, acl.ErrNotFound
    }
    
    // 4. 检查 Token 是否过期
    if !token.ExpirationTime.IsZero() && time.Now().After(token.ExpirationTime) {
        // 异步删除过期 Token
        go r.delegate.ACLTokenDelete(token.AccessorID)
        return nil, acl.ErrNotFound
    }
    
    // 5. 解析 Token 关联的 Policies 和 Roles
    policies, err := r.resolvePoliciesForToken(token)
    if err != nil {
        return nil, err
    }
    
    // 6. 编译 Policies 为 Authorizer
    authorizer, err := r.newAuthorizerFromPolicies(policies)
    if err != nil {
        return nil, err
    }
    
    // 7. 存入缓存
    entry := &authorizerCacheEntry{
        authorizer: authorizer,
        token:      token,
        expiresAt:  time.Now().Add(r.config.ACLTokenTTL), // 默认 30s
        fetchedAt:  time.Now(),
    }
    r.cache.Add(secretID, entry)
    
    return authorizer, nil
}

func (r *ACLResolver) resolvePoliciesForToken(token *structs.ACLToken) ([]*structs.ACLPolicy, error) {
    var policies []*structs.ACLPolicy
    
    // 1. 直接关联的 Policies
    for _, link := range token.Policies {
        policy, err := r.resolvePolicyByID(link.ID)
        if err != nil {
            return nil, err
        }
        if policy != nil {
            policies = append(policies, policy)
        }
    }
    
    // 2. 通过 Roles 关联的 Policies
    for _, roleLink := range token.Roles {
        role, err := r.resolveRoleByID(roleLink.ID)
        if err != nil {
            return nil, err
        }
        if role == nil {
            continue
        }
        
        for _, policyLink := range role.Policies {
            policy, err := r.resolvePolicyByID(policyLink.ID)
            if err != nil {
                return nil, err
            }
            if policy != nil {
                policies = append(policies, policy)
            }
        }
    }
    
    // 3. ServiceIdentities 转换为隐式 Policy
    for _, si := range token.ServiceIdentities {
        policy := synthesizeServiceIdentityPolicy(si)
        policies = append(policies, policy)
    }
    
    // 4. NodeIdentities 转换为隐式 Policy
    for _, ni := range token.NodeIdentities {
        policy := synthesizeNodeIdentityPolicy(ni)
        policies = append(policies, policy)
    }
    
    return policies, nil
}

func synthesizeServiceIdentityPolicy(si *structs.ACLServiceIdentity) *structs.ACLPolicy {
    // ServiceIdentity 自动生成以下权限：
    // - service:write (允许注册服务)
    // - service:read (允许查询服务)
    // - node:read (允许查询节点)
    // - intention:read (允许读取意图)
    
    rules := fmt.Sprintf(`
service "%s" {
  policy = "write"
}
service "%s-sidecar-proxy" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}
`, si.ServiceName, si.ServiceName)
    
    return &structs.ACLPolicy{
        ID:          fmt.Sprintf("synthetic-policy-service-%s", si.ServiceName),
        Name:        fmt.Sprintf("service-identity-%s", si.ServiceName),
        Description: "Synthetic policy generated from service identity",
        Rules:       rules,
    }
}

type PolicyAuthorizer struct {
    // 默认策略（allow 或 deny）
    defaultPolicy acl.EnforcementDecision
    
    // 各资源的规则树
    serviceRules   *policyRuleSet
    nodeRules      *policyRuleSet
    keyRules       *policyRuleSet
    sessionRules   *policyRuleSet
    eventRules     *policyRuleSet
    queryRules     *policyRuleSet
    
    // 全局权限
    aclRule      string // "read" / "write" / "deny"
    keyringRule  string
    operatorRule string
    meshRule     string
    peeringRule  string
}

type policyRuleSet struct {
    // 精确匹配规则：资源名 -> 策略级别
    exactRules map[string]string
    
    // 前缀匹配规则：前缀 -> 策略级别（按前缀长度排序）
    prefixRules []prefixRule
}

type prefixRule struct {
    prefix string
    policy string
}

func (p *PolicyAuthorizer) ServiceWrite(name string, ctx *acl.AuthorizerContext) acl.EnforcementDecision {
    // 1. 查找精确匹配规则
    if policy, ok := p.serviceRules.exactRules[name]; ok {
        return policyToDecision(policy, "write")
    }
    
    // 2. 查找前缀匹配规则（最长匹配优先）
    for i := len(p.serviceRules.prefixRules) - 1; i >= 0; i-- {
        rule := p.serviceRules.prefixRules[i]
        if strings.HasPrefix(name, rule.prefix) {
            return policyToDecision(rule.policy, "write")
        }
    }
    
    // 3. 无匹配规则，返回 Default（由默认策略决定）
    return acl.Default
}

func policyToDecision(policy string, requiredLevel string) acl.EnforcementDecision {
    levels := map[string]int{
        "deny":  0,
        "read":  1,
        "list":  2,
        "write": 3,
    }
    
    required := levels[requiredLevel]
    actual := levels[policy]
    
    if actual >= required {
        return acl.Allow
    }
    if policy == "deny" {
        return acl.Deny
    }
    return acl.Default
}