扫码登录：cdrop 自签会话原语 + 薄账户层 + 受限访客 + 2FA step-up

身份仍源自 OAuth provider（user_id = OIDC sub），cdrop 在其上自维护一薄层：自签会话令牌 + accounts 表，并新增扫码快速登录。实施蓝本见 AUTH.md。后端 · 自签会话原语 - web_sessions 加 kind/scope/granted_by 列（bootstrap 幂等迁移）；既有 oidc 会话行为不变，新增 self（滑动续期）/ guest（受限·不续）两类 - cdrop 自签 HS256 会话 access token，密钥派生自 SESSION_SECRET，与落盘 AES、 shortcut HS256 三密钥域隔离；jwtauth.verifySelfToken 无状态校验、靠 typ 区分 - requireFullSession 守卫：guest 会话不得改账号 / 再批准设备 / 签长效 token - /auth/refresh 按 kind 分流：self/guest 纯自签、不触 IdP 后端 · 扫码登录（internal/httpapi/qr.go） - qr/start・status・request・approve・deny 五端点 + login_requests 表 + reaper - 三密钥分离：QR 仅含批准信息，会话只投递给持私有 poll_secret 的原设备（偷拍 QR 者无 poll_secret 领不到会话、未登录批不了准） - 会话在新设备侧领取（cookie 不经手机）、单次消费、短 TTL 后端 · 薄账户层与 2FA step-up - accounts 表（键 sub，不含任何凭证）：exchange/refresh upsert match_key / 显示名 / 头像 / roles，供显示与未来管理员开启迁移标记时跨源关联 - step-up（默认关）：开启后 qr/approve 要求新鲜 prompt=login 授权码，后端就地换 id_token、JWKS 验签 + auth_time 窗口 + sub 匹配，provider 2FA 于此往返强制前端（web/） - 显码页 /link/new + 批准页 /link + net/qr.ts，对齐 Theme B、复用 AuthShell 与聚珍排版管线、零新全局样式 - step-up 再认证流：批准前跑 prompt=login PKCE，回调分叉（不消费一次性 code、独立 state key）后带 step_up_code/verifier 调 approve - 三语 i18n qr.*；新增 qrcode 依赖修复 · clipboard sweeper（早已提交的损坏） - ClearExpiredClipboards 因 clipboard.sql 全角注释触发 sqlc 1.31 多字节偏移 bug，生成 SQL 被截断为「UPDATE clipboard_state SET content =」，sweeper 运行期报「incomplete input」、过期剪贴板内容从未清除（短 TTL 暴露保护失效） - 注释改纯 ASCII 并加 bug 警告，重生成得完整 SQL；prod 已验证 sweeper 由 ERROR 转为正常清理（cleared count=1）构建 - .dockerignore：排除本地 node_modules 等，避免宿主原生二进制污染镜像内 vite 构建 - Dockerfile.base：GOPROXY 改为可经 --build-arg 覆盖（默认仍官方代理，受限网络构建时传区域镜像即可，仓库不固化区域值）文档 - 新增 AUTH.md（账户与登录实施蓝本）；README 特性；.env.example / compose.snippet 增配置项（QR / 自签会话 TTL / step-up / match_claim）测试 - 自签 token 密钥域隔离、扫码端到端（领取 / 单次 / poll_secret 校验 / deny / step-up 门）、extractIdentity、web_sessions 升级迁移
2026-06-21 22:43:36 +08:00
parent eda23f79b1
commit 90a3790a98
50 changed files with 4130 additions and 43 deletions
@@ -11,12 +11,22 @@ type Claims struct {
 	// enforces this). This keeps a leaked shortcut token's blast radius minimal.
 	JTI    string
 	Scopes []string
+	// SessionScope is set only for cdrop self-signed session tokens (scan-login):
+	// "full" or "guest". Empty for OIDC / dev sessions and scoped shortcut tokens.
+	// A "guest" session is capability-limited (requireFullSession rejects it on
+	// account-management routes) even though it is not Scoped().
+	SessionScope string
 }

 // Scoped reports whether these claims came from a scoped shortcut token rather
 // than a full login session.
 func (c *Claims) Scoped() bool { return c.JTI != "" }

