Device capability nodes

Device capability nodes

The Device tab in the Holaryn pocket console can make a paired phone available for a few narrow
actions: take one new camera photo, read one location snapshot, show a local notification, or
upload one file you select. The phone is not another agent and does not accept arbitrary tools.

Start a device node

First enable and pair mobile supervision. Open the pocket console over
HTTPS, select Device, then select Start serving. The page reports four independent facts:

• whether this paired device is active;
• whether the browser says the capability is foreground/background available;
• the OS permission (prompt, granted, denied, restricted, or unavailable); and
• the Holaryn server grant (ask, allow, or deny).

Pairing does not grant camera, location, or notification permission. Use the corresponding
Enable… control on the phone; the browser/OS owns the resulting prompt. File selection remains
user-mediated for every request.

From a terminal on the Holaryn host, inspect and set grants:

holaryn device list
holaryn device grant <device-id> camera.capture allow
holaryn device grant <device-id> location.snapshot ask --expires-in 3600
holaryn device activity --device-id <device-id>

Use deny to block a capability even if its OS permission remains granted.

Invoke a capability

In chat, ask Holaryn for the device action and review the ordinary tool approval. For example:

Use my paired phone's location snapshot to tell me the local weather. Do not request precise
location if city-level accuracy is enough.

The approval and phone request identify the exact device, capability, parameters, expected data
movement, and expiry. On the phone, expand Exact parameters, then choose Use this phone or
Deny. Camera, location, file, and other sensitive actions run only while the PWA is visible.
A persistent red activity indicator remains visible while a camera, location, or transfer action
is in progress.

For an operator/API smoke test:

holaryn device invoke <device-id> notification.send \
  --parameters '{"title":"Holaryn","body":"Nightly verification finished"}'

The phone claims the request, displays the exact title/body, and waits for Use this phone.
Successful output looks like:

{"capability":"notification.send","device_id":"…","invocation_id":"dinv_…","state":"queued"}

Camera and selected-file transfers

The camera produces one JPEG after device confirmation. Selected file opens the OS picker and
uploads only the file chosen for that request. Transfers are split into hashed chunks. A retry
asks which chunks are missing, and completion verifies the total byte count and final SHA-256
before Holaryn publishes an artifact. Cancelling or failing integrity checks publishes nothing.

The server stores bounded provenance: device, capability, invocation, device observation time,
server receipt time, exact parameter digest, approval state, payload digest, and artifact ID. The
activity log stores state changes but not the photo, location, notification body, or file content.

Offline, cancellation, and lost devices

Sensitive device requests do not execute from an offline queue. They expire, and reconnect does
not revive them. A notification capability may advertise safe offline queueing, but an expired,
cancelled, replayed, or revoked request still fails closed.

Cancel queued or running work from the host:

holaryn device cancel <invocation-id>

If a device is lost, use:

holaryn device revoke <device-id> --lost

That marks the node lost, cancels pending device work, and revokes the shared mobile credential
and sessions. Where supported, holaryn device wipe <device-id> asks the PWA to remove its local
credential and capability state; the phone displays the request and acknowledges it. This is not
a claim to erase an entire phone.

Manual release smoke test

On a real paired phone:

1. Start serving and confirm camera/location begin as prompt until the OS prompt is accepted.
2. Allow the four reference capabilities on the server.
3. Complete one camera, location, notification, and selected-file invocation.
4. Put the PWA in the background and confirm camera/location/file requests do not run.
5. Interrupt a multi-chunk upload, resume missing chunks, then cancel a second transfer.
6. Replay a resolved request or wait past expiry and confirm the phone cannot execute it.
7. Revoke the device and confirm its existing session immediately returns unauthorized.
8. Navigate with a keyboard or screen reader and confirm permission, grant, active-use, expiry,
   and error states are announced without relying on color.