@openvtc/trust-tasks 0.28.18 → 0.28.19

package/CHANGELOG.md

@@ -11,6 +11,38 @@ 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.28.19 — 2026-11-06
+
+
+### Added
+
+- **vtc/badges**: Member badges — community badges backed by groups, awards accepted by the member, kudos, Open Badges credentials (vtc/badges/*/0.1) (#1052)
+
+* feat(vtc/badges): member badges — community badges backed by groups, awards accepted by the member, kudos, Open Badges credentials (vtc/badges/*/0.1)
+
+  A new family for the VTI Community Badges chapter (VTI-BDG-001 – 095): pictures
+  with a name a member earns, holds and shows on their directory card.
+
+  - A community badge is backed by a community group: `create` creates the group
+    as vtc/groups/create does, its managers are the badge's owners, its members
+    the holders; requests reuse vtc/groups/join and requests/decide, owners reuse
+    managers/add and remove. The shared Group record gains an optional `badgeId`
+    (additive).
+  - An award is an offer until its recipient accepts (awards/offer → mine/accept
+    or mine/decline); mine/accept issues the badge credential as the group's DID
+    first and records the membership after. mine/accept states the credential
+    profile: an Open Badges 3.0 OpenBadgeCredential with the community as the
+    Achievement's creator and endorser, one evidence entry per award; short-lived
+    with no status inside the community, long-lived with a slot in the community's
+    own status set where holders may show it outside.
+  - Hidden is portal-only (mine/hide, mine/show): walls, holders/list and counts
+    leave a hidden holder out; awards/list shows owners the hidden mark.
+  - Kudos badges (kudos/give, kudos/list): given by any member to any other within
+    per-giver limits, each giving an award of its own; promote turns one into a
+    community badge.
+  - settings/show and settings/update hold the community's switches and limits.
+  - images/upload and images/get mirror the directory's picture pipeline.
+
 ## 0.28.18 — 2026-11-05
 
 

package/dist/_shared/components.d.ts

@@ -385,12 +385,48 @@ export type AuthModel = "aws-roles-anywhere" | "gcp-wif-pinned" | "azure-cert" |
  * An explicit authority scope — used for both the act scope and the approve scope of an entry. Exactly one of three shapes, discriminated by `scope`: `all`, `none`, or `contexts` with a NON-EMPTY list. The empty list is not a fourth shape: it is invalid, so a serializer that drops or empties the list produces a document that fails validation rather than one that silently means something else.
  */
 export type AuthorityScope = AuthorityScopeAll | AuthorityScopeNone | AuthorityScopeContexts;
+/**
+ * Opaque identifier of one giving of a badge to one member: `awd_` followed by 16 to 64 base64url characters. Random and unique within the community.
+ */
+export type AwardId = string;
+/**
+ * What the award is for, from the giver, shown to the recipient and written as the award's evidence narrative where the badge carries a credential. Plain text; erased with its author (VTI-BDG-090).
+ */
+export type AwardNote = string;
+/**
+ * `offered`: waiting for the recipient. `accepted`: the recipient took it; for a community badge the credential was issued and the membership recorded. `declined`: the recipient declined; nothing was recorded in the group and nothing issued. `withdrawn`: the giver withdrew the offer before a decision. `expired`: the offer lapsed unanswered. `revoked`: taken back after acceptance (VTI-BDG-023).
+ */
+export type AwardState = "offered" | "accepted" | "declined" | "withdrawn" | "expired" | "revoked";
 export type AwsArn = string;
 export type AwsRegion = string;
 /**
  * The ARN of an AWS IAM role, in any AWS partition (`arn:aws:`, `arn:aws-cn:`, `arn:aws-us-gov:`). Validated here because the community passes it to STS AssumeRole and derives the partition of the session policy's resources from it; it must never carry anything but a role ARN.
  */
 export type AwsRoleArn = string;
+/**
+ * How the badge is earned, shown to members and written into the credential's Achievement as its criteria narrative. Plain text.
+ */
+export type BadgeCriteria = string;
+/**
+ * What the badge is for. Plain text; a reader MUST NOT treat it as instructions.
+ */
+export type BadgeDescription = string;
+/**
+ * Opaque identifier of a badge: `bdg_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BDG-001).
+ */
+export type BadgeId = string;
+/**
+ * `community`: defined by holders of `vtc.badges.admin`, given by its owners (its badge group's managers), may carry a credential. `kudos`: made by a member the community's badge settings admit, given by any active member to any other, never a credential. Fixed for the badge's life; a kudos badge becomes a community badge only by promotion (vtc/badges/promote).
+ */
+export type BadgeKind = "community" | "kudos";
+/**
+ * The badge's name, shown on the wall and written into the credential's Achievement. Plain text; a reader MUST NOT treat it as instructions.
+ */
+export type BadgeName = string;
+/**
+ * `active`: may be given and shown. `retired`: kept for its holders' own history, never given, never shown to members who do not hold it (VTI-BDG-005).
+ */
+export type BadgeState = "active" | "retired";
 export type BindingId = string;
 export type BindingSpec = RoomBindingSpec | GrantsBindingSpec | RoleBindingSpec;
 /**
@@ -2201,6 +2237,10 @@ export type Vid = string;
  * How much of a room its host can see, fixed at creation and immutable thereafter. `open`: records are cleartext, searchable and fully audited. `attributed`: record content is sealed, and the host still learns which member acted. `private`: content is sealed and membership is presented in zero knowledge, so the host verifies that a member acted without learning which. Immutable because a downgrade cannot un-see cleartext and an upgrade would protect only what came after while presenting as though it protected everything.
  */
 export type Visibility = "open" | "attributed" | "private";
