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

35.1 Επισκόπηση

Κατάσταση: Η σελίδα αποτελεί τεχνική αναφορά για την υλοποίηση Automations 0.92.1. Δεν ισχυρίζεται διαθεσιμότητα για πελάτες· η επαλήθευση στο staging και η ενεργοποίηση παραγωγής είναι ξεχωριστά στάδια.

Τα Sophea Automations είναι αποκλειστικό runtime ροών εργασίας με UI που προσαρτάται στο web app του Nous. Το Portal υπογράφει βραχύβια token εκκίνησης μέσω του BFF του Nous· οι έμπιστες ενέργειες Sophea χρησιμοποιούν τον broker του Nous για λειτουργίες γνώσης και agent. Το έγγραφο περιγράφει τα όρια υπηρεσιών, τον κύκλο ζωής ταυτότητας και τη διάδοση ACL με συγκεκριμένο πεδίο εφαρμογής.

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

Τα Sophea Automations περιλαμβάνουν αποκλειστικό runtime υπηρεσίας Activepieces και ενσωματωμένη προσάρτηση frontend:

1. Runtime Automations: αποκλειστικά API, workers και flow engine με δικούς τους πόρους PostgreSQL και Redis.
2. Ενσωματωμένο UI: το web app του Nous προσαρτά το frontend runtime Automations σε Shadow DOM στη διαδρομή /app/automations· δεν εκτελείται μέσα στο backend του Nous ούτε σε iframe.

Τα έμπιστα Sophea pieces καλούν broker endpoints του Nous για λειτουργίες που υποστηρίζει το Nous. Το runtime δεν αποκτά άμεση πρόσβαση στη βάση δεδομένων του Nous.

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

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

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

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

Browser
  -> Nous web app: `/app/automations`
     -> Το `AutomationsHost` προσαρτά το `mountNousAutomations` σε Shadow DOM
        -> BFF ίδιας προέλευσης: `POST /api/automations/embed-token`
           -> backend Nous: `/automations/embed-token`
              -> signer Portal: `/api/internal/automations/embed-token`
                 (έλεγχος υπηρεσίας με `X-Client-ID`)
              <- βραχύβιο υπογεγραμμένο token εκκίνησης δεσμευμένο στην
                 ταυτότητα Portal, στον Workspace και στο έργο Automations
        -> αποκλειστικό frontend/API runtime Automations
           -> αποκλειστικά Activepieces API, workers και flow engine
              -> αποκλειστικά PostgreSQL + Redis του Automations
              -> έμπιστα Sophea pieces -> υπογράφων Automations API -> Nous broker
                 -> Nous RAG (υπογεγραμμένα ACL principals για αναζήτηση γνώσης)
                 -> Agent Service
              -> proxy μοντέλων Portal για Generate/Refine

35.3 Το μοτίβο broker

Ο broker είναι η έμπιστη διαδρομή για ενέργειες που υποστηρίζει το Nous: οι κλήσεις των Sophea pieces χρησιμοποιούν HTTP endpoints στο backend του Nous, υπογεγραμμένα με HMAC, αντί για άμεση πρόσβαση στη βάση δεδομένων του Nous.

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

1. Ένα βήμα ροής εκτελείται στο runtime των Automations.
2. Το Sophea piece στέλνει μια επιτρεπόμενη λειτουργία και το επιχειρησιακό payload στο Automations API με το τυποποιημένο Engine token του.
3. Το API επαληθεύει την ουρά και την ενεργή εργασία του token και ανακτά έργο, χώρο εργασίας, μισθωτή, εκτέλεση, βήμα και μέλος εκκίνησης από εγγραφές του διακομιστή.
4. Το API υπολογίζει την υπογραφή HMAC-SHA256 και στέλνει το αίτημα στο διαμορφωμένο broker endpoint του Nous.
5. Το Nous επαληθεύει την υπογραφή και τη συμμετοχή στον χώρο εργασίας πριν εκτελέσει τη λειτουργία.

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

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

35.3.3 Υπογραφή HMAC

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

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

Οι κατάλογοι ιδιοτήτων διατηρούν run ID execute-property και το αντίστοιχο βήμα καταλόγου. Το payload παραλείπει το attempt_no· η υπογραφή χρησιμοποιεί προσπάθεια 0. Οι λειτουργίες εκτέλεσης μοντέλου διατηρούν operation IDs που περιλαμβάνουν την προσπάθεια.

Το SOPHEA_AUTOMATIONS_BROKER_SECRET μοιράζεται μεταξύ Automations API και backend του Nous και δεν μεταβιβάζεται σε θυγατρικές διεργασίες engine ή pieces. Το API στέλνει την υπογραφή στην κεφαλίδα Authorization ως Bearer ${timestamp}.${signature}. Ο πιστοποιημένος engine παραμένει έμπιστος για τις δηλώσεις βήματος και προσπάθειας μέσα στη δική του ενεργή εργασία και έργο· οι δηλώσεις αυτές δεν αποτελούν ανεξάρτητη κρυπτογραφική πιστοποίηση.

Πρόσθετες κεφαλίδες: - 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 (εάν έχει οριστεί)

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

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

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

1. Αντιστοίχιση έργου στον διακομιστή: το Automations API ανακτά τον χώρο εργασίας και τον μισθωτή από το έργο της πιστοποιημένης ενεργής εργασίας.
2. Αιτήματα προς τον broker: το API δημιουργεί το workspace_id και τα πεδία ταυτότητας· τα επιχειρησιακά payloads των pieces δεν μπορούν να τα αντικαταστήσουν.
3. Ερωτήματα βάσης δεδομένων: το backend του Nous ανοίγει μια συνεδρία βάσης δεδομένων περιορισμένη στον μισθωτή για κάθε κλήση προς τον broker

