security-rbac-auth

name	security-rbac-auth
description	Implement authentication, authorization, and security controls. Use for JWT handling, API key management, RBAC, OAuth integration, and security policies. Triggers on "authentication", "authorization", "JWT", "API key", "RBAC", "OAuth", "security", "permissions", or when implementing spec/006-security-governance.md.

Security, RBAC, and Authentication

Overview

Implement comprehensive security for AgentStack including authentication (JWT, API Keys, OAuth), authorization (RBAC), and security controls (encryption, audit logging, secret management).

Security Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Security Stack                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    PERIMETER                              │  │
│  │  TLS 1.3 │ Rate Limiting │ CORS │ WAF                     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                           │                                     │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                 AUTHENTICATION                            │  │
│  │  JWT (RS256) │ API Keys │ OAuth 2.0 │ OIDC                │  │
│  └──────────────────────────────────────────────────────────┘  │
│                           │                                     │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                 AUTHORIZATION                             │  │
│  │  RBAC │ Project Scoping │ Resource Policies               │  │
│  └──────────────────────────────────────────────────────────┘  │
│                           │                                     │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                 DATA PROTECTION                           │  │
│  │  Encryption at Rest │ Secrets │ PII Masking               │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

JWT Authentication

JWT Structure

// internal/auth/jwt/claims.go
package jwt

import (
    "time"
    
    "github.com/golang-jwt/jwt/v5"
)

type Claims struct {
    jwt.RegisteredClaims
    
    // User identity
    UserID string `json:"sub"`
    Email  string `json:"email"`
    
    // Organization context
    OrgID     string   `json:"org_id"`
    ProjectID string   `json:"project_id,omitempty"`
    TeamIDs   []string `json:"teams,omitempty"`
    
    // Permissions
    Permissions []string `json:"permissions"`
    Roles       []string `json:"roles"`
}

func NewClaims(user *User, org *Organization) *Claims {
    now := time.Now()
    return &Claims{
        RegisteredClaims: jwt.RegisteredClaims{
            Issuer:    "https://auth.agentstack.io",
            Audience:  jwt.ClaimStrings{"https://api.agentstack.io"},
            Subject:   user.ID,
            IssuedAt:  jwt.NewNumericDate(now),
            ExpiresAt: jwt.NewNumericDate(now.Add(1 * time.Hour)),
            NotBefore: jwt.NewNumericDate(now),
            ID:        uuid.NewString(),
        },
        UserID:      user.ID,
        Email:       user.Email,
        OrgID:       org.ID,
        TeamIDs:     user.TeamIDs,
        Permissions: user.GetPermissions(org),
        Roles:       user.GetRoles(org),
    }
}

JWT Service

// internal/auth/jwt/service.go
package jwt

import (
    "crypto/rsa"
    "fmt"
    "time"
    
    "github.com/golang-jwt/jwt/v5"
)

type Service struct {
    privateKey *rsa.PrivateKey
    publicKey  *rsa.PublicKey
    keyID      string
}

func NewService(privateKeyPEM, publicKeyPEM []byte, keyID string) (*Service, error) {
    privateKey, err := jwt.ParseRSAPrivateKeyFromPEM(privateKeyPEM)
    if err != nil {
        return nil, fmt.Errorf("parse private key: %w", err)
    }
    
    publicKey, err := jwt.ParseRSAPublicKeyFromPEM(publicKeyPEM)
    if err != nil {
        return nil, fmt.Errorf("parse public key: %w", err)
    }
    
    return &Service{
        privateKey: privateKey,
        publicKey:  publicKey,
        keyID:      keyID,
    }, nil
}

func (s *Service) GenerateToken(claims *Claims) (string, error) {
    token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
    token.Header["kid"] = s.keyID
    
    return token.SignedString(s.privateKey)
}

func (s *Service) ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) ({}, ) {
         _, ok := token.Method.(*jwt.SigningMethodRSA); !ok {
             , fmt.Errorf(, token.Header[])
        }
         s.publicKey, 
    })
    
     err !=  {
         , err
    }
    
    claims, ok := token.Claims.(*Claims)
     !ok || !token.Valid {
         , fmt.Errorf()
    }
    
     claims, 
}


 GenerateRefreshToken(userID ) (, ) {
    claims := &jwt.RegisteredClaims{
        Subject:   userID,
        ExpiresAt: jwt.NewNumericDate(time.Now().Add( *  * time.Hour)),
        IssuedAt:  jwt.NewNumericDate(time.Now()),
        ID:        uuid.NewString(),
    }
    
    token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
     token.SignedString(s.privateKey)
}

