feat: add auth Identity model and Authenticator interface

Add the Identity type that represents an authenticated request,
context helpers for propagating identity through middleware,
the Authenticator interface for pluggable auth mechanisms,
and the ErrInvalidCredentials sentinel error.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Miguel Martín <mmartinv@redhat.com>

Author: mmartinv

internal/auth/authenticator.go

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: (C) 2026 Red Hat Inc.
+// SPDX-License-Identifier: Apache 2.0
+
+package auth
+
+import (
+	"context"
+	"net/http"
+)
+
+// Authenticator extracts and validates credentials from an HTTP request.
+//
+// Authenticate returns:
+//   - (*Identity, nil) on successful authentication
+//   - (nil, nil) when no credentials are present (the request is unauthenticated
+//     but another authenticator may handle it)
+//   - (nil, error) when credentials are present but invalid or an internal error occurs
+type Authenticator interface {
+	Name() string
+	Authenticate(ctx context.Context, r *http.Request) (*Identity, error)
+}

internal/auth/identity.go

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: (C) 2026 Red Hat Inc.
+// SPDX-License-Identifier: Apache 2.0
+
+package auth
+
+import (
+	"context"
+	"errors"
+)
+
+type contextKey struct{}
+
+var ErrInvalidCredentials = errors.New("invalid credentials")
+
+type Identity struct {
+	subject    string
+	name       string
+	authMethod string
+	roles      []string
+	scopes     []string
+	metadata   map[string]string
+}
+
+func NewIdentity(subject, name, authMethod string, roles, scopes []string, metadata map[string]string) *Identity {
+	id := &Identity{
+		subject:    subject,
+		name:       name,
+		authMethod: authMethod,
+	}
+	if roles != nil {
+		id.roles = make([]string, len(roles))
+		copy(id.roles, roles)
+	}
+	if scopes != nil {
+		id.scopes = make([]string, len(scopes))
+		copy(id.scopes, scopes)
+	}
+	if metadata != nil {
+		id.metadata = make(map[string]string, len(metadata))
+		for k, v := range metadata {
+			id.metadata[k] = v
+		}
+	}
+	return id
+}
+
+func (i *Identity) Subject() string    { return i.subject }
+func (i *Identity) Name() string       { return i.name }
+func (i *Identity) AuthMethod() string { return i.authMethod }
+
+func (i *Identity) Roles() []string {
+	out := make([]string, len(i.roles))
+	copy(out, i.roles)
+	return out
+}
+
+func (i *Identity) Scopes() []string {
+	out := make([]string, len(i.scopes))
+	copy(out, i.scopes)
+	return out
+}
+
+func (i *Identity) Metadata() map[string]string {
+	out := make(map[string]string, len(i.metadata))
+	for k, v := range i.metadata {
+		out[k] = v
+	}
+	return out
+}
+
+func (i *Identity) HasAllScopes(required []string) bool {
+	if len(required) == 0 {
+		return true
+	}
+	if i == nil || len(i.scopes) < len(required) {
+		return false
+	}
+	have := make(map[string]struct{}, len(i.scopes))
+	for _, s := range i.scopes {
+		have[s] = struct{}{}
+	}
+	for _, r := range required {
+		if _, ok := have[r]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+func ContextWithIdentity(ctx context.Context, id *Identity) context.Context {
+	if id == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, contextKey{}, id)
+}
+
+// IdentityFromContext retrieves the authenticated identity from the context.
+// Returns (nil, false) when no identity is present.
+func IdentityFromContext(ctx context.Context) (*Identity, bool) {
+	id, ok := ctx.Value(contextKey{}).(*Identity)
+	return id, ok
+}

internal/auth/identity_test.go

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: (C) 2026 Red Hat Inc.
+// SPDX-License-Identifier: Apache 2.0
+
+package auth
+
+import (
+	"context"
+	"testing"
+)
+
+func TestHasAllScopes(t *testing.T) {
+	id := NewIdentity("", "", "", nil, []string{"vouchers:read", "vouchers:write", "vouchers:delete", "device-ca:read"}, nil)
+
+	tests := []struct {
+		name     string
+		required []string
+		want     bool
+	}{
+		{"single present scope", []string{"vouchers:read"}, true},
+		{"multiple present scopes", []string{"vouchers:read", "vouchers:write"}, true},
+		{"all present scopes", []string{"vouchers:delete"}, true},
+		{"missing scope", []string{"vouchers:extend"}, false},
+		{"one present one missing", []string{"vouchers:read", "vouchers:extend"}, false},
+		{"nil required", nil, true},
+		{"empty required", []string{}, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := id.HasAllScopes(tt.required)
+			if got != tt.want {
+				t.Errorf("HasAllScopes(%v) = %v, want %v", tt.required, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIdentityContext(t *testing.T) {
+	id := NewIdentity("user-123", "admin", "", nil, nil, nil)
+	ctx := ContextWithIdentity(context.Background(), id)
+
+	found, ok := IdentityFromContext(ctx)
+	if !ok || found == nil {
+		t.Fatal("expected identity in context, got nil")
+	}
+	if found.Subject() != "user-123" {
+		t.Errorf("expected subject 'user-123', got %q", found.Subject())
+	}
+
+	empty, ok := IdentityFromContext(context.Background())
+	if ok || empty != nil {
+		t.Errorf("expected no identity from empty context, got %v", empty)
+	}
+
+	nilCtx := ContextWithIdentity(context.Background(), nil)
+	nilID, nilOK := IdentityFromContext(nilCtx)
+	if nilOK || nilID != nil {
+		t.Errorf("expected (nil, false) after storing nil identity, got (%v, %v)", nilID, nilOK)
+	}
+}