# 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)*