@things-factory/auth-base 10.1.4 → 10.1.6

package/tests/password-persistence.test.ts

@@ -0,0 +1,147 @@
+/**
+ * 비밀번호 변경이 **DB 에 무엇을 남기나** — 실 엔티티로 저장하고 읽어서 확인한다.
+ *
+ * ── 왜 이것이 첫 DB 시험인가 ────────────────────────────────────────────────
+ * 「비밀번호를 바꾸면 다른 기기의 세션이 끊겨야 한다」를 세우려면 그 판단의 근거가 필요하고,
+ * 후보는 `User.passwordUpdatedAt` 이다. 그런데 그 칸을 쓰는 코드가 이 모양이다:
+ *
+ *     await repository.save({ ...user, passwordUpdatedAt: new Date() })   // change-pwd.ts:79
+ *
+ * 이 저장소는 **읽어 온 엔티티를 펼쳐 `save` 하면 칸이 조용히 안 써지는** 함정을 이미 한 번
+ * 겪었다(도메인 시각대 — 로그는 「두었습니다」, `select` 는 `None`). 그러니 그 칸을 근거로
+ * 삼기 전에 **읽어서 확인해야 한다.** 코드도 로그도 근거가 아니다.
+ *
+ * 여기서는 실제 컨트롤러(`changePwd`)를 그대로 태운다 — 칸을 직접 써 보는 것이 아니라,
+ * 화면이 부르는 그 경로가 무엇을 남기는지를 본다.
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { User } = loadCompiled('service/user/user')
+const { changePwd } = loadCompiled('controllers/change-pwd')
+
+const CURRENT = 'Passw0rd!'
+const NEXT = 'N3xtPass!'
+
+/** `changePwd` 가 컨텍스트에서 실제로 읽는 것만 담는다 — 도메인과 언어뿐이다. */
+function contextFor(domain: any) {
+  return { state: { domain }, lng: 'en-US' }
+}
+
+async function seedUser(domain: any) {
+  const salt = User.generateSalt()
+
+  return await getRepository(User).save({
+    username: 'kim',
+    email: 'kim@example.com',
+    name: 'Kim',
+    salt,
+    password: User.encode(CURRENT, salt),
+    status: 'activated',
+    domains: [domain]
+  })
+}
+
+let domain: any
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+  domain = await getRepository(Domain).save({ name: 'plant-a', subdomain: 'plant-a' })
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+describe('changePwd 가 DB 에 남기는 것', () => {
+  it('새 비밀번호로 로그인할 수 있게 된다', async () => {
+    const user = await seedUser(domain)
+
+    await changePwd({ id: user.id }, CURRENT, NEXT, NEXT, contextFor(domain))
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+    expect(User.verify(stored.password, NEXT, stored.salt)).toBe(true)
+    expect(User.verify(stored.password, CURRENT, stored.salt)).toBe(false)
+  })
+
+  it('`passwordUpdatedAt` 이 실제로 써진다 — 펼쳐 넣은 칸이 살아남는가', async () => {
+    /*
+     * 이 시험이 이 파일의 이유다. 세션 무효화가 이 칸을 근거로 삼을 수 있는지가 여기서 갈린다.
+     * 반환값이나 로그가 아니라 **다시 읽은 행**을 본다.
+     */
+    const user = await seedUser(domain)
+    expect(user.passwordUpdatedAt).toBeFalsy() /* 새로 만든 행은 `null` 이다 */
+
+    const before = Date.now()
+    await changePwd({ id: user.id }, CURRENT, NEXT, NEXT, contextFor(domain))
+    const after = Date.now()
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+
+    expect(stored.passwordUpdatedAt).toBeTruthy()
+
+    const written = new Date(stored.passwordUpdatedAt).getTime()
+    expect(written).toBeGreaterThanOrEqual(before - 1000)
+    expect(written).toBeLessThanOrEqual(after + 1000)
+  })
+
+  it('토큰을 돌려준다 — 그리고 그 토큰의 `iat` 이 칸보다 앞선다', async () => {
+    /*
+     * `token-issuance.test.ts` 가 초 절삭을 단위로 보였고, 여기서는 **실제 경로**에서 같은 일이
+     * 일어나는 것을 본다: `changePwd` 는 칸을 쓴 뒤(:79) 토큰을 발급한다(:99). 그래서
+     * `iat * 1000 < passwordUpdatedAt` 로 옛 세션을 끊으면 **방금 받은 이 토큰도 끊긴다.**
+     */
+    const jwt = require('jsonwebtoken')
+    const user = await seedUser(domain)
+
+    const token = await changePwd({ id: user.id }, CURRENT, NEXT, NEXT, contextFor(domain))
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+
+    const { iat } = jwt.decode(token) as any
+    expect(iat * 1000).toBeLessThan(new Date(stored.passwordUpdatedAt).getTime())
+  })
+
+  it('현재 비밀번호가 틀리면 아무것도 바꾸지 않는다', async () => {
+    const user = await seedUser(domain)
+
+    await expect(changePwd({ id: user.id }, 'WrongPass!', NEXT, NEXT, contextFor(domain))).rejects.toThrow()
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+    expect(User.verify(stored.password, CURRENT, stored.salt)).toBe(true)
+    expect(stored.passwordUpdatedAt).toBeFalsy()
+  })
+
+  it('확인 비밀번호가 다르면 거절한다', async () => {
+    const user = await seedUser(domain)
+
+    await expect(changePwd({ id: user.id }, CURRENT, NEXT, 'Different1!', contextFor(domain))).rejects.toThrow()
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+    expect(User.verify(stored.password, CURRENT, stored.salt)).toBe(true)
+  })
+
+  it('새 비밀번호가 규칙에 안 맞으면 거절한다', async () => {
+    const user = await seedUser(domain)
+
+    await expect(changePwd({ id: user.id }, CURRENT, 'short', 'short', contextFor(domain))).rejects.toThrow()
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+    expect(User.verify(stored.password, CURRENT, stored.salt)).toBe(true)
+  })
+
+  it('salt 는 그대로 두고 해시만 바꾼다', async () => {
+    /* salt 를 함께 갈면 비밀번호 이력 대조(`User.verify(h.password, …, h.salt)`)가 옛 salt 를
+       들고 있어야 성립한다. 지금 어느 쪽인지를 고정해 둔다. */
+    const user = await seedUser(domain)
+
+    await changePwd({ id: user.id }, CURRENT, NEXT, NEXT, contextFor(domain))
+
+    const stored = await getRepository(User).findOneBy({ id: user.id })
+    expect(stored.salt).toBe(user.salt)
+  })
+})