+// Guest reports whether these claims came from a restricted guest session (a
+// scan-login borrow). Guest sessions can transfer files but not manage the
+// account, approve other devices, or mint long-lived tokens.
+func (c *Claims) Guest() bool { return c.SessionScope == "guest" }
+
 // HasScope reports whether the claims grant the named scope.
 func (c *Claims) HasScope(scope string) bool {
 	for _, s := range c.Scopes {
@@ -40,6 +50,13 @@ func ClaimsFromContext(ctx context.Context) (*Claims, bool) {
 	return c, ok
 }

+// ContextWithClaims attaches claims to a context — the inverse of
+// ClaimsFromContext. The auth middleware uses this; it is also the seam handlers
+// and tests use to inject claims directly.
+func ContextWithClaims(ctx context.Context, c *Claims) context.Context {
+	return context.WithValue(ctx, claimsCtxKey, c)
+}
+
 func DeviceNameFromContext(ctx context.Context) (string, bool) {
 	n, ok := ctx.Value(deviceCtxKey).(string)
 	return n, ok
@@ -29,10 +29,11 @@ type Store interface {
 }

 type Authenticator struct {
-	cfg   *config.Config
-	store Store
-	jwks  *jwksCache
-	hsKey []byte
+	cfg             *config.Config
+	store           Store
+	jwks            *jwksCache
+	hsKey           []byte
+	sessionTokenKey []byte
 }

 func New(cfg *config.Config, store Store) *Authenticator {
@@ -43,6 +44,9 @@ func New(cfg *config.Config, store Store) *Authenticator {
 	if cfg.HS256Secret != "" {
 		a.hsKey = DeriveHS256Key(cfg.HS256Secret)
 	}
+	// Self-signed session tokens (scan-login) are keyed off SessionSecret; nil
+	// when unset (dev) disables verifySelfToken, matching the minting side.
+	a.sessionTokenKey = DeriveSessionTokenKey(cfg.SessionSecret)
 	if cfg.AuthMode == "prod" && cfg.OIDCJWKSURL != "" {
 		a.jwks = newJWKSCache(cfg.OIDCJWKSURL, 10*time.Minute)
 	}
@@ -101,12 +105,51 @@ func (a *Authenticator) verify(ctx context.Context, token string, r *http.Reques
 	if a.cfg.AuthMode == "dev" {
 		return a.verifyDev(token, r)
 	}
+	// cdrop self-signed session tokens first: distinct key + typ=session, so a
+	// shortcut token (different key, requires jti) never validates here and a
+	// session token never falls through to the shortcut path's DB lookup.
+	if c, err := a.verifySelfToken(token); err == nil {
+		return c, nil
+	}
 	if c, err := a.verifyHS256(ctx, token); err == nil {
 		return c, nil
 	}
 	return a.verifyRS256(ctx, token)
 }

+// verifySelfToken validates a cdrop self-signed session access token (AUTH.md
+// §3.1): HS256 over DeriveSessionTokenKey, carrying typ=session and a full/guest
+// scope. Stateless by design — no DB lookup, so it stays cheap on every request;
+// revocation rides the short TTL (the session row is re-checked at /auth/refresh).
+func (a *Authenticator) verifySelfToken(token string) (*Claims, error) {
+	if len(a.sessionTokenKey) == 0 {
+		return nil, errors.New("session token key not configured")
+	}
+	parsed, err := jwt.ParseSigned(token, []jose.SignatureAlgorithm{jose.HS256})
+	if err != nil {
+		return nil, err
+	}
+	var std jwt.Claims
+	custom := map[string]any{}
+	if err := parsed.Claims(a.sessionTokenKey, &std, &custom); err != nil {
+		return nil, err
+	}
+	if err := std.ValidateWithLeeway(jwt.Expected{Time: time.Now()}, 30*time.Second); err != nil {
+		return nil, err
+	}
+	if typ, _ := custom["typ"].(string); typ != "session" {
+		return nil, errors.New("not a session token")
+	}
+	if std.Subject == "" {
+		return nil, errors.New("session token missing subject")
+	}
+	scope, _ := custom["scope"].(string)
+	if scope != "full" && scope != "guest" {
+		return nil, errors.New("session token invalid scope")
+	}
+	return &Claims{UserID: std.Subject, SessionScope: scope}, nil
+}
+
 func (a *Authenticator) verifyDev(token string, r *http.Request) (*Claims, error) {
 	if subtle.ConstantTimeCompare([]byte(token), []byte(a.cfg.DevToken)) != 1 {
 		return nil, errors.New("invalid dev token")
@@ -220,6 +263,66 @@ func (a *Authenticator) verifyRS256(ctx context.Context, token string) (*Claims,
 	return claimsFromJWT(std, custom)
 }

+// VerifyIDToken validates an OIDC id_token (RS256 via JWKS, issuer + audience)
+// from a fresh prompt=login exchange and returns its subject and auth_time (the
+// epoch second of the actual end-user authentication). Used for step-up re-auth
+// (AUTH.md §6): the caller checks sub matches and auth_time is recent enough.
+func (a *Authenticator) VerifyIDToken(ctx context.Context, token string) (subject string, authTime int64, err error) {
+	if a.jwks == nil {
+		return "", 0, errors.New("JWKS not configured")
+	}
+	parsed, err := jwt.ParseSigned(token, []jose.SignatureAlgorithm{jose.RS256})
+	if err != nil {
+		return "", 0, err
+	}
+	if len(parsed.Headers) == 0 {
+		return "", 0, errors.New("missing token headers")
+	}
+	key, err := a.jwks.GetKey(ctx, parsed.Headers[0].KeyID)
+	if err != nil {
+		return "", 0, err
+	}
+	var std jwt.Claims
+	custom := map[string]any{}
+	if err := parsed.Claims(key, &std, &custom); err != nil {
+		return "", 0, err
+	}
+	expected := jwt.Expected{Time: time.Now()}
+	if a.cfg.OIDCIssuer != "" {
+		expected.Issuer = a.cfg.OIDCIssuer
+	}
+	if a.cfg.OIDCAudience != "" {
+		expected.AnyAudience = parseAudiences(a.cfg.OIDCAudience)
+	}
+	if err := std.ValidateWithLeeway(expected, 30*time.Second); err != nil {
+		return "", 0, err
+	}
+	if std.Subject == "" {
+		return "", 0, errors.New("missing subject claim")
+	}
+	at, ok := numericClaim(custom["auth_time"])
+	if !ok {
+		return "", 0, errors.New("missing auth_time claim")
+	}
+	return std.Subject, at, nil
+}
+
+// numericClaim coerces a JSON number claim (float64 from stdlib unmarshal, or
+// json.Number / int64) to int64.
+func numericClaim(v any) (int64, bool) {
+	switch n := v.(type) {
+	case float64:
+		return int64(n), true
+	case int64:
+		return n, true
+	case json.Number:
+		if i, err := n.Int64(); err == nil {
+			return i, true
+		}
+	}
+	return 0, false
+}
+
 // parseAudiences splits a comma-separated OIDCAudience config into a jwt.Audience
 // set. Multiple values let one backend accept tokens minted for several OAuth
 // clients (the web app and the desktop client carry different `aud`); go-jose's
@@ -284,6 +387,20 @@ func DeriveHS256Key(secret string) []byte {
 	return sum[:]
 }

+// DeriveSessionTokenKey derives the HMAC key for cdrop's self-signed session
+// access tokens from CDROP_SESSION_SECRET. Domain-separated from both the at-rest
+// refresh-token AES key (plain sha256(secret), in httpapi) and the shortcut-token
+// key (DeriveHS256Key) so one secret yields three independent keys — a session
+// token can never validate as a shortcut token, or vice versa. Empty secret →
+// nil, which disables both minting and verifying (dev / unconfigured prod).
+func DeriveSessionTokenKey(secret string) []byte {
+	if secret == "" {
+		return nil
+	}
+	sum := sha256.Sum256([]byte("cdrop-session-jwt\x00" + secret))
+	return sum[:]
+}
+
 // SanitizeDeviceName enforces the global ASCII-only device-name policy. Device
 // names ride in the X-Device-Name HTTP header, which can't carry non-ASCII
 // reliably (and browser fetch rejects such header values outright), so the name
@@ -488,3 +488,80 @@ func TestSanitizeDeviceName(t *testing.T) {
 		}
 	}
 }
+
+// signSelfToken mints a cdrop self-signed session token the way httpapi.mintSessionToken
+// does: HS256 over DeriveSessionTokenKey, with typ + scope custom claims and no jti.
+func signSelfToken(t *testing.T, secret, sub, typ, scope string, exp time.Time) string {
+	t.Helper()
+	sig, err := jose.NewSigner(
+		jose.SigningKey{Algorithm: jose.HS256, Key: DeriveSessionTokenKey(secret)},
+		(&jose.SignerOptions{}).WithType("JWT"),
+	)
+	if err != nil {
+		t.Fatalf("signer: %v", err)
+	}
+	std := jwt.Claims{
+		Subject:  sub,
+		IssuedAt: jwt.NewNumericDate(time.Now()),
+		Expiry:   jwt.NewNumericDate(exp),
+	}
+	tok, err := jwt.Signed(sig).Claims(std).Claims(map[string]any{"typ": typ, "scope": scope}).Serialize()
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+	return tok
+}
+
+// A cdrop self-signed session token authenticates as a full or guest session;
+// guest is capability-limited (Guest() true). A wrong typ or an unknown scope is
+// rejected, and the SessionSecret-derived key is domain-isolated from the HS256
+// shortcut key so the two token families never cross-validate (AUTH.md §3.1).
+func TestSelfToken_ScopeAndKeyIsolation(t *testing.T) {
+	secret := "test-session-secret-at-least-32-bytes-long"
+	a := New(&config.Config{AuthMode: "prod", SessionSecret: secret}, &fakeDeviceUpserter{})
+	exp := time.Now().Add(time.Hour)
+
+	// Full session: authenticates, not scoped, not guest.
+	code, claims := serveBearer(a, signSelfToken(t, secret, "user-x", "session", "full", exp))
+	if code != http.StatusOK {
+		t.Fatalf("full session token: got %d, want 200", code)
+	}
+	if claims == nil || claims.UserID != "user-x" || claims.SessionScope != "full" || claims.Scoped() || claims.Guest() {
+		t.Fatalf("full session claims wrong: %+v", claims)
+	}
+
+	// Guest session: authenticates and is marked guest (capability-limited).
+	code, claims = serveBearer(a, signSelfToken(t, secret, "user-x", "session", "guest", exp))
+	if code != http.StatusOK || claims == nil || !claims.Guest() || claims.Scoped() {
+		t.Fatalf("guest session: code=%d claims=%+v", code, claims)
+	}
+
+	// Wrong typ (not "session") signed with the session key → rejected.
+	if c, _ := serveBearer(a, signSelfToken(t, secret, "user-x", "other", "full", exp)); c != http.StatusUnauthorized {
+		t.Errorf("wrong typ: got %d, want 401", c)
+	}
+	// Unknown scope → rejected (no privilege-by-typo).
+	if c, _ := serveBearer(a, signSelfToken(t, secret, "user-x", "session", "admin", exp)); c != http.StatusUnauthorized {
+		t.Errorf("invalid scope: got %d, want 401", c)
+	}
+
+	// Key-domain isolation: with BOTH secrets set, the two families stay disjoint —
+	// a session token never becomes scoped, a shortcut token never becomes a session.
+	hsSecret := "test-hs256-secret-at-least-32-bytes-long"
+	store := &fakeDeviceUpserter{tokens: map[string]db.ShortcutToken{
+		"jti-1": {Jti: "jti-1", UserID: "user-x", Scopes: "clipboard", ExpiresAt: exp.Unix()},
+	}}
+	ab := New(&config.Config{AuthMode: "prod", SessionSecret: secret, HS256Secret: hsSecret}, store)
+	if _, sc := serveBearer(ab, signSelfToken(t, secret, "user-x", "session", "guest", exp)); sc == nil || sc.Scoped() || !sc.Guest() {
+		t.Errorf("session token leaked into scoped path: %+v", sc)
+	}
+	if _, hc := serveBearer(ab, signHS256(t, hsSecret, "user-x", "jti-1", "clipboard", exp)); hc == nil || !hc.Scoped() || hc.SessionScope != "" {
+		t.Errorf("shortcut token leaked into session path: %+v", hc)
+	}
+
+	// No SessionSecret on the server → self tokens are unverifiable (key nil).
+	noSecret := New(&config.Config{AuthMode: "prod", HS256Secret: hsSecret}, &fakeDeviceUpserter{})
+	if c, _ := serveBearer(noSecret, signSelfToken(t, secret, "user-x", "session", "full", exp)); c != http.StatusUnauthorized {
+		t.Errorf("self token without server SessionSecret must be rejected, got %d", c)
+	}
+}