strands-labs
diff --git a/‎CHANGELOG.md‎
Lines changed: 58 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 58 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 3 additions & 0 deletions b/‎README.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎strands_robots/mesh/iot/__init__.py‎
Lines changed: 5 additions & 5 deletions b/‎strands_robots/mesh/iot/__init__.py‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎strands_robots/mesh/iot/camera_offload.py‎
Lines changed: 81 additions & 12 deletions b/‎strands_robots/mesh/iot/camera_offload.py‎
Lines changed: 81 additions & 12 deletions
@@ -3,6 +3,64 @@
 All notable behavioural changes to `strands-robots` are logged here. Follows
 [Keep a Changelog](https://keepachangelog.com/) conventions.
 
+## Unreleased - #228 (AWS IoT provisioning hardening)
+
+### Changed: default presigned-URL TTL for camera offload
+
+``CameraOffloader.presign_ttl`` default is now **60 seconds** (was 3600s).
+A 1-hour ceiling (``MAX_PRESIGN_TTL_SECONDS``) is enforced; values above
+the cap are clamped with a ``WARNING``. The change shrinks the replay
+window for a captured ``strands/<thing>/camera/<cam>/ref`` MQTT message
+from one hour to one minute.
+
+Migration: deployments whose downstream consumers (review UIs,
+recording pipelines that fetch on a delay) need >60 seconds of validity
+should opt in explicitly:
+
+```bash
+export STRANDS_MESH_CAMERA_PRESIGN_TTL=3600   # legacy 1h
+```
+
+or pass ``presign_ttl=3600`` to ``CameraOffloader(...)`` / ``enable_for_mesh(...)``.
+
+### Added: AWS IoT provisioning hardening
+
+Applies to ``strands_robots.mesh.iot.provision`` and
+``strands_robots.mesh.iot.camera_offload``:
+
+- **CA pinning** — ``AmazonRootCA1.pem`` is verified against an
+  in-tree pin tuple (``_AMAZON_ROOT_CA1_PINS``) at download AND on
+  every on-disk re-use. Defeats CA-substitution MITM. Operators can
+  add additional pins via ``STRANDS_MESH_CA_PINS`` (comma-separated
+  64-char lowercase hex). The break-glass ``STRANDS_MESH_DISABLE_CA_PIN=true``
+  (case-insensitive) writes a ``.unverified`` sidecar marker (mode
+  ``0o600``) for audit traceability.
+- **Strict thing-name regex** (``^[a-zA-Z0-9_-]{1,128}$``,
+  ``re.fullmatch``) applied symmetrically across ``provision_robot``,
+  ``provision_operator``, and ``teardown_thing``. Rejects path
+  separators, dots, spaces, NUL, non-ASCII, and trailing
+  ``
+``/````/``	``. Pre-existing AWS IoT Things containing ``:``
+  must be renamed (we deliberately reject ``:`` due to NTFS / classic
+  Mac filesystem semantics).
+- **IoT policy scope** — robot/operator policies use explicit
+  per-thing topic prefixes; no ``Resource: '*'`` on Receive.
+  ``OperatorPublishToFleet``'s ``*/cmd`` wildcard is documented and
+  pinned as a deliberate design choice (``test_publish_to_fleet_wildcard_is_deliberate``).
+- **Per-recv TLS timeout bound** via custom ``HTTPSHandler`` (defeats
+  malicious-broker connection-stalling).
+- **``teardown_thing(cert_dir=...)`` kwarg** for parity with
+  ``provision_robot``/``provision_operator`` (closes stale-credential
+  leak on non-default ``cert_dir`` deployments).
+
+New env vars (documented in README Configuration matrix):
+``STRANDS_MESH_CA_PINS``, ``STRANDS_MESH_DISABLE_CA_PIN``,
+``STRANDS_MESH_CAMERA_PRESIGN_TTL``.
+
+Known follow-ups: #249 (camera privacy kill-switch + S3 ACL),
+#251 (chunked-read parity in ``_ensure_ca``), #259 (kwarg negative-TTL
+WARNING symmetry), #260 (warn on re-use of break-glass-written CA).
+
 ## Unreleased - #178 (LiberoOffScreenRenderEngine retired)
 
 ### Removed: ``LiberoOffScreenRenderEngine`` simulation backend (BREAKING)
 
@@ -501,6 +501,9 @@ agent.tool.gr00t_inference(action="stop", port=8000)
 | `ZENOH_CONNECT` | Comma-separated list of remote Zenoh endpoints to connect to | - |
 | `ZENOH_LISTEN` | Comma-separated list of endpoints for the local Zenoh listener | - |
 | `STRANDS_MESH_AUDIT_DIR` | Directory for the safety audit log (`mesh_audit.jsonl`) | `~/.strands_robots/` |
+| `STRANDS_MESH_CA_PINS` | Comma-separated SHA-256 hex pins, **additive** to the bundled Amazon Root CA1 pin tuple. Operator break-glass for an AWS-side root rotation that arrives before the next `strands-robots` release ships the new pin. Must match `^[0-9a-fA-F]{64}$` per entry. | unset |
+| `STRANDS_MESH_DISABLE_CA_PIN` | Set to `true` (case-insensitive) to skip CA pin verification on the *download* path only. The on-disk re-use path always raw-checks the pin regardless. Last-resort break-glass; prefer `STRANDS_MESH_CA_PINS` for rotations. | `false` |
+| `STRANDS_MESH_CAMERA_PRESIGN_TTL` | Default TTL (seconds) for S3 presigned URLs emitted on the IoT camera-offload path. Capped at 3600s (1h); a `0` is clamped to 1s. Non-integer values fall back to the default with a WARNING. | `60` |
 | `GROOT_API_TOKEN` | API token for GR00T inference service | - |
 | `STRANDS_ROBOT_MODE` | Override `Robot()` factory mode detection (`sim`, `real`, `auto`) | `auto` |
 | `STRANDS_TRUST_REMOTE_CODE` | Set to `1` to opt into HuggingFace `trust_remote_code` for `lerobot_local` policies | unset |
 
@@ -2,10 +2,10 @@
 
 This subpackage owns the cloud-side concerns of the mesh:
 