package/tests/permission-gate.test.ts

@@ -0,0 +1,226 @@
+/**
+ * 인가 게이트(`checkPermission`) 판정 시험.
+ *
+ * 이 함수가 플랫폼의 **모든** 권한 판정의 마지막 자리다 — `@privilege` 지시자와
+ * `auth-private-process-router`·`integration-base` 의 시나리오 실행이 모두 여기로 모인다.
+ * 그런데 저장소의 시험 316개 중 이 함수를 부르는 것이 없었다. 리빌딩 전에 **지금 무엇을 하는지**
+ * 를 고정한다.
+ *
+ * ## 이 시험이 고정하는 사실 중 둘은 「옳다」가 아니라 「지금 그렇다」다
+ *
+ *  ① **선언이 없으면 통과한다** — 게이트가 opt-in 이라는 뜻이고, 지시자를 잊은 리졸버는
+ *    조용히 열린다(무선언 mutation 509개). 「닫힘을 기본으로」는 결정 대기 사항이다.
+ *  ② **unsafeIP + 이름 없는 선언**의 규칙이 뒤집혀 있다 — 안전하지 않은 IP 에서 *더* 열린다.
+ *    아래 해당 케이스에 그 자리를 표시해 두었다. 정책이 정해지면 시험을 먼저 바꾼다.
+ *
+ * 두 사실은 정책 결정(`docs/design/auth-rebuild.md` §1 · §7)이 나오기 전에는 바꾸지 않는다.
+ * 시험이 지금 거동을 붙잡고 있으므로, 바꿀 때 무엇이 달라지는지 보인다.
+ */
+
+import { loadCompiled } from './compiled'
+
+const { checkPermission } = loadCompiled('utils/check-permission')
+const { User } = loadCompiled('service/user/user')
+
+const DOMAIN = { id: 'domain-1', subdomain: 'plant-a' } as any
+const USER = { id: 'user-1', domains: [DOMAIN] } as any
+
+/** 역할 기반 판정(`User.hasPrivilege`)은 DB 를 본다 — 판정 규칙만 보려고 그 답을 고정한다. */
+function withRolePrivilege(answer: boolean) {
+  User.hasPrivilege = jest.fn().mockResolvedValue(answer)
+  return User.hasPrivilege
+}
+
+/**
+ * 소유권 판정은 `process` 에 실린다(`domain-authenticate-middleware` 가 설치한다).
+ * 게이트가 **자기 안에 없는 것에 의존**한다는 사실 자체가 아래 마지막 케이스의 주제다.
+ */
+function withOwnership({ owner = false, superUser = false } = {}) {
+  ;(process as any).domainOwnerGranted = jest.fn().mockResolvedValue(owner)
+  ;(process as any).superUserGranted = jest.fn().mockResolvedValue(superUser)
+}
+
+beforeEach(() => {
+  withOwnership()
+  withRolePrivilege(false)
+})
+
+afterEach(() => {
+  delete (process as any).domainOwnerGranted
+  delete (process as any).superUserGranted
+})
+
+describe('선언이 없는 자리', () => {
+  it('선언이 없으면 통과한다 — 게이트는 opt-in 이다', async () => {
+    for (const nothing of [undefined, null]) {
+      expect(await checkPermission(nothing, USER, DOMAIN)).toBe(true)
+    }
+  })
+
+  it('사용자도 도메인도 없어도 통과한다 — 선언이 없으면 아무것도 보지 않는다', async () => {
+    expect(await checkPermission(undefined, undefined, undefined)).toBe(true)
+  })
+})
+
+describe('이름이 있는 권한 (category + privilege)', () => {
+  const NAMED = { category: 'board', privilege: 'mutation' }
+
+  it('역할이 그 권한을 가지면 통과한다', async () => {
+    const hasPrivilege = withRolePrivilege(true)
+
+    expect(await checkPermission(NAMED, USER, DOMAIN)).toBe(true)
+    expect(hasPrivilege).toHaveBeenCalledWith('mutation', 'board', DOMAIN, USER)
+  })
+
+  it('역할이 없으면 거절한다', async () => {
+    expect(await checkPermission(NAMED, USER, DOMAIN)).toBe(false)
+  })
+
+  it('소유권이 선언되지 않았으면 소유자여도 역할로만 판정한다', async () => {
+    withOwnership({ owner: true, superUser: true })
+
+    /* 선언에 owner/super 가 없다 — 우회는 **선언한 자리에서만** 일어난다. */
+    expect(await checkPermission(NAMED, USER, DOMAIN)).toBe(false)
+  })
+})
+
+describe('소유권 우회 (domainOwnerGranted / superUserGranted)', () => {
+  const OWNER_GRANTED = { category: 'board', privilege: 'mutation', owner: true }
+  const SUPER_GRANTED = { category: 'board', privilege: 'mutation', super: true }
+
+  it('도메인 소유자는 역할 없이 통과한다', async () => {
+    withOwnership({ owner: true })
+    const hasPrivilege = withRolePrivilege(false)
+
+    expect(await checkPermission(OWNER_GRANTED, USER, DOMAIN)).toBe(true)
+    /* 역할은 아예 보지 않는다 — 그래서 admin 계정으로는 거절 경로를 볼 수 없다. */
+    expect(hasPrivilege).not.toHaveBeenCalled()
+  })
+
+  it('수퍼유저는 역할 없이 통과한다', async () => {
+    withOwnership({ superUser: true })
+
+    expect(await checkPermission(SUPER_GRANTED, USER, DOMAIN)).toBe(true)
+  })
+
+  it('선언이 owner 만인데 수퍼유저이면 우회하지 않는다', async () => {
+    withOwnership({ superUser: true })
+
+    expect(await checkPermission(OWNER_GRANTED, USER, DOMAIN)).toBe(false)
+  })
+})
+
+describe('이름이 없는 선언 — 소유권만으로 판정한다', () => {
+  it('소유권만 선언한 자리는 소유자에게 열린다', async () => {
+    withOwnership({ owner: true })
+
+    expect(await checkPermission({ owner: true }, USER, DOMAIN)).toBe(true)
+  })
+
+  it('소유자가 아니면 닫힌다 — 다만 돌려주는 값이 `false` 가 아니라 `undefined` 다', async () => {
+    /* 선언한 타입은 `Promise<boolean>` 인데 실제로는 `(true && false) || (undefined && …)`
+       = `undefined` 가 나온다. 지금 모든 소비처가 `if (await checkPermission(…))` 로 받으므로
+       거동은 같다 — 그러나 시그니처가 사실과 다르고, `=== false` 로 받는 소비처가 하나
+       생기는 순간 조용히 통과한다. 그래서 값 자체를 고정한다. */
+    const decision = await checkPermission({ owner: true }, USER, DOMAIN)
+
+    expect(decision).toBeFalsy()
+    expect(decision).toBeUndefined()
+  })
+
+  it('아무것도 선언하지 않은 빈 선언은 닫힌다', async () => {
+    /* `{}` 는 `!privilegeObject` 가 아니므로 첫 관문을 통과하고, 여기서 falsy 로 떨어진다.
+       같은 `{}` 가 unsafeIP 에서는 **열린다** — 아래 unsafeIP 절이 그 비대칭을 붙잡는다. */
+    expect(await checkPermission({}, USER, DOMAIN)).toBeFalsy()
+  })
+})
+
+describe('금지 목록 (prohibitedPrivileges)', () => {
+  const NAMED = { category: 'board', privilege: 'mutation' }
+  const PROHIBITED = [{ category: 'board', privilege: 'mutation' }]
+
+  it('금지된 권한은 역할이 있어도 거절한다', async () => {
+    withRolePrivilege(true)
+
+    expect(await checkPermission(NAMED, USER, DOMAIN, false, PROHIBITED)).toBe(false)
+  })
+
+  it('다른 권한의 금지는 영향이 없다', async () => {
+    withRolePrivilege(true)
+
+    expect(
+      await checkPermission(NAMED, USER, DOMAIN, false, [{ category: 'board', privilege: 'query' }])
+    ).toBe(true)
+  })
+
+  it('소유권 우회가 금지 목록보다 먼저 판정된다 — 금지 목록은 소유자를 막지 못한다', async () => {
+    withOwnership({ owner: true })
+
+    expect(
+      await checkPermission({ ...NAMED, owner: true }, USER, DOMAIN, false, PROHIBITED)
+    ).toBe(true)
+  })
+})
+
+describe('안전하지 않은 IP (unsafeIP)', () => {
+  const NAMED = { category: 'board', privilege: 'mutation' }
+
+  it('이름이 있는 권한은 소유권을 무시하고 역할로만 판정한다', async () => {
+    withOwnership({ owner: true, superUser: true })
+    withRolePrivilege(false)
+
+    expect(await checkPermission({ ...NAMED, owner: true, super: true }, USER, DOMAIN, true)).toBe(false)
+  })
+
+  it('역할이 있으면 안전하지 않은 IP 에서도 통과한다', async () => {
+    withRolePrivilege(true)
+
+    expect(await checkPermission(NAMED, USER, DOMAIN, true)).toBe(true)
+  })
+
+  it('금지 목록은 안전하지 않은 IP 에서 그대로 적용된다', async () => {
+    withRolePrivilege(true)
+
+    expect(
+      await checkPermission(NAMED, USER, DOMAIN, true, [{ category: 'board', privilege: 'mutation' }])
+    ).toBe(false)
+  })
+
+  /*
+   * ── 여기서부터가 뒤집힌 자리다 ─────────────────────────────────────────────
+   * 규칙은 `return !domainOwnerGranted && !superUserGranted` (check-permission.ts:29).
+   * 주석은 「unsafeIP 상황에서는 ownership granted 는 적용되지 않는다」고 적혀 있는데,
+   * 「적용하지 않는다」의 결과가 **거절**이 아니라 **선언을 뒤집은 값**이다.
+   * 아래 두 케이스는 그 결과를 그대로 고정한다 — 정책(§7)이 정해지면 시험을 먼저 바꾼다.
+   */
+  it('[뒤집힘] 소유권을 선언한 자리는 안전하지 않은 IP 에서 닫힌다', async () => {
+    withOwnership({ owner: true })
+
+    expect(await checkPermission({ owner: true }, USER, DOMAIN, true)).toBe(false)
+  })
+
+  it('[뒤집힘] 아무것도 선언하지 않은 빈 선언은 안전하지 않은 IP 에서 오히려 열린다', async () => {
+    /* 안전한 IP 에서는 같은 `{}` 가 닫힌다. 「없음」 기본값이 안전하지 않은 쪽으로 기운다. */
+    expect(await checkPermission({}, USER, DOMAIN, true)).toBe(true)
+    expect(await checkPermission({}, USER, DOMAIN, false)).toBeFalsy()
+  })
+})
+
+describe('게이트가 자기 밖에 의존하는 것', () => {
+  it('소유권 판정자가 설치되지 않은 경로에서 부르면 던진다', async () => {
+    delete (process as any).domainOwnerGranted
+
+    /* `domain-authenticate-middleware` 가 `process` 에 심는다. 미들웨어를 타지 않는
+       호출 경로(작업 스케줄러·구독 밖 내부 호출)에서 소유권을 선언한 자리를 판정하면
+       판정이 아니라 예외가 된다. */
+    await expect(checkPermission({ owner: true }, USER, DOMAIN)).rejects.toThrow()
+  })
+
+  it('소유권을 선언하지 않은 자리는 판정자가 없어도 동작한다', async () => {
+    delete (process as any).domainOwnerGranted
+    delete (process as any).superUserGranted
+    withRolePrivilege(true)
+
+    expect(await checkPermission({ category: 'board', privilege: 'mutation' }, USER, DOMAIN)).toBe(true)
+  })
+})

