Documentation
¶
Overview ¶
本文件实现任务 S06:Authorization Service(OAuth 流 stub)。
对齐上游:packages/credentials/authorization
说明:M39 已提供 AuthorizationService 注册原语(Register/List/Begin/Cancel 的 flow 载体)。S06 在此基础上补齐「流程生命周期」的 stub 语义:
- AuthService 持有一次性回调 token:Begin → 创建 pending session 并返回 token;
- Complete(token, value) 模拟「OAuth 回调拿到凭据」:把 value 写入凭证 Store (store.Set),session 进入 completed —— 之后 M39 的 Resolve 即可解析到该凭证;
- Cancel 取消 pending session(并调用 flow.Cancel);
生产环境接入真实浏览器/SDK 时,只需把 Complete 换成真实回调端点即可,本 stub 保持接口稳定。
Package credentials 提供凭证(Credentials)与授权流(Authorization Flow)接缝。
对齐上游:packages/credentials/credentials + credentials-local + authorization
设计要点:
- CredentialRef 使用品牌化类型(POSIX 变量名,如 OPENAI_API_KEY),每轮 LLM 请求 调用 Resolve 一次读取当前值,修改 env 后下一轮请求即看到新值;
- 凭证记录通过 Storage Domain 持久化,修改携带 CAS 版本(record modify CAS), 并发写冲突会被拒绝;
- describe() 只暴露「是否有值 + 是否可写」,绝不输出明文;
- AuthorizationFlow 注册后可 list/begin/cancel(OAuth 等外部流程的 stub 载体, S06 提供完整 stub 实现)。
Index ¶
- type AuthService
- func (s *AuthService) Begin(ctx context.Context, flowID FlowID) (token string, err error)
- func (s *AuthService) Cancel(ctx context.Context, token string) error
- func (s *AuthService) Complete(ctx context.Context, token string, value string) error
- func (s *AuthService) List() []AuthSession
- func (s *AuthService) Status(token string) (AuthSession, bool)
- type AuthSession
- type AuthStatus
- type AuthorizationService
- type CredentialInfo
- type Flow
- type FlowID
- type Store
- func (s *Store) Describe(ctx context.Context) []CredentialInfo
- func (s *Store) Resolve(ctx context.Context, ref brand.CredentialRef) (string, bool)
- func (s *Store) Set(ctx context.Context, ref brand.CredentialRef, value string) error
- func (s *Store) Unset(ctx context.Context, ref brand.CredentialRef) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthService ¶
type AuthService struct {
// contains filtered or unexported fields
}
AuthService 编排「begin → 回调 → resolved credential」的授权流程 stub。
func NewAuthService ¶
func NewAuthService(auth *AuthorizationService, store *Store) *AuthService
NewAuthService 创建授权服务 stub,绑定底层 flow 注册表与凭证存储。
func (*AuthService) Begin ¶
Begin 启动指定授权流,返回一次性回调 token。 适用范围:list flows → begin(token) → 外部完成 → Complete(token, value)。
func (*AuthService) Cancel ¶
func (s *AuthService) Cancel(ctx context.Context, token string) error
Cancel 取消 pending 会话(并调用 flow.Cancel)。
func (*AuthService) Complete ¶
Complete 模拟 OAuth 回调:把 value 写入凭证 Store,会话进入 completed。 后续 M39 的 Resolve(flowID 对应的 ref) 即可取到 value。
func (*AuthService) Status ¶
func (s *AuthService) Status(token string) (AuthSession, bool)
Status 返回指定会话状态。
type AuthSession ¶
type AuthSession struct {
ID string `json:"id"`
FlowID FlowID `json:"flowId"`
Status AuthStatus `json:"status"`
StartedAt time.Time `json:"startedAt"`
CredRef brand.CredentialRef `json:"credRef,omitempty"` // 回调写入的凭证引用
HasValue bool `json:"hasValue"`
}
AuthSession 是一条授权流程会话记录。
type AuthStatus ¶
type AuthStatus string
AuthStatus 是授权会话状态。
const ( AuthPending AuthStatus = "pending" // 等待回调 AuthCompleted AuthStatus = "completed" // 凭证已写入 AuthCancelled AuthStatus = "cancelled" // 已取消 )
授权会话状态枚举。
type AuthorizationService ¶
type AuthorizationService struct {
// contains filtered or unexported fields
}
AuthorizationService 是授权流注册中心。
func NewAuthorizationService ¶
func NewAuthorizationService() *AuthorizationService
NewAuthorizationService 创建授权服务。
func (*AuthorizationService) Cancel ¶
func (a *AuthorizationService) Cancel(ctx context.Context, id FlowID) error
Cancel 取消指定授权流。
func (*AuthorizationService) Register ¶
func (a *AuthorizationService) Register(f *Flow) error
Register 注册一个授权流。
type CredentialInfo ¶
type CredentialInfo struct {
Ref brand.CredentialRef `json:"ref"`
Writable bool `json:"writable"`
HasValue bool `json:"hasValue"`
}
CredentialInfo 是 describe 输出的单条凭证描述(不含明文)。
type Flow ¶
type Flow struct {
// ID 唯一标识。
ID FlowID
// Name 人类可读名称。
Name string
// Begin 开始授权流,返回可用于完成授权的提示/URL(stub 可返回占位)。
Begin func(ctx context.Context) (string, error)
// Cancel 取消授权流。
Cancel func(ctx context.Context) error
}
Flow 描述一个授权流(如 OAuth 授权码流)。
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store 是凭证存储:内存缓存 + Storage Domain CAS 持久化。
func (*Store) Describe ¶
func (s *Store) Describe(ctx context.Context) []CredentialInfo
Describe 输出凭证清单:只暴露 ref + writable + 是否有值,绝不输出明文。