devpi-admin 1.3.0__tar.gz → 1.4.0__tar.gz

{devpi_admin-1.3.0 → devpi_admin-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devpi-admin
-Version: 1.3.0
+Version: 1.4.0
 Summary: Modern web UI plugin for devpi-server — drop-in replacement for devpi-web
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License: MIT
@@ -38,16 +38,16 @@ talks to the standard devpi JSON API directly.
 - Server info with version of devpi-server and all installed plugins (auto-detected)
 - Cache metrics with hit-rate bars (storage, changelog, relpath caches)
 - Whoosh search index queue status
-- **Replica status** (master only, authenticated users only) - per-replica cards with
-  authoritative `applied_serial` vs. master serial. Three states:
-  - **in sync** - replica matches master serial
+- **Replica status** (primary only, authenticated users only) - per-replica cards with
+  authoritative `applied_serial` vs. primary serial. Three states:
+  - **in sync** - replica matches primary serial
   - **lagging** - replica is behind but advancing
   - **stuck** - replica has been polling the same serial for >=30 s; usually means a
     server-side plugin (`devpi-admin`, `devpi-web`, ...) is missing or out of date on the replica
 - **Topbar health indicator** - the `devpi admin` logo is coloured green / orange / red
   on every page, refreshed every 30 s in the background:
   - server reachable, all replicas in sync
-  - at least one replica lagging (visible to authenticated master operators)
+  - at least one replica lagging (visible to authenticated primary operators)
   - server not responding
 
 ### Indexes
@@ -55,19 +55,13 @@ talks to the standard devpi JSON API directly.
 - Warning tags for ACL edge cases:
   - **`world-writable`** - `acl_upload` contains `:ANONYMOUS:`; supply-chain risk
   - **`no upload`** - `acl_upload` is empty; nobody (not even owner / root) can publish
-- Adaptive kebab menu - items hint whether a token will be issued:
-  - **`pip.conf`** (public read index, no auth needed) vs. **`pip.conf + token`** (private read)
-  - **`.pypirc`** (public upload, no auth needed) vs. **`.pypirc + token`** (private upload).
-    Hidden when nobody can upload (`acl_upload` empty).
-- **`pip.conf` modal** - issues a short-lived `read`-scope token bound to the index. Returns
-  the full `pip.conf` (Copy / Download), a one-off `pip install --index-url ...` command, and
-  the raw `user:token` pair for `curl`, `devpi login`, etc. Anonymous-readable indexes show
-  a static pip.conf without credentials.
-- **`.pypirc` modal** - issues an `upload`-scope token bound to the index. Returns the full
-  `.pypirc` (Copy / Download), `TWINE_*` environment variable block, a one-shot
-  `twine upload --repository-url ... -u ... -p ... dist/*` command, and the raw `user:token`
-  pair. Anonymous-upload indexes (rare; world-writable) show a static `.pypirc` without
-  credentials and a security warning.
+- Index card kebab:
+  - **`pip.conf`** (public indexes only) — static one-click pip.conf with the index URL,
+    no token issuance needed
+  - **`Tokens`** (owner / root only) — opens the per-index unified Tokens modal with two
+    sections (Admin + Devpi), shows existing tokens for this index, lets you issue new
+    ones with the index pre-filled and locked
+  - **`Edit`** / **`Delete`** (owner / root)
 - Create / edit / delete indexes via modal dialogs
 - `bases` editor with drag & drop priority ordering and transitive inheritance display
 - `acl_upload` and `acl_read` tag pickers with user selection dropdown
@@ -132,8 +126,9 @@ talks to the standard devpi JSON API directly.
   users (admin delegation) but not for itself. Admin-token-authenticated requests cannot
   issue further tokens. Issuance verifies the target user is in `acl_read` /
   `acl_upload` of the target index.
-- **Management rules**: list / revoke is allowed for the token owner or root. Per-index
-  token list endpoint shows only the caller's own tokens (root sees all).
+- **Management rules**: list / revoke is allowed for the token owner or root. The
+  per-index token list shows all tokens for **index owner / root**; other callers see
+  only tokens bound to themselves.
 - **Auto-cleanup**:
   - User delete -> all tokens for that user removed from keyfs
   - Index delete -> all tokens bound to that index removed (USER subscriber diffs the
@@ -147,9 +142,33 @@ talks to the standard devpi JSON API directly.
 
 ### Users
 - Create, edit (email, password), delete users (admin only)
-- **Tokens manager** (kebab -> Tokens) - per-user list with label, **index, scope**,
-  expiry, issuer, IP; revoke individual or "Reset all". Wide modal layout so the table
-  doesn't overflow on stage indexes with long names.
+- **Tokens manager** (kebab -> Tokens) - unified modal with one or two sections:
+  - **Admin tokens** (built-in) — per-user list with label, index, scope, expiry,
+    issuer, IP; individual revoke or "Reset all"
+  - **Devpi tokens** (only when the `devpi-tokens` plugin is installed) — list of
+    macaroon tokens with parsed restrictions (indexes, allowed permissions, projects,
+    expires, not-before); individual revoke
+  - Empty sections hide automatically (no clutter). Banner above Devpi section
+    (dismissible per user) explains the different threat model — raw secret in keyfs
+    vs. hash-only Admin storage.
+- **Issue token** (`+ Issue new` button) — single unified modal for both backends:
+  - Token type selector at the top picks Admin vs. Devpi (Devpi default when the
+    plugin is installed). Hidden when only Admin is available.
+  - Index picker shows everything the bound user can access (owns, or appears in
+    `acl_read` / `acl_upload`). Devpi uses a multi tag picker; Admin uses a single
+    select.
+  - Admin scope dropdown adapts to the picked index: public indexes get only
+    `upload` (read tokens are useless when anyone can read), private indexes get
+    both with `read` as default.
+  - Devpi permissions are checkboxes; destructive operations (`del_*`,
+    `index_modify`, `index_delete`) are tucked behind an "Advanced" toggle with a
+    visual warning.
+  - Expiry: presets (1 hour to 1 year) plus a `Custom…` datetime option. Optional
+    Not-before for delayed activation (Devpi only).
+  - On success the modal swaps to a read-once view with the raw token, pip.conf,
+    `.pypirc`, `TWINE_*` env, and a `user:token` pair — but only the configs that
+    actually match the issued token's intent (no pip.conf for upload-only or
+    public-index tokens; no `.pypirc` for read-only tokens).
 
 ### Packages
 - Client-side search with PEP 503 name normalization and relevance ranking
@@ -210,10 +229,10 @@ for HTML requests while `devpi-web` would still serve its own HTML on other rout
 ### Replicas: install on every node
 
 `devpi-admin` registers custom keyfs keys (`+admin/tokens/...`,
-`+admin/user-tokens/...`, `+admin/index-tokens/...`). Master writes to these on every
-token issue / revoke. **Replicas without `devpi-admin` installed cannot apply those
-changelog entries** - `import_changes` fails with `AssertionError` on the missing
-keyfs key, the replica rolls back to the prior serial, and replication stalls.
+`+admin/user-tokens/...`, `+admin/index-tokens/...`). The primary writes to these on
+every token issue / revoke. **Replicas without `devpi-admin` installed cannot apply
+those changelog entries** - `import_changes` fails with `AssertionError` on the
+missing keyfs key, the replica rolls back to the prior serial, and replication stalls.
 
 The dashboard's stuck-replica detection is designed exactly for this: a `stuck`
 state on a replica card almost always means a plugin (typically `devpi-admin` itself,
@@ -222,14 +241,14 @@ is straightforward:
 
 ```bash
 # on the replica
-~/.venv/bin/pip install --upgrade devpi-admin   # match master version
+~/.venv/bin/pip install --upgrade devpi-admin   # match primary version
 systemctl restart devpi
 ```
 
 Replication resumes from the failed serial automatically - no manual keyfs surgery.
 
-**Upgrade order:** replicas first, then master. If you upgrade master first and that
-release introduces a new keyfs key, replicas would crash on the very next poll.
+**Upgrade order:** replicas first, then primary. If you upgrade the primary first and
+that release introduces a new keyfs key, replicas would crash on the very next poll.
 
 See `INSTALL.md` section 11 for full step-by-step replica setup and dashboard interpretation.
 
@@ -255,6 +274,51 @@ ExecStart=/opt/pypi/venv/bin/devpi-server \
 
 See `INSTALL.md` for a full systemd unit example.
 
+### Optional plugins
+
+#### `devpi-tokens` coexistence
+
+`devpi-admin` plays nicely with the optional `devpi-tokens` plugin. When
+installed, the SPA detects it (via `/+api` features list and `/+status`
+versioninfo) and **automatically merges Devpi tokens into the same Tokens
+modal** that lists Admin tokens — same kebab item ("Tokens"), same
+"+ Issue new" flow, same per-index Tokens modal. The user picks the
+backend in the Issue form via a token-type selector.
+
+```bash
+/var/lib/pypi/venv/bin/pip install devpi-tokens
+systemctl --user restart devpi
+```
+
+The two token systems run side by side without conflict:
+
+| | Admin tokens | Devpi tokens |
+|---|---|---|
+| Plugin | `devpi-admin` (built-in) | `devpi-tokens` (optional) |
+| Storage | SHA-256 hash in keyfs | Raw HMAC key in keyfs |
+| Listable (incl. derived) | yes, all | initial only — derived macaroons are stateless |
+| Audit log on lookup | yes | no |
+| HTTP method whitelist | `read` blocks DELETE; `upload` blocks DELETE | relies on `--allowed` permission filter |
+| Multi-index per token | no (1:1) | yes |
+| Per-project filter | no | yes (`--projects`) |
+| Cross-user index | no (must be in ACL) | yes (any user/index pair) |
+| CLI compatibility | UI / API only | works with `devpi token-login` |
+
+**Threat model note.** Macaroon HMAC verification requires the secret in
+plaintext on the server, so `devpi-tokens` cannot hash-store; a leaked
+backup or replica disk dump exposes working credentials. Prefer Admin
+tokens for privileged workflows. The UI surfaces this via a (dismissible
+per-user) security banner above the Devpi section of every Tokens modal.
+
+`acl_read` (provided by `devpi-admin`) applies to both token systems
+identically — devpi evaluates `pkg_read` ACL against whichever identity
+the auth chain produced, regardless of token source.
+
+**Testing without the plugin installed.** Append `?no-devpi-tokens` to any
+SPA URL to make the UI behave as if the plugin weren't there (kebab item
+disappears, type selector hides, etc.). Saves you a `pip uninstall + restart`
+round-trip when verifying graceful degradation.
+
 ## Usage
 
 After restart, open:
