Permission Service Integration

Overview

The PermissionService is a centralized authorization service that:

Queries user roles from Better Auth PostgreSQL tables
Maps roles to permissions (e.g., owner → ["org:manage", "data:write", "leave:approve", ...])
Caches permission lookups for 5 minutes
Provides methods to check authorization in your use cases

Use it whenever you need to verify if a user is allowed to perform an action.

Interface

The PermissionService implements the port.PermissionService interface:

// internal/modules/organizations/application/port/permission_service.go

type PermissionService interface {
    // GetUserPlatformRole returns the global role (user, admin, superadmin)
    GetUserPlatformRole(ctx context.Context, userID string) (string, error)

    // IsUserSuperAdmin checks if user has superadmin platform role
    IsUserSuperAdmin(ctx context.Context, userID string) (bool, error)

    // GetUserOrgRole returns the user's role in a specific organization
    GetUserOrgRole(ctx context.Context, userID, organizationID string) (string, error)

    // CanManageOrg checks if user can manage the organization
    CanManageOrg(ctx context.Context, userID, organizationID string) (bool, error)

    // GetUserPermissions returns all permissions for a user in an org
    GetUserPermissions(ctx context.Context, userID, organizationID string) ([]string, error)

    // HasPermission checks if user has a specific permission in an org
    HasPermission(ctx context.Context, userID, organizationID, permission string) (bool, error)

    // CanApproveLeaveFor checks if user can approve leave for an employee
    CanApproveLeaveFor(ctx context.Context, approverID, employeeID, organizationID string) (bool, error)

    // CanUserApproveLease checks if user can approve lease (placeholder)
    CanUserApproveLease(ctx context.Context, userID, organizationID string) (bool, error)
}

Usage Patterns

Pattern 1: Check Specific Permission

When: You need to verify a single permission like “data:write” or “leave:approve”

// In your use case or handler
func (s *MyService) UpdateData(ctx context.Context, userID, orgID, dataID string, updates *Data) error {
    // Check permission
    hasPermission, err := s.permissionSvc.HasPermission(ctx, userID, orgID, "data:write")
    if err != nil {
        return fmt.Errorf("failed to check permission: %w", err)
    }
    if !hasPermission {
        return errors.New("user not authorized to update data")
    }

    // Proceed with update
    return s.dataRepo.Update(ctx, dataID, updates)
}

Pattern 2: Check Role

When: You need to know what role the user has (for role-specific logic or UI rendering)

func (s *MyService) GetUserOrgContext(ctx context.Context, userID, orgID string) (*UserOrgContext, error) {
    role, err := s.permissionSvc.GetUserOrgRole(ctx, userID, orgID)
    if err != nil {
        return nil, err
    }

    canManage, err := s.permissionSvc.CanManageOrg(ctx, userID, orgID)
    if err != nil {
        return nil, err
    }

    return &UserOrgContext{
        UserID:        userID,
        OrganizationID: orgID,
        Role:          role,
        CanManage:     canManage,
    }, nil
}

Pattern 3: Check Multiple Permissions (Any)

When: User needs ANY of several permissions to proceed

func (s *MyService) CanExportData(ctx context.Context, userID, orgID string) (bool, error) {
    permissions, err := s.permissionSvc.GetUserPermissions(ctx, userID, orgID)
    if err != nil {
        return false, err
    }

    // Check if user has any export permission
    for _, perm := range permissions {
        if strings.HasPrefix(perm, "data:") || strings.HasPrefix(perm, "report:") {
            return true, nil
        }
    }
    return false, nil
}

Pattern 4: Leave Approval (Pre-Built Method)

When: Checking if user can approve leave for an employee

// In approval_service.go (Leave module)
func (s *ApprovalService) ApproveRequest(ctx context.Context, requestID, approverID string) error {
    request, _ := s.leaveRequestRepo.FindByID(ctx, requestID)

    // Use the specialized leave-approval check
    canApprove, err := s.permissionSvc.CanApproveLeaveFor(
        ctx,
        approverID,
        request.UserID,
        request.OrganizationID,
    )
    if err != nil {
        return err
    }
    if !canApprove {
        return errors.New("not authorized")
    }

    // Proceed with approval
    return s.leaveRequestRepo.Update(ctx, request)
}

Integration with Dependency Injection

In Module Initialization

// internal/modules/mymodule/module.go

import (
    orgModule "github.com/waynecheah/go-core/internal/modules/organizations"
)

func NewModule(c *app.Container, orgModule *organizations.Module) *Module {
    // ... other initialization

    // Get PermissionService from organizations module
    myService := usecase.NewMyService(
        myRepo,
        orgModule.Permissions,  // <-- Use this!
    )

    return &Module{
        Service: myService,
    }
}

