Support Cargo Authentication / Authorization protocols

[dralley]

Is your feature request related to a problem? Please describe.

Currently pulp_rpm does not do any authentication or authorization protocols, so any user can upload to any package namespace or yank any package via the API.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context about the feature request here.

[dralley]

Here's a "plan" suggested by claude, which IMO looks reasonable.

Proper Authentication for Cargo API Endpoints — Roadmap

Context

pulp_rust currently uses a hardcoded stub token for Cargo API auth. This document designs the roadmap for replacing it with proper per-user token authentication, distribution-scoped permissions, and crate ownership — integrating with Pulp's existing RBAC infrastructure.

How Cargo auth works

• Cargo sends Authorization: <raw_token> (not Bearer) on state-changing requests (publish, yank, unyank) when config.json has "auth-required": false
• When "auth-required": true, Cargo sends the token on ALL requests (including downloads and index)
• cargo login --registry NAME prompts the user to paste a token — token creation is out-of-band (web UI, REST API, etc.)
• Token format is opaque — registries define their own format
• Cargo supports credential providers (external processes) for secure token storage, but the registry side is the same regardless

How Pulp auth works today

• REST API uses HTTP Basic Auth + Django session auth
• RBAC via drf-access-policy: declarative DEFAULT_ACCESS_POLICY on viewsets with conditions like has_model_perms, has_obj_perms
• Roles (Role model) bundle permissions; assigned to users/groups at global, domain, or object level via UserRole/GroupRole
• pulp_container provides a prior-art example: ContainerNamespace model with namespace-scoped permissions

Key challenge

Cargo endpoints (CargoPublishApiView, CargoDownloadApiView) are plain DRF APIViews, not NamedModelViewSets. They currently set authentication_classes = [] and permission_classes = [], bypassing Pulp's RBAC entirely. Proper auth needs to bridge the gap between Cargo's Authorization: <token> header and Pulp's user/role/permission system.

---

Phase 1: Per-User Cargo Tokens (replace stub)

Goal: Users can create personal API tokens via Pulp's REST API, use them with cargo login, and publish/yank with their own identity.

1a. CargoToken model

New model in pulp_rust/app/models.py:

class CargoToken(BaseModel):
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="cargo_tokens")
    token = models.CharField(max_length=255, unique=True, db_index=True)
    name = models.CharField(max_length=255)  # human-readable label
    last_used = models.DateTimeField(null=True)

• Token value: crg_ prefix + 40 hex chars (generated via secrets.token_hex(20))
• crg_ prefix makes tokens grep-able in logs and distinguishable from other credentials

1b. CargoTokenAuthentication class

New DRF authentication class in pulp_rust/app/auth.py (replaces require_cargo_token decorator):

class CargoTokenAuthentication(BaseAuthentication):
    def authenticate(self, request):
        token = request.META.get("HTTP_AUTHORIZATION")
        if not token:
            return None  # let other auth classes try
        try:
            cargo_token = CargoToken.objects.select_related("user").get(token=token)
        except CargoToken.DoesNotExist:
            raise AuthenticationFailed("invalid token")
        cargo_token.last_used = timezone.now()
        cargo_token.save(update_fields=["last_used"])
        return (cargo_token.user, cargo_token)

• Returns (user, auth) tuple — standard DRF pattern
• The auth object (the CargoToken) is available as request.auth
• Returning None when no header is present allows unauthenticated access for public endpoints

1c. Token management viewset

New CargoTokenViewSet in pulp_rust/app/viewsets.py:

• POST /pulp/api/v3/cargo/tokens/ — create token (returns the token value once; stored as hash)
• GET /pulp/api/v3/cargo/tokens/ — list user's tokens (name, last_used, created; NOT the token value)
• DELETE /pulp/api/v3/cargo/tokens/{id}/ — revoke token

Access policy: authenticated users can only manage their own tokens.

1d. Wire into views

• Add CargoTokenAuthentication to authentication_classes on CargoPublishApiView and CargoDownloadApiView
• Keep Pulp's default auth classes too (so admin users with Basic Auth can also operate)
• Add AccessPolicyFromDB or custom permission class that checks request.user.is_authenticated for state-changing methods
• Remove the @require_cargo_token decorator

1e. /me endpoint (auth verification)

Implement GET /me on the Cargo API. Cargo calls this during cargo login to verify the token is valid.

• Returns 200 with {"ok": true} if the token is valid
• Returns 401 if the token is missing or invalid
• Wired into CargoTokenAuthentication

1f. cargo login flow

1. User creates a token via Pulp REST API: POST /pulp/api/v3/cargo/tokens/ (authenticated with HTTP Basic Auth)
2. API returns the token string (shown once, then only the hash is stored)
3. User runs cargo login --registry my-crates and pastes the token
4. Cargo stores it in ~/.cargo/credentials.toml
5. Cargo calls /me to verify the token
6. Subsequent cargo publish / cargo yank send it in the Authorization header

