@things-factory/auth-base 10.1.47 → 10.1.106

package/tests/access-request-db.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Asking, deciding, telling - the access request end to end on the database (ADR-0103).
+ *
+ * The controller is called with a request state as the doors receive it. `notify` is a spy: the notification
+ * module is optional and the row is the record.
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Role } = loadCompiled('service/role/role')
+const { Privilege } = loadCompiled('service/privilege/privilege')
+const { User } = loadCompiled('service/user/user')
+const { DomainOwner } = loadCompiled('service/domain-owner/domain-owner')
+const { AccessRequest } = loadCompiled('service/access-request/access-request')
+const access = loadCompiled('controllers/access-request')
+
+let domain: any
+let other: any
+let warehouseMutation: any
+let warehouseQuery: any
+let userMutation: any
+let inbound: any
+let manager: any
+let admins: any
+let kim: any
+let park: any
+let owner: any
+
+async function makeUser(name: string, domains: any[], roles: any[] = [], over: any = {}) {
+  const tag = Math.random().toString(36).slice(2, 8)
+  return await getRepository(User).save({
+    username: `${name}-${tag}`,
+    email: `${name}-${tag}@example.com`,
+    name,
+    salt: User.generateSalt(),
+    status: 'activated',
+    domains,
+    roles,
+    ...over
+  })
+}
+
+function contextOf(user: any, over: any = {}) {
+  const notify = jest.fn().mockResolvedValue(undefined)
+  const afterCommit: any[] = []
+  return {
+    state: { domain, user, afterCommit, notify, ...over },
+    t: (key: string) => key,
+    afterCommit,
+    notify
+  } as any
+}
+
+async function commit(context: any) {
+  for (const step of context.afterCommit) await step.run()
+}
+
+async function holds(user: any, category: string, privilege: string) {
+  return await User.hasPrivilege(privilege, category, domain, user)
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+
+  const saved = await getRepository(Domain).save({ name: 'Plant A', subdomain: 'plant-a' })
+  domain = await getRepository(Domain).findOneBy({ id: saved.id })
+  other = await getRepository(Domain).save({ name: 'Other', subdomain: 'other' })
+
+  warehouseMutation = await getRepository(Privilege).save({ name: 'mutation', category: 'warehouse' })
+  warehouseQuery = await getRepository(Privilege).save({ name: 'query', category: 'warehouse' })
+  userMutation = await getRepository(Privilege).save({ name: 'mutation', category: 'user' })
+
+  inbound = await getRepository(Role).save({ name: 'inbound', domain, privileges: [warehouseMutation] })
+  manager = await getRepository(Role).save({ name: 'manager', domain, privileges: [warehouseMutation, warehouseQuery, userMutation] })
+  admins = await getRepository(Role).save({ name: 'admins', domain, privileges: [userMutation, warehouseQuery] })
+
+  kim = await makeUser('kim', [domain])
+  park = await makeUser('park', [domain], [admins])
+  owner = await makeUser('owner', [domain])
+  await getRepository(DomainOwner).save({ domain, user: owner })
+})
+
+const ASK = { category: 'warehouse', privilege: 'mutation', operationName: 'updateInboundPlan', reason: 'inbound from today' }
+
+describe('asking', () => {
+  it('★ a request is a row - pending, fourteen days, and the people who decide are told once', async () => {
+    const context = contextOf(kim)
+    const request = await access.requestAccess(ASK, context)
+    await commit(context)
+
+    expect(request).toMatchObject({ state: 'PENDING', category: 'warehouse', privilege: 'mutation', count: 1, reason: 'inbound from today' })
+    expect(context.notify).toHaveBeenCalledTimes(1)
+    expect([...context.notify.mock.calls[0][0].receivers].sort()).toEqual([owner.id, park.id].sort())
+  })
+
+  it('★ asking again adds to the pending one - no second row, nobody told again', async () => {
+    await access.requestAccess(ASK, contextOf(kim))
+    const again = contextOf(kim)
+    const merged = await access.requestAccess({ ...ASK, reason: 'still needed' }, again)
+    await commit(again)
+
+    expect(merged.count).toBe(2)
+    expect(merged.reason).toBe('still needed')
+    expect(await getRepository(AccessRequest).count()).toBe(1)
+    expect(again.notify).not.toHaveBeenCalled()
+  })
+
+  it('★ a privilege the caller holds is not asked for', async () => {
+    const kimWithRole = await makeUser('lee', [domain], [inbound])
+    await expect(access.requestAccess(ASK, contextOf(kimWithRole))).rejects.toMatchObject({ code: 'access-request-already-holds' })
+  })
+
+  it('★ refused by the license, not by a role - not taken, whatever the screen sent', async () => {
+    const context = contextOf(kim, { prohibitedPrivileges: [{ category: 'warehouse', privilege: 'mutation', by: 'license' }] })
+    await expect(access.requestAccess(ASK, context)).rejects.toMatchObject({ code: 'access-request-not-by-role', params: { because: 'license' } })
+  })
+
+  it('a privilege nobody declared is not asked for', async () => {
+    await expect(access.requestAccess({ category: 'nothing', privilege: 'here' }, contextOf(kim))).rejects.toMatchObject({
+      code: 'access-request-unknown-privilege'
+    })
+  })
+
+  it('the requester withdraws their own, and nobody else can', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    await expect(access.withdrawAccessRequest(request.id, contextOf(park))).rejects.toMatchObject({ code: 'access-request-not-withdrawable' })
+    expect((await access.withdrawAccessRequest(request.id, contextOf(kim))).state).toBe('WITHDRAWN')
+  })
+})
+
+describe('who decides', () => {
+  it('★ owners and holders of user:mutation in this domain, never the requester', async () => {
+    const outsider = await makeUser('outsider', [other], [admins])
+    const ids = await access.findDeciderIds(domain, park.id)
+    expect(ids).toEqual([owner.id].sort())
+    expect(ids).not.toContain(outsider.id)
+  })
+})
+
+describe('deciding', () => {
+  it('★ grant puts the requester into the role - they pass the gate on the next request', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    const context = contextOf(park)
+    const decided = await access.decideAccessRequest({ requestId: request.id, decision: 'GRANT', roleId: inbound.id }, context)
+    await commit(context)
+
+    expect(decided).toMatchObject({ state: 'GRANTED', grantedRole: { id: inbound.id } })
+    expect(await holds(kim, 'warehouse', 'mutation')).toBe(true)
+    expect(context.notify).toHaveBeenCalledWith(expect.objectContaining({ receivers: [kim.id], title: 'access-request.notify.granted.title' }))
+  })
+
+  it('★ deny keeps the reason and tells the requester', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    const context = contextOf(park)
+    const decided = await access.decideAccessRequest({ requestId: request.id, decision: 'DENY', reason: 'IT only' }, context)
+    await commit(context)
+
+    expect(decided).toMatchObject({ state: 'DENIED', decisionReason: 'IT only' })
+    expect(await holds(kim, 'warehouse', 'mutation')).toBe(false)
+    expect(context.notify).toHaveBeenCalledWith(expect.objectContaining({ title: 'access-request.notify.denied.title' }))
+  })
+
+  it('★ the second decision is refused - the first one stands', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    await access.decideAccessRequest({ requestId: request.id, decision: 'DENY', reason: 'no' }, contextOf(owner))
+    await expect(access.decideAccessRequest({ requestId: request.id, decision: 'GRANT', roleId: inbound.id }, contextOf(park))).rejects.toMatchObject({
+      code: 'access-decision-request-not-pending'
+    })
+    expect(await holds(kim, 'warehouse', 'mutation')).toBe(false)
+  })
+
+  it('★ two people deciding at once - exactly one wins (both reviews read PENDING before either writes)', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    const results = await Promise.allSettled([
+      access.decideAccessRequest({ requestId: request.id, decision: 'DENY', reason: 'no' }, contextOf(owner)),
+      access.decideAccessRequest({ requestId: request.id, decision: 'GRANT', roleId: inbound.id }, contextOf(park))
+    ])
+
+    expect(results.map(r => r.status).sort()).toEqual(['fulfilled', 'rejected'])
+    const lost = results.find(r => r.status === 'rejected') as PromiseRejectedResult
+    expect(lost.reason).toMatchObject({ code: 'access-decision-request-not-pending' })
+  })
+
+  it('★ the review blocks inside the door too - a role without the privilege is refused', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    await expect(access.decideAccessRequest({ requestId: request.id, decision: 'GRANT', roleId: admins.id }, contextOf(park))).rejects.toMatchObject({
+      code: 'access-decision-role-does-not-grant'
+    })
+    expect((await getRepository(AccessRequest).findOneBy({ id: request.id })).state).toBe('PENDING')
+  })
+
+  it('★ another tenant\'s role is refused - it is not this domain\'s to give', async () => {
+    const foreign = await getRepository(Role).save({ name: 'foreign', domain: other, privileges: [warehouseMutation] })
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    await expect(access.decideAccessRequest({ requestId: request.id, decision: 'GRANT', roleId: foreign.id }, contextOf(park))).rejects.toMatchObject({
+      code: 'access-decision-role-not-assignable'
+    })
+  })
+
+  it('a request of another domain is not found from this one', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    const stranger = await makeUser('stranger', [other], [admins])
+    const fromThere = contextOf(stranger, { domain: await getRepository(Domain).findOneBy({ id: other.id }) })
+    await expect(access.decideAccessRequest({ requestId: request.id, decision: 'DENY', reason: 'x' }, fromThere)).rejects.toMatchObject({
+      code: 'access-decision-access-request-not-found'
+    })
+  })
+
+  it('★ a grant closes the same person\'s other requests it now answers', async () => {
+    const first = await access.requestAccess(ASK, contextOf(kim))
+    const second = await access.requestAccess({ category: 'warehouse', privilege: 'query' }, contextOf(kim))
+    await access.decideAccessRequest({ requestId: first.id, decision: 'GRANT', roleId: manager.id }, contextOf(owner))
+
+    expect((await getRepository(AccessRequest).findOneBy({ id: second.id })).state).toBe('GRANTED')
+  })
+})
+
+describe('the review as the screen asks it', () => {
+  it('★ candidates smallest first, and the review of a big role names what else it gives', async () => {
+    const request = await access.requestAccess(ASK, contextOf(kim))
+    const candidates = await access.rolesGranting('warehouse', 'mutation', domain)
+    expect(candidates.map((c: any) => c.name)).toEqual(['inbound', 'manager'])
+
+    const issues = await access.reviewDecision({ requestId: request.id, decision: 'GRANT', roleId: manager.id }, contextOf(park))
+    expect(issues.map((i: any) => i.code).sort()).toEqual(['decider-lacks-it', 'role-grants-admin', 'role-grants-more', 'smaller-role-exists'])
+  })
+})

