veza/veza-backend-api/internal/services/terms_service.go

package services

// TermsService — RGPD-compliant terms-acceptance ledger (v1.0.10 légal 3).
//
// Three document classes are tracked : CGU (terms of service), CGV
// (sales terms — for marketplace buyers/sellers), Mentions (legal
// mentions/impressum). The privacy notice (CookieBanner + the
// `/legal/privacy` page in v1.0.10 légal 1) intentionally has no
// "accept" button — privacy notice is informational, not contractual.
//
// Architecture :
//   - Current versions hardcoded as a struct constant in this file.
//     Bump the constants when the text changes ; next call to
//     NeedsAcceptance returns the unaccepted set.
//   - One row per (user, terms_type, version) ; UNIQUE index prevents
//     duplicate inserts on idempotent retries.
//   - The `/api/v1/legal/terms/accept` handler captures IP + UA at
//     accept time and writes them in the row — legal evidence.

import (
	"context"
	"errors"
	"time"

	"github.com/google/uuid"
	"go.uber.org/zap"
	"gorm.io/gorm"
)

// TermsType enumerates the document classes the platform tracks.
// Stored as VARCHAR (not enum) so adding a new class needs no schema
// migration ; just register it in `CurrentTerms` below.
type TermsType string

const (
	TermsTypeCGU      TermsType = "cgu"
	TermsTypeCGV      TermsType = "cgv"
	TermsTypeMentions TermsType = "mentions"
)

// CurrentTerms holds the live version label per document class.
// Convention : ISO publication date (YYYY-MM-DD). Bump when the text
// changes — every existing user will be force-re-prompted on their
// next session.
//
// Keep these aligned with what the frontend pages display. Drift here
// is the legal contradiction the migration was designed to prevent ;
// guard with the integration test in service_test if added later.
var CurrentTerms = map[TermsType]string{
	TermsTypeCGU:      "2026-04-30",
	TermsTypeCGV:      "2026-04-30",
	TermsTypeMentions: "2026-04-30",
}

// TermsAcceptance is the GORM model — one row per accepted document.
type TermsAcceptance struct {
	ID         uuid.UUID  `gorm:"type:uuid;primaryKey;default:gen_random_uuid()" json:"id"`
	UserID     uuid.UUID  `gorm:"type:uuid;not null;index:idx_terms_acceptances_user_doc_version,unique" json:"user_id"`
	TermsType  string     `gorm:"size:32;not null;index:idx_terms_acceptances_user_doc_version,unique;index:idx_terms_acceptances_doc_version" json:"terms_type"`
	Version    string     `gorm:"size:32;not null;index:idx_terms_acceptances_user_doc_version,unique;index:idx_terms_acceptances_doc_version" json:"version"`
	AcceptedAt time.Time  `gorm:"not null;default:now()" json:"accepted_at"`
	IPAddress  *string    `gorm:"type:inet" json:"ip_address,omitempty"`
	UserAgent  *string    `gorm:"size:512" json:"user_agent,omitempty"`
}

// TableName overrides GORM's default pluralisation — the migration
// uses the explicit name `terms_acceptances`.
func (TermsAcceptance) TableName() string { return "terms_acceptances" }

// TermsService writes acceptance ledger rows and answers
// "what's still unaccepted ?" queries.
type TermsService struct {
	db     *gorm.DB
	logger *zap.Logger
}

// NewTermsService constructs the service with the shared GORM handle
// and a structured logger.
func NewTermsService(db *gorm.DB, logger *zap.Logger) *TermsService {
	return &TermsService{db: db, logger: logger}
}

// CurrentVersionsResponse is the public shape returned by
// GET /api/v1/legal/terms/current. The Unaccepted slice is empty for
// guests + for users who have already accepted every current version.
type CurrentVersionsResponse struct {
	Versions   map[TermsType]string `json:"versions"`
	Unaccepted []TermsType          `json:"unaccepted,omitempty"`
}

