Merge pull request #67 from keyxmakerx/claude/gallant-johnson-kd574n

fix: per-player permission sync — push + member-mapping UI + match warnings + DM-only clarity

Author: keyxmakerx

.ai.md

@@ -75,7 +75,8 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 | `scripts/item-sync.mjs` | Actor inventory ↔ Chronicle "Has Item" relations. System data sync (quantity, equipped) via relation metadata |
 | `scripts/note-sync.mjs` | Chronicle Notes ↔ JournalEntries in "Chronicle Notes" folder tree. Case normalization (camelCase ↔ snake_case). Sharing → ownership mapping |
 | `scripts/adapters/generic-adapter.mjs` | API-driven adapter: fetches field defs from `/systems/:id/character-fields` API, auto-generates mappings from `foundry_path` annotations in system manifests. Works for all installed systems |
-| `scripts/sync-dashboard.mjs` | 8-tab ApplicationV2 dashboard (Entities, Shops, Maps, Characters, Calendar, Status). Pull/push actions, health metrics, error log, search/filter. Status tab also surfaces a **Copy Calendar Diagnostics** button (`_buildCalendarDiagnosticsInput()` + `buildCalendarDiagnostics()`) so GMs can export a Calendaria diagnostic report without opening the Sync Calendar editor. |
+| `scripts/sync-dashboard.mjs` | 9-tab ApplicationV2 dashboard (Config, Entities, Shops, Maps, Characters, **Members**, Notes, Calendar, Status). Pull/push actions, health metrics, error log, search/filter. **Members tab** (FM-PERM-SYNC): per-member Foundry-user mapping dropdown + matched/UNMATCHED badge, wired to `setUserMappings`; row view-model in `_member-mapping.mjs`. Status tab surfaces a **Copy Calendar Diagnostics** button and a **DM-only-hidden counter** (audit §1A — clarifies that private entities synced but landed hidden-from-players). |
+| `scripts/_member-mapping.mjs` | Pure view-model `buildMemberRows({members, mappings, foundryUsers, keyOf})` for the dashboard Members tab — one row per Chronicle member with current mapping + matched/UNMATCHED badge (stale mappings → UNMATCHED). No Foundry globals; unit-tested at `tools/test-permission-sync.mjs`. |
 | `templates/sync-dashboard.hbs` | Handlebars template for the sync dashboard tabs and content |
 | `templates/shop-window.hbs` | Handlebars template for shop inventory display |
 | `styles/chronicle-sync.css` | Status indicator + shop window styles |
@@ -273,6 +274,38 @@ or WS vs REST payload differences. Verify with the Chronicle dev before changing
 - Uses `GET/PUT /entities/:eid/permissions` endpoints
 - Reverse-map Foundry ownership changes to Chronicle entity permissions
 
+### FM-PERM-SYNC: Per-player Permission Sync + Mapping UI (DONE)
+
+Closes the per-player gaps from the 2026-06-21 permission-sync audit. Fail-CLOSED
+posture preserved throughout — any ambiguity resolves toward LESS player visibility.
+
+- **Per-user push (Foundry→Chronicle).** `journal-sync.mjs::_buildPermissionGrants`
+  (pure, tested) reverse-maps each Foundry per-user ownership entry → Chronicle
+  `{subject_type:'user', subject_id, permission}` via `SyncManager.getChronicleUserId`
+  (level ≥ OWNER → `edit`, else `view`). `_pushPermissions` sends `visibility:'custom'`
+  only when real user grants exist; unmapped Foundry users are SKIPPED (never
+  over-shared) and surfaced (notification + dashboard `warning`).
+- **Manual mapping UI + match-error surfacing (the operator must-have).** Dashboard
+  **Members tab** lists every Chronicle member (`getMembers()`) with a Foundry-user
+  dropdown + matched/UNMATCHED badge; selecting persists via `setUserMappings`. On
+  connect, `fetchAndCacheMembers` auto-matches by display name then emits a visible
+  `ui.notifications.warn` + dashboard `warning` listing every member that did NOT
+  auto-match (previously silently skipped). `SyncManager.memberKey(member)` (exported,
+  tested) is the single source of truth for the member→mapping key (`user_id`, falls
+  back to `id`).
+- **Silent-failure surfacing (audit §3).** Dropped unmapped grant in `_buildOwnership`,
+  fail-closed-to-NONE permissions-API error, per-user push failures, and a members-
+  fetch failure all now log a dashboard `warning`/`error` + notify where user-facing.
+- **Perception-gap counter (audit §1A).** `SyncManager.noteDmOnlyHidden()` /
+  `getDmOnlyHiddenCount()` count private entities that synced but landed hidden-from-
+  players; the Status tab shows "N DM-only entities synced (hidden per the setting)".
+- **Consume `tag_grants` + `public` (audit §5).** `_buildOwnership` maps a `public`
+  grant → OBSERVER/OWNER default (never lowers a higher grant); `tag_grants` can't be
+  expanded to Foundry users so they're surfaced as a warning, keeping fail-closed.
+- **Tests:** `tools/test-permission-sync.mjs` (push grant-building, memberKey, unmatched
+  warning, member-row view-model) + new cases in `tools/test-build-ownership.mjs`
+  (public/tag_grants/dropped-grant/DM-only-count).
+
 ### F-3: System Detection & Character Field Templates (DONE)
 - `SyncManager._detectSystem()` queries `GET /api/v1/campaigns/:id/systems` on start
 - Matches Foundry `game.system.id` to Chronicle system, stores in `detectedSystem` setting

