@things-factory/auth-base 10.1.7 → 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.7",
+  "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.7",
+    "@things-factory/email-base": "^10.1.16",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.7",
+    "@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": "9a036f83f5751f9e4af9180e9a0018f716a4ba27"
+  "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

@@ -178,3 +178,82 @@ describe('스키마를 지으면서 남기는 것', () => {
     expect(description).toContain('board:mutation')
   })
 })
+
+/*
+ * ── 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' } }
+    })
+
+    return () => privilegeDirectiveResolver(schema)
+  }
+
+  it('refuses an empty declaration, and names the field', () => {
+    expect(buildField('@privilege')).toThrow(/Query\.field declares nothing/)
+  })
+
+  it('tells the writer what the two real shapes are', () => {
+    expect(buildField('@privilege')).toThrow(/domainOwnerGranted/)
+    expect(buildField('@privilege')).toThrow(/carries no directive at all/)
+  })
+
+  it('refuses a category with no privilege', () => {
+    expect(buildField('@privilege(category: "board")')).toThrow(/a category with no privilege/)
+  })
+
+  it('refuses a privilege with no category', () => {
+    expect(buildField('@privilege(privilege: "mutation")')).toThrow(/a privilege with no category/)
+  })
+
+  /*
+   * ── 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/
+    )
+  })
+
+  it('tells the reader what is declared and where to declare more', () => {
+    const build = buildField('@privilege(category: "board", privilege: "approve")')
+
+    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/)
+  })
+
+  it('accepts an axis once the installation declares it', () => {
+    const { declareAxes } = loadCompiled('service/privilege/privilege-axis')
+
+    expect(buildField('@privilege(category: "kpi", privilege: "read")')).toThrow()
+
+    declareAxes(['query', 'mutation', 'read'])
+
+    expect(buildField('@privilege(category: "kpi", privilege: "read")')).not.toThrow()
+  })
+
+  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()
+  })
+})

package/tests/role-template.test.ts

@@ -17,7 +17,11 @@ const {
   unknownTemplateGrants
 } = loadCompiled('service/role-template/role-template')
 
+const { declareAxes } = loadCompiled('service/privilege/privilege-axis')
+
 beforeEach(() => {
+  /* Nobody declared, so the defaults apply — query/mutation with query read-only. */
+  delete (process as any).PRIVILEGE_AXES
   ;(process as any)['ROLE_TEMPLATES'] = {}
   ;(process as any).PRIVILEGES = {
     'board query': ['board', 'query'],
@@ -118,6 +122,38 @@ describe('the two templates the framework computes', () => {
     expect(viewer.grants.find(grant => grant.category === 'board')!.axes).toEqual(['query'])
   })
 
+  it('builds the viewer from the declared read-only axes, not from the word "query"', () => {
+    /*
+     * A house that spells its read axis `read` gets a viewer over `read`. Matching the literal
+     * `query` was right here and wrong there — dssp's `kpi` has eight axes and none of them is
+     * `query`, so its main module would have gone missing from VIEWER without a word anywhere.
+     */
+    declareAxes(['read', 'input'], { readOnly: ['read'] })
+    ;(process as any).PRIVILEGES = {
+      'kpi read': ['kpi', 'read'],
+      'kpi input': ['kpi', 'input']
+    }
+
+    const viewer = computedRoleTemplates().find(one => one.id === 'framework.viewer')!
+
+    expect(viewer.grants).toEqual([{ category: 'kpi', axes: ['read'] }])
+  })
+
+  it('does not offer a viewer at all when nobody said which axes are read-only', () => {
+    /*
+     * ⚠ The point of this one. Offering an empty VIEWER would let an administrator pick it,
+     * get a role, and open nothing — and the role list would count that zero correctly and
+     * present it as fact. "We do not know" is not "there are none", so the template is
+     * withheld and `reportDeclaredAxes` says so at boot.
+     */
+    declareAxes(['read', 'input'])
+
+    const ids = computedRoleTemplates().map(one => one.id)
+
+    expect(ids).toEqual(['framework.administrator'])
+    expect(ids).not.toContain('framework.viewer')
+  })
+
   it('offers the computed two alongside whatever applications declared', () => {
     registerRoleTemplate({ id: 'plant.z', name: 'Z', grants: [] })