@things-factory/auth-base 10.1.6 → 10.1.16

package/dist-server/utils/check-permission.js

@@ -15,8 +15,17 @@ async function checkPermission(privilegeObject, user, domain, unsafeIP, prohibit
             }
             return await user_js_1.User.hasPrivilege(privilege, category, domain, user);
         }
-        // privilege, category가 설정되지 않은 경우에는 ownership granted가 설정되었다면 허가하지 않는다.
-        return !domainOwnerGranted && !superUserGranted;
+        /*
+         * Ownership does not count from an unsafe address, so a declaration that rests on
+         * ownership alone has nothing left to stand on here and the answer is no.
+         *
+         * This read `!domainOwnerGranted && !superUserGranted` until 2026-09-15, which answered
+         * **yes** for an object that named nothing at all — the same `{}` a safe address
+         * refused. An unsafe address was the more permissive of the two, which is backwards.
+         * `privilege-directive.ts` now refuses to build a declaration that names nothing, but
+         * this function is exported and called directly, so the rule is fixed here too.
+         */
+        return false;
     }
     else {
         if (!privilege || !category) {

package/dist-server/utils/check-permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"check-permission.js","sourceRoot":"","sources":["../../server/utils/check-permission.ts"],"names":[],"mappings":";;AAIA,0CA+CC;AAjDD,qDAA8C;AAEvC,KAAK,UAAU,eAAe,CACnC,eAAgC,EAChC,IAAU,EACV,MAAc,EACd,QAAkB,EAClB,oBAAgE;IAEhE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,eAAe,CAAA;IAEnG,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,8CAA8C;YAC9C,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;gBAClG,OAAO,KAAK,CAAA;YACd,CAAC;YAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;QACnE,CAAC;QAED,wEAAwE;QACxE,OAAO,CAAC,kBAAkB,IAAI,CAAC,gBAAgB,CAAA;IACjD,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,8DAA8D;YAC9D,OAAO,CACL,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CACrE,CAAA;QACH,CAAC;QAED,IACE,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EACpE,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;YAClG,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;IACnE,CAAC;AACH,CAAC","sourcesContent":["import { Domain } from '@things-factory/shell'\nimport { PrivilegeObject } from '../service/privilege/privilege.js'\nimport { User } from '../service/user/user.js'\n\nexport async function checkPermission(\n  privilegeObject: PrivilegeObject,\n  user: User,\n  domain: Domain,\n  unsafeIP?: boolean,\n  prohibitedPrivileges?: { category: string; privilege: string }[]\n): Promise<boolean> {\n  if (!privilegeObject) {\n    return true\n  }\n\n  const { owner: domainOwnerGranted, super: superUserGranted, category, privilege } = privilegeObject\n\n  if (unsafeIP) {\n    if (privilege && category) {\n      // unsafeIP 상황에서는 ownership granted는 적용되지 않는다.\n      if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n        return false\n      }\n\n      return await User.hasPrivilege(privilege, category, domain, user)\n    }\n\n    // privilege, category가 설정되지 않은 경우에는 ownership granted가 설정되었다면 허가하지 않는다.\n    return !domainOwnerGranted && !superUserGranted\n  } else {\n    if (!privilege || !category) {\n      // privilege, category가 설정되지 않은 경우에는 ownership granted만을 적용한다.\n      return (\n        (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n        (superUserGranted && (await process.superUserGranted(domain, user)))\n      )\n    }\n\n    if (\n      (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n      (superUserGranted && (await process.superUserGranted(domain, user)))\n    ) {\n      return true\n    }\n\n    if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n      return false\n    }\n\n    return await User.hasPrivilege(privilege, category, domain, user)\n  }\n}\n"]}
+{"version":3,"file":"check-permission.js","sourceRoot":"","sources":["../../server/utils/check-permission.ts"],"names":[],"mappings":";;AAIA,0CAwDC;AA1DD,qDAA8C;AAEvC,KAAK,UAAU,eAAe,CACnC,eAAgC,EAChC,IAAU,EACV,MAAc,EACd,QAAkB,EAClB,oBAAgE;IAEhE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,eAAe,CAAA;IAEnG,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,8CAA8C;YAC9C,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;gBAClG,OAAO,KAAK,CAAA;YACd,CAAC;YAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;QACnE,CAAC;QAED;;;;;;;;;WASG;QACH,OAAO,KAAK,CAAA;IACd,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,8DAA8D;YAC9D,OAAO,CACL,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CACrE,CAAA;QACH,CAAC;QAED,IACE,CAAC,kBAAkB,IAAI,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YACxE,CAAC,gBAAgB,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EACpE,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAC,SAAS,IAAI,SAAS,CAAC,EAAE,CAAC;YAClG,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,MAAM,cAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;IACnE,CAAC;AACH,CAAC","sourcesContent":["import { Domain } from '@things-factory/shell'\nimport { PrivilegeObject } from '../service/privilege/privilege.js'\nimport { User } from '../service/user/user.js'\n\nexport async function checkPermission(\n  privilegeObject: PrivilegeObject,\n  user: User,\n  domain: Domain,\n  unsafeIP?: boolean,\n  prohibitedPrivileges?: { category: string; privilege: string }[]\n): Promise<boolean> {\n  if (!privilegeObject) {\n    return true\n  }\n\n  const { owner: domainOwnerGranted, super: superUserGranted, category, privilege } = privilegeObject\n\n  if (unsafeIP) {\n    if (privilege && category) {\n      // unsafeIP 상황에서는 ownership granted는 적용되지 않는다.\n      if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n        return false\n      }\n\n      return await User.hasPrivilege(privilege, category, domain, user)\n    }\n\n    /*\n     * Ownership does not count from an unsafe address, so a declaration that rests on\n     * ownership alone has nothing left to stand on here and the answer is no.\n     *\n     * This read `!domainOwnerGranted && !superUserGranted` until 2026-09-15, which answered\n     * **yes** for an object that named nothing at all — the same `{}` a safe address\n     * refused. An unsafe address was the more permissive of the two, which is backwards.\n     * `privilege-directive.ts` now refuses to build a declaration that names nothing, but\n     * this function is exported and called directly, so the rule is fixed here too.\n     */\n    return false\n  } else {\n    if (!privilege || !category) {\n      // privilege, category가 설정되지 않은 경우에는 ownership granted만을 적용한다.\n      return (\n        (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n        (superUserGranted && (await process.superUserGranted(domain, user)))\n      )\n    }\n\n    if (\n      (domainOwnerGranted && (await process.domainOwnerGranted(domain, user))) ||\n      (superUserGranted && (await process.superUserGranted(domain, user)))\n    ) {\n      return true\n    }\n\n    if ((prohibitedPrivileges || []).find(pp => pp.category == category && pp.privilege == privilege)) {\n      return false\n    }\n\n    return await User.hasPrivilege(privilege, category, domain, user)\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/auth-base",
-  "version": "10.1.6",
+  "version": "10.1.16",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -34,9 +34,9 @@
     "@reduxjs/toolkit": "^2.2.5",
     "@simplewebauthn/browser": "^13.0.0",
     "@simplewebauthn/server": "^13.0.0",
-    "@things-factory/email-base": "^10.1.4",
+    "@things-factory/email-base": "^10.1.16",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.4",
+    "@things-factory/shell": "^10.1.16",
     "@things-factory/utils": "^10.1.3",
     "@types/webappsec-credential-management": "^0.6.9",
     "jsonwebtoken": "^9.0.0",
@@ -48,5 +48,5 @@
     "passport-jwt": "^4.0.0",
     "passport-local": "^1.0.0"
   },
-  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
+  "gitHead": "aff86bc162b42c1d933711f7bc85a073f1ddcd29"
 }

package/tests/domain-inheritance-sentinel.test.ts

@@ -0,0 +1,93 @@
+/**
+ * What `inherited: Only` binds when the domain has no parent.
+ *
+ * ── What was here until 2026-09-15 ───────────────────────────────────────────
+ *     qb.andWhere(`${alias}.domain = :domain`, { domain: domain.parentId || 'Impossible' })
+ *
+ * "Match nothing" is the right intent — a root domain inherits from nobody — but it was
+ * spelled as a **value** bound to a uuid column. sqlite compares it as text and returns zero
+ * rows, which is the intended answer arrived at by accident, so it was green through three
+ * years of development. postgres parses it and refuses the whole query:
+ *
+ *     invalid input syntax for type uuid: "Impossible"   (observed 2026-09-15, path ["roles"])
+ *
+ * ── Why this test is written against the parameters, not the rows ────────────
+ * This harness is sqlite and cannot fail the way the server does; `tests/db.ts` says as much
+ * about column dialects. So it reads what TypeORM is about to **send** instead of what comes
+ * back. The defect lived in what we build, and what we build is the same on every driver —
+ * which makes this the way to reach the whole class our sqlite development cannot see.
+ */
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { Role } = loadCompiled('service/role/role')
+
+const shell = require('@things-factory/shell')
+
+const ROOT = { id: '00000000-0000-4000-8000-000000000001', parentId: null }
+const CHILD = { id: '00000000-0000-4000-8000-000000000002', parentId: ROOT.id }
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+function builderFor(domain: { id: string; parentId: string | null }, inherited: string) {
+  return shell.getQueryBuilderFromListParams({
+    repository: getRepository(Role),
+    params: { filters: [], inherited },
+    domain,
+    searchables: ['name', 'description']
+  })
+}
+
+function parametersFor(domain: { id: string; parentId: string | null }, inherited: string): any[] {
+  return builderFor(domain, inherited).getQueryAndParameters()[1]
+}
+
+function queryFor(domain: { id: string; parentId: string | null }, inherited: string): string {
+  return builderFor(domain, inherited).getQueryAndParameters()[0]
+}
+
+describe('inherited: Only', () => {
+  it('binds the parent id when there is one', () => {
+    expect(parametersFor(CHILD, 'Only')).toContain(ROOT.id)
+  })
+
+  it('binds nothing at all when there is no parent', () => {
+    /*
+     * The sentinel is gone. "A root domain inherits from nobody" is a condition, and it is now
+     * written as one — `1 = 0` — rather than as a value that has to survive a uuid parser.
+     */
+    expect(parametersFor(ROOT, 'Only')).not.toContain('Impossible')
+
+    const sql = queryFor(ROOT, 'Only')
+
+    expect(sql).toContain('1 = 0')
+  })
+
+  it('refuses a value that is not one of the three', () => {
+    /*
+     * An empty result would be read as "nothing matched". This is a tenant isolation filter;
+     * a malfunction here has to be loud, and the enum means no current caller can reach it.
+     */
+    expect(() => parametersFor(ROOT, 'Onyl')).toThrow(/unknown inherited value/)
+  })
+
+  it('binds nothing that is not a uuid for the other two scopes', () => {
+    /* None and Include are fine, which is why this went unnoticed: two of three scopes work. */
+    const uuidish = /^[0-9a-f-]{36}$/i
+
+    for (const scope of ['None', 'Include']) {
+      for (const parameter of parametersFor(ROOT, scope)) {
+        if (typeof parameter === 'string') {
+          expect(parameter).toMatch(uuidish)
+        }
+      }
+    }
+  })
+})

package/tests/permission-gate.test.ts

@@ -128,9 +128,11 @@ describe('이름이 없는 선언 — 소유권만으로 판정한다', () => {
     expect(decision).toBeUndefined()
   })
 
-  it('아무것도 선언하지 않은 빈 선언은 닫힌다', async () => {
-    /* `{}` 는 `!privilegeObject` 가 아니므로 첫 관문을 통과하고, 여기서 falsy 로 떨어진다.
-       같은 `{}` 가 unsafeIP 에서는 **열린다** — 아래 unsafeIP 절이 그 비대칭을 붙잡는다. */
+  it('refuses an object that names nothing', async () => {
+    /* `{}` is not `!privilegeObject`, so it passes the first gate and falls out falsy here.
+       The unsafe-address block below asserts the same answer, which is the point: it used to
+       answer the opposite. `privilege-directive.ts` refuses to build this shape at all now,
+       but `checkPermission` is exported and reachable without it. */
     expect(await checkPermission({}, USER, DOMAIN)).toBeFalsy()
   })
 })
@@ -187,21 +189,23 @@ describe('안전하지 않은 IP (unsafeIP)', () => {
   })
 
   /*
-   * ── 여기서부터가 뒤집힌 자리다 ─────────────────────────────────────────────
-   * 규칙은 `return !domainOwnerGranted && !superUserGranted` (check-permission.ts:29).
-   * 주석은 「unsafeIP 상황에서는 ownership granted 는 적용되지 않는다」고 적혀 있는데,
-   * 「적용하지 않는다」의 결과가 **거절**이 아니라 **선언을 뒤집은 값**이다.
-   * 아래 두 케이스는 그 결과를 그대로 고정한다 — 정책(§7)이 정해지면 시험을 먼저 바꾼다.
+   * ── An unsafe address is never the more permissive of the two ────────────────
+   * These two were marked 뒤집힘 and pinned the opposite answer until 2026-09-15. The rule
+   * read `return !domainOwnerGranted && !superUserGranted`: "ownership does not apply from an
+   * unsafe address" came out as the declaration inverted rather than as a refusal, so an
+   * object naming nothing opened from an unsafe address and closed from a safe one.
+   *
+   * The architect found the same asymmetry from the other side on 2026-09-15, looking at what
+   * a field would do if someone wrote `@privilege()` wanting "signed in is enough".
    */
-  it('[뒤집힘] 소유권을 선언한 자리는 안전하지 않은 IP 에서 닫힌다', async () => {
+  it('refuses a declaration resting on ownership alone', 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)
+  it('refuses an object that names nothing, the same as a safe address does', async () => {
+    expect(await checkPermission({}, USER, DOMAIN, true)).toBe(false)
     expect(await checkPermission({}, USER, DOMAIN, false)).toBeFalsy()
   })
 })

package/tests/privilege-axis.test.ts

@@ -0,0 +1,157 @@
+/**
+ * The axis vocabulary — who owns it, and what a value outside it does.
+ *
+ * The framework used to accept any string as an axis. `@privilege(privilege: "mutaiton")`
+ * registered a pair in `process['PRIVILEGES']` that nobody would ever be granted: a gate shut
+ * forever, with nothing anywhere to read. Closing the axis to `query | mutation` in the
+ * framework would have fixed that and broken dssp's 40 declarations, so the owner declares
+ * and the framework asks.
+ */
+
+import { loadCompiled } from './compiled'
+
+const { declareAxes, declaredAxes, isDeclaredAxis, readOnlyAxes, readOnlyAxesAreKnown, DEFAULT_AXES } = loadCompiled(
+  'service/privilege/privilege-axis'
+)
+
+beforeEach(() => {
+  delete (process as any).PRIVILEGE_AXES
+})
+
+afterEach(() => {
+  delete (process as any).PRIVILEGE_AXES
+})
+
+describe('an installation that declares nothing', () => {
+  it('gets query and mutation', () => {
+    expect([...declaredAxes()].sort()).toEqual(['mutation', 'query'])
+    expect(DEFAULT_AXES).toEqual(['query', 'mutation'])
+  })
+
+  it('still refuses a value outside them', () => {
+    /*
+     * The defaults are a vocabulary, not an off switch. An installation that forgot to declare
+     * is the common case, and it is the one that most needs the typo caught.
+     */
+    expect(isDeclaredAxis('query')).toBe(true)
+    expect(isDeclaredAxis('mutaiton')).toBe(false)
+  })
+})
+
+describe('an installation that declares its own words', () => {
+  it('accepts them', () => {
+    declareAxes(['read', 'input', 'finalize'])
+
+    expect(isDeclaredAxis('read')).toBe(true)
+    expect(isDeclaredAxis('finalize')).toBe(true)
+  })
+
+  it('replaces the defaults rather than adding to them', () => {
+    /*
+     * A house that says "my axes are read and input" has said what its axes are. Keeping
+     * query and mutation alongside would let a declaration use a word this installation
+     * does not actually mean, which is the thing being prevented.
+     */
+    declareAxes(['read', 'input'])
+
+    expect(isDeclaredAxis('query')).toBe(false)
+    expect([...declaredAxes()].sort()).toEqual(['input', 'read'])
+  })
+})
+
+describe('more than one module declaring', () => {
+  it('takes the union, because one installation mixes vocabularies', () => {
+    /*
+     * This is dssp: `project` is declared with query/mutation while `kpi` uses eight words of
+     * its own, in the same installation. Each module says what it uses.
+     */
+    declareAxes(['query', 'mutation'])
+    declareAxes(['read', 'assessment'])
+
+    expect([...declaredAxes()].sort()).toEqual(['assessment', 'mutation', 'query', 'read'])
+  })
+
+  it('does not treat the same axis twice as a conflict', () => {
+    /* Two modules reaching for `read` independently is the case this is built for. */
+    declareAxes(['read'])
+    declareAxes(['read'])
+
+    expect([...declaredAxes()]).toEqual(['read'])
+  })
+})
+
+describe('what declareAxes refuses', () => {
+  it('refuses an empty list, which would refuse every declaration', () => {
+    expect(() => declareAxes([])).toThrow(/at least one axis/)
+    expect(() => declareAxes(undefined as any)).toThrow(/at least one axis/)
+  })
+
+  it('refuses a value that is not a word', () => {
+    expect(() => declareAxes([''])).toThrow(/non-empty strings/)
+    expect(() => declareAxes(['  '])).toThrow(/non-empty strings/)
+    expect(() => declareAxes([null as any])).toThrow(/non-empty strings/)
+  })
+
+  it('changes nothing when it refuses', () => {
+    declareAxes(['read'], { readOnly: ['read'] })
+
+    expect(() => declareAxes(['input', ''])).toThrow()
+
+    /*
+     * Every value is checked before any is stored, so a refused call leaves the vocabulary as
+     * it was. An earlier draft added axes as it walked the list and stopped at the bad one,
+     * which left `input` declared by a call that threw.
+     */
+    expect(isDeclaredAxis('input')).toBe(false)
+    expect(isDeclaredAxis('read')).toBe(true)
+  })
+
+  it('refuses a read-only axis that is not in the same call', () => {
+    /*
+     * A typo here is the quietest kind: `readOnly: ['querry']` would mark nothing, VIEWER
+     * would lose every category of this module, and the screen would count the shortfall
+     * correctly and present it as fact.
+     */
+    expect(() => declareAxes(['query', 'mutation'], { readOnly: ['querry'] })).toThrow(/not in the same call/)
+    expect(() => declareAxes(['read'], { readOnly: ['query'] })).toThrow(/Declared here: read/)
+  })
+})
+
+describe('which axes are read-only', () => {
+  it('defaults to query when nobody declared anything', () => {
+    /* The vocabulary and the answer to "which half is safe" travel together. */
+    expect([...readOnlyAxes()]).toEqual(['query'])
+    expect(readOnlyAxesAreKnown()).toBe(true)
+  })
+
+  it('is unknown when a house declared its own words and did not say', () => {
+    declareAxes(['read', 'input', 'finalize'])
+
+    expect(readOnlyAxes().size).toBe(0)
+    expect(readOnlyAxesAreKnown()).toBe(false)
+  })
+
+  it('takes the union across modules, like the axes themselves', () => {
+    declareAxes(['query', 'mutation'], { readOnly: ['query'] })
+    declareAxes(['read', 'finalize'], { readOnly: ['read'] })
+
+    expect([...readOnlyAxes()].sort()).toEqual(['query', 'read'])
+  })
+
+  it('does not mean the operation is a @Query', () => {
+    /*
+     * `exportLabelStudioAnnotations` is declared `@Mutation` and gated on `label-studio:query`
+     * [읽었음 task-management.ts:200-204]. It calls an external API's export and returns what
+     * comes back; nothing in our database moves. The axis is the correct one, and a role
+     * holding only that axis still changes nothing.
+     *
+     * This test carries no assertion about that file — it cannot, from here. It exists so the
+     * next person reading `readOnly` finds the distinction spelled out beside the code rather
+     * than only in a comment they might skip.
+     */
+    declareAxes(['query', 'mutation'], { readOnly: ['query'] })
+
+    expect(readOnlyAxes().has('query')).toBe(true)
+    expect(readOnlyAxes().has('mutation')).toBe(false)
+  })
+})

package/tests/privilege-directive.test.ts

@@ -13,7 +13,6 @@
 
 import { graphql } from 'graphql'
 import { makeExecutableSchema } from '@graphql-tools/schema'
-import { logger } from '@things-factory/env'
 
 import { loadCompiled } from './compiled'
 
@@ -34,7 +33,6 @@ const typeDefs = `
     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")
   }
 `
 
@@ -45,8 +43,7 @@ function buildSchema() {
       Query: {
         guardedBoard: () => 'board',
         ownershipOnly: () => 'ownership',
-        undeclared: () => 'undeclared',
-        moved: () => 'moved'
+        undeclared: () => 'undeclared'
       }
     }
   })
