---
robots: noindex, nofollow
---

# GSTP Extensions for the `envelope` Command Line Tool

Wolf McNally, Lead Researcher
Blockchain Commons
October 30, 2024

These are proposed extensions to the `envelope` command line tool to support GSTP.

## Overview of Required Functionality (Sender)

### Expression Composition

- Specify function identifiers as envelope subject.
- Specify parameter identifiers as assertion predicates.

### Generating the Request

- Wrap an expression in a request with a specific or freshly generated ARID.
- Add the 'senderPublicKey' assertion.

### Composing Sender Continuation

- Specify the envelope to be encrypted back to the sender.
- Specify whether the continuation should include the request ARID.
- Specify whether the continuation should include an expiration date.
- Add the 'senderContinuation' assertion to the request.

### Adding a Recipient Continuation

- Add the 'recipientContinuation' assertion to the request.

### Sign and Encrypt the Request

- Sign the request with the sender's private key.
- Encrypt the request with the recipient's public key.

## Overview of Required Functionality (Recipient)

### Decrypting the Request

- Decrypt the request with the recipient's private key.

### Process the Message Signature

- Validate the signature of the request against the 'senderPublicKey' assertion.
- Extract the signed request.
- Extract the sender's public key.

### Process the Recipient Continuation

- Decrypt the recipient continuation.
- Validate the expiration date.
- Validate the request ARID by comparing it to the response ARID.
- Extract the continuation envelope.

### Process the Sender Continuation

- Extract the sender continuation.

### Extracting the Request ID and Body Expression

- Extract the request ARID.
- Extract the body expression.
- Extract the function identifier.
- Extract the parameters.

## Enhancements to Existing Commands

Enhancements to the existing `envelope` command line tool will be made to support function and parameter identifiers directly.

# Creates an envelope with a function identifier as its subject.
# Function identifiers can be a number or a string.
$ envelope subject type function <FUNCTION>

ur:envelope

# Extracts the subject of an envelope as a function identifier.
$ envelope extract function [ENVELOPE]

<FUNCTION>

# Creates an envelope with a parameter identifier as its subject.
# Parameter identifiers can be a number or a string.
$ envelope subject type parameter <PARAMETER>

ur:envelope

# Extracts the subject of an envelope as a parameter identifier.
$ envelope extract parameter [ENVELOPE]

<PARAMETER>

# Parameter identifiers can be used as assertion predicates.
$ envelope assertion add pred-obj parameter <PARAMETER> <OBJ_TYPE> <OBJ_VALUE> [ENVELOPE]

ur:envelope

### New `expression` Subcommand

This new subcommand affords the composition and parsing of expression envelopes.

# Creates an envelope with a function identifier as its subject.
$ envelope expression function <FUNCTION>

ur:envelope

# Add a parameter to an expression envelope.
$ envelope expression parameter <PARAMETER> <VALUE_TYPE> <VALUE> [ENVELOPE]

ur:envelope

# Returns the function identifier of an expression envelope, followed by the parameters.
# Validates the envelope as an expression.
# Ignores non-parameter assertions.
# Optionally returns error if non-parameter assertions are present.
$ envelope expression parse [ENVELOPE]

<function>
ur:envelope
ur:envelope
...

### New `gstp` Subcommand

This new subcommand affords the composition and parsing of GSTP messages.

# Creates a complete, ready to send GSTP message.
#
# If only a sender public key is provided, then the envelope will not be signed,
# and the continuation, if present, will not be encrypted. This is primarily for
# debugging, testing, and educational purposes.
$ envelope gstp compose \
    --request | --success | --failure \                 # The type of message to send.
    --id ur:arid \                                      # Optional for request, if not specified generates a new ARID.
    --sender ur:crypto-prvkeys | ur:crypto-pubkeys \    # Envelope not signed if only a public key is specified.
    --sender-continuation ur:envelope \ \               # Optional, no continuation if not specified.
    --sender-continuation-expiry <DATE> \               # Optional, no expiry if not specified.
    --sender-continuation-id \                          # Optional, no continuation ARID if not specified.
    --recipient ur:public-key-base                      # Optional, envelope is not encrypted if not specified.
    --recipient-continuation <SEALED_ENVELOPE> \        # Optional, no continuation if not specified.
    [EXPRESSION_ENVELOPE] | [RESULT] | [ERROR]          # The body of the request, or the result or error of the response.

<GSTP_ENVELOPE>

# Validates, extracts, and returns the components of a received GSTP message, formatted to STDOUT on separate lines.
$ envelope gstp parse \
    --recipient <PRIVATE_KEY_BASE> \
    [<GSTP_ENVELOPE>]

"request" | "success" | "failure" \    # The type of message received.
<ARID> \                  # The message ARID.
<PUBLIC_KEY_BASE> \       # The sender's public key.
<EXPRESSION_ENVELOPE> | <RESULT> | <ERROR> \    # The body of the request, or the result or error of the response.
<ENVELOPE> \              # The recipient's decrypted continuation, if present.
<EXPECTED_ARID> \         # The ARID from the recipient continuation, if present.
<EXPIRED_AFTER> \         # The continuation expiry from the recipient continuation, if present.
<ENCRYPTED_ENVELOPE> \    # The sender's continuation, if present.