cloud evidence¶

NAME¶

phyware cloud evidence — stakeholder query commands for sealed Evidence Lockers.

SYNOPSIS¶

phyware cloud evidence events    [OPTIONS] <LOCKER_ID> --grant-token <TOKEN>
phyware cloud evidence manifest  [OPTIONS] <LOCKER_ID> --grant-token <TOKEN>
phyware cloud evidence verify    [OPTIONS] <LOCKER_ID> --grant-token <TOKEN>

DESCRIPTION¶

These commands let an authorized stakeholder (regulator, insurer, legal counsel, auditor, or operator) query a sealed Evidence Locker without needing a tenant API key. Authentication is via a Bearer grant token issued by the locker operator with phyware cloud lockers grants issue. See issue #77.

events¶

Returns events copied into the locker (paginated). Each query is recorded in the locker's append-only audit log.

manifest¶

Returns the locker manifest (scope, event count, Merkle root, sealed timestamp). Lightweight call — no event payloads.

verify¶

Recomputes the Merkle root from the locker's events and compares it against the value sealed at seal time. Use to verify the locker has not been tampered with.

OPTIONS¶

Flag	Type	Required	Default	Env
`--url`	string	No	`http://localhost:8000`	`PHYCLOUD_URL`
`--api-key`	string	No	—	`PHYCLOUD_API_KEY`
`--output`	enum	No	`table`	—
`--grant-token`	string	Yes	—	`PHYCLOUD_GRANT_TOKEN`
`--offset`	integer	No	`0`	—
`--limit`	integer	No	`100`	—

ARGUMENTS¶

Name	Required	Description
`LOCKER_ID`	Yes	Unique locker identifier

INPUT¶

None — all parameters are passed as flags / arguments.

OUTPUT¶

events returns an array of:

Field	Type	Description
`id`	integer	Locker-event row id
`event_id`	string	Original PhyCloud event id
`content_hash`	string	SHA-256 content hash of the event
`previous_hash`	string	Hash of the previous event in the chain
`sequence_number`	integer	Sequence number from PhyCloud
`event_data`	object	Full UDM event payload
`original_ingested_at`	string	When PhyCloud first ingested the event
`copied_at`	string	When the event was copied into the locker

manifest returns:

Field	Type	Description
`locker_id`	string	Unique locker identifier
`name`	string	Locker name
`status`	string	Locker status
`event_count`	integer	Number of events
`merkle_root`	string	Sealed Merkle root

verify returns:

Field	Type	Description
`valid`	boolean	True if recomputed root matches stored
`computed_root`	string	Recomputed Merkle root
`stored_root`	string	Merkle root sealed at creation time

EXIT CODES¶

Code	Meaning
`0`	Success
`1`	Generic / connection error
`2`	Authentication / authorisation error
`3`	Resource not found
`4`	Validation error
`5`	Server-side error

EXAMPLES¶

# Stakeholder workflow with a grant token
export PHYCLOUD_GRANT_TOKEN=<token-from-grants-issue>

# 1. Inspect the manifest
phyware cloud evidence manifest lk_abc123

# 2. Verify integrity
phyware cloud evidence verify lk_abc123

# 3. Pull events
phyware cloud evidence events lk_abc123 --output json

# Paginate through events
phyware cloud evidence events lk_abc123 --offset 100 --limit 50

# Extract content hashes
phyware cloud evidence events lk_abc123 -o json | jq '[.[].content_hash]'

# Verify and check the boolean flag
phyware cloud evidence verify lk_abc123 -o json | jq -r '.valid'

AGENT NOTES¶

--grant-token (or PHYCLOUD_GRANT_TOKEN) is required — the tenant --api-key is ignored on these endpoints. Every query is recorded in the locker's audit log under the stakeholder's name. Use manifest first (lightweight), then verify, then events (which can be large).

ERRORS¶

Code	Message	Remediation
`FORBIDDEN`	Invalid or insufficient grant token	Verify the grant token has `read_events`
`NOT_FOUND`	Locker not found	Check `LOCKER_ID`
`EXPIRED`	Grant token expired or revoked	Request a fresh grant from the locker operator