Commissioning the cloud service

Who this page is for

This page is for the person who operates your organisation’s BioTrack cloud service, usually an Alcra engineer. It assumes access to the Cloudflare account and the cloud/ folder of the BioTrack source. BioTrack administrators at a site do not need it; see Connect and activate instead.

This page covers the commissioner’s side of cloud reporting: preparing a tenant and site, issuing activation codes, revoking installations and changing retention, with the safeguards each command enforces.

What you operate

The cloud service is a Cloudflare Worker (biotrack-cloud-api) with a D1 database (biotrack-cloud). The Worker accepts signed requests from BioTrack installations and runs a daily scheduled job at 02:17 UTC that enforces retention and expires stale key rotations. The request format is described in cloud/openapi.yaml, which is still marked as a draft.

The commissioning commands run from the cloud/ folder with Node.js 22 and npm 11. Each one calls Wrangler against the remote D1 database, so your Wrangler session must be authenticated to the right Cloudflare account. Every command:

• accepts only the flags it lists, each once, and prints its usage and exits if anything is missing or malformed;
• takes an --actor identifier for the audit trail (letters, digits and @ . _ -, up to 128 characters);
• changes exactly one row, or reports that nothing changed and exits with an error;
• refuses to report success if Wrangler’s output cannot be read.

Prepare the tenant and site

Before issuing a code, create the tenant (organisation) and its site in D1 through your controlled Cloudflare administration process. There is no BioTrack command for this step.

• A tenant has a name and a retention period of 1, 3, 5 or 7 years. D1 refuses any other value.
• A site belongs to one tenant and has a name and a time zone.

Record both UUIDs. You need them for the activation code.

Issue an activation code

npm run activation-code:create -- \
  --tenant <tenant-uuid> \
  --site <site-uuid> \
  --actor <commissioner-id> \
  --hours 24

• --hours is optional. The default is 24 and the allowed range is 1 to 168 (seven days).
• The command creates a random 256-bit code and stores only its SHA-256 hash in D1. It succeeds only if the site belongs to the tenant; otherwise it reports No code was created and shows nothing.
• On success it prints the code once. The plaintext is not stored and cannot be shown again.

Send the code to the site administrator through an approved private channel. Never put it in tickets, logs or shared chats.

When the administrator selects Activate, the installation sends its installation ID and public key, signed with the matching private key, along with a fresh timestamp and one-time value. In a single D1 transaction the Worker registers the key against the tenant and site from the code record, marks the code used, and writes an audit record. Codes can be used once. Wrong, expired and already-used codes all get the same response.

Ask the administrator to confirm the Site shown under Installation identity afterwards.

Revoke an installation

Revoke an installation when its computer is retired, lost or suspected to be compromised.

1. Get the installation UUID. The site administrator can read it under Public enrollment identity (for manual commissioning or support) in Settings → Cloud reporting.

2. Get the customer-approved change or incident reference.

3. Run:

   npm run installation:revoke -- \
     --tenant <tenant-uuid> \
     --installation <installation-uuid> \
     --actor <commissioner-id> \
     --reason "Workstation decommissioned under change CHG-1234" \
     --confirm REVOKE

4. Check that the command reports exactly one revoked installation.

5. Confirm with the site that the installation now shows Retrying in Settings → Cloud reporting.

The tenant and installation must match and the installation must still be active. The reason must be 10 to 500 characters. One D1 insert records an immutable revocation, marks the installation revoked, expires any pending key rotation, and writes an audit record with the actor, reason and time. From then on the Worker refuses every sync, state and key-rotation request from that installation. The computer keeps collecting attendance locally.

Revocation cannot be reversed with this command. If it reports no change or an unreadable result, stop and investigate. Do not issue a replacement activation code until you have independently confirmed the intended tenant and site.

Change retention

npm run retention:change -- \
  --tenant <tenant-uuid> \
  --from 3 \
  --to 1 \
  --actor <commissioner-id> \
  --reason "Customer-approved change CHG-1235" \
  --confirm CHANGE-RETENTION

• --from must match the tenant’s current value, so a command prepared before someone else’s change cannot overwrite it silently. --from and --to must differ and both must be 1, 3, 5 or 7.
• The reason must be 10 to 500 characters.
• One D1 insert changes the tenant’s policy and writes immutable evidence of the old and new values, actor, reason and time, plus an audit record. The command prints the audit UUID; record it.
• D1 rejects direct edits to the tenant’s retention value and any attempt to change or delete the evidence.

Reducing retention deletes data

A shorter period takes effect at the next daily run, which permanently deletes cloud records older than the new cutoff. Get the customer’s written approval and a confirmed backup or export decision before you run it.

Audit trail

D1 keeps evidence for each commissioning event:

Event	Evidence
Activation	Code redemption record and an audit record
Key rotation	Versioned public-key history and an audit record
Revocation	Immutable revocation record and an audit record
Retention change	Immutable policy-change record and an audit record
Retention enforcement	One run record per tenant with the cutoff and the number of items deleted, kept for about eight years

Audit records fall under the tenant’s retention period like other cloud data.

Before production activation

The following items are still open and should be completed before any installation is activated against production:

• Repeat the installation revocation exercise, which passes locally, against the deployed D1 database.
• Repeat the 30-day offline catch-up, lost-acknowledgement and tenant-isolation exercise, which passes locally, against the deployed D1 database.
• Enrol the customer’s recovery administrator and passkey.
• Test rate limiting and operational alerts.
• Build the portal and read-only authorisation layer.

The Worker’s /v1/recovery/ endpoints are reserved and return “not implemented” until commissioning trust is configured.

Data and retention The payload allowlist, tenant scoping and retention rules the Worker enforces.