apitoken

package
v1.0.0-rc.21 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package apitoken 管理 API 令牌(路线图 M12):给 App、MCP 与 qB 兼容入口用,网页登录仍然只认 session。

令牌是 `ptt_<id>_<secret>`,secret 是 32 字节随机数的 base64url。库里只存 secret 的 SHA-256:按 id 找到那一行, 再用常量时间比较散列。高熵的随机令牌不需要 bcrypt,每个请求也不用做一次慢散列。 格式不对、id 不存在、secret 不对、过期、已撤销一律返回同一个 ErrUnauthorized,不给枚举的线索。

Index

Constants

View Source
const (
	ScopeAppRead    = "app:read"
	ScopeAppWrite   = "app:write"
	ScopeMCPRead    = "mcp:read"
	ScopeMCPWrite   = "mcp:write"
	ScopeQbitCompat = "qbit:compat"
)

权限范围:精确匹配,不支持通配。

Variables

View Source
var (
	ErrInvalid      = errors.New("参数不对")
	ErrNotFound     = errors.New("没有这个令牌")
	ErrUnauthorized = errors.New("令牌无效或已过期")
)

Scopes 是所有权限范围,也是令牌里 scope 的排列顺序。

Functions

func ValidScope

func ValidScope(s string) bool

ValidScope 报告是不是认识的权限范围。

Types

type CreateInput

type CreateInput struct {
	Name          string   `json:"name"`
	Scopes        []string `json:"scopes"`
	ExpiresInDays int      `json:"expires_in_days"`
}

CreateInput 是新建令牌的内容。ExpiresInDays 为 0 时不过期。

type Store

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

Store 存取令牌。

func New

func New(db *gorm.DB) *Store

New 建一个令牌库。

func (*Store) Create

func (s *Store) Create(ctx context.Context, in CreateInput, by string) (Token, string, error)

Create 新建令牌,返回令牌与明文(明文只在这里给一次)。

func (*Store) Get

func (s *Store) Get(ctx context.Context, id uint) (Token, error)

Get 按编号复查令牌:qB 兼容入口登录以后用会话,每次请求都要确认令牌还在、没过期。不存在、过期都是 ErrUnauthorized;也记最近一次使用。

func (*Store) List

func (s *Store) List(ctx context.Context) ([]Token, error)

List 列出令牌(新的在前)。

func (*Store) Revoke

func (s *Store) Revoke(ctx context.Context, id uint) error

Revoke 撤销令牌(删掉,立即生效)。

func (*Store) Verify

func (s *Store) Verify(ctx context.Context, plain string) (Token, error)

Verify 校验明文令牌,对的时候返回令牌(顺带记下最近一次使用,5 分钟内最多写一次库)。

type Token

type Token struct {
	ID         uint       `json:"id"`
	Name       string     `json:"name"`
	Scopes     []string   `json:"scopes"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
	CreatedBy  string     `json:"created_by"`
	CreatedAt  time.Time  `json:"created_at"`
}

Token 是一个令牌(不含明文与散列)。

func (Token) Has

func (t Token) Has(scope string) bool

Has 报告令牌有没有这个权限范围。

Jump to

Keyboard shortcuts

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