Auth Middleware

// internal/api/middleware/auth.go
package middleware

import (
    "context"
    "strings"
    
    "github.com/gofiber/fiber/v2"
)

type contextKey string

const (
    UserContextKey   contextKey = "user"
    ClaimsContextKey contextKey = "claims"
)

func JWTAuth(jwtService *jwt.Service) fiber.Handler {
    return func(c *fiber.Ctx) error {
        authHeader := c.Get("Authorization")
        if authHeader == "" {
            return c.Status(401).JSON(fiber.Map{
                "error": "missing authorization header",
            })
        }
        
        parts := strings.SplitN(authHeader, " ", 2)
        if len(parts) != 2 || parts[0] != "Bearer" {
            return c.Status(401).JSON(fiber.Map{
                "error": "invalid authorization format",
            })
        }
        
        claims, err := jwtService.ValidateToken(parts[1])
        if err != nil {
            return c.Status(401).JSON(fiber.Map{
                "error": "invalid token",
            })
        }
        
        // Add claims to context
        c.Locals((ClaimsContextKey), claims)
        
         c.Next()
    }
}

 *jwt.Claims {
    claims, _ := c.Locals((ClaimsContextKey)).(*jwt.Claims)
     claims
}

API Key Authentication

API Key Structure

// internal/auth/apikey/key.go
package apikey

import (
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "strings"
)

const (
    Prefix    = "ask_"  // AgentStack Key
    KeyLength = 32      // bytes
)

type APIKey struct {
    ID           string
    Prefix       string    // "ask_"
    Hash         string    // SHA-256 hash of full key
    ProjectID    string
    OrgID        string
    Name         string
    Permissions  []string
    LastUsedAt   *time.Time
    ExpiresAt    *time.Time
    CreatedAt    time.Time
}

// Generate creates a new API key and returns the full key (shown once)
func Generate(projectID, orgID, name string, permissions []string) (*APIKey, string, error) {
    // Generate random bytes
    randomBytes := make([]byte, KeyLength)
    if _, err := rand.Read(randomBytes); err != nil {
        return nil, "", err
    }
    
    // Encode to base62-like string
    keyBody := base64.RawURLEncoding.EncodeToString(randomBytes)
    fullKey := Prefix + keyBody
    
    // Hash for storage (never store plaintext)
    hash := sha256.Sum256([]byte(fullKey))
    hashStr := fmt.Sprintf(, hash)
    
    key := &APIKey{
        ID:          uuid.NewString(),
        Prefix:      fullKey[:(Prefix)+], 
        Hash:        hashStr,
        ProjectID:   projectID,
        OrgID:       orgID,
        Name:        name,
        Permissions: permissions,
        CreatedAt:   time.Now(),
    }
    
     key, fullKey, 
}


 Verify(providedKey )  {
    hash := sha256.Sum256([](providedKey))
     fmt.Sprintf(, hash) == k.Hash
}

API Key Middleware

// internal/api/middleware/apikey.go
package middleware

func APIKeyAuth(keyRepo apikey.Repository) fiber.Handler {
    return func(c *fiber.Ctx) error {
        // Check X-API-Key header
        apiKey := c.Get("X-API-Key")
        if apiKey == "" {
            // Also check Authorization header
            authHeader := c.Get("Authorization")
            if strings.HasPrefix(authHeader, "Bearer ask_") {
                apiKey = strings.TrimPrefix(authHeader, "Bearer ")
            }
        }
        
        if apiKey == "" {
            return c.Status(401).JSON(fiber.Map{
                "error": "missing API key",
            })
        }
        
        // Validate prefix
        if !strings.HasPrefix(apiKey, apikey.Prefix) {
            return c.Status(401).JSON(fiber.Map{
                "error": "invalid API key format",
            })
        }
        
        // Look up key by prefix (first 8 chars)
        prefix := apiKey[:len(apikey.Prefix)+4]
        key, err := keyRepo.FindByPrefix(c.Context(), prefix)
        if err != nil {
            return c.Status(401).JSON(fiber.Map{
                "error": "invalid API key",
            })
        }
        
        // Verify full key
         !key.Verify(apiKey) {
             c.Status().JSON(fiber.Map{
                : ,
            })
        }
        
        
         key.ExpiresAt !=  && key.ExpiresAt.Before(time.Now()) {
             c.Status().JSON(fiber.Map{
                : ,
            })
        }
        
        
         keyRepo.UpdateLastUsed(context.Background(), key.ID)
        
        
        c.Locals(, key)
        c.Locals(, key.OrgID)
        c.Locals(, key.ProjectID)
        c.Locals(, key.Permissions)
        
         c.Next()
    }
}

