@manablox/api-rpc 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@manablox/api-rpc",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/auth": "0.1.0",
+    "@manablox/core": "0.1.0",
+    "@manablox/db": "0.1.0",
+    "@manablox/media": "0.1.0",
+    "@manablox/services": "0.1.0",
+    "@orpc/server": "^1.15.0",
+    "@orpc/openapi": "^1.15.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/base.ts

@@ -0,0 +1,68 @@
+import { assertCan, type Permission } from '@manablox/auth';
+import { ManabloxError } from '@manablox/core';
+import { ORPCError, os } from '@orpc/server';
+import type { RpcContext } from './context.js';
+
+/**
+ * Base procedure builder. Every management procedure runs through it, so the
+ * `ManabloxError` → transport mapping lives in exactly one place.
+ */
+export const base = os.$context<RpcContext>().use(async ({ next }) => {
+  try {
+    return await next();
+  } catch (error) {
+    throw toOrpcError(error);
+  }
+});
+
+export function toOrpcError(error: unknown): unknown {
+  if (!ManabloxError.is(error)) return error;
+
+  const code = (
+    {
+      validation: 'BAD_REQUEST',
+      bad_request: 'BAD_REQUEST',
+      not_found: 'NOT_FOUND',
+      conflict: 'CONFLICT',
+      forbidden: 'FORBIDDEN',
+      unauthorized: 'UNAUTHORIZED',
+      internal: 'INTERNAL_SERVER_ERROR',
+    } as const
+  )[error.kind];
+
+  return new ORPCError(code, {
+    message: error.key,
+    // Structured details survive to the client: key, path and params per problem.
+    data: { key: error.key, details: error.details },
+  });
+}
+
+/** Requires an authenticated principal. */
+export const authed = base.use(async ({ context, next }) => {
+  if (!context.principal) throw toOrpcError(ManabloxError.unauthorized());
+  return next({ context: { ...context, principal: context.principal } });
+});
+
+/**
+ * Requires a permission in the space named by the input's `spaceId`.
+ *
+ * Authorisation is a middleware rather than a call at the top of each handler, so a new
+ * procedure cannot forget it — the input type makes `spaceId` mandatory.
+ */
+export function scoped(permission: Permission) {
+  return authed.use(async ({ context, next }, input: unknown) => {
+    const spaceId = (input as { spaceId?: string } | undefined)?.spaceId ?? null;
+    assertCan(context.principal, spaceId, permission);
+    return next();
+  });
+}
+
+/** Requires an instance-wide superadmin, for operations that are not space-scoped. */
+export const superadmin = authed.use(async ({ context, next }) => {
+  // A space-restricted API key is confined to those spaces, so it never reaches an
+  // instance-wide operation even when its owner is a superadmin.
+  if (context.principal?.role !== 'superadmin' || context.principal.allowedSpaceIds) {
+    throw toOrpcError(ManabloxError.forbidden('auth.superadminRequired'));
+  }
+  return next();
+});

package/src/context.ts