+/**
+ * Who sees a member's badges, the member's own setting (VTI-BDG-031). `members`: every active member the directory shows their card to. `nobody`: no one but the member. Never wider than the directory shows the card.
+ */
+export type WallVisibility = "members" | "nobody";
 /**
  * A file's content hash: the lowercase hex SHA-256 of its bytes — the `etag` vtc/website/files/list reports, and the `ETag` a direct read of the path returns, without the HTTP quotes.
  */
@@ -5521,6 +5561,31 @@ export interface AutoGrantSweep {
      */
     errors: number;
 }
+/**
+ * One giving of a badge to one member. `givenBy` is the giver's directory entry, absent for an award a dynamic badge group's rule made. `note` is shown to the recipient, the giver, the badge's owners and administrators, never to other members. `credentialId` is present on an accepted award of a community badge: the badge credential that evidences it, renewed or re-issued as the badge's regime requires.
+ */
+export interface Award {
+    awardId: AwardId;
+    badgeId: BadgeId;
+    /**
+     * The recipient.
+     */
+    entryId: EntryId;
+    givenBy?: EntryId;
+    note?: AwardNote;
+    state: AwardState;
+    offeredAt: string;
+    /**
+     * When the recipient accepted or declined, the giver withdrew, the offer expired, or the award was revoked.
+     */
+    decidedAt?: string;
+    /**
+     * When an unanswered offer lapses, where the community expires offers.
+     */
+    expiresAt?: string;
+    credentialId?: GroupCredentialId;
+    ext?: Ext;
+}
 /**
  * Unencrypted metadata plus the encrypted payload. The KDF and cipher parameters travel in the clear so a reader can decrypt without knowing this specification's defaults.
  */
@@ -5556,6 +5621,108 @@ export interface BackupEnvelope {
      */
     ciphertext: string;
 }
+/**
+ * A badge as a caller who may see it sees it. `groupId` is present exactly when `kind` is `community`. `holderCount` only to callers who may see the badge's holders, counted over holders who have not hidden it (VTI-BDG-030, VTI-BDG-033). `createdBy` is the directory entry of the administrator or member who made it, where they have one.
+ */
+export interface Badge {
+    badgeId: BadgeId;
+    kind: BadgeKind;
+    name: BadgeName;
+    description: BadgeDescription;
+    criteria?: BadgeCriteria;
+    /**
+     * The badge's picture, re-encoded and stored by the community (vtc/badges/images/upload), read with vtc/badges/images/get. `url` and `urlExpiresAt` MAY appear in a projection as for a card picture; for a badge whose holders may show it outside, `url` MAY be the picture's stable public location.
+     */
+    image: CardBlobRef;
+    /**
+     * Whether one member may hold the badge more than once, each giving an award of its own (VTI-BDG-022). Always true for a kudos badge.
+     */
+    repeatable: boolean;
+    /**
+     * Community badges only. Whether a member may ask for it: a request to join its badge group, decided by its owners (VTI-BDG-014). Absent reads as false.
+     */
+    requestable?: boolean;
+    /**
+     * Whether members who do not hold the badge see it in the community's badge list. An unlisted badge is seen by its holders, its owners and administrators.
+     */
+    listed: boolean;
+    /**
+     * Community badges only. Whether its holders may show it outside the community, which decides the credential's regime: short-lived and renewed with no status when false, long-lived with a status in the community's own status set when true (VTI-BDG-061, VTI-BDG-062). Absent reads as false.
+     */
+    shareableOutside?: boolean;
+    /**
+     * The badge group that backs a community badge: its managers are the badge's owners, its members the holders, its DID the credential's issuer.
+     */
+    groupId?: GroupId;
+    state: BadgeState;
+    /**
+     * Holders who show the badge. Only to callers who may see the holders.
+     */
+    holderCount?: number;
+    createdAt: string;
+    createdBy?: EntryId;
+    updatedAt?: string;
+    retiredAt?: string;
+    /**
+     * Ecosystem-defined extension members per SPEC.md §4.5.1. An extension member MUST NOT carry authority.
+     */
+    ext?: Ext;
+}
+/**
+ * The community's bounds (VTI-BDG-032, VTI-BDG-040). Each has a default a community that states none applies.
+ */
+export interface BadgeLimits {
+    /**
+     * Kudos one member may give in a day. Default 10.
+     */
+    kudosPerGiverPerDay?: number;
+    /**
+     * How often the same member may give a kudos badge to the same member: at most once a day, once a week, or without bound. Default `day`.
+     */
+    sameGiverSameMember?: "day" | "week" | "unbounded";
+    /**
+     * Days of membership before a member may give kudos or make a kudos badge. Default 7.
+     */
+    minTenureDays?: number;
+    /**
+     * Kudos badges one member may make in a calendar month. Default 5.
+     */
+    kudosBadgesPerMakerPerMonth?: number;
+    /**
+     * Badges a member may pin beside their name. Default 2.
+     */
+    maxPinned?: number;
+    /**
+     * Days an unanswered offer stands before it expires. Absent: offers do not expire.
+     */
+    offerExpiresAfterDays?: number;
+}
+/**
+ * The community's badge settings (VTI-BDG-004). `enabled` false hides every badge surface and keeps every record; nothing is given or issued while it is false.
+ */
+export interface BadgeSettings {
+    enabled: boolean;
+    kudosMakers: KudosMakers;
+    limits?: BadgeLimits;
+    /**
+     * Whether a member's kudos total is shown on their card (VTI-BDG-043).
+     */
+    showKudosTotals: boolean;
+    /**
+     * Whether dynamic badge groups are computed (VTI-BDG-013). False: a community badge may not be created on a dynamic group, and existing ones are not recomputed.
+     */
+    automaticBadges: boolean;
+    /**
+     * Whether any community badge may be marked `requestable`. False: every badge group is closed.
+     */
+    membersMayRequest: boolean;
+    /**
+     * Validity of a badge credential its holders may show outside (VTI-BDG-062). Default 730.
+     */
+    credentialValidDays?: number;
+    updatedAt?: string;
+    ext?: Ext;
+}
 /**
  * An open ballot: one answer per question of the manifest, in any order. The bytes a cast's proof binds are the RFC 8785 (JCS) canonicalization of this object as received.
  */
