internal_membership

package
v1.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package internal_membership exposes octo-server's Project membership facts over an authenticated service-to-service surface, for consumers that hold no end-user token.

Why a separate module from modules/project

modules/project owns the user-facing surface: every route there is mounted behind AuthMiddleware plus the Space/Project middleware, and its handlers answer a logged-in human. The endpoints here answer a PEER SERVICE holding a deployment-issued token, and they must not inherit any of that: no AuthMiddleware, no uid, no per-uid rate limiter. Mixing the two trust domains in one module means one wrong middleware line grants a service token a user-scoped route, or leaves a service route depending on a uid that is never present.

The split also keeps the error contract right. modules/project pins its wire status to 400 (ResponseErrorL) for D14 compatibility with shipped clients; these endpoints have no such clients and use ResponseErrorLWithStatus, so a peer service reads a real 401/400/500 like it does from every other /v1/internal endpoint in this repository.

Scalar membership facts use pkg/project. The full roster calls the exported modules/project read service, which owns its DAO and response projection; this HTTP module never copies those reads. pkg/project remains independent of modules/project. Cross-module HTTP tests live in the external test package so the production dependency is not reversed by in-package test imports.

Consumers

The Loop/Fleet control plane, which needs two facts octo-server alone can answer: whether a NAMED OTHER user still holds a seat in a project (the end-user verify endpoint can only speak for its own token holder), and whether a project's membership has changed since an authorization snapshot was taken. Every endpoint is gated by its own X-Internal-Token so a leaked credential grants exactly one capability.

Index

Constants

View Source
const (
	// MembershipInternalTokenEnv gates this module's endpoints. The Loop/Fleet
	// control plane presents the value in X-Internal-Token on every call, and
	// the same variable name is used on the Fleet side for the credential it
	// sends — one secret, one name, so an operator cannot mis-pair them.
	//
	// Exported so main.go can feed the value into the cross-capability
	// exclusion checks without a second copy of the literal drifting out of
	// sync with this constant.
	MembershipInternalTokenEnv = "OCTO_MEMBERSHIP_INTERNAL_TOKEN"

	// PeerMaxCacheAgeEnv is the second half of the enablement gate: the operator
	// declares, in seconds, the time bound the PEER places on decisions it caches
	// from these endpoints. Setting the token without it does not enable the
	// capability.
	//
	// # Why the release condition is an env and not a sentence
	//
	// member_epoch cannot be a sufficient invalidation signal, and not because of
	// any defect: it is keyed per PROJECT while one of the four axes that decide
	// the answer — a super-admin ban or an account destroy — is per USER. A ban
	// moves no epoch, so a cached grant keeps its agreement and a cached denial
	// survives the unban. Nothing on this side can close that; the bound has to
	// exist on the consumer. See docs/project-membership-cache-bound-proposal.md.
	//
	// That made the safety argument for shipping "the peer implements a TTL, and
	// the token stays unset until they do" — a promise living in a PR description
	// and a rollout document, with the only observable being a gauge nobody had a
	// reason to watch. This branch's whole discipline is that a mistake worth
	// making impossible should be made INEXPRESSIBLE rather than documented, and
	// the branch had not applied it to its own release condition. Now enabling the
	// capability requires stating the bound, and the stated value is published as
	// a metric so "did anyone actually agree a number" is answerable at any time.
	//
	// It carries the VALUE rather than being a yes/no acknowledgement because the
	// value is the contract. When §3.1 of the proposal lands and the answers start
	// carrying max_age_seconds on the wire, this is where that number comes from —
	// no second source to drift.
	//
	// This is NOT a claim that the peer honours it. The server cannot verify that
	// from here; §5 of the proposal specifies the measured gate (observe the
	// peer's re-verification interval) that eventually can. It is the difference
	// between an unstated assumption and a stated one.
	PeerMaxCacheAgeEnv = "OCTO_MEMBERSHIP_INTERNAL_PEER_MAX_CACHE_AGE_SECONDS"
)

Environment knobs and wire constants.

A distinct token per internal consumer is the repository convention (see modules/internal_resolve/config.go and modules/bot_mention/config.go): it lets one consumer be revoked or rotated without disturbing the rest, and bounds the blast radius when a single value leaks.

Variables

This section is empty.

Functions

This section is empty.

Types

type Module

type Module struct {
	log.Log
	// contains filtered or unexported fields
}

Module is the module handle registered with the wkhttp router.

func New

func New(ctx *config.Context) *Module

New loads the enablement configuration at construction. When any part of it is missing or invalid the reason is logged and every request is refused — the module still mounts, so a misconfigured deployment fails closed on the endpoint rather than failing to boot the whole server.

Two things have to be right, not one. The token is the credential; the declared peer cache bound is the RELEASE CONDITION, and it is enforced here rather than promised in a document because these endpoints hand a peer authorization answers whose account axis member_epoch structurally cannot invalidate. See PeerMaxCacheAgeEnv.

Refusing to enable rather than panicking is deliberate and matches the rest of this module: one capability's misconfiguration must not take down a server whose other two dozen modules are serving real traffic. The distinction an operator needs — "off because nobody configured it" versus "off because I configured it wrong" — is carried by the ERROR line and the configured gauge, not by the process exiting.

func (*Module) Route

func (m *Module) Route(r *wkhttp.WKHttp)

Route mounts the membership and project-list endpoints under /v1/internal.

Middleware EXECUTION ORDER matters and is asserted by a test:

  1. per-endpoint strict IP rate limit — MUST run first, so abusive traffic never reaches the token compare (a Redis Lua round trip) or the database.
  2. internalAuthMiddleware — constant-time X-Internal-Token compare, fail-closed when unset.

Both are mounted on the CONCRETE routes rather than on the group. Gin runs group handlers ahead of route handlers, so auth-on-group + limiter-on-route would execute as auth → limiter: a missing or wrong token would then abort before consuming the strict bucket, and token-probing traffic would fall back to the much wider global per-IP bucket. modules/internal_resolve documents having been bitten by exactly this ordering.

None of these routes takes AuthMiddleware. That is the deliberate exclusion the space-isolation rule asks to be documented: these endpoints have no end user, the caller is a peer service authenticated by a deployment-issued token, and there is no session identity for a user-scoped middleware to read. On the list route uid is a token-authorized query target, or project_ids names metadata candidates; neither is caller identity. The required space_id scopes both modes. The Project member-list route binds its required space_id and project_id together; its peer authorizes the end user.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址