@ossy/users 3.0.8 → 3.2.0

package/README.md

@@ -20,6 +20,10 @@ Client exports (`@ossy/users`) surface action metadata for the SDK. Server expor
 | Action | Access | Task |
 |--------|--------|------|
 | `@ossy/users/actions/update-details` | authenticated | `@ossy/users/tasks/update-details` |
+| `@ossy/users/actions/request-email-change` | authenticated | `@ossy/users/tasks/request-email-change` |
+| `@ossy/users/actions/confirm-email-change` | public | `@ossy/users/tasks/confirm-email-change` |
+| `@ossy/users/actions/edit-profile-details` | authenticated | client-only (profile editor) |
+| `@ossy/users/actions/save-profile-details` | authenticated | client-only (profile form submit) |
 | `@ossy/users/actions/get-current-user-history` | authenticated | `@ossy/users/tasks/get-current-user-history` |
 | `@ossy/users/actions/join-workspace` | authenticated | `@ossy/users/tasks/join-workspace` |
 | `@ossy/users/actions/leave-workspace` | authenticated | `@ossy/users/tasks/leave-workspace` |
@@ -44,9 +48,13 @@ User entity events use the universal envelope: `type` (schema id), `resourceId`,
 | `Created` | New user (`type: 'User'` or `'Bot'`) |
 | `SignInVerified` | Sets `verifiedAt` on first verification |
 | `NameUpdated` | Updates `firstName` / `lastName` |
+| `EmailChangeRequested` | Sets `pendingEmail` (verification mail sent to the new address) |
+| `EmailUpdated` | Sets `email`, clears `pendingEmail` (old address is notified) |
 | `WorkspaceJoined` | Adds workspace id to `workspaces[]` |
 | `WorkspaceLeft` | Removes workspace id from `workspaces[]` |
 
+Email change is a two-step flow: authenticated `request-email-change` appends `EmailChangeRequested` and emails a confirmation link; public `confirm-email-change` (GET `/api/v0/users/confirm-email-change?token=…` / page `/verify-email-change`) appends `EmailUpdated`. If the new address is already used by another account, request returns `{ ok: true }` without events or mail. Mail is sent only via the `email` integration; if it is missing after the aggregate update, the task still returns `{ ok: true }` and logs a warning so verification / old-address notices are not dropped silently.
+
 `UsersEvents.SignedUp` was renamed to `UsersEvents.Created` to match the ADR 0008 lifecycle name.
 
 ## Server usage
@@ -62,6 +70,16 @@ UserSchema.user
 // => '@ossy/users/schema/user'
 ```
 
+## Forms & flows
+
+| Primitive | Id |
+|---|---|
+| Form | `@ossy/users/form/update-profile-details` |
+| Schema | `@ossy/users/schema/update-profile-details` |
+| Flow | `@ossy/users/flows/update-email` |
+
+`update-email.flow.js` composes the sign-up flow, edits email on `@profile`, confirms via `@ossy/users/emails/verify-email-change`, asserts return to profile, and checks `[data-user-email="$email"]` for the new address.
+
 ## Testing
 
 ```bash
