Learning Attestations from the Command Line

Attestations, endorsements, and other claims can be created using Gordian Envelope. They can be published in whole or published as a hash to be revealed later. Alternatively, they can be attached directly to an identity.

The following command-line examples use the Rust Envelope CLI to create claims. More examples can be found in Learning XIDs from the Command Line, particularly chapter 2, which demonstrates more ways to make claims, and chapter 3, which shows how to attach those claims to identities.

The Bytewords CLI is also used in a single example to generate a UR by hand.

Creating Self-Attestations

The following example uses the fair witness methodology to create a claim. A good self attestation contains the following elements:

Clear Subject: What specifically is being attested to

PROJECT=$(envelope subject type string "Financial API Security Overhaul")

Specific Claims with Context:

PROJECT=$(envelope assertion add pred-obj string "role" string "Lead Security Developer" "$PROJECT")
PROJECT=$(envelope assertion add pred-obj string "timeframe" string "2022-03 through 2022-09" "$PROJECT")

Methodology and Evidence:

PROJECT=$(envelope assertion add pred-obj string "methodology" string "Security testing with automated scanning and manual code review" "$PROJECT")
PROJECT=$(envelope assertion add pred-obj string "metricsHash" digest "$METRICS_HASH" "$PROJECT")

Transparent Limitations:

PROJECT=$(envelope assertion add pred-obj string "limitations" string "Backend components only, limited frontend involvement" "$PROJECT")

Cryptographic Signatures:

WRAPPED_PROJECT=$(envelope subject type wrapped $PROJECT)
SIGNED_PROJECT=$(envelope sign -s "$PRIVATE_KEYS" "$WRAPPED_PROJECT")

Publication:

This complete self-attestation looks as follows:

{
    "Financial API Security Overhaul" [
        "limitations": "Backend components only, limited frontend involvement"
        "methodology": "Security testing with automated scanning and manual code review"
        "metricsHash": Digest(b3cb8720)
        "role": "Lead Security Developer"
       "timeframe": "2022-03 through 2022-09"
    ]
} [
    'signed': Signature
]

The subject could choose to store, privately share, or publish the attestation, to share or publish only a hash of the attestation, or to attach it to their identity (such as linking it as an edge to a XID).

Adding Verifiable Self-Attestations

Self-attestations become more credible when they reference independently verifiable sources. The follow examples add new verifiable details to the previous $PROJECT.

Git Commit References:

This demonstrates how Github records can make a project verifiable.

# Generate a hash of the hashes in the commit history
GIT_HISTORY_HASH=$(git log --pretty=format:"%H" | shasum -a 256 | awk '{print $1}')

# Encode per the [ur:digest CDDL](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2021-002-digest.md#cddl)
GIT_HISTORY_HASH_BW=$(bytewords -i hex "5820"$GIT_HISTORY_HASH -o minimal)
GIT_HISTORY_HASH_UR="ur:digest/"$GIT_HISTORY_HASH_BW  

# Add the verifiable reference to the project
PROJECT_GIT=$(envelope subject type string "https://github.com/organization/project")   
PROJECT_GIT=$(envelope assertion add pred-obj string "gitCommitHistory" digest "$GIT_HISTORY_HASH_UR" "$PROJECT_GIT")
PROJECT_GIT=$(envelope assertion add pred-obj string 'gitCommitHistoryDate' string `date -Iminutes` "$PROJECT_GIT")
PROJECT_GIT=$(envelope assertion add pred-obj string "gitVerificationNote" string "Commits signed with GPG key fingerprint 3AA5 C34D..." "$PROJECT_GIT")
PROJECT=$(envelope assertion add pred-obj string "gitRepo" envelope $PROJECT_GIT $PROJECT)

Published Work:

This demonstrates how a published work can make a project verifiable.

PROJECT_DOI=$(envelope subject type string "10.1234/journal.article")
PROJECT_DOI=$(envelope assertion add pred-obj known date string "2023-05-12" "$PROJECT_DOI")
PROJECT=$(envelope assertion add pred-obj string "publicationDOI" envelope $PROJECT_DOI "$PROJECT")

Public Demonstrations:

This demonstrates how a demo can make a project verifiable.

PROJECT_DEMO=$(envelope subject type uri "https://example.com/demo-with-timestamp")
PROJECT_DEMO=$(envelope assertion add pred-obj known date string "2023-07-09" "$PROJECT_DEMO")
PROJECT=$(envelope assertion add pred-obj string "demoVideo" envelope $PROJECT_DEMO "$PROJECT")

Cryptographic Signatures:

Since we adjusted the core $PROJECT data, we must re-sign.

WRAPPED_PROJECT=$(envelope subject type wrapped $PROJECT)
SIGNED_PROJECT=$(envelope sign -s "$PRIVATE_KEYS" "$WRAPPED_PROJECT")

Identifier Link:

The signed credential has now improved the original attestation through additional data that is verifiable in various ways.

{
    "Financial API Security Overhaul" [
        "demoVideo": URI(https://example.com/demo-with-timestamp) [
            'date': "2023-07-09"
        ]
        "gitRepo": "https://github.com/organization/project" [
            "gitCommitHistory": Digest(cff55bed)
            "gitCommitHistoryDate": "2026-07-08T11:18-10:00"
            "gitVerificationNote": "Commits signed with GPG key fingerprint 3AA5 C34D..."
        ]
        "limitations": "Backend components only, limited frontend involvement"
        "methodology": "Security testing with automated scanning and manual code review"
        "metricsHash": Digest(b3cb8720)
        "publicationDOI": "10.1234/journal.article" [
            'date': "2023-05-12"
        ]
        "role": "Lead Security Developer"
        "timeframe": "2022-03 through 2022-09"
    ]
} [
    'signed': Signature
]

