Voice — Share
After the fact and by choice, a visitor shares one of their committed voice notes with the keeper; the phone seals a copy to the keeper's public key, the guide stores what it cannot open, and the audio's hash goes on the chain.
Type URI https://tasks.mages.city/spec/mages/voice/share/0.1 · records · Visitor → Guide
payload.schema.json · invalid examples · spec.md
Today: live POST https://trust.mages.city/api/voice/share. This document form is not accepted anywhere yet; see build with it.
front matter
slug: mages/voice/share
version: "0.1"
title: Voice — Share
summary: After the fact and by choice, a visitor shares one of their committed voice notes with the keeper; the phone seals a copy to the keeper's public key, the guide stores what it cannot open, and the audio's hash goes on the chain.
status: draft
targetFrameworkVersion: "0.6.0"
category: data-exchange
keywords:
- mages-city
- hitchhikers-guide
- voice
- keeper
- sealed-share
authors:
- Mitch (https://github.com/mitchuski)
parties:
- role: Visitor (mark)
requirement: REQUIRED
member: issuer
identifierScope: pairwise
- role: Guide (the Hitchhiker's Guide chain)
requirement: REQUIRED
member: recipient
identifierScope: public
proofRequirement:
request: OPTIONAL
response: OPTIONAL
rationale: >-
Before joining, a visitor has only a mark and no key the guide recognises.
What is sent is bound by its hash on a public chain; after joining, a
member's VTA signs.
issuedAtRequirement:
requirement: REQUIRED
rationale: >-
The task appends to the chain (SPEC §7.3 item 17), and the guide's limits
are counted per night.
sideEffects:
level: mutating
rationale: >-
Stores one keeper-sealed copy of the note, queues it for the keeper, counts it against the mark's nightly cap, and appends one `share` link binding the note and its audio hash.
consequences:
- The keeper can open the shared copy; the guide cannot.
- The audio's hash on the chain lets the keeper check the copy is the note committed.
exposure:
discloses: metadata
ingests: personal
actsAsSubject: false
rationale: >-
Ingests a copy of a person's voice, sealed to the keeper's key so the guide stores it without being able to read it, and the audio's hash. Discloses the appended link.
retention:
class: durable
rationale: >-
The sealed copy is kept for the keeper; the link stays on the chain.
maxDocumentBytes:
request: 1048576
rationale: >-
One sealed copy is at most 480,000 base64 characters plus a wrapped key of at most 1,200; 1 MiB holds it with the envelope.
errorCodes:
- code: mages/voice/share:notYours
meaning: No voice link on this guide carries this note under this mark.
retryable: false
- code: mages/voice/share:alreadyShared
meaning: This note has already been shared with the keeper.
retryable: false
- code: mages/voice/share:markLimit
meaning: This mark has shared 3 notes tonight.
retryable: false
- code: mages/voice/share:slowDown
meaning: The guide is rate-limiting this source; try again in a moment.
retryable: true
- code: mages/voice/share:chainFull
meaning: The guide's chain accepts no more links.
retryable: false
related:
- mages/voice/commit
- mages/contribution/disposeAbstract
A note committed with mages/voice/commit stays the visitor's. Voice — Share gives one to the keeper: the phone opens its own note, seals a fresh copy to the keeper's public key (/keeper.pub.jwk, RSA-OAEP wrapping an AES-GCM key), and sends only that. The guide stores a copy it cannot open, and the chain gets the audio's hash, so the keeper can check that the copy is the note committed.
Status of this Document
This is a draft, private Trust Task specification (SPEC §6.5), published under https://tasks.mages.city/spec/mages/ as part of the mages family. It describes POST /api/voice/share of the Hitchhiker's Guide Worker as of 17 November 2026, which does not yet accept the document form; the payload members are named in the document form's spelling, and the Worker's own names are given beside them. The schema MAY change without notice.
Conformance
RFC2119 and RFC8174 key-word conventions apply.
A conforming consumer (the guide) MUST, after framework and schema validation:
- Refuse unless a
voicelink with thisvoiceexists on its chain under the issuer's mark (notYours). - Refuse a note already shared (
alreadyShared) and a fourth share from this mark tonight (markLimit). - Store
{iv, ct, wrapped, audioHash}for the keeper, append onesharelink whose leaf bindsvoiceandaudioHash, and answer with it.
The keeper, on opening the copy, MUST check sha256(audio) == audioHash and the link's presence before using it.
Definitions
- Mark, intent, leaf — see CONVENTIONS.
Request
{
"id": "urn:uuid:8c9d0e1f-2a3b-4c4d-8e5f-6a7b8c9d0e1f",
"type": "https://tasks.mages.city/spec/mages/voice/share/0.1",
"issuer": "2e1dba5c6e34487e6cbd9de6e673f0f173bdeb94eabe630fcca7aae4428acded",
"recipient": "did:web:trust.mages.city",
"issuedAt": "2026-11-17T21:30:00Z",
"payload": {
"voice": "1c3e5b7d9f0a2c4e6b8d1f3a5c7e9b0d2f4a6c8e1b3d5f7a9c0e2b4d6f8a1c3e",
"audioHash": "3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b",
"iv": "q83vEjRWeJA=",
"ct": "T2dnUwACAAAAAAAAAAA=",
"wrapped": "kX2bQ9mT0vR1sYp8LcA="
}
}
Response
{
"id": "urn:uuid:9d0e1f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a",
"type": "https://tasks.mages.city/spec/mages/voice/share/0.1#response",
"threadId": "urn:uuid:8c9d0e1f-2a3b-4c4d-8e5f-6a7b8c9d0e1f",
"issuer": "did:web:trust.mages.city",
"recipient": "2e1dba5c6e34487e6cbd9de6e673f0f173bdeb94eabe630fcca7aae4428acded",
"issuedAt": "2026-11-17T21:30:01Z",
"payload": {
"seq": 377,
"hash": "4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f"
}
}
Security & Privacy
Data carried
A sealed copy of a voice note, its wrapped key and the audio's hash. The guide cannot open the copy; the keeper's private key never lives on the guide.
Correlation
The share is joined to the visitor's mark and to the note's earlier link. The keeper hears the voice, which can identify the speaker; that is what sharing means. The guide's identifier scope is public because what it records is evidence the visitor may later carry 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 sealed copy is kept for the keeper; the link stays on the chain.
Consent/purpose
Sharing is after the fact, per note, by the visitor's choice, capped at 3 a night. The keeper MUST NOT pass a shared note on without the visitor's separate consent.
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.