package/tests/access-request-review.test.ts

@@ -0,0 +1,155 @@
+/**
+ * The access decision review - pure (ADR-0103, docs/design/access-request.md §6-1).
+ *
+ * The list screen, the AI 입력 draft card and the decision door all read this one function, so what it says
+ * is what every one of them says. Each code is held here on its own.
+ */
+
+import {
+  effectiveState,
+  expiryFrom,
+  isBlocked,
+  reviewAccessDecision,
+  smallestRole,
+  type DecisionFacts
+} from '../server/utils/access-request-review.js'
+
+const NOW = new Date('2026-10-02T09:00:00Z')
+const ASKED = { category: 'warehouse', privilege: 'mutation' }
+const SEE = { category: 'warehouse', privilege: 'query' }
+const GRANT_ROLES = { category: 'user', privilege: 'mutation' }
+
+function facts(over: Partial<DecisionFacts> = {}): DecisionFacts {
+  return {
+    request: { state: 'PENDING', requesterId: 'kim', ...ASKED, expiresAt: expiryFrom(NOW) },
+    deciderId: 'park',
+    decision: 'GRANT',
+    reason: null,
+    role: { id: 'r-inbound', name: 'inbound', privileges: [ASKED] },
+    requester: { active: true, inDomain: true },
+    requesterHoldsIt: false,
+    candidates: [{ id: 'r-inbound', name: 'inbound', privilegeCount: 1 }],
+    deciderPrivileges: [ASKED, SEE, GRANT_ROLES],
+    deciderIsOwner: false,
+    deniedBefore: null,
+    now: NOW,
+    ...over
+  }
+}
+
+const codes = (f: DecisionFacts) => reviewAccessDecision(f).map(issue => `${issue.blocking ? '⛔' : '⚠'}${issue.code}`)
+
+describe('a clean grant', () => {
+  it('★ the smallest role that holds exactly what was asked passes with nothing to say', () => {
+    expect(reviewAccessDecision(facts())).toEqual([])
+  })
+})
+
+describe('what keeps a decision from being made', () => {
+  it('★ no such request', () => {
+    expect(codes(facts({ request: null }))).toEqual(['⛔access-request-not-found'])
+  })
+
+  it('★ decided, withdrawn or expired already - another person may have decided a moment ago', () => {
+    for (const state of ['GRANTED', 'DENIED', 'WITHDRAWN', 'EXPIRED'] as const) {
+      expect(codes(facts({ request: { ...facts().request!, state } }))).toContain('⛔request-not-pending')
+    }
+  })
+
+  it('★ a pending request past its time is expired whatever the column says', () => {
+    const late = facts({ request: { ...facts().request!, expiresAt: new Date(NOW.getTime() - 1) } })
+    expect(codes(late)).toContain('⛔request-not-pending')
+  })
+
+  it('★ the decider is the requester', () => {
+    expect(codes(facts({ deciderId: 'kim' }))).toContain('⛔own-request')
+  })
+
+  it('★ the requester is locked, inactive or gone from the domain', () => {
+    expect(codes(facts({ requester: { active: false, inDomain: true } }))).toContain('⛔requester-unavailable')
+    expect(codes(facts({ requester: { active: true, inDomain: false } }))).toContain('⛔requester-unavailable')
+    expect(codes(facts({ requester: null }))).toContain('⛔requester-unavailable')
+  })
+
+  it('★ a denial without a reason', () => {
+    expect(codes(facts({ decision: 'DENY', reason: '  ', role: null }))).toEqual(['⛔deny-needs-reason'])
+    expect(codes(facts({ decision: 'DENY', reason: 'IT only', role: null }))).toEqual([])
+  })
+
+  it('★ the requester holds it already', () => {
+    expect(codes(facts({ requesterHoldsIt: true }))).toContain('⛔already-holds')
+  })
+
+  it('★ no role chosen, or one this domain cannot assign', () => {
+    expect(codes(facts({ role: null }))).toEqual(['⛔role-required'])
+    expect(codes(facts({ role: null, roleNamedButNotAssignable: true }))).toEqual(['⛔role-not-assignable'])
+  })
+
+  it('★ the role does not hold the asked privilege', () => {
+    expect(codes(facts({ role: { id: 'r-viewer', name: 'viewer', privileges: [SEE] } }))).toEqual(['⛔role-does-not-grant'])
+  })
+})
+
+describe('what the person deciding is told', () => {
+  const manager = { id: 'r-manager', name: 'manager', privileges: [ASKED, SEE, GRANT_ROLES] }
+  const candidates = [
+    { id: 'r-inbound', name: 'inbound', privilegeCount: 1 },
+    { id: 'r-manager', name: 'manager', privilegeCount: 3 }
+  ]
+
+  it('★ the role gives more than was asked - named', () => {
+    const issues = reviewAccessDecision(facts({ role: manager, candidates }))
+    expect(issues.find(i => i.code === 'role-grants-more')).toMatchObject({
+      blocking: false,
+      params: { count: 2, privileges: 'warehouse:query, user:mutation' }
+    })
+  })
+
+  it('★ the role hands on the power to give roles', () => {
+    expect(codes(facts({ role: manager, candidates }))).toContain('⚠role-grants-admin')
+  })
+
+  it('asking for the role-giving power itself is not warned as a side effect', () => {
+    const asked = facts({
+      request: { ...facts().request!, ...GRANT_ROLES },
+      role: { id: 'r-admin', name: 'admin', privileges: [GRANT_ROLES] },
+      candidates: [{ id: 'r-admin', name: 'admin', privilegeCount: 1 }]
+    })
+    expect(codes(asked)).not.toContain('⚠role-grants-admin')
+  })
+
+  it('★ a smaller role grants it too - its name', () => {
+    const issues = reviewAccessDecision(facts({ role: manager, candidates }))
+    expect(issues.find(i => i.code === 'smaller-role-exists')).toMatchObject({ params: { role: 'inbound', count: 1 } })
+  })
+
+  it('★ the role gives what the decider does not have - told, not refused (Q6)', () => {
+    const issues = reviewAccessDecision(facts({ role: manager, candidates, deciderPrivileges: [ASKED] }))
+    expect(issues.find(i => i.code === 'decider-lacks-it')).toMatchObject({ blocking: false, params: { privileges: 'warehouse:query, user:mutation' } })
+    expect(isBlocked(issues)).toBe(false)
+  })
+
+  it('an owner is not told they lack anything', () => {
+    expect(codes(facts({ role: manager, candidates, deciderPrivileges: [], deciderIsOwner: true }))).not.toContain('⚠decider-lacks-it')
+  })
+
+  it('★ denied before - by whom, when, why', () => {
+    const issues = reviewAccessDecision(facts({ deniedBefore: { by: 'Lee', at: '2026-09-01T00:00:00Z', reason: 'IT only' } }))
+    expect(issues).toEqual([
+      { code: 'denied-before', blocking: false, field: 'request', params: { by: 'Lee', at: '2026-09-01T00:00:00.000Z', reason: 'IT only' } }
+    ])
+  })
+})
+
+describe('helpers', () => {
+  it('the smallest role, ties by name - the same answer every time', () => {
+    expect(smallestRole([{ name: 'b', privilegeCount: 2 }, { name: 'a', privilegeCount: 2 }, { name: 'c', privilegeCount: 5 }])?.name).toBe('a')
+    expect(smallestRole([])).toBeUndefined()
+  })
+
+  it('a request waits fourteen days', () => {
+    expect(expiryFrom(NOW).toISOString()).toBe('2026-10-16T09:00:00.000Z')
+    expect(effectiveState('PENDING', null, NOW)).toBe('PENDING')
+    expect(effectiveState('GRANTED', new Date(0), NOW)).toBe('GRANTED')
+  })
+})

