Firebase Security Rules Release Notes

To review release notes for the Firebase console and for other Firebase platforms and related SDKs, refer to the Firebase Release Notes.

September 22, 2022

Cross-service Rules (Rules Language enhancement). We're excited to deliver one of the most popular feature requests for Security Rules. Security Rules in Cloud Storage for Firebase now supports cross-service Rules with two brand new functions, firestore.get() and firestore.exists(). These functions let you query your project's Firestore data, similar to the get() and exists() functions in Firestore Rules.
How can you use it?

Say you have a social media app, and you want to allow users to share photos with a set of friends. Your Firestore database stores data related to your users in a collection called users, with a document for each user’s UID.

Within each document (representing a user), there’s a list called friends that contains other UIDs. The photos for the main application are stored in Cloud Storage for Firebase, with each user having a folder named for their UID.

To only allow each user to view the pictures of their friends, you can add rules like:
```
    service firebase.storage {
      match /b/{bucket}/o {
        match /users/{uid}/files/{fileId} {
          // Owners can view and update their own files if they're listed in Firestore
          allow write, read: if
              request.auth.uid == uid &&
              firestore.exists(/databases/(default)/documents/users/$(uid));

          // Friends can read if they are listed
          allow read: if
              request.auth.uid in
              firestore.get(/databases/(default)/documents/users/$(uid)).data.friends;
        }
      }
    }
  
```

July 8 2021

Requests Monitor Rules lets you inspect requests made to your local Firestore Emulator in real-time, including the request method, path, and how Security Rules were evaluated. Check out this blog post for more detail. It's available in the Emulator Suite that shipped in the Firebase CLI v9.16.0.

How can you use it?

Under the new Firestore > Requests tab of the Emulator UI, you can view recent requests and new ones as they come in. Click into any of them to view all the details of the request.

Request Monitor is a great debugging feature generally, but is especially useful for writing or debugging Security Rules. Clicking on any request will show the details of the Rules evaluation. Statements that matched and were evaluated will be highlighted and show the result of the evaluation. And with all the details of the request, you may notice new access patterns you want to build into your Security Rules!

March 25, 2020

Type Checks Rules now checks for common type errors and warnings in the CLI, the Firebase Console, and the Emulator Suite. Errors will block using or deploying your rules, but warnings will not. Take a look at the examples below. Available in Rules Language v1, v2.

How can you use it?

You'll notice new warnings for things like a function that is never called, when a function is called with the wrong number of arguments, or when a variable is never used.

You'll also see errors if you hit one of the limits on code complexity that we use to keep decisions from security rules extremely fast. Some examples are if there are more than 10 local variables in a function or more than 20 path captures in one path. You'll also see an error if we need you to resolve ambiguity; for example, if a function is redefined or a variable is defined multiple times the same scope.

We hope the new errors and warnings help avoid common mistakes in rules code. Let us know how they work for you!
Rules Playground You can now debug your Firestore and Storage rules in the console by hovering over expressions in the Rules Playground. Check out the documentation or example below for more details.

How can you use it?

To use the Playground Debugger, start by running a simulation in the Rules Playground. Then hover over either an expression in the rules or part of the request in the right side bar. If you hover over part of the request in the side bar, then the rule that used that information to make a decision will be highlighted. If you hover on a rule, the parts of the request that caused the decision will be highlighted.

The Rules Playground can't capture all test cases; keep using the emulator suite for advanced cases. Use the Rules Playground as a way to experiment or proof-of-concept new rules.

Map Diffs (Rules Language enhancement). Map Diffs give the difference between maps. Since request and resource objects are structured as maps, this is great for diffing old and new data. Take a look at the documentation and the examples below. Available in Rules Language v1, v2.

How can you use it?

To use it in rules:

// Returns a MapDiff object
map1.diff(map2)

The MapDiffobject has the following methods:

addedKeys() // a set of strings of keys that are in after but not before
removedKeys() // a set of strings of keys that are in before but not after
changedKeys() // a set of strings of keys that are in both maps but have different values
affectedKeys() // a set of strings that's the union of addedKeys() + removedKeys() + updatedKeys()
unchangedKeys() // a set of strings of keys that are in both maps and have the same value in both

A practical example:

// This rule only allows updates where "a" is the only field affected
allow update: if request.resource.data.diff(resource.data).affectedKeys().hasOnly(["a"]);

Map.diff() doesn't require you to know in advance what all the fields will be, so hopefully you can write more future-proof rules.

Local Variables (Rules Language enhancement). Local variables are now supported in Security Rules! Create a local variable in rules functions by using the keyword let. Take a look at the documentation and the examples below. Available in Rules Language v2.
How can you use it?

Up to ten local variables can be created inside functions, and the function still needs to end with a return statement.

For example, a function in Security Rules that determines the length of the hypotenuse of a right triangle could use local variables:
```
rules_version = "2";
function length_of_hypotenuse(a, b) {
let a2 = math.pow(a, 2);
let b2 = math.pow(b, 2);
let c2 = a2 + b2;
let c = math.sqrt(c2);
return  c;
}
```
(We also implemented math.pow and math.sqrt so we could use this example.)
Ternary Operators (Rules Language enhancement). If your Security Rules contain complex control flow, you'll appreciate that there's now a Ternary Operator in Rules for Firestore and Storage. It works just as you'd expect: condition ? true case : false case. Take a look at the documentation and the examples below. Available in Rules Language v1, v2.
How can you use it?