@@ -527,7 +591,7 @@ Revoke a single token.
 - **200:** `{"revoked": true, "id": "abc..."}`
 - **404:** token id not found
 
-### Replication observability (master only)
+### Replication observability (primary only)
 
 #### `GET /+admin-api/replicas`
 Last-known poll info per replica, captured from each `GET /+changelog/{N}-` request via
@@ -538,7 +602,7 @@ applied (`start_serial - 1` from its most recent poll). Compare against `/+statu
 Why this isn't `polling_replicas` from `/+status`: devpi-server overwrites
 `xom.polling_replicas[uuid].serial` during streaming and gives a misleading "caught up"
 reading once the response generator drains. Capturing `start_serial` at the request
-boundary is the only stable signal master alone can produce.
+boundary is the only stable signal the primary alone can produce.
 
 - **Auth:** required
 - **200:**
@@ -558,7 +622,7 @@ boundary is the only stable signal master alone can produce.
   }
   ```
 - Entries auto-expire after 10 min of silence. Dict size capped at 256 entries
-  (least-recently-seen evicted first) so an attacker spamming UUIDs cannot exhaust master memory.
+  (least-recently-seen evicted first) so an attacker spamming UUIDs cannot exhaust primary memory.
 
 ## Project layout
 

{devpi_admin-1.3.0 → devpi_admin-1.4.0}/README.md