@@ -9312,6 +9479,10 @@ export interface Group {
      * `true` while the group has a `grants` or `role` binding. Such a group is `static` and `closed` for as long as it does.
      */
     carriesAuthority: boolean;
+    /**
+     * Present exactly when the group backs a community badge (vtc/badges/*): its managers are the badge's owners, its members the badge's holders, and its DID issues the badge credential in place of a membership credential. A badge group never carries authority, is not counted among the groups two members share, and is listed among the community's groups only to a caller who asks for badge groups (VTI-BDG-010 – VTI-BDG-012).
+     */
+    badgeId?: BadgeId;
     /**
      * Active members. Only to callers who may see the member list.
      */
@@ -10319,6 +10490,24 @@ export interface KeyScopeListed {
 export interface KeyScopeNone {
     scope: "none";
 }
+/**
+ * Who may make a kudos badge (VTI-BDG-004). `nobody`: no kudos badges. `roles`: holders of any of `roles`, or members of any of `groups`. `members`: every active member.
+ */
+export interface KudosMakers {
+    policy: "nobody" | "roles" | "members";
+    /**
+     * Community role names. Read exactly when `policy` is `roles`.
+     *
+     * @maxItems 32
+     */
+    roles?: string[];
+    /**
+     * Read exactly when `policy` is `roles`.
+     *
+     * @maxItems 32
+     */
+    groups?: GroupId[];
+}
 /**
  * Which limits an override applies to. `room`: the room as a whole. `memberDefault`: every member of the room who has no override of their own. `member`: one named member — `member` is REQUIRED with this kind and forbidden with the others, a rule this schema does not express; a community refuses a violation with `malformedRequest`.
  */
@@ -10956,6 +11145,26 @@ export interface MonitorFilter {
      */
     failuresOnly?: boolean;
 }
+/**
+ * A badge as its holder sees it in their own list: the wall entry plus what only the holder knows — whether they hid it, their position for it, and the credential that evidences it.
+ */
+export interface MyBadge {
+    badge: Badge;
+    count: number;
+    since: string;
+    latestAt?: string;
+    pinned: boolean;
+    /**
+     * The holder hid it: off their wall, out of the badge's holder list for members, out of its count; the awards, the membership and the credential stand (VTI-BDG-030).
+     */
+    hidden: boolean;
+    /**
+     * The holder's order on their wall, lowest first.
+     */
+    position?: number;
+    credentialId?: GroupCredentialId;
+    credentialValidUntil?: string;
+}
 export interface NetworkMembership {
     /**
      * The network's DID.
@@ -15852,6 +16061,25 @@ export interface WakeTriggerPolicy {
      */
     allowedTriggers: string[];
 }
+/**
+ * One badge on a member's wall as a viewer sees it: the badge, how many times the member holds it, since when, and whether the member pinned it. Hidden badges are never wall entries (VTI-BDG-030).
+ */
+export interface WallEntry {
+    badge: Badge;
+    /**
+     * Accepted awards of this badge the member holds.
+     */
+    count: number;
+    /**
+     * When the member first accepted this badge.
+     */
+    since: string;
+    /**
+     * When the member last accepted an award of this badge.
+     */
+    latestAt?: string;
+    pinned: boolean;
+}
 export interface WalrusSettings {
     kind: "walrus";
     /**