RBAC Authorization

Role Definitions

// internal/auth/rbac/roles.go
package rbac

type Role string

const (
    // Platform level
    RolePlatformAdmin Role = "platform:admin"
    
    // Organization level
    RoleOrgOwner  Role = "org:owner"
    RoleOrgAdmin  Role = "org:admin"
    RoleOrgMember Role = "org:member"
    
    // Project level
    RoleProjectAdmin     Role = "project:admin"
    RoleProjectDeveloper Role = "project:developer"
    RoleProjectViewer    Role = "project:viewer"
)

type Permission string

const (
    // Agent permissions
    PermAgentsRead   Permission = "agents:read"
    PermAgentsWrite  Permission = "agents:write"
    PermAgentsDelete Permission = "agents:delete"
    PermAgentsDeploy Permission = "agents:deploy"
    
    // Secret permissions
    PermSecretsRead  Permission = "secrets:read"
    PermSecretsWrite Permission = "secrets:write"
    
    // Project permissions
    PermProjectRead   Permission = "project:read"
    PermProjectWrite  Permission = "project:write"
    PermProjectDelete Permission = "project:delete"
    
    // Team permissions
    PermTeamManage Permission = "team:manage"
    
    // Billing
    PermBillingManage Permission = "billing:manage"
)

// RolePermissions maps roles to their permissions
var RolePermissions = map[Role][]Permission{
    RolePlatformAdmin: {
        PermAgentsRead, PermAgentsWrite, PermAgentsDelete, PermAgentsDeploy,
        PermSecretsRead, PermSecretsWrite,
        PermProjectRead, PermProjectWrite, PermProjectDelete,
        PermTeamManage, PermBillingManage,
    },
    RoleOrgOwner: {
        PermAgentsRead, PermAgentsWrite, PermAgentsDelete, PermAgentsDeploy,
        PermSecretsRead, PermSecretsWrite,
        PermProjectRead, PermProjectWrite, PermProjectDelete,
        PermTeamManage, PermBillingManage,
    },
    RoleOrgAdmin: {
        PermAgentsRead, PermAgentsWrite, PermAgentsDelete, PermAgentsDeploy,
        PermSecretsRead, PermSecretsWrite,
        PermProjectRead, PermProjectWrite,
        PermTeamManage,
    },
    RoleProjectDeveloper: {
        PermAgentsRead, PermAgentsWrite, PermAgentsDeploy,
        PermSecretsRead,
        PermProjectRead,
    },
    RoleProjectViewer: {
        PermAgentsRead,
        PermProjectRead,
    },
}

Authorization Middleware

// internal/api/middleware/authorize.go
package middleware

import (
    "github.com/gofiber/fiber/v2"
)

// RequirePermission checks if user has the required permission
func RequirePermission(permission rbac.Permission) fiber.Handler {
    return func(c *fiber.Ctx) error {
        claims := ClaimsFromContext(c)
        if claims == nil {
            // Check API key permissions
            perms, _ := c.Locals("permissions").([]string)
            if !hasPermission(perms, string(permission)) {
                return c.Status(403).JSON(fiber.Map{
                    "error":   "forbidden",
                    "message": "insufficient permissions",
                })
            }
            return c.Next()
        }
        
        // Check JWT permissions
        if !hasPermission(claims.Permissions, string(permission)) {
            return c.Status(403).JSON(fiber.Map{
                "error":   "forbidden",
                "message": "insufficient permissions",
            })
        }
        
        return c.Next()
    }
}

// RequireRole checks if user has one of the required roles
func RequireRole(roles ...rbac.Role) fiber.Handler {
       {
        claims := ClaimsFromContext(c)
         claims ==  {
             c.Status().JSON(fiber.Map{
                : ,
            })
        }
        
         _, required :=  roles {
             _, userRole :=  claims.Roles {
                 userRole == (required) {
                     c.Next()
                }
            }
        }
        
         c.Status().JSON(fiber.Map{
            :   ,
            : ,
        })
    }
}

  {
     _, p :=  perms {
         p == required || p ==  {
             
        }
    }
     
}

Resource-Level Authorization

// internal/auth/rbac/policy.go
package rbac

import "context"

type Policy interface {
    CanAccess(ctx context.Context, subject Subject, resource Resource, action Action) (bool, error)
}

