@checkstack/auth-common 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,79 @@
1
1
  # @checkstack/auth-common
2
2
 
3
+ ## 0.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 9faec1f: # Unified AccessRule Terminology Refactoring
8
+
9
+ This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
10
+
11
+ ## Changes
12
+
13
+ ### Core Infrastructure (`@checkstack/common`)
14
+
15
+ - Introduced `AccessRule` interface as the primary access control type
16
+ - Added `accessPair()` helper for creating read/manage access rule pairs
17
+ - Added `access()` builder for individual access rules
18
+ - Replaced `Permission` type with `AccessRule` throughout
19
+
20
+ ### API Changes
21
+
22
+ - `env.registerPermissions()` → `env.registerAccessRules()`
23
+ - `meta.permissions` → `meta.access` in RPC contracts
24
+ - `usePermission()` → `useAccess()` in frontend hooks
25
+ - Route `permission:` field → `accessRule:` field
26
+
27
+ ### UI Changes
28
+
29
+ - "Roles & Permissions" tab → "Roles & Access Rules"
30
+ - "You don't have permission..." → "You don't have access..."
31
+ - All permission-related UI text updated
32
+
33
+ ### Documentation & Templates
34
+
35
+ - Updated 18 documentation files with AccessRule terminology
36
+ - Updated 7 scaffolding templates with `accessPair()` pattern
37
+ - All code examples use new AccessRule API
38
+
39
+ ## Migration Guide
40
+
41
+ ### Backend Plugins
42
+
43
+ ```diff
44
+ - import { permissionList } from "./permissions";
45
+ - env.registerPermissions(permissionList);
46
+ + import { accessRules } from "./access";
47
+ + env.registerAccessRules(accessRules);
48
+ ```
49
+
50
+ ### RPC Contracts
51
+
52
+ ```diff
53
+ - .meta({ userType: "user", permissions: [permissions.read.id] })
54
+ + .meta({ userType: "user", access: [access.read] })
55
+ ```
56
+
57
+ ### Frontend Hooks
58
+
59
+ ```diff
60
+ - const canRead = accessApi.usePermission(permissions.read.id);
61
+ + const canRead = accessApi.useAccess(access.read);
62
+ ```
63
+
64
+ ### Routes
65
+
66
+ ```diff
67
+ - permission: permissions.entityRead.id,
68
+ + accessRule: access.read,
69
+ ```
70
+
71
+ ### Patch Changes
72
+
73
+ - Updated dependencies [9faec1f]
74
+ - Updated dependencies [f533141]
75
+ - @checkstack/common@0.2.0
76
+
3
77
  ## 0.1.0
4
78
 
5
79
  ### Minor Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@checkstack/auth-common",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
