|
| 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