LogoNotyra Docs
プラグイン

権限と通信

同意・通信先・プライベートアドレス・エラーの扱い

Permission は notyra.permissions に { name, purpose? } として宣言します。purpose は開発者が利用目的を説明する文字列で、Notyra の定義する権限説明と並んで表示されます。

Permission必要な API
notes:readnotes.listRootFolders、list、read
notes:writenotes.create、update、rename、move、delete
clipboardclipboard.readText、writeText
shell:openExternalshell.openExternal
networknetwork.fetch。通信先の宣言も必要

CSS・パネル・Markdown・エディタ・コマンド・キー・設定・アクティブノート通知には Permission は不要です。権限不足なら処理を呼ぶ前に permissionDenied で拒否します。インストール時は権限0件でも同意を求めます。更新で新しい権限・宛先を増やすと追加分への同意を求め、減らしたものは同意済み一覧から取り除きます。

通信先の書式

networkDestinations の要素は api.example.com、*.example.com、localhost:11434、192.168.1.10:8080、[::1]:3000 のように宣言します。URL のスキーム・パス・認証情報は含めません。ポートは1〜65535。未指定は実効ポート80または443だけに一致します。指定した場合はそのポートにだけ一致します。ホスト名は大文字小文字を区別しません。

*.example.com は a.example.com や a.b.example.com に一致し、example.com 自体には一致しません。IP は値として照合します。ホスト名 localhost だけを Private とし、foo.localhost やワイルドカードは Public です。

Private の範囲は 0.0.0.0/32、::/128、127.0.0.0/8、::1、RFC1918 の 10.0.0.0/8・172.16.0.0/12・192.168.0.0/16、リンクローカル 169.254.0.0/16・fe80::/10、IPv6 ユニークローカル fc00::/7 です。IPv4 射影 IPv6 は IPv4 として扱います。CGNAT 100.64.0.0/10 は Public です。

Public として同意した名前が Private IP に解決される場合は、未指定アドレスも含めて送信前にブロックします。localhost が Private 外に解決される場合もブロックします。検査済みアドレスへの接続を固定し、リダイレクト先も毎回照合します。

HTTP/HTTPS のみ、リダイレクトは最大10回、各要求は名前解決から受信完了まで30秒、応答本文は10 MiBまでです。プロキシ設定は使いません。Host・接続制御用ヘッダーなどは上書きできません。例外的に長い通信をするコマンドも、ホストから呼ばれるコマンド自体の10秒制限に注意してください。

エラー

kind内容
permissionDenied必要な Permission がない。details にバックエンドの権限情報を含む場合がある
schemeNotAllowed通信の http/https、外部リンクの http/https/mailto 以外
blocked未同意のホスト・ポート、リダイレクト先、または DNS 解決結果の違反
outOfScope登録済みルート外のノートパス
notFound / nameConflictノートがない、または名前変更先が使用済み
deleteRejected削除確認でユーザーがキャンセル
timeout / tooManyRedirects / responseTooLarge通信の時間・回数・サイズ上限
network / io通信またはファイル操作の失敗
invalidArgument / pluginNotActive引数が不正、または停止後の呼び出し

blocked のバックエンド情報には host、port、reason が入り、理由は notDeclared・redirectNotDeclared・resolvedToPrivate・resolvedToNonPrivate です。例外を握りつぶさず、必要ならエラーパネルで利用者に伝えてください。

Permission は API の誤用を防ぐゲートで、第三者コードを完全に隔離するサンドボックスではありません。信頼できる配布元を選び、秘密情報をプラグインのソースや配布 ZIP に含めないでください。