35.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(): ανοίγει μια συνεδρία βάσης δεδομένων περιορισμένη στον μισθωτή και εκτελεί τη λειτουργία

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

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

Η λειτουργία shell καθορίζει επίσης τον τρόπο εκτέλεσης κώδικα. Η διαμόρφωση ανάπτυξης της Sophea ορίζει το AP_EXECUTION_MODE σε SANDBOX_CODE_ONLY. Τα βήματα Code εκτελούνται από προεπιλογή σε V8 isolate (isolated-vm). Ένα βήμα Code με ενεργό το Deno εκτελείται σε διεργασία Deno μίας εκτέλεσης, και το Deno είναι διαθέσιμο μόνο στη λειτουργία SANDBOX_CODE_ONLY. Οι εκφράσεις προτύπων { } εκτελούνται πάντα σε V8 isolates.

Ο κώδικας V8 λαμβάνει αντίγραφα των εισόδων και δεν διαθέτει Node built-ins. Η διεργασία Deno δεν έχει δικαιώματα δικτύου, πρόσβασης στο περιβάλλον ή δημιουργίας υποδιεργασιών και μπορεί να διαβάσει τον κατάλογο του βήματος. Η λειτουργία SANDBOX_CODE_ONLY απενεργοποιεί τις εξαρτήσεις npm στα βήματα Code.

Ο έμπιστος κώδικας των Sophea pieces εκτελείται έξω από αυτά τα sandbox κώδικα χρήστη, σε ξεχωριστή διεργασία Node που δημιουργεί ο engine. Η διεργασία αυτή κληρονομεί το περιβάλλον του engine εκτός από το AP_SANDBOX_WS_TOKEN, ώστε ο έμπιστος κώδικας piece να χρησιμοποιεί το SOPHEA_AUTOMATIONS_BROKER_SECRET για να υπογράφει κλήσεις προς τον broker. Τα βήματα Code του χρήστη δεν λαμβάνουν αυτό το μυστικό. Εάν το AP_EXECUTION_MODE οριστεί σε UNSANDBOXED ενώ η λειτουργία shell είναι ενεργή, ο engine απορρίπτει τον συνδυασμό και αποτυγχάνει με ασφαλή τρόπο (fail closed), ώστε ένα σφάλμα διαμόρφωσης να μην μπορεί να επαναφέρει σιωπηρά την εκτέλεση κώδικα εντός διεργασίας.

Το UNSANDBOXED παραμένει μόνο για ρητή ανάπτυξη από έμπιστο χειριστή με τη λειτουργία shell απενεργοποιημένη και δεν αποτελεί ποτέ επιλογή παραγωγής της Sophea. Τα V8 isolates δεν αποτελούν όριο πυρήνα και εκτελούνται μέσα στη διεργασία του engine. Η υποδιεργασία των trusted pieces προορίζεται για ελεγμένο κώδικα, όχι για μη έμπιστο κώδικα ροής.

35.5 Διάδοση ACL

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

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

1. Δημόσια έγγραφα: PUBLIC_DOC_PAT.
2. Έγγραφα συγκεκριμένου χρήστη: το principal κανονικοποιημένου email του χρήστη από το prefix_user_email(email).
3. Έγγραφα εξωτερικών ομάδων: principals ομάδων που επιλύονται για το email του χρήστη από το fetch_external_group_ids_for_email.

Το ACL υπογράφεται με NOUS_RAG_SERVICE_AUTH_KEY μέσω HMAC-SHA256 και αποστέλλεται στην υπηρεσία RAG στο X-Sophea-Principals. Αυτό περιγράφει την εξουσιοδότηση για αναζήτηση γνώσης· δεν συνεπάγεται καθολικά δικαιώματα για connectors ή άλλα εξωτερικά συστήματα.

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

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

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

Οι κλήσεις υπηρεσιών της Sophea έχουν διαφορετικά συμβόλαια. Ο πίνακας περιγράφει μόνο κεφαλίδες broker και RAG· ο έλεγχος ταυτότητας webhook διαμορφώνεται ξεχωριστά σε κάθε trigger Catch Webhook.

Κεφαλίδα	Πεδίο και σκοπός
Authorization	Αίτημα προς τον broker του Nous υπογεγραμμένο με HMAC
X-Sophea-Automation-Project-ID	Έργο Automations για αίτημα προς broker
X-Sophea-Automation-Run-ID	Αναγνωριστικό εκτέλεσης ροής
X-Sophea-Automation-Step-ID	Αναγνωριστικό βήματος ροής
X-Sophea-Operation-ID	Αναγνωριστικό συσχέτισης λειτουργίας
X-Sophea-Tenant-ID	Περιλαμβάνεται όταν έχει επιλυθεί tenant
X-Sophea-User-ID	Περιλαμβάνεται όταν έχει επιλυθεί χρήστης που ενεργεί
X-Sophea-Principals	Υπογεγραμμένο ACL προς την υπηρεσία RAG, όχι γενική κεφαλίδα broker

35.6 Σχετική τεκμηρίωση

• Connectors επιχειρησιακού επιπέδου
• Sophea και γενικά εργαλεία αυτοματοποίησης
• Τοποθέτηση προϊόντος: docs/product-06-sophea-automations.md
• Ενσωμάτωση RAG: docs/product-04-sophea-nous-rag.md
• Ενσωμάτωση Portal: docs/product-02-sophea-nous-portal.md