+210

src/lib/permissions.ts

reviewed

··· 1 1 + /** 2 2 + * Granular Permissions — role-based access control for documents. 3 3 + * 4 4 + * Pure logic module: permission definitions, role checks, sharing. 5 5 + * Storage and enforcement handled by the application layer. 6 6 + */ 7 7 + 8 8 + export type Permission = 'view' | 'comment' | 'edit' | 'admin'; 9 9 + 10 10 + export type Role = 'viewer' | 'commenter' | 'editor' | 'owner'; 11 11 + 12 12 + export interface DocumentPermission { 13 13 + userId: string; 14 14 + userName: string; 15 15 + role: Role; 16 16 + grantedAt: number; 17 17 + grantedBy: string; 18 18 + } 19 19 + 20 20 + export interface ShareLink { 21 21 + id: string; 22 22 + docId: string; 23 23 + role: Role; 24 24 + createdAt: number; 25 25 + createdBy: string; 26 26 + expiresAt: number | null; 27 27 + maxUses: number | null; 28 28 + useCount: number; 29 29 + } 30 30 + 31 31 + /** Permissions each role grants (cumulative) */ 32 32 + const ROLE_PERMISSIONS: Record<Role, Permission[]> = { 33 33 + viewer: ['view'], 34 34 + commenter: ['view', 'comment'], 35 35 + editor: ['view', 'comment', 'edit'], 36 36 + owner: ['view', 'comment', 'edit', 'admin'], 37 37 + }; 38 38 + 39 39 + /** Role hierarchy (higher index = more permissions) */ 40 40 + const ROLE_HIERARCHY: Role[] = ['viewer', 'commenter', 'editor', 'owner']; 41 41 + 42 42 + /** 43 43 + * Check if a role has a specific permission. 44 44 + */ 45 45 + export function hasPermission(role: Role, permission: Permission): boolean { 46 46 + return ROLE_PERMISSIONS[role]?.includes(permission) ?? false; 47 47 + } 48 48 + 49 49 + /** 50 50 + * Get all permissions for a role. 51 51 + */ 52 52 + export function getPermissions(role: Role): Permission[] { 53 53 + return [...(ROLE_PERMISSIONS[role] || [])]; 54 54 + } 55 55 + 56 56 + /** 57 57 + * Compare two roles. Returns negative if a < b, 0 if equal, positive if a > b. 58 58 + */ 59 59 + export function compareRoles(a: Role, b: Role): number { 60 60 + return ROLE_HIERARCHY.indexOf(a) - ROLE_HIERARCHY.indexOf(b); 61 61 + } 62 62 + 63 63 + /** 64 64 + * Check if roleA is at least as privileged as roleB. 65 65 + */ 66 66 + export function isAtLeast(roleA: Role, roleB: Role): boolean { 67 67 + return compareRoles(roleA, roleB) >= 0; 68 68 + } 69 69 + 70 70 + /** 71 71 + * Grant a permission to a user on a document. 72 72 + */ 73 73 + export function grantPermission( 74 74 + permissions: DocumentPermission[], 75 75 + userId: string, 76 76 + userName: string, 77 77 + role: Role, 78 78 + grantedBy: string, 79 79 + now = Date.now(), 80 80 + ): DocumentPermission[] { 81 81 + // Update existing or add new 82 82 + const existing = permissions.findIndex(p => p.userId === userId); 83 83 + const entry: DocumentPermission = { 84 84 + userId, 85 85 + userName, 86 86 + role, 87 87 + grantedAt: now, 88 88 + grantedBy, 89 89 + }; 90 90 + 91 91 + if (existing !== -1) { 92 92 + const updated = [...permissions]; 93 93 + updated[existing] = entry; 94 94 + return updated; 95 95 + } 96 96 + 97 97 + return [...permissions, entry]; 98 98 + } 99 99 + 100 100 + /** 101 101 + * Revoke a user's permission on a document. 102 102 + * Cannot revoke the owner's permission. 103 103 + */ 104 104 + export function revokePermission( 105 105 + permissions: DocumentPermission[], 106 106 + userId: string, 107 107 + ): DocumentPermission[] { 108 108 + const target = permissions.find(p => p.userId === userId); 109 109 + if (!target || target.role === 'owner') return permissions; 110 110 + return permissions.filter(p => p.userId !== userId); 111 111 + } 112 112 + 113 113 + /** 114 114 + * Get a user's role on a document, or null if not authorized. 115 115 + */ 116 116 + export function getUserRole( 117 117 + permissions: DocumentPermission[], 118 118 + userId: string, 119 119 + ): Role | null { 120 120 + const perm = permissions.find(p => p.userId === userId); 121 121 + return perm ? perm.role : null; 122 122 + } 123 123 + 124 124 + /** 125 125 + * Check if a user can perform a specific action. 126 126 + */ 127 127 + export function canPerform( 128 128 + permissions: DocumentPermission[], 129 129 + userId: string, 130 130 + permission: Permission, 131 131 + ): boolean { 132 132 + const role = getUserRole(permissions, userId); 133 133 + if (!role) return false; 134 134 + return hasPermission(role, permission); 135 135 + } 136 136 + 137 137 + /** 138 138 + * Check if a granter can assign a specific role. 139 139 + * Users can only assign roles equal to or below their own. 140 140 + */ 141 141 + export function canGrantRole( 142 142 + granterRole: Role, 143 143 + targetRole: Role, 144 144 + ): boolean { 145 145 + return isAtLeast(granterRole, targetRole); 146 146 + } 147 147 + 148 148 + /** 149 149 + * Create a share link. 150 150 + */ 151 151 + export function createShareLink( 152 152 + docId: string, 153 153 + role: Role, 154 154 + createdBy: string, 155 155 + options?: { expiresAt?: number; maxUses?: number }, 156 156 + now = Date.now(), 157 157 + ): ShareLink { 158 158 + return { 159 159 + id: `share-${now}-${Math.random().toString(36).slice(2, 8)}`, 160 160 + docId, 161 161 + role, 162 162 + createdAt: now, 163 163 + createdBy, 164 164 + expiresAt: options?.expiresAt ?? null, 165 165 + maxUses: options?.maxUses ?? null, 166 166 + useCount: 0, 167 167 + }; 168 168 + } 169 169 + 170 170 + /** 171 171 + * Check if a share link is still valid. 172 172 + */ 173 173 + export function isShareLinkValid( 174 174 + link: ShareLink, 175 175 + now = Date.now(), 176 176 + ): boolean { 177 177 + if (link.expiresAt !== null && now > link.expiresAt) return false; 178 178 + if (link.maxUses !== null && link.useCount >= link.maxUses) return false; 179 179 + return true; 180 180 + } 181 181 + 182 182 + /** 183 183 + * Increment the use count of a share link. 184 184 + */ 185 185 + export function useShareLink(link: ShareLink): ShareLink { 186 186 + return { ...link, useCount: link.useCount + 1 }; 187 187 + } 188 188 + 189 189 + /** 190 190 + * List all users with a specific role. 191 191 + */ 192 192 + export function getUsersByRole( 193 193 + permissions: DocumentPermission[], 194 194 + role: Role, 195 195 + ): DocumentPermission[] { 196 196 + return permissions.filter(p => p.role === role); 197 197 + } 198 198 + 199 199 + /** 200 200 + * Count users by role. 201 201 + */ 202 202 + export function countByRole( 203 203 + permissions: DocumentPermission[], 204 204 + ): Record<Role, number> { 205 205 + const counts: Record<Role, number> = { viewer: 0, commenter: 0, editor: 0, owner: 0 }; 206 206 + for (const p of permissions) { 207 207 + counts[p.role]++; 208 208 + } 209 209 + return counts; 210 210 + }

+187

tests/permissions.test.ts

reviewed

··· 1 1 + import { describe, it, expect } from 'vitest'; 2 2 + import { 3 3 + hasPermission, 4 4 + getPermissions, 5 5 + compareRoles, 6 6 + isAtLeast, 7 7 + grantPermission, 8 8 + revokePermission, 9 9 + getUserRole, 10 10 + canPerform, 11 11 + canGrantRole, 12 12 + createShareLink, 13 13 + isShareLinkValid, 14 14 + useShareLink, 15 15 + getUsersByRole, 16 16 + countByRole, 17 17 + type DocumentPermission, 18 18 + } from '../src/lib/permissions.js'; 19 19 + 20 20 + const PERMS: DocumentPermission[] = [ 21 21 + { userId: 'alice', userName: 'Alice', role: 'owner', grantedAt: 1000, grantedBy: 'system' }, 22 22 + { userId: 'bob', userName: 'Bob', role: 'editor', grantedAt: 2000, grantedBy: 'alice' }, 23 23 + { userId: 'carol', userName: 'Carol', role: 'viewer', grantedAt: 3000, grantedBy: 'alice' }, 24 24 + ]; 25 25 + 26 26 + describe('Permissions', () => { 27 27 + describe('hasPermission', () => { 28 28 + it('viewer can view but not edit', () => { 29 29 + expect(hasPermission('viewer', 'view')).toBe(true); 30 30 + expect(hasPermission('viewer', 'edit')).toBe(false); 31 31 + expect(hasPermission('viewer', 'comment')).toBe(false); 32 32 + }); 33 33 + 34 34 + it('editor can view, comment, and edit', () => { 35 35 + expect(hasPermission('editor', 'view')).toBe(true); 36 36 + expect(hasPermission('editor', 'comment')).toBe(true); 37 37 + expect(hasPermission('editor', 'edit')).toBe(true); 38 38 + expect(hasPermission('editor', 'admin')).toBe(false); 39 39 + }); 40 40 + 41 41 + it('owner has all permissions', () => { 42 42 + expect(hasPermission('owner', 'view')).toBe(true); 43 43 + expect(hasPermission('owner', 'comment')).toBe(true); 44 44 + expect(hasPermission('owner', 'edit')).toBe(true); 45 45 + expect(hasPermission('owner', 'admin')).toBe(true); 46 46 + }); 47 47 + }); 48 48 + 49 49 + describe('getPermissions', () => { 50 50 + it('returns all permissions for a role', () => { 51 51 + expect(getPermissions('commenter')).toEqual(['view', 'comment']); 52 52 + }); 53 53 + }); 54 54 + 55 55 + describe('compareRoles / isAtLeast', () => { 56 56 + it('compares role hierarchy', () => { 57 57 + expect(compareRoles('owner', 'viewer')).toBeGreaterThan(0); 58 58 + expect(compareRoles('viewer', 'editor')).toBeLessThan(0); 59 59 + expect(compareRoles('editor', 'editor')).toBe(0); 60 60 + }); 61 61 + 62 62 + it('checks minimum role level', () => { 63 63 + expect(isAtLeast('owner', 'editor')).toBe(true); 64 64 + expect(isAtLeast('viewer', 'editor')).toBe(false); 65 65 + expect(isAtLeast('editor', 'editor')).toBe(true); 66 66 + }); 67 67 + }); 68 68 + 69 69 + describe('grantPermission', () => { 70 70 + it('adds new user permission', () => { 71 71 + const updated = grantPermission(PERMS, 'dave', 'Dave', 'commenter', 'alice', 5000); 72 72 + expect(updated).toHaveLength(4); 73 73 + expect(updated[3].userId).toBe('dave'); 74 74 + expect(updated[3].role).toBe('commenter'); 75 75 + }); 76 76 + 77 77 + it('updates existing user role', () => { 78 78 + const updated = grantPermission(PERMS, 'carol', 'Carol', 'editor', 'alice', 5000); 79 79 + expect(updated).toHaveLength(3); 80 80 + const carol = updated.find(p => p.userId === 'carol')!; 81 81 + expect(carol.role).toBe('editor'); 82 82 + }); 83 83 + }); 84 84 + 85 85 + describe('revokePermission', () => { 86 86 + it('removes user permission', () => { 87 87 + const updated = revokePermission(PERMS, 'carol'); 88 88 + expect(updated).toHaveLength(2); 89 89 + expect(updated.find(p => p.userId === 'carol')).toBeUndefined(); 90 90 + }); 91 91 + 92 92 + it('cannot revoke owner permission', () => { 93 93 + const updated = revokePermission(PERMS, 'alice'); 94 94 + expect(updated).toHaveLength(3); // unchanged 95 95 + }); 96 96 + 97 97 + it('ignores unknown user', () => { 98 98 + expect(revokePermission(PERMS, 'unknown')).toHaveLength(3); 99 99 + }); 100 100 + }); 101 101 + 102 102 + describe('getUserRole', () => { 103 103 + it('returns role for known user', () => { 104 104 + expect(getUserRole(PERMS, 'bob')).toBe('editor'); 105 105 + }); 106 106 + 107 107 + it('returns null for unknown user', () => { 108 108 + expect(getUserRole(PERMS, 'unknown')).toBeNull(); 109 109 + }); 110 110 + }); 111 111 + 112 112 + describe('canPerform', () => { 113 113 + it('owner can admin', () => { 114 114 + expect(canPerform(PERMS, 'alice', 'admin')).toBe(true); 115 115 + }); 116 116 + 117 117 + it('editor can edit but not admin', () => { 118 118 + expect(canPerform(PERMS, 'bob', 'edit')).toBe(true); 119 119 + expect(canPerform(PERMS, 'bob', 'admin')).toBe(false); 120 120 + }); 121 121 + 122 122 + it('viewer can only view', () => { 123 123 + expect(canPerform(PERMS, 'carol', 'view')).toBe(true); 124 124 + expect(canPerform(PERMS, 'carol', 'edit')).toBe(false); 125 125 + }); 126 126 + 127 127 + it('unknown user cannot do anything', () => { 128 128 + expect(canPerform(PERMS, 'unknown', 'view')).toBe(false); 129 129 + }); 130 130 + }); 131 131 + 132 132 + describe('canGrantRole', () => { 133 133 + it('owner can grant any role', () => { 134 134 + expect(canGrantRole('owner', 'editor')).toBe(true); 135 135 + expect(canGrantRole('owner', 'owner')).toBe(true); 136 136 + }); 137 137 + 138 138 + it('editor cannot grant owner', () => { 139 139 + expect(canGrantRole('editor', 'owner')).toBe(false); 140 140 + expect(canGrantRole('editor', 'editor')).toBe(true); 141 141 + expect(canGrantRole('editor', 'viewer')).toBe(true); 142 142 + }); 143 143 + }); 144 144 + 145 145 + describe('share links', () => { 146 146 + it('creates a valid share link', () => { 147 147 + const link = createShareLink('doc-1', 'viewer', 'alice', {}, 5000); 148 148 + expect(link.docId).toBe('doc-1'); 149 149 + expect(link.role).toBe('viewer'); 150 150 + expect(link.useCount).toBe(0); 151 151 + expect(isShareLinkValid(link, 6000)).toBe(true); 152 152 + }); 153 153 + 154 154 + it('detects expired link', () => { 155 155 + const link = createShareLink('doc-1', 'viewer', 'alice', { expiresAt: 5000 }, 1000); 156 156 + expect(isShareLinkValid(link, 6000)).toBe(false); 157 157 + }); 158 158 + 159 159 + it('detects max uses reached', () => { 160 160 + let link = createShareLink('doc-1', 'viewer', 'alice', { maxUses: 2 }, 1000); 161 161 + link = useShareLink(link); 162 162 + link = useShareLink(link); 163 163 + expect(isShareLinkValid(link)).toBe(false); 164 164 + }); 165 165 + 166 166 + it('increments use count', () => { 167 167 + const link = createShareLink('doc-1', 'viewer', 'alice'); 168 168 + const used = useShareLink(link); 169 169 + expect(used.useCount).toBe(1); 170 170 + }); 171 171 + }); 172 172 + 173 173 + describe('getUsersByRole / countByRole', () => { 174 174 + it('filters by role', () => { 175 175 + expect(getUsersByRole(PERMS, 'editor')).toHaveLength(1); 176 176 + expect(getUsersByRole(PERMS, 'viewer')).toHaveLength(1); 177 177 + }); 178 178 + 179 179 + it('counts by role', () => { 180 180 + const counts = countByRole(PERMS); 181 181 + expect(counts.owner).toBe(1); 182 182 + expect(counts.editor).toBe(1); 183 183 + expect(counts.viewer).toBe(1); 184 184 + expect(counts.commenter).toBe(0); 185 185 + }); 186 186 + }); 187 187 + });