1g. Token storage

Decision: Hashed (SHA-256). Token shown once at creation, stored as SHA-256 hash. Lookup: hash(incoming_token) → query by hash. If lost, user must create a new token.

---

Phase 2: Distribution-Scoped Permissions

Goal: Control who can publish/yank on which distribution (registry), using Pulp's existing RBAC.

2a. Define permissions

Add to RustDistribution.Meta.permissions:

permissions = [
    ("publish_rustdistribution", "Publish crates to this distribution"),
    ("yank_rustdistribution", "Yank/unyank crates in this distribution"),
]

2b. Define roles

LOCKED_ROLES = [
    {
        "role": "rust.distribution_publisher",
        "permissions": [
            "rust.publish_rustdistribution",
            "rust.yank_rustdistribution",
            "rust.view_rustdistribution",
        ],
    },
    {
        "role": "rust.distribution_viewer",
        "permissions": [
            "rust.view_rustdistribution",
        ],
    },
]

2c. Update access policies

On publish/yank/unyank endpoints, check has_obj_perms:rust.publish_rustdistribution (or yank_rustdistribution) against the distribution being operated on.

2d. Token scoping (optional enhancement)

Add scope fields to CargoToken:

• distributions — M2M to RustDistribution (empty = all the user has access to)
• actions — JSON list of allowed actions (["publish", "yank"], empty = all)

This mirrors crates.io's RFC 2947 token scoping. Can be deferred.

---

Phase 3: Crate Ownership (deferred)

Goal: Track who owns which crate names, and only allow owners to publish new versions or yank. Deferred — any authenticated user with distribution-level permission can publish any crate name for now.

3a. CrateOwnership model

class CrateOwnership(BaseModel):
    distribution = models.ForeignKey(RustDistribution, on_delete=models.CASCADE)
    crate_name = models.CharField(max_length=255)
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)

    class Meta:
        unique_together = ("distribution", "crate_name", "user")

• Scoped per-distribution (different registries can have different owners for the same crate name)
• First publisher of a crate name automatically becomes owner
• Owners can add/remove other owners

3b. Ownership endpoints

Implement the Cargo owner API:

• GET /api/v1/crates/{name}/owners — list owners
• PUT /api/v1/crates/{name}/owners — add owner (body: {"users": ["username"]})
• DELETE /api/v1/crates/{name}/owners — remove owner

3c. Publish authorization check

In CargoPublishApiView.put():

1. If the crate name has no owners yet → allow (auto-assign publisher as owner)
2. If the crate name has owners → only allow if request.user is an owner

3d. Yank authorization check

Only crate owners (or distribution admins) can yank/unyank.

---

Phase 4: auth-required mode

Goal: Support private registries where even downloads and index browsing require authentication.

4a. Make auth-required configurable

Add auth_required boolean field to RustDistribution model. Serve it in config.json:

data = {
    "dl": self.base_download_url,
    "api": self.base_api_url,
    "auth-required": distribution.auth_required,
}

4b. Enforce on read endpoints

When auth_required is True on a distribution:

• CargoIndexApiViewSet.retrieve() requires authentication
• CargoDownloadApiView.get() requires authentication
• IndexRoot.retrieve() (config.json) should return 401 without auth, which triggers Cargo's automatic retry with credentials

---

Implementation Order & Dependencies

Phase	Depends On	Scope
1 (tokens)	Nothing	New model, auth class, viewset, migration
2 (distribution perms)	Phase 1	Permissions, roles, access policy updates
3 (crate ownership)	Phase 1	New model, owner endpoints, publish/yank checks
4 (auth-required)	Phase 1	Distribution field, read-endpoint enforcement

Phases 2, 3, and 4 are independent of each other and can be done in any order after Phase 1.

---

Key Files

• pulp_rust/app/auth.py — current stub decorator, will be replaced with CargoTokenAuthentication
• pulp_rust/app/models.py — add CargoToken, later CrateOwnership
• pulp_rust/app/views.py — CargoPublishApiView, CargoDownloadApiView, IndexRoot
• pulp_rust/app/viewsets.py — add CargoTokenViewSet
• pulp_rust/app/serializers.py — add token serializers
• pulpcore/app/authentication.py — reference for auth class patterns
• pulpcore/app/models/role.py — Role, UserRole, GroupRole
• pulpcore/app/access_policy.py — AccessPolicyFromDB
• pulp_container/app/models.py — ContainerNamespace (prior art for namespace permissions)

Decisions Made

• Token storage: Hashed (SHA-256). Token shown once at creation, not recoverable.
• /me endpoint: Yes, implement for cargo login verification.
• Crate ownership: Deferred. Distribution-level permissions are sufficient for now.