refresh

type GCCollector interface {
	ObserveRefreshGC(ctx context.Context, result string, removed int, duration time.Duration)
}

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

type GCWorkerConfig struct {
	Store     Store
	Clock     clock.Clock
	Interval  time.Duration
	Retention time.Duration
	Logger    *slog.Logger
	Metrics   GCCollector
}

type NoopGCCollector struct{}

type Policy struct {
	ReuseInterval  time.Duration
	MaxAge         time.Duration
	MaxIdle        time.Duration
	GraceMaxReuses int
}

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

type Store interface {
	// Issue creates a new refresh chain for (sessionID, subjectID). The
	// Store generates an opaque wire token of the form
	// base64url(selector_16B) "." base64url(verifier_32B) and persists only
	// (selector, sha256(verifier)). Token.ExpiresAt = now + Policy.MaxAge.
	//
	// authzEpochAtIssue is the snapshot of users.authz_epoch at issue time;
	// it is persisted on the row and returned to validate paths so that
	// sessionrefresh can reject stale grants (S4d). Zero is invalid:
	// implementations return ErrValidationFailed (storetest conformance
	// T-S4D-2 enforces).
	//
	// Consistency: L1 LocalTx — single INSERT, no outbox event.
	Issue(ctx context.Context, sessionID, subjectID string, authzEpochAtIssue int64) (wire string, tok *Token, err error)

	// Peek validates the presented wire token and returns the metadata for the
	// currently-presented row without issuing a child and without flipping
	// rotated_at. Callers use this for no-side-effect preflight checks before
	// deciding whether to commit a rotation.
	//
	// Return shape matches the package-level vocabulary above:
	//   - valid token            → (*Token{SubjectID, SessionID, ...}, nil)
	//   - reuse detected         → (*Token{SubjectID, SessionID, ...}, ErrReused)
	//   - any other rejection    → (nil, ErrRejected)
	//
	// Implementations MUST still commit the per-session cascade-revoke before
	// returning ErrReused — that is a security response and persists
	// regardless of caller transaction outcome. The token returned alongside
	// ErrReused conveys *only* the row identity (SubjectID, SessionID, ID,
	// CreatedAt, ExpiresAt); it is not a usable refresh credential.
	//
	// Consistency: L1 LocalTx — read-only for valid tokens; reuse-detection
	// cascade revoke is committed before returning ErrReused.
	Peek(ctx context.Context, presentedWire string) (tok *Token, err error)

	// Rotate consumes the presented wire token and advances the chain by
	// issuing a new child. Returns the new wire token alongside its
	// metadata on success.
	//
	// Branches (return shape matches the package-level vocabulary):
	//
	//   - active happy path: presented token is the current live row →
	//     INSERT child, flip parent rotated_at, return new wire +
	//     (*Token{...}, nil).
	//   - grace retry: parent's rotated_at was already set but the retry
	//     arrived within Policy.ReuseInterval → INSERT another child,
	//     return a distinct new wire + (*Token{...}, nil). Preserves
	//     idempotency for SPA double-submit without weakening reuse
	//     detection.
	//   - reuse detection: parent's rotated_at was set beyond
	//     Policy.ReuseInterval, OR grace counter cap exhausted →
	//     cascade-revoke the entire session_id lineage, emit slog Error
	//     "reuse_detected", return ("", *Token{SubjectID, SessionID, ...},
	//     ErrReused). The token conveys row identity for the service-layer
	//     user-wide invalidation cascade.
	//   - malformed / unknown selector / verifier mismatch / expired /
	//     revoked: return ("", nil, ErrRejected) with corresponding slog
	//     "reason".
	//
	// Consistency: L1 LocalTx — INSERT child + UPDATE parent within one
	// transaction; reuse-detection cascade revoke is committed before
	// returning ErrReused.
	Rotate(ctx context.Context, presentedWire string) (wire string, tok *Token, err error)

	// RevokeSession marks every row in the session_id lineage as revoked.
	// Idempotent — 0 rows affected is not an error. Called by business flows
	// such as logout, where refresh-chain revoke must share the caller's
	// transaction boundary with session state and outbox writes.
	//
	// Consistency: L1 LocalTx — single UPDATE.
	RevokeSession(ctx context.Context, sessionID string) error

	// RevokeSessionDetached marks every row in the session_id lineage as
	// revoked outside the caller's ambient transaction/cancellation boundary.
	// It is reserved for security/compensation paths where the revoke must
	// persist even if the triggering request is canceled or the surrounding
	// business transaction rolls back.
	//
	// Consistency: L1 LocalTx — single UPDATE committed independently by
	// durable implementations. In-memory implementations may share the same
	// critical section as RevokeSession.
	RevokeSessionDetached(ctx context.Context, sessionID string) error

	// RevokeUser marks every row belonging to subjectID as revoked.
	// Called by user-delete, user-lock, and change-password flows to
	// invalidate every refresh chain owned by the subject in one atomic
	// statement. Idempotent. There is intentionally no detached RevokeUser:
	// these user-level revokes are business state transitions that must remain
	// atomic with user/session mutations and related outbox writes. Session-
	// level cascade revoke is split because it also serves security responses
	// to token reuse and compensating cleanup.
	//
	// Consistency: L1 LocalTx — single UPDATE.
	RevokeUser(ctx context.Context, subjectID string) error

	// GC removes rows whose effective expiry has passed olderThan. Effective
	// expiry is the earlier of expires_at (hard cap) and idle_expires_at
	// (sliding window driven by Policy.MaxIdle). Implementations MUST sweep on
	// the LEAST(expires_at, idle_expires_at) so an idle-abandoned chain is
	// reclaimed without waiting for the hard MaxAge horizon.
	//
	// Safe to run from a background worker; batched with SKIP LOCKED to avoid
	// contending with active Rotate traffic.
	//
	// Consistency: L0 LocalOnly — best-effort cleanup.
	GC(ctx context.Context, olderThan time.Time) (removed int, err error)
}

type Token struct {
	ID        uuid.UUID
	SessionID string
	SubjectID string
	CreatedAt time.Time
	ExpiresAt time.Time
	// AuthzEpochAtIssue snapshots users.authz_epoch at the moment this
	// refresh row was inserted (Issue / Rotate child). sessionrefresh rejects
	// a presented token whose AuthzEpochAtIssue != current users.authz_epoch
	// via an independent stale-epoch code path: the service's
	// rejectIfStaleEpoch runs in refreshInTx **before** calling Rotate,
	// detects the mismatch, and invokes `cascadeRevoke("stale-epoch")`
	// directly for a session-scoped revocation. This is separate from
	// handleReuseDetected, which is the reuse-attack cascade entry triggered
	// from Peek and Rotate (user-wide Invalidator.Apply). Without this
	// column, refresh re-mints access tokens with live user.epoch and stale
	// grants "upgrade" to current epoch (PR #490 review P1-#2).
	//
	// ADR-credential §A6 (stale-epoch path) + §A8 (row-level credential
	// provenance).
	AuthzEpochAtIssue int64
}