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

package/src/helpers/clientSchema.test.ts

@@ -0,0 +1,182 @@
+/**
+ * The client form is composed, not invented.
+ *
+ * What used to be asserted here — which grants exist, what each field is
+ * called, which of them are text boxes — is the backend's answer now,
+ * serialized by `plone.restapi` from `IClientRecords`. So the grants offered
+ * are exactly what the token endpoint implements, without this file holding a
+ * list that could drift from it.
+ *
+ * What is left to test is the composition, and the two questions that exist
+ * only while a client is being registered.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  EDITABLE,
+  clientSchema,
+  fromFormData,
+  toFormData,
+} from './clientSchema';
+import type { OAuthClient } from '../types';
+
+const intl = {
+  formatMessage: (m: { defaultMessage: string }) => m.defaultMessage,
+} as any;
+
+/** What `@identity-clients` sends: `IClientRecords`, serialized. */
+const SERVED = {
+  type: 'object',
+  properties: {
+    title: { title: 'Title', type: 'string' },
+    enabled: { title: 'Enabled', type: 'boolean' },
+    redirect_uris: { title: 'Redirect URIs', type: 'array', widget: 'token' },
+    grant_types: {
+      title: 'Grants',
+      type: 'array',
+      choices: [
+        ['authorization_code', 'authorization_code'],
+        ['client_credentials', 'client_credentials'],
+        ['refresh_token', 'refresh_token'],
+      ],
+    },
+    scope: { title: 'Scopes', type: 'array' },
+    service_user: { title: 'Acts as', type: 'string' },
+  },
+  required: ['title'],
+  fieldsets: [
+    { id: 'default', title: 'Default', fields: ['title', 'enabled'] },
+    {
+      id: 'flow',
+      title: 'Flow',
+      fields: ['redirect_uris', 'grant_types', 'scope', 'service_user'],
+    },
+  ],
+};
+
+describe('clientSchema', () => {
+  it('carries the served properties through untouched', () => {
+    const schema = clientSchema(SERVED, false, intl);
+
+    expect(schema.properties.grant_types).toEqual(
+      SERVED.properties.grant_types,
+    );
+  });
+
+  it('offers exactly the grants the backend implements', () => {
+    // Not a list this file keeps in step by hand. The vocabulary is built on
+    // the backend from what the token endpoint serves and what discovery
+    // advertises, so the three can no longer disagree.
+    const schema = clientSchema(SERVED, true, intl);
+
+    expect(
+      (schema.properties.grant_types as any).choices.map(
+        ([value]: [string, string]) => value,
+      ),
+    ).toEqual(['authorization_code', 'client_credentials', 'refresh_token']);
+  });
+
+  it('asks for the permanent id only when registering', () => {
+    expect(clientSchema(SERVED, true, intl).properties.client_id).toBeTruthy();
+    expect(
+      clientSchema(SERVED, false, intl).properties.client_id,
+    ).toBeUndefined();
+  });
+
+  it('requires the id it cannot invent', () => {
+    expect(clientSchema(SERVED, true, intl).required).toContain('client_id');
+  });
+
+  it('offers whether a client is public only at registration', () => {
+    // It decides whether a secret is minted, which is a fact about
+    // registration rather than a setting.
+    expect(clientSchema(SERVED, true, intl).properties.public).toBeTruthy();
+    expect(clientSchema(SERVED, false, intl).properties.public).toBeUndefined();
+  });
+
+  it('asks nothing an edit cannot change', () => {
+    const schema = clientSchema(SERVED, false, intl);
+    const offered = schema.fieldsets.flatMap((f) => f.fields);
+
+    expect(offered.every((field) => EDITABLE.includes(field))).toBe(true);
+  });
+
+  it('survives a backend that sent no schema', () => {
+    // An empty form is recoverable; a crash on `schema.fieldsets` is not.
+    const schema = clientSchema(undefined, true, intl);
+
+    expect(schema.fieldsets).toEqual([]);
+  });
+});
+
+describe('toFormData', () => {
+  it('starts a registration on the grant that makes it work', () => {
+    expect(toFormData().grant_types).toEqual(['authorization_code']);
+  });
+
+  it('edits a scope as the list of permissions it is', () => {
+    // The backend field is a tuple of choices, so nothing here splits a
+    // string any more -- the two conversions this helper used to do existed
+    // only because the record was one line of space-separated text.
+    const client = { scope: ['openid', 'profile', 'email'] } as OAuthClient;
+
+    expect(toFormData(client).scope).toEqual(['openid', 'profile', 'email']);
+  });
+
+  it('copies the scopes rather than sharing them', () => {
+    // The form mutates what it is given, and the client in the store is not
+    // the form's to edit.
+    const client = { scope: ['openid'] } as OAuthClient;
+
+    expect(toFormData(client).scope).not.toBe(client.scope);
+  });
+
+  it('has no scopes for a client that carries none', () => {
+    expect(toFormData({} as OAuthClient).scope).toEqual([]);
+  });
+});
+
+describe('fromFormData', () => {
+  it('sends the scopes as the list the record now holds', () => {
+    const payload = fromFormData({ scope: ['openid', 'email'] }, true);
+
+    expect(payload.scope).toEqual(['openid', 'email']);
+  });
+
+  it('drops the scope widget’s empty rows too', () => {
+    const payload = fromFormData({ scope: ['openid', '', null] }, true);
+
+    expect(payload.scope).toEqual(['openid']);
+  });
+
+  it('drops a list widget’s empty rows', () => {
+    const payload = fromFormData(
+      { redirect_uris: ['https://a.example/cb', '', null] },
+      true,
+    );
+
+    expect(payload.redirect_uris).toEqual(['https://a.example/cb']);
+  });
+
+  it('does not judge a redirect URI', () => {
+    // Whether this server will send a browser there is decided on the backend
+    // field, which refuses it and says why. Correcting it here would only
+    // hide which value the refusal is about.
+    const payload = fromFormData(
+      { redirect_uris: ['  https://a.example/cb#frag  '] },
+      true,
+    );
+
+    expect(payload.redirect_uris).toEqual(['  https://a.example/cb#frag  ']);
+  });
+
+  it('sends only what a PATCH accepts', () => {
+    // The backend refuses the whole request when it sees a field it will not
+    // change, so the two lists agreeing is what keeps an edit from failing
+    // wholesale.
+    const payload = fromFormData({ title: 'x', client_id: 'nope' }, false);
+
+    expect(payload.client_id).toBeUndefined();
+    expect(Object.keys(payload).every((k) => EDITABLE.includes(k))).toBe(true);
+  });
+});

