@jskit-ai/workspaces-core 0.1.81 → 0.1.82

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/workspaces-core",
-  version: "0.1.81",
+  version: "0.1.82",
   kind: "runtime",
   description: "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
   dependsOn: [
@@ -86,6 +86,11 @@ export default Object.freeze({
           path: "/api/workspaces",
           summary: "List workspaces visible to authenticated user."
         },
+        {
+          method: "GET",
+          path: "/api/workspace/invitations/resolve",
+          summary: "Resolve safe public workspace invitation metadata."
+        },
         {
           method: "GET",
           path: "/api/workspace/invitations/pending",
@@ -142,10 +147,10 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/json-rest-api-core": "0.1.50",
-        "@jskit-ai/resource-core": "0.1.50",
-        "@jskit-ai/resource-crud-core": "0.1.50",
-        "@jskit-ai/users-core": "0.1.115"
+        "@jskit-ai/json-rest-api-core": "0.1.51",
+        "@jskit-ai/resource-core": "0.1.51",
+        "@jskit-ai/resource-crud-core": "0.1.51",
+        "@jskit-ai/users-core": "0.1.116"
       },
       dev: {}
     },
@@ -191,6 +196,34 @@ export default Object.freeze({
         reason: "Install app-owned role catalog in a dedicated config file.",
         category: "workspaces-core",
         id: "users-core-app-owned-role-catalog-config"
+      },
+      {
+        from: "templates/packages/main/src/server/email/workspaceInviteEmail.js",
+        to: "packages/main/src/server/email/workspaceInviteEmail.js",
+        preserveOnRemove: true,
+        reason: "Install app-owned editable workspace invite email template.",
+        category: "workspaces-core",
+        id: "workspaces-core-main-workspace-invite-email-template"
+      }
+    ],
+    source: [
+      {
+        op: "ensure-import",
+        file: "config/server.js",
+        namedImports: ["renderWorkspaceInviteEmail"],
+        from: "../packages/main/src/server/email/workspaceInviteEmail.js",
+        reason: "Load app-owned workspace invite email renderer from packages/main.",
+        category: "workspaces-core",
+        id: "workspaces-core-server-config-workspace-invite-email-import"
+      },
+      {
+        op: "ensure-assignment",
+        file: "config/server.js",
+        target: "config.workspaceInviteEmailTemplate",
+        value: "renderWorkspaceInviteEmail",
+        reason: "Bind app-owned workspace invite email renderer into server config.",
+        category: "workspaces-core",
+        id: "workspaces-core-server-config-workspace-invite-email-template"
       }
     ],
     text: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.1.81",
+  "version": "0.1.82",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -18,14 +18,14 @@
     "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.1.104",
-    "@jskit-ai/database-runtime": "0.1.105",
-    "@jskit-ai/http-runtime": "0.1.104",
-    "@jskit-ai/json-rest-api-core": "0.1.50",
-    "@jskit-ai/kernel": "0.1.106",
-    "@jskit-ai/resource-crud-core": "0.1.50",
-    "@jskit-ai/resource-core": "0.1.50",
-    "@jskit-ai/users-core": "0.1.115",
+    "@jskit-ai/auth-core": "0.1.105",
+    "@jskit-ai/database-runtime": "0.1.106",
+    "@jskit-ai/http-runtime": "0.1.105",
+    "@jskit-ai/json-rest-api-core": "0.1.51",
+    "@jskit-ai/kernel": "0.1.107",
+    "@jskit-ai/resource-crud-core": "0.1.51",
+    "@jskit-ai/resource-core": "0.1.51",
+    "@jskit-ai/users-core": "0.1.116",
     "json-rest-schema": "1.x.x"
   }
 }

package/src/server/common/repositories/workspaceInvitesRepository.js

@@ -132,6 +132,23 @@ function createRepository({ api, knex } = {}) {
     return normalizeInviteRecord(rows[0] || null);
   }
 
