Organizations and Repository RBAC

This document maps the current organizations and repository RBAC implementation in open-git. It is written for maintainers who need to understand how URL ownership, Stack Auth teams, cached organization membership, repository grants, gateways, and UI/API authorization fit together.

Executive Summary

The system now separates repository ownership from user profiles by introducing namespaces. A namespace is the canonical URL owner for repositories and can be either a user namespace or an organization namespace.

Organizations are backed by Stack Auth teams. Stack remains the source of truth for team identity, team membership, and team-level organization permissions. open-git stores a local organization row, a namespace row, and a cached membership row so repository authorization can be evaluated quickly by the web app and by standalone gateways.

Repository authorization is capability-based. The web app computes effective access with getRepositoryAccess, which merges:

1. Public repository baseline capabilities.
2. Personal namespace owner privileges.
3. Organization admin privileges.
4. Direct per-repository grants.

For organization repositories, direct per-repository grants only apply while the user is an active member of the owning organization, unless the user is an org admin. This prevents stale repo grants from continuing to authorize after organization removal.

Source Of Truth Files

Terms

Identity And Ownership Model

Repository URLs use namespaces, not user profiles.

/:namespaceSlug/:repositorySlug

The namespace slug is globally unique across users and organizations.

user_profiles.username
        |
        | user namespace
        v
namespaces(kind = "user", slug, user_profile_id)
        |
        | owns
        v
repositories(owner_namespace_id, slug)

Stack team
        |
        | mirrored by
        v
organizations(stack_team_id, namespace_id)
        |
        | org namespace
        v
namespaces(kind = "org", slug)
        |
        | owns
        v
repositories(owner_namespace_id, slug)

Important Ownership Invariant

repositories.ownerNamespaceId is the authority for ownership and URLs.

repositories.ownerProfileId is no longer the owner authority. It is nullable audit metadata for the profile that created the repository. Code that needs the repository owner should use ownerNamespaceId or helpers that join through namespaces.

Owner Resolution

getRepositoryByOwnerAndSlug(ownerUsername, slug) joins repositories to namespaces:

repositories.owner_namespace_id = namespaces.id
namespaces.slug = ownerUsername
repositories.slug = slug

It returns repository data plus:

The name ownerUsername is legacy naming. For org-owned repositories it is the organization namespace slug, not a user username.

Database Model

namespaces

Canonical owner identity for URLs and repository ownership.

Indexes:

organizations

Local open-git organization record linked to a Stack team.

Indexes:

organization_memberships

Local cache of Stack team membership and derived org capabilities.

Indexes:

repositories

Repository ownership now points to namespaces.

Indexes:

repository_access_grants

Direct per-user repository grants.

Important behavior:

repository_invitations

Email invitations for repository access.

Important behavior:

Capability Vocabulary

Repo capabilities live in apps/web/lib/repository-permissions.ts.

Repository Capabilities

Repository Capability Dependencies

Capabilities are dependency-expanded in the web app before storage or evaluation.

Repository Presets

Presets are UI-level groupings for common access levels.

Public Baselines

Public repositories automatically grant baseline capabilities.

Signed-in public users can create issues, create pull requests, review pull requests, and post in Campfire if Campfire is enabled. They cannot push branches, change settings, manage permissions, manage CI, merge PRs, or delete repositories unless another rule grants those capabilities.

Organization Capabilities

Org capabilities are cached in organization_memberships.capabilities.

Stack Permission Mapping

Stack Auth remains the source of truth for team permissions.

Access Evaluator

The web app's central access evaluator is:

getRepositoryAccess(profile, repository) -> RepositoryAccess

Return shape:

Evaluation Order

The implementation effectively evaluates access like this:

start with empty capability set

if repository.visibility == "public":
  if profile exists:
    add signed-in public baseline
  else:
    add anonymous public baseline

load owner namespace and linked organization, if any

if no profile:
  return public baseline result

if namespace.kind == "user" and namespace.user_profile_id == profile.id:
  mark personal owner
  add all repo capabilities

if repository is org-owned:
  load active organization membership for profile
  if membership capabilities include org.admin:
    mark org admin
    add all repo capabilities

directGrantApplies =
  repository is not org-owned
  OR profile has active org membership
  OR profile is org admin

if directGrantApplies:
  load repository_access_grants row for repo/profile
  normalize and dependency-expand capabilities
  add them to the effective set

return sorted/structured access result

Access Source Precedence

There is no deny rule. Effective access is the union of all applicable allow sources.

Because there is no deny rule, a user can retain access through public baseline even if a direct grant is removed. Removing a grant only removes the capabilities that came from that grant.

