auth

type CacheOption struct {
	// TTL is how long a resolved identity stays in cache. 0 disables.
	TTL time.Duration

	// MaxEntries bounds the cache so a misbehaving client can't OOM
	// the app by sending many unique tokens. 0 means unbounded.
	MaxEntries int
}

type CachedIdentity struct {
	TokenPrefix string
	Identity    *Identity
	ExpiresAt   time.Time
}

type Config struct {
	// Extract pulls the raw token from the request. Defaults to Bearer()
	// (Authorization: Bearer <token>). Combine strategies with Chain.
	Extract Extractor

	// Resolve is REQUIRED — the function that turns a raw token into an
	// Identity. The package owns extraction, caching, and enforcement;
	// Resolve is the single plug the caller supplies.
	Resolve Resolver

	// Cache memoizes resolved identities so the backend call fires at
	// most once per TTL per token. Zero TTL disables caching entirely.
	Cache CacheOption

	// Permissions overrides the default roles+scopes check. Useful when
	// an app has a hierarchical role model or non-trivial scope matching.
	Permissions PermissionFn

	// OnResolve fires after every successful resolution — good for
	// audit logging or per-user metrics.
	OnResolve func(ctx context.Context, id *Identity)

	// OnFail fires on extraction / resolution failure. The token is
	// passed so handlers can log prefixes for diagnostics; do NOT log
	// the full token in production.
	OnFail func(ctx context.Context, token string, err error)

	// OnUnauthenticated customizes the REST 401 response. Default:
	// AbortWithStatusJSON(401, {"error": err.Error()}). Override to
	// match your app's error envelope (e.g. pkg.Response-style
	// success:false payload).
	//
	// The handler is responsible for calling c.Abort* — return without
	// aborting and auth falls back to its default 401 so a misconfigured
	// hook never accidentally authorizes a request.
	OnUnauthenticated func(c *gin.Context, err error)

	// OnForbidden customizes the REST 403 response. Same contract as
	// OnUnauthenticated.
	OnForbidden func(c *gin.Context, err error)

	// GraphQLErrorWrap transforms ErrUnauthenticated / ErrForbidden
	// before they're returned from a resolver. Default: pass through
	// so the standard "auth: unauthenticated" / "auth: forbidden"
	// messages appear in the GraphQL errors array. Override to wrap
	// in a typed error the client expects.
	GraphQLErrorWrap func(err error) error
}

type Extractor interface {
	Extract(r *http.Request) (string, bool)
}

type ExtractorFunc func(r *http.Request) (string, bool)

type Identity struct {
	ID     string
	Roles  []string
	Scopes []string
	Extra  any
}

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

type PermissionFn func(id *Identity, required []string) bool

type Resolver func(ctx context.Context, token string) (*Identity, error)