36  Πώς λειτουργούν τα Sophea Automations

36.1 Επισκόπηση

Τα Sophea Automations αποτελούν το επίπεδο αυτοματοποίησης ροών εργασίας της πλατφόρμας Sophea. Εκτελούνται ενσωματωμένα στο backend του Nous και χρησιμοποιούν από κοινού με την υπόλοιπη πλατφόρμα τον έλεγχο ταυτότητας, την απομόνωση μισθωτών και τα δικαιώματα. Αυτό το έγγραφο εξηγεί την αρχιτεκτονική, το μοτίβο broker και τον τρόπο λειτουργίας της απομόνωσης μισθωτών και της διάδοσης ACL.

36.2 Αρχιτεκτονική

Τα Sophea Automations αποτελούνται από δύο στοιχεία:

  1. Automations API server (TypeScript, Fastify): διαχειρίζεται τις ροές, την εκτέλεση και το web περιβάλλον δημιουργίας
  2. Automations web frontend (React, Vite): το οπτικό περιβάλλον δημιουργίας ροών και ο πίνακας ελέγχου

Και τα δύο στοιχεία εκτελούνται στο namespace του Nous στο Kubernetes. Το Automations API επικοινωνεί με το backend του Nous μέσω broker endpoints υπογεγραμμένων με HMAC και με την υπηρεσία RAG μέσω υπογεγραμμένων ACL principals.

36.2.1 Κύκλος ζωής ταυτότητας και πρόσβασης

Ο λογαριασμός Automations συνδέεται με τη σταθερή ταυτότητα χρήστη στο Portal και όχι με μια διεύθυνση email. Επομένως, η αλλαγή ή η εκ νέου εκχώρηση ενός email δεν συγχωνεύει λογαριασμούς Automations ούτε μεταφέρει την πρόσβασή τους.

Η πλατφόρμα Automations παρέχεται από τον διαχειριστή της πλατφόρμας πριν ενεργοποιηθεί η πρόσβαση πελατών. Το άνοιγμα των Automations μπορεί να δημιουργήσει το έργο και τη συμμετοχή του μέλους για τον χώρο εργασίας, αλλά δεν μπορεί να δημιουργήσει την πλατφόρμα ούτε να εκχωρήσει δικαιώματα διαχειριστή πλατφόρμας.

Σε κάθε αίτημα χρήστη προς ένα έργο χώρου εργασίας, τα Automations ελέγχουν στο Portal την τρέχουσα πραγματική συμμετοχή στον χώρο εργασίας πριν εφαρμόσουν τον τοπικό ρόλο έργου. Η κατάργηση μιας άμεσης πρόσβασης ή μιας πρόσβασης που προέρχεται από Ομάδα ή Οργανισμό αποκλείει το επόμενο αίτημα του μέλους, ακόμη και αν χρησιμοποιείται υπάρχουσα συνεδρία Automations. Αν το Portal δεν μπορεί να επιβεβαιώσει τη συμμετοχή, η πρόσβαση απορρίπτεται με ασφαλή τρόπο.

Browser
  |
  v
Nous (nginx reverse proxy)
  |
  +--> Automations API (Fastify, TypeScript)
  |       |
  |       +--> Nous Broker (HMAC-signed HTTP)
  |       |      |
  |       |      +--> Nous RAG (signed ACL principals)
  |       |      +--> Agent Service (X-Sophea headers)
  |       |      +--> Portal (HMAC bearer auth)
  |       |
  |       +--> Flow Engine (Code steps and {{ }} expressions run in V8 isolates)
  |
  +--> Nous Backend (FastAPI, Python)

36.3 Το μοτίβο broker

Το μοτίβο broker είναι ο βασικός μηχανισμός ασφαλείας των Sophea Automations. Αντί να παρέχεται στο Automations API άμεση πρόσβαση στη βάση δεδομένων, όλες οι λειτουργίες δεδομένων περνούν από HTTP endpoints στο backend του Nous, τα οποία είναι υπογεγραμμένα με HMAC.

36.3.1 Πώς λειτουργεί

  1. Ένα βήμα ροής εκτελείται στο sandbox των Automations
  2. Η ενέργεια του Sophea piece καλεί τη postToNousBrokerRaw() με μια διαδρομή broker και ένα payload
  3. Ο client του broker (broker.ts) ανακτά την ταυτότητα του χώρου εργασίας από το περιβάλλον της ροής:
    • workspaceId από το context.project.externalId()
    • tenantId από την αντιστοίχιση του χώρου εργασίας
    • runAsUserId από το context.run.triggeredBy.externalId()
  4. Ο client υπολογίζει μια υπογραφή HMAC-SHA256 για το σώμα του αιτήματος και τα πεδία ταυτότητας
  5. Το υπογεγραμμένο αίτημα αποστέλλεται στο broker endpoint του backend του Nous
  6. Το backend του Nous επαληθεύει την υπογραφή HMAC, ελέγχει τη συμμετοχή στον χώρο εργασίας και εκτελεί τη λειτουργία

