Cakupan operator

Cakupan operator menentukan apa yang boleh dilakukan klien Gateway setelah terautentikasi. Cakupan ini adalah pagar pembatas bidang kontrol di dalam satu domain operator Gateway tepercaya, bukan isolasi multi-penyewa yang bermusuhan. Jika Anda membutuhkan pemisahan kuat antara orang, tim, atau mesin, jalankan Gateway terpisah di bawah pengguna OS atau host yang berbeda.

Terkait: Keamanan, protokol Gateway, pemasangan Gateway, CLI Perangkat.

# Peran

Klien WebSocket Gateway terhubung dengan satu peran:

• operator: klien bidang kontrol seperti CLI, UI Kontrol, automasi, dan proses pembantu tepercaya.
• node: host kapabilitas seperti macOS, iOS, Android, atau Node tanpa antarmuka yang mengekspos perintah melalui node.invoke.

Metode RPC operator memerlukan peran operator. Metode yang berasal dari Node memerlukan peran node.

# Tingkat cakupan

Cakupan	Arti
operator.read	Status baca-saja, daftar, katalog, log, pembacaan sesi, dan panggilan bidang kontrol lain yang tidak mengubah data.
operator.write	Tindakan operator pengubah data normal seperti mengirim pesan, memanggil alat, memperbarui pengaturan bicara/suara, dan relai perintah Node. Juga memenuhi operator.read.
operator.admin	Akses administratif bidang kontrol. Memenuhi setiap cakupan operator.*. Diperlukan untuk mutasi konfigurasi, pembaruan, hook native, namespace sensitif yang dicadangkan, dan persetujuan berisiko tinggi.
operator.pairing	Pengelolaan pemasangan perangkat dan Node, termasuk mencantumkan, menyetujui, menolak, menghapus, merotasi, dan mencabut catatan pemasangan atau token perangkat.
operator.approvals	API persetujuan exec dan Plugin.
operator.talk.secrets	Membaca konfigurasi Talk dengan rahasia yang disertakan.

Cakupan operator.* mendatang yang tidak dikenal memerlukan kecocokan tepat kecuali pemanggil memiliki operator.admin.

# Cakupan metode hanyalah gerbang pertama

Setiap RPC Gateway memiliki cakupan metode dengan hak istimewa minimum. Cakupan metode itu menentukan apakah permintaan dapat mencapai handler. Beberapa handler kemudian menerapkan pemeriksaan yang lebih ketat pada waktu persetujuan berdasarkan hal konkret yang disetujui atau dimutasi.

Contoh:

• device.pair.approve dapat dijangkau dengan operator.pairing, tetapi menyetujui perangkat operator hanya dapat mencetak atau mempertahankan cakupan yang sudah dimiliki pemanggil.
• node.pair.approve dapat dijangkau dengan operator.pairing, lalu menurunkan cakupan persetujuan tambahan dari daftar perintah Node yang tertunda.
• chat.send biasanya merupakan metode bercakupan tulis, tetapi /config set dan /config unset persisten memerlukan operator.admin pada tingkat perintah.

Ini memungkinkan operator bercakupan lebih rendah melakukan tindakan pemasangan berisiko rendah tanpa membuat semua persetujuan pemasangan hanya untuk admin.

# Persetujuan pemasangan perangkat

Catatan pemasangan perangkat adalah sumber tahan lama untuk peran dan cakupan yang disetujui. Perangkat yang sudah dipasangkan tidak mendapatkan akses lebih luas secara diam-diam: koneksi ulang yang meminta peran lebih luas atau cakupan lebih luas akan membuat permintaan peningkatan baru yang tertunda.

Saat menyetujui permintaan perangkat:

• Permintaan tanpa peran operator tidak memerlukan persetujuan cakupan token operator.
• Permintaan untuk operator.read, operator.write, operator.approvals, operator.pairing, atau operator.talk.secrets mengharuskan pemanggil memiliki cakupan tersebut, atau operator.admin.
• Permintaan untuk operator.admin memerlukan operator.admin.
• Permintaan perbaikan tanpa cakupan eksplisit dapat mewarisi cakupan token operator yang ada. Jika token yang ada tersebut bercakupan admin, persetujuan tetap memerlukan operator.admin.

Untuk sesi token perangkat yang dipasangkan, pengelolaan bercakupan mandiri kecuali pemanggil juga memiliki operator.admin: pemanggil non-admin hanya melihat entri pemasangannya sendiri, hanya dapat menyetujui atau menolak permintaan tertunda miliknya sendiri, dan hanya dapat merotasi, mencabut, atau menghapus entri perangkatnya sendiri.

# Persetujuan pemasangan Node

node.pair.* legacy menggunakan penyimpanan pemasangan Node terpisah yang dimiliki Gateway. Node WS menggunakan pemasangan perangkat dengan role: node, tetapi kosakata tingkat persetujuan yang sama berlaku.

node.pair.approve menggunakan daftar perintah permintaan tertunda untuk menurunkan cakupan tambahan yang diperlukan:

• Permintaan tanpa perintah: operator.pairing
• Perintah Node non-exec: operator.pairing + operator.write
• system.run, system.run.prepare, atau system.which: operator.pairing + operator.admin

Pemasangan Node menetapkan identitas dan kepercayaan. Ini tidak menggantikan kebijakan persetujuan exec system.run milik Node sendiri.

# Autentikasi rahasia bersama

Autentikasi token/kata sandi gateway bersama diperlakukan sebagai akses operator tepercaya untuk Gateway tersebut. Permukaan HTTP yang kompatibel dengan OpenAI dan /tools/invoke memulihkan kumpulan cakupan default operator penuh yang normal untuk autentikasi bearer rahasia bersama, meskipun pemanggil mengirim cakupan deklaratif yang lebih sempit.

Mode yang membawa identitas, seperti autentikasi proksi tepercaya atau none ingress privat, tetap dapat menghormati cakupan deklaratif eksplisit. Gunakan Gateway terpisah untuk pemisahan batas kepercayaan yang nyata.