-- :mod:`provision`      — single-Thing bootstrap (cert + policy + Thing).
-- :mod:`bootstrap`      — account-wide bootstrap (Rules + Lambda +
+- :mod:`provision`  — single-Thing bootstrap (cert + policy + Thing).
+- :mod:`bootstrap`  — account-wide bootstrap (Rules + Lambda +
   DynamoDB audit + Fleet Provisioning template).
-- :mod:`shadow`         — Device Shadow named-shadow mirror of presence.
+- :mod:`shadow`  — Device Shadow named-shadow mirror of presence.
 - :mod:`camera_offload` — S3-backed camera frame offload.
 
 The wire-level transport (:class:`IotMqttTransport`) lives in
@@ -20,14 +20,14 @@
     from strands_robots.mesh.iot import bootstrap_account, provision_robot
 
     # 1. Once per AWS account/region: spin up Rules / Lambda / DynamoDB /
-    #    Fleet Provisioning template / etc.
+    #  Fleet Provisioning template / etc.
     bootstrap_account()
 
     # 2. Per robot: issue a cert + attach the strands-robot policy.
     p = provision_robot("so100-arm-01")
 
     # 3. Run the robot under the iot transport.
-    #    (export the env vars from p.env_vars() and `Robot()` Just Works.)
+    #  (export the env vars from p.env_vars() and `Robot()` Just Works.)
 
 For a single-robot dev setup, step 1 is optional — without it E-stop
 fan-out and DynamoDB audit just don't activate; everything else still
 
@@ -37,7 +37,23 @@
 ``STRANDS_MESH_CAMERA_S3_PREFIX``
     Optional prefix inside the bucket (defaults to ``""``).
 ``STRANDS_MESH_CAMERA_PRESIGN_TTL``
-    Seconds the presigned GET URL stays valid (default 3600).
+    Seconds the presigned GET URL stays valid. Defaults to
+    :data:`DEFAULT_PRESIGN_TTL_SECONDS` (60s); clamped at
+    :data:`MAX_PRESIGN_TTL_SECONDS` (1 hour) to prevent accidental
+    day- or week-long URLs. Pass ``presign_ttl=N`` to override
+    explicitly; the env-var fallback only applies when the kwarg is
+    ``None``.
+
+Bucket-ownership threat model
+-----------------------------
+The S3 PutObject path in :meth:`CameraOffloader._upload_frame` does
+not pass an ``ACL=`` kwarg. The contract for the offload bucket is
+that the operator configures it with object-ownership control
+``BucketOwnerEnforced`` (and a bucket policy that denies public
+ACLs); that enforcement is out of scope for this library because
+deployments differ on whether the bucket is shared with non-mesh
+producers. A future code-side ``ACL="private"`` + ``ChecksumAlgorithm``
+hardening is tracked in #249.
 """
 
 from __future__ import annotations
@@ -50,7 +66,13 @@
 logger = logging.getLogger(__name__)
 
 
-DEFAULT_PRESIGN_TTL_SECONDS = 3600
+# Lifetime of the presigned GET URL we hand out for each camera frame.
+# Kept deliberately short -- anyone who briefly captures a /ref MQTT message
+# can use the URL inside this window. ``STRANDS_MESH_CAMERA_PRESIGN_TTL``
+# overrides for higher-latency consumers, clamped to MAX_PRESIGN_TTL_SECONDS
+# (1 hour) to prevent accidental day- or week-long URLs.
+DEFAULT_PRESIGN_TTL_SECONDS = 60
+MAX_PRESIGN_TTL_SECONDS = 3600
 
 
 class CameraOffloader:
@@ -70,9 +92,46 @@ def __init__(
     ) -> None:
         self.bucket = bucket or os.getenv("STRANDS_MESH_CAMERA_S3_BUCKET", "")
         self.prefix = (prefix or os.getenv("STRANDS_MESH_CAMERA_S3_PREFIX") or "").strip("/")
-        self.presign_ttl = presign_ttl or int(
-            os.getenv("STRANDS_MESH_CAMERA_PRESIGN_TTL", str(DEFAULT_PRESIGN_TTL_SECONDS))
-        )
+        if presign_ttl is not None:
+            ttl_raw = presign_ttl
+        else:
+            raw_env = os.getenv("STRANDS_MESH_CAMERA_PRESIGN_TTL")
+            if raw_env is None or raw_env == "":
+                ttl_raw = DEFAULT_PRESIGN_TTL_SECONDS
+            else:
+                try:
+                    ttl_raw = int(raw_env)
+                except ValueError:
+                    logger.warning(
+                        "[camera_offload] STRANDS_MESH_CAMERA_PRESIGN_TTL=%r is not an integer; using default %ds",
+                        raw_env,
+                        DEFAULT_PRESIGN_TTL_SECONDS,
+                    )
+                    ttl_raw = DEFAULT_PRESIGN_TTL_SECONDS
+        if ttl_raw > MAX_PRESIGN_TTL_SECONDS:
+            logger.warning(
+                "[camera_offload] STRANDS_MESH_CAMERA_PRESIGN_TTL=%d > %d cap; clamping",
+                ttl_raw,
+                MAX_PRESIGN_TTL_SECONDS,
+            )
+            ttl_raw = MAX_PRESIGN_TTL_SECONDS
+        if ttl_raw < 1:
+            # Issue #262: WARN on any sub-1 value EXCEPT exactly 0.
+            # ``presign_ttl=0`` is the documented kwarg-vs-env-precedence
+            # sentinel pinned by ``test_presign_ttl_none_vs_zero.py`` (R1
+            # fix). ``presign_ttl=-99`` is unambiguously a bug at the call
+            # site -- no caller deliberately wants a negative TTL clamped
+            # to 1 -- and we surface it. The env-var path always WARNs
+            # (operator-side bug if STRANDS_MESH_CAMERA_PRESIGN_TTL=-99).
+            if presign_ttl is None or presign_ttl != 0:
+                source = "env" if presign_ttl is None else "kwarg"
+                logger.warning(
+                    "[camera_offload] presign_ttl=%d < 1 floor; clamping to 1s (source=%s)",
+                    ttl_raw,
+                    source,
+                )
+            ttl_raw = 1
+        self.presign_ttl = ttl_raw
         self.region = region or os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION"))
         self._s3: Any | None = None
 
@@ -120,7 +179,7 @@ def upload_frame(self, peer_id: str, cam_name: str, jpeg_bytes: bytes, ts: float
                 Body=jpeg_bytes,
                 ContentType="image/jpeg",
             )
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 -- boto3 raises ClientError, EndpointConnectionError, NoCredentialsError, etc.; offload is best-effort
             logger.debug("[camera_offload] put_object %s failed: %s", key, exc)
             return None
 
@@ -130,7 +189,7 @@ def upload_frame(self, peer_id: str, cam_name: str, jpeg_bytes: bytes, ts: float
                 Params={"Bucket": self.bucket, "Key": key},
                 ExpiresIn=self.presign_ttl,
             )
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 -- boto3 ClientError / NoCredentialsError; presign is best-effort
             logger.debug("[camera_offload] presign %s failed: %s", key, exc)
             url = None
 
@@ -181,7 +240,7 @@ def _publish_cameras_once_with_offload() -> None:
         # call it to preserve any user customisation that might have been added).
         try:
             original()
-        except Exception as exc:
+        except Exception as exc:  # noqa: BLE001 -- original is user-customised; offload must not block on user code
             logger.debug("[camera_offload] original _publish_cameras_once raised: %s", exc)
 
         # Now do the S3 offload + ref publish per camera.
@@ -195,13 +254,14 @@ def _publish_cameras_once_with_offload() -> None:
 
         try:
             obs = inner.get_observation()
-        except Exception:
+        except Exception as exc:  # noqa: BLE001 -- LeRobot get_observation() may raise hardware-specific errors
+            logger.debug("[camera_offload] get_observation failed: %s", exc)
             return
 
         try:
             import cv2
-        except Exception:
-            logger.debug("[camera_offload] cv2 unavailable — skipping S3 upload")
+        except ImportError:
+            logger.debug("[camera_offload] cv2 unavailable -- skipping S3 upload")
             return
 
         transport = current_transport()
@@ -231,8 +291,17 @@ def _publish_cameras_once_with_offload() -> None:
                 if ref is None:
                     continue
                 ref["shape"] = list(shape)
+                # Publish the /ref topic via the transport layer.
+                # On ``iot`` the IoT Policy's AllowOwnTopics statement
+                # bounds writes to ``strands/<ThingName>/*`` (covers
+                # ``camera/*/ref`` via the trailing wildcard); on
+                # ``bridge`` the Zenoh ACL adds a LAN-side gate on top.
+                # ``enable_for_mesh`` early-returns unless the active
+                # backend is one of those two, so the publish reaches
+                # the wire only when at least one of these gates is in
+                # force.
                 transport.put(f"strands/{mesh.peer_id}/camera/{cam_name}/ref", ref)
-            except Exception as exc:
+            except Exception as exc:  # noqa: BLE001 -- numpy / cv2 / transport.put can raise diverse errors per frame; offload is best-effort
                 logger.debug(
                     "[camera_offload] %s/%s offload failed: %s",
                     mesh.peer_id,