package/src/access.ts ADDED
@@ -0,0 +1,91 @@
1
+ import { access, accessPair, type AccessRule } from "@checkstack/common";
2
+
3
+ /**
4
+ * Access rules for the Auth plugin.
5
+ *
6
+ * Auth has fine-grained access rules for different operations
7
+ * on users, roles, teams, strategies, etc.
8
+ */
9
+ export const authAccess = {
10
+ /**
11
+ * User management access rules.
12
+ */
13
+ users: {
14
+ read: access("users", "read", "List all users"),
15
+ create: access(
16
+ "users.create",
17
+ "manage",
18
+ "Create new users (credential strategy)"
19
+ ),
20
+ manage: access("users", "manage", "Delete users"),
21
+ },
22
+
23
+ /**
24
+ * Role management access rules.
25
+ */
26
+ roles: {
27
+ read: access("roles", "read", "Read and list roles"),
28
+ create: access("roles.create", "manage", "Create new roles"),
29
+ update: access(
30
+ "roles.update",
31
+ "manage",
32
+ "Update role names and access rules"
33
+ ),
34
+ delete: access("roles.delete", "manage", "Delete roles"),
35
+ manage: access("roles", "manage", "Assign roles to users"),
36
+ },
37
+
38
+ /**
39
+ * Authentication strategy management.
40
+ */
41
+ strategies: access(
42
+ "strategies",
43
+ "manage",
44
+ "Manage authentication strategies and settings"
45
+ ),
46
+
47
+ /**
48
+ * Registration settings management.
49
+ */
50
+ registration: access(
51
+ "registration",
52
+ "manage",
53
+ "Manage user registration settings"
54
+ ),
55
+
56
+ /**
57
+ * External application management.
58
+ */
59
+ applications: access(
60
+ "applications",
61
+ "manage",
62
+ "Create, update, delete, and view external applications"
63
+ ),
64
+
65
+ /**
66
+ * Team management access rules.
67
+ */
68
+ teams: accessPair("teams", {
69
+ read: "View teams and team memberships",
70
+ manage: "Create, delete, and manage all teams and resource access",
71
+ }),
72
+ };
73
+
74
+ /**
75
+ * All access rules for registration with the plugin system.
76
+ */
77
+ export const authAccessRules: AccessRule[] = [
78
+ authAccess.users.read,
79
+ authAccess.users.create,
80
+ authAccess.users.manage,
81
+ authAccess.roles.read,
82
+ authAccess.roles.create,
83
+ authAccess.roles.update,
84
+ authAccess.roles.delete,
85
+ authAccess.roles.manage,
86
+ authAccess.strategies,
87
+ authAccess.registration,
88
+ authAccess.applications,
89
+ authAccess.teams.read,
90
+ authAccess.teams.manage,
91
+ ];
package/src/index.ts CHANGED
@@ -1,4 +1,4 @@
1
- export * from "./permissions";
1
+ export * from "./access";
2
2
  export * from "./rpc-contract";
3
3
  export * from "./plugin-metadata";
4
4
  export * from "./schemas";
@@ -5,7 +5,7 @@ import {
5
5
  lucideIconSchema,
6
6
  } from "@checkstack/common";
7
7
  import { z } from "zod";
8
- import { permissions } from "./permissions";
8
+ import { authAccess } from "./access";
9
9
  import { pluginMetadata } from "./plugin-metadata";
10
10
 
11
11
  // Base builder with full metadata support
@@ -23,12 +23,12 @@ const RoleDtoSchema = z.object({
23
23
  id: z.string(),
24
24
  name: z.string(),
25
25
  description: z.string().optional().nullable(),
26
- permissions: z.array(z.string()),
26
+ accessRules: z.array(z.string()),
27
27
  isSystem: z.boolean().optional(),
28
28
  isAssignable: z.boolean().optional(), // False for anonymous role
29
29
  });
30
30
 
