Understanding — Offer

PROPOSED — not yet upstreamed. Built to the ToIP spec.meta.schema.json for the dtgwg-trust-tasks-tf registry; the slug below is proposed to that namespace, not registry-accepted. The PR is pending; the registry's decision governs.

Proposed slug: understanding/offer · version 0.1 · status draft

A joining party consensually offers its address and intent to a host; the host answers with the gateway — the terms document whose comprehension, not any credential, is the key to what follows.

Abstract

The Understanding — Offer Trust Task opens the proof-of-understanding
ceremony: a joining party offers its address and intent to a host —
consent-first; the host never scans for it. The host's #response is the
gateway: a reference to the terms document governing the room, pinned by
digest. Reading the gateway is where the handshake actually happens; the family
rule — access is earned by understanding, not credential — starts here.

The ceremony is the consent-first peer counterpart of the supervised
agent-admission/* family: no
supervisor, two parties meeting as equals, and the outcome is a sealed
bilateral agreement (understanding/seal) followed
by a brokered grant (understanding/grant), not a
deployment credential.

Status of this Document

This is a draft Trust Task specification per SPEC.md §5.3; the schema MAY change without notice. Feedback via the issue tracker.

Conformance

RFC2119(https://www.rfc-editor.org/rfc/rfc2119) and RFC8174(https://www.rfc-editor.org/rfc/rfc8174) key-word conventions apply.

A conforming producer (the joining party) MUST emit a Trust Task document whose type is https://trusttasks.org/spec/understanding/offer/0.1, offering an address it controls. Offering is consent: a host MUST NOT open a pending join for an address that was discovered rather than offered.

A conforming consumer (the host) MUST:

Probe the offered address deterministically before recording the join, and refuse intermittent resolution with nameResolvesSometimes — a sometimes-resolving name poisons every later step of the ceremony with ambiguity.
Answer with a gateway reference pinned by digest, so the joiner and host can later agree on exactly which terms were read (understanding/exchange echoes the digest).
Serve the gateway such that near-misses degrade soft — a wrong path lands on the gateway, never a hard failure. The front door of a trust ceremony must not 502.

Payload

payload.endpoint (REQUIRED) — the offered address (URI) the joiner answers at.
payload.intent (REQUIRED) — one line of free text: what the joiner wants of the room.
payload.ext — extension slot per SPEC.md §4.5.1.

Request

{
  "id": "urn:uuid:d39ce7fc-061a-4fc8-ea3b-243546576879",
  "type": "https://trusttasks.org/spec/understanding/offer/0.1",
  "issuer": "did:key:z6MkJoiningPartyExample",
  "recipient": "did:key:z6MkHostExample",
  "issuedAt": "2026-07-18T16:00:00Z",
  "payload": {
    "endpoint": "https://192.168.55.144:8443/join",
    "intent": "Join the shared workshop model as a contributing member."
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-07-18T16:00:00Z",
    "verificationMethod": "did:key:z6MkJoiningPartyExample#z6MkJoiningPartyExample",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3FXQmV6ExampleProofValueForUnderstandingOffer"
  }
}

Response

{
  "id": "urn:uuid:e4adf80d-172b-4ad9-fb4c-354657687980",
  "type": "https://trusttasks.org/spec/understanding/offer/0.1#response",
  "issuer": "did:key:z6MkHostExample",
  "recipient": "did:key:z6MkJoiningPartyExample",
  "threadId": "urn:uuid:d39ce7fc-061a-4fc8-ea3b-243546576879",
  "issuedAt": "2026-07-18T16:00:02Z",
  "payload": {
    "gateway": {
      "uri": "https://host.example.com/gateway",
      "digest": "5b6c7d8e9f202132435b6c7d8e9f202132435b6c7d8e9f202132435b6c7d8e9f"
    },
    "exchangeBy": "2026-07-18T17:00:00Z"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-07-18T16:00:02Z",
    "verificationMethod": "did:key:z6MkHostExample#z6MkHostExample",
    "proofPurpose": "assertionMethod",
    "proofValue": "z58aKqExampleProofValueForUnderstandingOfferResponse"
  }
}

Security & Privacy

The offer discloses the joiner's address and intent to the host — exactly the
disclosure the joiner consented to by offering; the host MUST NOT probe beyond
the offered address. A pending join is enumeration surface: hosts SHOULD
rate-limit offers and expire unanswered ones. The gateway digest is
load-bearing for the whole ceremony — a host that rotates its terms mid-join
must expect gatewayStale at exchange and reissue, never silently re-pin.

Assets

Source: specs/understanding/offer/0.1/ — spec.md + payload.schema.json

📎 understanding-offerpayload.schema.json spec.md

upstream: ~/dtgwg-trust-tasks-tf-mage (untracked contribution lane; upstream registry: trustoverip/dtgwg-trust-tasks-tf) · author: Mitchell Travers · the git source wins on any disagreement · (⚔️⊥⿻⊥🧙)😊

← The Trust Tasks · Welcome Visitors