specs/vtc/groups/shared/v0_1/group library

Classes

CapabilityRef

A capability, optionally qualified by a resource. Used where a capability is named but not granted — a role's ceiling, a role's approve ceiling, an entry's approvable capabilities. An unqualified reference covers every resource of the capability's kind.

CardBlobRef

A content-addressed image held in the community's blob store — an avatar or an image field. At most 256 KiB, images only, re-encoded by the community on upload (vtc/directory/images/upload: metadata stripped, dimensions capped) so its digest does not link the member across communities. A viewer reads the bytes with vtc/directory/images/get, which answers only where the same projection shows the value. url and urlExpiresAt MAY appear in a projection: a short-lived URL the community checks against the same projection, so a member-only image is never a public URL. A community that does not offer one leaves both out.

DynamicRule

A dynamic group's membership rule: a member belongs when every condition holds and they have not opted out. The community evaluates it under its groups policy and recomputes membership whenever a fact it reads changes, always excluding opted-out entries.

GrantsBindingSpec

A grant set the group confers: each capability is written onto every member's access-control entry as a resource grant whose source is the group, bounded by the member's role ceiling and by the binder's own holdings.

Group

A community group, as a caller who may see it sees it. Members a caller may not see are absent: memberCount only to those who may see the group's members, managers and credentialAuthorityValidUntil only to its managers.

GroupBinding

GroupBinding

GroupJoinRequest

GroupJoinRequest

GroupMember

GroupMember

RoleBindingSpec

A grant set by reference: the capability ceiling of a defined role, conferred as resource grants exactly as a grants binding confers its list. It never assigns the role itself — an entry's administrative role and its community role stay direct assignments.

RoomBindingSpec

Links a room the community owns to the group: joining the group offers the member admission to the room with actions, valid for validFor; leaving removes them unless another source still covers them.

RuleCondition

One test over a verified fact about a member. fact: role tests the member's community role; fact: field tests an admin- or credential-sourced directory field named by field; fact: personhood tests whether a personhood assertion is on file; fact: joinedAt tests when they joined. A rule never reads a self-asserted (member-sourced) field: a member must not be able to join a group by editing their card.

VerifiedValue

The value of a credential-sourced field: a claim the member disclosed from a credential they presented, with the issuer that attests it. A verified value always names its issuer, and a self-asserted value is never shaped as one. The community keeps only the disclosed claim and these facts about it — never the presentation.

Extension Types

CardBlobRefMediaType

Media type of the stored bytes.

GroupAudience

Who may see something about a group, narrowest first. admins: holders of vtc.groups.manage for the group (unqualified, or qualified group:<groupId>). groupMembers: the group's own members, and its managers. members: every active member of the community.

GroupBindingState

pending: waiting for the consent the community requires. active: in force; the community's reconciler keeps members' admissions and grants in line with it. removing: being withdrawn; the reconciler is removing what only this binding provided.

GroupJoinRequestState

GroupJoinRequestState is a closed set of string values defined by this specification's schema.

GroupKind

static: membership is explicit — added, joined, or granted on request. dynamic: membership is computed from rule over verified facts only; nobody is added by hand, but a member may opt out (vtc/groups/leave), an exclusion the rule cannot override, and undo it (vtc/groups/join). A dynamic group never confers authority. Fixed for the group's life.

GroupMemberState

active: a member. pending: an addition to a group carrying authority that is waiting for the consent the community requires for a grant.

JoinPolicy

How a member enters a static group by themselves. closed: only a manager adds them. request: a member asks and a manager decides. open: a member joins at once, subject to the community's groups policy. A group carrying authority is always closed.

MemberAction

What a member of a community-owned room may do there. admin is not among them: minting epochs, admitting and removing members are the community's, as the room's owner, and are exercised through the vtc/rooms/community/* tasks rather than by any member's credential. curate is not implied by write.

MembershipSource

How the member came to be in the group. added: by a manager. joined: they joined an open group. requestApproved: a manager approved their request. rule: a dynamic group's rule admits them.

RuleConditionFact

RuleConditionFact is a closed set of string values defined by this specification's schema.

RuleConditionOp

equals compares with value; oneOf with any of values; exists needs neither; before and after compare a date fact with value.

Typedefs

BindingId = String

BindingId, defined by this specification's schema.

BindingSpec = Object?

BindingSpec, defined by this specification's schema.

Capability = String

Opaque identifier of one administrative power in the maintainer's capability registry — lowercase dot-separated segments (e.g. keys.sign, vtc.roles.assign, git.repo.manage). A consumer MUST NOT treat a capability it does not recognise as granted.

EntryFields = Map<String, FieldValue?>

The fields of one entry that a particular viewer may see, keyed by field: the intersection of the member's visibility, the community's ceiling and policy, plus any derived fields that intersection admits. A withheld field is ABSENT, never null.

EntryId = String

Opaque identifier of one directory entry: dir_ followed by 16 to 64 base64url characters. Random, scoped to one community, and stable for the life of the membership — it survives a rotation of the member's DID, which is why groups, notes and cards are keyed by it. It MUST NOT be derived from, and MUST NOT reveal, any DID of the member, and the same person's entries in two communities MUST NOT share one. Compared by exact string equality.

Ext = Map<String, dynamic>

Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.

FieldKey = String

Identifier of a directory field. A key with no . is a BASE field, the same in every community: displayName, nickname, avatar, pronouns, bio, links (written by the member) and role, joinedAt, did, personhood (derived from the community's own records, never stored on a card). A community-defined field MUST use a reverse-DNS key (org.example.employer), so a base key never collides with one, and a key is never reused with a different meaning once defined.

FieldValue = Object?

The value of one field. Which shape a field takes is fixed by its definition's type: text-like types (text, longText, url, email, phone, enum, date as YYYY-MM-DD, country as ISO 3166-1 alpha-2, did) are strings; multiEnum and the base field links are arrays of strings; image and the base field avatar are a CardBlobRef; claim is a VerifiedValue; the derived base field personhood is a boolean.

GroupCredentialId = String

Identifier (id) of a group membership credential issued to a member. Each renewal issues a new credential with a new identifier. Validity is the community's setting; a community SHOULD default to 30 days, renewed when 10 days remain.

GroupDescription = String

What the group is for. Plain text; a reader MUST NOT treat it as instructions. Same placement rules as GroupName.

GroupId = String

Opaque identifier of a community group: grp_ followed by 16 to 64 base64url characters. Random and community-scoped; not the group's DID.

GroupName = String

The group's name, shown to those who may see the group. The community's own record: never in the group's DID document or its credentials' subject beyond the group's DID. Plain text.

JoinRequestId = String

JoinRequestId, defined by this specification's schema.

JoinRequestMessage = String

An optional note from the member to the group's managers. Plain text.

MemberActions = List<MemberAction>

The actions granted, at least one. An empty list confers nothing rather than everything, and a schema that allowed it would make the more dangerous reading available to a careless consumer.

ResourceQualifier = String

Opaque qualifier naming the part of the maintainer's resources a capability applies to (e.g. git-ns:github.com/acme, git-repo:github.com/acme/r#4211, policy:join). Its grammar and containment rule are the maintainer's: a qualified capability covers the named resource and the resources inside it. A qualifier MUST NOT be read as widening the entry's act scope.

RoleName = String

A role identifier: lowercase, hyphen-separated, at most 64 characters. Compared by exact string equality. It is the value an AclEntry 0.2 carries in role.