`d933bdc`

api: propagate PAT policy actors

Authored by mfwolffe <wolffemf@dukes.jmu.edu> yesterday

SHA: d933bdc35515ec40286b16af9c924d30c0979003
Parents: b4c53a7
Tree: ea9999e

9 changed files

Status	File	+	-
M	`docs/internal/permissions.md`	4	4
A	`docs/public/api/actions.md`	52	0
M	`docs/public/api/overview.md`	2	1
M	`internal/web/handlers/api/actions_cancel.go`	2	3
M	`internal/web/handlers/api/actions_rerun.go`	2	3
M	`internal/web/handlers/api/checks.go`	1	2
M	`internal/web/handlers/api/stars.go`	1	5
M	`internal/web/middleware/middleware_test.go`	17	0
M	`internal/web/middleware/pat.go`	21	6

docs/internal/permissions.mdmodified

    suspending an account takes effect on the user's next click.
  * **Web (PAT)** — `middleware.PATAuthMiddleware` rejects requests
    whose owning user has `suspended_at IS NOT NULL` with a 401 before
 -  the handler runs. Code paths under PAT auth construct
 -  `policy.UserActor(..., IsSuspended: false, ...)` because the gate
 -  is upstream; the field is still passed for honesty and is correct
 -  by construction.
 +  the handler runs. It still binds username, suspension, and site-admin
 +  fields into `middleware.PATAuth`; API policy gates must construct
 +  actors through `PATAuth.PolicyActor()` so the request actor stays
 +  honest even as the middleware evolves.
  * **git over HTTPS (`internal/web/handlers/githttp`)** — the basic-
    auth resolver (`auth.go::resolveViaPAT`/`resolveViaPassword`)
    rejects suspended owners with `errBadCredentials` *before* the

docs/public/api/actions.mdadded

 +# Actions workflow API
++
 +Actions workflow lifecycle endpoints are PAT-authenticated and require
 +`repo:write`. The token's user must also have write permission on the
 +repository that owns the target run or job.
++
 +## Cancel job
++
 +```text
 +POST /api/v1/jobs/{id}/cancel
 +```
++
 +Requests cancellation for a workflow job. Queued jobs become terminal
 +immediately. Running jobs set `cancel_requested=true`; the runner observes
 +that flag through its cancel-check endpoint, stops the active container, and
 +reports the terminal status.
++
 +Response: `202 Accepted`.
++
 +```json
 +{
 +  "job_id": 10,
 +  "run_id": 4,
 +  "repo_id": 2,
 +  "changed_jobs": 1,
 +  "run_completed": false,
 +  "run_conclusion": ""
 +}
 +```
++
 +## Re-run workflow run
++
 +```text
 +POST /api/v1/runs/{id}/rerun
 +```
++
 +Creates a new workflow run from the original run's commit and workflow file.
 +Only terminal runs are rerunnable. The new run records `parent_run_id` so the
 +history remains linked.
++
 +Response: `201 Created`.
++
 +```json
 +{
 +  "run_id": 12,
 +  "run_index": 8,
 +  "parent_run_id": 4,
 +  "repo_id": 2,
 +  "workflow_file": ".shithub/workflows/ci.yml",
 +  "head_sha": "0123456789abcdef0123456789abcdef01234567"
 +}
 +```

docs/public/api/overview.mdmodified

  > **Status.** The API is intentionally narrow today. Endpoints
  > currently shipped: `GET /api/v1/user`, the
  > `/api/v1/repos/{owner}/{repo}/check-runs` family, and the
 -> `/api/v1/user/starred*` stars endpoints. Other sections of this
 +> `/api/v1/user/starred*` stars endpoints, plus the Actions lifecycle
 +> routes in [Actions workflow API](actions.md). Other sections of this
  > reference (Issues, Pull requests, Webhooks, etc.) describe the
  > **planned** shape and will land in subsequent sprints. Pages
  > that document planned-only endpoints carry a banner.

internal/web/handlers/api/actions_cancel.gomodified

  		writeAPIError(w, http.StatusNotFound, "job not found")
  		return
+ 	}
 -	job, run, repo, ok := h.resolveCancellableJob(w, r, auth.UserID, jobID)
 +	job, run, repo, ok := h.resolveCancellableJob(w, r, auth.PolicyActor(), jobID)
  	if !ok {
  		return
+ 	}
  func (h *Handlers) resolveCancellableJob(
  	w http.ResponseWriter,
  	r *http.Request,
 -	userID int64,
 +	actor policy.Actor,
  	jobID int64,
  ) (actionsdb.WorkflowJob, actionsdb.WorkflowRun, reposdb.Repo, bool) {
  	q := actionsdb.New()
+ 		}
  		return actionsdb.WorkflowJob{}, actionsdb.WorkflowRun{}, reposdb.Repo{}, false
