Access Control v2 + detailed analytics + unified shell (2.1.0)

CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to Shelf will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.1.0] — 2026-07-19
+
+Access control for restricted documentation, a much richer analytics dashboard,
+and a unified app shell. Backwards-compatible: existing products stay public and
+nothing changes until you mark a product restricted.
+
+### Added
+
+- **Restricted products & access control** — a product can be marked *restricted*: it is then hidden from anyone without a read grant and returns `404` on unauthorized access (no existence leak); anonymous visitors are sent to login, admins see everything. Orthogonal to visibility, so a product can be preview + restricted.
+- **Permission groups** — groups grant read access to restricted products and, optionally, Shelf adminship. Membership is either an explicit email list (stageable before a user's first login) or **auto-computed** from a sandboxed JsEval predicate over the user's login claims (e.g. `user.email.endsWith('@cocoar.dev')`), recomputed at login / on save / on demand. Managed under Administration → Groups, with a script dry-run.
+- **Product-side access grants** — assign who may read a restricted product directly on the product (Access tab): both **groups and individual users** are principals and can be granted. Users are keyed by email so access can be staged before their first login.
+- **Detailed analytics dashboard** — an interactive **world map** of visitor cities (bubbles by volume), country and city breakdowns with **flags and full names**, browser / OS / language / referrer breakdowns, per-product filtering and an IP-exclude filter. All aggregation happens server-side.
+- **Groups & principals API** — `GET/POST/PUT/DELETE /_api/groups`, `POST /_api/groups/recalculate`, `POST /_api/groups/test-script`, `GET /_api/principals`.
+
+### Changed
+
+- **Unified app shell** — the public landing page and the admin UI now share one shell: the same header everywhere (with dark/light toggle), the admin sidebar for logged-in admins on every page, and dark mode working on the landing page too.
+- **Analytics summary** now returns cities, geolocated map points, and browser/OS/language/referrer breakdowns; the access log stores visitor lat/lng and shows country flags.
+- Groups live under Administration alongside Users.
+
+### Security
+
+- **Product writes via the admin cookie now require admin.** Previously any authenticated (JIT-provisioned) user could create, update or delete products through the cookie path; this is now gated to admins. The CI/CD Bearer API-key path is unchanged.
+- Admin can additionally be granted through an `IsAdminGroup` permission group (in addition to the `shelf:admin` token permission and the `Modgud.Admins` allowlist).
+
 ## [2.0.0] — 2026-07-18
 
 Shelf 2.0 turns the standalone file-only server into a modgud-federated,

CLAUDE.md

@@ -49,6 +49,28 @@ authorization-code flow (citydiary pattern, code + PKCE):
 - API keys for CI/CD (`ApiKeyFilter`): per-product key → UI-managed master key
   (`ShelfSettings` doc) → config/env bootstrap key. Keys are readable for admins
   (deliberate: docs hosting, not an IdP).
+- **Product writes require admin** on the cookie path (`ApiKeyFilter` → `IAccessResolver`);
+  the Bearer API-key path is unchanged (machine track).
+
+### Access control v2 (restricted products, groups, principals)
+
+- `ProductConfig.Restricted` (orthogonal to `Visibility`) hides a product from anyone without a
+  read grant; `DocsRoutingMiddleware` gates it — authed-no-grant → **404** (no existence leak),
+  anonymous HTML → login redirect, anonymous asset → 401. Products API / landing / `llms.txt`
+  filter restricted products out for non-grantees.
+- **Groups** (`Group` doc) are permission carriers: `MemberEmails` (explicit, stageable pre-login)
+  and/or `MembershipMode.Auto` with a **JsEval** predicate over the persisted login **claims
+  snapshot** (`UserDocument.Claims/Permissions`, refreshed each login). Auto-membership is
+  materialized (`AutoMemberUserIds`) by `IGroupMembershipRecalculator` at login / group save /
+  manual. `IsAdminGroup` grants adminship.
+- Grants live **on the product**: `ProductConfig.ReadPrincipals` (a `PrincipalRef` list). Both
+  `Group` and `UserDocument` implement `IPrincipal`, so groups and individual users (by email)
+  are assignable. `IAccessResolver` (per-request, memoized) resolves `{isAdmin, groupIds, email}`
+  and `CanRead(product)` — no JsEval in the hot path.
+- **Admin** = `shelf:admin` token permission OR `Modgud.Admins` allowlist OR an `IsAdminGroup`
+  group (via `IAccessResolver.IsAdminAsync`, wired into the `"Admin"` policy, `ApiKeyFilter`, `/auth/me`).
+- JsEval: `Cocoar.JsEval.Engine` (copy+adapt from timetodo, in-memory — no event sourcing / SQL
+  translation); predicates are sandboxed and **fail-closed**.
 
 ## Configuration
 
@@ -63,32 +85,46 @@ subdomain (branded login, e.g. `https://shelf.auth.cocoar.dev`), `ApiKey` (boots
 
 ## API surface (`/_api`)
 
-- Public: `GET /products`, `GET /products/{p}`, `GET /products/{p}/versions`, `GET /shelf-config`
-- Cookie or Bearer key: product CRUD, version upload/delete (`ApiKeyFilter`)
-- Auth: `POST /auth/otp/request|verify`, `POST /auth/logout`, `GET /auth/me`
+- Public read: `GET /products`, `GET /products/{p}`, `GET /products/{p}/versions`, `GET /shelf-config`
+  (restricted products filtered out / 404 for non-grantees, per request via `IAccessResolver`)
+- Product CRUD, version upload/delete (`ApiKeyFilter`) — Bearer key, or **admin** cookie
+- Auth: login is the server route `GET /login` (OIDC challenge); `GET /logout`, `GET /_api/auth/me`
 - Admin policy: `/settings/*` (master key), `/products/{p}/api-key` (reveal), `/users/*`,
-  `/analytics/*` (visits, summary, GeoIP status/download)
+  `/analytics/*` (visits+summary with `product`/`from`/`to`/`excludeIps`, GeoIP status/download),
+  `/groups/*` (CRUD, `/recalculate`, `/test-script` dry-run), `/principals` (assignable groups+users)
 
 ## Key Files
 
 Backend (`src/Cocoar.Shelf/`):
 - `Program.cs` — startup, Marten schema, auth wiring, middleware pipeline
 - `ShelfOptions.cs` — all configuration (incl. `ModgudOptions`)
-- `Identity/` — ModgudUserProvisioning, ModgudClaimsTransformation,
+- `Identity/` — ModgudUserProvisioning, ModgudClaimsTransformation, ClaimsSnapshot,
   RbacCookiePreservation, AdminCheck, MartenUserStore
+- `Models/` — ProductConfig (+`Restricted`, `ReadPrincipals`), Group, Principal
+  (`IPrincipal`/`PrincipalRef`), UserDocument (+claims snapshot), AccessLogEntry (+lat/lng)
 - `Endpoints/` — ApiEndpoints (products/versions), AuthEndpoints, SettingsEndpoints,
-  UserEndpoints, AnalyticsEndpoints, TestAuthEndpoints, ApiKeyFilter
+  UserEndpoints, AnalyticsEndpoints, GroupEndpoints, PrincipalEndpoints, TestAuthEndpoints, ApiKeyFilter
 - `Middleware/DocsRoutingMiddleware.cs` — docs routing, rewriting, access-log recording
-  (HTML GETs only)
+  (HTML GETs only), restricted-product gating
 - `Services/` — ManifestService, UploadService, SettingsService, GeoIpService,
   AccessLogChannel/PersistenceService, MartenProductConfigService + migration,
-  BasePathDetector/Rewriter
+  MartenGroupService, BasePathDetector/Rewriter
+- `Services/Access/` — IAccessResolver, IGroupMembershipEvaluator (JsEval),
+  IGroupMembershipRecalculator, ILoginAccessProcessor
 
 Frontend (`src/Cocoar.Shelf.Client/src/`):
 - Routed modals via `@cocoar/vue-fragment-parser` (`route.meta.routedFragments`, URL-hash
   `#create` / `#<id>`; fixed height via `overlayOptions`); shared shell `components/ModalLayout.vue`
-- `views/products/` — grid + tabbed edit modal (General / Tags & API / Versions)
-- `views/admin/` — GeneralSettings (master key), Users, AccessLog, GeoIP; `views/AnalyticsView.vue`
+- `layouts/AppLayout.vue` — one shared shell for landing + admin (header always; sidebar for
+  logged-in admins everywhere); `views/LandingView.vue` renders inside it
+- `views/products/` — grid + tabbed edit modal (General / **Access** / Tags & API / Versions);
+  Access tab = Restricted toggle + principal picker (groups + users)
+- `views/groups/` — Groups grid + tabbed modal (General / Members / Auto-membership with
+  `CoarScriptEditor` from `@cocoar/vue-script-editor` + dry-run)
+- `views/admin/` — GeneralSettings (master key), Users, Groups, AccessLog, GeoIP;
+  `views/AnalyticsView.vue` — dashboard with world map (`@cocoar/vue-map`), flags (`flag-icons`)
+- `core/geo.ts` — country code → name (`Intl.DisplayNames`) + SVG flag class (flag-icons;
+  emoji flags don't render on Windows)
 - Conventions: labels via `CoarFormField` (inputs have NO label prop — also true in vue-ui 2.x), card
   titles via `CoarCard` `#header` slot, destructive actions via `useDialog().confirm`,
   grids bind `rowDataRef(computed(() => store.items))` to Pinia stores; bump
@@ -109,3 +145,8 @@ Frontend (`src/Cocoar.Shelf.Client/src/`):
 - **Public read endpoints stay unauthenticated**; keys/admin data are admin-gated
 - **Access log counts page views** (HTML GETs), not assets or HEAD requests
 - **Admin UI is desktop-only** — no mobile optimization
+- **Access control is opt-in** — `Restricted` defaults false; unrestricted products behave exactly as before
+- **Grants live on the product** (`ReadPrincipals`), not the group — you assign who may read where you toggle Restricted; groups/users are both `IPrincipal`
+- **Restricted → 404, not 403** for authed-no-grant (no existence leak); restricted products are fully invisible (no teaser)
+- **Analytics aggregation is server-side** — the browser only renders; country flags/names are derived client-side from the ISO code (display only)
+- **modgud owns identity, Shelf owns authorization** — groups/grants reference products, which only exist in Shelf, so revocation is immediate (per request, not next login)

src/Cocoar.Shelf.Client/package.json

@@ -11,7 +11,10 @@
   "dependencies": {
     "@cocoar/vue-data-grid": "2.17.1",
     "@cocoar/vue-fragment-parser": "2.17.1",
+    "@cocoar/vue-map": "2.17.1",
+    "@cocoar/vue-script-editor": "2.17.1",
     "@cocoar/vue-ui": "2.17.1",
+    "flag-icons": "^7.5.0",
     "overlayscrollbars": "^2.16.0",
     "pinia": "^4.0.2",
     "vue": "^3.5.40",

src/Cocoar.Shelf.Client/src/components/TopList.vue

@@ -2,7 +2,10 @@
   <div class="top-list">
     <div v-for="item in items" :key="item.label" class="top-item">
       <div class="top-line">
-        <span class="top-label" :title="item.label">{{ item.label }}</span>
+        <span class="top-label" :title="item.label">
+          <span v-if="item.flag" :class="flagClass(item.flag)" class="top-flag" />
+          {{ item.label }}
+        </span>
         <span class="top-count">{{ item.count }}</span>
       </div>
       <div class="top-bar-track">
@@ -14,9 +17,11 @@
 
 <script setup lang="ts">
 import { computed } from 'vue';
+import { flagClass } from '@/core/geo';
 
 const props = defineProps<{
-  items: { label: string; count: number }[];
+  /** Each item may carry an optional `flag` = ISO country code, rendered as an SVG flag prefix. */
+  items: { label: string; count: number; flag?: string }[];
 }>();
 
 const max = computed(() => Math.max(1, ...props.items.map(i => i.count)));
@@ -48,6 +53,12 @@ function barWidth(count: number): string {
   min-width: 0;
 }
 
+.top-flag {
+  margin-right: 6px;
+  border-radius: 2px;
+  vertical-align: -1px;
+}
+
 .top-count {
   color: var(--coar-text-neutral-secondary);
   font-variant-numeric: tabular-nums;