design-15: user names + v2 sidecar regeneration (sb meta) - #2
Merged
Conversation
sb user add/del payloads now carry a per-user name (the design-15 §5
derived u_<hash>) in every protocol's user object, and add/del matching
also keys on name, so renamed credentials stay idempotent. name is the
join key sing-box uses for auth metadata, auth_user route rules, and
per-user stats counters.
New `sb meta` command regenerates the sidecar in
lattice.singbox-metadata.v2 shape: existing v2 line_uuid or v1
lines{}.line_id identity is preserved per conf file (v1 line_id is
adopted as the v2 line_uuid), fresh uuids only for lines with no
identity; the v1 .node/.lines keys are kept alongside so pre-v2 readers
keep working. It is the on-box fallback writer — the Lattice server
stays the authoritative one.
tests/design-15-user-meta.sh is the repo's first test harness: it
extracts the functions under test and asserts user-obj name handling,
name-keyed matching, meta regeneration, v1 upgrade, idempotent rerun,
chain preservation, and the missing-node-id failure (22 assertions).
design-15 §8 / ADR-004: toggles experimental.v2ray_api in config.json through the same atomic jq + check + rollback pattern as sb user, restricted to loopback listens (a stats API must never bind a routable address) with port validation, then restarts the core. This is what the agent's singbox-stats collector dials (LATTICE_SINGBOX_STATS_API).
Make the sb Design 15 commands resolve configuration files and users by exact identity, reject ambiguous legacy matches and traversal, preserve validated sidecar extensions, enforce literal loopback stats listeners, and surface restart failures instead of reporting partial success. Constraint: Existing unambiguous legacy user selectors remain supported during migration. Rejected: Match name or any credential field | shared credentials can delete unrelated users. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Never turn restart failure or invalid sidecar input into ok=true. Tested: bash -n src/core.sh tests/design-15-user-meta.sh; design-15-user-meta.sh 41/41; git diff --check Not-tested: Full 233boy installer harness on HK, deferred to canary
lr00rl
force-pushed
the
feat/design-15-user-meta
branch
from
July 22, 2026 13:07
04f3b1c to
ebfcdbc
Compare
lr00rl
marked this pull request as ready for review
July 22, 2026 13:08
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
design-15 D3 companion slice for the Lattice per-line user write path (LatticeNet/lattice-server#14):
sb user add|del: every protocol's derived user object now carriesname(the design-15 §5u_<sha256(user|line_uuid)[:16]>) — the single join key for sing-box auth metadata,auth_userroute rules, anduser>>><name>>>>traffic>>>stats. Matching also keys onname, so credential rotation stays idempotent.sb meta: regenerates/etc/sing-box/lattice-metadata.jsoninlattice.singbox-metadata.v2shape — preserves existing v2line_uuid/ v1lines{}.line_idper conf file (v1 id adopted as v2line_uuid), mints fresh uuids only for identity-less lines, preserves declaredchainblocks, keeps v1.node/.lineskeys for older readers, and fails loud when node id is unknown. The Lattice server remains the authoritative writer; this is the on-box fallback/repair path.user/meta.Verification
tests/design-15-user-meta.sh(new, the repo's first harness): 22 assertions, all pass locally (bash extraction harness — user-obj name per protocol, name-keyed match, fresh/upgrade/idempotent/chain-preserving meta regeneration, missing-node-id failure)bash -nclean on core.sh/help.shStacked on #1. Refs LatticeNet/lattice#2, LatticeNet/lattice-server#14.