lang/en.json

@@ -86,6 +86,7 @@
         "Maps": "Maps",
         "Notes": "Notes",
         "Characters": "Characters",
+        "Members": "Members",
         "Calendar": "Calendar",
         "Status": "Status"
       },
@@ -191,6 +192,18 @@
         "NoSystem": "Character sync requires a matching game system.",
         "NoSystemHint": "Your Foundry system must match a Chronicle game system with character field templates."
       },
+      "Members": {
+        "Title": "Permission Mapping",
+        "Intro": "Map each Chronicle campaign member to a Foundry user so per-player permissions sync. Unmatched members are skipped — their per-player grants won't sync in either direction until mapped.",
+        "FoundryUser": "Foundry user",
+        "Matched": "Matched",
+        "Unmatched": "UNMATCHED",
+        "Refresh": "Refresh Members",
+        "RefreshHint": "Re-fetch campaign members from Chronicle and re-run auto-match",
+        "UnmatchedWarning": "{count} Chronicle member(s) are not mapped to a Foundry user. Their per-player permissions will NOT sync until you map them below.",
+        "NoMembers": "No campaign members loaded.",
+        "NoMembersHint": "Members load when sync connects. Use Refresh Members to fetch them now."
+      },
       "OfflineWarning": "Sync messages are queued while disconnected, but the queue is limited. Extended offline periods may cause missed updates — use Pull All after reconnecting to ensure consistency.",
       "StatusTab": {
         "Connection": "Connection",
@@ -207,6 +220,7 @@
         "CharacterSyncEnabled": "Enabled",
         "CharacterSyncDisabled": "Disabled",
         "CharacterSyncNoSystem": "Requires matching game system",
+        "DmOnlyHiddenNote": "{count} DM-only entit(y/ies) synced this session and were hidden from players (per the \"DM-only hidden\" setting). The GM sees them; players intentionally don't — this is not a sync failure.",
         "RecentActivity": "Recent Activity",
         "NoActivity": "No recent activity.",
         "ClearLog": "Clear Log",

scripts/_member-mapping.mjs

@@ -0,0 +1,82 @@
+/**
+ * Chronicle Sync - Member ↔ Foundry-user mapping view-model
+ *
+ * Pure builder for the dashboard Members tab. Given the Chronicle campaign
+ * members, the current `userMappings` table, the available Foundry users, and
+ * a member-key resolver, it produces one row per member describing the current
+ * mapping and whether it is matched or UNMATCHED.
+ *
+ * Kept side-effect-free (no Foundry globals) so it can be unit-tested without a
+ * Foundry runtime — the same pattern the sync-calendar pure helpers use.
+ *
+ * Security posture: an UNMATCHED member's per-player permission grants are
+ * silently dropped on both push and pull, so the row's `matched=false` /
+ * `UNMATCHED` badge is the operator's required signal that a wrong/missing
+ * mapping is widening or narrowing access without their knowledge (audit §2).
+ */
+
+/**
+ * @typedef {object} MemberRow
+ * @property {string} key          - Chronicle user-id key (mapping table key).
+ * @property {string} name         - Member display name.
+ * @property {string} [role]       - Chronicle role label, if present.
+ * @property {string|null} foundryUserId - Currently mapped Foundry user id, or null.
+ * @property {string|null} foundryUserName - Currently mapped Foundry user name, or null.
+ * @property {boolean} matched     - True when mapped to a live Foundry user.
+ * @property {Array<{id: string, name: string, selected: boolean}>} options - Dropdown options.
+ */
+
+/**
+ * Build the Members-tab rows.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.members - Chronicle members (`GET /members`).
+ * @param {Object<string,string>} params.mappings - `userMappings` (chronicleId → foundryId).
+ * @param {Array<{id: string, name: string}>} params.foundryUsers - `game.users` (id + name).
+ * @param {(member: object) => (string|null)} params.keyOf - Member-key resolver (`memberKey`).
+ * @returns {{rows: MemberRow[], matchedCount: number, unmatchedCount: number}}
+ */
+export function buildMemberRows({ members, mappings, foundryUsers, keyOf }) {
+  const userList = Array.isArray(foundryUsers) ? foundryUsers : [];
+  const map = mappings || {};
+  const rows = [];
+  let matchedCount = 0;
+
+  for (const member of members || []) {
+    const key = keyOf(member);
+    if (!key) continue;
+
+    const mappedId = map[key] || null;
+    // A mapping only counts as "matched" if it points at a Foundry user that
+    // still exists — a stale id (user deleted) must surface as UNMATCHED so the
+    // operator re-maps it rather than trusting a dead link.
+    const mappedUser = mappedId ? userList.find((u) => u.id === mappedId) : null;
+    const matched = !!mappedUser;
+    if (matched) matchedCount++;
+
+    const options = [
+      { id: '', name: '— Unmapped —', selected: !matched },
+      ...userList.map((u) => ({
+        id: u.id,
+        name: u.name,
+        selected: u.id === mappedId,
+      })),
+    ];
+
+    rows.push({
+      key,
+      name: member.display_name || key,
+      role: member.role || '',
+      foundryUserId: mappedId,
+      foundryUserName: mappedUser ? mappedUser.name : null,
+      matched,
+      options,
+    });
+  }
+
+  return {
+    rows,
+    matchedCount,
+    unmatchedCount: rows.length - matchedCount,
+  };
+}