@affectively/aeon 1.0.0 → 1.2.0

package/dist/crypto/index.d.cts

@@ -0,0 +1,407 @@
+/**
+ * Aeon Crypto Types
+ *
+ * Type definitions for cryptographic operations in Aeon.
+ * These are compatible with @affectively/ucan and @affectively/zk-encryption.
+ */
+/**
+ * Decentralized Identifier (DID)
+ * Format: did:method:identifier
+ */
+type DID = `did:${string}:${string}`;
+/**
+ * Supported signing algorithms
+ */
+type SigningAlgorithm = 'ES256' | 'Ed25519' | 'ES384' | 'ES512';
+/**
+ * Key pair for signing and verification
+ */
+interface KeyPair {
+    algorithm: SigningAlgorithm;
+    publicKey: JsonWebKey;
+    privateKey?: JsonWebKey;
+    fingerprint: string;
+}
+/**
+ * Identity representing a user or node
+ */
+interface Identity {
+    did: DID;
+    signingKey: KeyPair;
+    encryptionKey?: KeyPair;
+    createdAt: number;
+    displayName?: string;
+}
+/**
+ * UCAN Capability structure
+ */
+interface Capability {
+    can: string;
+    with: string;
+    constraints?: Record<string, unknown>;
+}
+/**
+ * UCAN Token payload
+ */
+interface UCANPayload {
+    iss: DID;
+    aud: DID;
+    exp: number;
+    nbf?: number;
+    iat?: number;
+    nonce?: string;
+    jti?: string;
+    att: Capability[];
+    prf?: string[];
+    fct?: Record<string, unknown>;
+}
+/**
+ * Parsed UCAN Token
+ */
+interface UCANToken {
+    payload: UCANPayload;
+    raw: string;
+    signature: Uint8Array;
+    algorithm: string;
+}
+/**
+ * UCAN verification result
+ */
+interface VerificationResult {
+    valid: boolean;
+    payload?: UCANPayload;
+    error?: string;
+    expired?: boolean;
+    shouldRotate?: boolean;
+    expiresIn?: number;
+}
+/**
+ * Encryption algorithms supported
+ */
+type EncryptionAlgorithm = 'ECIES-P256' | 'AES-256-GCM';
+/**
+ * HKDF domain separator categories
+ */
+type DomainCategory = 'default' | 'sync' | 'message' | 'api-key' | 'personal-data' | string;
+/**
+ * EC Key pair for ECDH operations
+ */
+interface ECKeyPair {
+    publicKey: JsonWebKey;
+    privateKey: JsonWebKey;
+    keyId: string;
+    createdAt: string;
+}
+/**
+ * Encrypted data envelope
+ */
+interface EncryptedPayload {
+    alg: EncryptionAlgorithm;
+    ct: string;
+    iv: string;
+    tag: string;
+    epk?: JsonWebKey;
+    category?: DomainCategory;
+    nonce?: string;
+    encryptedAt: number;
+}
+/**
+ * Decryption result
+ */
+interface DecryptionResult {
+    plaintext: Uint8Array;
+    category?: DomainCategory;
+    encryptedAt: number;
+}
+/**
+ * Aeon encryption mode
+ */
+type AeonEncryptionMode = 'none' | 'transport' | 'at-rest' | 'end-to-end';
+/**
+ * Aeon sync capability namespace
+ */
+declare const AEON_CAPABILITIES: {
+    readonly SYNC_READ: "aeon:sync:read";
+    readonly SYNC_WRITE: "aeon:sync:write";
+    readonly SYNC_ADMIN: "aeon:sync:admin";
+    readonly NODE_REGISTER: "aeon:node:register";
+    readonly NODE_HEARTBEAT: "aeon:node:heartbeat";
+    readonly REPLICATE_READ: "aeon:replicate:read";
+    readonly REPLICATE_WRITE: "aeon:replicate:write";
+    readonly STATE_READ: "aeon:state:read";
+    readonly STATE_WRITE: "aeon:state:write";
+    readonly STATE_RECONCILE: "aeon:state:reconcile";
+};
+type AeonCapability = (typeof AEON_CAPABILITIES)[keyof typeof AEON_CAPABILITIES];
+/**
+ * Crypto configuration for Aeon
+ */
+interface AeonCryptoConfig {
+    /** Default encryption mode for sync messages */
+    defaultEncryptionMode: AeonEncryptionMode;
+    /** Require all messages to be signed */
+    requireSignatures: boolean;
+    /** Require UCAN capability verification */
+    requireCapabilities: boolean;
+    /** Allowed signature algorithms */
+    allowedSignatureAlgorithms: string[];
+    /** Allowed encryption algorithms */
+    allowedEncryptionAlgorithms: string[];
+    /** UCAN audience DID for verification */
+    ucanAudience?: string;
+    /** Session key expiration (ms) */
+    sessionKeyExpiration?: number;
+}
+/**
+ * Default crypto configuration
+ */
+declare const DEFAULT_CRYPTO_CONFIG: AeonCryptoConfig;
+/**
+ * Authenticated sync message fields
+ */
+interface AuthenticatedMessageFields {
+    /** Sender DID */
+    senderDID?: string;
+    /** Receiver DID */
+    receiverDID?: string;
+    /** UCAN token for capability verification */
+    ucan?: string;
+    /** Message signature (base64url) */
+    signature?: string;
+    /** Whether payload is encrypted */
+    encrypted?: boolean;
+}
+/**
+ * Secure sync session
+ */
+interface SecureSyncSession {
+    id: string;
+    initiator: string;
+    participants: string[];
+    sessionKey?: Uint8Array;
+    encryptionMode: AeonEncryptionMode;
+    requiredCapabilities: string[];
+    status: 'pending' | 'active' | 'completed' | 'failed';
+    startTime: string;
+    endTime?: string;
+}
+/**
+ * Node with identity information
+ */
+interface SecureNodeInfo {
+    id: string;
+    did?: string;
+    publicSigningKey?: JsonWebKey;
+    publicEncryptionKey?: JsonWebKey;
+    capabilities?: string[];
+    lastSeen?: number;
+}
+/**
+ * Capability verification result
+ */
+interface AeonCapabilityResult {
+    authorized: boolean;
+    error?: string;
+    issuer?: string;
+    grantedCapabilities?: Array<{
+        can: string;
+        with: string;
+    }>;
+}
+/**
+ * Signed data envelope for sync operations
+ */
+interface SignedSyncData<T = unknown> {
+    payload: T;
+    signature: string;
+    signer: string;
+    algorithm: string;
+    signedAt: number;
+}
+
+/**
+ * Aeon Crypto Provider Interface
+ *
+ * Abstract interface for cryptographic operations.
+ * Aeon core remains zero-dependency - crypto is injected through this interface.
+ */
+
+/**
+ * Abstract crypto provider interface
+ *
+ * Implementations use @affectively/ucan and @affectively/zk-encryption
+ * or other compatible libraries.
+ */
+interface ICryptoProvider {
+    /**
+     * Generate a new identity with DID and key pairs
+     */
+    generateIdentity(displayName?: string): Promise<{
+        did: string;
+        publicSigningKey: JsonWebKey;
+        publicEncryptionKey?: JsonWebKey;
+    }>;
+    /**
+     * Get the local identity's DID
+     */
+    getLocalDID(): string | null;
+    /**
+     * Export local identity's public info for sharing
+     */
+    exportPublicIdentity(): Promise<SecureNodeInfo | null>;
+    /**
+     * Register a known remote node's public keys
+     */
+    registerRemoteNode(node: SecureNodeInfo): Promise<void>;
+    /**
+     * Get a remote node's public key
+     */
+    getRemotePublicKey(did: string): Promise<JsonWebKey | null>;
+    /**
+     * Sign data with local identity's private key
+     */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign structured data and wrap in SignedSyncData envelope
+     */
+    signData<T>(data: T): Promise<SignedSyncData<T>>;
+    /**
+     * Verify a signature from a remote node
+     */
+    verify(did: string, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+    /**
+     * Verify a SignedSyncData envelope
+     */
+    verifySignedData<T>(signedData: SignedSyncData<T>): Promise<boolean>;
+    /**
+     * Encrypt data for a recipient
+     */
+    encrypt(plaintext: Uint8Array, recipientDID: string): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+        encryptedAt: number;
+    }>;
+    /**
+     * Decrypt data
+     */
+    decrypt(encrypted: {
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+    }, senderDID?: string): Promise<Uint8Array>;
+    /**
+     * Derive or get a session key for communication with a peer
+     */
+    getSessionKey(peerDID: string): Promise<Uint8Array>;
+    /**
+     * Encrypt with a session key
+     */
+    encryptWithSessionKey(plaintext: Uint8Array, sessionKey: Uint8Array): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        encryptedAt: number;
+    }>;
+    /**
+     * Decrypt with a session key
+     */
+    decryptWithSessionKey(encrypted: {
+        ct: string;
+        iv: string;
+        tag: string;
+    }, sessionKey: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Create a UCAN token
+     */
+    createUCAN(audience: string, capabilities: Array<{
+        can: string;
+        with: string;
+    }>, options?: {
+        expirationSeconds?: number;
+        proofs?: string[];
+    }): Promise<string>;
+    /**
+     * Verify a UCAN token
+     */
+    verifyUCAN(token: string, options?: {
+        expectedAudience?: string;
+        requiredCapabilities?: Array<{
+            can: string;
+            with: string;
+        }>;
+    }): Promise<AeonCapabilityResult>;
+    /**
+     * Delegate capabilities
+     */
+    delegateCapabilities(parentToken: string, audience: string, capabilities: Array<{
+        can: string;
+        with: string;
+    }>, options?: {
+        expirationSeconds?: number;
+    }): Promise<string>;
+    /**
+     * Compute hash of data
+     */
+    hash(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Generate random bytes
+     */
+    randomBytes(length: number): Uint8Array;
+    /**
+     * Check if crypto is properly initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Null crypto provider for when crypto is disabled
+ *
+ * All operations either throw or return permissive defaults.
+ */
+declare class NullCryptoProvider implements ICryptoProvider {
+    private notConfiguredError;
+    generateIdentity(): Promise<{
+        did: string;
+        publicSigningKey: JsonWebKey;
+        publicEncryptionKey?: JsonWebKey;
+    }>;
+    getLocalDID(): string | null;
+    exportPublicIdentity(): Promise<SecureNodeInfo | null>;
+    registerRemoteNode(): Promise<void>;
+    getRemotePublicKey(): Promise<JsonWebKey | null>;
+    sign(): Promise<Uint8Array>;
+    signData<T>(_data: T): Promise<SignedSyncData<T>>;
+    verify(): Promise<boolean>;
+    verifySignedData(): Promise<boolean>;
+    encrypt(): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        epk?: JsonWebKey;
+        encryptedAt: number;
+    }>;
+    decrypt(): Promise<Uint8Array>;
+    getSessionKey(): Promise<Uint8Array>;
+    encryptWithSessionKey(): Promise<{
+        alg: string;
+        ct: string;
+        iv: string;
+        tag: string;
+        encryptedAt: number;
+    }>;
+    decryptWithSessionKey(): Promise<Uint8Array>;
+    createUCAN(): Promise<string>;
+    verifyUCAN(): Promise<AeonCapabilityResult>;
+    delegateCapabilities(): Promise<string>;
+    hash(): Promise<Uint8Array>;
+    randomBytes(length: number): Uint8Array;
+    isInitialized(): boolean;
+}
+
+export { AEON_CAPABILITIES, type AeonCapability, type AeonCapabilityResult, type AeonCryptoConfig, type AeonEncryptionMode, type AuthenticatedMessageFields, type Capability, DEFAULT_CRYPTO_CONFIG, type DID, type DecryptionResult, type DomainCategory, type ECKeyPair, type EncryptedPayload, type EncryptionAlgorithm, type ICryptoProvider, type Identity, type KeyPair, NullCryptoProvider, type SecureNodeInfo, type SecureSyncSession, type SignedSyncData, type SigningAlgorithm, type UCANPayload, type UCANToken, type VerificationResult };