@@ -0,0 +1,18 @@
+import type { ApiKeyService, ManabloxAuth, Principal } from '@manablox/auth';
+import type { Manablox } from '@manablox/core';
+import type { Repositories } from '@manablox/db';
+import type { MediaService } from '@manablox/media';
+import type { ContentService, ContentTypeService, Loaders } from '@manablox/services';
+
+export interface RpcContext {
+  manablox: Manablox;
+  repos: Repositories;
+  auth: ManabloxAuth;
+  apiKeys: ApiKeyService;
+  media: MediaService;
+  content: ContentService;
+  contentTypes: ContentTypeService;
+  loaders: Loaders;
+  principal: Principal | null;
+  headers: Headers;
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { assetRouter } from './routers/asset.js';
+import { contentRouter } from './routers/content.js';
+import { contentTypeRouter } from './routers/content-type.js';
+import { spaceRouter } from './routers/space.js';
+import { userRouter } from './routers/user.js';
+
+export * from './base.js';
+export * from './context.js';
+
+/**
+ * The management API. The admin imports the *type* of this object and gets end-to-end
+ * safety with no codegen step.
+ */
+export const router = {
+  content: contentRouter,
+  contentTypes: contentTypeRouter,
+  spaces: spaceRouter,
+  assets: assetRouter,
+  users: userRouter,
+};
+
+export type ManabloxRouter = typeof router;

package/src/routers/asset.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { scoped } from '../base.js';
+
+const uuid = z.string().uuid();
+
+export const assetRouter = {
+  list: scoped('asset:read')
+    .input(
+      z.object({
+        spaceId: uuid,
+        mimeType: z.string().optional(),
+        search: z.string().max(200).optional(),
+        limit: z.number().int().min(1).max(100).default(40),
+        offset: z.number().int().min(0).default(0),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      const page = await context.repos.assets.list(
+        {
+          spaceId: input.spaceId,
+          ...(input.mimeType ? { mimeType: input.mimeType } : {}),
+          ...(input.search ? { search: input.search } : {}),
+        },
+        { limit: input.limit, offset: input.offset },
+      );
+      return {
+        ...page,
+        items: page.items.map((asset) => ({
+          ...asset,
+          url: context.media.urlFor(asset),
+          thumbnailUrl: asset.mimeType.startsWith('image/')
+            ? context.media.urlFor(asset, 'thumb', 'webp')
+            : null,
+        })),
+      };
+    }),
+
+  get: scoped('asset:read')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      const asset = await context.repos.assets.findById(input.id);
+      if (!asset) return null;
+      return { ...asset, url: context.media.urlFor(asset) };
+    }),
+
+  update: scoped('asset:write')
+    .input(
+      z.object({
+        spaceId: uuid,
+        id: uuid,
+        name: z.string().max(200).optional(),
+        alt: z.string().max(500).nullable().optional(),
+        title: z.string().max(500).nullable().optional(),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      const { spaceId: _spaceId, id, ...data } = input;
+      return context.repos.assets.update(id, data);
+    }),
+
+  delete: scoped('asset:delete')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      await context.media.delete(input.id);
+      return { ok: true };
+    }),
+};

package/src/routers/content-type.ts