// CurrentVersions returns the platform's currently-published versions
// and, when userID is non-zero, the list of document classes the user
// hasn't yet accepted at the current version.
func (s *TermsService) CurrentVersions(ctx context.Context, userID uuid.UUID) (*CurrentVersionsResponse, error) {
	resp := &CurrentVersionsResponse{
		Versions: make(map[TermsType]string, len(CurrentTerms)),
	}
	for k, v := range CurrentTerms {
		resp.Versions[k] = v
	}

	if userID == uuid.Nil {
		return resp, nil
	}

	// Pull every (terms_type, version) the user has accepted. Cheap:
	// 1-3 rows per user in steady state, indexed by user_id.
	type acceptedRow struct {
		TermsType string
		Version   string
	}
	var rows []acceptedRow
	if err := s.db.WithContext(ctx).
		Model(&TermsAcceptance{}).
		Where("user_id = ?", userID).
		Select("terms_type, version").
		Scan(&rows).Error; err != nil {
		return nil, err
	}

	accepted := make(map[TermsType]string, len(rows))
	for _, r := range rows {
		accepted[TermsType(r.TermsType)] = r.Version
	}

	for tt, current := range CurrentTerms {
		if accepted[tt] != current {
			resp.Unaccepted = append(resp.Unaccepted, tt)
		}
	}
	return resp, nil
}

// AcceptInput captures the per-document accept payload. The handler
// builds one of these per accepted class ; the service writes them
// in a single transaction for atomicity.
type AcceptInput struct {
	TermsType TermsType
	Version   string
	IPAddress *string
	UserAgent *string
}

// ErrTermsVersionMismatch is returned by Accept when the client
// supplies a version that doesn't match what the server considers
// current. Prevents stale-cache replays where a user clicks
// "accept" on yesterday's terms while today's are already published.
var ErrTermsVersionMismatch = errors.New("terms version mismatch — refresh the page and re-read the document")

// Accept records one or more terms acceptances for a user. Each
// (terms_type, version) is verified against CurrentTerms before
// insert ; mismatched submissions return ErrTermsVersionMismatch
// without writing anything. Idempotent — duplicate (user, type,
// version) tuples are absorbed by the unique index.
func (s *TermsService) Accept(ctx context.Context, userID uuid.UUID, inputs []AcceptInput) error {
	if userID == uuid.Nil {
		return errors.New("userID required")
	}
	if len(inputs) == 0 {
		return errors.New("no acceptances provided")
	}

	// Server-side authoritative version check : even if the SPA
	// thinks it's accepting current, only the server's CurrentTerms
	// definition matters.
	for _, in := range inputs {
		current, ok := CurrentTerms[in.TermsType]
		if !ok {
			return errors.New("unknown terms_type: " + string(in.TermsType))
		}
		if in.Version != current {
			s.logger.Warn("Terms accept rejected: version mismatch",
				zap.String("user_id", userID.String()),
				zap.String("terms_type", string(in.TermsType)),
				zap.String("submitted", in.Version),
				zap.String("current", current),
			)
			return ErrTermsVersionMismatch
		}
	}

	// Single transaction so a partial failure leaves no half-state.
	rows := make([]TermsAcceptance, 0, len(inputs))
	now := time.Now().UTC()
	for _, in := range inputs {
		rows = append(rows, TermsAcceptance{
			UserID:     userID,
			TermsType:  string(in.TermsType),
			Version:    in.Version,
			AcceptedAt: now,
			IPAddress:  in.IPAddress,
			UserAgent:  in.UserAgent,
		})
	}

	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
		// `OnConflict DO NOTHING` makes the call idempotent : if the
		// user already accepted this exact (type, version), we just
		// no-op rather than 500 on a unique-violation. GORM doesn't
		// expose ON CONFLICT directly across all dialects ; we use
		// the Clause() form so this stays Postgres-friendly.
		// The unique index on (user_id, terms_type, version) is what
		// the conflict resolution targets.
		for _, row := range rows {
			if err := tx.
				Where("user_id = ? AND terms_type = ? AND version = ?",
					row.UserID, row.TermsType, row.Version).
				FirstOrCreate(&row).Error; err != nil {
				return err
			}
		}
		s.logger.Info("Terms acceptances recorded",
			zap.String("user_id", userID.String()),
			zap.Int("count", len(rows)),
		)
		return nil
	})
}