package/tests/privilege-directive.test.ts

@@ -0,0 +1,270 @@
+/**
+ * `@privilege` 지시자 — **이음매** 시험.
+ *
+ * `permission-gate.test.ts` 는 판정 규칙을 본다. 그런데 규칙이 옳아도 **부르는 자리**가 틀리면
+ * 화면은 열린다. 그 자리가 이 지시자다: 스키마의 모든 필드를 훑어 게이트를 감싸고, 거절을
+ * `extensions` 와 함께 던진다. 지시자 안에 인라인으로 있던 문장 만들기는 이미 떼어냈는데
+ * (`privilege-rejection.ts`), **감싸는 행위 자체**에는 시험이 없었다.
+ *
+ * 그래서 여기서는 실제로 스키마를 짓고 쿼리를 태운다. type-graphql 리졸버는 jest 에서 들 수
+ * 없으므로(tests/compiled.ts) SDL 로 같은 모양을 만든다 — 지시자가 보는 것은 필드 설정과
+ * `context.state` 뿐이므로 판정 경로는 동일하다.
+ */
+
+import { graphql } from 'graphql'
+import { makeExecutableSchema } from '@graphql-tools/schema'
+import { logger } from '@things-factory/env'
+
+import { loadCompiled } from './compiled'
+
+const { privilegeDirectiveTypeDefs, privilegeDirectiveResolver } = loadCompiled(
+  'service/privilege/privilege-directive'
+)
+const { User } = loadCompiled('service/user/user')
+
+const DOMAIN = { id: 'domain-1', subdomain: 'plant-a' }
+const USER = { id: 'user-1', domains: [DOMAIN] }
+
+/**
+ * 지시자가 붙은 필드와 붙지 않은 필드를 나란히 둔다 — 이 대비가 「기본값이 열려 있다」를
+ * 눈으로 보여 준다.
+ */
+const typeDefs = `
+  type Query {
+    guardedBoard: String @privilege(category: "board", privilege: "mutation")
+    ownershipOnly: String @privilege(domainOwnerGranted: true)
+    undeclared: String
+    moved: String @privilege(category: "ai-assistant", privilege: "mutation", legacy: "board-ai")
+  }
+`
+
+function buildSchema() {
+  const schema = makeExecutableSchema({
+    typeDefs: [privilegeDirectiveTypeDefs, typeDefs],
+    resolvers: {
+      Query: {
+        guardedBoard: () => 'board',
+        ownershipOnly: () => 'ownership',
+        undeclared: () => 'undeclared',
+        moved: () => 'moved'
+      }
+    }
+  })
+
+  return privilegeDirectiveResolver(schema)
+}
+
+/** 이 category 들만 가진 사람. `hasPrivilege(privilege, category, ...)` 순서를 그대로 받는다. */
+function granted(...categories: string[]) {
+  User.hasPrivilege = jest.fn().mockImplementation(async (_privilege: string, category: string) =>
+    categories.includes(category)
+  )
+}
+
+function run(schema: any, field: string, state: any = {}) {
+  return graphql({
+    schema,
+    source: `{ ${field} }`,
+    contextValue: { state: { domain: DOMAIN, user: USER, ...state } }
+  })
+}
+
+function withOwnership({ owner = false, superUser = false } = {}) {
+  ;(process as any).domainOwnerGranted = jest.fn().mockResolvedValue(owner)
+  ;(process as any).superUserGranted = jest.fn().mockResolvedValue(superUser)
+}
+
+beforeEach(() => {
+  withOwnership()
+  User.hasPrivilege = jest.fn().mockResolvedValue(false)
+})
+
+afterEach(() => {
+  delete (process as any).domainOwnerGranted
+  delete (process as any).superUserGranted
+})
+
+describe('선언하지 않은 필드', () => {
+  it('아무 권한 없이 열린다 — 지시자를 잊으면 게이트가 없다', async () => {
+    const result = await run(buildSchema(), 'undeclared')
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ undeclared: 'undeclared' })
+  })
+
+  it('사용자가 없어도 열린다 — 게이트가 아예 감싸지지 않았다', async () => {
+    const result = await run(buildSchema(), 'undeclared', { user: undefined })
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ undeclared: 'undeclared' })
+  })
+})
+
+describe('선언한 필드', () => {
+  it('역할이 있으면 값을 준다', async () => {
+    User.hasPrivilege = jest.fn().mockResolvedValue(true)
+
+    const result = await run(buildSchema(), 'guardedBoard')
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ guardedBoard: 'board' })
+  })
+
+  it('역할이 없으면 값을 주지 않고 거절한다', async () => {
+    const result = await run(buildSchema(), 'guardedBoard')
+
+    expect(result.data).toEqual({ guardedBoard: null })
+    expect(result.errors).toHaveLength(1)
+  })
+
+  it('거절에 무엇이 필요했는지를 구조로 싣는다 — 화면이 문장을 파싱하지 않는다', async () => {
+    const result = await run(buildSchema(), 'guardedBoard')
+    const { code, requires } = result.errors![0].extensions as any
+
+    expect(code).toBe('FORBIDDEN')
+    expect(requires).toEqual({ category: 'board', privilege: 'mutation' })
+  })
+
+  it('요청의 언어로 거절한다', async () => {
+    const schema = buildSchema()
+    const result = await graphql({
+      schema,
+      source: '{ guardedBoard }',
+      contextValue: {
+        state: { domain: DOMAIN, user: USER },
+        t: (key: string, params: any) => `${params.x} 권한이 필요합니다.`
+      }
+    })
+
+    expect(result.errors![0].message).toBe('board:mutation 권한이 필요합니다.')
+  })
+})
+
+describe('소유권만 선언한 필드', () => {
+  it('소유자에게 열린다', async () => {
+    withOwnership({ owner: true })
+
+    const result = await run(buildSchema(), 'ownershipOnly')
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ ownershipOnly: 'ownership' })
+  })
+
+  it('소유자가 아니면 거절하고, 필요한 것을 `ownership` 으로 말한다', async () => {
+    const result = await run(buildSchema(), 'ownershipOnly')
+
+    expect(result.errors).toHaveLength(1)
+    expect((result.errors![0].extensions as any).requires).toBe('ownership')
+  })
+})
+
+describe('안전하지 않은 IP 가 이음매를 지나 게이트까지 간다', () => {
+  it('금지 목록이 실려 판정을 바꾼다', async () => {
+    User.hasPrivilege = jest.fn().mockResolvedValue(true)
+
+    const allowed = await run(buildSchema(), 'guardedBoard', { unsafeIP: true })
+    expect(allowed.errors).toBeUndefined()
+
+    const prohibited = await run(buildSchema(), 'guardedBoard', {
+      unsafeIP: true,
+      prohibitedPrivileges: [{ category: 'board', privilege: 'mutation' }]
+    })
+    expect(prohibited.errors).toHaveLength(1)
+  })
+})
+
+/**
+ * 권한 이름을 옮기는 중.
+ *
+ * 옛 이름을 받아 주지 않으면 옮긴 그날 그 기능을 쓰던 사람들이 전부 막힌다. 그런데 옛 부여를
+ * 역할 행에 베껴 넣으면 조용히 권한이 번지고 되돌릴 근거가 없어진다. 그래서 **행은 그대로 두고
+ * 문에서 한동안 받아 준다.**
+ */
+describe('옮기는 중인 권한', () => {
+  it('새 이름을 가졌으면 열린다', async () => {
+    granted('ai-assistant')
+
+    const result = await run(buildSchema(), 'moved')
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ moved: 'moved' })
+  })
+
+  it('새 이름이 없고 옛 이름만 있어도 열린다 — 옮긴 날 아무도 막히지 않는다', async () => {
+    granted('board-ai')
+
+    const result = await run(buildSchema(), 'moved')
+
+    expect(result.errors).toBeUndefined()
+    expect(result.data).toEqual({ moved: 'moved' })
+  })
+
+  it('둘 다 없으면 거절하고, 필요한 것은 새 이름으로 말한다', async () => {
+    granted()
+
+    const result = await run(buildSchema(), 'moved')
+
+    expect(result.data).toEqual({ moved: null })
+    expect(result.errors).toHaveLength(1)
+    /* 옛 이름을 말하면 관리자가 곧 사라질 권한을 부여한다. */
+    expect((result.errors![0].extensions as any).requires).toEqual({
+      category: 'ai-assistant',
+      privilege: 'mutation'
+    })
+  })
+
+  it('금지 목록이 새 쌍을 막고 있으면 옛 이름으로도 열리지 않는다', async () => {
+    /*
+     * 금지 목록은 옛 이름을 모른다. 별칭이 금지를 되돌리면 「이 IP 에서는 이것을 못 한다」는
+     * 설정이 조용히 무력해진다.
+     */
+    granted('board-ai')
+
+    const result = await run(buildSchema(), 'moved', {
+      unsafeIP: true,
+      prohibitedPrivileges: [{ category: 'ai-assistant', privilege: 'mutation' }]
+    })
+
+    expect(result.errors).toHaveLength(1)
+  })
+
+  it('옛 이름을 부른 것을 로그에 남긴다 — 누가 기대고 있는지가 부여의 근거다', async () => {
+    granted('board-ai')
+
+    const warn = jest.spyOn(logger, 'warn')
+
+    await run(buildSchema(), 'moved')
+
+    expect(warn).toHaveBeenCalled()
+    expect(warn.mock.calls[0][0]).toContain('board-ai:mutation')
+    warn.mockRestore()
+  })
+})
+
+describe('스키마를 지으면서 남기는 것', () => {
+  it('선언한 (category, privilege) 를 전역 레지스트리에 등록한다', () => {
+    /* 부팅 때 없는 권한 행을 만드는 근거다 — 마이그레이션도 수동 생성도 필요 없다. */
+    buildSchema()
+
+    expect((process as any).PRIVILEGES['board mutation']).toEqual(['board', 'mutation'])
+  })
+
+  it('옛 이름은 등록하지 않는다 — 그래서 옛 권한 행이 유령으로 보인다', () => {
+    /*
+     * `isDeprecatedPrivilege` 는 「레지스트리에 없으면 유령」으로 판정한다
+     * (`privilege-deprecation.ts`). 옛 쌍을 등록하면 관리자 목록에서 옛 행이 정상으로 보여
+     * **별칭을 지울 시점을 아무도 못 본다.** 이 시험이 그 신호를 지킨다.
+     */
+    buildSchema()
+
+    expect((process as any).PRIVILEGES['ai-assistant mutation']).toEqual(['ai-assistant', 'mutation'])
+    expect((process as any).PRIVILEGES['board-ai mutation']).toBeUndefined()
+  })
+
+  it('필드 설명에 필요한 권한을 적어 둔다', async () => {
+    const schema = buildSchema()
+    const description = (schema.getQueryType() as any).getFields().guardedBoard.description
+
+    expect(description).toContain('board:mutation')
+  })
+})