@openvtc/trust-tasks 0.19.3 → 0.19.4

package/CHANGELOG.md

@@ -11,6 +11,167 @@ The package versions over **its own API** — what a consumer compiles against
 not over `SPEC.md`. Below 1.0 a breaking change bumps the leading non-zero
 component.
 
+## 0.19.4 — 2026-09-11
+
+
+### Added
+
+- **vtc/vetting/vetters**: Vetter profile, listing and grant resend; manifest branding; ticket URI (#453)
+
+Applicants need to find vetters without the community publishing its vetters
+  by fiat. A grant still lists nobody; a vetter opts in.
+
+  vtc/vetting/vetters/profile/0.1 — vetter -> community. Replaces the sender's
+  whole profile: `listed` (required), `displayName?` (1-128), `languages` (0-16
+  BCP 47 tags, 2-35), `location?` ({ country alpha-2 upper case, region?,
+  city? }), `methods` (1-3 VettingMethod), `acceptsDocumentation` (0-16
+  VettingDocumentation), `availability?` (1-500), `contactHint?` (1-300),
+  `events` (0-32 of { name 1-200, startDate, endDate, location?, https url? }),
+  `ext?`. Returns `{ listed, updatedAt }`. Refuses a sender without a live vetter
+  grant, or not an active member, with `vtc/vetting/vetters/profile:notEligible`;
+  an event ending before it starts or more than 31 days after it with
+  `malformedRequest`. Idempotent replace; deleted when the grant is revoked or
+  the member leaves. issuedAt REQUIRED, proof RECOMMENDED.
+
+  vtc/vetting/vetters/list/0.1 — any identified applicant or member ->
+  community, read-only. Filters `language` (tag or `-` prefix), `country`,
+  `region`, `city`, `method`, `eventFrom`/`eventTo`/`eventName`, `limit`
+  (1-100, default 50), `cursor` (<= 512), `ext`. Returns `vetters`
+  (ListedVetter: vetterDid, displayName?, languages, location?, methods,
+  acceptsDocumentation, availability?, contactHint?, events with endDate >= today
+  UTC, grantValidUntil, updatedAt) and `nextCursor?`. Only active members with a
+  live grant and `listed: true`. States why the family has no `show`: a lookup by
+  DID would reveal unlisted vetters.
+
+  vtc/vetting/vetters/resend/0.1 — vetter -> community. Empty payload; the
+  community re-delivers the sender's live vetter role credential, unchanged, over
+  credential-exchange/issue and returns `{ credentialId, validUntil }`.
+  `vtc/vetting/vetters/resend:notGranted` when there is no live grant.
+
+  The shared profile pieces live in vtc/_shared/0.1/vetter-profile.
+
+  vtc/join-requests/manifest/0.2 — the response gains optional `branding`
+  (CommunityBranding: displayName 1-128, accentColor #rrggbb, https logoUrl
+  <= 2048, ext). Additive, outside every criterion, so no requirementsDigest
+  covers it. Example added.
+
+  vetting/request/0.1 — informative "Ticket URI" section for the QR payload:
+  vetting-ticket:?v=1&community=..&vetter=..&ticket=..&secret=.. or ..&code=..
+
+  vtc/vetting/vetters/grant/0.1 — links profile, list and resend; revoking a
+  grant deletes the profile; the consent text now says a grant alone lists
+  nobody. The identity-vetting ceremony relates vtc/vetting/vetters/list.
+
+  Rust and TS bindings regenerated.
+
+- **vtc/vetting/vetters**: Grant the vetter role, and pin the eligibility presentation (#452)
+
+Vetter eligibility is a community-issued role credential, and this adds the
+  task that issues it.
+
+  vtc/vetting/vetters/grant/0.1 — community administrator -> community, proof
+  REQUIRED. `{ memberDid, validitySeconds? (86400..=63072000) }` returns
+  `{ endorsementId, credentialId, validFrom, validUntil }`. The community issues
+  the member an EndorsementCredential whose endorsement is
+  `{ type: CommunityRole, role: vetter, communityDid }`, with a revocation
+  credentialStatus entry and 365 days' validity by default, and delivers it
+  over credential-exchange/issue. A member with a live grant gets that grant
+  back. Revocation is vtc/endorsements/revoke; removing a member revokes their
+  grants. Administrator capability only; `notMember` for a non-member.
+
+  vetting/request/0.1 — `eligibilityVp` is now a documented, still-optional
+  presentation: W3C v2 `@context` first, `VerifiablePresentation` type,
+  `holder` the vetter, `nonce` the request document id, `domain` the
+  applicant's joinDid, an `authentication` Data Integrity proof, and the
+  community's CommunityRole credential for the manifest's
+  eligibleVetters.role among its credentials. The applicant's check is
+  advisory; the community is authoritative.
+
+  vtc/join-requests/manifest/0.2 — `eligibleVetters.role` names the role in a
+  community-issued CommunityRole endorsement credential.
+
+- **vtc/vetting**: Withdraw a vetting statement, and the identity-vetting ceremony (#451)
+
+* feat(vetting): peer identity-vetting request, session and decline
+
+  A community that admits people on peer identity vetting needs its members
+  to check applicants before it decides: in person or on a call, against
+  whatever documentation each vetter accepts, ending in a signed statement
+  the applicant later submits. That exchange runs between two people's
+  agents, with no community service party to it, so it gets its own
+  top-level family.
+
+  - vetting/request/0.1 — applicant -> vetter. Carries the community, the
+    requirementsDigest being gathered for, the join DID (equal to the
+    issuer), and a ticket or an introduction. The response accepts with a
+    requestId and a presentation of the vetter's membership and role.
+    Refusals are trust-task-error codes; a wrong short ticket code gets no
+    reply at all, so guessing learns nothing.
+  - vetting/session/0.1 — vetter -> applicant, opened while the two are
+    together. Issues the challenge and required claims; the response is the
+    signed Vetting Card. The session document's id is the statement's
+    taskContext and its task digest binds it, mirroring witness/session. The
+    spoken match code is derived from that id so both agents compute it.
+  - vetting/decline/0.1 — vetter -> applicant, reason optional, never sent to
+    the community.
+
+- **vetting**: Peer identity-vetting request, session and decline (#450)
+
+* feat(vetting): peer identity-vetting request, session and decline
+
+  A community that admits people on peer identity vetting needs its members
+  to check applicants before it decides: in person or on a call, against
+  whatever documentation each vetter accepts, ending in a signed statement
+  the applicant later submits. That exchange runs between two people's
+  agents, with no community service party to it, so it gets its own
+  top-level family.
+
+  - vetting/request/0.1 — applicant -> vetter. Carries the community, the
+    requirementsDigest being gathered for, the join DID (equal to the
+    issuer), and a ticket or an introduction. The response accepts with a
+    requestId and a presentation of the vetter's membership and role.
+    Refusals are trust-task-error codes; a wrong short ticket code gets no
+    reply at all, so guessing learns nothing.
+  - vetting/session/0.1 — vetter -> applicant, opened while the two are
+    together. Issues the challenge and required claims; the response is the
+    signed Vetting Card. The session document's id is the statement's
+    taskContext and its task digest binds it, mirroring witness/session. The
+    spoken match code is derived from that id so both agents compute it.
+  - vetting/decline/0.1 — vetter -> applicant, reason optional, never sent to
+    the community.
+
+
+
+### Specifications
+
+- **vtc/join-requests/manifest**: Advertise identity-vetting requirements per criterion (#449)
+
+* spec(vtc/join-requests/manifest): advertise identity-vetting requirements per criterion
+
+  A community that admits people on peer identity vetting has to say what it
+  needs before anyone applies: how many statements, from distinct eligible
+  vetters, by which methods, with what independence. A presentation-definition
+  can ask for "credentials of type EndorsementCredential"; it cannot count
+  issuers, cap relationships, or require that an issuer holds a role.
+
+  0.2 adds an optional `vetting` object beside each criterion's
+  presentation-definition, and a `requirementsDigest` (JCS -> multihash ->
+  multibase over the criterion) that names one version of it, so an applicant
+  who started under older requirements can be evaluated under them within the
+  community's `requirementsGrace`.
+
+  Every number is community policy. The schema carries no defaults: an absent
+  member means no constraint of that kind. `acceptedDocumentClasses` is
+  optional and absent by default, because each vetter decides what
+  documentation they accept.
+
+  The shared vocabulary (method, document class, accepted documentation,
+  declared relationship) lands in `vetting/_shared/0.1`, so the manifest and
+  the vetting/* peer tasks that follow compare values rather than translate
+  them. Claim types reuse persona's `ClaimType` rather than redefining it.
+
+  0.1 is untouched.
+
 ## 0.19.3 — 2026-09-10
 
 

package/dist/_shared/components.d.ts

@@ -31,6 +31,10 @@ export type AnchorCadence = "never" | "renewal" | "manual";
  * The kind of privileged change recorded in the audit log.
  */
 export type AuditAction = "setAcl" | "accessListAdd" | "accessListRemove" | "accessListClear" | "accountAdd" | "accountRemove" | "accountChangeType" | "accountChangeQueueLimits" | "adminAdd" | "adminStrip";
+/**
+ * A calendar date, `YYYY-MM-DD` (RFC 3339 full-date), with no time or zone. Compared as a UTC date.
+ */
+export type CalendarDate = string;
 /**
  * Fine-grained capability flag scoped to the device's allowed contexts. See SPEC.md for the full semantics of each. Capability values are additive: a consumer MUST ignore a value it does not recognise rather than reject the binding, and MUST NOT treat an unrecognised value as conferring anything.
  */
@@ -55,6 +59,10 @@ export type ConsumerKind_DeviceV0_1 = Companion_DeviceV0_1 | Service_DeviceV0_1;
  * Discriminator: is this consumer a user-driven Companion or a headless Service?
  */
 export type ConsumerKind_DeviceV0_2 = Companion_DeviceV0_2 | Service_DeviceV0_2;
+/**
+ * An ISO 3166-1 alpha-2 country code, upper case, e.g. `DE`.
+ */
+export type CountryCode = string;
 /**
  * Stable identifier for an issued credential — the handle for revocation and audit. Opaque to the holder: it MUST be echoed verbatim when revoking and MUST NOT be parsed.
  */
@@ -158,10 +166,18 @@ export type KeyType = "ed25519" | "x25519" | "p256";
  * The interaction kind: a 1:1 direct message, a multi-party group, or a broadcast channel.
  */
 export type Kind = "dm" | "group" | "channel";
+/**
+ * A BCP 47 language tag, e.g. `en`, `de-AT`. Compared case-insensitively.
+ */
+export type LanguageTag = string;
 /**
  * Scopes one application's records within a context, so several tools can share a context without colliding — `openvtc`, `cnm`, an agent runtime. The maintainer MUST NOT interpret the value; it is an opaque partition name. Namespaces are first-come and unreserved, so an application SHOULD pick a stable, specific one: a future per-namespace ACL would grant on this exact string, which makes renaming a namespace a migration rather than an edit.
  */
 export type Namespace = string;
+/**
+ * A region or city name as the vetter writes it. Compared case-insensitively and otherwise exactly.
+ */
+export type PlaceName = string;
 /**
  * One line of a profile, in exactly one of four forms. Together they are the whole of a profile's flexibility, and each exists for a case the others handle badly.
  *
@@ -400,6 +416,175 @@ export type Version_PersonaV0_1 = number;
  * A value of the namespace's monotonic write counter (see this schema's description). Server-assigned; a producer never chooses one.
  */
 export type Version_VtaV0_1 = number;
+/**
+ * What documentation the vetter relies on, in the same tokens as vetting/request's `acceptsDocumentation` — `passport`, `nationalId`, `driverLicence`, `none`, or another lowerCamelCase class. The vetter's own choice; empty says nothing either way.
+ *
+ * @maxItems 16
+ */
+export type VetterAcceptsDocumentation = [] | [VettingDocumentation] | [VettingDocumentation, VettingDocumentation] | [VettingDocumentation, VettingDocumentation, VettingDocumentation] | [VettingDocumentation, VettingDocumentation, VettingDocumentation, VettingDocumentation] | [VettingDocumentation, VettingDocumentation, VettingDocumentation, VettingDocumentation, VettingDocumentation] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+] | [
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation,
+    VettingDocumentation
+];
+/**
+ * Vetter-authored free text on when they are available to vet. Attributed to the vetter.
+ */
+export type VetterAvailability = string;
+/**
+ * Vetter-authored free text on how to obtain a ticket from them, e.g. `Find me at the OpenVTC booth`. A hint, not an address a request can be sent to: vetting/request still needs a ticket or an introduction the vetter accepts.
+ */
+export type VetterContactHint = string;
+/**
+ * The name the vetter chooses to be listed under. Self-asserted and unverified: it is not the name on any document, and a client MUST attribute it to the vetter.
+ */
+export type VetterDisplayName = string;
+/**
+ * The methods the vetter offers, from `inPerson`, `video`, `priorAcquaintance`.
+ *
+ * @minItems 1
+ * @maxItems 3
+ */
+export type VetterMethods = [VettingMethod] | [VettingMethod, VettingMethod] | [VettingMethod, VettingMethod, VettingMethod];
+/**
+ * A class of documentation, named in lowerCamelCase. Open rather than enumerated, because what documentation a vetter accepts is each vetter's own choice. Well-known values: `passport`, `nationalId`, `driverLicence`, and `none` — the vetter will attest without a document, which is the `priorAcquaintance` case. Only the class ever travels — never a document number, an image, an issuing authority or an expiry date. `none` states a policy (what a vetter accepts); a record of what was relied on expresses 'no document' as an empty list instead.
+ */
+export type VettingDocumentation = string;
+/**
+ * How the vetter established that the person they checked is the person controlling the applicant's DID. `inPerson` — both people were physically together. `video` — a live, two-way video call. `priorAcquaintance` — the vetter has known or worked with this person over a period, and attests from that knowledge rather than from a document. A method is a description of what happened, not an assurance level: which methods count, and how many of each, is community policy.
+ */
+export type VettingMethod = "inPerson" | "video" | "priorAcquaintance";
+/**
+ * The vetter's own declaration of how they relate to the applicant. Declared, not verified: it exists so community policy can cap how much evidence comes from people close to the applicant, and a false declaration is the vetter's attributable act.
+ */
+export type VettingRelationship = "none" | "communityColleague" | "sameEmployer" | "family" | "otherPersonal";
 /**
  * A Verifiable Identifier (SPEC §4.8). For a mediator-served account this is the account's controlling DID, carried verbatim and compared by exact string equality. For privacy — and because some mediators key accounts by a one-way hash and never hold the full DID — a stable hash of the DID (e.g. its SHA-256 digest) is an equally valid value here: producer and consumer simply agree on the same opaque identifier and compare by exact string equality. The field carries whichever form the issuing mediator uses.
  */
@@ -1293,6 +1478,23 @@ export interface CredentialReference {
      */
     expiresAt?: string | null;
 }
+/**
+ * A W3C Data Integrity proof by the card's publisher. Additional Data Integrity members (e.g. `created`) are permitted and are covered as the cryptosuite defines.
+ */
+export interface DataIntegrityProof {
+    type: "DataIntegrityProof";
+    /**
+     * e.g. `eddsa-jcs-2022`.
+     */
+    cryptosuite: string;
+    /**
+     * A verification method of `publisher`, authorized for `assertionMethod`.
+     */
+    verificationMethod: string;
+    proofPurpose: "assertionMethod";
+    proofValue: string;
+    [k: string]: unknown | undefined;
+}
 /**
  * One presentation request awaiting the holder's decision, as the approver sees it.
  *
@@ -3548,6 +3750,102 @@ export interface VerdictWith {
      */
     presentationDefinition?: {};
 }
+/**
+ * An event the vetter will attend and vet at. `endDate` is on or after `startDate` and no more than 31 days after it; JSON Schema cannot compare two members, so the community checks both and refuses a violation with `malformedRequest`.
+ */
+export interface VetterEvent {
+    /**
+     * The event's name, e.g. `Linux Plumbers Conference 2026`.
+     */
+    name: string;
+    startDate: CalendarDate;
+    endDate: CalendarDate;
+    location?: VetterLocation;
+    /**
+     * OPTIONAL. The event's own https page.
+     */
+    url?: string;
+}
+/**
+ * Where a vetter can meet people, as coarse as the vetter chooses: a country, optionally a region, optionally a city. Never a street address.
+ */
+export interface VetterLocation {
+    country: CountryCode;
+    region?: PlaceName;
+    city?: PlaceName;
+}
+export interface VettingCard {
+    /**
+     * Exactly `VerifiableDataStructure`, `RelationshipCard` and `VettingCard`, in any order.
+     *
+     * @minItems 3
+     * @maxItems 3
+     */
+    type: [
+        "VerifiableDataStructure" | "RelationshipCard" | "VettingCard",
+        "VerifiableDataStructure" | "RelationshipCard" | "VettingCard",
+        "VerifiableDataStructure" | "RelationshipCard" | "VettingCard"
+    ];
+    /**
+     * Fresh per card. A card is never re-sent to a second session under the same id.
+     */
+    id: string;
+    /**
+     * The applicant's DID — the issuer of the vetting request and the subject every resulting statement names. The card is signed with this DID's assertion key.
+     */
+    publisher: string;
+    cardVersion: number;
+    /**
+     * The vetter's DID — the issuer of the vetting session. A card addressed to anyone else is refused.
+     */
+    audience: string;
+    /**
+     * The community the applicant is being vetted for.
+     */
+    community: string;
+    /**
+     * The session's challenge, copied verbatim.
+     */
+    challenge: string;
+    /**
+     * The session's domain, copied verbatim.
+     */
+    domain: string;
+    issuedAt: string;
+    /**
+     * No later than the session's `expiresAt`.
+     */
+    expiresAt: string;
+    /**
+     * @minItems 1
+     */
+    claims: [VettingCardClaim, ...VettingCardClaim[]];
+    /**
+     * digestMultibase over the RFC 8785 canonicalization of `{ "salt": commitmentSalt, "claims": R }`, where R is `{ "type", "value" }` for every card claim whose type the session lists in `requiredClaims`, ordered by `type` then `value` (code-point order). SHA-256 RECOMMENDED. Because the applicant uses one salt per application, every vetter of that application sees the same value.
+     */
+    identityCommitment: DigestMultibase;
+    /**
+     * 32 random bytes, base64url without padding, generated once per application. Goes to vetters inside the card and to nobody else: a party holding the commitment without the salt cannot test guesses at the claimed name.
+     */
+    commitmentSalt: string;
+    proof: DataIntegrityProof;
+}
+export interface VettingCardClaim {
+    /**
+     * The claim type. `person.portrait` is refused: identity vetting works by a vetter looking at the person, not by transmitting their image.
+     */
+    type: ClaimType;
+    /**
+     * The claimed value, exactly as rendered from the applicant's persona — a string for most claim types, structured JSON for some (e.g. a postal address). Authored by the applicant and asserted under their signature; the vetter's check is what gives it any assurance.
+     */
+    value: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Where the value's assurance comes from. `selfAsserted` — the applicant says so, and the vetter's human check is the only assurance added — is the only value this version defines; a verifier MUST NOT treat any other value as adding assurance it does not understand.
+     */
+    provenance: string;
+}
 /**
  * An opaque, gateway-issued reference to a device's push channel (push wake-up binding, https://trusttasks.org/binding/push/0.1). The push gateway returns it to the device at registration; the device conveys it to its VTA (device/set-wake), and the VTA provisions it to authorized triggers (its mediator and/or itself). The raw platform push token (APNs/FCM/WebPush) is held ONLY by the gateway and is never represented here — the handle abstracts the platform, so adding new push methods (e.g. PWA Web Push) needs no change to triggers or VTA config. A handle is a bearer capability to *request* a wake (subject to the gateway's allowlist), never to read the channel.
  */