In Your Use Case

// internal/modules/mymodule/application/usecase/my_service.go

type MyService struct {
    repo              port.MyRepository
    permissionSvc     orgPort.PermissionService  // <-- Inject this
}

func NewMyService(
    repo port.MyRepository,
    permissionSvc orgPort.PermissionService,
) *MyService {
    return &MyService{
        repo:          repo,
        permissionSvc: permissionSvc,
    }
}

func (s *MyService) DoSomething(ctx context.Context, userID, orgID string) error {
    canDo, err := s.permissionSvc.HasPermission(ctx, userID, orgID, "my:permission")
    if err != nil {
        return err
    }
    if !canDo {
        return errors.New("not authorized")
    }
    // ... proceed
}

Caching Behavior

Cache Details

Key: perm:<userId>:<organizationId>
TTL: 5 minutes
Stored: User’s org role + resolved permissions array

How It Works

First request:

User→PermissionSvc.HasPermission("user1", "org1", "leave:approve")
  ├─ Cache miss (no entry)
  ├─ Query: SELECT role FROM member WHERE userId='user1' AND organizationId='org1'
  ├─ Result: role="admin"
  ├─ Resolve: admin → ["data:read", "data:write", "leave:approve", ...]
  ├─ Cache: store {"role": "admin", "permissions": [...]}, TTL=5min
  └─ Return: true (contains "leave:approve")

Second request (within 5 minutes):

User→PermissionSvc.HasPermission("user1", "org1", "data:write")
  ├─ Cache hit!
  ├─ Return: true (contains "data:write")

After 5 minutes:

User→PermissionSvc.HasPermission("user1", "org1", "leave:approve")
  ├─ Cache expired
  ├─ Query: SELECT role FROM member WHERE userId='user1' AND organizationId='org1'
  ├─ ... repeat above ...

Performance Impact

Cached: ~1-2 µs (map lookup)
Uncached: ~10-50 ms (DB query + resolution)

This is why caching is important — a single approval operation might check permissions 3-4 times.

Error Handling

Common Errors

// User not found in organization
role, err := s.permissionSvc.GetUserOrgRole(ctx, "nonexistent-user", "org1")
// err might be: "user not found in organization" or ErrUserNotInOrg

// Database error
perms, err := s.permissionSvc.GetUserPermissions(ctx, "user1", "org1")
// err might be: "failed to query database: connection timeout"

// Always check err!
if err != nil {
    return fmt.Errorf("permission check failed: %w", err)
}

Defensive Coding

Always treat missing users as “not authorized”:

canApprove, err := s.permissionSvc.CanApproveLeaveFor(ctx, approverID, employeeID, orgID)
if err != nil {
    // Log the error but fail securely
    s.log.Error("permission check failed", zap.Error(err))
    return errors.New("authorization failed (please try again)")
}
if !canApprove {
    return errors.New("not authorized")
}

Permission Reference

Available Permissions

Permission	Role	Meaning
`data:read`	staff, member, viewer	Read data/records
`data:write`	owner, admin, staff	Write/edit data
`leave:request`	owner, admin, staff, member	Request leave
`leave:approve`	owner, admin	Approve leave requests
`member:invite`	owner, admin	Invite members
`member:manage`	owner, admin	Update member roles
`member:remove`	owner, admin	Remove members
`org:manage`	owner, admin	Manage org settings
`report:view`	owner, admin	View reports
`report:export`	owner, admin	Export reports

Role-to-Permission Mapping

// internal/modules/organizations/application/usecase/permission_service.go
var defaultRolePermissions = map[string][]string{
    "owner": {
        "data:read", "data:write",
        "leave:approve", "leave:request",
        "member:invite", "member:manage", "member:remove",
        "org:manage",
    },
    "admin": {
        "data:read", "data:write",
        "leave:approve", "leave:request",
        "member:invite", "member:manage", "member:remove",
        "org:manage",
    },
    "staff": {
        "data:read", "data:write",
        "leave:request",
    },
    "member": {
        "data:read", "data:write",
        "leave:request",
    },
    "viewer": {
        "data:read",
    },
}

Middleware Integration

Auto-Extracting Organization from JWT

The request context contains organization_id from the JWT. Use it:

// In your handler
func (h *MyHandler) MyEndpoint(c echo.Context) error {
    userID := c.Get("user_id").(string)
    orgID := c.Get("organization_id").(string)  // From JWT context

    canDo, err := h.service.CheckPermission(c.Request().Context(), userID, orgID, "my:perm")
    if err != nil || !canDo {
        return echo.NewHTTPError(http.StatusForbidden, "Not authorized")
    }

    // Proceed
}

