feat(auth): add scoped temporary credentials

.github/workflows/docker-publish.yml

@@ -36,6 +36,20 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      - name: Verify release tag matches Cargo version
+        shell: bash
+        run: |
+          set -euo pipefail
+          package_version="$(awk '
+            /^\[workspace.package\]$/ { in_workspace = 1; next }
+            in_workspace && /^version = / {
+              gsub(/"/, "", $3)
+              print $3
+              exit
+            }
+          ' Cargo.toml)"
+          test "${GITHUB_REF_NAME}" = "v${package_version}"
+
       - name: Log in to Docker Hub
         uses: docker/login-action@v3
         with:
@@ -47,7 +61,7 @@ jobs:
         uses: houseabsolute/actions-rust-cross@v1
         with:
           target: ${{ matrix.target.arch }}-unknown-linux-musl
-          toolchain: 1.88.0
+          toolchain: 1.98.0
           args: "--locked --release --bin pb-mapper"
           strip: true
 

.github/workflows/release-ui.yml

@@ -80,7 +80,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
       - name: Build latest Windows FFI
         run: |
           make build-pb-mapper-ffi-windows
@@ -128,7 +128,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
       - name: Install dependencies
         run: |
           sudo apt-get update -y
@@ -236,7 +236,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
       - name: Set up Android NDK
         uses: nttld/setup-ndk@v1
         with:
@@ -399,7 +399,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
       - name: Install appdmg
         run: |
           npm install -g appdmg
@@ -480,7 +480,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
       - name: Build latest iOS FFI
         run: |
           make build-pb-mapper-ffi-ios

.github/workflows/release.yml

@@ -61,7 +61,7 @@ jobs:
         uses: houseabsolute/actions-rust-cross@v1
         with:
           target: ${{ matrix.platform.target }}
-          toolchain: 1.88.0
+          toolchain: 1.98.0
           args: "--locked --release --bin pb-mapper"
           strip: true
 
@@ -77,3 +77,7 @@ jobs:
             LICENSE
             README.md
             README.zh-CN.md
+            docs/authentication-v2.md
+            docs/authentication-v2.zh-CN.md
+            docs/user-guide.md
+            docs/user-guide.zh-CN.md

.github/workflows/syntax-check.yml

@@ -62,8 +62,11 @@ jobs:
               # belongs to the Rust side and must be matched before ui/*.
               ui/native/*) rust=true ;;
               ui/*) flutter=true ;;
-              src/*|tests/*|examples/*) rust=true ;;
+              crates/*|src/*|tests/*|examples/*) rust=true ;;
               Cargo.toml|Cargo.lock|rust-toolchain.toml|rustfmt.toml) rust=true ;;
+              # Per-crate manifests. `case` patterns match the whole path, so
+              # the unanchored entry above only ever catches the root manifest.
+              */Cargo.toml|*/Cargo.lock) rust=true ;;
               # A change to this workflow has to prove itself on both.
               .github/workflows/syntax-check.yml) rust=true; flutter=true ;;
             esac
@@ -88,7 +91,7 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: 1.88.0
+          toolchain: 1.98.0
           components: clippy, rustfmt
 
       - name: Cache Rust dependencies

AGENTS.md

@@ -1,19 +1,24 @@
 # Repository Guidelines
 
 ## Architecture Overview
-- One `pb-mapper` binary in `src/bin/` with four role commands:
+- One `pb-mapper` binary in `crates/pb-mapper-cli/src/bin/` with five role commands:
   - `server`: central router (default port 7666)
   - `register`: registers local TCP/UDP services with the router
   - `connect`: connects to a registered service and exposes a local port
   - `status`: queries router IDs and registered keys
