Security Rules

Security Rules are CloudBase cloud storage's file-level permission control feature, allowing precise control over read and write permissions for each file through custom expressions.

PG mode

This page is classic-mode only. In PG environments, file-level permissions are expressed via PostgreSQL RLS policies with much greater power — see PG Cloud Storage — RLS policy patterns.

Configuration Entry

In CloudBase Console/Cloud Storage, click "Permission Settings" and select "Custom Security Rules" to configure security rules.

⚠️ Notes:

• CloudBase console and server-side always have read and write permissions for all files. Security rules only apply to requests from clients (mini programs, web, etc.)
• After modifying security rules, it takes 1-3 minutes for permissions to take effect. Please be patient
• Before publishing, be sure to evaluate the security of the rules to avoid data leakage caused by public rules

Basic Syntax

{
  "read": "expression",    // Read permission control expression
  "write": "expression"    // Write permission control expression
}

Common Templates

Public Read, Creator Write

{
  "read": true,
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}

Creator Only

{
  "read": "resource.openid == auth.openid || resource.openid == auth.uid",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}

Public Read, Admin Write

{
  "read": true,
  "write": false
}

Admin Only

{
  "read": false,
  "write": false
}

💡 Note: With this configuration, all client requests are denied. Only administrators can access through the CloudBase console or server-side SDK.

Authenticated Users Only

{
  "read": "auth != null",
  "write": "auth != null && auth.loginType != 'ANONYMOUS'"
}

Expression Syntax

Built-in Variables

Variable	Description	Example
auth	User authentication info	auth.openid, auth.uid
resource	File resource info	resource.openid

auth Object Properties

Property	Description	Type	Example
uid	User unique identifier (Web)	string	"abc123"
openid	User unique identifier (Mini Program)	string	"oABC123"
loginType	Login method	string	"WECHAT"

LoginType Enum Values

Enum Value	Login Method
WECHAT_PUBLIC	WeChat Official Account
WECHAT_OPEN	WeChat Open Platform
ANONYMOUS	Anonymous Login
EMAIL	Email Login
CUSTOM	Custom Login

resource Object Properties

Property	Description	Type	Example
openid	File creator unique identifier	string	"oABC123"
path	File relative path in cloud storage (excluding bucket name), format: path/filename.jpg	string	photos/photo.jpg

Operators

Operator	Description	Example
==	Equal	auth.uid == resource.openid
!=	Not equal	auth.loginType != 'ANONYMOUS'
>	Greater than	now \> resource.metadata.expireTime
<	Less than	now \< resource.metadata.publishTime
>=	Greater or equal	auth.vipLevel \>= 3
<=	Less or equal	resource.size \<= 10485760
&&	Logical AND	auth != null && auth.loginType == 'WECHAT'
||	Logical OR	auth.uid == resource.openid || auth.isAdmin

Operation Types

Operation	Description	Default
read	Read file (download, get URL)	false
write	Write file (upload, delete)	false

Regular Expression Support

Security rules support regular expressions to match file paths, but only the .test() method is supported. Common JavaScript string methods are not supported.

Supported Syntax

Basic Regex

{
  "read": "/test/.test(resource.path)",
  "write": "false"
}

Matches all files containing test in the path.

Path Prefix Match

{
  "read": "/^test\\//.test(resource.path)",
  "write": "false"
}

Matches all files starting with test/.

💡 Note: Slashes / in paths must be escaped with double backslashes \\/.

File Extension Match

{
  "read": "/.*\\.png$/.test(resource.path)",
  "write": "false"
}

Matches all .png files.

💡 Note: The dot . needs to be escaped as \\., and $ indicates the end of the path.

Multiple Path Match

{
  "read": "/test|uploads/.test(resource.path)",
  "write": "false"
}

Matches files containing test or uploads in the path.

Combined Conditions

{
  "read": "/public/.test(resource.path) && auth.uid != null",
  "write": "/public/.test(resource.path) && auth.loginType != 'ANONYMOUS'"
}

