Admin 쓰기 관문 강화 — 원장 · 지표 · 감사 기록과 서버 산출 필드 차단 · 마스터 전용 문서 · 거부 기록 · 권한 경계 시험

app/firebase/functions/src/admin/admin.ts

@@ -12,25 +12,85 @@ import { ERR, fail } from '../core/errors.js';
  * 여기서만 남길 수 있고, rbac-summary 가 요구하는 작업 로그가 그것이다.
  */
 
-/** 원장·지갑은 이 경로로 못 쓴다. 재화는 반드시 원장 함수를 지나야 한다. */
+/**
+ * 원장 · 지표 · 감사 기록은 이 경로로 못 쓴다 — **master 도 불가**.
+ * 반드시 원장 · 집계 함수를 지나야 하고, 감사 로그는 고칠 수 없어야 감사 로그다.
+ */
 const FORBIDDEN = [
-  /popTransactions/, /popLots/, /\/wallet\//, /fpiSnapshots/,
+  /popTransactions/, /popLots/, /\/wallet\//, /fpiSnapshots/, /growthEvents/,
+  /\/fpiEvents\//, /\/eclipseRounds\//, /\/fandomDailyStats\//, /^\/?adminActionLogs\//,
 ];
 
+/** 서버 산출 필드 — 문서 자체는 쓸 수 있어도 이 필드는 master 도 못 바꾼다. */
+const DERIVED_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  fandoms: ['fpiScore', 'fpiAxes', 'fpiRanks', 'fpiRanksPrev', 'sfpi', 'growthPop',
+    'rankingEligible', 'eclipsePenaltyRevision'],
+  users: ['userExp', 'userLevel', 'passportTier', 'totalContributedPop'],
+};
+
+/**
+ * 팬덤 문서의 Eclipse 운영값(팬덤별 일정 · 설정, C-24)은 rules 의 `fandoms` 쓰기처럼
+ * master 만 바꾼다. 원장 · 지표는 아니므로 master 에게는 열어 둔다.
+ */
+const MASTER_ONLY_FIELDS: Readonly<Record<string, readonly string[]>> = {
+  fandoms: ['eclipseSettings', 'eclipseSchedule'],
+};
+
+/**
+ * `firestore.rules` 에서 **master 전용 쓰기**인 최상위 컬렉션(rules 「allow write: if isMaster()」).
+ *
+ * 이 함수는 Admin SDK 라 규칙을 거치지 않는다. 여기서 같은 선을 긋지 않으면 ops 가
+ * 재화 정책(`config`) · 퀘스트 · 행성 단계 같은 마스터 전용 문서를 우회해 쓴다.
+ * `configPrivate` 는 규칙상 서버 전용이라 함께 막는다.
+ */
+const MASTER_ONLY = new Set([
+  'config', 'configPrivate', 'appConfig', 'i18n', 'planetStages', 'quests', 'badges',
+]);
+
+/** 거부도 남긴다(FR-ADM-01). 로그 실패가 원래 거부 사유를 가리지 않게 삼킨다. */
+async function logDenied(actorUid: string, role: unknown, targetPath: unknown, why: string) {
+  try {
+    await getFirestore().collection('adminActionLogs').add({
+      actorUid, role: typeof role === 'string' ? role : null,
+      targetPath: typeof targetPath === 'string' ? targetPath : null,
+      denied: true, deniedReason: why, createdAt: FieldValue.serverTimestamp(),
+    });
+  } catch { /* 거부 응답이 우선이다 */ }
+}
+
 export const fnAdminWrite = onCall(async (req) => {
   const actorUid = callerUid(req);
-  const role = requireRole(req, ['master', 'ops']);
+  const rawPath = (req.data as Record<string, unknown> | null)?.targetPath;
+  let role: 'master' | 'ops';
+  try {
+    role = requireRole(req, ['master', 'ops']) as 'master' | 'ops';
+  } catch (e) {
+    await logDenied(actorUid, req.auth?.token?.role, rawPath, 'ROLE');
+    throw e;
+  }
   const targetPath = str(req.data, 'targetPath');
   const reason = str(req.data, 'reason');
   const patch = (req.data as Record<string, unknown>)?.patch;
 
+  const segments0 = targetPath.split('/').filter(Boolean);
+  // 최상위 문서(`fandoms/{id}` · `users/{uid}`)에만 산출 필드가 있다.
+  const docKind = segments0.length === 2 ? segments0[0]! : '';
+  const keys = typeof patch === 'object' && patch !== null ? Object.keys(patch) : [];
+  if (FORBIDDEN.some((re) => re.test(targetPath)) ||
+      keys.some((k) => DERIVED_FIELDS[docKind]?.includes(k))) {
+    await logDenied(actorUid, role, targetPath, 'LEDGER_OR_DERIVED');
+    // 관리자라도 잔액 · 지표를 직접 고칠 수 없다. 별첨1 ② 「원장 정합성」의 마지막 방벽이다.
+    fail(ERR.permissionDenied, '원장 · 지표 · 감사 기록은 전용 함수로만 변경할 수 있습니다.');
+  }
+  if (role !== 'master' && (MASTER_ONLY.has(segments0[0] ?? '') ||
+      keys.some((k) => MASTER_ONLY_FIELDS[docKind]?.includes(k)))) {
+    await logDenied(actorUid, role, targetPath, 'MASTER_ONLY');
+    fail(ERR.permissionDenied, '마스터 권한이 필요한 문서입니다.');
+  }
+
   if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
     fail(ERR.permissionDenied, '변경 내용이 올바르지 않습니다.');
   }
-  if (FORBIDDEN.some((re) => re.test(targetPath))) {
-    // 관리자라도 잔액을 직접 고칠 수 없다. 별첨1 ② 「원장 정합성」의 마지막 방벽이다.
-    fail(ERR.permissionDenied, '재화 관련 문서는 원장 함수로만 변경할 수 있습니다.');
-  }
   // 경로 깊이가 짝수여야 문서다. 홀수면 컬렉션이라 통째로 덮어쓸 위험이 있다.
   const segments = targetPath.split('/').filter(Boolean);
   if (segments.length === 0 || segments.length % 2 !== 0) {