Implement layered permission architecture for genesis ecosystem

[the-gigi]

Context

Genesis-bootstrapped dev systems currently rely on PATs for cross-org access. This works but has problems:

• PATs are tied to a person, not a system
• PATs can't be cleanly scoped per-project
• No clean audit trail (all actions appear as the PAT owner)
• If the human revokes the PAT, all projects break simultaneously

Proposed: Three-layer permission model

See BRAINSTORMING.md > Permission Architecture for the full design.

Layer 1: Genesis GitHub App — shared, minimal permissions (read code, write issues). Already exists as genesis-dev-bot.

Layer 2: Per-project GitHub Apps — each dev system gets its own App scoped to its specific needs. repo-guardian would get an App with contents:write, pull_requests:write, security_events:read. Other projects get only what they need.

Layer 3: Bootstrap PAT — human-held, used only for operations Apps can't do (creating other Apps, managing installations). Never used for day-to-day.

Tasks

• Document exact permissions needed by genesis App (Layer 1) vs current state
• Define the App creation flow: what does genesis output when a new project needs an App?
• Create an issue template / checklist for "set up project App" that guides the human
• Update genesis bootstrapping to include the App request issue in the initial scaffold
• Migrate repo-guardian from PAT to dedicated App (see Sayfan-AI/repo-guardian tracking issue)
• Consider org-level secret for bootstrap PAT so all repos can access it
• Remove "Security boundaries" open question from BRAINSTORMING.md (now answered)

Notes

• GitHub Apps and PATs cannot be created programmatically — initial setup always needs a human
• Installation tokens (short-lived, scoped) can be generated programmatically once the App is installed
• This is infrastructure work that benefits all current and future genesis projects

[the-gigi]

Tracking issue for repo-guardian migration: Sayfan-AI/repo-guardian#23

[the-gigi]

Revised approach: Single App with per-token permission scoping

After investigating GitHub's limits (100 App registrations per user/org, no programmatic create/delete of App registrations), the per-project App model won't scale. With genesis designed to bootstrap many projects, we'd hit the 100-App ceiling quickly.

New design: One genesis App, scoped tokens per project

GitHub's POST /app/installations/{id}/access_tokens endpoint accepts both repositories and permissions parameters. The token's permissions must be equal to or less than the App's registered permissions — so we register one App with the union of all permissions, and each project mints a narrowly scoped 1-hour token at runtime.

Genesis App registration (broad — the ceiling):

• contents: write, pull_requests: write, issues: write, security_events: read, actions: read, metadata: read, etc.

repo-guardian token (narrow — what it actually gets):

- uses: actions/create-github-app-token@v1
  with:
    app-id: ${{ secrets.GENESIS_APP_ID }}
    private-key: ${{ secrets.GENESIS_APP_PRIVATE_KEY }}
    permission-contents: write
    permission-pull-requests: write
    permission-security-events: read
    permission-issues: write

A read-only auditor project would get:

    permission-contents: read
    permission-metadata: read

Benefits

• 1 App — no scaling limit, no per-project App ceremony
• Least-privilege per project — each project declares exactly what it needs
• 1-hour token lifetime — no long-lived credentials floating around
• Single install per org — install once on the-gigi and Sayfan-AI, all projects use it
• Clean audit trail — all actions appear as genesis-dev-bot[bot]

Risk: private key leak

If the App's private key leaks, an attacker could mint a max-permission token. Mitigations:

• Store private key as org-level encrypted secret (not per-repo)
• Rotate the key periodically
• Installation still acts as a second gate (App must be installed on target repo)

Updated tasks

• Audit genesis App's current registered permissions — ensure it covers what all projects need
• Update genesis App permissions if needed (add security_events: read, etc.)
• Define a convention for how projects declare their required permissions (e.g., .genesis/config.toml)
• Update genesis bootstrapping to generate workflows with scoped permission-* inputs
• Migrate repo-guardian to use scoped tokens instead of REPO_GUARDIAN_PAT (Sayfan-AI/repo-guardian#23)
• Store genesis App private key as org-level secret (accessible to all repos)
• Document key rotation procedure

This supersedes the original three-layer model. The per-project App layer is replaced by per-token scoping from a single App.