@@ -14,16 +14,16 @@ talks to the standard devpi JSON API directly.
 - Server info with version of devpi-server and all installed plugins (auto-detected)
 - Cache metrics with hit-rate bars (storage, changelog, relpath caches)
 - Whoosh search index queue status
-- **Replica status** (master only, authenticated users only) - per-replica cards with
-  authoritative `applied_serial` vs. master serial. Three states:
-  - **in sync** - replica matches master serial
+- **Replica status** (primary only, authenticated users only) - per-replica cards with
+  authoritative `applied_serial` vs. primary serial. Three states:
+  - **in sync** - replica matches primary serial
   - **lagging** - replica is behind but advancing
   - **stuck** - replica has been polling the same serial for >=30 s; usually means a
     server-side plugin (`devpi-admin`, `devpi-web`, ...) is missing or out of date on the replica
 - **Topbar health indicator** - the `devpi admin` logo is coloured green / orange / red
   on every page, refreshed every 30 s in the background:
   - server reachable, all replicas in sync
-  - at least one replica lagging (visible to authenticated master operators)
+  - at least one replica lagging (visible to authenticated primary operators)
   - server not responding
 
 ### Indexes
@@ -31,19 +31,13 @@ talks to the standard devpi JSON API directly.
 - Warning tags for ACL edge cases:
   - **`world-writable`** - `acl_upload` contains `:ANONYMOUS:`; supply-chain risk
   - **`no upload`** - `acl_upload` is empty; nobody (not even owner / root) can publish
