Presence — Thumb

A visitor sends a thumbs up, "I was here", to a guide that keeps a chain; the guide appends a link under the visitor's mark (a witness link when the room's code is given) and holds the digest of the visitor's claim code for later.

Type URI https://tasks.mages.city/spec/mages/presence/thumb/0.1 · records · Visitor → Guide
payload.schema.json · invalid examples · spec.md

Today: live POST https://trust.mages.city/api/thumb · the claim code is still four words there. This document form is not accepted anywhere yet; see build with it.

front matter
slug: mages/presence/thumb
version: "0.1"
title: Presence — Thumb
summary: A visitor sends a thumbs up, "I was here", to a guide that keeps a chain; the guide appends a link under the visitor's mark (a witness link when the room's code is given) and holds the digest of the visitor's claim code for later.
status: draft
targetFrameworkVersion: "0.6.0"
category: provenance
keywords:
  - mages-city
  - hitchhikers-guide
  - thumbs-up
  - presence
  - witness
  - hash-chain
authors:
  - Mitch (https://github.com/mitchuski)
parties:
  - role: Visitor (mark)
    requirement: REQUIRED
    member: issuer
    identifierScope: pairwise
  - role: Guide (a chain-keeping guide, such as the Hitchhiker's Guide)
    requirement: REQUIRED
    member: recipient
    identifierScope: public
proofRequirement:
  request: OPTIONAL
  response: OPTIONAL
  rationale: >-
    Before joining, the visitor has only a mark and no key the guide recognises.
    What binds the visitor to the thumb is the claim code their phone minted and
    kept: the guide holds only its digest, so only that phone can later redeem
    it. The link is on a public chain anyone can re-derive. After joining, a
    member's VTA signs.
issuedAtRequirement:
  requirement: REQUIRED
  rationale: >-
    A thumb appends to the chain (SPEC §7.3 item 17), and a witness code is
    valid only in its time window, so the guide must place the thumb in time.
sideEffects:
  level: mutating
  rationale: >-
    Appends one `thumb` link, or a `witness` link when the room's code checks,
    to the guide's chain under the visitor's mark, and stores the claim-code
    digest on it. Append-only.
consequences:
  - One link naming the mark is appended to the guide's chain and folded into the night's root.
  - Where a claim-code digest is given, it is held on the link so the code can later be redeemed for the night's badge (docs/PROFILE_GUIDE_NIGHT_BADGE.md).
exposure:
  discloses: metadata
  ingests: metadata
  actsAsSubject: false
  rationale: >-
    Ingests the mark, an optional digest and an optional witness code: hashes
    and a short window code, no personal data. Discloses the appended link.
retention:
  class: durable
  rationale: >-
    The link is the night's record that this mark was there; it stays on the
    chain, and the claim digest stays with it until redeemed or never.
errorCodes:
  - code: mages/presence/thumb:chainFull
    meaning: The guide's chain accepts no more links tonight.
    retryable: false
related:
  - mages/meet/confirm
  - mages/constellation/commit
  - vtc/badges/claims/redeem
  - witness/session

Abstract

On a guide night, the first thing a visitor does is press 👍. Presence — Thumb sends it: the guide appends a link under the visitor's mark, and, if the visitor scanned the room's screen, a witness link that names the place. The phone also mints a claim code, shows it once, and sends only its digest; after joining Mages City, the member redeems the code for the night's badge.

A thumb that is never sent (agentprivacy.ai holds its thumbs in the browser) is not this task. It is the intent thumb (CONVENTIONS), whose leaf may later ride mages/constellation/commit.

Status of this Document

This is a draft, private Trust Task specification (SPEC §6.5), published under the Mages City namespace (https://tasks.mages.city/spec/mages/) as part of the mages family. It describes POST /api/thumb of the Hitchhiker's Guide Worker as of 17 November 2026, which does not yet accept the document form. Its claim code is four words today; this specification replaces them with a ClaimSecret of the upstream badge tasks (G1 of the guide-night badge profile). The schema MAY change without notice.

Conformance

RFC2119 and RFC8174 key-word conventions apply.

A conforming producer (the visitor's phone) MUST emit a Trust Task document whose type is https://tasks.mages.city/spec/mages/presence/thumb/0.1, with issuer set to the mark. Where it mints a claim code, it MUST draw at least 128 bits from a cryptographic random source, encode them base64url without padding, keep the code on the device, show it to the visitor once, and send only claimDigest.

A conforming consumer (the guide) MUST, after framework and schema validation:

  1. Check witness against the room's code for the current and previous window; when it checks, append a witness link with the night's place, otherwise a thumb link, and report witnessed and, when a code was given but did not check, expired.
  2. Store claimDigest, where given, on the link and nowhere else.
  3. Answer with the link, or refuse with chainFull.

Definitions

Request

{
  "id": "urn:uuid:3b6f2a1e-8c4d-4f7a-9e21-5d0c7b8a9f13",
  "type": "https://tasks.mages.city/spec/mages/presence/thumb/0.1",
  "issuer": "2e1dba5c6e34487e6cbd9de6e673f0f173bdeb94eabe630fcca7aae4428acded",
  "recipient": "did:web:trust.mages.city",
  "issuedAt": "2026-11-17T19:05:00Z",
  "payload": {
    "claimDigest": "5f0c2a7e9b1d3f6a8c0e2b4d6f8a1c3e5b7d9f0a2c4e6b8d1f3a5c7e9b0d2f4a",
    "witness": "a41c9e0b2f"
  }
}

Response

{
  "id": "urn:uuid:6d5c4b3a-2918-4f07-8e6d-5c4b3a291807",
  "type": "https://tasks.mages.city/spec/mages/presence/thumb/0.1#response",
  "threadId": "urn:uuid:3b6f2a1e-8c4d-4f7a-9e21-5d0c7b8a9f13",
  "issuer": "did:web:trust.mages.city",
  "recipient": "2e1dba5c6e34487e6cbd9de6e673f0f173bdeb94eabe630fcca7aae4428acded",
  "issuedAt": "2026-11-17T19:05:01Z",
  "payload": {
    "seq": 291,
    "hash": "7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b",
    "kind": "witness",
    "witnessed": true
  }
}

Security & Privacy

Data carried

A mark, a digest and a window code in; a link out. The claim code itself never leaves the phone. A producer MUST NOT add a note, referrer or anything else: a thumb is a presence, not a message.

Correlation

The mark is pairwise to the guide and stable on the device, so every link a visitor makes under it is joinable; a fresh start is a new device secret. The claim digest adds no correlation until redemption, which links the mark to a member on purpose (see the badge profile). The guide's identifier scope is public because the link is evidence the visitor later carries to a community, which must see which guide recorded it; a pairwise guide identifier would hide that and protect no one, the guide being a public party.

Retention

durable. The link stays on the chain.

Consent/purpose

The visitor presses 👍 to say they were here, for their own record and for the community they may join. It is not analytics; the guide MUST NOT use marks to follow visitors across nights beyond what the chain itself shows.

Drafts, version 0.1, private Trust Task specifications (SPEC §6.5) published by the City under its own domain. Every specification here passes the Trust Tasks task force's own validator against its registry at 0cdf9e517 (17 Nov 2026). Formal models of the family and of the public registry: trust-tasks-formal. Nothing here is on the wire yet: the City's sites still speak their own shapes, and move to these one at a time. Text: CC BY 4.0; schemas and tools: Apache-2.0.