package/src/helpers/clientSchema.ts

@@ -0,0 +1,181 @@
+/**
+ * The OAuth client form, composed from what the backend already sent.
+ *
+ * This file used to build the schema: its own grant list, its own labels, its
+ * own English. The backend serves one now, produced by `plone.restapi` from
+ * `IClientRecords` — the interface the client's own storage is described by —
+ * so the grants offered are exactly what the token endpoint implements, and
+ * every label is translated in the site's language.
+ *
+ * What is left is composition and the two questions that exist only while a
+ * client is being registered: the permanent `client_id`, and whether the
+ * client is public. Neither is a stored field an operator edits — the first
+ * becomes the record prefix and the second decides whether a secret is minted
+ * — so neither is in the schema, and both disappear from the edit form.
+ * @module helpers/clientSchema
+ */
+import { defineMessages } from 'react-intl';
+
+import type { JsonSchema, OAuthClient, VoltoSchema } from '../types';
+
+import type { IntlShape } from 'react-intl';
+
+/**
+ * Fields a `PATCH` may change.
+ *
+ * Mirrors `EDITABLE` in the backend's patch service, which refuses anything
+ * else outright rather than dropping it silently. `client_id` and the auth
+ * method are absent from both: changing either means registering a new
+ * client, and the form says so rather than offering a field the backend
+ * would reject.
+ */
+export const EDITABLE = [
+  'title',
+  'redirect_uris',
+  'grant_types',
+  'scope',
+  'enabled',
+  'service_user',
+];
+
+const messages = defineMessages({
+  registration: { id: 'Registration', defaultMessage: 'Registration' },
+  clientId: { id: 'Client ID', defaultMessage: 'Client ID' },
+  clientIdHelp: {
+    id: 'client-id-help',
+    defaultMessage:
+      'Permanent. It is what every token already issued is bound to, so it ' +
+      'cannot be changed afterwards.',
+  },
+  publicClient: { id: 'Public client', defaultMessage: 'Public client' },
+  publicClientHelp: {
+    id: 'client-public-help',
+    defaultMessage:
+      'A native or browser app, which cannot keep a secret. No secret is ' +
+      'minted and PKCE becomes mandatory instead.',
+  },
+});
+
+/**
+ * Build the client form from the schema the backend sent.
+ *
+ * @param served The schema from `@identity-clients`.
+ * @param adding Whether this registers a client, which asks two more
+ *   questions than an edit does.
+ * @param intl For the labels of the two registration-only fields.
+ * @returns A Volto schema.
+ */
+export function clientSchema(
+  served: JsonSchema | undefined,
+  adding: boolean,
+  intl: IntlShape,
+): VoltoSchema {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const fieldsets: { id: string; title: string; fields: string[] }[] = [];
+  const required = [...(served?.required ?? [])];
+
+  if (adding) {
+    properties.client_id = {
+      title: intl.formatMessage(messages.clientId),
+      description: intl.formatMessage(messages.clientIdHelp),
+      type: 'string',
+    };
+    properties.public = {
+      title: intl.formatMessage(messages.publicClient),
+      description: intl.formatMessage(messages.publicClientHelp),
+      type: 'boolean',
+    };
+    required.push('client_id');
+  }
+
+  Object.assign(properties, served?.properties ?? {});
+
+  (served?.fieldsets ?? []).forEach((fieldset, index) => {
+    const fields =
+      index === 0
+        ? [
+            ...(adding ? ['client_id'] : []),
+            ...fieldset.fields.filter(
+              (name) => adding || EDITABLE.includes(name),
+            ),
+            ...(adding ? ['public'] : []),
+          ]
+        : fieldset.fields.filter((name) => adding || EDITABLE.includes(name));
+    if (fields.length) {
+      fieldsets.push({
+        id: fieldset.id,
+        title:
+          index === 0 && adding
+            ? intl.formatMessage(messages.registration)
+            : fieldset.title,
+        fields,
+      });
+    }
+  });
+
+  return { fieldsets, properties, required };
+}
+
+/**
+ * Turn a client from the API into form data.
+ *
+ * @param client The client, or undefined when registering.
+ * @returns Form data.
+ */
+export function toFormData(client?: OAuthClient): Record<string, unknown> {
+  if (!client) {
+    // `Form` seeds the rest from the schema's own defaults; what it cannot
+    // know is that a new registration is meant to work, which is what the
+    // authorization-code grant amounts to.
+    return { grant_types: ['authorization_code'], public: false };
+  }
+  return {
+    title: client.title ?? '',
+    enabled: client.enabled ?? true,
+    grant_types: [...(client.grant_types ?? [])],
+    redirect_uris: [...(client.redirect_uris ?? [])],
+    scope: [...(client.scope ?? [])],
+    service_user: client.service_user ?? '',
+  };
+}
+
+/**
+ * Turn submitted form data back into the API payload.
+ *
+ * Shape only. Whether a redirect URI is one this server will send a browser
+ * to is decided on the backend field, which refuses a fragment, a wildcard, a
+ * `javascript:` scheme and plain HTTP off the loopback -- and says which. The
+ * blank entries dropped below are a list widget's empty rows, not a judgement
+ * about any value somebody typed.
+ *
+ * @param formData What the form submitted.
+ * @param adding Whether this registers a client; an edit sends only what
+ *   the backend accepts, since it refuses the whole request otherwise.
+ * @returns The body for POST or PATCH.
+ */
+export function fromFormData(
+  formData: Record<string, any>,
+  adding: boolean,
+): Record<string, unknown> {
+  const data = formData ?? {};
+  const payload: Record<string, unknown> = {
+    title: data.title ?? '',
+    grant_types: [...(data.grant_types ?? [])],
+    redirect_uris: (data.redirect_uris ?? []).filter(Boolean),
+    scope: (data.scope ?? []).filter(Boolean),
+    service_user: data.service_user ?? '',
+  };
+
+  if (adding) {
+    payload.client_id = String(data.client_id ?? '').trim();
+    payload.public = Boolean(data.public);
+    return payload;
+  }
+  payload.enabled = Boolean(data.enabled);
+  // Filtered rather than assembled a second time: the backend refuses the
+  // whole request when it sees a field it will not change, so the two lists
+  // agreeing is what keeps an edit from failing wholesale.
+  return Object.fromEntries(
+    Object.entries(payload).filter(([field]) => EDITABLE.includes(field)),
+  );
+}

