@openvtc/trust-tasks 0.28.20 → 0.28.22

package/src/vtc/badges/claims/redeem/0.1/payload.ts

@@ -0,0 +1,454 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/badges/claims/redeem/0.1/payload.schema.json
+ */
+
+import type { Award, AwardId, AwardNote, AwardShare, AwardState, BadgeId, ClaimSecret, EntryId, Ext, GroupCredentialId } from "../../../../../_shared/components.js";
+
+
+/**
+ * Redeem a claim code: the member is admitted to the badge, the redemption being their consent. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCBadgesClaimsRedeemPayload {
+  code: ClaimSecret;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/badges/claims/redeem/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1#response.
+ */
+export interface VTCBadgesClaimsRedeemResponsePayload {
+  /**
+   * The award the claim recorded, `accepted`, its giver the code's issuer.
+   */
+  award: Award;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Award, AwardId, AwardNote, AwardShare, AwardState, BadgeId, ClaimSecret, EntryId, Ext, GroupCredentialId };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1" as const;
+
+/**
+ * The earlier version of this specification that this one declares it
+ * extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
+ * `null`. Only the direct declaration — follow the chain with
+ * `extendsChain` / `readForSpec`.
+ */
+export const EXTENDS: string | null = null;
+
+/**
+ * Why this version is deprecated, or `null` while it is current. A
+ * superseded or retired version is still supported, and is withdrawn from
+ * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
+ * Versions").
+ */
+export const DEPRECATION: string | null = null;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCBadgesClaimsRedeemPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCBadgesClaimsRedeemResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1",
+  "title": "VTC Badges — Claims — Redeem — payload",
+  "description": "Redeem a claim code: the member is admitted to the badge, the redemption being their consent. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "code"
+  ],
+  "properties": {
+    "code": {
+      "$ref": "#/$defs/ClaimSecret"
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Claims — Redeem — response payload",
+      "description": "The success response to a vtc/badges/claims/redeem/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "award"
+      ],
+      "properties": {
+        "award": {
+          "$ref": "#/$defs/Award",
+          "description": "The award the claim recorded, `accepted`, its giver the code's issuer."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Award": {
+      "title": "Award",
+      "description": "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. `shared` is present on an accepted award of a badge its holders may show outside while its holder shares it (vtc/badges/awards/share).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "awardId",
+        "badgeId",
+        "entryId",
+        "state",
+        "offeredAt"
+      ],
+      "properties": {
+        "awardId": {
+          "$ref": "#/$defs/AwardId"
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The recipient."
+        },
+        "givenBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "note": {
+          "$ref": "#/$defs/AwardNote"
+        },
+        "state": {
+          "$ref": "#/$defs/AwardState"
+        },
+        "offeredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the recipient accepted or declined, the giver withdrew, the offer expired, or the award was revoked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an unanswered offer lapses, where the community expires offers."
+        },
+        "credentialId": {
+          "$ref": "#/$defs/GroupCredentialId"
+        },
+        "shared": {
+          "$ref": "#/$defs/AwardShare"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "AwardShare": {
+      "title": "AwardShare",
+      "description": "Where an accepted award is shown outside the community, by its holder's choice (VTI-BDG-070): the public location that answers a verification of exactly what the credential says, the baked image where the community serves one, and since when. Present only while the holder shares the award; absent once they stop, the award is taken back, the badge is retired or the holder departs. The locations are unguessable and name no other holder (VTI-BDG-071).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "verificationUrl",
+        "since"
+      ],
+      "properties": {
+        "verificationUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "The public location that answers the credential and a verification of it."
+        },
+        "bakedImageUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "The badge's picture with the credential baked into it, for a website or an email signature. Absent where the community serves no baked image."
+        },
+        "since": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "AwardState": {
+      "title": "AwardState",
+      "description": "`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).",
+      "type": "string",
+      "enum": [
+        "offered",
+        "accepted",
+        "declined",
+        "withdrawn",
+        "expired",
+        "revoked"
+      ]
+    },
+    "AwardNote": {
+      "title": "AwardNote",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "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)."
+    },
+    "BadgeId": {
+      "title": "BadgeId",
+      "description": "Opaque identifier of a badge: `bdg_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BDG-001).",
+      "type": "string",
+      "pattern": "^bdg_[A-Za-z0-9_-]{16,64}$"
+    },
+    "AwardId": {
+      "title": "AwardId",
+      "description": "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.",
+      "type": "string",
+      "pattern": "^awd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupCredentialId": {
+      "title": "GroupCredentialId",
+      "description": "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.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "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.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "ClaimSecret": {
+      "title": "ClaimSecret",
+      "description": "A claim code itself: at least 128 random bits the community generated, base64url (22 to 64 characters). A bearer secret: shown to its issuer once, redeemed by a member, never stored or answered again (VTI-BDG-025).",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Badges — Claims — Redeem — response payload",
+      "description": "The success response to a vtc/badges/claims/redeem/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/badges/claims/redeem/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "award"
+      ],
+      "properties": {
+        "award": {
+          "$ref": "#/$defs/Award",
+          "description": "The award the claim recorded, `accepted`, its giver the code's issuer."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "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.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Award": {
+      "title": "Award",
+      "description": "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. `shared` is present on an accepted award of a badge its holders may show outside while its holder shares it (vtc/badges/awards/share).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "awardId",
+        "badgeId",
+        "entryId",
+        "state",
+        "offeredAt"
+      ],
+      "properties": {
+        "awardId": {
+          "$ref": "#/$defs/AwardId"
+        },
+        "badgeId": {
+          "$ref": "#/$defs/BadgeId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId",
+          "description": "The recipient."
+        },
+        "givenBy": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "note": {
+          "$ref": "#/$defs/AwardNote"
+        },
+        "state": {
+          "$ref": "#/$defs/AwardState"
+        },
+        "offeredAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "decidedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the recipient accepted or declined, the giver withdrew, the offer expired, or the award was revoked."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When an unanswered offer lapses, where the community expires offers."
+        },
+        "credentialId": {
+          "$ref": "#/$defs/GroupCredentialId"
+        },
+        "shared": {
+          "$ref": "#/$defs/AwardShare"
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "AwardShare": {
+      "title": "AwardShare",
+      "description": "Where an accepted award is shown outside the community, by its holder's choice (VTI-BDG-070): the public location that answers a verification of exactly what the credential says, the baked image where the community serves one, and since when. Present only while the holder shares the award; absent once they stop, the award is taken back, the badge is retired or the holder departs. The locations are unguessable and name no other holder (VTI-BDG-071).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "verificationUrl",
+        "since"
+      ],
+      "properties": {
+        "verificationUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "The public location that answers the credential and a verification of it."
+        },
+        "bakedImageUrl": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 2048,
+          "description": "The badge's picture with the credential baked into it, for a website or an email signature. Absent where the community serves no baked image."
+        },
+        "since": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "AwardState": {
+      "title": "AwardState",
+      "description": "`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).",
+      "type": "string",
+      "enum": [
+        "offered",
+        "accepted",
+        "declined",
+        "withdrawn",
+        "expired",
+        "revoked"
+      ]
+    },
+    "AwardNote": {
+      "title": "AwardNote",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "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)."
+    },
+    "BadgeId": {
+      "title": "BadgeId",
+      "description": "Opaque identifier of a badge: `bdg_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BDG-001).",
+      "type": "string",
+      "pattern": "^bdg_[A-Za-z0-9_-]{16,64}$"
+    },
+    "AwardId": {
+      "title": "AwardId",
+      "description": "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.",
+      "type": "string",
+      "pattern": "^awd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "GroupCredentialId": {
+      "title": "GroupCredentialId",
+      "description": "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.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "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.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "ClaimSecret": {
+      "title": "ClaimSecret",
+      "description": "A claim code itself: at least 128 random bits the community generated, base64url (22 to 64 characters). A bearer secret: shown to its issuer once, redeemed by a member, never stored or answered again (VTI-BDG-025).",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;