@things-factory/auth-base 10.1.192 → 10.1.202

package/tests/audit-db.test.ts

@@ -0,0 +1,394 @@
+/**
+ * The audit record (ADR-0141) - what it keeps, and what it never keeps.
+ *
+ * The doors run through the real `@privilege` wrapper on an SDL schema (the shape
+ * `privilege-directive.test.ts` uses - type-graphql resolvers cannot be loaded under jest), inside a
+ * real audit scope, against the sqlite harness. Grants run through the real subscribers.
+ */
+
+import { graphql } from 'graphql'
+import { makeExecutableSchema } from '@graphql-tools/schema'
+
+import { authDataSource, closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { privilegeDirectiveTypeDefs, privilegeDirectiveResolver } = loadCompiled('service/privilege/privilege-directive')
+const { auditTargetDirectiveTypeDefs } = loadCompiled('service/audit/audit-target')
+const { runInAuditScope, recordAuditAction, flushAudit, auditHealth } = loadCompiled('service/audit/audit-recorder')
+const { AuditAction } = loadCompiled('service/audit/audit-action')
+const { AuditRequest } = loadCompiled('service/audit/audit-request')
+const { AuditQuery } = loadCompiled('service/audit/audit-query')
+const { purgeExpiredAudit } = loadCompiled('service/audit/audit-retention')
+const { User } = loadCompiled('service/user/user')
+const { Role } = loadCompiled('service/role/role')
+const { Privilege } = loadCompiled('service/privilege/privilege')
+const { signin } = loadCompiled('controllers/signin')
+
+const PASSWORD = 'Passw0rd!'
+
+let domain: any
+let other: any
+let kim: any
+let lee: any
+
+const typeDefs = `
+  type Item { id: String }
+  type Query {
+    payslip(employeeId: String): String
+      @privilege(category: "payroll", privilege: "query")
+      @auditTarget(kind: "Employee", arg: "employeeId")
+    payslips: [Item] @privilege(category: "payroll", privilege: "query")
+    broken: String @privilege(category: "payroll", privilege: "query")
+    ownersOnly: String @privilege(superUserGranted: true)
+  }
+`
+
+function buildSchema() {
+  const schema = makeExecutableSchema({
+    typeDefs: [privilegeDirectiveTypeDefs, auditTargetDirectiveTypeDefs, typeDefs],
+    resolvers: {
+      Query: {
+        payslip: (_: any, { employeeId }: any) => `pay of ${employeeId}`,
+        payslips: () => [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+        broken: () => {
+          const error: any = new Error('salary 4,200,000 for kim')
+          error.extensions = { code: 'INTERNAL_SERVER_ERROR' }
+          throw error
+        },
+        ownersOnly: () => 'ok'
+      }
+    }
+  })
+  return privilegeDirectiveResolver(schema, { modules: [], mode: 'boot' })
+}
+
+/** A koa-like request: what the recorder reads from it and nothing more. */
+function koaContext(user: any, query: string, at = domain) {
+  return {
+    method: 'POST',
+    path: '/graphql',
+    state: { domain: at, user },
+    req: { headers: { 'x-forwarded-for': '203.0.113.7, 10.0.0.1' }, socket: { remoteAddress: '10.0.0.1' } },
+    request: { header: { 'user-agent': 'Mozilla/5.0 test' }, body: { query, operationName: 'Pay' } }
+  }
+}
+
+/** One request through the schema, as the auth middleware runs it. */
+async function request(user: any, query: string, at = domain) {
+  const context = koaContext(user, query, at)
+  const result = await runInAuditScope(context, 'graphql', () => graphql({ schema: buildSchema(), source: query, contextValue: context }))
+  await flushAudit()
+  return result
+}
+
+const actions = (where: any = {}) => getRepository(AuditAction).find({ where, relations: ['actor', 'domain'] })
+
+async function seedUser(name: string, overrides: any = {}) {
+  const salt = User.generateSalt()
+  return await getRepository(User).save({
+    username: name,
+    email: `${name}@example.com`,
+    name,
+    salt,
+    password: User.encode(PASSWORD, salt),
+    status: 'activated',
+    domains: [domain],
+    ...overrides
+  })
+}
+
+function allow(granted: boolean, { superUser = false } = {}) {
+  User.hasPrivilege = jest.fn().mockResolvedValue(granted)
+  ;(process as any).domainOwnerGranted = jest.fn().mockResolvedValue(false)
+  ;(process as any).superUserGranted = jest.fn().mockResolvedValue(superUser)
+}
+
+const originalHasPrivilege = User.hasPrivilege
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+  User.hasPrivilege = originalHasPrivilege
+  domain = await getRepository(Domain).save({ name: 'office', subdomain: 'office' })
+  other = await getRepository(Domain).save({ name: 'plant', subdomain: 'plant' })
+  kim = await seedUser('kim')
+  lee = await seedUser('lee')
+})
+
+afterEach(() => {
+  delete (process as any).domainOwnerGranted
+  delete (process as any).superUserGranted
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+describe('a request is one line, its doors are rows (§3.1 · §3.2)', () => {
+  it('equal checks in one request become one row with a count, keeping each target', async () => {
+    allow(true)
+    await request(kim, '{ a: payslip(employeeId: "emp-one") b: payslip(employeeId: "emp-two") c: payslip(employeeId: "emp-one") }')
+
+    const [line] = await getRepository(AuditRequest).find({ relations: ['actor', 'domain'] })
+    expect(line).toMatchObject({ channel: 'graphql', operationType: 'query', operationName: 'Pay', fields: 'payslip', ip: '203.0.113.7', userAgent: 'Mozilla/5.0 test' })
+    /* The root fields by schema name - the arguments asked never reach the line. */
+    expect(JSON.stringify(line)).not.toMatch(/emp-one|emp-two/)
+    expect(line.actor.id).toBe(kim.id)
+    expect(line.domain.id).toBe(domain.id)
+
+    const [check] = await actions({ kind: 'door.check' })
+    expect(check).toMatchObject({ door: 'payroll:query', decision: 'granted', basis: 'role', count: 3, targetKind: 'Employee', targetRole: 'requested', requestId: line.id })
+    expect([...check.targetIds].sort()).toEqual(['emp-one', 'emp-two'])
+
+    const [result] = await actions({ kind: 'door.result' })
+    expect(result).toMatchObject({ outcome: 'ok', count: 3 })
+  })
+
+  it('a check-in outside GraphQL is a line under the site and person its event named', async () => {
+    const context = { method: 'GET', path: '/auth/checkin/office', state: {}, req: { headers: {}, socket: { remoteAddress: '10.0.0.9' } }, request: { header: {} }, _matchedRoute: '/auth/checkin/:subdomain?' }
+    await runInAuditScope(context, 'http', () => recordAuditAction({ kind: 'auth.checkin', outcome: 'ok' }, { actorId: kim.id, domainId: domain.id }))
+    await flushAudit()
+
+    const [line] = await getRepository(AuditRequest).find({ relations: ['actor', 'domain'] })
+    expect(line).toMatchObject({ channel: 'http', route: '/auth/checkin/:subdomain?', ip: '10.0.0.9' })
+    expect(line.actor.id).toBe(kim.id)
+    expect(line.domain.id).toBe(domain.id)
+  })
+
+  it('an http request that recorded nothing leaves no line', async () => {
+    await runInAuditScope({ method: 'GET', path: '/theme.css', state: {} }, 'http', async () => undefined)
+    await flushAudit()
+    expect(await getRepository(AuditRequest).count()).toBe(0)
+  })
+
+  it('a list counts what it returned', async () => {
+    allow(true)
+    await request(kim, '{ payslips { id } }')
+
+    const [result] = await actions({ kind: 'door.result' })
+    expect(result.returned).toBe(3)
+  })
+
+  it('a refusal is a check with its cause and no result', async () => {
+    allow(false)
+    await request(kim, '{ payslip(employeeId: "e9") }')
+
+    const rows = await actions()
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ kind: 'door.check', decision: 'denied', basis: 'role', targetIds: ['e9'] })
+  })
+
+  it('passing the door is not doing the work - an error is a result with a code, never the message', async () => {
+    allow(true)
+    await request(kim, '{ broken }')
+
+    const [result] = await actions({ kind: 'door.result' })
+    expect(result).toMatchObject({ outcome: 'error', code: 'INTERNAL_SERVER_ERROR' })
+    expect(JSON.stringify(await actions())).not.toMatch(/4,200,000|salary/)
+  })
+
+  it('a pass that rested on superuser says so', async () => {
+    allow(false, { superUser: true })
+    await request(kim, '{ ownersOnly }')
+
+    const [check] = await actions({ kind: 'door.check' })
+    expect(check).toMatchObject({ door: 'super', decision: 'granted', basis: 'superuser' })
+  })
+})
+
+describe('who may do what is recorded where it is saved (§3.3 · §4-1)', () => {
+  async function grant(user: any, roles: any[]) {
+    const holder = await getRepository(User).findOne({ where: { id: user.id }, relations: ['roles'] })
+    holder.roles = roles
+    return await getRepository(User).save(holder)
+  }
+
+  it('a role given and taken back', async () => {
+    const role = await getRepository(Role).save({ name: 'payroll', domain })
+
+    await runInAuditScope(koaContext(lee, ''), 'http', () => grant(kim, [role]))
+    await runInAuditScope(koaContext(lee, ''), 'http', () => grant(kim, []))
+    await flushAudit()
+
+    const granted = await actions({ kind: 'role.grant' })
+    expect(granted).toHaveLength(1)
+    expect(granted[0]).toMatchObject({ targetKind: 'User', targetIds: [kim.id], objectKind: 'Role', objectId: role.id })
+    expect(granted[0].actor.id).toBe(lee.id)
+    expect(granted[0].domain.id).toBe(domain.id)
+
+    expect(await actions({ kind: 'role.revoke' })).toHaveLength(1)
+  })
+
+  it('a privilege added to a role, and removed', async () => {
+    const privilege = await getRepository(Privilege).save({ name: 'query', category: 'payroll' })
+    const role = await getRepository(Role).save({ name: 'payroll', domain, privileges: [privilege] })
+    role.privileges = []
+    await getRepository(Role).save(role)
+
+    expect(await actions({ kind: 'role.privilege.add' })).toMatchObject([{ targetIds: [role.id], objectKind: 'Privilege', objectId: privilege.id }])
+    expect(await actions({ kind: 'role.privilege.remove' })).toHaveLength(1)
+  })
+
+  it('a status change keeps the states, nothing else', async () => {
+    kim.status = 'inactive'
+    await getRepository(User).save(kim)
+
+    const [row] = await actions({ kind: 'user.status' })
+    expect(row.detail).toEqual({ from: 'activated', to: 'inactive' })
+  })
+
+  it('a grant rolled back leaves no record', async () => {
+    const role = await getRepository(Role).save({ name: 'payroll', domain })
+
+    await expect(
+      authDataSource().transaction(async manager => {
+        const holder = await manager.getRepository(User).findOne({ where: { id: kim.id }, relations: ['roles'] })
+        holder.roles = [role]
+        await manager.getRepository(User).save(holder)
+        throw new Error('the change failed')
+      })
+    ).rejects.toThrow('the change failed')
+
+    expect(await actions({ kind: 'role.grant' })).toHaveLength(0)
+  })
+
+  it('a grant whose record cannot be written does not happen', async () => {
+    const role = await getRepository(Role).save({ name: 'payroll', domain })
+    const table = authDataSource().getMetadata(AuditAction).tableName
+    await authDataSource().query(`ALTER TABLE ${table} RENAME TO ${table}_away`)
+
+    try {
+      await expect(grant(kim, [role])).rejects.toThrow()
+    } finally {
+      await authDataSource().query(`ALTER TABLE ${table}_away RENAME TO ${table}`)
+    }
+
+    const holder = await getRepository(User).findOne({ where: { id: kim.id }, relations: ['roles'] })
+    expect(holder.roles).toHaveLength(0)
+  })
+})
+
+describe('only the fields it allows (§3.4)', () => {
+  it('a detail key the kind did not register is refused', async () => {
+    await expect(recordAuditAction({ kind: 'user.status', detail: { salary: 4200000 } })).rejects.toThrow(/does not allow detail "salary"/)
+  })
+
+  it('a kind nobody registered is refused', async () => {
+    await expect(recordAuditAction({ kind: 'payroll.view' })).rejects.toThrow(/not registered/)
+  })
+})
+
+describe('signing in (§3.3)', () => {
+  it('a success, a wrong password, an account that does not exist', async () => {
+    await signin({ username: 'kim', password: PASSWORD })
+    await expect(signin({ username: 'kim', password: 'Wr0ngPass!' })).rejects.toThrow()
+    await expect(signin({ username: 'nobody', password: PASSWORD })).rejects.toThrow()
+    await flushAudit()
+
+    const rows = await getRepository(AuditAction).find({ where: { kind: 'auth.signin' }, relations: ['actor'], order: { createdAt: 'ASC' } })
+    expect(rows.map(row => [row.outcome, row.code, row.actor?.id ?? null])).toEqual([
+      ['ok', null, kim.id],
+      ['error', 'password-not-matched', kim.id],
+      ['error', 'user not found', null]
+    ])
+  })
+})
+
+describe('a write that fails is counted apart and does not stop the answer (§4-4 · §4-5)', () => {
+  it('the request is answered and the failure counted', async () => {
+    allow(true)
+    const before = auditHealth().failures
+    const table = authDataSource().getMetadata(AuditRequest).tableName
+    await authDataSource().query(`ALTER TABLE ${table} RENAME TO ${table}_away`)
+
+    try {
+      const result = await request(kim, '{ payslip(employeeId: "e1") }')
+      expect(result.data).toEqual({ payslip: 'pay of e1' })
+    } finally {
+      await authDataSource().query(`ALTER TABLE ${table}_away RENAME TO ${table}`)
+    }
+
+    expect(auditHealth().failures).toBe(before + 1)
+    expect(auditHealth().lastFailedAt).toBeInstanceOf(Date)
+  })
+})
+
+describe('reading the audit (§5 · §6)', () => {
+  const day = 24 * 60 * 60 * 1000
+  const from = new Date(Date.now() - day)
+  const to = new Date(Date.now() + day)
+  const context = (user = lee, at = domain) => ({ state: { domain: at, user } })
+
+  it("each member's checks, audit reads left out, and only this domain's", async () => {
+    allow(true)
+    await request(kim, '{ payslip(employeeId: "e1") }')
+    await request(kim, '{ payslips { id } }', other)
+    allow(false)
+    await request(kim, '{ payslip(employeeId: "e2") }')
+    await recordAuditAction({ kind: 'door.check', door: 'audit:query', decision: 'granted' }, { actorId: kim.id, domainId: domain.id })
+    await recordAuditAction({ kind: 'auth.checkin', outcome: 'ok' }, { actorId: kim.id, domainId: domain.id })
+
+    const people = await new AuditQuery().auditPeople(from, to, context())
+    const row = people.find((one: any) => one.user.id === kim.id)
+    expect(row).toMatchObject({ granted: 1, denied: 1, checkins: 1 })
+    expect(row.lastCheckinAt).toBeInstanceOf(Date)
+    /* The moment itself - a driver's zone-less text read as local time was hours off. */
+    expect(Math.abs(row.lastCheckinAt.getTime() - Date.now())).toBeLessThan(60_000)
+    expect(people.find((one: any) => one.user.id === lee.id)).toMatchObject({ granted: 0, denied: 0, checkins: 0 })
+  })
+
+  it('every declared door, one with no record in the period too', async () => {
+    await getRepository(Privilege).save([
+      { name: 'query', category: 'payroll' },
+      { name: 'mutation', category: 'payroll' },
+      { name: 'query', category: 'audit' }
+    ])
+    allow(true)
+    await request(kim, '{ payslip(employeeId: "e1") }')
+
+    const doors = await new AuditQuery().auditDoors(from, to, context())
+    expect(doors.map((one: any) => [one.door, one.people, one.granted])).toEqual([
+      ['payroll:mutation', 0, 0],
+      ['payroll:query', 1, 1]
+    ])
+  })
+
+  it('records narrow by outcome, and never reach another domain', async () => {
+    allow(true)
+    await request(kim, '{ payslip(employeeId: "e1") }')
+    await request(kim, '{ payslip(employeeId: "e1") }', other)
+    allow(false)
+    await request(lee, '{ payslip(employeeId: "e2") }')
+
+    const all = await new AuditQuery().auditRecords({ from, to }, context())
+    expect(all.total).toBe(2)
+
+    const denied = await new AuditQuery().auditRecords({ from, to, outcome: 'denied' }, context())
+    expect(denied.items.map((one: any) => one.request.actor.id)).toEqual([lee.id])
+    expect(denied.items[0].actions.map((one: any) => one.kind)).toEqual(['door.check'])
+  })
+
+  it('my record is what I did, whatever is asked', async () => {
+    await recordAuditAction({ kind: 'auth.checkin', outcome: 'ok' }, { actorId: kim.id, domainId: domain.id })
+    await recordAuditAction(
+      { kind: 'role.grant', targetKind: 'User', targetIds: [kim.id], objectKind: 'Role', objectId: 'r' },
+      { actorId: lee.id, domainId: domain.id }
+    )
+
+    const mine = await new AuditQuery().myAuditActions(undefined, 10, context(kim))
+    expect(mine.map((one: any) => one.kind)).toEqual(['auth.checkin'])
+  })
+})
+
+describe('retention (§7)', () => {
+  it('removes what is past a year and keeps the rest', async () => {
+    await recordAuditAction({ kind: 'auth.checkin', outcome: 'ok' }, { actorId: kim.id, domainId: domain.id })
+    const later = new Date(Date.now() + 366 * 24 * 60 * 60 * 1000)
+
+    expect(await purgeExpiredAudit(new Date())).toEqual({ requests: 0, actions: 0 })
+    expect(await purgeExpiredAudit(later)).toEqual({ requests: 0, actions: 1 })
+  })
+})

