Изучите основной синтаксис языка правил безопасности Firebase для Cloud Storage.

Firebase Security Rules для Cloud Storage позволяет управлять доступом к объектам, хранящимся в сегментах Cloud Storage. Гибкий синтаксис правил позволяет создавать правила для управления любой операцией, от всех записей в сегмент Cloud Storage до операций с определенным файлом.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Cloud Storage data.

В этом руководстве описаны базовый синтаксис и структура Cloud Storage Security Rules, которые используются для создания полных наборов правил.

Декларация сервиса и базы данных

Firebase Security Rules для Cloud Storage всегда начинается со следующего объявления:

service firebase.storage {
    // ...
}

Объявление service firebase.storage ограничивает область действия правил до Cloud Storage, предотвращая конфликты между Cloud Storage Security Rules и правилами для других продуктов, таких как Cloud Firestore.

Основные правила чтения и записи

Базовые правила состоят из оператора match, определяющего сегменты Cloud Storage, оператора соответствия, указывающего название файла, и выражения allow, определяющего, когда разрешено чтение указанных данных. Выражения allow определяют методы доступа (например, чтение или запись) и условия, при которых доступ разрешен или запрещен.

В наборе правил по умолчанию первое выражение match использует подстановочный знак {bucket}, чтобы указать, что правила применяются ко всем сегментам в проекте. Подробнее о подстановочных знаках мы поговорим в следующем разделе.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

Все операторы match указывают на файлы. Оператор match может указывать на определенный файл, например match /images/profilePhoto.png.

Сопоставляйте подстановочные знаки

Помимо указания на один файл, Security Rules может использовать подстановочные знаки, чтобы указать на любой файл с заданным префиксом строки в имени, включая косые черты, как в match /images/{imageId}.

В примере выше в операторе match используется синтаксис подстановочного знака {imageId}. Это означает, что правило применяется к любому файлу, название которого начинается с /images/, например /images/profilePhoto.png или /images/croppedProfilePhoto.png. При оценке выражений allow в операторе соответствия переменная imageId будет заменена на название файла изображения, например profilePhoto.png или croppedProfilePhoto.png.

На переменную с подстановочным знаком можно ссылаться из match, чтобы предоставить авторизацию для имени файла или пути:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

Иерархические данные

Как мы уже говорили, в сегменте Cloud Storage нет иерархической структуры. Но используя соглашение об именах файлов, часто включающее косые черты в именах файлов, мы можем имитировать структуру, которая выглядит как вложенная серия каталогов и подкаталогов. Важно понимать, как Firebase Security Rules взаимодействует с такими названиями файлов.

Рассмотрим ситуацию, когда у нас есть набор файлов, названия которых начинаются с /images/. Firebase Security Rules применяются только к совпадающему названию файла, поэтому настройки доступа, заданные для основы /images/, не применяются к основе /mp3s/. Вместо этого создайте явные правила, соответствующие разным шаблонам названий файлов:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

При вложении операторов match путь внутреннего оператора match всегда добавляется к пути внешнего оператора match. Поэтому следующие два набора правил эквивалентны:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

Подстановочные знаки для рекурсивного сопоставления

Помимо подстановочных знаков, которые сопоставляют и возвращают строки в конце названия файла, можно объявить подстановочный знак для нескольких сегментов, чтобы выполнять более сложное сопоставление. Для этого добавьте =** к названию подстановочного знака, например {path=**}:

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

Если файлу соответствуют несколько правил, результатом будет OR результатов всех оценок правил. То есть если любое правило, которому соответствует файл, оценивается как true, результатом будет true.

В приведенных выше правилах файл images/profilePhoto.png можно прочитать, если значение condition или other_condition равно true, а файл images/users/user:12345/profilePhoto.png зависит только от результата other_condition.

Правила Cloud Storage Security Rules не каскадируются и оцениваются, только если путь запроса совпадает с путем, для которого заданы правила.

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

Точечные операции

В некоторых случаях полезно разбить read и write на более мелкие операции. Например, в приложении могут быть разные условия для создания и удаления файлов.

Операцию read можно разбить на get и list.

Правило write можно разбить на create, update и delete:

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single file read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Security Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to file contents
      allow create: if <condition>;

      // Applies to updates to (pre-existing) file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

Перекрывающиеся утверждения о совпадении

Название файла может соответствовать нескольким операторам match. Если запросу соответствуют несколько выражений allow, доступ разрешается, если любое из условий имеет значение true:

service firebase.storage {
  match b/{bucket}/o {
    // Matches file names directly inside of '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches file names anywhere under `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

В примере выше все операции чтения и записи в файлы, название которых начинается с /images/, разрешены, потому что второе правило всегда имеет значение true, даже если первое правило имеет значение false.

Правила – это не фильтры

После того как вы защитите свои данные и начнете выполнять операции с файлами, помните, что правила безопасности не являются фильтрами. Вы не можете выполнять операции с набором файлов, соответствующих шаблону имени файла, и ожидать, что Cloud Storage получит доступ только к тем файлам, к которым у текущего клиента есть разрешение на доступ.

Рассмотрим следующее правило безопасности:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

Отклонено. Это правило отклоняет следующий запрос, поскольку набор результатов может включать файлы, для которых contentType не равно image/png:

filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

Правила в Cloud Storage Security Rules оценивают каждый запрос по его потенциальному результату и отклоняют запрос, если он может вернуть файл, на чтение которого у клиента нет разрешения. Запросы на доступ должны соответствовать ограничениям, заданным в правилах.

Дальнейшие действия

Вы можете узнать больше о Firebase Security Rules для Cloud Storage:

• Изучите следующую важную концепцию языка правил – динамические условия, которые позволяют правилам проверять авторизацию пользователей, сравнивать существующие и входящие данные, проверять входящие данные и многое другое.

• Ознакомьтесь с типичными примерами использования и определениями Firebase Security Rules, которые к ним относятся.

Вы можете изучить Firebase Security Rules вариантов использования, характерных для Cloud Storage: