@byline/admin 2.4.0 → 2.4.2

package/src/modules/admin-account/components/update.tsx

@@ -0,0 +1,263 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Self-service profile form.
+ *
+ * Editable surface is intentionally narrower than the admin-users
+ * `update.tsx`: no `is_super_admin`, `is_enabled`, or
+ * `is_email_verified` toggles. A user cannot grant themselves
+ * super-admin or flip their own status — those flow through the
+ * admin-users module on a privileged admin's session.
+ *
+ * Patch is built diff-style against the loaded row and submitted with
+ * the row's `vid` so a concurrent edit elsewhere surfaces as
+ * `admin.users.versionConflict` and we prompt for reload.
+ */
+
+import { useState } from 'react'
+import { revalidateLogic, useForm } from '@tanstack/react-form-start'
+
+import { Alert, Button, Input, LoaderEllipsis } from '@byline/ui/react'
+import cx from 'classnames'
+import { z } from 'zod'
+
+import { useBylineAdminServices } from '../../../services/admin-services-context.js'
+import styles from './update.module.css'
+import type { AccountResponse } from '../index.js'
+
+const updateAccountSchema = z.object({
+  given_name: z.string().max(100, 'Given name must not exceed 100 characters'),
+  family_name: z.string().max(100, 'Family name must not exceed 100 characters'),
+  username: z.string().max(100, 'Username must not exceed 100 characters'),
+  email: z
+    .email({ message: 'Enter a valid email address' })
+    .min(3)
+    .max(254, 'Email must not exceed 254 characters'),
+})
+
+type UpdateAccountValues = z.infer<typeof updateAccountSchema>
+
+function defaultsFrom(account: AccountResponse): UpdateAccountValues {
+  return {
+    given_name: account.given_name ?? '',
+    family_name: account.family_name ?? '',
+    username: account.username ?? '',
+    email: account.email,
+  }
+}
+
+function buildPatch(values: UpdateAccountValues, account: AccountResponse) {
+  const patch: {
+    given_name?: string | null
+    family_name?: string | null
+    username?: string | null
+    email?: string
+  } = {}
+  const normaliseText = (value: string): string | null => (value.trim().length > 0 ? value : null)
+  const nextGiven = normaliseText(values.given_name)
+  const nextFamily = normaliseText(values.family_name)
+  const nextUsername = normaliseText(values.username)
+  if (nextGiven !== account.given_name) patch.given_name = nextGiven
+  if (nextFamily !== account.family_name) patch.family_name = nextFamily
+  if (nextUsername !== account.username) patch.username = nextUsername
+  if (values.email !== account.email) patch.email = values.email
+  return patch
+}
+
+interface UpdateAccountProps {
+  account: AccountResponse
+  onClose?: () => void
+  onSuccess?: (account: AccountResponse) => void
+}
+
+export function UpdateAccount({ account, onClose, onSuccess }: UpdateAccountProps) {
+  const { updateAccount } = useBylineAdminServices()
+  const [formError, setFormError] = useState<string | null>(null)
+  const [successMessage, setSuccessMessage] = useState<string | null>(null)
+
+  const form = useForm({
+    defaultValues: defaultsFrom(account),
+    validationLogic: revalidateLogic({
+      mode: 'blur',
+      modeAfterSubmission: 'change',
+    }),
+    validators: {
+      onDynamic: updateAccountSchema,
+    },
+    onSubmit: async ({ value }) => {
+      setFormError(null)
+      setSuccessMessage(null)
+      const patch = buildPatch(value, account)
+      if (Object.keys(patch).length === 0) {
+        setSuccessMessage('No changes to save.')
+        return
+      }
+      try {
+        const updated = await updateAccount({ data: { vid: account.vid, patch } })
+        setSuccessMessage('Saved.')
+        onSuccess?.(updated)
+      } catch (err) {
+        const code = getErrorCode(err)
+        if (code === 'admin.users.emailInUse') {
+          form.setFieldMeta('email', (meta) => ({
+            ...meta,
+            errorMap: { ...meta.errorMap, onServer: 'This email is already in use.' },
+            errors: ['This email is already in use.'],
+          }))
+          return
+        }
+        if (code === 'admin.users.versionConflict') {
+          setFormError(
+            'Your account has been modified elsewhere since you opened this form. Reload to refresh and try again.'
+          )
+          return
+        }
+        if (code === 'admin.account.notFound') {
+          setFormError('Your admin account could not be found. Please sign in again.')
+          return
+        }
+        setFormError('Could not save changes. Please try again.')
+      }
+    },
+  })
+
+  return (
+    <div className={cx('byline-account-update-wrap', styles.wrap)}>
+      <form
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault()
+          event.stopPropagation()
+          void form.handleSubmit()
+        }}
+        className={cx('byline-account-update-form', styles.form)}
+      >
+        {formError ? <Alert intent="danger">{formError}</Alert> : null}
+        {successMessage ? <Alert intent="success">{successMessage}</Alert> : null}
+
+        <form.Field name="given_name">
+          {(field) => (
+            <Input
+              label="Given name"
+              id="given_name"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              autoComplete="given-name"
+            />
+          )}
+        </form.Field>
+
+        <form.Field name="family_name">
+          {(field) => (
+            <Input
+              label="Family name"
+              id="family_name"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              autoComplete="family-name"
+            />
+          )}
+        </form.Field>
+
+        <form.Field name="username">
+          {(field) => (
+            <Input
+              label="Username"
+              id="username"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              helpText="Optional. Leave blank to clear."
+              autoComplete="username"
+            />
+          )}
+        </form.Field>
+
+        <form.Field name="email">
+          {(field) => (
+            <Input
+              label="Email"
+              id="email"
+              name={field.name}
+              type="email"
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              autoComplete="email"
+              required
+            />
+          )}
+        </form.Field>
+
+        <div className={cx('byline-account-update-actions', styles.actions)}>
+          <Button
+            type="button"
+            intent="secondary"
+            size="sm"
+            onClick={onClose}
+            className={cx('byline-account-update-action', styles.action)}
+          >
+            {successMessage ? 'Close' : 'Cancel'}
+          </Button>
+          <form.Subscribe
+            selector={(state) => ({
+              canSubmit: state.canSubmit,
+              isSubmitting: state.isSubmitting,
+              isDirty: state.isDirty,
+            })}
+          >
+            {({ canSubmit, isSubmitting }) => (
+              <Button
+                size="sm"
+                intent="primary"
+                type="submit"
+                disabled={!canSubmit || isSubmitting}
+                className={cx('byline-account-update-action', styles.action)}
+              >
+                {isSubmitting === true ? <LoaderEllipsis size={42} /> : 'Save'}
+              </Button>
+            )}
+          </form.Subscribe>
+        </div>
+      </form>
+    </div>
+  )
+}
+
+function firstError(errors: readonly unknown[]): string | undefined {
+  for (const err of errors) {
+    if (typeof err === 'string') return err
+    if (err && typeof err === 'object' && 'message' in err) {
+      const msg = (err as { message?: unknown }).message
+      if (typeof msg === 'string') return msg
+    }
+  }
+  return undefined
+}
+
+function getErrorCode(err: unknown): string | null {
+  return typeof (err as { code?: unknown })?.code === 'string'
+    ? (err as { code: string }).code
+    : null
+}