Making Peer Endorsements

You can also create endorsements about other people. Following the Fair Witness methdology, this requires:

Endorser Information:

The endorseer is identified, and then additional data is used to describe who they are and what their biases are.

SOURCE=$(envelope subject type ur $MY_XID_ID)
SOURCE=$(envelope assertion add pred-obj string "endorser" string "TechPM - Project Manager with 12 years experience" "$SOURCE")

Basis for Endorsement:

SOURCE=$(envelope assertion add pred-obj string "basis" string "Direct observation throughout the project plus review of metrics" "$SOURCE")

Endorser’s Limitations:

SOURCE=$(envelope assertion add pred-obj string "endorserLimitation" string "Limited technical background in cryptography" "$SOURCE")

Potential Biases:

SOURCE=$(envelope assertion add pred-obj string "potentialBias" string "Had management responsibility for project success" "$SOURCE")

Relationship Disclosure:

SOURCE=$(envelope assertion add pred-obj string "relationship" string "Direct project oversight as Project Manager" "$SOURCE")

Clear Identification of Subject:

TARGET=$(envelope subject type ur $XID_ID)

Specific Observations:

Observations are then applied to the $TARGET as a standardized methodology described in Learning XIDs.

TARGET=$(envelope assertion add pred-obj string "project" string "Financial API Project" "$TARGET")
TARGET=$(envelope assertion add pred-obj string "observation" string "BRadvoc8 designed innovative authentication system that exceeded security requirements" "$TARGET")

Standard Format:

This example follows the edge formatting of endorsements, which calls for a unique subject, a descriptive isA and a source and target, potentially with additional info about each. (Any alternative format could be used.)

EDGE=$(envelope subject type string "endorsement-from-charlene")
EDGE=$(envelope assertion add pred-obj known 'isA' known 'attestation' $EDGE)
EDGE=$(envelope assertion add pred-obj known 'source' envelope $SOURCE $EDGE)
EDGE=$(envelope assertion add pred-obj known 'target' envelope $TARGET $EDGE)

Cryptographic Signature:

WRAPPED_EDGE=$(envelope subject type wrapped $EDGE)
SIGNED_EDGE=$(envelope sign -s "$MY_KEYS" "$WRAPPED_EDGE")

The result is as follows:

{
    "endorsement-from-charlene" [
        'isA': 'attestation'
        'source': XID(51754269) [
            "basis": "Direct observation throughout the project plus review of metrics"
            "endorser": "TechPM - Project Manager with 12 years experience"
            "endorserLimitation": "Limited technical background in cryptography"
            "potentialBias": "Had management responsibility for project success"
            "relationship": "Direct project oversight as Project Manager"
        ]
        'target': XID(e37356a3) [
            "observation": "BRadvoc8 designed innovative authentication system that exceeded security requirements"
            "project": "Financial API Project"
        ]
    ]
} [
    'signed': Signature
]

Accepting an Endorsement

For maximum credibility, endorsements should follow an acceptance model:

Recipient Reviews Endorsement:

Evaluates accuracy and fairness
Checks for appropriate context and disclosure
Verifies the endorser’s signature

# Verify the signature is valid
if envelope verify -v "$ENDORSER_PUBLIC_KEY" "$SIGNED_EDGE"; then
  echo "✅ Endorsement signature verified"
else
  echo "❌ Invalid endorsement signature"
fi
   
# Review the endorsement content
envelope format "$SIGNED_EDGE"

Recipient Decides Whether to Accept:
- Can accept the endorsement as is
- Can request modifications before accepting
- Can decline the endorsement
Recipient Includes Accepted Endorsement:

As noted previously, a user can choose to publish an attestation in a variety of ways. One of the most powerful is to add an endorsement to a XID, which can be done as an edge or an attachment, depending on the precise formatting.
```
XID_WITH_EDGE=$(envelope xid edge add \
  --verify inception \
  $SIGNED_EDGE $XID)
```

Recipient Publishes Public Version of XID

The user can then produce a public version of their XID, which involves advancing a provenance mark and eliding unneeded private date, as explained in Learning XIDs.

XID_WITH_EDGE=$(envelope xid provenance next \
  --password "$PASSWORD" \
  --sign inception \
  --private encrypt \
  --generator encrypt \
  --encrypt-password "$PASSWORD" \
  "$XID_WITH_EDGE")
PUBLIC_XID_WITH_EDGE=$(envelope xid export \
  --private elide \
  --generator elide \
  "$XID_WITH_EDGE")

Part of this publication is --sign inception, which is where the user signs the XID with the edge to show that they’ve agreed for it to be part of their identity information.

The result will look like:

{
    XID(e37356a3) [
        'edge': {
            "endorsement-from-charlene" [
                'isA': 'attestation'
                'source': XID(51754269) [
                    "basis": "Direct observation throughout the project plus review of metrics"
                    "endorser": "TechPM - Project Manager with 12 years experience"
                    "endorserLimitation": "Limited technical background in cryptography"
                    "potentialBias": "Had management responsibility for project success"
                    "relationship": "Direct project oversight as Project Manager"
                ]
                'target': XID(e37356a3) [
                    "observation": "BRadvoc8 designed innovative authentication system that exceeded security requirements"
                    "project": "Financial API Project"
                ]
            ]
        } [
            'signed': Signature
        ]
        'key': PublicKeys(77f5072e, SigningPublicKey(e37356a3, Ed25519PublicKey(234563e3)), EncapsulationPublicKey(20016c72, X25519PublicKey(20016c72))) [
            'allow': 'All'
            'nickname': "BRadvoc8"
            ELIDED
        ]
        'provenance': ProvenanceMark(c2c580a8) [
            ELIDED
        ]
    ]
} [
    'signed': Signature(Ed25519)
]

Check Your Understanding