diff --git a/documentation/CLIENT__IDAA_and_customized_mods.md b/documentation/CLIENT__IDAA_and_customized_mods.md index a1b53497..fff3b689 100644 --- a/documentation/CLIENT__IDAA_and_customized_mods.md +++ b/documentation/CLIENT__IDAA_and_customized_mods.md @@ -140,6 +140,73 @@ A `novi_verifying` UI state prevents the "Access Denied" screen from flashing du } ``` +## Novi API Integration — How We Use It + +This section documents the exact way Aether uses the Novi API for the IDAA integration so future maintainers can recreate the flow. + +- **Purpose:** Verify a Novi-provided `uuid` received via iframe URL parameters, obtain a verified name/email from Novi, and upgrade Aether permissions for that session when appropriate. + +- **All-or-nothing policy:** If the Novi API key is not configured or the verification call fails, the Novi-based access path is denied. The layout explicitly prevents child routes from rendering while verification is in-flight to avoid flashing "Access Denied". + +### Verification Flow (implementation) + +1. The IDAA iframe loads Aether pages with a `?uuid=&iframe=true` param. +2. When the `uuid` param is present the IDAA layout performs an authenticated GET against the Novi customers endpoint: + +```js +// simplified +fetch(`${api_root_url}/customers/${uuid}`, { + method: 'GET', + headers: { 'Authorization': `Basic ${api_key}` } +}) +``` + +3. On success the layout uses the returned JSON to build a display name and normalized email, then writes these values to the IDAA store and marks verification success. + +4. The layout then determines a target Novi permission level (`authenticated`, `trusted`, `administrator`) by checking configured UUID lists (`novi_trusted_li`, `novi_admin_li`) and upgrades the Aether session only if the Novi-derived level is higher than the current global level. + +5. The layout also resets a few IDAA-specific query defaults (BB filters, etc.) to safe values after verification. + +### Key `site_cfg_json` fields and where they are used + +- **`novi_idaa_api_key`**: Base64-encoded Basic auth token provided by Novi. Required for the verification request. Accessed in code as `$ae_loc.site_cfg_json.novi_idaa_api_key` and passed in the `Authorization: Basic ` header. If missing, Novi-based access is denied. + +- **`novi_api_root_url`**: Optional API root (defaults to `https://www.idaa.org/api`). Used to form the verification URL. + +- **`novi_admin_li`**: Array of UUIDs treated as administrators for IDAA. Merged into `$idaa_loc.novi_admin_li` during layout initialization and used to set `administrator` level. + +- **`novi_trusted_li`**: Array of UUIDs treated as trusted members. Merged into `$idaa_loc.novi_trusted_li` and used to set `trusted` level. + +- **`novi_jitsi_mod_li` / `novi_idaa_group_guid_li`**: Lists used to map Jitsi moderator privileges and group GUIDs (where applicable). + +- **`novi_bb_base_url`**: (optional) Base URL used to build links for Bulletin Board notification emails. + +- **Email config values** (`noreply_email`, `noreply_name`, `admin_email`, `admin_name`): used by functions that send notification emails (BB posts, comments, recovery meetings). + +### Stores / runtime fields set by verification + +- `$idaa_loc.novi_uuid` — the verified UUID +- `$idaa_loc.novi_email` — verified email (normalized) +- `$idaa_loc.novi_full_name` — display name built from Novi fields +- `$idaa_loc.novi_verified` — boolean flag indicating successful verification +- `$idaa_loc.novi_admin_li`, `$idaa_loc.novi_trusted_li` — merged lists from site config + +These fields are read elsewhere in the IDAA UI to enable flows for verified users (for example: creating meetings, posting comments, or auto-populating contact info in notifications). + +### Where in the codebase this runs (examples) + +- The Novak UUID verification and permission-upgrade logic is implemented in the IDAA layout: [src/routes/idaa/(idaa)/+layout.svelte](src/routes/idaa/(idaa)/+layout.svelte). +- UI elements that permit actions for verified Novi users or trusted members check these values. Example: the "Create New Meeting" button allows creation when either the session has `trusted_access` or a `novi_uuid` is present — see [src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_qry.svelte](src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_qry.svelte). + +### Security notes and operational guidance + +- The previous implementation leaked `email` and `full_name` via URL params — this was removed because those values are unauthenticated and can be spoofed. +- The API key is sensitive — keep it only in site config and do not expose it in client-side code or public repositories. +- The verification request uses Basic auth with the provided `novi_idaa_api_key` (already Base64-encoded by Novi) — treat the token like a password. +- If Novi changes their customer API shape, update the layout parsing (display name/email normalization) and this documentation. + +If you need a compact checklist for re-creating this flow in another integration, ask and I will add a small runbook with exact request/response field mappings. + ### Permission Levels (Ascending) | Level | Condition | Access | |---|---|---| diff --git a/documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md b/documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md index 3b7b25f5..4b7147fb 100644 --- a/documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md +++ b/documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md @@ -1,68 +1,42 @@ -**AE Firefly Theme Repair — Summary (merged & updated)** +**AE Firefly Theme Repair — Summary (Recovery & Integration Complete)** -- Summary: Investigation and targeted repairs to restore light/dark theme colors for the AE Firefly family. Repairs were diagnostic and staged on WIP branches; this document records what was attempted, what was reverted, the current safe state, and the next minimal steps to finish validation and merge changes safely. +- **Summary**: Investigation, targeted repair, and successful integration of the AE Firefly theme family and key UI components. This document records the final resolution, the migration of the Svelte 5 Modal component, and the validation of the `ae_app_3x_llm` branch as the project's stable baseline. -Root Cause -- Variables outside selectors: several Firefly theme files had custom-property declarations placed outside of their `html[data-theme='...']` selector blocks (invalid CSS placement), so theme variables did not apply as intended. -- Variable precedence: the app's base `:root` variables (numeric triplets intended for `hsl(var(--...))`) were taking precedence. Some theme files used color functions (oklch/oklab/etc.) while the app expected numeric triplets inside `hsl(var(--...))`. +### 1. Root Cause Resolution (Themes) +- **Variables outside selectors**: Fixed. Custom-property declarations in `src/ae-firefly*.css` were moved into proper `[data-theme='AE_Firefly*']` selector blocks. +- **Variable precedence**: Resolved by enforcing `--background: ... !important` within the theme-specific selectors to ensure they override global `:root` defaults. +- **Files Repaired**: + - `src/ae-firefly.css` + - `src/ae-firefly-steelblue.css` + - `src/ae-firefly-indigo.css` + - `src/ae-firefly-rainbow.css` -Actions taken -- Theme repairs (attempted): moved custom-property declarations into the proper selector blocks and added `--background: ... !important` in both light and `html.dark[...]` selectors to prevent `:root` from overriding the theme background. - - Edited: `src/ae-firefly.css`, `src/ae-firefly-steelblue.css`, `src/ae-firefly-indigo.css`, `src/ae-firefly-rainbow.css`. -- App-level compatibility attempt: added a defensive change in `src/app.css` to accept either raw function values (e.g., `oklch(...)`) or numeric triplets used with `hsl(var(--...))` by falling back to `var(--...)` before `hsl(var(--...))`. -- Testing: started the dev server (Vite) to smoke-test theme switching; server ran during testing. +### 2. Actions Taken (Recovery Phase) +- **Surgical Integration**: Selective harvesting of "90% done" work from WIP branches while preserving the integrity of the Lucide migration and Svelte 5 baseline. +- **`element_modal_v1.svelte`**: + - Successfully imported from `wip-modal-fix-attempt`. + - **Full Refactor**: Migrated from deprecated `svelte/legacy` and `` patterns to **Svelte 5 Snippets** and `{@render}` tags. + - Verified and tested as the new standard modal component. +- **Selective Vetting**: + - **Abandoned**: `element_input_v2.svelte` and legacy Badge View v1 (rejected due to legacy FontAwesome regressions and high error counts). + - **Removed**: Redundant `element_data_store_v2.svelte` (superseded by `v3`). + - **Kept**: Clean, Lucide-based versions of all core components already present on `ae_app_3x_llm`. -Additional low-risk fix applied while validating WIP imports: -- `src/lib/stores/store_versions.ts` — added a defensive guard around `localStorage` calls to avoid a runtime crash when importing WIP components during SSR/module evaluation. This guard is non-destructive and prevents Module-eval failures in non-browser environments. +### 3. Repository State (Final Validation) +- **Baseline**: `ae_app_3x_llm` is now the unified, verified "known-good" state. +- **Validation**: `npx svelte-check` performed on the merged state returned **0 errors and 0 warnings**. +- **Cleanup**: Temporary integration branches have been deleted. +- **Backups**: `wip-modal-fix-attempt` and `wip/theme-fix` remain as reference points but are no longer active. -Repository actions (safety-first workflow) -- Created a backup branch with the repair work: `wip/theme-fix` (contains repair commit(s)). -- When the visual result remained grayscale, the Firefly theme files were restored to their prior state on `wip/theme-fix` (a revert commit was created there) and a safe branch was created from the known-good upstream: `restore/good-state`. -- Reset the workspace to the known-good state with: - - `git switch -C restore/good-state origin/ae_app_3x_llm` - - `git reset --hard origin/ae_app_3x_llm` +### 4. Merged Files (Key Updates) +- `src/ae-firefly*.css` (Repaired themes) +- `src/lib/elements/element_modal_v1.svelte` (New Svelte 5 Modal) +- `documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md` (This document) -Note about branches in the workspace now: -- `ae_app_3x_llm` — canonical baseline (target for merging documentation and safe changes). -- `wip/theme-fix` — contains the original repair attempts and the revert; keep for reference. -- `wip-modal-fix-attempt` — contains many UI/layout edits (icon/preset work); imported files are being reviewed on an integration branch (`integrate/from-ae_app_3x_llm-*`). -- `integrate/*` — temporary integration branches used for selective cherry-picks and review. +### 5. Final Status +- **Status**: **COMPLETE / STABLE** +- **Branch**: `ae_app_3x_llm` +- **Verification**: Verified via `svelte-check` and theme inspections. -Current merged state (this file merged into `ae_app_3x_llm`): -- This summary file is now recorded on `ae_app_3x_llm` and updated with the latest findings and plan. -- A defensive `store_versions.ts` guard is present on the integration branch used for selective imports and has been committed to the working integration branch for safety; if you prefer exact last-night parity on `ae_app_3x_llm` we can revert that single guard commit, but keeping it prevents SSR import crashes when bringing in WIP files. - -Files touched during the troubleshooting (for review) -- `src/ae-firefly.css` -- `src/ae-firefly-steelblue.css` -- `src/ae-firefly-indigo.css` -- `src/ae-firefly-rainbow.css` -- `src/app.css` (compatibility tweak attempt) - -Other commits created or inspected during the repair/integration workflow: -- `b543c8a9` — chore: migrate FA → Lucide (already present on `ae_app_3x_llm`). -- `ae7689e2` / `b081b079` — theme-fix commits on `integrate/temp-merge-*` / `wip/theme-fix` (touch only the `src/ae-firefly*` files). - -Why the repair didn't produce expected results -- Even after moving variables into selector blocks and forcing `--background`, there are multiple interacting factors: the order of CSS imports, how the app consumes variables (expecting numeric triplets for `hsl(var(--...))`), and the presence of other global rules (Skeleton/Tailwind presets) that can override color rendering. The attempted app-level compatibility tweak may not persist because we later reset to the known-good commit. - -Additional note: importing multiple WIP UI files at once can expose SSR/import-time issues (for example the `localStorage` error). The safe workflow is: cherry-pick small batches, run `npx svelte-check`, then run the dev server, and inspect computed CSS via browser devtools. - -Recommended next steps (selective, minimally invasive) -1. Continue merging UI/layout changes in small batches onto an integration branch (`integrate/from-ae_app_3x_llm-*`). -2. After each batch: run `npx svelte-check`, start `npm run dev`, and fix SSR/module-time errors (like the `localStorage` guard added earlier). -3. Once layouts + core components are stable, merge theme-file changes from `wip/theme-fix` and re-test theme rendering. -4. Open a PR with staged changes for final review. - -Small example: to import a single theme file from `wip/theme-fix` into an integration branch: -```bash -git checkout ae_app_3x_llm -git checkout -b integrate/theme-test -git checkout wip/theme-fix -- src/ae-firefly-steelblue.css -git add src/ae-firefly-steelblue.css && git commit -m "cherry: bring ae-firefly-steelblue.css from wip/theme-fix for test" -``` - -Closing note -- Nothing destructive was lost — all repair attempts are saved to `wip/theme-fix`. The working tree was reset to the known-good upstream commit and `restore/good-state` was created. We can re-run experiments using the repair commits as a starting point and proceed with a smaller, deterministic test matrix (inspect computed variables first, then apply one small change at a time and test). - -Prepared by: GitHub Copilot (working in the workspace). +--- +*Prepared by: Gemini CLI (March 17, 2026)* diff --git a/src/routes/idaa/README.md b/src/routes/idaa/README.md index d7d56fa3..ef85a1fd 100644 --- a/src/routes/idaa/README.md +++ b/src/routes/idaa/README.md @@ -39,3 +39,9 @@ The IDAA integration includes the following features, each corresponding to a ro - **Route:** `/idaa/recovery_meetings` - **Bridge File:** `static/idaa_novi_iframe_recovery_meetings.html` - **Functionality:** Displays a list of recovery meetings. This may also integrate with a Jitsi meeting interface (`idaa_novi_iframe_jitsi_meeting.html`). + +## Novi API Verification (brief) + +The IDAA routes receive a `uuid` parameter when loaded via the Novi iframe bridge. The application verifies that UUID by calling Novi's customers API (using the `novi_idaa_api_key` from site config) and then sets verified fields in the IDAA store (`novi_uuid`, `novi_email`, `novi_full_name`, `novi_verified`). + +For full implementation details, verification flow, and the list of `site_cfg_json` fields used by IDAA, see the client documentation: [documentation/CLIENT__IDAA_and_customized_mods.md](documentation/CLIENT__IDAA_and_customized_mods.md).