# hcfs-shared

Shared types and utilities used across HCFS client and server components.

## Modules

| Module | Description |
|--------|-------------|
| `network` | API request/response types and manifest verification |
| `http` | HTTP client configuration and header parsing utilities |
| `utils` | Serialization helpers |

## Network Types

### Response Wrappers

```rust
// Generic response enum for all API endpoints
pub enum NetworkResponse<T> {
    Success(T),
    Conflict(ConflictResponse),
    Error(ErrorResponse),
}

// Type aliases for each endpoints
pub type DownloadResponse = NetworkResponse<DownloadResult>;
pub type UploadResponse = NetworkResponse<UploadResult>;
pub type DeleteResponse = NetworkResponse<DeleteResult>;
pub type GetStateResponse = NetworkResponse<GetStateResult>;
```

### Upload Types

```rust
pub struct UploadResult {
    pub upload_id: String,      // Storage backend identifier
    pub file_id: String,        // Hex-encoded path hash
    pub timestamp: i64,         // Unix timestamp
    pub revision_id: [u8; 32],  // Server-assigned revision
}

pub struct Manifest {
    pub user_id: String,
    pub version: String,
    pub file_id: String,
    pub ciphertext_hash: String,       // SHA256 of ciphertext
    pub size_bytes: u64,
    pub timestamp: i64,
    pub signature: Vec<u8>,            // Ed25519 signature
    pub signing_key: [u8; 32],         // Public key
    pub path_hash: [u8; 32],           // SHA256 of relative path
    pub salted_hash: [u8; 32],         // SHA256(user_id || plaintext)
    pub revision_seq: u64,             // Monotonic sequence
    pub base_revision_id: Option<[u8; 32]>,  // For optimistic concurrency
    pub encrypted_path: Vec<u8>,       // For path recovery
}
```

### Download Types

```rust
pub struct DownloadResult {
    pub revision_seq: u64,
    pub revision_id: [u8; 32],
    pub size_bytes: u64,
}
```

### State Types

```rust
pub struct GetStateResult {
    pub user_id: String,
    pub files: Vec<RemoteFileEntry>,
    pub total_count: u64,
    pub has_more: bool,       // Pagination indicator
    pub offset: u32,
    pub limit: u32,
}

pub struct RemoteFileEntry {
    pub path_hash: [u8; 32],
    pub salted_hash: [u8; 32],
    pub size_bytes: u64,
    pub revision_seq: u64,
    pub revision_id: [u8; 32],
    pub encrypted_path: Vec<u8>,
}

pub struct PaginationQuery {
    pub offset: Option<u32>,
    pub limit: Option<u32>,
}
```

### Error Types

```rust
pub struct ErrorResponse {
    pub error: String,    // Error code
    pub message: String,  // Human-readable message
}

pub struct ConflictResponse {
    pub error: String,
    pub message: String,
    pub current_revision_id: [u8; 32],
    pub current_revision_seq: u64,
}
```

## Manifest Verification

The `Manifest` type includes signature verification for ToS acceptance:

```rust
impl Manifest {
    /// Verify signature without checking ciphertext hash (streaming)
    pub fn verify_signature(&self) -> Result<()>;

    /// Verify signature and ciphertext hash (buffered)
    pub async fn verify_request(&self, ciphertext: &[u8]) -> Result<()>;
}
```

## HTTP Utilities

### Client Configuration

```rust
pub struct HttpClientConfig {
    pub timeout: Duration,              // Default: 5 minutes
    pub connect_timeout: Duration,      // Default: 30 seconds
    pub accept_invalid_certs: bool,     // Default: false
}

// Builder pattern
let config = HttpClientConfig::new()
    .with_timeout(Duration::from_secs(600))
    .with_accept_invalid_certs(true);

let client = build_http_client(&config)?;
```

### Header Parsing

```rust
// Parse u64 from header
let size = parse_header_u64(&headers, "X-Size-Bytes");

// Parse 32-byte array from hex-encoded header
let revision_id = parse_header_bytes32(&headers, "X-Revision-Id");

// Build authorization headers
let headers = build_auth_headers(
    Some("api-key"),
    Some("bearer-token"),
);
```