package/tests/assignable-roles-db.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Putting a person into roles - one function, the domain's scope, ids found again (ADR-0103 decision 2).
+ *
+ * `updateUserRoles` concatenated the client's `selectedRoles` onto the user as sent and removed every held role
+ * whose id was in `availableRoles`. A role of another tenant went in; another tenant's role id in
+ * `availableRoles` took that role away from the person in the other domain. The access request grants through
+ * the same function, so both doors are held here.
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Role } = loadCompiled('service/role/role')
+const { GrantedRole } = loadCompiled('service/granted-role/granted-role')
+const { User } = loadCompiled('service/user/user')
+const { UserMutation } = loadCompiled('service/user/user-mutation')
+const { assignRoles } = loadCompiled('utils/assignable-roles')
+
+let parent: any
+let child: any
+let stranger: any
+
+async function loadDomain(id: string) {
+  return await getRepository(Domain).findOneBy({ id })
+}
+
+async function makeUser(domains: any[], roles: any[]) {
+  const tag = Math.random().toString(36).slice(2, 8)
+  return await getRepository(User).save({
+    username: `u-${tag}`,
+    email: `u-${tag}@example.com`,
+    name: 'Kim',
+    salt: User.generateSalt(),
+    status: 'activated',
+    domains,
+    roles
+  })
+}
+
+async function heldRoleNames(user: any) {
+  const read = await getRepository(User).findOne({ where: { id: user.id }, relations: ['roles'] })
+  return read.roles.map((role: any) => role.name).sort()
+}
+
+function updateUserRoles(user: any, available: any[], selected: any[], domain: any) {
+  return new UserMutation().updateUserRoles(
+    user.username,
+    available.map(role => ({ id: role.id })),
+    selected.map(role => ({ id: role.id })),
+    { state: { domain }, t: (key: string) => key } as any
+  )
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+
+  const domainRepository = getRepository(Domain)
+  const savedParent = await domainRepository.save({ name: 'HQ', subdomain: 'hq' })
+  const savedChild = await domainRepository.save({ name: 'Plant A', subdomain: 'plant-a', parent: savedParent })
+  const savedStranger = await domainRepository.save({ name: 'Other', subdomain: 'other' })
+
+  parent = await loadDomain(savedParent.id)
+  child = await loadDomain(savedChild.id)
+  stranger = await loadDomain(savedStranger.id)
+})
+
+describe('what a domain can put a person into', () => {
+  it('its own role, its parent role and a role granted to it - all three', async () => {
+    const own = await getRepository(Role).save({ name: 'operator', domain: child })
+    const inherited = await getRepository(Role).save({ name: 'viewer', domain: parent })
+    const granted = await getRepository(Role).save({ name: 'partner', domain: stranger })
+    await getRepository(GrantedRole).save({ role: granted, domain: child })
+    const user = await makeUser([child], [])
+
+    const { added } = await assignRoles(user, { add: [own.id, inherited.id, granted.id] }, child)
+
+    expect(added.map((role: any) => role.name).sort()).toEqual(['operator', 'partner', 'viewer'])
+    expect(await heldRoleNames(user)).toEqual(['operator', 'partner', 'viewer'])
+  })
+
+  it('★ another tenant\'s role is refused by name, and nothing is saved', async () => {
+    const own = await getRepository(Role).save({ name: 'operator', domain: child })
+    const foreign = await getRepository(Role).save({ name: 'auditor', domain: stranger })
+    const user = await makeUser([child], [])
+
+    await expect(assignRoles(user, { add: [own.id, foreign.id] }, child)).rejects.toMatchObject({
+      code: 'role-not-assignable-here',
+      params: { roles: foreign.id }
+    })
+    expect(await heldRoleNames(user)).toEqual([])
+  })
+
+  it('a role already held is not added twice and is not reported as added', async () => {
+    const own = await getRepository(Role).save({ name: 'operator', domain: child })
+    const user = await makeUser([child], [own])
+
+    const { added } = await assignRoles(user, { add: [own.id] }, child)
+
+    expect(added).toEqual([])
+    expect(await heldRoleNames(user)).toEqual(['operator'])
+  })
+})
+
+describe('updateUserRoles goes through the same function', () => {
+  it('★ a foreign role in selectedRoles is refused - it used to be attached as sent', async () => {
+    const foreign = await getRepository(Role).save({ name: 'auditor', domain: stranger })
+    const user = await makeUser([child], [])
+
+    /* The method is called directly, so the Refusal arrives before SpeakRefusals turns it into a sentence. */
+    await expect(updateUserRoles(user, [], [foreign], child)).rejects.toMatchObject({ code: 'role-not-assignable-here' })
+    expect(await heldRoleNames(user)).toEqual([])
+  })
+
+  it('★ a foreign role in availableRoles stays with the person - this domain cannot take it', async () => {
+    const own = await getRepository(Role).save({ name: 'operator', domain: child })
+    const theirs = await getRepository(Role).save({ name: 'auditor', domain: stranger })
+    const user = await makeUser([child, stranger], [own, theirs])
+
+    await updateUserRoles(user, [own, theirs], [], child)
+
+    expect(await heldRoleNames(user)).toEqual(['auditor'])
+  })
+
+  it('within the scope it replaces as before - remove the shown, add the chosen', async () => {
+    const a = await getRepository(Role).save({ name: 'a', domain: child })
+    const b = await getRepository(Role).save({ name: 'b', domain: child })
+    const user = await makeUser([child], [a])
+
+    await updateUserRoles(user, [a, b], [b], child)
+
+    expect(await heldRoleNames(user)).toEqual(['b'])
+  })
+})

