stash

docs/glossary.md

@@ -0,0 +1,229 @@
+# Glossary
+
+This page collects one unambiguous name for each concept discussed in [federation.md](federation.md)
+and the [design-in-progress](design-in-progress/) documents, so later writing can refer to them
+consistently instead of reinventing or subtly renaming them. Entries are grouped by topic, and
+alphabetical within each group. Each one notes whether the concept exists in Toolshed today or is
+still a design proposal, and links back to where it's discussed in full.
+
+Two terms are easy to conflate and worth telling apart up front: a **domain** is who a handle
+belongs to; an **origin** is where a classification entry came from. They look similar in prose but
+are unrelated concepts, see their entries below.
+
+---
+
+## Federation Basics
+
+**Backend** (Implemented)
+The server software that stores an [actor](#actor)'s data and is currently authoritative for a
+[domain](#domain). Deliberately decoupled from both the domain (a backend isn't tied to one domain,
+and can be authoritative for many at once) and the [frontend](#frontend) (the app a user loads isn't
+necessarily served by the backend that ends up handling their requests). Prefer "backend" over the
+looser word "server" when precision matters, "server" is used informally in places to mean either
+backend or domain interchangeably.
+*See: [federation.md](federation.md#servers)*
+
+**Discovery** (Implemented)
+The lookup a [frontend](#frontend) performs to find which [backend](#backend) is currently
+authoritative for a [domain](#domain), given a [handle](#handle). Operational/DNS-level detail
+about how this lookup works belongs in the deployment docs, not here, this glossary only fixes the
+name for the concept.
+*See: [federation.md](federation.md#servers)*
+
+**Domain** (Implemented)
+The half of a [handle](#handle) after the `@`, e.g. `toolsheddomain.tld`. An authority record, not
+a location or a piece of software: it says which [backend](#backend) currently vouches for handles
+under it, nothing more. Not the same thing as an [origin](#origin), see the note at the top of this
+page.
+*See: [federation.md](federation.md#servers)*
+
+**Frontend** (Implemented)
+The client application a user interacts with. Independent of any one [domain](#domain) or
+[backend](#backend): given a handle, it performs [discovery](#discovery) to find the right backend
+and talks to it directly, regardless of where the frontend itself was loaded from.
+*See: [federation.md](federation.md#servers)*
+
+**Handle** (Implemented)
+A name that's unique within its own scope and carries, as part of itself, enough information to say
+where it's authoritative, without needing a central registry to look it up. The general term
+covering [user handles](#user-handle), [group handles](#group-handle) (proposed),
+[classification handles](#classification-handle), and [item handles](#item-handle) (proposed).
+*See: [federation.md](federation.md#unique-handles)*
+
+**Strict resolution** (Implemented)
+The rule that a reference to a [handle](#handle) a backend doesn't recognize is left unresolved
+rather than guessed at or silently merged into something that looks similar. The foundational
+guarantee the rest of the handle system, and most of the open problems in
+[tags.md](design-in-progress/tags.md), are trying to preserve or actually make hold.
+*See: [federation.md](federation.md#tags-properties-and-categories)*
+
+## Actors, Identity & Sharing
+
+**Actor** (Proposed)
+Umbrella term for anything that can hold a handle, have friends, and own items. Today this only
+means [user](#user). [Groups](#group) are a proposed second kind of actor, so that "friendship,"
+"ownership," and "handle" all mean the same thing regardless of which kind of actor is involved.
+*See: [groups.md](design-in-progress/groups.md#are-group-handles-different-from-user-handles-or-is-a-group-just-a-special-kind-of-user)*
+
+**Availability policy** (Implemented)
+A setting on an item (`private` / `share` / `lend` / `rent` / `sell`) controlling who besides the
+owner can see it. Today the audience for any non-`private` policy is implicitly "all of the owner's
+[friends](#friend-friendship)," equally, there's no way to name a narrower audience. See [targeted
+sharing](#targeted-sharing) for the proposed alternative.
+*See: [groups.md](design-in-progress/groups.md#interaction-with-availability-policy)*
+
+**Friend / Friendship** (Implemented for users; proposed for groups)
+A mutual, explicitly-established trust relationship between two [actors](#actor). Established by a
+friend-request/accept exchange, which is also the point a [public key](#keypair-private-key-public-key)
+is first trusted for that handle. Currently only exists between users; groups having friends, and
+groups befriending groups, are proposed extensions of the same mechanism, not a new one.
+*See: [federation.md](federation.md#cryptography), [groups.md](design-in-progress/groups.md#should-a-group-be-able-to-grant-read-access-to-non-members-group-friends)*
+
+**Group** (Proposed)
+A second kind of [actor](#actor), modeling collective ownership (a club, workshop, or company)
+rather than any one person owning something. All members hold equal edit rights over what the group
+owns; membership itself is the privilege, there's no separate owner/member distinction within a
+group. Backed by a [membership list](#membership-list) rather than a [keypair](#keypair-private-key-public-key),
+and identified by a [group handle](#group-handle).
+*See: [groups.md](design-in-progress/groups.md#what-a-group-is)*
+
+**Group handle** (Proposed)
+A [group](#group)'s handle: a name and [domain](#domain) written like a [user handle](#user-handle)
+but prefixed with `#`, e.g. `#groupname@toolsheddomain.tld`. The prefix keeps groups and users in
+disjoint namespaces on the same domain (no squatting collision between a user and a group wanting
+the same name) and lets an actor's kind be read directly off its handle, without a lookup.
+*See: [federation.md](federation.md#users-and-groups), [groups.md](design-in-progress/groups.md#are-group-handles-different-from-user-handles-or-is-a-group-just-a-special-kind-of-user)*
+
+**Identity** (Implemented)
+A [user handle](#user-handle) paired with the [keypair](#keypair-private-key-public-key) that backs
+it, held together as the one unit a [backend](#backend) actually trusts: not just a name, and not
+just key material, but both at once. This is what gets established at registration for one's own
+handle, and what gets recorded on [friend](#friend-friendship)-accept for someone else's handle.
+Only [users](#user) have an identity in this sense, since a [group](#group) is deliberately backed
+by a [membership list](#membership-list) instead of a keypair, there's no key half for a group
+handle to pair with.
+*See: [federation.md](federation.md#cryptography)*
+
+**Keypair / Private key / Public key** (Implemented, users only)
+The asymmetric keypair backing exactly one [user handle](#user-handle); together, a handle and the
+keypair backing it are what's called an [identity](#identity). The private key signs requests made
+as that user and never leaves their control; the public key is handed out to establish trust in the
+handle (at registration, or via a [friend](#friend-friendship) exchange) and is used to verify
+signatures. Only user handles carry a keypair, not groups, classification handles, or item handles.
+*See: [federation.md](federation.md#cryptography)*
+
+**Membership list** (Proposed)
+The record of which [user handles](#user-handle) currently belong to a [group](#group), maintained
+by whichever backend is authoritative for the group's handle. What backs a group's identity in
+place of a keypair: a request "as the group" is a normal signed request from a current member, plus
+a check against this list, not a request signed by some shared group key.
+*See: [groups.md](design-in-progress/groups.md#does-a-group-need-its-own-keypair)*
+
+**Signature / Signing** (Implemented)
+The act of authenticating a request as genuinely coming from a specific [user
+handle](#user-handle), unaltered, using that handle's private key. Establishes authenticity and
+integrity only, not confidentiality (that's HTTPS's job) and not, today, protection against replay.
+*See: [federation.md](federation.md#cryptography)*
+
+**Targeted sharing** (Proposed)
+Sharing an item with one specific [actor](#actor) (a particular friend, or a particular group)
+instead of the current all-or-nothing [availability policy](#availability-policy) audience of every
+friend equally. Flagged as a generalization useful beyond groups specifically, not a groups-only
+feature.
+*See: [groups.md](design-in-progress/groups.md#should-anyone-be-able-to-share-directly-with-a-specific-group-instead-of-with-my-friends-generally)*
+
+**User** (Implemented)
+The original, and currently only implemented, kind of [actor](#actor): backed by exactly one
+[keypair](#keypair-private-key-public-key) and identified by a [user handle](#user-handle).
+*See: [federation.md](federation.md#users-and-groups)*
+
+**User handle** (Implemented)
+A user's username paired with its [domain](#domain), written like an email address, e.g.
+`user@toolsheddomain.tld`. Unique only within its domain, not across all of Toolshed. Contrast with
+a [group handle](#group-handle), which is the same shape but prefixed with `#`. Paired with its
+[keypair](#keypair-private-key-public-key), the two together are called an [identity](#identity).
+*See: [federation.md](federation.md#users-and-groups)*
+
+## Classification: Tags, Properties & Categories
+
+**Alias** (Proposed)
+An explicit, one-directional "supersedes"/"alias of" pointer from one [classification
+handle](#classification-handle) to another, asserting they mean the same thing. Never inferred
+automatically, always a deliberate act, in keeping with [strict resolution](#strict-resolution). For
+a property alias specifically, also states a unit conversion (even if it's "identical unit, factor
+1"); without one, the values behind the two handles aren't assumed to be comparable.
+*See: [tags.md](design-in-progress/tags.md#open-design-ideas)*
+
+**Classification handle** (Implemented)
+Umbrella term for a [tag](#tag-property-category), [property](#tag-property-category), or
+[category](#tag-property-category) handle, of the form `origin#type:name`, e.g.
+`git:base#property:length`. Distinct from a [user handle](#user-handle) or [item
+handle](#item-handle): it names a reusable classification concept, not an actor or an owned thing.
+*See: [federation.md](federation.md#tags-properties-and-categories)*
+
+**Definition fingerprint** (Partially implemented)
+A hash of a classification entry's full definition, used to tell whether two [actors](#actor)
+that both use the same handle actually mean the same thing. A sha256 of each `shared_data/*.json`
+file is already computed and stored per import (`ImportedIdentifierSets.hash`), but it's only ever
+recorded, not compared, so it doesn't yet catch a [handle collision](#handle-collision) in
+practice.
+*See: [tags.md](design-in-progress/tags.md#open-design-ideas)*
+
+**Fragmentation** (Known problem)
+Two different [classification handles](#classification-handle) that mean, or were intended to
+mean, the same real-world concept (different origins, or a locally-invented tag versus a shared
+one). The opposite failure from a [handle collision](#handle-collision): visible and merely
+wasteful, rather than silent and dangerous.
+*See: [tags.md](design-in-progress/tags.md#problem)*
+
+**Handle collision** (Known problem)
+Two [actors](#actor) independently ending up with the exact same [classification
+handle](#classification-handle) string backing two different definitions, e.g. two servers that
+each imported `git:ee2` from what has since become diverging branches. The dangerous mirror image
+of [fragmentation](#fragmentation): silent, because nothing about the interaction signals that
+anything's wrong, both sides just say the same string.
+*See: [tags.md](design-in-progress/tags.md#worked-example-the-same-handle-meaning-two-different-things)*
+
+**Origin** (Implemented)
+The first component of a [classification handle](#classification-handle), naming where that tag,
+property, or category came from, e.g. `git:base` in `git:base#property:length`. Not necessarily a
+server or a domain, it can equally be a shared reference dataset (like the files in
+`backend/shared_data/`) or a server's own locally-invented taxonomy. Not the same thing as a
+[domain](#domain), see the note at the top of this page.
+*See: [federation.md](federation.md#tags-properties-and-categories)*
+
+**Tag / Property / Category** (Implemented)
+The three kinds of classification entity an item can reference, each identified by a
+[classification handle](#classification-handle). A property additionally carries unit metadata
+(`unit_symbol`/`unit_name`), though property *values* on an item are plain, undeclared-type
+strings today.
+*See: [federation.md](federation.md#tags-properties-and-categories), [tags.md](design-in-progress/tags.md)*
+
+## Items & Physical Labels
+
+**Item Handle** (Proposed)
+The compact identifier for a specific item that's meaningful outside its owner's own account:
+`user@domain.tld:id`, the owner's [user handle](#user-handle) plus a [local id](#local-id). Used
+where it's already clear from context that it's a Toolshed item, e.g. inside the app, in exports,
+in logs, so it doesn't need to spell that out or be openable on its own. Contrast with [Item
+URL](#item-url), the self-contained form for when no such context can be assumed.
+*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
+
+**Item Label** (Proposed)
+A physical, scannable encoding (QR code, barcode, or similar) of an item's [Item URL](#item-url),
+meant to be printed and stuck on the physical object it refers to.
+*See: [items-labels.md](design-in-progress/items-labels.md#goals)*
+
+**Item URL** (Proposed)
+The self-contained URL form of an [Item Handle](#item-handle), for use with no context at all, e.g.
+an [Item Label](#item-label): `https://<any frontend>/i/user@domain.tld/id`. Has to open directly
+to the right frontend and land on the right item on its own, since the reader can't be assumed to
+already know what it is or which server it belongs to. Any frontend can serve this URL, the host
+named in it isn't part of the item's identity, only the handle in its path is.
+*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
+
+**Local id** (Implemented)
+An item's identifier as it exists today: unique only within its owner's own inventory, not
+meaningful outside that owner's account. The starting point both the [Item
+Handle](#item-handle) and [Item URL](#item-url) build on.
+*See: [federation.md](federation.md#items), [items-labels.md](design-in-progress/items-labels.md#problem)*