@jskit-ai/workspaces-core 0.1.211 → 0.1.213

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.1.211",
+  "version": "0.1.213",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -18,11 +18,11 @@
     "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.233",
-    "@jskit-ai/json-rest-api-core": "0.1.177",
-    "@jskit-ai/resource-core": "0.1.175",
-    "@jskit-ai/resource-crud-core": "0.1.175",
-    "@jskit-ai/users-core": "0.1.246",
+    "@jskit-ai/database-runtime": "0.1.235",
+    "@jskit-ai/json-rest-api-core": "0.1.179",
+    "@jskit-ai/resource-core": "0.1.177",
+    "@jskit-ai/resource-crud-core": "0.1.177",
+    "@jskit-ai/users-core": "0.1.248",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
@@ -169,8 +169,8 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.1.231",
-    "@jskit-ai/http-runtime": "0.1.231",
-    "@jskit-ai/kernel": "0.1.233"
+    "@jskit-ai/auth-core": "0.1.233",
+    "@jskit-ai/http-runtime": "0.1.233",
+    "@jskit-ai/kernel": "0.1.235"
   }
 }

package/patterns/workspace-server/PATTERN.md

@@ -28,6 +28,26 @@ member permissions, personal-workspace behavior, and surface access rules.
 Use workspace routes, resources, scope helpers, tenancy profiles, and settings
 contracts exported by `@jskit-ai/workspaces-core`.
 
+## Role display labels
+
+Each `roleCatalog.roles[roleId]` definition may include an optional string
+`label`. JSKIT trims it and preserves nonempty labels in role descriptors,
+catalogue clones and Members/Workspace Settings responses. Labels are display
+metadata; they do not inherit from a parent role. Missing, blank or non-string
+labels keep the existing role-title fallback.
+
+Shared Members invitation and member-role selectors show the label but submit
+the role id. Pending invitation captions, workspace role captions and the
+default invitation email use the same configured labels. Pending invitation
+responses expose optional `roleLabel` alongside the unchanged `roleSid`.
+Applications with their own invitation renderer may use its optional
+`roleLabel` input; `roleSid` remains the stored role id.
+
+Keep existing permissions, inheritance, assignability and
+`workspace.defaultInviteRole` when adding a label. `owner` remains
+nonassignable. Custom roles, including specialised Training roles, are ordinary
+catalogue entries. Updating labels requires no database migration.
+
 ## Transactional invitation participation
 
 Through `workspaces.core`, register one callback during feature setup with

package/patterns/workspace-server/example/config/roles.js

