Creating Public Documents

The Tsrct protocol allows you to publish immutable, digitally signed documents that are globally readable by any party across the internet. By setting the Access Control List to acl_pub, your document becomes part of the public cryptographic record—accessible without authentication while remaining tamper-evident and verifiably attributed to your public identity.

[!NOTE] Domain / Organization Publishing Scope:
This CLI creation workflow is currently intended for public documents issued by a domain or organization, where direct signing is performed using a Key Management Service (such as Google Cloud KMS) or an organization signing key. This makes it particularly well-suited for automated backend systems, CI/CD pipelines, live data feeds, and official binary/software releases.

Common use cases for public documents include:

• Automated Data Feeds & Real-Time Notices: Pricing engines, market status reports, live telemetry, and regulatory announcements.
• Software & Binary Releases: Cryptographically signed application builds, firmware binaries, release checksums, and update manifests.
• Brand Assets & Media: Official corporate logos, favicons, branding kits, and media files.
• Public Catalogs & Product Specs: Market registrations, OpenAPI definitions, product catalogs, and financial disclosures.
• Open Attestations & Public Keys: Root organizational credentials, certificate chains, and domain trust anchors.

The Public Document Model

Unlike private documents (acl_pri), public documents do not require authorization to view:

graph LR
    Publisher[Publisher] -- "doc-create (--acl acl_pub)" --> TsrctCloud[Tsrct Cloud / API]
    AnyClient[Any Web User / cURL / Agent] -- "GET /<UID>/body (No JWT Required)" --> TsrctCloud
    TsrctCloud -- "200 OK (Verifiable Content)" --> AnyClient

1. Publication: The publisher signs the payload using their registered private key (locally or via KMS) and sets --acl acl_pub.
2. Access: The document can be fetched by anyone over standard HTTP/HTTPS.
3. No Authentication Required: The requester does not need to supply an X-TSRCT-AUTH JWT or API key.
4. Verifiable Authenticity: Any consumer can retrieve the publisher’s registered public key and verify the digital signature (sig) over the document body (sha).

1. Prepare Your Payload

A public document can be of any data format (plain text, JSON, Markdown, binary images, PDFs, etc.). You can provide payload content either directly on the command line or from a file:

Option A: Inline Plain Text (--text)

For short messages, notices, or status updates, you can pass text directly on the command line without creating a file. When --typ text is specified, cty automatically defaults to text/plain.

Option B: Structured JSON File (market-notice.json)

{
  "noticeId": "PUB-2026-001",
  "topic": "Market Schedule Update",
  "effectiveDate": "2026-09-01T00:00:00Z",
  "publisher": "tradex.atomcloud.com",
  "summary": "Regular holiday trading hours schedule for Labor Day 2026."
}

Option C: Media / Binary Asset (logo.png)

Binary assets such as PNG/JPEG images, SVG vectors, or PDF files can be published directly from your local filesystem using --typ blob and providing the appropriate --cty (e.g., image/png).

2. Issue the T-Doc via CLI

Use the tsrct tdoc doc-create command. The critical flag for public visibility is --acl acl_pub.

Example 1: Publishing Inline Plain Text Directly

(Using --text without creating an external file)

tsrct tdoc doc-create \
  --typ text \
  --text "System maintenance completed successfully on cluster us-central1." \
  --src <YOUR_ORG_UID> \
  --uid maintenance-complete-20260901 \
  --dsc "Maintenance Confirmation Notice" \
  --tag "ops, notice, maintenance" \
  --acl acl_pub \
  --lst true \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

[!NOTE] When --typ text is used with --text, the CLI automatically base64-encodes the string and sets --cty to text/plain.

Example 2: Publishing a Public JSON Notice from File

tsrct tdoc doc-create \
  --typ json \
  --cty application/json \
  --input market-notice.json \
  --src <YOUR_ORG_UID> \
  --uid market-notice-2026-001 \
  --dsc "Public Market Holiday Schedule" \
  --tag "notice, trading, schedule" \
  --acl acl_pub \
  --lst true \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

Example 3: Publishing a Public Image / Brand Asset

(As seen in deployment workflows such as deploy-atomcloud-com)

