# Google Cloud OAuth Setup — Step by Step

## Step 1: Create Google Cloud Project (or use existing)

1. Go to https://console.cloud.google.com/
2. Sign in with `hoffmann.family.manager@gmail.com`
3. Create new project (or select existing):
   - Project name: `hoffmann-icarus` (or your preference)
   - Organization: None (personal project)

## Step 2: Enable Google Calendar API

1. In the project, go to **APIs & Services** → **Library**
2. Search "Google Calendar API"
3. Click **Enable**

## Step 3: Configure OAuth Consent Screen

1. Go to **APIs & Services** → **OAuth consent screen**
2. Choose **External** (since this is a personal/family app)
3. Fill in:
   - App name: `Icarus Family Assistant`
   - User support email: `hoffmann.family.manager@gmail.com`
   - Developer contact: `hoffmann.family.manager@gmail.com`
4. Click **Save and Continue**
5. **Scopes** — Add:
   - `https://www.googleapis.com/auth/calendar.readonly`
   - (Search "calendar.readonly", check the box, click **Update**)
6. Click **Save and Continue**
7. **Test users** — Add your email:
   - `hoffmann.family.manager@gmail.com`
8. Click **Save and Continue** → **Back to Dashboard**

## Step 4: Create OAuth 2.0 Credentials

1. Go to **APIs & Services** → **Credentials**
2. Click **+ Create Credentials** → **OAuth client ID**
3. Application type: **Desktop app**
4. Name: `Icarus Desktop Client`
5. Click **Create**
6. Download the JSON file — this is your `client_secret.json`

## Step 5: Secure the Credential File

**Important:** This file contains sensitive secrets.

1. Move it to the Beelink (via secure transfer — scp, Tailscale, etc.)
2. Place at: `/home/hoffmann_admin/.config/gog/client_secret.json`
3. Set permissions: `chmod 600 /home/hoffmann_admin/.config/gog/client_secret.json`
4. **Never commit to git, never share**

## Step 6: Authenticate with gog

On the Beelink (titanium-butler), run:

```bash
# Create config directory
mkdir -p /home/hoffmann_admin/.config/gog

# Set credentials
gog auth credentials /home/hoffmann_admin/.config/gog/client_secret.json

# Add account with calendar scope (readonly enforced)
gog auth add hoffmann.family.manager@gmail.com --services calendar

# This will open a browser for OAuth consent. Since you're on SSH, use:
# Option A: Local browser + copy-paste code
# Option B: Run on a machine with browser, copy token to Beelink
```

## Step 7: Verify Read-Only Scope

```bash
# Check token scopes
gog auth list --json

# Should show:
# {
#   "email": "hoffmann.family.manager@gmail.com",
#   "scopes": ["https://www.googleapis.com/auth/calendar.readonly"]
# }

# Test query (should work)
gog calendar events primary --from 2026-05-01T00:00:00Z --to 2026-05-07T23:59:59Z

# Test write (should FAIL — confirming read-only)
# This command should error with "insufficient permissions"
```

## Step 8: Icarus Integration

Once gog is authenticated, I'll configure:

1. **CalendarValidator** class in `services/icarus/calendar_adapter.py`
2. **Read-only enforcement** — Code checks token scope before every query
3. **Event-driven queries** — Only called from `shadow_bot.py` after tripwire fire
4. **Rate limiting** — Max 50 queries/day, tracked in staging.db

---

## Security Checklist

| Check | Status |
|-------|--------|
| OAuth scope = `calendar.readonly` only | ⏳ Verify after setup |
| Client secret file permissions = 600 | ⏳ Set after transfer |
| No write API calls in code | ✅ Enforced in spec |
| Rate limiting configured | ✅ Will implement |
| Token refresh handled | ✅ gog handles automatically |

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| "Access blocked: app not verified" | OAuth consent screen → click "Advanced" → "Go to Icarus Family Assistant (unsafe)" |
| "Token expired" | `gog auth refresh hoffmann.family.manager@gmail.com` |
| "API not enabled" | Go to Library → search "Calendar API" → Enable |
| "Insufficient permissions" on write | Expected! Confirms read-only is working. |

---

## Next Step

After you complete Steps 1-5, transfer the `client_secret.json` to the Beelink and let me know the path. I'll run `gog auth` and verify the read-only scope, then dispatch Socrates for the CalendarValidator implementation.

**Questions or blockers?** Ping me at any step.