tenseleyflow/shithub / 0f2f494

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+// Package policy is the single source of truth for "who can do what".

+// Every authorization decision in shithub flows through Can(); handlers

+// must not read ownership, visibility, or collaborator state inline.

+//

+// The package shape:

+//

+//	Actor      — who is asking (anonymous, suspended, site-admin etc.)

+//	Resource   — what they want to act on (a RepoRef today; org/team later)

+//	Action     — a constant from the registry below

+//	Can(...)   — the only public decision function

+//	Decision   — { Allow bool; Reason string }

+//

+// Reasons are for logs and admin debugging, never for end-user error

+// strings — they can leak existence.

+package policy

+

+// Action is a constant identifier for an operation against some resource.

+// Adding a new action: add the const, register a default rule in

+// policy.Can, and extend the test matrix. The matrix test asserts that

+// every Action has explicit coverage for every Actor archetype.

+type Action string

+

+// Repo-level actions.

+const (

+	ActionRepoRead  Action = "repo:read"

+	ActionRepoWrite Action = "repo:write"

+	ActionRepoAdmin Action = "repo:admin"

+

+	ActionRepoSettingsGeneral       Action = "repo:settings:general"

+	ActionRepoSettingsCollaborators Action = "repo:settings:collaborators"

+	ActionRepoSettingsBranches      Action = "repo:settings:branches"

+

+	ActionRepoArchive    Action = "repo:archive"

+	ActionRepoDelete     Action = "repo:delete"

+	ActionRepoTransfer   Action = "repo:transfer"

+	ActionRepoVisibility Action = "repo:visibility"

+)

+

+// Issue-level actions. (Issue resources arrive in S18; S15 just ships

+// the registry entries so the matrix is exhaustive from day one.)

+const (

+	ActionIssueRead    Action = "issue:read"

+	ActionIssueCreate  Action = "issue:create"

+	ActionIssueComment Action = "issue:comment"

+	ActionIssueClose   Action = "issue:close"

+	ActionIssueLabel   Action = "issue:label"

+	ActionIssueAssign  Action = "issue:assign"

+)

+

+// Pull-request actions. (Pull resources arrive in S19; same note as above.)

+const (

+	ActionPullRead   Action = "pull:read"

+	ActionPullCreate Action = "pull:create"

+	ActionPullMerge  Action = "pull:merge"

+	ActionPullReview Action = "pull:review"

+	ActionPullClose  Action = "pull:close"

+)

+

+// Per-user social actions.

+const (

+	ActionStarCreate Action = "star:create"

+	ActionForkCreate Action = "fork:create"

+)

+

+// AllActions is the canonical list. The matrix test iterates this so a

+// new Action that's not registered above will fail coverage and force

+// the author to think through every actor archetype.

+var AllActions = []Action{

+	ActionRepoRead, ActionRepoWrite, ActionRepoAdmin,

+	ActionRepoSettingsGeneral, ActionRepoSettingsCollaborators, ActionRepoSettingsBranches,

+	ActionRepoArchive, ActionRepoDelete, ActionRepoTransfer, ActionRepoVisibility,

+	ActionIssueRead, ActionIssueCreate, ActionIssueComment, ActionIssueClose, ActionIssueLabel, ActionIssueAssign,

+	ActionPullRead, ActionPullCreate, ActionPullMerge, ActionPullReview, ActionPullClose,

+	ActionStarCreate, ActionForkCreate,

+}

+

+// isWriteAction returns true when the action mutates state. Used by the

+// suspended-user gate (suspended accounts can read but not write).

+func isWriteAction(a Action) bool {

+	switch a {

+	case ActionRepoRead, ActionIssueRead, ActionPullRead:

+		return false

+	default:

+		return true

+	}

+}

+

+// isReadAction is the inverse, broken out for readability at call sites

+// that branch on intent rather than on the absence of writes.

+func isReadAction(a Action) bool { return !isWriteAction(a) }

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+// Actor is the authenticated identity asking for a decision. The web

+// layer constructs one from middleware.CurrentUserFromContext + a

+// suspended/admin check. SSH and HTTP git transports build their own

+// from the resolved auth principal.

+//

+// An anonymous request has UserID == 0; IsAnonymous == true. Convention

+// is that callers fill IsAnonymous explicitly even when UserID == 0