tsrct tdoc doc-create \
  --typ blob \
  --cty "image/png" \
  --input "assets/atomcloud-logo.png" \
  --src "$TSRCT_UID" \
  --uid "logo-main" \
  --dsc "Official Atomcloud Primary Logo" \
  --tag "favicon, icon, logo" \
  --acl "acl_pub" \
  --lst true \
  --key "$TSRCT_KEY" \
  --key-host gcp \
  --sig-key-resource "projects/$PROJECT/locations/LOCATION/keyRings/$DOMAIN-keyring/cryptoKeys/$DOMAIN-init-key-sig/cryptoKeyVersions/1"

3. Understanding Public Listability (--lst)

The --lst (listable) flag controls whether your public document is discoverable via publisher document feeds and automated scrapers, or kept unlisted:

[!TIP] Use --lst true for content intended for broad discovery (press releases, product specs, logos, branding assets).
Use --lst false when sharing public verification links (like an unlisted order receipt or direct confirmation) where you want zero authentication friction, but do not want the document indexed in your public stream.

4. Lineage, Evolution, and Metadata

Tsrct documents support rich header metadata for tracking lineage, forward chaining, custom attributes, and mutable virtual pointers:

4.1 Cryptographic Back-References (ref)

The --ref flag enables you to establish an immutable chain of custody / lineage by back-pointing to one or more prior documents (such as an earlier version of a specification, a referenced contract, or an original image):

• CLI Usage: Pass a comma-separated list of document UIDs:

  --ref "<PRIOR_ORG_UID>.<PRIOR_DOC_UID_1>,<PRIOR_ORG_UID>.<PRIOR_DOC_UID_2>"
  

• How It Works: During creation, the Tsrct CLI resolves each referenced document via tsrctApi.getRefs(refs) and embeds a cryptographic proof object inside the ref array of the header:

  "ref": [
    {
      "uid": "9000990009900099000990009.20240220115508-9666bc1f8cb7f5d3",
      "sha": "9hit9rq8qeefFQ69w7DDZ0mEm6TCZscix9hegyiBycg",
      "sig": "NlDX_HbHRb6x7i4p...",
      "tds": "gp5bbKGZRIl0yZX..."
    }
  ]
  

• Integrity Guarantee: The reference cryptographically locks the exact version of the referenced document (sha, sig, and footer tds). If the prior document is altered or deleted, downstream verification will detect the discrepancy.

4.2 Custom Metadata Object (mtd)

The mtd field allows publishers to attach an arbitrary JSON metadata object directly to the document header without modifying the body schema:

• Header Structure:

  "mtd": {
    "version": "2.4.0",
    "author": "Architecture Working Group",
    "department": "Engineering",
    "environment": "production",
    "dimensions": { "width": 1024, "height": 1024 }
  }
  

• Key Properties & Validation Rules:
  • Format: Must be a valid JSON Object {} (not a primitive value or JSON Array).
  • Size Limit: Total serialized string length must be under 4,096 characters.
  • Cryptographically Signed: Because mtd is part of the header, it is signed and tamper-proof.
  • Non-Indexed: Fields inside mtd are application-level metadata and are not indexed for server-side database searching.

4.3 Forward Chaining & Stream Sequencing (cid and seq)

While --ref creates backward pointers to existing prior documents, the cid (Correlation ID) and seq (Sequence Number) fields provide forward pointers to group, thread, and order an ongoing series of documents where future document UIDs are not yet known at creation time:

• Use Cases: Multi-part document series (e.g. Part 1, Part 2, Part 3), ongoing public audit logs, live status feeds, or sequential incident response updates.
• CLI Flags:
  • --cid <CORRELATION_ID>: A unique correlation identifier string that ties all related documents in the stream together.
  • --seq <SEQUENCE_NUMBER>: A numeric sequence counter (e.g., 1, 2, 3 or a millisecond timestamp) defining the document’s chronological place in the sequence.

# Publishing Part 1 of a public incident report series
tsrct tdoc doc-create \
  --typ json \
  --cty application/json \
  --input incident-part1.json \
  --src <YOUR_ORG_UID> \
  --uid incident-20260901-pt1 \
  --cid "INC-20260901-NETWORK" \
  --seq 1 \
  --acl acl_pub \
  --lst true \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

Validation & Co-Dependency Rules:

