@openvtc/trust-tasks 0.3.0 → 0.4.0

package/src/policy/evaluate/0.3/payload.ts

@@ -3,6 +3,10 @@
  * Source: specs/policy/evaluate/0.3/payload.schema.json
  */
 
+/**
+ * Multibase-encoded multihash over the RFC 8785 (JCS) canonicalization of the payload, salted with the request challenge, present when a delegated-execution consent flow must bind approval to this exact payload. Absent when no consent binding is in play.
+ */
+export type DigestMultibase = string;
 /**
  * A single binding target for a vault entry. Tagged union over the discriminator `kind`. A VaultEntry's `targets` array MAY mix any number of these.
  */
@@ -42,10 +46,7 @@ export interface PolicyInput {
      * The identifier the task acts on — the value at the spec's `subjectPath` (usually a DID). The evaluator checks the consumer's authority to act on this subject. Absent for subjectless tasks (discovery, list).
      */
     subject?: string;
-    /**
-     * Multihash of the canonicalized payload, salted with the request challenge, present when a delegated-execution consent flow must bind approval to this exact payload. Absent when no consent binding is in play.
-     */
-    payloadDigest?: string;
+    payloadDigest?: DigestMultibase;
     /**
      * Authoritative integrity class (SPEC §7.3 item 13). The evaluator MUST derive this from the compiled handler it is about to invoke, not from the wire — the registry's declared value is advisory only.
      */
@@ -176,7 +177,7 @@ export interface PolicyDecision {
 export const TYPE_URI = "https://trusttasks.org/spec/policy/evaluate/0.3" as const;
 
 /** Stable alias for this specification's request payload shape. */
-export type Payload = SiteTarget;
+export type Payload = DigestMultibase;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/policy/evaluate/0.3#response" as const;

package/src/task-consent/decision/0.1/payload.ts

@@ -3,10 +3,18 @@
  * Source: specs/task-consent/decision/0.1/payload.schema.json
  */
 
+/**
+ * Echoes the digest of the task being authorized, in the encoding `task-consent/request` carried it. The executor re-derives it from the payload it is about to execute and refuses on mismatch — this is what makes the approved payload the executed payload, cryptographically rather than by convention.
+ */
+export type DigestMultibase = string;
 /**
  * The approver's answer. `deny` aborts the pending request; a subsequent submit of the same task starts a fresh one.
  */
 export type Decision = "approve" | "deny";
+/**
+ * The digest this decision concerned, in the encoding `task-consent/request` carried it.
+ */
+export type DigestMultibase1 = string;
 
 /**
  * An enrolled approver authorizes (or refuses) one pending privileged task, bound to the exact payload it was shown. The proof on this document — not the transport session that carried it — is the authorization.
@@ -16,10 +24,7 @@ export interface TaskConsentDecisionPayload {
    * Echoes the task-consent/request this decision answers, binding it to that one pending request. An executor MUST consume the challenge at execution rather than on receipt of this decision: a decision authorizes exactly one execution, and consuming it earlier lets an executor's own retry legitimately replay it.
    */
   challenge: string;
-  /**
-   * Echoes the digest of the task being authorized. The executor re-derives it from the payload it is about to execute and refuses on mismatch — this is what makes the approved payload the executed payload, cryptographically rather than by convention.
-   */
-  payloadDigest: string;
+  payloadDigest: DigestMultibase;
   decision: Decision;
   /**
    * OPTIONAL human-facing note, most useful on a `deny`.
@@ -41,10 +46,7 @@ export interface TaskConsentDecisionResponsePayload {
    * `granted` = the threshold is met and the requester's re-submit will now execute. `pending` = the approval was recorded but more are needed. `denied` = the request was aborted.
    */
   status: "granted" | "pending" | "denied";
-  /**
-   * The digest this decision concerned.
-   */
-  payloadDigest: string;
+  payloadDigest: DigestMultibase1;
   /**
    * Distinct approvals recorded so far.
    */
@@ -60,7 +62,7 @@ export interface TaskConsentDecisionResponsePayload {
 export const TYPE_URI = "https://trusttasks.org/spec/task-consent/decision/0.1" as const;
 
 /** Stable alias for this specification's request payload shape. */
-export type Payload = Decision;
+export type Payload = DigestMultibase;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/task-consent/decision/0.1#response" as const;

package/src/task-consent/granted/0.1/payload.ts

@@ -3,6 +3,11 @@
  * Source: specs/task-consent/granted/0.1/payload.schema.json
  */
 
+/**
+ * The salted wire digest of the approved task — the same value the matching task-consent/request carried and the decision echoed. The requester already holds it; it is repeated here only so the requester can correlate the notice to the pending task it should now re-submit. It confers nothing: the executor's single-use grant lookup at re-submit is the authorization.
+ */
+export type DigestMultibase = string;
+
 /**
  * Fire-and-forget notice from the executor to the requester that its pending task has reached the approval threshold and a single-use grant is waiting, so the requester re-submits at once instead of polling. Non-load-bearing by design: the grant check at re-submit is the real gate, so a lost or spurious notice costs at most one poll cycle.
  */
@@ -11,10 +16,7 @@ export interface TaskConsentGrantedPayload {
    * Always `granted`. A denial sends no notice — the requester's re-submit discovers it, and a notice that could carry a denial would tempt a consumer into treating this advisory channel as the authoritative outcome, which it is not.
    */
   status: "granted";
-  /**
-   * The salted wire digest of the approved task — the same value the matching task-consent/request carried and the decision echoed. The requester already holds it; it is repeated here only so the requester can correlate the notice to the pending task it should now re-submit. It confers nothing: the executor's single-use grant lookup at re-submit is the authorization.
-   */
-  payloadDigest: string;
+  payloadDigest: DigestMultibase;
   /**
    * Type URI of the approved task, for correlation and display at the requester. Advisory on the same terms as the digest — the executor re-derives everything it enforces from the re-submitted payload itself.
    */
@@ -32,7 +34,7 @@ export interface Ext {
 export const TYPE_URI = "https://trusttasks.org/spec/task-consent/granted/0.1" as const;
 
 /** Stable alias for this specification's request payload shape. */
-export type Payload = TaskConsentGrantedPayload;
+export type Payload = DigestMultibase;
 
 /**
  * SPEC.md §7.2 policy for the request variant, from this specification's

package/src/task-consent/request/0.1/payload.ts

@@ -3,6 +3,11 @@
  * Source: specs/task-consent/request/0.1/payload.schema.json
  */
 
+/**
+ * The binding between what the approver sees and what executes. Multibase-encoded multihash over the RFC 8785 (JCS) canonicalization of the payload, the task type, and the `challenge` as salt. The decision echoes it; the executor re-derives it from the payload it is about to run and refuses on mismatch. Salted because an unsalted digest over a low-entropy payload is a confirmation oracle for anyone who observes it in transit.
+ */
+export type DigestMultibase = string;
+
 /**
  * The executor asks an enrolled approver device to authorize one pending privileged task, presenting the effects it computed by dry-running the real handler against its own prior state. The executor signs this document; the approver renders only what it verifies under that signature.
  */
@@ -15,10 +20,7 @@ export interface TaskConsentRequestPayload {
    * Type URI of the task awaiting approval. It is bound into `payloadDigest`: without that binding, two tasks whose payloads canonicalize identically would share a digest, and an approval for a benign task would authorize a destructive one.
    */
   taskType: string;
-  /**
-   * The binding between what the approver sees and what executes. Digest of the canonical (RFC 8785 JCS) payload, the task type, and the `challenge` as salt. The decision echoes it; the executor re-derives it from the payload it is about to run and refuses on mismatch. Salted because an unsalted digest over a low-entropy payload is a confirmation oracle for anyone who observes it in transit.
-   */
-  payloadDigest: string;
+  payloadDigest: DigestMultibase;
   /**
    * Authoritative SPEC §7.3 item 13 side-effect class of the pending task, derived by the executor from the compiled handler it is about to invoke. NEVER taken from the registry: a registry that decided this would be a consent kill-switch, downgradeable by publishing a new version with a weaker class.
    */
@@ -157,7 +159,7 @@ export interface TaskConsentRequestResponsePayload {
 export const TYPE_URI = "https://trusttasks.org/spec/task-consent/request/0.1" as const;
 
 /** Stable alias for this specification's request payload shape. */
-export type Payload = TaskConsentRequestPayload;
+export type Payload = DigestMultibase;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/task-consent/request/0.1#response" as const;

package/src/vta/credentials/issue/0.1/payload.ts

@@ -39,6 +39,8 @@ export interface Ext {
 }
 /**
  * The success response to a vta/credentials/issue request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vta/credentials/issue/0.1#response.
+ *
+ * This is the credentials/_shared IssuedCredential shape — same members, same required set — plus `supersedes` and `ext`. It states them inline rather than `$ref`-ing the shared definition because that definition sets `additionalProperties: false`, which under `allOf` would reject the two extra members. The shared CredentialId is still referenced. Keep the two in step by hand if either changes.
  */
 export interface VTACredentialsIssueResponsePayload {
   credentialId: CredentialId;

package/src/vta/credentials/issue/0.2/payload.ts

@@ -0,0 +1,101 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vta/credentials/issue/0.2/payload.schema.json
+ */
+
+/**
+ * The success response to a vta/credentials/issue request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vta/credentials/issue/0.1#response.
+ *
+ * Composed from the shared IssuedCredential rather than restating it: that definition is the issuance receipt every issuer returns, and duplicating it here let the two drift silently. `unevaluatedProperties` closes the object after the `allOf` is applied, which is what makes the composition possible at all — `additionalProperties` is evaluated per-subschema against the whole object and would reject `supersedes` and `ext`.
+ */
+export type VTACredentialsIssueResponsePayload = IssuedCredentialBase;
+/**
+ * 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.
+ */
+export type CredentialId = string;
+
+export interface VTACredentialsIssuePayload {
+  /**
+   * DID of the credential's subject/holder (becomes credentialSubject.id).
+   */
+  holder: string;
+  /**
+   * The scoped claims to attest — the share's scope. Opaque to the framework; non-empty.
+   */
+  claims: {};
+  /**
+   * Additional credential type beyond VerifiableCredential (e.g. ScopedShareCredential). Some values name a claims profile defined by this specification (e.g. GovernancePolicyCredential), which constrains the shape of `claims`.
+   */
+  credentialType?: string;
+  /**
+   * Credential lifetime in seconds from issuance. The issuer MAY cap this.
+   */
+  validitySeconds: number;
+  /**
+   * Optional human-readable rationale, recorded for audit.
+   */
+  purpose?: string;
+  ext?: Ext;
+}
+/**
+ * Ecosystem-defined extension members per SPEC.md §4.5.1.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+/**
+ * The members of an issuance receipt, deliberately left **open** so a consuming specification can `$ref` it under `allOf` and add its own, then close the result with `unevaluatedProperties: false`.
+ *
+ * A closure inside this definition would defeat that. Both `additionalProperties` and `unevaluatedProperties` are evaluated against the whole instance from within the subschema that declares them, and neither can see members the *outer* schema matched — so either one here rejects the consumer's extras. Only an `unevaluatedProperties` at the outer level sees everything the composition matched. Use `IssuedCredential` where a closed standalone shape is wanted.
+ */
+export interface IssuedCredentialBase {
+  credentialId: CredentialId;
+  /**
+   * The issued Verifiable Credential (W3C VC Data Model 2.0), signed by the issuer's key. Opaque to the framework.
+   */
+  credential: {};
+  /**
+   * When the credential was minted.
+   */
+  issuedAt?: string;
+  /**
+   * When the credential's validUntil falls due.
+   */
+  expiresAt: string;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vta/credentials/issue/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTACredentialsIssueResponsePayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vta/credentials/issue/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTACredentialsIssueResponsePayload;
+
+/**
+ * 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.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+} 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,
+} as const;

package/src/vtc/relationships/request/0.1/payload.ts

@@ -0,0 +1,71 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/relationships/request/0.1/payload.schema.json
+ */
+
+/**
+ * A member asks another member to issue them a Verifiable Relationship Credential. Everything here is a hint: the issuing member decides, and declines with a trust-task-error carrying `vtc/relationships/request:declined` rather than a bespoke rejection message.
+ */
+export interface VTCRelationshipsRequestPayload {
+  /**
+   * Why the requester is asking, in their own words, for the issuing member to weigh. A hint and not a term — the issuing member is under no obligation to honour it, and MUST NOT treat its absence as a defect. Free text reaching a human, so a producer SHOULD keep it to what it is willing to have quoted back.
+   */
+  reason?: string;
+  ext?: Ext;
+}
+/**
+ * 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.
+ */
+export interface Ext {
+  [k: string]: unknown | undefined;
+}
+/**
+ * The issued credential. Returned only where the issuing member agreed; a decline is a trust-task-error, not a response with an empty field.
+ */
+export interface VTCRelationshipsRequestResponsePayload {
+  /**
+   * A signed W3C Verifiable Relationship Credential (opaque here). Its issuer MUST be the issuing member — the party that signed this response — and its credentialSubject.id MUST name the requester. The same shape `vtc/relationships/publish` accepts, so a requester can lodge it with the community unchanged.
+   */
+  vrc: {};
+  /**
+   * SHA-256 of the returned VRC, for out-of-band integrity checks. Matches the digest `vtc/relationships/publish` reports once the credential is lodged, so the two can be tied together without re-hashing.
+   */
+  vrcSha256?: string;
+  ext?: Ext;
+}
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/relationships/request/0.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCRelationshipsRequestPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/relationships/request/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCRelationshipsRequestResponsePayload;
+
+/**
+ * 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.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: true,
+  isRecipientRequired: true,
+} 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,
+} as const;