feat(ssf): 托管机器凭据并支持动态恢复

Gateway 连接表单接收认证中心一次性交付的 machine Client 凭据，后端立即写入 SecretStore，数据库和公开响应只保留引用及公开 Client ID。SSF 管理 Token、Verification 和 RFC 7662 内省统一从动态凭据读取，支持现有连接无重启修复及进程重启恢复，环境变量仅保留为旧部署回退。\n\n验证：go test ./apps/api/...；pnpm nx test web；真实重启、OIDC 登录与 session-revoked 1.29 秒失效验收。
2026-07-17 09:13:57 +08:00
parent 8e33d1d33e
commit ffb85b73af
15 changed files with 327 additions and 90 deletions
@@ -34,6 +34,7 @@ type ConnectionRepository interface {
 	CreateSecurityEventConnection(context.Context, store.CreateSecurityEventConnectionInput) (store.SecurityEventConnection, error)
 	SecurityEventConnection(context.Context) (store.SecurityEventConnection, error)
 	BindSecurityEventConnection(context.Context, string, string, string, string, int64) (store.SecurityEventConnection, error)
+	SetSecurityEventManagementCredential(context.Context, string, string, string) (store.SecurityEventConnection, error)
 	UpdateSecurityEventConnectionLifecycle(context.Context, string, string, *string) (store.SecurityEventConnection, error)
 	SetSecurityEventNextCredential(context.Context, string, string) (store.SecurityEventConnection, error)
 	PromoteSecurityEventCredential(context.Context, string, string) (store.SecurityEventConnection, error)
@@ -181,51 +182,114 @@ func (m *ConnectionManager) Get(ctx context.Context) (ConnectionView, error) {
 	return m.view(connection), nil
 }

-func (m *ConnectionManager) Connect(ctx context.Context, issuer, idempotencyKey string) (ConnectionView, error) {
+func (m *ConnectionManager) IntrospectionCredential(ctx context.Context) (string, []byte, error) {
+	connection, err := m.repository.SecurityEventConnection(ctx)
+	if errors.Is(err, store.ErrSecurityEventConnectionNotFound) {
+		if m.config.ManagementClientID != "" && m.config.ManagementClientSecret != "" {
+			return m.config.ManagementClientID, []byte(m.config.ManagementClientSecret), nil
+		}
+		return "", nil, errors.New("managed machine credential is unavailable")
+	}
+	if err != nil {
+		return "", nil, err
+	}
+	return m.managementCredential(ctx, connection)
+}
+
+func (m *ConnectionManager) Connect(ctx context.Context, issuer, managementClientID string, managementSecret []byte, idempotencyKey string) (ConnectionView, error) {
 	m.operation.Lock()
 	defer m.operation.Unlock()
 	issuer = strings.TrimRight(strings.TrimSpace(issuer), "/")
+	managementClientID = strings.TrimSpace(managementClientID)
 	if idempotencyKey == "" {
 		return ConnectionView{}, errors.New("idempotency key is required")
 	}
-	if err := m.validatePrerequisites(issuer); err != nil {
+	existing, err := m.repository.SecurityEventConnection(ctx)
+	if err != nil && !errors.Is(err, store.ErrSecurityEventConnectionNotFound) {
+		return ConnectionView{}, err
+	}
+	credentialsProvided := managementClientID != "" || len(managementSecret) > 0
+	if (managementClientID == "") != (len(managementSecret) == 0) {
+		return ConnectionView{}, errors.New("machine client id and secret must be provided together")
+	}
+	if !credentialsProvided {
+		if err == nil {
+			managementClientID, managementSecret, _ = m.managementCredential(ctx, existing)
+		} else {
+			managementClientID = strings.TrimSpace(m.config.ManagementClientID)
+			managementSecret = []byte(m.config.ManagementClientSecret)
+		}
+	}
+	defer clear(managementSecret)
+	if err := m.validatePrerequisites(issuer, managementClientID, managementSecret, errors.Is(err, store.ErrSecurityEventConnectionNotFound)); err != nil {
 		return ConnectionView{}, err
 	}
-	existing, err := m.repository.SecurityEventConnection(ctx)
 	if err == nil {
 		if existing.TransmitterIssuer != issuer {
 			return ConnectionView{}, store.ErrSecurityEventConnectionConflict
 		}
+		if credentialsProvided {
+			existing, err = m.persistManagementCredential(ctx, existing, managementClientID, managementSecret)
+			if err != nil {
+				return ConnectionView{}, err
+			}
+		}
 		if existing.StreamID != nil && !resumableConnectionLifecycle(existing.LifecycleStatus) {
+			if existing.Audience != nil {
+				if err := m.activate(ctx, existing); err != nil {
+					return ConnectionView{}, err
+				}
+			}
 			return m.view(existing), nil
 		}
 		return m.resumeConnecting(ctx, existing)
 	}
-	if !errors.Is(err, store.ErrSecurityEventConnectionNotFound) {
-		return ConnectionView{}, err
-	}
 	connectionID := uuid.NewString()
 	reference := "ssf-push-" + connectionID
+	managementReference := "ssf-management-" + connectionID
+	if err := m.secrets.Put(ctx, managementReference, managementSecret); err != nil {
+		return ConnectionView{}, err
+	}
 	secret, err := randomPushBearer()
 	if err != nil {
+		_ = m.secrets.Delete(ctx, managementReference)
 		return ConnectionView{}, err
 	}
 	defer clear(secret)
 	if err := m.secrets.Put(ctx, reference, secret); err != nil {
+		_ = m.secrets.Delete(ctx, managementReference)
 		return ConnectionView{}, err
 	}
 	endpoint := strings.TrimRight(m.config.PublicBaseURL, "/") + "/api/v1/security-events/ssf"
 	connection, err := m.repository.CreateSecurityEventConnection(ctx, store.CreateSecurityEventConnectionInput{
 		ConnectionID: connectionID, TransmitterIssuer: issuer, EndpointURL: endpoint,
-		CredentialRef: reference, IdempotencyKey: idempotencyKey,
+		CredentialRef: reference, ManagementClientID: managementClientID,
+		ManagementCredentialRef: managementReference, IdempotencyKey: idempotencyKey,
 	})
 	if err != nil {
 		_ = m.secrets.Delete(ctx, reference)
+		_ = m.secrets.Delete(ctx, managementReference)
 		return ConnectionView{}, err
 	}
 	return m.resumeConnecting(ctx, connection)
 }

+func (m *ConnectionManager) persistManagementCredential(ctx context.Context, connection store.SecurityEventConnection, clientID string, secret []byte) (store.SecurityEventConnection, error) {
+	reference := "ssf-management-" + connection.ConnectionID + "-" + uuid.NewString()
+	if err := m.secrets.Put(ctx, reference, secret); err != nil {
+		return store.SecurityEventConnection{}, err
+	}
+	updated, err := m.repository.SetSecurityEventManagementCredential(ctx, connection.ConnectionID, clientID, reference)
+	if err != nil {
+		_ = m.secrets.Delete(ctx, reference)
+		return store.SecurityEventConnection{}, err
+	}
+	if connection.ManagementCredentialRef != nil {
+		_ = m.secrets.Delete(ctx, *connection.ManagementCredentialRef)
+	}
+	return updated, nil
+}
+
 func resumableConnectionLifecycle(status string) bool {
 	switch status {
 	case "connecting", "verifying", "degraded", "error":
@@ -484,6 +548,11 @@ func (m *ConnectionManager) activate(ctx context.Context, connection store.Secur
 		return err
 	}
 	defer clear(current)
+	managementClientID, managementSecret, err := m.managementCredential(ctx, connection)
+	if err != nil {
+		return err
+	}
+	defer clear(managementSecret)
 	var next []byte
 	if connection.NextCredentialRef != nil {
 		next, err = m.secrets.Get(ctx, *connection.NextCredentialRef)
@@ -517,7 +586,7 @@ func (m *ConnectionManager) activate(ctx context.Context, connection store.Secur
 	service, err := NewService(m.repository, ServiceConfig{
 		Issuer: connection.TransmitterIssuer, Audience: *connection.Audience, StreamID: *connection.StreamID,
 		ManagementTokenURL: strings.TrimRight(m.config.OIDCIssuer, "/") + "/token",
-		ManagementClientID: m.config.ManagementClientID, ManagementSecret: m.config.ManagementClientSecret,
+		ManagementClientID: managementClientID, ManagementSecret: string(managementSecret),
 		HeartbeatInterval: m.config.HeartbeatInterval, StaleAfter: m.config.StaleAfter,
 		HTTPClient: safeClient,
 	})
@@ -656,13 +725,16 @@ func (m *ConnectionManager) finishRetirement(connection store.SecurityEventConne
 	}
 	m.stopRuntime()
 	_ = m.secrets.Delete(m.ctx, connection.CredentialRef)
+	if connection.ManagementCredentialRef != nil {
+		_ = m.secrets.Delete(m.ctx, *connection.ManagementCredentialRef)
+	}
 	if connection.NextCredentialRef != nil {
 		_ = m.secrets.Delete(m.ctx, *connection.NextCredentialRef)
 	}
 }

-func (m *ConnectionManager) validatePrerequisites(issuer string) error {
-	if !m.config.OIDCEnabled || m.config.ManagementClientID == "" || m.config.ManagementClientSecret == "" {
+func (m *ConnectionManager) validatePrerequisites(issuer, managementClientID string, managementSecret []byte, requirePublicBaseURL bool) error {
+	if !m.config.OIDCEnabled || strings.TrimSpace(managementClientID) == "" || len(managementSecret) < 16 {
 		return errors.New("OIDC and RFC 7662 machine client must be configured")
 	}
 	if _, err := uuid.Parse(m.config.OIDCTenantID); err != nil {
@@ -671,6 +743,9 @@ func (m *ConnectionManager) validatePrerequisites(issuer string) error {
 	if _, err := validatedIssuerURL(issuer, m.config.AppEnv); err != nil {
 		return err
 	}
+	if !requirePublicBaseURL {
+		return nil
+	}
 	endpoint, err := url.Parse(strings.TrimRight(m.config.PublicBaseURL, "/") + "/api/v1/security-events/ssf")
 	if err != nil || endpoint.Host == "" || endpoint.User != nil || endpoint.RawQuery != "" || endpoint.Fragment != "" {
 		return errors.New("AI_GATEWAY_PUBLIC_BASE_URL is invalid")
@@ -710,12 +785,21 @@ func (m *ConnectionManager) discover(ctx context.Context, issuer string) (transm
 }

 func (m *ConnectionManager) managementToken(ctx context.Context, client *http.Client, scopes string) (string, error) {
+	connection, err := m.repository.SecurityEventConnection(ctx)
+	if err != nil {
+		return "", err
+	}
+	managementClientID, managementSecret, err := m.managementCredential(ctx, connection)
+	if err != nil {
+		return "", err
+	}
+	defer clear(managementSecret)
 	form := url.Values{"grant_type": {"client_credentials"}, "scope": {scopes}}
 	request, err := http.NewRequestWithContext(ctx, http.MethodPost, strings.TrimRight(m.config.OIDCIssuer, "/")+"/token", strings.NewReader(form.Encode()))
 	if err != nil {
 		return "", err
 	}
-	request.SetBasicAuth(m.config.ManagementClientID, m.config.ManagementClientSecret)
+	request.SetBasicAuth(managementClientID, string(managementSecret))
 	request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 	response, err := client.Do(request)
 	if err != nil {
@@ -736,6 +820,24 @@ func (m *ConnectionManager) managementToken(ctx context.Context, client *http.Cl
 	return payload.AccessToken, nil
 }

+func (m *ConnectionManager) managementCredential(ctx context.Context, connection store.SecurityEventConnection) (string, []byte, error) {
+	if connection.ManagementCredentialRef != nil && connection.ManagementClientID != "" {
+		secret, err := m.secrets.Get(ctx, *connection.ManagementCredentialRef)
+		if err != nil {
+			return "", nil, err
+		}
+		if len(secret) < 16 {
+			clear(secret)
+			return "", nil, errors.New("managed machine credential is invalid")
+		}
+		return connection.ManagementClientID, secret, nil
+	}
+	if m.config.ManagementClientID != "" && m.config.ManagementClientSecret != "" {
+		return m.config.ManagementClientID, []byte(m.config.ManagementClientSecret), nil
+	}
+	return "", nil, errors.New("managed machine credential is unavailable")
+}
+
 func (m *ConnectionManager) findStream(ctx context.Context, client *http.Client, configuration transmitterConfiguration, token, description, endpoint string) (streamConfiguration, error) {
 	var streams []streamConfiguration
 	if err := requestJSON(ctx, client, http.MethodGet, configuration.ConfigurationEndpoint, token, nil, &streams); err != nil {
@@ -789,11 +891,18 @@ func (m *ConnectionManager) view(connection store.SecurityEventConnection) Conne
 		ConnectionID: connection.ConnectionID, TransmitterIssuer: connection.TransmitterIssuer,
 		ReceiverEndpoint: connection.EndpointURL, Audience: connection.Audience, StreamID: connection.StreamID,
 		LifecycleStatus: connection.LifecycleStatus, HealthMode: connection.HealthMode,
-		ManagementClientID: m.config.ManagementClientID, LastVerificationAt: connection.LastVerificationAt,
+		ManagementClientID: managementClientIDForView(connection.ManagementClientID, m.config.ManagementClientID), LastVerificationAt: connection.LastVerificationAt,
 		LastErrorCategory: connection.LastErrorCategory, Version: connection.Version,
 	}
 }

+func managementClientIDForView(managed, fallback string) string {
+	if strings.TrimSpace(managed) != "" {
+		return managed
+	}
+	return fallback
+}
+
 func validateCreatedStream(stream streamConfiguration, issuer, endpoint string) error {
 	if _, err := uuid.Parse(stream.StreamID); err != nil || stream.Issuer != issuer || stream.Audience == "" ||
 		stream.Delivery.Method != pushDeliveryMethod || stream.Delivery.EndpointURL != endpoint ||