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/sessionAbstract
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:
- Check
witnessagainst the room's code for the current and previous window; when it checks, append awitnesslink with the night's place, otherwise athumblink, and reportwitnessedand, when a code was given but did not check,expired. - Store
claimDigest, where given, on the link and nowhere else. - Answer with the link, or refuse with
chainFull.
Definitions
- Mark, intent — see CONVENTIONS.
- Witness code — the first 10 hex characters of
sha256("witness|" + key + "|" + night + "|" + window), shown on the room's screen and valid for its window and the one before. - Claim code — a bearer secret the phone mints, in the shape of
ClaimSecretfromvtc/badges(_shared/0.1/badge.schema.json): at least 128 random bits, base64url, 22 to 64 characters. The phone shows it once, as a link (https://trust.mages.city/claim#<code>) and a QR, and keeps it;claimDigestis the lowercase hex sha256 of the code's ASCII bytes.
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.