Enhance documentation and add new features: Updated README with new modules including WebAuthn, magic link, and consent management. Expanded ROADMAP with completed security and auth extensions. Introduced OAuth2 scopes in claims and session metadata structure for improved session management.

Author: ahmetbilgay

README.md

@@ -13,20 +13,34 @@ Core modules: `auth`, `tenant`, `permission`, and `storage` — JWT-based authen
 ## Modules
 
 - `auth`: JWT service, guards, middleware adapters
-- `auth/mfa`: 2FA/MFA TOTP (pquerna/otp)
+- `auth/mfa`: 2FA/MFA TOTP (pquerna/otp), recovery codes
 - `auth/apikey`: API key validation
+- `auth/webauthn`: WebAuthn/Passkeys (build with `-tags webauthn`)
+- `auth/magiclink`: magic link / email OTP
+- `auth/blacklist`: JWT blacklist for immediate revoke
+- `auth/ipfilter`: IP allowlist/blocklist
+- `auth/oauth2provider`: OAuth2 authorization server
+- `auth/scopes`: OAuth2 scope checks in claims
 - `auth/tenantsql`: tenant filter helpers
 - `tenant`: tenant selection, override policy, lifecycle (create/suspend/delete)
+- `tenant/features`: tenant-level feature flags, plan limits
 - `permission`: permission check service
+- `permission/abac`: ABAC conditions (resource owner, department, environment)
 - `social`: social login callback and account linking
 - `social/providers/google`: Google OIDC
 - `social/providers/github`: GitHub OAuth
+- `consent`: OAuth2 consent management
+- `saml`: SAML 2.0 SSO
+- `ldap`: LDAP/Active Directory auth
+- `webhooks`: event webhooks (user.created, session.revoked, etc.)
+- `config`: config validation helpers
 - `storage`: DB adapter interfaces
 - `storage/memory`: in-memory adapters for quick start
 - `storage/postgres`: Postgres adapter (SessionStore, RefreshStore)
 - `storage/redis`: Redis adapter (SessionStore, RefreshStore)
 - `observability/logging`: structured logging (dev/prod)
 - `observability/metrics`: Prometheus metrics
+- `observability/audit`: audit log search and export (JSON, CSV)
 - `observability/tracing`: OpenTelemetry-compatible tracing
 - `admin`: optional admin panel (tenants, permissions, sessions) mountable at any URL
 
@@ -37,6 +51,7 @@ Core modules: `auth`, `tenant`, `permission`, and `storage` — JWT-based authen
 - `gin`
 - `echo`
 - `fiber`
+- `graphql` (auth adapter for GraphQL resolvers)
 
 ## Goal
 

ROADMAP.md

@@ -14,14 +14,37 @@ The library provides a solid foundation. Priority gaps for production:
 ## P1 - Multi-tenant Runtime
 
 - Tenant lifecycle API (done)
-- Tenant-level feature flags and plan/policy binding
+- Tenant-level feature flags and plan/policy binding (done)
 - Permission wildcard support (done)
-- ABAC conditions (resource owner, department, environment)
+- ABAC conditions (resource owner, department, environment) (done)
 
 ## P2 - DX and Operations
 
-- Config validation package extensions (strict mode)
+- Config validation package extensions (strict mode) (done)
 - OpenTelemetry tracing hooks (done)
 - Prometheus metrics (done)
 - Migration-ready SQL adapter packages - postgres (done)
 - Versioned changelog + release automation (done)
+
+## P2 - Security & Auth Extensions (done)
+
+- WebAuthn/Passkeys
+- Magic link / Email OTP
+- MFA recovery codes
+- OAuth2 Provider mode
+- OAuth2 scopes in claims
+
+## P3 - Operations (done)
+
+- Session metadata (IP, user-agent, last activity)
+- Audit log search/export
+- IP allowlist/blocklist
+- JWT blacklist
+- Consent management
+
+## P4 - Enterprise & Integrations (done)
+
+- SAML 2.0
+- LDAP/Active Directory
+- Webhook events
+- GraphQL adapter

auth/adapters/graphql/middleware.go