package/tests/permission-gate.test.ts

@@ -117,15 +117,13 @@ describe('이름이 없는 선언 — 소유권만으로 판정한다', () => {
     expect(await checkPermission({ owner: true }, USER, DOMAIN)).toBe(true)
   })
 
-  it('소유자가 아니면 닫힌다 — 다만 돌려주는 값이 `false` 가 아니라 `undefined` 다', async () => {
-    /* 선언한 타입은 `Promise<boolean>` 인데 실제로는 `(true && false) || (undefined && …)`
-       = `undefined` 가 나온다. 지금 모든 소비처가 `if (await checkPermission(…))` 로 받으므로
-       거동은 같다 — 그러나 시그니처가 사실과 다르고, `=== false` 로 받는 소비처가 하나
-       생기는 순간 조용히 통과한다. 그래서 값 자체를 고정한다. */
+  it('소유자가 아니면 닫힌다 — 값은 `false` 다', async () => {
+    /* 2026-10-02 까지는 `(true && false) || (undefined && …)` = `undefined` 가 나왔다. 선언한 타입은
+       `Promise<boolean>` 이었고, `=== false` 로 받는 소비처가 생기는 순간 조용히 통과할 자리였다.
+       판정이 이유를 내게 되면서(`judgePermission`, ADR-0103) 값이 타입과 같아졌다. */
     const decision = await checkPermission({ owner: true }, USER, DOMAIN)
 
-    expect(decision).toBeFalsy()
-    expect(decision).toBeUndefined()
+    expect(decision).toBe(false)
   })
 
   it('refuses an object that names nothing', async () => {

package/tests/privilege-directive.test.ts

@@ -291,3 +291,24 @@ describe('a declaration that names nothing', () => {
     expect(buildField('@privilege(superUserGranted: true)')).not.toThrow()
   })
 })
+
+describe('거절이 이유를 싣는다 (ADR-0103 결정 1)', () => {
+  it('★ 역할이 없으면 because: role — 화면이 「권한 요청」을 띄운다', async () => {
+    const result = await run(buildSchema(), 'guardedBoard')
+    expect((result.errors![0].extensions as any).because).toBe('role')
+  })
+
+  it('★ 라이선스가 막으면 역할이 있어도 because: license — 요청할 것이 아니다', async () => {
+    User.hasPrivilege = jest.fn().mockResolvedValue(true)
+    const result = await run(buildSchema(), 'guardedBoard', {
+      prohibitedPrivileges: [{ category: 'board', privilege: 'mutation', by: 'license' }]
+    })
+    expect((result.errors![0].extensions as any).because).toBe('license')
+  })
+
+  it('★ 보호 주소 밖에서 소유자 전용이면 because: address', async () => {
+    withOwnership({ owner: true })
+    const result = await run(buildSchema(), 'ownershipOnly', { unsafeIP: true })
+    expect((result.errors![0].extensions as any).because).toBe('address')
+  })
+})

package/tests/privilege-rejection.test.ts

@@ -70,3 +70,35 @@ describe('privilege rejection', () => {
     expect(privilegeRejection({}, undefined, 'mutation').extensions.requires).toBe('ownership')
   })
 })