36.3.2 Γιατί είναι σημαντικό

  • Χωρίς άμεση πρόσβαση στη βάση δεδομένων: το Automations API δεν προσπελαύνει ποτέ απευθείας τη βάση δεδομένων του Nous
  • Επιβολή απομόνωσης μισθωτών στο όριο: κάθε αίτημα προς τον broker μεταφέρει την ταυτότητα του χώρου εργασίας, η οποία επαληθεύεται σε κάθε κλήση
  • Δυνατότητα ελέγχου: κάθε κλήση προς τον broker καταγράφεται με workspace ID, run ID, step ID και αριθμό προσπάθειας
  • Περιορισμός ρυθμού: τα broker endpoints μπορούν να επιβάλλουν όρια ρυθμού ανά χώρο εργασίας

36.3.3 Υπογραφή HMAC

Η υπογραφή HMAC υπολογίζεται για το εξής:

${timestamp}.${sha256(body)}.${projectId}.${runId}.${stepId}.${attemptNo}

Υπογράφεται με το SOPHEA_AUTOMATIONS_BROKER_SECRET (κοινόχρηστο μεταξύ Automations API και backend του Nous). Η υπογραφή αποστέλλεται στην κεφαλίδα Authorization ως Bearer ${timestamp}.${signature}.

Πρόσθετες κεφαλίδες: - X-Sophea-Automation-Project-ID - X-Sophea-Automation-Run-ID - X-Sophea-Automation-Step-ID - X-Sophea-Operation-ID - X-Sophea-Tenant-ID (εάν έχει οριστεί) - X-Sophea-User-ID (εάν έχει οριστεί)

36.4 Απομόνωση μισθωτών

36.4.1 Ο χώρος εργασίας αντιστοιχεί στον μισθωτή

Στη Sophea, ένας χώρος εργασίας αντιστοιχεί σε έναν μισθωτή. Κάθε ροή, εκτέλεση και εκτέλεση piece περιορίζεται σε έναν χώρο εργασίας. Το workspace ID διαδίδεται μέσω των εξής:

  1. Περιβάλλον ροής: το context.project.externalId() επιστρέφει το workspace ID
  2. Αιτήματα προς τον broker: πεδίο workspace_id στο σώμα κάθε αιτήματος προς τον broker
  3. Ερωτήματα βάσης δεδομένων: το backend του Nous ανοίγει μια συνεδρία βάσης δεδομένων περιορισμένη στον μισθωτή για κάθε κλήση προς τον broker

36.4.2 Ασφάλεια broker endpoint

Κάθε broker endpoint ακολουθεί το ίδιο μοτίβο ασφαλείας:

  1. _headers_match_body(): επαληθεύει ότι η υπογραφή HMAC υπολογίστηκε για το ίδιο σώμα που παραλήφθηκε
  2. verify_automation_broker_authorization(): επαληθεύει την υπογραφή HMAC και τη χρονική σήμανση
  3. _verify_runtime_member(): ελέγχει ότι ο χρήστης που υπέβαλε το αίτημα είναι ενεργό μέλος του χώρου εργασίας
  4. _tenant_id_from_member(): ανακτά το tenant ID από τη συμμετοχή στον χώρο εργασίας
  5. _execute_runtime_broker_call(): ανοίγει μια συνεδρία βάσης δεδομένων περιορισμένη στον μισθωτή και εκτελεί τη λειτουργία

36.4.3 Λειτουργία shell

Η λειτουργία shell περιορίζει τα διαθέσιμα pieces σε μια ελεγμένη λίστα επιτρεπόμενων στοιχείων. Έτσι αποτρέπεται η εκτέλεση μη έμπιστων pieces σε περιβάλλοντα παραγωγής. Η λίστα επιτρεπόμενων στοιχείων ορίζεται στο nous-automations-shell.ts και περιλαμβάνει μόνο pieces εγκεκριμένα από τη Sophea.