package/src/modules/admin-account/errors.ts

@@ -0,0 +1,75 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Module-local error codes for admin-account self-service.
+ *
+ * Same `code + factory` shape as the other admin modules. The codes are
+ * prefixed `admin.account.*` so they sort alongside any future
+ * `admin.account` ability keys (today there are none — self-service is
+ * gated only by "you must be authenticated and you can only act on
+ * yourself") and so transport layers can branch on them distinctly
+ * from `admin.users.*`. Note that `admin.users.versionConflict` and
+ * `admin.users.emailInUse` are also reachable here because the service
+ * delegates to `AdminUsersRepository.update` / `setPasswordHash`; both
+ * are deliberately surfaced unmodified so the UI sees a single error
+ * code per condition.
+ */
+
+export const AdminAccountErrorCodes = {
+  NOT_FOUND: 'admin.account.notFound',
+  INVALID_CURRENT_PASSWORD: 'admin.account.invalidCurrentPassword',
+} as const
+
+export type AdminAccountErrorCode =
+  (typeof AdminAccountErrorCodes)[keyof typeof AdminAccountErrorCodes]
+
+export interface AdminAccountErrorOptions {
+  message?: string
+  cause?: unknown
+}
+
+export class AdminAccountError extends Error {
+  public readonly code: AdminAccountErrorCode
+
+  constructor(code: AdminAccountErrorCode, options: { message: string; cause?: unknown }) {
+    super(options.message, options.cause != null ? { cause: options.cause } : undefined)
+    this.name = 'AdminAccountError'
+    this.code = code
+  }
+}
+
+const make =
+  (code: AdminAccountErrorCode, defaultMessage: string) =>
+  (options?: AdminAccountErrorOptions): AdminAccountError =>
+    new AdminAccountError(code, {
+      message: options?.message ?? defaultMessage,
+      cause: options?.cause,
+    })
+
+/**
+ * The actor's admin-user id no longer resolves to a row. Typically
+ * means the session refers to a user that has been deleted out of band
+ * — the transport handler should clear cookies and redirect to
+ * sign-in.
+ */
+export const ERR_ADMIN_ACCOUNT_NOT_FOUND = make(
+  AdminAccountErrorCodes.NOT_FOUND,
+  'admin account not found'
+)
+
+/**
+ * The supplied current password did not verify against the stored hash.
+ * Returned for the change-password flow — message is intentionally
+ * generic so it can be surfaced verbatim to end users without leaking
+ * timing or existence signals.
+ */
+export const ERR_ADMIN_ACCOUNT_INVALID_CURRENT_PASSWORD = make(
+  AdminAccountErrorCodes.INVALID_CURRENT_PASSWORD,
+  'current password is incorrect'
+)

package/src/modules/admin-account/index.ts

@@ -0,0 +1,60 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/admin/admin-account` — self-service surfaces for the currently
+ * signed-in admin user.
+ *
+ * Distinct from `@byline/admin/admin-users` in two ways:
+ *
+ *   1. The actor IS the target. Commands take no `id` field — the
+ *      target is sourced from `actor.id` on the authenticated
+ *      `RequestContext`. There is no way at the command surface to
+ *      ask "operate on someone else."
+ *   2. There is no ability gate. The other admin modules use
+ *      `assertAdminActor(context, ability)`; this module uses
+ *      `requireAdminActor(context)` — authn-only. "Anyone may change
+ *      their own password" is the policy.
+ *
+ * Reuses `AdminUsersRepository` from `@byline/admin/admin-users` rather
+ * than introducing a parallel repo — the table is the same and the
+ * narrower self-service surface is structural rather than physical.
+ *
+ * Active-session listing / revocation is intentionally not included
+ * yet — that depends on `RefreshTokensRepository` semantics and a
+ * "sign out everywhere on password change" follow-up.
+ */
+
+export {
+  changeAccountPasswordCommand,
+  getAccountCommand,
+  updateAccountCommand,
+} from './commands.js'
+export {
+  AdminAccountError,
+  type AdminAccountErrorCode,
+  AdminAccountErrorCodes,
+  ERR_ADMIN_ACCOUNT_INVALID_CURRENT_PASSWORD,
+  ERR_ADMIN_ACCOUNT_NOT_FOUND,
+} from './errors.js'
+export {
+  accountResponseSchema,
+  changeAccountPasswordRequestSchema,
+  getAccountRequestSchema,
+  okResponseSchema,
+  updateAccountRequestSchema,
+} from './schemas.js'
+export { AdminAccountService } from './service.js'
+export type { AdminAccountCommandDeps } from './commands.js'
+export type {
+  AccountResponse,
+  ChangeAccountPasswordRequest,
+  GetAccountRequest,
+  OkResponse,
+  UpdateAccountRequest,
+} from './schemas.js'

package/src/modules/admin-account/schemas.ts

@@ -0,0 +1,84 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Zod schemas for the admin-account commands.
+ *
+ * Self-service is intentionally narrower than admin-users:
+ *
+ *   - The actor IS the target. None of the request schemas accept an
+ *     `id` field — the command resolves the target from
+ *     `actor.id`. Persisting `id` in the request shape would
+ *     immediately invite "but what if I pass someone else's id?"
+ *     mistakes downstream.
+ *   - The update patch excludes `is_super_admin`, `is_enabled`, and
+ *     `is_email_verified`. Self-service must never let a user grant
+ *     themselves super-admin or flip their own enabled state. Those
+ *     fields stay editable through the admin-users module by an admin
+ *     who holds the relevant ability.
+ *   - `changePassword` requires the *current* password as a defence
+ *     against session-hijack abuse: an attacker with a stolen session
+ *     cookie still needs the password they don't have to swap it out.
+ *
+ * The response shape is the same as `adminUserResponseSchema` so the
+ * admin-account UI and the admin-users UI render the same row shape
+ * — re-exported here for convenience.
+ */
+
+import { passwordSchema } from '@byline/core/validation'
+import { z } from 'zod'
+
+import { adminUserResponseSchema, okResponseSchema } from '../admin-users/schemas.js'
+
+const vidSchema = z
+  .number({ message: 'vid is required' })
+  .int({ message: 'vid must be an integer' })
+  .positive({ message: 'vid must be positive' })
+
+const emailSchema = z
+  .email({ message: 'email must be a valid address' })
+  .min(3)
+  .max(254)
+  .transform((v) => v.toLowerCase())
+
+const nameSchema = z.string().min(1).max(100)
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+/** No payload — target is the actor on context. */
+export const getAccountRequestSchema = z.object({}).strict()
+export type GetAccountRequest = z.infer<typeof getAccountRequestSchema>
+
+export const updateAccountRequestSchema = z.object({
+  vid: vidSchema,
+  patch: z
+    .object({
+      email: emailSchema.optional(),
+      given_name: nameSchema.nullish(),
+      family_name: nameSchema.nullish(),
+      username: z.string().min(1).max(100).nullish(),
+    })
+    .refine((p) => Object.keys(p).length > 0, { message: 'patch cannot be empty' }),
+})
+export type UpdateAccountRequest = z.infer<typeof updateAccountRequestSchema>
+
+export const changeAccountPasswordRequestSchema = z.object({
+  vid: vidSchema,
+  currentPassword: z.string().min(1, { message: 'current password is required' }),
+  newPassword: passwordSchema,
+})
+export type ChangeAccountPasswordRequest = z.infer<typeof changeAccountPasswordRequestSchema>
+
+// ---------------------------------------------------------------------------
+// Responses (re-exports — same shape as the admin-users module)
+// ---------------------------------------------------------------------------
+
+export { adminUserResponseSchema as accountResponseSchema, okResponseSchema }
+export type { AdminUserResponse as AccountResponse, OkResponse } from '../admin-users/schemas.js'

package/src/modules/admin-account/service.ts

@@ -0,0 +1,92 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { toAdminUser } from '../admin-users/dto.js'
+import { ERR_ADMIN_USER_EMAIL_IN_USE } from '../admin-users/errors.js'
+import { hashPassword, verifyPassword } from '../auth/password.js'
+import {
+  ERR_ADMIN_ACCOUNT_INVALID_CURRENT_PASSWORD,
+  ERR_ADMIN_ACCOUNT_NOT_FOUND,
+} from './errors.js'
+import type { AdminUsersRepository } from '../admin-users/repository.js'
+import type {
+  AccountResponse,
+  ChangeAccountPasswordRequest,
+  UpdateAccountRequest,
+} from './schemas.js'
+
+/**
+ * Self-service business logic for the currently signed-in admin user.
+ *
+ * Reuses `AdminUsersRepository` rather than introducing a parallel
+ * repository — the underlying table is the same, and self-service is
+ * just a narrower surface over it. The narrowing is structural:
+ *
+ *   - Every method takes `actorId` (sourced server-side from the
+ *     authenticated `RequestContext`) and uses it as the target id.
+ *     Callers cannot supply a target id; commands look it up from
+ *     `actor.id` and pass it in.
+ *   - `updateAccount` excludes `is_super_admin`, `is_enabled`, and
+ *     `is_email_verified` from the writable surface. The schema
+ *     already strips them, but the service signature reinforces it.
+ *   - `changePassword` verifies the *current* password before swapping
+ *     in the new hash. A hijacked session cannot use this flow to lock
+ *     out the legitimate owner.
+ *
+ * Note on session revocation: changing a password here does **not**
+ * currently revoke other refresh tokens — existing access tokens stay
+ * valid until their 15-minute expiry, and other refresh tokens remain
+ * useable. A "sign out everywhere on password change" follow-up should
+ * call `RefreshTokensRepository.revokeAllExcept(adminUserId, currentJti)`
+ * once that lands.
+ */
+export class AdminAccountService {
+  readonly #repo: AdminUsersRepository
+
+  constructor(deps: { repo: AdminUsersRepository }) {
+    this.#repo = deps.repo
+  }
+
+  async getAccount(actorId: string): Promise<AccountResponse> {
+    const row = await this.#repo.getById(actorId)
+    if (!row) throw ERR_ADMIN_ACCOUNT_NOT_FOUND()
+    return toAdminUser(row)
+  }
+
+  async updateAccount(actorId: string, request: UpdateAccountRequest): Promise<AccountResponse> {
+    const current = await this.#repo.getById(actorId)
+    if (!current) throw ERR_ADMIN_ACCOUNT_NOT_FOUND()
+
+    if (request.patch.email != null && request.patch.email !== current.email) {
+      const owner = await this.#repo.getByEmail(request.patch.email)
+      if (owner && owner.id !== actorId) throw ERR_ADMIN_USER_EMAIL_IN_USE()
+    }
+
+    const row = await this.#repo.update(actorId, request.vid, request.patch)
+    return toAdminUser(row)
+  }
+
+  async changePassword(
+    actorId: string,
+    request: ChangeAccountPasswordRequest
+  ): Promise<AccountResponse> {
+    // Pull the row *with* the password hash so we can verify the
+    // supplied current password before persisting a new one. The
+    // sign-in-shaped row is treated as ephemeral here — the hash
+    // string is never propagated outside this method.
+    const withHash = await this.#repo.getByIdForSignIn(actorId)
+    if (!withHash) throw ERR_ADMIN_ACCOUNT_NOT_FOUND()
+
+    const ok = await verifyPassword(request.currentPassword, withHash.password_hash)
+    if (!ok) throw ERR_ADMIN_ACCOUNT_INVALID_CURRENT_PASSWORD()
+
+    const newHash = await hashPassword(request.newPassword)
+    const row = await this.#repo.setPasswordHash(actorId, request.vid, newHash)
+    return toAdminUser(row)
+  }
+}

package/src/modules/admin-permissions/abilities.ts

@@ -0,0 +1,46 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AbilityRegistry } from '@byline/auth'
+
+/**
+ * Ability keys for the admin-permissions module.
+ *
+ * `read` gates the inspector view (see docs/AUTHN-AUTHZ.md).
+ * `update` will gate the per-role ability editor mounted on the
+ * admin-roles role detail page — declared here so the role editor can
+ * assert against it once that surface lands. The per-role editor shares
+ * the `update` key rather than minting `grant` / `revoke` keys: granting
+ * abilities to a role is a single editorial operation from the admin's
+ * perspective, and a granular split would force a redundant key on
+ * every permission-managing role.
+ */
+export const ADMIN_PERMISSIONS_ABILITIES = {
+  read: 'admin.permissions.read',
+  update: 'admin.permissions.update',
+} as const
+
+export type AdminPermissionsAbilityKey =
+  (typeof ADMIN_PERMISSIONS_ABILITIES)[keyof typeof ADMIN_PERMISSIONS_ABILITIES]
+
+export function registerAdminPermissionsAbilities(registry: AbilityRegistry): void {
+  registry.register({
+    key: ADMIN_PERMISSIONS_ABILITIES.read,
+    label: 'Read admin permissions',
+    description: 'View the abilities inspector and per-role ability grants.',
+    group: 'admin.permissions',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_PERMISSIONS_ABILITIES.update,
+    label: 'Update admin permissions',
+    description: "Edit a role's ability grants.",
+    group: 'admin.permissions',
+    source: 'admin',
+  })
+}