-- Adaptive kebab menu - items hint whether a token will be issued:
-  - **`pip.conf`** (public read index, no auth needed) vs. **`pip.conf + token`** (private read)
-  - **`.pypirc`** (public upload, no auth needed) vs. **`.pypirc + token`** (private upload).
-    Hidden when nobody can upload (`acl_upload` empty).
-- **`pip.conf` modal** - issues a short-lived `read`-scope token bound to the index. Returns
-  the full `pip.conf` (Copy / Download), a one-off `pip install --index-url ...` command, and
-  the raw `user:token` pair for `curl`, `devpi login`, etc. Anonymous-readable indexes show
-  a static pip.conf without credentials.
-- **`.pypirc` modal** - issues an `upload`-scope token bound to the index. Returns the full
-  `.pypirc` (Copy / Download), `TWINE_*` environment variable block, a one-shot
-  `twine upload --repository-url ... -u ... -p ... dist/*` command, and the raw `user:token`
-  pair. Anonymous-upload indexes (rare; world-writable) show a static `.pypirc` without
-  credentials and a security warning.
+- Index card kebab:
+  - **`pip.conf`** (public indexes only) — static one-click pip.conf with the index URL,
+    no token issuance needed
+  - **`Tokens`** (owner / root only) — opens the per-index unified Tokens modal with two
+    sections (Admin + Devpi), shows existing tokens for this index, lets you issue new
+    ones with the index pre-filled and locked
+  - **`Edit`** / **`Delete`** (owner / root)
 - Create / edit / delete indexes via modal dialogs
 - `bases` editor with drag & drop priority ordering and transitive inheritance display
 - `acl_upload` and `acl_read` tag pickers with user selection dropdown
@@ -108,8 +102,9 @@ talks to the standard devpi JSON API directly.
   users (admin delegation) but not for itself. Admin-token-authenticated requests cannot
   issue further tokens. Issuance verifies the target user is in `acl_read` /
   `acl_upload` of the target index.
