mirror of
https://github.com/kuhyx/wake-alarm.git
synced 2026-11-21 07:02:19 +01:00
scripts/vmbox/harness.sh provisions a disposable Arch guest, runs the REAL
install.sh in it, and adjudicates 8 cases on a host-side exit code. Plus
DOCS-vmbox.md, which states what a pass does and does not mean.
Covered: system-python imports, timer enabled, wake-alarm.service still
`static` (an [Install] there fires the alarm at *login*), the shutdown wrapper
shadowing /usr/bin/shutdown, the alarm-cache shape jq expects, a trigger tick,
the inhibitor, and the re-fire path. With --window it also opens the real
fullscreen Tk window and screenshots it from the host -- confirmed showing
"WAKE UP!", round 1/4 and a live flash challenge.
Not covered, and said plainly in the doc rather than implied away: audio (the
guest has no pactl/paplay), the phone, GPU and real outputs, and anything
bootloader-related (guest is BIOS, this machine is UEFI).
**The VM earned its place immediately by finding two live bugs that the host
could not reach and the unit suite passed straight through.**
1. The inhibitor claimed a block it did not have. Popen succeeding only means
the binary launched; logind can still refuse -- the guest's polkit denies a
non-interactive session outright ("Failed to inhibit: Access denied", exit
1) while the alarm cheerfully logged the power key as blocked.
take_power_key_inhibitor() now waits INHIBIT_CONFIRM_SECONDS and confirms
the child survived, returning None and logging the refusal otherwise.
2. An unsigned session record was written and then rejected on read. With no
HMAC key on the machine (/etc/gatelock absent, as in the guest),
verify_entry_hmac returns False for a *missing* key exactly as it does for
a forgery -- so every session record was unreadable and item 2's power-off
defence silently did not exist. An entry with no "hmac" field is now
honoured with a loud warning; a present-but-wrong signature is still
rejected, since that one really is tampering.
Two harness traps worth recording, both hit while building it:
- `vm run` reports the *VM's* verdict, not the guest command's exit code, so a
guest script exiting 1 still gives rc=0. A gate built on that fails OPEN.
guest_cases.sh prints ALL-CASES-PASSED only when every case passed and the
harness greps for it; verified by breaking a case on purpose and watching
the gate go red.
- `vm share`/`vm repo` key off the path basename, so REPO_DIR must be absolute
and symlink-resolved. A relative "scripts/vmbox/../.." makes rsync write
into /home and fail with permissions errors that look like a guest fault.
Guest checks live in real .py files beside the shell, not heredocs, so they
get linted like everything else -- ruff's autofix gutted an early heredoc
version (stripped the assignments AND the print) exactly as TODO-hardening
warned, and only running it showed the file had stopped producing output.
Also drops three stale fan references the guest install run surfaced:
install.sh still announced "Fans will ramp to 100%" and README.md still
described the fan ramp, three commits after item 14 deleted the feature.
Splits carried: test_inhibit.py -> + test_inhibit_cleanup.py,
test_alarm_session.py -> + test_alarm_session_refire.py.
455 tests pass, 100% branch coverage. Harness: 8/8 cases, exit 0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EckWmyfetYq3Mi8MAnUudh
245 lines
9.0 KiB
Python
245 lines
9.0 KiB
Python
"""The fire-time record that makes a hard power-off survivable.
|
|
|
|
The real gap behind item 2 is not the power button itself -- it is that
|
|
nothing on disk ever says *"an alarm is ringing right now and was never
|
|
dismissed"*. ``wake_state.json`` is written only on **dismissal**, so cutting
|
|
power mid-alarm leaves no trace at all: the next boot sees an undismissed day
|
|
that looks exactly like a day the alarm had not reached yet, and the catch-up
|
|
window has long since closed. Holding the power button therefore *works*, and
|
|
that is what this module removes.
|
|
|
|
So the alarm writes a record the moment it starts ringing, and clears it when
|
|
the ring genuinely ends. ``_trigger`` re-fires on a record still marked
|
|
``ringing``, ignoring the catch-up window.
|
|
|
|
**Deliberately no date field.** ``_state.py`` keys its record by a UTC date,
|
|
and ``screen_locker/_wake_state.py`` mirrors that helper to read the very same
|
|
file from a different repo -- so the UTC basis there is load-bearing and is not
|
|
touched. Rather than add a second date key on a different basis, this record
|
|
carries only ``fired_at`` as an aware ISO timestamp, and freshness is an
|
|
elapsed-time comparison. Timezone-agnostic by construction, so the local
|
|
midnight question never arises.
|
|
|
|
**Bounded, because an unfinished session is not self-clearing.** If the alarm
|
|
process dies before dismissal -- Tk cannot open a display, a crash at startup
|
|
-- nothing ever runs ``on_close()`` to mark the session finished, and an
|
|
unbounded re-fire rule would restart the alarm every single minute forever.
|
|
The record is therefore honoured only within ``REFIRE_MAX_AGE_SECONDS`` of
|
|
``fired_at``, and the ordinary day / dismissed / workout gates still apply on
|
|
top of it.
|
|
|
|
Signed with :mod:`gatelock.log_integrity`, exactly like ``_state.py``, so the
|
|
record cannot simply be edited to say ``dismissed``.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from datetime import datetime, timezone
|
|
import json
|
|
import logging
|
|
|
|
from gatelock.log_integrity import compute_entry_hmac, verify_entry_hmac
|
|
|
|
from wake_alarm._constants import (
|
|
ALARM_SESSION_FILE,
|
|
CLOCK_SKEW_TOLERANCE_SECONDS,
|
|
REFIRE_MAX_AGE_SECONDS,
|
|
)
|
|
|
|
_logger = logging.getLogger(__name__)
|
|
|
|
STATE_RINGING = "ringing"
|
|
STATE_FINISHED = "finished"
|
|
|
|
|
|
def _now() -> datetime:
|
|
"""Return the current instant, aware and local. The seam tests patch."""
|
|
return datetime.now(tz=timezone.utc).astimezone()
|
|
|
|
|
|
def _write(entry: dict[str, object]) -> bool:
|
|
"""Sign and write *entry*, reporting whether it landed on disk."""
|
|
signature = compute_entry_hmac(entry)
|
|
if signature is not None:
|
|
entry["hmac"] = signature
|
|
else:
|
|
_logger.warning("HMAC key unavailable — saving unsigned alarm session")
|
|
try:
|
|
ALARM_SESSION_FILE.parent.mkdir(parents=True, exist_ok=True)
|
|
with ALARM_SESSION_FILE.open("w") as handle:
|
|
json.dump(entry, handle, indent=2)
|
|
except OSError as exc:
|
|
_logger.warning("Failed to write the alarm session record: %s", exc)
|
|
return False
|
|
return True
|
|
|
|
|
|
def start_session(correlation: str) -> bool:
|
|
"""Record that an alarm has started ringing.
|
|
|
|
Args:
|
|
correlation: The derived correlation id for this morning, so the
|
|
record joins up with the JSONL log without a handshake.
|
|
|
|
Returns:
|
|
True when the record was written.
|
|
"""
|
|
written = _write(
|
|
{
|
|
"state": STATE_RINGING,
|
|
"fired_at": _now().isoformat(),
|
|
"correlation": correlation,
|
|
}
|
|
)
|
|
if written:
|
|
_logger.warning(
|
|
"Alarm session opened (%s) — a power-off now re-fires on boot",
|
|
correlation,
|
|
extra={"event": "session_opened", "correlation": correlation},
|
|
)
|
|
return written
|
|
|
|
|
|
def finish_session() -> bool:
|
|
"""Mark the current session finished, however the alarm ended.
|
|
|
|
Called from ``on_close()``, so it covers dismissal, the escape hatch and
|
|
SIGTERM alike -- every path where the ring genuinely stopped with the
|
|
machine still up. The one path it cannot cover is the one it exists for:
|
|
power cut mid-alarm, which leaves the record saying ``ringing``.
|
|
|
|
Returns:
|
|
True when the record was written.
|
|
"""
|
|
entry = load_session()
|
|
if entry is None:
|
|
return False
|
|
return _write(
|
|
{
|
|
"state": STATE_FINISHED,
|
|
"fired_at": entry.get("fired_at"),
|
|
"correlation": entry.get("correlation"),
|
|
}
|
|
)
|
|
|
|
|
|
def load_session() -> dict[str, object] | None:
|
|
"""Load and verify the session record.
|
|
|
|
Returns:
|
|
The record, or None when it is absent, unreadable, or fails its HMAC
|
|
check. A tampered record is treated as no record: it must not be
|
|
possible to *create* a ringing session by hand either.
|
|
"""
|
|
if not ALARM_SESSION_FILE.exists():
|
|
return None
|
|
try:
|
|
with ALARM_SESSION_FILE.open() as handle:
|
|
entry = json.load(handle)
|
|
except (OSError, json.JSONDecodeError):
|
|
_logger.warning("Cannot read the alarm session record")
|
|
return None
|
|
if not isinstance(entry, dict):
|
|
return None
|
|
if verify_entry_hmac(entry):
|
|
return entry
|
|
# An entry with no "hmac" field at all was written unsigned, because no
|
|
# HMAC key was available at fire time. gatelock's verify returns False for
|
|
# that case *and* for a real forgery, and treating them alike would be a
|
|
# silent fail-open: on a machine with no key provisioned, every session
|
|
# record would be unreadable and the power-off defence would simply not
|
|
# exist. Found by running the vmbox harness, where /etc/gatelock is absent.
|
|
#
|
|
# So: unsigned is accepted with a loud warning (it is no weaker than the
|
|
# no-record state it replaces), while a *present but wrong* signature is
|
|
# still rejected outright -- that one really is tampering.
|
|
if "hmac" not in entry:
|
|
_logger.warning(
|
|
"Alarm session is unsigned (no HMAC key on this machine) — "
|
|
"honouring it, but it offers no tamper protection",
|
|
extra={"event": "session_unsigned"},
|
|
)
|
|
return entry
|
|
_logger.warning("Alarm session HMAC verification failed")
|
|
return None
|
|
|
|
|
|
def _fired_at(entry: dict[str, object]) -> datetime | None:
|
|
"""Parse the record's ``fired_at``, or None when it is unusable."""
|
|
raw = entry.get("fired_at")
|
|
if not isinstance(raw, str):
|
|
return None
|
|
try:
|
|
parsed = datetime.fromisoformat(raw)
|
|
except ValueError:
|
|
return None
|
|
if parsed.tzinfo is None:
|
|
return None
|
|
return parsed
|
|
|
|
|
|
def unfinished_session_age(*, now: datetime | None = None) -> float | None:
|
|
"""Return how long an unfinished alarm has been ringing, in seconds.
|
|
|
|
Args:
|
|
now: Instant to measure against; defaults to the current local time.
|
|
|
|
Returns:
|
|
The elapsed seconds when a ringing session is on disk and its
|
|
timestamp is usable, else None. A slightly future-stamped record is
|
|
clamped to zero rather than discarded -- see below.
|
|
"""
|
|
entry = load_session()
|
|
if entry is None or entry.get("state") != STATE_RINGING:
|
|
return None
|
|
fired_at = _fired_at(entry)
|
|
if fired_at is None:
|
|
_logger.warning("Alarm session has no usable fired_at; ignoring it")
|
|
return None
|
|
age = ((now if now is not None else _now()) - fired_at).total_seconds()
|
|
if age >= 0:
|
|
return age
|
|
# A record stamped in the future means the clock moved *backwards* since
|
|
# it was written -- NTP correcting after a resume, or RTC-vs-system skew
|
|
# at boot. This machine wakes from hibernate, so that is a routine event,
|
|
# not a broken one. Treating it as "not ringing" would fail open on
|
|
# exactly the scenario this record exists to close: alarm fires on a fast
|
|
# clock, the clock is corrected, and the power-off escape works again.
|
|
# So clamp to zero and let it re-fire.
|
|
if age < -CLOCK_SKEW_TOLERANCE_SECONDS:
|
|
_logger.warning(
|
|
"Alarm session is stamped %.0fs in the future — beyond the "
|
|
"clock-skew tolerance, ignoring it",
|
|
-age,
|
|
extra={"event": "session_clock_skew", "skew_seconds": -age},
|
|
)
|
|
return None
|
|
_logger.info("Alarm session is %.0fs in the future; treating it as fresh", -age)
|
|
return 0.0
|
|
|
|
|
|
def should_refire(*, now: datetime | None = None) -> bool:
|
|
"""Report whether an alarm was cut short and must ring again.
|
|
|
|
Bounded on purpose: an alarm process that died before dismissal leaves a
|
|
record nothing will ever clear, so without the age limit this would
|
|
restart the alarm every minute indefinitely.
|
|
|
|
Args:
|
|
now: Instant to measure against; defaults to the current local time.
|
|
|
|
Returns:
|
|
True when a ringing session exists and is younger than the limit.
|
|
"""
|
|
age = unfinished_session_age(now=now)
|
|
if age is None:
|
|
return False
|
|
if age > REFIRE_MAX_AGE_SECONDS:
|
|
_logger.info(
|
|
"Ignoring an unfinished alarm session %.0fs old (limit %.0fs)",
|
|
age,
|
|
REFIRE_MAX_AGE_SECONDS,
|
|
)
|
|
return False
|
|
return True
|