# CLIENT: IDAA — International Doctors in Alcoholics Anonymous **Client:** International Doctors in Alcoholics Anonymous (IDAA) **Module Path:** `src/routes/idaa/` **State Stores:** `src/lib/stores/ae_idaa_stores.ts` **Last Updated:** 2026-03-09 (Novi UUID verification upgrade) --- ## ⚠️ CRITICAL PRIVACY REQUIREMENT **ALL IDAA content is PRIVATE. Authentication is required for ALL modules.** IDAA serves a sensitive population — physicians in addiction recovery. Content exposure to the public is a **severe security failure** and a violation of member trust. - A previous AI agent accidentally exposed IDAA Bulletin Board content publicly. This must never happen again. - Every route, component, and API call in this module must enforce authentication. - When in doubt: **it's private**. **Required access level:** `trusted_access` or higher for all IDAA content. --- ## What IDAA Is IDAA is a private membership organization for physicians in recovery. They use the Aether platform for: - A private document archive (historical materials, meeting records) - A members-only bulletin board (community posts and discussion) - A searchable directory of in-person and virtual recovery meetings - Video conferencing (Jitsi-based) IDAA's Aether instance is embedded as an **iframe inside their existing Novi-powered website** (`idaa.org`). Novi is their external Association Management System (AMS) — it handles membership records and authentication. Aether receives the member context via URL parameters on iframe load. --- ## Architecture: Composite Module IDAA is **not a standalone module** — it is a **composition of three existing Aether modules**, access-gated and branded for the IDAA client. | IDAA Feature | Aether Module Used | Library | |---|---|---| | Archives | Archives module | `src/lib/ae_archives/` | | Bulletin Board (BB) | Posts module | `src/lib/ae_posts/` | | Recovery Meetings | Events module (repurposed) | `src/lib/ae_events/` | | Video Conferences | Jitsi (external embed) | External | There is **no `src/lib/ae_idaa/`** library directory. IDAA-specific state and logic lives in `ae_idaa_stores.ts` and the route components only. This design allows the IDAA module to be removed or updated without touching core modules. --- ## Route Structure ``` src/routes/idaa/ ├── +layout.svelte # Root layout: Novi UUID extraction, iframe height sync ├── (idaa)/ │ ├── +layout.svelte # Access gate: blocks render if unauthorized; permission upgrade │ ├── +page.svelte # IDAA dashboard — 3-module selector │ ├── archives/ # Archives submodule │ │ ├── +page.svelte # Archive list (LiveQuery) │ │ └── [archive_id]/ │ │ ├── +page.svelte # Archive detail + content viewer │ │ ├── ae_idaa_comp__archive_obj_id_view.svelte │ │ ├── ae_idaa_comp__archive_obj_id_edit.svelte │ │ ├── ae_idaa_comp__archive_content_obj_id_edit.svelte │ │ └── ae_idaa_comp__modal_media_player.svelte │ ├── bb/ # Bulletin Board (Posts) submodule │ │ ├── +page.svelte # Post list (LiveQuery, archive-filtered) │ │ └── [post_id]/ │ │ ├── +page.svelte # Post detail + comments │ │ ├── ae_idaa_comp__post_obj_id_view.svelte │ │ ├── ae_idaa_comp__post_obj_id_edit.svelte │ │ └── ae_idaa_comp__post_comment_obj_id_edit.svelte │ ├── recovery_meetings/ # Recovery Meetings (Events repurposed) │ │ ├── +layout.ts # Layout loader (auth, stores) │ │ ├── +layout.svelte # Layout wrapper │ │ ├── +page.svelte # Meeting list + search filters │ │ ├── ae_idaa_comp__event_obj_li_wrapper.svelte # List container/modal host │ │ ├── ae_idaa_comp__event_obj_li.svelte # Individual list item card │ │ ├── ae_idaa_comp__event_obj_qry.svelte # Query/filter bar │ │ ├── ae_idaa_comp__event_obj_id_view.svelte # Meeting detail (read-only) │ │ ├── ae_idaa_comp__event_obj_id_edit.svelte # Meeting edit form (active) │ │ └── [event_id]/ │ │ ├── +page.svelte # Meeting detail page — renders view OR edit based on session flag │ │ └── +page.ts │ ├── video_conferences/ # Jitsi video conference integration │ └── jitsi_reports/ # Jitsi meeting activity log report (trusted_access only) ``` > **Note:** Recovery Meetings has **two UI entry points**: > 1. **Modal pattern** (primary list flow) — list, view, and edit components live at `recovery_meetings/` > level, toggled via `$idaa_sess.recovery_meetings` session flags (`show__modal_view`, `show__modal_edit`). > 2. **Direct page** (`[event_id]/+page.svelte`) — navigating to `/idaa/recovery_meetings/` renders > the same view/edit components gated by `$idaa_sess.recovery_meetings.edit__event_obj`. > > Both patterns use `ae_idaa_comp__event_obj_id_edit.svelte`. The edit form clears **both** > `show__modal_edit` and `edit__event_obj` on save/cancel so it works correctly from either entry point. --- ## Authentication: Novi UUID System IDAA members do not log in through Aether — they log in through Novi (idaa.org), and Novi passes their identity to the Aether iframe via URL parameters. ### URL Parameters (on iframe load) ``` ?uuid=<36-char-uuid> &iframe=true &key= ``` > **Security note (2026-03-09):** The iframe HTML files previously also passed `email` and `full_name` > via URL params. These were unverifiable claims that could be spoofed via URL. They have been removed. > The SvelteKit layout now fetches verified identity directly from the Novi API. > See "Iframe Integration" → "Novi UUID Verification Flow" below. ### Verification Flow (`(idaa)/+layout.svelte`) When a `uuid` param is present in the URL, the layout performs an **async Novi API call** to verify: 1. The UUID actually exists in Novi's system (prevents fake/crafted UUIDs) 2. Gets verified name and email directly from Novi — these can't be forged via URL 3. Sets `$idaa_loc.novi_uuid`, `$idaa_loc.novi_email`, `$idaa_loc.novi_full_name` 4. Sets `$idaa_loc.novi_verified = true` on success A `novi_verifying` UI state prevents the "Access Denied" screen from flashing during the API round-trip. **All or nothing:** If the Novi API key is not configured, or the verification call fails, access is denied. There is no URL-param fallback. **Required `site_cfg_json` fields:** ```json { "novi_idaa_api_key": "Base64-encoded-key-from-Novi", "novi_api_root_url": "https://www.idaa.org/api", // optional, this is the default "novi_admin_li": ["uuid-1", "uuid-2"], "novi_trusted_li": ["uuid-3", "uuid-4"], "novi_idaa_group_guid_li": ["group-uuid"] // Jitsi moderators only } ``` ## 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". - **Rate limits (Novi API):** 20 calls/second · 600 calls/minute · 100,000 calls/day. The layout handles 429 responses with a 10-second flat backoff and one retry. If the retry also returns 429, access is denied and a "Reload / Retry" button is shown. The 5-minute TTL cache on successful verification prevents repeated calls during normal use. ### 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. - **`jitsi_exclude_names`**: (optional) Array of display name strings to exclude from Jitsi Reports. Used to hide known staff and test accounts from the activity report so participant counts and lists reflect real member activity only. Names are matched case-insensitively against `final_participants[].displayName`. Example: `["Scott I.", "Michelle V.", "Brie K."]`. The filter is applied before the "Real meetings only" threshold check — a session with only excluded participants is treated as having 0 real participants. - **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 | |---|---|---| | Anonymous | No UUID, unrecognized UUID, or verification failure | No access | | Authenticated | UUID verified against Novi API | View own content, limited actions | | Trusted | Verified UUID in `novi_trusted_li` | Full member access to all IDAA content | | Administrator | Verified UUID in `novi_admin_li` | Full access + edit/manage | `novi_trusted_li` and `novi_admin_li` are managed in Aether site config (not in Novi directly). ## Identity Linkage: The Novi UUID Rule (Triple Linkage) **CRITICAL ARCHITECTURAL STANDARD:** All member-generated content in the IDAA module MUST be explicitly linked to the member's Novi UUID via the `external_person_id` field. This linkage is the primary mechanism for ownership, edit permissions, and auditing. ### 1. Mandatory at Creation Linkage MUST happen at the moment of initial object creation (POST). Shell records created without an `external_person_id` are considered orphaned and may be inaccessible to the creator. ### 2. Triple Linkage Scope The following objects require mandatory `external_person_id` linkage: - **Recovery Meetings** (`ae_Event`) - **Bulletin Board Posts** (`ae_Post`) - **Post Comments** (`ae_PostComment`) ### 3. Implementation Patterns - **Buttons:** Creation buttons (e.g., "Create New Meeting") must include `external_person_id: $idaa_loc.novi_uuid` in their initial `create_ae_obj` payload. - **Edit Forms:** Edit components must provide robust fallbacks to `$idaa_loc.novi_uuid` for new or incomplete records, ensuring identity is captured even if the initial creation call was narrow. - **Identity Sync:** Along with the UUID, `full_name` and `email` should also be synced from `$idaa_loc` to provide human-readable context in notifications and admin views. - **Race Condition Defense:** `$idaa_loc` may be briefly null on mount before the store hydrates from localStorage. Creation buttons and edit submit handlers must scavenge identity directly from `localStorage.getItem('ae_idaa_loc')` as a fallback when the store value is missing. ### 4. Staff Editing Rules (IDAA Trusted/Admin Staff) IDAA staff have their own Novi UUID. When they edit member content, their identity must **not** overwrite the member's `external_person_id`, `full_name`, or `email`. | Content Type | `external_person_id` for staff | `full_name` / `email` for staff | |---|---|---| | BB Post | **Readonly** (unless `administrator_access`) — member's UUID preserved | Same — rendered from existing record, not staff identity | | Post Comment | **Preserved** — form state initializes from existing record first | Same | | Recovery Meeting | **Intentionally editable** for trusted staff — staff can reassign meeting ownership | Contact 1 renders from existing `contact_li_json[0]` first; staff identity only fills if blank | The fallback to `$idaa_loc.novi_uuid` (the current user's UUID) only fires when the record has **no** existing `external_person_id`. For any record properly created after the 2026-04-07 triple-linkage enforcement, this fallback should never be reached. ### 5. Recovery Meetings — Contact 1 Convention In 99% of cases, **Contact 1 should be the same person linked via `external_person_id`** — the IDAA member who owns and runs the meeting. These are two separate fields: - `external_person_id` — the ownership/identity link (Novi UUID). Determines who may edit the meeting. - `contact_li_json[0]` — the displayed contact info (name, email, phone). Shown to members searching for meetings. They are expected to match but are set independently. Members unlock Contact 1 via confirm dialog if they need to list a different contact. Staff can edit both fields directly. ### Permission Upgrade Rule ``` // RULE: Only UPGRADE to Novi-based permissions, NEVER downgrade. // If a user has a higher global Aether role (site manager, super), // their global role is preserved and not overwritten by Novi auth. ``` This ensures that OSIT staff with `super` or `manager` roles retain full access regardless of Novi UUID status. ### Non-Novi Sign-in Paths (unaffected) - **User/Pass or Auth Link:** No `uuid` in URL → layout Novi block does not run - **Shared Passcode:** No `uuid` in URL → layout Novi block does not run ### Access Gate (`(idaa)/+layout.svelte`) The inner layout blocks ALL rendering if the user is not authorized: - `novi_verifying = true` → "Verifying identity..." spinner - Verification failed or no UUID → "Access Denied" error page - Access check runs before any child routes render --- ## Module 1: Archives **Route:** `/idaa/archives/` **Library:** `src/lib/ae_archives/` **Types:** `ae_Archive`, `ae_ArchiveContent` The Archives module stores IDAA historical content — meeting records, conference proceedings, historical documents, and media. ### Object Types **Archive (Container)** - Represents a collection (e.g., "2019 Conference Proceedings") - Key fields: `name`, `description`, `original_datetime`, `original_location`, `archive_on` - `archive_on` — date when this archive collection is auto-hidden (scheduled visibility control) **ArchiveContent (Items)** - Individual items within an archive - Supports multiple content types: `'text'`, `'file'`, `'url'`, `'video'` - Key fields: `archive_content_type`, `content_html`, `url`, `hosted_file_id`, `duration` - Video/audio content has a dedicated media player component ### Database (Dexie) ``` db_archives.archive — Archive containers db_archives.content — Archive content items (linked by archive_id) ``` ### Demo / Test IDs - Archive: `nAA2bHLv8RK` (id: 1) "One Sky Test Archive" - Archive Content: `UjKzrk-GKu5` (id: 1) "Hosted File Test" --- ## Module 2: Bulletin Board (BB) **Route:** `/idaa/bb/` **Library:** `src/lib/ae_posts/` **Types:** `ae_Post`, `ae_PostComment` The BB is the IDAA members-only community discussion board. It is the **most sensitive module** — public exposure must never occur. ### Object Types **Post (Thread)** - Key fields: `title`, `content`, `anonymous`, `full_name`, `email` - `archive_on` — date after which the post is hidden from all views - `archive` — boolean flag for immediate archival - `enable_comments` — controls whether replies are allowed - `post_comment_count` — cached count of replies **PostComment (Reply)** - Key fields: `post_id`, `content`, `anonymous`, `full_name`, `email` - Replies inherit the parent post's visibility rules ### Post Visibility / Archival Filter Posts with `archive_on` set to a past date are **automatically hidden** from all queries. This is enforced at the component level via a LiveQuery filter: ```typescript // This filter is REQUIRED — do not remove it filter((x) => !x.archive_on || archiveDate > now) ``` Archived posts are soft-deleted — they remain in the database for audit purposes but are not shown to members. Most recent first (sorted `updated_on DESC`). ### Database (Dexie) ``` db_posts.post — Posts (threads) db_posts.comment — Post comments (linked by post_id) ``` --- ## Module 3: Recovery Meetings **Route:** `/idaa/recovery_meetings/` **Library:** `src/lib/ae_events/` (standard Events module, repurposed) **Types:** `ae_Event` (standard event type, filtered for meeting context) Recovery Meetings reuses the Aether Events object to represent AA recovery meetings. These are NOT conferences — they are regular ongoing meetings (weekly, monthly, etc.) available to IDAA members. ### Search Filters Members can filter meetings by: - **Fulltext search** — name, location - **Physical** — in-person meetings - **Virtual** — online meetings (Zoom, Google Meet, etc.) - **Meeting type** — specific meeting format categories Search is debounced (250ms) and uses the standard Aether SWR pattern. ### Search Architecture — What Is and Isn't Searched The fulltext search runs against the `default_qry_str` field (backend-computed, contains: `id_random`, type, name, description, timezone, recurring pattern/text, location text). **Contact names and emails are NOT currently searchable.** The `contact_li_json` field is a JSON longtext — MariaDB cannot efficiently substring-search it directly. The backend already has a `contact_li_json_ext` (STORED GENERATED, indexed) column to work around this, but it has not yet been added to the searchable fields whitelist in the API. **Pending fix (tracked in TODO__Agents.md, 2026-04-08):** - Backend: add `contact_li_json_ext` to the event object searchable fields whitelist - Frontend: add `contact_li_json_ext` as an OR condition in `search__event()`, and update the local IDB fast-path filter to parse `contact_li_json` for instant cache results ### Edit Form — Sections and Key Fields The edit form (`ae_idaa_comp__event_obj_id_edit.svelte`) is organized into these sections. All fields map directly to the `ae_Event` object; none are IDAA-specific custom fields. | Section | Key Fields | | --- | --- | | **General Information** | `name` (required), `description` (TipTap rich text), `type` (IDAA / Caduceus / Family Recovery) | | **How to Attend** | `physical` (bool), `virtual` (bool) toggles; conditionally shows: | | → Physical | `location_address_json` (name, line_1–3, city, state, postal, country), `location_text` (TipTap) | | → Virtual | Platform toggle: **Zoom** (`attend_url_code` meeting ID, `attend_url_passcode`, `attend_json.zoom.passcode_enc`, `attend_json.zoom.domain`, `attend_json.zoom.full_url`), **Jitsi** (`attend_json.jitsi.*`), **Other** (`attend_url`, `attend_url_passcode`, `attend_phone`, `attend_phone_passcode`) | | → Both | `attend_text` (TipTap — additional attendance instructions) | | **Schedule** | `recurring_pattern` (weekly/every other week/monthly/other), `weekday_*` (Sun–Sat booleans), `timezone`, `recurring_start_time`, `recurring_end_time`, `recurring_text` (optional TipTap, auto-generated with `*gen*` prefix if blank) | | **Contacts** | `external_person_id` (Novi UUID link), `contact_li_json[0]` (Contact 1: name, email, phone_mobile, phone_home, phone_office — name/email locked to Novi user by default), `contact_li_json[1]` (Contact 2: same fields, optional) | | **Admin Options** | `status`, `hide`, `priority`, `sort`, `group`, `enable`, `notes` (TipTap) — **trusted_access only** | **Rich text fields** all use `AE_Comp_Editor_TipTap` with separate `*_new_html` state variables (not bound to `$idaa_slct.event_obj` directly) to track change state for the save-button logic. **Zoom URL auto-generation:** Triggered by `$idaa_trig = 'update_zoom_full_url'`. An `$effect` reconstructs `attend_json.zoom.full_url` from domain + meeting_id + passcode_enc whenever the Meeting ID, Passcode, Encrypted Passcode, or Domain fields change. **Recurring text auto-generation:** If `recurring_text` is blank or contains the `*gen*` prefix, the submit handler generates a human-readable string (e.g., `*gen* weekly: Monday, Wednesday at 7:00 PM America/Chicago`). Members can opt into a custom text via "Add More Details?" (admin/trusted only). **Contact 1 lock:** Contact 1 name and email default to the logged-in Novi member's identity (`$idaa_loc.novi_full_name`, `$idaa_loc.novi_email`). They are `readonly` unless the user explicitly unlocks them via confirm dialog (or has administrator access). ### Jitsi Integration Some virtual meetings are hosted via Jitsi. Members with a Jitsi moderator UUID (`novi_jitsi_mod_li`) have elevated permissions in video sessions. ### Edit Form — Implementation Notes (v2) - The v2 edit form uses a `