@or3/cloud 0.1.37 → 0.1.49

package/LICENSE

@@ -0,0 +1,17 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 @Saluana
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -16,10 +16,15 @@ saves both values in the mode-`0600`
 `or3-cloud/.or3-initial-credentials` file. It does not print the password.
 Save the file in a password manager, then delete it. Open
 [http://127.0.0.1:3000](http://127.0.0.1:3000) and sign in.
+During initialization the CLI proves both account logins, persists their bcrypt
+hashes in the managed data volume, removes the plaintext provisioning passwords
+from `.env`, and recreates the container without them. The `0600` handoff file
+is the only remaining plaintext copy managed by the CLI.
 
 The published Cloud image supports `linux/amd64` and `linux/arm64` and uses
-Basic Auth + SQLite + filesystem storage. The CLI checks the image manifest
-before it writes deployment state.
+Basic Auth + SQLite + filesystem storage. The CLI checks the image manifest,
+source/version labels, and then writes a digest-qualified image reference; it
+also verifies the image of the running container before committing state.
 
 ## Run it publicly on a VPS
 
@@ -41,6 +46,7 @@ Run these from the deployment directory created by `init`:
 
 ```sh
 npx @or3/cloud doctor
+npx @or3/cloud verify
 npx @or3/cloud backup
 npx @or3/cloud update
 npx @or3/cloud rollback --yes
@@ -52,16 +58,112 @@ npx @or3/cloud stop
 npx @or3/cloud restart
 ```
 
+Run `verify` after every update and before declaring a deployment healthy. It
+checks the managed image digest, deep provider health, Basic Auth sign-in,
+session hydration, SQLite sync, a disposable filesystem upload/download/delete
+cycle, both SQLite databases, volume ownership, proxy runtime settings, and a
+bounded window of serious container logs. On a public VPS, require the real
+HTTPS path (with no redirects) using `npx @or3/cloud verify --public`.
+After changing the owner password in the app, pass the current credential only
+through an owner-only file:
+`npx @or3/cloud verify --public --verification-email owner@example.com --verification-password-file /secure/current-owner-password`.
+Until the one-time handoff file is deleted, `verify` may read its initial owner
+credential from that protected file; it is never restored to `.env` or Docker
+container metadata.
+Verification rejects cross-origin filesystem grants and unexpected methods or
+headers, validates the storage ID before uploading, deletes its probe, and
+revokes its temporary session even when a later check fails.
+
 Do not run `docker compose down --volumes` on a normal deployment: it deletes
 the application data. Use `backup` before an update or any destructive action.
 When an adopted legacy deployment used a different container UID, `update`
 rebuilds the data from its checksummed pre-update backup as the hardened
 runtime user. It does not recursively rewrite file ownership in place, and a
 failed migration restores the recorded legacy root owner and snapshot.
+Updates also replace the generated Compose/Caddy files from the target CLI.
+Those files are checksummed into the pre-update backup and restored on a failed
+update, rollback, restore, or interrupted-operation recovery. Backups also
+carry a deployment-local authentication tag, so an altered or foreign archive
+cannot supply configuration or executable Compose assets. Every mutating
+command holds one deployment-wide lease; do not delete `.or3-cloud` lock or
+recovery files by hand.
+Backup artifacts are allocated in that journal before archiving, fully
+revalidated before success is reported, and safely removed by `recover` if a
+hard interruption leaves an incomplete artifact. A standalone backup and a
+failed adoption preserve whether the original app was intentionally stopped.
+Initialization and adoption also fail closed unless Docker explicitly confirms
+that the target volumes, project containers, and networks do not exist.
+Docker architecture checks query the selected daemon, remote daemons skip
+misleading client-host port probes, every Docker command has a deadline, and
+streaming archive children are terminated as a process group on timeout.
+Lifecycle commits fsync files and parent directories before/after rename.
+Restore refuses pre-authenticated-asset backups instead of mixing an old image
+with current Compose/Caddy files, and failed asset rollback retains any
+recovery copies it could not reinstall.
+Use owner/admin password files for noninteractive credential rotation. TTY
+prompts suppress input, Docker receives only environment variable names in its
+argument vector, and the admin credential file is committed with
+write/fsync/rename so journal replay cannot encounter a truncated JSON file.
+A successful rotation removes the obsolete `.or3-initial-credentials` copy.
+It also removes the plaintext provisioning passwords from `.env` and the
+recreated container; older deployments migrate to this layout on reset.
+
+The authentication key is intentionally not embedded in an exported archive.
+Escrow an owner-only copy of `.or3-cloud/backup-auth.key` separately in an
+encrypted secret store; put that key back in the recovered deployment before
+restoring an off-host archive.
+When selecting an exact version, run the matching CLI package, for example
+`npx --yes @or3/cloud@0.1.39 update --to 0.1.39`; the CLI refuses mismatched
+package and image versions so their generated assets cannot drift.
 For a destructive purge, export a fresh backup to a new directory on another
 filesystem first; `remove --purge-data --yes` verifies that export before it
 will delete anything.
 
+## Dashboard updates
+
+New managed Linux deployments expose a **Dashboard Update** card only when a
+local Linux Docker socket passes the CLI's disposable, exact-mount bridge
+probe. Click **Check for updates**, then approve the exact latest release. The
+card uses the same managed updater as the CLI: it makes a verified backup,
+waits for deep health, and restores the prior release and data if the update
+fails. Hosts that do not pass the probe remain CLI-only.
+
+Release-check results, including the last successful latest version and a
+bounded failure or compatibility reason, persist across page reloads and
+operator restarts. Accepted asynchronous starts return HTTP 202; corrupt or
+unavailable operator responses are reported separately from unsupported hosts.
+While an update is active, the card announces state changes and polls every two
+seconds, backing off on connection failures and stopping after 15 minutes or a
+terminal result.
+
+Once an earlier protocol-compatible release exists, the tagged release gate
+also upgrades a disposable installation from it through this Unix API, proves
+concurrent starts serialize, checks persisted data and deep health, and rolls
+the deployment back.
+
+The application container never receives the Docker socket. A separate,
+socket-only operator sidecar is the only container with Docker access, and it
+accepts only status, release-check, and exact-version update requests. It runs
+in a dedicated digest-pinned operator image—not the web application image.
+Before running privileged release code, it installs with lifecycle scripts
+disabled, verifies the npm registry signature and the exact SLSA bundle, and
+requires that the signed package came from this repository's tagged
+`release-cloud.yml` workflow. That authenticated package pins both qualified
+GHCR image digests and the exact source revision carried by both images, so
+moving or replacing a version tag—or mixing artifacts from different
+commits—is rejected before an image can run. A stale dashboard-owned update is
+recovered automatically with its exact target CLI; unrelated/manual operations
+remain locked for host-side `recover`. Existing deployments gain the card after
+one normal exact-version CLI update. Remote Docker hosts remain CLI-only.
+
+The operator socket is deployment-group-only, mutation requests are bounded,
+and accepted/rejected operations are recorded without secrets in
+`.or3-cloud/dashboard-update-audit.jsonl`. These are operational controls, not
+a host sandbox: the dedicated operator has read-write Docker API access and is
+therefore a host-root trust component. Application-process code execution is
+inside the dashboard-update trust boundary; disable the operator overlay and
+use host CLI updates when that tradeoff is unacceptable.
+
 Managed registration is invite-only: the bootstrap owner signs in first and
 invites additional users from the in-product admin flow. Guest access and
 anonymous registration stay disabled. Uploading/installing custom plugins or

package/assets/Caddyfile

@@ -3,11 +3,14 @@
 	# site handler runs, so Strict-Transport-Security is only ever emitted on
 	# HTTPS responses (it is meaningless on plain HTTP).
 	header {
-		Strict-Transport-Security "max-age=31536000; includeSubDomains"
+		Strict-Transport-Security "max-age=31536000"
 		X-Content-Type-Options "nosniff"
 		X-Frame-Options "DENY"
 		Referrer-Policy "strict-origin-when-cross-origin"
 		Permissions-Policy "camera=(), microphone=(), geolocation=()"
+		# Nuxt needs same-origin scripts plus inline hydration styles/scripts; the
+		# fixed Cloud profile has no browser-side third-party providers.
+		Content-Security-Policy "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; media-src 'self' blob:; worker-src 'self' blob:; frame-src 'none'; upgrade-insecure-requests"
 	}
 
 	encode zstd gzip

package/assets/compose.operator.yaml

@@ -0,0 +1,61 @@
+# This overlay is included only after the CLI proves the local Docker socket
+# can be mounted and used by the recorded deployment owner. Keeping it out of
+# compose.yaml is intentional: Compose interpolates variables in inactive
+# profiles too, which would otherwise break CLI-only installs.
+services:
+  or3:
+    # The app needs only group write access to the operator socket; it never
+    # receives the Docker socket or the deployment bind mount.
+    group_add:
+      - "${OR3_OPERATOR_GID}"
+    volumes:
+      # The web service can connect only to the narrow Unix-socket API. It does
+      # not receive the Docker socket or managed deployment directory.
+      - type: bind
+        source: ./.or3-cloud/operator-ipc
+        target: /run/or3-operator
+        read_only: true
+        bind:
+          create_host_path: false
+
+  or3-operator:
+    # SECURITY TRUST BOUNDARY: read-write Docker API access is
+    # host-root-equivalent. The controls below reduce accidental surface; they
+    # do not sandbox a compromised operator from the host Docker daemon.
+    image: ${OR3_OPERATOR_IMAGE}
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}
+    entrypoint: ["/usr/local/bin/node", "/operator/dashboard-operator.mjs"]
+    working_dir: ${OR3_DEPLOYMENT_DIR}
+    environment:
+      DOCKER_HOST: unix:///var/run/docker.sock
+      OR3_DASHBOARD_OPERATOR_SOCKET: /run/or3-operator/operator.sock
+    user: "${OR3_OPERATOR_UID}:${OR3_OPERATOR_GID}"
+    group_add:
+      - "${OR3_DOCKER_GID}"
+    volumes:
+      - type: bind
+        source: ${OR3_DEPLOYMENT_DIR}
+        target: ${OR3_DEPLOYMENT_DIR}
+      - type: bind
+        source: ./dashboard-operator.mjs
+        target: /operator/dashboard-operator.mjs
+        read_only: true
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${OR3_DOCKER_SOCKET}
+        target: /var/run/docker.sock
+      - type: bind
+        source: ./.or3-cloud/operator-ipc
+        target: /run/or3-operator
+        bind:
+          create_host_path: false
+    restart: on-failure
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp:size=128m

package/assets/compose.public.yaml

@@ -3,6 +3,8 @@ services:
     # Pinned to the exact patch release and image digest so a floating tag
     # cannot silently change proxy behavior or the base image.
     image: caddy:2.10.2-alpine@sha256:4c6e91c6ed0e2fa03efd5b44747b625fec79bc9cd06ac5235a779726618e530d
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}
     depends_on:
       or3:
         # This gates Caddy's initial startup only. A later unhealthy OR3
@@ -44,5 +46,9 @@ services:
 volumes:
   caddy-data:
     name: ${OR3_CADDY_DATA_VOLUME}
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}
   caddy-config:
     name: ${OR3_CADDY_CONFIG_VOLUME}
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}

package/assets/compose.yaml

@@ -3,6 +3,8 @@ name: ${OR3_COMPOSE_PROJECT}
 services:
   or3:
     image: ${OR3_IMAGE}
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}
     env_file:
       - .env
     environment:
@@ -70,3 +72,5 @@ services:
 volumes:
   or3-data:
     name: ${OR3_VOLUME_NAME}
+    labels:
+      io.or3.cloud.deployment-id: ${OR3_DEPLOYMENT_ID}