type Subject struct {
    UserID      string
    OrgID       string
    ProjectID   string
    Roles       []Role
    Permissions []Permission
}

type Resource struct {
    Type      string // "agent", "secret", "project"
    ID        string
    OwnerOrg  string
    OwnerProj string
}

type Action string

const (
    ActionRead   Action = "read"
    ActionWrite  Action = "write"
    ActionDelete Action = "delete"
    ActionDeploy Action = "deploy"
)

type DefaultPolicy struct {
    repo PolicyRepository
}

func (p *DefaultPolicy) CanAccess(ctx context.Context, subject Subject, resource Resource, action Action) (bool, error) {
    // Platform admin can do anything
    if hasRole(subject.Roles, RolePlatformAdmin) {
        return true, nil
    }
    
    // Must be in same org
    if subject.OrgID != resource.OwnerOrg {
        return false, nil
    }
    
    // Check project-level access
     resource.OwnerProj !=  && subject.ProjectID != resource.OwnerProj {
        
         !hasRole(subject.Roles, RoleOrgAdmin, RoleOrgOwner) {
             , 
        }
    }
    
    
    requiredPerm := resourceActionToPermission(resource.Type, action)
     hasPermission(subject.Permissions, requiredPerm), 
}

OAuth 2.0 Integration

// internal/auth/oauth/provider.go
package oauth

import (
    "context"
    
    "golang.org/x/oauth2"
    "golang.org/x/oauth2/google"
    "golang.org/x/oauth2/github"
)

type Provider interface {
    AuthURL(state string) string
    Exchange(ctx context.Context, code string) (*oauth2.Token, error)
    GetUserInfo(ctx context.Context, token *oauth2.Token) (*UserInfo, error)
}

type UserInfo struct {
    ID       string
    Email    string
    Name     string
    Avatar   string
    Provider string
}

type GoogleProvider struct {
    config *oauth2.Config
}

func NewGoogleProvider(clientID, clientSecret, redirectURL string) *GoogleProvider {
    return &GoogleProvider{
        config: &oauth2.Config{
            ClientID:     clientID,
            ClientSecret: clientSecret,
            RedirectURL:  redirectURL,
            Scopes:       []string{"openid", "email", "profile"},
            Endpoint:     google.Endpoint,
        },
    }
}

func (p *GoogleProvider) AuthURL(state string) string {
    return p.config.AuthCodeURL(state)
}

func (p *GoogleProvider) Exchange(ctx context.Context, code string) (*oauth2.Token, error) {
     p.config.Exchange(ctx, code)
}

 GetUserInfo(ctx context.Context, token *oauth2.Token) (*UserInfo, ) {
    client := p.config.Client(ctx, token)
    resp, err := client.Get()
     err !=  {
         , err
    }
     resp.Body.Close()
    
     info  {
        ID       
        Email    
        Name     
        Picture  
    }
     err := json.NewDecoder(resp.Body).Decode(&info); err !=  {
         , err
    }
    
     &UserInfo{
        ID:       info.ID,
        Email:    info.Email,
        Name:     info.Name,
        Avatar:   info.Picture,
        Provider: ,
    }, 
}

Secret Management

// internal/secrets/service.go
package secrets

import (
    "context"
    "crypto/aes"
    "crypto/cipher"
    "crypto/rand"
    "encoding/base64"
)

type Service struct {
    key  []byte // 32 bytes for AES-256
    repo Repository
}

func NewService(encryptionKey string, repo Repository) *Service {
    return &Service{
        key:  []byte(encryptionKey),
        repo: repo,
    }
}

func (s *Service) Create(ctx context.Context, projectID, name, value string) (*Secret, error) {
    // Encrypt value
    encrypted, err := s.encrypt(value)
    if err != nil {
        return nil, err
    }
    
    secret := &Secret{
        ID:        uuid.NewString(),
        ProjectID: projectID,
        Name:      name,
        Value:     encrypted,
        CreatedAt: time.Now(),
    }
    
    return s.repo.Create(ctx, secret)
}

func (s *Service) Get(ctx context.Context, projectID, name string) (string, error) {
    secret, err := s.repo.FindByName(ctx, projectID, name)
    if err != nil {
        return "", err
    }
    
    return s.decrypt(secret.Value)
}

