Validators — Atlas Protocol Docs

@app_/validators

Zod schema definitions for all Atlas Protocol data structures. Provides runtime type validation and TypeScript type inference for envelopes, proofs, identity, registry configuration, and Schema.org-based types.

Module structure

Import path	Contents
atlas-protocol/*	Envelope, header, and proof schemas
custodian/*	Identity, session, and PoW API schemas
registry/*	DataCatalog, setup, storage config schemas
schema-org/*	Schema.org-based types (Person, BuyAction, etc.)

Envelope schemas

Core envelope types used across the protocol. SignedEnvelope is the base, CreateEnvelope adds link references for publishing, and PresentedEnvelope is what registries return with full metadata.

// atlas-protocol/create-envelope.schema.ts
import type { CreateEnvelope, SignedEnvelope } from '@app_/validators/atlas-protocol/create-envelope.schema';

// SignedEnvelope — base envelope structure
type SignedEnvelope = {
  signature: string;
  data: unknown;
  expiresAt?: string;
  recipientKeyId?: string;
  kemCiphertext?: string;
  encryptedData?: string;
  encryptionNonce?: string;
};

// CreateEnvelope — extends with optional link references
type CreateEnvelope = SignedEnvelope & {
  linksTo?: string[];  // hashes of related envelopes
};

// atlas-protocol/presented-envelope.schema.ts
type PresentedEnvelope = {
  hash: string;
  contentHash: string;
  authorHash: string;
  author: {
    verificationStatus: string;
    fairShares: number;
    competences: string[];
    dataFidelity: string[];
  };
  authorPublicKey: string;
  data: unknown;
  signature: string;
  createdAt: string;
  expiresAt?: string;
  recipientKeyId?: string;
  kemCiphertext?: string;
  encryptedData?: string;
  encryptionNonce?: string;
};

Authentication headers

// atlas-protocol/headers.schema.ts
import { atlasIdentityHeaderSchema, atlasProofsHeaderSchema } from '@app_/validators/atlas-protocol/headers.schema';

// Validates a Falcon-1024 public key in base64
atlasIdentityHeaderSchema.parse(publicKey);

// Validates JSON string containing array of proofs
atlasProofsHeaderSchema.parse(proofsJsonString);

Proof schemas

Proof of Work and Permit (delegated key) proofs. Both wrap Schema.org CreativeWork types with Atlas-specific additional types.

// schema-org/proof-of-work/proof-of-work.schema.ts
type ProofOfWork = {
  data: {
    '@context': 'https://schema.org';
    '@type': 'CreativeWork';
    additionalType: 'atlas:proofOfWork';
    identifier: { propertyID: 'atlas'; value: string };  // 32-char hex nonce
    additionalProperty: [
      { name: 'validFrom'; value: string },
      { name: 'validUntil'; value: string },
    ];
  };
  signature: string;
};

// schema-org/permit/permit.schema.ts
type PermitProof = {
  data: {
    '@context': 'https://schema.org';
    '@type': 'CreativeWork';
    additionalType: 'atlas:delegatedKey';
    identifier: { propertyID: 'atlas'; value: string };  // delegated public key
    validFrom?: string;
    validUntil?: string;
  };
  signature: string;
};

Identity & Custodian schemas

// custodian/identity.schema.ts
type BootstrapIdentityBody =
  | { mode: 'generate' }
  | { mode: 'import'; signingKeys: { publicKey: string; privateKey: string } };

type BootstrapIdentityResponse = {
  ok: boolean;
  publicKey: string;
};

type IdentitySessionResponse = {
  publicKey: string;
  publicEncryptionKey?: string;
  delegatedPrivateKey: string;
  proofs: Array<ProofOfWork | PermitProof>;
  preferences: PreferencesConfig;
};

type PreferencesConfig = {
  theme?: string;
  language?: string;
  guides: RegistryEntry[];
  shelters: RegistryEntry[];
};

Registry schemas

Registry configuration and DataCatalog — the self-describing envelope that registries publish to announce their capabilities, storage policies, and operator identity.

// registry/data-catalog.schema.ts
type RegistryDataCatalog = {
  '@context': 'https://schema.org';
  '@type': 'DataCatalog';
  additionalType: 'atlas:registry';
  url: string;
  sameAs: string[];
  description?: string;
  about: string[];   // scope types
  publisher: {
    member: Array<{
      '@type': 'OrganizationRole';
      member: { identifier: { value: string } };  // operator hash
      roleName: 'operator';
    }>;
  };
  storage: StorageConfig;
  bridges: BridgesConfig;
};

// registry/api.schema.ts
type SetupStatus = {
  isSetupComplete: boolean;
  isRegistryLocked: boolean;
  isOperatorAuthorized: boolean;
  canSetupOperator: boolean;
  canRecoverOperator: boolean;
};

Schema.org types

// schema-org types available in validators:
// - PersonNameBroadcast    — Identity name announcements
// - TrustReview            — Trust allocation ratings
// - MoneyTransfer          — FairShares transfers
// - BuyActionQueryUnits    — Buy query access
// - BuyActionShelter       — Buy shelter (hosting) lease
// - IdentityVerificationCredential — Identity verification
// - ApplyActionIdentityVerification — Request identity verification

import type { MoneyTransfer } from '@app_/validators/schema-org/money-transfer/money-transfer.schema';
import type { TrustReview } from '@app_/validators/schema-org/person/person-trust-allocation.schema';