tenseleyflow/shithub / ce07729

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

+

+package pat

+

+import (

+	"sync"

+	"time"

+)

+

+// Debouncer suppresses repeat last-used updates for a given token within

+// a time window. The auth middleware calls ShouldTouch before issuing

+// the DB write so 100 requests/sec hitting the same token don't burn

+// 100 UPDATEs on user_tokens.

+//

+// Eviction is a simple cap-based sweep: once the map exceeds maxEntries,

+// we drop entries older than the window. Acceptable for our scale —

+// bounded by the active-PAT count, not the request rate.

+type Debouncer struct {

+	mu         sync.Mutex

+	last       map[int64]time.Time

+	window     time.Duration

+	maxEntries int

+	now        func() time.Time

+}

+

+// NewDebouncer returns a Debouncer with a 60-second default window and a

+// 4096-entry cap. The defaults are right for our launch scale; expose as

+// fields (NOT as constructor args) if a test needs to override them.

+func NewDebouncer(window time.Duration) *Debouncer {

+	if window <= 0 {

+		window = 60 * time.Second

+	}

+	return &Debouncer{

+		last:       make(map[int64]time.Time),

+		window:     window,

+		maxEntries: 4096,

+		now:        time.Now,

+	}

+}

+

+// ShouldTouch reports whether the auth middleware should issue a

+// last-used DB write for tokenID right now. Returns true at most once per

+// (tokenID, window) pair — subsequent calls within the window return

+// false. Always thread-safe.

+func (d *Debouncer) ShouldTouch(tokenID int64) bool {

+	now := d.now()

+	d.mu.Lock()

+	defer d.mu.Unlock()

+	if last, ok := d.last[tokenID]; ok && now.Sub(last) < d.window {

+		return false

+	}

+	d.last[tokenID] = now

+	if len(d.last) > d.maxEntries {

+		d.evictStaleLocked(now)

+	}

+	return true

+}

+

+func (d *Debouncer) evictStaleLocked(now time.Time) {

+	for k, t := range d.last {

+		if now.Sub(t) >= d.window {

+			delete(d.last, k)

+		}

+	}

+}

+

+// Forget removes tokenID from the debouncer's memory — useful when a

+// token is revoked, so a subsequent (unauthenticated) lookup with the

+// same id can't accidentally inherit a stale "recently touched" state.

+func (d *Debouncer) Forget(tokenID int64) {

+	d.mu.Lock()

+	defer d.mu.Unlock()

+	delete(d.last, tokenID)

+}

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

+

+// Package pat owns personal-access-token minting, hashing, scope

+// constants, and the auth-middleware verification path.

+//

+// Format: shithub_pat_<32-char-base62>. The fixed `shithub_pat_` prefix is

+// recognized by secret-scanning tooling and by our own log redactor — so

+// even if someone accidentally pastes a raw token into a log line or a

+// public PR, downstream tooling has a chance to spot it.

+package pat

+

+import (

+	"crypto/rand"

+	"crypto/sha256"

+	"crypto/subtle"

+	"errors"

+	"fmt"

+	"strings"

+)

+

+// Prefix is the fixed marker prepended to every minted token.

+const Prefix = "shithub_pat_"

+

+// PayloadLen is the length of the random payload (chars), not bytes.

+// 32 base62 characters carry log2(62)*32 ≈ 190 bits of entropy — well

+// beyond any plausible brute-force budget.

+const PayloadLen = 32

+

+// DisplayPrefixLen is how much of the raw token we keep for display

+// (e.g. on the listing page). It includes the literal `shithub_pat_`

+// plus four characters of payload, enough to disambiguate at a glance.

+const DisplayPrefixLen = len("shithub_pat_") + 4

+

+// MaxTokensPerUser bounds the listing page and the auth-lookup table size.

+const MaxTokensPerUser = 50

+

+// alphabet is the base62 character set used for the random payload.

+const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

+

+// ErrMalformed is returned when the supplied string isn't a well-formed

+// shithub PAT. Distinct from "valid format but unknown" so the auth

+// middleware can short-circuit without touching the DB.

+var ErrMalformed = errors.New("pat: malformed token")

+

+// Mint generates a fresh raw token, its sha256 hash (for storage), and

+// its display prefix. The raw token MUST be shown to the user exactly

+// once and never stored.

+func Mint() (raw string, hash []byte, prefix string, err error) {

+	payload, err := randomBase62(PayloadLen)

+	if err != nil {

+		return "", nil, "", fmt.Errorf("pat: mint payload: %w", err)

+	}

+	raw = Prefix + payload

+	sum := sha256.Sum256([]byte(raw))

+	prefix = raw[:DisplayPrefixLen]

+	return raw, sum[:], prefix, nil

+}

+

+// HashOf computes the canonical lookup hash for raw, after verifying

+// the prefix and length. Use this on every middleware lookup so a

+// malformed input never reaches the DB index.