func (s *Service) encrypt(plaintext string) (, ) {
    block, err := aes.NewCipher(s.key)
     err !=  {
         , err
    }
    
    gcm, err := cipher.NewGCM(block)
     err !=  {
         , err
    }
    
    nonce := ([], gcm.NonceSize())
     _, err := rand.Read(nonce); err !=  {
         , err
    }
    
    ciphertext := gcm.Seal(nonce, nonce, [](plaintext), )
     base64.StdEncoding.EncodeToString(ciphertext), 
}

 decrypt(ciphertext ) (, ) {
    data, err := base64.StdEncoding.DecodeString(ciphertext)
     err !=  {
         , err
    }
    
    block, err := aes.NewCipher(s.key)
     err !=  {
         , err
    }
    
    gcm, err := cipher.NewGCM(block)
     err !=  {
         , err
    }
    
    nonceSize := gcm.NonceSize()
    nonce, ciphertextBytes := data[:nonceSize], data[nonceSize:]
    
    plaintext, err := gcm.Open(, nonce, ciphertextBytes, )
     err !=  {
         , err
    }
    
     (plaintext), 
}

Audit Logging

// internal/audit/logger.go
package audit

import (
    "context"
    "encoding/json"
    "time"
)

type Event struct {
    ID          string                 `json:"id"`
    Timestamp   time.Time              `json:"timestamp"`
    Actor       Actor                  `json:"actor"`
    Action      string                 `json:"action"`
    Resource    Resource               `json:"resource"`
    Result      string                 `json:"result"` // success, failure
    IP          string                 `json:"ip"`
    UserAgent   string                 `json:"user_agent"`
    Details     map[string]interface{} `json:"details,omitempty"`
}

type Actor struct {
    Type   string `json:"type"` // user, api_key, service
    ID     string `json:"id"`
    Email  string `json:"email,omitempty"`
    OrgID  string `json:"org_id"`
}

type Resource struct {
    Type      string `json:"type"`
    ID        string `json:"id"`
    ProjectID string `json:"project_id,omitempty"`
}

type Logger struct {
    writer EventWriter
}

 Log(ctx context.Context, event Event)  {
    event.ID = uuid.NewString()
    event.Timestamp = time.Now().UTC()
    
     l.writer.Write(ctx, event)
}


 LogAction(ctx context.Context, action , resource Resource, result ) {
    actor := ActorFromContext(ctx)
    event := Event{
        Actor:    actor,
        Action:   action,
        Resource: resource,
        Result:   result,
        IP:       IPFromContext(ctx),
    }
    l.Log(ctx, event)
}

Rate Limiting

// internal/api/middleware/ratelimit.go
package middleware

import (
    "time"
    
    "github.com/gofiber/fiber/v2"
    "github.com/redis/go-redis/v9"
)

type RateLimiter struct {
    redis  *redis.Client
    limit  int
    window time.Duration
}

func NewRateLimiter(redis *redis.Client, limit int, window time.Duration) *RateLimiter {
    return &RateLimiter{
        redis:  redis,
        limit:  limit,
        window: window,
    }
}

func (rl *RateLimiter) Middleware() fiber.Handler {
    return func(c *fiber.Ctx) error {
        // Get identifier (API key or user ID)
        key := rl.getKey(c)
        
        // Increment counter
        count, err := rl.redis.Incr(c.Context(), key).Result()
        if err != nil {
            // Allow on Redis failure (fail open)
            return c.Next()
        }
        
        // Set expiry on first request
        if count == 1 {
            rl.redis.Expire(c.Context(), key, rl.window)
        }
        
        // Check limit
        if int(count) > rl.limit {
            ttl, _ := rl.redis.TTL(c.Context(), key).Result()
            
            c.Set("X-RateLimit-Limit", fmt.Sprintf("%d", rl.limit))
            c.Set("X-RateLimit-Remaining", "0")
            c.Set("X-RateLimit-Reset", fmt.Sprintf("%d", time.Now().Add(ttl).Unix()))
            c.Set(, fmt.Sprintf(, (ttl.Seconds())))
            
             c.Status().JSON(fiber.Map{
                :   ,
                : ,
            })
        }
        
        
        c.Set(, fmt.Sprintf(, rl.limit))
        c.Set(, fmt.Sprintf(, rl.limit-(count)))
        
         c.Next()
    }
}

 getKey(c *fiber.Ctx)  {
    
     key, ok := c.Locals().(*apikey.APIKey); ok {
         fmt.Sprintf(, key.ID)
    }
     claims := ClaimsFromContext(c); claims !=  {
         fmt.Sprintf(, claims.UserID)
    }
     fmt.Sprintf(, c.IP())
}

Resources

• references/oauth-providers.md - OAuth provider configurations
• references/security-headers.md - HTTP security headers