> ## Documentation Index
> Fetch the complete documentation index at: https://docs-terra.withunify.org/llms.txt
> Use this file to discover all available pages before exploring further.

# File Storage

> How Terra securely stores uploaded files with private buckets and signed URLs

# File Storage

> All files are stored in private Supabase Storage buckets. Zero public URLs.

## Security Model

Government applicants upload sensitive documents: IDs, tax returns, medical records. These must **never** be publicly accessible.

```mermaid theme={null}
flowchart LR
    Upload[Upload] --> Bucket[(Private Bucket)]
    Bucket -->|service_role only| SignedURL[Signed URL]
    SignedURL -->|60s expiry| Admin[Admin View]
```

## Storage Structure

Files are stored with unpredictable paths:

```
form-uploads/
  {formId}/
    {uuid}/
      {sanitized-filename}
```

The UUID prevents path enumeration attacks.

## Upload Flow

```typescript theme={null}
// 1. Request signed upload URL
const { data } = await supabaseAdmin.storage
  .from("form-uploads")
  .createSignedUploadUrl(path);

// 2. Client uploads directly to signed URL
await fetch(data.signedUrl, {
  method: "PUT",
  body: file,
});
```

## Download Flow (Admin Only)

```typescript theme={null}
// Generate short-lived download URL
const { data } = await supabaseAdmin.storage
  .from("form-uploads")
  .createSignedUrl(path, 60); // 60 second expiry

return data.signedUrl;
```

## Google Drive Integration

For forms with Google Drive configured, files go to Drive instead:

```typescript theme={null}
if (form.google_drive_folder_id) {
  // Upload to Drive via service account
  const fileId = await uploadToDrive(file, folderId);
  return { provider: "drive", fileId };
} else {
  // Upload to Supabase
  await uploadToSupabase(file, path);
  return { provider: "supabase", path };
}
```

***

<CardGroup cols={2}>
  <Card title="Google Drive" icon="google-drive" href="/integrations/google-drive">
    Drive integration setup
  </Card>

  <Card title="Encryption" icon="lock" href="/core-systems/data/encryption-pii">
    PII protection
  </Card>
</CardGroup>