oauth

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// DefaultDCRWindow 是管理员打开接入窗口时的默认时长(也是「续期」每次加的时长)。
	DefaultDCRWindow = 10 * time.Minute
	// MaxDCRWindow 是接入窗口的时长上限:无论怎么续,总剩余都不超过它。
	MaxDCRWindow = 60 * time.Minute
)

接入窗口(#239):自动注册(DCR,POST /oauth/register)默认不是常开的。 管理员要先在「设置 → OAuth 授权」里开一个限时窗口,窗口期间客户端才能自己登记;窗口之外一律 403 registration_window_closed。 这样公网上就不再有一个常开的、任何人都能往库里写登记的入口。

语义与 ExecMesh 的发现窗口(terminal/registry.go)一致:默认 10 分钟、续期在剩余时间上累加、总剩余不超过 60 分钟、 只存内存(Hub 重启即关闭)。窗口只管 DCR;CIMD 客户端(client_id 本身是 https 地址)不登记,不受窗口约束。

View Source
const (
	DCRModeOff    = "off"    // 关闭:POST /oauth/register 一律 403 registration_disabled
	DCRModeWindow = "window" // 限时窗口(默认):窗口开着才受理
	DCRModeAlways = "always" // 常开:任何时候都受理
)

自动注册的三种方式(见 model.OAuthPolicy 的说明)。

View Source
const (
	RevokeSourceAdmin     = "admin"     // 管理员在设置里撤销授权,或删除了授权创建的凭据
	RevokeSourceSupersede = "supersede" // 批准新授权时勾选了「撤销旧授权」
	RevokeSourceConnector = "connector" // 连接器自己调用了 /oauth/revoke(RFC 7009)
)

撤销来源(oauth_revoke 详情里的 source=…)。

View Source
const (
	AccessTokenPrefix = "rmo_"
)
View Source
const EventGrantSuperseded = "oauth_grant_superseded"

EventGrantSuperseded 是「新授权取代了同一个应用的旧授权」的审计事件名(与 terminal.EvOAuthGrantSuperseded 一致)。

View Source
const EventTokenDenied = "oauth_token_denied"

EventTokenDenied 是令牌端点拒绝一次刷新 / 换码的审计事件名(与 terminal.EvOAuthTokenDenied 一致)。

View Source
const UnusedClientMaxAge = 24 * time.Hour

UnusedClientMaxAge:DCR 登记之后超过这么久还没走完授权,会在下一次有客户端登记时被清理。 设置页「刚登记、还没授权」清单只列还没到期的,免得列出一条随时会被清掉的。

Variables

View Source
var ErrInvalidPreviousGrant = errors.New("previous grant not found, already revoked, or belongs to another application")

ErrInvalidPreviousGrant 表示「沿用 / 撤销」的目标不是这个应用名下还没撤销的授权。批准会失败、待决请求保留,用户可以重新选择。

Functions

func ClearCIMDCache

func ClearCIMDCache()

ClearCIMDCache 供测试清空 CIMD 缓存。

func ClientGroupKey added in v2.2.0

func ClientGroupKey(clientID string) string

ClientGroupKey 把 client_id 变成一个不透明、稳定的分组键(SHA-256 前 8 字节的十六进制),给授权列表 / 凭据列表把「同一个应用」归到一起用。 不直接给 client_id:它在授权页之外没有用处,而列表只需要一个能比较相等的键。空 client_id 返回空串。

func ClientRef added in v2.1.0

func ClientRef(clientID string) string

ClientRef 取 DCR client_id 里的随机段(设置页用它指认一条登记,不把完整的 client_id 放进 URL);不是本服务签发的返回空串。

func DCRModeOf added in v2.1.0

func DCRModeOf(p model.OAuthPolicy) string

DCRModeOf 把策略里的两个布尔值翻译成自动注册方式。

func GenerateAccessToken

func GenerateAccessToken() (plain string, hash string, err error)

func GenerateAuthCode

func GenerateAuthCode() (string, error)

func GenerateRefreshToken

func GenerateRefreshToken() (plain string, hash string, err error)

func HashToken

func HashToken(plain string) string

func InternalCredentialToken

func InternalCredentialToken(grantID uint) string

func IsAccessTokenFormat

func IsAccessTokenFormat(s string) bool

func IsCustomSchemeRedirect

func IsCustomSchemeRedirect(redir string) bool

IsCustomSchemeRedirect 是否为 RFC 8252 私有方案(非 http(s))。

func IsLoopbackRedirect

func IsLoopbackRedirect(redir string) bool

func Issuer

func Issuer(cfg *config.Config, st *store.Store, r *http.Request) string

func NormalizeAndValidatePolicy

func NormalizeAndValidatePolicy(p model.OAuthPolicy) (model.OAuthPolicy, error)

NormalizeAndValidatePolicy 校验策略字段并规整对外地址(去掉首尾空白)。

func ParseScopeString

func ParseScopeString(scope string) []string

func ProtocolEnabled

func ProtocolEnabled(cfg *config.Config, st *store.Store) bool

ProtocolEnabled 环境硬开关关闭或策略总开关关闭时,OAuth 协议端点与 MCP 元数据均不启用。

func PublicBase

func PublicBase(cfg *config.Config, st *store.Store, r *http.Request) (string, bool)

PublicBase 返回对外可见的根 URL(无尾斜杠)与是否来自请求推导。

func RedirectDisplayScheme

func RedirectDisplayScheme(redir string) string

RedirectDisplayScheme 供授权页展示。

func RedirectHost

func RedirectHost(redir string) string

RedirectHost 用于授权页展示(只显示主机名)。

func RedirectURIInList

func RedirectURIInList(uris []string, requested string) bool

func RedirectURIMatches

func RedirectURIMatches(registered, requested string) bool

RedirectURIMatches 精确匹配 redirect_uri;回环地址按 RFC 8252 忽略端口。

func ResetCIMDNetHooksForTest

func ResetCIMDNetHooksForTest()

ResetCIMDNetHooksForTest 恢复默认 CIMD 网络行为。

func ResolvePublicBase

func ResolvePublicBase(cfg *config.Config, st *store.Store, r *http.Request) (base string, derived bool)

ResolvePublicBase 返回 issuer 根 URL 与是否来自请求推导(推导时需 no-store / Vary)。

func ResourceMetadataURL

func ResourceMetadataURL(cfg *config.Config, st *store.Store, r *http.Request) string

func ResourceURL

func ResourceURL(cfg *config.Config, st *store.Store, r *http.Request) string

func RevokeBroadcastedElsewhere added in v2.2.0

func RevokeBroadcastedElsewhere(detail string) bool

RevokeBroadcastedElsewhere 判断一条 oauth_revoke 审计对应的凭据列表变化是否已经由别处广播过: 管理端发起的撤销(source=admin:API 处理函数自己广播)与被新授权取代(source=supersede:随后的 oauth_grant_superseded 事件广播)不需要再广播一次;连接器自己撤销(source=connector)没有别的广播来源,要在审计钩子里广播, 否则打开着的凭据页要等下一次刷新才看到授权消失。旧版本只写「grant」,按管理端发起处理。

func ScopesToPermissions

func ScopesToPermissions(scopes []string) (model.Permissions, bool)

func SetCIMDCacheClock

func SetCIMDCacheClock(fn func() time.Time)

SetCIMDCacheClock 供测试注入缓存时钟。

func SetCIMDHTTPDoer

func SetCIMDHTTPDoer(d HTTPDoer)

func SetCIMDLookupHost

func SetCIMDLookupHost(fn func(ctx context.Context, host string) error)

SetCIMDLookupHost 供测试注入 DNS 解析(返回 nil 表示通过)。

func SetCIMDNetHooksForTest

func SetCIMDNetHooksForTest(lookup func(context.Context, string) ([]netip.Addr, error), dial func(context.Context, string, string) (net.Conn, error))

SetCIMDNetHooksForTest 注入 CIMD 网络钩子(仅测试)。

func SetServiceClock

func SetServiceClock(fn func() time.Time)

func TokenEqualHash

func TokenEqualHash(plain, hash string) bool

func ValidateCodeChallenge

func ValidateCodeChallenge(challenge string) bool

ValidateCodeChallenge S256 challenge 必须为 43 字符 base64url。

func ValidateCodeVerifier

func ValidateCodeVerifier(verifier string) bool

ValidateCodeVerifier RFC 7636 code_verifier。

func ValidateRedirectHostSyntax

func ValidateRedirectHostSyntax(host string) bool

ValidateRedirectHostSyntax 校验从请求推导出的 Host 是否合法。

func ValidateRedirectURI

func ValidateRedirectURI(raw string) error

ValidateRedirectURI 校验 OAuth redirect_uri(DCR / CIMD / authorize 共用)。

func ValidateRedirectURIList

func ValidateRedirectURIList(uris []string) error

ValidateRedirectURIList 校验列表长度与每一项。

func VerifyPKCE

func VerifyPKCE(challenge, method, verifier string) bool

PKCE S256

func WWWAuthenticateValue

func WWWAuthenticateValue(cfg *config.Config, st *store.Store, r *http.Request) string

func WarnUntrustedClient added in v2.1.0

func WarnUntrustedClient(clientID string, redirectURI string, registered bool) bool

WarnUntrustedClient 报告批准页要不要对这个客户端显示黄色提示「此客户端不在默认信任列表中」。 这只是提醒你看清楚是谁在申请,不会拒绝任何授权——真正的闸门是总开关与 DCR 开关。规则固定,没有开关:

  • registered 为真(本服务登记的 DCR 客户端):看重定向地址的主机,官方域名不提示;
  • registered 为假、client_id 是 https 地址(CIMD 客户端):看这个地址的主机,官方域名不提示;
  • 本机回环重定向一律提示(Claude Code 等本地工具;批准页另有一条专门的回环提示,见 IsLoopbackRedirect);
  • 地址解析不了、或不是官方域名:提示。

为什么要传 registered:本服务给 DCR 客户端签发的 client_id 就是「<对外地址>/oauth/clients/<随机串>」, 对外地址是 https 时它也以 https:// 开头——只看前缀会把真正的 ChatGPT / Claude 登记当成 CIMD、去比对本服务自己的域名, 于是永远被当成陌生来源。是不是 DCR 要由「这个 client_id 是不是在本服务登记过」来决定,调用方(授权入口)知道。

Types

type ApproveDecision

type ApproveDecision struct {
	// TerminalHosts / TerminalModeCap 是批准页明确给出的值;沿用旧授权(InheritFrom)时,nil / 空串表示「用旧凭据的」。
	TerminalHosts   []string
	TerminalModeCap string
	Approve         bool
	DenyReason      string
	// InheritFrom 是要沿用设置的旧授权编号(0 = 不沿用,按批准页默认值建新凭据);Supersede 是新授权**发出令牌之后**要撤销的旧授权编号(#294)。
	// 两者都必须是同一个应用(client_id)名下还没撤销的授权,否则批准失败(ErrInvalidPreviousGrant)、待决请求保留,用户可以重新选择。
	InheritFrom uint
	Supersede   []uint
}

ApproveDecision 用户批准授权(已通过 Web 登录与解锁校验)。

type AuditFn

type AuditFn func(event, result, detail string)

AuditFn 记录 OAuth 审计事件(不含机密)。

type CIMDDocument

type CIMDDocument struct {
	ClientID      string   `json:"client_id"`
	ClientName    string   `json:"client_name"`
	RedirectURIs  []string `json:"redirect_uris"`
	GrantTypes    []string `json:"grant_types"`
	ResponseTypes []string `json:"response_types"`
	TokenAuth     string   `json:"token_endpoint_auth_method"`
}

CIMDDocument 是客户端元数据文档的最小字段集。

func FetchCIMD

func FetchCIMD(ctx context.Context, clientIDURL string) (CIMDDocument, error)

type DCRStatus added in v2.1.0

type DCRStatus struct {
	// Mode:自动注册方式 off / window / always(由策略的 allow_dcr 与 dcr_always 决定)。
	Mode string `json:"mode"`
	// Open:此刻 POST /oauth/register 会不会被受理。授权服务器没在服务时一律 false;always 为 true;window 看窗口是否开着。
	Open bool `json:"open"`
	// Until 与 RemainingSeconds 只在 window 方式且窗口开着时有值。
	Until            *time.Time `json:"until,omitempty"`
	RemainingSeconds int        `json:"remaining_seconds"`
	// DefaultMinutes / MaxMinutes 是窗口的默认时长与上限(页面据此写按钮与说明,不在前端再写死一份)。
	DefaultMinutes int `json:"default_minutes"`
	MaxMinutes     int `json:"max_minutes"`
}

DCRStatus 是设置页「接入窗口」卡片用的只读视图:现算、不落库,只描述事实。 它挂在 EffectiveStatus.DCR 下面返回,与可编辑的策略分开——「策略里写着限时窗口」不等于「窗口此刻开着」。

func BuildDCRStatus added in v2.1.0

func BuildDCRStatus(p model.OAuthPolicy, now, windowUntil time.Time, serving bool) DCRStatus

BuildDCRStatus 由策略、此刻时间、窗口到期时间(零值 = 没开)与「授权服务器是否在服务」算出展示状态。

type EffectiveStatus added in v2.1.0

type EffectiveStatus struct {
	// EnvOff:环境变量 RELAYMESH_OAUTH=off 把 OAuth 整个关了(此时策略里的开关改了也没用,要去掉环境变量并重启)。
	EnvOff bool `json:"env_off"`
	// Enabled:协议端点此刻真的在服务(策略总开关打开,且没有被环境变量关掉)。
	Enabled bool `json:"enabled"`
	// PublicBase:此刻对外使用的根地址(无尾斜杠),PublicBaseSource 说明它从哪来(env / settings / derived)。
	PublicBase       string           `json:"public_base"`
	PublicBaseSource PublicBaseSource `json:"public_base_source"`
	// SettingsPublicURLShadowed:环境变量设置了对外地址,而设置页里也填了一个不同的值——设置页的那个被盖掉了。
	SettingsPublicURLShadowed bool `json:"settings_public_url_shadowed"`
	// ConnectorURL:在 ChatGPT / Claude 里添加连接器时要粘贴的地址(对外地址 + /mcp)。
	ConnectorURL string `json:"connector_url"`
	// 两个元数据地址:自检与排错时用。
	ResourceMetadataURL   string `json:"resource_metadata_url"`
	AuthServerMetadataURL string `json:"authorization_server_metadata_url"`
	// DCR:自动注册此刻的状态(方式 / 现在受不受理 / 接入窗口的剩余时间;#239)。Effective 只能按策略算出方式与「常开时受理」,
	// 接入窗口的开合在授权服务里,API 层用 Service.DCRStatus 覆盖这个字段。
	DCR DCRStatus `json:"dcr"`
}

EffectiveStatus 是设置页「状态卡」用的只读视图:这一刻 OAuth 到底有没有在服务、对外地址是什么、 ChatGPT / Claude 里的连接器该填哪个地址。

全部现算、不落库,只描述事实,不含任何密钥;它与策略(可编辑的那份)分开返回, 因为「策略里写着开」不等于「真的开着」——环境变量 RELAYMESH_OAUTH=off 会把它整个盖掉。

func Effective added in v2.1.0

func Effective(cfg *config.Config, st *store.Store, r *http.Request) EffectiveStatus

Effective 按这次请求(决定了「推导出来的地址」)计算 OAuth 的生效状态。

type HTTPDoer

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer 供测试注入;生产使用 net/http.Client。

type PendingRequestView

type PendingRequestView struct {
	ID            string   `json:"id"`
	ClientID      string   `json:"client_id"`
	ClientName    string   `json:"client_name"`
	RedirectHost  string   `json:"redirect_host"`
	Scopes        []string `json:"scopes"`
	Resource      string   `json:"resource"`
	WarnUntrusted bool     `json:"warn_untrusted"`
	WarnLoopback  bool     `json:"warn_loopback"`
}

PendingRequest 供 REST 读取待决授权。

type PreviousGrant added in v2.2.0

type PreviousGrant struct {
	GrantID      uint    `json:"grant_id"`
	CredentialID uint    `json:"credential_id"`
	CreatedAt    string  `json:"created_at"`
	LastUsedAt   *string `json:"last_used_at"`
	// Live 为 false 表示连接器还没用授权码换过令牌(半成品授权):它的设置只是批准页给的默认值,没有沿用的价值,但可以顺手清掉。
	Live     bool `json:"live"`
	IsActive bool `json:"is_active"`

	TerminalHosts   []string          `json:"terminal_hosts"`
	TerminalModeCap string            `json:"terminal_mode_cap"`
	Permissions     model.Permissions `json:"permissions"`
	ExpiresAt       *string           `json:"expires_at"`
	HasLimits       bool              `json:"has_limits"`
	AllowedCIDRs    int               `json:"allowed_cidr_count"`
	// WholeFS 为 true 表示这条凭据现在开着「允许整个文件系统」:它**不会**被沿用(开启它要刚刚重新验证密码并写审计,
	// 不能借批准页悄悄带过去),批准页据此提示管理员需要的话在凭据管理里重新开启。
	WholeFS bool `json:"whole_fs"`
}

PreviousGrant 是授权页「你之前授权过这个应用」那一栏里的一条:旧授权与它对应凭据**现在**的设置(不是批准时的快照)。

type PublicBaseSource added in v2.1.0

type PublicBaseSource string

PublicBaseSource 说明对外根地址是从哪里来的。设置页的状态卡靠它回答两个问题: 「我在设置页填的地址是不是被环境变量盖掉了」「现在用的是不是只按请求头推导出来的(公网上的客户端用不了)」。

const (
	PublicBaseFromEnv      PublicBaseSource = "env"      // 环境变量 RELAYMESH_PUBLIC_URL
	PublicBaseFromSettings PublicBaseSource = "settings" // 设置页保存的「对外地址」
	PublicBaseDerived      PublicBaseSource = "derived"  // 两处都没设:按请求的 Host / X-Forwarded-* 推导
)

func ResolvePublicBaseSource added in v2.1.0

func ResolvePublicBaseSource(cfg *config.Config, st *store.Store, r *http.Request) (string, PublicBaseSource)

ResolvePublicBaseSource 返回对外根 URL(无尾斜杠)与它的来源;优先级固定为 环境变量 > 设置页 > 请求推导。

type RedirectSummary added in v2.1.0

type RedirectSummary struct {
	Hosts     []string
	Untrusted bool // 有任何一个回调地址会让批准页显示黄色提示(含回环)
	Loopback  bool // 有任何一个回调地址是本机回环
}

RedirectSummary 是一条 DCR 登记的回调地址概况,给设置页「刚登记、还没授权的客户端」清单用: 去重后的回调主机,以及按批准页同一套规则得出的「陌生来源 / 本机回环」标记。

func SummarizeRedirects added in v2.1.0

func SummarizeRedirects(redirectURIs []string) RedirectSummary

SummarizeRedirects 汇总一条 DCR 登记的回调地址(登记的客户端一定是 registered)。没有任何回调地址按陌生来源处理。

type RevokeFn

type RevokeFn func(credentialID uint, reason string)

RevokeFn 撤销隐藏凭据时结束进行中的命令(与删除令牌相同)。

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service OAuth 授权服务器与资源元数据。

func NewService

func NewService(cfg *config.Config, st *store.Store, audit AuditFn, revoke RevokeFn) *Service

func (*Service) CloseDCRWindow added in v2.1.0

func (s *Service) CloseDCRWindow() bool

CloseDCRWindow 立即关闭接入窗口,返回此前是否开着。

func (*Service) Config

func (s *Service) Config() *config.Config

func (*Service) DCRStatus added in v2.1.0

func (s *Service) DCRStatus(p model.OAuthPolicy) DCRStatus

DCRStatus 返回策略 p 下接入窗口此刻的展示状态。

func (*Service) Decide

func (s *Service) Decide(ctx context.Context, reqID string, d ApproveDecision) (redirectURL string, err error)

func (*Service) DeleteRegisteredClient added in v2.1.0

func (s *Service) DeleteRegisteredClient(ctx context.Context, clientID string) (bool, error)

DeleteRegisteredClient 删除一条还没授权过的登记,返回是否真的删了(不存在或已经授权过的不删,返回 false)。 删除之后这个 client_id 不能再发起授权;它正在进行中的授权请求(批准页还开着)和还没兑换的授权码一并作废, 否则管理员刚删掉的登记仍能在批准页上被批准。

func (*Service) Enabled

func (s *Service) Enabled() bool

func (*Service) FindUnusedClientByRef added in v2.1.0

func (s *Service) FindUnusedClientByRef(ctx context.Context, ref string) (*model.OAuthClient, error)

FindUnusedClientByRef 按 ClientRef 找一条还没授权过的登记(不看是否过期,过期没清的也能删);找不到返回 nil。

func (*Service) GetPending

func (s *Service) GetPending(id string) (*PendingRequestView, bool)

func (*Service) ListUnusedClients added in v2.1.0

func (s *Service) ListUnusedClients(ctx context.Context) ([]model.OAuthClient, error)

ListUnusedClients 返回「刚登记、还没授权」的客户端:登记之后还没走完授权(没有签发过令牌)、也没过期的 DCR 登记,新的在前。 已授权的应用在授权列表里;CIMD 客户端不登记,不会出现在这里。

func (*Service) Mount

func (s *Service) Mount(engine *gin.Engine)

Mount 注册 /.well-known/* 与 /oauth/*(须在 SPA NoRoute 之前注册)。

func (*Service) OpenDCRWindow added in v2.1.0

func (s *Service) OpenDCRWindow(d time.Duration, extend bool) time.Time

OpenDCRWindow 打开接入窗口(extend=false:把剩余时间重置为 d)或续期(extend=true:在剩余时间上累加 d,窗口没开着时等同于打开)。 d 小于等于 0 用默认 10 分钟,超过 60 分钟按 60 分钟。返回新的到期时间。 前置条件由调用方(API 层)检查:授权服务器在服务、自动注册方式是限时窗口。

func (*Service) PreviousGrants added in v2.2.0

func (s *Service) PreviousGrants(ctx context.Context, clientID string) ([]PreviousGrant, error)

PreviousGrants 列出某个应用(client_id)名下还没撤销的授权,新的在前,最多 previousGrantsMax 条,附上它们对应凭据现在的设置。 凭据已经不存在的授权没有可展示、可沿用的东西,跳过。

func (*Service) ResolveCredential

func (s *Service) ResolveCredential(ctx context.Context, plain string) (*model.MCPCredential, error)

func (*Service) RevokeGrant

func (s *Service) RevokeGrant(ctx context.Context, grantID uint) error

RevokeGrant 管理端撤销授权。

func (*Service) SavePolicy

func (s *Service) SavePolicy(ctx context.Context, p model.OAuthPolicy) error

SavePolicy 保存 OAuth 策略并记审计。detail 只记各开关的开 / 关与「是否填了对外地址」,不写地址本身,也不含任何机密。

func (*Service) Store

func (s *Service) Store() *store.Store

Store 暴露给 api 包

func (*Service) WWWAuthenticate

func (s *Service) WWWAuthenticate(r *http.Request) string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL