CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

documenso-enterprise-rbac

tessl install github:jeremylongshore/claude-code-plugins-plus-skills --skill documenso-enterprise-rbac
github.com/jeremylongshore/claude-code-plugins-plus-skills

Configure Documenso enterprise role-based access control and team management. Use when implementing team permissions, configuring organizational roles, or setting up enterprise access controls. Trigger with phrases like "documenso RBAC", "documenso teams", "documenso permissions", "documenso enterprise", "documenso roles".

Review Score

77%

Validation Score

11/16

Implementation Score

65%

Activation Score

90%

Documenso Enterprise RBAC

Overview

Configure enterprise-grade role-based access control for Documenso integrations with team management and permission hierarchies.

Prerequisites

  • Documenso Teams or Enterprise plan
  • Understanding of RBAC concepts
  • Identity provider (optional, for SSO)

Documenso Team Roles

RoleDocumentsTemplatesTeam SettingsAPI Access
OwnerFullFullFullFull
AdminFullFullManage membersFull
MemberCreate/Edit ownUseNoneLimited
ViewerView onlyViewNoneRead-only

Role Implementation

Step 1: Define Application Roles

// src/auth/roles.ts
export enum SigningRole {
  Admin = "admin",
  Manager = "manager",
  User = "user",
  Viewer = "viewer",
  ApiService = "api_service",
}

export interface SigningPermissions {
  documents: {
    create: boolean;
    read: boolean;
    update: boolean;
    delete: boolean;
    send: boolean;
  };
  templates: {
    create: boolean;
    read: boolean;
    update: boolean;
    delete: boolean;
    use: boolean;
  };
  team: {
    manageMembers: boolean;
    manageSettings: boolean;
    viewAuditLog: boolean;
  };
  api: {
    useApi: boolean;
    manageWebhooks: boolean;
  };
}

export const ROLE_PERMISSIONS: Record<SigningRole, SigningPermissions> = {
  [SigningRole.Admin]: {
    documents: { create: true, read: true, update: true, delete: true, send: true },
    templates: { create: true, read: true, update: true, delete: true, use: true },
    team: { manageMembers: true, manageSettings: true, viewAuditLog: true },
    api: { useApi: true, manageWebhooks: true },
  },
  [SigningRole.Manager]: {
    documents: { create: true, read: true, update: true, delete: true, send: true },
    templates: { create: true, read: true, update: true, delete: false, use: true },
    team: { manageMembers: false, manageSettings: false, viewAuditLog: true },
    api: { useApi: true, manageWebhooks: false },
  },
  [SigningRole.User]: {
    documents: { create: true, read: true, update: true, delete: false, send: true },
    templates: { create: false, read: true, update: false, delete: false, use: true },
    team: { manageMembers: false, manageSettings: false, viewAuditLog: false },
    api: { useApi: false, manageWebhooks: false },
  },
  [SigningRole.Viewer]: {
    documents: { create: false, read: true, update: false, delete: false, send: false },
    templates: { create: false, read: true, update: false, delete: false, use: false },
    team: { manageMembers: false, manageSettings: false, viewAuditLog: false },
    api: { useApi: false, manageWebhooks: false },
  },
  [SigningRole.ApiService]: {
    documents: { create: true, read: true, update: true, delete: false, send: true },
    templates: { create: false, read: true, update: false, delete: false, use: true },
    team: { manageMembers: false, manageSettings: false, viewAuditLog: false },
    api: { useApi: true, manageWebhooks: false },
  },
};

Step 2: Permission Checking

// src/auth/permissions.ts
import { SigningRole, ROLE_PERMISSIONS, SigningPermissions } from "./roles";

type PermissionPath =
  | `documents.${keyof SigningPermissions["documents"]}`
  | `templates.${keyof SigningPermissions["templates"]}`
  | `team.${keyof SigningPermissions["team"]}`
  | `api.${keyof SigningPermissions["api"]}`;

export function hasPermission(
  role: SigningRole,
  permission: PermissionPath
): boolean {
  const [category, action] = permission.split(".") as [
    keyof SigningPermissions,
    string
  ];

  const permissions = ROLE_PERMISSIONS[role];
  return (permissions[category] as any)[action] ?? false;
}

export function checkPermission(
  role: SigningRole,
  permission: PermissionPath
): void {
  if (!hasPermission(role, permission)) {
    throw new ForbiddenError(
      `Permission denied: ${permission} requires higher role than ${role}`
    );
  }
}

export class ForbiddenError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "ForbiddenError";
  }
}

Step 3: Express Middleware

// src/middleware/auth.ts
import { Request, Response, NextFunction } from "express";
import { SigningRole, hasPermission } from "../auth";

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      user?: {
        id: string;
        email: string;
        role: SigningRole;
        teamId?: string;
      };
    }
  }
}

export function requireRole(requiredRole: SigningRole) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user) {
      return res.status(401).json({ error: "Authentication required" });
    }

    const roleHierarchy = [
      SigningRole.Viewer,
      SigningRole.User,
      SigningRole.Manager,
      SigningRole.Admin,
    ];

    const userRoleIndex = roleHierarchy.indexOf(user.role);
    const requiredRoleIndex = roleHierarchy.indexOf(requiredRole);

    if (userRoleIndex < requiredRoleIndex) {
      return res.status(403).json({
        error: "Forbidden",
        message: `Role ${requiredRole} required, you have ${user.role}`,
      });
    }

    next();
  };
}

export function requirePermission(permission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user) {
      return res.status(401).json({ error: "Authentication required" });
    }

    if (!hasPermission(user.role, permission as any)) {
      return res.status(403).json({
        error: "Forbidden",
        message: `Permission '${permission}' denied for role ${user.role}`,
      });
    }

    next();
  };
}

Step 4: Document Ownership

// src/services/document-access.ts
interface DocumentOwnership {
  documentId: string;
  ownerId: string;
  teamId?: string;
  sharedWith: string[];  // User IDs with explicit access
}

class DocumentAccessService {
  private ownership = new Map<string, DocumentOwnership>();

  async canAccess(
    userId: string,
    userRole: SigningRole,
    documentId: string
  ): Promise<boolean> {
    // Admins can access all team documents
    if (userRole === SigningRole.Admin) {
      return true;
    }

    const ownership = this.ownership.get(documentId);
    if (!ownership) {
      return false;
    }

    // Owner always has access
    if (ownership.ownerId === userId) {
      return true;
    }

    // Check explicit sharing
    if (ownership.sharedWith.includes(userId)) {
      return true;
    }

    // Managers can access team documents
    if (userRole === SigningRole.Manager && ownership.teamId) {
      const userTeam = await this.getUserTeam(userId);
      return userTeam === ownership.teamId;
    }

    return false;
  }

  async canModify(
    userId: string,
    userRole: SigningRole,
    documentId: string
  ): Promise<boolean> {
    // Viewers cannot modify
    if (userRole === SigningRole.Viewer) {
      return false;
    }

    // Others need access + not viewer
    return this.canAccess(userId, userRole, documentId);
  }

  async registerDocument(
    documentId: string,
    ownerId: string,
    teamId?: string
  ): Promise<void> {
    this.ownership.set(documentId, {
      documentId,
      ownerId,
      teamId,
      sharedWith: [],
    });
  }

  async shareDocument(
    documentId: string,
    shareWithUserId: string
  ): Promise<void> {
    const ownership = this.ownership.get(documentId);
    if (ownership) {
      ownership.sharedWith.push(shareWithUserId);
    }
  }

  private async getUserTeam(userId: string): Promise<string | undefined> {
    // Implement team lookup
    return undefined;
  }
}

export const documentAccess = new DocumentAccessService();

Step 5: API Route Protection

// src/api/documents.ts
import express from "express";
import { requirePermission, requireRole } from "../middleware/auth";
import { SigningRole } from "../auth";
import { documentAccess } from "../services/document-access";

const router = express.Router();

// Create document - requires documents.create permission
router.post(
  "/documents",
  requirePermission("documents.create"),
  async (req, res) => {
    const { title, templateId } = req.body;
    const userId = req.user!.id;

    const doc = await signingService.createDocument(title, templateId);

    // Register ownership
    await documentAccess.registerDocument(
      doc.documentId,
      userId,
      req.user!.teamId
    );

    res.json(doc);
  }
);

// Delete document - requires documents.delete AND ownership
router.delete(
  "/documents/:id",
  requirePermission("documents.delete"),
  async (req, res) => {
    const documentId = req.params.id;
    const { id: userId, role } = req.user!;

    // Check ownership
    const canModify = await documentAccess.canModify(userId, role, documentId);
    if (!canModify) {
      return res.status(403).json({ error: "Not authorized for this document" });
    }

    await signingService.deleteDocument(documentId);
    res.json({ deleted: true });
  }
);

// Team management - requires team.manageMembers permission
router.post(
  "/team/members",
  requirePermission("team.manageMembers"),
  async (req, res) => {
    const { email, role } = req.body;
    // Add team member logic
    res.json({ added: true });
  }
);

// Audit log - requires team.viewAuditLog permission
router.get(
  "/team/audit-log",
  requirePermission("team.viewAuditLog"),
  async (req, res) => {
    const auditLog = await getAuditLog(req.user!.teamId!);
    res.json(auditLog);
  }
);

export default router;

Step 6: Audit Logging

// src/audit/logger.ts
interface AuditEntry {
  timestamp: Date;
  userId: string;
  userEmail: string;
  userRole: SigningRole;
  action: string;
  resourceType: "document" | "template" | "team" | "settings";
  resourceId: string;
  details: Record<string, any>;
  ipAddress?: string;
  success: boolean;
}

class AuditLogger {
  async log(entry: Omit<AuditEntry, "timestamp">): Promise<void> {
    const fullEntry: AuditEntry = {
      ...entry,
      timestamp: new Date(),
    };

    // Store in database
    await db.auditLog.create({ data: fullEntry });

    // Log to monitoring
    console.log(
      `[AUDIT] ${entry.action} ${entry.resourceType}:${entry.resourceId} ` +
      `by ${entry.userEmail} (${entry.userRole}) - ${entry.success ? "OK" : "DENIED"}`
    );

    // Alert on security events
    if (this.isSecurityEvent(entry)) {
      await this.alertSecurity(fullEntry);
    }
  }

  private isSecurityEvent(entry: Omit<AuditEntry, "timestamp">): boolean {
    return (
      !entry.success ||
      entry.action.includes("delete") ||
      entry.action.includes("permission") ||
      entry.resourceType === "team"
    );
  }

  private async alertSecurity(entry: AuditEntry): Promise<void> {
    // Send to security team
  }
}

export const auditLogger = new AuditLogger();

// Middleware to log all protected actions
export function auditMiddleware(action: string, resourceType: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const startTime = Date.now();

    // Capture original end function
    const originalEnd = res.end;

    res.end = function (chunk?: any, encoding?: any) {
      // Log after response is sent
      auditLogger.log({
        userId: req.user?.id ?? "anonymous",
        userEmail: req.user?.email ?? "unknown",
        userRole: req.user?.role ?? SigningRole.Viewer,
        action,
        resourceType: resourceType as any,
        resourceId: req.params.id ?? "none",
        details: {
          method: req.method,
          path: req.path,
          durationMs: Date.now() - startTime,
          statusCode: res.statusCode,
        },
        ipAddress: req.ip,
        success: res.statusCode < 400,
      });

      return originalEnd.call(this, chunk, encoding);
    };

    next();
  };
}

Multi-Tenant Architecture

// src/tenant/context.ts
interface TenantContext {
  tenantId: string;
  documensoApiKey: string;
  features: {
    templatesEnabled: boolean;
    webhooksEnabled: boolean;
    maxDocumentsPerMonth: number;
  };
}

const tenantContexts = new Map<string, TenantContext>();

export function getTenantContext(tenantId: string): TenantContext {
  const context = tenantContexts.get(tenantId);
  if (!context) {
    throw new Error(`Unknown tenant: ${tenantId}`);
  }
  return context;
}

export function getDocumensoClientForTenant(tenantId: string): Documenso {
  const context = getTenantContext(tenantId);

  return new Documenso({
    apiKey: context.documensoApiKey,
  });
}

Output

  • Role-based permissions implemented
  • Document ownership tracked
  • Audit logging enabled
  • Multi-tenant support ready

Error Handling

RBAC IssueCauseSolution
403 ForbiddenInsufficient roleRequest role upgrade
Cannot deleteNot ownerCheck ownership
Audit gapMiddleware missingAdd audit middleware
Tenant mismatchWrong contextVerify tenant ID

Resources

  • RBAC Best Practices
  • Documenso Teams
  • OWASP Access Control

Next Steps

For migration strategies, see documenso-migration-deep-dive.