+  async function findByTokenHashWithWorkspace(tokenHash, options = {}) {
+    const normalizedTokenHash = normalizeText(tokenHash);
+    if (!normalizedTokenHash) {
+      return null;
+    }
+
+    const rows = await queryInvites(
+      {
+        tokenHash: normalizedTokenHash
+      },
+      options,
+      { includeWorkspace: true }
+    );
+
+    return normalizeInviteWithWorkspace(rows[0] || null);
+  }
+
   async function listPendingByEmail(email, options = {}) {
     const normalizedEmail = normalizeLowerText(email);
     if (!normalizedEmail) {
@@ -349,6 +366,7 @@ function createRepository({ api, knex } = {}) {
   return Object.freeze({
     withTransaction,
     findPendingByTokenHash,
+    findByTokenHashWithWorkspace,
     listPendingByEmail,
     listPendingByWorkspaceIdWithWorkspace,
     insert,

package/src/server/workspaceMembers/defaultWorkspaceInviteEmail.js

@@ -0,0 +1,42 @@
+function escapeHtml(value = "") {
+  return String(value ?? "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function renderDefaultWorkspaceInviteEmail({
+  inviteUrl = "",
+  workspace = {},
+  inviter = null,
+  roleSid = "member",
+  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 expiryText = expiresAt ? `This invitation expires at ${expiresAt}.` : "";
+  const intro = inviterName
+    ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`
+    : `You have been invited to join ${workspaceName} as ${roleName}.`;
+  const subject = `You're invited to ${workspaceName}`;
+  const text = [intro, expiryText, `Open this link to accept the invitation:`, inviteUrl]
+    .filter(Boolean)
+    .join("\n\n");
+  const html = [
+    `<p>${escapeHtml(intro)}</p>`,
+    expiryText ? `<p>${escapeHtml(expiryText)}</p>` : "",
+    `<p><a href="${escapeHtml(inviteUrl)}">Accept invitation</a></p>`,
+    `<p>${escapeHtml(inviteUrl)}</p>`
+  ].filter(Boolean).join("\n");
+
+  return {
+    subject,
+    text,
+    html
+  };
+}
+
+export { renderDefaultWorkspaceInviteEmail };

package/src/server/workspaceMembers/registerWorkspaceMembers.js

@@ -7,6 +7,8 @@ import { createService as createWorkspaceMembersService } from "./workspaceMembe
 import { workspaceMembersActions } from "./workspaceMembersActions.js";
 import { createWorkspaceRoleCatalog } from "../../shared/roles.js";
 import { createWorkspaceEntityAndBootstrapEvents } from "../common/support/realtimeServiceEvents.js";
+import { renderDefaultWorkspaceInviteEmail } from "./defaultWorkspaceInviteEmail.js";
+import { createWorkspaceInviteUrlBuilder } from "./workspaceInviteUrls.js";
 
 
 function resolveWorkspaceMembersInviteExpiresInMs(appConfig = {}) {
@@ -18,6 +20,23 @@ function resolveWorkspaceMembersInviteExpiresInMs(appConfig = {}) {
   return inviteExpiresInMs;
 }
 
+function resolveWorkspaceInviteEmailTemplate(scope, appConfig = {}) {
+  if (typeof scope.has === "function" && scope.has("workspaces.invite.emailTemplate")) {
+    return scope.make("workspaces.invite.emailTemplate");
+  }
+
+  const configuredTemplate =
+    appConfig.workspaceInviteEmailTemplate ||
+    appConfig.workspaceInviteEmailRenderer ||
+    appConfig.workspaceInvitations?.emailTemplate ||
+    appConfig.workspaceInvitations?.emailRenderer;
+  if (typeof configuredTemplate === "function") {
+    return configuredTemplate;
+  }
+
+  return renderDefaultWorkspaceInviteEmail;
+}
+
 const INVITE_RECIPIENT_BOOTSTRAP_AUDIENCE = Object.freeze({
   preset: "event_scope",
   async userQuery({ knex, event } = {}) {
@@ -57,12 +76,22 @@ function registerWorkspaceMembers(app) {
     "workspaces.members.service",
     (scope) => {
       const appConfig = resolveAppConfig(scope);
+      const env = typeof scope.has === "function" && scope.has("jskit.env") ? scope.make("jskit.env") : process.env;
       return createWorkspaceMembersService({
         workspaceMembershipsRepository: scope.make("internal.repository.workspace-memberships"),
         workspaceInvitesRepository: scope.make("internal.repository.workspace-invites"),
         inviteExpiresInMs: resolveWorkspaceMembersInviteExpiresInMs(appConfig),
         roleCatalog: createWorkspaceRoleCatalog(appConfig),
-        workspaceInvitationsEnabled: scope.make("workspaces.invitations.enabled") === true
+        workspaceInvitationsEnabled: scope.make("workspaces.invitations.enabled") === true,
+        inviteUrlBuilder: createWorkspaceInviteUrlBuilder({
+          appConfig,
+          env
+        }),
+        workspaceInviteMailer:
+          typeof scope.has === "function" && scope.has("workspaces.invite.mailer")
+            ? scope.make("workspaces.invite.mailer")
+            : null,
+        workspaceInviteEmailTemplate: resolveWorkspaceInviteEmailTemplate(scope, appConfig)
       });
     },
     {

package/src/server/workspaceMembers/workspaceInviteUrls.js

@@ -0,0 +1,65 @@
+function normalizeInvitePathTemplate(value = "") {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return "/invite/:token";
+  }
+  return raw.startsWith("/") ? raw : `/${raw}`;
+}
+
+function buildInvitePath(token, pathTemplate = "/invite/:token") {
+  const encodedToken = encodeURIComponent(String(token || "").trim());
+  const template = normalizeInvitePathTemplate(pathTemplate);
+  if (template.includes(":token")) {
+    return template.replaceAll(":token", encodedToken);
+  }
+  if (template.includes("[token]")) {
+    return template.replaceAll("[token]", encodedToken);
+  }
+  return `${template.replace(/\/$/, "")}/${encodedToken}`;
+}
+
+function normalizeBaseUrl(value = "") {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return "";
+  }
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return "";
+    }
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return "";
+  }
+}
+
+function createWorkspaceInviteUrlBuilder({
+  appConfig = {},
+  env = {}
+} = {}) {
+  const inviteConfig = appConfig?.workspaceInvitations && typeof appConfig.workspaceInvitations === "object"
+    ? appConfig.workspaceInvitations
+    : {};
+  const baseUrl = normalizeBaseUrl(
+    inviteConfig.inviteBaseUrl ||
+      inviteConfig.baseUrl ||
+      appConfig?.appPublicUrl ||
+      env.APP_PUBLIC_URL ||
+      ""
+  );
+  const pathTemplate = normalizeInvitePathTemplate(inviteConfig.invitePath || inviteConfig.path || "/invite/:token");
+
+  return function buildWorkspaceInviteUrl({ token } = {}) {
+    const invitePath = buildInvitePath(token, pathTemplate);
+    if (!baseUrl) {
+      return invitePath;
+    }
+    return new URL(invitePath, `${baseUrl}/`).toString();
+  };
+}
+
+export {
+  buildInvitePath,
+  createWorkspaceInviteUrlBuilder
+};

package/src/server/workspaceMembers/workspaceMembersService.js

@@ -3,13 +3,17 @@ import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/actio
 import { buildInviteToken, hashInviteToken } from "@jskit-ai/auth-core/server/inviteTokens";
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { OWNER_ROLE_ID, createWorkspaceRoleCatalog, cloneWorkspaceRoleCatalog } from "../../shared/roles.js";
+import { renderDefaultWorkspaceInviteEmail } from "./defaultWorkspaceInviteEmail.js";
 
 function createService({
   workspaceMembershipsRepository,
   workspaceInvitesRepository,
   inviteExpiresInMs,
   roleCatalog = null,
-  workspaceInvitationsEnabled = true
+  workspaceInvitationsEnabled = true,
+  inviteUrlBuilder = null,
+  workspaceInviteMailer = null,
+  workspaceInviteEmailTemplate = renderDefaultWorkspaceInviteEmail
 } = {}) {
   if (!workspaceMembershipsRepository || !workspaceInvitesRepository) {
     throw new Error("workspaceMembersService requires membership and invite repositories.");
@@ -24,6 +28,15 @@ function createService({
     ? [...resolvedRoleCatalog.assignableRoleIds]
     : [];
   const resolvedWorkspaceInvitationsEnabled = workspaceInvitationsEnabled === true;
+  const resolvedInviteUrlBuilder = typeof inviteUrlBuilder === "function"
+    ? inviteUrlBuilder
+    : ({ token }) => `/invite/${encodeURIComponent(String(token || "").trim())}`;
+  const resolvedWorkspaceInviteMailer =
+    workspaceInviteMailer && typeof workspaceInviteMailer === "object" ? workspaceInviteMailer : null;
+  const resolvedWorkspaceInviteEmailTemplate =
+    typeof workspaceInviteEmailTemplate === "function"
+      ? workspaceInviteEmailTemplate
+      : renderDefaultWorkspaceInviteEmail;
 
   function ensureWorkspaceInvitationsEnabled() {
     if (resolvedWorkspaceInvitationsEnabled) {
@@ -77,6 +90,52 @@ function createService({
     };
   }
 
+  function normalizeInviteDeliveryResult(value = {}) {
+    const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    return {
+      status: normalizeLowerText(source.status || "sent") || "sent",
+      message: normalizeText(source.message),
+      providerMessageId: normalizeText(source.providerMessageId)
+    };
+  }
+
+  async function deliverInviteEmail({ workspace, user, invite, inviteUrl } = {}, options = {}) {
+    if (!resolvedWorkspaceInviteMailer || typeof resolvedWorkspaceInviteMailer.sendWorkspaceInvite !== "function") {
+      return {
+        status: "mailer_unconfigured",
+        message: "No workspace invite mailer is configured.",
+        providerMessageId: ""
+      };
+    }
+
+    try {
+      const message = await resolvedWorkspaceInviteEmailTemplate({
+        email: invite.email,
+        inviteUrl,
+        workspace: mapWorkspaceSummary(workspace),
+        inviter: user || null,
+        roleSid: invite.roleSid,
+        expiresAt: invite.expiresAt
+      });
+      const result = await resolvedWorkspaceInviteMailer.sendWorkspaceInvite({
+        email: invite.email,
+        inviteUrl,
+        workspace: mapWorkspaceSummary(workspace),
+        inviter: user || null,
+        roleSid: invite.roleSid,
+        expiresAt: invite.expiresAt,
+        message
+      }, options);
+      return normalizeInviteDeliveryResult(result || { status: "sent" });
+    } catch (error) {
+      return {
+        status: "failed",
+        message: normalizeText(error?.message || "Unable to send workspace invite email."),
+        providerMessageId: ""
+      };
+    }
+  }
+
   async function listRoles(options = {}) {
     return cloneWorkspaceRoleCatalog({
       ...resolvedRoleCatalog,
@@ -176,6 +235,7 @@ function createService({
   }
 
   async function createInvite(workspace, user, payload = {}, options = {}) {
+    ensureWorkspaceInvitationsEnabled();
     const email = normalizeLowerText(payload.email);
     const roleSid = normalizeLowerText(payload.roleSid || "member") || "member";
     if (!assignableRoleIds.includes(roleSid)) {
@@ -190,6 +250,7 @@ function createService({
 
     const token = buildInviteToken();
     const tokenHash = hashInviteToken(token);
+    const expiresAt = new Date(Date.now() + resolvedInviteExpiresInMs).toISOString();
     await workspaceInvitesRepository.expirePendingByWorkspaceIdAndEmail(workspace.id, email, options);
     const createdInvite = await workspaceInvitesRepository.insert(
       {
@@ -199,7 +260,7 @@ function createService({
         status: "pending",
         tokenHash,
         invitedByUserId: normalizeRecordId(user?.id, { fallback: null }),
-        expiresAt: new Date(Date.now() + resolvedInviteExpiresInMs).toISOString()
+        expiresAt
       },
       options
     );
@@ -209,14 +270,33 @@ function createService({
     }
 
     const response = await listInvitesPayload(workspace, options);
+    const inviteUrl = resolvedInviteUrlBuilder({
+      token,
+      invite: createdInvite,
+      workspace
+    });
+    const inviteDelivery = await deliverInviteEmail({
+      workspace,
+      user,
+      invite: {
+        ...createdInvite,
+        email,
+        roleSid,
+        expiresAt: createdInvite?.expiresAt || expiresAt
+      },
+      inviteUrl
+    }, options);
     return {
       ...response,
       inviteTokenPreview: token,
+      inviteUrl,
+      inviteDelivery,
       createdInviteId
     };
   }
 
   async function revokeInvite(workspace, inviteId, options = {}) {
+    ensureWorkspaceInvitationsEnabled();
     const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
     if (!normalizedInviteId) {
       throw new AppError(400, "Validation failed.");

package/src/server/workspacePendingInvitations/bootWorkspacePendingInvitations.js

@@ -2,6 +2,7 @@ import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/share
 import { workspaceMembersResource } from "../../shared/resources/workspaceMembersResource.js";
 import { workspacePendingInvitationsResource } from "../../shared/resources/workspacePendingInvitationsResource.js";
 import {
+  WORKSPACE_INVITATION_RESOLVE_TRANSPORT,
   WORKSPACE_INVITE_REDEEM_TRANSPORT,
   WORKSPACE_PENDING_INVITATIONS_TRANSPORT
 } from "../../shared/jsonApiTransports.js";
@@ -15,6 +16,14 @@ function resolveAuthenticatedUserRecordId(_record, context = {}) {
   throw new Error("JSON:API response requires request.user.id.");
 }
 
+function resolveInviteResolutionRecordId(record = {}) {
+  const recordId = record?.id || record?.token;
+  if (recordId != null && String(recordId).trim()) {
+    return recordId;
+  }
+  return "workspace-invitation";
+}
+
 function bootWorkspacePendingInvitations(app) {
   if (!app || typeof app.make !== "function") {
     throw new Error("bootWorkspacePendingInvitations requires application make().");
@@ -22,6 +31,33 @@ function bootWorkspacePendingInvitations(app) {
 
   const router = app.make("jskit.http.router");
 
+  router.register(
+    "GET",
+    "/api/workspace/invitations/resolve",
+    {
+      auth: "public",
+      meta: {
+        tags: ["workspace"],
+        summary: "Resolve safe public workspace invitation metadata"
+      },
+      ...createJsonApiResourceRouteContract({
+        ...WORKSPACE_INVITATION_RESOLVE_TRANSPORT,
+        query: workspacePendingInvitationsResource.operations.resolve.query,
+        output: workspacePendingInvitationsResource.operations.resolve.output,
+        outputKind: "record",
+        getRecordId: resolveInviteResolutionRecordId,
+        includeValidation400: true
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "workspace.invitation.resolve",
+        input: request.input.query
+      });
+      reply.code(200).send(response);
+    }
+  );
+
   router.register(
     "GET",
     "/api/workspace/invitations/pending",

package/src/server/workspacePendingInvitations/registerWorkspacePendingInvitations.js

@@ -106,6 +106,17 @@ function registerWorkspacePendingInvitations(app) {
     }
   );
 
+  if (typeof app.has === "function" && !app.has("auth.invitationContextResolver")) {
+    app.singleton("auth.invitationContextResolver", (scope) => {
+      const service = scope.make("workspaces.pending-invitations.service");
+      return {
+        async resolveInvitationContext(invitation, options = {}) {
+          return service.resolveInviteContextForAuth(invitation, options);
+        }
+      };
+    });
+  }
+
   app.actions(
     withActionDefaults(workspacePendingInvitationsActions, {
       domain: "workspace",

package/src/server/workspacePendingInvitations/workspacePendingInvitationsActions.js

@@ -3,9 +3,31 @@ import {
 } from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
 import { returnJsonApiData } from "@jskit-ai/http-runtime/shared";
 import { workspaceMembersResource } from "../../shared/resources/workspaceMembersResource.js";
+import { workspacePendingInvitationsResource } from "../../shared/resources/workspacePendingInvitationsResource.js";
 import { resolveActionUser } from "../common/support/resolveActionUser.js";
 
 const workspacePendingInvitationsActions = Object.freeze([
+  {
+    id: "workspace.invitation.resolve",
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "enabled",
+    input: workspacePendingInvitationsResource.operations.resolve.query,
+    output: null,
+    idempotency: "none",
+    audit: {
+      actionName: "workspace.invitation.resolve"
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return returnJsonApiData(
+        await deps.workspacePendingInvitationsService.resolveInviteByToken(input?.token, {
+          context
+        })
+      );
+    }
+  },
   {
     id: "workspace.invitations.pending.list",
     version: 1,

package/src/server/workspacePendingInvitations/workspacePendingInvitationsService.js

@@ -34,6 +34,67 @@ function createService({
     return tokenHash;
   }
 
+  function maskInviteEmail(email = "") {
+    const normalizedEmail = normalizeLowerText(email);
+    const [localPart = "", domain = ""] = normalizedEmail.split("@");
+    if (!localPart || !domain) {
+      return "";
+    }
+    const visibleLocal = localPart.length <= 2 ? localPart[0] || "" : localPart.slice(0, 2);
+    return `${visibleLocal}${"*".repeat(Math.max(localPart.length - visibleLocal.length, 1))}@${domain}`;
+  }
+
+  function resolvePublicInviteStatus(invite = null) {
+    if (!invite) {
+      return "not_found";
+    }
+    const status = normalizeLowerText(invite.status || "pending") || "pending";
+    if (status === "pending" && invite.expiresAt && new Date(invite.expiresAt).getTime() < Date.now()) {
+      return "expired";
+    }
+    if (["accepted", "revoked", "expired"].includes(status)) {
+      return status;
+    }
+    return "pending";
+  }
+
+  function mapResolvedInvite(invite = null, token = "") {
+    const status = resolvePublicInviteStatus(invite);
+    if (!invite) {
+      return {
+        id: "not-found",
+        token: normalizeText(token),
+        status,
+        email: "",
+        maskedEmail: "",
+        roleSid: "",
+        expiresAt: null,
+        workspace: {
+          id: "",
+          slug: "",
+          name: "",
+          avatarUrl: ""
+        }
+      };
+    }
+
+    return {
+      id: normalizeRecordId(invite.id, { fallback: "" }),
+      token: normalizeText(token),
+      status,
+      email: normalizeLowerText(invite.email),
+      maskedEmail: maskInviteEmail(invite.email),
+      roleSid: normalizeLowerText(invite.roleSid || "member") || "member",
+      expiresAt: invite.expiresAt || null,
+      workspace: {
+        id: normalizeRecordId(invite.workspaceId, { fallback: "" }),
+        slug: normalizeText(invite.workspaceSlug),
+        name: normalizeText(invite.workspaceName || invite.workspaceSlug),
+        avatarUrl: normalizeText(invite.workspaceAvatarUrl)
+      }
+    };
+  }
+
   function mapPendingInvite(invite = {}) {
     const id = normalizeRecordId(invite.id, { fallback: null });
     const workspaceId = normalizeRecordId(invite.workspaceId, { fallback: null });
@@ -93,6 +154,35 @@ function createService({
     return invites.map((invite) => mapPendingInvite(invite)).filter(Boolean);
   }
 
+  async function resolveInviteByToken(token, options = {}) {
+    const tokenHash = requireInviteTokenHash(token);
+    const invite = typeof workspaceInvitesRepository.findByTokenHashWithWorkspace === "function"
+      ? await workspaceInvitesRepository.findByTokenHashWithWorkspace(tokenHash, options)
+      : await workspaceInvitesRepository.findPendingByTokenHash(tokenHash, options);
+
+    return mapResolvedInvite(invite, token);
+  }
+
+  async function resolveInviteContextForAuth({ token, email } = {}, options = {}) {
+    const resolved = await resolveInviteByToken(token, options);
+    if (resolved.status !== "pending") {
+      throw new AppError(409, "Invitation is not available.");
+    }
+    if (normalizeLowerText(resolved.email) !== normalizeLowerText(email)) {
+      throw new AppError(403, "Invitation email does not match account email.");
+    }
+
+    return {
+      token: resolved.token,
+      workspaceId: resolved.workspace.id,
+      workspaceSlug: resolved.workspace.slug,
+      workspaceName: resolved.workspace.name,
+      email: resolved.email,
+      roleSid: resolved.roleSid,
+      expiresAt: resolved.expiresAt
+    };
+  }
+
   function requireWorkspaceIdFromInvite(invite, methodName = "workspacePendingInvitationsService") {
     const workspaceId = normalizeRecordId(invite?.workspaceId, { fallback: null });
     if (!workspaceId) {
@@ -152,6 +242,8 @@ function createService({
   }
 
   return Object.freeze({
+    resolveInviteByToken,
+    resolveInviteContextForAuth,
     listPendingInvitesForUser,
     acceptInviteByToken,
     refuseInviteByToken

package/src/shared/jsonApiTransports.js

@@ -65,6 +65,12 @@ const WORKSPACE_PENDING_INVITATIONS_TRANSPORT = deepFreeze({
   responseKind: "record"
 });
 
+const WORKSPACE_INVITATION_RESOLVE_TRANSPORT = deepFreeze({
+  kind: "jsonapi-resource",
+  responseType: "workspace-invitation-resolutions",
+  responseKind: "record"
+});
+
 export {
   WORKSPACES_TRANSPORT,
   WORKSPACES_COLLECTION_TRANSPORT,
@@ -75,5 +81,6 @@ export {
   WORKSPACE_INVITES_TRANSPORT,
   WORKSPACE_INVITE_CREATE_TRANSPORT,
   WORKSPACE_INVITE_REDEEM_TRANSPORT,
+  WORKSPACE_INVITATION_RESOLVE_TRANSPORT,
   WORKSPACE_PENDING_INVITATIONS_TRANSPORT
 };