個人用拡張機能

個人用拡張機能は、Marinaraにボタン、パネル、補助機能を追加する小さなコードです。Professor Mariに書いてもらうことができ、そもそも実行するかどうかは自分で決めます。このガイドでは、拡張機能の確認、有効化、エクスポート、復旧について説明します。自分で書く場合は、Personal Extensionsの作成を参照してください。

拡張機能の種類

名前	内容
Personal Extension(個人用拡張機能)	Professor Mariが書いてくれた拡張機能です。Settings → Addons(設定 → アドオン)の下に下書きとして表示されます。
External Extension(外部拡張機能)	他の人が作った拡張機能、または自分で書いた拡張機能です。サードパーティー製拡張機能のインポートを許可するの追加手順が必要です。
Browser Extension(ブラウザー拡張機能)	ブラウザーの中のサンドボックスで動きます。デフォルトのままで安全です。
Server Extension(サーバー拡張機能)	Marinaraを動かしているコンピューター上の、OSのサンドボックスの中で動きます。対応するプラットフォームが必要です。
Full page access(ページ全体へのアクセス)	サンドボックスを外す権限です。完全に信頼できるコードにだけ使ってください。

共有された拡張機能をインストールする

始める前に、サードパーティー製拡張機能のインポートを許可するの2つの手順を済ませてください。済ませていないと、インポートのボタンは表示されません。

Settings → Addons(設定 → アドオン)を開きます。External Extensions(外部拡張機能)の下で、.zip、.json、.css、.jsのファイルならImport Extension File(拡張機能のファイルをインポート)を、フォルダーならImport Extension Folder(拡張機能のフォルダーをインポート)を選びます。
新しい下書きを開きます。下書きは無効の状態で、コードとハッシュが表示されます。ハッシュとは、そのコードそのものを表す短いフィンガープリントです(MarinaraはSHA-256を使います)。
コードとRequested access(要求されている権限)の一覧を読みます。
そのバージョンをそのまま受け入れられる場合にだけ、Review and Run(確認して実行)を選びます。すると、拡張機能は有効と表示されます。

うまくいかなかった場合: インポートのボタンが見当たらないときは、2つの手順のどちらかが済んでいません。.envを変更したあとは、忘れずにMarinaraを再起動してください。

Professor Mariが作った拡張機能を確認する

始める前に、Professor Mariに拡張機能の作成を頼んでください。Professor Mariはコードを保存できますが、承認したり有効にしたりはできません。このセクションには、New Draftボタンも、インポートの操作もありません。

Settings → Addons → Personal Extensions(設定 → アドオン → 個人用拡張機能)を開きます。下書きがない場合は、「Ask Professor Mari to create an extension for you. Nothing runs until you enable it and approve the exact code hash.」と表示されます。
下書きを開いてコードを読みます。ハッシュとRequested access(要求されている権限)の一覧を確認します。
そのバージョンをそのまま受け入れられる場合にだけ、Review and Run(確認して実行)を選びます。

下書きはすべて無効の状態から始まります。コードの編集、権限の変更、リビジョンの復元のいずれかを行うと、拡張機能は無効になり、あらためて承認が必要になります。

Warning: サンドボックスはコードにできることを制限しますが、コードを信頼できるものにするわけではありません。有害な拡張機能でも、ウォッチドッグ(暴走したコードを止めるタイマー)が止めるまでプロセッサーの時間を浪費する、上限まで自分のストレージを埋める、ログを使って欺く、といったことはできます。ページ全体へのアクセスを持つ拡張機能は、意図的にサンドボックスを手放しています。有効にする前にコードを読み、サードパーティー製のコードは1行残らず確認してください。

うまくいかなかった場合: Professor Mariによる編集や、リビジョンの復元を行うと、下書きは無効に戻ります。もう一度確認し、ダイアログに表示されたハッシュが、自分が読んだコードのものであることを確かめてください。

拡張機能にできること

ブラウザー拡張機能は、ブラウザーの中のサンドボックス(外から隔離された領域)で動きます。Marinaraのページ、Cookie、ブラウザーのストレージ、ネットワークには届きません。できることは次のとおりです。

非公開のストレージを持ち、ログを書く
Marinaraが使用中のテーマで描画するボタン、メニュー項目、パネルを追加する
開いているチャットのIDを読み取る
現在のキャラクターまたはペルソナの一部の項目を読み取る(該当する権限を承認した場合だけ)

全体の一覧はPersonal Extensionsの作成にあります。

サーバー拡張機能は、OSのサンドボックスの中で、別のNodeプロセス(サーバーのコンピューター上で動くプログラム)として動きます。Marinaraのファイル、自分のファイル、サーバーの秘密情報、ネットワーク、子プロセス、ワーカー、ネイティブアドオンには届きません。

対応プラットフォーム

ブラウザー拡張機能はブラウザーがサンドボックス化するため、どの環境でも動きます。サーバー拡張機能には、対応するOSのサンドボックスが必要です。サンドボックスがない環境では無効のままで、Marinaraがサンドボックスなしでサーバー拡張機能を実行することはありません。