Allows authenticated users to read files in the public path, and non-anonymous users to write.

Unsupported Methods

The following methods are not available in security rules:

Method	Example	Alternative
startsWith()	resource.path.startsWith('test/')	Use /^test\\//.test(resource.path)
includes()	resource.path.includes('test/')	Use /test/.test(resource.path)
indexOf()	resource.path.indexOf('test/') === 0	Use /^test\\//.test(resource.path)
match()	resource.path.match(/^test\//)	Use /^test\\//.test(resource.path)
substr()	resource.path.substr(0, 5) == 'test/'	Use regex or string equality check

In addition, security rules do not support negating the result of a regex match, i.e., !/xxx/.test(resource.path) is not available. Therefore, when you need to block a specific directory (deny that directory while allowing all others), negation cannot be used. Instead, use a whitelist approach by explicitly listing the directories that are allowed.

Incorrect (block the private/ directory, allow all others):

{
  "read": "!/^private\\//.test(resource.path)"
}

Correct (whitelist approach, only allow the public/ and uploads/ directories):

{
  "read": "/^public\\//.test(resource.path) || /^uploads\\//.test(resource.path)"
}

Regular Expression Syntax Rules

Rule	Description	Example
Must use .test()	Regex must be called via .test() method	/^test/.test(resource.path)
Slash escaping	Path separator / must be written as \\/	/^uploads\\//.test(resource.path)
Special char escape	Regex special characters need escaping, e.g., . as \\.	/.*\\.jpg$/.test(resource.path)
Supports OR	Can use pipe for simple OR operations	/test|uploads/.test(resource.path)
No grouping	Cannot use parentheses for complex grouping	/^(test|uploads)\\//.test(...) or /\.(png|jpg)$/.test(...) not supported, use /^test\\//.test(...) || /^uploads\\//.test(...)
Supports anchors	Supports ^ (start) and $ (end)	/^public/.test(...) or /\\.png$/.test(...)
No negation	Cannot negate the result of .test() with !	!/^test\\//.test(...) not supported; to block a directory, use a whitelist that explicitly lists allowed directories

Practical Examples

Multiple Public Directories

{
  "read": "/^test\\//.test(resource.path) || /^uploads\\//.test(resource.path) || /^public\\//.test(resource.path)",
  "write": "resource.openid == auth.openid"
}

Allows all users to read files in test/, uploads/, public/ directories, but only creators can write.

Specific File Types Public

{
  "read": "/\\.png$/.test(resource.path) || /\\.jpg$/.test(resource.path) || /\\.jpeg$/.test(resource.path) || /\\.gif$/.test(resource.path)",
  "write": "auth != null"
}

Public read access for all image files, authenticated users can upload.

💡 Note: Since parentheses grouping is not supported, multiple regex expressions need to be connected with ||.

Hierarchical Permission Control

{
  "read": "/^public\\//.test(resource.path) || (auth != null && /^private\\//.test(resource.path) && resource.openid == auth.uid)",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}

• public/ directory is readable by everyone
• private/ directory is only readable by file creators
• All files are only writable by creators

Application Scenarios

Personal Photo Album

Requirement: Users can only view and manage photos they uploaded.

{
  "read": "resource.openid == auth.openid || resource.openid == auth.uid",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}

// Mini Program - Upload photo
wx.cloud.uploadFile({
  cloudPath: `photos/${Date.now()}.jpg`,
  filePath: tempFilePath,
});

// Web SDK - Get my photo list (requires cloud function query)
app.callFunction({
  name: "getMyPhotos",
});

Public Photo Album

Requirement: Only read files in the public folder

{
  "read": "/^public\\//.test(resource.path)",
  "write": "auth.uid == resource.openid || auth.openid == resource.openid"
}

Cross-platform Compatibility

Since mini programs use auth.openid and web uses auth.uid, it's recommended to check both in security rules:

{
  "read": "resource.openid == auth.openid || resource.openid == auth.uid",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}