Namespace Flows

User Onboarding And User Namespace Creation

Entrypoints:

Flow:

Stack user signs in
  -> upsert user_profiles by stack_user_id
  -> if username exists:
       sync current user's Stack team memberships
       accept pending repository invitations for primary email
       ensure Stack client metadata reflects onboarding state
  -> if username missing:
       redirect to onboarding

When a username is selected:

setUserProfileUsername(user, username)
  -> upsert user profile
  -> transaction:
       check namespaces.slug for collision
       update user_profiles.username
       insert/update namespaces(kind = "user", user_profile_id = profile.id)

Collision behavior:

Organization Creation

Entrypoint:

createOrganizationFromForm

Flow:

ensure user is onboarded
  -> normalize display name and slug
  -> validate slug using namespace/user slug rules
  -> check global namespace availability
  -> create Stack team
  -> write openGitNamespaceSlug into Stack metadata
  -> create local namespace(kind = "org")
  -> create local organizations row with stack_team_id
  -> create creator membership with:
       org.member
       org.admin
       org.create_repositories
       org.manage_repositories
  -> redirect to /:orgSlug

Failure cleanup:

Organization Membership Sync

Two sync paths exist:

Current-user sync:

user.listTeams()
  -> find local organizations with matching stack_team_id
  -> for each linked org:
       derive capabilities from Stack permissions
       upsert active organization_memberships row
  -> deactivate this Stack user's memberships for orgs no longer returned
  -> revoke org repository grants for deactivated local profile IDs

Full org sync:

stackServerApp.getTeam(organization.stackTeamId)
  -> team.listUsers()
  -> update local organization and namespace display metadata
  -> match Stack users to local user_profiles by stack_user_id
  -> upsert active memberships for returned users
  -> deactivate memberships for users no longer in Stack team
  -> revoke org repository grants for deactivated local profile IDs

Permission derivation:

start with org.member
if Stack user has $update_team:
  add org.admin
if Stack user has org:create_repositories:
  add org.create_repositories
if Stack user has org:manage_repositories:
  add org.manage_repositories

Organization Settings

Entrypoints:

Settings visibility:

Repository Flows

Repository Creation

Entrypoint:

createRepositoryFromForm

Flow:

ensure user is onboarded
  -> normalize repo slug, description, visibility
  -> require ownerNamespaceId from form
  -> validate repo slug
  -> canCreateRepositoryInNamespace(namespaceId, profileId, user)
  -> check repo slug uniqueness inside namespace
  -> storageId = `${namespace.slug}/${repoSlug}`
  -> insert repositories:
       ownerNamespaceId = namespace.id
       ownerProfileId = creator profile id
       slug, description, visibility, storageId, defaultBranch
  -> create backing code-storage repo
  -> optionally create README initial commit
  -> index repo immediately or enqueue index job
  -> redirect to /:namespaceSlug/:repoSlug

Create permission by namespace kind:

Storage note:

storageId includes the namespace slug. Org slug renames are disabled in the UI because storage IDs currently use slugs.

Repository Read Pages

Most repository pages follow this pattern:

getRepositoryByOwnerAndSlug(username, repository)
  -> getOnboardingStatus()
  -> getRepositoryAccess(profile, repository)
  -> require repo.view
  -> render or 404

Examples:

Repository Settings

Repository settings use separate capabilities for separate actions.

Settings page refresh behavior:

If the viewer can manage permissions on an org repo, the settings page attempts a full Stack team sync before rendering grants. It then recomputes repository access. This keeps cached org memberships close to Stack before access is managed.

Repository Grants

Grant flow:

grantRepositoryAccessFromForm
  -> ensure onboarded
  -> resolve repository by namespace slug and repo slug
  -> require repo.permissions.manage
  -> findRepositoryGrantTarget(identifier, repository)
  -> derive capabilities from preset and explicit checkboxes
  -> normalize and expand capabilities
  -> upsert repository_access_grants row
  -> revalidate settings page

Grant target rules:

Direct grant applicability at access-check time:

Repository Invitations

Invitation flow for personal repositories:

createRepositoryInvitationFromForm
  -> require repo.permissions.manage
  -> reject if repository is org-owned
  -> normalize email
  -> normalize capabilities
  -> create or update pending repository_invitations row

on onboarded session load:
  -> acceptPendingRepositoryInvitationsForUser(primaryEmail, profileId)
  -> find unaccepted/unrevoked invitations by normalized email
  -> grant repository access to this profile
  -> mark invitations accepted