@@ -0,0 +1,54 @@
+package graphql
+
+import (
+	"context"
+
+	"github.com/parevo/core/auth"
+	"github.com/parevo/core/auth/adapters"
+	"github.com/parevo/core/tenant"
+)
+
+// ResolverContext injects auth into GraphQL resolver context.
+type ResolverContext struct {
+	Auth   *auth.Service
+	Tenant *tenant.Service
+	Opts   adapters.Options
+}
+
+// NewResolverContext creates a resolver context helper.
+func NewResolverContext(authSvc *auth.Service, tenantSvc *tenant.Service, opts adapters.Options) *ResolverContext {
+	opts = opts.WithDefaults()
+	return &ResolverContext{Auth: authSvc, Tenant: tenantSvc, Opts: opts}
+}
+
+// AuthenticateRequest authenticates the request and returns a context with claims.
+// Call this at the start of your GraphQL request handler (e.g. in the middleware before graphql.Execute).
+func (r *ResolverContext) AuthenticateRequest(ctx context.Context, authHeader, tenantID string) (context.Context, error) {
+	policy := r.Opts.OverridePolicy
+	if policy == nil {
+		policy = auth.StaticTenantOverridePolicy{Allow: false}
+	}
+	newCtx, _, err := r.Auth.AuthenticateContext(ctx, authHeader, tenantID, policy)
+	return newCtx, err
+}
+
+// RequireAuth returns an error if the context has no valid claims.
+func RequireAuth(ctx context.Context) error {
+	_, ok := auth.ClaimsFromContext(ctx)
+	if !ok {
+		return auth.ErrUnauthenticated
+	}
+	return nil
+}
+
+// RequireScope returns an error if claims don't have the required scope.
+func RequireScope(ctx context.Context, scope string) error {
+	claims, ok := auth.ClaimsFromContext(ctx)
+	if !ok {
+		return auth.ErrUnauthenticated
+	}
+	if !auth.HasScope(claims, scope) {
+		return auth.ErrForbidden
+	}
+	return nil
+}

auth/adapters/graphql/middleware_test.go

@@ -0,0 +1,59 @@
+package graphql
+
+import (
+	"context"
+	"testing"
+
+	"github.com/parevo/core/auth"
+	"github.com/parevo/core/auth/adapters"
+	"github.com/parevo/core/tenant"
+)
+
+func TestRequireAuth(t *testing.T) {
+	ctx := context.Background()
+
+	if err := RequireAuth(ctx); err != auth.ErrUnauthenticated {
+		t.Errorf("empty context should fail: %v", err)
+	}
+
+	ctx = auth.WithClaims(ctx, &auth.Claims{UserID: "u1"})
+	if err := RequireAuth(ctx); err != nil {
+		t.Errorf("context with claims should pass: %v", err)
+	}
+}
+
+func TestRequireScope(t *testing.T) {
+	ctx := context.Background()
+
+	if err := RequireScope(ctx, "read:orders"); err != auth.ErrUnauthenticated {
+		t.Errorf("empty context should fail: %v", err)
+	}
+
+	ctx = auth.WithClaims(ctx, &auth.Claims{UserID: "u1", Scopes: []string{"read:*"}})
+	if err := RequireScope(ctx, "read:orders"); err != nil {
+		t.Errorf("matching scope should pass: %v", err)
+	}
+
+	ctx = auth.WithClaims(ctx, &auth.Claims{UserID: "u1", Scopes: []string{"read:orders"}})
+	if err := RequireScope(ctx, "write:users"); err != auth.ErrForbidden {
+		t.Errorf("missing scope should fail: %v", err)
+	}
+}
+
+func TestResolverContext_AuthenticateRequest(t *testing.T) {
+	authSvc, _ := auth.NewService(auth.Config{
+		Issuer:    "test",
+		Audience:  "test",
+		SecretKey: []byte("super-secret-key-at-least-32-bytes"),
+	})
+	rc := NewResolverContext(authSvc, &tenant.Service{}, adapters.Options{})
+
+	token, _ := authSvc.IssueAccessToken(auth.Claims{UserID: "u1", TenantID: "t1"})
+	ctx, err := rc.AuthenticateRequest(context.Background(), "Bearer "+token, "t1")
+	if err != nil {
+		t.Fatalf("AuthenticateRequest failed: %v", err)
+	}
+	if _, ok := auth.ClaimsFromContext(ctx); !ok {
+		t.Error("context should have claims")
+	}
+}

auth/blacklist/blacklist.go

