firefrost-operations-manual/docs/tasks/scoped-gitea-token/deployment-guide.md

# Scoped Gitea Token for Pokerole Project - Deployment Guide

**Status:** Ready  
**Priority:** Tier 1 - Security Foundation  
**Time Estimate:** 15 minutes  
**Depends:** Vaultwarden operational  
**Last Updated:** 2026-02-17

---

## Overview

Create a scoped Gitea API token limited exclusively to the Pokerole project repositories. This replaces the current master token with proper Iron Wall boundary enforcement - technical restrictions instead of "honor system" trust.

**Iron Wall Principle:** Enforce boundaries technically, not socially.

---

## The Problem

**Current State:**
- Pokerole project (Claudius) uses master Gitea token
- Token has full access to ALL repositories including Firefrost infrastructure
- Relies on "honor system" for Claudius not to access Firefrost repos
- Single compromise exposes entire infrastructure

**Risk:**
- Accidental access to Firefrost operations manual
- Potential cross-contamination of projects
- No defense-in-depth isolation
- Violates least-privilege principle

**The Goal:**
- Claudius gets ONLY what's needed: 4 Pokerole repos
- Zero access to Firefrost infrastructure
- Technical enforcement via Gitea's scoped token permissions
- Proper isolation between projects

---

## Pokerole Repositories

**Repos that need access (4 total):**

1. `pokerole-project` (main project repo)
2. `pokerole-data` (data files and assets)
3. `pokerole-tools` (tooling and scripts)
4. `pokerole-docs` (documentation)

**Everything else (including `firefrost-operations-manual`) should be inaccessible.**

---

## Prerequisites

