# Buddy CRM — Access & Account Registry

Last updated: 2026-05-06

This document tracks which services Buddy CRM depends on, who has admin access, and how to add a second administrator for bus-factor resilience.

---

## Service Account Summary

| # | Service | Purpose | Admin(s) | Emergency access |
|---|---|---|---|---|
| 1 | **GitHub** | Source of truth for code; push triggers Netlify auto-deploy | Marc Burborough | Repo is private under `nownz-marc/buddy-crm` |
| 2 | **Netlify** | Hosting, functions, env vars, deploys | Marc Burborough | Via shared credentials (Account Access and Passwords) |
| 3 | **Supabase** | Database (shared with original Buddy) | Marc Burborough | Via shared credentials |
| 4 | **Microsoft Azure** | App Registration (SSO + Graph for Outlook sync) | Managed by Max / Platform team | Please see Max / Platform team |
| 5 | **Google Cloud** | Gemini API key | Marc Burborough | Via shared credentials |
| 6 | **Mailchimp** | Audience Buddy integration | Marc Burborough | Via shared credentials |
| 7 | **Gmail** | Skill-queue notification SMTP | Marc Burborough | Via shared credentials |
| 8 | **Domain/DNS** | (if a custom domain is configured) | Marc Burborough | Via shared credentials |

**Emergency access:** other Now NZ staff have access to Marc's service credentials via the company password manager. Please contact Marketing for details about the Account Access and Passwords sheet.

---

## Service Details & How to Add a Second Admin

### 1. GitHub

**What admin access enables:**
- Push to `main` (which triggers a Netlify auto-deploy)
- Manage branches, review PRs, manage repo settings

**How to add a collaborator:**
1. github.com/nownz-marc/buddy-crm → Settings → Collaborators
2. Add by GitHub username
3. Set permission to "Write" (push) or "Admin"

### 2. Netlify

**What admin access enables:**
- Deploy and roll back the site
- View and edit env vars (secrets)
- View function logs
- Change site settings (domain, build config, headers, function timeouts)
- Manage the GitHub integration

**How to add a team member:**
1. https://app.netlify.com → Team settings → Members
2. "Invite members" → enter email
3. Role: "Owner" (full access) or "Developer" (deploy + logs, no billing)

The new admin needs a Netlify account beforehand.

### 3. Supabase

**What admin access enables:**
- View and edit database tables directly
- Run SQL queries (apply migrations, toggle feature flags)
- View API keys
- Manage RLS policies and RPC functions
- Restart the project if paused

**How to add a team member:**
1. https://supabase.com/dashboard → project → Settings → Team
2. Invite by email
3. Role: "Owner"