+// implies it — duplication is cheap and keeps the boolean visible at

+// every call site.

+type Actor struct {

+	UserID      int64

+	Username    string

+	IsAnonymous bool

+	IsSuspended bool

+	IsSiteAdmin bool

+}

+

+// AnonymousActor returns the canonical anonymous Actor. Use in tests

+// and at unauthenticated entrypoints.

+func AnonymousActor() Actor {

+	return Actor{IsAnonymous: true}

+}

+

+// UserActor wraps a logged-in user. Suspension and site-admin flags

+// must be loaded from the DB by the caller — the policy package does

+// not query users on its own to keep the decision pure.

+func UserActor(userID int64, username string, suspended, siteAdmin bool) Actor {

+	return Actor{

+		UserID:      userID,

+		Username:    username,

+		IsSuspended: suspended,

+		IsSiteAdmin: siteAdmin,

+	}

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+import (

+	reposdb "github.com/tenseleyFlow/shithub/internal/repos/sqlc"

+)

+

+// NewRepoRefFromRepo converts a reposdb.Repo into a policy RepoRef.

+// Used at the boundary between data-access and policy code: any caller

+// that already has a Repo row passes it in, and policy never imports

+// reposdb at the rule layer.

+func NewRepoRefFromRepo(r reposdb.Repo) RepoRef {

+	ref := RepoRef{

+		ID:         r.ID,

+		Visibility: string(r.Visibility),

+		IsArchived: r.IsArchived,

+		IsDeleted:  r.DeletedAt.Valid,

+	}

+	if r.OwnerUserID.Valid {

+		ref.OwnerUserID = r.OwnerUserID.Int64

+	}

+	if r.OwnerOrgID.Valid {

+		ref.OwnerOrgID = r.OwnerOrgID.Int64

+	}

+	return ref

+}

+

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+import (

+	"context"

+	"sync"

+)

+

+// cacheKey is the per-(actor, repo) composite the cache memoizes

+// effective role lookups against. The cache is request-scoped — created

+// in WithCache, dropped when the context goes out of scope.

+type cacheKey struct {

+	actorUserID int64

+	repoID      int64

+}

+

+// requestCache holds the memo. The lock is held across DB lookups so

+// concurrent goroutines reading the same key (rare in practice — a

+// single request pipeline is typically sequential) coalesce into one

+// query.

+type requestCache struct {

+	mu    sync.Mutex

+	roles map[cacheKey]Role

+}

+

+type cacheCtxKey struct{}

+

+// WithCache returns a derived context that carries a per-request memo.

+// Wire this into the request middleware once, and every Can() call on

+// downstream handlers benefits from de-duplication. Calling Can with a

+// context that has no cache is supported — the lookup just runs every

+// time.

+func WithCache(ctx context.Context) context.Context {

+	c := &requestCache{roles: make(map[cacheKey]Role, 4)}

+	return context.WithValue(ctx, cacheCtxKey{}, c)

+}

+

+// cacheFromContext returns the cache or nil. Internal helper — Can()

+// degrades gracefully when nil.

+func cacheFromContext(ctx context.Context) *requestCache {

+	c, _ := ctx.Value(cacheCtxKey{}).(*requestCache)

+	return c

+}

+

+// InvalidateRepo drops cached entries for one repo. Call this from

+// handlers that mutate collaborator state and then re-check policy

+// inside the same request.

+func InvalidateRepo(ctx context.Context, repoID int64) {

+	c := cacheFromContext(ctx)

+	if c == nil {

+		return

+	}

+	c.mu.Lock()

+	defer c.mu.Unlock()

+	for k := range c.roles {

+		if k.repoID == repoID {

+			delete(c.roles, k)

+		}

+	}

+}

+

+// cacheGet returns (role, true) when present.

+func cacheGet(c *requestCache, k cacheKey) (Role, bool) {

+	if c == nil {

+		return RoleNone, false

+	}

+	c.mu.Lock()

+	defer c.mu.Unlock()

+	r, ok := c.roles[k]

+	return r, ok

+}

+

+// cachePut stores a role. Safe to call with c == nil.

+func cachePut(c *requestCache, k cacheKey, r Role) {

+	if c == nil {

+		return

+	}

+	c.mu.Lock()

+	defer c.mu.Unlock()

+	c.roles[k] = r

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+import (

+	"context"

+	"errors"

+	"net/http"

+

+	"github.com/jackc/pgx/v5"

+	"github.com/jackc/pgx/v5/pgxpool"

+

+	policydb "github.com/tenseleyFlow/shithub/internal/auth/policy/sqlc"

+)

+

+// Deps wires the policy package against Postgres. Construct once at

+// boot and keep alive for the process lifetime.

+type Deps struct {

+	Pool *pgxpool.Pool

+}

+

+// DenyCode is a typed enum carried on a deny Decision so handlers can

+// pick a friendly user-facing message without re-deriving the reason

+// from the resource. Read this; do not parse Decision.Reason.

+type DenyCode int

+

+const (

+	// DenyNone is the zero value used on an allow Decision.

+	DenyNone DenyCode = iota

+	DenyRepoDeleted

+	DenyActorSuspended

+	DenyArchived

+	DenyVisibility    // anonymous-or-non-collab on a private repo

+	DenyRoleTooLow    // logged-in but role insufficient

+	DenyAnonymous     // login required (e.g. star/fork)

+	DenyDBError

+)

+

+// Decision is the verdict from Can. Allow is the only field handlers

+// should branch on for control flow. DenyCode lets the handler pick a

+// user-facing message; Reason is for logs and tests, never end-user

+// surfaces — it can carry implementation details that constitute

+// existence leaks.

+type Decision struct {

+	Allow  bool

+	Reason string

+	Code   DenyCode

+}

+

+// allow / deny are convenience constructors used by the rule engine

+// below to keep each branch one short line.

+func allow(reason string) Decision { return Decision{Allow: true, Reason: reason} }

+func deny(code DenyCode, reason string) Decision {

+	return Decision{Allow: false, Reason: reason, Code: code}

+}

+

+// Can is the single authorization decision function. Every handler,

+// hook, and worker in shithub funnels through here. Order of evaluation

+// is significant — higher-precedence denies (deletion, suspension)

+// short-circuit before role lookups touch the DB.

+//

+// The cache (if present in ctx via WithCache) is consulted before any

+// query and populated on the first lookup.

+func Can(ctx context.Context, d Deps, actor Actor, action Action, repo RepoRef) Decision {

+	// 1. Soft-deleted repos: nothing is allowed against them, full stop.

+	//    (Site admins can technically still hard-delete via admin

+	//    tooling, which doesn't go through Can.)

+	if repo.IsDeleted {

+		return deny(DenyRepoDeleted, "repo deleted")

+	}

+

+	// 2. Site admins: read access to anything; explicit-impersonation

+	//    needed for writes (S34 wires the impersonation surface — for

+	//    now the override only fires on read actions).

+	if actor.IsSiteAdmin && isReadAction(action) {

+		return allow("site admin read")

+	}

+

+	// 3. Suspended actors: writes denied unconditionally; reads against

+	//    public repos are still allowed (matches GitHub's "ghost-mode"

+	//    suspension semantics).

+	if actor.IsSuspended && isWriteAction(action) {

+		return deny(DenyActorSuspended, "actor suspended")

+	}

+

+	// 4. Anonymous + private: existence-leak-safe deny. Handler maps to

+	//    404 via Maybe404.

+	if actor.IsAnonymous && repo.IsPrivate() {

+		return deny(DenyVisibility, "anonymous on private repo")

+	}

+

+	// 5. Visibility for reads on public repos: anyone (anon or logged-

+	//    in) can read public, regardless of suspension.

+	if isReadAction(action) && repo.IsPublic() {

+		return allow("public repo read")

+	}

+

+	// 6. From here we need the actor's effective role on the repo.

+	//    Owner short-circuits to admin; collaborator role from DB

+	//    otherwise; org membership stub for S31.

+	role, err := effectiveRole(ctx, d, actor, repo)

+	if err != nil {

+		// DB error: deny rather than allow. Surface in logs via the

+		// reason; the caller is expected to log and fail closed.

+		return deny(DenyDBError, "role lookup failed: "+err.Error())

+	}

+

+	// 7. Archived repos: writes denied even for owners. Reads still go

+	//    through the role check above. (We could short-circuit reads

+	//    earlier but keeping the flow uniform makes the matrix readable.)

+	if repo.IsArchived && isWriteAction(action) {

+		return deny(DenyArchived, "repo archived")

+	}

+

+	// 8. Map action → minimum required role; check.

+	want := minRoleFor(action)

+	if want != RoleNone && !RoleAtLeast(role, want) {

+		// No role at all + private repo → look like a visibility deny

+		// so the handler picks the 404-leak guard. Otherwise it's a

+		// genuine role-too-low for a logged-in collaborator.

+		if role == RoleNone && repo.IsPrivate() {

+			return deny(DenyVisibility, "no role on private repo")

+		}

+		return deny(DenyRoleTooLow, "role too low")

+	}

+

+	// 9. Login-required actions: star/fork need any logged-in user.

+	if (action == ActionStarCreate || action == ActionForkCreate) && actor.IsAnonymous {

+		return deny(DenyAnonymous, "anonymous cannot star/fork")

+	}

+

+	return allow("granted")

+}

+

+// IsVisibleTo is a convenience wrapper around Can(actor, repo:read, …).

+// Used by listing endpoints that need to filter results by visibility

+// without caring about the deny reason.

+func IsVisibleTo(ctx context.Context, d Deps, actor Actor, repo RepoRef) bool {

+	return Can(ctx, d, actor, ActionRepoRead, repo).Allow

+}

+

+// Maybe404 maps a deny Decision to an HTTP status code that doesn't

+// leak existence. The convention:

+//

+//   - allow → 200 (caller handles)

+//   - deny on a private+anonymous (or non-collab+non-owner) → 404

+//   - any other deny → 403

+//

+// Handlers should call this after checking Allow, only when serving

+// the rejection response.

+func Maybe404(decision Decision, repo RepoRef, actor Actor) int {

+	if decision.Allow {

+		return http.StatusOK

+	}

+	// Anything that turns on private-visibility surfaces as 404.

+	if repo.IsPrivate() {

+		// Owner of a private repo getting denied is a real 403 (e.g.

+		// archived push). We approximate "owner" as having matching

+		// owner_user_id; collaborator status doesn't change the leak

+		// analysis since the row already exists in their world.

+		if actor.UserID != 0 && actor.UserID == repo.OwnerUserID {

+			return http.StatusForbidden

+		}

+		return http.StatusNotFound

+	}

+	return http.StatusForbidden

+}

+

+// effectiveRole computes the highest-effective role for actor on repo.

+// Owner ⇒ implicit admin; collaborator role from repo_collaborators;

+// nothing otherwise.

+func effectiveRole(ctx context.Context, d Deps, actor Actor, repo RepoRef) (Role, error) {

+	if actor.UserID != 0 && actor.UserID == repo.OwnerUserID {

+		return RoleAdmin, nil

+	}

+	if actor.UserID == 0 {

+		return RoleNone, nil

+	}

+

+	// Cache check.

+	cache := cacheFromContext(ctx)

+	key := cacheKey{actorUserID: actor.UserID, repoID: repo.ID}

+	if r, ok := cacheGet(cache, key); ok {

+		return r, nil

+	}

+

+	// DB lookup.

+	if d.Pool == nil {

+		// In tests where a Deps without Pool is passed, fail closed.

+		return RoleNone, nil

+	}

+	q := policydb.New()

+	dbRole, err := q.GetCollabRole(ctx, d.Pool, policydb.GetCollabRoleParams{

+		RepoID: repo.ID,

+		UserID: actor.UserID,

+	})

+	if errors.Is(err, pgx.ErrNoRows) {

+		cachePut(cache, key, RoleNone)

+		return RoleNone, nil

+	}

+	if err != nil {

+		return RoleNone, err

+	}

+	r := roleFromDB(dbRole)

+	cachePut(cache, key, r)

+	return r, nil

+}

+

+// minRoleFor returns the minimum collaborator role required for the

+// action against an existing repo. Owner is implicit admin, so this

+// table is the single source of truth for "what role grants what."

+//

+//nolint:gocyclo // exhaustive switch is the readable shape here.

+func minRoleFor(action Action) Role {

+	switch action {

+	// Read tier — public repos bypass via the early allow in Can; this

+	// is the gate for *private* read access.

+	case ActionRepoRead, ActionIssueRead, ActionPullRead:

+		return RoleRead

+

+	// Triage tier — issue-shape mutations without code write.

+	case ActionIssueClose, ActionIssueLabel, ActionIssueAssign:

+		return RoleTriage

+

+	// Write tier — code push, branch create, PR open/comment.

+	case ActionRepoWrite, ActionPullCreate, ActionPullReview, ActionPullClose,

+		ActionIssueCreate, ActionIssueComment:

+		return RoleWrite

+

+	// Maintain tier — most settings except dangerous ones.

+	case ActionRepoSettingsGeneral, ActionRepoSettingsBranches:

+		return RoleMaintain

+

+	// Admin tier — destructive and ownership-changing actions.

+	case ActionRepoAdmin, ActionRepoSettingsCollaborators,

+		ActionRepoArchive, ActionRepoDelete, ActionRepoTransfer, ActionRepoVisibility,

+		ActionPullMerge:

+		return RoleAdmin

+

+	// Login-required but no role required (any logged-in user).

+	case ActionStarCreate, ActionForkCreate:

+		return RoleNone

+

+	default:

+		// Unknown actions deny by default — RoleAdmin is impossibly

+		// high for a stranger so this acts as a fail-closed gate.

+		return RoleAdmin

+	}

+}

+

+// errBadAction is returned by Can when a caller passes a value that

+// doesn't match any registered Action. Reserved for tests.

+var errBadAction = errors.New("policy: unregistered action")

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy_test

+

+import (

+	"context"

+	"testing"

+

+	"github.com/tenseleyFlow/shithub/internal/auth/policy"

+)

+

+// The matrix is built from three orthogonal axes: actor archetype,

+// resource shape, and Action. We enumerate every combination and

+// assert the verdict so a future refactor that breaks one cell fails

+// loudly.

+

+type actorKind int

+

+const (

+	actorAnonymous actorKind = iota

+	actorOwner

+	actorCollabRead

+	actorCollabTriage

+	actorCollabWrite

+	actorCollabMaintain

+	actorCollabAdmin

+	actorUnrelated

+	actorSuspendedOwner

+	actorSuspendedCollabWrite

+	actorSiteAdmin

+)

+

+func (k actorKind) String() string {

+	return [...]string{

+		"anonymous", "owner",

+		"collab-read", "collab-triage", "collab-write", "collab-maintain", "collab-admin",

+		"unrelated", "suspended-owner", "suspended-collab-write", "site-admin",

+	}[k]

+}

+

+type repoKind int

+

+const (

+	repoPublic repoKind = iota

+	repoPrivate

+	repoArchivedPublic

+	repoArchivedPrivate

+	repoDeletedPublic

+)

+

+func (k repoKind) String() string {

+	return [...]string{"public", "private", "archived-public", "archived-private", "deleted-public"}[k]

+}

+

+const (

+	ownerID  int64 = 100

+	otherID  int64 = 200

+	repoIDV  int64 = 1000

+)

+

+func makeActor(k actorKind) policy.Actor {

+	switch k {

+	case actorAnonymous:

+		return policy.AnonymousActor()

+	case actorOwner:

+		return policy.UserActor(ownerID, "owner", false, false)

+	case actorCollabRead, actorCollabTriage, actorCollabWrite, actorCollabMaintain, actorCollabAdmin:

+		return policy.UserActor(otherID, "collab", false, false)

+	case actorUnrelated:

+		return policy.UserActor(otherID+1, "stranger", false, false)

+	case actorSuspendedOwner:

+		return policy.UserActor(ownerID, "owner", true, false)

+	case actorSuspendedCollabWrite:

+		return policy.UserActor(otherID, "collab", true, false)

+	case actorSiteAdmin:

+		return policy.UserActor(otherID+2, "admin", false, true)

+	}

+	return policy.AnonymousActor()

+}

+

+func makeRepo(k repoKind) policy.RepoRef {

+	r := policy.RepoRef{ID: repoIDV, OwnerUserID: ownerID}

+	switch k {

+	case repoPublic:

+		r.Visibility = "public"

+	case repoPrivate:

+		r.Visibility = "private"

+	case repoArchivedPublic:

+		r.Visibility = "public"

+		r.IsArchived = true

+	case repoArchivedPrivate:

+		r.Visibility = "private"

+		r.IsArchived = true

+	case repoDeletedPublic:

+		r.Visibility = "public"

+		r.IsDeleted = true

+	}

+	return r

+}

+

+// fakeRoleResolver intercepts the cache layer so tests can assert role

+// outcomes without hitting Postgres. Each collab actorKind seeds a

+// specific role in the cache pre-Can.

+func ctxWithCollabRole(t *testing.T, kind actorKind) context.Context {

+	t.Helper()

+	ctx := policy.WithCache(context.Background())

+	role := map[actorKind]policy.Role{

+		actorCollabRead:           policy.RoleRead,

+		actorCollabTriage:         policy.RoleTriage,

+		actorCollabWrite:          policy.RoleWrite,

+		actorCollabMaintain:       policy.RoleMaintain,

+		actorCollabAdmin:          policy.RoleAdmin,

+		actorSuspendedCollabWrite: policy.RoleWrite,

+	}[kind]

+	if role != policy.RoleNone {

+		policy.PrimeCacheForTest(ctx, otherID, repoIDV, role)

+	}

+	return ctx

+}

+

+// expect computes the canonical verdict for a (actorKind, repoKind, Action)

+// triple. The function below is the policy spec restated in plain Go;

+// if Can() and expect() ever disagree, one of them has a bug.

+//

+//nolint:gocyclo // exhaustive shape is by design.

+func expect(actor actorKind, repo repoKind, action policy.Action) bool {

+	// Deleted repo → nothing.

+	if repo == repoDeletedPublic {

+		return false

+	}

+	isWrite := action != policy.ActionRepoRead && action != policy.ActionIssueRead && action != policy.ActionPullRead

+

+	// Site admin can read everything (except deleted handled above).

+	if actor == actorSiteAdmin && !isWrite {

+		return true

+	}

+

+	// Suspended actors: writes always blocked. Reads against public repos

+	// still allowed (matches the suspended-then-read public code path).

+	if actor == actorSuspendedOwner || actor == actorSuspendedCollabWrite {

+		if isWrite {

+			return false

+		}

+		// fall through to the visibility check

+	}

+

+	isPrivate := repo == repoPrivate || repo == repoArchivedPrivate

+	isArchived := repo == repoArchivedPublic || repo == repoArchivedPrivate

+

+	// Anonymous + private → deny.

+	if actor == actorAnonymous && isPrivate {

+		return false

+	}

+

+	// Public repo reads: anyone.

+	if !isWrite && !isPrivate {

+		return true

+	}

+

+	// Compute role.

+	var have policy.Role

+	switch actor {

+	case actorOwner, actorSuspendedOwner:

+		have = policy.RoleAdmin

+	case actorCollabRead:

+		have = policy.RoleRead

+	case actorCollabTriage:

+		have = policy.RoleTriage

+	case actorCollabWrite, actorSuspendedCollabWrite:

+		have = policy.RoleWrite

+	case actorCollabMaintain:

+		have = policy.RoleMaintain

+	case actorCollabAdmin:

+		have = policy.RoleAdmin

+	}

+

+	// Archived: writes denied (covers owner too).

+	if isArchived && isWrite {

+		return false

+	}

+

+	// Login-only social actions.

+	if action == policy.ActionStarCreate || action == policy.ActionForkCreate {

+		return have != policy.RoleNone || (actor != actorAnonymous)

+	}

+

+	// Role check.

+	want := mirrorMinRoleFor(action)

+	if want == policy.RoleNone {

+		return actor != actorAnonymous

+	}

+	return policy.RoleAtLeast(have, want)

+}

+

+// mirrorMinRoleFor mirrors policy.minRoleFor for test side. We could

+// expose the internal helper; keeping the mirror enforces that the

+// matrix knows about every action explicitly.

+func mirrorMinRoleFor(a policy.Action) policy.Role {

+	switch a {

+	case policy.ActionRepoRead, policy.ActionIssueRead, policy.ActionPullRead:

+		return policy.RoleRead

+	case policy.ActionIssueClose, policy.ActionIssueLabel, policy.ActionIssueAssign:

+		return policy.RoleTriage

+	case policy.ActionRepoWrite, policy.ActionPullCreate, policy.ActionPullReview, policy.ActionPullClose,

+		policy.ActionIssueCreate, policy.ActionIssueComment:

+		return policy.RoleWrite

+	case policy.ActionRepoSettingsGeneral, policy.ActionRepoSettingsBranches:

+		return policy.RoleMaintain

+	case policy.ActionRepoAdmin, policy.ActionRepoSettingsCollaborators,

+		policy.ActionRepoArchive, policy.ActionRepoDelete, policy.ActionRepoTransfer, policy.ActionRepoVisibility,

+		policy.ActionPullMerge:

+		return policy.RoleAdmin

+	case policy.ActionStarCreate, policy.ActionForkCreate:

+		return policy.RoleNone

+	}

+	return policy.RoleAdmin

+}

+

+func TestCan_Matrix(t *testing.T) {

+	t.Parallel()

+	d := policy.Deps{} // pool nil OK; cache primes the role

+

+	for _, ak := range []actorKind{

+		actorAnonymous, actorOwner,

+		actorCollabRead, actorCollabTriage, actorCollabWrite, actorCollabMaintain, actorCollabAdmin,

+		actorUnrelated, actorSuspendedOwner, actorSuspendedCollabWrite, actorSiteAdmin,

+	} {

+		for _, rk := range []repoKind{

+			repoPublic, repoPrivate, repoArchivedPublic, repoArchivedPrivate, repoDeletedPublic,

+		} {

+			for _, action := range policy.AllActions {

+				ak, rk, action := ak, rk, action

+				name := ak.String() + "/" + rk.String() + "/" + string(action)

+				t.Run(name, func(t *testing.T) {

+					t.Parallel()

+					ctx := ctxWithCollabRole(t, ak)

+					actor := makeActor(ak)

+					repo := makeRepo(rk)

+					got := policy.Can(ctx, d, actor, action, repo).Allow

+					want := expect(ak, rk, action)

+					if got != want {

+						t.Errorf("Can(%s, %s, %s) = %v, want %v",

+							ak, rk, action, got, want)

+					}

+				})

+			}

+		}

+	}

+}

+

+func TestRoleAtLeast(t *testing.T) {

+	t.Parallel()

+	cases := []struct {

+		have, want policy.Role

+		ok         bool

+	}{

+		{policy.RoleAdmin, policy.RoleRead, true},

+		{policy.RoleAdmin, policy.RoleAdmin, true},

+		{policy.RoleWrite, policy.RoleAdmin, false},

+		{policy.RoleRead, policy.RoleTriage, false},

+		{policy.RoleNone, policy.RoleRead, false},

+		{policy.RoleRead, policy.RoleNone, false}, // RoleNone is meaningless as a target

+	}

+	for _, c := range cases {

+		if got := policy.RoleAtLeast(c.have, c.want); got != c.ok {

+			t.Errorf("RoleAtLeast(%q, %q) = %v, want %v", c.have, c.want, got, c.ok)

+		}

+	}

+}

+

+func TestMaybe404(t *testing.T) {

+	t.Parallel()

+	priv := policy.RepoRef{ID: 1, OwnerUserID: ownerID, Visibility: "private"}

+	pub := policy.RepoRef{ID: 1, OwnerUserID: ownerID, Visibility: "public"}

+	owner := policy.UserActor(ownerID, "o", false, false)

+	stranger := policy.UserActor(otherID, "s", false, false)

+

+	// Anonymous on private → 404 leak guard.

+	if got := policy.Maybe404(policy.Decision{Allow: false}, priv, policy.AnonymousActor()); got != 404 {

+		t.Errorf("anonymous on private: got %d, want 404", got)

+	}

+	// Stranger on private → 404 (don't reveal existence).

+	if got := policy.Maybe404(policy.Decision{Allow: false}, priv, stranger); got != 404 {

+		t.Errorf("stranger on private: got %d, want 404", got)

+	}

+	// Owner on private (e.g. archived push) → real 403.

+	if got := policy.Maybe404(policy.Decision{Allow: false}, priv, owner); got != 403 {

+		t.Errorf("owner deny on private: got %d, want 403", got)

+	}

+	// Public deny → 403 always.

+	if got := policy.Maybe404(policy.Decision{Allow: false}, pub, policy.AnonymousActor()); got != 403 {

+		t.Errorf("anonymous deny on public: got %d, want 403", got)

+	}

+	// Allow → 200 regardless of repo shape.

+	if got := policy.Maybe404(policy.Decision{Allow: true}, priv, owner); got != 200 {

+		t.Errorf("allow: got %d, want 200", got)

+	}

+}

+

+func TestCacheInvalidate(t *testing.T) {

+	t.Parallel()

+	ctx := policy.WithCache(context.Background())

+	policy.PrimeCacheForTest(ctx, otherID, repoIDV, policy.RoleAdmin)

+

+	// Confirm primed.

+	d := policy.Deps{}

+	actor := policy.UserActor(otherID, "u", false, false)

+	repo := policy.RepoRef{ID: repoIDV, OwnerUserID: ownerID, Visibility: "private"}

+	if !policy.Can(ctx, d, actor, policy.ActionRepoAdmin, repo).Allow {

+		t.Fatalf("primed cache should grant admin")

+	}

+

+	// Invalidate; with no DB pool the next lookup falls through to RoleNone.

+	policy.InvalidateRepo(ctx, repoIDV)

+	if policy.Can(ctx, d, actor, policy.ActionRepoAdmin, repo).Allow {

+		t.Errorf("after invalidate, admin should deny without role row")

+	}

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+// RepoRef is the policy-side projection of a repos row. Construct from

+// either reposdb.Repo or any of the GetRepoBy* row types via NewRepoRef

+// helpers in the policy package's adapters file (kept policy-internal

+// so the policy package never imports reposdb directly — sqlc rows

+// flow in via constructors at call boundaries).

+//

+// OwnerOrgID is the S31-shape: zero today; populated when org-owned

+// repos ship. Can() already branches on OwnerOrgID > 0 so that S31's

+// org membership lookup plugs in cleanly.

+type RepoRef struct {

+	ID          int64

+	OwnerUserID int64

+	OwnerOrgID  int64

+	Visibility  string // "public" | "private"

+	IsArchived  bool

+	IsDeleted   bool

+}

+

+// IsPublic returns true when the repo's visibility column is "public".

+// Other code paths must not parse Visibility directly — read it through

+// these helpers so the canonical strings live in one place.

+func (r RepoRef) IsPublic() bool { return r.Visibility == "public" }

+

+// IsPrivate is the inverse. Use whichever phrasing reads better at the

+// call site.

+func (r RepoRef) IsPrivate() bool { return r.Visibility == "private" }

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+import policydb "github.com/tenseleyFlow/shithub/internal/auth/policy/sqlc"

+

+// Role models the per-collaborator grant. The five values mirror

+// GitHub's tiers; the order matters because RoleAtLeast depends on it.

+type Role string

+

+const (

+	// RoleNone is the zero value used by callers when no row exists.

+	RoleNone     Role = ""

+	RoleRead     Role = "read"

+	RoleTriage   Role = "triage"

+	RoleWrite    Role = "write"

+	RoleMaintain Role = "maintain"

+	RoleAdmin    Role = "admin"

+)

+

+// roleRank maps a role to its position in the lattice. Higher rank →

+// strictly more powerful. RoleNone is below everything; RoleAdmin is

+// the top.

+func roleRank(r Role) int {

+	switch r {

+	case RoleAdmin:

+		return 5

+	case RoleMaintain:

+		return 4

+	case RoleWrite:

+		return 3

+	case RoleTriage:

+		return 2

+	case RoleRead:

+		return 1

+	default:

+		return 0

+	}

+}

+

+// RoleAtLeast reports whether `have` grants at least `want`. RoleNone

+// grants nothing.

+func RoleAtLeast(have, want Role) bool {

+	return roleRank(have) >= roleRank(want) && roleRank(want) > 0

+}

+

+// roleFromDB translates the sqlc-generated enum to our domain type.

+// We mirror values rather than re-using the DB type so the policy

+// package's API doesn't require callers to import policydb.

+func roleFromDB(r policydb.CollabRole) Role {

+	return Role(r)

+}

+

+// roleToDB is the inverse, used by callers that mutate collaborators.

+func roleToDB(r Role) policydb.CollabRole {

+	return policydb.CollabRole(r)

+}

+// SPDX-License-Identifier: AGPL-3.0-or-later

+

+package policy

+

+import "context"

+

+// PrimeCacheForTest seeds the request cache with a (user, repo) → role

+// entry so tests can drive Can() without a live DB. Only call from

+// _test.go files; the export is intentionally export-tagged-as-test in

+// its name so production callers don't reach for it.

+func PrimeCacheForTest(ctx context.Context, userID, repoID int64, role Role) {

+	cachePut(cacheFromContext(ctx), cacheKey{actorUserID: userID, repoID: repoID}, role)

+}