toolshed/docs/design-in-progress/items-labels.md

# Item Handles & Physical Labels (Design in Progress)

Status: not implemented. This document collects the problem, goals, and open design questions for
giving inventory items stable identifiers and physical (scannable) labels. Nothing here is
settled.

## Problem

As described in federation.md's "Unique Handles" section, an item today is identified only by a
local id scoped to its owner, it isn't given an explicit, portable handle the way a tag, property,
or category is. That's fine as long as the only thing ever addressing an item is the owning user's
own signed API traffic. It stops being fine the moment something *outside* that loop needs to
refer to the item:

- A friend who borrowed a physical tool has no way to look it up other than finding it in the
  owner's shared inventory list by eye.
  There's nothing you could put on a sticker.
- If items ever need to be referenced from outside their owner's own requests (a group's shared
  view, a lending record, a printed label), there's currently no stable identifier to reference
  that's meaningful outside the owner's own account.
- A local database id isn't something we'd want to expose or rely on externally: it's an
  implementation detail of one backend's storage, not a handle with the same guarantees
  (uniqueness, meaning, longevity) the rest of the federation model gives every other kind of
  entity.

Put simply: every other kind of thing in Toolshed (users, tags, properties, categories) has a
handle that means something outside of one database. Items don't, and physical labeling is the
clearest case where that gap actually matters.

## Goals

- Give an item a handle that's meaningful and resolvable outside its owner's own account, without
  requiring items to become shared/reusable entities the way tags are (an item is still owned by
  exactly one person; see the "Items" subsection of federation.md for why that keeps things
  simple).
- Support a physical label (QR code, barcode, or similar) that can be printed and stuck on a real
  object, such that scanning it gets you to the right item on the right backend.
- Make the label survive the normal life of a physical object: it gets lent out, comes back,
  maybe changes which storage location it lives in, all without needing a new label printed.

## Non-goals (for now)

- Turning items into shareable/reusable entities across owners (that's what tags/categories are
  for; see [tags.md](tags.md)). An item handle identifies *this specific person's specific thing*,
  not a class of thing.
- Solving inventory tracking/auditing (check-in/check-out logs) as a whole system; that can build
  on top of a stable item handle once one exists, but isn't the same problem.

## Open design questions

**What does the handle look like?**
The natural extension of the existing scheme is owner handle + local id, that's enough to be
globally unique (no two users share a handle, and ids are already unique within one user's
inventory) without inventing a new namespace. Worth deciding whether the id should be the existing
internal database id (simple, but leaks a little implementation detail and a rough count of
someone's inventory) or a separate opaque id generated for exactly this purpose (see the
unguessability question below).

Two distinct formats are needed, because "an item handle" is used in two different situations:

- *A compact handle, for use where context already makes clear it's a Toolshed item.* Inside the
  app, in exports, in logs, anywhere the reader already knows they're looking at Toolshed data,
  the handle doesn't need to spell that out or be openable on its own. This can be as short as
  `user@domain.tld:id`, the item's owner handle with `:id` appended, mirroring how a tag/category
  handle already appends `:name` after its origin (see federation.md's Unique Handles section).
  No new delimiter concept, just the same pattern applied to items.

- *A self-contained URL, for use with no context at all.* A physical label, a link shared outside
  the app, has to work without the reader already knowing what it is or which server it belongs
  to, so it needs to open directly to the right frontend, resolve the right backend, and land on
  the right item. That means it has to encode the same information (owner handle + item id) as a
  full URL, e.g. `https://toolshed.webdomain.tld/i/alice@example.com/42`, note the owner's handle
  can be embedded in a path segment as-is (`@` doesn't need escaping in a URL path), which keeps it
  one segment shorter than splitting the handle back into `domain/user`, and means the handle is
  visible unmodified inside the link rather than reassembled from separate parts. If the owner is
  ever a group rather than a user (see groups.md), its handle carries a leading `#`, which does need
  the `+`-for-`#` substitution described in [handles-and-shortids.md](../handles-and-shortids.md)'s
  Handle syntax section before it can sit in a path segment, e.g.
  `https://toolshed.webdomain.tld/i/+climbing@example.com/42`. The frontend host
  in this URL (`toolshed.webdomain.tld`) doesn't have to be, and generally won't be, the backend
  authoritative for `example.com`, any frontend can resolve any handle (see federation.md's Servers
  subsection), so this is just whichever frontend happens to be handling the link, not part of the
  item's identity.

Both formats should stay as short as the encoded information allows, this matters most for the URL
form, since it's the one that ends up in a QR code or printed label where physical size is a real
constraint (see the labels goal above).

**How does this fit with the frontend's existing routes?**
There's already a `/inventory/shared/:user/:id` route (`InventoryDetailForeign`), but today
`:user` is just a bare username with no domain, i.e. it only works for a friend on the viewer's own
domain, and the view itself doesn't yet do anything domain-aware with that param. A resolvable
global handle needs the full `user@domain.tld` and a lookup step this route doesn't have yet. Two
ways to reconcile that: extend the existing route to take a full handle in the `:user` segment
(`/inventory/shared/alice@example.com/42`, no new route shape needed, just a richer meaning for the
param it already has), or treat the short `/i/...` URL as a dedicated, minimal entry point whose
only job is to resolve a handle and then hand off into whatever the richer in-app view ends up
being. The two aren't mutually exclusive: the short form is what needs to be small enough to print,
the in-app route doesn't have the same constraint and can stay more descriptive.

**What does scanning a label actually do?**
Probably: the label encodes a URL or handle-like string; scanning it opens the frontend, which
resolves the owner's domain the same way it resolves any other handle (see federation.md), and
lands on that item. This reuses the discovery mechanism that already exists for logging in as a
handle, rather than inventing a second one.

**Does resolving a label require authorization?**
An item's availability policy already controls who can see it (owner-only if private, friends if
shared, etc.). A label should presumably respect the same policy rather than being a backdoor that
makes a private item visible to literally anyone who finds the physical object and scans its code.
That means resolving a label isn't a free public lookup, it goes through the same friend/signature
checks as everything else, which has UX implications (an anonymous finder of a lost tool can't
necessarily see who it belongs to).

**Does the label need to be opaque/unguessable?**
If item ids are small sequential integers, a label built from a guessable id lets anyone enumerate
a user's items by scanning or guessing nearby numbers, even if each individual lookup is
authorization-checked. Probably wants some amount of unguessability even before authorization is
considered, as a defense-in-depth measure.

**What survives item changes?**
Storage location, availability policy, name, and description can all change over the life of an
object without it becoming a "different" item. The label should point at the handle, not at any of
that mutable data, so none of those changes require a new label. The one thing that probably *does*
need a decision is deletion: does a handle ever get reused, or is it retired for good once an item
is deleted (retiring seems safer, avoids an old label resolving to an unrelated new item later)?

**Relationship to lending/borrowing.**
A scannable label is the obvious hook for a future "mark as borrowed / returned" flow. Not solving
that now, but the handle scheme chosen here should be able to carry that later without a redesign,
i.e. it should be able to identify the item independent of who currently physically has it.