Compare commits
16
Commits
92f875621d
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c2cc69091f | ||
|
|
db8422afda | ||
|
|
c5c6ec1453 | ||
|
|
158d21ca04 | ||
|
|
86e548f2fc | ||
|
|
3293472cad | ||
|
|
864100b813 | ||
|
|
9971a63635 | ||
|
|
9c29bfcd86 | ||
|
|
8588b058c5 | ||
|
|
d7e19bd9da | ||
|
|
a00fad5553 | ||
|
|
a3ef408de6 | ||
|
|
aa3436fd1d | ||
|
|
4dd33c90e1 | ||
|
|
2e8cf269fb |
+7
-4
@@ -1,7 +1,10 @@
|
||||
# Generate separate 32-byte hex values with: openssl rand -hex 32
|
||||
# Keep .env private (chmod 600). Never commit real values.
|
||||
MONGO_ROOT_PASSWORD=
|
||||
MONGO_APP_PASSWORD=
|
||||
# The MongoDB URI must use an application-scoped user and a host address that
|
||||
# is reachable from Docker; 127.0.0.1 inside a container is the container.
|
||||
MONGO_CONNECTION_STRING=
|
||||
MONGO_DATABASE=guestops
|
||||
GUESTOPS_PUBLIC_ORIGIN=https://guestops-sandbox.futuresens.co.uk
|
||||
GUESTOPS_ALLOWED_HOSTS=guestops-sandbox.futuresens.co.uk;localhost;127.0.0.1
|
||||
GOOGLE_CLIENT_ID=
|
||||
GOOGLE_CLIENT_SECRET=
|
||||
GOOGLE_ENABLE_SENDING=false
|
||||
@@ -11,7 +14,7 @@ AI_MODEL=
|
||||
# Optional private host-side JSON file binding internal hotel IDs to OHIP credentials.
|
||||
# Default example has no connections. Never commit the real configuration.
|
||||
PMS_CONFIG_FILE_HOST=./deploy/pms.example.json
|
||||
# CI produces image archives. Set these to the loaded, reviewed commit tags.
|
||||
# Ansible builds the reviewed source package. Set these to its full-commit image tags.
|
||||
GUESTOPS_API_IMAGE=guestops-api:local
|
||||
GUESTOPS_WORKER_IMAGE=guestops-worker:local
|
||||
|
||||
|
||||
@@ -1,98 +0,0 @@
|
||||
name: Build and verify web migration
|
||||
on:
|
||||
push:
|
||||
branches: [main, 'codex/**']
|
||||
tags: ['[0-9]+.[0-9]+.[0-9]+']
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
permissions:
|
||||
contents: read
|
||||
jobs:
|
||||
verify:
|
||||
runs-on: ubuntu-latest
|
||||
services:
|
||||
mongo:
|
||||
image: mongo:8.0
|
||||
ports: ['27017:27017']
|
||||
options: >-
|
||||
--health-cmd "mongosh --quiet --eval 'db.adminCommand({ping:1}).ok'"
|
||||
--health-interval 10s --health-timeout 5s --health-retries 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-dotnet@v4
|
||||
with: { dotnet-version: '10.0.x' }
|
||||
- uses: actions/setup-node@v4
|
||||
with: { node-version: '22', cache: npm, cache-dependency-path: web/package-lock.json }
|
||||
- name: Build services
|
||||
run: dotnet build src/GuestOps.Worker/GuestOps.Worker.csproj -c Release
|
||||
- name: Verify backup validation and failure recovery
|
||||
run: python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
- name: Build interface
|
||||
working-directory: web
|
||||
run: npm ci && npm run build
|
||||
- name: Start isolated preview API
|
||||
run: |
|
||||
ASPNETCORE_ENVIRONMENT=Development Preview=true dotnet src/GuestOps.Api/bin/Release/net10.0/GuestOps.Api.dll --urls http://127.0.0.1:5180 > /tmp/guestops-api.log 2>&1 &
|
||||
for i in $(seq 1 30); do curl -fsS http://127.0.0.1:5180/health && exit 0; sleep 1; done
|
||||
cat /tmp/guestops-api.log
|
||||
exit 1
|
||||
- name: Verify MongoDB and HTTP boundaries
|
||||
env:
|
||||
MONGO_TEST_URI: mongodb://127.0.0.1:27017
|
||||
TEST_API_URL: http://127.0.0.1:5180
|
||||
run: dotnet run --project tests/GuestOps.Tests/GuestOps.Tests.csproj -c Release
|
||||
- name: Build Linux images
|
||||
run: |
|
||||
docker build --target api -t guestops-api:${{ github.sha }} .
|
||||
docker build --target worker -t guestops-worker:${{ github.sha }} .
|
||||
- name: Package reviewed images
|
||||
if: github.event_name != 'pull_request'
|
||||
run: |
|
||||
docker save guestops-api:${{ github.sha }} guestops-worker:${{ github.sha }} | gzip -n > guestops-images.tar.gz
|
||||
python3 deploy/release_record.py \
|
||||
--artifact guestops-images.tar.gz \
|
||||
--commit '${{ github.sha }}' \
|
||||
--api-image 'guestops-api:${{ github.sha }}' \
|
||||
--api-id "$(docker image inspect --format '{{.Id}}' 'guestops-api:${{ github.sha }}')" \
|
||||
--worker-image 'guestops-worker:${{ github.sha }}' \
|
||||
--worker-id "$(docker image inspect --format '{{.Id}}' 'guestops-worker:${{ github.sha }}')" \
|
||||
--output release-record.json
|
||||
sha256sum --check <(python3 -c "import json; r=json.load(open('release-record.json')); print(r['artifact']['sha256'] + ' ' + r['artifact']['name'])")
|
||||
- name: Smoke test production containers and restart persistence
|
||||
env:
|
||||
GUESTOPS_API_IMAGE: guestops-api:${{ github.sha }}
|
||||
GUESTOPS_WORKER_IMAGE: guestops-worker:${{ github.sha }}
|
||||
BOOTSTRAP_EMAIL: ci-owner@example.invalid
|
||||
BOOTSTRAP_HOTEL: CI test hotel
|
||||
run: |
|
||||
export MONGO_ROOT_PASSWORD=$(openssl rand -hex 32)
|
||||
export MONGO_APP_PASSWORD=$(openssl rand -hex 32)
|
||||
export BOOTSTRAP_PASSWORD=$(openssl rand -hex 24)
|
||||
trap 'docker compose down --volumes' EXIT
|
||||
docker compose config --quiet
|
||||
docker compose up -d --no-build
|
||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health
|
||||
docker compose run --rm --no-deps -e BOOTSTRAP_EMAIL -e BOOTSTRAP_HOTEL -e BOOTSTRAP_PASSWORD api --bootstrap
|
||||
python3 tests/production_smoke.py
|
||||
docker compose restart api worker
|
||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health
|
||||
python3 tests/production_smoke.py --read
|
||||
install -m 600 /dev/null .env
|
||||
python3 deploy/ops.py preflight --offline
|
||||
mkdir -m 700 .guestops-test-keyring
|
||||
export GNUPGHOME="$PWD/.guestops-test-keyring"
|
||||
gpg --batch --pinentry-mode loopback --passphrase '' --quick-generate-key 'GuestOps CI <ci@example.invalid>' rsa2048 encr 1d
|
||||
BACKUP_RECIPIENT=$(gpg --batch --with-colons --list-keys | awk -F: '$1=="fpr" {print $10; exit}')
|
||||
backup_dir=$(mktemp -d)
|
||||
python3 deploy/ops.py backup --recipient "$BACKUP_RECIPIENT" --output "$backup_dir/fixture.tar.gpg" --confirm-maintenance
|
||||
python3 deploy/ops.py restore-drill "$backup_dir/fixture.tar.gpg" --api-image "$GUESTOPS_API_IMAGE"
|
||||
curl --retry 30 --retry-delay 2 --retry-all-errors --fail http://127.0.0.1:8080/health/ready
|
||||
python3 tests/production_smoke.py --read
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: github.event_name != 'pull_request'
|
||||
with:
|
||||
name: guestops-linux-${{ github.run_number }}
|
||||
path: |
|
||||
guestops-images.tar.gz
|
||||
release-record.json
|
||||
retention-days: 90
|
||||
@@ -17,6 +17,7 @@
|
||||
**/payments.local.json
|
||||
.guestops-maintenance.lock
|
||||
.guestops-test-keyring/
|
||||
.guestops-release/
|
||||
guestops-backup-*/
|
||||
guestops-restore-*/
|
||||
*.tar.gpg
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Version>0.1.0</Version>
|
||||
<Version>0.2.1</Version>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
|
||||
+5
-1
@@ -14,7 +14,11 @@ RUN dotnet publish src/GuestOps.Worker/GuestOps.Worker.csproj -c Release -o /pub
|
||||
|
||||
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS api
|
||||
WORKDIR /app
|
||||
RUN mkdir -p /var/lib/guestops/keys && chown -R app:app /var/lib/guestops && chmod 700 /var/lib/guestops/keys
|
||||
RUN groupadd --gid 25001 guestops-secrets \
|
||||
&& usermod --append --groups guestops-secrets app \
|
||||
&& mkdir -p /var/lib/guestops/keys \
|
||||
&& chown -R app:app /var/lib/guestops \
|
||||
&& chmod 700 /var/lib/guestops/keys
|
||||
COPY --from=backend /publish/api ./
|
||||
COPY --from=frontend /build/web/dist ./wwwroot/
|
||||
ENV ASPNETCORE_URLS=http://+:8080 ASPNETCORE_ENVIRONMENT=Production Keys__Path=/var/lib/guestops/keys
|
||||
|
||||
+42
-14
@@ -1,10 +1,36 @@
|
||||
# GuestOps Milestone Report
|
||||
|
||||
Version: **0.1.0**
|
||||
Last updated: **29 September 2026**
|
||||
Version: **0.2.1 release candidate**
|
||||
Last updated: **30 September 2026**
|
||||
|
||||
This is the working delivery tracker for GuestOps Web. Update a milestone when its state changes and link the pull request, release artifact, test run, or acceptance record that proves the change.
|
||||
|
||||
## Milestones at a glance
|
||||
|
||||
This summary explains what each milestone delivers and where it currently stands. The release-gate and delivery tables below contain the detailed evidence and exit conditions.
|
||||
|
||||
| # | Milestone | What it delivers | Current position |
|
||||
| ---: | --- | --- | --- |
|
||||
| 1 | Web foundation | The React application, ASP.NET Core API, tenant-isolated MongoDB storage, preview mode, and container foundation. | **Implemented.** The application foundation and automated tests are on `main`. |
|
||||
| 2 | AI suggestions and reviewed Gmail sending | AI-assisted reply drafts and staff-reviewed Gmail delivery with safety and duplicate-send controls. | **Implemented; acceptance required.** Real Gmail threading, revocation, uncertain-send, and staff-review scenarios still need live evidence. |
|
||||
| 3 | OHIP PMS workflow | Internal proposal, approval, and execution controls for PMS operations. | **Implemented; acceptance required.** The workflow exists, but provider-contract and sandbox acceptance remain outstanding. |
|
||||
| 4 | NMI payment workflow | Internal payment proposal, approval, status, expiry, and reconciliation controls. | **Implemented; acceptance required.** The workflow exists, but real payment-provider sandbox acceptance remains outstanding. |
|
||||
| 5 | FAQ automation | Knowledge-based FAQ drafting, test mode, approval controls, and guarded live automation. | **Implemented; acceptance required.** Live mode remains disabled pending quality, false-positive, monitoring, and rollback acceptance. |
|
||||
| 6 | Team onboarding and account recovery | Staff invitations, password setup/reset, access disable/restore, and administrator recovery. | **Implemented; acceptance required.** Deployed link delivery, expiry, recovery, and administrator procedures still need operational evidence. |
|
||||
| 7 | Google connection recovery | OAuth reconnect, checkpoint recovery, grant revocation handling, and worker restart safety. | **Implemented; acceptance required.** Dedicated Google-account and worker-restart exercises have not yet been accepted. |
|
||||
| 8 | Operational readiness | Host backup, monitoring, and recovery are provided by the existing central infrastructure. | **External.** GuestOps no longer carries a second application-specific operational stack. |
|
||||
| 9 | Versioned releases | A deterministic version-named source archive and Ansible-controlled installation. | **Implemented; acceptance required.** Package the tested commit as `guestops_<version>.tar.gz` and deploy it through the central playbook. |
|
||||
| 10 | Debian deployment and persistence | Secure Debian/Compose deployment, HTTPS, external MongoDB, and persistent Data Protection keys. | **In progress.** The single Ansible playbook builds the API/worker, configures Nginx, restricts the listener and checks public readiness; sandbox deployment remains to be exercised. |
|
||||
| 11 | Backups, monitoring, and recovery | Existing central MongoDB backup, Filebeat, host monitoring, and version-based rollback. | **External.** Rollback selects an older archive and reruns the same deployment playbook. |
|
||||
| 12 | Google mailbox acceptance | End-to-end Gmail consent, import, recovery, reviewed sending, reconciliation, and revocation evidence. | **In progress.** The runbook, record validator and release-bound Gate B bundle integration exist; the live synthetic-data exercise and independent review remain outstanding. |
|
||||
| 13 | Rezlynx/Guestline adapter | The real PMS provider adapter, mappings, idempotency, reconciliation, and ambiguous-write handling. | **Planned.** Provider contract and sandbox access are still required before implementation and acceptance. |
|
||||
| 14 | Payment links and status | The real payment-provider integration, webhooks, expiry, replay protection, and reconciliation. | **Planned.** The provider path and sandbox acceptance plan still need to be confirmed and completed. |
|
||||
| 15 | Knowledge, AI, and FAQ activation | Supervised knowledge-quality, AI-draft, FAQ test-mode, staff-training, and stop-control acceptance. | **Implemented; acceptance required.** Evaluation tooling and cross-release bundle validation exist; the supervised evaluation, staff training and independent approval remain outstanding. |
|
||||
| 16 | Identity, preferences, and privacy | Account/session controls, hotel preferences, privacy inventory, retention decisions, and audit review. | **Implemented; acceptance required.** Legal and operational decisions, identity checks, and independent review remain outstanding. |
|
||||
| 17 | Inbox usability and desktop parity | Stable pagination, protected unsaved drafts, hotel-timezone display, and desktop workflow parity. | **Implemented; acceptance required.** Automated checks pass; the supervised desktop exercise and independent approval remain outstanding. |
|
||||
| 18 | Pilot, capacity, and release approval | Capacity proof, incident exercise, five-business-day hotel pilot, findings closure, and Gate B approval. | **In progress.** Live prerequisites, incident rehearsal, five-day pilot and named approvals remain open. |
|
||||
| 19 | Account security and self-service | TOTP MFA, recovery codes, transactional email, granular roles, preferences, and security notifications. | **Implemented on the development branch; acceptance required.** Keep it separate until `0.2.1` is approved and tagged, then review, merge, and version it as `0.3.0`. |
|
||||
|
||||
## Status key
|
||||
|
||||
- **Implemented** — present on `main` and supported by code or automated-test evidence.
|
||||
@@ -32,17 +58,17 @@ This is the working delivery tracker for GuestOps Web. Update a milestone when i
|
||||
| 5 | FAQ automation | B | Implemented / acceptance required | Draft and approval controls are promoted to local `main`. Keep live automation disabled until knowledge quality, thresholds, and rollback behaviour pass acceptance. |
|
||||
| 6 | Team onboarding and account recovery | B | Implemented / acceptance required | Invitation, password reset, and recovery flows are promoted to local `main`; verify deployed links, mail delivery, token expiry, and administrator recovery procedures. |
|
||||
| 7 | Google connection recovery | B | Implemented / acceptance required | Connection epochs, checkpoint recovery, and revocation handling are promoted to local `main`; complete real Google acceptance and worker-restart exercises. |
|
||||
| 8 | Operational readiness tooling | A | Implemented / acceptance required | Backup, restore, release, and diagnostic tooling is promoted to local `main`; execute it on the actual Debian host and retain evidence. |
|
||||
| 9 | Gitea and reproducible releases | A | In progress | The reviewed candidate is promoted in the local `main` history. CI now records the full commit, matched application version, archive checksum and immutable image IDs, and the rollback procedure is documented. Push the merge, retain the successful release evidence off-host, and create a new immutable approval tag; the existing `0.1.0` tag remains attached to the original foundation release. |
|
||||
| 10 | Debian deployment and persistence | A | In progress | Compose uses separate named database and shared key volumes, private host configuration, loopback-only API access and bounded logs. The confirmation-gated persistence drill verifies restart and container-recreation behaviour. Run it on the provisioned Debian host, complete HTTPS and controlled-reboot acceptance, and retain the evidence. |
|
||||
| 11 | Backups, monitoring, and recovery | A | In progress | Encrypted backup and isolated restore tooling now includes opt-in systemd scheduling without command-line secrets. Install and test it on Debian, configure monitored off-host transfer and durable logs, name alert/retention owners, and retain evidence from a timed restore and recovery drill. |
|
||||
| 12 | Google mailbox and reviewed-reply acceptance | B | In progress | The synthetic-data provider runbook, exact scenario set and restricted-record validator are implemented. Complete every scenario against the accepted Debian release and dedicated Google sandbox accounts, independently review the evidence, and retain the validated record. |
|
||||
| 8 | Operational readiness tooling | A | External | Use the existing host backup, Filebeat, monitoring and recovery processes instead of a second GuestOps-specific operational stack. |
|
||||
| 9 | Gitea and versioned releases | A | In progress | `deploy/package_source.py` packages an explicit committed ref as immutable `guestops_<version>.tar.gz`, verifies matching .NET/frontend versions, and refuses overwrite. Deploy it through the central version-selected Ansible playbook. |
|
||||
| 10 | Debian deployment and persistence | A | In progress | Compose runs API and worker against the existing MongoDB, preserves a named Data Protection key volume, and binds the API to loopback. Exercise the single Ansible playbook on sandbox and confirm a second deployment preserves the keys. |
|
||||
| 11 | Backups, monitoring, and recovery | A | External | The existing central MongoDB backup, Filebeat, host monitoring and archive retention remain authoritative. Rollback selects an earlier GuestOps version and reruns the deployment playbook. |
|
||||
| 12 | Google mailbox and reviewed-reply acceptance | B | In progress | The synthetic-data provider runbook, exact scenario set and restricted-record validator are implemented and wired into the Gate B bundle validator. Complete every scenario against the accepted Debian release and dedicated Google sandbox accounts, independently review the evidence, and retain the validated record. |
|
||||
| 13 | Rezlynx/Guestline adapter | C | Planned | Obtain the provider contract and sandbox, implement the adapter and mapping, and accept idempotency, stale-data, ambiguous-write, and reconciliation paths. |
|
||||
| 14 | Payment links and status | C | Planned | Select/confirm the payment-provider path, complete sandbox and webhook acceptance, and prove expiry, replay protection, reconciliation, and support recovery. |
|
||||
| 15 | Knowledge, AI, and FAQ activation | B | In progress | Owners can run a bounded no-send batch evaluation against current FAQ rules and approved knowledge, with false-positive/negative results and documented zero-error activation thresholds and stop conditions. Curate hotel-specific cases, evaluate AI suggestions separately, train staff, name monitoring/rollback owners, and retain staged-activation evidence. |
|
||||
| 16 | Identity, preferences, and privacy | B/C | In progress | Login throttling now uses the client address only after one-hop processing from the explicitly trusted reverse proxy. Finish privacy/retention decisions, preference coverage, identity acceptance and audit review. |
|
||||
| 17 | Inbox usability and desktop parity | B | In progress | The inbox now uses tenant-scoped stable cursor pagination in pages of 50 and protects unsaved drafts during navigation, conversation selection, filtering and search changes. Inbox, activity, mailbox-health and FAQ-history timestamps use the saved hotel timezone; finish the remaining secondary screens and agreed desktop-parity acceptance. |
|
||||
| 18 | Pilot, capacity, and release approval | B/C | Planned | Run the supervised pilot, exercise support and incident procedures, validate capacity, resolve pilot findings, and capture explicit go/no-go approval for wider rollout. |
|
||||
| 15 | Knowledge, AI, and FAQ activation | B | Implemented / acceptance required | Owners can run a bounded no-send batch evaluation, and a release-bound acceptance record enforces positive/negative coverage, zero FAQ errors, separate AI review, staff training, stop-control evidence and named monitoring/rollback owners. The integrated Gate B bundle rejects release or environment mismatches. Complete the supervised evaluation and retain independent approval. |
|
||||
| 16 | Identity, preferences, and privacy | B/C | Implemented / acceptance required | Login throttling trusts the client address only after one-hop processing by the configured proxy. A release-bound review now covers owner-controlled preferences, account/session controls, data inventory, retention/deletion/legal-hold ownership, provider decisions, audit evidence and known identity limitations. Complete the legal/operational decisions and independently approve the record. |
|
||||
| 17 | Inbox usability and desktop parity | B | Implemented / acceptance required | The inbox uses tenant-scoped stable cursor pagination in pages of 50 and protects unsaved drafts during route/history navigation, reload, conversation selection, filtering and search. Operational timestamps use the saved hotel timezone, and a release-bound desktop-parity acceptance record is implemented. The implementation and preview HTTP suite pass; run the supervised exercise against the approved release and retain independent approval. |
|
||||
| 18 | Pilot, capacity, and release approval | B/C | In progress | Complete the live Gate A/B exercises against the selected version, resolve or contain findings, and retain separate hotel-owner and technical approval. Gate C remains dependent on milestones 13 and 14. |
|
||||
|
||||
## Delivery sequence
|
||||
|
||||
@@ -54,10 +80,12 @@ Milestones 13 (Guestline/Rezlynx) and 14 (payments) can progress as parallel pro
|
||||
|
||||
## Next actions
|
||||
|
||||
- [ ] Push the local release-candidate promotion to the intended default branch and retain its successful CI evidence.
|
||||
- [ ] Choose the next semantic version, update both project version files, then create and archive a new immutable approval tag (the existing `0.1.0` tag identifies the foundation release).
|
||||
- [ ] Merge the Action removal and release-process update to the intended default branch; that resulting commit becomes the new package candidate.
|
||||
- [x] Preserve the published `0.2.0` tag unchanged and use the clean `0.2.1` candidate line from `main`, excluding Milestone 19 application code.
|
||||
- [ ] Create the immutable versioned archive with `deploy/package_source.py`, copy it into the Ansible files directory, and select its version in group vars.
|
||||
- [ ] Create and archive the immutable `0.2.1` approval tag only after Gate B approval.
|
||||
- [ ] Deploy to the target Debian environment with persistent MongoDB and data-protection keys.
|
||||
- [ ] Run and record backup, restore, restart, monitoring, and rollback exercises.
|
||||
- [ ] Confirm the existing central backup and monitoring processes include GuestOps, then test rollback by selecting the previous version.
|
||||
- [ ] Complete real Google mailbox acceptance without using production guest data.
|
||||
- [ ] Resolve or explicitly contain the milestone 16–17 pilot findings listed above.
|
||||
- [ ] Obtain the Guestline/Rezlynx interface contract and sandbox access.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
A Linux-hosted hotel email workspace, developed separately from the Windows GuestOps application. **This migration now includes AI draft generation, staff-approved Gmail sending, reviewed OHIP reservation updates, NMI hosted invoices, controlled FAQ auto-replies and team onboarding. It is not yet a production-complete replacement.**
|
||||
|
||||
Current development version: **0.1.0**
|
||||
Current release-candidate version: **0.2.1**
|
||||
|
||||
Project progress is tracked in the [milestone report](MILESTONES.md). User-visible changes and release limitations are recorded in the [release notes](RELEASE_NOTES.md).
|
||||
|
||||
@@ -57,7 +57,9 @@ Open http://127.0.0.1:5173 and select **Open preview workspace**. Each preview l
|
||||
|
||||
For MongoDB-backed operation, disable Preview and set `Mongo__ConnectionString`, `Mongo__Database`, and a persistent private `Keys__Path`. See [deployment](docs/deployment.md).
|
||||
|
||||
Operational tooling includes an owner-only Workspace health page and Linux deployment preflight, encrypted backup and isolated restore drill. See [operations and recovery](docs/operations.md) before the hotel pilot.
|
||||
The owner-only Workspace health page remains available in the application. Host monitoring, MongoDB backup and disaster recovery are provided by the existing central infrastructure.
|
||||
|
||||
Release packaging is runner-free. `deploy/package_source.py` creates an immutable `guestops_<version>.tar.gz` archive from one explicit committed Git ref for handoff to the Futuresens Ansible deployment. It never packages uncommitted working-tree files.
|
||||
|
||||
## Verification
|
||||
|
||||
@@ -66,7 +68,7 @@ dotnet run --project tests/GuestOps.Tests
|
||||
cd web && npm ci && npm run build
|
||||
```
|
||||
|
||||
Set `MONGO_TEST_URI` to an isolated MongoDB server and `TEST_API_URL=http://127.0.0.1:5180` with a preview API running to enable database and HTTP integration checks. The suite creates and drops only its own randomly named `guestops_test_*` database. CI runs both integrations and builds both Linux images.
|
||||
Set `MONGO_TEST_URI` to an isolated MongoDB server and `TEST_API_URL=http://127.0.0.1:5180` with a preview API running to enable database and HTTP integration checks. The suite creates and drops only its own randomly named `guestops_test_*` database. Run these checks before creating a versioned source package. GuestOps does not require a Gitea Actions runner; deployment follows the existing Futuresens source-package and Ansible process described in the [deployment guide](docs/deployment.md).
|
||||
|
||||
See [controlled FAQ automation](docs/auto-replies.md), [NMI payment setup and recovery](docs/payments.md), [OHIP reservation setup and recovery](docs/pms.md), [AI drafts and reply delivery setup](docs/replies.md), [migration status](docs/migration.md) and [deployment guide](docs/deployment.md).
|
||||
|
||||
|
||||
+12
-6
@@ -1,8 +1,8 @@
|
||||
# GuestOps Release Notes
|
||||
|
||||
## Next release — Unreleased
|
||||
## 0.2.1 — Gate B release candidate
|
||||
|
||||
The reviewed candidate is now promoted into the local `main` history. It is not yet approved for live hotel operations and does not become a release until the merge is pushed, CI evidence is retained and a new immutable semantic-version tag is approved.
|
||||
This candidate freezes the implemented Gate B scope for controlled acceptance. It is not yet approved for live hotel operations and does not become a release until the exact commit is pushed, a checksummed source package and operational evidence are retained, the supervised pilot is approved and the immutable `0.2.1` tag is created.
|
||||
|
||||
### Promoted scope
|
||||
|
||||
@@ -10,20 +10,26 @@ The reviewed candidate is now promoted into the local `main` history. It is not
|
||||
- Approval-controlled OHIP PMS and NMI payment workflows.
|
||||
- FAQ automation controls, team invitations, password recovery, and stronger Google connection recovery.
|
||||
- No-send FAQ batch evaluation with false-positive and false-negative reporting before activation.
|
||||
- Stable tenant-scoped inbox pagination beyond the former 500-message view, stronger unsaved-draft navigation guards, and hotel-timezone inbox timestamps.
|
||||
- Release-bound automation and identity/privacy acceptance records covering training, provider decisions, retention ownership and known limitations.
|
||||
- Stable tenant-scoped inbox pagination beyond the former 500-message view, unsaved-draft guards including browser history navigation, consistent hotel-timezone timestamps across operational screens, and a release-bound desktop-parity acceptance record.
|
||||
- A bounded read-only sandbox capacity probe plus machine-validated, release-bound supervised-pilot run, go/no-go and incident-exercise records.
|
||||
- Backup, restore, opt-in systemd scheduling, deployment, persistence-drill, diagnostic, release-evidence, Google acceptance-record validation and rollback tooling.
|
||||
|
||||
These capabilities still require their separately documented provider, host and operational acceptance. Google, PMS and payment-provider acceptance is not established by local automated tests.
|
||||
|
||||
### Known limitations and launch conditions
|
||||
|
||||
- Gate A still requires a successful default-branch CI run, durable off-host release archive, target-Debian deployment, persistent storage/key validation, monitoring, and a successful restore/rollback exercise.
|
||||
- Gate B still requires real Google acceptance and supervised staff testing. Before pilot use, safely paginate beyond the 500-conversation limit, protect drafts across every navigation path, make login throttling proxy-aware, and render dates in the saved hotel timezone—or record and approve explicit operational containment.
|
||||
- Gate A still requires a checksummed source package from the exact default-branch commit, Ansible installation on the target Debian host, persistent storage/key validation, monitoring, and a successful restore/rollback exercise.
|
||||
- Gate B still requires real Google acceptance and supervised staff testing, including desktop-parity acceptance of pagination, draft protection, proxy-aware login throttling and saved-hotel-timezone rendering.
|
||||
- Gate C still requires the Rezlynx/Guestline adapter and independently accepted PMS/payment workflows, plus privacy, identity, capacity, and release approvals.
|
||||
- FAQ live mode and all external write actions must remain disabled until their corresponding acceptance gate has passed.
|
||||
|
||||
See [MILESTONES.md](MILESTONES.md) for the gate assessment, delivery sequence, and remaining work.
|
||||
|
||||
## 0.2.0 — Superseded candidate identifier
|
||||
|
||||
The published `0.2.0` tag is retained unchanged for auditability but is not the approved deployment candidate. It identifies a development-line commit that is not on the clean Gate B release branch. Do not package or deploy it; `0.2.1` supersedes it.
|
||||
|
||||
## 0.1.0 — 29 September 2026
|
||||
|
||||
The `0.1.0` tag identifies the initial GuestOps Web foundation. It is not approved for live hotel operations.
|
||||
@@ -39,4 +45,4 @@ The `0.1.0` tag identifies the initial GuestOps Web foundation. It is not approv
|
||||
|
||||
### Versioning
|
||||
|
||||
The .NET projects and frontend package currently share version `0.1.0`. Before the next approval tag, choose the next semantic version and update both files together. Move the **Next release** section to that version only after the exact commit, checksummed artifacts and acceptance evidence have been approved.
|
||||
The foundation remains tagged `0.1.0`. The .NET projects and frontend package now share candidate version `0.2.1`; create that immutable tag only after the exact commit, checksummed artifacts and Gate B acceptance evidence have been approved.
|
||||
|
||||
+10
-27
@@ -1,9 +1,9 @@
|
||||
name: guestops
|
||||
x-app-env: &app-env
|
||||
Mongo__ConnectionString: mongodb://guestops:${MONGO_APP_PASSWORD:?Set MONGO_APP_PASSWORD}@mongo:27017/guestops?authSource=guestops
|
||||
Mongo__Database: guestops
|
||||
Mongo__ConnectionString: ${MONGO_CONNECTION_STRING:?Set MONGO_CONNECTION_STRING}
|
||||
Mongo__Database: ${MONGO_DATABASE:-guestops}
|
||||
Keys__Path: /var/lib/guestops/keys
|
||||
PublicUrl: https://sandbox-guestops.futuresens.co.uk
|
||||
PublicUrl: ${GUESTOPS_PUBLIC_ORIGIN:?Set GUESTOPS_PUBLIC_ORIGIN}
|
||||
Google__ClientId: ${GOOGLE_CLIENT_ID:-}
|
||||
Google__ClientSecret: ${GOOGLE_CLIENT_SECRET:-}
|
||||
AutoReply__EnableLive: ${AUTO_REPLY_ENABLE_LIVE:-false}
|
||||
@@ -22,7 +22,7 @@ services:
|
||||
environment:
|
||||
<<: *app-env
|
||||
ASPNETCORE_ENVIRONMENT: Production
|
||||
AllowedHosts: sandbox-guestops.futuresens.co.uk;localhost;127.0.0.1
|
||||
AllowedHosts: ${GUESTOPS_ALLOWED_HOSTS:?Set GUESTOPS_ALLOWED_HOSTS}
|
||||
Proxy__KnownAddress: ${GUESTOPS_GATEWAY:-172.30.87.1}
|
||||
Ai__ApiKey: ${AI_API_KEY:-}
|
||||
Ai__Model: ${AI_MODEL:-}
|
||||
@@ -32,8 +32,9 @@ services:
|
||||
- app-keys:/var/lib/guestops/keys
|
||||
- ${PMS_CONFIG_FILE_HOST:-./deploy/pms.example.json}:/run/guestops/pms.json:ro
|
||||
- ${PAYMENTS_CONFIG_FILE_HOST:-./deploy/payments.example.json}:/run/guestops/payments.json:ro
|
||||
depends_on:
|
||||
mongo: { condition: service_healthy }
|
||||
labels:
|
||||
co.elastic.logs/enabled: "true"
|
||||
service.name: guestops-api
|
||||
logging: *logging
|
||||
mem_limit: 1g
|
||||
security_opt: ["no-new-privileges:true"]
|
||||
@@ -43,31 +44,13 @@ services:
|
||||
restart: unless-stopped
|
||||
environment: *app-env
|
||||
volumes: ["app-keys:/var/lib/guestops/keys"]
|
||||
depends_on:
|
||||
mongo: { condition: service_healthy }
|
||||
labels:
|
||||
co.elastic.logs/enabled: "true"
|
||||
service.name: guestops-worker
|
||||
logging: *logging
|
||||
mem_limit: 768m
|
||||
security_opt: ["no-new-privileges:true"]
|
||||
mongo:
|
||||
image: mongo:8.0
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
MONGO_INITDB_ROOT_USERNAME: admin
|
||||
MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD:?Set MONGO_ROOT_PASSWORD}
|
||||
MONGO_APP_PASSWORD: ${MONGO_APP_PASSWORD:?Set MONGO_APP_PASSWORD}
|
||||
volumes:
|
||||
- mongo-data:/data/db
|
||||
- ./deploy/mongo-init.js:/docker-entrypoint-initdb.d/guestops.js:ro
|
||||
command: ["mongod", "--wiredTigerCacheSizeGB", "1"]
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "mongosh --quiet --eval 'db.adminCommand({ping:1}).ok' | grep 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 12
|
||||
logging: *logging
|
||||
mem_limit: 2500m
|
||||
volumes:
|
||||
mongo-data:
|
||||
app-keys:
|
||||
networks:
|
||||
default:
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-automation-acceptance",
|
||||
"targetGate": "B",
|
||||
"dataClassification": "synthetic-only",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"environment": "https://sandbox-guestops.example.invalid",
|
||||
"operator": "REPLACE OPERATOR",
|
||||
"reviewedBy": "REPLACE REVIEWER",
|
||||
"startedAt": "2026-10-01T09:00:00Z",
|
||||
"endedAt": "2026-10-01T10:00:00Z",
|
||||
"reviewedAt": "2026-10-01T11:00:00Z",
|
||||
"faqEvaluation": {"positiveCases": 0, "negativeCases": 0, "falsePositives": 0, "falseNegatives": 0, "reportSha256": "0000000000000000000000000000000000000000000000000000000000000000"},
|
||||
"aiEvaluation": {"casesReviewed": 0, "unsafeDraftsApproved": 0, "reportSha256": "0000000000000000000000000000000000000000000000000000000000000000"},
|
||||
"staffTrained": 0,
|
||||
"monitoringOwner": "REPLACE",
|
||||
"rollbackOwner": "REPLACE",
|
||||
"scenarios": [
|
||||
{"id": "ai-suggestion-review", "status": "not-run", "evidence": []},
|
||||
{"id": "faq-positive-negative", "status": "not-run", "evidence": []},
|
||||
{"id": "faq-stop-control", "status": "not-run", "evidence": []},
|
||||
{"id": "knowledge-curation", "status": "not-run", "evidence": []},
|
||||
{"id": "monitoring-rollback", "status": "not-run", "evidence": []},
|
||||
{"id": "staff-training", "status": "not-run", "evidence": []}
|
||||
],
|
||||
"postAcceptanceState": {"faqMode": "off", "pmsWrites": "disabled", "paymentCreation": "disabled"}
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate restricted Gate B knowledge, AI and FAQ acceptance evidence."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
|
||||
SCENARIOS = {
|
||||
"knowledge-curation", "faq-positive-negative", "faq-stop-control",
|
||||
"ai-suggestion-review", "staff-training", "monitoring-rollback",
|
||||
}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
return dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
|
||||
|
||||
def name(value: object, field: str) -> str:
|
||||
result = str(value or "").strip()
|
||||
require(2 <= len(result) <= 120 and "@" not in result, f"{field} requires a name without an email address.")
|
||||
return result
|
||||
|
||||
|
||||
def refs(value: object, field: str) -> None:
|
||||
require(isinstance(value, list) and 1 <= len(value) <= 10 and all(
|
||||
isinstance(item, str) and 3 <= len(item) <= 200 and "@" not in item for item in value
|
||||
), f"{field} requires safe opaque evidence references.")
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Acceptance record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 1, "Unsupported automation acceptance schema.")
|
||||
require(record.get("system") == "guestops-automation-acceptance", "system must be guestops-automation-acceptance.")
|
||||
require(record.get("targetGate") == "B", "Automation acceptance must target Gate B.")
|
||||
require(record.get("dataClassification") == "synthetic-only", "Automation acceptance must use synthetic data only.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None, "releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None, "releaseRecordSha256 must be a SHA-256 digest.")
|
||||
origin = urlparse(str(record.get("environment", "")))
|
||||
require(origin.scheme == "https" and origin.hostname and origin.path in ("", "/") and not origin.query and not origin.fragment and origin.username is None and origin.password is None,
|
||||
"environment must be an HTTPS origin without credentials, path, query or fragment.")
|
||||
operator = name(record.get("operator"), "operator")
|
||||
reviewer = name(record.get("reviewedBy"), "reviewedBy")
|
||||
require(operator.casefold() != reviewer.casefold(), "operator and reviewedBy must be different people.")
|
||||
started = timestamp(record.get("startedAt"), "startedAt")
|
||||
ended = timestamp(record.get("endedAt"), "endedAt")
|
||||
reviewed = timestamp(record.get("reviewedAt"), "reviewedAt")
|
||||
require(started <= ended <= reviewed, "Acceptance timestamps are out of order.")
|
||||
|
||||
faq = record.get("faqEvaluation")
|
||||
require(isinstance(faq, dict), "faqEvaluation is required.")
|
||||
for field in ("positiveCases", "negativeCases"):
|
||||
require(isinstance(faq.get(field), int) and not isinstance(faq.get(field), bool) and faq[field] > 0,
|
||||
f"faqEvaluation.{field} must be a positive integer.")
|
||||
require(faq.get("falsePositives") == 0 and faq.get("falseNegatives") == 0,
|
||||
"FAQ activation requires zero false positives and zero false negatives.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(faq.get("reportSha256", ""))) is not None,
|
||||
"faqEvaluation.reportSha256 must identify the retained report.")
|
||||
ai = record.get("aiEvaluation")
|
||||
require(isinstance(ai, dict) and isinstance(ai.get("casesReviewed"), int) and not isinstance(ai.get("casesReviewed"), bool) and ai["casesReviewed"] > 0,
|
||||
"aiEvaluation requires at least one reviewed case.")
|
||||
require(isinstance(ai.get("unsafeDraftsApproved"), int) and not isinstance(ai.get("unsafeDraftsApproved"), bool)
|
||||
and ai["unsafeDraftsApproved"] == 0, "No unsafe AI draft may be approved.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(ai.get("reportSha256", ""))) is not None,
|
||||
"aiEvaluation.reportSha256 must identify the retained report.")
|
||||
require(isinstance(record.get("staffTrained"), int) and not isinstance(record.get("staffTrained"), bool) and record["staffTrained"] > 0,
|
||||
"At least one pilot staff member must complete training.")
|
||||
name(record.get("monitoringOwner"), "monitoringOwner")
|
||||
name(record.get("rollbackOwner"), "rollbackOwner")
|
||||
|
||||
scenarios = record.get("scenarios")
|
||||
require(isinstance(scenarios, list), "scenarios must be a list.")
|
||||
ids = [item.get("id") for item in scenarios if isinstance(item, dict)]
|
||||
require(len(ids) == len(scenarios) and len(ids) == len(set(ids)) and set(ids) == SCENARIOS,
|
||||
"Acceptance record requires the exact automation scenario set.")
|
||||
for item in scenarios:
|
||||
require(item.get("status") == "pass", f"Scenario {item['id']} has not passed.")
|
||||
refs(item.get("evidence"), f"Scenario {item['id']}")
|
||||
require(record.get("postAcceptanceState") == {"faqMode": "off", "pmsWrites": "disabled", "paymentCreation": "disabled"},
|
||||
"Acceptance must end with FAQ live mode, PMS writes and payment creation disabled.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print("Automation acceptance record is structurally complete. This validates the record, not its restricted evidence.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Automation acceptance record rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-desktop-parity",
|
||||
"dataClassification": "synthetic-only",
|
||||
"desktopBaselineCommit": "18b983bf402ecdded6430fd40bc4d3320587595a",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"environment": "https://sandbox-guestops.example.invalid",
|
||||
"browser": {
|
||||
"name": "Microsoft Edge",
|
||||
"version": "REPLACE_WITH_FULL_VERSION",
|
||||
"operatingSystem": "Windows 11"
|
||||
},
|
||||
"viewport": {"width": 1440, "height": 900, "deviceScaleFactor": 1},
|
||||
"hotelTimeZone": "Europe/London",
|
||||
"operator": "Acceptance operator",
|
||||
"reviewedBy": "Independent reviewer",
|
||||
"startedAt": "2026-09-29T09:00:00Z",
|
||||
"endedAt": "2026-09-29T10:00:00Z",
|
||||
"reviewedAt": "2026-09-29T11:00:00Z",
|
||||
"scenarios": [
|
||||
{"id": "desktop-layout", "status": "not-run", "evidence": []},
|
||||
{"id": "draft-conversation-guard", "status": "not-run", "evidence": []},
|
||||
{"id": "draft-filter-search-guard", "status": "not-run", "evidence": []},
|
||||
{"id": "draft-route-history-reload-guard", "status": "not-run", "evidence": []},
|
||||
{"id": "inbox-core-workflow", "status": "not-run", "evidence": []},
|
||||
{"id": "pagination-beyond-500", "status": "not-run", "evidence": []},
|
||||
{"id": "role-and-control-parity", "status": "not-run", "evidence": []},
|
||||
{"id": "timezone-and-dst", "status": "not-run", "evidence": []}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,121 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate a restricted GuestOps desktop-parity acceptance record."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
|
||||
DESKTOP_BASELINE = "18b983bf402ecdded6430fd40bc4d3320587595a"
|
||||
SCENARIOS = {
|
||||
"inbox-core-workflow",
|
||||
"pagination-beyond-500",
|
||||
"draft-conversation-guard",
|
||||
"draft-filter-search-guard",
|
||||
"draft-route-history-reload-guard",
|
||||
"timezone-and-dst",
|
||||
"role-and-control-parity",
|
||||
"desktop-layout",
|
||||
}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
parsed = dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
require(parsed.tzinfo == dt.timezone.utc, f"{field} must be UTC.")
|
||||
return parsed
|
||||
|
||||
|
||||
def safe_name(value: object, field: str) -> str:
|
||||
name = str(value or "").strip()
|
||||
require(2 <= len(name) <= 120 and "@" not in name, f"{field} requires a name without an email address.")
|
||||
return name
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Acceptance record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 1, "Unsupported acceptance record schema.")
|
||||
require(record.get("system") == "guestops-desktop-parity",
|
||||
"Acceptance record system must be guestops-desktop-parity.")
|
||||
require(record.get("dataClassification") == "synthetic-only",
|
||||
"Desktop acceptance must use synthetic data only.")
|
||||
require(record.get("desktopBaselineCommit") == DESKTOP_BASELINE,
|
||||
"desktopBaselineCommit must identify the reviewed desktop baseline.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None,
|
||||
"releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None,
|
||||
"releaseRecordSha256 must be a SHA-256 digest.")
|
||||
|
||||
origin = urlparse(str(record.get("environment", "")))
|
||||
require(origin.scheme == "https" and origin.hostname and origin.path in ("", "/")
|
||||
and not origin.query and not origin.fragment and origin.username is None and origin.password is None,
|
||||
"environment must be an HTTPS origin without credentials, path, query or fragment.")
|
||||
|
||||
browser = record.get("browser")
|
||||
require(isinstance(browser, dict) and set(browser) == {"name", "version", "operatingSystem"},
|
||||
"browser must contain exactly name, version and operatingSystem.")
|
||||
for field in ("name", "version", "operatingSystem"):
|
||||
require(2 <= len(str(browser.get(field, "")).strip()) <= 120,
|
||||
f"browser.{field} is required.")
|
||||
viewport = record.get("viewport")
|
||||
require(isinstance(viewport, dict) and set(viewport) == {"width", "height", "deviceScaleFactor"},
|
||||
"viewport must contain exactly width, height and deviceScaleFactor.")
|
||||
require(isinstance(viewport["width"], int) and not isinstance(viewport["width"], bool)
|
||||
and 1280 <= viewport["width"] <= 7680, "Desktop viewport width must be between 1280 and 7680 pixels.")
|
||||
require(isinstance(viewport["height"], int) and not isinstance(viewport["height"], bool)
|
||||
and 720 <= viewport["height"] <= 4320, "Desktop viewport height must be between 720 and 4320 pixels.")
|
||||
require(isinstance(viewport["deviceScaleFactor"], (int, float)) and not isinstance(viewport["deviceScaleFactor"], bool)
|
||||
and 0.5 <= viewport["deviceScaleFactor"] <= 4, "deviceScaleFactor must be between 0.5 and 4.")
|
||||
time_zone = str(record.get("hotelTimeZone", ""))
|
||||
require(time_zone == "UTC" or re.fullmatch(r"[A-Za-z_]+(?:/[A-Za-z0-9_+\-]+)+", time_zone) is not None,
|
||||
"hotelTimeZone must be UTC or an IANA timezone name.")
|
||||
|
||||
operator = safe_name(record.get("operator"), "operator")
|
||||
reviewer = safe_name(record.get("reviewedBy"), "reviewedBy")
|
||||
require(operator.casefold() != reviewer.casefold(), "operator and reviewedBy must be different people.")
|
||||
started = timestamp(record.get("startedAt"), "startedAt")
|
||||
ended = timestamp(record.get("endedAt"), "endedAt")
|
||||
reviewed = timestamp(record.get("reviewedAt"), "reviewedAt")
|
||||
require(started <= ended <= reviewed, "Acceptance timestamps are out of order.")
|
||||
|
||||
scenarios = record.get("scenarios")
|
||||
require(isinstance(scenarios, list), "scenarios must be a list.")
|
||||
ids = [item.get("id") for item in scenarios if isinstance(item, dict)]
|
||||
require(len(ids) == len(scenarios) and len(ids) == len(set(ids)) and set(ids) == SCENARIOS,
|
||||
"Acceptance record requires the exact desktop scenario set.")
|
||||
for item in scenarios:
|
||||
scenario_id = item["id"]
|
||||
require(item.get("status") == "pass", f"Scenario {scenario_id} has not passed.")
|
||||
evidence = item.get("evidence")
|
||||
require(isinstance(evidence, list) and 1 <= len(evidence) <= 10 and all(
|
||||
isinstance(value, str) and 3 <= len(value) <= 200 and "@" not in value for value in evidence
|
||||
), f"Scenario {scenario_id} requires safe opaque evidence references without email addresses.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print(f"Desktop-parity acceptance record is structurally complete: {len(SCENARIOS)} scenarios passed. This validates the record, not its restricted evidence.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Desktop-parity acceptance record rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -2,7 +2,7 @@
|
||||
"acceptedAt": "2026-01-01T00:00:00Z",
|
||||
"acceptedBy": "REPLACE WITH APPROVER",
|
||||
"endedAt": "2026-01-01T00:00:00Z",
|
||||
"environment": "https://sandbox-guestops.futuresens.co.uk",
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk",
|
||||
"mailboxLabel": "sandbox mailbox A",
|
||||
"operator": "REPLACE WITH OPERATOR",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-identity-privacy",
|
||||
"targetGate": "B",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"environment": "https://sandbox-guestops.example.invalid",
|
||||
"operator": "REPLACE OPERATOR",
|
||||
"reviewedBy": "REPLACE REVIEWER",
|
||||
"startedAt": "2026-10-01T09:00:00Z",
|
||||
"endedAt": "2026-10-01T10:00:00Z",
|
||||
"reviewedAt": "2026-10-01T11:00:00Z",
|
||||
"retention": {
|
||||
"conversationDays": 0,
|
||||
"auditDays": 0,
|
||||
"backupDays": 0,
|
||||
"accountDays": 0,
|
||||
"privacyOwner": "REPLACE",
|
||||
"deletionOwner": "REPLACE",
|
||||
"legalHoldOwner": "REPLACE",
|
||||
"deletionProcedure": "REPLACE-RESTRICTED-REFERENCE",
|
||||
"legalHoldProcedure": "REPLACE-RESTRICTED-REFERENCE"
|
||||
},
|
||||
"providers": {
|
||||
"google": {"status": "pending", "evidence": []},
|
||||
"openai": {"status": "pending", "evidence": []}
|
||||
},
|
||||
"preferencesReviewed": [],
|
||||
"scenarios": [
|
||||
{"id": "account-lifecycle", "status": "not-run", "evidence": []},
|
||||
{"id": "audit-review", "status": "not-run", "evidence": []},
|
||||
{"id": "backup-retention", "status": "not-run", "evidence": []},
|
||||
{"id": "data-inventory", "status": "not-run", "evidence": []},
|
||||
{"id": "known-identity-limitations", "status": "not-run", "evidence": []},
|
||||
{"id": "login-throttling", "status": "not-run", "evidence": []},
|
||||
{"id": "preference-coverage", "status": "not-run", "evidence": []},
|
||||
{"id": "provider-processing", "status": "not-run", "evidence": []},
|
||||
{"id": "retention-deletion", "status": "not-run", "evidence": []},
|
||||
{"id": "role-boundaries", "status": "not-run", "evidence": []},
|
||||
{"id": "session-invalidation", "status": "not-run", "evidence": []}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate restricted Gate B identity, preference and privacy acceptance evidence."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
|
||||
SCENARIOS = {
|
||||
"role-boundaries", "account-lifecycle", "login-throttling", "session-invalidation",
|
||||
"preference-coverage", "data-inventory", "retention-deletion", "backup-retention",
|
||||
"provider-processing", "audit-review", "known-identity-limitations",
|
||||
}
|
||||
PREFERENCES = {
|
||||
"hotel-name", "timezone", "signature", "ai-drafts", "staff-sending",
|
||||
"faq-mode", "pms-updates", "payment-creation",
|
||||
}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
return dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
|
||||
|
||||
def name(value: object, field: str) -> str:
|
||||
result = str(value or "").strip()
|
||||
require(2 <= len(result) <= 120 and "@" not in result, f"{field} requires a name without an email address.")
|
||||
return result
|
||||
|
||||
|
||||
def refs(value: object, field: str) -> None:
|
||||
require(isinstance(value, list) and 1 <= len(value) <= 10 and all(
|
||||
isinstance(item, str) and 3 <= len(item) <= 200 and "@" not in item for item in value
|
||||
), f"{field} requires safe opaque evidence references.")
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Acceptance record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 1, "Unsupported identity/privacy acceptance schema.")
|
||||
require(record.get("system") == "guestops-identity-privacy", "system must be guestops-identity-privacy.")
|
||||
require(record.get("targetGate") == "B", "Identity/privacy acceptance must target Gate B.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None, "releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None, "releaseRecordSha256 must be a SHA-256 digest.")
|
||||
origin = urlparse(str(record.get("environment", "")))
|
||||
require(origin.scheme == "https" and origin.hostname and origin.path in ("", "/") and not origin.query and not origin.fragment and origin.username is None and origin.password is None,
|
||||
"environment must be an HTTPS origin without credentials, path, query or fragment.")
|
||||
operator = name(record.get("operator"), "operator")
|
||||
reviewer = name(record.get("reviewedBy"), "reviewedBy")
|
||||
require(operator.casefold() != reviewer.casefold(), "operator and reviewedBy must be different people.")
|
||||
started = timestamp(record.get("startedAt"), "startedAt")
|
||||
ended = timestamp(record.get("endedAt"), "endedAt")
|
||||
reviewed = timestamp(record.get("reviewedAt"), "reviewedAt")
|
||||
require(started <= ended <= reviewed, "Acceptance timestamps are out of order.")
|
||||
|
||||
retention = record.get("retention")
|
||||
require(isinstance(retention, dict), "retention decisions are required.")
|
||||
for field in ("conversationDays", "auditDays", "backupDays", "accountDays"):
|
||||
value = retention.get(field)
|
||||
require(isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= 3650,
|
||||
f"retention.{field} must be between 1 and 3650 days.")
|
||||
for field in ("privacyOwner", "deletionOwner", "legalHoldOwner"):
|
||||
name(retention.get(field), f"retention.{field}")
|
||||
for field in ("deletionProcedure", "legalHoldProcedure"):
|
||||
refs([retention.get(field)], f"retention.{field}")
|
||||
|
||||
providers = record.get("providers")
|
||||
require(isinstance(providers, dict) and set(providers) == {"google", "openai"},
|
||||
"providers must contain exactly google and openai decisions.")
|
||||
require(all(isinstance(decision, dict) for decision in providers.values()),
|
||||
"Each provider decision must be an object.")
|
||||
require(providers["google"].get("status") == "accepted", "Google processing must be accepted for the Gate B mailbox pilot.")
|
||||
require(providers["openai"].get("status") in ("accepted", "disabled"), "OpenAI processing must be accepted or disabled.")
|
||||
for provider, decision in providers.items():
|
||||
refs(decision.get("evidence"), f"Provider {provider}")
|
||||
preferences = record.get("preferencesReviewed")
|
||||
require(isinstance(preferences, list) and all(isinstance(item, str) for item in preferences)
|
||||
and set(preferences) == PREFERENCES and len(preferences) == len(PREFERENCES),
|
||||
"preferencesReviewed must contain the exact owner-controlled preference set.")
|
||||
|
||||
scenarios = record.get("scenarios")
|
||||
require(isinstance(scenarios, list), "scenarios must be a list.")
|
||||
ids = [item.get("id") for item in scenarios if isinstance(item, dict)]
|
||||
require(len(ids) == len(scenarios) and len(ids) == len(set(ids)) and set(ids) == SCENARIOS,
|
||||
"Acceptance record requires the exact identity/privacy scenario set.")
|
||||
for item in scenarios:
|
||||
require(item.get("status") == "pass", f"Scenario {item['id']} has not passed.")
|
||||
refs(item.get("evidence"), f"Scenario {item['id']}")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print("Identity/privacy acceptance record is structurally complete. This validates the record, not its restricted evidence or legal decisions.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Identity/privacy acceptance record rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-incident-exercise",
|
||||
"targetGate": "B",
|
||||
"dataClassification": "synthetic-only",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"environment": "https://sandbox-guestops.example.invalid",
|
||||
"operator": "Exercise operator",
|
||||
"incidentCommander": "Incident commander",
|
||||
"reviewedBy": "Independent reviewer",
|
||||
"startedAt": "2026-09-29T09:00:00Z",
|
||||
"endedAt": "2026-09-29T10:00:00Z",
|
||||
"reviewedAt": "2026-09-29T11:00:00Z",
|
||||
"targetsMinutes": {
|
||||
"detection": 10,
|
||||
"containment": 20,
|
||||
"recovery": 60
|
||||
},
|
||||
"observedMinutes": {
|
||||
"detection": 0,
|
||||
"containment": 0,
|
||||
"recovery": 0
|
||||
},
|
||||
"scenarios": [
|
||||
{"id": "alert-and-escalate", "status": "not-run", "evidence": []},
|
||||
{"id": "controlled-recovery", "status": "not-run", "evidence": []},
|
||||
{"id": "disable-worker-writes", "status": "not-run", "evidence": []},
|
||||
{"id": "google-uncertain-send", "status": "not-run", "evidence": []},
|
||||
{"id": "image-rollback", "status": "not-run", "evidence": []},
|
||||
{"id": "restore-readiness", "status": "not-run", "evidence": []}
|
||||
],
|
||||
"postExerciseState": {
|
||||
"externalWrites": "disabled",
|
||||
"faqMode": "off",
|
||||
"unresolvedOperations": 0
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,132 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate a restricted GuestOps incident and rollback exercise record."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
|
||||
GATE_B_SCENARIOS = {
|
||||
"alert-and-escalate",
|
||||
"disable-worker-writes",
|
||||
"google-uncertain-send",
|
||||
"restore-readiness",
|
||||
"image-rollback",
|
||||
"controlled-recovery",
|
||||
}
|
||||
GATE_C_SCENARIOS = GATE_B_SCENARIOS | {
|
||||
"pms-ambiguous-write",
|
||||
"payment-ambiguous-create",
|
||||
}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def utc_timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
parsed = dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
require(parsed.tzinfo == dt.timezone.utc, f"{field} must be UTC.")
|
||||
return parsed
|
||||
|
||||
|
||||
def safe_name(value: object, field: str) -> str:
|
||||
name = str(value or "").strip()
|
||||
require(2 <= len(name) <= 120 and "@" not in name, f"{field} requires a name without an email address.")
|
||||
return name
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Exercise record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 1, "Unsupported exercise record schema.")
|
||||
require(record.get("system") == "guestops-incident-exercise",
|
||||
"Exercise record system must be guestops-incident-exercise.")
|
||||
gate = record.get("targetGate")
|
||||
require(gate in ("B", "C"), "targetGate must be B or C.")
|
||||
require(record.get("dataClassification") == "synthetic-only",
|
||||
"Incident exercises must use synthetic data only.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None,
|
||||
"releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None,
|
||||
"releaseRecordSha256 must be a SHA-256 digest.")
|
||||
|
||||
environment = str(record.get("environment", ""))
|
||||
parsed_url = urlparse(environment)
|
||||
require(parsed_url.scheme == "https" and parsed_url.hostname and parsed_url.path in ("", "/")
|
||||
and not parsed_url.query and not parsed_url.fragment and parsed_url.username is None
|
||||
and parsed_url.password is None,
|
||||
"environment must be an HTTPS origin without credentials, path, query or fragment.")
|
||||
|
||||
operator = safe_name(record.get("operator"), "operator")
|
||||
commander = safe_name(record.get("incidentCommander"), "incidentCommander")
|
||||
reviewer = safe_name(record.get("reviewedBy"), "reviewedBy")
|
||||
require(len({operator.casefold(), commander.casefold(), reviewer.casefold()}) == 3,
|
||||
"operator, incidentCommander and reviewedBy must be different people.")
|
||||
|
||||
started = utc_timestamp(record.get("startedAt"), "startedAt")
|
||||
ended = utc_timestamp(record.get("endedAt"), "endedAt")
|
||||
reviewed = utc_timestamp(record.get("reviewedAt"), "reviewedAt")
|
||||
require(started <= ended <= reviewed, "Exercise timestamps are out of order.")
|
||||
|
||||
targets = record.get("targetsMinutes")
|
||||
observed = record.get("observedMinutes")
|
||||
require(isinstance(targets, dict) and isinstance(observed, dict),
|
||||
"targetsMinutes and observedMinutes are required.")
|
||||
metric_keys = {"detection", "containment", "recovery"}
|
||||
require(set(targets) == metric_keys and set(observed) == metric_keys,
|
||||
"Timing records require exactly detection, containment and recovery.")
|
||||
for metric in sorted(metric_keys):
|
||||
target = targets[metric]
|
||||
actual = observed[metric]
|
||||
require(isinstance(target, (int, float)) and not isinstance(target, bool) and 0 < target <= 1440,
|
||||
f"{metric} target must be greater than zero and no more than 1440 minutes.")
|
||||
require(isinstance(actual, (int, float)) and not isinstance(actual, bool) and 0 <= actual <= target,
|
||||
f"Observed {metric} time must meet its pre-agreed target.")
|
||||
|
||||
scenarios = record.get("scenarios")
|
||||
require(isinstance(scenarios, list), "scenarios must be a list.")
|
||||
ids = [item.get("id") for item in scenarios if isinstance(item, dict)]
|
||||
required = GATE_C_SCENARIOS if gate == "C" else GATE_B_SCENARIOS
|
||||
require(len(ids) == len(scenarios) and len(ids) == len(set(ids)) and set(ids) == required,
|
||||
f"Gate {gate} requires the exact incident scenario set.")
|
||||
for item in scenarios:
|
||||
scenario_id = item["id"]
|
||||
require(item.get("status") == "pass", f"Scenario {scenario_id} has not passed.")
|
||||
evidence = item.get("evidence")
|
||||
require(isinstance(evidence, list) and 1 <= len(evidence) <= 10 and all(
|
||||
isinstance(value, str) and 3 <= len(value) <= 200 and "@" not in value
|
||||
for value in evidence
|
||||
), f"Scenario {scenario_id} requires safe opaque evidence references without email addresses.")
|
||||
|
||||
final_state = record.get("postExerciseState")
|
||||
require(isinstance(final_state, dict) and final_state == {
|
||||
"externalWrites": "disabled",
|
||||
"faqMode": "off",
|
||||
"unresolvedOperations": 0,
|
||||
}, "Exercise must end with writes disabled, FAQ mode off and no unresolved operations.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print("Incident exercise record is structurally complete and passed. This validates the record, not its restricted evidence.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Incident exercise record rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -1,2 +0,0 @@
|
||||
const guestops = db.getSiblingDB('guestops');
|
||||
guestops.createUser({user: 'guestops', pwd: process.env.MONGO_APP_PASSWORD, roles: [{role: 'readWrite', db: 'guestops'}]});
|
||||
@@ -1,31 +0,0 @@
|
||||
# Install within the existing Nginx configuration. Obtain the certificate first.
|
||||
server {
|
||||
listen 80;
|
||||
server_name sandbox-guestops.futuresens.co.uk;
|
||||
location /.well-known/acme-challenge/ { root /var/www/letsencrypt; }
|
||||
location / { return 301 https://$host$request_uri; }
|
||||
}
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name sandbox-guestops.futuresens.co.uk;
|
||||
ssl_certificate /etc/letsencrypt/live/sandbox-guestops.futuresens.co.uk/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/sandbox-guestops.futuresens.co.uk/privkey.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
add_header Strict-Transport-Security "max-age=31536000" always;
|
||||
client_max_body_size 128k;
|
||||
# OAuth authorization codes and state must not appear in access logs.
|
||||
location = /api/integrations/google/callback {
|
||||
access_log off;
|
||||
proxy_pass http://127.0.0.1:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto https;
|
||||
}
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8080;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto https;
|
||||
proxy_set_header X-Forwarded-For $remote_addr;
|
||||
proxy_read_timeout 60s;
|
||||
}
|
||||
}
|
||||
-344
@@ -1,344 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""GuestOps dedicated-Compose operations. Never prints credentials or provider data."""
|
||||
import argparse
|
||||
import contextlib
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import re
|
||||
import shutil
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
import tarfile
|
||||
import tempfile
|
||||
import time
|
||||
import urllib.request
|
||||
import uuid
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
FILES = {"mongo.archive.gz", "keys.tar.gz", "configuration.json", "manifest.json"}
|
||||
LIMIT = 8 * 1024**3
|
||||
|
||||
|
||||
def require(condition, message):
|
||||
if not condition:
|
||||
raise RuntimeError(message)
|
||||
|
||||
|
||||
def run(args, *, output=None, input_file=None, timeout=900):
|
||||
# Provider output may contain secrets; errors identify only the program.
|
||||
result = subprocess.run(args, cwd=ROOT, stdin=input_file or subprocess.DEVNULL,
|
||||
stdout=output or subprocess.PIPE, stderr=subprocess.PIPE, timeout=timeout)
|
||||
require(result.returncode == 0, f"{args[0]} step failed. Check the private operator environment; no command output was logged.")
|
||||
return result.stdout or b""
|
||||
|
||||
|
||||
def compose(*args, **kwargs):
|
||||
return run(["docker", "compose", *args], **kwargs)
|
||||
|
||||
|
||||
def digest(path):
|
||||
with path.open("rb") as stream:
|
||||
return hashlib.file_digest(stream, "sha256").hexdigest()
|
||||
|
||||
|
||||
def image_id(image):
|
||||
require(not image.startswith("-"), "Invalid image reference.")
|
||||
return run(["docker", "image", "inspect", "--format", "{{.Id}}", image]).decode().strip()
|
||||
|
||||
|
||||
def provider_configured(config, target):
|
||||
section = "Pms" if target == "/run/guestops/pms.json" else "Payments"
|
||||
# Only the exact shipped empty template is public; unknown settings fail closed.
|
||||
return config not in ({}, {section: {"Hotels": {}}})
|
||||
|
||||
|
||||
def persistence_layout(config):
|
||||
"""Return the resolved named volumes required to survive recreation."""
|
||||
services = config["services"]
|
||||
declared = config.get("volumes", {})
|
||||
|
||||
def volume_for(service, target):
|
||||
matches = [v for v in services[service].get("volumes", []) if v["target"] == target]
|
||||
require(len(matches) == 1 and matches[0]["type"] == "volume" and matches[0].get("source"),
|
||||
f"{service} requires one named persistent volume at {target}.")
|
||||
source = matches[0]["source"]
|
||||
require(source in declared, f"{service} volume {source} must be declared at the top level.")
|
||||
return declared[source].get("name") or source
|
||||
|
||||
api_keys = volume_for("api", "/var/lib/guestops/keys")
|
||||
worker_keys = volume_for("worker", "/var/lib/guestops/keys")
|
||||
require(api_keys == worker_keys, "API and worker key volumes differ.")
|
||||
mongo_data = volume_for("mongo", "/data/db")
|
||||
require(api_keys != mongo_data, "Database and key data require separate named volumes.")
|
||||
return {"keys": api_keys, "database": mongo_data}
|
||||
|
||||
|
||||
AUTH = 'const c=new Mongo("mongodb://127.0.0.1"); c.getDB("admin").auth(process.env.MONGO_INITDB_ROOT_USERNAME,process.env.MONGO_INITDB_ROOT_PASSWORD);'
|
||||
INVENTORY = 'const d=c.getDB("guestops"); print(JSON.stringify({bytes:d.stats().storageSize+d.stats().indexSize,collections:Object.fromEntries(d.getCollectionNames().filter(n=>!n.startsWith("system.")).sort().map(n=>[n,{count:d.getCollection(n).countDocuments({}),indexes:d.getCollection(n).getIndexes().map(i=>{delete i.ns;return i;}).sort((a,b)=>a.name.localeCompare(b.name))}]))}));'
|
||||
|
||||
|
||||
def mongo(script):
|
||||
return compose("exec", "-T", "mongo", "mongosh", "--quiet", "--nodb", "--eval", AUTH + script)
|
||||
|
||||
|
||||
def configuration():
|
||||
config = json.loads(compose("config", "--format", "json"))
|
||||
services = config["services"]
|
||||
require(set(services) == {"api", "worker", "mongo"}, "This tool supports the dedicated three-service GuestOps Compose deployment only.")
|
||||
require(not services["mongo"].get("ports"), "MongoDB must not have published ports.")
|
||||
ports = services["api"].get("ports", [])
|
||||
require(len(ports) == 1 and ports[0].get("host_ip") == "127.0.0.1" and int(ports[0]["target"]) == 8080, "API must publish only port 8080 on loopback.")
|
||||
require(not services["worker"].get("ports"), "Worker must not publish ports.")
|
||||
for name in ("api", "worker"):
|
||||
env = services[name]["environment"]
|
||||
require(env.get("Mongo__Database") == "guestops" and "@mongo:27017/guestops?" in env.get("Mongo__ConnectionString", ""), "Backup supports only the dedicated Compose guestops database.")
|
||||
require(str(env.get("Preview", "false")).lower() != "true", "Production preview is forbidden.")
|
||||
require(env.get("Keys__Path") == "/var/lib/guestops/keys", "Unexpected key directory.")
|
||||
require(services["api"]["environment"].get("ASPNETCORE_ENVIRONMENT") == "Production", "API must use Production environment.")
|
||||
require(re.fullmatch(r"https://[A-Za-z0-9.-]+", services["api"]["environment"].get("PublicUrl", "")), "PublicUrl must be an HTTPS hostname without a path.")
|
||||
persistence_layout(config)
|
||||
return config
|
||||
|
||||
|
||||
def wait_for(action, message, attempts=60):
|
||||
for attempt in range(attempts):
|
||||
try:
|
||||
action()
|
||||
return
|
||||
except Exception:
|
||||
if attempt == attempts - 1:
|
||||
raise RuntimeError(message)
|
||||
time.sleep(1)
|
||||
|
||||
|
||||
def volume_identity(name):
|
||||
require(not name.startswith("-"), "Invalid volume name.")
|
||||
details = json.loads(run(["docker", "volume", "inspect", name]))
|
||||
require(len(details) == 1 and details[0].get("Name") == name, "Named volume inspection failed.")
|
||||
return {"name": name, "driver": details[0].get("Driver"), "scope": details[0].get("Scope")}
|
||||
|
||||
|
||||
def readiness():
|
||||
with urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=10) as response:
|
||||
require(json.load(response) == {"status": "ready"}, "Loopback readiness failed.")
|
||||
|
||||
|
||||
def persistence_drill(args):
|
||||
require(args.confirm_restart, "Persistence drill requires --confirm-restart: all services will be restarted and application containers recreated.")
|
||||
config = configuration()
|
||||
layout = persistence_layout(config)
|
||||
before_volumes = {purpose: volume_identity(name) for purpose, name in layout.items()}
|
||||
before_inventory = json.loads(mongo(INVENTORY))
|
||||
probe = compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "api", "--backup-probe").decode().strip()
|
||||
require(re.fullmatch(r"[A-Za-z0-9_-]{20,4096}", probe), "Key probe did not return a valid protected value.")
|
||||
|
||||
# Restart the database first, then its clients, so recovery is exercised in a known order.
|
||||
compose("restart", "-t", "150", "mongo")
|
||||
wait_for(lambda: mongo('const r=c.getDB("admin").runCommand({ping:1});if(!r.ok)quit(1);'), "MongoDB did not recover after restart.")
|
||||
compose("restart", "-t", "150", "api", "worker")
|
||||
wait_for(readiness, "API readiness did not recover after restart.")
|
||||
|
||||
# Recreate stateless containers as an image upgrade would, without rebuilding or changing data volumes.
|
||||
compose("up", "-d", "--no-build", "--force-recreate", "api", "worker")
|
||||
wait_for(readiness, "API readiness did not recover after container recreation.")
|
||||
compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "-e", "BACKUP_PROBE=" + probe, "api", "--verify-backup-probe")
|
||||
|
||||
after_volumes = {purpose: volume_identity(name) for purpose, name in layout.items()}
|
||||
after_inventory = json.loads(mongo(INVENTORY))
|
||||
require(after_volumes == before_volumes, "A persistent volume identity changed during the drill.")
|
||||
require(after_inventory["collections"] == before_inventory["collections"], "Database collection counts or indexes changed during the drill.")
|
||||
print("Persistence drill passed: named volumes, database counts/indexes, data-protection keys and readiness survived restart and container recreation.")
|
||||
|
||||
|
||||
def preflight(args):
|
||||
config = configuration()
|
||||
env_file = ROOT / ".env"
|
||||
require(env_file.is_file() and not env_file.is_symlink(), "Create a private .env file before deployment.")
|
||||
require(stat.S_IMODE(env_file.stat().st_mode) & 0o077 == 0, ".env must not be accessible to group or other users.")
|
||||
require(shutil.disk_usage(ROOT).free >= 8 * 1024**3, "Keep at least 8 GiB free before deployment; allow extra room for backups.")
|
||||
for name, service in config["services"].items():
|
||||
image_id(service["image"])
|
||||
for volume in service.get("volumes", []):
|
||||
if volume["type"] == "bind":
|
||||
require(Path(volume["source"]).exists(), f"A required {name} bind mount is missing.")
|
||||
if volume["target"] in ("/run/guestops/pms.json", "/run/guestops/payments.json"):
|
||||
provider = Path(volume["source"])
|
||||
if provider_configured(json.loads(provider.read_text()), volume["target"]):
|
||||
require(stat.S_IMODE(provider.stat().st_mode) & 0o077 == 0, "Configured provider files must not be accessible to group or other users.")
|
||||
if not args.offline:
|
||||
url = config["services"]["api"]["environment"]["PublicUrl"]
|
||||
require(re.fullmatch(r"https://[A-Za-z0-9.-]+", url), "PublicUrl must be an HTTPS hostname without a path.")
|
||||
with urllib.request.urlopen(url + "/health/ready", timeout=15) as response:
|
||||
require(response.url == url + "/health/ready" and json.load(response) == {"status": "ready"}, "Public HTTPS readiness failed.")
|
||||
print("Preflight passed: private database, loopback API, production settings, images, mounts and disk headroom" + ("; HTTPS not checked." if args.offline else "; public HTTPS and database readiness checked."))
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def maintenance_lock():
|
||||
import fcntl
|
||||
with (ROOT / ".guestops-maintenance.lock").open("a") as lock:
|
||||
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
||||
yield
|
||||
|
||||
|
||||
def backup(args):
|
||||
require(args.confirm_maintenance, "Backup requires --confirm-maintenance: API and workers will briefly stop.")
|
||||
require(re.fullmatch(r"[A-Fa-f0-9]{40}", args.recipient), "Use a verified full 40-character GPG recipient fingerprint.")
|
||||
run(["gpg", "--batch", "--list-keys", args.recipient])
|
||||
destination = Path(args.output).resolve()
|
||||
require(not destination.exists(), "Backup output already exists; choose a new filename.")
|
||||
require(destination.parent.is_dir(), "Create the private backup directory first.")
|
||||
require(stat.S_IMODE(destination.parent.stat().st_mode) & 0o077 == 0, "Backup directory must be private (mode 700).")
|
||||
config = configuration()
|
||||
runtime = {}
|
||||
for service in ("api", "worker", "mongo"):
|
||||
cid = compose("ps", "--status", "running", "-q", service).decode().strip()
|
||||
require(re.fullmatch(r"[a-f0-9]{12,64}", cid), f"Exactly one running {service} container is required.")
|
||||
runtime[service] = json.loads(run(["docker", "inspect", cid]))[0]
|
||||
require(shutil.disk_usage(destination.parent).free >= 3 * json.loads(mongo(INVENTORY))["bytes"] + 1024**3, "Insufficient free space for a consistent encrypted backup.")
|
||||
partial = destination.with_name(destination.name + ".partial-" + uuid.uuid4().hex)
|
||||
with maintenance_lock(), tempfile.TemporaryDirectory(prefix="guestops-backup-", dir=destination.parent) as folder:
|
||||
folder = Path(folder)
|
||||
stopped = False
|
||||
ttl = None
|
||||
try:
|
||||
# Set before stopping so partial stop failures also attempt recovery.
|
||||
stopped = True
|
||||
compose("stop", "-t", "150", "api", "worker")
|
||||
ttl = json.loads(mongo('print(JSON.stringify(c.getDB("admin").runCommand({getParameter:1,ttlMonitorEnabled:1}).ttlMonitorEnabled));'))
|
||||
require(isinstance(ttl, bool), "Cannot determine MongoDB TTL monitor state.")
|
||||
mongo('const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:false});if(!r.ok)quit(1);')
|
||||
inventory = json.loads(mongo(INVENTORY))
|
||||
dump = 'set -eu; case "$MONGO_INITDB_ROOT_PASSWORD" in ""|*[!0-9a-fA-F]*) exit 1;; esac; umask 077; cfg=$(mktemp); trap \'rm -f "$cfg"\' EXIT; printf \'password: "%s"\\n\' "$MONGO_INITDB_ROOT_PASSWORD" > "$cfg"; mongodump --config "$cfg" --username "$MONGO_INITDB_ROOT_USERNAME" --authenticationDatabase admin --db guestops --archive --gzip'
|
||||
with (folder / "mongo.archive.gz").open("wb") as output:
|
||||
compose("exec", "-T", "mongo", "sh", "-c", dump, output=output)
|
||||
probe = compose("run", "--rm", "--no-deps", "-T", "-e", "Logging__LogLevel__Default=None", "api", "--backup-probe").decode().strip()
|
||||
require(re.fullmatch(r"[A-Za-z0-9_-]{20,4096}", probe), "Key probe did not return a valid protected value.")
|
||||
with (folder / "keys.tar.gz").open("wb") as output:
|
||||
compose("run", "--rm", "--no-deps", "-T", "--entrypoint", "tar", "api", "-C", "/var/lib/guestops/keys", "-czf", "-", ".", output=output)
|
||||
mounted = {}
|
||||
for volume in config["services"]["api"].get("volumes", []):
|
||||
if volume["type"] == "bind" and volume["target"] in ("/run/guestops/pms.json", "/run/guestops/payments.json"):
|
||||
mounted[volume["target"]] = Path(volume["source"]).read_text()
|
||||
(folder / "configuration.json").write_text(json.dumps({"compose": config, "runtime": runtime, "providerFiles": mounted}))
|
||||
manifest = {"format": 1, "createdAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "inventory": inventory, "probe": probe, "apiImageId": runtime["api"]["Image"], "mongoImageId": runtime["mongo"]["Image"], "sha256": {name: digest(folder / name) for name in FILES - {"manifest.json"}}}
|
||||
(folder / "manifest.json").write_text(json.dumps(manifest))
|
||||
finally:
|
||||
try:
|
||||
if ttl is not None:
|
||||
mongo('const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:' + str(ttl).lower() + '});if(!r.ok)quit(1);')
|
||||
finally:
|
||||
if stopped:
|
||||
compose("start", "api", "worker")
|
||||
try:
|
||||
with tarfile.open(folder / "bundle.tar", "w") as archive:
|
||||
for name in sorted(FILES):
|
||||
archive.add(folder / name, arcname=name, recursive=False)
|
||||
run(["gpg", "--batch", "--trust-model", "always", "--recipient", args.recipient, "--output", str(partial), "--encrypt", str(folder / "bundle.tar")])
|
||||
os.link(partial, destination) # Atomic publication, never overwrite an existing backup.
|
||||
finally:
|
||||
partial.unlink(missing_ok=True)
|
||||
print("Encrypted backup complete. Copy it off-server and perform a restore drill.")
|
||||
|
||||
|
||||
def scheduled_backup(args):
|
||||
require(args.confirm_maintenance, "Scheduled backup requires --confirm-maintenance because API and workers will briefly stop.")
|
||||
recipient = os.environ.get("BACKUP_RECIPIENT", "")
|
||||
directory_value = os.environ.get("BACKUP_DIRECTORY", "")
|
||||
require(re.fullmatch(r"[A-Fa-f0-9]{40}", recipient), "BACKUP_RECIPIENT must be a verified full GPG fingerprint.")
|
||||
require(directory_value != "", "BACKUP_DIRECTORY must name the private off-checkout staging directory.")
|
||||
requested_directory = Path(directory_value)
|
||||
require(requested_directory.is_absolute() and not requested_directory.is_symlink(), "BACKUP_DIRECTORY must be an absolute, non-symlink path.")
|
||||
directory = requested_directory.resolve()
|
||||
require(directory.is_dir(), "BACKUP_DIRECTORY must be an existing real directory.")
|
||||
require(ROOT not in directory.parents and directory != ROOT, "Scheduled backups must be staged outside the application checkout.")
|
||||
require(stat.S_IMODE(directory.stat().st_mode) & 0o077 == 0, "BACKUP_DIRECTORY must be private (mode 700).")
|
||||
timestamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
|
||||
destination = directory / f"guestops-{timestamp}.tar.gpg"
|
||||
backup(argparse.Namespace(confirm_maintenance=True, recipient=recipient, output=str(destination)))
|
||||
print(f"Scheduled backup staged as {destination.name}. Off-host transfer and alert verification remain required.")
|
||||
|
||||
|
||||
def unpack(bundle, folder):
|
||||
with tarfile.open(bundle, "r:") as archive:
|
||||
members = archive.getmembers()
|
||||
require(len(members) == len(FILES) and {m.name for m in members} == FILES, "Unexpected backup members.")
|
||||
require(all(m.isfile() and 0 <= m.size <= LIMIT for m in members) and sum(m.size for m in members) <= LIMIT, "Invalid or oversized backup members.")
|
||||
for member in members:
|
||||
with archive.extractfile(member) as source, (folder / member.name).open("xb") as output:
|
||||
shutil.copyfileobj(source, output)
|
||||
manifest = json.loads((folder / "manifest.json").read_text())
|
||||
require(manifest.get("format") == 1 and set(manifest.get("sha256", {})) == FILES - {"manifest.json"}, "Unsupported backup format.")
|
||||
for name, expected in manifest["sha256"].items():
|
||||
require(digest(folder / name) == expected, "Backup checksum verification failed.")
|
||||
return manifest
|
||||
|
||||
|
||||
def restore_drill(args):
|
||||
backup_file = Path(args.backup).resolve()
|
||||
require(backup_file.is_file(), "Backup file is missing.")
|
||||
with tempfile.TemporaryDirectory(prefix="guestops-restore-", dir=ROOT) as temp:
|
||||
folder = Path(temp)
|
||||
run(["gpg", "--batch", "--max-output", str(LIMIT), "--output", str(folder / "bundle.tar"), "--decrypt", str(backup_file)])
|
||||
require((folder / "bundle.tar").stat().st_size <= LIMIT, "Decrypted bundle exceeds the 8 GiB pilot limit.")
|
||||
manifest = unpack(folder / "bundle.tar", folder)
|
||||
require(image_id(args.api_image) == manifest["apiImageId"] and image_id(args.mongo_image) == manifest["mongoImageId"], "Load the exact trusted API and MongoDB images used for this backup.")
|
||||
require(shutil.disk_usage(ROOT).free > 3 * manifest["inventory"]["bytes"] + 1024**3, "Insufficient restore drill space.")
|
||||
keys = folder / "keys"
|
||||
keys.mkdir(mode=0o700)
|
||||
with tarfile.open(folder / "keys.tar.gz", "r:gz") as archive:
|
||||
total = 0
|
||||
for member in archive:
|
||||
if member.name in (".", "./") and member.isdir():
|
||||
continue
|
||||
name = member.name.removeprefix("./")
|
||||
total += member.size
|
||||
require(member.isfile() and re.fullmatch(r"[A-Za-z0-9_-]+\.xml", name) and member.size < 1024**2 and total < 16 * 1024**2, "Invalid key archive.")
|
||||
with archive.extractfile(member) as source, (keys / name).open("xb") as output:
|
||||
shutil.copyfileobj(source, output)
|
||||
run(["docker", "run", "--rm", "--pull", "never", "--network", "none", "--user", "0:0", "--read-only", "--mount", f"type=bind,src={keys},dst=/var/lib/guestops/keys,readonly", "-e", "Logging__LogLevel__Default=None", "-e", "BACKUP_PROBE=" + manifest["probe"], args.api_image, "--verify-backup-probe"])
|
||||
cid = run(["docker", "run", "-d", "--pull", "never", "--network", "none", "--memory", "1g", "--label", "guestops.restore-drill=true", args.mongo_image, "--bind_ip", "127.0.0.1", "--setParameter", "ttlMonitorEnabled=false"]).decode().strip()
|
||||
require(re.fullmatch(r"[a-f0-9]{64}", cid), "Unexpected restore container identifier.")
|
||||
try:
|
||||
for attempt in range(30):
|
||||
try:
|
||||
run(["docker", "exec", cid, "mongosh", "--quiet", "--eval", "db.adminCommand({ping:1})"], timeout=10)
|
||||
break
|
||||
except RuntimeError:
|
||||
if attempt == 29:
|
||||
raise
|
||||
time.sleep(1)
|
||||
with (folder / "mongo.archive.gz").open("rb") as source:
|
||||
run(["docker", "exec", "-i", cid, "mongorestore", "--archive", "--gzip", "--nsInclude", "guestops.*"], input_file=source)
|
||||
restored = json.loads(run(["docker", "exec", cid, "mongosh", "--quiet", "--nodb", "--eval", 'const c=new Mongo("mongodb://127.0.0.1");' + INVENTORY]))
|
||||
require(restored["collections"] == manifest["inventory"]["collections"], "Restored collection counts or indexes differ.")
|
||||
finally:
|
||||
run(["docker", "rm", "-f", "-v", cid]) # Only the exact container created above and its anonymous volumes.
|
||||
print("Restore drill passed: collection counts, indexes and actual key decryption verified in isolated containers. Production was not restored or modified.")
|
||||
|
||||
|
||||
def main():
|
||||
require(os.name == "posix", "Run deployment operations on Linux.")
|
||||
os.umask(0o077)
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
subs = parser.add_subparsers(dest="command", required=True)
|
||||
check = subs.add_parser("preflight"); check.add_argument("--offline", action="store_true")
|
||||
persistence = subs.add_parser("persistence-drill"); persistence.add_argument("--confirm-restart", action="store_true")
|
||||
save = subs.add_parser("backup"); save.add_argument("--recipient", required=True); save.add_argument("--output", required=True); save.add_argument("--confirm-maintenance", action="store_true")
|
||||
scheduled = subs.add_parser("scheduled-backup"); scheduled.add_argument("--confirm-maintenance", action="store_true")
|
||||
drill = subs.add_parser("restore-drill"); drill.add_argument("backup"); drill.add_argument("--api-image", required=True); drill.add_argument("--mongo-image", default="mongo:8.0")
|
||||
args = parser.parse_args()
|
||||
{"preflight": preflight, "persistence-drill": persistence_drill, "backup": backup, "scheduled-backup": scheduled_backup, "restore-drill": restore_drill}[args.command](args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except Exception as error:
|
||||
# Never include subprocess output, config values or parsed guest data.
|
||||
print(str(error) if isinstance(error, RuntimeError) else "Operation failed (" + type(error).__name__ + "). No sensitive details were logged.", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Create a deterministic GuestOps source package from one committed Git tree."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import gzip
|
||||
import io
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
|
||||
SEMVER = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+")
|
||||
FULL_SHA = re.compile(r"[0-9a-f]{40}")
|
||||
|
||||
|
||||
def git(repository: Path, *arguments: str, binary: bool = False) -> bytes | str:
|
||||
result = subprocess.run(
|
||||
["git", "-C", str(repository), *arguments],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=not binary,
|
||||
)
|
||||
return result.stdout if binary else result.stdout.strip()
|
||||
|
||||
|
||||
def committed_text(repository: Path, commit: str, path: str) -> str:
|
||||
return str(git(repository, "show", f"{commit}:{path}"))
|
||||
|
||||
|
||||
def versions(repository: Path, commit: str) -> tuple[str, str]:
|
||||
props = ET.fromstring(committed_text(repository, commit, "Directory.Build.props"))
|
||||
version_node = props.find(".//Version")
|
||||
if version_node is None or not version_node.text:
|
||||
raise ValueError("The committed Directory.Build.props has no Version element.")
|
||||
dotnet_version = version_node.text.strip()
|
||||
package = json.loads(committed_text(repository, commit, "web/package.json"))
|
||||
web_version = str(package.get("version", ""))
|
||||
return dotnet_version, web_version
|
||||
|
||||
|
||||
def build_package(repository: Path, ref: str, output_directory: Path) -> tuple[Path, dict[str, str]]:
|
||||
repository = repository.resolve()
|
||||
output_directory = output_directory.resolve()
|
||||
if not (repository / ".git").exists():
|
||||
raise ValueError("--repository must be a Git working tree.")
|
||||
|
||||
commit = str(git(repository, "rev-parse", "--verify", f"{ref}^{{commit}}")).lower()
|
||||
if FULL_SHA.fullmatch(commit) is None:
|
||||
raise ValueError("The selected ref did not resolve to a full Git commit SHA.")
|
||||
|
||||
dotnet_version, web_version = versions(repository, commit)
|
||||
if dotnet_version != web_version:
|
||||
raise ValueError(
|
||||
f"Committed release versions differ: .NET={dotnet_version}, web={web_version}."
|
||||
)
|
||||
if SEMVER.fullmatch(dotnet_version) is None:
|
||||
raise ValueError("The committed version must use MAJOR.MINOR.PATCH.")
|
||||
|
||||
prefix = f"guestops_{dotnet_version}/"
|
||||
tar_bytes = bytes(
|
||||
git(
|
||||
repository,
|
||||
"archive",
|
||||
"--format=tar",
|
||||
f"--prefix={prefix}",
|
||||
commit,
|
||||
binary=True,
|
||||
)
|
||||
)
|
||||
compressed = io.BytesIO()
|
||||
with gzip.GzipFile(fileobj=compressed, mode="wb", filename="", mtime=0) as stream:
|
||||
stream.write(tar_bytes)
|
||||
archive_bytes = compressed.getvalue()
|
||||
|
||||
archive = output_directory / f"guestops_{dotnet_version}.tar.gz"
|
||||
if archive.exists():
|
||||
raise ValueError("The output package already exists; published versions are not overwritten.")
|
||||
|
||||
output_directory.mkdir(parents=True, exist_ok=True)
|
||||
archive.write_bytes(archive_bytes)
|
||||
return archive, {"commit": commit, "version": dotnet_version}
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--ref", required=True, help="Exact tag, branch, or full commit to package.")
|
||||
parser.add_argument("--repository", type=Path, default=Path(__file__).resolve().parents[1])
|
||||
parser.add_argument("--output-directory", required=True, type=Path)
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
archive, details = build_package(args.repository, args.ref, args.output_directory)
|
||||
except (OSError, ValueError, ET.ParseError, json.JSONDecodeError, subprocess.SubprocessError) as error:
|
||||
print(f"Source packaging failed: {error}", file=sys.stderr)
|
||||
raise SystemExit(1)
|
||||
print(json.dumps({"archive": str(archive), **details}, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"approvals": {
|
||||
"hotelOwner": {"approvedAt": "2026-01-01T00:00:00Z", "name": "REPLACE"},
|
||||
"technicalOwner": {"approvedAt": "2026-01-01T00:00:00Z", "name": "REPLACE"}
|
||||
},
|
||||
"capacity": {
|
||||
"hostMetricsSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"observedConcurrency": 0,
|
||||
"observedCpuHeadroomPercent": 0,
|
||||
"observedErrorRate": 1,
|
||||
"observedMemoryHeadroomPercent": 0,
|
||||
"observedP95Ms": 0,
|
||||
"reportSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"targetConcurrency": 1,
|
||||
"targetCpuHeadroomPercent": 25,
|
||||
"targetErrorRate": 0,
|
||||
"targetMemoryHeadroomPercent": 25,
|
||||
"targetP95Ms": 0
|
||||
},
|
||||
"decidedAt": "2026-01-01T00:00:00Z",
|
||||
"decision": "pending",
|
||||
"evidence": [],
|
||||
"pilot": {
|
||||
"businessDaysObserved": 0,
|
||||
"hotelsObserved": 0,
|
||||
"recordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"stopConditionsObserved": 1,
|
||||
"unresolvedFindings": 1
|
||||
},
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"schemaVersion": 2,
|
||||
"targetGate": "B"
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-supervised-pilot",
|
||||
"targetGate": "B",
|
||||
"releaseCommit": "0000000000000000000000000000000000000000",
|
||||
"releaseRecordSha256": "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
"environment": "https://sandbox-guestops.example.invalid",
|
||||
"hotelLabel": "approved-pilot-hotel",
|
||||
"hotelCount": 1,
|
||||
"plannedBusinessDays": 5,
|
||||
"owners": {
|
||||
"hotelOwner": "REPLACE HOTEL OWNER",
|
||||
"technicalOwner": "REPLACE TECHNICAL OWNER",
|
||||
"rollbackDecisionMaker": "REPLACE ROLLBACK OWNER"
|
||||
},
|
||||
"startedOn": "2026-10-05",
|
||||
"endedOn": "2026-10-09",
|
||||
"pilotControls": {
|
||||
"pmsWrites": "disabled",
|
||||
"paymentCreation": "disabled",
|
||||
"faqMode": "off",
|
||||
"googleReviewedSending": "accepted"
|
||||
},
|
||||
"dailyReviews": [
|
||||
{"date": "2026-10-05", "status": "not-run", "reviewedBy": "REPLACE", "evidence": []},
|
||||
{"date": "2026-10-06", "status": "not-run", "reviewedBy": "REPLACE", "evidence": []},
|
||||
{"date": "2026-10-07", "status": "not-run", "reviewedBy": "REPLACE", "evidence": []},
|
||||
{"date": "2026-10-08", "status": "not-run", "reviewedBy": "REPLACE", "evidence": []},
|
||||
{"date": "2026-10-09", "status": "not-run", "reviewedBy": "REPLACE", "evidence": []}
|
||||
],
|
||||
"stopConditions": {
|
||||
"tenant-leakage": false,
|
||||
"credential-exposure": false,
|
||||
"data-loss": false,
|
||||
"unapproved-send": false,
|
||||
"duplicate-send": false,
|
||||
"unreconciled-uncertain-send": false,
|
||||
"failed-rollback": false,
|
||||
"monitoring-loss": false
|
||||
},
|
||||
"findings": [],
|
||||
"postPilotState": {
|
||||
"pmsWrites": "disabled",
|
||||
"paymentCreation": "disabled",
|
||||
"faqMode": "off"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,129 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate a GuestOps supervised-pilot go/no-go record."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
|
||||
|
||||
GATE_B = {
|
||||
"release-package", "debian-host", "persistence", "backup-restore", "google-mailbox",
|
||||
"automation", "identity-privacy", "inbox-usability", "capacity",
|
||||
"incident-support", "pilot-findings",
|
||||
}
|
||||
GATE_C = GATE_B | {"pms-provider", "payment-provider"}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
parsed = dt.datetime.fromisoformat(value[:-1] + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
return parsed
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Approval record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 2, "Unsupported approval schema; Gate B 0.2.1 requires schemaVersion 2.")
|
||||
gate = record.get("targetGate")
|
||||
require(gate in ("B", "C"), "targetGate must be B or C.")
|
||||
require(record.get("decision") == "approved", "Only an explicit approved decision passes validation.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None,
|
||||
"releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None,
|
||||
"releaseRecordSha256 must be a SHA-256 digest.")
|
||||
decided = timestamp(record.get("decidedAt"), "decidedAt")
|
||||
|
||||
approvals = record.get("approvals")
|
||||
require(isinstance(approvals, dict) and set(approvals) == {"hotelOwner", "technicalOwner"},
|
||||
"Separate hotelOwner and technicalOwner approvals are required.")
|
||||
approver_names = []
|
||||
for role, approval in approvals.items():
|
||||
name = str(approval.get("name", "")).strip() if isinstance(approval, dict) else ""
|
||||
require(2 <= len(name) <= 120 and "@" not in name,
|
||||
f"{role} approval requires a named owner without an email address.")
|
||||
approver_names.append(name.casefold())
|
||||
require(timestamp(approval.get("approvedAt"), f"{role}.approvedAt") <= decided,
|
||||
f"{role} approval cannot occur after the decision.")
|
||||
require(len(set(approver_names)) == 2, "hotelOwner and technicalOwner must be different people.")
|
||||
|
||||
evidence = record.get("evidence")
|
||||
require(isinstance(evidence, list), "evidence must be a list.")
|
||||
ids = [item.get("id") for item in evidence if isinstance(item, dict)]
|
||||
required = GATE_C if gate == "C" else GATE_B
|
||||
require(len(ids) == len(evidence) and len(ids) == len(set(ids)) and set(ids) == required,
|
||||
f"Gate {gate} requires the exact evidence set.")
|
||||
for item in evidence:
|
||||
item_id = item["id"]
|
||||
status = item.get("status")
|
||||
require(status in ("pass", "contained"), f"Evidence {item_id} must pass or have approved containment.")
|
||||
references = item.get("references")
|
||||
require(isinstance(references, list) and 1 <= len(references) <= 10 and all(isinstance(value, str) and 3 <= len(value) <= 200 and "@" not in value for value in references),
|
||||
f"Evidence {item_id} requires safe opaque references without email addresses.")
|
||||
if status == "contained":
|
||||
containment = item.get("containment")
|
||||
require(isinstance(containment, dict), f"Evidence {item_id} requires containment details.")
|
||||
require(2 <= len(str(containment.get("owner", ""))) <= 120, f"Evidence {item_id} containment requires an owner.")
|
||||
require(timestamp(containment.get("expiresAt"), f"{item_id}.containment.expiresAt") > decided,
|
||||
f"Evidence {item_id} containment must expire after the decision.")
|
||||
require(5 <= len(str(containment.get("rollbackTrigger", ""))) <= 300,
|
||||
f"Evidence {item_id} containment requires a rollback trigger.")
|
||||
|
||||
capacity = record.get("capacity")
|
||||
require(isinstance(capacity, dict), "Capacity thresholds and observations are required.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(capacity.get("reportSha256", ""))) is not None,
|
||||
"capacity.reportSha256 must identify the retained probe report.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(capacity.get("hostMetricsSha256", ""))) is not None,
|
||||
"capacity.hostMetricsSha256 must identify the retained host metrics.")
|
||||
for observed, target in (("observedP95Ms", "targetP95Ms"), ("observedErrorRate", "targetErrorRate")):
|
||||
values = (capacity.get(observed), capacity.get(target))
|
||||
require(all(isinstance(value, (int, float)) and not isinstance(value, bool) for value in values)
|
||||
and 0 <= capacity[observed] <= capacity[target],
|
||||
f"Capacity {observed} must be within its approved {target}.")
|
||||
require(capacity["targetP95Ms"] > 0, "Capacity targetP95Ms must be positive.")
|
||||
require(capacity["targetErrorRate"] <= 1, "Capacity targetErrorRate must be a ratio no greater than 1.")
|
||||
concurrency = (capacity.get("observedConcurrency"), capacity.get("targetConcurrency"))
|
||||
require(all(isinstance(value, int) and not isinstance(value, bool) for value in concurrency)
|
||||
and capacity["observedConcurrency"] >= capacity["targetConcurrency"] > 0,
|
||||
"Observed concurrency must meet the approved positive target.")
|
||||
for resource in ("Cpu", "Memory"):
|
||||
target = capacity.get(f"target{resource}HeadroomPercent")
|
||||
observed = capacity.get(f"observed{resource}HeadroomPercent")
|
||||
require(all(isinstance(value, (int, float)) and not isinstance(value, bool) for value in (target, observed))
|
||||
and 25 <= target <= observed <= 100,
|
||||
f"Observed {resource.lower()} headroom must meet the approved target of at least 25 percent.")
|
||||
|
||||
pilot = record.get("pilot")
|
||||
require(isinstance(pilot, dict), "A supervised pilot summary is required.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(pilot.get("recordSha256", ""))) is not None,
|
||||
"pilot.recordSha256 must identify the retained pilot run record.")
|
||||
require(pilot.get("businessDaysObserved") == 5, "The pilot must cover exactly five business days.")
|
||||
require(pilot.get("hotelsObserved") == 1, "The Gate B pilot must cover exactly one hotel.")
|
||||
require(pilot.get("stopConditionsObserved") == 0, "A pilot with a stop condition cannot be approved.")
|
||||
require(pilot.get("unresolvedFindings") == 0, "All pilot findings must be resolved or explicitly contained.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print("Pilot approval record is structurally complete and approved. This validates the record, not its restricted evidence.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Pilot approval rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -0,0 +1,163 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate a restricted five-business-day GuestOps pilot run record."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime as dt
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
from urllib.parse import urlparse
|
||||
|
||||
|
||||
STOP_CONDITIONS = {
|
||||
"tenant-leakage",
|
||||
"credential-exposure",
|
||||
"data-loss",
|
||||
"unapproved-send",
|
||||
"duplicate-send",
|
||||
"unreconciled-uncertain-send",
|
||||
"failed-rollback",
|
||||
"monitoring-loss",
|
||||
}
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if not condition:
|
||||
raise ValueError(message)
|
||||
|
||||
|
||||
def date_value(value: object, field: str) -> dt.date:
|
||||
require(isinstance(value, str), f"{field} must be an ISO date.")
|
||||
try:
|
||||
return dt.date.fromisoformat(value)
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} must be an ISO date.") from error
|
||||
|
||||
|
||||
def timestamp(value: object, field: str) -> dt.datetime:
|
||||
require(isinstance(value, str) and value.endswith("Z"), f"{field} must be a UTC timestamp ending in Z.")
|
||||
try:
|
||||
return dt.datetime.fromisoformat(value.removesuffix("Z") + "+00:00")
|
||||
except ValueError as error:
|
||||
raise ValueError(f"{field} is not a valid timestamp.") from error
|
||||
|
||||
|
||||
def safe_name(value: object, field: str) -> str:
|
||||
name = str(value or "").strip()
|
||||
require(2 <= len(name) <= 120 and "@" not in name, f"{field} requires a name without an email address.")
|
||||
return name
|
||||
|
||||
|
||||
def references(value: object, field: str) -> None:
|
||||
require(isinstance(value, list) and 1 <= len(value) <= 10 and all(
|
||||
isinstance(item, str) and 3 <= len(item) <= 200 and "@" not in item for item in value
|
||||
), f"{field} requires one to ten safe opaque references without email addresses.")
|
||||
|
||||
|
||||
def business_dates(start: dt.date, end: dt.date) -> list[dt.date]:
|
||||
days = []
|
||||
current = start
|
||||
while current <= end:
|
||||
if current.weekday() < 5:
|
||||
days.append(current)
|
||||
current += dt.timedelta(days=1)
|
||||
return days
|
||||
|
||||
|
||||
def validate(record: object) -> None:
|
||||
require(isinstance(record, dict), "Pilot run record must be a JSON object.")
|
||||
require(record.get("schemaVersion") == 1, "Unsupported pilot run schema.")
|
||||
require(record.get("system") == "guestops-supervised-pilot", "Pilot run system must be guestops-supervised-pilot.")
|
||||
require(record.get("targetGate") == "B", "This pilot run record is restricted to Gate B.")
|
||||
require(re.fullmatch(r"[0-9a-f]{40}", str(record.get("releaseCommit", ""))) is not None,
|
||||
"releaseCommit must be a full lowercase Git SHA.")
|
||||
require(re.fullmatch(r"[0-9a-f]{64}", str(record.get("releaseRecordSha256", ""))) is not None,
|
||||
"releaseRecordSha256 must be a SHA-256 digest.")
|
||||
|
||||
origin = urlparse(str(record.get("environment", "")))
|
||||
require(origin.scheme == "https" and origin.hostname and origin.path in ("", "/") and not origin.query
|
||||
and not origin.fragment and origin.username is None and origin.password is None,
|
||||
"environment must be an HTTPS origin without credentials, path, query or fragment.")
|
||||
label = str(record.get("hotelLabel", "")).strip()
|
||||
require(3 <= len(label) <= 80 and "@" not in label, "hotelLabel must be a non-email alias.")
|
||||
require(record.get("hotelCount") == 1, "Gate B pilot must contain exactly one hotel.")
|
||||
require(record.get("plannedBusinessDays") == 5, "Gate B pilot must require five business days.")
|
||||
|
||||
owners = record.get("owners")
|
||||
require(isinstance(owners, dict) and set(owners) == {"hotelOwner", "technicalOwner", "rollbackDecisionMaker"},
|
||||
"owners must contain hotelOwner, technicalOwner and rollbackDecisionMaker.")
|
||||
names = {role: safe_name(value, f"owners.{role}") for role, value in owners.items()}
|
||||
require(names["hotelOwner"].casefold() != names["technicalOwner"].casefold(),
|
||||
"hotelOwner and technicalOwner must be different people.")
|
||||
|
||||
start = date_value(record.get("startedOn"), "startedOn")
|
||||
end = date_value(record.get("endedOn"), "endedOn")
|
||||
expected_days = business_dates(start, end)
|
||||
require(len(expected_days) == 5, "Pilot window must contain exactly five business days.")
|
||||
reviews = record.get("dailyReviews")
|
||||
require(isinstance(reviews, list) and len(reviews) == 5, "Exactly five daily reviews are required.")
|
||||
review_dates = []
|
||||
for index, review in enumerate(reviews):
|
||||
require(isinstance(review, dict), f"dailyReviews[{index}] must be an object.")
|
||||
review_date = date_value(review.get("date"), f"dailyReviews[{index}].date")
|
||||
review_dates.append(review_date)
|
||||
require(review.get("status") == "pass", f"Daily review {review_date} has not passed.")
|
||||
safe_name(review.get("reviewedBy"), f"dailyReviews[{index}].reviewedBy")
|
||||
references(review.get("evidence"), f"dailyReviews[{index}].evidence")
|
||||
require(review_dates == expected_days, "Daily reviews must cover each business day in chronological order.")
|
||||
|
||||
controls = record.get("pilotControls")
|
||||
require(controls == {"pmsWrites": "disabled", "paymentCreation": "disabled", "faqMode": "off",
|
||||
"googleReviewedSending": "accepted"},
|
||||
"Pilot controls require accepted reviewed Google sending with PMS, payments and FAQ live mode disabled.")
|
||||
stop_conditions = record.get("stopConditions")
|
||||
require(isinstance(stop_conditions, dict) and set(stop_conditions) == STOP_CONDITIONS,
|
||||
"stopConditions must contain the exact Gate B stop-condition set.")
|
||||
require(all(value is False for value in stop_conditions.values()),
|
||||
"A pilot with an observed stop condition cannot pass.")
|
||||
|
||||
findings = record.get("findings")
|
||||
require(isinstance(findings, list), "findings must be a list, including an empty list when none were found.")
|
||||
finding_ids = []
|
||||
for finding in findings:
|
||||
require(isinstance(finding, dict), "Each finding must be an object.")
|
||||
finding_id = str(finding.get("id", ""))
|
||||
require(re.fullmatch(r"[a-z0-9][a-z0-9-]{2,79}", finding_id) is not None, "Finding IDs must be safe opaque identifiers.")
|
||||
finding_ids.append(finding_id)
|
||||
severity = finding.get("severity")
|
||||
disposition = finding.get("disposition")
|
||||
require(severity in ("critical", "high", "medium", "low"), f"Finding {finding_id} has an invalid severity.")
|
||||
require(disposition in ("resolved", "contained"), f"Finding {finding_id} must be resolved or contained.")
|
||||
references(finding.get("evidence"), f"Finding {finding_id} evidence")
|
||||
require(not (severity in ("critical", "high") and disposition == "contained"),
|
||||
f"Finding {finding_id} is too severe for containment.")
|
||||
if disposition == "contained":
|
||||
containment = finding.get("containment")
|
||||
require(isinstance(containment, dict), f"Finding {finding_id} requires containment details.")
|
||||
safe_name(containment.get("owner"), f"Finding {finding_id} containment owner")
|
||||
require(timestamp(containment.get("expiresAt"), f"Finding {finding_id}.containment.expiresAt").date() > end,
|
||||
f"Finding {finding_id} containment must expire after the pilot.")
|
||||
require(5 <= len(str(containment.get("rollbackTrigger", ""))) <= 300,
|
||||
f"Finding {finding_id} containment requires a rollback trigger.")
|
||||
require(len(finding_ids) == len(set(finding_ids)), "Finding IDs must be unique.")
|
||||
|
||||
require(record.get("postPilotState") == {"pmsWrites": "disabled", "paymentCreation": "disabled", "faqMode": "off"},
|
||||
"Pilot must end with PMS writes, payment creation and FAQ live mode disabled.")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("record", type=Path)
|
||||
args = parser.parse_args()
|
||||
validate(json.loads(args.record.read_text(encoding="utf-8")))
|
||||
print("Supervised pilot record is structurally complete: five business days passed without a stop condition. This validates the record, not its restricted evidence.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
try:
|
||||
main()
|
||||
except (OSError, ValueError, json.JSONDecodeError) as error:
|
||||
print(f"Supervised pilot record rejected: {error}", file=__import__("sys").stderr)
|
||||
raise SystemExit(1)
|
||||
@@ -1,76 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Create deterministic evidence for a reviewed GuestOps image archive."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def project_versions() -> tuple[str, str]:
|
||||
props = (ROOT / "Directory.Build.props").read_text(encoding="utf-8")
|
||||
match = re.search(r"<Version>([^<]+)</Version>", props)
|
||||
if match is None:
|
||||
raise ValueError("Directory.Build.props does not contain a Version element")
|
||||
package = json.loads((ROOT / "web" / "package.json").read_text(encoding="utf-8"))
|
||||
return match.group(1), str(package["version"])
|
||||
|
||||
|
||||
def sha256(path: Path) -> str:
|
||||
digest = hashlib.sha256()
|
||||
with path.open("rb") as stream:
|
||||
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
|
||||
digest.update(chunk)
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--artifact", required=True, type=Path)
|
||||
parser.add_argument("--commit", required=True)
|
||||
parser.add_argument("--api-image", required=True)
|
||||
parser.add_argument("--api-id", required=True)
|
||||
parser.add_argument("--worker-image", required=True)
|
||||
parser.add_argument("--worker-id", required=True)
|
||||
parser.add_argument("--output", required=True, type=Path)
|
||||
args = parser.parse_args()
|
||||
|
||||
commit = args.commit.lower()
|
||||
if re.fullmatch(r"[0-9a-f]{40}", commit) is None:
|
||||
parser.error("--commit must be a full 40-character Git SHA")
|
||||
if not args.artifact.is_file():
|
||||
parser.error("--artifact must name an existing file")
|
||||
|
||||
dotnet_version, web_version = project_versions()
|
||||
if dotnet_version != web_version:
|
||||
parser.error(
|
||||
f"release versions differ: .NET={dotnet_version}, web={web_version}"
|
||||
)
|
||||
|
||||
record = {
|
||||
"artifact": {
|
||||
"name": args.artifact.name,
|
||||
"sha256": sha256(args.artifact),
|
||||
"size": args.artifact.stat().st_size,
|
||||
},
|
||||
"commit": commit,
|
||||
"images": {
|
||||
"api": {"id": args.api_id, "reference": args.api_image},
|
||||
"worker": {"id": args.worker_id, "reference": args.worker_image},
|
||||
},
|
||||
"schemaVersion": 1,
|
||||
"version": dotnet_version,
|
||||
}
|
||||
args.output.write_text(
|
||||
json.dumps(record, indent=2, sort_keys=True) + "\n", encoding="utf-8"
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,21 +0,0 @@
|
||||
[Unit]
|
||||
Description=GuestOps encrypted maintenance backup
|
||||
Requires=docker.service
|
||||
After=docker.service
|
||||
ConditionPathIsDirectory=/srv/guestops
|
||||
ConditionPathIsDirectory=/var/backups/guestops
|
||||
ConditionPathIsDirectory=/var/lib/guestops-backup/gnupg
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
WorkingDirectory=/srv/guestops
|
||||
EnvironmentFile=/etc/guestops/backup.env
|
||||
Environment=GNUPGHOME=/var/lib/guestops-backup/gnupg
|
||||
UMask=0077
|
||||
ExecStart=/usr/bin/python3 /srv/guestops/deploy/ops.py scheduled-backup --confirm-maintenance
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectHome=true
|
||||
ProtectSystem=full
|
||||
ReadWritePaths=/var/backups/guestops /var/lib/guestops-backup/gnupg
|
||||
TimeoutStartSec=45min
|
||||
@@ -1,11 +0,0 @@
|
||||
[Unit]
|
||||
Description=Run the GuestOps encrypted backup each day
|
||||
|
||||
[Timer]
|
||||
OnCalendar=*-*-* 02:17:00 UTC
|
||||
RandomizedDelaySec=30min
|
||||
Persistent=true
|
||||
Unit=guestops-backup.service
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
+1
-1
@@ -27,7 +27,7 @@ unset RECOVERY_EMAIL
|
||||
|
||||
The command uses the configured database, generates a private link, prints it to the administrator's terminal and exits. Share it only with the verified owner. Do not paste it into tickets, chat logs, build logs or source control; avoid running this command in a recorded terminal. It expires in 30 minutes and can be consumed once. Running the command again invalidates the earlier link. Bootstrap remains a create-only command and cannot reset passwords.
|
||||
|
||||
`PublicUrl` must be the configured HTTPS origin, normally `https://sandbox-guestops.futuresens.co.uk`. Request Host headers never determine recovery-link origins. The Development-only preview uses `http://127.0.0.1:5173`.
|
||||
`PublicUrl` must be the configured HTTPS origin, such as `https://guestops-sandbox.futuresens.co.uk`. Request Host headers never determine recovery-link origins. The Development-only preview uses `http://127.0.0.1:5173`.
|
||||
|
||||
## Storage and session behavior
|
||||
|
||||
|
||||
+49
-73
@@ -1,89 +1,65 @@
|
||||
# Debian sandbox deployment
|
||||
# GuestOps deployment
|
||||
|
||||
Target: `https://sandbox-guestops.futuresens.co.uk`. These are reviewable deployment instructions; creating these files does not deploy or change the server.
|
||||
GuestOps is deployed by the central Futuresens Ansible repository. Sandbox is
|
||||
`https://guestops-sandbox.futuresens.co.uk` and production is
|
||||
`https://guestops.futuresens.co.uk`.
|
||||
|
||||
## 1. Prepare the host
|
||||
## Prepare a version
|
||||
|
||||
Check the existing Nginx, Docker, MongoDB and firewall configuration before installation. Preserve existing services. The provided Compose file creates a dedicated MongoDB instance for GuestOps with no host port; if MongoDB already exists on the host, use a reviewed private connection and application-scoped user instead of starting a conflicting instance.
|
||||
|
||||
Install Docker Engine/Compose and Nginx using their official Debian instructions. Keep SSH access unchanged. Only HTTPS/HTTP for this hostname need public access; port 8080 is loopback-only and MongoDB has no published port.
|
||||
|
||||
Clone the private repository using an authorized GitHub account. Place the checkout in a dedicated application directory. Copy `.env.example` to `.env`, set permissions to 600, and fill two different MongoDB passwords generated with `openssl rand -hex 32`. Use hex values so they are safe in the MongoDB URI. Store real values only on the server or in its secret-management system.
|
||||
|
||||
The MongoDB initialization script runs only on a new volume. Changing `.env` later does not rotate existing database users. Rotate those credentials through MongoDB administration and update application configuration together.
|
||||
|
||||
## 2. Load reviewed application images
|
||||
|
||||
CI builds API and worker images and packages them in a `guestops-linux-*` artifact. Download the successful artifact for the desired commit and transfer it to the sandbox through your normal authorized deployment process.
|
||||
The .NET version in `Directory.Build.props` and the frontend version in
|
||||
`web/package.json` must match. Test the committed revision, then package it:
|
||||
|
||||
```sh
|
||||
docker load -i guestops-images.tar.gz
|
||||
dotnet run --project tests/GuestOps.Tests
|
||||
python3 -m unittest discover -s tests -p "test_*.py"
|
||||
cd web && npm ci && npm run build && cd ..
|
||||
|
||||
python3 deploy/package_source.py \
|
||||
--ref FULL_COMMIT_OR_TAG \
|
||||
--output-directory ../ansible/playbooks/files/guestops
|
||||
```
|
||||
|
||||
Set `GUESTOPS_API_IMAGE=guestops-api:<commit-sha>` and `GUESTOPS_WORKER_IMAGE=guestops-worker:<commit-sha>` in `.env` using that exact build's SHA. Then run:
|
||||
For version `0.2.1`, this creates `guestops_0.2.1.tar.gz`. Published version
|
||||
files are immutable; change the application version before making another
|
||||
archive.
|
||||
|
||||
## Configure Ansible
|
||||
|
||||
The server group needs only the application switch, version and subdomain:
|
||||
|
||||
```yaml
|
||||
hasguestops: true
|
||||
guestopsversion: "0.2.1"
|
||||
guestopssubdomain: "guestops-sandbox"
|
||||
```
|
||||
|
||||
Production uses `guestopssubdomain: "guestops"`. Runtime credentials and the
|
||||
MongoDB connection string belong in encrypted Ansible Vault data. The MongoDB
|
||||
URI must use a least-privilege `guestops` database user and an address reachable
|
||||
from Docker containers.
|
||||
|
||||
## Deploy
|
||||
|
||||
Deploy sandbox first:
|
||||
|
||||
```sh
|
||||
docker compose config --quiet
|
||||
docker compose up -d --no-build
|
||||
curl --fail http://127.0.0.1:8080/health
|
||||
ansible-playbook playbooks/guestops.yml -K --ask-vault-pass \
|
||||
--extra-vars "thehost=sandbox"
|
||||
```
|
||||
|
||||
Do not run `docker compose config` without `--quiet` in shared logs: expanded configuration contains secrets. Local image builds are available with Compose for development, but CI builds avoid consuming sandbox resources.
|
||||
|
||||
## 3. Provision the first hotel owner
|
||||
|
||||
The API has an administrative bootstrap command. It creates one hotel and one owner, refuses an existing email address, and does not reset passwords. Run it with environment variables passed from a private terminal; do not put the password directly in shell history or a repository file.
|
||||
After acceptance, deploy the same versioned archive to production:
|
||||
|
||||
```sh
|
||||
read -r -p 'Owner email: ' BOOTSTRAP_EMAIL
|
||||
read -r -p 'Hotel name: ' BOOTSTRAP_HOTEL
|
||||
read -r -s -p 'Owner password (14+ characters): ' BOOTSTRAP_PASSWORD
|
||||
printf '\n'
|
||||
export BOOTSTRAP_EMAIL BOOTSTRAP_HOTEL BOOTSTRAP_PASSWORD
|
||||
docker compose run --rm --no-deps -e BOOTSTRAP_EMAIL -e BOOTSTRAP_HOTEL -e BOOTSTRAP_PASSWORD api --bootstrap
|
||||
unset BOOTSTRAP_EMAIL BOOTSTRAP_HOTEL BOOTSTRAP_PASSWORD
|
||||
ansible-playbook playbooks/guestops.yml -K --ask-vault-pass \
|
||||
--extra-vars "thehost=dbserver"
|
||||
```
|
||||
|
||||
There is no development/demo account in production. Owners can issue staff invitation and assisted recovery links through Team; see [account setup](accounts.md). Passwords must be 14–128 characters. Public self-registration is not enabled.
|
||||
The playbook stops the existing Compose project without deleting volumes,
|
||||
replaces `/srv/guestops`, renders private configuration, builds and starts the
|
||||
API and worker, configures Nginx, and verifies local and public readiness. Port
|
||||
8080 remains loopback-only and the `guestops_app-keys` volume survives
|
||||
redeployment.
|
||||
|
||||
## 4. Configure HTTPS
|
||||
|
||||
Verify the hostname's DNS resolves to this server. Obtain a valid certificate for it using your existing ACME/Certbot process. The Nginx example expects a Let's Encrypt certificate. For first issuance, configure the port-80 ACME location before enabling the port-443 block; do not point Nginx at missing certificate files.
|
||||
|
||||
Merge `deploy/nginx.conf` into the existing host configuration, check with `nginx -t`, then reload Nginx. Confirm HTTPS serves the login page. API cookies are always Secure outside preview mode; logging in through plain HTTP is intentionally unsupported.
|
||||
|
||||
Compose reserves the private bridge `172.30.87.0/24`, with gateway `172.30.87.1`. The API trusts the host gateway's `X-Forwarded-Proto` header so Nginx's HTTPS connections receive secure session and CSRF cookies. Check for an existing network using that range. If it conflicts, set both `GUESTOPS_SUBNET` and `GUESTOPS_GATEWAY` in `.env` to a free matching subnet and gateway. Do not replace this with unrestricted forwarded-header trust.
|
||||
|
||||
The login rate limiter uses the client address forwarded by the explicitly configured host proxy (10 attempts per client address per minute). ASP.NET accepts one forwarding hop only from `Proxy__KnownAddress`; arbitrary client-supplied forwarding headers are not trusted. Keep the API port loopback-only and update the known address together with any reviewed Compose subnet change.
|
||||
|
||||
## 5. Configure Google
|
||||
|
||||
Create or select your Google Cloud project, enable Gmail API, and configure a Web application OAuth client. Register this exact redirect URI:
|
||||
|
||||
`https://sandbox-guestops.futuresens.co.uk/api/integrations/google/callback`
|
||||
|
||||
Configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the server's `.env` and recreate the API/worker services. Sign in as hotel owner, open Settings and connect a dedicated test mailbox. By default the only requested Gmail scope is `gmail.readonly`. Optional staff-approved sending adds `gmail.send` after server configuration and reconnection; see [AI drafts and reply delivery](replies.md).
|
||||
|
||||
OAuth requests expire after ten minutes, are bound to the signed-in user and hotel, and can be consumed once. Refresh tokens are protected with ASP.NET Data Protection. API and worker share the private persistent key volume; back it up securely with the database. Losing it prevents existing mailbox tokens and sessions from being decrypted. Filesystem protection for the key volume is required; it is separate from MongoDB and must not be publicly served or committed.
|
||||
|
||||
A multi-hotel production launch using Gmail restricted scopes requires planning for Google's verification/security-assessment requirements. This implementation does not bypass those requirements. See [Google restricted-scope verification](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification).
|
||||
|
||||
## 6. Acceptance and rollback
|
||||
|
||||
Verify separate hotels cannot read or edit each other's records; save and reload settings; restart services and confirm persistence; import test messages twice without duplicates; check the worker resumes a paginated import; confirm no mail is sent without explicit staff approval and that default-disabled sending remains blocked. Review the activity log and Google account used by the connection.
|
||||
|
||||
Keep reviewed image IDs and release images for rollback and backups of both MongoDB and the key volume. Do not remove named volumes to fix application errors. The initial release has no automatic schema migration that destroys data. Use the [operational preflight, encrypted backup and isolated restore drill](operations.md), and establish retention and off-server copies before importing real guest data. `/health/ready` checks database reachability; the owner's Workspace health page also reports worker heartbeat and mailbox/reply exceptions.
|
||||
|
||||
Before accepting the host, run the confirmation-gated persistence drill during an announced maintenance window:
|
||||
|
||||
```sh
|
||||
python3 deploy/ops.py preflight
|
||||
python3 deploy/ops.py persistence-drill --confirm-restart
|
||||
python3 deploy/ops.py preflight
|
||||
```
|
||||
|
||||
The drill restarts MongoDB, API and worker, then force-recreates the stateless application containers using the already selected images. It verifies that the resolved database and key volumes keep the same identities, MongoDB collection counts and indexes remain unchanged, a value protected before restart can still be decrypted, and loopback readiness recovers. It does not alter provider feature flags, upgrade images, validate public TLS, or replace the separate backup/restore drill.
|
||||
|
||||
Record the host, operator, start/end time, release record checksum, resolved image IDs, preflight output and drill result in the deployment acceptance record. Also verify Docker starts at boot and perform a controlled Debian reboot before Gate A approval. After reboot, run the online preflight and inspect the Workspace health page; do not infer worker health solely from API readiness.
|
||||
|
||||
The supplied Docker `json-file` logs are size-capped to protect the small pilot disk, but container recreation removes that container's local log history. Before host acceptance, route GuestOps and Nginx logs to the site's durable restricted logging system, or use a reviewed Docker logging override backed by persistent systemd journal storage. Prove that operators can retrieve pre-recreation logs without exposing request credentials or OAuth callback query strings. Central retention and alerting are completed under milestone 11.
|
||||
To roll back, select an older retained `guestopsversion` in group vars and run
|
||||
the same playbook. MongoDB backup, Filebeat, certificates, and host monitoring
|
||||
are provided by the existing central infrastructure.
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# Desktop-parity acceptance
|
||||
|
||||
Run this supervised exercise against the exact HTTPS sandbox release using synthetic conversations and accounts. Compare the web workflow with the reviewed desktop baseline `18b983bf402ecdded6430fd40bc4d3320587595a`; this is workflow and safety parity, not a claim that the interfaces are visually identical.
|
||||
|
||||
Use the browser and workstation configuration intended for the pilot. Record its full browser version, operating system, viewport, scale factor and the hotel's saved IANA timezone. Keep screenshots and recordings in the restricted acceptance store because UI evidence may contain message text or account details. The operator and independent reviewer must be different people.
|
||||
|
||||
## Required scenarios
|
||||
|
||||
| Record ID | Exercise | Passing result |
|
||||
| --- | --- | --- |
|
||||
| `inbox-core-workflow` | Open a synthetic conversation, create and save a draft, use an approved answer, change status and reload. | The same conversation and saved state remain available, and no action sends mail. |
|
||||
| `pagination-beyond-500` | Seed more than 500 tenant-scoped conversations and load successive 50-item pages while another conversation is inserted. | Every original record can be reached once without cross-hotel records, duplicates or skipped records. |
|
||||
| `draft-conversation-guard` | Edit without saving, select another conversation, reject the discard prompt, then accept it. | Rejection retains the draft and selection; acceptance changes conversation and discards only the unsaved edit. |
|
||||
| `draft-filter-search-guard` | Repeat the reject/accept checks while changing status filters and search text. | Rejection preserves the edit and prior view; acceptance applies the requested view change. |
|
||||
| `draft-route-history-reload-guard` | With an unsaved edit, try sidebar navigation, browser Back/Forward and reload or tab close. | In-app navigation and browser history require confirmation; reload or close raises the browser's native unsaved-change warning. |
|
||||
| `timezone-and-dst` | Choose a timezone different from the workstation and inspect inbox, activity, health, mailbox, automation, PMS, payment and team-link times, including values around a daylight-saving transition. | Every operational timestamp follows the saved hotel timezone and represents the same instant consistently. |
|
||||
| `role-and-control-parity` | Exercise owner and staff accounts with provider writes and automation disabled. | Staff cannot access owner functions, and neither role can bypass feature, review or provider controls. |
|
||||
| `desktop-layout` | Complete the workflow at the recorded desktop viewport and scale, including keyboard navigation and browser zoom checks agreed for the pilot. | Primary controls remain visible and usable without clipped dialogs, overlapping content or an inaccessible action. |
|
||||
|
||||
## Record and validation
|
||||
|
||||
Copy `deploy/desktop-acceptance.example.json` into the restricted acceptance store. Replace its release identifiers, environment, workstation details, timestamps and people. Mark each scenario `pass` only after the independent reviewer has checked its evidence. The example is intentionally invalid while scenarios are `not-run`.
|
||||
|
||||
```sh
|
||||
python3 deploy/desktop_acceptance.py /secure/acceptance/desktop-acceptance.json
|
||||
```
|
||||
|
||||
The validator checks structure, release and baseline binding, desktop dimensions, independent review, complete passing scenarios and opaque evidence references. It cannot inspect screenshots or prove browser behavior. Retain the validated record and its checksum, then reference it from `inbox-usability` in the pilot approval record.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Gate B automation, identity and privacy acceptance
|
||||
|
||||
Run these reviews against the exact `0.2.1` candidate on the accepted HTTPS sandbox. Keep guest data, staff addresses, provider agreements, screenshots and raw reports in the restricted evidence store. Repository records contain opaque references only.
|
||||
|
||||
## Knowledge, AI and FAQ automation
|
||||
|
||||
Curate representative hotel-specific positive and negative FAQ cases. Use the bounded no-send evaluation and require zero false positives and zero false negatives. Review AI suggestions separately; escalations are valid outcomes, but no unsafe or unsupported draft may be approved. Exercise the FAQ stop control, train every pilot staff member, and name monitoring and rollback owners. Finish with FAQ mode off and PMS/payment writes disabled.
|
||||
|
||||
Copy `deploy/automation-acceptance.example.json`, complete the record, independently review its evidence, and run:
|
||||
|
||||
```sh
|
||||
python3 deploy/automation_acceptance.py /secure/acceptance/automation-acceptance.json
|
||||
```
|
||||
|
||||
## Identity, preferences and privacy
|
||||
|
||||
The hotel and privacy owners must approve explicit retention periods for conversations, audit history, backups and accounts. Name privacy, deletion and legal-hold owners and retain the deletion and hold procedures. Review Google processing for the mailbox pilot; either accept OpenAI processing or keep AI drafts disabled.
|
||||
|
||||
Exercise owner/staff boundaries, invitation and recovery lifecycle, trusted-proxy throttling, session invalidation, every owner-controlled preference, data inventory, deletion/retention handling, backup retention and audit evidence. Explicitly review the known absence of MFA, granular roles and self-service recovery; any accepted containment belongs in the final pilot decision.
|
||||
|
||||
Copy `deploy/identity-privacy-acceptance.example.json`, complete the record, independently review its evidence, and run:
|
||||
|
||||
```sh
|
||||
python3 deploy/identity_privacy_acceptance.py /secure/acceptance/identity-privacy-acceptance.json
|
||||
```
|
||||
|
||||
These validators check completeness and release binding. They do not make legal decisions, inspect provider agreements or implement deletion on behalf of the operator. Reference the retained records and validator output from `automation` and `identity-privacy` in the final pilot approval.
|
||||
@@ -6,7 +6,7 @@ Keep screenshots, Gmail message source, provider console records and request dia
|
||||
|
||||
## Preparation and stop conditions
|
||||
|
||||
Record the release commit, release-record SHA-256, image IDs, environment, operator, approver and maintenance window. Use two dedicated Google test accounts so the different-account rejection can be exercised without a personal account. Send only clearly synthetic messages between controlled recipients.
|
||||
Record the deployed GuestOps version, environment, operator, approver and maintenance window. Use two dedicated Google test accounts so the different-account rejection can be exercised without a personal account. Send only clearly synthetic messages between controlled recipients.
|
||||
|
||||
Start with AI drafts, staff sending, FAQ live mode, PMS writes and payment creation disabled. Confirm the OAuth redirect URI exactly matches the HTTPS sandbox. Stop immediately if a mailbox appears under the wrong hotel, a recipient differs from the review screen, an unapproved message is sent, a duplicate is observed, provider output exposes credentials, or an uncertain outcome is about to be blindly retried. Preserve evidence and follow the incident process.
|
||||
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# Incident and rollback exercise
|
||||
|
||||
Run this exercise on the approved sandbox release with synthetic records only. Agree detection, containment and recovery targets before starting. The operator, incident commander and independent reviewer must be different people. Keep actual guest addresses, credentials, tokens, provider payloads and raw incident evidence in the restricted acceptance store.
|
||||
|
||||
## Gate B scenarios
|
||||
|
||||
| Record ID | Exercise | Passing evidence |
|
||||
| --- | --- | --- |
|
||||
| `alert-and-escalate` | Introduce an approved synthetic failure and use normal monitoring and support routes. | The alert is detected, the incident commander is engaged and timestamps meet the agreed detection target. |
|
||||
| `disable-worker-writes` | Use the documented controls to stop worker-driven provider writes and FAQ automation. | Pending work does not reach a provider, controls remain effective across a worker restart and staff can identify the safe state. |
|
||||
| `google-uncertain-send` | Simulate an interrupted or ambiguous Gmail submission. | Staff do not resend blindly, reconcile using the stable message ID and retain the disposition. |
|
||||
| `restore-readiness` | Use the isolated restore procedure and inspect provider-facing records before enabling workers. | The restored system becomes ready, older approvals remain held and external effects are reconciled. |
|
||||
| `image-rollback` | Deploy the retained prior image IDs using the rollback procedure without replacing MongoDB or key volumes. | The recorded images run, readiness and read-only smoke checks pass and persistent state remains available. |
|
||||
| `controlled-recovery` | Recover the approved release after containment. | Monitoring is healthy, held operations are dispositioned and the exercise ends with writes disabled and FAQ mode off. |
|
||||
|
||||
For Gate C, also exercise `pms-ambiguous-write` and `payment-ambiguous-create`. In both cases, lose or interrupt the synthetic provider response and prove the operation is reconciled read-only without creating a replacement request or replaying the approval.
|
||||
|
||||
## Record and validation
|
||||
|
||||
Copy `deploy/incident-exercise.example.json` into the restricted acceptance store and record the deployed GuestOps version and environment. Replace the example timestamps, people, targets and evidence references. Change a scenario to `pass` only after its evidence has been independently reviewed. The example is intentionally invalid because its scenarios are `not-run`.
|
||||
|
||||
For a Gate C exercise, set `targetGate` to `C` and add the PMS and payment scenario records. Validate the completed record with:
|
||||
|
||||
```sh
|
||||
python3 deploy/incident_exercise.py /secure/acceptance/incident-exercise.json
|
||||
```
|
||||
|
||||
The validator checks record completeness, release binding, scenario coverage, independent roles, timing targets and the safe final state. It does not inspect the referenced evidence, create an incident response capability or authorize a pilot. Retain its output and the record checksum, then reference them from `incident-support` in the pilot approval record.
|
||||
+2
-2
@@ -42,11 +42,11 @@ Implemented owner-only disconnect/reconnect and import restart controls, synchro
|
||||
|
||||
## Milestone 8: operational readiness
|
||||
|
||||
Implemented owner-only workspace health, database readiness, worker heartbeat, Linux deployment preflight, maintenance-window encrypted database/key/configuration backup and an isolated restore drill. The drill verifies collection counts, indexes and actual key decryption. Scheduling, off-server copies and production disaster cutover remain operator tasks; the Debian server rehearsal is still required. See [operations and recovery](operations.md).
|
||||
The application provides owner-only workspace health, database readiness and worker heartbeat information. Docker, Filebeat, MongoDB backup, host monitoring and disaster recovery are owned by the existing central infrastructure rather than duplicated inside GuestOps.
|
||||
|
||||
## Remaining milestones
|
||||
|
||||
1. Run dedicated Google test-mailbox acceptance, add full thread aggregation and history repair, and rehearse server backup/restore before the first hotel pilot.
|
||||
1. Run dedicated Google test-mailbox acceptance, add full thread aggregation and history repair, and confirm the central server backup/restore process before the first hotel pilot.
|
||||
2. Add verified transactional email for invitations and recovery notifications, MFA, granular roles and user preferences.
|
||||
3. Run a representative live AI draft evaluation, improve retrieval and evidence presentation, and approve the selected provider data-processing arrangements.
|
||||
4. Extend the implemented durable reply queue with operator recovery tooling and broaden the controlled FAQ rules only after live acceptance. Preserve the rule that uncertain sends are never blindly replayed.
|
||||
|
||||
@@ -1,127 +0,0 @@
|
||||
# Operations and recovery
|
||||
|
||||
The owner-only **Workspace health** page reports database reachability, the worker's last heartbeat, mailbox recovery counts and reply exceptions. A heartbeat older than three minutes is marked stale. It proves that the worker process recently reached MongoDB, not that every provider or job succeeded. Reply totals cover at most the latest 500 conversations in this hotel. The page does not verify backups. `/health/ready` returns only readiness status and HTTP 503 when the database cannot be reached.
|
||||
|
||||
## Release evidence and rollback
|
||||
|
||||
Every non-pull-request CI build packages the API and worker images under the full Git commit SHA. The accompanying `release-record.json` binds the archive checksum, application version, commit, image references and immutable Docker image IDs. Retain both files together in restricted off-host release storage; the CI artifact is a transfer mechanism, not the permanent archive.
|
||||
|
||||
Before deployment, verify the archive against its record without loading it:
|
||||
|
||||
```sh
|
||||
python3 - <<'PY'
|
||||
import hashlib, json, pathlib
|
||||
r = json.load(open('release-record.json', encoding='utf-8'))
|
||||
p = pathlib.Path(r['artifact']['name'])
|
||||
assert hashlib.sha256(p.read_bytes()).hexdigest() == r['artifact']['sha256']
|
||||
print(r['commit'], r['version'], r['images'])
|
||||
PY
|
||||
```
|
||||
|
||||
Load the archive, verify each loaded image ID matches the record, set `GUESTOPS_API_IMAGE` and `GUESTOPS_WORKER_IMAGE` to the recorded full-SHA references, and run the deployment preflight. Record the CI run, commit, checksum and operator in the change ticket. A release tag is an approval marker; do not move or reuse an existing tag. The application and web versions must match before the record can be created.
|
||||
|
||||
For rollback, first disable worker-driven external writes and reconcile any sending, payment or PMS operation that may have completed since the prior release. Confirm the previous release archive and record are retained, verify its checksum and image IDs, take an encrypted backup, then select the previous recorded image references in `.env` and recreate only the API and worker. Do not roll back MongoDB or the key volume merely to change application images. Run the online preflight, readiness check and read-only smoke test before re-enabling the worker or provider writes. If a release introduced an incompatible data change, follow its release-specific recovery plan rather than starting an older image against newer data.
|
||||
|
||||
## Deployment preflight
|
||||
|
||||
Run from the dedicated GuestOps checkout on Linux with Python 3.11 or later, Docker with Compose, and GnuPG installed. The tool supports the supplied three-service Compose deployment and the `guestops` database only. Docker access is administrator-equivalent; use the designated server operator account. Load the reviewed API, worker and MongoDB images first, configure `.env` with mode 600, and follow [deployment](deployment.md).
|
||||
|
||||
```sh
|
||||
python3 deploy/ops.py preflight --offline
|
||||
# After Nginx, DNS, TLS and services are running:
|
||||
python3 deploy/ops.py preflight
|
||||
```
|
||||
|
||||
Preflight checks production settings, shared persistent keys, unpublished MongoDB/worker ports, a loopback API port, required images and mounts, private secret files, and at least 8 GiB free disk. The online check also verifies the configured HTTPS readiness URL. This is not a firewall, capacity or provider acceptance test. Allow additional disk space for the database, images and temporary backup/restore files; the supplied server initially had 18 GiB free.
|
||||
|
||||
Configured provider files must be readable by the API container's `app` user while inaccessible to other users. Set their ownership to that image's application UID and mode 600, and run the backup as an authorized operator able to read them (for example root with its designated public GPG keyring). Keep their parent directory private. Empty shipped example files contain no credentials and do not need this ownership change. Check the UID in the reviewed image rather than assuming it matches your host login.
|
||||
|
||||
## Encrypted backup
|
||||
|
||||
Keep the recovery private key on an administrator-controlled recovery machine, with a securely stored passphrase and a second protected recovery copy. Import only its public key on the server and verify its full 40-character fingerprint through a trusted channel. The tool selects that exact fingerprint; it does not establish who owns the key. Do not put private keys, decrypted backups or provider secrets in GitHub.
|
||||
|
||||
```sh
|
||||
gpg --import /secure/path/recovery-public.asc
|
||||
gpg --fingerprint
|
||||
install -d -m 700 "$HOME/guestops-backups"
|
||||
read -r -p 'Verified recovery key fingerprint: ' BACKUP_RECIPIENT
|
||||
python3 deploy/ops.py backup --recipient "$BACKUP_RECIPIENT" \
|
||||
--output "$HOME/guestops-backups/guestops-$(date -u +%Y%m%dT%H%M%SZ).tar.gpg" \
|
||||
--confirm-maintenance
|
||||
unset BACKUP_RECIPIENT
|
||||
```
|
||||
|
||||
This command causes a maintenance interruption. It stops the API and worker, temporarily pauses MongoDB's TTL expiry monitor, dumps MongoDB, and saves the shared Data Protection keys and deployed configuration. The configuration includes credentials and provider files, so the entire bundle is encrypted. Services and the previous TTL setting are restored in a `finally` block before encryption finishes. A successful backup message does not prove that restarted services are healthy; run the online preflight afterwards.
|
||||
|
||||
No other application or administrator may write to this database during the snapshot. Standalone MongoDB dumps need coordinated writes for consistency; see the [MongoDB backup guidance](https://www.mongodb.com/docs/v8.0/tutorial/backup-and-restore-tools/). The tool is intentionally limited to the dedicated stack. It requires the hexadecimal MongoDB root password generated in the deployment guide.
|
||||
|
||||
Copy the encrypted file off-server to restricted storage after every successful backup. Retain the exact API, worker and MongoDB images with the release: an image tag alone can change, and the drill requires matching image IDs. Agree the backup schedule, retention and tolerated data loss before a hotel pilot. Scheduling, off-server transfer, deletion and alerting are operator responsibilities in this milestone; none is silently installed.
|
||||
|
||||
### Optional systemd schedule
|
||||
|
||||
The repository includes an opt-in daily systemd service and timer. They are templates, not automatically installed. The service assumes the reviewed checkout is `/srv/guestops` and stages encrypted files in `/var/backups/guestops`; review and change both unit files together if the host uses different paths.
|
||||
|
||||
Create the staging directory and environment file without storing a private key or passphrase on the server:
|
||||
|
||||
```sh
|
||||
sudo install -d -m 700 /var/backups/guestops /var/lib/guestops-backup/gnupg /etc/guestops
|
||||
sudo install -m 600 /dev/null /etc/guestops/backup.env
|
||||
sudoedit /etc/guestops/backup.env
|
||||
sudo env GNUPGHOME=/var/lib/guestops-backup/gnupg gpg --import /secure/path/recovery-public.asc
|
||||
sudo env GNUPGHOME=/var/lib/guestops-backup/gnupg gpg --fingerprint
|
||||
```
|
||||
|
||||
The file contains only these two settings. `BACKUP_RECIPIENT` is the verified 40-character public-key fingerprint already imported into the service account's GPG keyring.
|
||||
|
||||
```text
|
||||
BACKUP_RECIPIENT=0123456789ABCDEF0123456789ABCDEF01234567
|
||||
BACKUP_DIRECTORY=/var/backups/guestops
|
||||
```
|
||||
|
||||
Review the unit sandbox against the host, copy `deploy/systemd/guestops-backup.service` and `.timer` to `/etc/systemd/system`, then validate and test before enabling:
|
||||
|
||||
```sh
|
||||
sudo systemd-analyze verify /etc/systemd/system/guestops-backup.service /etc/systemd/system/guestops-backup.timer
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl start guestops-backup.service
|
||||
sudo systemctl status guestops-backup.service
|
||||
sudo systemctl enable --now guestops-backup.timer
|
||||
systemctl list-timers guestops-backup.timer
|
||||
```
|
||||
|
||||
The timer deliberately causes the same brief maintenance interruption as a manual backup. `Persistent=true` runs a missed event after downtime, so choose and communicate the maintenance window. A successful unit only stages an encrypted file locally. Configure an independently monitored off-host transfer, verify the destination checksum, alert on both unit and transfer failure, and test the alert route. Do not add automatic deletion until retention, legal hold and recovery requirements have named owners.
|
||||
|
||||
Temporary plaintext files are held in private directories and removed on normal completion or exceptions. Process termination or power loss can leave temporary data, stopped services or TTL expiry disabled. After an interrupted run, inspect the dedicated project and remove only its identified abandoned temporary directory after securing any recovery material. Restore the recorded TTL setting (normally true) and restart the services:
|
||||
|
||||
```sh
|
||||
docker compose exec -T mongo mongosh --quiet --nodb --eval 'const c=new Mongo("mongodb://127.0.0.1"); c.getDB("admin").auth(process.env.MONGO_INITDB_ROOT_USERNAME,process.env.MONGO_INITDB_ROOT_PASSWORD); const r=c.getDB("admin").runCommand({setParameter:1,ttlMonitorEnabled:true}); if(!r.ok)quit(1);'
|
||||
docker compose start api worker
|
||||
python3 deploy/ops.py preflight
|
||||
```
|
||||
|
||||
Use the previous value instead of true if TTL expiry was deliberately disabled beforehand. Do not remove production volumes to recover from a failed backup.
|
||||
|
||||
## Isolated restore drill
|
||||
|
||||
Use a trusted encrypted backup and the recovery key on a Linux recovery machine. Unlock the key through the local GPG agent before running the batch command; never pass its passphrase on the command line. Load the exact reviewed images from the backed-up release first.
|
||||
|
||||
```sh
|
||||
python3 deploy/ops.py restore-drill /secure/path/guestops-backup.tar.gpg \
|
||||
--api-image guestops-api:REVIEWED_RELEASE \
|
||||
--mongo-image mongo:8.0
|
||||
```
|
||||
|
||||
The drill decrypts into a private temporary directory, checks the four expected files and their hashes, rejects unsafe archive entries, and verifies that the restored keys decrypt a protected test value. It then restores MongoDB into a newly created container with no external network or published ports and compares every restored collection's count and indexes. TTL expiry is disabled in this disposable database so expired token records do not disappear during comparison. The exact temporary container and its volumes are removed afterwards. No worker or production application is started.
|
||||
|
||||
The decrypted bundle is capped at 8 GiB for this pilot tool. Leave room for the encrypted file, decrypted archive, extracted files and restored database. GPG's [output limit](https://www.gnupg.org/documentation/manuals/gnupg/GPG-Input-and-Output.html) bounds decrypted output; checksums detect corruption, not the identity of the backup creator. Use backups from the trusted operator only. A drill checks counts, indexes and key decryption, not every document's business meaning or live provider connectivity.
|
||||
|
||||
## Actual disaster recovery
|
||||
|
||||
This milestone implements a rehearsal, not an automatic production restore or cutover command. Before real guest data is accepted, rehearse a separate recovery deployment and document its precise image IDs, volume names, secret locations and operator responsibilities.
|
||||
|
||||
Restore into new isolated MongoDB and key volumes; preserve the damaged original for investigation. Reconstruct reviewed configuration from the encrypted bundle without copying old Docker container IDs or blindly executing archived configuration. Restore the `guestops` database with the compatible MongoDB tools and restore the matching key files with the application's required ownership. Check hotel/account records and saved settings before exposing the recovered API. Keep the worker stopped, provider writes disabled and external network access restricted throughout this process.
|
||||
|
||||
**A restored database can predate emails, invoices and PMS changes that providers already completed.** Review pending, sending and uncertain records against provider evidence before enabling any worker, including automatic FAQ rules. Do not replay an older approval merely because the restored record says it is pending. Reconcile external effects, validate account sessions and mailbox authorization, and explicitly approve the cutover only after these checks. Rotate credentials if compromise prompted the recovery. Keep the old deployment stopped when enabling the replacement.
|
||||
|
||||
CI exercises a synthetic encrypted backup and isolated restore drill, including actual key decryption and database comparison. A successful CI drill is separate from the required rehearsal on the Debian server with its actual deployment configuration.
|
||||
|
||||
+1
-1
@@ -46,6 +46,6 @@ Only unsubmitted proposals can be cancelled in GuestOps. Invoice closure, refund
|
||||
|
||||
## Acceptance before live use
|
||||
|
||||
Automated tests use an in-process fake HTTP handler and never contact NMI. They cover tenant isolation, amount/currency/identity mismatches, partial status, concurrent approvals, lost create responses, pagination and merchant changes. CI checks the production configuration mount and disabled defaults.
|
||||
Automated tests use an in-process fake HTTP handler and never contact NMI. They cover tenant isolation, amount/currency/identity mismatches, partial status, concurrent approvals, lost create responses, pagination and merchant changes. Run the production-configuration and disabled-default checks before packaging and again during the Ansible deployment verification.
|
||||
|
||||
Use a dedicated sandbox merchant and recipient to validate authentication, supported currency, exact request/response fields, preservation of `order_details.order_id`, customer invoice email and hosted checkout, partial/full payments and interrupted-request recovery. Live acceptance remains pending. Planet, direct payment links in GuestOps replies, automatic booking after payment, automated expiry/closure and background polling are follow-on work.
|
||||
|
||||
+1
-1
@@ -34,6 +34,6 @@ Current limitations: messages imported before reply headers were stored must be
|
||||
|
||||
## Verification
|
||||
|
||||
The test suite covers competing workers, send identity/thread headers, invalid recipients, header injection, uncertain outcomes, restart recovery, pre-send token failure, disabling hotel sending, cross-hotel access, Gmail reconciliation mismatches, AI source isolation, invalid citations, escalations and incomplete responses. CI also runs production container login/restart-persistence smoke checks. Live acceptance must additionally verify Google consent, actual threading, grant revocation, a representative AI draft evaluation set and provider error behaviour with the configured accounts.
|
||||
The test suite covers competing workers, send identity/thread headers, invalid recipients, header injection, uncertain outcomes, restart recovery, pre-send token failure, disabling hotel sending, cross-hotel access, Gmail reconciliation mismatches, AI source isolation, invalid citations, escalations and incomplete responses. Run the production-container login and restart-persistence smoke checks before packaging and during Ansible deployment verification. Live acceptance must additionally verify Google consent, actual threading, grant revocation, a representative AI draft evaluation set and provider error behaviour with the configured accounts.
|
||||
|
||||
Implementation references: [OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [Gmail sending](https://developers.google.com/workspace/gmail/api/guides/sending), [Gmail threads](https://developers.google.com/workspace/gmail/api/guides/threads).
|
||||
|
||||
@@ -16,7 +16,7 @@ public sealed class GoogleMailbox(HttpClient http, IConfiguration config, IStore
|
||||
private readonly IDataProtector protector = protection.CreateProtector("GoogleMailbox.refresh.v1");
|
||||
private string ClientId => config["Google:ClientId"] ?? "";
|
||||
private string ClientSecret => config["Google:ClientSecret"] ?? "";
|
||||
private string Callback => (config["PublicUrl"] ?? "https://sandbox-guestops.futuresens.co.uk").TrimEnd('/') + "/api/integrations/google/callback";
|
||||
private string Callback => (config["PublicUrl"] ?? "https://guestops-sandbox.futuresens.co.uk").TrimEnd('/') + "/api/integrations/google/callback";
|
||||
public bool Configured => ClientId.Length > 0 && ClientSecret.Length > 0;
|
||||
public bool SendingConfigured => Configured && config.GetValue<bool>("Google:EnableSending");
|
||||
public string AuthorizationUrl(string state) => "https://accounts.google.com/o/oauth2/v2/auth?" + string.Join("&", new Dictionary<string,string> {
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Exercise disposable CI containers through the host's trusted proxy address.
|
||||
"""Exercise disposable deployment containers through the host's trusted proxy address.
|
||||
|
||||
The forwarded HTTPS header simulates Nginx TLS termination; this is never run
|
||||
against an existing hotel database. Cookie values and credentials are not logged.
|
||||
@@ -66,13 +66,13 @@ team = request("/api/team")
|
||||
assert all("passwordHash" not in member and "securityStamp" not in member and "accountLinkHash" not in member for member in team)
|
||||
if "--read" in sys.argv:
|
||||
assert hotel["signature"] == "Persisted across container restart"
|
||||
invited = next(member for member in team if member["email"] == "ci-staff@example.invalid")
|
||||
invited = next(member for member in team if member["email"] == "deployment-staff@example.invalid")
|
||||
assert invited["pending"] and not invited["active"] and invited["linkPurpose"] == "Invite"
|
||||
else:
|
||||
hotel["signature"] = "Persisted across container restart"
|
||||
request("/api/hotel", "PUT", hotel)
|
||||
invite = request("/api/team/invite", "POST", {"name": "CI Staff", "email": "ci-staff@example.invalid"})
|
||||
assert invite["link"].startswith("https://sandbox-guestops.futuresens.co.uk/account#token=")
|
||||
invite = request("/api/team/invite", "POST", {"name": "Deployment Staff", "email": "deployment-staff@example.invalid"})
|
||||
assert invite["link"].startswith("https://guestops-sandbox.futuresens.co.uk/account#token=")
|
||||
request("/api/auth/logout", "POST")
|
||||
request("/api/hotel", expected=401)
|
||||
print("Production smoke checks passed: built UI, secure cookies, owner login, persisted settings and staff invitation, onboarding and logout.")
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
spec = importlib.util.spec_from_file_location("desktop_acceptance", Path(__file__).resolve().parents[1] / "deploy" / "desktop_acceptance.py")
|
||||
acceptance = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(acceptance)
|
||||
|
||||
|
||||
def valid_record():
|
||||
return {
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-desktop-parity",
|
||||
"dataClassification": "synthetic-only",
|
||||
"desktopBaselineCommit": acceptance.DESKTOP_BASELINE,
|
||||
"releaseCommit": "a" * 40,
|
||||
"releaseRecordSha256": "b" * 64,
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk",
|
||||
"browser": {"name": "Microsoft Edge", "version": "140.0.0.0", "operatingSystem": "Windows 11"},
|
||||
"viewport": {"width": 1440, "height": 900, "deviceScaleFactor": 1},
|
||||
"hotelTimeZone": "Europe/London",
|
||||
"operator": "Acceptance operator",
|
||||
"reviewedBy": "Independent reviewer",
|
||||
"startedAt": "2026-09-29T09:00:00Z",
|
||||
"endedAt": "2026-09-29T10:00:00Z",
|
||||
"reviewedAt": "2026-09-29T11:00:00Z",
|
||||
"scenarios": [
|
||||
{"id": scenario, "status": "pass", "evidence": [f"restricted-ticket-{index}"]}
|
||||
for index, scenario in enumerate(sorted(acceptance.SCENARIOS), 1)
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
class DesktopAcceptanceTests(unittest.TestCase):
|
||||
def test_complete_record_passes(self):
|
||||
acceptance.validate(valid_record())
|
||||
|
||||
def test_exact_scenarios_and_desktop_baseline_are_required(self):
|
||||
record = valid_record();record["scenarios"].pop()
|
||||
with self.assertRaisesRegex(ValueError, "exact desktop scenario"):
|
||||
acceptance.validate(record)
|
||||
record = valid_record();record["desktopBaselineCommit"] = "c" * 40
|
||||
with self.assertRaisesRegex(ValueError, "reviewed desktop baseline"):
|
||||
acceptance.validate(record)
|
||||
|
||||
def test_desktop_viewport_and_timezone_are_required(self):
|
||||
record = valid_record();record["viewport"]["width"] = 1024
|
||||
with self.assertRaisesRegex(ValueError, "Desktop viewport width"):
|
||||
acceptance.validate(record)
|
||||
record = valid_record();record["hotelTimeZone"] = "local browser time"
|
||||
with self.assertRaisesRegex(ValueError, "IANA timezone"):
|
||||
acceptance.validate(record)
|
||||
|
||||
def test_independent_review_and_safe_evidence_are_required(self):
|
||||
record = valid_record();record["reviewedBy"] = record["operator"]
|
||||
with self.assertRaisesRegex(ValueError, "different people"):
|
||||
acceptance.validate(record)
|
||||
record = valid_record();record["scenarios"][0]["evidence"] = ["guest@example.invalid"]
|
||||
with self.assertRaisesRegex(ValueError, "safe opaque"):
|
||||
acceptance.validate(record)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,85 @@
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
def module(name):
|
||||
spec = importlib.util.spec_from_file_location(name, ROOT / "deploy" / f"{name}.py")
|
||||
result = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(result)
|
||||
return result
|
||||
|
||||
|
||||
automation = module("automation_acceptance")
|
||||
privacy = module("identity_privacy_acceptance")
|
||||
|
||||
|
||||
def base(system):
|
||||
return {
|
||||
"schemaVersion": 1, "system": system, "targetGate": "B",
|
||||
"releaseCommit": "a" * 40, "releaseRecordSha256": "b" * 64,
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk",
|
||||
"operator": "Acceptance operator", "reviewedBy": "Independent reviewer",
|
||||
"startedAt": "2026-10-01T09:00:00Z", "endedAt": "2026-10-01T10:00:00Z", "reviewedAt": "2026-10-01T11:00:00Z",
|
||||
}
|
||||
|
||||
|
||||
def automation_record():
|
||||
record = base("guestops-automation-acceptance")
|
||||
record.update({
|
||||
"dataClassification": "synthetic-only",
|
||||
"faqEvaluation": {"positiveCases": 20, "negativeCases": 20, "falsePositives": 0, "falseNegatives": 0, "reportSha256": "c" * 64},
|
||||
"aiEvaluation": {"casesReviewed": 20, "unsafeDraftsApproved": 0, "reportSha256": "d" * 64},
|
||||
"staffTrained": 3, "monitoringOwner": "Monitoring owner", "rollbackOwner": "Rollback owner",
|
||||
"scenarios": [{"id": item, "status": "pass", "evidence": ["restricted-" + item]} for item in sorted(automation.SCENARIOS)],
|
||||
"postAcceptanceState": {"faqMode": "off", "pmsWrites": "disabled", "paymentCreation": "disabled"},
|
||||
})
|
||||
return record
|
||||
|
||||
|
||||
def privacy_record():
|
||||
record = base("guestops-identity-privacy")
|
||||
record.update({
|
||||
"retention": {"conversationDays": 365, "auditDays": 730, "backupDays": 30, "accountDays": 730,
|
||||
"privacyOwner": "Privacy owner", "deletionOwner": "Deletion owner", "legalHoldOwner": "Legal hold owner",
|
||||
"deletionProcedure": "restricted-deletion", "legalHoldProcedure": "restricted-legal-hold"},
|
||||
"providers": {"google": {"status": "accepted", "evidence": ["restricted-google"]},
|
||||
"openai": {"status": "disabled", "evidence": ["restricted-openai-decision"]}},
|
||||
"preferencesReviewed": sorted(privacy.PREFERENCES),
|
||||
"scenarios": [{"id": item, "status": "pass", "evidence": ["restricted-" + item]} for item in sorted(privacy.SCENARIOS)],
|
||||
})
|
||||
return record
|
||||
|
||||
|
||||
class GateBAcceptanceTests(unittest.TestCase):
|
||||
def test_complete_records_pass(self):
|
||||
automation.validate(automation_record())
|
||||
privacy.validate(privacy_record())
|
||||
|
||||
def test_automation_requires_zero_faq_errors_and_training(self):
|
||||
record = automation_record();record["faqEvaluation"]["falsePositives"] = 1
|
||||
with self.assertRaisesRegex(ValueError, "zero false positives"):
|
||||
automation.validate(record)
|
||||
record = automation_record();record["staffTrained"] = 0
|
||||
with self.assertRaisesRegex(ValueError, "staff member"):
|
||||
automation.validate(record)
|
||||
|
||||
def test_privacy_requires_retention_and_google_decisions(self):
|
||||
record = privacy_record();record["retention"]["conversationDays"] = 0
|
||||
with self.assertRaisesRegex(ValueError, "conversationDays"):
|
||||
privacy.validate(record)
|
||||
record = privacy_record();record["providers"]["google"]["status"] = "pending"
|
||||
with self.assertRaisesRegex(ValueError, "Google processing"):
|
||||
privacy.validate(record)
|
||||
|
||||
def test_privacy_requires_exact_preference_coverage(self):
|
||||
record = privacy_record();record["preferencesReviewed"].pop()
|
||||
with self.assertRaisesRegex(ValueError, "exact owner-controlled"):
|
||||
privacy.validate(record)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -14,7 +14,7 @@ def valid_report():
|
||||
"system": "google-mailbox",
|
||||
"releaseCommit": "a" * 40,
|
||||
"releaseRecordSha256": "b" * 64,
|
||||
"environment": "https://sandbox-guestops.futuresens.co.uk",
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk",
|
||||
"mailboxLabel": "sandbox mailbox A",
|
||||
"operator": "Test operator",
|
||||
"startedAt": "2026-09-29T10:00:00Z",
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
spec = importlib.util.spec_from_file_location("incident_exercise", Path(__file__).resolve().parents[1] / "deploy" / "incident_exercise.py")
|
||||
exercise = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(exercise)
|
||||
|
||||
|
||||
def valid_record(gate="B"):
|
||||
required = exercise.GATE_C_SCENARIOS if gate == "C" else exercise.GATE_B_SCENARIOS
|
||||
return {
|
||||
"schemaVersion": 1,
|
||||
"system": "guestops-incident-exercise",
|
||||
"targetGate": gate,
|
||||
"dataClassification": "synthetic-only",
|
||||
"releaseCommit": "a" * 40,
|
||||
"releaseRecordSha256": "b" * 64,
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk",
|
||||
"operator": "Exercise operator",
|
||||
"incidentCommander": "Incident commander",
|
||||
"reviewedBy": "Independent reviewer",
|
||||
"startedAt": "2026-09-29T09:00:00Z",
|
||||
"endedAt": "2026-09-29T10:00:00Z",
|
||||
"reviewedAt": "2026-09-29T11:00:00Z",
|
||||
"targetsMinutes": {"detection": 10, "containment": 20, "recovery": 60},
|
||||
"observedMinutes": {"detection": 5, "containment": 15, "recovery": 45},
|
||||
"scenarios": [
|
||||
{"id": scenario, "status": "pass", "evidence": [f"restricted-ticket-{index}"]}
|
||||
for index, scenario in enumerate(sorted(required), 1)
|
||||
],
|
||||
"postExerciseState": {
|
||||
"externalWrites": "disabled", "faqMode": "off", "unresolvedOperations": 0,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class IncidentExerciseTests(unittest.TestCase):
|
||||
def test_gate_b_and_c_complete_records_pass(self):
|
||||
exercise.validate(valid_record("B"))
|
||||
exercise.validate(valid_record("C"))
|
||||
|
||||
def test_gate_specific_scenarios_are_required(self):
|
||||
record = valid_record("C")
|
||||
record["scenarios"].pop()
|
||||
with self.assertRaisesRegex(ValueError, "exact incident scenario"):
|
||||
exercise.validate(record)
|
||||
|
||||
def test_timings_must_meet_preagreed_targets(self):
|
||||
record = valid_record()
|
||||
record["observedMinutes"]["containment"] = 21
|
||||
with self.assertRaisesRegex(ValueError, "Observed containment"):
|
||||
exercise.validate(record)
|
||||
record = valid_record()
|
||||
record["targetsMinutes"]["recovery"] = True
|
||||
with self.assertRaisesRegex(ValueError, "recovery target"):
|
||||
exercise.validate(record)
|
||||
|
||||
def test_independent_people_and_safe_evidence_are_required(self):
|
||||
record = valid_record()
|
||||
record["reviewedBy"] = record["operator"]
|
||||
with self.assertRaisesRegex(ValueError, "different people"):
|
||||
exercise.validate(record)
|
||||
record = valid_record()
|
||||
record["scenarios"][0]["evidence"] = ["guest@example.invalid"]
|
||||
with self.assertRaisesRegex(ValueError, "safe opaque"):
|
||||
exercise.validate(record)
|
||||
|
||||
def test_safe_post_exercise_state_is_required(self):
|
||||
record = valid_record()
|
||||
record["postExerciseState"]["externalWrites"] = "enabled"
|
||||
with self.assertRaisesRegex(ValueError, "writes disabled"):
|
||||
exercise.validate(record)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,186 +0,0 @@
|
||||
import contextlib
|
||||
import hashlib
|
||||
import importlib.util
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import tarfile
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
spec = importlib.util.spec_from_file_location("ops", Path(__file__).resolve().parents[1] / "deploy" / "ops.py")
|
||||
ops = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(ops)
|
||||
|
||||
|
||||
class ArchiveTests(unittest.TestCase):
|
||||
def test_persistence_layout_resolves_shared_keys_and_database(self):
|
||||
config = {
|
||||
"services": {
|
||||
"api": {"volumes": [{"type": "volume", "source": "app-keys", "target": "/var/lib/guestops/keys"}]},
|
||||
"worker": {"volumes": [{"type": "volume", "source": "app-keys", "target": "/var/lib/guestops/keys"}]},
|
||||
"mongo": {"volumes": [{"type": "volume", "source": "mongo-data", "target": "/data/db"}]},
|
||||
},
|
||||
"volumes": {
|
||||
"app-keys": {"name": "guestops_app-keys"},
|
||||
"mongo-data": {"name": "guestops_mongo-data"},
|
||||
},
|
||||
}
|
||||
self.assertEqual(ops.persistence_layout(config), {"keys": "guestops_app-keys", "database": "guestops_mongo-data"})
|
||||
|
||||
def test_persistence_layout_rejects_anonymous_or_split_keys(self):
|
||||
config = {
|
||||
"services": {
|
||||
"api": {"volumes": [{"type": "volume", "source": "api-keys", "target": "/var/lib/guestops/keys"}]},
|
||||
"worker": {"volumes": [{"type": "volume", "source": "worker-keys", "target": "/var/lib/guestops/keys"}]},
|
||||
"mongo": {"volumes": [{"type": "volume", "source": "mongo-data", "target": "/data/db"}]},
|
||||
},
|
||||
"volumes": {"api-keys": {}, "worker-keys": {}, "mongo-data": {}},
|
||||
}
|
||||
with self.assertRaisesRegex(RuntimeError, "key volumes differ"):
|
||||
ops.persistence_layout(config)
|
||||
|
||||
config["services"]["worker"]["volumes"][0] = {"type": "volume", "target": "/var/lib/guestops/keys"}
|
||||
with self.assertRaisesRegex(RuntimeError, "named persistent volume"):
|
||||
ops.persistence_layout(config)
|
||||
|
||||
def test_persistence_drill_requires_explicit_restart_confirmation(self):
|
||||
with self.assertRaisesRegex(RuntimeError, "confirm-restart"):
|
||||
ops.persistence_drill(type("Args", (), {"confirm_restart": False})())
|
||||
|
||||
def test_persistence_drill_restarts_then_recreates_stateless_services(self):
|
||||
compose_calls = []
|
||||
inventory = json.dumps({"bytes": 1, "collections": {"hotels": {"count": 1, "indexes": []}}}).encode()
|
||||
|
||||
def compose(*args, **kwargs):
|
||||
compose_calls.append(args)
|
||||
return b"a" * 30 if args[-1] == "--backup-probe" else b""
|
||||
|
||||
def mongo(script):
|
||||
return inventory if "storageSize" in script else b""
|
||||
|
||||
with patch.object(ops, "configuration", return_value={}), \
|
||||
patch.object(ops, "persistence_layout", return_value={"keys": "keys", "database": "data"}), \
|
||||
patch.object(ops, "volume_identity", side_effect=lambda name: {"name": name, "driver": "local", "scope": "local"}), \
|
||||
patch.object(ops, "compose", side_effect=compose), \
|
||||
patch.object(ops, "mongo", side_effect=mongo), \
|
||||
patch.object(ops, "wait_for", side_effect=lambda action, message: action()), \
|
||||
patch.object(ops, "readiness"):
|
||||
ops.persistence_drill(type("Args", (), {"confirm_restart": True})())
|
||||
|
||||
self.assertIn(("restart", "-t", "150", "mongo"), compose_calls)
|
||||
self.assertIn(("restart", "-t", "150", "api", "worker"), compose_calls)
|
||||
self.assertIn(("up", "-d", "--no-build", "--force-recreate", "api", "worker"), compose_calls)
|
||||
self.assertTrue(any("--verify-backup-probe" in call for call in compose_calls))
|
||||
|
||||
def test_empty_provider_templates_are_not_secret_configuration(self):
|
||||
for section, target in (("Pms", "/run/guestops/pms.json"), ("Payments", "/run/guestops/payments.json")):
|
||||
self.assertFalse(ops.provider_configured({section: {"Hotels": {}}}, target))
|
||||
self.assertTrue(ops.provider_configured({section: {"Hotels": {"fixture": {"Key": "fixture"}}}}, target))
|
||||
self.assertTrue(ops.provider_configured({section: {"Unknown": "fixture"}}, target))
|
||||
|
||||
def bundle(self, root, change=None):
|
||||
files = {name: b"fixture backup data" for name in ops.FILES - {"manifest.json"}}
|
||||
files["manifest.json"] = json.dumps({"format": 1, "sha256": {name: hashlib.sha256(data).hexdigest() for name, data in files.items()}}).encode()
|
||||
target = root / "bundle.tar"
|
||||
with tarfile.open(target, "w") as archive:
|
||||
for name, data in files.items():
|
||||
member = tarfile.TarInfo(name); member.size = len(data)
|
||||
if change:
|
||||
change(member)
|
||||
archive.addfile(member, io.BytesIO(data) if member.isfile() else None)
|
||||
return target
|
||||
|
||||
def test_checked_archive_roundtrip(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
||||
self.assertEqual(ops.unpack(self.bundle(root), dest)["format"], 1)
|
||||
|
||||
def test_path_escape_rejected(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
||||
def corrupt(member):
|
||||
if member.name == "configuration.json": member.name = "../outside"
|
||||
with self.assertRaisesRegex(RuntimeError, "Unexpected backup members"):
|
||||
ops.unpack(self.bundle(root, corrupt), dest)
|
||||
self.assertFalse((root / "outside").exists())
|
||||
|
||||
def test_symlink_rejected(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
||||
def corrupt(member):
|
||||
if member.name == "configuration.json": member.type = tarfile.SYMTYPE; member.linkname = "/etc/passwd"; member.size = 0
|
||||
with self.assertRaisesRegex(RuntimeError, "Invalid or oversized"):
|
||||
ops.unpack(self.bundle(root, corrupt), dest)
|
||||
|
||||
def test_checksum_mismatch_rejected(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
root = Path(temp); dest = root / "dest"; dest.mkdir()
|
||||
with patch.object(ops, "digest", return_value="changed"):
|
||||
with self.assertRaisesRegex(RuntimeError, "checksum"):
|
||||
ops.unpack(self.bundle(root), dest)
|
||||
|
||||
def test_backup_requires_explicit_maintenance(self):
|
||||
with self.assertRaisesRegex(RuntimeError, "confirm-maintenance"):
|
||||
ops.backup(type("Args", (), {"confirm_maintenance": False})())
|
||||
|
||||
def test_scheduled_backup_requires_explicit_maintenance(self):
|
||||
with self.assertRaisesRegex(RuntimeError, "confirm-maintenance"):
|
||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": False})())
|
||||
|
||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
||||
def test_scheduled_backup_uses_private_external_directory_and_environment(self):
|
||||
with tempfile.TemporaryDirectory() as parent:
|
||||
directory = Path(parent) / "backups"
|
||||
directory.mkdir(mode=0o700)
|
||||
captured = []
|
||||
with patch.dict(os.environ, {"BACKUP_RECIPIENT": "A" * 40, "BACKUP_DIRECTORY": str(directory)}), \
|
||||
patch.object(ops, "ROOT", Path(parent) / "checkout"), \
|
||||
patch.object(ops, "backup", side_effect=lambda args: captured.append(args)), \
|
||||
patch.object(ops.time, "strftime", return_value="20260929T020000Z"):
|
||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": True})())
|
||||
self.assertEqual(captured[0].recipient, "A" * 40)
|
||||
self.assertEqual(Path(captured[0].output), directory / "guestops-20260929T020000Z.tar.gpg")
|
||||
self.assertTrue(captured[0].confirm_maintenance)
|
||||
|
||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
||||
def test_scheduled_backup_rejects_checkout_directory(self):
|
||||
with tempfile.TemporaryDirectory() as parent:
|
||||
checkout = Path(parent) / "checkout"
|
||||
directory = checkout / "backups"
|
||||
directory.mkdir(parents=True, mode=0o700)
|
||||
with patch.dict(os.environ, {"BACKUP_RECIPIENT": "A" * 40, "BACKUP_DIRECTORY": str(directory)}), \
|
||||
patch.object(ops, "ROOT", checkout):
|
||||
with self.assertRaisesRegex(RuntimeError, "outside the application checkout"):
|
||||
ops.scheduled_backup(type("Args", (), {"confirm_maintenance": True})())
|
||||
|
||||
@unittest.skipUnless(os.name == "posix", "Linux file permission semantics")
|
||||
def test_dump_failure_restarts_services_and_ttl(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
calls = []
|
||||
def compose(*args, **kwargs):
|
||||
calls.append(args)
|
||||
if args[0] == "ps": return b"a" * 64
|
||||
if "sh" in args: raise RuntimeError("Simulated dump failure")
|
||||
return b""
|
||||
def mongo(script):
|
||||
calls.append((script,))
|
||||
if "getParameter" in script: return b"true"
|
||||
if "storageSize" in script: return b'{"bytes":1,"collections":{}}'
|
||||
return b""
|
||||
def run(args, **kwargs):
|
||||
return b'[{"Image":"sha256:fixture"}]' if "inspect" in args else b""
|
||||
args = type("Args", (), {"confirm_maintenance": True, "recipient": "A" * 40, "output": str(Path(temp) / "backup.gpg")})()
|
||||
with patch.object(ops, "configuration", return_value={}), patch.object(ops, "run", side_effect=run), patch.object(ops, "compose", side_effect=compose), patch.object(ops, "mongo", side_effect=mongo), patch.object(ops, "maintenance_lock", return_value=contextlib.nullcontext()):
|
||||
with self.assertRaisesRegex(RuntimeError, "Simulated dump failure"):
|
||||
ops.backup(args)
|
||||
self.assertIn(("start", "api", "worker"), calls)
|
||||
self.assertTrue(any("ttlMonitorEnabled:true" in call[0] for call in calls))
|
||||
self.assertFalse(Path(args.output).exists())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
import importlib.util
|
||||
import json
|
||||
from pathlib import Path
|
||||
import subprocess
|
||||
import tarfile
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
spec = importlib.util.spec_from_file_location("package_source", ROOT / "deploy" / "package_source.py")
|
||||
package_source = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(package_source)
|
||||
|
||||
|
||||
def run(repository: Path, *arguments: str) -> str:
|
||||
result = subprocess.run(
|
||||
["git", "-C", str(repository), *arguments],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
return result.stdout.strip()
|
||||
|
||||
|
||||
class PackageSourceTests(unittest.TestCase):
|
||||
def repository(self, root: Path, dotnet_version: str = "1.2.3", web_version: str = "1.2.3") -> tuple[Path, str]:
|
||||
repository = root / "repository"
|
||||
(repository / "web").mkdir(parents=True)
|
||||
run(repository, "init")
|
||||
run(repository, "config", "user.name", "GuestOps Test")
|
||||
run(repository, "config", "user.email", "guestops@example.invalid")
|
||||
run(repository, "config", "core.autocrlf", "false")
|
||||
(repository / "Directory.Build.props").write_text(
|
||||
f"<Project><PropertyGroup><Version>{dotnet_version}</Version></PropertyGroup></Project>\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(repository / "web" / "package.json").write_text(
|
||||
json.dumps({"version": web_version}) + "\n", encoding="utf-8"
|
||||
)
|
||||
(repository / "application.txt").write_text("committed application\n", encoding="utf-8")
|
||||
run(repository, "add", ".")
|
||||
run(repository, "commit", "-m", "fixture")
|
||||
return repository, run(repository, "rev-parse", "HEAD")
|
||||
|
||||
def test_packages_only_the_selected_commit_with_version_name(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
repository, commit = self.repository(root)
|
||||
(repository / "application.txt").write_text("uncommitted change\n", encoding="utf-8")
|
||||
|
||||
archive, details = package_source.build_package(repository, commit, root / "output")
|
||||
|
||||
self.assertEqual(archive.name, "guestops_1.2.3.tar.gz")
|
||||
self.assertEqual(details, {"commit": commit, "version": "1.2.3"})
|
||||
with tarfile.open(archive, "r:gz") as package:
|
||||
member = package.extractfile("guestops_1.2.3/application.txt")
|
||||
self.assertIsNotNone(member)
|
||||
self.assertEqual(member.read().decode("utf-8").strip(), "committed application")
|
||||
|
||||
def test_same_commit_produces_identical_package(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
repository, commit = self.repository(root)
|
||||
first, _ = package_source.build_package(repository, commit, root / "first")
|
||||
second, _ = package_source.build_package(repository, commit, root / "second")
|
||||
self.assertEqual(first.read_bytes(), second.read_bytes())
|
||||
|
||||
def test_rejects_mismatched_versions_and_existing_output(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
repository, commit = self.repository(root, web_version="1.2.4")
|
||||
with self.assertRaisesRegex(ValueError, "versions differ"):
|
||||
package_source.build_package(repository, commit, root / "output")
|
||||
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
repository, commit = self.repository(root)
|
||||
package_source.build_package(repository, commit, root / "output")
|
||||
with self.assertRaisesRegex(ValueError, "not overwritten"):
|
||||
package_source.build_package(repository, commit, root / "output")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,82 @@
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
spec = importlib.util.spec_from_file_location("pilot_approval", Path(__file__).resolve().parents[1] / "deploy" / "pilot_approval.py")
|
||||
approval = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(approval)
|
||||
|
||||
|
||||
def valid_record(gate="B"):
|
||||
ids = approval.GATE_C if gate == "C" else approval.GATE_B
|
||||
return {
|
||||
"schemaVersion": 2, "targetGate": gate, "decision": "approved",
|
||||
"releaseCommit": "a" * 40, "releaseRecordSha256": "b" * 64,
|
||||
"decidedAt": "2026-09-29T12:00:00Z",
|
||||
"approvals": {
|
||||
"hotelOwner": {"name": "Hotel owner", "approvedAt": "2026-09-29T11:00:00Z"},
|
||||
"technicalOwner": {"name": "Technical owner", "approvedAt": "2026-09-29T11:30:00Z"},
|
||||
},
|
||||
"capacity": {"reportSha256": "c" * 64, "hostMetricsSha256": "d" * 64, "targetConcurrency": 10, "observedConcurrency": 10, "targetP95Ms": 500, "observedP95Ms": 250, "targetErrorRate": 0.01, "observedErrorRate": 0, "targetCpuHeadroomPercent": 25, "observedCpuHeadroomPercent": 40, "targetMemoryHeadroomPercent": 25, "observedMemoryHeadroomPercent": 35},
|
||||
"pilot": {"recordSha256": "e" * 64, "businessDaysObserved": 5, "hotelsObserved": 1, "stopConditionsObserved": 0, "unresolvedFindings": 0},
|
||||
"evidence": [{"id": item, "status": "pass", "references": ["restricted-ticket-" + item]} for item in sorted(ids)],
|
||||
}
|
||||
|
||||
|
||||
class PilotApprovalTests(unittest.TestCase):
|
||||
def test_gate_b_and_c_complete_records_pass(self):
|
||||
approval.validate(valid_record("B"))
|
||||
approval.validate(valid_record("C"))
|
||||
|
||||
def test_pending_or_missing_evidence_fails(self):
|
||||
record = valid_record();record["decision"] = "pending"
|
||||
with self.assertRaisesRegex(ValueError, "explicit approved"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["evidence"].pop()
|
||||
with self.assertRaisesRegex(ValueError, "exact evidence"):
|
||||
approval.validate(record)
|
||||
|
||||
def test_capacity_must_meet_preapproved_targets(self):
|
||||
record = valid_record();record["capacity"]["observedP95Ms"] = 501
|
||||
with self.assertRaisesRegex(ValueError, "observedP95Ms"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["capacity"]["observedConcurrency"] = 9
|
||||
with self.assertRaisesRegex(ValueError, "Observed concurrency"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["capacity"]["targetConcurrency"] = True
|
||||
with self.assertRaisesRegex(ValueError, "Observed concurrency"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["capacity"]["targetErrorRate"] = 2
|
||||
with self.assertRaisesRegex(ValueError, "ratio"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["capacity"]["observedCpuHeadroomPercent"] = 24
|
||||
with self.assertRaisesRegex(ValueError, "cpu headroom"):
|
||||
approval.validate(record)
|
||||
|
||||
def test_completed_five_day_single_hotel_pilot_is_required(self):
|
||||
record = valid_record();record["pilot"]["businessDaysObserved"] = 4
|
||||
with self.assertRaisesRegex(ValueError, "five business days"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["pilot"]["stopConditionsObserved"] = 1
|
||||
with self.assertRaisesRegex(ValueError, "stop condition"):
|
||||
approval.validate(record)
|
||||
|
||||
def test_approvers_must_be_separate_people_without_email_addresses(self):
|
||||
record = valid_record();record["approvals"]["technicalOwner"]["name"] = "Hotel owner"
|
||||
with self.assertRaisesRegex(ValueError, "different people"):
|
||||
approval.validate(record)
|
||||
record = valid_record();record["approvals"]["hotelOwner"]["name"] = "owner@example.invalid"
|
||||
with self.assertRaisesRegex(ValueError, "without an email"):
|
||||
approval.validate(record)
|
||||
|
||||
def test_containment_requires_owner_future_expiry_and_trigger(self):
|
||||
record = valid_record();item = record["evidence"][0];item["status"] = "contained"
|
||||
with self.assertRaisesRegex(ValueError, "containment details"):
|
||||
approval.validate(record)
|
||||
item["containment"] = {"owner": "Release owner", "expiresAt": "2026-10-10T12:00:00Z", "rollbackTrigger": "Rollback if the contained condition occurs."}
|
||||
approval.validate(record)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,59 @@
|
||||
import importlib.util
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
|
||||
|
||||
spec = importlib.util.spec_from_file_location("pilot_run", Path(__file__).resolve().parents[1] / "deploy" / "pilot_run.py")
|
||||
pilot = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(pilot)
|
||||
|
||||
|
||||
def valid_record():
|
||||
days = [f"2026-10-{day:02d}" for day in range(5, 10)]
|
||||
return {
|
||||
"schemaVersion": 1, "system": "guestops-supervised-pilot", "targetGate": "B",
|
||||
"releaseCommit": "a" * 40, "releaseRecordSha256": "b" * 64,
|
||||
"environment": "https://guestops-sandbox.futuresens.co.uk", "hotelLabel": "pilot-hotel-a",
|
||||
"hotelCount": 1, "plannedBusinessDays": 5,
|
||||
"owners": {"hotelOwner": "Hotel owner", "technicalOwner": "Technical owner", "rollbackDecisionMaker": "Technical owner"},
|
||||
"startedOn": days[0], "endedOn": days[-1],
|
||||
"pilotControls": {"pmsWrites": "disabled", "paymentCreation": "disabled", "faqMode": "off", "googleReviewedSending": "accepted"},
|
||||
"dailyReviews": [{"date": day, "status": "pass", "reviewedBy": "Daily reviewer", "evidence": [f"restricted-{day}"]} for day in days],
|
||||
"stopConditions": {condition: False for condition in pilot.STOP_CONDITIONS},
|
||||
"findings": [],
|
||||
"postPilotState": {"pmsWrites": "disabled", "paymentCreation": "disabled", "faqMode": "off"},
|
||||
}
|
||||
|
||||
|
||||
class PilotRunTests(unittest.TestCase):
|
||||
def test_complete_five_day_record_passes(self):
|
||||
pilot.validate(valid_record())
|
||||
|
||||
def test_exact_business_days_are_required(self):
|
||||
record = valid_record();record["dailyReviews"].pop()
|
||||
with self.assertRaisesRegex(ValueError, "Exactly five"):
|
||||
pilot.validate(record)
|
||||
record = valid_record();record["dailyReviews"][1]["date"] = "2026-10-07"
|
||||
with self.assertRaisesRegex(ValueError, "each business day"):
|
||||
pilot.validate(record)
|
||||
|
||||
def test_stop_condition_prevents_pass(self):
|
||||
record = valid_record();record["stopConditions"]["duplicate-send"] = True
|
||||
with self.assertRaisesRegex(ValueError, "stop condition"):
|
||||
pilot.validate(record)
|
||||
|
||||
def test_critical_findings_cannot_be_contained(self):
|
||||
record = valid_record();record["findings"] = [{"id": "security-001", "severity": "critical", "disposition": "contained", "evidence": ["restricted-finding"]}]
|
||||
with self.assertRaisesRegex(ValueError, "too severe"):
|
||||
pilot.validate(record)
|
||||
|
||||
def test_lower_severity_containment_requires_owner_expiry_and_trigger(self):
|
||||
record = valid_record();record["findings"] = [{"id": "usability-001", "severity": "low", "disposition": "contained", "evidence": ["restricted-finding"]}]
|
||||
with self.assertRaisesRegex(ValueError, "containment details"):
|
||||
pilot.validate(record)
|
||||
record["findings"][0]["containment"] = {"owner": "Finding owner", "expiresAt": "2026-10-31T12:00:00Z", "rollbackTrigger": "Stop if the issue affects guest handling."}
|
||||
pilot.validate(record)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,82 +0,0 @@
|
||||
import hashlib
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
|
||||
class ReleaseRecordTests(unittest.TestCase):
|
||||
def test_writes_versions_checksum_and_immutable_image_ids(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
artifact = Path(directory) / "guestops-images.tar.gz"
|
||||
output = Path(directory) / "release-record.json"
|
||||
artifact.write_bytes(b"reviewed image archive")
|
||||
|
||||
subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(ROOT / "deploy" / "release_record.py"),
|
||||
"--artifact",
|
||||
str(artifact),
|
||||
"--commit",
|
||||
"a" * 40,
|
||||
"--api-image",
|
||||
"guestops-api:" + "a" * 40,
|
||||
"--api-id",
|
||||
"sha256:api",
|
||||
"--worker-image",
|
||||
"guestops-worker:" + "a" * 40,
|
||||
"--worker-id",
|
||||
"sha256:worker",
|
||||
"--output",
|
||||
str(output),
|
||||
],
|
||||
check=True,
|
||||
)
|
||||
|
||||
record = json.loads(output.read_text(encoding="utf-8"))
|
||||
self.assertEqual(record["version"], "0.1.0")
|
||||
self.assertEqual(record["commit"], "a" * 40)
|
||||
self.assertEqual(record["images"]["api"]["id"], "sha256:api")
|
||||
self.assertEqual(
|
||||
record["artifact"]["sha256"],
|
||||
hashlib.sha256(artifact.read_bytes()).hexdigest(),
|
||||
)
|
||||
|
||||
def test_rejects_abbreviated_commit(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
artifact = Path(directory) / "images.tar.gz"
|
||||
artifact.write_bytes(b"fixture")
|
||||
result = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(ROOT / "deploy" / "release_record.py"),
|
||||
"--artifact",
|
||||
str(artifact),
|
||||
"--commit",
|
||||
"abc123",
|
||||
"--api-image",
|
||||
"api:test",
|
||||
"--api-id",
|
||||
"sha256:api",
|
||||
"--worker-image",
|
||||
"worker:test",
|
||||
"--worker-id",
|
||||
"sha256:worker",
|
||||
"--output",
|
||||
str(Path(directory) / "record.json"),
|
||||
],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertIn("full 40-character Git SHA", result.stderr)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Generated
+2
-2
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "guestops-web",
|
||||
"version": "0.1.0",
|
||||
"version": "0.2.1",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "guestops-web",
|
||||
"version": "0.1.0",
|
||||
"version": "0.2.1",
|
||||
"dependencies": {
|
||||
"lucide-react": "^0.577.0",
|
||||
"react": "19.2.8",
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
{"name":"guestops-web","private":true,"version":"0.1.0","type":"module","scripts":{"dev":"vite --host 127.0.0.1","build":"tsc -b && vite build","check":"tsc -b"},"dependencies":{"react":"19.2.8","react-dom":"19.2.8","lucide-react":"^0.577.0"},"devDependencies":{"@types/react":"^19.2.0","@types/react-dom":"^19.2.0","@vitejs/plugin-react":"6.1.1","typescript":"~5.9.3","vite":"8.2.2"}}
|
||||
{"name":"guestops-web","private":true,"version":"0.2.1","type":"module","scripts":{"dev":"vite --host 127.0.0.1","build":"tsc -b && vite build","check":"tsc -b"},"dependencies":{"react":"19.2.8","react-dom":"19.2.8","lucide-react":"^0.577.0"},"devDependencies":{"@types/react":"^19.2.0","@types/react-dom":"^19.2.0","@vitejs/plugin-react":"6.1.1","typescript":"~5.9.3","vite":"8.2.2"}}
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { useEffect, useState } from 'react';
|
||||
import { api, type Hotel } from './api';
|
||||
import { hotelTime } from './time';
|
||||
type Payment={id:string;reference:string;email:string;description:string;amount:number;currency:string;state:string;detail:string;invoiceId:string;version:number;expiresAt:string;updatedAt:string;checkedAt:string|null};
|
||||
type Connection={configured:boolean;createsConfigured:boolean;sandbox:boolean;preview:boolean};
|
||||
type Props={hotel:Hotel;owner:boolean;busy:boolean;run:(f:()=>Promise<void>)=>Promise<void>;onHotel:(h:Hotel)=>void};
|
||||
@@ -19,7 +20,7 @@ export function PaymentsPage({hotel,owner,busy,run,onHotel}:Props){
|
||||
<section className="settings-card"><h2>Payment connection</h2><p>{connection?.preview?'Sample workspace: no invoices, emails or payments can be created.':connection?.configured?`NMI ${connection.sandbox?'sandbox':'production'} configuration is available.`:'Your administrator needs to configure this hotel’s NMI merchant account.'}</p><p className="small muted">GuestOps hotel ID: {hotel.id}</p><label className="checkbox-label"><input type="checkbox" checked={hotel.paymentsEnabled||false} disabled={busy||!owner||(!connection?.createsConfigured&&!hotel.paymentsEnabled)} onChange={e=>{const enabled=e.target.checked;run(async()=>{if(enabled&&!window.confirm('Enable reviewed NMI invoice creation after sandbox acceptance? Creating an invoice may email the customer.'))return;onHotel(await api<Hotel>('/payments/controls','PUT',{version:hotel.version,enabled}));});}}/>Allow owner-approved payment invoices</label><p className="small muted">Card details are entered on NMI’s hosted page. GuestOps never asks for a card number.</p></section>
|
||||
<div className="pms-columns"><section className="settings-card"><h2>Prepare a payment request</h2><form onSubmit={propose}><fieldset disabled={busy||!owner||!connection?.configured}><label>Unique payment reference<input value={reference} onChange={e=>setReference(e.target.value)} pattern="[A-Za-z0-9-]+" maxLength={80} required placeholder="WH-2481-DEPOSIT"/></label><label>Customer email<input type="email" value={email} onChange={e=>setEmail(e.target.value)} maxLength={254} required/></label><label>Description<input value={description} onChange={e=>setDescription(e.target.value)} maxLength={250} required placeholder="Deposit for reservation WH-2481"/></label><div className="form-grid"><label>Amount<input type="number" min="0.01" max="100000" step="0.01" required value={amount} onChange={e=>setAmount(e.target.value)}/></label><label>Currency<select value={currency} onChange={e=>setCurrency(e.target.value)}><option>GBP</option><option>EUR</option><option>USD</option></select></label></div><button className="button secondary">Prepare for review</button></fieldset></form><p className="small muted">Preparation saves a proposal only. Verify the agreed amount and booking terms separately; this does not reserve a room.</p></section>
|
||||
<section className="settings-card"><h2>Payment history</h2>{items.length===0&&<p>No payment requests yet.</p>}<div className="pms-history">{items.map(p=><button key={p.id} className={'pms-history-item '+(selected===p.id?'selected':'')} onClick={()=>{setSelected(p.id);setApproved(false);}}><strong>{p.reference} · {p.currency} {p.amount.toFixed(2)}</strong><span>{p.state==='NeedsReview'?'Needs verification':p.state==='Paid'?'Paid · reported by NMI':p.state} · {p.email}</span></button>)}</div></section></div>
|
||||
{current&&<section className="settings-card" aria-label="Payment request review"><h2>{current.state==='Review'?'Review this payment request':'Payment request status'}</h2><dl className="pms-reservation"><div><dt>Reference</dt><dd>{current.reference}</dd></div><div><dt>Customer</dt><dd>{current.email}</dd></div><div><dt>Amount</dt><dd>{current.currency} {current.amount.toFixed(2)}</dd></div><div><dt>Description</dt><dd>{current.description}</dd></div><div><dt>NMI invoice</dt><dd>{current.invoiceId||'Not confirmed'}</dd></div><div><dt>Last verified</dt><dd>{current.checkedAt?new Date(current.checkedAt).toLocaleString():'Not yet verified'}</dd></div></dl><p role="status"><strong>{current.state==='Paid'?'Paid · reported by NMI':current.state}</strong> — {current.detail}</p>
|
||||
{current&&<section className="settings-card" aria-label="Payment request review"><h2>{current.state==='Review'?'Review this payment request':'Payment request status'}</h2><dl className="pms-reservation"><div><dt>Reference</dt><dd>{current.reference}</dd></div><div><dt>Customer</dt><dd>{current.email}</dd></div><div><dt>Amount</dt><dd>{current.currency} {current.amount.toFixed(2)}</dd></div><div><dt>Description</dt><dd>{current.description}</dd></div><div><dt>NMI invoice</dt><dd>{current.invoiceId||'Not confirmed'}</dd></div><div><dt>Last verified</dt><dd>{current.checkedAt?hotelTime(current.checkedAt,hotel.timezone):'Not yet verified'}</dd></div></dl><p role="status"><strong>{current.state==='Paid'?'Paid · reported by NMI':current.state}</strong> — {current.detail}</p>
|
||||
{current.state==='Review'?<><div className="staff-note">Creating the invoice may email this customer a hosted payment link through NMI. GuestOps records the invoice and its status.</div><label className="checkbox-label"><input type="checkbox" checked={approved} onChange={e=>setApproved(e.target.checked)}/>I checked the recipient, amount and currency, and approve NMI emailing this payment request.</label><div className="form-actions"><button className="button secondary" disabled={busy||!owner||connection?.preview} onClick={()=>action('cancel')}>Cancel proposal</button><button className="button primary" disabled={busy||!owner||connection?.preview||!hotel.paymentsEnabled||!connection?.createsConfigured||!approved||Date.now()>new Date(current.expiresAt).getTime()} onClick={()=>action('create')}>Approve and create invoice</button></div><p className="small muted">Approval expires after fifteen minutes. A payment reference cannot be reused.</p></>:!['Cancelled','NotCreated'].includes(current.state)&&<><button className="button secondary" disabled={busy||!owner||connection?.preview||(current.state==='Creating'&&Date.now()-new Date(current.updatedAt).getTime()<300000)} onClick={()=>action('check')}>Verify with NMI</button><p className="small muted">This only reads invoice status. An interrupted creation can be checked after five minutes. Uncertain invoices are never automatically recreated.</p></>}
|
||||
<p className="small muted">A paid invoice is not confirmation of bank settlement or a hotel booking. Refunds, invoice closure and disputes are handled in the merchant portal.</p>
|
||||
</section>}
|
||||
|
||||
+2
-1
@@ -1,5 +1,6 @@
|
||||
import { useEffect, useState } from 'react';
|
||||
import { api, type Hotel } from './api';
|
||||
import { hotelTime } from './time';
|
||||
type Snapshot={id:string;reservationId:string;confirmation:string;guestName:string;arrival:string;departure:string;status:string;roomType:string;total:string;fetchedAt:string};
|
||||
type Change={id:string;reservationId:string;kind:string;arrival:string;departure:string;note:string;state:string;detail:string;version:number;updatedAt:string;expiresAt:string;before:Snapshot;after:Snapshot|null};
|
||||
type Connection={configured:boolean;writesConfigured:boolean;hotelCode:string;preview:boolean};
|
||||
@@ -21,7 +22,7 @@ export function PmsPage({hotel,owner,busy,run,onHotel}:Props){
|
||||
<section className="settings-card"><h2>OHIP connection</h2><p>{connection?.configured?`Connected configuration for property ${connection.hotelCode}. Lookup will verify access.`:connection?.preview?'Sample workspace: real PMS lookup and updates are disabled.':'Your administrator needs to configure this hotel’s OHIP connection.'}</p><p className="small muted">GuestOps hotel ID: {hotel.id}</p><label className="checkbox-label"><input type="checkbox" checked={hotel.pmsUpdatesEnabled||false} disabled={busy||!owner||(!connection?.writesConfigured&&!hotel.pmsUpdatesEnabled)} onChange={e=>{const enabled=e.target.checked;run(async()=>{if(enabled&&!window.confirm('Enable staff-approved PMS updates for this hotel? Only enable this after the configured OHIP sandbox has passed acceptance checks.'))return;onHotel(await api<Hotel>('/pms/controls','PUT',{version:hotel.version,enabled}));});}}/>Allow owner-approved PMS updates</label><p className="small muted">Lookup is available separately. Every change needs review; automatic PMS updates are off.</p></section>
|
||||
<div className="pms-columns"><section className="settings-card"><h2>Find a reservation</h2><form onSubmit={lookup}><label>Exact confirmation number<input value={confirmation} maxLength={80} pattern="[a-zA-Z0-9-]+" required onChange={e=>setConfirmation(e.target.value)} placeholder="For example, 12345678"/></label><button className="button primary" disabled={busy||!connection?.configured}>Look up reservation</button></form>
|
||||
{snapshot&&<><Reservation value={snapshot}/><form onSubmit={propose}><fieldset disabled={busy||!owner}><label>Proposed action<select value={kind} onChange={e=>setKind(e.target.value)}><option value="AddNote">Add an internal reservation note</option><option value="StayDates">Change stay dates</option></select></label>{kind==='AddNote'?<label>Note<textarea rows={4} maxLength={2000} value={note} required onChange={e=>setNote(e.target.value)}/></label>:<div className="form-grid"><label>New arrival<input type="date" value={arrival} required onChange={e=>setArrival(e.target.value)}/></label><label>New departure<input type="date" value={departure} required onChange={e=>setDeparture(e.target.value)}/></label></div>}<button className="button secondary">Prepare for review</button></fieldset></form><p className="small muted">Preparing a proposal does not update the PMS. Lookup and proposals expire after ten minutes.</p></>}
|
||||
</section><section className="settings-card"><h2>Change history</h2>{!changes.length&&<p>No PMS changes have been prepared yet.</p>}<div className="pms-history">{changes.map(c=><button className={'pms-history-item '+(selected===c.id?'selected':'')} key={c.id} onClick={()=>{setSelected(c.id);setChecked(false);}}><strong>{c.before.confirmation} · {c.kind==='AddNote'?'Reservation note':'Stay dates'}</strong><span>{c.state==='NeedsReview'?'Needs verification':c.state} · {new Date(c.updatedAt).toLocaleString()}</span></button>)}</div></section></div>
|
||||
</section><section className="settings-card"><h2>Change history</h2>{!changes.length&&<p>No PMS changes have been prepared yet.</p>}<div className="pms-history">{changes.map(c=><button className={'pms-history-item '+(selected===c.id?'selected':'')} key={c.id} onClick={()=>{setSelected(c.id);setChecked(false);}}><strong>{c.before.confirmation} · {c.kind==='AddNote'?'Reservation note':'Stay dates'}</strong><span>{c.state==='NeedsReview'?'Needs verification':c.state} · {hotelTime(c.updatedAt,hotel.timezone)}</span></button>)}</div></section></div>
|
||||
{current&&<section className="settings-card pms-review" aria-label="PMS change review"><h2>{current.state==='Review'?'Review this PMS change':'PMS change status'}</h2><Reservation value={current.before}/><div className="staff-note">{current.kind==='StayDates'?`Requested stay: ${current.arrival} to ${current.departure}`:`Add internal note: ${current.note}`}</div><p role="status"><strong>{current.state==='NeedsReview'?'Needs verification':current.state}</strong> — {current.detail}</p>{current.after&&<><h3>Latest observed PMS state</h3><Reservation value={current.after}/></>}{current.state==='Review'&&<>{current.kind==='StayDates'&&<label className="checkbox-label"><input type="checkbox" checked={checked} onChange={e=>setChecked(e.target.checked)}/>I checked availability, rate consequences and guest agreement in the PMS. GuestOps does not quote or guarantee a new price here.</label>}<div className="form-actions"><button className="button secondary" disabled={busy||!owner||connection?.preview} onClick={()=>action('cancel')}>Cancel proposal</button><button className="button primary" disabled={busy||!owner||!hotel.pmsUpdatesEnabled||!connection?.writesConfigured||(current.kind==='StayDates'&&!checked)||new Date(current.expiresAt)<new Date()} onClick={()=>action('apply')}>Approve and apply to PMS</button></div></>}{(current.state==='NeedsReview'||current.state==='Applying')&&<><button className="button secondary" disabled={busy||!owner||(current.state==='Applying'&&Date.now()-new Date(current.updatedAt).getTime()<300000)} onClick={()=>action('verify')}>Verify current PMS state</button><p className="small muted">An interrupted update can be checked after five minutes. Verification only reads the PMS; it never repeats the update.</p></>}<p className="small muted">Operation reference: {current.id}</p></section>}
|
||||
</div>;
|
||||
}
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
import { useEffect, useState } from 'react';
|
||||
import { api } from './api';
|
||||
import { hotelTime } from './time';
|
||||
type Member={id:string;name:string;email:string;role:string;active:boolean;pending:boolean;version:number;linkPurpose:string;linkExpiresAt:string|null};
|
||||
type Link={userId:string;link:string;expiresAt:string};
|
||||
export function TeamPage({owner}:{owner:boolean}) {
|
||||
export function TeamPage({owner,timeZone}:{owner:boolean;timeZone:string}) {
|
||||
const [members,setMembers]=useState<Member[]>([]),[name,setName]=useState(''),[email,setEmail]=useState(''),[error,setError]=useState(''),[busy,setBusy]=useState(false),[link,setLink]=useState<Link|null>(null),[copied,setCopied]=useState(false);
|
||||
async function refresh(){setMembers(await api<Member[]>('/team'));}
|
||||
useEffect(()=>{if(owner)refresh().catch(e=>setError(e.message));},[owner]);
|
||||
async function act(path:string,body:unknown){if(busy)return;setBusy(true);setError('');setLink(null);setCopied(false);try{const result=await api<Link|null>(path,'POST',body);if(result?.link)setLink(result);await refresh();}catch(e){setError(e instanceof Error?e.message:'Please try again.');}finally{setBusy(false);}}
|
||||
if(!owner)return <div className="page"><h1>Team access</h1><p>Your hotel owner manages staff accounts.</p></div>;
|
||||
return <div className="page settings-page"><div className="page-heading"><span className="eyebrow">A place for everyone</span><h1>Your team</h1><p>Give each colleague their own access to the hotel workspace.</p></div>{error&&<div className="alert" role="alert">{error}</div>}
|
||||
{link&&<section className="settings-card account-link" aria-label="Private account link"><h2>Share this link privately</h2><p><strong>For {members.find(m=>m.id===link.userId)?.email||"the selected colleague"}</strong></p><p>No email has been sent. Verify the colleague's identity and share only with the intended account holder. Anyone with this link can set their password.</p><p>Expires {new Date(link.expiresAt).toLocaleString()}. The link is shown here once.</p><label>Private account link<textarea readOnly rows={3} value={link.link} onFocus={e=>e.target.select()}/></label><div className="form-actions"><button className="button secondary" onClick={()=>setLink(null)}>Dismiss link</button><button className="button primary" onClick={async()=>{try{await navigator.clipboard.writeText(link.link);setCopied(true);}catch{setError('Select and copy the link manually.');}}}>{copied?'Copied':'Copy private link'}</button></div></section>}
|
||||
{link&&<section className="settings-card account-link" aria-label="Private account link"><h2>Share this link privately</h2><p><strong>For {members.find(m=>m.id===link.userId)?.email||"the selected colleague"}</strong></p><p>No email has been sent. Verify the colleague's identity and share only with the intended account holder. Anyone with this link can set their password.</p><p>Expires {hotelTime(link.expiresAt,timeZone)}. The link is shown here once.</p><label>Private account link<textarea readOnly rows={3} value={link.link} onFocus={e=>e.target.select()}/></label><div className="form-actions"><button className="button secondary" onClick={()=>setLink(null)}>Dismiss link</button><button className="button primary" onClick={async()=>{try{await navigator.clipboard.writeText(link.link);setCopied(true);}catch{setError('Select and copy the link manually.');}}}>{copied?'Copied':'Copy private link'}</button></div></section>}
|
||||
<section className="settings-card"><h2>Invite a colleague</h2><p className="muted">Staff can work on guest conversations. Owners manage hotel settings, integrations and approvals.</p><form onSubmit={e=>{e.preventDefault();void act('/team/invite',{name,email});}}><fieldset disabled={busy}><div className="form-grid"><label>Full name<input required minLength={2} maxLength={100} value={name} onChange={e=>setName(e.target.value)}/></label><label>Work email<input type="email" required maxLength={254} value={email} onChange={e=>setEmail(e.target.value)}/></label></div><div className="form-actions"><button className="button primary">Create invitation link</button></div></fieldset></form></section>
|
||||
<section className="settings-card"><h2>Workspace members</h2><div className="team-list">{members.map(m=><article className="team-member" key={m.id}><div><strong>{m.name}</strong><p>{m.email}</p><span className={'status '+(m.active?'Completed':'NeedsAttention')}>{m.role} · {m.active?'Active':m.pending?'Awaiting invitation acceptance':'Disabled'}</span>{m.linkPurpose&&<p className="small muted">{m.linkPurpose} link expires {new Date(m.linkExpiresAt!).toLocaleString()}</p>}</div>{m.role==='Staff'&&<div className="team-actions">{m.pending?<button className="button secondary compact" disabled={busy} onClick={()=>act('/team/invite',{name:m.name,email:m.email})}>New invitation</button>:<button className="button secondary compact" disabled={busy} onClick={()=>act(`/team/${m.id}/${m.active?'reset':'restore'}`,{version:m.version})}>{m.active?'Reset password':'Restore access'}</button>}{m.linkPurpose&&<button className="button secondary compact" disabled={busy} onClick={()=>act(`/team/${m.id}/revoke`,{version:m.version})}>Revoke link</button>}{m.active&&<button className="button secondary compact" disabled={busy} onClick={()=>{if(window.confirm(`Disable access for ${m.name}? Their existing sessions will end.`))void act(`/team/${m.id}/disable`,{version:m.version});}}>Disable access</button>}</div>}</article>)}</div><p className="small muted">New links replace earlier links. Password recovery ends existing sessions once accepted. Owner recovery is handled by your server administrator.</p></section>
|
||||
<section className="settings-card"><h2>Workspace members</h2><div className="team-list">{members.map(m=><article className="team-member" key={m.id}><div><strong>{m.name}</strong><p>{m.email}</p><span className={'status '+(m.active?'Completed':'NeedsAttention')}>{m.role} · {m.active?'Active':m.pending?'Awaiting invitation acceptance':'Disabled'}</span>{m.linkPurpose&&<p className="small muted">{m.linkPurpose} link expires {hotelTime(m.linkExpiresAt!,timeZone)}</p>}</div>{m.role==='Staff'&&<div className="team-actions">{m.pending?<button className="button secondary compact" disabled={busy} onClick={()=>act('/team/invite',{name:m.name,email:m.email})}>New invitation</button>:<button className="button secondary compact" disabled={busy} onClick={()=>act(`/team/${m.id}/${m.active?'reset':'restore'}`,{version:m.version})}>{m.active?'Reset password':'Restore access'}</button>}{m.linkPurpose&&<button className="button secondary compact" disabled={busy} onClick={()=>act(`/team/${m.id}/revoke`,{version:m.version})}>Revoke link</button>}{m.active&&<button className="button secondary compact" disabled={busy} onClick={()=>{if(window.confirm(`Disable access for ${m.name}? Their existing sessions will end.`))void act(`/team/${m.id}/disable`,{version:m.version});}}>Disable access</button>}</div>}</article>)}</div><p className="small muted">New links replace earlier links. Password recovery ends existing sessions once accepted. Owner recovery is handled by your server administrator.</p></section>
|
||||
</div>;
|
||||
}
|
||||
type Setup={preview:boolean;steps:{title:string;detail:string;path:string;complete:boolean;optional:boolean}[]};
|
||||
|
||||
+5
-3
@@ -1,4 +1,4 @@
|
||||
import React, { useEffect, useState } from 'react';
|
||||
import React, { useEffect, useRef, useState } from 'react';
|
||||
import { createRoot } from 'react-dom/client';
|
||||
import { Inbox, BookOpen, Settings, Activity as ActivityIcon, Search, ArrowUpRight, ChevronDown, Check, CheckCheck, Clock3, FileText, LogOut, RefreshCw, ArrowLeft, Plus, X, Mail, ShieldCheck, Save, CircleHelp, Banknote, Building2, ChevronRight } from 'lucide-react';
|
||||
import { api, session, type Session, type Hotel, type Conversation, type ConversationPage, type Knowledge, type Activity, type Mailboxes } from './api';
|
||||
@@ -19,6 +19,7 @@ const date = (value: string,timeZone: string) => new Date(value).toLocaleString(
|
||||
function App() {
|
||||
const [auth,setAuth] = useState<Session|null>(null), [error,setError] = useState(''), [notice,setNotice] = useState('');
|
||||
const [hotel,setHotel] = useState<Hotel|null>(null), [page,setPage] = useState(location.pathname === '/' ? '/inbox' : location.pathname), [busy,setBusy] = useState(false);
|
||||
const pageRef=useRef(page);
|
||||
const [conversations,setConversations] = useState<Conversation[]>([]), [knowledge,setKnowledge] = useState<Knowledge[]>([]), [activity,setActivity] = useState<Activity[]>([]), [mailboxes,setMailboxes] = useState<Mailboxes>({ configured:false,items:[] });
|
||||
const [conversationCursor,setConversationCursor]=useState<string|null>(null);
|
||||
const [loaded,setLoaded] = useState(false);
|
||||
@@ -27,7 +28,8 @@ function App() {
|
||||
setHotel(h);setConversations(c.items);setConversationCursor(c.nextCursor);setKnowledge(k);setActivity(a);setMailboxes(m);setLoaded(true);
|
||||
}
|
||||
async function moreConversations(){if(!conversationCursor)return;const page=await api<ConversationPage>('/conversations/page?cursor='+encodeURIComponent(conversationCursor));setConversations(old=>[...old,...page.items.filter(item=>!old.some(existing=>existing.id===item.id))]);setConversationCursor(page.nextCursor);}
|
||||
useEffect(() => { session().then(setAuth).catch(e=>setError(e.message)); const expired=()=>{setAuth(null);session().then(setAuth).catch(()=>{});setError('Your session has ended. Sign in again.');}; window.addEventListener('session-expired',expired); const pop=()=>setPage(location.pathname);window.addEventListener('popstate',pop);return()=>{window.removeEventListener('session-expired',expired);window.removeEventListener('popstate',pop);}; },[]);
|
||||
useEffect(()=>{pageRef.current=page;},[page]);
|
||||
useEffect(() => { session().then(setAuth).catch(e=>setError(e.message)); const expired=()=>{setAuth(null);session().then(setAuth).catch(()=>{});setError('Your session has ended. Sign in again.');}; window.addEventListener('session-expired',expired); const pop=()=>{if(!window.dispatchEvent(new Event('workspace-navigate',{cancelable:true}))){history.pushState({},'',pageRef.current);return;}setPage(location.pathname==='/'?'/inbox':location.pathname);};window.addEventListener('popstate',pop);return()=>{window.removeEventListener('session-expired',expired);window.removeEventListener('popstate',pop);}; },[]);
|
||||
useEffect(()=>{if(auth?.user) refresh().catch(e=>setError(e.message));},[auth?.user?.id]);
|
||||
useEffect(()=>{if(!notice)return;const timer=setTimeout(()=>setNotice(''),4500);return()=>clearTimeout(timer);},[notice]);
|
||||
async function run(action:()=>Promise<void>) { if(busy)return; setBusy(true);setError('');try{await action();}catch(e){setError(e instanceof Error?e.message:'Something went wrong.');}finally{setBusy(false);} }
|
||||
@@ -51,7 +53,7 @@ function App() {
|
||||
<main className="main">
|
||||
<header className="topbar"><span><span className="breadcrumb">Workspace</span><ChevronRight size={14}/>{page==='/inbox'?'Inbox':page==='/knowledge'?'Hotel knowledge':page==='/activity'?'Activity':page==='/reservations'?'Reservations':page==='/payments'?'Payments':page==='/automation'?'FAQ automation':page==='/team'?'Your team':page==='/setup'?'Hotel setup':page==='/health'?'Workspace health':'Settings'}</span><div className="topbar-right">{auth.preview&&<span className="preview-pill">Preview · sample data</span>}<span className="draft-mode"><span/>{hotel?.autoReplyMode==='Live'?'FAQ auto-replies enabled':hotel?.staffSendingEnabled?'Staff-approved sending':'Draft-only mode'}</span><button className="icon-button" aria-label="Refresh workspace" disabled={busy} onClick={()=>run(refresh)}><RefreshCw size={17}/></button></div></header>
|
||||
{errorBox}{notice&&<div className="toast" role="status"><Check size={17}/>{notice}</div>}
|
||||
{!loaded?<div className="loading"><p>Loading your hotel…</p></div>:page==='/health'?<OperationsPage owner={auth.user.role==='Owner'} go={go}/>:page==='/team'?<TeamPage owner={auth.user.role==='Owner'}/>:page==='/setup'?<OnboardingPage owner={auth.user.role==='Owner'} go={go}/>:page==='/inbox'?<InboxPage hotel={hotel!} mailboxes={mailboxes} conversations={conversations} hasMore={!!conversationCursor} loadMore={()=>run(moreConversations)} knowledge={knowledge} busy={busy} run={run} onUpdate={c=>setConversations(old=>old.map(x=>x.id===c.id?c:x))} notify={setNotice} go={go}/>:page==='/automation'?<AutomationPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/payments'?<PaymentsPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/reservations'?<PmsPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/knowledge'?<KnowledgePage items={knowledge} canEdit={auth.user.role==='Owner'} busy={busy} run={run} onUpdate={item=>setKnowledge(old=>old.some(x=>x.id===item.id)?old.map(x=>x.id===item.id?item:x):[...old,item])} notify={setNotice}/>:page==='/activity'?<div className="page"><PageHeading eyebrow="A clear record" title="Workspace activity" text="Changes made by your team, in one place."/><div className="activity-list">{activity.length?activity.map(a=><div className="activity-row" key={a.id}><span className="activity-icon"><Check size={18}/></span><div><strong>{a.action}</strong><p>{a.userName}</p></div><time>{date(a.at,hotel!.timezone)}</time></div>):<Empty title="No activity yet" text="Changes to your workspace will appear here."/>}</div></div>:<SettingsPage onMailboxes={setMailboxes} hotel={hotel!} mailboxes={mailboxes} preview={auth.preview} owner={auth.user.role==='Owner'} busy={busy} run={run} onSave={h=>{setHotel(h);setNotice('Hotel settings saved.');}}/>}
|
||||
{!loaded?<div className="loading"><p>Loading your hotel…</p></div>:page==='/health'?<OperationsPage owner={auth.user.role==='Owner'} go={go}/>:page==='/team'?<TeamPage owner={auth.user.role==='Owner'} timeZone={hotel!.timezone}/>:page==='/setup'?<OnboardingPage owner={auth.user.role==='Owner'} go={go}/>:page==='/inbox'?<InboxPage hotel={hotel!} mailboxes={mailboxes} conversations={conversations} hasMore={!!conversationCursor} loadMore={()=>run(moreConversations)} knowledge={knowledge} busy={busy} run={run} onUpdate={c=>setConversations(old=>old.map(x=>x.id===c.id?c:x))} notify={setNotice} go={go}/>:page==='/automation'?<AutomationPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/payments'?<PaymentsPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/reservations'?<PmsPage hotel={hotel!} owner={auth.user.role==='Owner'} busy={busy} run={run} onHotel={setHotel}/>:page==='/knowledge'?<KnowledgePage items={knowledge} canEdit={auth.user.role==='Owner'} busy={busy} run={run} onUpdate={item=>setKnowledge(old=>old.some(x=>x.id===item.id)?old.map(x=>x.id===item.id?item:x):[...old,item])} notify={setNotice}/>:page==='/activity'?<div className="page"><PageHeading eyebrow="A clear record" title="Workspace activity" text="Changes made by your team, in one place."/><div className="activity-list">{activity.length?activity.map(a=><div className="activity-row" key={a.id}><span className="activity-icon"><Check size={18}/></span><div><strong>{a.action}</strong><p>{a.userName}</p></div><time>{date(a.at,hotel!.timezone)}</time></div>):<Empty title="No activity yet" text="Changes to your workspace will appear here."/>}</div></div>:<SettingsPage onMailboxes={setMailboxes} hotel={hotel!} mailboxes={mailboxes} preview={auth.preview} owner={auth.user.role==='Owner'} busy={busy} run={run} onSave={h=>{setHotel(h);setNotice('Hotel settings saved.');}}/>}
|
||||
</main>
|
||||
</div>;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user