In this example, the ternary operator sets the path to look up group membership, and then the function returns the result of an exist call:
```
function isGroupMember(group, visibility) {
    let membership = visibility == "adminsOnly"
        ? /databases/$(db)/documents/admins/$(request.auth.uid)
        : /databases/$(db)/documents/$(group)/$(request.auth.uid);
    return exists(membership);
}
```

December 9, 2019

Set type (Rules Language enhancement). Sets are now a supported type in Firebase Security Rules! This is great for enforcing required and optional fields. Lists can be converted into Sets by calling myList.toSet(). Available in Firebase Security Rules Language v1, v2.
How can you use it?

What can you do with Sets? Mostly compare to and diff against other Sets:
```
mySet == myOtherSet #Comparing a set to another type returns false.
mySet.size()
mySet.hasAll(myOtherSet) # Can also be passed a List
mySet.hasOnly(myOtherSet) # Can also be passed a List
mySet.hasAny(myOtherSet) # Can also be passed a List
mySet.union(myOtherSet)
mySet.intersection(myOtherSet)
mySet.difference(myOtherSet)
```
Here's an example of using Sets to ensuring that a document only has fields "a", "b", and "c":
```
request.resource.data.keys().toSet() == ["a", "b", "c"].toSet()
```
Similarly, you could make sure that a document only has specified keys, but not others:
```
(request.resource.data.keys().toSet() - ["required","and","opt","keys"].toSet()).size == 0?`
```
Rule evaluation metrics in Stackdriver. Rule evaluation metrics are now exported from Firebase into Stackdriver for Cloud Firestore, the Realtime Database, and Cloud Storage! This lets you set up monitoring and alerting around authorization requests for your app. Available in Rules Language v1, v2.
How can you use it?

Three metrics are available in Stackdriver:
- Allowed Requests, when the rules grant access
- Denied Requests
- Errored Requests
When you roll out a new version of your app or security rules, you can now monitor the performance of your Rules evaluations. The alerts available through Stackdriver let you configure notifications to stay on top of your data security. Be sure to read the docs for Cloud Firestore, Realtime Database, and Cloud Storage.

October 8, 2019

Map get (Rules Language enhancement). Fetching values within a map just got easier with get. It takes two arguments: the first is the key within the Map, and the second is a default value to return if the key doesn't exist. Check out the documentation and the following examples. Available in Rules Language v1, v2.
How can you use it?

In this example, the Map has a key "foo", so a call to get returns the corresponding value "1":
```
{ "foo": 1, "bar": 2 }.get("foo", 7) => 1
```
Here, since the Map doesn't have key "baz", the default value "7" is returned:
```
{ "foo": 1, "bar": 2 }.get("baz", 7) => 7
```
How is this different than Map indexing, like {"foo": 1}["foo"] => 1? Indexing and gets will both let you fetch a field from a document or other Map, including nested fields. Gets also let you provide a default value, which can mean less code to write and maintain in your Rules.

To demonstrate the syntax for get on a nested Map , here's an example that allows the client to read a data item if it has been tagged as "published". The rule takes a Rules request object (a Map); it fetches the value for resource.data.visibility; it checks if that value is "published". If the value is null, get returns the default value "hidden", the string comparison fails, and read access is denied:
```
allow read: if request.get(["resource", "data", "visibility"], "hidden") == "published";
```
Hashing (Rules Language enhancement). Ever want to hash a value in Firebase Security Rules, either to obscure content that you don't want in plaintext or to avoid handling something unwieldy? Now that that Hashing is available in Firebase Security Rules, you can! Take a look at the documentation and the examples below. Available in Rules Language v1, v2.
How can you use it?

New hashing and hashing-adjacent methods are:
```
hashing.crc32()
hashing.crc32c()
hashing.sha256()
hashing.md5()
<ByteValue>.toBase64()
<ByteValue>.toHexString()
<String>.toUtf8()
```
For example, previously, if the version of an email in Firestore was hashed with SHA-256, you wouldn't be able to compare that email to the plaintext email sent with the auth object. Now you can:
```
hashing.sha256(request.auth.email.utf8()) == resource.data.ownerEmailHash
```
Alternatively, if you have a field in a document for users to store their novellas, you may want to have a shorter identifier for that very long string:
```
match /novellas/{hash} {
 allow write: if hash == hashing.sha256(request.resource.data.
           novella.utf8()) && resource == null
}
```
Strings are treated as UTF-8-encoded bytes, and the return value is a Bytes type:
```
hashing.md5("Tag".utf8()) => b"wQEFjn6iG7vypayJMIjpCw=="
```
String replace (Rules Language enhancement). Sometimes a String in your Rules isn't exactly in the form you need it. Now you have String.replace() to do some light cleanup. It works like you would guess: "myString".replace("my", "your") => "yourString". This function is described in the documentation and another example is shown below. Available in Firebase Security Rules Language v1, v2.
Another example?

This is an example of removing the leading "+" from phone numbers, to have a canonical version of the number to do other things with:
```
request.auth.token.phone_number.replace('+', '')
```
This feature was requested from StackOverflow, so keep asking us for things!

Firebase Security Rules Release Notes

September 22, 2022

How can you use it?

July 8 2021

How can you use it?

March 25, 2020

How can you use it?

How can you use it?

February 13, 2020

How can you use it?

How can you use it?

How can you use it?

December 9, 2019

How can you use it?

How can you use it?

October 8, 2019

How can you use it?

How can you use it?

Another example?