Testing

Unit Test Example

// internal/modules/mymodule/application/usecase/my_service_test.go

func TestMyService_DoSomething_NotAuthorized(t *testing.T) {
    mockPermissionSvc := &mockPermissionService{}
    mockPermissionSvc.On("HasPermission",
        mock.Anything,
        "user1",
        "org1",
        "my:permission",
    ).Return(false, nil)

    svc := NewMyService(mockRepo, mockPermissionSvc)

    err := svc.DoSomething(context.Background(), "user1", "org1")
    assert.Error(t, err)
    assert.Equal(t, "not authorized", err.Error())
}

func TestMyService_DoSomething_Authorized(t *testing.T) {
    mockPermissionSvc := &mockPermissionService{}
    mockPermissionSvc.On("HasPermission",
        mock.Anything,
        "user1",
        "org1",
        "my:permission",
    ).Return(true, nil)

    svc := NewMyService(mockRepo, mockPermissionSvc)

    err := svc.DoSomething(context.Background(), "user1", "org1")
    assert.NoError(t, err)
}

FAQ

Q: Can I change permission mappings?

A: The mappings are hardcoded in permission_service.go (the defaultRolePermissions map). To change them, edit this file and redeploy. This is intentional — permissions are part of system design, not runtime configuration.

Q: What if I need real-time permission updates (< 5 sec)?

A: Options:

Use shorter TTL: Change cache TTL from 5 min to 1 min in NewPermissionService()
Subscribe to events: Have Bun publish a NATS event when role changes, Go listens and invalidates cache
Disable cache: Return false from cache.get() to force DB queries (not recommended for performance)

Q: Can I add new permissions?

A: Yes:

Add the permission string to the appropriate role in defaultRolePermissions
Use it in your service: HasPermission(ctx, user, org, "my:new:permission")
Test it

Q: What about superadmins?

A: Platform superadmins (from auth.role = "superadmin") can do anything. Check with IsUserSuperAdmin(ctx, userID) if needed.

Role Assignment and Authorization — How roles are assigned via Better Auth
Authentication Architecture — JWT validation and Better Auth integration
Leave Module Integration — Real-world usage example

Documentations

Getting Started

API

Modules

Infrastructure

Development

Guides

Permission Service Integration

Permission Service Integration

Overview

Interface

Usage Patterns

Pattern 1: Check Specific Permission

Pattern 2: Check Role

Pattern 3: Check Multiple Permissions (Any)

Pattern 4: Leave Approval (Pre-Built Method)

Integration with Dependency Injection

In Module Initialization

In Your Use Case

Caching Behavior

Cache Details

How It Works

Performance Impact

Error Handling

Common Errors

Defensive Coding

Permission Reference

Available Permissions

Role-to-Permission Mapping

Middleware Integration

Auto-Extracting Organization from JWT

Testing

Unit Test Example

FAQ

Q: Can I change permission mappings?

Q: What if I need real-time permission updates (< 5 sec)?

Q: Can I add new permissions?

Q: What about superadmins?

​Permission Service Integration

​Overview

​Interface

​Usage Patterns

​Pattern 1: Check Specific Permission

​Pattern 2: Check Role

​Pattern 3: Check Multiple Permissions (Any)

​Pattern 4: Leave Approval (Pre-Built Method)

​Integration with Dependency Injection

​In Module Initialization

​In Your Use Case

​Caching Behavior

​Cache Details

​How It Works

​Performance Impact

​Error Handling

​Common Errors

​Defensive Coding

​Permission Reference

​Available Permissions

​Role-to-Permission Mapping

​Middleware Integration

​Auto-Extracting Organization from JWT

​Testing

​Unit Test Example

​FAQ

​Q: Can I change permission mappings?

​Q: What if I need real-time permission updates (< 5 sec)?

​Q: Can I add new permissions?

​Q: What about superadmins?

​Related Documentation

Permission Service Integration

Overview

Interface

Usage Patterns

Pattern 1: Check Specific Permission

Pattern 2: Check Role

Pattern 3: Check Multiple Permissions (Any)

Pattern 4: Leave Approval (Pre-Built Method)

Integration with Dependency Injection

In Module Initialization

In Your Use Case

Caching Behavior

Cache Details

How It Works

Performance Impact

Error Handling

Common Errors

Defensive Coding

Permission Reference

Available Permissions

Role-to-Permission Mapping

Middleware Integration

Auto-Extracting Organization from JWT

Testing

Unit Test Example

FAQ

Q: Can I change permission mappings?

Q: What if I need real-time permission updates (< 5 sec)?

Q: Can I add new permissions?

Q: What about superadmins?

Related Documentation