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):

• repo:read - Read access to repositories
• 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:

• pokerole-project
• pokerole-data
• pokerole-tools
• 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

# 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

# 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

# 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:

**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:

# 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)