+func HashOf(raw string) ([]byte, error) {

+	if !strings.HasPrefix(raw, Prefix) {

+		return nil, ErrMalformed

+	}

+	if len(raw) != len(Prefix)+PayloadLen {

+		return nil, ErrMalformed

+	}

+	for _, r := range raw[len(Prefix):] {

+		if !isBase62(r) {

+			return nil, ErrMalformed

+		}

+	}

+	sum := sha256.Sum256([]byte(raw))

+	return sum[:], nil

+}

+

+// EqualHash compares two stored hashes in constant time. The auth path

+// already keys by hash via UNIQUE-index lookup, but we also expose this

+// for any future code that compares hashes outside a DB lookup.

+func EqualHash(a, b []byte) bool {

+	return subtle.ConstantTimeCompare(a, b) == 1

+}

+

+// LooksLike reports whether s resembles a PAT (cheap structural check).

+// Used by URL-credential redaction in the log layer.

+func LooksLike(s string) bool {

+	if !strings.HasPrefix(s, Prefix) {

+		return false

+	}

+	if len(s) != len(Prefix)+PayloadLen {

+		return false

+	}

+	for _, r := range s[len(Prefix):] {

+		if !isBase62(r) {

+			return false

+		}

+	}

+	return true

+}

+

+func isBase62(r rune) bool {

+	return (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9')

+}

+

+// randomBase62 returns n base62 characters from crypto/rand. Reads more

+// bytes than strictly needed and rejection-samples to keep the

+// distribution uniform.

+func randomBase62(n int) (string, error) {

+	out := make([]byte, 0, n)

+	buf := make([]byte, n*2)

+	for len(out) < n {

+		if _, err := rand.Read(buf); err != nil {

+			return "", err

+		}

+		for _, b := range buf {

+			// 256 mod 62 == 8; reject the top range to avoid bias.

+			if b >= 248 {

+				continue

+			}

+			out = append(out, alphabet[b%62])

+			if len(out) == n {

+				break

+			}

+		}

+	}

+	return string(out), nil

+}

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

+

+package pat

+

+import (

+	"crypto/sha256"

+	"strings"

+	"testing"

+	"time"

+)

+

+func TestMint_FormatAndUniqueness(t *testing.T) {

+	t.Parallel()

+	seen := map[string]bool{}

+	for i := 0; i < 100; i++ {

+		raw, hash, prefix, err := Mint()

+		if err != nil {

+			t.Fatalf("Mint: %v", err)

+		}

+		if !strings.HasPrefix(raw, Prefix) {

+			t.Fatalf("missing prefix: %s", raw)

+		}

+		if len(raw) != len(Prefix)+PayloadLen {

+			t.Fatalf("wrong length: %d", len(raw))

+		}

+		if !strings.HasPrefix(prefix, Prefix) {

+			t.Fatalf("display prefix wrong: %s", prefix)

+		}

+		if len(prefix) != DisplayPrefixLen {

+			t.Fatalf("display prefix length: %d", len(prefix))

+		}

+		if seen[raw] {

+			t.Fatalf("duplicate raw token: %s", raw)

+		}

+		seen[raw] = true

+		want := sha256.Sum256([]byte(raw))

+		if !EqualHash(want[:], hash) {

+			t.Fatalf("hash mismatch")

+		}

+	}

+}

+

+func TestHashOf_RoundTrip(t *testing.T) {

+	t.Parallel()

+	raw, hash, _, _ := Mint()

+	got, err := HashOf(raw)

+	if err != nil {

+		t.Fatalf("HashOf: %v", err)

+	}

+	if !EqualHash(got, hash) {

+		t.Fatalf("hash round-trip mismatch")

+	}

+}

+

+func TestHashOf_RejectsMalformed(t *testing.T) {

+	t.Parallel()

+	cases := []string{

+		"",

+		"not-a-pat",

+		Prefix + "tooshort",

+		Prefix + strings.Repeat("a", PayloadLen-1),

+		Prefix + strings.Repeat("a", PayloadLen+1),

+		Prefix + strings.Repeat("!", PayloadLen),

+	}

+	for _, c := range cases {

+		if _, err := HashOf(c); err == nil {

+			t.Errorf("expected error for %q", c)

+		}

+	}

+}

+

+func TestLooksLike(t *testing.T) {

+	t.Parallel()

+	raw, _, _, _ := Mint()

+	if !LooksLike(raw) {

+		t.Fatal("LooksLike rejected its own output")

+	}

+	if LooksLike("not-a-pat") {

+		t.Fatal("LooksLike accepted nonsense")

+	}

+}

+

+// ----- scopes -----

+

+func TestHasScope(t *testing.T) {

+	t.Parallel()

+	if !HasScope([]string{"repo:read"}, ScopeRepoRead) {

+		t.Fatal("repo:read should grant repo:read")

+	}

+	if !HasScope([]string{"repo:write"}, ScopeRepoRead) {

+		t.Fatal("repo:write should imply repo:read")

+	}

+	if HasScope([]string{"repo:read"}, ScopeRepoWrite) {

+		t.Fatal("repo:read should NOT imply repo:write")

+	}

+	if !HasScope([]string{"user:write"}, ScopeUserRead) {

+		t.Fatal("user:write should imply user:read")

+	}

+	if HasScope(nil, ScopeRepoRead) {

+		t.Fatal("empty held should grant nothing")

+	}

+}

+

+func TestNormalizeScopes(t *testing.T) {

+	t.Parallel()

+	in := []string{"user:read", "bogus", "repo:read", "repo:read", "user:read"}

+	got := NormalizeScopes(in)

+	want := []string{"repo:read", "user:read"}

+	if len(got) != len(want) {

+		t.Fatalf("got %v, want %v", got, want)

+	}

+	for i := range got {

+		if got[i] != want[i] {

+			t.Fatalf("got %v, want %v", got, want)

+		}

+	}

+}

+

+// ----- debouncer -----

+

+func TestDebouncer_FirstCallTouchesAndSubsequentSuppresses(t *testing.T) {

+	t.Parallel()

+	d := NewDebouncer(60 * time.Second)

+	if !d.ShouldTouch(1) {

+		t.Fatal("first call must touch")

+	}

+	if d.ShouldTouch(1) {

+		t.Fatal("second call within window must suppress")

+	}

+}

+

+func TestDebouncer_DifferentTokensIndependent(t *testing.T) {

+	t.Parallel()

+	d := NewDebouncer(60 * time.Second)

+	if !d.ShouldTouch(1) {

+		t.Fatal("first call for 1")

+	}

+	if !d.ShouldTouch(2) {

+		t.Fatal("first call for 2")

+	}

+}

+

+func TestDebouncer_WindowReset(t *testing.T) {

+	t.Parallel()

+	d := NewDebouncer(50 * time.Millisecond)

+	if !d.ShouldTouch(1) {

+		t.Fatal("first")

+	}

+	time.Sleep(80 * time.Millisecond)

+	if !d.ShouldTouch(1) {

+		t.Fatal("after window")

+	}

+}

+

+func TestDebouncer_HighRate(t *testing.T) {

+	t.Parallel()

+	d := NewDebouncer(60 * time.Second)

+	touches := 0

+	for i := 0; i < 100; i++ {

+		if d.ShouldTouch(42) {

+			touches++

+		}

+	}

+	if touches != 1 {

+		t.Fatalf("got %d touches over 100 calls, want 1", touches)

+	}

+}

+

+func TestDebouncer_Forget(t *testing.T) {

+	t.Parallel()

+	d := NewDebouncer(60 * time.Second)

+	d.ShouldTouch(1)

+	d.Forget(1)

+	if !d.ShouldTouch(1) {

+		t.Fatal("after Forget, ShouldTouch must return true again")

+	}

+}

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

+

+package pat

+

+// Scope is a typed scope constant. The set is intentionally coarse —

+// matches the GitHub classic-PAT model. Fine-grained per-repo scoping

+// is a post-MVP project.

+type Scope string

+

+const (

+	ScopeRepoRead  Scope = "repo:read"

+	ScopeRepoWrite Scope = "repo:write"

+	ScopeUserRead  Scope = "user:read"

+	ScopeUserWrite Scope = "user:write"

+	ScopeAdminRead Scope = "admin:read"

+)

+

+// AllScopes is the canonical ordered list — drives the create-form UI

+// and the validation list in ValidScope.

+var AllScopes = []Scope{

+	ScopeRepoRead,

+	ScopeRepoWrite,

+	ScopeUserRead,

+	ScopeUserWrite,

+	ScopeAdminRead,

+}

+

+// ValidScope reports whether s is a known scope name.

+func ValidScope(s string) bool {

+	for _, sc := range AllScopes {

+		if string(sc) == s {

+			return true

+		}

+	}

+	return false

+}

+

+// HasScope reports whether held grants required. Operations that don't

+// require a scope (browser-session callers) skip this check entirely.

+//

+// repo:write implicitly grants repo:read; user:write implicitly grants

+// user:read. We expand the implication here so callers don't have to.

+func HasScope(held []string, required Scope) bool {

+	want := string(required)

+	for _, h := range held {

+		if h == want {

+			return true

+		}

+		if required == ScopeRepoRead && h == string(ScopeRepoWrite) {

+			return true

+		}

+		if required == ScopeUserRead && h == string(ScopeUserWrite) {

+			return true

+		}

+	}

+	return false

+}

+

+// NormalizeScopes filters input to known scopes, deduplicates, and

+// returns them in AllScopes order. Used by the create handler to

+// canonicalize whatever the form submitted before it lands in the DB.

+func NormalizeScopes(in []string) []string {

+	seen := map[string]struct{}{}

+	for _, s := range in {

+		if ValidScope(s) {

+			seen[s] = struct{}{}

+		}

+	}

+	out := make([]string, 0, len(seen))

+	for _, sc := range AllScopes {

+		if _, ok := seen[string(sc)]; ok {

+			out = append(out, string(sc))

+		}

+	}

+	return out

+}