@@ -69,4 +87,4 @@ npm test -w @ossy/users
 npm run test:integration -w @ossy/users
 ```
 
-Unit coverage lives in package tests; `users.integration.spec.js` exercises actions against `@ossy/platform`.
+Unit coverage lives in package tests; `users.integration.spec.js` exercises actions against `@ossy/platform`. Product e2e: `npm run test:e2e:flows` in `@ossy/app-test` (includes `update-email` when built into the manifest).

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@ossy/users",
   "description": "User domain - aggregate, events, and validators for the Ossy user model",
-  "version": "3.0.8",
+  "version": "3.2.0",
   "private": false,
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
-    "./server": "./src/server.js"
+    "./server": "./src/server.js",
+    "./update-email.flow.js": "./src/update-email.flow.js",
+    "./update-profile-details.schema.js": "./src/update-profile-details.schema.js"
   },
   "scripts": {
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
@@ -21,6 +23,9 @@
   },
   "peerDependencies": {
     "@ossy/authentication": ">=1.0.0",
+    "@ossy/design-system": ">=1.0.0",
+    "@ossy/platform": ">=1.0.0",
+    "@ossy/router-react": ">=1.0.0",
     "@ossy/sdk-react": ">=1.0.0",
     "react": ">=19.0.0 <20.0.0"
   },
@@ -29,9 +34,9 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@ossy/config": "^3.0.8",
-    "@ossy/observability": "^3.0.8",
-    "@ossy/schema": "^3.0.8",
+    "@ossy/config": "^3.0.9",
+    "@ossy/observability": "^3.0.9",
+    "@ossy/schema": "^3.0.9",
     "nanoid": "^5.1.11"
   },
   "devDependencies": {
@@ -43,5 +48,5 @@
     "/src",
     "README.md"
   ],
-  "gitHead": "980b380c9dee0de78ef3ebabe86efcec1c223a9a"
+  "gitHead": "b045f1fd7f2fe00c776b9ea96f76083b93fd8556"
 }

package/src/VerifyEmailChange.jsx

@@ -0,0 +1,114 @@
+import React, { useState, useEffect } from 'react'
+import { View, Text, Switch, Button, useLocale } from '@ossy/design-system'
+import { useRouter } from '@ossy/router-react'
+
+const FlowStage = {
+  Confirming: 'Confirming',
+  Success: 'Success',
+  Error: 'Error',
+}
+
+const SUCCESS_DISPLAY_MS = 1500
+
+export const VerifyEmailChange = ({
+  surface = 'primary',
+  roundness = 'l',
+  inset = 'l',
+  gap = 'l',
+  ...props
+}) => {
+  const { t } = useLocale()
+  const router = useRouter()
+  const token = router.searchParams.token
+  const [flowStage, setFlowStage] = useState(FlowStage.Confirming)
+  const [confirmed, setConfirmed] = useState(false)
+  const [successAt, setSuccessAt] = useState(null)
+
+  useEffect(() => {
+    if (!token) {
+      setFlowStage(FlowStage.Error)
+      return
+    }
+
+    let didCancel = false
+    setFlowStage(FlowStage.Confirming)
+
+    fetch(`/api/v0/users/confirm-email-change?token=${encodeURIComponent(token)}`, {
+      credentials: 'include',
+    })
+      .then((res) => {
+        if (!res.ok) throw new Error('Confirm failed')
+        return res.json()
+      })
+      .then(() => {
+        if (didCancel) return
+        setFlowStage(FlowStage.Success)
+        setSuccessAt(Date.now())
+        setConfirmed(true)
+      })
+      .catch(() => {
+        if (didCancel) return
+        setFlowStage(FlowStage.Error)
+      })
+
+    return () => {
+      didCancel = true
+    }
+  }, [token])
+
+  useEffect(() => {
+    if (!confirmed) return
+
+    const elapsed = successAt ? Date.now() - successAt : SUCCESS_DISPLAY_MS
+    const remaining = Math.max(0, SUCCESS_DISPLAY_MS - elapsed)
+
+    const timer = setTimeout(() => {
+      window.location.assign(router.getHref('profile') || '/profile')
+    }, remaining)
+
+    return () => clearTimeout(timer)
+  }, [confirmed, successAt, router])
+
+  return (
+    <View
+      data-region="content"
+      surface={surface}
+      inset={inset}
+      roundness={roundness}
+      gap={gap}
+      {...props}
+    >
+      <Switch on={flowStage}>
+        <Switch.Case match={[FlowStage.Confirming]}>
+          <Text as="h1" variant="heading-tertiary" text="users.verifyEmailChange.confirming" />
+        </Switch.Case>
+
+        <Switch.Case match={[FlowStage.Success]}>
+          <View data-flow-stage="email-change-success">
+            <Text as="h1" variant="heading-tertiary" text="users.verifyEmailChange.successRedirect" />
+          </View>
+        </Switch.Case>
+
+        <Switch.Case match={[FlowStage.Error]}>
+          <View gap="s" style={{ flexGrow: 1 }}>
+            <Text as="h1" variant="heading-tertiary">
+              {t('users.verifyEmailChange.errorTitle')}
+            </Text>
+            <Text>
+              {t('users.verifyEmailChange.errorBody')}
+            </Text>
+          </View>
+          <View layout="row" justifyContent="flex-end" gap="s">
+            <Button
+              variant="cta"
+              prefix="redo"
+              href={router.getHref('profile') || '/profile'}
+            >
+              {t('users.verifyEmailChange.profileButton')}
+            </Button>
+          </View>
+        </Switch.Case>
+      </Switch>
+    </View>
+  )
+}

package/src/confirm-email-change.action.js

@@ -0,0 +1,4 @@
+export const metadata = {
+  id: '@ossy/users/actions/confirm-email-change',
+  access: 'public',
+}

package/src/confirm-email-change.api.js

@@ -0,0 +1,34 @@
+import { ActionService } from '@ossy/platform'
+
+export const metadata = {
+  id: 'users.confirm-email-change',
+  path: '/api/v0/users/confirm-email-change',
+  action: '@ossy/users/actions/confirm-email-change',
+  method: 'GET',
+  query: ['token'],
+}
+
+export default async function handle (req, res) {
+  if (req.method !== 'GET') {
+    res.setHeader('Allow', 'GET')
+    res.status(405).json({ error: 'Method Not Allowed' })
+    return
+  }
+
+  const token = req.query?.token
+  if (!token || typeof token !== 'string') {
+    res.status(400).json({ message: 'No token provided' })
+    return
+  }
+
+  try {
+    const result = await ActionService.invoke('@ossy/users/actions/confirm-email-change', {
+      payload: { token },
+      req,
+    })
+    res.status(200).json(result)
+  } catch (err) {
+    const status = err?.status ?? 401
+    res.status(status).json({ error: err?.message || 'Unauthorized' })
+  }
+}

package/src/confirm-email-change.task.js

@@ -0,0 +1,89 @@
+import path from 'node:path'
+import { Aggregate } from '@ossy/event-store'
+import { User, UsersEvents, UserSchema } from '@ossy/users/server'
+import { EmailRenderer } from '@ossy/email'
+import { createTranslatorForBuild } from '@ossy/platform/locale'
+import { createLogger } from '@ossy/observability'
+import { verifyEmailChangeToken } from './email-change-token.js'
+import EmailChangedEmail, {
+  id as emailChangedEmailId,
+} from './email-changed.email.jsx'
+
+export const metadata = { id: '@ossy/users/tasks/confirm-email-change' }
+
+const log = createLogger('@ossy/users/tasks/confirm-email-change')
+
+/**
+ * Confirm a pending email change from a signed EmailChange token.
+ * Appends `EmailUpdated`, then notifies the previous address.
+ *
+ * @param {{ payload: { token?: string }, integrations: unknown, req: unknown }} context
+ * @returns {Promise<{ ok: true, email: string }>}
+ */
+export async function run ({ payload, integrations, req }) {
+  const { userId, email: newEmail } = await verifyEmailChangeToken(payload?.token)
+
+  const user = await Aggregate.Of(User, userId).then(Aggregate.View())
+  if (!user?.id) {
+    throw Object.assign(new Error('Invalid token'), { status: 401 })
+  }
+
+  const previousEmail = user.email
+  if (!previousEmail) {
+    throw Object.assign(new Error('Invalid user'), { status: 400 })
+  }
+
+  if (previousEmail === newEmail) {
+    return { ok: true, email: newEmail }
+  }
+
+  const existingUser = await Aggregate.Collection.findOne({
+    'state.email': newEmail,
+    type: { $in: [UserSchema.user, User.AggregateType] },
+  }).then((agg) => agg?.state)
+
+  if (existingUser && existingUser.id !== userId) {
+    log.warn('Email change confirm blocked; address already in use')
+    throw Object.assign(new Error('Email unavailable'), { status: 409 })
+  }
+
+  await Aggregate.Of(User, userId)
+    .then(Aggregate.Add(UsersEvents.EmailUpdated({
+      email: newEmail,
+      previousEmail,
+      createdBy: userId,
+    })))
+    .then(Aggregate.Save())
+
+  const buildDir = path.resolve(process.cwd(), 'build')
+  const t = createTranslatorForBuild(buildDir, undefined, { defaultLanguage: 'en' })
+  const subject = t('users.emailChanged.subject')
+  const { html, text } = EmailRenderer.render(EmailChangedEmail, {
+    previousEmail,
+    email: newEmail,
+    t,
+  })
+
+  const emailClient = integrations?.get?.('email')
+  if (!emailClient) {
+    // Email already updated; surface misconfig so the old-address notice is not silently dropped.
+    log.warn('No email integration available; skipping email-changed notification', {
+      userId,
+      previousEmail,
+      email: newEmail,
+    })
+    return { ok: true, email: newEmail }
+  }
+
+  await emailClient.send({
+    to: previousEmail,
+    from: 'noreply@ossy.se',
+    subject,
+    html,
+    text,
+    // Required for flow/dev-inbox matching (`email.id` / template filter).
+    templateId: emailChangedEmailId,
+  })
+
+  return { ok: true, email: newEmail }
+}

package/src/edit-profile-details.action.js

@@ -0,0 +1,7 @@
+/** Client-only — opens the profile details editor. */
+export const metadata = {
+  id: '@ossy/users/actions/edit-profile-details',
+  access: 'authenticated',
+  icon: 'pen',
+  label: '@ossy/users/actions/edit-profile-details.label',
+}

package/src/email-change-token.js

@@ -0,0 +1,41 @@
+import jwt from 'jsonwebtoken'
+import { ConfigService } from '@ossy/config'
+
+export const EMAIL_CHANGE_TOKEN_TYPE = 'EmailChange'
+
+/**
+ * @param {{ userId: string, email: string }} args
+ * @returns {string}
+ */
+export function createEmailChangeToken ({ userId, email }) {
+  const expiresIn = ConfigService.TokenValidity
+  return jwt.sign(
+    { sub: userId, type: EMAIL_CHANGE_TOKEN_TYPE, email },
+    ConfigService.TokenSecret,
+    { expiresIn, algorithm: 'HS256' },
+  )
+}
+
+/**
+ * @param {string} token
+ * @returns {Promise<{ userId: string, email: string }>}
+ */
+export function verifyEmailChangeToken (token) {
+  return new Promise((resolve, reject) => {
+    if (!token) {
+      return reject(Object.assign(new Error('No token provided'), { status: 400 }))
+    }
+    jwt.verify(token, ConfigService.TokenSecret, { algorithms: ['HS256'] }, (err, payload) => {
+      if (err) {
+        return reject(Object.assign(new Error('Invalid or expired token'), { status: 401 }))
+      }
+      if (payload?.type !== EMAIL_CHANGE_TOKEN_TYPE) {
+        return reject(Object.assign(new Error('Invalid token type'), { status: 401 }))
+      }
+      if (!payload?.sub || typeof payload.email !== 'string') {
+        return reject(Object.assign(new Error('Invalid token payload'), { status: 401 }))
+      }
+      resolve({ userId: payload.sub, email: payload.email })
+    })
+  })
+}

package/src/email-change-token.spec.js

@@ -0,0 +1,36 @@
+import { describe, expect, it, beforeAll } from '@jest/globals'
+import {
+  createEmailChangeToken,
+  verifyEmailChangeToken,
+  EMAIL_CHANGE_TOKEN_TYPE,
+} from './email-change-token.js'
+
+describe('email-change-token', () => {
+  beforeAll(() => {
+    process.env.TOKEN_SECRET = process.env.TOKEN_SECRET || 'test-token-secret-for-email-change'
+  })
+
+  it('round-trips userId and email with EmailChange type', async () => {
+    const token = createEmailChangeToken({
+      userId: 'user-42',
+      email: 'new@example.com',
+    })
+    const payload = await verifyEmailChangeToken(token)
+    expect(payload).toEqual({ userId: 'user-42', email: 'new@example.com' })
+    expect(EMAIL_CHANGE_TOKEN_TYPE).toBe('EmailChange')
+  })
+
+  it('rejects missing tokens', async () => {
+    await expect(verifyEmailChangeToken('')).rejects.toMatchObject({
+      message: 'No token provided',
+      status: 400,
+    })
+  })
+
+  it('rejects garbage tokens', async () => {
+    await expect(verifyEmailChangeToken('not-a-jwt')).rejects.toMatchObject({
+      message: 'Invalid or expired token',
+      status: 401,
+    })
+  })
+})

package/src/email-changed.email.jsx

@@ -0,0 +1,30 @@
+import { EmailLayout, EmailText } from '@ossy/email'
+
+export const id = '@ossy/users/emails/email-changed'
+
+/**
+ * Notification to the previous address after a successful email change.
+ *
+ * @param {{ previousEmail?: string, email?: string, theme?: object, t?: (key: string) => string }} props
+ */
+export default function EmailChangedEmail ({
+  previousEmail,
+  email,
+  theme,
+  t = (key) => key,
+}) {
+  return (
+    <EmailLayout theme={theme}>
+      <h1 style={{ color: '#111111', margin: '0 0 16px' }}>{t('users.emailChanged.title')}</h1>
+      <EmailText>
+        {t('users.emailChanged.body')}
+      </EmailText>
+      {(previousEmail || email) && (
+        <EmailText>
+          {previousEmail ? `${previousEmail} → ` : ''}
+          {email || ''}
+        </EmailText>
+      )}
+    </EmailLayout>
+  )
+}

package/src/en.translations.json

@@ -12,5 +12,30 @@
   "@ossy/users/actions/leave-workspace.label": "Leave workspace",
   "@ossy/users/actions/leave-workspace.description": "Remove the current user from a workspace",
   "@ossy/users/actions/update-details.label": "Update user details",
-  "@ossy/users/actions/update-details.description": "Update profile fields for the authenticated user"
+  "@ossy/users/actions/update-details.description": "Update profile fields for the authenticated user",
+  "@ossy/users/actions/request-email-change.label": "Request email change",
+  "@ossy/users/actions/request-email-change.description": "Send a verification link to a new email address for the authenticated user",
+  "@ossy/users/actions/confirm-email-change.label": "Confirm email change",
+  "@ossy/users/actions/confirm-email-change.description": "Confirm a pending email change from a verification link",
+  "@ossy/users/actions/edit-profile-details.label": "Edit",
+  "@ossy/users/actions/edit-profile-details.description": "Open the profile details editor",
+  "@ossy/users/actions/save-profile-details.label": "Save",
+  "@ossy/users/actions/save-profile-details.description": "Save profile name and email changes",
+  "@ossy/users/form/update-profile-details.label": "Update profile details",
+  "@ossy/users/schema/update-profile-details.firstName.label": "First name",
+  "@ossy/users/schema/update-profile-details.lastName.label": "Last name",
+  "@ossy/users/schema/update-profile-details.email.label": "Email address",
+  "verify-email-change.documentTitle": "Confirm email change",
+  "users.verifyEmailChange.subject": "Confirm your new Ossy email",
+  "users.verifyEmailChange.title": "Confirm email change",
+  "users.verifyEmailChange.body": "Click the button below to confirm this email address for your Ossy account.",
+  "users.verifyEmailChange.button": "Confirm email",
+  "users.verifyEmailChange.confirming": "Confirming email change...",
+  "users.verifyEmailChange.successRedirect": "Email updated, redirecting...",
+  "users.verifyEmailChange.errorTitle": "Could not update email",
+  "users.verifyEmailChange.errorBody": "This confirmation link is invalid or has expired. Request a new change from your profile.",
+  "users.verifyEmailChange.profileButton": "Back to profile",
+  "users.emailChanged.subject": "Your Ossy email was changed",
+  "users.emailChanged.title": "Email address updated",
+  "users.emailChanged.body": "The email address on your Ossy account was changed. If you did not make this change, contact support."
 }

package/src/index.js

@@ -2,6 +2,12 @@ export { metadata as GetUserApiTokens } from './get-api-tokens.action.js'
 export { metadata as CreateUserApiToken } from './create-api-token.action.js'
 export { metadata as InvalidateApiToken } from './invalidate-api-token.action.js'
 export { metadata as UpdateUserDetails } from './update-details.action.js'
+export { metadata as RequestEmailChange } from './request-email-change.action.js'
+export { metadata as ConfirmEmailChange } from './confirm-email-change.action.js'
+export { metadata as EditProfileDetails } from './edit-profile-details.action.js'
+export { metadata as SaveProfileDetails } from './save-profile-details.action.js'
+export { metadata as UpdateProfileDetailsForm } from './update-profile-details.form.js'
 export { metadata as GetCurrentUserHistory } from './get-current-user-history.action.js'
 export { metadata as JoinWorkspace } from './join-workspace.action.js'
 export { metadata as LeaveWorkspace } from './leave-workspace.action.js'
+export { VerifyEmailChange } from './VerifyEmailChange.jsx'

package/src/request-email-change.action.js

@@ -0,0 +1,4 @@
+export const metadata = {
+  id: '@ossy/users/actions/request-email-change',
+  access: 'authenticated',
+}

package/src/request-email-change.task.js

@@ -0,0 +1,108 @@
+import path from 'node:path'
+import { Aggregate } from '@ossy/event-store'
+import { User, UsersEvents, UserSchema } from '@ossy/users/server'
+import { Token, TokenEvents } from '@ossy/tokens/server'
+import { EmailRenderer } from '@ossy/email'
+import { ConfigService } from '@ossy/config'
+import { createTranslatorForBuild } from '@ossy/platform/locale'
+import { createLogger } from '@ossy/observability'
+import { createEmailChangeToken, EMAIL_CHANGE_TOKEN_TYPE } from './email-change-token.js'
+import VerifyEmailChangeEmail, {
+  id as verifyEmailChangeEmailId,
+} from './verify-email-change.email.jsx'
+
+export const metadata = { id: '@ossy/users/tasks/request-email-change' }
+
+const log = createLogger('@ossy/users/tasks/request-email-change')
+
+const isEmailLike = (maybeEmail) => /.@.+\.../.test(maybeEmail)
+
+/**
+ * Request an email change for the authenticated user.
+ * If the new email is already used by another account, returns `{ ok: true }`
+ * without creating events or sending mail (avoids email enumeration).
+ *
+ * @param {{ payload: { email?: string }, integrations: unknown, req: unknown }} context
+ */
+export async function run ({ payload, integrations, req }) {
+  const createdBy = payload?.userId ?? req?.userId
+  const currentUser = payload?.currentUser ?? req?.user
+  const email = payload?.email?.trim?.()
+
+  if (!createdBy) {
+    throw Object.assign(new Error('Unauthorized'), { status: 401 })
+  }
+  if (!isEmailLike(email)) {
+    throw Object.assign(new Error('No email provided'), { status: 400 })
+  }
+
+  const currentEmail = currentUser?.email?.trim?.() ?? currentUser?.email
+
+  if (email === currentEmail) {
+    return { ok: true }
+  }
+
+  // Snapshots may be typed as SchemaId or legacy AggregateType (`User`).
+  const existingUser = await Aggregate.Collection.findOne({
+    'state.email': email,
+    type: { $in: [UserSchema.user, User.AggregateType] },
+  }).then((agg) => agg?.state)
+
+  if (existingUser && existingUser.id !== createdBy) {
+    log.info('Email change requested for address already in use; returning silently')
+    return { ok: true }
+  }
+
+  const token = createEmailChangeToken({ userId: createdBy, email })
+  const expiresIn = ConfigService.TokenValidity
+  const expiresAt = Date.now() + Number(expiresIn) * 1000
+  const tokenCreatedEvent = TokenEvents.Created({
+    type: EMAIL_CHANGE_TOKEN_TYPE,
+    createdBy,
+    subject: createdBy,
+    token,
+    expiresAt,
+  })
+
+  await Aggregate.Of(User, createdBy)
+    .then(Aggregate.Add(UsersEvents.EmailChangeRequested({
+      email,
+      createdBy,
+    })))
+    .then(Aggregate.Save())
+
+  await Aggregate.Of(Token, tokenCreatedEvent)
+
+  const baseUrl = ConfigService.getWebClientBaseUrl(req)
+  const buildDir = path.resolve(process.cwd(), 'build')
+  const t = createTranslatorForBuild(buildDir, undefined, { defaultLanguage: 'en' })
+  const subject = t('users.verifyEmailChange.subject')
+  const { html, text } = EmailRenderer.render(VerifyEmailChangeEmail, {
+    token: tokenCreatedEvent.payload.token,
+    baseUrl,
+    email,
+    t,
+  })
+
+  const emailClient = integrations?.get?.('email')
+  if (!emailClient) {
+    // Pending email already recorded; surface misconfig so verification mail is not silently dropped.
+    log.warn('No email integration available; skipping verify-email-change mail', {
+      userId: createdBy,
+      email,
+    })
+    return { ok: true }
+  }
+
+  await emailClient.send({
+    to: email,
+    from: 'noreply@ossy.se',
+    subject,
+    html,
+    text,
+    // Required for flow/dev-inbox matching (`email.id` / template filter).
+    templateId: verifyEmailChangeEmailId,
+  })
+
+  return { ok: true }
+}

package/src/save-profile-details.action.js

@@ -0,0 +1,6 @@
+/** Client-only — submits the profile details form (name and/or email change). */
+export const metadata = {
+  id: '@ossy/users/actions/save-profile-details',
+  access: 'authenticated',
+  label: '@ossy/users/actions/save-profile-details.label',
+}

package/src/sv.translations.json

@@ -12,5 +12,30 @@
   "@ossy/users/actions/leave-workspace.label": "Lämna workspace",
   "@ossy/users/actions/leave-workspace.description": "Ta bort nuvarande användare från ett workspace",
   "@ossy/users/actions/update-details.label": "Uppdatera användaruppgifter",
-  "@ossy/users/actions/update-details.description": "Uppdatera profilfält för den inloggade användaren"
+  "@ossy/users/actions/update-details.description": "Uppdatera profilfält för den inloggade användaren",
+  "@ossy/users/actions/request-email-change.label": "Begär e-poständring",
+  "@ossy/users/actions/request-email-change.description": "Skicka en verifieringslänk till en ny e-postadress för den inloggade användaren",
+  "@ossy/users/actions/confirm-email-change.label": "Bekräfta e-poständring",
+  "@ossy/users/actions/confirm-email-change.description": "Bekräfta en väntande e-poständring via verifieringslänk",
+  "@ossy/users/actions/edit-profile-details.label": "Redigera",
+  "@ossy/users/actions/edit-profile-details.description": "Öppna redigeraren för profiluppgifter",
+  "@ossy/users/actions/save-profile-details.label": "Spara",
+  "@ossy/users/actions/save-profile-details.description": "Spara namn- och e-poständringar",
+  "@ossy/users/form/update-profile-details.label": "Uppdatera profiluppgifter",
+  "@ossy/users/schema/update-profile-details.firstName.label": "Förnamn",
+  "@ossy/users/schema/update-profile-details.lastName.label": "Efternamn",
+  "@ossy/users/schema/update-profile-details.email.label": "E-postadress",
+  "verify-email-change.documentTitle": "Bekräfta e-poständring",
+  "users.verifyEmailChange.subject": "Bekräfta din nya Ossy-e-post",
+  "users.verifyEmailChange.title": "Bekräfta e-poständring",
+  "users.verifyEmailChange.body": "Klicka på knappen nedan för att bekräfta den här e-postadressen för ditt Ossy-konto.",
+  "users.verifyEmailChange.button": "Bekräfta e-post",
+  "users.verifyEmailChange.confirming": "Bekräftar e-poständring...",
+  "users.verifyEmailChange.successRedirect": "E-post uppdaterad, omdirigerar...",
+  "users.verifyEmailChange.errorTitle": "Kunde inte uppdatera e-post",
+  "users.verifyEmailChange.errorBody": "Den här bekräftelselänken är ogiltig eller har gått ut. Begär en ny ändring från din profil.",
+  "users.verifyEmailChange.profileButton": "Tillbaka till profil",
+  "users.emailChanged.subject": "Din Ossy-e-post har ändrats",
+  "users.emailChanged.title": "E-postadress uppdaterad",
+  "users.emailChanged.body": "E-postadressen på ditt Ossy-konto har ändrats. Om du inte gjorde ändringen, kontakta support."
 }

package/src/update-email.flow.js

@@ -0,0 +1,55 @@
+import signUpFlow from '@ossy/authentication/sign-up.flow.js'
+import { metadata as EditProfileDetails } from './edit-profile-details.action.js'
+import { metadata as SaveProfileDetails } from './save-profile-details.action.js'
+import { metadata as UpdateProfileDetailsForm } from './update-profile-details.form.js'
+
+export const metadata = {
+  id: '@ossy/users/flows/update-email',
+  feature: 'users',
+  requires: ['server', 'database'],
+}
+
+/**
+ * Happy path for issue #415 — request email change from profile, confirm via
+ * verification mail, land back on profile with the new address active.
+ */
+export default {
+  title: 'Update email',
+  description: 'Signed-in user changes email from profile, confirms via link, and returns to profile',
+  steps: [
+    ...signUpFlow.steps,
+    { page: '@profile' },
+    { result: { action: EditProfileDetails, timeout: 10000 } },
+    { action: EditProfileDetails },
+    // Preserve sign-up address before the profile form overwrites `$email`.
+    { capture: { previousEmail: '$email' } },
+    { form: UpdateProfileDetailsForm },
+    { action: SaveProfileDetails },
+    { result: { selector: '[data-flow-stage="email-change-requested"]', timeout: 10000 } },
+    {
+      email: {
+        to: '$email',
+        id: '@ossy/users/emails/verify-email-change',
+        click: 'Confirm email',
+      },
+    },
+    { result: { selector: '[data-flow-stage="email-change-success"]', timeout: 10000 } },
+    { result: { page: '@profile', timeout: 15000 } },
+    // `$email` is the faker address filled into the profile form (new address).
+    { result: { selector: '[data-user-email="$email"]', timeout: 15000 } },
+    // Issue #415: previous address receives a change notification (no link to click).
+    {
+      page: '@dev-inbox',
+      search: {
+        to: '$previousEmail',
+        template: '@ossy/users/emails/email-changed',
+      },
+    },
+    {
+      result: {
+        selector: '[data-email-template="@ossy/users/emails/email-changed"][data-email-to="$previousEmail"]',
+        timeout: 15000,
+      },
+    },
+  ],
+}

package/src/update-profile-details.form.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/users/form/update-profile-details',
+  schemaId: '@ossy/users/schema/update-profile-details',
+  label: '@ossy/users/form/update-profile-details.label',
+}

package/src/update-profile-details.schema.js

@@ -0,0 +1,11 @@
+/** Profile account details — UI fields and flow faker schema. */
+export default {
+  id: '@ossy/users/schema/update-profile-details',
+  name: 'Update profile details',
+  icon: 'profile',
+  fields: [
+    { name: 'firstName', type: 'text', required: true },
+    { name: 'lastName', type: 'text', required: true },
+    { name: 'email', type: 'email', required: true },
+  ],
+}

package/src/user.aggregate.js

@@ -34,6 +34,19 @@ export class User {
           return { ...user, firstName, lastName }
         }
 
+        case 'EmailChangeRequested':
+          return {
+            ...user,
+            pendingEmail: event.payload.email,
+          }
+
+        case 'EmailUpdated':
+          return {
+            ...user,
+            email: event.payload.email,
+            pendingEmail: undefined,
+          }
+
         case 'WorkspaceJoined':
           return {
             ...user,

package/src/user.aggregate.spec.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from '@jest/globals'
+import { User } from './user.aggregate.js'
+import { UsersEvents } from './users.events.js'
+
+describe('User.View email change', () => {
+  it('sets pendingEmail on EmailChangeRequested and updates email on EmailUpdated', () => {
+    const created = UsersEvents.Created({
+      email: 'old@example.com',
+      firstName: 'Ada',
+      lastName: 'Lovelace',
+      userId: 'user-1',
+    })
+    const requested = {
+      ...UsersEvents.EmailChangeRequested({
+        email: 'new@example.com',
+        createdBy: 'user-1',
+      }),
+      resourceId: 'user-1',
+      created: Date.now(),
+    }
+    const updated = {
+      ...UsersEvents.EmailUpdated({
+        email: 'new@example.com',
+        previousEmail: 'old@example.com',
+        createdBy: 'user-1',
+      }),
+      resourceId: 'user-1',
+      created: Date.now() + 1,
+    }
+
+    const afterRequest = User.View([created, requested])
+    expect(afterRequest.email).toBe('old@example.com')
+    expect(afterRequest.pendingEmail).toBe('new@example.com')
+
+    const afterConfirm = User.View([created, requested, updated])
+    expect(afterConfirm.email).toBe('new@example.com')
+    expect(afterConfirm.pendingEmail).toBeUndefined()
+  })
+})

package/src/users.events.js

@@ -39,6 +39,22 @@ export class UsersEvents {
     }
   }
 
+  static EmailChangeRequested ({ email, createdBy }) {
+    return {
+      event: 'EmailChangeRequested',
+      createdBy,
+      payload: { email },
+    }
+  }
+
+  static EmailUpdated ({ email, previousEmail, createdBy }) {
+    return {
+      event: 'EmailUpdated',
+      createdBy,
+      payload: { email, previousEmail },
+    }
+  }
+
   static WorkspaceJoined ({ workspaceId, createdBy }) {
     return {
       event: 'WorkspaceJoined',

package/src/users.integration.spec.js

@@ -402,6 +402,152 @@ describe('[users/actions/get-current-user-history]', () => {
   })
 })
 
+describe('[users/actions/request-email-change]', () => {
+
+  TestUtil.AssertActionAuthenticationNeeded({
+    actionId: '@ossy/users/actions/request-email-change',
+    payload: { email: 'new@example.com' },
+  })
+
+  describe('given an email that is not already in use', () => {
+    it('must return OK 200 and produce EmailChangeRequested plus an EmailChange token', async () => {
+      const user = await TestUtil.GetAuthenticatedTestUser()
+      const newEmail = `new-${Date.now()}-${casual.email}`
+
+      await TestUtil.AssertActionResponse({
+        actionId: '@ossy/users/actions/request-email-change',
+        headers: authHeaders(user.token),
+        payload: { email: newEmail },
+        expectedResponseStatus: 200,
+        expectedResponseBody: { ok: true },
+      })
+
+      await TestUtil.AssertEventExist({
+        type: USER_SCHEMA,
+        resourceId: user.id,
+        event: 'EmailChangeRequested',
+        'payload.email': newEmail,
+      })
+
+      const jwt = await TestUtil.getLatestEmailChangeJwtForSubject(user.id)
+      expect(typeof jwt).toBe('string')
+    })
+  })
+
+  describe('given an email that is already in use', () => {
+    it('must return OK 200 without EmailChangeRequested or EmailChange token', async () => {
+      const takenEmail = `taken-${Date.now()}-${casual.email}`
+      await TestUtil.AssertActionResponse({
+        actionId: '@ossy/authentication/actions/sign-up',
+        payload: { email: takenEmail, firstName: 'Taken', lastName: 'User' },
+        expectedResponseStatus: 200,
+        expectedResponseBody: { ok: true },
+      })
+
+      const user = await TestUtil.GetAuthenticatedTestUser()
+      const tokensBefore = await TestUtil.countEmailChangeTokenEvents()
+
+      await TestUtil.AssertActionResponse({
+        actionId: '@ossy/users/actions/request-email-change',
+        headers: authHeaders(user.token),
+        payload: { email: takenEmail },
+        expectedResponseStatus: 200,
+        expectedResponseBody: { ok: true },
+      })
+
+      const changeEvents = await TestUtil.GetEvents({
+        type: USER_SCHEMA,
+        resourceId: user.id,
+        event: 'EmailChangeRequested',
+      }).catch(() => [])
+      const tokensAfter = await TestUtil.countEmailChangeTokenEvents()
+
+      expect(changeEvents).toEqual([])
+      expect(tokensAfter).toEqual(tokensBefore)
+    })
+  })
+
+  describe('given an invalid email', () => {
+    invalidEmails.forEach((invalidEmail) => {
+      it(
+        `must return BAD REQUEST 400 for invalid email: ${invalidEmail}`,
+        async () => {
+          const user = await TestUtil.GetAuthenticatedTestUser()
+          await TestUtil.AssertActionResponse({
+            actionId: '@ossy/users/actions/request-email-change',
+            headers: authHeaders(user.token),
+            payload: { email: invalidEmail },
+            expectedResponseStatus: 400,
+            expectedResponseBody: { error: 'No email provided' },
+          })
+        },
+      )
+    })
+  })
+
+})
+
+describe('[/users/confirm-email-change][GET]', () => {
+
+  describe('given a valid EmailChange token', () => {
+    it('must return OK 200, produce EmailUpdated, and update get-current-user email', async () => {
+      const user = await TestUtil.GetAuthenticatedTestUser()
+      const newEmail = `confirm-${Date.now()}-${casual.email}`
+
+      await TestUtil.AssertActionResponse({
+        actionId: '@ossy/users/actions/request-email-change',
+        headers: authHeaders(user.token),
+        payload: { email: newEmail },
+        expectedResponseStatus: 200,
+        expectedResponseBody: { ok: true },
+      })
+
+      const emailChangeJwt = await TestUtil.getLatestEmailChangeJwtForSubject(user.id)
+
+      const response = await fetch(
+        `${getApiTestBaseUrl()}/users/confirm-email-change?token=${emailChangeJwt}`,
+        { method: 'GET' },
+      )
+      const body = await response.json()
+
+      expect(response.status).toBe(200)
+      expect(body).toEqual({ ok: true, email: newEmail })
+
+      await TestUtil.AssertEventExist({
+        type: USER_SCHEMA,
+        resourceId: user.id,
+        event: 'EmailUpdated',
+        'payload.email': newEmail,
+        'payload.previousEmail': user.email,
+      })
+
+      const currentUserResponse = await TestUtil.InvokeAction({
+        actionId: '@ossy/authentication/actions/get-current-user',
+        headers: authHeaders(user.token),
+      })
+      const currentUser = await currentUserResponse.json()
+      expect(currentUser.email).toBe(newEmail)
+    })
+  })
+
+  describe('given an invalid token', () => {
+    it('must return 400 when token query param is missing', () => TestUtil.AssertResponse({
+      endpoint: '/users/confirm-email-change',
+      method: 'GET',
+      expectedResponseStatus: 400,
+      expectedResponseBody: { message: 'No token provided' },
+    }))
+
+    it('must return 401 for a garbage token', () => TestUtil.AssertResponse({
+      endpoint: '/users/confirm-email-change?token=notatoken',
+      method: 'GET',
+      expectedResponseStatus: 401,
+      expectedResponseBody: { error: 'Invalid or expired token' },
+    }))
+  })
+
+})
+
 describe('[users/actions/create-api-token]', () => {
 
   TestUtil.AssertActionAuthenticationNeeded({

package/src/users.queries.js

@@ -10,8 +10,8 @@ export class UsersQueries {
     log.debug(`[UsersQueries][getByEmail()] Fetch user for ${email}`)
 
     return Aggregate.Collection.findOne({
-      type: UserSchema.user,
       'state.email': email,
+      type: { $in: [UserSchema.user, 'User'] },
     }).then(aggregate => aggregate?.state)
   }
 

package/src/verify-email-change.email.jsx

@@ -0,0 +1,30 @@
+import { EmailLayout, EmailButton, EmailText } from '@ossy/email'
+
+export const id = '@ossy/users/emails/verify-email-change'
+
+/**
+ * @param {{ token: string, baseUrl?: string, email?: string, theme?: object, t?: (key: string) => string }} props
+ */
+export default function VerifyEmailChangeEmail ({
+  token,
+  baseUrl = 'https://app.ossy.se',
+  email,
+  theme,
+  t = (key) => key,
+}) {
+  const url = new URL('/verify-email-change', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`)
+  url.searchParams.set('token', token)
+
+  return (
+    <EmailLayout theme={theme}>
+      <h1 style={{ color: '#111111', margin: '0 0 16px' }}>{t('users.verifyEmailChange.title')}</h1>
+      <EmailText>
+        {t('users.verifyEmailChange.body')}
+        {email ? ` (${email})` : ''}
+      </EmailText>
+      <EmailButton href={url.toString()} theme={theme}>
+        {t('users.verifyEmailChange.button')}
+      </EmailButton>
+    </EmailLayout>
+  )
+}

package/src/verify-email-change.page.jsx

@@ -0,0 +1,31 @@
+import React from 'react'
+import { View } from '@ossy/design-system'
+import { VerifyEmailChange } from './VerifyEmailChange.jsx'
+
+export const metadata = {
+  id: 'verify-email-change',
+  path: '/verify-email-change',
+  layout: '@ossy/app/layout/blank',
+}
+
+const VerifyEmailChangePage = () => (
+  <View
+    layout="off-center-s"
+    inset="s"
+    surface="base"
+    style={{ height: '100%', minHeight: '100%' }}
+  >
+    <View inset="s" roundness="l" surface="primary" data-region="content" style={{ height: '100%' }}>
+      <VerifyEmailChange
+        data-region="content"
+        inset="none"
+        style={{
+          padding: 'var(--space-l) var(--space-l) var(--space-m) var(--space-l)',
+          height: '100%',
+        }}
+      />
+    </View>
+  </View>
+)
+
+export default VerifyEmailChangePage