QuDEFENSE API (0.1.0)

Compute SHA-256 fingerprint for a file and its metadata from a provided S3 presigned URL. Logs the transaction to the Algorand blockchain. It's important to retain the returned file_id for future use.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

The metadata includes:
- File name
- File modified date
- File size
- File type

The fingerprint and metadata are stored on the Algorand blockchain for permanent record.

Example request:
```json
{
    "s3_presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/file?AWSAccessKeyId=...",
    "tags": {
        "department": "finance",
        "document_type": "invoice"
    }
}
```

Example response:
```json
{
    "status": "success",
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "metadata_hash": "7c4a8d09ca3762af61e59520943dc26494f8941b",
    "file_metadata": {
        "file_name": "invoice.pdf",
        "file_size": 12345,
        "file_type": "application/pdf",
        "modified_date": "2024-01-01T12:00:00Z"
    },
    "blockchain_app_id": "123456789",
    "blockchain_txid": "ABCDEF123456789",
    "file_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

Asynchronously compute SHA-256 fingerprint for a file from an S3 presigned URL. Returns a job ID that can be used to check the fingerprint status.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

The fingerprint process:
1. Downloads the file from the provided S3 presigned URL
2. Computes the SHA-256 hash of the file
3. Creates metadata including file name, size, and type
4. Stores the fingerprint and metadata on the Algorand blockchain
5. Returns a job ID for tracking progress

Example request:
```json
{
    "s3_presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/file?AWSAccessKeyId=...",
    "tags": {
        "department": "finance",
        "document_type": "invoice"
    }
}
```

Example response:
```json
{
    "status": "accepted",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "File fingerprinting started"
}
```

Use the returned job_id with the /jobs/{job_id} endpoint to check the status.

Verify a file's fingerprint against the stored SHA-256 fingerprint on the Algorand blockchain. Logs the attempt to the blockchain.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

This endpoint:
1. Computes the SHA-256 hash of the provided file
2. Retrieves the stored hash from the blockchain
3. Compares the hashes to verify file integrity
4. Logs the verification attempt to the blockchain

Example request:
```json
{
    "s3_presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/file?AWSAccessKeyId=...",
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "tags": {
        "verification_reason": "annual_audit",
        "auditor": "john_doe"
    }
}
```

Example response:
```json
{
    "status": true,
    "fingerprint_verify_result": "MATCH",
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "bytes_processed": 12345,
    "blockchain_app_id": "123456789",
    "blockchain_txid": "ABCDEF123456789",
    "file_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

Asynchronously verify a file's fingerprint against the stored SHA-256 fingerprint on the Algorand blockchain. Returns a job ID that can be used to check the verification status.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

The verification process:
1. Downloads the file from the provided S3 presigned URL
2. Computes the SHA-256 hash of the file
3. Retrieves the stored hash from the blockchain
4. Compares the hashes to verify file integrity
5. Logs the verification attempt to the blockchain
6. Returns a job ID for tracking progress

Example request:
```json
{
    "s3_presigned_url": "https://your-bucket.s3.amazonaws.com/path/to/file?AWSAccessKeyId=...",
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "tags": {
        "verification_reason": "annual_audit",
        "auditor": "john_doe"
    }
}
```

Example response:
```json
{
    "status": "accepted",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "File verification started"
}
```

Use the returned job_id with the /jobs/{job_id} endpoint to check the status.

Get the current status and details of a job by its ID.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

The response includes:
- Job status (pending, processing, completed, failed)
- Progress percentage
- Bytes processed
- Result data (if completed)
- Error message (if failed)
- Timing information (requested, started, completed)

Example response for a completed fingerprint job:
```json
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4",
    "status": "completed",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:05Z",
    "job_type": "fingerprint",
    "error_message": null,
    "result_data": {
        "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "metadata_hash": "7c4a8d09ca3762af61e59520943dc26494f8941b",
        "blockchain_app_id": "123456789",
        "blockchain_txid": "ABCDEF123456789",
        "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4",
        "file_metadata": {
            "file_name": "invoice.pdf",
            "modified_date": "2024-01-01T12:00:00Z",
            "file_type": "application/pdf"
        }
    },
    "progress_percentage": 100,
    "bytes_processed": 12345,
    "requested_datetime": "2024-01-01T12:00:00Z",
    "complete_datetime": "2024-01-01T12:00:05Z"
}
```

Example response for a completed verify job:
```json
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4",
    "status": "completed",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:05Z",
    "job_type": "verify",
    "error_message": null,
    "result_data": {
        "fingerprint_verify_result": "MATCH",
        "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "bytes_processed": 12345,
        "blockchain_app_id": "123456789",
        "blockchain_txid": "ABCDEF123456789",
        "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4"
    },
    "progress_percentage": 100,
    "bytes_processed": 12345,
    "requested_datetime": "2024-01-01T12:00:00Z",
    "complete_datetime": "2024-01-01T12:00:05Z"
}
```

List jobs with optional filtering by file_id and status.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

Query Parameters:
- file_id: Filter jobs by file ID (optional)
- status: Filter jobs by status (pending, processing, completed, failed) (optional)
- limit: Maximum number of jobs to return (default: 10)
- offset: Number of jobs to skip for pagination (default: 0)

Example response:
```json
{
    "jobs": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4",
            "status": "completed",
            "created_at": "2024-01-01T12:00:00Z",
            "updated_at": "2024-01-01T12:00:05Z",
            "job_type": "fingerprint",
            "error_message": null,
            "result_data": {
                "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "metadata_hash": "7c4a8d09ca3762af61e59520943dc26494f8941b",
                "blockchain_app_id": "123456789",
                "blockchain_txid": "ABCDEF123456789",
                "file_id": "86d51ec5-75b3-4612-8a02-a8564d9888e4",
                "file_metadata": {
                    "file_name": "invoice.pdf",
                    "modified_date": "2024-01-01T12:00:00Z",
                    "file_type": "application/pdf"
                }
            },
            "progress_percentage": 100,
            "bytes_processed": 12345,
            "requested_datetime": "2024-01-01T12:00:00Z",
            "complete_datetime": "2024-01-01T12:00:05Z"
        }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
}
```

Search for previously fingerprinted files based on various criteria with pagination.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

Search criteria include:
- Date range (fingerprint date or verification date)
- Verification status (verified at least once, has mismatches)
- Tags (key-value pairs)
- Blockchain app ID
- IP address

Example request:
```
GET /v1/files/search?start_date=2024-01-01&end_date=2024-12-31&date_type=fingerprint&verified_at_least_once=true&tag_key=department&tag_value=finance&page=1&page_size=20&sort_order=FINGERPRINT_DATE_DESC
```

Example response:
```json
{
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_pages": 5,
    "files": [
        {
            "file_id": "550e8400-e29b-41d4-a716-446655440000",
            "file_name": "invoice.pdf",
            "file_path": "path/to/file",
            "file_size": 12345,
            "storage_provider": "S3",
            "storage_bucket_name": "my-bucket",
            "fingerprint_requested_datetime": "2024-01-01T12:00:00Z",
            "fingerprint_start_datetime": "2024-01-01T12:00:01Z",
            "fingerprint_complete_datetime": "2024-01-01T12:00:05Z",
            "blockchain_provider": "Algorand",
            "blockchain_app_id": 123456789,
            "api_client_id": "client123",
            "tags": {
                "department": "finance",
                "document_type": "invoice"
            }
        }
    ]
}
```

Fetches all data associated with a previously fingerprinted file. For blockchain direct information, see the Get blockchain history API call.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

This endpoint returns comprehensive information about a file, including:
- Basic file information (name, size, path)
- Storage details (provider, bucket)
- Fingerprint timestamps
- Blockchain information
- Tags
- Verification history

Example request:
```
GET /v1/files/550e8400-e29b-41d4-a716-446655440000
```

Example response:
```json
{
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "invoice.pdf",
    "file_path": "path/to/file",
    "file_size": 12345,
    "storage_provider": "S3",
    "storage_bucket_name": "my-bucket",
    "fingerprint_requested_datetime": "2024-01-01T12:00:00Z",
    "fingerprint_start_datetime": "2024-01-01T12:00:01Z",
    "fingerprint_complete_datetime": "2024-01-01T12:00:05Z",
    "blockchain_provider": "Algorand",
    "blockchain_app_id": 123456789,
    "api_client_id": "client123",
    "tags": {
        "department": "finance",
        "document_type": "invoice"
    },
    "fingerprint_verification_history": [
        {
            "timestamp": "2024-01-02T12:00:00Z",
            "status": "MATCH",
            "verifier": "john_doe"
        }
    ]
}
```

Returns the complete blockchain history for a fingerprinted file.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

This endpoint provides:
- Contract information (creator, creation date)
- Global state (file hash, metadata hash)
- Complete verification history

Example request:
```
GET /v1/files/550e8400-e29b-41d4-a716-446655440000/blockchain-history
```

Example response:
```json
{
    "app_id": 123456789,
    "contract_info": {
        "creator_address": "ABCDEF123456789",
        "created_at": "2024-01-01T12:00:00Z",
        "creation_transaction_id": "TX123456789",
        "is_deleted": false
    },
    "global_state": {
        "fh": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "mh": "7c4a8d09ca3762af61e59520943dc26494f8941b"
    },
    "verification_history": [
        {
            "id": "ver123",
            "timestamp": 1704115200,
            "status": "MATCH",
            "result": "SUCCESS",
            "attempted_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "transaction_id": "TX987654321"
        }
    ]
}
```

Useful for testing connection to the QuDefense Core API. Requires authentication.

Required Headers:
- qudefense-client-id: Your client ID for authentication
- qudefense-secret-access-key: Your secret access key for authentication

Returns a simple welcome message if authentication is successful.

Example response:
```json
{
    "msg": "Congratulations! You've connected to the QuDefense Core API"
}
```