lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/commands/connect.py

@@ -0,0 +1,717 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse connect <provider>`: open the provider's own approval.
+
+    lighthouse connect                 # what is connected, and what can be
+    lighthouse connect github
+    lighthouse connect aws --no-browser
+    lighthouse connect gitlab --reuse-local     # offers `glab`'s sign-in; asks first
+    security find-generic-password -s gh-ci -w | \
+        lighthouse connect github --credential-stdin --access read_write \
+            --target organisation=example-air       # an existing token, as you
+    ... | lighthouse connect github --credential-stdin \
+            --deployment-key "$(terraform output -raw deployment_public_key)"
+
+**What this command does and does not do.** It opens the portal's Connect page
+for this tenant, which is where the provider's own approval is started:
+GitHub's app installation, GitLab's OAuth approval, Datadog's integration
+approval, the cloud roles' stack. It does not write
+the connection itself, and that is deliberate rather than unfinished: the CLI
+holds a *delegated* token, and a delegated token may never administer
+(`docs/adr/0012-delegated-credentials.md`).
+
+It opens `/connect` rather than `/connect/<provider>`, because the portal has
+one Connect page and not one per connector. A deep link that 404s is worse
+than a page with the right card on it, so the provider is named in this
+command's own output instead.
+Connecting a provider gives LightHouse standing access to a company's estate,
+so it is approved by a person in the portal, under their own second factor,
+and audited there — never by a token sitting in a shell history or a CI
+variable.
+
+So what the CLI saves a developer is the part that is actually tedious: finding
+the right screen, with the right scopes, for the right tenant. One command
+instead of four clicks.
+
+**What is offered comes from the service.** The listing reads
+`GET /api/v1/connectors`, the same catalogue the portal's Connect page shows:
+each connector's `state` is `available` (connect it now), `engineer` (your
+engineer configures it in your deployment; it is read today) or `coming`. The
+CLI keeps no list of its own except as a fallback for a role that may not read
+the catalogue, and says so when it uses it.
+
+**Reusing a local sign-in.** Where `gh`, `glab` or a Datadog key is already set
+up on this machine, `--reuse-local` offers to use it instead of a fresh
+approval. It is offered **only on an explicit yes**: never on `--yes`, never
+under `--no-input`, and never without naming exactly which local credential
+would be read and where it would go. A tool that quietly harvested the
+credentials it found on a developer's laptop would be indistinguishable from
+one that should not be trusted. On that yes, and only then, the credential is
+asked of the tool that owns it (`gh auth token`, `glab config get token`, or
+`DD_API_KEY` and `DD_APP_KEY` from this shell, with `DD_SITE`), and handed
+straight to the same path as `--credential-stdin` below: sealed on this
+machine to your deployment where it can keep it, as you, never printed.
+Refused, and said why, under `--yes`, under `--no-input`, when standard input
+is not a terminal, on any answer but `yes`, and when the tool will not give
+one.
+
+**Feeding an existing token (`--credential-stdin`).** A token that already
+exists (in a laptop's Keychain, in `gh auth token`, in a password manager) is
+connected exactly as if the client's administrator had pasted it on the
+Connect page: the same `POST /api/v1/connectors/<id>/token`, the same check at
+the provider, the same sealing, the same audit entry naming them. Three rules
+make that safe to script:
+
+- **It is the person, not the CLI's token.** Connecting is administration, and
+  a delegated token administers nothing (ADR 0012), so this request carries
+  the person's own Cloudflare Access session for the tenant host instead,
+  from `cloudflared access token` (they sign in once with `cloudflared access
+  login https://<host>`, second factor included). The service sees a client
+  administrator at their own keyboard, which is what they are; the delegated
+  token is not sent at all. AAL staff and machine keys are refused by the
+  service as they are on the page.
+- **The credential is read from standard input, never from an argument.** So
+  it is in no shell history, no process listing and no log. It is never
+  printed: the answer is the connection's card, which holds a fingerprint and
+  no credential.
+- **Read is the default.** `--access read_write` is the administrator's
+  explicit choice, and the service refuses a token whose scopes disagree with
+  it (`credential_can_write`, `credential_cannot_write`), as the page does.
+- **Finance, aviation, ERP and HR read only (contracts 1.27, 1.28).**
+  `--access read_write` for one of them is refused here, before standard input is read, with the
+  card's own reason (`read_only_connector`), and the service and the
+  deployment refuse it too.
+
+**Sealed on this machine (contract 1.18).** Where the tenant's deployment
+advertises a sealing key and both sides switched `secret.put` on
+(`GET /api/v1/connectors/sealing`), the token is sealed here, to the
+deployment's own key (`lighthouse/sealing.py`), and only the sealed blob, its
+keyed fingerprint and the connection id it was sealed for are sent: the
+control plane never sees the token, and the deployment writes it to the
+client's own secrets store and checks it at the provider. With
+`--deployment-key` (or `LIGHTHOUSE_DEPLOYMENT_KEY`), the deployment's public
+key as the client's own infrastructure printed it, the advertisement must be
+signed by exactly that key: a substituted sealing key is refused before
+anything is sealed, and a deployment that cannot seal is refused rather than
+sent the token in the clear. Without a pin, the advertisement is checked
+against the keys the control plane says the deployment registered (the
+Connect page's trust), and where nothing can seal, the token is sent as
+before and sealed under the tenant's own key, which the answer says.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import re
+import shutil
+import subprocess  # noqa: S404  # nosec B404 - asks `gh`/`glab` if they are signed in
+from dataclasses import dataclass
+from typing import Any
+
+from lighthouse import sealing
+from lighthouse.device import open_browser
+from lighthouse.exits import FAILED, USAGE, CliError
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+@dataclass(frozen=True)
+class Provider:
+    name: str
+    label: str
+    family: str                 # the service's family (1.26), or cloud for a deployment target
+    state: str                  # available | engineer | upgrade | coming | onboarding
+    scopes: str
+    local: str | None = None    # the local tool whose sign-in could be reused
+    why: str = ""
+    kind: str = ""              # what it holds (1.26): Mail, CRM, Service desk ...
+    read_only_why: str = ""     # 1.27: why it connects read-only (finance, aviation), or ""
+
+    @property
+    def built(self) -> bool:
+        """Whether LightHouse reads it today: connectable in the portal, or
+        configured by the client's engineer."""
+        return self.state in ("available", "engineer")
+
+
+# The local tool whose sign-in `--reuse-local` could offer, by connector id.
+LOCAL = {"github": "gh", "gitlab": "glab", "datadog": "datadog"}
+FAMILY = {"github": "code", "gitlab": "code", "datadog": "observability"}
+
+# What is known without asking the service: the three connectors LightHouse
+# connects today, with the read-only scopes the control plane asks for, and the
+# four places the engine can be deployed. **The service's catalogue
+# (`GET /api/v1/connectors`) is the authority**: `connect` reads it and uses this
+# table only when it cannot (a role that may not read it, say), and for the
+# deployment targets, which are not connectors.
+FALLBACK: tuple[Provider, ...] = (
+    Provider("aws", "Amazon Web Services", "cloud", "available",
+             "a scoped role created by the one-click stack; read-only outside the engine"),
+    Provider("azure", "Microsoft Azure", "cloud", "available",
+             "a scoped app registration created by the Bicep stack"),
+    Provider("gcp", "Google Cloud", "cloud", "available",
+             "a scoped service account created by the Terraform stack"),
+    Provider("docker", "Your own servers (Docker or Podman)", "cloud", "available",
+             "no cloud credential: Compose runs the engine in your own estate"),
+    Provider("github", "GitHub", "code", "available",
+             "contents:read, metadata:read, issues:read, pull_requests:read", local="gh"),
+    Provider("gitlab", "GitLab", "code", "available",
+             "read_api", local="glab"),
+    Provider("datadog", "Datadog", "observability", "available",
+             "monitors_read, incident_read, notebooks_read", local="datadog"),
+    # The engine reads these; a client's own engineer configures them in the
+    # deployment's catalogue, so they are not connectable in the portal yet.
+    Provider("gdrive", "Google Drive", "data", "engineer", "drive.readonly"),
+    Provider("confluence", "Confluence", "data", "engineer", "read:content:confluence"),
+    Provider("jira", "Jira", "data", "engineer", "read:jira-work"),
+    Provider("upload", "File upload", "data", "engineer", "none: you upload the files"),
+    # The engine does not read these yet.
+    Provider("sharepoint", "SharePoint", "data", "coming", "Sites.Selected (read)"),
+    Provider("onedrive", "OneDrive", "data", "coming", "Files.Read.All"),
+    Provider("s3", "Amazon S3", "data", "coming",
+             "s3:GetObject, s3:ListBucket on the named prefix"),
+    Provider("azure-blob", "Azure Blob Storage", "data", "coming", "Storage Blob Data Reader"),
+    Provider("salesforce", "Salesforce", "data", "coming",
+             "api, refresh_token (read-only profile)"),
+    Provider("servicenow", "ServiceNow", "data", "coming", "snc_read_only"),
+    Provider("slack", "Slack", "data", "coming", "channels:history, files:read"),
+    Provider("teams", "Microsoft Teams", "data", "coming", "ChannelMessage.Read.All"),
+    Provider("postgres", "PostgreSQL", "data", "coming", "a read-only role you create"),
+    Provider("snowflake", "Snowflake", "data", "coming", "a read-only role you create"),
+)
+BY_NAME = {p.name: p for p in FALLBACK}
+
+
+def from_catalogue(card: dict[str, Any]) -> Provider:
+    """A provider as the service describes it: its `state` is the service's own
+    (`available` to connect now, `engineer` where the client's engineer
+    configures it, `coming` where the engine does not read it yet)."""
+    name = str(card.get("connector"))
+    return Provider(name, str(card.get("name") or name),
+                    str(card.get("family") or FAMILY.get(name, "data")),
+                    str(card.get("state") or ("available" if card.get("available") else "coming")),
+                    ", ".join(card.get("scopes") or []) or str(card.get("brings") or ""),
+                    local=LOCAL.get(name), why=str(card.get("why") or ""),
+                    kind=str(card.get("kind") or ""),
+                    read_only_why=str(card.get("read_only_why") or ""))
+
+
+def connect_url(host: str) -> str:
+    """Where a person approves a connection: the portal's one Connect page.
+
+    Not `/connect/<provider>`: the portal has a single page listing every
+    connector, so a per-provider path would be a 404 — and a link that 404s
+    teaches a developer to stop following this command's links.
+    """
+    return f"https://{host}/connect"
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("provider", nargs="?",
+                    help="the provider to connect; `list` (or nothing) to list them")
+    ap.add_argument("--family", default=None,
+                    help="with list: one family (google, microsoft, oracle, crm, ...)")
+    ap.add_argument("--kind", default=None,
+                    help="with list: what it holds (crm, mail, service-desk, ...)")
+    ap.add_argument("--search", default=None,
+                    help="with list: words to find in the name, family, kind or description "
+                         "(\"email\" finds Mail, \"tickets\" finds Service desk)")
+    ap.add_argument("--state", default=None,
+                    choices=("available", "engineer", "upgrade", "coming", "onboarding"),
+                    help="with list: only connectors in this state")
+    ap.add_argument("--no-browser", action="store_true", dest="no_browser",
+                    help="print the approval URL instead of opening it")
+    ap.add_argument("--reuse-local", action="store_true", dest="reuse_local",
+                    help="offer to reuse a sign-in already on this machine (asks first)")
+    ap.add_argument("--all", action="store_true", dest="every",
+                    help="with no provider: list the coming ones too")
+    ap.add_argument("--credential-stdin", action="store_true", dest="credential_stdin",
+                    help="connect an existing token, read from standard input, as yourself "
+                         "(needs `cloudflared access login https://<host>`)")
+    ap.add_argument("--access", choices=("read", "read_write"), default="read",
+                    help="with --credential-stdin: read (the default) or read_write")
+    ap.add_argument("--target", action="append", default=[], metavar="KEY=VALUE",
+                    help="with --credential-stdin: what the connection points at "
+                         "(organisation=..., instance_url=..., site=...); repeatable")
+    ap.add_argument("--deployment", default=None,
+                    help="with --credential-stdin: the deployment that keeps the credential, "
+                         "where the tenant has more than one")
+    ap.add_argument("--deployment-key", default=None, dest="deployment_key", metavar="KEY",
+                    help="with --credential-stdin: pin the deployment's public key (base64 or "
+                         "PEM, as your infrastructure printed it); the token is sealed only to "
+                         "a sealing key that key signed (or LIGHTHOUSE_DEPLOYMENT_KEY)")
+
+
+# -- an existing token, as the person --------------------------------------------
+
+_TARGET_KEY = re.compile(r"^[a-z_]{1,40}$")
+_HOST = re.compile(r"^[a-z0-9][a-z0-9.-]{0,252}[a-z0-9]$")
+
+
+def person_session(host: str) -> str:
+    """The person's own Cloudflare Access session for `host`, from
+    `cloudflared access token`. Its output is the token and is never printed;
+    a failure says how to sign in rather than what cloudflared said."""
+    hint = f"sign in first: cloudflared access login https://{host}"
+    tool = shutil.which("cloudflared")
+    if not _HOST.match(host) or tool is None:
+        raise CliError("connecting a token needs your own portal session, from cloudflared",
+                       code=USAGE, error="no_session", hint=hint)
+    try:
+        # A fixed argument vector, the tool's resolved path and a checked
+        # hostname: never a shell.
+        done = subprocess.run(  # noqa: S603  # nosec B603
+            [tool, "access", "token", f"-app=https://{host}"],
+            capture_output=True, timeout=30, check=False, shell=False, text=True)
+    except (OSError, subprocess.SubprocessError):
+        raise CliError("cloudflared did not answer", code=USAGE, error="no_session",
+                       hint=hint) from None
+    token = (done.stdout or "").strip()
+    if done.returncode != 0 or not token or any(c.isspace() for c in token):
+        raise CliError("there is no portal session for this host on this machine",
+                       code=USAGE, error="no_session", hint=hint)
+    return token
+
+
+def _targets(pairs: list[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for pair in pairs:
+        key, sep, value = pair.partition("=")
+        if not sep or not _TARGET_KEY.match(key) or not value.strip():
+            raise CliError(f"--target is KEY=VALUE, not {key!r}", code=USAGE,
+                           error="bad_target")
+        out[key] = value.strip()
+    return out
+
+
+def _read_credential(ctx: Context) -> str:
+    """The credential, from standard input. Piped, it is read whole (a Datadog
+    key pair and an Atlassian credential are two lines; a Google key is a
+    file); at a terminal, it is asked for without echo."""
+    import sys
+    stream = ctx.stdin or sys.stdin
+    if stream.isatty():
+        if getattr(ctx.args, "no_input", False):
+            raise CliError("pipe the credential in: --no-input is set", code=USAGE,
+                           error="no_credential")
+        got = getpass.getpass("Paste the credential (not shown): ")
+    else:
+        got = stream.read()
+    got = got.rstrip("\r\n")
+    if len(got.strip()) < 8:
+        raise CliError("no credential on standard input", code=USAGE, error="no_credential",
+                       hint="pipe it in: security find-generic-password -s <name> -w | "
+                            "lighthouse connect <provider> --credential-stdin")
+    return got
+
+
+def _pin(ctx: Context) -> bytes | None:
+    text = getattr(ctx.args, "deployment_key", None) or ctx.env.get("LIGHTHOUSE_DEPLOYMENT_KEY")
+    if not text:
+        return None
+    try:
+        return sealing.load_deployment_key(text)
+    except sealing.SealingError as e:
+        raise CliError(str(e), code=USAGE, error="bad_deployment_key") from None
+
+
+def _sealer(ctx: Context, client: Any, provider: Provider) -> dict[str, Any] | None:
+    """Where this credential can be sealed to, or None to send it as before.
+
+    A pinned deployment key makes sealing a requirement: nothing is sent in
+    the clear, and an advertisement that key did not sign stops everything."""
+    pinned = _pin(ctx)
+    try:
+        info = client.get("/api/v1/connectors/sealing") or {}
+    except CliError as e:
+        # A control plane before 1.18 has no such route.
+        if pinned is None and e.extra.get("status") in (404, 405):
+            return None
+        raise
+    wanted = getattr(ctx.args, "deployment", None)
+    ready = [d for d in info.get("deployments") or [] if d.get("ready") and d.get("sealing")
+             and (wanted is None or d.get("deployment") == wanted)]
+    if provider.name not in (info.get("connectors") or []) or not ready:
+        if pinned is not None:
+            why = next((d.get("why") for d in info.get("deployments") or [] if d.get("why")), "")
+            raise CliError("your deployment cannot keep this credential in your own store, so "
+                           "it was not sent", code=FAILED, error="sealing_unavailable",
+                           hint=why or None)
+        return None
+    if len(ready) > 1:
+        raise CliError("more than one deployment can keep it: name one with --deployment",
+                       code=USAGE, error="deployment_required",
+                       hint=", ".join(sorted(str(d["deployment"]) for d in ready)))
+    dep = ready[0]
+    full = f"{info.get('tenant')}/{dep['deployment']}"
+    keys = [pinned] if pinned is not None else [
+        base64.b64decode(k) for k in dep.get("deployment_keys") or []]
+    if not sealing.verify_advert(dep["sealing"], full, keys):
+        raise CliError("the sealing key LightHouse relayed is not signed by "
+                       + ("the deployment key you pinned" if pinned else
+                          "your deployment's registered key")
+                       + "; nothing was sent", code=FAILED, error="sealing_key_unverified")
+    return {"deployment": dep["deployment"], "full": full, "public": dep["sealing"]["public"],
+            "fingerprint_key": base64.b64decode(info.get("fingerprint_key") or ""),
+            "pinned": pinned is not None}
+
+
+def _sealed_body(where: dict[str, Any], provider: Provider, credential: str,
+                 target: dict[str, str]) -> dict[str, Any]:
+    try:
+        fields = sealing.credential_fields(provider.name, credential, target)
+    except sealing.SealingError as e:
+        raise CliError(str(e), code=USAGE, error="bad_credential") from None
+    cid = sealing.connection_id()
+    body = {"sealed": sealing.seal(where["public"], sealing.canonical(fields),
+                                   deployment=where["full"], connector=provider.name, name=cid),
+            "fingerprint": sealing.fingerprint(fields, where["fingerprint_key"]),
+            "connection": cid, "deployment": where["deployment"], "target": target,
+            "sealed_by": "cli"}
+    fields.clear()
+    return body
+
+
+def _connect_token(ctx: Context, provider: Provider, credential: str | None = None,
+                   target: dict[str, str] | None = None) -> dict[str, Any]:
+    """`POST /api/v1/connectors/<id>/token` as the person: the credential
+    sealed here to the deployment where it can keep it (1.18), otherwise in
+    the request body and nowhere else. Dropped once sent either way. Given
+    `credential` (a reused local sign-in), standard input is not read."""
+    if provider.state != "available":
+        raise CliError(f"{provider.label} cannot be connected with a token here "
+                       f"({provider.state})", code=USAGE, error="not_connectable")
+    target = {**_targets(getattr(ctx.args, "target", []) or []), **(target or {})}
+    access = getattr(ctx.args, "access", "read") or "read"
+    if access != "read" and (provider.name in sealing.WAVE_046
+                             or provider.name in sealing.WAVE_047):
+        # 1.27: finance and aviation read only; refused here, before anything
+        # is read from standard input or sealed.
+        raise CliError(provider.read_only_why or f"{provider.label} connects read-only; "
+                       "connect it with --access read", code=USAGE, error="read_only_connector")
+    credential = credential if credential is not None else _read_credential(ctx)
+    host = ctx.host
+    client = ctx.new_client(host, None, session=person_session(host))
+    path = f"/api/v1/connectors/{provider.name}/token"
+    where = None
+    try:
+        where = _sealer(ctx, client, provider)
+        if where is None and (provider.name in sealing.ENTERPRISE
+                              or provider.name in sealing.WAVE_046
+                              or provider.name in sealing.WAVE_047):
+            # Contracts 1.26 to 1.28: these are sealed here or not sent at all.
+            engine = ("0.47.1" if provider.name in sealing.WAVE_047
+                      else "0.46.0" if provider.name in sealing.WAVE_046 else "0.45.0")
+            raise CliError(f"{provider.label}'s credential is only ever sealed to your "
+                           f"deployment, which cannot keep it yet (engine {engine} with its own "
+                           "store); nothing was sent", code=FAILED, error="sealing_required")
+        if where is None:
+            body: dict[str, Any] = {"credential": credential, "target": target}
+        else:
+            body = _sealed_body(where, provider, credential, target)
+        if access != "read":
+            body["access"] = access
+        try:
+            got = client.post(path, body) or {}
+        except CliError as e:
+            # The deployment rotated its sealing key since it was read: seal
+            # again to the new one, once.
+            if where is None or e.error not in ("sealing_key_changed", "conflict"):
+                raise
+            where = _sealer(ctx, client, provider)
+            if where is None:
+                raise
+            body = {**_sealed_body(where, provider, credential, target),
+                    **({"access": access} if access != "read" else {})}
+            got = client.post(path, body) or {}
+    finally:
+        credential = ""
+        client.close()
+    pending = bool(got.get("pending"))
+    return {"ok": True, "provider": provider.name, "label": provider.label,
+            "connected": not pending, "pending": pending, "connection": got.get("id"),
+            "access": got.get("access"),
+            "can_write": got.get("can_write"), "write_scopes": got.get("write_scopes") or [],
+            "access_note": got.get("access_note"), "state": got.get("state"),
+            "fingerprint": got.get("fingerprint"), "replaced": got.get("replaced") or [],
+            "card": got.get("label"),
+            "sealed_by": got.get("sealed_by") or ("cli" if where else None),
+            "pinned": bool(where and where["pinned"]),
+            "deployment": got.get("deployment"), "custody": got.get("custody"),
+            "reason": got.get("reason") if pending else None,
+            "command": (got.get("command") or {}).get("command_id") if pending else None}
+
+
+# -- detecting a local sign-in ---------------------------------------------------
+
+def _ran_ok(argv: list[str]) -> bool:
+    """Whether a local tool reports itself signed in. Its output is never read
+    and never printed: a token could be in it."""
+    if shutil.which(argv[0]) is None:
+        return False
+    try:
+        # A fixed argument vector from the table above: never a shell, and never
+        # anything a person typed.
+        done = subprocess.run(argv, capture_output=True, timeout=10,  # noqa: S603  # nosec B603
+                              check=False, shell=False)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.returncode == 0
+
+
+def local_signin(provider: Provider, env: dict[str, str]) -> dict[str, Any] | None:
+    """What is already signed in on this machine for `provider`, or None.
+
+    Only the *fact* of a sign-in is established — never the credential. The
+    credential is read only after a person says yes, and then by the tool that
+    owns it, not by reading its files.
+    """
+    if provider.local == "gh" and _ran_ok(["gh", "auth", "status"]):
+        return {"tool": "gh", "how": "`gh auth token` would be asked for the token"}
+    if provider.local == "glab" and _ran_ok(["glab", "auth", "status"]):
+        return {"tool": "glab", "how": "`glab config get token` would be asked for the token"}
+    if provider.local == "datadog" and env.get("DD_API_KEY") and env.get("DD_APP_KEY"):
+        return {"tool": "environment",
+                "how": "DD_API_KEY and DD_APP_KEY are set in this shell"}
+    return None
+
+
+def catalogue(ctx: Context) -> tuple[dict[str, Provider], list[dict[str, Any]], str]:
+    """The connectors and the connections, from `GET /api/v1/connectors`.
+
+    Returns `(providers by name, connections, source)`. Where the service will
+    not say (exit 3 or 4: a role that may not read it), the built-in table
+    stands in, `source` says `built-in`, and the command warns, so a label is
+    never presented as the service's when it is the CLI's.
+    """
+    query = _filters(ctx)
+    try:
+        body = ctx.client().get("/api/v1/connectors", **query) or {}
+    except CliError as e:
+        if e.code not in (3, 4):
+            raise
+        ctx.out.warn(f"could not read the connector catalogue ({e.error}); "
+                     f"showing what this CLI knows")
+        return dict(BY_NAME), [], "built-in"
+    found = {str(c.get("connector")): from_catalogue(c) for c in body.get("connectors") or []}
+    # Deployment targets are not connectors, so the catalogue does not list
+    # them; a filtered listing is the catalogue's alone.
+    for p in FALLBACK:
+        if p.family == "cloud" and not query:
+            found.setdefault(p.name, p)
+    live = [c for c in body.get("connections") or [] if c.get("state") != "disconnected"]
+    return found, live, "service"
+
+
+def _filters(ctx: Context) -> dict[str, str]:
+    """`--family`, `--kind`, `--search` and `--state`, as the service's query
+    parameters (contract 1.26). The service matches them: synonyms, case and
+    partial words, the same rules as the portal and the docs."""
+    got = {"family": getattr(ctx.args, "family", None), "kind": getattr(ctx.args, "kind", None),
+           "q": getattr(ctx.args, "search", None), "state": getattr(ctx.args, "state", None)}
+    return {k: str(v) for k, v in got.items() if v}
+
+
+def _local_match(p: Provider, query: dict[str, str]) -> bool:
+    """The built-in table's stand-in for the service's filters: exact family,
+    kind and state, and every search word somewhere in the label or family."""
+    def norm(v: str) -> str:
+        return re.sub(r"[\s_\-]+", " ", v.strip().lower())
+    hay = norm(f"{p.name} {p.label} {p.family} {p.kind} {p.scopes}")
+    return ((not query.get("family") or norm(p.family) == norm(query["family"]))
+            and (not query.get("kind") or norm(p.kind) == norm(query["kind"]))
+            and (not query.get("state") or p.state == query["state"])
+            and all(w in hay for w in norm(query.get("q", "")).split()))
+
+
+def _listing(ctx: Context) -> dict[str, Any]:
+    known, connections, source = catalogue(ctx)
+    live = {str(c.get("connector")) for c in connections}
+    query = _filters(ctx)
+    every = getattr(ctx.args, "every", False) or bool(query)
+    rows = [p for p in known.values() if (p.built or every)
+            and (source == "service" or _local_match(p, query))]
+    return {"ok": True, "source": source, "filters": query, "providers": [
+        {"provider": p.name, "label": p.label, "family": p.family, "kind": p.kind,
+         "status": "connected" if p.name in live else p.state,
+         "scopes": p.scopes,
+         "connect": connect_url(ctx.host)} for p in rows],
+        "connected": len(live)}
+
+
+def _show_listing(out: Out, body: dict[str, Any]) -> None:
+    out.table(["provider", "what", "family", "kind", "status", "read-only scopes"],
+              [[p["provider"], p["label"], p["family"], p.get("kind", ""), p["status"],
+                p["scopes"]] for p in body["providers"]])
+    if not body["providers"]:
+        out.note("no connector matches; ask for one from Help, or tell your Atlantic contact")
+    out.note("`lighthouse connect <provider>` opens the approval; `--all` lists the coming "
+             "ones too; `connect list --family F --kind K --search WORDS` narrows the list")
+
+
+def connect(ctx: Context) -> dict[str, Any]:
+    name = getattr(ctx.args, "provider", None)
+    if not name or name == "list":
+        return _listing(ctx)
+    known, _connections, _source = catalogue(ctx)
+    provider = known.get(name.lower())
+    if provider is None:
+        raise CliError(f"{name!r} is not a provider LightHouse knows", code=USAGE,
+                       error="unknown_provider",
+                       hint="run `lighthouse connect --all` to see every one")
+    if getattr(ctx.args, "credential_stdin", False):
+        return _connect_token(ctx, provider)
+    url = connect_url(ctx.host)
+    out: dict[str, Any] = {"ok": True, "provider": provider.name, "label": provider.label,
+                           "status": provider.state,
+                           "approval_url": url, "scopes": provider.scopes,
+                           "opened": False, "reuse": None}
+    if provider.state == "coming":
+        out["message"] = (f"connecting {provider.label} is coming; the page lists it and says so")
+    elif provider.state == "engineer":
+        out["message"] = provider.why or (f"{provider.label} is configured by your engineer in "
+                                           f"your deployment, not connected from the portal")
+    if getattr(ctx.args, "reuse_local", False):
+        found = local_signin(provider, ctx.env)
+        if found is None:
+            out["reuse"] = {"offered": False,
+                            "reason": f"no local sign-in for {provider.label} on this machine"}
+        else:
+            out["reuse"] = _offer_reuse(ctx, provider, found)
+            if out["reuse"].get("sent"):
+                return {**out["reuse"]["connection"], "reuse": {
+                    k: v for k, v in out["reuse"].items() if k != "connection"}}
+    if not ctx.args.no_browser:
+        out["opened"] = open_browser(url, opener=ctx.opener)
+    return out
+
+
+DD_SITES = {v: k for k, v in sealing.DATADOG_ENGINE_SITES.items()}
+
+
+def _tool_output(argv: list[str]) -> str | None:
+    """The first line a local tool prints, or None. Never printed or logged:
+    it is a credential."""
+    tool = shutil.which(argv[0])
+    if tool is None:
+        return None
+    try:
+        # A fixed argument vector from this module, the tool's resolved path:
+        # never a shell, never anything typed.
+        done = subprocess.run([tool, *argv[1:]], capture_output=True,  # noqa: S603  # nosec B603
+                              timeout=15, check=False, shell=False, text=True)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    got = (done.stdout or "").strip().splitlines()
+    if done.returncode != 0 or not got or any(c.isspace() for c in got[0].strip()):
+        return None
+    return got[0].strip()
+
+
+def read_local(provider: Provider, env: dict[str, str]) -> tuple[str, dict[str, str]] | None:
+    """The credential, from the tool that owns it, and what it points at.
+    Called only after a person typed yes."""
+    if provider.local == "gh":
+        token = _tool_output(["gh", "auth", "token"])
+        return (token, {}) if token else None
+    if provider.local == "glab":
+        host = (env.get("GITLAB_HOST") or "gitlab.com").strip()
+        if not re.match(r"^[a-z0-9][a-z0-9.-]{0,252}$", host.lower()):
+            return None
+        token = _tool_output(["glab", "config", "get", "token", "--host", host])
+        target = {} if host == "gitlab.com" else {"instance_url": f"https://{host}"}
+        return (token, target) if token else None
+    if provider.local == "datadog":
+        api, app = env.get("DD_API_KEY", "").strip(), env.get("DD_APP_KEY", "").strip()
+        if not api or not app:
+            return None
+        site = DD_SITES.get(env.get("DD_SITE", "").strip().lower(), "")
+        return f"{api}\n{app}", ({"site": site} if site else {})
+    return None
+
+
+def _offer_reuse(ctx: Context, provider: Provider, found: dict[str, Any]) -> dict[str, Any]:
+    """Ask, in as many words, before touching a credential this machine holds.
+
+    `--yes` does not answer this one, and neither does a pipe. A blanket yes on
+    the command line is consent to the command's own work, not consent to hand
+    a developer's personal GitHub token to a service, and the two must not be
+    the same keystroke; a `yes` piped into standard input is not a person.
+    """
+    import sys
+    question = (f"Reuse the {found['tool']} sign-in on this machine for {provider.label}? "
+                f"{found['how']}. It would be sealed on this machine and sent to {ctx.host} "
+                f"as you, to be kept in your own deployment where it can, or under your "
+                f"tenant's own key")
+    refusal = ("no_input" if getattr(ctx.args, "no_input", False) else
+               "yes_flag" if getattr(ctx.args, "yes", False) else
+               "not_interactive" if not (ctx.stdin or sys.stdin).isatty() else
+               "not_connectable" if provider.state != "available" else None)
+    if refusal is not None:
+        why = {"no_input": "--no-input is set", "yes_flag": "--yes is not consent to hand "
+               "over a credential", "not_interactive": "standard input is not a terminal",
+               "not_connectable": f"{provider.label} is not connected with a token"}[refusal]
+        ctx.out.note(f"{question}: not asked, because {why}")
+        return {"offered": True, "accepted": False, "reason": refusal}
+    ctx.out.say(question + ".")
+    answer = (ctx.reader or input)("Type yes to use it, anything else to approve in the "
+                                   "browser instead: ").strip().lower()
+    if answer != "yes":
+        return {"offered": True, "accepted": False, "reason": "declined"}
+    got = read_local(provider, ctx.env)
+    if got is None:
+        return {"offered": True, "accepted": True, "sent": False, "tool": found["tool"],
+                "reason": "local_read_failed",
+                "message": f"{found['tool']} did not give a credential; nothing was sent"}
+    credential, target = got
+    try:
+        connected = _connect_token(ctx, provider, credential=credential, target=target)
+    finally:
+        credential = ""
+    return {"offered": True, "accepted": True, "sent": True, "tool": found["tool"],
+            "connection": connected}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if "providers" in body:
+        _show_listing(out, body)
+        return
+    if body.get("pending"):
+        out.pairs([("sent to your own store", body.get("card") or body["label"]),
+                   ("deployment", body.get("deployment") or ""),
+                   ("access", "can write" if body.get("can_write") else "read only"),
+                   ("connection", body.get("connection") or "")])
+        out.note(body.get("reason") or "waiting for your deployment to keep it")
+        if body.get("custody"):
+            out.note(body["custody"])
+        if body.get("sealed_by") == "cli" and not body.get("pinned"):
+            out.note("pin --deployment-key to check the sealing key against your own "
+                     "infrastructure's record of the deployment")
+        return
+    if body.get("connected"):
+        out.pairs([("connected", body.get("card") or body["label"]),
+                   ("access", "can write" if body.get("can_write") else "read only"),
+                   ("state", body.get("state") or ""),
+                   ("connection", body.get("connection") or "")])
+        if body.get("access_note"):
+            out.note(body["access_note"])
+        if body.get("custody"):
+            out.note(body["custody"])
+        return
+    out.pairs([("provider", body["label"]), ("status", body["status"]),
+               ("read-only scopes", body["scopes"]), ("approve at", body["approval_url"])])
+    out.note(f"the Connect page lists every connector; use the {body['label']} card")
+    if body.get("message"):
+        out.warn(body["message"])
+    reuse = body.get("reuse")
+    if reuse and reuse.get("message"):
+        out.warn(reuse["message"])
+    elif reuse and reuse.get("offered") and not reuse.get("accepted"):
+        out.note("not reusing a local sign-in")
+    if body["opened"]:
+        out.note("opened in your browser")
+
+
+COMMANDS = (Command("connect", "open a provider's own approval for this tenant",
+                    _configure, connect, _show),)