-- Core crates: `src/pb_server`, `src/local/{server,client}`, `src/common` (protocol, streams, listeners), `src/utils`.
+  - `admin`: issues, lists, and revokes credentials; rotates the administrator key
+- Crates, bottom-up: `pb-mapper-core` (credentials, checksum, config, addressing)
+  → `pb-mapper-auth` (credential lifecycle and persistence) → `pb-mapper-protocol`
+  (framing and secure sessions) → `pb-mapper-server` and `pb-mapper-client`, which
+  are peers → `pb-mapper-cli`. `ui/native/pb_mapper_ffi` is the C ABI cdylib.
 
 ## Project Structure & Modules
-- `src/`: Rust backend and CLI
-  - `src/bin/pb-mapper.rs`: unified CLI entry point
-  - `src/pb_server`, `src/local`, `src/common`, `src/utils`
+- `crates/`: the Rust workspace; the root `Cargo.toml` is a virtual manifest
+  - `crates/pb-mapper-cli/src/bin/pb-mapper.rs`: unified CLI entry point
+  - `crates/pb-mapper-{core,auth,protocol,server,client,cli}`
+  - `crates/pb-mapper-cli/tests/`: integration tests; loads env from `tests/.env`
+  - `crates/pb-mapper-cli/examples/`: runnable examples
 - `ui/`: Flutter UI; Rust bridge under `ui/native/*`
-- `tests/`: integration tests; loads env from `tests/.env`
 - `docker/`, `services/`, `scripts/`: container, systemd, build/release
 
 ## Build, Test, and Development Commands
@@ -28,7 +33,9 @@
 Notes: CI builds release artifacts on tags `vX.Y.Z` (see `.github/workflows/release.yml`).
 
 ## Coding Style & Naming Conventions
-- Rust 2021; toolchain pinned via `rust-toolchain.toml` (CI uses 1.88.0)
+- Edition is set once in `[workspace.package]`; the toolchain is pinned in
+  `rust-toolchain.toml`, which CI installs. Both are deliberately not repeated
+  here — a version in prose goes stale on the next upgrade.
 - Format: `cargo fmt --all` (4 spaces; import grouping per `rustfmt.toml`)
 - Lint: `cargo clippy --all-targets -- -D warnings`
 - Naming: modules/functions `snake_case`, types/traits `PascalCase`, consts `SCREAMING_SNAKE_CASE`

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-08-18
+- Added a sole administrator credential plus renewable, expiring, and immediately revocable `pbmt1_` temporary credentials with fixed-slot O(1) lookup and isolated per-key service namespaces.
+- Added single-flight protocol-v2 authentication with directional AES-256-GCM keys, monotonic frame counters, authenticated routing metadata, durable first-flight replay protection, and optional legacy framing during migration.
+- Added encrypted snapshot/WAL authentication state, exclusive `auth.lock`, lifecycle audit records, hierarchical timing-wheel expiry, hard closure of revoked live connections, recoverable root-key rotation, and explicit auth-state reset.
+- Extended the unified CLI with temporary-key lifecycle, service/connection inventory, auth status, protocol policy, root rotation, namespace targeting, and human/JSON/NDJSON output.
+- Replaced insecure default-key fallback with first-start random administrator-key generation, retained machine-derived keys only for explicit compatibility, and updated Flutter, installers, systemd, Docker, release metadata, and bilingual documentation.
+- Recovery keys must decrypt existing snapshot or WAL state before they are persisted. Interrupted rotation and reset recover from staged `admin.key.next` and `server-instance-id.next`.
+- First-flight salts are unique for nonce 0: admission is atomic under one lock, torn replay records fail closed, and a nonce-0 error frame is sent only after that salt is reserved.
+- Pinned UI and local tunnels to the credential and relay address captured at start, and bound tunneled-frame checksums to each hop's authenticated session key.
+- Aborted pooled registration workers and accepted connection tasks on shutdown; the relay reaps connection tasks with a `JoinSet`.
+
 ## [0.3.0] - 2026-08-18
 - Replaced the three role-specific executables with one `pb-mapper` CLI and explicit `server`, `register`, `connect`, and `status` commands.
 - Consolidated release archives into one cross-platform binary artifact per target and updated Docker, installers, systemd templates, build scripts, deployment skills, and documentation to use it.