Η λειτουργία shell καθορίζει επίσης τον τρόπο εκτέλεσης κώδικα. Σε κάθε περιβάλλον Sophea, το AP_EXECUTION_MODE είναι SANDBOX_CODE_ONLY: τα βήματα Code και οι εκφράσεις προτύπων { } εκτελούνται μέσα σε νέα V8 isolates (isolated-vm) αντί της διεργασίας του engine. Ο κώδικας στο sandbox λαμβάνει μόνο αντίγραφα των εισόδων του. Τα Node APIs (process, require, σύστημα αρχείων, πρόσβαση δικτύου, timers) δεν είναι διαθέσιμα και δεν είναι δυνατή η εγκατάσταση πακέτων npm. Ο έμπιστος κώδικας των Sophea pieces συνεχίζει να εκτελείται στη διεργασία του engine, όπου υπογράφει τις κλήσεις προς τον broker με το SOPHEA_AUTOMATIONS_BROKER_SECRET. Ο κώδικας χρήστη στο sandbox δεν μπορεί να διαβάσει αυτή τη διεργασία ούτε το περιβάλλον της. Εάν το AP_EXECUTION_MODE οριστεί σε UNSANDBOXED ενώ η λειτουργία shell είναι ενεργή, ο engine απορρίπτει τον συνδυασμό και αποτυγχάνει με ασφαλή τρόπο (fail closed), ώστε ένα σφάλμα διαμόρφωσης να μην μπορεί να επαναφέρει σιωπηρά την εκτέλεση κώδικα εντός διεργασίας. Το UNSANDBOXED παραμένει μόνο για ρητή ανάπτυξη από έμπιστο χειριστή με τη λειτουργία shell απενεργοποιημένη και δεν αποτελεί ποτέ επιλογή παραγωγής της Sophea. Η απομόνωση V8 δεν αποτελεί όριο πυρήνα. Η απομόνωση σε επίπεδο διεργασίας παραμένει μελλοντική ενίσχυση.

36.5 Διάδοση ACL

36.5.1 Υπογεγραμμένα ACL principals

Όταν ένα βήμα ροής πραγματοποιεί αναζήτηση στη βάση γνώσης, το broker endpoint δημιουργεί υπογεγραμμένα ACL principals που καθορίζουν σε ποια έγγραφα μπορεί να έχει πρόσβαση η αναζήτηση. Το ACL δημιουργείται από:

  1. Δημόσια έγγραφα: PUBLIC_DOC_PAT (όλα τα μέλη του χώρου εργασίας έχουν πρόσβαση)
  2. Έγγραφα συγκεκριμένου χρήστη: prefix_user_email(email) (έγγραφα περιορισμένα στο email του χρήστη)

Το ACL υπογράφεται με το NOUS_RAG_SERVICE_AUTH_KEY μέσω HMAC-SHA256 και αποστέλλεται στην υπηρεσία RAG στην κεφαλίδα X-Sophea-Principals.

36.5.2 Πώς λειτουργεί

  1. Το broker endpoint λαμβάνει το αίτημα αναζήτησης με την ταυτότητα του χώρου εργασίας και του χρήστη
  2. Η _signed_principals_for_member() δημιουργεί το ACL για τον χρήστη που υπέβαλε το αίτημα
  3. Το ACL υπογράφεται και αποστέλλεται στην υπηρεσία RAG
  4. Η υπηρεσία RAG επαληθεύει την υπογραφή και φιλτράρει τα αποτελέσματα αναζήτησης ώστε να περιλαμβάνουν μόνο έγγραφα στα οποία έχει πρόσβαση ο χρήστης

Έτσι διασφαλίζεται ότι τα βήματα ροής μπορούν να προσπελάσουν μόνο έγγραφα τα οποία έχει δικαίωμα να δει ο χρήστης που υπέβαλε το αίτημα, ακόμη και όταν εκτελούνται σε αυτοματοποιημένο περιβάλλον.

36.6 Κεφαλίδες μεταξύ υπηρεσιών

Όλες οι κλήσεις μεταξύ υπηρεσιών μεταφέρουν κεφαλίδες ειδικές για τη Sophea:

Κεφαλίδα Σκοπός
X-Sophea-Tenant-ID Υποχρεωτική: προσδιορίζει τον μισθωτή
X-Sophea-Run-ID Κλειδί idempotency για το Agent Service
X-Sophea-User-ID Προαιρετική: προσδιορίζει τον χρήστη
X-Sophea-Operation-ID Ιχνηλάτηση και συσχέτιση
X-Sophea-Principals Υπογεγραμμένο ACL για την υπηρεσία RAG
X-Sophea-Signature Υπογραφή HMAC για webhook triggers
X-Sophea-Timestamp Χρονική σήμανση για την επαλήθευση υπογραφής webhook