@@ -0,0 +1,47 @@
+package blacklist
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+var ErrTokenBlacklisted = errors.New("token is blacklisted")
+
+// Store persists blacklisted JWT IDs (jti) or token hashes.
+type Store interface {
+	Add(ctx context.Context, jtiOrHash string, expiresAt time.Time) error
+	Contains(ctx context.Context, jtiOrHash string) (bool, error)
+}
+
+// Service provides JWT blacklist for immediate revoke (logout).
+type Service struct {
+	store Store
+}
+
+// NewService creates a blacklist service.
+func NewService(store Store) *Service {
+	return &Service{store: store}
+}
+
+// Revoke adds a token to the blacklist until it expires.
+func (s *Service) Revoke(ctx context.Context, jtiOrHash string, expiresAt time.Time) error {
+	return s.store.Add(ctx, jtiOrHash, expiresAt)
+}
+
+// IsBlacklisted returns true if the token should be rejected.
+func (s *Service) IsBlacklisted(ctx context.Context, jtiOrHash string) (bool, error) {
+	return s.store.Contains(ctx, jtiOrHash)
+}
+
+// Check returns ErrTokenBlacklisted if the token is blacklisted.
+func (s *Service) Check(ctx context.Context, jtiOrHash string) error {
+	ok, err := s.IsBlacklisted(ctx, jtiOrHash)
+	if err != nil {
+		return err
+	}
+	if ok {
+		return ErrTokenBlacklisted
+	}
+	return nil
+}

auth/blacklist/blacklist_test.go

@@ -0,0 +1,49 @@
+package blacklist
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/parevo/core/storage/memory"
+)
+
+func TestBlacklist_RevokeAndCheck(t *testing.T) {
+	store := memory.NewBlacklistStore()
+	svc := NewService(store)
+	ctx := context.Background()
+
+	expiresAt := time.Now().Add(time.Hour)
+	if err := svc.Revoke(ctx, "jti-123", expiresAt); err != nil {
+		t.Fatalf("Revoke failed: %v", err)
+	}
+
+	ok, err := svc.IsBlacklisted(ctx, "jti-123")
+	if err != nil {
+		t.Fatalf("IsBlacklisted failed: %v", err)
+	}
+	if !ok {
+		t.Error("token should be blacklisted")
+	}
+
+	if err := svc.Check(ctx, "jti-123"); err != ErrTokenBlacklisted {
+		t.Errorf("Check should return ErrTokenBlacklisted: %v", err)
+	}
+}
+
+func TestBlacklist_NotBlacklisted(t *testing.T) {
+	svc := NewService(memory.NewBlacklistStore())
+	ctx := context.Background()
+
+	ok, err := svc.IsBlacklisted(ctx, "unknown")
+	if err != nil {
+		t.Fatalf("IsBlacklisted failed: %v", err)
+	}
+	if ok {
+		t.Error("unknown token should not be blacklisted")
+	}
+
+	if err := svc.Check(ctx, "unknown"); err != nil {
+		t.Errorf("Check should pass for non-blacklisted: %v", err)
+	}
+}

auth/claims.go

@@ -7,6 +7,7 @@ type Claims struct {
 	TenantID    string   `json:"tenant_id"`
 	Roles       []string `json:"roles,omitempty"`
 	Permissions []string `json:"permissions,omitempty"`
+	Scopes      []string `json:"scope,omitempty"` // OAuth2 scopes, e.g. "read:orders write:users"
 	SessionID   string   `json:"session_id,omitempty"`
 	TokenType   string   `json:"typ,omitempty"`
 	jwt.RegisteredClaims

auth/ipfilter/ipfilter.go

@@ -0,0 +1,56 @@
+package ipfilter
+
+import (
+	"context"
+	"errors"
+	"net"
+)
+
+var (
+	ErrIPBlocked = errors.New("IP address blocked")
+	ErrIPNotAllowed = errors.New("IP address not in allowlist")
+)
+
+// Store provides IP allowlist/blocklist per tenant or global.
+type Store interface {
+	IsAllowed(ctx context.Context, tenantID, ip string) (bool, error)
+	IsBlocked(ctx context.Context, tenantID, ip string) (bool, error)
+}
+
+// Service checks IP against allow/block lists.
+type Service struct {
+	store     Store
+	allowMode bool // true: allowlist (deny by default), false: blocklist (allow by default)
+}
+
+// NewService creates an IP filter service.
+func NewService(store Store, allowlistMode bool) *Service {
+	return &Service{store: store, allowMode: allowlistMode}
+}
+
+// Allow returns nil if the IP is allowed.
+func (s *Service) Allow(ctx context.Context, tenantID, ip string) error {
+	if ip == "" {
+		return nil
+	}
+	if net.ParseIP(ip) == nil {
+		return nil
+	}
+	blocked, err := s.store.IsBlocked(ctx, tenantID, ip)
+	if err != nil {
+		return err
+	}
+	if blocked {
+		return ErrIPBlocked
+	}
+	if s.allowMode {
+		allowed, err := s.store.IsAllowed(ctx, tenantID, ip)
+		if err != nil {
+			return err
+		}
+		if !allowed {
+			return ErrIPNotAllowed
+		}
+	}
+	return nil
+}