@@ -54,13 +51,6 @@ function buildSchema() {
   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,
@@ -173,98 +163,97 @@ describe('안전하지 않은 IP 가 이음매를 지나 게이트까지 간다'
   })
 })
 
-/**
- * 권한 이름을 옮기는 중.
- *
- * 옛 이름을 받아 주지 않으면 옮긴 그날 그 기능을 쓰던 사람들이 전부 막힌다. 그런데 옛 부여를
- * 역할 행에 베껴 넣으면 조용히 권한이 번지고 되돌릴 근거가 없어진다. 그래서 **행은 그대로 두고
- * 문에서 한동안 받아 준다.**
- */
-describe('옮기는 중인 권한', () => {
-  it('새 이름을 가졌으면 열린다', async () => {
-    granted('ai-assistant')
-
-    const result = await run(buildSchema(), 'moved')
+describe('스키마를 지으면서 남기는 것', () => {
+  it('선언한 (category, privilege) 를 전역 레지스트리에 등록한다', () => {
+    /* 부팅 때 없는 권한 행을 만드는 근거다 — 마이그레이션도 수동 생성도 필요 없다. */
+    buildSchema()
 
-    expect(result.errors).toBeUndefined()
-    expect(result.data).toEqual({ moved: 'moved' })
+    expect((process as any).PRIVILEGES['board mutation']).toEqual(['board', 'mutation'])
   })
 
-  it('새 이름이 없고 옛 이름만 있어도 열린다 — 옮긴 날 아무도 막히지 않는다', async () => {
-    granted('board-ai')
-
-    const result = await run(buildSchema(), 'moved')
+  it('필드 설명에 필요한 권한을 적어 둔다', async () => {
+    const schema = buildSchema()
+    const description = (schema.getQueryType() as any).getFields().guardedBoard.description
 
-    expect(result.errors).toBeUndefined()
-    expect(result.data).toEqual({ moved: 'moved' })
+    expect(description).toContain('board:mutation')
   })
+})
 
-  it('둘 다 없으면 거절하고, 필요한 것은 새 이름으로 말한다', async () => {
-    granted()
+/*
+ * ── A declaration that names nothing stops the boot ───────────────────────────
+ * Schema assembly is the only moment this can be caught. After it, an empty declaration is
+ * indistinguishable from a real one at the call site: the directive is present, the wrapper
+ * runs, and the answer comes back from `checkPermission` with nothing to look up.
+ *
+ * `@privilege()` was the worst of these — it answered by the caller's address, refusing from a
+ * safe one and passing everyone from an unsafe one, so whoever tried it learned the opposite
+ * lesson depending on where they sat (architect, 2026-09-15).
+ *
+ * [확인함] 2026-09-15 · six repositories · zero declarations of either shape, so refusing them
+ * breaks nothing that exists. The throw is for the one someone writes next.
+ */
+describe('a declaration that names nothing', () => {
+  function buildField(declaration: string) {
+    const schema = makeExecutableSchema({
+      typeDefs: [privilegeDirectiveTypeDefs, `type Query { field: String ${declaration} }`],
+      resolvers: { Query: { field: () => 'value' } }
+    })
 
-    const result = await run(buildSchema(), 'moved')
+    return () => privilegeDirectiveResolver(schema)
+  }
 
-    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('refuses an empty declaration, and names the field', () => {
+    expect(buildField('@privilege')).toThrow(/Query\.field declares nothing/)
   })
 
-  it('금지 목록이 새 쌍을 막고 있으면 옛 이름으로도 열리지 않는다', async () => {
-    /*
-     * 금지 목록은 옛 이름을 모른다. 별칭이 금지를 되돌리면 「이 IP 에서는 이것을 못 한다」는
-     * 설정이 조용히 무력해진다.
-     */
-    granted('board-ai')
-
-    const result = await run(buildSchema(), 'moved', {
-      unsafeIP: true,
-      prohibitedPrivileges: [{ category: 'ai-assistant', privilege: 'mutation' }]
-    })
+  it('tells the writer what the two real shapes are', () => {
+    expect(buildField('@privilege')).toThrow(/domainOwnerGranted/)
+    expect(buildField('@privilege')).toThrow(/carries no directive at all/)
+  })
 
-    expect(result.errors).toHaveLength(1)
+  it('refuses a category with no privilege', () => {
+    expect(buildField('@privilege(category: "board")')).toThrow(/a category with no privilege/)
   })
 
-  it('옛 이름을 부른 것을 로그에 남긴다 — 누가 기대고 있는지가 부여의 근거다', async () => {
-    granted('board-ai')
+  it('refuses a privilege with no category', () => {
+    expect(buildField('@privilege(privilege: "mutation")')).toThrow(/a privilege with no category/)
+  })
 
-    const warn = jest.spyOn(logger, 'warn')
+  /*
+   * ── An axis this installation does not declare ──────────────────────────────
+   * A typo used to be the quietest defect in the file. `privilege: "mutaiton"` registered a
+   * pair in `process['PRIVILEGES']` that no role would ever hold — the field was shut to
+   * everyone, permanently, and nothing said so. The framework does not own the word list
+   * (dssp declares eight of its own), so the check asks the installation.
+   */
+  it('refuses an axis outside the declared vocabulary', () => {
+    expect(buildField('@privilege(category: "board", privilege: "mutaiton")')).toThrow(
+      /uses axis "mutaiton", which this installation does not declare/
+    )
+  })
 
-    await run(buildSchema(), 'moved')
+  it('tells the reader what is declared and where to declare more', () => {
+    const build = buildField('@privilege(category: "board", privilege: "approve")')
 
-    expect(warn).toHaveBeenCalled()
-    expect(warn.mock.calls[0][0]).toContain('board-ai:mutation')
-    warn.mockRestore()
+    expect(build).toThrow(/Declared axes: mutation, query/)
+    /* The hook a module would reach for runs after the schema is built, so it must say so. */
+    expect(build).toThrow(/top level of the module's server\/index\.ts/)
+    expect(build).toThrow(/too late/)
   })
-})
 
-describe('스키마를 지으면서 남기는 것', () => {
-  it('선언한 (category, privilege) 를 전역 레지스트리에 등록한다', () => {
-    /* 부팅 때 없는 권한 행을 만드는 근거다 — 마이그레이션도 수동 생성도 필요 없다. */
-    buildSchema()
+  it('accepts an axis once the installation declares it', () => {
+    const { declareAxes } = loadCompiled('service/privilege/privilege-axis')
 
-    expect((process as any).PRIVILEGES['board mutation']).toEqual(['board', 'mutation'])
-  })
+    expect(buildField('@privilege(category: "kpi", privilege: "read")')).toThrow()
 
-  it('옛 이름은 등록하지 않는다 — 그래서 옛 권한 행이 유령으로 보인다', () => {
-    /*
-     * `isDeprecatedPrivilege` 는 「레지스트리에 없으면 유령」으로 판정한다
-     * (`privilege-deprecation.ts`). 옛 쌍을 등록하면 관리자 목록에서 옛 행이 정상으로 보여
-     * **별칭을 지울 시점을 아무도 못 본다.** 이 시험이 그 신호를 지킨다.
-     */
-    buildSchema()
+    declareAxes(['query', 'mutation', 'read'])
 
-    expect((process as any).PRIVILEGES['ai-assistant mutation']).toEqual(['ai-assistant', 'mutation'])
-    expect((process as any).PRIVILEGES['board-ai mutation']).toBeUndefined()
+    expect(buildField('@privilege(category: "kpi", privilege: "read")')).not.toThrow()
   })
 
-  it('필드 설명에 필요한 권한을 적어 둔다', async () => {
-    const schema = buildSchema()
-    const description = (schema.getQueryType() as any).getFields().guardedBoard.description
-
-    expect(description).toContain('board:mutation')
+  it('still builds the two shapes that do name something', () => {
+    expect(buildField('@privilege(category: "board", privilege: "mutation")')).not.toThrow()
+    expect(buildField('@privilege(domainOwnerGranted: true)')).not.toThrow()
+    expect(buildField('@privilege(superUserGranted: true)')).not.toThrow()
   })
 })