Atlas Envelope

An envelope is a self-describing, signed data record. It carries its Schema.org type, authorship proof, and enough context for any app to validate it without prior coordination.

Envelopes are the atomic unit of data in Atlas. Everything that enters a registry, travels between peers, or gets ranked by a Guide is an envelope.

Structure

At minimum an envelope contains a signature and a data payload. The data field holds a Schema.org object with @context and @type.

{
  "signature": "<falcon-signature-base64>",
  "data": {
    "@context": "https://schema.org",
    "@type": "Message",
    "text": "Hello, Atlas.",
    "dateSent": "2026-04-02T12:00:00.000Z"
  }
}

Presented Envelope

When a registry returns an envelope it attaches computed metadata: the envelope hash, content hash, author identity, verification status, and the timestamp when it was received.

{
  "hash": "<blake3-hex>",
  "contentHash": "<sha256-cid>",
  "authorHash": "<blake3-of-public-key>",
  "authorPublicKey": "<falcon-public-key-base64>",
  "author": {
    "verificationStatus": "VERIFIED",
    "fairShares": 100,
    "competences": [],
    "createdAt": "2026-03-01T00:00:00.000Z"
  },
  "signature": "<falcon-signature-base64>",
  "data": {
    "@context": "https://schema.org",
    "@type": "Message",
    "text": "Hello, Atlas.",
    "dateSent": "2026-04-02T12:00:00.000Z"
  },
  "createdAt": "2026-04-02T12:00:01.000Z"
}

Hashing

The envelope hash is computed over a canonical object using safe-stable-stringify for deterministic key ordering, then hashed with Blake3. Null fields are included explicitly — omitting them would change the hash.

// Canonical object — deterministically serialized with safe-stable-stringify
const canonical = {
  author: { PublicKey: authorPublicKey },
  contentHash,          // sha256-CID of data field
  data,                 // the Schema.org payload
  encryptedData: null,  // or base64 string
  encryptionNonce: null,
  expiresAt: null,      // or ISO string
  kemCiphertext: null,
  recipientHash: null,  // or blake3 hash of recipient key
};

const envelopeHash = blake3(safeStableStringify(canonical));

Signing

The author signs the Blake3 hash bytes with their Falcon private key (or a delegated key, accompanied by a Permit proof). The signature and data are submitted together — the registry recomputes the hash and verifies before storing.

import { signEnvelope } from "@app_/crypto";

const { signature, contentHash, hash } = await signEnvelope({
  data: {
    "@context": "https://schema.org",
    "@type": "Message",
    "text": "Hello, Atlas.",
    "dateSent": new Date().toISOString(),
  },
  authorPublicKey: session.publicKey,
  privateKey: session.delegatedPrivateKey,
});

Verification

Any party can verify an envelope. If the proofs include a Permit, the delegated key is extracted and verified against the author's root public key. The envelope hash is recomputed and checked against the signature. Expired envelopes are rejected.

import { verifyEnvelope } from "@app_/crypto";

// Returns { contentHash, hash } on success, throws on failure.
// If proofs contain a Permit, the delegated key is extracted
// and verified against the author's root public key.
const result = await verifyEnvelope(envelope, authorPublicKey, proofs);

Schema.org Types

The data.@type field determines how an envelope is indexed, queried, and processed. Registries specialize by type. Atlas extends Schema.org with additionalType for protocol-specific subtypes.

Encryption

Envelopes support end-to-end encryption. The data field is replaced with encryptedData, and the recipient is identified by a hash of their public key. Encryption uses ML-KEM (X-Wing) for key encapsulation and AES-256-GCM for the payload.

{
  "signature": "<falcon-signature-base64>",
  "data": null,
  "recipientHash": "<blake3-of-recipient-public-key>",
  "kemCiphertext": "<ml-kem-encapsulated-key-base64>",
  "encryptedData": "<aes-256-gcm-ciphertext-base64>",
  "encryptionNonce": "<aes-gcm-nonce-base64>",
  "expiresAt": "2026-05-02T12:00:00.000Z"
}

Linking

Envelopes can reference other envelopes via the linksTo field — an array of envelope hashes. Links are directional and stored as relations. Only the author can create links from their envelopes. Targets must already exist.

{
  "signature": "...",
  "data": {
    "@context": "https://schema.org",
    "@type": "Comment",
    "text": "Great post."
  },
  "linksTo": ["<hash-of-parent-envelope>"]
}

Creating Envelopes

Envelopes are submitted in batches via POST /envelopes. The registry verifies each signature, checks for duplicates, validates links, and runs type-specific processors before storing.

import { createEnvelopeMethods } from "@app_/registry-client";

const { createSignedEnvelopes } = createEnvelopeMethods(buildHeaders);

// Signs and submits a batch of envelopes in one call.
const { hashes } = await createSignedEnvelopes(registryUrl, [
  { data, authorPublicKey, privateKey },
]);

Querying Envelopes

Registries expose envelopes through typed endpoints with Prisma-style filtering. Query by Schema.org type, author, time range, or fetch a single envelope by hash.

GET /envelopes/type/message?take=20&skip=0 HTTP/2.0

GET /envelopes?where={"data":{"path":["@type"],"equals":"Article"}} HTTP/2.0

GET /envelopes/<hash> HTTP/2.0

Blobs

Binary attachments (images, files) are uploaded separately to /blobs via chunked upload. The registry returns a CID, size, and encoding format. Envelopes reference blobs through contentUrl fields in their data payload (e.g. ImageObject attachments on a Message).