@@ -0,0 +1,116 @@
+import { renderContentTypeConfig } from '@manablox/services';
+import { z } from 'zod';
+import { base, scoped, superadmin } from '../base.js';
+
+const uuid = z.string().uuid();
+
+const fieldSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().min(1).max(64),
+  label: z.string().optional(),
+  type: z.string(),
+  settings: z.record(z.string(), z.unknown()).default({}),
+  required: z.boolean().default(false),
+  localized: z.boolean().default(false),
+  unique: z.boolean().default(false),
+  readRoles: z.array(z.string()).optional(),
+  writeRoles: z.array(z.string()).optional(),
+  admin: z
+    .object({
+      zone: z.enum(['main', 'sidebar']).default('main'),
+      width: z.number().int().min(25).max(100).default(100),
+      position: z.number().int().default(0),
+      help: z.string().optional(),
+      placeholder: z.string().optional(),
+    })
+    .optional(),
+});
+
+const contentTypeSchema = z.object({
+  name: z.string().min(1).max(64),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  kind: z.enum(['content', 'block']).default('content'),
+  spaceId: uuid.nullable().default(null),
+  hasSlug: z.boolean().optional(),
+  isPublishable: z.boolean().optional(),
+  isVisibleInTree: z.boolean().optional(),
+  canBeVisibleInMenu: z.boolean().optional(),
+  fields: z.array(fieldSchema).default([]),
+});
+
+export const contentTypeRouter = {
+  list: scoped('contentType:read')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.contentTypes.list(input.spaceId)),
+
+  get: scoped('contentType:read')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => context.contentTypes.get(input.id)),
+
+  create: scoped('contentType:write')
+    .input(contentTypeSchema.extend({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.contentTypes.create(input)),
+
+  update: scoped('contentType:write')
+    .input(contentTypeSchema.extend({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => context.contentTypes.update(input.id, input)),
+
+  delete: scoped('contentType:delete')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      await context.contentTypes.delete(input.id);
+      return { ok: true };
+    }),
+
+  /**
+   * The field-type catalogue the admin's "add field" menu is built from. Derived from
+   * the registry, so a plugin's field type appears in the menu with no admin change.
+   */
+  fieldTypes: base.handler(async ({ context }) =>
+    context.manablox.fieldTypes.all.map((type) => ({
+      name: type.name,
+      label: type.label,
+      icon: type.icon ?? null,
+      description: type.description ?? null,
+      nested: type.nested ?? false,
+      filters: type.filters,
+      admin: type.admin,
+    })),
+  ),
+
+  /** JSON Schema for one field type's settings, so the admin renders its form generically. */
+  fieldTypeSettingsSchema: base
+    .input(z.object({ name: z.string() }))
+    .handler(async ({ input, context }) => {
+      const type = context.manablox.fieldTypes.get(input.name);
+      const schema = type.settingsSchema as unknown as { toJSONSchema?: () => unknown };
+      return {
+        name: type.name,
+        jsonSchema: typeof schema.toJSONSchema === 'function' ? schema.toJSONSchema() : null,
+      };
+    }),
+
+  /**
+   * The space's runtime types rendered as `manablox.config.ts` source, for moving a type
+   * built in the admin into code where it can be reviewed and versioned.
+   */
+  config: scoped('contentType:read')
+    .input(z.object({ spaceId: uuid, ids: z.array(uuid).optional() }))
+    .handler(async ({ input, context }) => {
+      const wanted = input.ids?.length ? new Set(input.ids) : null;
+      const types = context.manablox.contentTypes
+        .forSpace(input.spaceId)
+        // Code-defined types already live in a config file; re-emitting them would invite
+        // a second, diverging definition of the same type.
+        .filter((type) => type.source !== 'code' && (!wanted || wanted.has(type.id)));
+
+      return { code: renderContentTypeConfig(types), count: types.length };
+    }),
+
+  reload: superadmin.handler(async ({ context }) => {
+    await context.manablox.reload(await context.repos.contentTypes.all());
+    return { schemaVersion: context.manablox.contentTypes.schemaVersion };
+  }),
+};

package/src/routers/content.ts

@@ -0,0 +1,200 @@
+import { actorRoles } from '@manablox/auth';
+import { z } from 'zod';
+import { base, scoped } from '../base.js';
+
+const uuid = z.string().uuid();
+
+const filterSchema = z.object({
+  spaceId: uuid,
+  typeIds: z.array(uuid).optional(),
+  locale: z.string().optional(),
+  status: z.enum(['draft', 'published', 'archived']).optional(),
+  parentId: uuid.nullable().optional(),
+  under: uuid.optional(),
+  search: z.string().max(200).optional(),
+  visibleInMenu: z.boolean().optional(),
+  fields: z
+    .array(
+      z.object({
+        name: z.string(),
+        op: z.enum([
+          'eq',
+          'neq',
+          'lt',
+          'lte',
+          'gt',
+          'gte',
+          'in',
+          'notIn',
+          'contains',
+          'startsWith',
+          'endsWith',
+          'isNull',
+          'isNotNull',
+        ]),
+        value: z.unknown().optional(),
+      }),
+    )
+    .max(10)
+    .optional(),
+});
+
+const paginationSchema = z.object({
+  limit: z.number().int().min(1).max(200).default(25),
+  offset: z.number().int().min(0).default(0),
+});
+
+const sortSchema = z
+  .array(
+    z.object({
+      by: z.enum(['position', 'title', 'createdAt', 'updatedAt', 'publishedAt', 'slug']),
+      direction: z.enum(['asc', 'desc']).default('asc'),
+    }),
+  )
+  .max(3);
+
+const saveSchema = z.object({
+  spaceId: uuid,
+  typeId: uuid,
+  locale: z.string().min(2).max(10).default('en'),
+  localizationId: uuid.optional(),
+  parentId: uuid.nullable().optional(),
+  title: z.string().min(1).max(500),
+  slug: z.string().max(200).optional(),
+  fields: z.record(z.string(), z.unknown()).default({}),
+  visibleInMenu: z.boolean().optional(),
+  position: z.number().int().optional(),
+  expectedVersion: z.number().int().positive().optional(),
+});
+
+export const contentRouter = {
+  list: scoped('content:read')
+    .input(
+      z
+        .object({
+          filter: filterSchema,
+          pagination: paginationSchema.optional(),
+          sort: sortSchema.optional(),
+        })
+        .transform((v) => ({ ...v, spaceId: v.filter.spaceId })),
+    )
+    .handler(async ({ input, context }) =>
+      context.content.list(
+        input.filter,
+        input.pagination ?? { limit: 25, offset: 0 },
+        input.sort ?? [],
+        { actor: toActor(context, input.filter.spaceId) },
+      ),
+    ),
+
+  tree: scoped('content:read')
+    .input(
+      z.object({
+        spaceId: uuid,
+        locale: z.string().default('en'),
+        rootId: uuid.nullable().default(null),
+      }),
+    )
+    .handler(async ({ input, context }) =>
+      context.content.tree(input.spaceId, input.locale, input.rootId),
+    ),
+
+  get: scoped('content:read')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) =>
+      context.content.get(input.id, { actor: toActor(context, input.spaceId) }),
+    ),
+
+  /** Field values with defaults filled in — what the editor opens a new document with. */
+  blank: scoped('content:read')
+    .input(z.object({ spaceId: uuid, typeId: uuid }))
+    .handler(async ({ input, context }) => ({
+      fields: await context.content.initFields(context.manablox.contentTypes.get(input.typeId)),
+    })),
+
+  create: scoped('content:write')
+    .input(saveSchema)
+    .handler(async ({ input, context }) =>
+      context.content.create(input, toActor(context, input.spaceId)),
+    ),
+
+  update: scoped('content:write')
+    .input(saveSchema.extend({ id: uuid }))
+    .handler(async ({ input, context }) =>
+      context.content.update(input.id, input, toActor(context, input.spaceId)),
+    ),
+
+  delete: scoped('content:delete')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => ({
+      deleted: await context.content.delete(input.id, toActor(context, input.spaceId)),
+    })),
+
+  publish: scoped('content:publish')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) =>
+      context.content.publish(input.id, toActor(context, input.spaceId)),
+    ),
+
+  unpublish: scoped('content:publish')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => {
+      await context.content.unpublish(input.id, toActor(context, input.spaceId));
+      return { ok: true };
+    }),
+
+  /** Reparent or reorder a document in the tree — a drag in the admin's tree panel. */
+  move: scoped('content:write')
+    .input(
+      z.object({
+        spaceId: uuid,
+        id: uuid,
+        parentId: uuid.nullable(),
+        position: z.number().int().min(0),
+      }),
+    )
+    .handler(async ({ input, context }) =>
+      context.content.move(input.spaceId, input.id, input.parentId, input.position),
+    ),
+
+  /** Every locale a document exists in, for the editor's language switcher. */
+  translations: scoped('content:read')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => context.content.translations(input.spaceId, input.id)),
+
+  /** Starts a translation of an existing document, in the localization group it shares. */
+  createTranslation: scoped('content:write')
+    .input(z.object({ spaceId: uuid, id: uuid, locale: z.string().min(2).max(10) }))
+    .handler(async ({ input, context }) =>
+      context.content.createTranslation(
+        input.spaceId,
+        input.id,
+        input.locale,
+        toActor(context, input.spaceId),
+      ),
+    ),
+
+  versions: scoped('content:read')
+    .input(z.object({ spaceId: uuid, id: uuid }))
+    .handler(async ({ input, context }) => context.repos.content.versions(input.id)),
+
+  versionSnapshot: scoped('content:read')
+    .input(z.object({ spaceId: uuid, id: uuid, version: z.number().int().positive() }))
+    .handler(async ({ input, context }) =>
+      context.repos.content.versionSnapshot(input.id, input.version),
+    ),
+
+  restore: scoped('content:write')
+    .input(z.object({ spaceId: uuid, id: uuid, version: z.number().int().positive() }))
+    .handler(async ({ input, context }) =>
+      context.content.restore(input.id, input.version, toActor(context, input.spaceId)),
+    ),
+};
+
+export { base };
+
+function toActor(context: { principal: unknown }, spaceId: string) {
+  const principal = context.principal as { userId: string } | null;
+  if (!principal) return null;
+  return { userId: principal.userId, roles: actorRoles(principal as never, spaceId) };
+}

