@orizm/cli 3.1.0 → 3.2.0

package/dist/docs/features/schema/authority.md

@@ -0,0 +1,456 @@
+<!-- source: docs/src/app/features/schema/authority/page.mdx -->
+
+# 権限
+
+このドキュメントでは、スキーマを通してCMSユーザー（以下、ユーザー）のアクセス権限を定義する方法を説明します。
+
+## コンセプト
+
+ロール、グループ、ルールの3つの概念を組み合わせることで、柔軟なアクセス制御を実現します。
+
+### ロールとグループ
+
+権限は **ロール** と **グループ** に紐づきます。ユーザーをロールやグループに所属させることで権限を付与します。
+
+例えば、以下のようにロールと権限を紐付けます。
+
+- **管理者**: すべてのリソースに対して読み取りと書き込みができる
+- **編集者**: コンテンツのリソースに対して読み取りと書き込みができる
+- **閲覧者**: コンテンツのリソースに対して読み取りができる
+
+### グループとマルチテナント
+
+ユーザーとデータをグループに紐付けることで、マルチテナントに適したアクセス制御を実現します。
+
+異なるグループに属するデータは論理的に分離されます。同じグループに所属するユーザーでなければアクセスできません。
+
+例えば、**店舗A**、**店舗B** の2つのグループがあるとします。  
+このとき店舗Aに属するデータは、店舗Aに属するユーザーのみアクセスでき、店舗Bに属するユーザーはアクセスできません。全店舗を管理するユーザーには、グループを横断してアクセスできる権限を設定できます。
+
+### ルール
+
+ルールはどのリソースに対して、どのような操作ができるかを定義します。
+
+リソースとは以下を指します。
+
+- **テーブル**
+- **バケット**
+
+それぞれのリソースに対して、以下の操作を定義できます。
+
+- **読み取り権限**: リソースの読み取りができるかどうか
+- **書き込み権限**: リソースの書き込みができるかどうか
+
+権限は **許可** と **拒否** の2つの方法で制御できます。
+
+## 権限の定義
+
+権限を定義する際には、`authorities` プロパティを使用します。
+
+以下の例では、`editor` ロールに対して、`blog` テーブルと `photo` バケットに対する読み書きを許可しています。また、ユーザー管理の操作を拒否しています。
+
+```ts copy filename="orizm.config.ts" showLineNumbers
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  authorities: [
+    {
+      match: { role: "editor" },
+      allowTables: ["blog"],
+      allowBuckets: ["photo"],
+      denyUserManagement: true,
+    },
+  ],
+});
+```
+
+### match
+
+`match` プロパティで、グループとロールに対して紐付けます。
+
+グループまたはロールのどちらかのみ指定することも、両方を指定することもできます。指定がない場合は、全てのユーザーに対してルールが適用されます。
+
+```ts copy
+{
+  match: {
+    group: "storeA",
+    role: "editor",
+  },
+}
+```
+
+### allow / deny
+
+`allow（許可）` と `deny（拒否）` プロパティで権限を定義します。使用できるルールは [ルール一覧](#ルール一覧) を参照してください。
+
+```ts copy
+{
+  allowTables: ["blog"],
+  allowBuckets: ["photo"],
+  denyUserManagement: true,
+}
+```
+
+### どのように適用されるか
+
+適用される権限は以下のように決まります。
+
+#### 同一オブジェクト内では `deny` が優先される
+
+同一オブジェクト内で `allow` と `deny` が両方定義されている場合、`deny` が優先されます。
+
+例えば以下の例では、最終的に `blog` テーブルへのアクセスは **拒否** されます。
+
+```ts copy
+[
+  {
+    allowTables: ["blog"],
+    denyTables: ["blog"],
+  },
+];
+```
+
+#### 同一オブジェクト内では詳細度の高いルールが優先される
+
+テーブルに関するルールを例に挙げると、以下の通り上から順に優先されます。
+
+1. `denyReadTables` / `denyWriteTables`
+1. `allowReadTables` / `allowWriteTables`
+1. `denyTables`
+1. `allowTables`
+1. `denyAllTables`
+1. `allowAllTables`
+
+以下の例では、最終的に `blog` テーブルへの **読み取り** のみが **許可** されます。
+
+```ts copy
+[
+  {
+    allowReadTables: ["blog"],
+    denyWriteTables: ["blog"],
+    allowTables: ["blog"],
+    denyAllTables: true,
+  },
+];
+```
+
+#### `authorities` 配列の後で定義されたルールが優先される
+
+authorities プロパティの定義は先頭から順に評価されます。後で定義されたルールにマッチした場合、それまでのルールを上書きします。
+
+例えば以下の例では、最終的に `blog` テーブルへの読み書きは **許可** されます。
+
+```ts copy
+[
+  {
+    denyTables: ["blog"],
+  },
+  {
+    allowTables: ["blog"],
+  },
+];
+```
+
+## 権限定義の例
+
+### 全ユーザーに全権限を付与
+
+```ts copy
+[
+  {
+    allowAllTables: true,
+    allowAllBuckets: true,
+    allowUserManagement: true,
+    allowAllGroups: true,
+  },
+];
+```
+
+### 読み取りと書き込みのロールを分離
+
+```ts copy
+[
+  {
+    // ロールなしのユーザーはアクセス拒否
+    denyAllTables: true,
+    denyAllBuckets: true,
+    denyUserManagement: true,
+    allowAllGroups: true,
+  },
+  {
+    // 閲覧者ロールは読み込みのみ許可
+    match: { role: "viewer" },
+    allowReadTables: ["blog"],
+    allowReadBuckets: ["photo"],
+  },
+  {
+    // 編集者ロールは読み込みと書き込みを許可
+    match: { role: "editor" },
+    allowAllTables: true,
+    allowAllBuckets: true,
+  },
+  {
+    // 管理者ロールは全権限を許可
+    match: { role: "admin" },
+    allowAllTables: true,
+    allowAllBuckets: true,
+    allowUserManagement: true,
+  },
+];
+```
+
+### マルチテナント
+
+```ts copy
+[
+  {
+    // ロールなしのユーザーはアクセス拒否
+    denyAllTables: true,
+    denyAllBuckets: true,
+    denyUserManagement: true,
+  },
+  {
+    // 閲覧者ロール
+    // 所属するグループのブログコンテンツの読み込みのみ許可
+    match: { role: "viewer" },
+    allowReadTables: ["blog"],
+    allowReadBuckets: ["photo"],
+  },
+  {
+    // 編集者ロール
+    // 所属するグループのブログコンテンツの読み書きを許可
+    match: { role: "editor" },
+    allowTables: ["blog"],
+    allowBuckets: ["photo"],
+  },
+  {
+    // テナント管理者
+    // 所属するグループのブログコンテンツの読み書きと
+    // ユーザー管理を許可
+    match: { role: "manager" },
+    allowTables: ["blog"],
+    allowBuckets: ["photo"],
+    allowUserManagement: true,
+  },
+  {
+    // 全権限を持つ管理者
+    match: { group: "admin" },
+    allowAllTables: true,
+    allowAllBuckets: true,
+    allowUserManagement: true,
+    allowAllGroups: true,
+  },
+];
+```
+
+## ルール一覧
+
+- [allowAllTables](#allowAllTables)
+- [denyAllTables](#denyAllTables)
+- [allowTables](#allowTables)
+- [denyTables](#denyTables)
+- [allowReadTables](#allowReadTables)
+- [denyReadTables](#denyReadTables)
+- [allowWriteTables](#allowWriteTables)
+- [denyWriteTables](#denyWriteTables)
+- [allowAllBuckets](#allowAllBuckets)
+- [denyAllBuckets](#denyAllBuckets)
+- [allowBuckets](#allowBuckets)
+- [denyBuckets](#denyBuckets)
+- [allowReadBuckets](#allowReadBuckets)
+- [denyReadBuckets](#denyReadBuckets)
+- [allowWriteBuckets](#allowWriteBuckets)
+- [denyWriteBuckets](#denyWriteBuckets)
+- [allowUserManagement](#allowUserManagement)
+- [denyUserManagement](#denyUserManagement)
+- [allowAllGroups](#allowAllGroups)
+
+### allowAllTables
+
+すべてのテーブルに対して **読み取りと書き込み** を **許可** します。
+
+```ts copy
+{
+  allowAllTables: true,
+}
+```
+
+### denyAllTables
+
+すべてのテーブルに対して **読み取りと書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyAllTables: true,
+}
+```
+
+### allowTables
+
+指定したテーブルに対して **読み取りと書き込み** を **許可** します。
+
+```ts copy
+{
+  allowTables: ["blog", "category", "tag"],
+}
+```
+
+### denyTables
+
+指定したテーブルに対して **読み取りと書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyTables: ["blog", "category", "tag"],
+}
+```
+
+### allowReadTables
+
+指定したテーブルの **読み取り** を **許可** します。
+
+```ts copy
+{
+  allowReadTables: ["blog", "category", "tag"],
+}
+```
+
+### denyReadTables
+
+指定したテーブルの **読み取り** を **拒否** します。
+
+```ts copy
+{
+  denyReadTables: ["blog", "category", "tag"],
+}
+```
+
+### allowWriteTables
+
+指定したテーブルの **書き込み** を **許可** します。
+
+```ts copy
+{
+  allowWriteTables: ["blog", "category", "tag"],
+}
+```
+
+### denyWriteTables
+
+指定したテーブルの **書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyWriteTables: ["blog", "category", "tag"],
+}
+```
+
+### allowAllBuckets
+
+すべてのバケットに対して **読み取りと書き込み** を **許可** します。
+
+```ts copy
+{
+  allowAllBuckets: true,
+}
+```
+
+### denyAllBuckets
+
+すべてのバケットに対して **読み取りと書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyAllBuckets: true,
+}
+```
+
+### allowBuckets
+
+指定したバケットに対して **読み取りと書き込み** を **許可** します。
+
+```ts copy
+{
+  allowBuckets: ["photo", "video", "audio"],
+}
+```
+
+### denyBuckets
+
+指定したバケットに対して **読み取りと書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyBuckets: ["photo", "video", "audio"],
+}
+```
+
+### allowReadBuckets
+
+指定したバケットの **読み取り** を **許可** します。
+
+```ts copy
+{
+  allowReadBuckets: ["photo", "video", "audio"],
+}
+```
+
+### denyReadBuckets
+
+指定したバケットの **読み取り** を **拒否** します。
+
+```ts copy
+{
+  denyReadBuckets: ["photo", "video", "audio"],
+}
+```
+
+### allowWriteBuckets
+
+指定したバケットの **書き込み** を **許可** します。
+
+```ts copy
+{
+  allowWriteBuckets: ["photo", "video", "audio"],
+}
+```
+
+### denyWriteBuckets
+
+指定したバケットの **書き込み** を **拒否** します。
+
+```ts copy
+{
+  denyWriteBuckets: ["photo", "video", "audio"],
+}
+```
+
+### allowUserManagement
+
+ユーザー管理の操作を **許可** します。
+
+```ts copy
+{
+  allowUserManagement: true,
+}
+```
+
+### denyUserManagement
+
+ユーザー管理の操作を **拒否** します。
+
+```ts copy
+{
+  denyUserManagement: true,
+}
+```
+
+### allowAllGroups
+
+すべてのグループのリソースに対してアクセスを許可します。
+
+```ts copy
+{
+  allowAllGroups: true,
+}
+```

package/dist/docs/features/schema/bucket.md

@@ -0,0 +1,142 @@
+<!-- source: docs/src/app/features/schema/bucket/page.mdx -->
+
+# バケット
+
+バケットは画像、動画、PDFなどのファイルを保存・配信するためのファイルストレージです。
+
+例えば、Webサイトで使用する画像をバケットに保存し、配信することができます。バケットにアップロードすると、アクセスするためのURLが発行されます。WebサイトではこのURLを `<img>` タグの `src` 属性に指定することで画像を表示できます。
+
+このドキュメントでは、バケット機能の概要とスキーマを通してバケットを定義する方法を説明します。
+
+## バケットの定義
+
+バケットを定義するには `buckets` プロパティを使用します。
+
+以下の例では、誰でもアクセスできる `publicFiles` バケットと、アクセスに認証が必要な `privateFiles` バケットを定義しています。
+
+```ts copy filename="orizm.config.ts" showLineNumbers
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  buckets: {
+    publicFiles: { accessControl: "public" },
+    privateFiles: { accessControl: "private" },
+  },
+});
+```
+
+### accessControl
+
+`accessControl` プロパティでバケットのアクセス制御を設定できます。指定しない場合は `public` になります。
+
+- **public**: 誰でもアクセスできる（公開バケット）
+- **private**: [署名付きURL](#署名付きurl) を知っているユーザーのみアクセスできる（非公開バケット）
+
+## 公開バケットへのアクセス
+
+アップロードされたファイルごとに、アクセスするためのURLが生成されます。
+
+```
+https://app.orizm.com/buckets/{プロジェクト名}/{バケット名}/{オブジェクトキー}
+```
+
+このURLを取得するには、CMS SDKでバケットに対して `list()` または `get()` を使用してファイルのメタデータを取得します。
+
+```ts copy
+// filesバケットのファイル一覧を取得
+const { contents } = await cmsClient.buckets.files.list();
+
+console.log(contents);
+// [
+//   {
+//     id: 1,
+//     key: 'zl9XQ3KeKX89Ttf3.png',
+//     size: 25667,
+//     type: 'image/png',
+//     width: 1024,
+//     height: 672,
+//     group: null,
+//     originalFilename: 'image.png',
+//     bucketName: 'files',
+//     projectName: 'demo-project',
+//     publicUrl: 'https://app.orizm.com/buckets/demo-project/files/zl9XQ3KeKX89Ttf3.png',
+//     protectedUrl: 'https://app.orizm.com/buckets-protected/demo-project/files/zl9XQ3KeKX89Ttf3.png?token={トークン}',
+//     createdAt: '2025-01-01T00:00:00.000Z',
+//     updatedAt: '2025-01-01T00:00:00.000Z'
+//   }
+// ]
+```
+
+レスポンスされた `publicUrl` プロパティにアクセス用のURLが含まれています。
+
+```
+https://app.orizm.com/buckets/demo-project/files/zl9XQ3KeKX89Ttf3.png
+```
+
+## 非公開バケットへのアクセス
+
+非公開バケットへアクセスするためのURLを取得するには、CMS SDKでバケットに対して `list()` または `get()` を使用してファイルのメタデータを取得します。
+
+```ts copy
+// systemFilesバケットのファイル一覧を取得
+const { contents } = await cmsClient.buckets.systemFiles.list();
+
+console.log(contents);
+// [
+//   {
+//     id: 1,
+//     key: 'zl9XQ3KeKX89Ttf3.png',
+//     size: 25667,
+//     type: 'image/png',
+//     width: 1024,
+//     height: 672,
+//     group: null,
+//     originalFilename: 'image.png',
+//     bucketName: 'systemFiles',
+//     projectName: 'demo-project',
+//     publicUrl: 'https://app.orizm.com/buckets/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png',
+//     protectedUrl: 'https://app.orizm.com/buckets-protected/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png?token={トークン}',
+//     createdAt: '2025-01-01T00:00:00.000Z',
+//     updatedAt: '2025-01-01T00:00:00.000Z'
+//   }
+// ]
+```
+
+レスポンスされた `protectedUrl` プロパティにアクセス用のURLが含まれています。
+
+このURLは署名付きURLと呼ばれ、アクセスするためのJWTトークンが含まれています。このトークンは `最大15分間有効` です。トークンの期限が切れた場合は、再度 `list()` または `get()` でデータを取得することで新しいURLを取得できます。
+
+```
+https://app.orizm.com/buckets-protected/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png?token={トークン}
+```
+
+> [!WARNING]
+> `publicUrl`
+> プロパティのURLでアクセスした場合は、認証エラーとしてステータスコード `401`
+> が返されます。
+
+## ファイルのアップロード
+
+ファイルをアップロードするにはCMS SDKの `upload()` メソッドを使用します。
+
+```ts copy
+// 引数 file はFile型オブジェクト
+await cmsClient.buckets.files.upload(file);
+```
+
+## ファイルの削除
+
+ファイルを削除するにはCMS SDKの `delete()` メソッドを使用します。
+
+```ts copy
+const fileKey = "zl9XQ3KeKX89Ttf3.png";
+await cmsClient.buckets.files.delete(fileKey);
+```
+
+## storage型カラム
+
+データベースで使用できる [storage型カラム](./database.md#storage) もファイルストレージとして類似した機能を持っています。
+
+storage型カラムとバケットはファイルを扱う点で似ていますが異なる点があります。バケットはシンプルなファイル置き場であるのに対し、storage型カラムはファイルをレコードに紐づけて扱えます。例えば、ブログ記事にサムネイル画像を設定する場合、storage型カラムを使用して画像ファイルをレコードに紐づけることができます。
+
+レコードが削除された場合、ファイルは30日後に自動で削除されます。削除前であれば、[編集履歴の管理機能](../history.md) を利用して復元することも可能です。