docs: align connector enrollment with Cloud

Author: abrichr

docs/BYOC_CONNECTOR.md

@@ -23,7 +23,7 @@ inbound ports.**
 ## The loop (all outbound)
 
 ```
-register -> POST /api/connector/register   enroll once, get a per-connector token
+create   -> authenticated Cloud settings  mint a revocable org-scoped token once
 poll     -> POST /api/connector/poll        long-poll; lease the next queued job
 execute  -> openadapt-flow run ...          the governed admission gate + Replayer,
                                              against the CUSTOMER'S own storage
@@ -39,22 +39,24 @@ the *same* fail-closed `openadapt-flow run` you would run locally.
 ```bash
 pip install openadapt-flow
 
-# 1. Enroll this machine once (mints + persists a per-connector token, 0600).
-openadapt-flow connector enroll \
+# 1. In app.openadapt.ai, open Dashboard → Settings →
+#    Customer-controlled connector, create a connector, and copy its token once
+#    into this machine's service manager or secret store.
+export BYOC_CONNECTOR_TOKEN='<shown-once token>'
+
+# 2. Run the daemon (poll -> execute -> report -> ack, until interrupted).
+openadapt-flow connector run \
   --control-plane-url https://app.openadapt.ai \
-  --enrollment-secret "$BYOC_ENROLLMENT_SECRET" \
   --org-id org_your_clinic \
   --profile /opt/openadapt/deployment.yaml \
   --storage-backend local \
   --storage-root /srv/openadapt        # a full-disk-encrypted customer volume
-
-# 2. Run the daemon (poll -> execute -> report -> ack, until interrupted).
-openadapt-flow connector run
 ```
 
-Enrollment persists to `~/.openadapt/connector.toml` (mode 0600 — it holds the
-token). A bare `connector run` reads it back. Every flag also resolves from an
-env var (`CONTROL_PLANE_URL`, `BYOC_CONNECTOR_TOKEN`, `BYOC_ORG_ID`, ...).
+Every flag also resolves from an environment variable
+(`CONTROL_PLANE_URL`, `BYOC_CONNECTOR_TOKEN`, `BYOC_ORG_ID`, ...).
+`connector enroll` remains available for mock/development control planes; live
+Cloud token creation is authenticated and organization-scoped in the dashboard.
 
 ## Data boundary and safety
 
@@ -95,8 +97,9 @@ authorizing a fresh run.
 ## Enabling the lane (control plane)
 
 The lane is off by default. An operator enables it with
-`BYOC_ENABLED=true` **and** a configured `BYOC_ENROLLMENT_SECRET`, and flips the
-org's `deployment_kind` to `byoc`. See openadapt-cloud `src/lib/byocLane.ts`.
+`BYOC_ENABLED=true` and authenticated run callbacks
+(`RUNNER_SHARED_SECRET`), then sets the organization's `deployment_kind` to
+`byoc`. See openadapt-cloud `src/lib/byocLane.ts`.
 
 ## What works today vs. what remains for production
 
@@ -112,9 +115,9 @@ org's `deployment_kind` to `byoc`. See openadapt-cloud `src/lib/byocLane.ts`.
 
 **Remaining for production:**
 
-* **Hardened auth.** Enrollment is a single org-shared secret today; production
-  wants per-org (ideally short-lived, rotating) enrollment tokens, plus
-  mTLS/private-link between the Connector and the control plane.
+* **Private transport options.** Connector tokens are organization-scoped,
+  revocable, and stored only as hashes in Cloud. Deployments that require
+  mTLS/private-link add that transport at the customer network boundary.
 * **Full policy materialization.** The delivered safety block governs *dispatch*
   and the two fail-closed gates above; materializing every safety key into the
   engine's runtime config (so e.g. the delivered grounding endpoint is the one

openadapt_flow/__main__.py

@@ -3411,7 +3411,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     pe = csub.add_parser(
         "enroll",
-        help="Enroll this machine as a Connector and persist the token (0600)",
+        help="Enroll against a mock/development control plane and persist its token",
     )
     pe.add_argument(
         "--control-plane-url", help="Control plane base URL (or CONTROL_PLANE_URL)"
@@ -3632,8 +3632,9 @@ def _cmd_connector(args: argparse.Namespace) -> int:
     # verb == "run"
     if not settings.token:
         print(
-            "connector run: not enrolled. Run `openadapt-flow connector enroll` "
-            "first, or pass --token / BYOC_CONNECTOR_TOKEN."
+            "connector run: no token. Create an organization connector in "
+            "OpenAdapt Cloud → Settings, then pass --token or set "
+            "BYOC_CONNECTOR_TOKEN."
         )
         return 2
     client = ConnectorClient(settings.control_plane_url, token=settings.token)

openadapt_flow/connector/__init__.py

@@ -7,15 +7,16 @@
 PHI-free status/halt metadata ever flows back to the control plane.
 
 Loop (all outbound HTTPS; zero inbound ports):
-    register -> POST /api/connector/register   (enroll once, get a token)
+    create   -> authenticated Cloud settings  (mint an org-scoped token once)
     poll     -> POST /api/connector/poll        (long-poll; lease the next job)
     execute  -> the governed ``openadapt-flow run`` admission gate + Replayer
                 (identity gates + effect verification + halt-don't-guess intact),
                 against the CUSTOMER'S own storage
     callback -> POST /api/internal/run-callback (PHI-free status/metrics)
     ack      -> POST /api/connector/ack         (only after callback acceptance)
 
-CLI: ``openadapt-flow connector enroll`` then ``openadapt-flow connector run``.
+CLI: create the token in Cloud settings, then ``openadapt-flow connector run``.
+``connector enroll`` is retained for mock/development control planes.
 """
 
 from openadapt_flow.connector.client import ConnectorClient, ConnectorClientError

openadapt_flow/connector/client.py

@@ -6,14 +6,15 @@
 runner or a Citrix Cloud Connector). The customer opens ZERO inbound ports.
 
 Endpoints (all outbound):
-  * ``POST /api/connector/register``     enroll once -> per-connector token
+  * ``POST /api/connector/register``     mock/dev enrollment compatibility
   * ``POST /api/connector/poll``         long-poll -> lease the next job
   * ``POST /api/connector/ack``          release the lease (done|failed)
   * ``POST /api/internal/run-callback``  PHI-free status/metrics (existing boundary)
 
-Auth: the per-connector token as ``Authorization: Bearer`` on poll/ack; the org
-enrollment secret (``x-byoc-enrollment-secret``) once on enroll; the run-scoped
-``x-run-token`` on the callback. Only ``httpx`` (already core) + stdlib is used.
+Auth: the organization-scoped per-connector token as ``Authorization: Bearer``
+on poll/ack and the run-scoped ``x-run-token`` on the callback. Live Cloud
+mints the connector token through its authenticated settings API; the legacy
+enrollment secret is used only by mock/development control planes.
 
 A custom ``transport`` (an :class:`httpx.BaseTransport`) may be injected so tests
 drive the whole enroll -> poll -> callback -> ack loop with ZERO network.