package/src/routers/space.ts

@@ -0,0 +1,267 @@
+import { ManabloxError } from '@manablox/core';
+import { SpaceTransferService } from '@manablox/services';
+import { z } from 'zod';
+import { authed, base, scoped, superadmin } from '../base.js';
+import type { RpcContext } from '../context.js';
+
+const uuid = z.string().uuid();
+
+const spaceSchema = z.object({
+  name: z.string().min(1).max(200),
+  machineName: z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]*$/)
+    .max(64),
+  description: z.string().nullable().optional(),
+  url: z.string().url(),
+  defaultLocale: z.string().min(2).max(10).default('en'),
+  locales: z.array(z.string().min(2).max(10)).min(1).default(['en']),
+  settings: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * `spaces_machine_name_key` is enforced in the database, so a taken machine name arrives
+ * as a Postgres unique violation and would surface as an opaque 500. Drizzle wraps the
+ * driver error, so the SQLSTATE is on `cause`.
+ */
+function rethrowMachineNameConflict(error: unknown, machineName: string | undefined): never {
+  const cause = (error as { cause?: { code?: string; message?: string } }).cause;
+  const code = (error as { code?: string }).code ?? cause?.code;
+  const detail = `${cause?.message ?? ''} ${(error as { message?: string }).message ?? ''}`;
+
+  if (code === '23505' && detail.includes('machine_name')) {
+    throw ManabloxError.validation(
+      [
+        {
+          key: 'space.machineName.taken',
+          path: ['machineName'],
+          params: { machineName: machineName ?? '' },
+        },
+      ],
+      'space.validation.failed',
+    );
+  }
+  throw error;
+}
+
+/**
+ * A space with no owner can never be granted one again: `user:write` is an owner's and an
+ * admin's permission, and an admin cannot promote themselves past their own role.
+ */
+async function assertNotLastOwner(
+  context: Pick<RpcContext, 'repos'>,
+  spaceId: string,
+  userId: string,
+): Promise<void> {
+  if ((await context.repos.users.roleIn(userId, spaceId)) !== 'owner') return;
+  const owners = (await context.repos.users.membersOf(spaceId)).filter(
+    (member) => member.role === 'owner',
+  );
+  if (owners.length <= 1) throw ManabloxError.badRequest('space.member.lastOwner', { spaceId });
+}
+
+/**
+ * The default locale names the column content falls back to, so a default outside the
+ * space's own locale set would leave every document with no readable fallback.
+ */
+function assertDefaultIsALocale(defaultLocale: string, locales: readonly string[]): void {
+  if (locales.includes(defaultLocale)) return;
+  throw ManabloxError.validation(
+    [
+      {
+        key: 'space.defaultLocale.notInLocales',
+        path: ['defaultLocale'],
+        params: { defaultLocale, locales: locales.join(', ') },
+      },
+    ],
+    'space.validation.failed',
+  );
+}
+
+export const spaceRouter = {
+  /** Only the spaces the caller is a member of — a superadmin sees all. */
+  list: authed.handler(async ({ context }) => {
+    const all = await context.repos.spaces.all();
+    const allowed = context.principal?.allowedSpaceIds;
+    const visible = allowed ? all.filter((space) => allowed.includes(space.id)) : all;
+    if (context.principal?.role === 'superadmin') return visible;
+    return visible.filter((space) => Boolean(context.principal?.spaces[space.id]));
+  }),
+
+  get: scoped('space:read')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.repos.spaces.findById(input.spaceId)),
+
+  create: superadmin.input(spaceSchema).handler(async ({ input, context }) => {
+    assertDefaultIsALocale(input.defaultLocale, input.locales);
+    const space = await context.repos.spaces
+      .create(input)
+      .catch((error) => rethrowMachineNameConflict(error, input.machineName));
+    // Whoever creates a space owns it, or they would immediately lock themselves out.
+    if (context.principal) {
+      await context.repos.users.grant(context.principal.userId, space.id, 'owner');
+    }
+    return space;
+  }),
+
+  update: scoped('space:write')
+    .input(spaceSchema.partial().extend({ spaceId: uuid }))
+    .handler(async ({ input, context }) => {
+      const { spaceId, ...data } = input;
+
+      // A partial update may move either half of the pair, so the check runs against the
+      // stored values for whichever half this call leaves alone.
+      if (data.defaultLocale || data.locales) {
+        const current = await context.repos.spaces.findById(spaceId);
+        if (!current) throw ManabloxError.notFound('space.notFound', { spaceId });
+        assertDefaultIsALocale(
+          data.defaultLocale ?? current.defaultLocale,
+          data.locales ?? current.locales,
+        );
+      }
+
+      return context.repos.spaces
+        .update(spaceId, data)
+        .catch((error) => rethrowMachineNameConflict(error, data.machineName));
+    }),
+
+  delete: scoped('space:delete')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => {
+      await context.repos.spaces.delete(input.spaceId);
+      return { ok: true };
+    }),
+
+  /**
+   * Nominates one document as the space's root. Stored in `settings` rather than on the
+   * content row so it survives the document being renamed, re-slugged or moved, and so a
+   * space has exactly one by construction.
+   *
+   * The delivery APIs resolve the empty path through it, matching the requested locale by
+   * localization group — pass `null` to clear.
+   */
+  setHome: scoped('space:write')
+    .input(z.object({ spaceId: uuid, contentId: uuid.nullable() }))
+    .handler(async ({ input, context }) => {
+      const space = await context.repos.spaces.findById(input.spaceId);
+      if (!space) throw ManabloxError.notFound('space.notFound', { spaceId: input.spaceId });
+
+      if (input.contentId) {
+        const row = await context.repos.content.findById(input.contentId);
+        if (!row || row.spaceId !== input.spaceId) {
+          throw ManabloxError.badRequest('content.notInSpace', { id: input.contentId });
+        }
+      }
+
+      const settings = { ...space.settings };
+      if (input.contentId) settings.homeContentId = input.contentId;
+      else delete settings.homeContentId;
+
+      return context.repos.spaces.update(input.spaceId, { settings });
+    }),
+
+  /**
+   * The whole space as one JSON document: its settings, its runtime content types, every
+   * document and the asset metadata. `space:write` rather than `space:read` because an
+   * export is every field of every document in one file, regardless of who may read what.
+   */
+  export: scoped('space:write')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) =>
+      new SpaceTransferService(context.manablox, context.repos).export(input.spaceId),
+    ),
+
+  /**
+   * Restores such a document, ids and all, into an instance that does not hold the space
+   * yet. Superadmin, because it creates a space — the same bar as `create`.
+   */
+  import: superadmin
+    .input(z.object({ payload: z.unknown() }))
+    .handler(async ({ input, context }) => {
+      const result = await new SpaceTransferService(context.manablox, context.repos).import(
+        input.payload,
+        context.principal.userId,
+      );
+      // Whoever imports a space owns it, exactly as if they had created it by hand.
+      await context.repos.users.grant(context.principal.userId, result.spaceId, 'owner');
+      return result;
+    }),
+
+  members: scoped('user:read')
+    .input(z.object({ spaceId: uuid }))
+    .handler(async ({ input, context }) => context.repos.users.membersOf(input.spaceId)),
+
+  grant: scoped('user:write')
+    .input(
+      z.object({
+        spaceId: uuid,
+        userId: uuid,
+        role: z.enum(['owner', 'admin', 'editor', 'author', 'viewer']),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      // Demoting the last owner locks the space out of ownership just as removing them does.
+      if (input.role !== 'owner') {
+        await assertNotLastOwner(context, input.spaceId, input.userId);
+      }
+      await context.repos.users.grant(input.userId, input.spaceId, input.role);
+      return { ok: true };
+    }),
+
+  /**
+   * Users who are not yet members, for the add-member picker. Scoped to `user:write` and
+   * returning only a name, an email and an id: a space admin needs to pick a colleague
+   * without being handed the instance's user directory, which is superadmin-only.
+   */
+  candidates: scoped('user:write')
+    .input(z.object({ spaceId: uuid, search: z.string().max(200).optional() }))
+    .handler(async ({ input, context }) => {
+      const [members, all] = await Promise.all([
+        context.repos.users.membersOf(input.spaceId),
+        context.repos.users.list({ limit: 100, offset: 0 }, input.search),
+      ]);
+      const taken = new Set(members.map((member) => member.userId));
+      return all.items
+        .filter((user) => !taken.has(user.id))
+        .map((user) => ({ id: user.id, name: user.name, email: user.email }));
+    }),
+
+  /** Grants the same role to several users at once, as the picker hands them over. */
+  addMembers: scoped('user:write')
+    .input(
+      z.object({
+        spaceId: uuid,
+        userIds: z.array(uuid).min(1).max(100),
+        role: z.enum(['owner', 'admin', 'editor', 'author', 'viewer']).default('editor'),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      // Already-members are skipped rather than rejected: the picker offers only
+      // non-members, so an overlap means the list went stale, not that the caller erred.
+      const members = await context.repos.users.membersOf(input.spaceId);
+      const taken = new Set(members.map((member) => member.userId));
+      const added = input.userIds.filter((userId) => !taken.has(userId));
+
+      for (const userId of added) {
+        await context.repos.users.grant(userId, input.spaceId, input.role);
+      }
+      return { ok: true, added: added.length };
+    }),
+
+  revoke: scoped('user:write')
+    .input(z.object({ spaceId: uuid, userId: uuid }))
+    .handler(async ({ input, context }) => {
+      await assertNotLastOwner(context, input.spaceId, input.userId);
+      await context.repos.users.revoke(input.userId, input.spaceId);
+      return { ok: true };
+    }),
+
+  /** Locales available for a space, for the editor's language switcher. */
+  locales: base.input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => {
+    const space = await context.repos.spaces.findById(input.spaceId);
+    return {
+      available: space?.locales ?? context.manablox.config.locales.available,
+      default: space?.defaultLocale ?? context.manablox.config.locales.default,
+    };
+  }),
+};

