Use VITE_DEV_TOKEN env var for dev auth token; add pre-commit hook to block JWT commits

Author: apdavison

.gitignore

@@ -15,6 +15,9 @@ apps/nar-browser/lib
 __pycache__
 .ipynb_checkpoints
 
+# secrets
+apps/nar-v3/.env.local
+
 # other
 *.log
 *.DS_Store

CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository layout
+
+All application code lives in `apps/nar-v3/`. The repo root contains only CI/CD configuration (`.gitlab-ci.yml`, `.github/workflows/`).
+
+## Commands
+
+All commands run from `apps/nar-v3/`:
+
+```bash
+npm run dev        # start Vite dev server
+npm run build      # production build
+npm run lint       # ESLint (0 warnings allowed)
+npm test           # run all tests (requires EBRAINS KG connectivity for "KG" tests)
+npm run testci     # run tests that don't require KG connectivity (CI-safe)
+npm run coverage   # test coverage
+```
+
+Run a single test file or filter by name:
+```bash
+npx vitest __tests__/utility.test.js
+npx vitest --grep "test name pattern"
+```
+
+## Authentication in development
+
+The app uses Keycloak/EBRAINS IAM OAuth. To authenticate in dev mode, copy `apps/nar-v3/.env.local.example` to `apps/nar-v3/.env.local` and paste a valid EBRAINS IAM token as `VITE_DEV_TOKEN`. The dev server will use it automatically — no edits to `main.jsx` needed. `.env.local` is gitignored. Tests that require live KG access have "KG" in their name and are skipped by `testci`.
+
+## Architecture
+
+The app is a React SPA that provides a browsable interface to neural activity datasets stored in the **EBRAINS Knowledge Graph (KG)**. Users can explore datasets, subjects, slices, patched cells, and electrophysiology recordings.
+
+### Data flow
+
+```
+React Router v6 loader
+  → datastore.js (fetch + in-memory cache)
+  → KG Core API v3 (https://core.kg.ebrains.eu/v3)
+  → openMINDS-formatted JSON-LD responses
+```
+
+Route loaders (in `src/routes/`) fetch data before rendering. `datastore.js` wraps all KG API calls with caching. `queries.js` and `queryLibrary.js` build the KG query payloads.
+
+### Graph database with hierarchical views
+
+The underlying data is a graph database (the EBRAINS KG). The current dataset views impose a particular hierarchical traversal of that graph, but this is just one perspective — future views may root themselves at different nodes (e.g. a recording-centric or subject-centric view).
+
+For patch clamp, the graph path from dataset to recordings looks like:
+
+```
+Dataset
+  └── StudiedSpecimen (Subject)
+      └── StudiedState
+          └── SlicePreparation → Slice(s)
+              └── CellPatching → PatchedCell(s)
+                  └── RecordingActivity / StimulationActivity
+                      └── DataFile(s)
+```
+
+For other electrophysiology modalities, there may be one or more intermediate Activities whose output is another StudiedState (rather than a final recording), before eventually reaching the RecordingActivity. The graph is not strictly a tree.
+
+Each level of this hierarchy has a corresponding card component in `src/components/`.
+
+### Auth and curator access
+
+`auth.js` handles Keycloak login and checks whether the user has curator permissions. Curators see `IN_PROGRESS` stage data; regular users see only `RELEASED` data. This stage flag flows through `datastore.js` into every KG query.
+
+### Key source files
+
+- `src/main.jsx` — app entry, Keycloak init, dev token
+- `src/routes/` — React Router route components with loaders
+- `src/datastore.js` — KG API wrapper with caching
+- `src/queries.js` / `src/queryLibrary.js` — KG query construction
+- `src/auth.js` — Keycloak authentication
+- `src/components/` — display components (one per hierarchy level)
+
+## Docker & deployment
+
+Two-stage Docker build: Node 20 for `npm run build`, then Nginx alpine to serve the static output on port 8080 as a non-root user. GitLab CI pushes `:prod` (main branch) or `:dev` (development branch) to `docker-registry.ebrains.eu/neuralactivity/nar-app-v3`.

apps/nar-v3/.env.local.example

@@ -0,0 +1,7 @@
+# Copy this file to .env.local and paste your EBRAINS IAM token below.
+# .env.local is gitignored — never commit your token.
+#
+# Get a token by logging in to https://iam.ebrains.eu and copying the
+# access token, or by running the dev server and grabbing it from the
+# browser's local storage after a successful login.
+VITE_DEV_TOKEN=

apps/nar-v3/src/main.jsx

@@ -126,12 +126,11 @@ function renderApp(auth) {
   );
 }
 
-window.addEventListener("DOMContentLoaded", () => initAuth(renderApp));
-
-
-// -- for development, comment out the previous line and uncomment the following ones
-
-// const auth = {
-//   token: "<paste token here>"
-// };
-// window.addEventListener('DOMContentLoaded', () => renderApp(auth));
+// In development, if VITE_DEV_TOKEN is set in .env.local, use it directly.
+// Otherwise fall through to the normal Keycloak login flow.
+// See .env.local.example for setup instructions.
+if (import.meta.env.DEV && import.meta.env.VITE_DEV_TOKEN) {
+  window.addEventListener("DOMContentLoaded", () => renderApp({ token: import.meta.env.VITE_DEV_TOKEN }));
+} else {
+  window.addEventListener("DOMContentLoaded", () => initAuth(renderApp));
+}

scripts/install-hooks.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Install git hooks from the scripts/ directory.
+# Run once after cloning: sh scripts/install-hooks.sh
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+cp "$REPO_ROOT/scripts/pre-commit" "$REPO_ROOT/.git/hooks/pre-commit"
+chmod +x "$REPO_ROOT/.git/hooks/pre-commit"
+
+echo "Installed pre-commit hook."

scripts/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Pre-commit hook: block commits that contain JWT tokens.
+# Install by running: scripts/install-hooks.sh
+
+jwt_pattern='eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}'
+
+if git diff --cached --unified=0 | grep '^+' | grep -qE "$jwt_pattern"; then
+    echo "ERROR: Possible JWT token detected in staged changes."
+    echo "Remove the token and try again. To store dev tokens safely, use .env.local."
+    exit 1
+fi