Developer API — Ice Vault

01. Authentication Logic

# API_AUTHENTICATION_PROTOCOL

This module handles secure access to the Ice Vault.
All requests must include a valid session and CSRF token.

## QUICK_START
1. Request login page to initialize cookies.
GET:  /auth/login/

2. Submit credentials via POST.
POST: /auth/login/

3. Use the established session for subsequent API calls.
GET: /api/users/me/

## SECURITY_NOTICE
- Session TTL: 24 Hours
- Rate Limit: 100 req/min per IP
- Encryption: TLS 1.3 Required

-- System_v1.4.2_Stable

import requests

session = requests.Session()
LOGIN_URL = 'https://icevault.space/auth/login/'

# 1. Initialize session and get CSRF
session.get(LOGIN_URL)
csrf = session.cookies['csrftoken']

# 2. Authenticate
payload = {
    'username': 'EMAIL',
    'password': 'PASS',
    'csrfmiddlewaretoken': csrf
}
session.post(LOGIN_URL, data=payload, headers={'Referer': LOGIN_URL})

import axios from 'axios';
import { wrapper } from 'axios-cookiejar-support';
import { CookieJar } from 'tough-cookie';

// Maintain cookies across requests
const jar = new CookieJar();
const client = wrapper(axios.create({ jar }));

await client.post(url, new URLSearchParams({
    username,
    password,
    csrfmiddlewaretoken: csrf
}));

// Using java.net.http.HttpClient with CookieHandler
var client = HttpClient.newBuilder()
    .cookieHandler(new CookieManager())
    .build();

var postBody = "username=...&csrf=" + csrf;
var request = HttpRequest.newBuilder()
    .uri(URI.create(LOGIN_URL))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(BodyPublishers.ofString(postBody))
    .build();

02. Upload Protocol

# UPLOAD_PROCESS_SPECIFICATION

Files never touch our main application server.
This ensures maximum_privacy and upload_speed.

## DATA_STRUCTURE
- archive_size_kb: Integer (mandatory for S3 policy)
- storage_class: STANDARD | GLACIER_IR | DEEP_ARCHIVE
- content_type: MIME type of the file

## INTEGRITY_VERIFICATION
After S3 upload, the /confirm-upload/ endpoint triggers an
internal head_object check to verify ETag and file presence.

// Vault_Storage_Engine: v2.1

import requests, os

# 1. Initialize Upload
file_path = "data.zip"
payload = {
    "archive": {
        "archive_size_kb": os.path.getsize(file_path) // 1024,
        "archive_name": "backup.zip",
        "storage_class": "GLACIER_IR"
    }
}
res = session.post('/api/initiate-upload/', json=payload).json()

# 2. Direct S3 Streaming
with open(file_path, 'rb') as f:
    requests.post(
        res['archive']['url'],
        data=res['archive']['fields'],
        files={'file': f}
    )

# 3. Server-Side Confirmation
session.post('/api/confirm-upload/', json={"uuid": res['uuid']})

const formData = new FormData();

// 1. Populate S3 specific fields from res.fields
Object.entries(res.archive.fields).forEach(([k, v]) => {
    formData.append(k, v);
});

// 2. Attach file stream
formData.append('file', fs.createReadStream('archive.zip'));

await axios.post(res.archive.url, formData, {
    headers: formData.getHeaders()
});

// Using Apache HttpClient for MultiPart
HttpEntity entity = MultipartEntityBuilder.create()
    .addTextBody("key", s3Fields.get("key"))
    .addTextBody("policy", s3Fields.get("policy"))
    .addBinaryBody("file", new File("archive.zip"))
    .build();

HttpPost request = new HttpPost(s3Url);
request.setEntity(entity);

02. Multipart Upload Protocol

# MULTIPART_TRANSFER_SPEC

Large files are fragmented into chunks for reliability.
Direct-to-S3 PUT streaming bypasses application bottlenecks.

## CHUNK_STRATEGY
- chunk_size_kb: Recommended 51200 (50MB)
- archive_part_count: Total fragments calculated by client
- part_urls: Map of part numbers to presigned S3 URLs

## CONSOLIDATION
The /confirm-upload/ endpoint requires archive_hashes.
A map of {part_number: ETag} is mandatory to assemble the final object.

// Vault_Storage_Engine: v2.5 (Multipart Enabled)

import os, math, requests

# 1. Initialize Multipart Session
size = os.path.getsize("archive.zip")
chunk_size = 50 * 1024 * 1024 # 50MB
parts = math.ceil(size / chunk_size)

init_data = {
    "archive": {
        "archive_size_kb": size // 1024,
        "archive_part_count": parts,
        "chunk_size_kb": 10240
    }
}
res = session.post('/api/storage/initiate-upload/', json=init_data).json()

# 2. Upload Fragments
hashes = {}
with open("archive.zip", "rb") as f:
    for p_num, url in res["archive"]["part_urls"].items():
        f.seek((int(p_num) - 1) * chunk_size)
        data = f.read(chunk_size)

        # Direct PUT to S3
        put_res = requests.put(url, data=data)
        hashes[p_num] = put_res.headers.get("ETag")

# 3. Finalize and Assemble
session.post('/api/storage/confirm-upload/', json={
    "uuid": res["uuid"],
    "archive_hashes": hashes
})

System Restriction

Are you sure?

01. Authentication Logic

02. Upload Protocol

02. Multipart Upload Protocol

Cookie Protocol