@@ -8,6 +8,7 @@ export const roleCatalog = {
       permissions: ["*"]
     },
     admin: {
+      label: "Administrator",
       assignable: true,
       inherits: "member",
       permissions: [
@@ -20,6 +21,7 @@ export const roleCatalog = {
       ]
     },
     member: {
+      label: "Team member",
       assignable: true,
       permissions: ["workspace.settings.view"]
     }

package/src/server/WorkspacesFeature.js

@@ -105,7 +105,8 @@ function createWorkspacesRuntime({ config, env, jsonRestApi } = {}) {
   });
   const workspacePendingInvitationsService = createWorkspacePendingInvitationsService({
     workspaceInvitesRepository,
-    workspaceMembershipsRepository
+    workspaceMembershipsRepository,
+    roleCatalog
   });
   const workspaceMembersService = createWorkspaceMembersService({
     workspaceMembershipsRepository,

package/src/server/common/formatters/workspaceFormatter.js

@@ -2,13 +2,16 @@ import { resolveWorkspaceThemePalettes } from "@jskit-ai/workspaces-core/shared/
 import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
 import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 
-function mapWorkspaceSummary(workspace, membership) {
+function mapWorkspaceSummary(workspace, membership, roleCatalog = null) {
+  const roleSid = normalizeLowerText(membership?.roleSid || "member") || "member";
+  const roleLabel = roleCatalog?.roles?.find((role) => role.id === roleSid)?.label;
   return {
     id: normalizeRecordId(workspace.id, { fallback: "" }),
     slug: normalizeText(workspace.slug),
     name: normalizeText(workspace.name),
     avatarUrl: normalizeText(workspace.avatarUrl),
-    roleSid: normalizeLowerText(membership?.roleSid || "member") || "member",
+    roleSid,
+    ...(roleLabel ? { roleLabel } : {}),
     isAccessible: normalizeLowerText(membership?.status || "active") === "active"
   };
 }

package/src/server/common/services/workspaceContextService.js

@@ -5,7 +5,8 @@ import {
   resolveTenancyProfile
 } from "../../../shared/tenancyProfile.js";
 import {
-  resolveRolePermissions
+  resolveRolePermissions,
+  createWorkspaceRoleCatalog
 } from "../../../shared/roles.js";
 import {
   mapWorkspaceSummary
@@ -144,8 +145,13 @@ function createService({
     }
 
     const list = await workspacesRepository.listForUserId(normalizedUserId, options);
+    const roleCatalog = createWorkspaceRoleCatalog(appConfig);
     const accessible = list
-      .map((entry) => mapWorkspaceSummary(entry, { roleSid: entry.roleSid, status: entry.membershipStatus }))
+      .map((entry) => mapWorkspaceSummary(
+        entry,
+        { roleSid: entry.roleSid, status: entry.membershipStatus },
+        roleCatalog
+      ))
       .filter((entry) => entry.isAccessible);
 
     return accessible;

package/src/server/workspaceMembers/defaultWorkspaceInviteEmail.js

@@ -12,11 +12,12 @@ function renderDefaultWorkspaceInviteEmail({
   workspace = {},
   inviter = null,
   roleSid = "member",
+  roleLabel = "",
   expiresAt = ""
 } = {}) {
   const workspaceName = String(workspace?.name || workspace?.slug || "the workspace").trim() || "the workspace";
   const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
-  const roleName = String(roleSid || "member").trim() || "member";
+  const roleName = (typeof roleLabel === "string" ? roleLabel.trim() : "") || String(roleSid || "member").trim() || "member";
   const expiryText = expiresAt ? `This invitation expires at ${expiresAt}.` : "";
   const intro = inviterName
     ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`

package/src/server/workspaceMembers/workspaceMembersService.js

@@ -110,12 +110,14 @@ function createService({
     }
 
     try {
+      const roleLabel = resolvedRoleCatalog.roles?.find((role) => role.id === invite.roleSid)?.label;
       const message = await resolvedWorkspaceInviteEmailTemplate({
         email: invite.email,
         inviteUrl,
         workspace: mapWorkspaceSummary(workspace),
         inviter: user || null,
         roleSid: invite.roleSid,
+        ...(roleLabel ? { roleLabel } : {}),
         expiresAt: invite.expiresAt
       });
       const result = await resolvedWorkspaceInviteMailer.sendWorkspaceInvite({

package/src/server/workspacePendingInvitations/workspacePendingInvitationsService.js

@@ -6,7 +6,8 @@ import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 
 function createService({
   workspaceInvitesRepository,
-  workspaceMembershipsRepository
+  workspaceMembershipsRepository,
+  roleCatalog = null
 } = {}) {
   if (!workspaceInvitesRepository || !workspaceMembershipsRepository) {
     throw new Error("workspacePendingInvitationsService requires invite and membership repositories.");
@@ -15,6 +16,12 @@ function createService({
   let acceptanceParticipant = null;
   let registrationClosed = false;
 
+  function roleLabelMetadata(roleSid) {
+    const role = roleCatalog?.roles?.find((entry) => entry.id === (normalizeLowerText(roleSid || "member") || "member"));
+    const label = typeof role?.label === "string" ? role.label.trim() : "";
+    return label ? { roleLabel: label } : {};
+  }
+
   function registerAcceptanceParticipant(participant) {
     if (typeof participant !== "function") {
       throw new TypeError("Acceptance participant must be a function.");
@@ -123,6 +130,7 @@ function createService({
       email: normalizeLowerText(invite.email),
       maskedEmail: maskInviteEmail(invite.email),
       roleSid: normalizeLowerText(invite.roleSid || "member") || "member",
+      ...roleLabelMetadata(invite.roleSid),
       expiresAt: invite.expiresAt || null,
       workspace: {
         id: normalizeRecordId(invite.workspaceId, { fallback: "" }),
@@ -149,6 +157,7 @@ function createService({
       workspaceName: normalizeText(invite.workspaceName || invite.workspaceSlug),
       workspaceAvatarUrl: normalizeText(invite.workspaceAvatarUrl),
       roleSid: normalizeLowerText(invite.roleSid || "member") || "member",
+      ...roleLabelMetadata(invite.roleSid),
       status: normalizeLowerText(invite.status || "pending") || "pending",
       expiresAt: invite.expiresAt || null,
       token: encodeInviteTokenHash(tokenHash)

package/src/shared/resources/workspacePendingInvitationsResource.js

@@ -34,6 +34,7 @@ const invitationResolveOutputSchema = createSchema({
   email: { type: "string", required: true },
   maskedEmail: { type: "string", required: true },
   roleSid: { type: "string", required: true },
+  roleLabel: { type: "string", required: false },
   expiresAt: { type: "string", required: false, nullable: true, minLength: 1 },
   workspace: {
     type: "object",
@@ -53,6 +54,7 @@ const pendingInvitationsListOutputSchema = createSchema({
       workspaceName: { type: "string", required: true, minLength: 1, maxLength: 160 },
       workspaceAvatarUrl: { type: "string", required: true },
       roleSid: { type: "string", required: true, minLength: 1, maxLength: 64 },
+      roleLabel: { type: "string", required: false },
       status: { type: "string", required: true, minLength: 1, maxLength: 64 },
       expiresAt: { type: "string", required: false, nullable: true, minLength: 1 },
       token: { type: "string", required: true, minLength: 1 }

package/src/shared/resources/workspaceResource.js

@@ -33,6 +33,7 @@ const workspaceListItemSchema = createSchema({
   name: { type: "string", required: true, minLength: 1, maxLength: 160 },
   avatarUrl: { type: "string", required: true },
   roleSid: { type: "string", required: true, minLength: 1, maxLength: 64 },
+  roleLabel: { type: "string", required: false },
   isAccessible: { type: "boolean", required: true }
 });
 

package/src/shared/resources/workspaceRoleCatalogSchema.js

@@ -2,6 +2,7 @@ import { createSchema } from "json-rest-schema";
 
 const workspaceRoleDescriptorSchema = createSchema({
   id: { type: "string", required: true, minLength: 1, maxLength: 64 },
+  label: { type: "string", required: false },
   assignable: { type: "boolean", required: true },
   permissions: {
     type: "array",

package/src/shared/roles.js

@@ -47,11 +47,13 @@ function resolveInheritedRolePermissions(roleSid, configuredRoles = {}, seenRole
 
 function createRoleDescriptor(roleSid, configuredDefinition, configuredRoles = {}) {
   const source = asRecord(configuredDefinition);
+  const label = typeof source.label === "string" ? source.label.trim() : "";
   const assignable = roleSid === OWNER_ROLE_ID ? false : source.assignable === true;
   const permissions = resolveInheritedRolePermissions(roleSid, configuredRoles);
 
   return Object.freeze({
     id: roleSid,
+    ...(label ? { label } : {}),
     assignable,
     permissions: Object.freeze([...permissions])
   });
@@ -99,6 +101,7 @@ function createWorkspaceRoleCatalog(appConfig = {}) {
       roles.map((role) =>
         Object.freeze({
           id: role.id,
+          ...(role.label ? { label: role.label } : {}),
           assignable: role.assignable,
           permissions: Object.freeze([...role.permissions])
         })
@@ -117,6 +120,7 @@ function cloneWorkspaceRoleCatalog(roleCatalog = null) {
     roles: Array.isArray(source.roles)
       ? source.roles.map((role) => ({
           id: normalizeRoleId(role?.id),
+          ...(typeof role?.label === "string" && role.label.trim() ? { label: role.label.trim() } : {}),
           assignable: role?.assignable === true,
           permissions: Array.isArray(role?.permissions) ? [...role.permissions] : []
         }))
@@ -129,6 +133,7 @@ function listRoleDescriptors(appConfig = {}) {
   const roleCatalog = createWorkspaceRoleCatalog(appConfig);
   return roleCatalog.roles.map((role) => ({
     id: role.id,
+    ...(role.label ? { label: role.label } : {}),
     assignable: role.assignable,
     permissions: [...role.permissions]
   }));

package/test/roleLabels.test.js

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { encodeInviteTokenHash } from "@jskit-ai/auth-core/shared/inviteTokens";
+import { createWorkspaceRoleCatalog, cloneWorkspaceRoleCatalog, listRoleDescriptors } from "../src/shared/roles.js";
+import { workspaceMembersResource } from "../src/shared/resources/workspaceMembersResource.js";
+import { workspaceSettingsResource, WORKSPACE_SETTINGS_FIELD_KEYS } from "../src/shared/resources/workspaceSettingsResource.js";
+import { workspacePendingInvitationsResource } from "../src/shared/resources/workspacePendingInvitationsResource.js";
+import { createService as createMembersService } from "../src/server/workspaceMembers/workspaceMembersService.js";
+import { createService as createSettingsService } from "../src/server/workspaceSettings/workspaceSettingsService.js";
+import { createService as createPendingService } from "../src/server/workspacePendingInvitations/workspacePendingInvitationsService.js";
+import { renderDefaultWorkspaceInviteEmail } from "../src/server/workspaceMembers/defaultWorkspaceInviteEmail.js";
+
+const config = {
+  roleCatalog: {
+    workspace: { defaultInviteRole: "worker" },
+    roles: {
+      owner: { label: "Owner", assignable: true, permissions: ["*"] },
+      worker: { label: " Member ", assignable: true, permissions: ["training.view"] },
+      safety_manager: { label: "Operator", assignable: true, inherits: "worker", permissions: ["training.manage"] },
+      administrator: { label: "Controller", assignable: true, inherits: "safety_manager", permissions: ["workspace.members.manage"] },
+      training_assessor: { label: "Training assessor", assignable: true, permissions: ["training.assess"] }
+    }
+  }
+};
+const catalog = createWorkspaceRoleCatalog(config);
+const workspace = { id: "7", slug: "example", name: "Example", ownerUserId: "9", avatarUrl: "" };
+const expectedLabels = ["Owner", "Member", "Operator", "Controller", "Training assessor"];
+
+function output(resource, operation, value) {
+  return validateSchemaPayload(resource.operations[operation].output, value, { phase: "output" });
+}
+
+test("configured labels survive creation, cloning and listing without changing role policy", () => {
+  for (const roles of [catalog.roles, cloneWorkspaceRoleCatalog(catalog).roles, listRoleDescriptors(config)]) {
+    assert.deepEqual(roles.map((role) => role.label), expectedLabels);
+    assert.equal(roles[0].assignable, false);
+    assert.deepEqual(roles[2].permissions, ["training.view", "training.manage"]);
+    assert.deepEqual(roles[4].permissions, ["training.assess"]);
+  }
+  assert.equal(catalog.defaultInviteRole, "worker");
+  assert.equal(catalog.assignableRoleIds.includes("owner"), false);
+  assert.equal(Object.isFrozen(catalog.roles[1]), true);
+  const clone = cloneWorkspaceRoleCatalog(catalog);
+  clone.roles[1].label = "Edited";
+  assert.equal(catalog.roles[1].label, "Member");
+});
+
+test("missing, whitespace and non-string labels retain the original descriptor shape", () => {
+  const roles = createWorkspaceRoleCatalog({ roleCatalog: { roles: {
+    member: { assignable: true, permissions: [] },
+    blank: { label: "   ", permissions: [] },
+    invalid: { label: 123, permissions: [] }
+  } } }).roles;
+  assert.equal(roles.every((role) => !Object.hasOwn(role, "label")), true);
+  assert.deepEqual(cloneWorkspaceRoleCatalog({ roles }).roles, roles);
+});
+
+test("Members and Invitations response validation preserves labels and saved role IDs", async () => {
+  let savedRole = "worker";
+  const service = createMembersService({
+    roleCatalog: catalog,
+    inviteExpiresInMs: 60_000,
+    workspaceMembershipsRepository: {
+      async listActiveByWorkspaceId() {
+        return [{ userId: "11", roleSid: savedRole, status: "active", displayName: "Person", email: "person@example.com" }];
+      },
+      async findByWorkspaceIdAndUserId() { return { userId: "11", roleSid: savedRole, status: "active" }; },
+      async upsertMembership(_workspaceId, _userId, patch) { savedRole = patch.roleSid; }
+    },
+    workspaceInvitesRepository: { async listPendingByWorkspaceIdWithWorkspace() { return []; } }
+  });
+  for (const roleSid of ["worker", "safety_manager", "administrator", "training_assessor"]) {
+    await service.updateMemberRole(workspace, { memberUserId: "11", roleSid });
+    const reloaded = output(workspaceMembersResource, "membersList", await service.listMembers(workspace));
+    assert.equal(savedRole, roleSid);
+    assert.equal(reloaded.members[0].roleSid, roleSid);
+    assert.deepEqual(reloaded.roleCatalog.roles.map((role) => role.label), expectedLabels);
+  }
+  const roles = output(workspaceMembersResource, "rolesList", await service.listRoles());
+  assert.deepEqual(roles.roles.map((role) => role.label), expectedLabels);
+  const invites = output(workspaceMembersResource, "invitesList", await service.listInvites(workspace));
+  assert.deepEqual(invites.roleCatalog.roles.map((role) => role.label), expectedLabels);
+  await assert.rejects(service.updateMemberRole(workspace, { memberUserId: "11", roleSid: "Controller" }), /Validation failed/);
+  await assert.rejects(service.updateMemberRole(workspace, { memberUserId: "11", roleSid: "owner" }), /Validation failed/);
+});
+
+test("Workspace Settings response validation preserves configured labels", async () => {
+  const service = createSettingsService({
+    roleCatalog: catalog,
+    workspaceSettingsRepository: {
+      async ensureForWorkspaceId() {
+        return { ...Object.fromEntries(WORKSPACE_SETTINGS_FIELD_KEYS.map((key) => [key, "#123456"])), invitesEnabled: true };
+      }
+    }
+  });
+  const response = output(workspaceSettingsResource, "view", await service.getWorkspaceSettings(workspace, {
+    context: { actor: { id: "9" }, permissions: ["workspace.settings.view"] }
+  }));
+  assert.deepEqual(response.roleCatalog.roles.map((role) => role.label), expectedLabels);
+});
+
+test("pending and resolved invitation responses derive labels while acceptance stores the role ID", async () => {
+  const tokenHash = "a".repeat(64);
+  const token = encodeInviteTokenHash(tokenHash);
+  const invite = { id: "10", workspaceId: "7", workspaceSlug: "example", workspaceName: "Example", roleSid: "safety_manager", status: "pending", email: "person@example.com", expiresAt: "2099-01-01T00:00:00.000Z", tokenHash };
+  let membership;
+  const service = createPendingService({
+    roleCatalog: catalog,
+    workspaceInvitesRepository: {
+      async listPendingByEmail() { return [invite]; },
+      async findByTokenHashWithWorkspace() { return invite; },
+      async findPendingByTokenHash() { return invite; },
+      async withTransaction(work) { return work({}); },
+      async markAcceptedById() {}
+    },
+    workspaceMembershipsRepository: { async upsertMembership(_workspaceId, _userId, patch) { membership = patch; } }
+  });
+  const user = { id: "11", email: invite.email };
+  const pending = output(workspacePendingInvitationsResource, "list", { pendingInvites: await service.listPendingInvitesForUser(user) });
+  const resolved = output(workspacePendingInvitationsResource, "resolve", await service.resolveInviteByToken(token));
+  assert.equal(pending.pendingInvites[0].roleLabel, "Operator");
+  assert.equal(resolved.roleLabel, "Operator");
+  assert.equal(resolved.roleSid, "safety_manager");
+  await service.acceptInviteByToken({ user, token });
+  assert.deepEqual(membership, { roleSid: "safety_manager", status: "active" });
+  assert.equal(Object.hasOwn(invite, "roleLabel"), false);
+});
+
+test("default invitation email uses the configured label with HTML escaping and the original fallback", () => {
+  const labelled = renderDefaultWorkspaceInviteEmail({ roleSid: "worker", roleLabel: " Member <team> " });
+  assert.match(labelled.text, /as Member <team>/u);
+  assert.match(labelled.html, /as Member &lt;team&gt;/u);
+  assert.match(renderDefaultWorkspaceInviteEmail({ roleSid: "worker" }).text, /as worker/u);
+});