package/src/helpers/firstLogin.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+import { afterLogin, toAppPath } from './firstLogin';
+import type { MyProfile } from '../types';
+
+function profile(overrides: Partial<MyProfile> = {}): MyProfile {
+  return {
+    '@id': 'http://backend:8080/Plone/@my-profile',
+    userid: 'alice-userid',
+    profile: 'http://backend:8080/Plone/identity-profiles/alice-userid',
+    review_state: 'incomplete',
+    missing: [],
+    ...overrides,
+  };
+}
+
+describe('toAppPath', () => {
+  it('strips a configured backend base', () => {
+    expect(
+      toAppPath(
+        'http://backend:8080/Plone/identity-profiles/alice',
+        'http://backend:8080/Plone',
+      ),
+    ).toBe('/identity-profiles/alice');
+  });
+
+  it('strips the origin when there is no configured base', () => {
+    expect(toAppPath('https://example.com/identity-profiles/alice')).toBe(
+      '/identity-profiles/alice',
+    );
+  });
+
+  it('leaves an already relative path alone', () => {
+    expect(toAppPath('/identity-profiles/alice')).toBe(
+      '/identity-profiles/alice',
+    );
+  });
+
+  it('adds the leading slash a relative answer may lack', () => {
+    expect(toAppPath('identity-profiles/alice')).toBe(
+      '/identity-profiles/alice',
+    );
+  });
+
+  it('handles an origin with nothing after it', () => {
+    expect(toAppPath('https://example.com')).toBe('/');
+  });
+
+  it('treats an empty URL as the site root', () => {
+    expect(toAppPath('')).toBe('/');
+  });
+});
+
+describe('afterLogin', () => {
+  it('diverts a user whose profile is incomplete to its edit form', () => {
+    // The edit form rather than the profile: it is missing something the
+    // site requires, and the view would ask for one more click to reach the
+    // only thing they can do about that.
+    expect(afterLogin(profile(), '/news', 'http://backend:8080/Plone')).toBe(
+      '/identity-profiles/alice-userid/edit',
+    );
+  });
+
+  it('leaves a completed profile alone', () => {
+    expect(afterLogin(profile({ review_state: 'complete' }), '/news')).toBe(
+      '/news',
+    );
+  });
+
+  it('does not divert a deactivated profile', () => {
+    // Diverting here would send somebody to a Profile they cannot even view.
+    expect(afterLogin(profile({ review_state: 'deactivated' }), '/news')).toBe(
+      '/news',
+    );
+  });
+
+  it('carries on when the user has no profile', () => {
+    expect(
+      afterLogin(profile({ profile: null, review_state: null }), '/news'),
+    ).toBe('/news');
+  });
+
+  it('carries on in a site without the extra installed', () => {
+    expect(afterLogin(null, '/news')).toBe('/news');
+  });
+
+  it('carries on before the answer has loaded', () => {
+    expect(afterLogin(undefined, '/news')).toBe('/news');
+  });
+});