package/tests/auth-base-role-tasks.test.ts

@@ -0,0 +1,58 @@
+/**
+ * auth-base's own tasks (ADR-0139 decision 11) - each names doors declared where auth-base runs
+ * (its own server or shell's, which it depends on), and says what it is in all six languages.
+ *
+ * A task naming a category nobody declares is a definition error only when an application builds a
+ * seat from it; a task with no words shows its id on the role screen. Both are caught here, where
+ * the task is written.
+ */
+
+import { readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+import { loadCompiled } from './compiled'
+
+const { ROLE_TASKS } = loadCompiled('role-tasks')
+
+const LANGUAGES = ['ko', 'en', 'ja', 'zh', 'es', 'ms']
+const SERVERS = [join(__dirname, '..', 'server'), join(__dirname, '..', '..', 'shell', 'server')]
+
+/** Every `@privilege(category: "x", privilege: "y")` written in auth-base's and shell's server source. */
+function declaredDoors(): Set<string> {
+  const doors = new Set<string>()
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (entry.name.endsWith('.ts')) {
+        const text = readFileSync(path, 'utf8')
+        for (const match of text.matchAll(/@privilege\(category: \\?"([^"\\]+)\\?", privilege: \\?"([^"\\]+)\\?"/g)) {
+          doors.add(`${match[1]}:${match[2]}`)
+        }
+      }
+    }
+  }
+  SERVERS.forEach(walk)
+  return doors
+}
+
+describe("auth-base's tasks", () => {
+  const doors = declaredDoors()
+
+  it.each(ROLE_TASKS.map((task: any) => [task.id, task]))('%s names doors declared where auth-base runs', (_id, task: any) => {
+    for (const grant of task.grants) {
+      for (const axis of grant.axes) expect(doors).toContain(`${grant.category}:${axis}`)
+    }
+  })
+
+  it.each(LANGUAGES)('%s says what each task is', language => {
+    const words = JSON.parse(readFileSync(join(__dirname, '..', 'translations', `${language}.json`), 'utf8'))
+    for (const task of ROLE_TASKS) {
+      expect({ task: task.id, name: !!words[`task.${task.id}.name`], description: !!words[`task.${task.id}.description`] }).toEqual({
+        task: task.id,
+        name: true,
+        description: true
+      })
+    }
+  })
+})

