Skip to content

Commit 92c2fb2

Browse files
loganjLarry
andauthored
docs(names): specify portable identity disambiguation (#227)
Signed-off-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz> Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz>
1 parent fa6b4b7 commit 92c2fb2

4 files changed

Lines changed: 2123 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,7 @@ controls are included. Keep Buzz running for existing agents to answer selected
301301

302302
## Project resources
303303

304+
- [Contextual identity names: cross-client spec and fixtures](src/bundled/identity-naming/README.md)
304305
- [Contributing](docs/contributing.md)
305306
- [Project leads](CODEOWNERS)
306307
- [Governance](GOVERNANCE.md)
Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Contextual identity names
2+
3+
`version 1` · `client display contract` · `no wire changes`
4+
5+
## Abstract
6+
7+
This contract gives different public keys distinct readable labels in a client
8+
view. It prefers humans before agents, then the viewer's identities before other
9+
identities. It uses owner names before public-key suffixes. It compares only the
10+
identities relevant to that view, not every identity the client has ever seen.
11+
12+
The `buzz.identity-naming` plugin registers this policy through the shared
13+
identity-names service. This directory owns the spec and portable fixtures;
14+
the resolver currently lives in `src/features/identity-names/policy.ts`.
15+
16+
This is an extraction of the behavior merged in
17+
[buzz-app #167](https://github.com/block/buzz-app/pull/167), at
18+
`82bb3a6`. It is not a new Nostr event kind, ownership protocol, or claim that
19+
other clients already implement these rules. The normative resolver below and
20+
[portable fixtures](identity-names.fixtures.json) are independent of React,
21+
plugins, storage, and transport. The final section describes the current desktop
22+
adapter separately.
23+
24+
MUST, MUST NOT, SHOULD, and MAY have their RFC 2119 meanings.
25+
26+
## Scope and authority
27+
28+
A **key** is a Nostr public key, not a name, persona, local configuration ID,
29+
process, or community membership. Two configurations with the same key are one
30+
identity even when they have different displayed names (**aliases**).
31+
32+
Labels are presentation only. Clients MUST retain the exact key for profile
33+
navigation, mentions, notifications, and other identity-bound actions. Labels
34+
MUST NOT grant control, prove ownership, substitute one agent instance for
35+
another, change stored configuration names, or change signed message text and
36+
recipient tags. A configuration editor MUST retain its exact configuration ID.
37+
38+
This contract does not specify profile validation, ownership verification,
39+
agent admission, discovery completeness, sorting, layout, animation, or search.
40+
It does not solve visual impersonation (for example, Unicode confusables).
41+
42+
## Inputs and outputs
43+
44+
The resolver takes:
45+
46+
- An ordered list of identity facts: `pubkey`, `name`, optional `isAgent`, and
47+
optional `ownerPubkey`. Keys MUST be valid 32-byte keys encoded as 64 hex
48+
characters. `name` is a string. Missing `isAgent` means false. An owner fact
49+
does not by itself set `isAgent`.
50+
- An optional viewer key. Missing viewer means no identity is "mine".
51+
- An optional candidate-key set. Omission selects all supplied facts; an empty
52+
set selects none. A selected key with no fact produces no result.
53+
54+
The caller MUST choose names and classification facts before resolving labels.
55+
Missing profiles and application-specific fallback text belong to that step,
56+
not to collision resolution. An empty name is allowed by the resolver and is
57+
compared like any other string; clients SHOULD supply a useful fallback instead.
58+
Invalid keys are outside this resolver's contract and MUST be handled before it
59+
runs, not converted into fabricated identities.
60+
61+
The result is a map from lowercase key to `{name, qualifier}`. `name` is the full
62+
label. `qualifier` is absent unless a key suffix was added, in which case it is
63+
only the suffix, without the preceding ` · `. Readable owner prefixes and
64+
` (agent)` are part of `name`, not `qualifier`. Map iteration order has no meaning.
65+
66+
### Normalization and aliases
67+
68+
1. Lowercase all identity, owner, viewer, and candidate keys.
69+
2. Trim names at both ends using the following code points (ECMAScript
70+
`String.trim`): U+0009–000D, U+0020, U+00A0, U+1680, U+2000–200A,
71+
U+2028–2029, U+202F, U+205F, U+3000, and U+FEFF.
72+
3. Compare names and completed labels by exact string equality. MUST NOT case
73+
fold, normalize Unicode, collapse interior whitespace, or strip punctuation.
74+
`Honey` and `honey` are different; so are composed and decomposed accents.
75+
4. Keep the last supplied fact for each key as its **preferred fact**. This
76+
selects the alias returned for that key and the raw name used when that key
77+
is looked up as an owner, even if the owner is outside the candidate set.
78+
5. Keep one working row per `(key, trimmed name)` pair; the last fact for that
79+
pair supplies its metadata. Do not collapse different aliases of one key.
80+
6. Select working rows by the candidate set. All selected aliases participate
81+
in collision checks, including aliases that will not be returned.
82+
83+
Callers SHOULD supply consistent classification and owner facts for a key's
84+
aliases. Input order matters for last-fact selection, not as a way to award a
85+
plain label to one of two equally ranked keys. To request a particular alias,
86+
a caller can append that alias's fact after the complete displayed fact list.
87+
88+
## Choosing the comparison context
89+
90+
Clients implementing the same surface SHOULD use the following contexts. Two
91+
clients can guarantee equal output only with equal effective facts, viewer,
92+
preferred aliases, and candidate set. Loading more facts or changing the viewer
93+
can legitimately change a label.
94+
95+
| Surface | Candidates |
96+
| --- | --- |
97+
| Channel or thread identities | Channel members, plus the requested identity for a historical/non-member reference |
98+
| Mention picker | All actual selectable mention choices, before text-search filtering; not only matching search results |
99+
| Composer's selected mentions | Channel members, available agent choices (including invitation choices where offered), and already selected recipient keys |
100+
| DM participant labels | That DM's participants |
101+
| Agent directory/management | The displayed collection's keys and all displayed configured aliases, including cross-community aliases |
102+
| Local activity/filter choices | The local choice set; unknown keys use the surface's existing key-label fallback |
103+
104+
Owners may be supplied as lookup facts without making them collision candidates.
105+
Clients MUST NOT add the whole global profile cache to an explicitly scoped
106+
candidate set. A requested identity outside that set SHOULD be added before
107+
resolution. The low-level resolver does not add it automatically.
108+
109+
Labels MUST be recomputed from original facts when relevant names, ownership
110+
hints, classification, candidates, viewer, or configured aliases change. Do not
111+
feed a previously generated label back as an original name. Clients MAY cache
112+
results, provided all these inputs are part of invalidation. Incomplete facts
113+
are not proof of global uniqueness; this contract gives local disambiguation,
114+
not a stable network-wide nickname registry.
115+
116+
## Resolution algorithm (normative)
117+
118+
### 1. Initialize each selected alias row
119+
120+
For each row set `base = trimmed name`, `label = base`, `length = 0`, and no
121+
`qualifier`. Set `mine` only if a viewer exists and either the row key or its
122+
owner key equals the viewer.
123+
124+
Assign a fixed priority (lower wins):
125+
126+
| Priority | Row |
127+
| --- | --- |
128+
| 0 | Non-agent whose key is the viewer |
129+
| 1 | Any other non-agent |
130+
| 2 | Agent that is mine |
131+
| 3 | Any other agent |
132+
133+
Human priority always wins over agent priority. "Mine" for a human means the
134+
viewer itself, not another human with an owner field. An agent without an owner
135+
is not mine merely because the viewer is also absent.
136+
137+
### 2. Find collisions and choose rows that may change
138+
139+
Group **all current labels** by exact equality. A group is a collision only if
140+
it contains more than one distinct key. Several aliases of one key alone do not
141+
collide.
142+
143+
For each collision group, find the minimum priority and the distinct keys at
144+
that priority. If exactly one key has that priority, all rows for that key keep
145+
the label in this round; the other rows may change. Otherwise every row in the
146+
group may change. Do not choose an arbitrary equal-priority winner.
147+
148+
### 3. Try readable qualification first
149+
150+
For each row allowed to change, if it is an agent and has not yet received a key
151+
suffix (`length == 0`):
152+
153+
1. If it is not mine and its owner has a non-empty preferred trimmed name in
154+
the full fact list, propose `<owner>’s <original trimmed name>`.
155+
2. Otherwise, if **any row in this collision group** is a non-agent, propose
156+
`<original trimmed name> (agent)`.
157+
3. Otherwise leave its current base unchanged.
158+
159+
For all other rows, leave the base unchanged. Owner names here are raw preferred
160+
names, not recursively resolved owner labels. The possessive is always U+2019
161+
followed by `s` and one ASCII space, even for a name ending in `s`.
162+
163+
Apply changed readable bases as both `base` and `label`. If at least one row in
164+
this group changed its readable base, add **no key suffix to any row in that
165+
group in this round**. Recheck on the next round instead. This matters: an
166+
unknown-owner agent can remain plain when another agent gains an owner prefix.
167+
168+
### 4. Add or extend key suffixes when readable labels did not change
169+
170+
If step 3 changed no readable base in the group, update every row allowed to
171+
change:
172+
173+
- Set `length` to 4 if zero; otherwise increment it by one.
174+
- Encode the row's public key as its lowercase NIP-19 Bech32 `npub`, including
175+
prefix and checksum. Suffixes use the **end of the complete encoded string**,
176+
not the end of the hex key or checksum-free payload.
177+
- If `length` is at most the npub string length, set `qualifier` to its last
178+
`length` characters.
179+
- Otherwise set `qualifier` to `<full npub> · <length minus npub length>`, with
180+
the counter in ordinary decimal, starting at 1 and without leading zeros.
181+
- Set `label = base + " · " + qualifier` (ASCII spaces, U+00B7 middle dot).
182+
183+
Do not reset a readable base when adding a suffix. Do not extend rows outside
184+
this group or a winning row that is not allowed to change.
185+
186+
### 5. Repeat and return preferred aliases
187+
188+
After processing the collision groups from the start of the round, regroup all
189+
labels and repeat steps 2–4 until no label belongs to two distinct keys. New
190+
labels MUST be checked against literal names, other generated labels, and all
191+
selected aliases. Priority applies again in every round, even to generated
192+
labels. Do not reserve original names unconditionally or suffix all rows once
193+
and assume the result is unique.
194+
195+
The counter after a full npub MUST keep advancing if occupied. Never clamp at
196+
the full npub: literal names can occupy it and several counter labels too.
197+
For finite inputs the suffix sequence can escape those occupied labels.
198+
199+
Return each selected key's row whose original trimmed name equals its preferred
200+
fact's trimmed name. Other aliases participated in the comparison but do not
201+
create extra entries in this key-indexed result.
202+
203+
## Examples
204+
205+
Here the viewer is Logan; Wes is another owner. All agents are named Honey.
206+
`<a4>` and `<b4>` stand for the last four npub characters of distinct agent keys;
207+
these examples assume those suffixes differ and no other labels collide.
208+
209+
| Identities in the context | Labels, in the same order |
210+
| --- | --- |
211+
| One Wes-owned agent | `Honey` |
212+
| Human, Logan's agent, Wes's agent | `Honey`; `Honey (agent)`; `Wes’s Honey` |
213+
| Logan's agent, Wes's agent | `Honey`; `Wes’s Honey` |
214+
| Two Logan-owned agents | `Honey · <a4>`; `Honey · <b4>` |
215+
| Two Wes-owned agents | `Wes’s Honey · <a4>`; `Wes’s Honey · <b4>` |
216+
| Human and two Logan-owned agents | `Honey`; `Honey (agent) · <a4>`; `Honey (agent) · <b4>` |
217+
| Two humans, neither the viewer | `Honey · <a4>`; `Honey · <b4>` |
218+
| Viewer named Honey, another human named Honey | `Honey`; `Honey · <b4>` |
219+
| Unknown-owner agent, Wes's agent | `Honey`; `Wes’s Honey` |
220+
221+
If a human's literal name is `Wes’s Honey`, that human wins a collision with a
222+
generated agent label of the same text. The agent becomes `Wes’s Honey · <b4>`.
223+
If a literal name occupies that result too, the algorithm rechecks and extends
224+
only the rows that lose or tie at that new collision.
225+
226+
## Conformance fixtures
227+
228+
[identity-names.fixtures.json](identity-names.fixtures.json) contains versioned
229+
semantic inputs, not signed events. Each case has `identities`, optional `viewer`
230+
and `candidates`, and an `expected` map. Absent qualifier is encoded as JSON
231+
`null`. Compare map keys and complete values, not map iteration order. Keep input
232+
array order: it selects preferred aliases. Expected results are stored literals;
233+
ports MUST NOT generate their expected results with their own resolver.
234+
235+
Cases cover priority, unknown owners/viewer, owner lookup outside the scope,
236+
empty scope, key normalization, exact Unicode comparison, alias selection,
237+
literal/generated collisions, suffix extension, and occupied full-key counters.
238+
The fixtures test the pure resolver. Adapter selection, fact validation, and
239+
identity-bound actions still need client-specific tests.
240+
241+
Run the fixtures against the desktop policy from the repository root:
242+
243+
```sh
244+
bin/pnpm exec vitest run src/features/identity-names/policy.test.ts
245+
```
246+
247+
## Desktop adapter (informative, not an authority protocol)
248+
249+
At the extraction baseline, [directory.ts](../../features/identity-names/directory.ts)
250+
constructs facts from public profiles, ready agent-library records, ready native
251+
configuration in the current community, and view-local display facts. Native
252+
non-empty names take precedence over library names in that community. The first
253+
library record per key uses its trimmed name, then the profile name, then
254+
`Agent`. Library/native naming records are classified as agents but do not by
255+
themselves invent an owner key. Explicit display facts replace that key's normal
256+
fact and can carry multiple aliases. The requested key is added to an explicit
257+
candidate set.
258+
259+
[profiles.ts](../../features/relay/profiles.ts) selects the latest kind-0 profile,
260+
uses non-blank `display_name` before `name`, and otherwise uses a short hex-key
261+
fallback. Agent hints come from `is_agent: true`, `isAgent: true`, or a
262+
structurally recognized `auth` tag. That fold extracts an owner hint from the
263+
latter; the naming path does **not** verify the owner's attestation signature.
264+
Clients MUST NOT use this display hint as authorization. Missing owner names
265+
simply remove the owner-prefix option; no invented owner or extra naming-only
266+
network fetch is required.
267+
268+
Without an active naming provider, the desktop service falls back to public
269+
profile names and caller fallbacks; that mode does not promise disambiguation.
270+
The policy is replaceable, but a client claiming version-1 conformance must
271+
produce this contract's output for the same inputs. Localized punctuation or a
272+
different case-folding rule is a different policy, not byte-identical conformance.
273+
274+
## Sources and specification precedents
275+
276+
- Algorithm: [policy.ts](../../features/identity-names/policy.ts) and
277+
[policy.test.ts](../../features/identity-names/policy.test.ts).
278+
- Context and fact selection: [directory.ts](../../features/identity-names/directory.ts),
279+
[react.ts](../../features/identity-names/react.ts), and
280+
[mention-choices.ts](../mentions/mention-choices.ts).
281+
- buzz-app feature-contract precedent: [Profiles](../../../docs/profiles.md) and
282+
[Unread](../../../docs/unread.md), especially explicit consumer and authority boundaries.
283+
- block/buzz, inspected at `797012ff01a6d499959b45ed2e56f7927c6a4d6b`:
284+
[NIP-MP](https://github.com/block/buzz/blob/797012ff01a6d499959b45ed2e56f7927c6a4d6b/docs/nips/NIP-MP.md)
285+
supplies the abstract/non-goals/normative-rules pattern;
286+
[fold fixtures](https://github.com/block/buzz/blob/797012ff01a6d499959b45ed2e56f7927c6a4d6b/docs/nips/NIP-MP.fold-fixtures.json)
287+
supply the portable semantic-input pattern;
288+
[agent profile identity](https://github.com/block/buzz/blob/797012ff01a6d499959b45ed2e56f7927c6a4d6b/docs/agent-profile-identity.md)
289+
supplies the exact-key versus persona/control boundary.
290+
291+
This document stays a client contract rather than taking a NIP number because
292+
it introduces no event format or relay behavior. Keep one canonical spec and
293+
fixture set; other client repositories can link here or vendor a pinned version.

0 commit comments

Comments
 (0)