auth

type Grant struct {
	// ID is the opaque identifier stored in the httpOnly cookie.
	ID string
	// FamilyID groups rotated grants for logout-all semantics.
	FamilyID string

	// Subject identifies the authenticated principal (e.g., user id or account id).
	Subject string
	// Scopes or roles associated with this grant (optional).
	Scopes []string

	// CreatedAt is when the grant was issued.
	CreatedAt time.Time
	// LastUsedAt is updated on use (for sliding TTL logic).
	LastUsedAt time.Time
	// ExpiresAt is the idle expiration time (sliding TTL).
	ExpiresAt time.Time
	// MaxExpiresAt is the absolute expiration cap.
	MaxExpiresAt time.Time

	// Device binding hints (optional; tolerant matching recommended).
	UAHash string
	IPHint string

	// Arbitrary metadata to support implementers (optional).
	Meta map[string]string
}

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

type Store interface {
	// Put inserts or updates a grant. Implementations may enforce TTLs based on grant fields.
	Put(ctx context.Context, g *Grant) error

	// Get retrieves a grant by id. Should return ErrNotFound if missing or expired.
	Get(ctx context.Context, id string) (*Grant, error)

	// Touch updates last-used timestamp and extends idle expiry (sliding TTL) as appropriate.
	Touch(ctx context.Context, id string, at time.Time) error

	// Rotate atomically replaces an existing grant id with a new one.
	// Returns the new id; implementations may keep the old id valid for a short grace window.
	Rotate(ctx context.Context, oldID string, newGrant *Grant) (string, error)

	// Revoke deletes a specific grant id immediately.
	Revoke(ctx context.Context, id string) error

	// RevokeFamily deletes all grants in the same family (logout-all across devices/tabs).
	RevokeFamily(ctx context.Context, familyID string) error
}