package/tests/list-inheritance-db.test.ts

@@ -24,8 +24,6 @@ const { InvitationStatus } = loadCompiled('utils/invitation-state')
 const { InvitationQuery } = loadCompiled('service/invitation/invitation-query')
 const { Partner } = loadCompiled('service/partner/partner')
 const { PartnerQuery } = loadCompiled('service/partner/partner-query')
-const { LoginHistory } = loadCompiled('service/login-history/login-history')
-const { LoginHistoryQuery } = loadCompiled('service/login-history/login-history-query')
 
 let parent: any
 let child: any
@@ -119,11 +117,6 @@ const LISTS: [string, () => Promise<any>, (params: any, context: any) => Promise
     'partners',
     () => getRepository(Partner).save({ domain: parent, partnerDomain, requestedAt: new Date() }),
     (params, context) => new PartnerQuery().partners(params, context)
-  ],
-  [
-    'login histories',
-    () => LoginHistory.stamp(parent, parentUser, '10.0.0.1'),
-    (params, context) => new LoginHistoryQuery().loginHistories(params, context)
   ]
 ]
 

package/tests/open-doors.test.ts

@@ -80,7 +80,7 @@ describe('the doors that were closed', () => {
    *                                  signs in, so adding one is not an edit to a settings row
    *   domainUserRoleRegister         makes a domain, its roles and its users. `domainRegister`
    *                                  beside it makes only a domain and is super-user only
-   *   loginHistories                 everybody's sign-ins
+   *   loginHistories                 everybody's sign-ins - now the audit's, behind `audit:query` (ADR-0141)
    *   invitation / invitations       and neither of them scopes by tenant at all
    *   sendInvitation / cancelInvitation / inviteUser
    */
@@ -96,7 +96,7 @@ describe('the doors that were closed', () => {
       'cancelInvitation',
       'inviteUser'
     ],
-    Query: ['loginHistories', 'invitation', 'invitations']
+    Query: ['auditRecords', 'auditPeople', 'auditDoors', 'auditHealth', 'invitation', 'invitations']
   }
 
   it.each(Object.entries(CLOSED).flatMap(([t, fields]) => fields.map(f => [t, f])))('%s.%s', (typeName, field) => {

package/tests/refusal-cause.test.ts

@@ -64,7 +64,7 @@ describe('a refusal says which of the four it was', () => {
   it('★ an owner without the role, from an unsafe address: address - from a safe one they pass', async () => {
     given({ owner: true })
     expect(await judgePermission(OWNED, USER, DOMAIN, true)).toEqual({ permitted: false, because: 'address' })
-    expect(await judgePermission(OWNED, USER, DOMAIN, false)).toEqual({ permitted: true })
+    expect(await judgePermission(OWNED, USER, DOMAIN, false)).toEqual({ permitted: true, by: 'domain-owner' })
   })
 
   it('an unsafe address whose ownership cannot be asked still refuses as role - it refused before', async () => {

package/tests/role-task.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Role tasks — the registry, what it refuses, and how a role is laid against tasks (ADR-0139 decision 11).
+ *
+ * The comparison is pure: a role's held privileges, the registered tasks, the declared privileges. The role screen
+ * draws exactly this, so what "all", "some", "none" and "broken" mean is pinned here.
+ */
+
+import { loadCompiled } from './compiled'
+
+const { registerRoleTask, roleTasks, roleTaskById, mergeGrants, taskCoverageOf, undeclaredTaskGrants } = loadCompiled('service/role-template/role-task')
+const { registerRoleTemplate, templateGrantsOf, templateDefinitionErrors, unknownTemplateGrants } = loadCompiled('service/role-template/role-template')
+
+const DECLARED = {
+  'board query': ['board', 'query'],
+  'board mutation': ['board', 'mutation'],
+  'order query': ['order', 'query'],
+  'worklist query': ['worklist', 'query'],
+  'worklist mutation': ['worklist', 'mutation']
+}
+
+beforeEach(() => {
+  ;(process as any)['ROLE_TASKS'] = {}
+  ;(process as any)['ROLE_TEMPLATES'] = {}
+  ;(process as any).PRIVILEGES = { ...DECLARED }
+})
+
+const held = (...pairs: string[]) => new Set(pairs.map(pair => pair.replace(':', ' ')))
+
+describe('declaring a task', () => {
+  it('can be found again by id', () => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+
+    expect(roleTaskById('board.reading')).toEqual({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+    expect(roleTasks()).toHaveLength(1)
+  })
+
+  it.each([['reading'], [''], ['.reading']])('refuses the id "%s" - the declaring module comes first', id => {
+    expect(() => registerRoleTask({ id, grants: [{ category: 'board', axes: ['query'] }] })).toThrow(/<module>.<work>/)
+  })
+
+  it('refuses a task that holds no privileges', () => {
+    expect(() => registerRoleTask({ id: 'board.nothing', grants: [] })).toThrow(/holds no privileges/)
+  })
+
+  it('refuses a grant with no axes - axes are listed one by one', () => {
+    expect(() => registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: [] }] })).toThrow(/one by one/)
+  })
+
+  it('refuses the same task declared twice - one piece of work is one task', () => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+
+    expect(() => registerRoleTask({ id: 'board.reading', grants: [{ category: 'order', axes: ['query'] }] })).toThrow(/declared twice/)
+  })
+
+  it('holds a privilege written twice once', () => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }, { category: 'board', axes: ['query'] }] })
+
+    expect(roleTaskById('board.reading').grants).toEqual([{ category: 'board', axes: ['query'] }])
+  })
+
+  it('★ lets two tasks share a privilege - that is not a duplicate', () => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+    registerRoleTask({ id: 'order.reading', grants: [{ category: 'order', axes: ['query'] }, { category: 'board', axes: ['query'] }] })
+
+    expect(roleTasks()).toHaveLength(2)
+  })
+
+  it('keeps a change-only grant as written - nothing adds query to it', () => {
+    registerRoleTask({ id: 'worklist.putting-up', grants: [{ category: 'worklist', axes: ['mutation'] }] })
+
+    expect(roleTaskById('worklist.putting-up').grants).toEqual([{ category: 'worklist', axes: ['mutation'] }])
+  })
+})
+
+describe('a template built from tasks', () => {
+  beforeEach(() => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+    registerRoleTask({ id: 'order.reading', grants: [{ category: 'order', axes: ['query'] }, { category: 'board', axes: ['query'] }] })
+  })
+
+  it('★ holds the union of its tasks and its own grants, each privilege once', () => {
+    registerRoleTemplate({ id: 'plant.reader', name: 'READER', tasks: ['board.reading', 'order.reading'], grants: [{ category: 'board', axes: ['mutation', 'query'] }] })
+
+    expect(templateGrantsOf({ id: 'plant.reader', name: 'READER', tasks: ['board.reading', 'order.reading'], grants: [{ category: 'board', axes: ['mutation', 'query'] }] })).toEqual([
+      { category: 'board', axes: ['query', 'mutation'] },
+      { category: 'order', axes: ['query'] }
+    ])
+  })
+
+  it('may be written with tasks and no grants', () => {
+    expect(() => registerRoleTemplate({ id: 'plant.reader', name: 'READER', tasks: ['board.reading'] })).not.toThrow()
+  })
+
+  it('still refuses a template with neither - leaving both out is forgetting', () => {
+    expect(() => registerRoleTemplate({ id: 'plant.reader', name: 'READER' } as any)).toThrow(/has no grants/)
+  })
+
+  it('★ names an unregistered task as a definition error', () => {
+    expect(templateDefinitionErrors({ id: 'plant.reader', name: 'READER', tasks: ['board.reading', 'board.writting'] })).toEqual(['task "board.writting" is not registered'])
+  })
+
+  it('★ names a task privilege this installation does not declare as a definition error', () => {
+    registerRoleTask({ id: 'board.exporting', grants: [{ category: 'board-export', axes: ['query'] }] })
+
+    expect(undeclaredTaskGrants(roleTaskById('board.exporting'))).toEqual(['board-export:query'])
+    expect(templateDefinitionErrors({ id: 'plant.reader', name: 'READER', tasks: ['board.exporting'] })).toEqual([
+      'task "board.exporting" names board-export:query, which this installation does not declare'
+    ])
+  })
+
+  it("keeps a template's own undeclared grants as before - skipped, not a definition error", () => {
+    const template = { id: 'plant.reader', name: 'READER', grants: [{ category: 'kpi', axes: ['query'] }] }
+
+    expect(templateDefinitionErrors(template)).toEqual([])
+    expect(unknownTemplateGrants(template)).toEqual(['kpi:query'])
+  })
+})
+
+describe('a role laid against the tasks', () => {
+  beforeEach(() => {
+    registerRoleTask({ id: 'board.reading', grants: [{ category: 'board', axes: ['query'] }] })
+    registerRoleTask({ id: 'board.keeping', grants: [{ category: 'board', axes: ['query', 'mutation'] }] })
+    registerRoleTask({ id: 'order.reading', grants: [{ category: 'order', axes: ['query'] }, { category: 'board', axes: ['query'] }] })
+  })
+
+  const statuses = (coverage: any) => Object.fromEntries(coverage.tasks.map((task: any) => [task.taskId, task.status]))
+
+  it('★ says all, some and none by what the role holds of each task', () => {
+    const coverage = taskCoverageOf(held('board:query'))
+
+    expect(statuses(coverage)).toEqual({ 'board.reading': 'all', 'board.keeping': 'some', 'order.reading': 'some' })
+    expect(coverage.tasks.find((task: any) => task.taskId === 'board.keeping').missing).toEqual([{ category: 'board', axes: ['mutation'] }])
+  })
+
+  it('★ a shared privilege alone makes every task that names it "some" - reported, not supplied', () => {
+    const coverage = taskCoverageOf(held('board:query'))
+
+    expect(coverage.tasks.find((task: any) => task.taskId === 'order.reading')).toMatchObject({
+      status: 'some',
+      held: [{ category: 'board', axes: ['query'] }],
+      missing: [{ category: 'order', axes: ['query'] }]
+    })
+  })
+
+  it('says none for a role that holds nothing of a task', () => {
+    expect(statuses(taskCoverageOf(held('worklist:query')))).toEqual({ 'board.reading': 'none', 'board.keeping': 'none', 'order.reading': 'none' })
+  })
+
+  it('★ keeps what no task names apart - and leaves out what nothing declares any more', () => {
+    const coverage = taskCoverageOf(held('board:query', 'worklist:query', 'worklist:mutation', 'retired:query'))
+
+    expect(coverage.unclassified).toEqual([{ category: 'worklist', axes: ['mutation', 'query'] }])
+  })
+
+  it('★ says broken for a task naming an undeclared privilege, whatever the role holds', () => {
+    registerRoleTask({ id: 'board.exporting', grants: [{ category: 'board', axes: ['query'] }, { category: 'board-export', axes: ['query'] }] })
+
+    const task = taskCoverageOf(held('board:query')).tasks.find((one: any) => one.taskId === 'board.exporting')
+    expect(task).toMatchObject({ status: 'broken', module: 'board', undeclared: [{ category: 'board-export', axes: ['query'] }] })
+  })
+
+  it('merges grants by category in the order first written', () => {
+    expect(mergeGrants([[{ category: 'b', axes: ['x'] }], [{ category: 'a', axes: ['y'] }, { category: 'b', axes: ['z', 'x'] }]])).toEqual([
+      { category: 'b', axes: ['x', 'z'] },
+      { category: 'a', axes: ['y'] }
+    ])
+  })
+})