core/server/store/api_token_iface.go

package store

import (
	"context"

	"armature/models"
)

// APITokenStore manages personal access tokens for programmatic API access.
type APITokenStore interface {
	// Create inserts a new API token. The token_hash must be a SHA-256 hash
	// of the raw token string. ID and CreatedAt are set by the implementation.
	Create(ctx context.Context, token *models.APIToken) error

	// GetByHash retrieves a non-expired token by its SHA-256 hash.
	// Returns nil, nil if not found or expired.
	GetByHash(ctx context.Context, tokenHash string) (*models.APIToken, error)

	// ListForUser returns all tokens belonging to a user, ordered by created_at DESC.
	ListForUser(ctx context.Context, userID string) ([]models.APIToken, error)

	// Revoke deletes a token owned by the specified user.
	// Returns the number of rows affected (0 if not found or not owned).
	Revoke(ctx context.Context, id, userID string) (int64, error)

	// RevokeByID deletes a token by ID regardless of owner (admin use).
	RevokeByID(ctx context.Context, id string) (int64, error)

	// CleanExpired deletes all tokens past their expires_at. Returns rows deleted.
	CleanExpired(ctx context.Context) (int64, error)

	// UpdateLastUsed sets last_used_at to now for the given token ID.
	UpdateLastUsed(ctx context.Context, id string) error
}