---
slug: vtc/join-requests/submit
version: "0.2"
title: VTC Join-Requests — Submit
summary: An applicant submits a request to join a Verifiable Trust Community, presenting the credentials the community's join policy requires.
status: draft
targetFrameworkVersion: "0.5.0"
category: governance
keywords:
  - vtc
  - join-requests
  - onboarding
  - submit
authors:
  - Glenn Gore (https://github.com/stormer78)
parties:
  - role: applicant
    requirement: REQUIRED
    member: issuer
    identifierScope: pairwise
  - role: community maintainer
    requirement: REQUIRED
    member: recipient
    identifierScope: public
proofRequirement:
  requirement: REQUIRED
  rationale: The document proof authenticates the applicant — its signer DID is the applicant DID. This replaces the transport-specific signature the pre-migration REST shape carried, and matches what DIDComm authcrypt provides intrinsically.
issuedAtRequirement:
  requirement: REQUIRED
  rationale: The applicant submits under their own authority, so a captured submission keeps re-presenting them to the community after they have stopped asking. Placing the document in a window is what lets the community stop treating it as a live request.
sideEffects:
  level: mutating
  rationale: "Creates a pending join request."
exposure:
  discloses: none
  ingests: personal
  actsAsSubject: true
  rationale: "The applicant submits on their own behalf — the subject is the proof signer, so the applicant acts as themselves; there is no separate subject field. Nothing is disclosed back to the applicant, but the request carries `vp` into the community: a Verifiable Presentation of credentials about an identifiable party, whose claim set is whatever that community's join policy demands, plus an opaque applicant-supplied `extensions` bag the community stores verbatim, plus `attributes` — self-asserted values about the applicant, such as a display name, answering the manifest's `requestedAttributes`."
retention:
  class: durable
  rationale: The community keeps the submitted presentation as the evidence its admission decision rested on — a decision it may have to account for to its members or to a regulator long after the fact, and which is unreconstructable if the presentation is discarded. That evidentiary value is exactly why a refused applicant does not get their claims back; see Security & Privacy → Retention, which states what this costs them.
errorCodes:
  - code: vtc/join-requests/submit:policyUnsatisfied
    meaning: The presentation did not satisfy the community's active join policy.
    retryable: false
  - code: vtc/join-requests/submit:presentationInvalid
    meaning: The Verifiable Presentation failed verification, or its holder did not match the proof signer.
    retryable: false
  - code: vtc/join-requests/submit:attributesMissing
    meaning: The manifest's `requestedAttributes` marks an attribute required and `attributes` does not answer it. The details name the missing types so the applicant can supply them and resubmit.
    retryable: false
    detailsSchema:
      type: object
      additionalProperties: false
      required: ["types"]
      properties:
        types:
          type: array
          maxItems: 32
          items:
            type: string
  - code: vtc/join-requests/submit:attributesUnrequested
    meaning: An entry in `attributes` names a type the manifest does not request. Refused rather than stored, so a client that over-shares cannot leave an applicant's data with a community that never asked for it. The details name the types.
    retryable: false
    detailsSchema:
      type: object
      additionalProperties: false
      required: ["types"]
      properties:
        types:
          type: array
          maxItems: 32
          items:
            type: string
  - code: vtc/join-requests/submit:challengeNotIssued
    meaning: "The submission's hidden-vetting proof is bound to a challenge, but the community holds no challenge for the applicant's DID — none was requested, or it expired and has since been discarded. The applicant requests a new challenge over `vtc/vetting/pcs-challenge`, builds the proof over it, and sends again."
    retryable: false
  - code: vtc/join-requests/submit:challengeAlreadyUsed
    meaning: "The challenge the proof is bound to was spent by an earlier submission or supplement. Challenges are single-use. The applicant requests a new one, rebuilds the proof, and sends again."
    retryable: false
  - code: vtc/join-requests/submit:challengeExpired
    meaning: "The challenge the proof is bound to is past its `expiresAt`. The details MAY carry `expiredAt`. The applicant requests a new one, rebuilds the proof, and sends again."
    retryable: false
    detailsSchema:
      type: object
      properties:
        expiredAt:
          type: string
          format: date-time
  - code: vtc/join-requests/submit:challengeMismatch
    meaning: "The proof is bound to a challenge other than the one the community holds open for this applicant — typically one it replaced when the applicant asked again. This attempt spends the open challenge. The applicant requests a new one, rebuilds the proof, and sends again."
    retryable: false
---

## Abstract

The **VTC Join-Requests — Submit** Trust Task opens an application to join a community. The applicant presents a W3C Verifiable Presentation (`vp`) whose credentials satisfy the community's join policy, and optionally consents to trust-registry publication. On acceptance the community records a **pending** request and returns its `requestId`, which the applicant polls with [`vtc/join-requests/status`](../../status/0.1/).

### Changes from 0.1

`0.1` returned `status`, a `const: "pending"`. A submission has four outcomes, not one: the policy may admit outright, refuse outright, park the request for a human or quorum decision, or ask the applicant for more evidence. A constant can express one of them, so the other three had to be reported as `pending` or not reported at all — and an applicant told "pending" cannot tell whether to wait or to act.

`0.2` returns a `verdict` — `effect` plus its effect-dependent detail — from the new shared `vtc/_shared/0.1/ceremony` component. `pending` maps onto `refer`, which is the outcome it actually described: parked, waiting on the community.

The distinction that matters most is between `refer` and `requestMore`. Both mean "not decided", and they place the next action with different parties: `refer` waits on the community, `requestMore` waits on the applicant and names what it needs. Collapsing them is what makes a join flow feel like a black box.

The applicant identity is the **document proof's signer** — there is no `applicantDid` or `signature` field. This is the transport-agnostic form: over DIDComm the authcrypt sender is the signer, over REST/TSP the framework proof is, and the payload is identical on every transport.

## Conformance

Producer: supply `vp` (its holder MUST equal the proof signer); optionally `registryConsent` and `extensions`. Carry a proof.

Consumer: verify the proof and the presentation; if the VP fails verification or the holder mismatches the signer, return `presentationInvalid`; if it does not satisfy the active join policy, return `policyUnsatisfied`. Otherwise evaluate the join policy and return `{ requestId, verdict }`, where the verdict carries what the policy decided and the detail that decision implies.

**Requested attributes.** Producer: answer the manifest's `requestedAttributes` in `attributes`, one entry per attribute given, and nothing it does not ask for. The values are self-asserted; the proof binds them to the applicant and attests nothing further.

Consumer: refuse with `attributesMissing`, naming the types, when a required requested attribute is not answered, and with `attributesUnrequested`, naming the types, when an entry names a type the manifest does not request. **MUST** store the answers with the request and show them to its reviewers as the applicant's own statement — never as verified — and **MUST NOT** let a join policy treat one as attested evidence. Their retention is the request's: they are deleted with it.

### Hidden-vetting challenge

A hidden-vetting proof travels as the `hiddenVetting` member of `extensions`, and is bound to the single-use challenge the community issued the applicant over [`vtc/vetting/pcs-challenge`](../../../vetting/pcs-challenge/0.1/spec.md). When a consumer counts that proof it spends the applicant's open challenge — whether or not the applicant is then admitted, and including on a mismatch — and refuses the submission, changing nothing else, with the code that says why:

- `challengeNotIssued` — it holds no challenge for the applicant's DID: none was requested, or it expired and was swept;
- `challengeAlreadyUsed` — the challenge was spent by an earlier submission or supplement;
- `challengeExpired` — the challenge is past its `expiresAt`; `details` **MAY** carry `expiredAt`;
- `challengeMismatch` — the proof is bound to a value other than the open challenge.

A consumer **MUST NOT** answer any of these with `malformedRequest`, and its `message` **MUST NOT** echo the challenge value. It **MUST** discard the challenge value when it spends it. It **MAY** keep a value-free spent marker — the challenge's expiry and when it was spent, never the value — until that expiry, so that a repeated attempt is answered `challengeAlreadyUsed` rather than `challengeNotIssued`; the marker is swept as an expired challenge is.

None of the four is retryable: the same document cannot succeed. The remedy is the same for all of them — request a new challenge, build a new proof over it, and send again, which is a new document — but they say different things. `challengeExpired` and `challengeNotIssued` are usually time: the applicant was slow, or the client asked too early. `challengeAlreadyUsed` is a resubmission or a race. `challengeMismatch` is usually a client defect, such as reusing a challenge after asking for another, and a client **SHOULD** report it as its own fault rather than the applicant's.

## Authorization

*Stated in anticipation of [SPEC §7.3](/SPEC.md#73-specification-requirements) item 15, which binds specifications targeting framework 0.4; this one targets 0.2, where the declaration is not yet required.*

The authorization evidence this task presupposes is the **presentation in `vp`, whose holder MUST equal the envelope proof's signer**. That equality is the whole authorization: it establishes that the party asking to join is the party the presented credentials describe.

`exposure.actsAsSubject` is `true` because the request is made in the subject's own name. A consumer that accepted a presentation whose holder differed from the signer would be admitting one party on another's evidence, which is why the check is stated as an equality rather than as two independent verifications.

The authorization decision is the *consumer*'s alone. This section describes the evidence the task assumes, not an obligation to authorize any particular party, and per [SPEC §7.2](/SPEC.md#72-consumer-requirements) item 10 verifying the `proof` establishes who asked, never that they may.

## Security & Privacy

### Data carried

`vp` is the payload, and it is the most personal member in this family. Its
schema calls it opaque because the *community's* join policy, not this
specification, decides what must be in it — so the sensitivity of a conforming
submission ranges from "proves control of a domain" to "proves a date of birth
off a government credential", and the wire form is identical in both cases. A
consumer cannot tell which it has been sent by looking at the type URI.

The applicant DID is deliberately **not** a payload member: it is the document
proof's signer. Collapsing the pre-migration REST `applicantDid` plus hex
`signature` into the framework proof removed a hand-rolled auth scheme in favour
of the one every conforming consumer already verifies, and it also removed a
field an applicant might have been tempted to populate with something other than
themselves. The VP is the *credential* evidence; the proof is *who submitted it*.

`registryConsent` is one boolean, and it is the member that governs the fate of
all the others — whether the applicant agreed to trust-registry publication.
`extensions` is an opaque applicant-supplied bag with no schema, stored verbatim
on the request row.

Minimisation is the applicant's, and it happens before the document is built: a
presentation is a selective disclosure, so a producer **SHOULD** present the
narrowest credential set and the fewest claims its reading of the
[manifest](../../manifest/0.1/spec.md) requires. There is no narrowing
afterwards. A producer **MUST NOT** move claims into `extensions` that it was
unwilling to put in `vp` — material there sits outside the presentation's
selective-disclosure machinery and is stored as plain JSON.

`attributes` carries plain values the applicant states about themselves —
self-asserted by construction, stored as given, and bound to the applicant only
by the document proof. It holds exactly what the manifest's
`requestedAttributes` asks for: a consumer refuses a type it did not request
(`attributesUnrequested`) rather than keep it, because a value accepted "just in
case" is personal data held with no stated purpose. A producer **SHOULD** send
these through the applicant's own disclosure path so that the applicant's record
of what they told whom includes them, and **MUST NOT** move a value into
`attributes` that the applicant would only share inside a credential.

### Correlation

The community maintainer declares `identifierScope: public`, and it has to. An
applicant has to address the community it means to join, having found that DID in
a directory, a manifest, or a governance document published by someone else; a
pairwise community identifier would mean no two prospective applicants could
confirm they were applying to the same body, and the
[manifest](../../manifest/0.1/spec.md) that tells them what to present could
not be tied to the community that will judge it. The cost is the ordinary one: a
community DID is a fixed point every observer of the ecosystem can name.

The applicant declares `identifierScope: pairwise`, and nothing in this task
argues otherwise. The signer DID must be stable enough to poll
[`status`](../../status/0.1/spec.md) and to receive a membership credential,
which is a lifetime measured in this one relationship — not a reason to reuse the
identifier with a second community. An applicant that submits to several
communities under one DID hands every one of them a join key to the others'
records, and this specification neither needs nor rewards that.

What is unavoidable is inside `vp`. Credential identifiers, issuer DIDs, and any
non-selectively-disclosable claim travel with the presentation, so two communities
holding submissions from the same person can align them on credential material
even where the applicant used distinct DIDs. That is a property of the
presentation formats, not of this task, and it is the reason the pairwise
declaration above is a floor rather than a guarantee.

### Retention

Durable, and this is the hard edge of the family. The community records the
presentation on a [`JoinRequest`](../../../_shared/0.1/join-request.schema.json)
row — as `vp`, and again as `vpClaims`, a canonical projection extracted at
submission time so the policy engine need not re-parse the presentation. Deleting
one copy does not delete the claims.

That row survives the decision. A **refused** applicant is left in a position
worth stating plainly: the claims they disclosed to a community that would not
have them remain on that community's systems, readable by every administrator
through [`show`](../../show/0.1/spec.md) and enumerable in bulk through
[`list`](../../list/0.1/spec.md), for as long as the community keeps the row.
Nothing in this payload sets a lifetime, no member requests erasure, and no error
code refuses a submission on retention grounds — the applicant's only control is
the one they exercised before submitting, by choosing what to present.

The retention is not gratuitous. The presentation is the evidence the admission
decision rested on, and a community that discards it cannot later show why it
admitted or refused anyone. Implementers **SHOULD** publish the disposal policy
that this specification cannot supply, and **SHOULD** distinguish the retention a
refused application needs from the retention an admitted one does, because the
two are not the same question and the schema does not separate them.

### Consent/purpose

The purpose is admission: the applicant discloses credentials so that one
community can decide one application against its published join policy.
`registryConsent` is the only member in the payload that speaks to any use beyond
that, and it speaks to exactly one — whether the applicant agreed to trust-registry
publication. Its scope is therefore narrow by construction, and a consumer
**MUST NOT** read a `true` there as agreement to anything else it might do with
the presentation.

`extensions` and `ext` are applicant-authored and carry no consent signal at all.
A community that mines them, or that reuses `vpClaims` to seed a member directory,
a mailing list, or a shared registry, is putting the material to a purpose the
applicant addressed only insofar as `registryConsent` covers it.

Whether a human reviews an application, whether a second approver is required, and
what lawful basis a deployment relies on for holding the presentation are all
consumer policy questions. Per [SPEC §7.3](/SPEC.md#73-specification-requirements)
item 13 this specification takes no position on any of them; it describes what the
document moves and where it comes to rest.