- [ ] Vaultwarden operational and accessible
- [ ] Gitea admin access (https://git.firefrostgaming.com)
- [ ] Knowledge of which Pokerole repos exist
- [ ] Access to update Pokerole session start prompt

---

## Implementation Steps

### Step 1: Log into Gitea

```
URL: https://git.firefrostgaming.com
Username: [your admin username]
Password: [from Vaultwarden or password manager]
```

### Step 2: Navigate to Access Tokens

1. Click your profile icon (top right)
2. Click **"Settings"**
3. Click **"Applications"** tab
4. Scroll to **"Manage Access Tokens"** section

### Step 3: Create New Scoped Token

**Token Settings:**

**Token Name:** `Pokerole Project - Claudius (Scoped)`

**Select Scopes:**

**Repository Scopes (ONLY these):**
- [x] `repo:read` - Read access to repositories
- [x] `repo:write` - Write access (for commits, PRs)

**Organization Scopes:**
- [ ] None (uncheck all)

**User Scopes:**
- [ ] None (uncheck all)

**Miscellaneous:**
- [ ] None (uncheck all)

**Important:** Do NOT select:
- Admin scopes
- Organization management
- User management
- Notification scopes
- Package scopes

### Step 4: Specify Repository Access

**If Gitea supports per-repo scoping:**

Select ONLY these repositories:
- [x] pokerole-project
- [x] pokerole-data
- [x] pokerole-tools
- [x] pokerole-docs

**If Gitea doesn't support per-repo scoping:**

Note: You may need to create an organization called "Pokerole" and move these repos into it, then scope the token to that organization only.

Alternative: Use Gitea's repository access controls to ensure the token owner only has access to Pokerole repos.

### Step 5: Generate and Copy Token

1. Click **"Generate Token"**
2. **CRITICAL:** Copy the token immediately - it only shows ONCE
3. Token will look like: `f8c6e2b4a1d9e7f3c5a8b2d6e9f1c4a7b3d5e8f2`

**Do NOT close the page until token is safely stored!**

### Step 6: Store Token in Vaultwarden

1. Log into Vaultwarden: `https://[vaultwarden-url]`
2. Create new item:
   - **Type:** Secure Note or Login
   - **Name:** `Gitea - Pokerole Scoped Token (Claudius)`
   - **Folder:** API Keys or Credentials
   - **Notes/Password:** Paste the token
   - **Custom Fields:**
     - `Scope`: Pokerole repos only (read/write)
     - `Created`: 2026-02-17
     - `Purpose`: Claudius access to Pokerole project
     - `Repositories`: pokerole-project, pokerole-data, pokerole-tools, pokerole-docs

3. **Add to Organization** (if sharing with Meg):
   - Click "Share" or "Collections"
   - Add to shared Firefrost organization
   - Grant read access to Meg

4. Save the item

### Step 7: Test Token Access

**Test 1: Verify access to Pokerole repos**

```bash
# Try to list Pokerole project repo
curl -H "Authorization: token NEW_SCOPED_TOKEN" \
  https://git.firefrostgaming.com/api/v1/repos/[username]/pokerole-project

# Should return repo details (success)
```

**Test 2: Verify NO access to Firefrost repos**

```bash
# Try to access Firefrost operations manual
curl -H "Authorization: token NEW_SCOPED_TOKEN" \
  https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual

# Should return 404 or 403 error (success - no access)
```

**Test 3: Verify write access to Pokerole**

```bash
# Try to create a test issue in Pokerole project
curl -X POST \
  -H "Authorization: token NEW_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test scoped token","body":"Testing write access"}' \
  https://git.firefrostgaming.com/api/v1/repos/[username]/pokerole-project/issues

# Should create issue successfully
# Then delete the test issue via Gitea web interface
```

### Step 8: Update Pokerole Session Start Prompt

1. Navigate to Pokerole project repository
2. Open: `misc-docs/SESSION-START-PROMPT.md` (or wherever session instructions are)
3. Find the section with the Gitea token
4. Replace the old master token with the new scoped token
5. Update any documentation that references the token
6. Add a note:

```markdown
**Gitea API Token (Scoped)**
This token provides access ONLY to Pokerole repositories:
- pokerole-project
- pokerole-data
- pokerole-tools
- pokerole-docs

This token does NOT have access to Firefrost Gaming infrastructure.
```

7. Commit the changes

### Step 9: Verify Claudius Can Access Pokerole

**Next time Claudius (Pokerole Claude instance) starts:**

1. Claudius should use the new scoped token
2. Verify Claudius can:
   - Clone Pokerole repos
   - Read files
   - Make commits
   - Push changes
3. Verify Claudius CANNOT:
   - Access Firefrost repos
   - List other organizations
   - Access admin functions

### Step 10: Revoke Old Master Token (Optional but Recommended)

**If you're confident the scoped token works:**

1. Return to Gitea → Settings → Applications
2. Find the old master token that Pokerole was using
3. Click **"Delete"** or **"Revoke"**
4. Confirm deletion

**⚠️ WARNING:** Only do this AFTER confirming scoped token works for Pokerole!

---

## Verification Checklist

After implementation, verify:

- [ ] Scoped token created in Gitea
- [ ] Token scoped to repository read/write ONLY
- [ ] Token stored in Vaultwarden
- [ ] Token tested: CAN access Pokerole repos
- [ ] Token tested: CANNOT access Firefrost repos
- [ ] Pokerole session prompt updated with new token
- [ ] Claudius tested with new token (successful)
- [ ] Old master token revoked (optional)
- [ ] Documentation updated

---

## Security Benefits

**Before (Master Token):**
- ❌ Full access to all repos
- ❌ Can access Firefrost infrastructure
- ❌ Can modify any organization
- ❌ Single point of compromise
- ❌ Relies on "honor system"

**After (Scoped Token):**
- ✅ Access limited to 4 Pokerole repos only
- ✅ Cannot see or access Firefrost infrastructure
- ✅ Cannot modify organizations or settings
- ✅ Compromise isolated to Pokerole only
- ✅ Technical enforcement (Iron Wall principle)

---

## Troubleshooting

### Token doesn't work for Pokerole repos

**Check:**
- Token has `repo:read` and `repo:write` scopes
- Token is correctly scoped to the right repos/organization
- Token was copied correctly (no extra spaces)
- Token hasn't been revoked

**Solution:**
```bash
# Test token directly
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.firefrostgaming.com/api/v1/user

# Should return user info if token is valid
```

### Token can still access Firefrost repos

**This means scoping failed. Check:**
- Did you select specific repos or just general scopes?
- Is the token user an admin? (Admin tokens may bypass scoping)
- Did you test with the correct token?

**Solution:**
- Revoke the token
- Create a new one with stricter scoping
- Consider creating a separate "pokerole-bot" user account with limited permissions

### Gitea doesn't support per-repo scoping

**Alternative approaches:**

**Option 1: Organization-based scoping**
1. Create "Pokerole" organization in Gitea
2. Move 4 Pokerole repos into that organization
3. Create token scoped to that organization only

**Option 2: Separate user account**
1. Create new Gitea user: `pokerole-bot`
2. Grant `pokerole-bot` access ONLY to Pokerole repos
3. Generate token for `pokerole-bot` user
4. Use that token in Pokerole project

### Claudius loses access after token change

**Check:**
- Is the new token in the session start prompt?
- Did Claudius try to use the old token?
- Is there a caching issue?

**Solution:**
- Verify token in session start docs is the new scoped token
- Clear any cached credentials
- Test token manually before giving to Claudius

---

## Maintenance

**Token Rotation:**
- Recommended: Rotate scoped tokens every 6-12 months
- Process: Create new scoped token, update docs, revoke old token

**Audit Access:**
- Periodically check Gitea access logs
- Verify Claudius is only accessing Pokerole repos
- Look for any unexpected access patterns

**Review Scopes:**
- If Pokerole needs change (new repos, different permissions), update token scopes
- Re-test after any scope changes

---

## Rollback Plan

If scoped token causes issues:

1. Keep the old master token reference available (don't delete immediately)
2. Test scoped token thoroughly before revoking old token
3. If problems arise:
   - Update session prompt back to old token
   - Fix scoped token issues
   - Re-test before switching again

---

## Future Enhancements

**Potential improvements:**
- Separate Gitea user accounts per project
- Token expiration and auto-rotation
- Audit logging of token usage
- Fine-grained permissions per repository
- Webhook-based access monitoring

---

## Related Tasks

- **Vaultwarden Setup** (prerequisite) - Must be operational
- **Command Center Security Hardening** - Part of overall security posture
- **Department Structure & Access Control** - Similar scoping for Wiki.js

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

---

**Document Status:** COMPLETE  
**Ready for Implementation:** When Vaultwarden is operational  
**Estimated Time:** 15 minutes  
**Risk Level:** LOW (non-destructive, easy rollback)