31
- const PermissionDtoSchema = z.object({
31
+ const AccessRuleDtoSchema = z.object({
32
32
  id: z.string(),
33
33
  description: z.string().optional(),
34
34
  });
@@ -118,33 +118,33 @@ export const authContract = {
118
118
  .output(RegistrationStatusSchema),
119
119
 
120
120
  // ==========================================================================
121
- // AUTHENTICATED ENDPOINTS (userType: "authenticated" - no specific permission)
121
+ // AUTHENTICATED ENDPOINTS (userType: "authenticated" - no specific access rule)
122
122
  // ==========================================================================
123
123
 
124
- permissions: _base
125
- .meta({ userType: "authenticated" }) // Any authenticated user can check their own permissions
126
- .output(z.object({ permissions: z.array(z.string()) })),
124
+ accessRules: _base
125
+ .meta({ userType: "authenticated" }) // Any authenticated user can check their own access rules
126
+ .output(z.object({ accessRules: z.array(z.string()) })),
127
127
 
128
128
  // ==========================================================================
129
- // USER MANAGEMENT (userType: "user" with permissions)
129
+ // USER MANAGEMENT (userType: "user" with access)
130
130
  // ==========================================================================
131
131
 
132
132
  getUsers: _base
133
- .meta({ userType: "user", permissions: [permissions.usersRead.id] })
133
+ .meta({ userType: "user", access: [authAccess.users.read] })
134
134
  .output(z.array(UserDtoSchema)),
135
135
 
136
136
  deleteUser: _base
137
- .meta({ userType: "user", permissions: [permissions.usersManage.id] })
137
+ .meta({ userType: "user", access: [authAccess.users.manage] })
138
138
  .input(z.string())
139
139
  .output(z.void()),
140
140
 
141
141
  createCredentialUser: _base
142
- .meta({ userType: "user", permissions: [permissions.usersCreate.id] })
142
+ .meta({ userType: "user", access: [authAccess.users.create] })
143
143
  .input(CreateCredentialUserInputSchema)
144
144
  .output(CreateCredentialUserOutputSchema),
145
145
 
146
146
  updateUserRoles: _base
147
- .meta({ userType: "user", permissions: [permissions.usersManage.id] })
147
+ .meta({ userType: "user", access: [authAccess.users.manage] })
148
148
  .input(
149
149
  z.object({
150
150
  userId: z.string(),
@@ -154,55 +154,55 @@ export const authContract = {
154
154
  .output(z.void()),
155
155
 
156
156
  // ==========================================================================
157
- // ROLE MANAGEMENT (userType: "user" with permissions)
157
+ // ROLE MANAGEMENT (userType: "user" with access)
158
158
  // ==========================================================================
159
159
 
160
160
  getRoles: _base
161
- .meta({ userType: "user", permissions: [permissions.rolesRead.id] })
161
+ .meta({ userType: "user", access: [authAccess.roles.read] })
162
162
  .output(z.array(RoleDtoSchema)),
163
163
 
164
- getPermissions: _base
165
- .meta({ userType: "user", permissions: [permissions.rolesRead.id] })
166
- .output(z.array(PermissionDtoSchema)),
164
+ getAccessRules: _base
165
+ .meta({ userType: "user", access: [authAccess.roles.read] })
166
+ .output(z.array(AccessRuleDtoSchema)),
167
167
 
168
168
  createRole: _base
169
- .meta({ userType: "user", permissions: [permissions.rolesCreate.id] })
169
+ .meta({ userType: "user", access: [authAccess.roles.create] })
170
170
  .input(
171
171
  z.object({
172
172
  name: z.string(),
173
173
  description: z.string().optional(),
174
- permissions: z.array(z.string()),
174
+ accessRules: z.array(z.string()),
175
175
  })
176
176
  )
177
177
  .output(z.void()),
178
178
 
179
179
  updateRole: _base
180
- .meta({ userType: "user", permissions: [permissions.rolesUpdate.id] })
180
+ .meta({ userType: "user", access: [authAccess.roles.update] })
181
181
  .input(
182
182
  z.object({
183
183
  id: z.string(),
184
184
  name: z.string().optional(),
185
185
  description: z.string().optional(),
186
- permissions: z.array(z.string()),
186
+ accessRules: z.array(z.string()),
187
187
  })
188
188
  )
189
189
  .output(z.void()),
190
190
 
191
191
  deleteRole: _base
192
- .meta({ userType: "user", permissions: [permissions.rolesDelete.id] })
192
+ .meta({ userType: "user", access: [authAccess.roles.delete] })
193
193
  .input(z.string())
194
194
  .output(z.void()),
195
195
 
196
196
  // ==========================================================================
197
- // STRATEGY MANAGEMENT (userType: "user" with permissions)
197
+ // STRATEGY MANAGEMENT (userType: "user" with access)
198
198
  // ==========================================================================
199
199
 
200
200
  getStrategies: _base
201
- .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
201
+ .meta({ userType: "user", access: [authAccess.strategies] })
202
202
  .output(z.array(StrategyDtoSchema)),
203
203
 
204
204
  updateStrategy: _base
205
- .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
205
+ .meta({ userType: "user", access: [authAccess.strategies] })
206
206
  .input(
207
207
  z.object({
208
208
  id: z.string(),
@@ -213,24 +213,24 @@ export const authContract = {
213
213
  .output(z.object({ success: z.boolean() })),
214
214
 
215
215
  reloadAuth: _base
216
- .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
216
+ .meta({ userType: "user", access: [authAccess.strategies] })
217
217
  .output(z.object({ success: z.boolean() })),
218
218
 
219
219
  // ==========================================================================
220
- // REGISTRATION MANAGEMENT (userType: "user" with permissions)
220
+ // REGISTRATION MANAGEMENT (userType: "user" with access)
221
221
  // ==========================================================================
222
222
 
223
223
  getRegistrationSchema: _base
224
224
  .meta({
225
225
  userType: "user",
226
- permissions: [permissions.registrationManage.id],
226
+ access: [authAccess.registration],
227
227
  })
228
228
  .output(z.record(z.string(), z.unknown())),
229
229
 
230
230
  setRegistrationStatus: _base
231
231
  .meta({
232
232
  userType: "user",
233
- permissions: [permissions.registrationManage.id],
233
+ access: [authAccess.registration],
234
234
  })
235
235
  .input(RegistrationStatusSchema)
236
236
  .output(z.object({ success: z.boolean() })),
@@ -240,10 +240,10 @@ export const authContract = {
240
240
  // ==========================================================================
241
241
 
242
242
  /**
243
- * Get permissions assigned to the anonymous role.
244
- * Used by core AuthService for permission checks on public endpoints.
243
+ * Get access rules assigned to the anonymous role.
244
+ * Used by core AuthService for access checks on public endpoints.
245
245
  */
246
- getAnonymousPermissions: _base
246
+ getAnonymousAccessRules: _base
247
247
  .meta({ userType: "service" })
248
248
  .output(z.array(z.string())),
249
249
 
@@ -293,28 +293,28 @@ export const authContract = {
293
293
  ),
294
294
 
295
295
  /**
296
- * Filter a list of user IDs to only those who have a specific permission.
296
+ * Filter a list of user IDs to only those who have a specific access rule.
297
297
  * Used by SignalService to send signals only to authorized users.
298
298
  */
299
- filterUsersByPermission: _base
299
+ filterUsersByAccessRule: _base
300
300
  .meta({ userType: "service" })
301
301
  .input(
302
302
  z.object({
303
303
  userIds: z.array(z.string()),
304
- permission: z.string(), // Fully-qualified permission ID
304
+ accessRule: z.string(), // Fully-qualified access rule ID
305
305
  })
306
306
  )
307
307
  .output(z.array(z.string())), // Returns filtered user IDs
308
308
 
309
309
  // ==========================================================================
310
- // APPLICATION MANAGEMENT (userType: "user" with permissions)
310
+ // APPLICATION MANAGEMENT (userType: "user" with access)
311
311
  // External API applications (API keys) with RBAC integration
312
312
  // ==========================================================================
313
313
 
314
314
  getApplications: _base
315
315
  .meta({
316
316
  userType: "user",
317
- permissions: [permissions.applicationsManage.id],
317
+ access: [authAccess.applications],
318
318
  })
319
319
  .output(
320
320
  z.array(
@@ -333,7 +333,7 @@ export const authContract = {
333
333
  createApplication: _base
334
334
  .meta({
335
335
  userType: "user",
336
- permissions: [permissions.applicationsManage.id],
336
+ access: [authAccess.applications],
337
337
  })
338
338
  .input(
339
339
  z.object({
@@ -358,7 +358,7 @@ export const authContract = {
358
358
  updateApplication: _base
359
359
  .meta({
360
360
  userType: "user",
361
- permissions: [permissions.applicationsManage.id],
361
+ access: [authAccess.applications],
362
362
  })
363
363
  .input(
364
364
  z.object({
@@ -373,7 +373,7 @@ export const authContract = {
373
373
  deleteApplication: _base
374
374
  .meta({
375
375
  userType: "user",
376
- permissions: [permissions.applicationsManage.id],
376
+ access: [authAccess.applications],
377
377
  })
378
378
  .input(z.string())
379
379
  .output(z.void()),
@@ -381,21 +381,21 @@ export const authContract = {
381
381
  regenerateApplicationSecret: _base
382
382
  .meta({
383
383
  userType: "user",
384
- permissions: [permissions.applicationsManage.id],
384
+ access: [authAccess.applications],
385
385
  })
386
386
  .input(z.string())
387
387
  .output(z.object({ secret: z.string() })), // New secret - shown once
388
388
 
389
389
  // ==========================================================================
390
- // TEAM MANAGEMENT (userType: "authenticated" with permissions)
390
+ // TEAM MANAGEMENT (userType: "authenticated" with access)
391
391
  // Resource-level access control via teams
392
- // Both users and applications can manage teams with proper permissions
392
+ // Both users and applications can manage teams with proper access
393
393
  // ==========================================================================
394
394
 
395
395
  getTeams: _base
396
396
  .meta({
397
397
  userType: "authenticated",
398
- permissions: [permissions.teamsRead.id],
398
+ access: [authAccess.teams.read],
399
399
  })
400
400
  .output(
401
401
  z.array(
@@ -412,7 +412,7 @@ export const authContract = {
412
412
  getTeam: _base
413
413
  .meta({
414
414
  userType: "authenticated",
415
- permissions: [permissions.teamsRead.id],
415
+ access: [authAccess.teams.read],
416
416
  })
417
417
  .input(z.object({ teamId: z.string() }))
418
418
  .output(
@@ -434,7 +434,7 @@ export const authContract = {
434
434
  createTeam: _base
435
435
  .meta({
436
436
  userType: "authenticated",
437
- permissions: [permissions.teamsManage.id],
437
+ access: [authAccess.teams.manage],
438
438
  })
439
439
  .input(
440
440
  z.object({
@@ -447,7 +447,7 @@ export const authContract = {
447
447
  updateTeam: _base
448
448
  .meta({
449
449
  userType: "authenticated",
450
- permissions: [permissions.teamsRead.id],
450
+ access: [authAccess.teams.read],
451
451
  })
452
452
  .input(
453
453
  z.object({
@@ -461,7 +461,7 @@ export const authContract = {
461
461
  deleteTeam: _base
462
462
  .meta({
463
463
  userType: "authenticated",
464
- permissions: [permissions.teamsManage.id],
464
+ access: [authAccess.teams.manage],
465
465
  })
466
466
  .input(z.string())
467
467
  .output(z.void()),
@@ -469,7 +469,7 @@ export const authContract = {
469
469
  addUserToTeam: _base
470
470
  .meta({
471
471
  userType: "authenticated",
472
- permissions: [permissions.teamsRead.id],
472
+ access: [authAccess.teams.read],
473
473
  })
474
474
  .input(z.object({ teamId: z.string(), userId: z.string() }))
475
475
  .output(z.void()),
@@ -477,7 +477,7 @@ export const authContract = {
477
477
  removeUserFromTeam: _base
478
478
  .meta({
479
479
  userType: "authenticated",
480
- permissions: [permissions.teamsRead.id],
480
+ access: [authAccess.teams.read],
481
481
  })
482
482
  .input(z.object({ teamId: z.string(), userId: z.string() }))
483
483
  .output(z.void()),
@@ -485,7 +485,7 @@ export const authContract = {
485
485
  addTeamManager: _base
486
486
  .meta({
487
487
  userType: "authenticated",
488
- permissions: [permissions.teamsManage.id],
488
+ access: [authAccess.teams.manage],
489
489
  })
490
490
  .input(z.object({ teamId: z.string(), userId: z.string() }))
491
491
  .output(z.void()),
@@ -493,7 +493,7 @@ export const authContract = {
493
493
  removeTeamManager: _base
494
494
  .meta({
495
495
  userType: "authenticated",
496
- permissions: [permissions.teamsManage.id],
496
+ access: [authAccess.teams.manage],
497
497
  })
498
498
  .input(z.object({ teamId: z.string(), userId: z.string() }))
499
499
  .output(z.void()),
@@ -501,7 +501,7 @@ export const authContract = {
501
501
  getResourceTeamAccess: _base
502
502
  .meta({
503
503
  userType: "authenticated",
504
- permissions: [permissions.teamsRead.id],
504
+ access: [authAccess.teams.read],
505
505
  })
506
506
  .input(z.object({ resourceType: z.string(), resourceId: z.string() }))
507
507
  .output(
@@ -518,7 +518,7 @@ export const authContract = {
518
518
  setResourceTeamAccess: _base
519
519
  .meta({
520
520
  userType: "authenticated",
521
- permissions: [permissions.teamsManage.id],
521
+ access: [authAccess.teams.manage],
522
522
  })
523
523
  .input(
524
524
  z.object({
@@ -534,7 +534,7 @@ export const authContract = {
534
534
  removeResourceTeamAccess: _base
535
535
  .meta({
536
536
  userType: "authenticated",
537
- permissions: [permissions.teamsManage.id],
537
+ access: [authAccess.teams.manage],
538
538
  })
539
539
  .input(
540
540
  z.object({
@@ -549,7 +549,7 @@ export const authContract = {
549
549
  getResourceAccessSettings: _base
550
550
  .meta({
551
551
  userType: "authenticated",
552
- permissions: [permissions.teamsRead.id],
552
+ access: [authAccess.teams.read],
553
553
  })
554
554
  .input(z.object({ resourceType: z.string(), resourceId: z.string() }))
555
555
  .output(z.object({ teamOnly: z.boolean() })),
@@ -557,7 +557,7 @@ export const authContract = {
557
557
  setResourceAccessSettings: _base
558
558
  .meta({
559
559
  userType: "authenticated",
560
- permissions: [permissions.teamsManage.id],
560
+ access: [authAccess.teams.manage],
561
561
  })
562
562
  .input(
563
563
  z.object({
@@ -581,7 +581,7 @@ export const authContract = {
581
581
  resourceType: z.string(),
582
582
  resourceId: z.string(),
583
583
  action: z.enum(["read", "manage"]),
584
- hasGlobalPermission: z.boolean(),
584
+ hasGlobalAccess: z.boolean(),
585
585
  })
586
586
  )
587
587
  .output(z.object({ hasAccess: z.boolean() })),
@@ -595,7 +595,7 @@ export const authContract = {
595
595
  resourceType: z.string(),
596
596
  resourceIds: z.array(z.string()),
597
597
  action: z.enum(["read", "manage"]),
598
- hasGlobalPermission: z.boolean(),
598
+ hasGlobalAccess: z.boolean(),
599
599
  })
600
600
  )
601
601
  .output(z.array(z.string())),
@@ -1,58 +0,0 @@
1
- import type { Permission } from "@checkstack/common";
2
-
3
- export const permissions = {
4
- usersRead: {
5
- id: "users.read",
6
- description: "List all users",
7
- },
8
- usersCreate: {
9
- id: "users.create",
10
- description: "Create new users (credential strategy)",
11
- },
12
- usersManage: {
13
- id: "users.manage",
14
- description: "Delete users",
15
- },
16
- rolesRead: {
17
- id: "roles.read",
18
- description: "Read and list roles",
19
- },
20
- rolesCreate: {
21
- id: "roles.create",
22
- description: "Create new roles",
23
- },
24
- rolesUpdate: {
25
- id: "roles.update",
26
- description: "Update role names and permissions",
27
- },
28
- rolesDelete: {
29
- id: "roles.delete",
30
- description: "Delete roles",
31
- },
32
- rolesManage: {
33
- id: "roles.manage",
34
- description: "Assign roles to users",
35
- },
36
- strategiesManage: {
37
- id: "strategies.manage",
38
- description: "Manage authentication strategies and settings",
39
- },
40
- registrationManage: {
41
- id: "registration.manage",
42
- description: "Manage user registration settings",
43
- },
44
- applicationsManage: {
45
- id: "applications.manage",
46
- description: "Create, update, delete, and view external applications",
47
- },
48
- teamsRead: {
49
- id: "teams.read",
50
- description: "View teams and team memberships",
51
- },
52
- teamsManage: {
53
- id: "teams.manage",
54
- description: "Create, delete, and manage all teams and resource access",
55
- },
56
- } satisfies Record<string, Permission>;
57
-
58
- export const permissionList = Object.values(permissions);