Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion .github/workflows/e2e-install.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,25 @@ jobs:
# Budget: native arm64 finishes in 10-15 min; qemu is 30-40 min; give
# headroom for docker pulls on cold runners.
timeout-minutes: 90
# Where the secrets live. ONE job on purpose: a scheduled/manual job of
# its own would repeat the fifteen steps below, and a caller job that
# `uses:` a reusable workflow cannot set an Environment (only the called
# workflow's own jobs can, and on a pull_request the PR head supplies that
# file too) — so the one job names its Environment by event instead. A pull_request run
# references `e2e-pull-request`, which holds no secrets and needs no
# protection (the job checks out and runs the PR head's own config and
# specs; see "Write .env.test" below). Every other run — the schedule, a
# dispatch — references `e2e-credentials`, whose deployment-branch policy
# (beta and main only) is what fences the secrets: a run from any other
# ref is refused before a step starts, whatever this file says, because
# on a pull_request the PR head supplies this file too. The owner
# configures both under Settings → Environments: create
# `e2e-pull-request` empty; create `e2e-credentials`, put the provider
# keys and TELEGRAM_BOT_TOKEN in it, restrict its deployment branches to
# beta and main, then DELETE the repository-level copies — with those
# still there, a same-repo PR that edits the step-level `if:` below reads
# them anyway, and that `if:` is hygiene, not the fence.
environment: ${{ github.event_name == 'pull_request' && 'e2e-pull-request' || 'e2e-credentials' }}
env:
CLAWBOX_PORT: "8080"
# Default target for the in-app updater test. On PRs targeted at this
Expand Down Expand Up @@ -98,12 +117,25 @@ jobs:
platforms: arm64

# Real AI-provider credentials are injected via repo secrets. The test
# steps that need them skip gracefully when the env var is empty, so
# steps that need them skip gracefully when the file is absent, so
# forks without secrets still get meaningful coverage. Values are
# passed through env vars and written via printf so a secret that
# happens to contain the EOF token or other heredoc-breaking bytes
# can't truncate the resulting .env file.
#
# Never on a pull_request run: this job checks out the PR HEAD and then
# runs its playwright.config.ts, global-setup.ts and specs on the host
# with this file beside them, so a same-repo PR branch could read the
# file and send it anywhere. A same-repo PR now behaves exactly like a
# fork PR; the credentialed specs run on the schedule and on dispatch.
# (A gate in this file is only hygiene — the PR head supplies the
# workflow too — which is why these secrets also belong in a GitHub
# Environment restricted to beta/main, not at repository scope.)
# Nothing reads CLAWBOX_UPGRADE_TARGET_BRANCH from the file — the
# updater spec reads process.env, set by the job-level env above — so
# the whole step is skipped rather than split.
- name: Write .env.test
if: ${{ github.event_name != 'pull_request' }}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
Expand Down
22 changes: 12 additions & 10 deletions CLAUDE.md

Large diffs are not rendered by default.

204 changes: 204 additions & 0 deletions clawkeep/clawkeep/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@

import os
import re
from dataclasses import dataclass
from pathlib import Path

from . import hermes, openclaw
Expand All @@ -47,6 +48,20 @@ class AgentMismatchError(Exception):
"""The snapshot belongs to a different agent than this device runs."""


class DestinationRefusedError(Exception):
"""The manifest wants to land an asset somewhere this box's agent keeps no
state — or in a shape (file vs directory, sqlite) the agent never writes.

Restore's destinations used to be READ from the manifest: `sourcePath` was
checked to be a non-empty string and then renamed over. A snapshot is not
a trustworthy document — every device paired to the account can write
into the same prefix, and a legacy plaintext `.tar.gz` needs no passphrase
at all — so a manifest naming `/home/clawbox/.ssh` would have had the
owner's `authorized_keys` swapped out by clicking Restore. Every
destination is now derived LOCALLY and the manifest may only agree.
"""


def _parse_edition_file(raw: str) -> str | None:
"""Minimal systemd EnvironmentFile parse — `KEY=value`, optional `export`,
optional quotes. Deliberately the same shape as `parseEditionEnvFile` in
Expand Down Expand Up @@ -157,6 +172,195 @@ def assert_archive_matches_device(manifest: dict) -> None:
)


# ── where a restore may land ─────────────────────────────────────────────────

@dataclass(frozen=True)
class RestoreRoot:
"""One place this box's agent keeps state, as restore may accept it."""

