From 2a5d71c637ec0212b685facdd117ed61956a7c70 Mon Sep 17 00:00:00 2001
From: Claude <claude@firefrostgaming.com>
Date: Tue, 17 Feb 2026 17:14:34 +0000
Subject: [PATCH] docs: Add deployment guide for Scoped Gitea Token

Created comprehensive guide for creating scoped Gitea token for Pokerole project:
- Step-by-step token creation in Gitea UI
- Proper scope selection (repo read/write only)
- Vaultwarden storage procedure
- Testing procedures (verify access/no-access)
- Session prompt update instructions
- Security benefits comparison
- Troubleshooting common issues
- Rollback plan

Implements Iron Wall principle: enforce boundaries technically,
not through honor system. Isolates Pokerole project from
Firefrost infrastructure.

Task: Scoped Gitea Token (Tier 1)
FFG-STD-002 compliant
---
 .../scoped-gitea-token/deployment-guide.md    | 389 ++++++++++++++++++
 1 file changed, 389 insertions(+)
 create mode 100644 docs/tasks/scoped-gitea-token/deployment-guide.md

diff --git a/docs/tasks/scoped-gitea-token/deployment-guide.md b/docs/tasks/scoped-gitea-token/deployment-guide.md
new file mode 100644
index 0000000..b09a84d
--- /dev/null
+++ b/docs/tasks/scoped-gitea-token/deployment-guide.md
@@ -0,0 +1,389 @@
+# 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)