Authentication

Comprehensive Ed25519-based cryptographic authentication system that ensures data integrity and access control across Eidetica's distributed architecture.

Overview

Eidetica implements mandatory authentication for all entries - there are no unsigned entries in the system. Every operation requires valid Ed25519 signatures, providing strong guarantees about data authenticity and enabling sophisticated access control in decentralized environments.

The authentication system is deeply integrated with the core database, not merely a consumer of the API. This tight integration enables efficient validation, deterministic conflict resolution during network partitions, and preservation of historical validity.

Architecture

Storage Location: Authentication configuration resides in the special _settings.auth store of each Database, using Doc CRDT for deterministic conflict resolution.

Validation Component: The AuthValidator provides centralized entry validation with performance-optimized caching.

Signature Format: All entries include authentication information in their structure:

{
  "auth": {
    "sig": "ed25519_signature_base64_encoded",
    "key": "KEY_NAME_OR_DELEGATION_PATH"
  }
}

Permission Hierarchy

Three-tier permission model with integrated priority system:

Permission	Settings Access	Key Management	Data Write	Data Read	Priority
Admin	✓	✓	✓	✓	0-2^32
Write	✗	✗	✓	✓	0-2^32
Read	✗	✗	✗	✓	None

Priority Semantics:

Lower numbers = higher priority (0 is highest)
Admin/Write permissions include u32 priority value
Keys can only modify other keys with equal or lower priority
Priority affects administrative operations, NOT CRDT merge resolution

Key Management

Direct Keys

Ed25519 public keys stored directly in the database's _settings.auth:

{
  "_settings": {
    "auth": {
      "KEY_LAPTOP": {
        "pubkey": "ed25519:BASE64_PUBLIC_KEY",
        "permissions": "write:10",
        "status": "active"
      }
    }
  }
}

Key Lifecycle

Keys transition between two states:

Active: Can create new entries, all operations permitted
Revoked: Cannot create new entries, historical entries remain valid

This design preserves the integrity of historical data while preventing future use of compromised keys.

Wildcard Keys

Special * key enables public access:

Can grant any permission level (read, write, or admin)
Commonly used for world-readable databases
Subject to same revocation mechanisms as regular keys

Delegation System

Databases can delegate authentication to other databases, enabling powerful authentication patterns without granting administrative privileges on the delegating database.

Core Concepts

Delegated Database References: Any database can reference another database as an authentication source:

{
  "_settings": {
    "auth": {
      "user@example.com": {
        "permission-bounds": {
          "max": "write:15",
          "min": "read" // optional
        },
        "database": {
          "root": "TREE_ROOT_ID",
          "tips": ["TIP_ID_1", "TIP_ID_2"]
        }
      }
    }
  }
}

Permission Clamping

Delegated permissions are constrained by bounds:

max: Maximum permission level (required)
min: Minimum permission level (optional)
Effective permission = clamp(delegated_permission, min, max)
Priority derives from the effective permission after clamping

Delegation Chains

Multi-level delegation supported with permission clamping at each level:

{
  "auth": {
    "key": [
      { "key": "org_tree", "tips": ["tip1"] },
      { "key": "team_tree", "tips": ["tip2"] },
      { "key": "ACTUAL_KEY" }
    ]
  }
}