#: Normalised absolute path.
path: str
#: The agent's own word for it: a Hermes `ASSETS` kind, or an OpenClaw
#: plan kind (`state`, `config`, `credentials`, `workspace`, `agent`).
kind: str
#: `"dir"` | `"file"` — what a manifest asset landing here must declare.
entry: str
#: Whether a manifest asset landing here may carry `sqlite: true`.
sqlite: bool
#: Hermes: the manifest's kind must be THIS root's kind (exact set, keyed
#: by kind). OpenClaw: matched by path, kind unpinned.
pin_kind: bool


@dataclass(frozen=True)
class RestoreRoots:
agent: str
roots: tuple[RestoreRoot, ...]


#: OpenClaw kinds whose destination may lie INSIDE a declared root rather
#: than equal one: a per-agent root or a workspace the owner has since moved
#: or removed from openclaw.json still sits under the state dir.
OPENCLAW_NESTED_KINDS = frozenset({"agent", "workspace"})

#: The one OpenClaw asset kind that is a single file (`openclaw.json`, when it
#: lives outside the state dir or in a config-only snapshot).
_OPENCLAW_FILE_KINDS = frozenset({"config"})


def restore_roots(cfg: Config) -> RestoreRoots:
"""Everywhere a restore on THIS box is allowed to land, derived locally.

Hermes: exactly `{source_path(a) for a in hermes.ASSETS}` — this package is
the only writer of a Hermes archive, so the set is closed and each root
carries the entry shape and sqlite flag its kind was archived with.

OpenClaw: what `openclaw backup create --dry-run --json` declares it would
archive today (`openclaw.plan_roots`) — resolved by the CLI under the same
environment it is spawned with here, so the list is by construction the
one a snapshot of this box was written from. Raises `OpenclawError` when
the CLI cannot answer; a restore then refuses rather than guessing.
"""
if device_agent() == AGENT_HERMES:
return RestoreRoots(
agent=AGENT_HERMES,
roots=tuple(
RestoreRoot(
path=os.path.normpath(str(hermes.source_path(a))),
kind=a.kind,
entry=a.entry,
sqlite=a.sqlite,
pin_kind=True,
)
for a in hermes.ASSETS
),
)
planned = openclaw.plan_roots(cfg.openclaw.binary)
return RestoreRoots(
agent=AGENT_OPENCLAW,
roots=tuple(
RestoreRoot(
path=os.path.normpath(root.path),
kind=root.kind,
entry="file" if root.kind in _OPENCLAW_FILE_KINDS else "dir",
sqlite=False,
pin_kind=False,
)
for root in planned
),
)


def _inside(target: str, root: str) -> bool:
return target != root and target.startswith(root.rstrip("/") + "/")


def assert_destination_allowed(
kind: str,
entry: str,
target: str,
*,
roots: RestoreRoots,
sqlite: bool = False,
) -> RestoreRoot:
"""Vet ONE manifest asset's destination against the local roots.

Returns the root the asset lands on. Its `path` is the path restore may
use — the manifest's own string, which by then has been proven to be an
absolute, already-normalised path equal to (or, for the OpenClaw nested
kinds, inside) a root this box declared. Its `sqlite` is what restore
must act on, and it is THIS BOX's word, never the manifest's: a Hermes
`sessions` manifest that omits the flag still lands on the `state.db`
root, and a restore that took the manifest's silence for "not sqlite"
would leave the old database's `-wal`/`-shm` pair beside the new file
for sqlite to replay into it. The manifest may only agree — `sqlite:
true` on a root this box does not archive that way is refused, since
honouring it would rename `config.yaml-wal` aside.
Raises `DestinationRefusedError` naming the kind and the path otherwise.

The shape rule first, whoever the agent is: `os.path.isabs(target)` and
`os.path.normpath(target) == target`. That refuses a relative path (which
would land wherever the daemon's cwd is — the ClawBox checkout, when the
web server spawns it), `~`, any `..` or `.` segment, a doubled slash and a
trailing slash — the CLI writes none of those, so a manifest carrying one
was not written by the CLI.
"""
where = f"{kind!r} asset at {target!r}"
# `//x` is the one spelling POSIX `normpath` keeps as is (an
# implementation-defined prefix), so it is named on its own.
if (
not os.path.isabs(target)
or target.startswith("//")
or os.path.normpath(target) != target
):
raise DestinationRefusedError(
f"refusing to restore the {where}: a destination must be an absolute, "
"normalised path (no relative path, no '~', no '..', no doubled or "
"trailing slash)",
)