Org-owned repositories intentionally reject email invitations. The intended flow is:

invite user to Stack team
  -> sync org membership into open-git
  -> grant repository access to active org member

Issues

Pull Requests

canViewPullRequestRepositories requires repo.view on both source and target repositories. API routes for PR JSON/files/diffs use it to avoid leaking private source repository data.

Forks

Forking requires repo.git.read on the source repository. Public repositories grant this to anonymous users as a read baseline, but the fork action itself requires onboarding because a fork needs an owner namespace.

CI

Campfire

Web app behavior:

Gateway behavior:

The Campfire gateway uses raw SQL and checks:

if repository is public:
  allow authenticated token holder to write
else if personal owner:
  allow
else if org admin:
  allow
else if org repo and not active member:
  deny
else if direct grant includes repo.campfire.write:
  allow
else:
  deny

The gateway only receives authenticated websocket/session context, so public repository write means "any authenticated user", not anonymous write.

Gateway Authorization

Gateways cannot import the web app's Drizzle helpers, so they reimplement the relevant checks in SQL.

Git Gateway

Repository resolution:

resolveRepository(sql, ownerUsername, slug)
  -> join repositories to namespaces
  -> namespaces.slug = ownerUsername
  -> repositories.slug = slug

Token authentication:

authenticateGitToken(sql, username, token)
  -> sha256(token)
  -> match user_profiles.username
  -> match git_access_tokens.token_hash
  -> require not revoked
  -> require not expired
  -> update last_used_at

Read/write checks:

SQL capability logic:

if repository.visibility == "public" and capability == "repo.git.read":
  allow
if no actor:
  deny
load namespace and organization
if user namespace owner:
  allow
if active org member with org.admin:
  allow
if org-owned and actor is not active org member:
  deny
if direct grant JSON contains exact capability:
  allow
else:
  deny

Important gateway caveat:

The gateway checks JSONB for the exact capability string. Web-created grants are normalized and dependency-expanded before storage, so implied capabilities should be present. Manually inserted grants that omit dependencies may behave differently in the gateway than in the web evaluator.

Campfire Gateway

The Campfire gateway mirrors the relevant subset of repository access for posting messages. It checks public visibility, personal ownership, active org admin status, active org membership, and direct repo.campfire.write grants.

It also resolves mentioned issues and PRs by joining referenced repositories through namespaces, so #123 style references across org/user namespaces resolve against namespace slugs rather than user profile usernames.

UI Mapping

Account Settings

Owner Pages

Repository listing behavior:

Repository Settings Panels

The settings page computes one RepositoryAccess object and passes booleans to forms:

canViewSettings is derived from any of:

repo.settings.manage
repo.permissions.manage
repo.ci.manage
repo.delete

Migration Sequence

0021_namespaces_and_organizations.sql

Purpose:

1. Create namespaces.
2. Create organizations.
3. Backfill one user namespace for every profile with a username.
4. Add repositories.owner_namespace_id.
5. Backfill repository namespace ownership from existing owner_profile_id.
6. Make owner_namespace_id required.
7. Add namespace/org/repository ownership indexes.

Backfill mapping:

user_profiles.username -> namespaces.slug
user_profiles.id -> namespaces.user_profile_id
repositories.owner_profile_id -> namespaces.user_profile_id
repositories.owner_namespace_id -> namespaces.id

0022_repository_permissions.sql

Purpose:

1. Create organization_memberships.
2. Create repository_access_grants.
3. Create repository_invitations.
4. Add FKs and indexes for membership, grants, and invites.

0023_repository_owner_audit_metadata.sql

Purpose:

1. Drop old owner/slug index.
2. Relax repositories.owner_profile_id from required to nullable.
3. Re-add FK with ON DELETE SET NULL.
4. Add repositories_owner_profile_idx.

End-To-End Flow Examples

Flow: Create An Organization Repository

User opens /repositories/new
  -> page calls listRepositoryOwnerNamespacesForUser
  -> ensure personal user namespace exists
  -> list Stack teams for user
  -> find linked open-git organizations
  -> call canCreateRepositoryInNamespace for each org namespace
  -> show personal namespace and creatable org namespaces

User submits create form with ownerNamespaceId = org namespace
  -> createRepositoryFromForm
  -> canCreateRepositoryInNamespace checks live Stack permissions
  -> insert repository with ownerNamespaceId = org namespace id
  -> ownerProfileId = creator profile id
  -> storageId = orgSlug/repoSlug
  -> create code-storage repository
  -> redirect to /orgSlug/repoSlug

Flow: Grant Write Access To An Org Repo