-- **Management rules**: list / revoke is allowed for the token owner or root. Per-index
-  token list endpoint shows only the caller's own tokens (root sees all).
+- **Management rules**: list / revoke is allowed for the token owner or root. The
+  per-index token list shows all tokens for **index owner / root**; other callers see
+  only tokens bound to themselves.
 - **Auto-cleanup**:
   - User delete -> all tokens for that user removed from keyfs
   - Index delete -> all tokens bound to that index removed (USER subscriber diffs the
@@ -123,9 +118,33 @@ talks to the standard devpi JSON API directly.
 
 ### Users
 - Create, edit (email, password), delete users (admin only)
-- **Tokens manager** (kebab -> Tokens) - per-user list with label, **index, scope**,
-  expiry, issuer, IP; revoke individual or "Reset all". Wide modal layout so the table
-  doesn't overflow on stage indexes with long names.
+- **Tokens manager** (kebab -> Tokens) - unified modal with one or two sections:
+  - **Admin tokens** (built-in) — per-user list with label, index, scope, expiry,
+    issuer, IP; individual revoke or "Reset all"
+  - **Devpi tokens** (only when the `devpi-tokens` plugin is installed) — list of
+    macaroon tokens with parsed restrictions (indexes, allowed permissions, projects,
+    expires, not-before); individual revoke
+  - Empty sections hide automatically (no clutter). Banner above Devpi section
+    (dismissible per user) explains the different threat model — raw secret in keyfs
+    vs. hash-only Admin storage.
+- **Issue token** (`+ Issue new` button) — single unified modal for both backends:
+  - Token type selector at the top picks Admin vs. Devpi (Devpi default when the
+    plugin is installed). Hidden when only Admin is available.
+  - Index picker shows everything the bound user can access (owns, or appears in
+    `acl_read` / `acl_upload`). Devpi uses a multi tag picker; Admin uses a single
+    select.
+  - Admin scope dropdown adapts to the picked index: public indexes get only
+    `upload` (read tokens are useless when anyone can read), private indexes get
+    both with `read` as default.
+  - Devpi permissions are checkboxes; destructive operations (`del_*`,
+    `index_modify`, `index_delete`) are tucked behind an "Advanced" toggle with a
+    visual warning.
+  - Expiry: presets (1 hour to 1 year) plus a `Custom…` datetime option. Optional
+    Not-before for delayed activation (Devpi only).
+  - On success the modal swaps to a read-once view with the raw token, pip.conf,
+    `.pypirc`, `TWINE_*` env, and a `user:token` pair — but only the configs that
+    actually match the issued token's intent (no pip.conf for upload-only or
+    public-index tokens; no `.pypirc` for read-only tokens).
 
 ### Packages
 - Client-side search with PEP 503 name normalization and relevance ranking
@@ -186,10 +205,10 @@ for HTML requests while `devpi-web` would still serve its own HTML on other rout
 ### Replicas: install on every node
 
 `devpi-admin` registers custom keyfs keys (`+admin/tokens/...`,
-`+admin/user-tokens/...`, `+admin/index-tokens/...`). Master writes to these on every
-token issue / revoke. **Replicas without `devpi-admin` installed cannot apply those
-changelog entries** - `import_changes` fails with `AssertionError` on the missing
-keyfs key, the replica rolls back to the prior serial, and replication stalls.
+`+admin/user-tokens/...`, `+admin/index-tokens/...`). The primary writes to these on
+every token issue / revoke. **Replicas without `devpi-admin` installed cannot apply
+those changelog entries** - `import_changes` fails with `AssertionError` on the
+missing keyfs key, the replica rolls back to the prior serial, and replication stalls.
 
 The dashboard's stuck-replica detection is designed exactly for this: a `stuck`
 state on a replica card almost always means a plugin (typically `devpi-admin` itself,
@@ -198,14 +217,14 @@ is straightforward:
 
 ```bash
 # on the replica
-~/.venv/bin/pip install --upgrade devpi-admin   # match master version
+~/.venv/bin/pip install --upgrade devpi-admin   # match primary version
 systemctl restart devpi
 ```
 
 Replication resumes from the failed serial automatically - no manual keyfs surgery.
 
-**Upgrade order:** replicas first, then master. If you upgrade master first and that
-release introduces a new keyfs key, replicas would crash on the very next poll.
+**Upgrade order:** replicas first, then primary. If you upgrade the primary first and
+that release introduces a new keyfs key, replicas would crash on the very next poll.
 
 See `INSTALL.md` section 11 for full step-by-step replica setup and dashboard interpretation.
 
@@ -231,6 +250,51 @@ ExecStart=/opt/pypi/venv/bin/devpi-server \
 
 See `INSTALL.md` for a full systemd unit example.
 
+### Optional plugins
+
+#### `devpi-tokens` coexistence
+
+`devpi-admin` plays nicely with the optional `devpi-tokens` plugin. When
+installed, the SPA detects it (via `/+api` features list and `/+status`
+versioninfo) and **automatically merges Devpi tokens into the same Tokens
+modal** that lists Admin tokens — same kebab item ("Tokens"), same
+"+ Issue new" flow, same per-index Tokens modal. The user picks the
+backend in the Issue form via a token-type selector.
+
+```bash
+/var/lib/pypi/venv/bin/pip install devpi-tokens
+systemctl --user restart devpi
+```
+
+The two token systems run side by side without conflict:
+
+| | Admin tokens | Devpi tokens |
+|---|---|---|
+| Plugin | `devpi-admin` (built-in) | `devpi-tokens` (optional) |
+| Storage | SHA-256 hash in keyfs | Raw HMAC key in keyfs |
+| Listable (incl. derived) | yes, all | initial only — derived macaroons are stateless |
+| Audit log on lookup | yes | no |
+| HTTP method whitelist | `read` blocks DELETE; `upload` blocks DELETE | relies on `--allowed` permission filter |
+| Multi-index per token | no (1:1) | yes |
+| Per-project filter | no | yes (`--projects`) |
+| Cross-user index | no (must be in ACL) | yes (any user/index pair) |
+| CLI compatibility | UI / API only | works with `devpi token-login` |
+
+**Threat model note.** Macaroon HMAC verification requires the secret in
+plaintext on the server, so `devpi-tokens` cannot hash-store; a leaked
+backup or replica disk dump exposes working credentials. Prefer Admin
+tokens for privileged workflows. The UI surfaces this via a (dismissible
+per-user) security banner above the Devpi section of every Tokens modal.
+
+`acl_read` (provided by `devpi-admin`) applies to both token systems
+identically — devpi evaluates `pkg_read` ACL against whichever identity
+the auth chain produced, regardless of token source.
+
+**Testing without the plugin installed.** Append `?no-devpi-tokens` to any
+SPA URL to make the UI behave as if the plugin weren't there (kebab item
+disappears, type selector hides, etc.). Saves you a `pip uninstall + restart`
+round-trip when verifying graceful degradation.
+
 ## Usage
 
 After restart, open:
@@ -503,7 +567,7 @@ Revoke a single token.
 - **200:** `{"revoked": true, "id": "abc..."}`
 - **404:** token id not found
 
-### Replication observability (master only)
+### Replication observability (primary only)
 
 #### `GET /+admin-api/replicas`
 Last-known poll info per replica, captured from each `GET /+changelog/{N}-` request via
@@ -514,7 +578,7 @@ applied (`start_serial - 1` from its most recent poll). Compare against `/+statu
 Why this isn't `polling_replicas` from `/+status`: devpi-server overwrites
 `xom.polling_replicas[uuid].serial` during streaming and gives a misleading "caught up"
 reading once the response generator drains. Capturing `start_serial` at the request
-boundary is the only stable signal master alone can produce.
+boundary is the only stable signal the primary alone can produce.
 
 - **Auth:** required
 - **200:**
@@ -534,7 +598,7 @@ boundary is the only stable signal master alone can produce.
   }
   ```
 - Entries auto-expire after 10 min of silence. Dict size capped at 256 entries
-  (least-recently-seen evicted first) so an attacker spamming UUIDs cannot exhaust master memory.
+  (least-recently-seen evicted first) so an attacker spamming UUIDs cannot exhaust primary memory.
 
 ## Project layout
 

{devpi_admin-1.3.0 → devpi_admin-1.4.0}/devpi_admin/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.3.0'
-__version_tuple__ = version_tuple = (1, 3, 0)
+__version__ = version = '1.4.0'
+__version_tuple__ = version_tuple = (1, 4, 0)
 
-__commit_id__ = commit_id = 'gca7f689da'
+__commit_id__ = commit_id = 'gc695723cf'

{devpi_admin-1.3.0 → devpi_admin-1.4.0}/devpi_admin/main.py

@@ -1345,7 +1345,11 @@ def _list_index_tokens_view(request):
         # Hide existence from anyone without read access.
         raise HTTPNotFound(json_body={"error": "index not found"})
     items = tokens.list_for_index(xom, idx_user, idx_name)
-    if auth_user != "root":
+    # Index owner / root see every token bound to this index — they're
+    # the people responsible for revoke decisions and need full audit
+    # visibility. Non-owners see only their own tokens (the bound user
+    # they themselves authenticate as), matching the per-user listing.
+    if auth_user != "root" and auth_user != idx_user:
         items = [(tid, meta) for tid, meta in items
                  if meta.get("user") == auth_user]
     result = [_format_token_record(tid, meta) for tid, meta in items]