if roots.agent == AGENT_HERMES:
matched = next(
(r for r in roots.roots if r.kind == kind and r.path == target), None,
)
if matched is None:
known = next((r for r in roots.roots if r.kind == kind), None)
if known is None:
raise DestinationRefusedError(
f"refusing to restore the {where}: {kind!r} is not something "
"a Hermes backup contains",
)
raise DestinationRefusedError(
f"refusing to restore the {where}: on this box the {kind!r} asset "
f"lives at {known.path!r}, and a snapshot does not get to choose "
"where it lands",
)
else:
exact = next((r for r in roots.roots if r.path == target), None)
if exact is not None:
matched = exact
elif kind in OPENCLAW_NESTED_KINDS and any(_inside(target, r.path) for r in roots.roots):
# An agent root or workspace that sits under a declared root — the
# box may have dropped that agent from openclaw.json since, and the
# directory is still the agent's own.
matched = RestoreRoot(path=target, kind=kind, entry="dir", sqlite=False, pin_kind=False)
else:
declared = ", ".join(sorted({r.path for r in roots.roots}))
raise DestinationRefusedError(
f"refusing to restore the {where}: it is not a place this box's "
f"OpenClaw keeps state (declared: {declared}). A snapshot does not "
"get to choose where it lands; if the state directory was moved "
"since this backup, restore it by hand",
)

if entry != matched.entry:
if roots.agent == AGENT_OPENCLAW and matched.entry == "file":
# The CLI writes no `entry` key, so a manifest is not LYING when
# it says nothing about a `config` asset: ClawKeep restores
# OpenClaw state as directories only, and a single-file asset —
# a config-only snapshot, or an openclaw.json kept outside the
# state directory — is a limitation of this restore, not a fault
# of the snapshot. Said as one, so the owner is not told to
# distrust a backup that is fine.
raise DestinationRefusedError(
f"refusing to restore the {where}: on this box that is a single "
"file, and ClawKeep restores OpenClaw state as directories only — "
"a config-only snapshot, or an openclaw.json kept outside the "
"state directory, has to be put back by hand",
)
raise DestinationRefusedError(
f"refusing to restore the {where}: this box archives it as a "
f"{matched.entry!r}, the manifest says {entry!r}",
)
if sqlite and not matched.sqlite:
raise DestinationRefusedError(
f"refusing to restore the {where}: it is not a sqlite database on this box",
)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# Every arm above leaves `matched.path == target` (the nested OpenClaw
# root is built from `target`), so the caller reads the path from here.
return matched


def verify_archive(cfg: Config, archive: Path, *, agent: str) -> None:
"""Verify a downloaded archive with the backend that WROTE it.

Expand Down
11 changes: 11 additions & 0 deletions clawkeep/clawkeep/hermes.py
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,17 @@ class HermesAsset:
HermesAsset("identity", "agent-identity", root="clawbox"),
)

#: The same allowlist keyed by kind — a TEST-ONLY mirror of :data:`ASSETS`,
#: nothing production reads. Restore never looks here: `agent.restore_roots`
#: builds the Hermes roots straight from `ASSETS`, and
#: `agent.assert_destination_allowed` matches a manifest asset's `kind` and
#: path against THOSE roots, so the manifest never gets to say where a kind
#: lands. What this mapping pins is the property that lookup relies on: one
#: root per kind. `test_every_asset_kind_is_unique…` checks it stays in step
#: with `ASSETS`, because a duplicated kind would make the by-kind match
#: ambiguous and hand the choice back to the manifest.
ASSETS_BY_KIND: dict[str, HermesAsset] = {a.kind: a for a in ASSETS}

#: Only these assets survive `only_config=True` — the "just the settings"
#: backup the config flag promises. Credentials are NOT among them: a
#: config-only snapshot is the one a customer is most likely to hand to
Expand Down
Loading
Loading