Org admin opens /org/repo/settings
  -> getRepositoryAccess sees org.admin
  -> repo.permissions.manage is present
  -> settings page syncs organization membership from Stack
  -> admin enters target username and Write preset

grantRepositoryAccessFromForm
  -> require repo.permissions.manage
  -> findRepositoryGrantTarget
       -> target profile must exist
       -> target profile must be active member of owning org
  -> capabilitiesForPreset("write")
  -> normalizeRepoCapabilities
  -> upsert repository_access_grants row

Target user next accesses repo
  -> getRepositoryAccess sees active org membership
  -> direct grant applies
  -> capabilities include write preset

Flow: Remove A User From An Organization

Org admin removes user in /org/settings
  -> removeOrganizationMemberFromForm requires Stack $remove_members
  -> team.removeUser(stackUserId)
  -> deactivateOrganizationMember locally
  -> revokeOrganizationRepositoryGrants for that profile
  -> syncOrganizationMembershipsFromStackTeam
  -> revalidate org pages

Removed user accesses private org repo
  -> getRepositoryAccess sees no active membership
  -> directGrantApplies is false
  -> no private baseline
  -> repo.view missing
  -> 404

Flow: Public External Contribution

Signed-in user opens public repo
  -> public signed-in baseline applies
  -> capabilities include repo.issue.create and repo.pull.create
  -> user can create issue or PR
  -> user cannot push to the target repo without repo.git.write

For PR creation
  -> target requires repo.pull.create
  -> source repository requires repo.git.write
  -> user usually selects their fork/source repo

Flow: Git Clone And Push

git clone /org/private-repo
  -> gateway resolves repo through namespaces.slug
  -> public read shortcut does not apply
  -> token auth must succeed with repo:read
  -> actorHasRepositoryCapability(..., repo.git.read)
       -> personal owner, org admin, or exact direct grant allows

git push /org/private-repo
  -> token auth must succeed with repo:write
  -> actorHasRepositoryCapability(..., repo.git.write)
       -> personal owner, org admin, or exact direct grant allows

Flow: Pending Personal Repo Invitation

Owner invites email to personal repo
  -> repository_invitations row is created

Invitee signs in and completes onboarding
  -> getOnboardingStatus sees onboarded profile
  -> acceptPendingRepositoryInvitationsForUser(primaryEmail, profile.id)
  -> grantRepositoryAccess creates direct grant
  -> invitation is marked accepted

Edge Cases And Expected Outcomes

Ownership And Slugs

Public And Private Visibility

Organization Membership

Direct Grants

Invitations

Pull Requests

Gateways

Settings And Destructive Actions

Implementation Notes And Risks

Gateways Duplicate Access Logic

The Git and Campfire gateways reimplement access checks in raw SQL. This is necessary because they are separate apps, but it means any future change to getRepositoryAccess must be mirrored in gateway SQL if it affects git or Campfire behavior.

Checklist for future capability changes:

1. Update repoCapabilities.
2. Update labels, dependencies, and presets.
3. Update settings/action gating if the capability gates UI.
4. Update gateway SQL if the capability is used outside the web app.
5. Update tests.
6. Check migrations/seed data if stored grants need new defaults.

Direct Grant Dependency Expansion

The web helper expands dependencies before storing grants. The gateway checks JSONB for exact capability strings. Keep using grantRepositoryAccess and normalizeRepoCapabilities for all grant writes.

Organization Membership Cache Drift

Stack is the authority, but open-git uses cached membership rows for repo auth. The cache is refreshed:

1. During onboarded session loads for the current user.
2. During org settings views/actions for the full organization.

If Stack changes happen out of band, cached rows may lag until one of those sync points runs. Deactivation paths are conservative: if Stack team listing fails, local memberships may be deactivated. Normal member removal and successful sync deactivation paths also revoke org repo grants when a local profile is known. In all cases, inactive memberships cause org repo grants to be ignored by the access evaluator.

Public Baseline Is Broad For Signed-In Users

Signed-in users get repo.issue.create, repo.pull.create, repo.pull.review, and repo.campfire.write on public repositories. This is a product decision encoded in signedInPublicCapabilities.

Legacy Owner Helpers Need Care

Most owner resolution now uses namespaces. Any helper that still accepts ownerProfileId should be reviewed before use with org repositories. In particular, ownerProfileId cannot answer "who owns this repository?" for org repos.

Test Scenarios To Keep Covered

Unit Tests

Existing coverage:

Recommended additional unit/integration cases:

Manual Flow Checks

Quick Reference: Capability To Surface

Quick Reference: Flow Decisions