@plone-collective/volto-identity 1.0.0-alpha.1

package/src/config/settings.ts

@@ -0,0 +1,72 @@
+import type { ConfigType } from '@plone/registry';
+import ProfileGate from '../components/ProfileGate/ProfileGate';
+
+declare module '@plone/types' {
+  export interface SettingsConfig {
+    /** Whether Plone's own username/password form is offered as well. */
+    identityShowPloneLogin: boolean;
+  }
+}
+
+/**
+ * Read a boolean out of the environment.
+ *
+ * Only the words are accepted, and anything unset falls back to the default.
+ * Deliberately not `Boolean(value)`: that reads the string `"false"` as true,
+ * which turns an operator switching the password form *off* into a site that
+ * still shows it.
+ *
+ * @param value The raw environment value.
+ * @param fallback What an unset variable means.
+ * @returns The decision.
+ */
+export function asBoolean(
+  value: string | undefined,
+  fallback: boolean,
+): boolean {
+  if (value === undefined || value === '') {
+    return fallback;
+  }
+  return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+
+export default function install(config: ConfigType) {
+  // Off by default: a site installing this add-on has external providers,
+  // and leaving the password form up next to them invites people to create a
+  // second way into the same account.
+  //
+  // An identity provider built on this package is the case that wants it on:
+  // its users *are* local, and it is the site people sign in to in order to
+  // sign in elsewhere.
+  //
+  // **This is only the default.** The deployment answer is
+  // `RAZZLE_IDENTITY_SHOW_PLONE_LOGIN`, read at *run* time by the Login
+  // component -- see `showPloneLogin` there. It is not read here, and that is
+  // the whole point: written out literally, `process.env.RAZZLE_...` is
+  // substituted into the browser bundle by webpack's DefinePlugin while
+  // `pnpm build` runs, which makes the value a property of the image. Two
+  // sites wanting two answers then need two images.
+  //
+  // A project that wants a different default overrides this setting in its
+  // own configuration, and the environment still wins over it.
+  config.settings.identityShowPloneLogin = false;
+
+  // The required-information gate, on every route.
+  //
+  // The backend has one too, and it lets `plone.restapi` requests through on
+  // purpose: Volto fetches the edit form over the API, so gating those would
+  // break the page the user is being sent to. Every navigation in this app is
+  // such a request, which means the backend gate never fires here and this is
+  // the one that does.
+  //
+  // An empty `match` mounts it everywhere, which is the point: a gate that
+  // only covers some routes is a list of ways around it.
+  config.settings.appExtras = [
+    ...(config.settings.appExtras ?? []),
+    // `props` is empty and still spelled out: `AppExtras` spreads it, so
+    // omitting it renders the same, but Volto's `Settings.d.ts` declares it
+    // required and the gate is the only entry this add-on adds.
+    { match: '', component: ProfileGate, props: {} },
+  ];
+  return config;
+}

package/src/config/views.ts

@@ -0,0 +1,30 @@
+import type { ConfigType } from '@plone/registry';
+import GroupView from '../components/Views/GroupView';
+import ProfileView from '../components/Views/ProfileView';
+
+/** Portal type of a user's Profile. */
+export const PROFILE_TYPE = 'UserProfile';
+
+/** Portal type of a group. */
+export const GROUP_TYPE = 'UserGroup';
+
+/**
+ * Give the two principal types views of their own.
+ *
+ * Both are content, so without this they rendered through Volto's default
+ * view: a title and a body that is empty, because neither type has rich text.
+ * What each page has to say is on fields the default view does not know about
+ * -- a person's picture, a group's nesting -- and for a group most of it is
+ * not on the content object at all.
+ *
+ * Registered by portal type rather than as a layout, so a site that files its
+ * users under its own type keeps its own view and gets neither of these.
+ */
+export default function install(config: ConfigType) {
+  config.views.contentTypesViews = {
+    ...config.views.contentTypesViews,
+    [PROFILE_TYPE]: ProfileView,
+    [GROUP_TYPE]: GroupView,
+  };
+  return config;
+}

package/src/config/widgets.ts

@@ -0,0 +1,25 @@
+import type { ConfigType } from '@plone/registry';
+import ProviderIconWidget from '../components/Widgets/ProviderIconWidget';
+
+/**
+ * The one widget this add-on supplies, and the reason it supplies only one.
+ *
+ * A widget is a component, so it can only live in the frontend. *Which* widget
+ * a field uses is a different question, and that one belongs to the backend:
+ * every field this add-on renders says so itself, through
+ * `directives.widget(..., frontendOptions={"widget": ...})`, and Volto looks
+ * the name up in this map. So the provider form asks for `color_picker` and
+ * `token` and gets Volto's own, and asks for `provider_icon` and gets this.
+ *
+ * That split is what the schema rewrite was about (Érico, 2026-08-29): the
+ * backend decides what a field is and how it should be edited, and the
+ * frontend supplies the component when it has one Volto does not.
+ */
+export default function install(config: ConfigType) {
+  config.widgets.widget = {
+    ...config.widgets.widget,
+    provider_icon: ProviderIconWidget,
+  };
+
+  return config;
+}

package/src/constants/ActionTypes.ts

@@ -0,0 +1,42 @@
+/**
+ * Action types for the identity add-on.
+ *
+ * Namespaced with the package name: Volto merges every add-on's reducers into
+ * one store, and a bare name like `LOGIN` would collide sooner or later.
+ * @module constants/ActionTypes
+ */
+
+export const LIST_LOGIN_PROVIDERS = 'IDENTITY_LIST_LOGIN_PROVIDERS';
+export const START_PROVIDER_LOGIN = 'IDENTITY_START_PROVIDER_LOGIN';
+export const COMPLETE_CALLBACK = 'IDENTITY_COMPLETE_CALLBACK';
+export const SEND_MAGIC_LINK = 'IDENTITY_SEND_MAGIC_LINK';
+export const CONFIRM_MAGIC_LINK = 'IDENTITY_CONFIRM_MAGIC_LINK';
+
+export const LIST_IDENTITIES = 'IDENTITY_LIST_IDENTITIES';
+export const START_LINKING = 'IDENTITY_START_LINKING';
+export const UNLINK_IDENTITY = 'IDENTITY_UNLINK_IDENTITY';
+
+export const LIST_GROUP_MEMBERS = 'IDENTITY_LIST_GROUP_MEMBERS';
+export const GET_USER_ACCOUNT = 'IDENTITY_GET_USER_ACCOUNT';
+
+export const GET_MY_PROFILE = 'IDENTITY_GET_MY_PROFILE';
+export const SET_PREFERRED_EMAIL = 'IDENTITY_SET_PREFERRED_EMAIL';
+export const GET_USER_PROFILE = 'IDENTITY_GET_USER_PROFILE';
+
+export const LIST_DRIVERS = 'IDENTITY_LIST_DRIVERS';
+export const LIST_PROVIDERS = 'IDENTITY_LIST_PROVIDERS';
+export const CREATE_PROVIDER = 'IDENTITY_CREATE_PROVIDER';
+export const UPDATE_PROVIDER = 'IDENTITY_UPDATE_PROVIDER';
+export const DELETE_PROVIDER = 'IDENTITY_DELETE_PROVIDER';
+export const TEST_PROVIDER = 'IDENTITY_TEST_PROVIDER';
+
+export const LIST_CLIENTS = 'IDENTITY_LIST_CLIENTS';
+export const CREATE_CLIENT = 'IDENTITY_CREATE_CLIENT';
+export const UPDATE_CLIENT = 'IDENTITY_UPDATE_CLIENT';
+export const DELETE_CLIENT = 'IDENTITY_DELETE_CLIENT';
+export const ROTATE_CLIENT_SECRET = 'IDENTITY_ROTATE_CLIENT_SECRET';
+export const LIST_KEYS = 'IDENTITY_LIST_KEYS';
+export const GET_CONSENT_REQUEST = 'IDENTITY_GET_CONSENT_REQUEST';
+export const LIST_GRANTS = 'IDENTITY_LIST_GRANTS';
+export const WITHDRAW_GRANT = 'IDENTITY_WITHDRAW_GRANT';
+export const ROTATE_KEY = 'IDENTITY_ROTATE_KEY';

package/src/constants/vocabularies.ts

@@ -0,0 +1,20 @@
+/**
+ * Vocabularies this add-on reads.
+ * @module constants/vocabularies
+ */
+
+/**
+ * The member fields a provider claim can be written to.
+ *
+ * Served by the backend from the site's live user schema, so it follows
+ * whatever the **User Schema** control panel was used to add.
+ */
+export const USER_FIELDS_VOCABULARY = 'pas.plugins.identity.UserFields';
+
+/**
+ * The groups a provider's group can be mapped onto.
+ *
+ * Every group PAS knows, whichever plugin answers for it, minus the virtual
+ * ones nobody is explicitly a member of.
+ */
+export const GROUPS_VOCABULARY = 'pas.plugins.identity.Groups';

package/src/customizations/volto/components/manage/Controlpanels/Users/RenderUsers.tsx

@@ -0,0 +1,23 @@
+/**
+ * Volto's users-control-panel row, replaced by this add-on's.
+ *
+ * Shadows `@plone/volto/components/manage/Controlpanels/Users/RenderUsers`
+ * (Volto 19.3.0).
+ *
+ * WHY IT IS SHADOWED. The row's {guilabel}`Edit` action is built inline and
+ * Volto has no extension point in it, so where that action leads cannot be
+ * changed without replacing the component. It led to the wrong form on the
+ * wrong store for every user whose fields live in a Profile, which is most of
+ * them.
+ *
+ * No code lives here. The component is
+ * `components/ControlPanel/RenderUsers`, with its tests and its stories
+ * beside it, and this file is the one line that puts it in Volto's place --
+ * a shadowed path is a wiring decision, not somewhere to keep an
+ * implementation nothing can import by name.
+ *
+ * @module customizations/volto/components/manage/Controlpanels/Users/RenderUsers
+ */
+import RenderUsers from '@plone-collective/volto-identity/components/ControlPanel/RenderUsers';
+
+export default RenderUsers;

package/src/customizations/volto/components/manage/Toolbar/PersonalTools.tsx

@@ -0,0 +1,21 @@
+/**
+ * Volto's personal-tools menu, replaced by this add-on's.
+ *
+ * Shadows `@plone/volto/components/manage/Toolbar/PersonalTools`
+ * (Volto 19.3.0).
+ *
+ * WHY IT IS SHADOWED. Volto has no extension point here. The only pluggable
+ * is `toolbar-user-menu`, at the end of the menu *list*, so the avatar block
+ * above it cannot be touched without replacing this component -- and the menu
+ * entries themselves cannot be reordered or removed at all.
+ *
+ * No code lives here. The component is `components/Toolbar/PersonalTools`,
+ * with its tests and its stories beside it, and this file is the one line
+ * that puts it in Volto's place -- a shadowed path is a wiring decision, not
+ * somewhere to keep an implementation nothing can import by name.
+ *
+ * @module customizations/volto/components/manage/Toolbar/PersonalTools
+ */
+import PersonalTools from '@plone-collective/volto-identity/components/Toolbar/PersonalTools';
+
+export default PersonalTools;

package/src/customizations/volto/components/manage/Toolbar/Toolbar.jsx

@@ -0,0 +1,21 @@
+/**
+ * Volto's toolbar, replaced by this add-on's.
+ *
+ * Shadows `@plone/volto/components/manage/Toolbar/Toolbar` (Volto 19.3.0).
+ *
+ * WHY IT IS SHADOWED. Volto has no extension point for the toolbar's user
+ * button. `toolbar-personal` is a DOM id on a button in this component, not a
+ * pluggable, so the icon it draws cannot be replaced without replacing the
+ * component around it -- and that icon is the generic `user.svg`, which says
+ * that somebody is signed in rather than who.
+ *
+ * No code lives here. The component is `components/Toolbar/Toolbar`, and this
+ * file is the one line that puts it in Volto's place -- a shadowed path is a
+ * wiring decision, not somewhere to keep an implementation nothing can import
+ * by name.
+ *
+ * @module customizations/volto/components/manage/Toolbar/Toolbar
+ */
+import Toolbar from '@plone-collective/volto-identity/components/Toolbar/Toolbar';
+
+export default Toolbar;

package/src/helpers/avatar.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+
+import { AVATAR_COLORS, colorFor, initialsFor } from './avatar';
+
+describe('initialsFor', () => {
+  it('takes the first letter of the first and last words', () => {
+    expect(initialsFor('Érico Andrei')).toBe('ÉA');
+  });
+
+  it('skips the middle names rather than the surname', () => {
+    // ÉA, not ÉD: a middle name must not push the surname out.
+    expect(initialsFor('Érico de Andrei')).toBe('ÉA');
+  });
+
+  it('takes two letters from a single name', () => {
+    expect(initialsFor('madonna')).toBe('MA');
+  });
+
+  it('takes one letter from a single-letter name', () => {
+    expect(initialsFor('x')).toBe('X');
+  });
+
+  it('uppercases for the locale', () => {
+    expect(initialsFor('érico andrei')).toBe('ÉA');
+  });
+
+  it('ignores words that carry no letter', () => {
+    // A userid like `alice (admin)` should not yield `A(`.
+    expect(initialsFor('alice (admin)')).toBe('AA');
+    // `bob - 2` has exactly one lettered word, so it is the single-name
+    // case: two letters from `bob`, not `B` twice.
+    expect(initialsFor('bob - 2')).toBe('BO');
+  });
+
+  it('answers nothing when there is no name at all', () => {
+    // The component draws a plain circle rather than an empty box.
+    expect(initialsFor('')).toBe('');
+    expect(initialsFor('   ')).toBe('');
+    expect(initialsFor(undefined)).toBe('');
+    expect(initialsFor(null)).toBe('');
+  });
+
+  it('answers nothing for a name with no letters in it', () => {
+    expect(initialsFor('123 456')).toBe('');
+  });
+
+  it('handles a name outside the Latin alphabet', () => {
+    expect(initialsFor('Ада Лавлейс')).toBe('АЛ');
+  });
+});
+
+describe('colorFor', () => {
+  it('always picks from the palette', () => {
+    for (const userid of ['alice', 'bob', '', 'a'.repeat(200), 'ürico']) {
+      expect(AVATAR_COLORS).toContain(colorFor(userid) as never);
+    }
+  });
+
+  it('is stable for the same user', () => {
+    // The point of deriving it: the same person is the same colour on every
+    // visit and every device, with nothing stored anywhere.
+    expect(colorFor('alice')).toBe(colorFor('alice'));
+  });
+
+  it('separates users who sit next to each other', () => {
+    // Not a guarantee for every pair -- ten colours cannot be -- but
+    // adjacent userids landing on one colour would be visible immediately.
+    const colors = new Set(
+      ['alice', 'bob', 'carol', 'dave'].map((id) => colorFor(id)),
+    );
+
+    expect(colors.size).toBeGreaterThan(1);
+  });
+
+  it('answers for a user with no id', () => {
+    expect(AVATAR_COLORS).toContain(colorFor(undefined) as never);
+    expect(AVATAR_COLORS).toContain(colorFor(null) as never);
+  });
+});

package/src/helpers/avatar.ts

@@ -0,0 +1,85 @@
+/**
+ * Standing in for a portrait nobody uploaded.
+ *
+ * Volto draws a camera icon when a user has no portrait, which is the same
+ * picture for everybody: it says "no image here" rather than "this is you".
+ * Initials on a colour derived from the userid are recognisable at a glance
+ * and stay put -- the same person gets the same colour on every visit, on
+ * every device, without anything being stored.
+ * @module helpers/avatar
+ */
+
+/**
+ * The palette initials are drawn on.
+ *
+ * Chosen for contrast against white text rather than for variety: every one
+ * of these clears WCAG AA at the size the avatar renders. Ten is enough that
+ * two people in a room rarely collide and few enough that each stays
+ * distinct -- a larger palette mostly adds colours that look alike.
+ */
+export const AVATAR_COLORS = [
+  '#0083be',
+  '#005d7a',
+  '#8b2f8b',
+  '#a13d63',
+  '#b5451b',
+  '#7a5c00',
+  '#2d6a4f',
+  '#1b5e8b',
+  '#5f3dc4',
+  '#8a3324',
+] as const;
+
+/**
+ * Return the initials to draw for a user.
+ *
+ * @param name The user's full name, or their login when they have no name.
+ * @returns One or two uppercase letters, or an empty string when the name
+ *   carries no letter at all.
+ */
+export function initialsFor(name: string | undefined | null): string {
+  const words = (name ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter((word) => /\p{L}/u.test(word));
+  if (words.length === 0) {
+    return '';
+  }
+  // First and last rather than the first two: "Érico de Andrei" reads as ÉA,
+  // and a middle name should not push the surname out.
+  const letters =
+    words.length === 1
+      ? [...words[0]].filter((c) => /\p{L}/u.test(c)).slice(0, 2)
+      : [firstLetter(words[0]), firstLetter(words[words.length - 1])];
+  return letters.join('').toLocaleUpperCase();
+}
+
+/**
+ * Return the first letter of a word, skipping anything that is not one.
+ *
+ * @param word The word.
+ * @returns The letter, or an empty string.
+ */
+function firstLetter(word: string): string {
+  return [...word].find((c) => /\p{L}/u.test(c)) ?? '';
+}
+
+/**
+ * Return the colour a user's initials are drawn on.
+ *
+ * Derived from the userid rather than the name, so somebody correcting the
+ * spelling of their own name does not change colour.
+ *
+ * @param userid The canonical Plone userid.
+ * @returns One of :data:`AVATAR_COLORS`.
+ */
+export function colorFor(userid: string | undefined | null): string {
+  const seed = userid ?? '';
+  let hash = 0;
+  for (const char of seed) {
+    // Ordinary string hash. It needs to be stable and spread, not secure --
+    // this picks a colour, and knowing how it picks reveals nothing.
+    hash = (hash * 31 + char.codePointAt(0)!) % 0xffffffff;
+  }
+  return AVATAR_COLORS[hash % AVATAR_COLORS.length];
+}

package/src/helpers/callback.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { readCallback } from './callback';
+
+describe('readCallback', () => {
+  it('reads an authorization code', () => {
+    const parsed = readCallback('?code=abc&state=xyz&provider=dex');
+
+    expect(parsed.kind).toBe('code');
+    expect(parsed.code).toBe('abc');
+    expect(parsed.state).toBe('xyz');
+    expect(parsed.provider).toBe('dex');
+  });
+
+  it('reads a magic link', () => {
+    const parsed = readCallback('?magic_link=tok');
+
+    expect(parsed.kind).toBe('magic-link');
+    expect(parsed.token).toBe('tok');
+  });
+
+  it('reports a provider refusal', () => {
+    // Providers signal a refusal by redirecting back with ?error=, not by
+    // failing the redirect. Missing this leaves the page spinning forever.
+    const parsed = readCallback('?error=access_denied&state=xyz');
+
+    expect(parsed.kind).toBe('error');
+    expect(parsed.error).toBe('access_denied');
+  });
+
+  it('prefers the refusal over a code that came with it', () => {
+    const parsed = readCallback('?error=access_denied&code=abc&state=xyz');
+
+    expect(parsed.kind).toBe('error');
+  });
+
+  it('treats a code without a state as incomplete', () => {
+    expect(readCallback('?code=abc').kind).toBe('none');
+  });
+
+  it('treats a state without a code as incomplete', () => {
+    expect(readCallback('?state=xyz').kind).toBe('none');
+  });
+
+  it('treats an empty query as incomplete', () => {
+    expect(readCallback('').kind).toBe('none');
+  });
+
+  it('ignores repeated parameters rather than guessing', () => {
+    // qs.parse gives an array for a repeated key. Taking the first would be
+    // picking one of two credentials an attacker supplied.
+    expect(readCallback('?magic_link=one&magic_link=two').kind).toBe('none');
+  });
+
+  it('defaults the provider to empty rather than undefined', () => {
+    const parsed = readCallback('?code=abc&state=xyz');
+
+    expect(parsed.provider).toBe('');
+  });
+});

package/src/helpers/callback.ts

@@ -0,0 +1,71 @@
+/**
+ * Reading the credential off a callback URL.
+ *
+ * Kept out of the component so it can be tested as what it is: a pure
+ * function over a query string, and the place every refusal is decided.
+ *
+ * Uses ``URLSearchParams`` rather than a query-string library, which brings
+ * the repeated-parameter handling with it: ``getAll`` makes ``?code=a&code=b``
+ * visibly two values, and picking one of two credentials an attacker supplied
+ * is not a decision this should be making quietly.
+ * @module helpers/callback
+ */
+
+export type CallbackKind = 'code' | 'magic-link' | 'error' | 'none';
+
+export interface ParsedCallback {
+  kind: CallbackKind;
+  provider?: string;
+  code?: string;
+  state?: string;
+  token?: string;
+  error?: string;
+}
+
+/**
+ * Return a parameter only when it appears exactly once.
+ *
+ * @param params The parsed query string.
+ * @param name Parameter to read.
+ * @returns The value, or ``undefined`` when absent or repeated.
+ */
+function single(params: URLSearchParams, name: string): string | undefined {
+  const values = params.getAll(name);
+  return values.length === 1 ? values[0] : undefined;
+}
+
+/**
+ * Read the credential off a callback URL.
+ *
+ * @param search The query string, with or without its leading ``?``.
+ * @returns What kind of callback this is, and its parts.
+ */
+export function readCallback(search: string): ParsedCallback {
+  const params = new URLSearchParams(search);
+
+  const error = single(params, 'error');
+  if (error) {
+    // Providers report a refusal by redirecting back with ?error=, not by
+    // failing the redirect. Without this the page would sit on "signing you
+    // in" forever.
+    return { kind: 'error', error };
+  }
+
+  const token = single(params, 'magic_link');
+  if (token) {
+    return { kind: 'magic-link', token };
+  }
+
+  const code = single(params, 'code');
+  const state = single(params, 'state');
+  if (code && state) {
+    return {
+      kind: 'code',
+      code,
+      state,
+      provider: single(params, 'provider') ?? '',
+    };
+  }
+
+  return { kind: 'none' };
+}