Share the `SUPABASE_SERVICE_KEY` with them securely (it's in Netlify env vars).

### 4. Microsoft Azure (Entra ID)

The App Registration powering Buddy CRM SSO and Outlook sync is managed by Max / Platform team.

**For any change** (redirect URIs, scope upgrades, client secret rotation, certificate management, audit-log review): please see Max / Platform team. Notable upcoming asks:

- Phase 3 Calendar write-back will need `Calendars.Read` upgraded to `Calendars.ReadWrite` and a fresh admin-consent prompt
- Web Push for the mobile PWA would need a separate consent ceremony (no Entra change required)

### 5. Google Cloud (Gemini API)

**What admin access enables:**
- View and regenerate the Gemini API key
- Monitor usage and quotas

**How to add a team member:**
1. https://console.cloud.google.com → IAM & Admin → IAM
2. "Grant Access" → enter Google account email
3. Role: "Editor" (for API key management) or "Owner"

### 6. Mailchimp

**How to add a team member:**
1. https://mailchimp.com → Account → Settings → Users
2. "Invite A User" → set access level (Manager or Admin)

### 7. Gmail (skill-queue notifications)

**How to update the App Password:**
1. Sign in to the notifications Gmail account
2. Security → 2-Step Verification → App passwords → Generate
3. Update `GMAIL_APP_PASSWORD` in Netlify env vars → trigger a redeploy

The Gmail account must have 2-Step Verification enabled for App Passwords to work.

---

## Credential Storage & Source Code Backup

All service credentials are stored in the company's secure password manager. **Please contact Marketing for details about the Account Access and Passwords sheet.**

Credentials stored:
- GitHub account credentials
- Netlify account credentials
- Supabase project URL + service-role key
- Azure App Registration details (managed by Max / Platform team)
- Google Cloud project + Gemini API key
- Mailchimp API key + server prefix
- Gmail account + App Password
- `BUDDY_SERVICE_KEY` (for service / MCP integrations)
- `EMAIL_TOKEN_KEY` (AES-256-GCM key for refresh-token encryption — **don't rotate casually**)
- `MS_CLIENT_SECRET` (Azure App Registration client secret)
- Domain registrar credentials (if a custom domain is configured)

Source code is on GitHub. The original Buddy platform is mirrored weekly to **[SharePoint](https://nownz.sharepoint.com/:f:/s/Tools/IgCJmDrcuGh5Q4cFoyy7dnVEAdL2H95BDPF2Pi-xFQjCyrM?e=CpyqwP)**.

---

## Onboarding a Second Developer/Admin

### Minimum setup ("can fix things")

1. Review credentials in the company password manager
2. Add to Netlify as Owner (rollback, logs, env vars)
3. Add to Supabase as Owner (toggle flags, query data)
4. Add to GitHub as collaborator (push access)
5. Share this `docs/` directory and the handover snapshot
6. Walk through:
   - How to roll back a deploy (`incident-playbooks.md` Playbook 1)
   - How to toggle a feature flag via SQL (`incident-playbooks.md` Playbook 9)
   - How to read Netlify function logs
   - Where env vars are and what they do (`environment-variables.md`)
   - The active Calendar v1 timezone bug investigation (`handover-2026-05-06.md` § 1.1)

### Full setup ("can develop and deploy")

All of the above, plus:

1. Coordinate with Max / Platform team for Azure App Registration access
2. Add to Google Cloud project
3. Clone the repo locally; run `npm install` for the Netlify Function deps
4. Walk through:
   - The architecture (`architecture-overview.md`)
   - The database schema (`database-schema.md`)
   - The deploy runbook (`deployment-runbook.md`) — pushing to `main` is the deploy trigger
   - Local dev: `npx serve .` works for static pages; `localhost` skips MSAL via `shared/auth.js` dev mode
   - The Outlook sync subsystem (architecture overview § Outlook Integration) — most operationally subtle part of the app

---

## What to Do If a Credential Is Compromised

### Immediate steps
1. **Identify** which credential is exposed
2. **Revoke or rotate** at the source
3. **Update** the new credential in Netlify env vars
4. **Trigger a redeploy** so functions pick up the change
5. **Audit** Supabase logs for unauthorized access if DB credentials were exposed

### Rotation procedures by credential

| Credential | Where to rotate | Notes |
|---|---|---|
| `SUPABASE_SERVICE_KEY` | Supabase Dashboard → Settings → API | Cannot be rotated in place — would require creating a new project. Contact Supabase support |
| `GEMINI_API_KEY` | Google Cloud Console → APIs & Services → Credentials | Delete old, create new |
| `MAILCHIMP_API_KEY` | Mailchimp → Account → Extras → API keys | Disable old, create new |
| `MS_CLIENT_SECRET` | Azure App Registration → Certificates & secrets (via Max / Platform team) | New secret only affects the auth-code exchange; stored refresh tokens still work |
| `EMAIL_TOKEN_KEY` | Netlify env vars | **High blast radius** — invalidates every encrypted refresh token in `user_graph_tokens`. Either restore the previous value or write a re-encryption migration; otherwise every BDM has to re-OAuth |
| `GMAIL_APP_PASSWORD` | Gmail → Security → App passwords | Revoke old, generate new |
| `BUDDY_SERVICE_KEY` | Netlify env vars + every consumer that holds it | E.g. `.mcp.json` in the original Buddy repo |
| Azure App Registration | Please see Max / Platform team | If deleted/recreated: update `AZURE_CLIENT_ID` / `AZURE_TENANT_ID` env vars and the hardcoded fallbacks in `shared/auth.js` and `netlify/functions/supabase-client.js` |

---

## Emergency Contacts

| Role | Name | Contact |
|---|---|---|
| Platform Owner / Developer | Marc Burborough | `marc.burborough@nownz.co.nz` |
| Second admin | *(add when appointed)* | *(add contact)* |
| Microsoft Azure (SSO + Graph) | Max / Platform team | *(see Max or Platform team for any Azure issue)* |
| Netlify Support | — | https://www.netlify.com/support/ |
| Supabase Support | — | https://supabase.com/support |