+ 	}
 -	actor := policy.UserActor(userID, "", false, false)
  	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, actor, policy.ActionRepoWrite, policy.NewRepoRefFromRepo(repo)).Allow {
  		writeAPIError(w, http.StatusNotFound, "job not found")
  		return actionsdb.WorkflowJob{}, actionsdb.WorkflowRun{}, reposdb.Repo{}, false

internal/web/handlers/api/actions_rerun.gomodified

  		writeAPIError(w, http.StatusNotFound, "run not found")
  		return
+ 	}
 -	run, repo, ok := h.resolveLifecycleRun(w, r, auth.UserID, runID)
 +	run, repo, ok := h.resolveLifecycleRun(w, r, auth.PolicyActor(), runID)
  	if !ok {
  		return
+ 	}
  func (h *Handlers) resolveLifecycleRun(
  	w http.ResponseWriter,
  	r *http.Request,
 -	userID int64,
 +	actor policy.Actor,
  	runID int64,
  ) (actionsdb.WorkflowRun, reposdb.Repo, bool) {
  	q := actionsdb.New()
+ 		}
  		return actionsdb.WorkflowRun{}, reposdb.Repo{}, false
+ 	}
 -	actor := policy.UserActor(userID, "", false, false)
  	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, actor, policy.ActionRepoWrite, policy.NewRepoRefFromRepo(repo)).Allow {
  		writeAPIError(w, http.StatusNotFound, "run not found")
  		return actionsdb.WorkflowRun{}, reposdb.Repo{}, false

internal/web/handlers/api/checks.gomodified

  		writeAPIError(w, http.StatusNotFound, "repo not found")
  		return nil, false
+ 	}
 -	actor := policy.UserActor(auth.UserID, "", false, false)
 -	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, actor, action, policy.NewRepoRefFromRepo(repo)).Allow {
 +	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, auth.PolicyActor(), action, policy.NewRepoRefFromRepo(repo)).Allow {
  		// Existence-leak: 404 instead of 403 when the actor can't see
  		// the repo. The PAT-scope check above is the public 403; this
  		// is the visibility gate.

internal/web/handlers/api/stars.gomodified

  		writeAPIError(w, http.StatusNotFound, "repo not found")
  		return reposdb.Repo{}, false
+ 	}
 -	// PAT-auth path: the middleware already rejected suspended
 -	// accounts; passing IsSuspended=false here is correct by
 -	// construction (documented in docs/internal/permissions.md).
 -	actor := policy.UserActor(auth.UserID, "", false, false)
 -	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, actor, policy.ActionStarCreate, policy.NewRepoRefFromRepo(repo)).Allow {
 +	if !policy.Can(r.Context(), policy.Deps{Pool: h.d.Pool}, auth.PolicyActor(), policy.ActionStarCreate, policy.NewRepoRefFromRepo(repo)).Allow {
  		writeAPIError(w, http.StatusNotFound, "repo not found")
  		return reposdb.Repo{}, false
+ 	}

internal/web/middleware/middleware_test.gomodified

+ 	}
+ }
 +func TestPATAuthPolicyActorPropagatesResolvedUserFlags(t *testing.T) {
 +	t.Parallel()
++
 +	actor := PATAuth{
 +		UserID:      42,
 +		Username:    "alice",
 +		IsSuspended: true,
 +		IsSiteAdmin: true,
 +	}.PolicyActor()
 +	if actor.UserID != 42 || actor.Username != "alice" || !actor.IsSuspended || !actor.IsSiteAdmin {
 +		t.Fatalf("PolicyActor did not propagate PAT user flags: %+v", actor)
 +	}
 +	if anon := (PATAuth{}).PolicyActor(); !anon.IsAnonymous {
 +		t.Fatalf("zero PATAuth should produce anonymous actor: %+v", anon)
 +	}
 +}
++
  // TestOptionalUser_StaleEpochSkipsBind is the corollary: when the
  // recorded session epoch doesn't match the current users.session_epoch
  // (because the user logged out everywhere), the binding is skipped so

internal/web/middleware/pat.gomodified

  	"github.com/jackc/pgx/v5/pgxpool"
  	"github.com/tenseleyFlow/shithub/internal/auth/pat"
 +	"github.com/tenseleyFlow/shithub/internal/auth/policy"
  	usersdb "github.com/tenseleyFlow/shithub/internal/users/sqlc"
+ )
  // the auth check passed via PAT, `Token != nil` and Scopes is the parsed
  // scope list. Pure session callers see the zero value.
  type PATAuth struct {
 -	UserID  int64
 -	TokenID int64
 -	Scopes  []string
 +	UserID      int64
 +	Username    string
 +	TokenID     int64
 +	Scopes      []string
 +	IsSuspended bool
 +	IsSiteAdmin bool
+ }
  // PATAuthFromContext returns the resolved PAT auth state, or the zero
  	return PATAuth{}
+ }
 +// PolicyActor returns the canonical policy actor for a resolved PAT request.
 +func (p PATAuth) PolicyActor() policy.Actor {
 +	if p.UserID == 0 {
 +		return policy.AnonymousActor()
 +	}
 +	return policy.UserActor(p.UserID, p.Username, p.IsSuspended, p.IsSiteAdmin)
 +}
++
  // PATConfig configures the PAT auth middleware.
  type PATConfig struct {
  	Pool      *pgxpool.Pool
+ 			}
  			ctx := context.WithValue(r.Context(), patAuthKey, PATAuth{
 -				UserID:  row.UserID,
 -				TokenID: row.ID,
 -				Scopes:  row.Scopes,
 +				UserID:      row.UserID,
 +				Username:    user.Username,
 +				TokenID:     row.ID,
 +				Scopes:      row.Scopes,
 +				IsSuspended: user.SuspendedAt.Valid,
 +				IsSiteAdmin: user.IsSiteAdmin,
  			})
  			next.ServeHTTP(w, r.WithContext(ctx))
  		})