プラットフォーム	サーバー拡張機能
macOS	macOSのサンドボックスであるSeatbeltでサンドボックス化
Linux(Bubblewrapあり)	LinuxのサンドボックスツールであるBubblewrapでサンドボックス化
Linux(`bwrap`なし)	無効: `bwrap`をインストール
Docker(デフォルト)	無効: コンテナーの権限による制限
Windows	無効: ブラウザー拡張機能を使用
Android	無効: ブラウザー拡張機能を使用

ブラウザー拡張機能は、どのプラットフォームでもサンドボックス化されます。ページ全体へのアクセスを持つ外部拡張機能は、どの環境でもサンドボックス化されず、常に明示的な信頼が必要です。

公式DockerイメージにはBubblewrapが含まれていますが、デフォルトのコンテナーでは、Bubblewrapに必要な入れ子の名前空間やマウントを作成できません。Marinaraは実行時にサンドボックスを検証し、コンテナーが許可しない場合はサーバー拡張機能を無効のままにします。Dockerの権限を上書きする方法と、そのセキュリティ上のトレードオフについては、トラブルシューティングを参照してください。

WindowsとAndroidには対応するプロセスサンドボックスがないため、サーバー拡張機能は使えません。ブラウザー拡張機能を使うか、Marinaraのサーバーを、macOS、またはbwrapのあるLinuxで動かしてください。

サードパーティー製拡張機能のインポートを許可する

サードパーティー製拡張機能のインポートは、他の人が書いたコードを実行するため、デフォルトではロックされ、表示もされません。次の2つの手順で使えるようになります。

Marinaraを動かしているコンピューターで、.envファイルにENABLE_EXTERNAL_EXTENSIONS=trueを設定し、Marinaraを再起動します。サーバー設定リファレンスを参照してください。
Settings → Advanced → Danger Zone(設定 → 詳細設定 → 危険な操作)を開き、データ削除の操作より下までスクロールして、警告を読んでからAllow third-party extension imports(サードパーティー製拡張機能のインポートを許可)をオンにします。

すると、Settings → Addons(設定 → アドオン)にExternal Extensions(外部拡張機能)が表示され、ファイルとフォルダーのインポート操作が使えるようになります。対応形式は次のとおりです。

.personal-extension.zipと、互換性のある.zipパッケージ
.jsonのマニフェスト
.css
.js、.mjs、.cjs
.server.js、.server.mjs、.server.cjs

インポートしたものに承認が付いてくることはなく、拡張機能が自分自身を有効にすることもできません。ほとんどのブラウザー拡張機能は、安全なサンドボックスの中に置いたままにしてください。Full page access(ページ全体へのアクセス)と表示されたパッケージは別です。

コードはMarinaraのページの中で、サンドボックスなしで動きます。
チャットやカードを読み取り、ブラウザーのストレージを使い、ネットワーク通信を行い、Marinara自身のAPIを呼び出せます。
有効にするのは、そのバージョンのコードを確認し、信頼できると判断したあとだけにしてください。
Professor Mariの下書きがこれを要求することはできません。

旧形式のもの、プロファイルからインポートされたもの、手作業で保存されたもの、出所が不明なレコードも、外部として扱われます。これらは2つの手順が両方とも済むまで、表示されず、承認できず、実行もされません。

どちらかの設定をオフにすると、インポートしたすべての拡張機能が無効になります。もう一度オンにしても、再び実行されることはありません。ページ全体へのアクセスを持つ拡張機能が変更を残した場合は、ページを再読み込みしてください。

うまくいかなかった場合: インポートの操作が表示されないときは、2つの手順が両方とも済んでいることを確認してください。あわせて、サーバーのコンピューターで操作しているか、Settings → Advanced → Admin Access(設定 → 詳細設定 → 管理者アクセス)に管理者用のシークレットを保存していることも確認してください。

エクスポート、リビジョン、トラブル時の対処

拡張機能のエクスポート操作を使うと、持ち運べるパッケージをダウンロードできます。エクスポートしたパッケージも、復元したパッケージも無効のままです。リビジョンを復元した場合も、無効の下書きに戻ります。

Settings → Addons → Extension revision history(設定 → アドオン → 拡張機能のリビジョン履歴)では、すべての個人用拡張機能と外部拡張機能について、以前のコードを何版保持するかを指定します。デフォルトは10です。0から10までを選べ、0にすると履歴を残しません。上限を下げると、古いリビジョンを完全に削除する前に確認が表示されます。現在のコード、承認、有効状態、保存済みの拡張機能データは保持されます。Professor Mariを通じた編集にも同じ上限が適用されます。

拡張機能の動作がおかしいときは、Disable(無効にする)を選びます。画面を操作できない場合は、Marinaraを停止し、該当するinstalled_extensionsレコードのenabledの値を"false"にします。approvedHashは絶対に手作業で設定しないでください。