package/src/helpers/firstLogin.ts

@@ -0,0 +1,76 @@
+/**
+ * Deciding where a just-signed-in user lands when the site has Profiles.
+ *
+ * Pure, and separate from the container, for the same reason `returnUrl` is:
+ * the decision is small, it is easy to get subtly wrong, and every branch of
+ * it deserves a test that does not need a store.
+ * @module helpers/firstLogin
+ */
+
+import { rememberReturn } from './profileGate';
+
+import type { MyProfile } from '../types';
+
+/**
+ * Turn an absolute backend URL into a path this Volto app can route to.
+ *
+ * The backend answers with the URL it is served under, which in a split
+ * deployment is not the URL the browser is on. Passing that straight to
+ * `history.push` would navigate off the frontend and land the user on the
+ * backend's own rendering of the Profile.
+ *
+ * @param url Absolute or relative URL from the backend.
+ * @param apiPath The backend's base URL, when it differs from the frontend's.
+ * @returns A site-relative path, always beginning with a slash.
+ */
+export function toAppPath(url: string, apiPath = ''): string {
+  if (!url) {
+    return '/';
+  }
+  let path = url;
+  if (apiPath && path.startsWith(apiPath)) {
+    path = path.slice(apiPath.length);
+  } else {
+    // No configured base, or the answer came from somewhere else: fall back to
+    // stripping the origin, which is all a path needs.
+    const match = /^https?:\/\/[^/]+(\/.*)?$/.exec(path);
+    if (match) {
+      path = match[1] ?? '/';
+    }
+  }
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+/**
+ * Work out where to send a user who has just signed in.
+ *
+ * Only an `incomplete` Profile diverts them. Every other answer — no Profile,
+ * a `complete` one, a `deactivated` one, a site without the extra installed —
+ * means "carry on where you were going". Diverting on anything else would
+ * trap a user with a deliberately sparse profile in a loop they cannot leave.
+ *
+ * They land on the **edit form** rather than on the profile. The profile is
+ * missing something the site requires, and a read-only page showing them that
+ * asks for an extra click to reach the only thing they can do about it.
+ *
+ * @param profile The `@my-profile` answer, or null before it has loaded.
+ * @param fallback Where the user was heading.
+ * @param apiPath The backend's base URL, when it differs from the frontend's.
+ * @returns The path to navigate to.
+ */
+export function afterLogin(
+  profile: MyProfile | null | undefined,
+  fallback: string,
+  apiPath = '',
+): string {
+  if (!profile?.profile || profile.review_state !== 'incomplete') {
+    return fallback;
+  }
+  // Where they were heading is not thrown away, it is parked. `ProfileGate`
+  // restores it the moment the profile stops being incomplete, which is what
+  // turns "you must fill this in first" into a detour rather than a dead end.
+  // In the demo that dead end was a user stranded on the identity provider,
+  // mid-way through signing in to a different site.
+  rememberReturn(fallback);
+  return `${toAppPath(profile.profile, apiPath)}/edit`;
+}

package/src/helpers/groupmap.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+
+import { fromGroupRows, toGroupRows } from './groupmap';
+
+describe('toGroupRows', () => {
+  it('turns a map into rows', () => {
+    expect(toGroupRows({ editors: 'site-editors' })).toEqual([
+      { '@id': expect.any(String), group: 'editors', local: 'site-editors' },
+    ]);
+  });
+
+  it('gives every row an @id', () => {
+    // ObjectListWidget keys its drag list on it and renders nothing for a
+    // row without one -- a silent empty list, not an error.
+    const rows = toGroupRows({ editors: 'site-editors', staff: 'site-staff' });
+
+    expect(rows.every((row) => row['@id'])).toBe(true);
+    expect(rows[0]['@id']).not.toEqual(rows[1]['@id']);
+  });
+
+  it('keeps the stored order', () => {
+    const rows = toGroupRows({ staff: 'site-staff', editors: 'site-editors' });
+
+    expect(rows.map((row) => row.group)).toEqual(['staff', 'editors']);
+  });
+
+  it('survives an absent map', () => {
+    expect(toGroupRows(undefined)).toEqual([]);
+  });
+});
+
+describe('fromGroupRows', () => {
+  it('turns rows back into a map', () => {
+    expect(
+      fromGroupRows([{ '@id': 'a', group: 'editors', local: 'site-editors' }]),
+    ).toEqual({ editors: 'site-editors' });
+  });
+
+  it('drops a row the operator has not finished', () => {
+    // A blank row is what pressing Add produces, and it must not be stored.
+    // It matters more here than in the property map: a half-written row that
+    // reached the backend as a key with an empty value is a mapping that
+    // grants nothing while looking on screen like one that grants something.
+    const blank = { '@id': 'a', group: '', local: '' };
+
+    expect(fromGroupRows([blank])).toEqual({});
+    expect(fromGroupRows([{ ...blank, group: 'editors' }])).toEqual({});
+    expect(fromGroupRows([{ ...blank, local: 'site-editors' }])).toEqual({});
+  });
+
+  it('trims both halves', () => {
+    const rows = [
+      { '@id': 'a', group: '  editors  ', local: '  site-editors  ' },
+    ];
+
+    expect(fromGroupRows(rows)).toEqual({ editors: 'site-editors' });
+  });
+
+  it('keeps the last of a repeated provider group', () => {
+    // Which is what the object it becomes would do anyway.
+    const rows = [
+      { '@id': 'a', group: 'editors', local: 'site-editors' },
+      { '@id': 'b', group: 'editors', local: 'site-staff' },
+    ];
+
+    expect(fromGroupRows(rows)).toEqual({ editors: 'site-staff' });
+  });
+
+  it('lets two provider groups grant the same local group', () => {
+    const rows = [
+      { '@id': 'a', group: 'editors', local: 'staff' },
+      { '@id': 'b', group: 'authors', local: 'staff' },
+    ];
+
+    expect(fromGroupRows(rows)).toEqual({ editors: 'staff', authors: 'staff' });
+  });
+
+  it('survives absent rows', () => {
+    expect(fromGroupRows(undefined)).toEqual({});
+  });
+});

package/src/helpers/groupmap.ts

@@ -0,0 +1,50 @@
+/**
+ * Conversion between the stored group map and the rows an editor shows.
+ *
+ * The mechanics are shared with the property map and live in
+ * {@link module:helpers/rowmap}; what belongs here is only the names this
+ * mapping's two halves go by.
+ *
+ * The halves are not symmetric, and the widget reflects that. The provider
+ * side is free text, because it is whatever the far end's directory happens
+ * to call a group and this site has no way to enumerate it. The local side is
+ * a vocabulary, because a group that does not exist here grants nothing --
+ * the backend skips it and logs -- and a picker is how that stops being a
+ * typo nobody notices.
+ * @module helpers/groupmap
+ */
+
+import { rowConverters } from './rowmap';
+
+/** One row of the group mapping editor. */
+export interface GroupMapRow {
+  '@id': string;
+  group: string;
+  local: string;
+}
+
+const converters = rowConverters<GroupMapRow>('group', 'local');
+
+/**
+ * Turn a stored group map into editor rows.
+ *
+ * @param map Provider-side group name to local group id.
+ * @returns One row per entry, in the map's own order.
+ */
+export function toGroupRows(
+  map: Record<string, string> | undefined,
+): GroupMapRow[] {
+  return converters.toRows(map);
+}
+
+/**
+ * Turn editor rows back into a stored group map.
+ *
+ * @param rows Rows from the editor.
+ * @returns Provider-side group name to local group id.
+ */
+export function fromGroupRows(
+  rows: GroupMapRow[] | undefined,
+): Record<string, string> {
+  return converters.fromRows(rows);
+}

package/src/helpers/identities.ts

@@ -0,0 +1,22 @@
+/**
+ * Working out what a user can still add, and how.
+ * @module helpers/identities
+ */
+
+/**
+ * The driver whose flow is a mailbox rather than a redirect.
+ *
+ * The login form renders it as an address field instead of a button, because
+ * the thing being proven is control of a mailbox and only the person signing
+ * in knows which one.
+ *
+ * It is *not* offered on the sign-in-methods page. The address a magic link
+ * proves is whatever was typed, so a free-text box there verifies any mailbox
+ * at all -- and a verified address is what a provider account can be
+ * auto-attached to. The addresses this site will verify are the ones already
+ * on your profile, and that page offers those instead. The backend enforces
+ * the same rule in two places, so this constant is a label rather than a
+ * gate: `@identities` leaves the provider out of `available`, and
+ * `POST @identities` refuses an address that is not yours.
+ */
+export const EMAIL_DRIVER = 'email';