Storage API 설정
Storage API는 소비 프로젝트에 R2/S3 credential을 주지 않고 업로드·조회·temporary URL·public URL을 제공하는 서버용 object storage gateway입니다.
설정 순서
- Provider Credential: R2/S3 access credential을 등록합니다. 이 값은 서버에서만 암호화 저장되며 binding에 반드시 연결해야 합니다.
- Bucket Binding: bucket alias, 실제 bucket name,
private또는publicvisibility를 등록합니다. public binding은 custom URL도 필수입니다. - Token grant: Storage API token에 사용 가능한 binding을 선택합니다. token에는 allowed binding ID만 저장하며 기본 bucket이나 별도 public-write 토글은 없습니다.
- Request visibility: 소비 서버가
visibility=private|public을 보냅니다.bucketalias는 특정 grant를 명시해야 할 때만 보냅니다.
자동 선택 규칙
bucket을 생략하면 Storage API가 token의 허용 binding 중 요청 visibility와 일치하는 후보를 찾습니다.
| 후보 수 | 결과 |
|---|---|
| 0 | storage_visibility_unsupported |
| 1 | 해당 binding 사용 |
| 2개 이상 | storage_bucket_ambiguous — alias를 명시하거나 grant를 정리해야 함 |
visibility도 생략하면 안전 기본값인 private가 적용됩니다. 명시한 alias의 visibility가 요청과 다르면 fail-closed됩니다.
Public 업로드 조건
Public 업로드는 다음 조건을 모두 만족해야 합니다.
- 운영 전역 public-upload switch가 켜져 있음
- token에 upload action이 있음
- token이 public binding을 grant받음
- binding visibility가 public이며 custom URL이 등록됨
- collection 정책이 public을 허용함
별도 token public-write boolean은 사용하지 않습니다.
보안 원칙
- long-lived Storage API token과 Provider Credential은 서버 secret store 또는
.env에만 둡니다. - Blade, JavaScript, localStorage, 브라우저 요청에 long-lived token을 넣지 않습니다.
- 소비 프로젝트에는 실제 R2/S3 access key와 bucket credential을 전달하지 않습니다.
- private object URL은 필요할 때 서버가 temporary URL을 발급합니다.