As enforced by the Tsrct validation engine:

1. Strict Co-Dependency: cid and seq must always be used together. If cid is specified without seq, or seq without cid, the Tsrct API rejects the document with an api_header_fields_error.
2. cid Constraints: Must be an alphanumeric string between 1 and 1,024 characters long.
3. seq Constraints: Must be a valid 64-bit integer (Long) value.

4.4 Virtual Identifiers for Document Evolution (vid and ver)

Every published Tsrct document receives an immutable, permanent uid. When a document is updated (such as a new version of a public API schema, legal policy, or pricing sheet), the new revision receives its own distinct uid.

To allow external systems, permalinks, and consumers to always access the latest approved revision without breaking existing references, Tsrct provides Virtual IDs (vid) paired with Version numbers (ver):

• How Virtual IDs Work:
  • The vid acts as a stable, unchanging alias / pointer that resolves to the latest version of the document.
  • When clients request a document by its vid, the platform returns the latest version’s uid.
  • Each successive release shares the exact same vid but specifies a higher ver number.

graph TD
    VID["Virtual ID: 9000...009.terms-of-service (Stable Alias)"]
    VID -->|ver: 1| V1["UID: ...009.tos-2025-v1 (Initial Release)"]
    VID -->|ver: 2| V2["UID: ...009.tos-2026-v2 (Current Active Revision)"]
    V2 -.->|--ref| V1

Publishing Revisions with vid and ver:

# Publishing Version 1 (Initial Document)
tsrct tdoc doc-create \
  --typ json \
  --input terms-v1.json \
  --src <YOUR_ORG_UID> \
  --uid tos-2025-v1 \
  --vid terms-of-service \
  --ver 1 \
  --acl acl_pub \
  --lst true \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

# Publishing Version 2 (Updated Revision pointing back to v1)
tsrct tdoc doc-create \
  --typ json \
  --input terms-v2.json \
  --src <YOUR_ORG_UID> \
  --uid tos-2026-v2 \
  --vid terms-of-service \
  --ver 2 \
  --ref "<YOUR_ORG_UID>.tos-2025-v1" \
  --acl acl_pub \
  --lst true \
  --key <YOUR_KEY_ID> \
  --key-host gcp \
  --sig-key-resource <YOUR_GCP_KMS_SIGNATURE_KEY_RESOURCE_PATH>

Validation Rules for vid & ver:

1. Mandatory Version Pairing: Any document specifying a vid must also include ver.
2. Prefix Enforcement: The vid must begin with <YOUR_ORG_UID>. as its prefix.
3. Monotonically Increasing Versions: When updating an existing vid, the new version number must be strictly greater than the current version (ver_new > ver_existing). Re-using a previous version or attempting to decrement it will fail validation.
4. UID Syntax Compliance: The vid must conform to standard Tsrct UID character and format requirements.

5. Key CLI Flags Breakdown

6. Retrieving Public Documents

Because the document is public (acl_pub), no JWT, API key, or authorization header is required.

Method A: Using the Tsrct CLI

tsrct dl --uid <FULL_DOCUMENT_UID>

Method B: Using cURL or Standard HTTP Clients

Public documents can be inspected directly via standard HTTP GET requests:

1. Get the Full T-Doc (Header + Base64 Body + Signature):

   curl -X GET https://api.tsrct.io/<FULL_DOCUMENT_UID>/tdoc
   

2. Get the Raw Body Payload Only (JSON, text, or binary stream):

   curl -X GET https://api.tsrct.io/<FULL_DOCUMENT_UID>/body
   

3. Get the Decoded Header Metadata:

   curl -X GET https://api.tsrct.io/<FULL_DOCUMENT_UID>
   

4. Lookup by SHA-256 Hash:

   curl -X GET https://api.tsrct.io/sha/<SHA256_OF_PAYLOAD>
   

5. Resolve and Fetch Latest Revision via Virtual ID (vid):

   curl -X GET https://api.tsrct.io/<FULL_VIRTUAL_ID>/body
   

Method C: Viewing in a Web Browser

Navigate to:

https://tsrct.io/<FULL_DOCUMENT_UID>

The Tsrct web interface will display the document’s verification status, cryptographic metadata, publisher public key, and payload.

7. Public vs. Private Comparison Summary