+
+describe('privilege rejection carries why (ADR-0103 decision 1)', () => {
+  it('★ the cause goes in extensions.because - a screen offers a request only for role', () => {
+    expect(privilegeRejection(undefined, 'twin', 'mutation', 'license').extensions).toEqual({
+      code: 'FORBIDDEN',
+      requires: { category: 'twin', privilege: 'mutation' },
+      because: 'license'
+    })
+  })
+
+  it('a caller that does not say keeps the old meaning - named is role, unnamed is ownership', () => {
+    expect(privilegeRejection(undefined, 'twin', 'mutation').extensions.because).toBe('role')
+    expect(privilegeRejection(undefined).extensions.because).toBe('ownership')
+  })
+
+  it('★ each cause has its own sentence - an address refusal does not say a privilege is missing', () => {
+    const address = privilegeRejection(undefined, 'twin', 'mutation', 'address').message
+    const license = privilegeRejection(undefined, 'twin', 'mutation', 'license').message
+    const role = privilegeRejection(undefined, 'twin', 'mutation', 'role').message
+    expect(new Set([address, license, role]).size).toBe(3)
+    expect(address).toContain('address')
+    expect(license).toContain('licensed')
+  })
+
+  it('every sentence key is in all five languages', () => {
+    const keys = ['error.x not allowed from this address', 'error.x not licensed', 'error.x refused for this request', 'error.ownership not allowed from this address']
+    for (const lng of ['en', 'ko', 'ja', 'zh', 'ms']) {
+      const dict = require(`../translations/${lng}.json`)
+      for (const key of keys) expect([lng, key, typeof dict[key]]).toEqual([lng, key, 'string'])
+    }
+  })
+})