@manablox/auth 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,20 @@
+# `@manablox/auth`
+
+Sessions, API keys and permissions. better-auth owns sign-in and sessions; this package wraps it, resolves a `Principal` from a request, checks a permission against the role table, and issues and verifies API keys, including ones restricted to a set of spaces.
+
+## Exports
+
+- `createAuth`, `resolvePrincipal`
+- `can`, `assertCan`, `actorRoles`, `Permission`, `Principal`
+- `ApiKeyService`
+- `promoteFirstUser`, `attachBootstrapOwner` — the first account is the superadmin
+
+## Depends on
+
+@manablox/db, better-auth
+
+## Test
+
+```sh
+pnpm --filter @manablox/auth test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manablox/auth",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,8 +11,8 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@manablox/core": "0.1.0",
-    "@manablox/db": "0.1.0",
+    "@manablox/core": "0.2.0",
+    "@manablox/db": "0.2.0",
     "better-auth": "^1.7.2",
     "drizzle-orm": "^0.45.2",
     "@node-rs/argon2": "^2.2.0"

package/src/api-key.ts

@@ -16,10 +16,23 @@ export interface IssueApiKeyOptions {
   expiresAt?: Date | undefined;
   /** Spaces the key may act in. `null`/omitted issues an unrestricted key. */
   spaceIds?: string[] | null | undefined;
+  /** Grants the key may use. `null`/omitted leaves the owner's role as the limit. */
+  permissions?: string[] | null | undefined;
 }
 
 const PREFIX = 'mbx';
 
+/**
+ * Takes a presented key apart. The secret is base64url and may itself contain `_`, so
+ * the key is not split on it: the prefix is a fixed twelve hex characters and the
+ * secret is whatever follows.
+ */
+export function parseApiKey(presented: string): { prefix: string; secret: string } | null {
+  const match = /^([a-z]+)_([0-9a-f]{12})_([A-Za-z0-9_-]+)$/.exec(presented);
+  if (!match || match[1] !== PREFIX) return null;
+  return { prefix: match[2] as string, secret: match[3] as string };
+}
+
 /**
  * Long-lived credentials for headless consumers.
  *
@@ -52,6 +65,7 @@ export class ApiKeyService {
         key: digest(secret),
         expiresAt: options.expiresAt ?? null,
         spaceIds: options.spaceIds?.length ? options.spaceIds : null,
+        permissions: options.permissions ?? null,
       })
       .returning();
 
@@ -77,6 +91,7 @@ export class ApiKeyService {
         expiresAt: schema.apikeys.expiresAt,
         lastRequest: schema.apikeys.lastRequest,
         spaceIds: schema.apikeys.spaceIds,
+        permissions: schema.apikeys.permissions,
         createdAt: schema.apikeys.createdAt,
       })
       .from(schema.apikeys)
@@ -84,9 +99,9 @@ export class ApiKeyService {
   }
 
   async resolve(presented: string): Promise<Principal | null> {
-    const parts = presented.split('_');
-    if (parts.length !== 3 || parts[0] !== PREFIX) return null;
-    const [, prefix, secret] = parts as [string, string, string];
+    const parsed = parseApiKey(presented);
+    if (!parsed) return null;
+    const { prefix, secret } = parsed;
 
     const rows = await this.db
       .select()
@@ -112,12 +127,16 @@ export class ApiKeyService {
     const user = await this.repos.users.findById(row.userId);
     if (!user || user.banned) return null;
 
-    const memberships = await this.repos.users.memberships(user.id);
+    const resolved = await this.repos.users.principal(user.id);
+    if (!resolved) return null;
     const allowed = row.spaceIds?.length ? new Set(row.spaceIds) : null;
     const spaces: Record<string, SpaceRole> = {};
-    for (const membership of memberships) {
-      if (allowed && !allowed.has(membership.spaceId)) continue;
-      spaces[membership.spaceId] = membership.role;
+    const permissions: Record<string, string[]> = {};
+    for (const [spaceId, role] of Object.entries(resolved.spaces)) {
+      if (allowed && !allowed.has(spaceId)) continue;
+      spaces[spaceId] = role;
+      const grants = resolved.permissions[spaceId];
+      if (grants) permissions[spaceId] = grants;
     }
 
     return {
@@ -125,8 +144,10 @@ export class ApiKeyService {
       email: user.email,
       role: user.role,
       spaces,
+      permissions,
       viaApiKey: true,
       allowedSpaceIds: allowed ? [...allowed] : null,
+      allowedGrants: row.permissions,
     };
   }
 

package/src/index.ts

@@ -3,12 +3,16 @@ import type { Database, Repositories } from '@manablox/db';
 import { schema } from '@manablox/db';
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { APIError } from 'better-auth/api';
 import { bearer } from 'better-auth/plugins';
 import type { ApiKeyService } from './api-key.js';
+import { hashPassword, MIN_PASSWORD_LENGTH, verifyPassword } from './password.js';
 import type { Principal } from './rbac.js';
 
 export * from './api-key.js';
+export * from './password.js';
 export * from './rbac.js';
+export * from './user.service.js';
 
 export type ManabloxAuth = ReturnType<typeof createAuth>;
 
@@ -17,6 +21,12 @@ export type ManabloxAuth = ReturnType<typeof createAuth>;
 export interface AuthCallbacks {
   /** Runs after a user row is created, inside better-auth's own transaction path. */
   onUserCreated?: (userId: string) => Promise<void>;
+  /**
+   * Whether the public sign-up endpoint may create an account right now. Absent means
+   * always. The host closes it once the first account exists, so every later account is
+   * created by an administrator rather than by whoever finds the login page.
+   */
+  allowSignUp?: () => Promise<boolean>;
 }
 
 export function createAuth(config: AuthConfig, db: Database, callbacks: AuthCallbacks = {}) {
@@ -38,18 +48,10 @@ export function createAuth(config: AuthConfig, db: Database, callbacks: AuthCall
 
     emailAndPassword: {
       enabled: config.emailAndPassword ?? true,
-      minPasswordLength: 12,
-      // Argon2id: memory-hard, and the current OWASP recommendation over bcrypt, which
-      // also silently truncates passwords at 72 bytes.
+      minPasswordLength: MIN_PASSWORD_LENGTH,
       password: {
-        hash: async (password) => {
-          const { hash } = await import('@node-rs/argon2');
-          return hash(password, { memoryCost: 19456, timeCost: 2, parallelism: 1 });
-        },
-        verify: async ({ hash: stored, password }) => {
-          const { verify } = await import('@node-rs/argon2');
-          return verify(stored, password);
-        },
+        hash: hashPassword,
+        verify: ({ hash: stored, password }) => verifyPassword(stored, password),
       },
     },
 
@@ -67,6 +69,12 @@ export function createAuth(config: AuthConfig, db: Database, callbacks: AuthCall
     databaseHooks: {
       user: {
         create: {
+          // Sign-up is the only path that creates a user through better-auth; accounts
+          // an administrator creates are written by `UserService` and never pass here.
+          before: async (user) => {
+            if (!callbacks.allowSignUp || (await callbacks.allowSignUp())) return { data: user };
+            throw new APIError('FORBIDDEN', { message: 'auth.signUp.closed' });
+          },
           after: async (user) => {
             await callbacks.onUserCreated?.(user.id);
           },
@@ -110,6 +118,7 @@ export async function resolvePrincipal(
     email: session.user.email,
     role: principal.role,
     spaces: principal.spaces,
+    permissions: principal.permissions,
   };
 }
 

package/src/password.ts

@@ -0,0 +1,17 @@
+/**
+ * Argon2id, the current OWASP recommendation over bcrypt — which also silently truncates
+ * passwords at 72 bytes. One definition serves better-auth's own sign-in path and the
+ * accounts an administrator creates, so both write the same hash format.
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const { hash } = await import('@node-rs/argon2');
+  return hash(password, { memoryCost: 19456, timeCost: 2, parallelism: 1 });
+}
+
+export async function verifyPassword(stored: string, password: string): Promise<boolean> {
+  const { verify } = await import('@node-rs/argon2');
+  return verify(stored, password);
+}
+
+/** Matches better-auth's `minPasswordLength`, so a password set here signs in there. */
+export const MIN_PASSWORD_LENGTH = 12;

package/src/rbac.ts

@@ -1,99 +1,48 @@
-import { ManabloxError } from '@manablox/core';
+import {
+  ALL_PERMISSIONS,
+  type ContentPermission,
+  grantsCover,
+  intersectGrants,
+  ManabloxError,
+  type Permission,
+  permissionsFor,
+  type SpaceRole,
+  typesCoveredBy,
+} from '@manablox/core';
 
-export type SpaceRole = 'owner' | 'admin' | 'editor' | 'author' | 'viewer';
-
-export type Permission =
-  | 'space:read'
-  | 'space:write'
-  | 'space:delete'
-  | 'contentType:read'
-  | 'contentType:write'
-  | 'contentType:delete'
-  | 'content:read'
-  | 'content:write'
-  | 'content:delete'
-  | 'content:publish'
-  | 'asset:read'
-  | 'asset:write'
-  | 'asset:delete'
-  | 'user:read'
-  | 'user:write'
-  | 'webhook:read'
-  | 'webhook:write';
-
-/** Role → permission mapping. */
-const ROLE_PERMISSIONS: Record<SpaceRole, Permission[]> = {
-  owner: [
-    'space:read',
-    'space:write',
-    'space:delete',
-    'contentType:read',
-    'contentType:write',
-    'contentType:delete',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'user:write',
-    'webhook:read',
-    'webhook:write',
-  ],
-  admin: [
-    'space:read',
-    'space:write',
-    'contentType:read',
-    'contentType:write',
-    'contentType:delete',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'user:write',
-    'webhook:read',
-    'webhook:write',
-  ],
-  editor: [
-    'space:read',
-    'contentType:read',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'webhook:read',
-  ],
-  // An author may write and delete, but never publish — the reason the role exists.
-  author: [
-    'space:read',
-    'contentType:read',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'asset:read',
-    'asset:write',
-    'user:read',
-  ],
-  viewer: ['space:read', 'contentType:read', 'content:read', 'asset:read', 'user:read'],
-};
+export {
+  ALL_PERMISSIONS,
+  BUILT_IN_ROLES,
+  type BuiltInRole,
+  CONTENT_ACTIONS,
+  type ContentAction,
+  type ContentPermission,
+  type Grant,
+  grantsCover,
+  intersectGrants,
+  isBuiltInRole,
+  normaliseGrants,
+  PERMISSION_GROUPS,
+  type Permission,
+  type PermissionGroup,
+  parseGrant,
+  permissionsFor,
+  type SpaceRole,
+  typesCoveredBy,
+} from '@manablox/core';
 
 export interface Principal {
   userId: string;
   email: string;
   /** Instance-wide role; `superadmin` short-circuits every space check. */
   role: string;
-  /** Space id → role in that space. */
+  /** Space id → the name of the role held there. */
   spaces: Record<string, SpaceRole>;
+  /**
+   * Space id → the grants that role carries, resolved when the principal is. Absent for
+   * a space whose role is built in: those are answered from the table above.
+   */
+  permissions?: Record<string, readonly string[]>;
   /** True when the request authenticated with an API key rather than a session. */
   viaApiKey?: boolean;
   /**
@@ -102,16 +51,36 @@ export interface Principal {
    * owner's own access and, unlike a role, it also binds a superadmin.
    */
   allowedSpaceIds?: string[] | null;
+  /**
+   * Grants this principal is confined to, or `null`/absent for no confinement. Set by an
+   * API key issued with a permission restriction: like `allowedSpaceIds` it only ever
+   * narrows the owner's own access, and it binds a superadmin too.
+   */
+  allowedGrants?: readonly string[] | null;
+}
+
+/** The grants a principal's role gives in a space, whatever kind of role it is. */
+export function grantsIn(principal: Principal, spaceId: string): readonly string[] {
+  const role = principal.spaces[spaceId];
+  if (!role) return [];
+  return principal.permissions?.[spaceId] ?? permissionsFor(role);
 }
 
-export function permissionsFor(role: SpaceRole): readonly Permission[] {
-  return ROLE_PERMISSIONS[role] ?? [];
+/**
+ * What a principal can actually do in a space: the role's grants (everything, for a
+ * superadmin) narrowed by an API key's restriction, if the request came through one.
+ */
+export function effectiveGrants(principal: Principal, spaceId: string): readonly string[] {
+  if (principal.allowedSpaceIds && !principal.allowedSpaceIds.includes(spaceId)) return [];
+  const held = principal.role === 'superadmin' ? ALL_PERMISSIONS : grantsIn(principal, spaceId);
+  return principal.allowedGrants ? intersectGrants(held, principal.allowedGrants) : held;
 }
 
 export function can(
   principal: Principal | null,
   spaceId: string | null,
   permission: Permission,
+  typeId?: string | null,
 ): boolean {
   if (!principal) return false;
   // Checked ahead of the superadmin short-circuit: a restricted key must not reach
@@ -119,22 +88,41 @@ export function can(
   if (principal.allowedSpaceIds && (!spaceId || !principal.allowedSpaceIds.includes(spaceId))) {
     return false;
   }
+  if (principal.allowedGrants && !grantsCover(principal.allowedGrants, permission, typeId)) {
+    return false;
+  }
   if (principal.role === 'superadmin') return true;
   if (!spaceId) return false;
-
-  const role = principal.spaces[spaceId];
-  if (!role) return false;
-  return ROLE_PERMISSIONS[role].includes(permission);
+  return grantsCover(grantsIn(principal, spaceId), permission, typeId);
 }
 
 export function assertCan(
   principal: Principal | null,
   spaceId: string | null,
   permission: Permission,
+  typeId?: string | null,
 ): void {
-  if (can(principal, spaceId, permission)) return;
+  if (can(principal, spaceId, permission, typeId)) return;
   if (!principal) throw ManabloxError.unauthorized();
-  throw ManabloxError.forbidden('auth.forbidden', { permission, spaceId });
+  throw ManabloxError.forbidden('auth.forbidden', {
+    permission,
+    spaceId,
+    ...(typeId ? { typeId } : {}),
+  });
+}
+
+/**
+ * The content types a principal may perform an action on in a space, or `null` for
+ * every type — what a listing narrows its filter to.
+ */
+export function allowedTypeIds(
+  principal: Principal | null,
+  spaceId: string,
+  permission: ContentPermission,
+): string[] | null {
+  if (!principal) return [];
+  if (principal.role === 'superadmin' && !principal.allowedGrants) return null;
+  return typesCoveredBy(effectiveGrants(principal, spaceId), permission);
 }
 
 /** Roles used by field-level `readRoles`/`writeRoles` checks. */

package/src/user.service.ts

@@ -0,0 +1,192 @@
+import { ManabloxError } from '@manablox/core';
+import {
+  type MembershipRow,
+  type Repositories,
+  rethrowUniqueViolation,
+  type SpaceRow,
+  type UserRow,
+  type UserUpdateData,
+} from '@manablox/db';
+import { hashPassword } from './password.js';
+
+export type InstanceRole = 'superadmin' | 'editor';
+
+export interface CreateUserInput {
+  name: string;
+  email: string;
+  password: string;
+  role: InstanceRole;
+}
+
+export interface UpdateUserInput {
+  name?: string | undefined;
+  email?: string | undefined;
+}
+
+/** A user row without anything a directory listing should not carry. */
+export interface UserSummary {
+  id: string;
+  name: string;
+  email: string;
+  image: string | null;
+  role: string;
+  banned: boolean;
+  banReason: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UserDetail extends UserSummary {
+  memberships: Array<{ spaceId: string; role: MembershipRow['role']; space: SpaceRow }>;
+}
+
+/**
+ * `users_email_key` is enforced in the database, so a taken address arrives as a
+ * Postgres unique violation and would surface as an opaque 500.
+ */
+const emailConflict = (email: string | undefined) => (error: unknown) =>
+  rethrowUniqueViolation(error, {
+    constraint: 'email',
+    key: 'user.email.taken',
+    path: ['email'],
+    params: { email: email ?? '' },
+    errorKey: 'user.validation.failed',
+  });
+
+/**
+ * Instance-wide user administration: the accounts, their instance role, and whether they
+ * may sign in at all. Space membership stays with `SpaceService`, because it is a
+ * property of the space.
+ *
+ * Every rule here exists to keep the instance reachable: an administrator cannot lock
+ * themself out, and the instance always keeps at least one superadmin.
+ */
+export class UserService {
+  constructor(private readonly repos: Repositories) {}
+
+  async get(userId: string): Promise<UserDetail> {
+    const user = await this.repos.users.findById(userId);
+    if (!user) throw ManabloxError.notFound('user.notFound', { id: userId });
+    const memberships = await this.repos.users.membershipsWithSpaces(userId);
+    return {
+      ...summary(user),
+      memberships: memberships.map((row) => ({
+        spaceId: row.spaceId,
+        role: row.role,
+        space: row.space,
+      })),
+    };
+  }
+
+  async list(pagination: { limit: number; offset: number }, search?: string) {
+    const page = await this.repos.users.list(pagination, search);
+    return { ...page, items: page.items.map(summary) };
+  }
+
+  async create(input: CreateUserInput): Promise<UserSummary> {
+    const email = normaliseEmail(input.email);
+    const user = await this.repos.users
+      .create({
+        name: input.name.trim(),
+        email,
+        role: input.role,
+        passwordHash: await hashPassword(input.password),
+      })
+      .catch(emailConflict(email));
+    return summary(user);
+  }
+
+  async update(userId: string, input: UpdateUserInput): Promise<UserSummary> {
+    const data: UserUpdateData = {};
+    if (input.name !== undefined) data.name = input.name.trim();
+    if (input.email !== undefined) data.email = normaliseEmail(input.email);
+    const user = await this.repos.users.update(userId, data).catch(emailConflict(data.email));
+    return summary(user);
+  }
+
+  /** Changing the instance role; the last superadmin cannot step down. */
+  async setRole(userId: string, role: InstanceRole): Promise<UserSummary> {
+    if (role !== 'superadmin') await this.assertNotLastSuperadmin(userId);
+    return summary(await this.repos.users.setRole(userId, role));
+  }
+
+  /**
+   * A new password, and every session gone with the old one: whoever held the account
+   * before the reset does not keep it afterwards.
+   */
+  async setPassword(userId: string, password: string): Promise<void> {
+    await this.require(userId);
+    await this.repos.users.setPasswordHash(userId, await hashPassword(password));
+    await this.repos.users.revokeSessions(userId);
+  }
+
+  /** A banned user is signed out everywhere and refused on the next request. */
+  async ban(actorId: string, userId: string, reason: string | null): Promise<UserSummary> {
+    this.assertNotSelf(actorId, userId);
+    await this.assertNotLastSuperadmin(userId);
+    const user = await this.repos.users.setBanned(userId, true, reason);
+    await this.repos.users.revokeSessions(userId);
+    return summary(user);
+  }
+
+  async unban(userId: string): Promise<UserSummary> {
+    return summary(await this.repos.users.setBanned(userId, false, null));
+  }
+
+  async delete(actorId: string, userId: string): Promise<void> {
+    this.assertNotSelf(actorId, userId);
+    await this.require(userId);
+    await this.assertNotLastSuperadmin(userId);
+    await this.repos.users.delete(userId);
+  }
+
+  /** Signs the user out of every device without touching the account. */
+  async revokeSessions(userId: string): Promise<void> {
+    await this.require(userId);
+    await this.repos.users.revokeSessions(userId);
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private async require(userId: string): Promise<UserRow> {
+    const user = await this.repos.users.findById(userId);
+    if (!user) throw ManabloxError.notFound('user.notFound', { id: userId });
+    return user;
+  }
+
+  private assertNotSelf(actorId: string, userId: string): void {
+    if (actorId === userId) throw ManabloxError.badRequest('user.self.protected', { id: userId });
+  }
+
+  /**
+   * Whatever happens to `userId`, one superadmin must remain — otherwise the instance
+   * has no one left who can create a space or manage users, and no way back.
+   */
+  private async assertNotLastSuperadmin(userId: string): Promise<void> {
+    const user = await this.require(userId);
+    if (user.role !== 'superadmin') return;
+    const count = await this.repos.users.countByRole('superadmin');
+    if (count <= 1) throw ManabloxError.badRequest('user.lastSuperadmin', { id: userId });
+  }
+}
+
+function summary(user: UserRow): UserSummary {
+  return {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    image: user.image,
+    role: user.role,
+    banned: user.banned,
+    banReason: user.banReason,
+    createdAt: user.createdAt,
+    updatedAt: user.updatedAt,
+  };
+}
+
+/** Lower-cased and trimmed, as better-auth stores it, so two spellings cannot coexist. */
+function normaliseEmail(email: string): string {
+  return email.trim().toLowerCase();
+}

package/test/api-key.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { parseApiKey } from '../src/api-key.js';
+
+describe('parseApiKey', () => {
+  it('keeps a secret that itself contains the separator', () => {
+    expect(parseApiKey('mbx_0123456789ab_ab_cd-ef_gh')).toEqual({
+      prefix: '0123456789ab',
+      secret: 'ab_cd-ef_gh',
+    });
+  });
+
+  it('refuses another prefix, a malformed lookup part, or an empty secret', () => {
+    expect(parseApiKey('abc_0123456789ab_secret')).toBeNull();
+    expect(parseApiKey('mbx_0123_secret')).toBeNull();
+    expect(parseApiKey('mbx_0123456789ab_')).toBeNull();
+    expect(parseApiKey('not a key')).toBeNull();
+  });
+});

package/test/rbac.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from 'vitest';
-import { actorRoles, assertCan, can, type Principal, permissionsFor } from '../src/rbac.js';
+import {
+  actorRoles,
+  allowedTypeIds,
+  assertCan,
+  can,
+  type Principal,
+  permissionsFor,
+} from '../src/rbac.js';
 
 const SPACE = 'space-1';
 
@@ -55,4 +62,67 @@ describe('rbac', () => {
       expect(permission.endsWith(':read')).toBe(true);
     }
   });
+
+  describe('a custom role', () => {
+    const TYPE = 'type-1';
+    const blogger = principal({
+      spaces: { [SPACE]: 'blogger' },
+      permissions: { [SPACE]: ['space:read', 'content:read', `content:write:${TYPE}`] },
+    });
+
+    it('answers from its own grants rather than the built-in table', () => {
+      expect(can(blogger, SPACE, 'content:read')).toBe(true);
+      expect(can(blogger, SPACE, 'asset:read')).toBe(false);
+    });
+
+    it('holds a content action for every type, or for the types named', () => {
+      expect(can(blogger, SPACE, 'content:read', 'type-2')).toBe(true);
+      expect(can(blogger, SPACE, 'content:write', TYPE)).toBe(true);
+      expect(can(blogger, SPACE, 'content:write', 'type-2')).toBe(false);
+      // Asked without a type: does the role write anything at all?
+      expect(can(blogger, SPACE, 'content:write')).toBe(true);
+      expect(can(blogger, SPACE, 'content:publish')).toBe(false);
+    });
+
+    it('tells a listing which types to narrow to', () => {
+      expect(allowedTypeIds(blogger, SPACE, 'content:read')).toBeNull();
+      expect(allowedTypeIds(blogger, SPACE, 'content:write')).toEqual([TYPE]);
+      expect(allowedTypeIds(blogger, SPACE, 'content:publish')).toEqual([]);
+      expect(allowedTypeIds(principal({ role: 'superadmin' }), SPACE, 'content:write')).toBeNull();
+    });
+
+    it('is nothing in a space where the name is unknown and no grants came along', () => {
+      const ghost = principal({ spaces: { [SPACE]: 'ghost' } });
+      expect(can(ghost, SPACE, 'content:read')).toBe(false);
+    });
+  });
+
+  describe('an API key confined to grants', () => {
+    const TYPE = 'type-1';
+    const key = principal({
+      spaces: { [SPACE]: 'editor' },
+      viaApiKey: true,
+      allowedGrants: ['content:read', `content:write:${TYPE}`, 'space:delete'],
+    });
+
+    it('never widens the owner: a grant the role lacks stays refused', () => {
+      expect(can(key, SPACE, 'space:delete')).toBe(false);
+    });
+
+    it('narrows the owner to the grants named', () => {
+      expect(can(key, SPACE, 'content:read')).toBe(true);
+      expect(can(key, SPACE, 'content:write', TYPE)).toBe(true);
+      expect(can(key, SPACE, 'content:write', 'type-2')).toBe(false);
+      expect(can(key, SPACE, 'asset:read')).toBe(false);
+      expect(allowedTypeIds(key, SPACE, 'content:write')).toEqual([TYPE]);
+    });
+
+    it('binds a superadmin too', () => {
+      const root = principal({ role: 'superadmin', spaces: {}, allowedGrants: ['content:read'] });
+      expect(can(root, SPACE, 'content:read')).toBe(true);
+      expect(can(root, SPACE, 'space:delete')).toBe(false);
+      expect(allowedTypeIds(root, SPACE, 'content:read')).toBeNull();
+      expect(allowedTypeIds(root, SPACE, 'content:write')).toEqual([]);
+    });
+  });
 });