Messages and Encoding
This page is normative
This page is considered a core part of the Vultron Protocol. This is a normative section of the documentation.
The whole specification on one page
The specification is also published as a single page that holds every section and annex in order, for printing or for searching the whole text at once.
This page holds sections 4 and 5 of the Vultron Protocol Specification. §4 says what a participant sends in each situation of a case, and what a message it receives means. §5 says how a message is encoded on the wire and delivered, including the required Representational State Transfer (REST) transport profile. The case state messages report the Vendor aware, Fix ready, fix Deployed (VFD) and Public aware, eXploit public, Attacks observed (PXA) dimensions of the Case State (CS).
4. Messages [N]
What happened to the formal message type shorthand?
The formal message set, with its two-letter shorthands such as RS, EP and CV, was a design model of the protocol's messages.
This version realizes that model as occasions, each conveyed by one wire activity.
Formal types that share one wire activity merged, and context tells them apart: the receiver's embargo state separates EV, EJ and EC from EP, ER and EA, and a field value separates CV, CF and CD, and CP, CX and CA.
EA and EC are the Case Owner's activation of a proposal, and ER and EJ its rejection, told apart by whether the case embargo is Proposed or Revise.
ER is also the CASE_MANAGER's abandonment of a proposal, its own Reject of the Invite.
A participant's Accept or Reject of an embargo Invite is its own consent, which the formal set does not model, so it carries no shorthand (MSM-02-010).
The formal set remains the vocabulary of the transition tables of §6 Report Management (RM) State Machine through §9 Participant Embargo Consent (PEC) State Machine (ADR-0083).
This section defines what a participant sends in each situation of a case, and what a message it receives means.
Its unit is the occasion: a situation in a case that a sender conveys with a particular Wire Activity.
A normative statement about a message is a statement about an occasion.
A protocol shorthand, such as RS or EP, is a cross-reference tag that names the formal message an occasion realizes.
Wire activities are written in the notation of Wire Activity Notation, Verb(Object)[field=Value], using the type values a sender puts on the wire.
§5 Encoding and Transport specifies how each one is encoded and delivered.
4.1 Rules Under Any Coordination Model
These rules hold for every message, however the case is coordinated.
Every message reports something that already happened. A message does not instruct its recipient to make a transition. It tells the recipient that the sender has made one, or that the sender has observed something (§3.1 Coordination Model). A proposal, such as an embargo invitation, asks for a decision, and its answer reports the decision once it is made.
A message that arrives before its case is held, not applied. A message from the CASE_MANAGER may reach a participant before the bootstrap message that establishes the case and its trust (§10.3 Case Bootstrap and the Trust Root). The participant holds such a message for a short, bounded interval, and drops it if the bootstrap message has not been validated by then. Applying it early would create case state from a message whose context was never established.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
CBT-03-001 |
SHOULD | If a CASE_MANAGER-originated case message arrives before the required bootstrap trust handoff, the receiving actor SHOULD queue it only for a short bounded interval rather than accepting or permanently trusting it immediately. The transport does not promise delivery order (SYNC-19-003), so a message from the real CASE_MANAGER can arrive before the bootstrap that makes it trusted. If the receiver drops the message at once, the message is lost. If the receiver applies it at once, it trusts a sender it has not checked. A short hold keeps the message until the bootstrap arrives, and the limit stops untrusted messages from staying in storage with no end. |
Refines: PCR-06-002 |
CBT-03-002 |
MUST NOT | A pre-bootstrap CASE_MANAGER message MUST NOT update local case state before the corresponding trust-establishing bootstrap message has been validated. Before the bootstrap is validated, the receiver cannot know that the sender is the CASE_MANAGER. A state change from that message can come from any actor, and the receiver would then hold case state that no trusted source sent. |
Refines: PCR-06-003 |
CBT-03-003 |
MUST | When the bounded pre-bootstrap queue interval (CBT-03-001) expires, the receiver MUST drop the queued message. A message the receiver cannot yet trust must not wait without limit for a case copy that may never arrive. Dropping it when the interval ends limits what the receiver stores. ADR-0163 gives the recovery of a dropped Invite to the CASE_MANAGER, which knows which Invites each participant has not answered. |
Extends: CBT-03-001 |
Messages are addressed according to the routing rules of §10 Case Coordination.
4.2 Knowledge Model and Actor Isolation
Each participant knows only what it has been told. This subsection states what follows from that, including why a recipient can obtain every object a message names (§5.2 Serialization).
What a participant knows versus what is true. A participant's replica reflects the messages it has received. Two participants in the same case may hold different views at the same moment, because a message is in transit or because a participant has not yet reported a change. The protocol does not keep every participant in agreement at every instant. Each participant converges on the case's canonical state as ledger entries reach it.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
VP-01-003 |
MUST NOT | Correct operation of the protocol MUST NOT depend on perfect information across all Participants Participants in a distributed CVD case never all see the same state at the same moment: messages are delayed, lost, or withheld by embargo scope. A protocol that needed perfect shared information would stall or misbehave in every real case, so each step must be safe on the partial view a participant actually holds. |
No participant reads another's state. Actors exchange information only through protocol messages, even when they run in one process. What a participant knows about another comes from the messages it has received, including the entries of the canonical ledger. This is what makes a participant's knowledge independent of any other participant being reachable.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
AKM-01-002 |
MUST NOT | Co-located actors MUST NOT communicate by reading or writing each other's local state, or by calling into each other directly. Co-located actors share a server or a process. A direct shortcut between co-located actors bypasses the inbox pipeline, so its exchanges skip validation, the addressee and entitlement gates, and the case ledger, and leave nothing a remote participant would receive. |
Derives from: PCR-01-003 |
AKM-01-003 |
MUST | Co-located actors MUST still exchange protocol messages through each other's inboxes. Co-located actors share a server or a process. Delivery through inboxes makes co-location invisible to the protocol: the same actors behave the same whether or not they share a process. |
Extends: AKM-01-002 |
PCR-01-003 |
MUST | The protocol MUST work the same whether every Actor runs on one host or on many. Actor co-location is an implementation choice. Co-location is a deployment choice. Code that reads another Actor's store, or waits for a side channel, works only while two Actors share a host. Per-actor stores (ADR-0073) prevent direct reads and writes, but not code that expects the case to be visible early. |
|
PCR-01-004 |
MUST | Actors MUST exchange information only through protocol messages. A protocol message is the one channel every deployment shares. Information that passes any other way works only while two Actors share a host, so the protocol would then depend on where the Actors run (PCR-01-003). |
Implements: PCR-01-003 |
PCR-01-005 |
MUST NOT | An Actor MUST NOT read, write, or otherwise reach into another Actor's store. Each Actor has its own store (ADR-0073). A read or write of another Actor's store works only on a shared host, and it changes that Actor's state without a message that Actor can check. |
Derives from: PCR-01-003 |
PCR-01-006 |
MUST NOT | An Actor MUST NOT rely on out-of-band communication with a co-located Actor. A side channel between two Actors on one host is not there when they run apart. Code that waits for one then fails, or works only by chance, in a distributed deployment. |
Derives from: PCR-01-003 |
PCR-01-007 |
MUST | An Actor that asked a CASE_MANAGER to create a case MUST treat the case as absent until the CASE_MANAGER's Create(VulnerabilityCase) reaches it. It never assumes that co-location makes the case visible sooner.The report receiver does not create the case (ADR-0041), so it holds the case only after the CASE_MANAGER's Create(VulnerabilityCase) arrives. A tree that acts on the case sooner has nothing to act on, even when the CASE_MANAGER shares its host. |
Refines: PCR-01-003 |
A recipient can obtain what a message names. A sender does not assume that a recipient holds an object it was never sent. An object the recipient cannot be expected to hold is carried inline, or by a reference the recipient can dereference. Either form satisfies the protocol.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
AKM-02-001 |
MUST NOT | An Actor MUST NOT assume that a recipient has knowledge of any object that has not been explicitly included in a prior activity sent to that recipient. A recipient holds only what it has been sent. An activity that relies on an object the recipient never received cannot be processed, or is processed against a guess, so a sender must reason from what it has actually delivered to that recipient. |
|
AKM-02-002 |
MUST NOT | Actors MUST NOT name an object the recipient cannot be expected to hold already by a reference the recipient cannot dereference (AKM-05-003, AKM-05-004). Such an object is carried inline, or by a reference the recipient can fetch. A reference the recipient can neither match to an object it holds nor fetch leaves it unable to read what the activity acts on, so it must refuse the activity or guess. Carrying such an object inline, or by a reference the recipient can fetch, keeps every activity processable by its addressee. |
Uses definition from: AKM-05-003 See also: AKM-05-004 — context for the reader |
4.3 Object Types
An activity's meaning depends on what it acts on, so the object types matter as much as the verbs. Vultron extends the ActivityStreams 2.0 (AS2) vocabulary with the object types a vulnerability case needs, and they are not a flat set. A case contains participants, reports, status records, embargoes and an ordered ledger, as the diagram below shows. That containment is the model the rest of this specification assumes.
---
title: Vultron object containment
---
classDiagram
VulnerabilityCase "1" *-- "1..*" CaseParticipant
VulnerabilityCase "1" *-- "0..*" VulnerabilityReport
VulnerabilityCase "1" *-- "1" CaseStatus
VulnerabilityCase "1" *-- "0..*" CaseLedgerEntry
VulnerabilityCase "1" *-- "0..*" EmbargoEvent
VulnerabilityCase "1" *-- "0..*" Note
CaseParticipant "1" *-- "0..*" ParticipantStatus
CaseParticipant "1" o-- "0..*" CaseParticipantRole
CaseParticipant "1" *-- "0..*" EmbargoConsent
EmbargoConsent ..> EmbargoEvent : consents to
CaseProposal ..> VulnerabilityCase : requests creation of
| Object | What it is |
|---|---|
VulnerabilityCase |
The case itself: the container for everything below |
CasePreview |
The case's preview: a minimal description of a case, carrying enough for an invited actor to decide whether to join and no vulnerability detail, sent as the preview of the case reference a stub Invite carries as its object |
VulnerabilityReport |
A report of the vulnerability, such as the one that started the case |
CaseParticipant |
An actor's membership in a case, carrying the roles it holds and the state it owns |
CaseParticipantRole |
A role offered to an actor in the context of a case. It is a distinct type so that offering a role is structurally different from offering ownership of the case |
EmbargoEvent |
An embargo's terms: its start and end times. It is a Vultron extension of the AS2 Event type, which is why embargo messages are invitations to an event rather than an embargo-specific verb |
EmbargoConsent |
One participant's consent to one embargo, held on that participant's record (§9 Participant Embargo Consent (PEC) State Machine) |
CaseLedgerEntry |
One entry in the canonical case ledger (§2.3 Protocol Objects and Messages) |
CaseProposal |
A request that some actor create and manage a case. The requesting actor does not intend to manage the case itself, and the actor that accepts becomes the case's creator |
CaseStatus / ParticipantStatus |
Status records: a ParticipantStatus is one participant's claim, and a CaseStatus is the case's canonical status, which only the CASE_MANAGER writes (§10.5 Claims and Canonical Status) |
ProcessingFault |
A receiver's report that it could not process a message (§4.11 Faults and Acknowledgments) |
Note |
The AS2 Note type, used unchanged for narrative posted to the case |
An embargo is sent as type: EmbargoEvent.
A sender gives an embargo the type value EmbargoEvent, not the plain AS2 Event it extends, and the occasion tables name it that way (Wire Activity Notation).
4.4 Message Tables
Each message subsection below includes its group of the occasion table, generated from the reference implementation's registry of wire activities (Message Types). Each row is one occasion, and its columns say:
| Column | Says |
|---|---|
| When… | The sender's situation |
| Send | The wire activity that conveys it |
| Send to | The addressee: the CASE_MANAGER, a participant, or, before a case exists, an actor outside any case |
| Sent by | The standing a receiver requires of the sender |
| Distinguished by | What tells this occasion apart from another occasion that shares its wire activity and addressee |
| Details | The occasion's section in the message reference, named by its protocol shorthand where it has one |
"The CASE_MANAGER" in a table is the participant that holds the CASE_MANAGER role for the case, whichever actor that is (§10 Case Coordination). A row whose "Sent by" reads "internal to the CASE_MANAGER" is an act the CASE_MANAGER performs on its own case. No receiver handles such an activity, though the CASE_MANAGER may commit it to the case ledger.
4.5 Report Management Messages
These messages concern one participant's handling of a report. Each reports a change to the sender's report management state (§6 Report Management (RM) State Machine).
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| a Reporter has written up a vulnerability and is about to submit the report | Create(VulnerabilityReport) |
an actor outside any case | any actor (usually: reporter) | — | Create report |
| a Reporter submits a vulnerability report to a Vendor or Coordinator | Offer(VulnerabilityReport) |
an actor outside any case | any actor (usually: reporter) | — | Report Submission (RS) |
| a report receiver has received a submitted report | Read(Offer(VulnerabilityReport)) |
an actor outside any case | the addressee of the vulnerability report offer (usually: vendor, coordinator) | — | Report Acknowledgment (RK) |
| a report receiver judges the report valid | Accept(Offer(VulnerabilityReport)) |
the CASE_MANAGER | a participant (usually: vendor, coordinator) | — | Validate report |
| a report receiver judges the report invalid | TentativeReject(Offer(VulnerabilityReport)) |
the CASE_MANAGER | a participant (usually: vendor, coordinator) | — | Invalidate report |
| a report receiver closes a report no case holds | Reject(Offer(VulnerabilityReport)) |
an actor outside any case | the addressee of the vulnerability report offer (usually: vendor, coordinator) | — | Close report |
| a Participant accepts the case for further action | Join(VulnerabilityCase) |
the CASE_MANAGER | a participant | — | Report/Case Accepted (RA) |
| a Participant defers further action on the case | Ignore(VulnerabilityCase) |
the CASE_MANAGER | a participant | — | Report/Case Deferred (RD) |
Only Report Submission (RS) drives a state change in its receiver: receiving a report moves the receiver to Received.
The other messages tell the receiver something about the sender and leave the receiver's own state alone.
A participant that joined the case by invitation never saw the report offer, so it reports Report Valid (RV), Report Invalid (RI) or Report Closed (RC) by answering the full-case Invite (§4.7 Case and Participant Messages).
RK acknowledges the submission, not the reading
Report Acknowledgment (RK) reports that the submission arrived.
It does not report that the recipient has read the report, assessed it, or agreed to work on it: those are RV, RI, Report/Case Accepted (RA) and Report/Case Deferred (RD).
The protocol defines no message meaning "I have read the report".
RK carries no report management state, so it tells the reporter nothing about whether the recipient has examined the content.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
RMB-08-003 |
MUST | An actor that an Offer(VulnerabilityReport) was addressed to MUST send the RK that acknowledges it to the reporter, the Offer's actor. It may send the RK at any time after it receives the report, whether or not a case exists for it.The reporter checks who may acknowledge its Offer against its own record of that Offer (RMB-08-004). The store of each addressee also holds a record. RK answers the reporter's Offer and is outside the case, so it is the stated exception to PCR-08-001 and to the routing topology of VP-18-001, VP-18-002 and VP-18-003. ECA DetailsSteps 1. [receiver of the report] Emit RK addressed to the Offer's actor → RK queued for the reporter only Postconditions - The reporter holds the RK |
Refines: VP-03-009 — RK acknowledging RS Supersedes: PCR-08-001 — the stated RK exception to CASE_MANAGER-only addressing Supersedes: VP-18-001 — the stated RK exception to the CASE_MANAGER routing path Supersedes: VP-18-002 — the stated RK exception to the no-direct-delivery rule Supersedes: VP-18-003 — the stated RK exception to CASE_MANAGER-mediated delivery |
RMB-08-005 |
MUST NOT | An actor MUST NOT send an RK that acknowledges a report submission to the CASE_MANAGER. The CASE_MANAGER has no record of the addressees of the Offer, so it cannot check an RK that it receives (RMB-08-004). An RK sent to it can also reach parties that did not receive the report. ECA DetailsPostconditions - The CASE_MANAGER received no RK |
Extends: RMB-08-003 |
RMB-08-006 |
MUST NOT | A receiver of an RK that acknowledges a report submission MUST NOT forward it. RK answers the reporter's Offer outside the case. A forwarded RK can reach parties that did not receive the report. ECA DetailsSteps 1. [any receiver of RK] Record the RK at intake → No RK forwarded |
Extends: RMB-08-003 |
RMB-08-007 |
MUST NOT | An actor MUST NOT write a case ledger entry for an RK that acknowledges a report submission. RK is outside the case, so it is not a case event. A ledgered RK would also replicate to parties that did not receive the report. ECA DetailsSteps 1. [any receiver of RK] Record the RK at intake → No ledger entry written |
Extends: RMB-08-003 |
VP-03-009 |
SHOULD | Recipients SHOULD acknowledge the \(R*\) messages they receive, other than \(RK\) itself. \(RK\) acknowledges only \(RS\): an addressee of the report's Offer sends it to the reporter (RMB-08-003). No other \(R*\) message is acknowledged with \(RK\); once a case exists, its acknowledgment is the CASE_MANAGER's ledger entry for it, fanned out to the participants. Before a case exists there is no ledger, so the reporter learns that its report arrived only from an \(RK\) (RMB-08-003). Once a case exists, every \(R*\) message goes to the CASE_MANAGER (PCR-08-001), and the ledger entry it commits already tells every participant the message was received; a separate \(RK\) would only add traffic and a second acknowledgment that could disagree with the ledger. |
4.6 Case Proposal Messages
A report receiver that does not intend to manage a case itself asks a Case Actor Service to open one. This exchange happens before the case exists, so its messages go to an actor outside any case.
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| a report receiver asks a Case Actor Service to open a case for a report | Create(CaseProposal) |
an actor outside any case | the case proposal's author (usually: vendor, coordinator) | — | Create case proposal |
| a Case Actor Service agrees to open the proposed case | Accept(CaseProposal) |
an actor outside any case | the addressee of the case proposal | — | Accept case proposal |
| a Case Actor Service declines to open the proposed case | Reject(CaseProposal) |
an actor outside any case | the addressee of the case proposal | — | Reject case proposal |
4.7 Case and Participant Messages
These messages create a case and manage who is in it.
Most have no protocol shorthand, because they concern the case as an object rather than any state machine's state.
The exception is the answer to the full-case Invite, which realizes RV, RI or RC, as described below.
How a participant joins, changes role and leaves is specified at §12 Participant Lifecycle Within a Case.
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| the CASE_MANAGER has opened a case for a submitted report | Create(VulnerabilityCase) |
a participant | the addressee of the case proposal or vulnerability report offer | — | Create case |
| the Case Owner links a further report to an existing case | Add(VulnerabilityReport)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | — | Add report to case |
| the CASE_MANAGER records the new Case Owner once a case ownership transfer is accepted | Update(VulnerabilityCase) |
a participant | internal to the CASE_MANAGER | — | Update Case Owner |
| the CASE_MANAGER brings a vulnerability item into a case, such as one a new case takes from its CSAF report | Add(VulnerabilityItem)[target=VulnerabilityCase] |
a participant | internal to the CASE_MANAGER | — | Add vulnerability item to case |
| the CASE_MANAGER brings a case reference into a case, such as one a new case takes from its CSAF report | Add(CaseReference)[target=VulnerabilityCase] |
a participant | internal to the CASE_MANAGER | — | Add case reference to case |
| the Case Owner offers a CVD role on the case to another participant | Offer(CaseParticipantRole)[context=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | — | Offer case participant role |
| a participant accepts a role offered to it on the case | Accept(Offer(CaseParticipantRole)[context=VulnerabilityCase]) |
the CASE_MANAGER | the addressee of the case participant role offer | — | Accept case participant role |
| a participant declines a role offered to it on the case | Reject(Offer(CaseParticipantRole)[context=VulnerabilityCase]) |
the CASE_MANAGER | the addressee of the case participant role offer | — | Reject case participant role |
| the Case Owner proposes to transfer ownership of the case to another participant | Offer(Offer(VulnerabilityCase)) |
the CASE_MANAGER | the Case Owner | — | Propose case ownership transfer |
| the CASE_MANAGER offers the case to the actor the Case Owner proposed | Offer(VulnerabilityCase) |
a participant | the CASE_MANAGER | — | Offer case ownership transfer |
| an actor accepts an offer of case ownership | Accept(Offer(VulnerabilityCase)) |
the CASE_MANAGER | the addressee of the vulnerability case offer | — | Accept case ownership transfer |
| an actor declines an offer of case ownership | Reject(Offer(VulnerabilityCase)) |
the CASE_MANAGER | the addressee of the vulnerability case offer | — | Reject case ownership transfer |
| the Case Owner withdraws its proposal while the offer of case ownership is open | Undo(Offer(Offer(VulnerabilityCase))) |
the CASE_MANAGER | the Case Owner | — | Withdraw case ownership transfer |
| the CASE_MANAGER invites an actor to join the case | Invite(VulnerabilityCase preview)[target=Actor] |
a participant | the CASE_MANAGER | — | Invite actor to case |
| an invited actor agrees to join the case | Accept(Invite(VulnerabilityCase preview)[target=Actor]) |
the CASE_MANAGER | the invitee | — | Accept invite to case |
| an invited actor declines to join the case | Reject(Invite(VulnerabilityCase preview)[target=Actor]) |
the CASE_MANAGER | the invitee | — | Reject invite to case |
| the CASE_MANAGER has replayed the case ledger to a newly joined Participant | Invite(whole VulnerabilityCase)[target=Actor] |
a participant | the CASE_MANAGER | — | Send Full-Case Invite |
| a Participant asked by a Full-Case Invite judges the case valid | Accept(Invite(whole VulnerabilityCase)[target=Actor]) |
the CASE_MANAGER | the invitee | — | Accept Full-Case Invite |
| a Participant asked by a Full-Case Invite judges the case invalid | TentativeReject(Invite(whole VulnerabilityCase)[target=Actor]) |
the CASE_MANAGER | the invitee | — | Tentatively reject Full-Case Invite |
| a Participant asked by a Full-Case Invite closes the case | Reject(Invite(whole VulnerabilityCase)[target=Actor]) |
the CASE_MANAGER | the invitee | — | Reject Full-Case Invite |
| the CASE_MANAGER has admitted a new Participant to the case | Announce(VulnerabilityCase) |
a participant | the CASE_MANAGER | — | Announce vulnerability case |
| a Participant ends its participation in the case | Leave(VulnerabilityCase) |
the CASE_MANAGER | the Case Owner or a participant | — | Close case |
| the Case Owner reinstates a removed Participant | Add(CaseParticipant)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | — | Add case participant to case |
| the Case Owner removes a Participant from active participation | Remove(CaseParticipant)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | — | Remove case participant from case |
| the CASE_MANAGER creates a participant record, such as the inert record for the invitee of a stub Invite | Create(CaseParticipant) |
a participant | internal to the CASE_MANAGER | — | Create case participant |
| the CASE_MANAGER changes a participant record, such as moving the CASE_OWNER role on an ownership transfer | Update(CaseParticipant) |
a participant | internal to the CASE_MANAGER | — | Update case participant |
The two ways an actor joins a case are different messages. Conflating them loses a round trip in which the Case Owner decides:
Invite(VulnerabilityCase preview)[target=Actor]is the CASE_MANAGER inviting an actor to join on the Case Owner's behalf. It is answered withAcceptorReject.Offer(Actor)[target=VulnerabilityCase]is a participant recommending an actor (§4.10 General Messages). It goes to the CASE_MANAGER, which passes it to the Case Owner as anOffer(CaseParticipant). The Case Owner decides on it, and its approval may cause anInviteto be sent. It is not an invitation to the recommended actor.
Both paths end in an Accept of the stub Invite (§12.2 Invitation and Acceptance).
That Accept joins the case; it is not RV.
The joined participant judges the case by answering the full-case Invite, Invite(whole VulnerabilityCase)[target=Actor], and that answer is RV, RI or RC.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
CM-16-001 |
MUST | A participant wishing to suggest that another actor be invited to the case MUST send Offer(Actor)[target=VulnerabilityCase] to the CASE_MANAGER's inbox, not directly to the Case Owner's inbox.All case-scoped protocol messages MUST route through the CASE_MANAGER so the event can be recorded in the canonical case ledger before any downstream action is taken (ADR-0021, PCR-08-001). |
Refines: PCR-08-001 |
CM-16-004 |
MUST | The CASE_MANAGER MUST transform the received Offer(Actor) into Offer(CaseParticipant)[target=VulnerabilityCase], whose CaseParticipant has attributed_to set to the actor and case_roles set to the roles, and send it to the Case Owner's inbox, with inReplyTo set to the ID of the original recommender's Offer activity and no origin.The Case Owner makes a membership decision about a CaseParticipant (actor + roles), not about a bare Actor identity. The forward answers the recommender's Offer, and AS2 inReplyTo names the entities an object responds to, so it preserves the causal chain without a side-channel data store. origin names where an object comes from or leaves, so it is not the link to an answered activity. |
|
CM-11-011 |
MUST | The CASE_MANAGER MUST record each full-case Invite reply as a move from RM.RECEIVED: RV Accept to RM.VALID, RI TentativeReject to RM.INVALID, RC Reject to RM.CLOSED.Each reply is the participant's own judgement of the case (ADR-0121). The three replies map to the three RM triage outcomes, so every replica records the judgement the participant made. |
|
CM-11-034 |
MUST | A reply to the full-case Invite MUST carry the replier's own ledger position: the log_index and entry_hash of its tail when it decided.The position is the reply's ledgerPosition, the property every case activity carries (VAM-04-012..014, SYNC-18-001, ADR-0156), so the CASE_MANAGER judges it against the Invite's floor (CM-11-012) from the one field it reads on every case activity. |
Extends: CM-11-011 |
CM-11-020 |
MUST NOT | A participant that joined a case through an Invite MUST NOT send Accept, TentativeReject or Reject of the original Offer(VulnerabilityReport).A reply must answer a message sent to the replier. A joined participant was never offered that report. |
|
CM-11-051 |
MUST NOT | A participant that joined a case through an Invite MUST NOT validate, invalidate or reject the case's report. It judges the case by replying to the full-case Invite (CM-11-011). A joined participant — a late joiner especially — judges the case as it stands, with its history, not the original submission, which may have been far sparser (ADR-0121). |
Extends: CM-11-020 See also: CM-11-011 — context for the reader |
4.8 Embargo Management Messages
These messages negotiate the case's embargo (§7 Embargo Management (EM) State Machine). A participant proposes or answers terms by writing to the CASE_MANAGER, which asks each other participant about a proposal, and the Case Owner decides whether a proposal takes effect.
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| the Case Owner terminates the active embargo | Remove(EmbargoEvent) |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner | — | Embargo Termination (ET) |
| the CASE_MANAGER ends the active embargo, on its own decision or on the Case Owner's | Remove(EmbargoEvent) |
a participant | the CASE_MANAGER | — | Tell a participant the embargo has ended |
| the CASE_MANAGER states the terms of the embargo in force | Announce(EmbargoEvent)[context=VulnerabilityCase] |
a participant | the CASE_MANAGER | register status of the named embargo ACTIVE |
Announce embargo |
| the CASE_MANAGER has applied an Embargo Termination a Case Owner sent before the end time | Announce(EmbargoEvent)[context=VulnerabilityCase] |
a participant | the CASE_MANAGER | register status of the named embargo TERMINATED |
Announce embargo termination |
| a Participant proposes embargo terms for a case with no active embargo | Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or an active participant | EM state NONE or PROPOSED |
Embargo Proposal (EP) |
| a Participant proposes revised terms for the active embargo | Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or an active participant | EM state ACTIVE or REVISE |
Embargo Revision Proposal (EV) |
| the CASE_MANAGER asks a Participant to answer embargo terms another Participant proposed | Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] |
a participant | the CASE_MANAGER | — | Ask a participant about proposed embargo terms |
| a Participant agrees to proposed embargo terms | Accept(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
the CASE_MANAGER | the invitee | EM state PROPOSED |
Agree to proposed embargo terms |
| a Participant agrees to a proposed embargo revision | Accept(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
the CASE_MANAGER | the invitee | EM state REVISE |
Agree to an embargo revision |
| a Participant refuses proposed embargo terms | Reject(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
the CASE_MANAGER | the invitee | EM state PROPOSED |
Refuse proposed embargo terms |
| a Participant refuses a proposed embargo revision | Reject(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
the CASE_MANAGER | the invitee | EM state REVISE |
Refuse an embargo revision |
| the CASE_MANAGER abandons an open embargo proposal it received once the case is public, an exploit is public or attacks are observed | Reject(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
a participant | the CASE_MANAGER | — | Abandon embargo proposal |
| the CASE_MANAGER abandons an open embargo proposal once the case is public, an exploit is public or attacks are observed | Undo(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
a participant | internal to the CASE_MANAGER | — | Withdraw an embargo invitation |
| the Case Owner decides to activate a proposed embargo for a case with no active embargo | Add(EmbargoEvent)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | EM state PROPOSED |
Embargo Proposal Acceptance (EA) |
| the Case Owner decides to replace the active embargo with a proposed revision | Add(EmbargoEvent)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | EM state REVISE |
Embargo Revision Acceptance (EC) |
| the Case Owner decides to reject a proposed embargo for a case with no active embargo | Reject(EmbargoEvent)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | EM state PROPOSED |
Reject embargo proposal |
| the Case Owner decides to reject a proposed revision | Reject(EmbargoEvent)[target=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner | EM state REVISE |
Embargo Revision Rejection (EJ) |
| a Participant bound by the active embargo stops complying with it | Leave(EmbargoEvent)[context=VulnerabilityCase] |
the CASE_MANAGER | a participant | — | Withdraw from embargo |
| the CASE_MANAGER has created a case and, with it, an embargo such as the default embargo | Create(EmbargoEvent) |
a participant | internal to the CASE_MANAGER | — | Create embargo event |
| the CASE_MANAGER creates a participant's consent row for an embargo, such as the UNINVITED row a proposal writes | Create(EmbargoConsent) |
a participant | internal to the CASE_MANAGER | — | Create embargo consent |
| the CASE_MANAGER changes a participant's consent row, such as an invitation timing out, the rows carried over at activation or a change of its own consent | Update(EmbargoConsent) |
a participant | internal to the CASE_MANAGER | — | Update embargo consent |
A revision proposal and an initial proposal are the same activity
Embargo Revision Proposal (EV), Embargo Revision Rejection (EJ) and Embargo Revision Acceptance (EC) share their wire activities with Embargo Proposal (EP), Embargo Proposal Rejection (ER) and Embargo Proposal Acceptance (EA).
The activity does not encode the difference.
EA and EC are both the Case Owner's Add(EmbargoEvent)[target=VulnerabilityCase], which adds the embargo to the case, and ER and EJ are both its Reject(EmbargoEvent)[target=VulnerabilityCase].
Each of the four names the Invite(EmbargoEvent) that proposed the embargo in inReplyTo.
ER is also the CASE_MANAGER's Reject(Invite(EmbargoEvent)) that abandons a proposal.
A participant's Accept or Reject of the Invite it was sent is its own consent, carries no shorthand, and moves no embargo state (MSM-02-010).
A receiver tells which it has received from its own embargo state, as the "Distinguished by" column states. If the case embargo is Active or Revise, an arriving proposal is a revision. If it is None or Proposed, the same message is an initial proposal.
The outcome of a rejection differs between the two: rejecting an initial proposal leaves the case with no embargo, while rejecting a revision leaves the agreed terms in force (§7.2 Transitions and Guards). An implementation that treats the activity as self-describing will mishandle every revision. Because a mishandled revision rejection returns the case to None, it silently drops embargoes that every participant still believes are in force.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
EMB-01-001 |
MUST | A Participant in EM None (q^em ∈ N) with CS not yet public/exploit/attack (q^cs ∈ ···pxa) receiving EP MUST transition their EM state to Proposed (q^em N → P). "Emit EK" is discharged by the CASE_MANAGER's commit of the received activity, fanned out as Add(CaseLedgerEntry); no EK message is emitted (EP-09-009).EP is the EM message that initiates embargo negotiation. When no embargo exists and the case is still pre-public, the receiver transitions to Proposed to signal they are evaluating the proposal. ECA DetailsPreconditions - EM state is None; CS matches pattern ...pxa - EM state: NONE- CS pattern: ...pxaSteps 1. [receiver] Transition EM state from NONE to PROPOSED → Receiver EM state is PROPOSED 2. [receiver] CASE_MANAGER commits the received EP and adds the entry to the ledger (discharges EK) → Ledger entry committed and fanned out; no EK message exists Postconditions - Receiver EM state is PROPOSED; EK discharged by the ledger commit |
Uses definition from: MSM-02-001 — EP shorthand wire-type mapping Uses definition from: EP-09-009 |
EMB-03-001 |
MUST | A Participant in EM Active (q^em ∈ A) with CS not yet public/exploit/attack (q^cs ∈ ···pxa) receiving EV MUST transition their EM state to Revise (q^em A → R). "Emit EK" is discharged by the CASE_MANAGER's commit of the received activity, fanned out as Add(CaseLedgerEntry); no EK message is emitted (EP-09-009, MSM-02-009).A participant must know that a change to the embargo is open while the current terms still bind it. Revise records both facts: an embargo is in force, and a revision of it waits for an answer. If the receiver stayed in Active, it could not tell that a later EC or EJ decides a revision. The revision does not change any participant's consent to the embargo in force until the Case Owner activates it (EP-05-002). ECA DetailsPreconditions - EM state is Active; CS matches pattern ...pxa - EM state: ACTIVE- CS pattern: ...pxaSteps 1. [receiver] Transition EM state from ACTIVE to REVISE → Receiver EM state is REVISE 2. [receiver] CASE_MANAGER commits the received EV and fans out its entry (discharges EK) → Ledger entry committed and fanned out; no EK message exists Postconditions - Receiver EM state is REVISE; original embargo remains in force; EK discharged by the ledger commit |
Uses definition from: MSM-02-003 — EV shorthand wire-type mapping Uses definition from: EP-09-009 See also: MSM-02-009 — context for the reader |
Choosing between EV and ET.
Embargo Termination (ET) takes effect immediately.
A sender that wants the embargo to end at some future point proposes that end date with EV instead.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
VP-11-008 |
SHOULD | If early embargo termination is desired but the termination date/time is in the future, this SHOULD be achieved through an Embargo Revision Proposal and additional communication Participants must keep the existing terms until the new end time arrives. A revision proposal changes the end time through the usual agreement process, rather than leaving participants unsure whether the embargo still holds. |
Tacit acceptance of a default embargo. Submitting a report without proposing terms accepts the receiver's default embargo policy (§7.2 Transitions and Guards). Where the receiver has published no default, the same section specifies a short protocol default, so an embargo-eligible case never begins without an embargo.
4.9 Case State Messages
These messages report facts about the vulnerability (§8 Case State (CS) Dimensions).
A participant reports them as a claim in a ParticipantStatus, and the CASE_MANAGER records the facts it adopts about the world in a CaseStatus.
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| the CASE_MANAGER records that the public knows of the vulnerability | Add(CaseStatus)[target=OrderedCollection, context=VulnerabilityCase] |
a participant | the CASE_MANAGER | pxaState = Pxa |
Public awareness in a case status |
| the CASE_MANAGER records that an exploit for the vulnerability is public | Add(CaseStatus)[target=OrderedCollection, context=VulnerabilityCase] |
a participant | the CASE_MANAGER | pxaState = PXa |
Exploit public in a case status |
| the CASE_MANAGER records that attackers are exploiting the vulnerability | Add(CaseStatus)[target=OrderedCollection, context=VulnerabilityCase] |
a participant | the CASE_MANAGER | pxaState = pxA |
Attacks observed in a case status |
| a Vendor becomes aware of the vulnerability | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author (usually: vendor) | vfState = Vf |
Vendor Awareness (CV) |
| a Vendor has a fix ready | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author (usually: vendor) | vfState = VF |
Fix Readiness (CF) |
| a Deployer has deployed the fix | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author (usually: deployer) | dState = D |
Fix Deployed (CD) |
| a Participant learns that the public knows of the vulnerability | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author | caseStatus.pxaState = Pxa |
Public awareness in a participant status |
| a Participant learns that an exploit for the vulnerability is public | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author | caseStatus.pxaState = PXa |
Exploit public in a participant status |
| a Participant observes attacks that exploit the vulnerability | Add(ParticipantStatus)[target=OrderedCollection, context=VulnerabilityCase] |
the CASE_MANAGER | the CASE_MANAGER or the Case Owner or the participant status's author | caseStatus.pxaState = pxA |
Attacks observed in a participant status |
Several case state occasions share one activity
Every claim a participant makes, whichever fact it reports, is Add(ParticipantStatus, target=<participant>/statuses).
Every fact the CASE_MANAGER records about the world is Add(CaseStatus, target=<case>/statuses).
The fact travels in the status record's fields, as the "Distinguished by" column states, so an implementation that dispatches on the activity alone cannot tell Fix Readiness (CF) from Attacks Observed (CA).
The two activities differ by the sender's authority, not by the fact.
Only the CASE_MANAGER sends Add(CaseStatus) (§10.5 Claims and Canonical Status).
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
RSH-04-001 |
MUST NOT | An actor that is not the CASE_MANAGER MUST NOT emit Add(CaseStatus).CaseStatus encodes shared EM and PXA state for the entire case. The CASE_MANAGER is the authoritative writer of canonical case state (ADR-0210, CLP-09). Allowing participants to emit Add(CaseStatus) directly would bypass the adoption authorization model. |
|
RSH-04-007 |
MUST | A participant that is not the CASE_MANAGER MUST report the CaseStatus it suggests by embedding it in its own Add(ParticipantStatus).A participant cannot send Add(CaseStatus) (RSH-04-001), but its view of P, X or A still needs to reach the case. Embedding it in the participant's own status puts it through the adoption gate (RSH-01-003). |
Extends: RSH-04-001 |
RSH-04-005 |
MUST | A receiver MUST refuse a received Add(CaseStatus) unless the case's CASE_MANAGER sent it to a participant.RSH-04-001 reserves Add(CaseStatus) for the CASE_MANAGER, which sends it to participants inside a case ledger entry. add_case_status_tree has no StatusAdoptionGate, so admitting it from another sender would adopt that participant's P, X or A report without the Case Owner approval RSH-07-001 requires. A participant embeds the P, X or A it reports in its own Add(ParticipantStatus) instead (RSH-04-007), which the CASE_MANAGER adopts through the gate (RSH-01-003). |
Derives from: RSH-04-001 Refines: HP-01-006 |
RSH-04-012 |
MUST | When a receiver refuses an Add(CaseStatus) under RSH-04-005, it MUST write nothing past intake and send nothing.A refused status is one the receiver must not act on. A write past intake would change case state on the refused claim, and a reply would answer a sender that had no right to send it. |
Extends: RSH-04-005 |
The Vendor aware, Fix ready, fix Deployed (VFD) occasions report the sender's own progress, so receiving one updates the receiver's model of the sender rather than the receiver's own state (§8.4 Receiving CS Messages: Own State vs. Model of Others).
The Public aware, eXploit public, Attacks observed (PXA) occasions in a ParticipantStatus report a claim about the world.
That claim becomes canonical case state only if the CASE_MANAGER adopts it (§11.3 Status Adoption: One Authorization Gate).
4.10 General Messages
These messages carry narrative and actor suggestions.
Together they realize the formal General Inquiry (GI), which spans two exchanges:
- the note lifecycle,
Add(Note)[target=VulnerabilityCase]andRemove(Note)[origin=VulnerabilityCase]; - the actor-suggestion exchange, in which a participant suggests an actor, the CASE_MANAGER presents the suggestion to the Case Owner, and the CASE_MANAGER tells the recommender the Case Owner's decision.
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| a Participant suggests an actor that the case should include | Offer(Actor)[target=VulnerabilityCase] |
the CASE_MANAGER | a participant | sender is not the Case Owner | Suggest actor to case |
| the Case Owner decides to invite an actor to the case | Offer(Actor)[target=VulnerabilityCase] |
the CASE_MANAGER | a participant | sender is the Case Owner | Ask the CASE_MANAGER to invite an actor |
| the CASE_MANAGER presents a suggested actor to the Case Owner | Offer(CaseParticipant)[target=VulnerabilityCase] |
a participant | the CASE_MANAGER | — | Offer case participant |
| the Case Owner approves a suggested actor | Accept(Offer(CaseParticipant)[target=VulnerabilityCase]) |
the CASE_MANAGER | the Case Owner | — | Accept case participant offer |
| the Case Owner declines a suggested actor | Reject(Offer(CaseParticipant)[target=VulnerabilityCase]) |
the CASE_MANAGER | the Case Owner | — | Reject case participant offer |
| the CASE_MANAGER tells a recommender that the actor it suggested will be invited | Accept(Offer(Actor)[target=VulnerabilityCase]) |
a participant | the CASE_MANAGER | — | Accept actor recommendation |
| the CASE_MANAGER tells a recommender that the Case Owner declined the actor it suggested | Reject(Offer(Actor)[target=VulnerabilityCase]) |
a participant | the CASE_MANAGER | — | Reject actor recommendation |
| a Participant posts a note to the case | Add(Note)[target=VulnerabilityCase] |
the CASE_MANAGER | an active participant | — | Add note to case |
| a note's author or the Case Owner withdraws a note from the case | Remove(Note)[origin=VulnerabilityCase] |
the CASE_MANAGER | the Case Owner or the note's author | — | Remove note from case |
A received Create(Note) is not a protocol message, and its receiver does not change the case because of it.
General Acknowledgment (GK) and General Error (GE) have no wire activity of their own; the mechanisms of §4.11 Faults and Acknowledgments serve their purposes.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
VAM-01-011 |
MUST | Each of these case records MUST enter a case only by its one attaching message, which carries it inline or by reference. A CaseStatus enters by the Add(CaseStatus) that attaches it (VAM-08-002). A ParticipantStatus enters by the Add(ParticipantStatus) that attaches it (VAM-08-004). A proposed EmbargoEvent enters by the Invite that proposes it (VAM-05-005). A Note enters by the Add(Note) that attaches it (VAM-07-002).These records mean nothing apart from their case, so a separate Create would add a "created but not attached" state needing its own ledger entry and replica step (CLP-07-013, RSH-08-004) for no gain (ADR-0137). A Create(Note), with or without a case context, is a deferred form recorded as an open question (MS-18-001). These records get one attaching message each. The Create a CASE_MANAGER ledger entry carries as its payload snapshot records a change; it is not a received message. |
Constrains: VAM-08-002 — the Add(CaseStatus) is the only way a case status enters a case Constrains: VAM-08-004 — the Add(ParticipantStatus) is the only way a participant status enters a case Constrains: VAM-05-005 — the Invite is the only way a proposed embargo event enters a case Constrains: VAM-07-002 — the Add(Note) is the only way a note enters a case |
VAM-01-019 |
MUST NOT | A received Create whose object is a CaseStatus, a ParticipantStatus, an EmbargoEvent, a CaseParticipant or a Note is not a protocol message. Its receiver MUST NOT change the case file because of it.Each of these records enters a case only by its attaching message (VAM-01-011) or as the CASE_MANAGER's consequence of an act it records (VAM-01-020). A separate Create would add a "created but not attached" state needing its own ledger entry and replica step (CLP-07-013, RSH-08-004) for no gain (ADR-0137). |
Derives from: VAM-01-011 |
VAM-01-020 |
MUST | A CaseParticipant MUST come into existence only as the CASE_MANAGER's consequence of an act that it records.A participant record means nothing apart from its case, and the CASE_MANAGER records each act that changes the case. A participant made any other way would be a case-file change outside the ledger (CLP-07-013, ADR-0137). |
4.11 Faults and Acknowledgments
The formal message set defines an acknowledgment and an error message for each of its four groups: RK, EK, CK and GK, and RE, EE, CE and GE.
Their status here is not uniform: the groups are not symmetric.
Of the eight, only RK has a wire activity, Read(Offer(VulnerabilityReport)) (§4.5 Report Management Messages).
The other seven have none.
None of the seven arrives as a message of its own, so a participant that waits for one waits forever.
The absences have two different reasons.
EK, CK and GK are redundant.
Changes to a case are replicated through the case ledger, and a participant shows that it received them by holding an unbroken hash chain (§4.12 Ledger Replication Messages).
A per-message acknowledgment would restate what the chain already shows.
RK survives because report submission happens before the case exists, so there is no ledger to carry it.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
EP-09-009 |
MUST NOT | The CASE_MANAGER's commit of a received embargo activity, fanned out as Add(CaseLedgerEntry), is the acknowledgement the EMB behavioural requirements express as "emit EK". Implementations MUST NOT define or emit an EK message to acknowledge an embargo activity.No EK exists in the production stack and MSM-02-009 records that its purpose is served by ledger hash-chain continuity. Under the relay every accepted embargo activity is committed and announced, so the record the specs want the receiver to produce already exists; a second acknowledgement would be a message with no reader (#3918). |
Refines: MSM-02-009 |
RE, EE, CE and GE are deliberately unmodeled, not merely unimplemented.
The protocol does not type an error message by the state machine that produced it, because that grouping tells a receiver nothing it can act on.
Knowing which machine was confused does not indicate what to do about it.
Errors are grouped by failure mode instead, which is actionable:
| Failure mode | When it applies | Wire activity | What the sender can do |
|---|---|---|---|
| Not understood | The message could not be parsed, or its meaning is unrecognized | Create(ProcessingFault) |
Re-send, or send a simpler equivalent |
| Understood but declined | The message was well-formed and meaningful, but the receiver will not act on it given the case's state | Reject of the message being declined |
Reconsider; the state, not the message, is the obstacle |
| Needs explanation | The condition cannot be expressed as a structured message and requires prose | Add(Note)[target=VulnerabilityCase] |
Read the explanation; there is no automatic recovery |
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
MSM-05-001 |
MUST | Fault reporting MUST be partitioned by failure mode rather than by state machine, using exactly three mechanisms: Create(ProcessingFault) when a message was received but not understood; as:Reject when a message was received and understood but declined; and Add(Note)[target=VulnerabilityCase] when the condition requires narrative explanation. A declined message gets a Reject when its addressee decides against it, and a Refuse, the vultron:Refuse subtype of as:Reject, when the CASE_MANAGER refuses it because a precondition did not hold.Failure mode is actionable to a receiver in a way that originating state machine is not. Not-understood calls for a format or version fix, declined calls for a protocol-level decision, and needs-explanation calls for a human. A partition by state machine (RE, EE, CE and GE) carries no such signal, so it would tell the sender only where the fault arose, not what to do about it. A Refuse is a Reject, so it adds no fourth mechanism. |
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| a Participant has received a message it cannot process | Create(ProcessingFault) |
the CASE_MANAGER | an active participant | — | Create processing fault |
| the CASE_MANAGER has refused a participant's assertion because a precondition did not hold | Refuse(Activity) |
a participant | the CASE_MANAGER | — | Refusal notice |
An actor that cannot process an inbound activity from an authenticated sender notifies that sender with Create(ProcessingFault).
It sends no fault to a sender that is not authenticated.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
ASK-07-001 |
MUST | An actor that cannot process an inbound activity from an authenticated sender MUST notify that sender by emitting Create(ProcessingFault). The exception is an inbound Create(ProcessingFault), which ASK-07-019 leaves unanswered.Without a notice, a failure that took milliseconds costs the sender its full ask deadline in silence. |
|
ASK-07-002 |
MUST NOT | An actor MUST NOT emit a processing fault in response to an inbound activity whose sender is not authenticated, or whose failure occurred before authentication. Explaining a parse or validation failure to an unauthenticated sender is a parser oracle, and an unauthenticated sender identity cannot be trusted as a reply address. |
Reject does not mean error
The Reject verb alone does not signal an error.
Reject also carries legitimate protocol answers, including closing a report and declining an embargo invitation, a case invitation, a case proposal or a case ownership transfer.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
MSM-05-003 |
MUST NOT | Implementations MUST NOT infer error semantics from the as:Reject verb alone, because as:Reject also carries legitimate protocol rejections, including closing a report and declining an embargo invitation, a case invitation, a case proposal or a case-ownership transfer.as:Reject is overloaded across error reporting and ordinary protocol refusal. A receiver that treats every as:Reject as a fault will misclassify routine protocol traffic as errors. |
Open question: what a sender does after a processing fault
Error message types (RE, EE, CE) are deliberately unmodeled (ADR-0049).
An actor that cannot process an inbound activity from an authenticated sender reports it with Create(ProcessingFault) (ASK-07-001).
The fault names the failed activity and a failure class, and its receiver rules are specified (§4.11 Faults and Acknowledgments, ASK-07).
On the sending side, a fault about an outstanding ask closes that ask (ASK-07-007).
A fault about an embargo message calls for an inquiry (VP-11-005), and so does a fault about a report-management or case-status message that does not say what went wrong (RMB-07-001, CSB-07-001).
Open: whether the sender resends the failed activity, drops it, or escalates to a person, and whether that choice depends on the failure class. Until this is settled, that choice belongs to each implementation.
4.12 Ledger Replication Messages
These messages keep every active participant's replica of the case ledger in step with the CASE_MANAGER's (§10.4 Ledger Replication and Case Delivery).
| When… | Send | Send to | Sent by | Distinguished by | Details |
|---|---|---|---|---|---|
| the CASE_MANAGER has committed a case event to the case ledger | Add(CaseLedgerEntry) |
a participant | the CASE_MANAGER | — | Add case ledger entry |
| a received ledger entry does not chain onto the Participant's own ledger | Reject(CaseLedgerEntry) |
the CASE_MANAGER | an active participant, including one that has left the case | — | Reject case ledger entry |
| a Participant checks that its ledger is current, such as after a restart, or holds a case but none of its entries | Read(OrderedCollection)[context=VulnerabilityCase] |
the CASE_MANAGER | a participant | — | Read case ledger |
Acknowledgment of the ledger is cumulative and implicit.
A participant whose local tail matches a received entry's previous-entry hash sends nothing, because the match is the acknowledgment.
On a mismatch it sends Reject(CaseLedgerEntry), and the CASE_MANAGER replays every entry after the last one the participant accepted.
A participant that wants to check its replica is current, after a restart for example, states its position with Read(<case>/ledger), a Read of the case's ledger stating the last entry it applied, and the CASE_MANAGER answers a lag the same way.
Whenever a participant states a position, the CASE_MANAGER also resends each Invite that participant still owes an answer to, as first sent, so an Invite lost before the participant could answer it reaches it again.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
MSM-05-002 |
MUST | Acknowledgement of replicated case-ledger state MUST be cumulative and implicit, through hash-chain continuity. A matching prev_log_hash already proves receipt of every prior entry, so per-message positive acknowledgement would be redundant. This is negative acknowledgement with gap-fill replay, structurally closer to a cumulative ACK or SACK scheme than to the formal per-message EK, CK and GK design. RK remains a real wire activity (MSM-01-008) because report submission is not ledger-replicated. |
|
MSM-05-007 |
MUST NOT | A receiver whose prev_log_hash matches its local tail MUST NOT emit an acknowledgement.The match already acknowledges every prior entry (MSM-05-002), so a positive acknowledgement would only add traffic. |
Refines: MSM-05-002 |
MSM-05-008 |
MUST | A receiver MUST emit Reject(CaseLedgerEntry) when an entry's prev_log_hash does not match its local tail. Its object is that entry and its inReplyTo the Add(CaseLedgerEntry) that carried it. The CASE_MANAGER then replays all entries after the last accepted hash.The mismatch is the one event the sender cannot see for itself. The Reject names where the receiver's chain ends, so the replay fills the gap. |
Extends: MSM-05-002 |
SYNC-17-001 |
MAY | A participant MAY send the case's CASE_MANAGER Read(<case>/ledger), whose object is the case's ledger <case>/ledger, an OrderedCollection named by its id and type, whose context is the case and whose ledgerPosition is the participant's tail in that ledger. A participant that holds no entry for the case states the empty ledger's position, index -1 with the case's genesis hash.ActivityStreams defines Read as the actor having read the object, so the activity states how far the sender has read the ledger. The CASE_MANAGER replays what follows, so a position behind its tail, or at -1, asks for a replay; one at its tail asks for nothing. A Reject(CaseLedgerEntry) would claim a refusal that did not happen, and naming the ledger rather than an entry gives every position, -1 included, one form with no bare object id (SE-01-006, ADR-0204). |
|
SYNC-17-004 |
MUST | When the stated position the CASE_MANAGER acts on (SYNC-17-002) is behind its tail, it MUST send the sender each later canonical entry, in log order. It sends them as Add(CaseLedgerEntry), under the replay rate bound (SYNC-15-003, SYNC-15-013) and outbox de-duplication (SYNC-15-012) of a Reject-triggered replay.This is the retry that SYNC-00-008 requires. It runs whenever the participant reads, so a lost last entry is recovered without waiting for a new commit. A Read can predate entries already on their way to the sender, so a stated lag can be transient; the replay rate bound, not the outbox de-duplication, is what limits the replays such a race causes. |
Implements: SYNC-00-008 Uses definition from: SYNC-15-003 Uses definition from: SYNC-15-012 Uses definition from: SYNC-15-013 See also: SYNC-17-002 — context for the reader |
SYNC-17-010 |
MUST | When the stated position the CASE_MANAGER acts on (SYNC-17-002) is its ledger tail, it MUST send nothing in answer. A participant at the tail is missing nothing, so any entry sent would be a duplicate. |
See also: SYNC-17-002 — context for the reader |
SYNC-20-001 |
MUST | When a participant on the case's roster that is not removed (CM-31-001) and whose closure is not recorded states a ledger position that names an entry in the CASE_MANAGER's ledger, in Read(<case>/ledger) (SYNC-17-001) or as an activity's ledgerPosition (SYNC-18-001), the CASE_MANAGER MUST resend each Invite that participant owes an answer to (SYNC-20-002), whether or not the participant is active (CM-10-004).A position statement is the first sign that the replica holds the case, so a resent Invite can now be answered (ADR-0163). The resend is not an answer to the position, so it runs apart from SYNC-17-002 and SYNC-18-007: a joiner that lost its Invite to the embargo in force has not consented, so it is inert, and is the one to ask again. A resent Invite was already sent and is not case content (CM-10-007), so nothing withheld leaks. |
Uses definition from: CM-10-004 Uses definition from: CM-31-001 Uses definition from: SYNC-17-001 Uses definition from: SYNC-18-001 Uses definition from: SYNC-20-002 |
4.13 Formal Message Set
The table below lists all 28 messages of the formal message set, each with the wire activities whose occasions carry it. It is generated from the same registry as the occasion tables above. A shorthand with no wire activity links to the section of the message reference that says why (§4.11 Faults and Acknowledgments).
5. Encoding and Transport [N]
This section specifies how a Vultron message is encoded and delivered. Where §4 Messages says what to send in each situation and what a received message means, this section says what a message looks like on the wire and how it reaches its addressee.
Vultron does not define its own message syntax. It uses ActivityStreams 2.0 (AS2), a published World Wide Web Consortium (W3C) vocabulary for describing things that actors do, and extends it with the object types of §4.3 Object Types. Reusing an existing vocabulary means the outer envelope is already specified, already tooled, and already understood by readers who have met it elsewhere.
The consequence is that Vultron messages look generic.
There is no ProposeEmbargo verb; there is an Invite whose object is an EmbargoEvent.
Meaning comes from the combination of verb, object and the fields that tell occasions apart, which is what the occasion tables of §4 Messages record.
5.1 Base Vocabulary
Every Vultron message is an AS2 Activity: an object describing an action, with the actor who performed it and the thing it was performed on.
Every Activity carries these fields:
| Field | Contains |
|---|---|
type |
The Activity type: the verb, such as Offer or Announce |
actor |
The Uniform Resource Identifier (URI) of the actor that performed the action |
object |
The thing acted on, inline or by reference (§5.2 Serialization) |
id |
A URI uniquely identifying this Activity, used for deduplication (§16.3 Replay and Idempotency) |
published |
The timestamp its sender stamps on the Activity |
The fields that tell occasions apart, such as target and context, are the bracketed fields of the Wire Activity Notation.
Vultron's own types are declared in the vocabulary namespace https://certcc.github.io/Vultron/ns.
A Vultron type that refines an AS2 type is sent with that AS2 type too, as the list ["<Vultron type>", "<AS2 type>"], so an AS2 receiver that does not know the Vultron type still reads the AS2 type.
A receiver reads a type list, in any order, as the most specific type it knows, and ignores a type name it does not know.
It refuses a list that names two known types when neither is a subtype of the other, because it cannot tell which one the sender meant.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
VM-03-005 |
MUST | A Vultron extension type can refine an ActivityStreams core type. A sender MUST write the type of such an extension as the list [extension type, core type], such as ["Refuse", "Reject"]. Inside the sender, the object still has only the extension type.The ActivityStreams Core extensibility guidance asks an extension type that overlaps a core type to carry the core type too. A plain ActivityStreams receiver that does not know the extension then still reads the message as the core type. Code that handles the message needs only one type: a list in code would change every type check for no gain (ADR-0196). |
|
VM-03-006 |
MUST | A receiver MUST read a type list, in any order, as the most specific type it knows, and ignore each term it does not know.ActivityStreams allows type to be a list, and VM-03-005 sends one. The most specific known type is the one the sender meant, and a term the receiver does not know is an extension it cannot read, so ["Foo", "Reject"] is a Reject (ADR-0196). |
Extends: VM-03-005 Refines: MV-01-001 |
VM-03-007 |
MUST | A receiver MUST refuse, as an unknown type, a received type list that names two known types when neither is a subtype of the other.When two known types are unrelated, the receiver cannot tell which one the sender meant, so it must not choose one (ADR-0196). |
Extends: VM-03-006 |
Every object an Activity embeds carries its own id too, at any depth, and a receiver refuses a message that embeds one without it.
An object inside a case preview is the exception: the preview shows what its sender chose, so the receiver reads such an object as sent, with or without its id or published (MV-12-006).
A Link, such as a Mention in tag, is not an object: it needs no id and names its resource by href.
Every whole object an Activity embeds, at any depth, also carries the published timestamp its author stamped on it, except an actor profile, a collection or an embargo consent row; a typed reference is not a whole object, and the case preview it may carry is a projection of the object it names.
A receiver refuses a message that embeds one without it, and names where the object sits.
An actor profile describes an actor and a collection is a container, so neither is an act made at a moment.
A case preview is a projection of the case, and a consent row is copied without a time, so neither needs one.
A typed reference, a URI and a Link are not whole objects, so they carry no time.
updated stays optional, and a receiver carries it as sent.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
MV-01-001 |
MUST | Incoming payloads MUST conform to ActivityStreams 2.0 structure Vultron messages are ActivityStreams 2.0 activities. Thus a payload that is not a correct AS2 activity has no defined meaning for the receiver. When the parser refuses the payload, the malformed input does not get to semantic extraction or to the handlers. These stages can then rely on the AS2 structure. |
|
OX-02-002 |
MUST | Each outbox activity MUST conform to ActivityStreams 2.0 structure Recipients are ActivityStreams 2.0 (AS2) and ActivityPub peers. A peer routes a body by its AS2 type, and it reads the terms of the body through @context. A body without that structure does not mean anything to the recipient. |
|
OID-01-001 |
MUST | All ActivityStreams object IDs MUST use full URI form ActivityPub requires every object it distributes to carry a publicly dereferenceable URI as its identifier, which a relative or bare identifier is not. ActivityStreams 2.0 alone only says relative references SHOULD NOT be used. Vultron inherits the ActivityPub rule. |
|
OID-01-013 |
MUST | A receiver MUST refuse a received message that embeds an ActivityStreams Object without an id, at any depth. A Link carries no such requirement, and neither does an object inside a preview (MV-12-006).ActivityPub requires every object it distributes to carry a unique global identifier. Its one exception, an intentionally transient object, does not fit case data that participants replicate and cite. OID-01-001 states the sender's side of that rule, and this states the receiver's. A Link is not an Object: AS2 names its resource by href. |
Refines: OID-01-001 |
OID-01-014 |
MUST NOT | A receiver MUST NOT mint an id for a received object or Link. A minted id would present the receiver's own invention as the sender's object, and it would differ on every receiver of the same message. A received Link that omits its id keeps none. An object or Link this process builds is still given a minted id (OID-01-004). |
Refines: OID-01-013 |
CLP-15-006 |
MUST | A participant MUST include a published timestamp on every protocol activity it emits.ActivityStreams makes published optional. Each check that reads the claimed time needs the sender's value (CLP-14-007, CLP-14-008), so a sender that omits it makes those checks impossible. |
|
CLP-15-008 |
MUST | A receiver MUST refuse at message validation, as malformed, an inbound activity that carries no published, never substituting its own clock for the missing value.A receiver that fills in the field cannot later tell a time the sender claimed from one it made. Each check that reads the claimed time then compares the receiver's clock with itself and never fires (CLP-14-007, CLP-14-008). A receiver that creates its own outbound activity stamps its own clock, which is correct. |
Extends: CLP-15-006 |
CLP-15-011 |
MUST | A receiver MUST refuse at message validation an inbound activity that carries, at any depth, a whole object with no published, naming the object's position. An actor profile, a collection and an EmbargoConsent row are exempt. A typed reference (MV-10-011), a URI and a Link are not whole objects, and a preview a typed reference carries is a projection of the object it names (ADR-0205), so the rule reaches none of them, nor any object inside such a preview (MV-12-006).A conformant sender states the time of every object it authors, so the rule refuses only malformed input. Refusing at the edge spares every reader of a received object's time a check of whether its type is one a decision needs, and lets core declare the time required (ADR-0032). An actor profile or a collection is not an act made at a moment, and many servers serve profiles without one. A case preview, a projection of the case it names, and a consent row are kept without a time by CM-17-010 and CM-23-044. |
Extends: CLP-15-007 See also: MV-10-011 — defines the typed reference the rule excludes; a scope boundary, not a dependency |
Vultron uses AS2 verbs rather than defining its own:
Create, Offer, Accept, Reject, TentativeReject, Announce, Update, Add, Remove, Invite, Read, Join, Leave, Ignore and Undo.
Because the verbs are generic, meaning often comes from nesting: an Activity whose object is itself an Activity.
Accepting an embargo is Accept(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]), an Accept whose object is the Invite being accepted, which in turn carries the embargo.
The nesting is what distinguishes accepting an embargo from accepting a report, Accept(Offer(VulnerabilityReport)).
This version uses the AS2 vocabulary, not full ActivityPub server behavior. Its conformance requirements do not include ActivityPub's inbox and outbox Hypertext Transfer Protocol (HTTP) delivery, WebFinger discovery or HTTP Signatures.
Informative: ActivityPub conformance is not required by this version
A future version is expected to raise the floor to ActivityPub; §1.3 Relationship to Existing Standards states the roadmap.
5.2 Serialization
Vultron messages are serialized as JavaScript Object Notation for Linked Data (JSON-LD). JSON-LD is JavaScript Object Notation (JSON) with a context that maps short names to full URIs. A message is therefore readable as ordinary JSON while remaining unambiguous about which vocabulary each term comes from.
An outbound message sets its top-level @context to a list of two URIs, in this order: the AS2 namespace, https://www.w3.org/ns/activitystreams, then the Vultron JSON-LD context document, https://certcc.github.io/Vultron/ns/context.jsonld.
The AS2 URI comes first so that an AS2 receiver that does not process JSON-LD still finds it, as AS2 requires producers to provide.
The Vultron context document declares every Vultron type name and the Vultron properties, each typed by its value kind as the AS2 context types its own: a link as "@type": "@id", a received document kept verbatim as "@type": "@json", and an ordered array, unordered array or IRI-keyed map with "@container" set to "@list", "@set" or "@index".
It also imports the AS2 namespace, but a receiver is not required to fetch it, so citing it alone would hide the AS2 reference from such a receiver.
An object nested in an activity does not restate the @context, because a JSON-LD context applies to every object inside the document that declares it.
An object a sender received from a peer and embeds as received keeps the @context it arrived with.
A receiver accepts a @context that is a single URI or a list of URIs.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
VM-10-001 |
MUST | Outbound Vultron wire messages MUST set the top-level @context to exactly the list ["https://www.w3.org/ns/activitystreams", "https://certcc.github.io/Vultron/ns/context.jsonld"], AS2 first, or, for a signed message (SIG-01-001), to exactly ["https://www.w3.org/ns/activitystreams", "https://certcc.github.io/Vultron/ns/context.jsonld", "https://w3id.org/security/data-integrity/v2"]: the data-integrity context is the third and final entry, and no other context is added.Derived from ADR-0069 (docs/adr/0069-vultron-namespace-uri.md). AS2 Core §2.1 asks every producer to reference the ActivityStreams namespace in @context, and an AS2 receiver that does not process JSON-LD, as most ActivityPub software does not, recognizes a message by finding that exact string. The Vultron context declares the CVD-specific types (VulnerabilityCase, EmbargoEvent, etc.) that the ActivityStreams namespace does not. The Vultron context document also imports AS2, but a receiver need not dereference it (VM-10-003), so citing the Vultron URI alone hides the AS2 reference from a plain-JSON receiver. |
Uses definition from: SIG-01-001 |
Timestamps have one written form. Every timestamp is an RFC 3339 date-time with an explicit offset, as AS2 requires. A Vultron node writes exactly six fractional-second digits, even when they are all zero, so one instant at one offset always has one string. The case ledger hashes and compares that text, so a second spelling would read as a different record. The fixed form is what a Vultron node writes, not what it requires to receive: a timestamp written with fewer digits still parses, and a peer may send one. A timestamp it carries from a peer keeps the offset that peer sent, so the same instant at another offset stays another string.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
CS-13-006 |
MUST | Wire-format datetime fields MUST serialize as RFC 3339 date-times with an explicit offset, so no naive or offset-free value reaches the wire. ActivityStreams 2.0 requires every date-time value to follow the RFC 3339 date-time form, in which the offset is mandatory. A peer cannot read a value without an offset as one instant, so it cannot compare it with other times. CS-13-005 holds Vultron's rules on which offset a timestamp carries. |
|
CS-13-007 |
MUST | Every datetime this node serializes MUST be written as an RFC 3339 date-time with exactly six fractional-second digits, whether or not its microseconds are zero. The case ledger hashes and compares timestamp text, so one instant at one offset needs one string. Whole seconds gave one string but made two acts one actor sends in the same second carry equal times; the fixed six-digit form keeps that one string and keeps the order. It fixes the fraction only: a carried timestamp keeps its own offset (CS-13-005, CLP-15-007), so the same instant at another offset is still another string. The form is what this node writes, not what it requires to receive: a peer may send whole seconds (ADR-0167). |
Refines: CS-13-006 — fixes the fractional-second digits of the RFC 3339 form Constrains: CLP-15-007 — A receiver carries a nested inbound timestamp as received, including at rendering, but writes its fractional digits in this node's one form. The instant and the offset are the peer's; the number of digits is not. |
CS-13-005 |
MUST | A wire timestamp this node generates MUST serialize with a UTC offset (Z or +00:00). A timestamp carried from a peer MUST serialize with the explicit offset it arrived with, which need not be UTC (CLP-15-007).UTC is the form every node can write without configuration. A carried timestamp is part of an activity that the case ledger records verbatim (CLP-07-011). A change from +05:00 to +00:00 keeps the instant but changes the offset, so replicas then hold different records. What this rule keeps is the offset value, not the spelling a peer chose for it: Z and +00:00 are one offset, and a carried Z serializes as +00:00 because that is the only form format_timestamp writes. This rule picks the offset only; CS-13-006 holds the separate rule that every wire timestamp has an explicit offset, and CS-13-007 fixes its fractional-second digits, which a carried timestamp takes like any other. |
Depends on: CLP-15-007 Refines: CS-13-006 — picks which explicit offset a wire timestamp carries |
A ledger entry hash covers one canonical form. A case ledger entry's hash is computed over the RFC 8785 JSON Canonicalization Scheme (JCS) serialization of the content it covers, its payload snapshot included. JCS fixes the key order, the form of each number and the escaping of each string, so a peer in any language hashes the same bytes for the same content. Every receiver recomputes the hash and refuses an entry whose content does not reproduce it (§10.4 Ledger Replication and Case Delivery).
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
SYNC-01-008 |
MUST | Not yet in the reference implementation (tracked by #3659) A CaseLedgerEntry's hash MUST be computed over the RFC 8785 (JCS) serialization of the content it covers, payload snapshot included.Every receiver recomputes an entry's hash and refuses a mismatch (SYNC-03-006, SYNC-03-012). A peer built in another language reproduces the hash only if the bytes it hashes are fixed by a published rule, not by one serializer's behavior. JCS is that rule: it fixes key order, number form and string escaping, and the signing cryptosuite already uses it (SIG-01-002). |
Extends: SYNC-01-003 |
The reference implementation does not hash the JCS form yet
The reference implementation hashes a sorted-key, compact JSON form that escapes non-ASCII text and writes numbers in Python's form, so it is not yet JCS. The requirement is listed in Known Gaps.
Objects travel inline or by reference. As AS2 allows, an Activity carries an object inline or names it by URI, and a receiver copes with either form. An object slot holds one of three forms, told apart by their keys alone (ADR-0198):
- A whole object carries any key beyond
id,typeandpreview, and the receiver validates it in full against its class. A whole object missing a field its class requires is refused, never read as a reference. - A typed reference is an inline object with exactly an
idand atype, and optionally apreview. It names an object of that type and claims nothing else about it. - A URI, or a
Linkthat carries one, names the object with no type.
A receiver routes an activity by a typed reference's type as it routes by a whole object's, but never reads the reference as the object.
A handler uses the object the receiver holds, or the receiver fetches the object first.
Only the case defines a preview: a case reference may carry the case stub, inline, as its preview (ADR-0205).
A typed reference that carries any other preview is refused, and the refusal names its position.
Inside a case preview, an object with only an id and a type, in a field that holds a case's objects, is read as that object shown by its id, not as a reference (MV-10-011).
A receiver reads a reference that carries a preview as received.
It never puts the object it holds in the reference's place, never fetches that object, and never seeds or updates a replica from it.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
MV-10-011 |
MUST | A receiver MUST read an inline object with exactly an id, a type and an optional preview as a typed reference of that type, unless the object sits inside a preview in a field that declares a loose form, which reads it as that form (MV-12-006). It routes the activity by the reference's type. It never reads the reference as the object: a handler uses the object the receiver holds, or fetches it (AKM-05-007), unless the reference carries a preview, which the receiver reads as received (MV-10-013).A bare URI carries no type, so a receiver must fetch the object before it can classify the activity. A typed reference lets it classify first and fetch only when a handler needs the content. The shape alone tells a reference from a whole object: any other key makes the object a whole object, which is refused when it fails its class (MV-04-003), so a broken object is never read as a reference (ADR-0198). |
Extends: MV-10-009 See also: AKM-05-007 — the fetch a handler relies on when the receiver lacks the object |
MV-10-012 |
MUST | A receiver MUST refuse a typed reference (MV-10-011) that carries a preview, naming its position, unless the protocol defines a preview for the reference's type and the preview is that preview, carried inline. The case is the one type with a defined preview: a case reference's preview is a CasePreview (CM-17-010).A preview is a limited view of an object for a recipient that may not hold it (ADR-0193), and what it may carry depends on the type. A preview of a type with no defined preview would be read by no rule, so it is refused rather than carried unchecked (ADR-0198). The case's preview is what an invitee decides on before it may see the case, so the stub Invite carries it (ADR-0205). Its recipient may not hold the case nor be entitled to fetch it, so a preview given by URI tells it nothing. |
Extends: MV-10-011 See also: CM-17-010 — the stub's contents, which are the case's preview |
MV-10-013 |
MUST NOT | A receiver MUST NOT read a typed reference that carries a preview (MV-10-012) as the object it names. It does not put the object it holds in the reference's place, does not fetch that object (AKM-05-007), and seeds or updates no replica from the reference (PCR-02-003). A preview is a limited view for a recipient not yet entitled to the object. The stub Invite and the full-case Invite both name the case and differ only in this form (ADR-0205). A CASE_MANAGER that expanded the reference into the case it holds would read an Accept of the stub Invite as an Accept of the full-case Invite. An invitee that fetched the case would ask for what it may not yet see. A replica built from a preview would be a hollow case. |
Extends: MV-10-011 See also: MV-10-012 — the previews a receiver accepts, which this rule reads as received See also: AKM-05-007 — the fetch this rule withholds for a previewed reference See also: PCR-02-003 — the replica a full case seeds and a preview never does |
An object the recipient cannot be expected to hold is carried inline, or named by a reference the recipient can dereference (§4.2 Knowledge Model and Actor Isolation). A production implementation can fetch an object named by a URI it holds no record of. The case-creation message that bootstraps a case is an exception: it carries the case and its participant records inline, and its receiver fetches none of them (§10.3 Case Bootstrap and the Trust Root).
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
SE-01-002 |
MUST | A receiver MUST cope with an object given either inline or as a URI reference, as ActivityStreams 2.0 allows. ActivityStreams 2.0 lets a sender give an object inline or by its URI, and conforming peers use both forms. If a receiver accepts only one form, it refuses or misreads correct messages from those peers. |
|
AKM-05-004 |
MUST | A production implementation MUST support object dereference (AKM-05-003). Given a URI it has not seen, it then fetches the object through an API call. A production deployment exchanges cases with independently built implementations, which may name objects by reference instead of inline. Without dereference it cannot process such an activity, and the refusals that stand in for dereference (AKM-05-003) would block legitimate traffic. |
Refines: AKM-05-003 |
How a case ledger entry records the objects of the activity it records is specified at §10.4 Ledger Replication and Case Delivery.
The reference implementation inlines every object
The reference implementation dereferences only a few references, so it carries every object inline and refuses a bare URI it cannot fetch where it needs the object.
The one exception is the case that a participant's Join, Ignore or Leave acts on, and the case of an ownership-transfer Offer: every receiver of these holds the case, so the activity names it by a typed reference, an inline object with only its id and type (ADR-0165).
That is a shortcut of the prototype, not a Vultron rule.
Provisional namespace URI
The namespace is currently hosted on GitHub Pages. A permanent URI may be registered in a future version (§15 IANA and Namespace Considerations).
5.3 Transport [N/I]
The transport moves a serialized message from one actor to another. The message schema of §5.1 Base Vocabulary and §5.2 Serialization is transport-agnostic: the same JSON payload is deliverable over any conformant transport.
An actor is identified by a URI, and that URI is also where it receives messages. Each actor exposes an inbox to receive Activities and an outbox from which it sends them. An actor's URI is its identity for every purpose in the protocol: there is no separate registry, and no name or hosting location carries authority (§2.2 Roles). Delivery is therefore inbox to inbox.
This version recognizes one required transport profile and describes a second that is anticipated.
REST (HTTP) profile [N]
This Representational State Transfer (REST) profile is the transport this version requires.
- Each actor exposes an inbox endpoint, named in its actor profile, that accepts inbound Activities.
- An outbound Activity is delivered by HTTP POST to the recipient's inbox.
- The POST names one of the two ActivityStreams media types as its
Content-Type:application/activity+json, orapplication/ld+jsonwith the ActivityStreams profile. An inbox accepts both and refuses any other media type, plainapplication/jsonincluded. - Authentication and authorization requirements are at §16 Security Considerations.
Requirements
| ID | Priority | Requirement | Related |
|---|---|---|---|
IE-02-001 |
MUST | The endpoint URL MUST be discoverable from actor profile ActivityPub requires every actor object to carry its inbox property, so a peer finds the endpoint from the profile rather than by a URL convention, which also leaves each deployment free to place it. |
|
IE-02-002 |
MUST | The endpoint MUST accept activities delivered to it by HTTP POST. ActivityPub delivers an activity to an inbox by HTTP POST. Vultron inherits the rule. That POST is the only method the inbox serves is this codebase's choice (IE-02-005). |
|
HTTP-01-004 |
MUST | A sender MUST deliver an activity to an inbox with Content-Type: application/activity+json or Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams".ActivityPub requires a POST to an inbox to use the ld+json ActivityStreams profile. Every Vultron inbox also accepts application/activity+json (HTTP-01-001, HTTP-01-002), so Vultron lets a sender use either form. That is looser than ActivityPub, so the rule is Vultron's own. A receiver that refuses other media types (HTTP-01-003) refuses plain application/json. |
Extends: HTTP-01-001 |
HTTP-01-001 |
MUST | Inbox endpoint MUST accept application/activity+json Content-TypeActivityPub only says a server SHOULD treat application/activity+json as equivalent to the JSON-LD media type it names for delivery (HTTP-01-002). Vultron makes that SHOULD a MUST, so the rule is Vultron's own, not inherited. |
|
HTTP-01-002 |
MUST | Inbox endpoint MUST accept application/ld+json; profile="https://www.w3.org/ns/activitystreams" Content-TypeThis is the media type ActivityPub names for delivery to an inbox. Vultron inherits the rule rather than defining it. |
|
HTTP-01-003 |
MUST | Not yet in the reference implementation (tracked by #4666) Inbox endpoint MUST reject requests with invalid Content-Type using HTTP 415 HTTP defines 415 Unsupported Media Type as the answer to a request whose content is in a format the target resource does not support. |
Implements: IE-03-001 |
The reference implementation's inbox accepts any media type
The reference implementation delivers with Content-Type: application/activity+json, but its inbox does not yet refuse other media types.
HTTP-01-003 is listed in Known Gaps.
Open question: which HTTP responses a receiving actor returns
This version does not say which HTTP status code a receiving actor returns when it refuses a message. For example, it does not say whether an invalid activity gets 422, an activity addressed only to other actors gets 400, or a message that cannot be decrypted gets 400.
One option is for the protocol to specify these responses, so that a sending actor can rely on them and act on them. The other is to leave them to each server implementation. A Vultron actor built on a stock ActivityPub server returns whatever that server returns, so a protocol rule could conflict with the server it runs on.
Until this is settled, these codes are recorded as the reference implementation's choices, not as protocol requirements. The codes that HTTP itself defines, such as 405 for an unsupported method and 413 for a body that is too large, are not part of this question.
ActivityPub federation profile [I]
Full ActivityPub conformance is not required by this version. The roadmap is at §1.3 Relationship to Existing Standards. Annex E Relationship to ActivityPub describes where Vultron follows ActivityPub conventions and where it diverges.
Participant discovery [I]
Before two actors can exchange messages, each needs to locate the other. WebFinger is the anticipated mechanism, consistent with its use alongside ActivityPub in federated systems. This version does not specify how an actor is found. Once an actor's profile is known, its inbox is the endpoint the profile names.
Transport is not routing
Which inbox a message may go to is a protocol rule, specified at §10.2 Routing Topology, and it applies whichever transport carries the message. The transport is responsible for getting a message to an inbox. The protocol is responsible for which inbox it may go to.
5.4 Worked Exchanges [I]
The exchanges below show occasions of §4 Messages as they appear on the wire.
Each one is given first in Wire Activity notation and then as the JSON a sender delivers.
The identifiers, timestamps and hashes are illustrative, and optional fields such as name and updated are left out.
Every activity carries the published timestamp its sender stamps on it (CLP-15-006), and so does every whole object it embeds other than the exempt kinds (CLP-15-011).
Submitting a report
A Finder submits a report to a Vendor, which acknowledges the submission with Report Acknowledgment (RK).
No case exists yet, so both messages go directly between the two actors.
| Step | Sender | Send to | Wire activity | Shorthand |
|---|---|---|---|---|
| 1 | Finder | Vendor | Offer(VulnerabilityReport) |
RS |
| 2 | Vendor | Finder | Read(Offer(VulnerabilityReport)) |
RK |
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Offer",
"id": "https://vultron.example/users/finndervul/activities/offer-1",
"published": "2026-05-30T10:00:00.000000+00:00",
"actor": "https://vultron.example/users/finndervul",
"to": ["https://vultron.example/organizations/vendorco"],
"object": {
"type": "VulnerabilityReport",
"id": "https://vultron.example/reports/FDR-8675309",
"published": "2026-05-30T09:30:00.000000+00:00",
"content": "I found a vulnerability!",
"attributedTo": "https://vultron.example/users/finndervul"
}
}
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Read",
"id": "https://vultron.example/organizations/vendorco/activities/read-1",
"published": "2026-05-30T11:00:00.000000+00:00",
"actor": "https://vultron.example/organizations/vendorco",
"to": ["https://vultron.example/users/finndervul"],
"content": "We have received the report. We will get back to you soon.",
"object": {
"type": "Offer",
"id": "https://vultron.example/users/finndervul/activities/offer-1",
"published": "2026-05-30T10:00:00.000000+00:00",
"actor": "https://vultron.example/users/finndervul",
"to": ["https://vultron.example/organizations/vendorco"],
"object": {
"type": "VulnerabilityReport",
"id": "https://vultron.example/reports/FDR-8675309",
"published": "2026-05-30T09:30:00.000000+00:00",
"content": "I found a vulnerability!",
"attributedTo": "https://vultron.example/users/finndervul"
}
}
}
Proposing and accepting an embargo
A Vendor proposes embargo terms for a case with no active embargo, Embargo Proposal (EP).
The CASE_MANAGER asks each other participant about the proposal, naming the proposer in attributedTo, the proposal in inReplyTo and the deadline for an answer in endTime.
A Coordinator agrees by accepting the Invite it received.
That answer is the Coordinator's own consent, so it carries no shorthand: Embargo Proposal Acceptance (EA) is the Case Owner's Add(EmbargoEvent)[target=VulnerabilityCase].
| Step | Sender | Send to | Wire activity | Shorthand |
|---|---|---|---|---|
| 1 | Vendor | the CASE_MANAGER | Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] |
EP |
| 2 | the CASE_MANAGER | Coordinator | Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase] |
— |
| 3 | Coordinator | the CASE_MANAGER | Accept(Invite(EmbargoEvent)[target=Actor, context=VulnerabilityCase]) |
— |
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Invite",
"id": "https://vultron.example/cases/1/embargo_proposals/1",
"published": "2026-06-01T18:00:00.000000+00:00",
"actor": "https://vultron.example/organizations/vendorco",
"to": ["https://vultron.example/case-actors/vendorco-case-actor"],
"context": "https://vultron.example/cases/1",
"summary": "We propose to embargo case 1 for 90 days.",
"object": {
"type": "EmbargoEvent",
"id": "https://vultron.example/cases/1/embargo_events/2026-08-30T00:00:00+00:00",
"published": "2026-06-01T18:00:00.000000+00:00",
"context": "https://vultron.example/cases/1",
"startTime": "2026-06-01T19:12:00.000000+00:00",
"endTime": "2026-08-30T00:00:00.000000+00:00"
}
}
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Invite",
"id": "https://vultron.example/cases/1/embargo_proposals/1/invites/coordinator",
"actor": "https://vultron.example/case-actors/vendorco-case-actor",
"attributedTo": "https://vultron.example/organizations/vendorco",
"inReplyTo": "https://vultron.example/cases/1/embargo_proposals/1",
"to": ["https://vultron.example/organizations/coordinator"],
"context": "https://vultron.example/cases/1",
"published": "2026-06-01T19:12:00.000000+00:00",
"endTime": "2026-06-08T19:12:00.000000+00:00",
"summary": "The vendor proposes to embargo case 1 for 90 days.",
"object": {
"type": "EmbargoEvent",
"id": "https://vultron.example/cases/1/embargo_events/2026-08-30T00:00:00+00:00",
"published": "2026-06-01T18:00:00.000000+00:00",
"context": "https://vultron.example/cases/1",
"startTime": "2026-06-01T19:12:00.000000+00:00",
"endTime": "2026-08-30T00:00:00.000000+00:00"
}
}
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Accept",
"id": "https://vultron.example/organizations/coordinator/activities/accept-1",
"published": "2026-06-02T09:00:00.000000+00:00",
"actor": "https://vultron.example/organizations/coordinator",
"to": ["https://vultron.example/case-actors/vendorco-case-actor"],
"context": "https://vultron.example/cases/1",
"object": {
"type": "Invite",
"id": "https://vultron.example/cases/1/embargo_proposals/1/invites/coordinator",
"actor": "https://vultron.example/case-actors/vendorco-case-actor",
"attributedTo": "https://vultron.example/organizations/vendorco",
"inReplyTo": "https://vultron.example/cases/1/embargo_proposals/1",
"to": ["https://vultron.example/organizations/coordinator"],
"context": "https://vultron.example/cases/1",
"published": "2026-06-01T19:12:00.000000+00:00",
"endTime": "2026-06-08T19:12:00.000000+00:00",
"object": {
"type": "EmbargoEvent",
"id": "https://vultron.example/cases/1/embargo_events/2026-08-30T00:00:00+00:00",
"published": "2026-06-01T18:00:00.000000+00:00",
"context": "https://vultron.example/cases/1",
"startTime": "2026-06-01T19:12:00.000000+00:00",
"endTime": "2026-08-30T00:00:00.000000+00:00"
}
}
}
Reporting a fix is ready
A Vendor reports that it has a fix ready, Fix Readiness (CF), as a claim in a new ParticipantStatus on its own participant record.
The vfState value VF is what distinguishes this occasion from the other claims that share the activity.
| Step | Sender | Send to | Wire activity | Shorthand |
|---|---|---|---|---|
| 1 | Vendor | the CASE_MANAGER | Add(ParticipantStatus, target=<participant>/statuses), with vfState VF |
CF |
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Add",
"id": "https://vultron.example/organizations/vendorco/activities/add-status-3",
"published": "2026-07-15T14:00:00.000000+00:00",
"actor": "https://vultron.example/organizations/vendorco",
"to": ["https://vultron.example/case-actors/vendorco-case-actor"],
"target": "https://vultron.example/cases/1/participants/vendorco",
"object": {
"type": "ParticipantStatus",
"id": "https://vultron.example/cases/1/participants/vendorco/status/3",
"published": "2026-07-15T14:00:00.000000+00:00",
"context": "https://vultron.example/cases/1",
"attributedTo": "https://vultron.example/organizations/vendorco",
"rmState": "ACCEPTED",
"vfState": "VF",
"caseEngagement": true,
"cvdRole": ["VENDOR"]
}
}
Replicating a ledger entry
The CASE_MANAGER has committed a case event to the case ledger and sends the entry to every active participant (§3.4 How the Dimensions Interact).
Each participant checks that the entry's prevLogHash matches the entryHash of the last entry it holds (§4.12 Ledger Replication Messages).
The entry shown is the first in its case's ledger, so its prevLogHash is the case's own genesis hash (CLP-08-001).
Its published is the CASE_MANAGER's commit stamp (CLP-14-002).
The two digests below are illustrative: they show the fields' shape and are not computed over the example's own values, so recomputing them from what is shown will not reproduce them.
| Step | Sender | Send to | Wire activity | Shorthand |
|---|---|---|---|---|
| 1 | the CASE_MANAGER | each participant | Add(CaseLedgerEntry) |
— |
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://certcc.github.io/Vultron/ns/context.jsonld"
],
"type": "Announce",
"id": "https://vultron.example/case-actors/vendorco-case-actor/activities/announce-0",
"published": "2026-05-31T12:00:01.000000+00:00",
"actor": "https://vultron.example/case-actors/vendorco-case-actor",
"to": ["https://vultron.example/organizations/coordinator"],
"object": {
"type": "CaseLedgerEntry",
"id": "https://vultron.example/cases/1/log/0",
"published": "2026-05-31T12:00:00.000000+00:00",
"caseId": "https://vultron.example/cases/1",
"logIndex": 0,
"logObjectId": "https://vultron.example/activities/00000000-0000-0000-0000-000000000001",
"semanticType": "create_case",
"payloadSnapshot": {},
"prevLogHash": "17334082900cbfad3b45787a0ef507390580bdf1508d78e3597435d79339ab3d",
"entryHash": "0dabc4e69c51c1fa7e30595ff3357fdcb1fbe4581aed3534bec1e92c30e84549",
"receivedAt": "2026-05-31T12:00:00.000000+00:00"
}
}