package/src/routers/user.ts

@@ -0,0 +1,68 @@
+import { assertCan } from '@manablox/auth';
+import { z } from 'zod';
+import { authed, superadmin } from '../base.js';
+
+const uuid = z.string().uuid();
+
+export const userRouter = {
+  me: authed.handler(async ({ context }) => {
+    const user = await context.repos.users.findById(context.principal.userId);
+    return user
+      ? {
+          id: user.id,
+          email: user.email,
+          name: user.name,
+          image: user.image,
+          role: user.role,
+          spaces: context.principal.spaces,
+        }
+      : null;
+  }),
+
+  list: superadmin
+    .input(
+      z.object({
+        search: z.string().max(200).optional(),
+        limit: z.number().int().min(1).max(100).default(25),
+        offset: z.number().int().min(0).default(0),
+      }),
+    )
+    .handler(async ({ input, context }) =>
+      context.repos.users.list({ limit: input.limit, offset: input.offset }, input.search),
+    ),
+
+  setRole: superadmin
+    .input(z.object({ userId: uuid, role: z.enum(['superadmin', 'editor']) }))
+    .handler(async ({ input, context }) => context.repos.users.setRole(input.userId, input.role)),
+
+  apiKeys: authed.handler(async ({ context }) => context.apiKeys.list(context.principal.userId)),
+
+  issueApiKey: authed
+    .input(
+      z.object({
+        name: z.string().min(1).max(100),
+        expiresAt: z.coerce.date().optional(),
+        /** Empty or omitted issues an unrestricted key. */
+        spaceIds: z.array(uuid).optional(),
+      }),
+    )
+    .handler(async ({ input, context }) => {
+      // A key may only be confined to spaces the issuer can already reach, so a
+      // restriction cannot be used to name a space the caller has no business knowing.
+      for (const spaceId of input.spaceIds ?? []) {
+        assertCan(context.principal, spaceId, 'space:read');
+      }
+      return context.apiKeys.issue(context.principal.userId, input.name, {
+        expiresAt: input.expiresAt,
+        spaceIds: input.spaceIds,
+      });
+    }),
+
+  revokeApiKey: authed.input(z.object({ id: uuid })).handler(async ({ input, context }) => {
+    // Scope the revoke to the caller's own keys so an id from elsewhere is inert.
+    const own = await context.apiKeys.list(context.principal.userId);
+    if (!own.some((key) => key.id === input.id)) return { ok: false };
+    await context.apiKeys.revoke(input.id);
+    return { ok: true };
+  }),
+};

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "@manablox/config-typescript/library.json", "include": ["src", "test"] }