Attestation (attestation.*)
One of the poq.toml spec sections.
Signed PoQ Report export — the output phase after review completes: schema, signing key, payload fields, and output format.
attestation
Signed PoQ Report export settings. This section controls how the signed YAML attestation is constructed and formatted for download.
[attestation]
schema_version = "poq.attestation/v1"
signing_key_id = "poq-prod-2024"
[attestation.payload]
include_per_validator_votes = true
include_rationales_inline = false
outputs_alias = "findings"
[attestation.payload.outputs]
report_hash = "audit_report_hash"
severity_in_report = "proposed_severity"
repo_url = "repository"
commit_hash = "commit_sha"
[[attestation.metadata]]
field_name = "report_source"
channel = "portal"
sender = "0xC921CF11A568142223a52C7f0b4AE7023fb3326B"
[attestation.output]
strategy = "aggregated"
delimiter = "\n\n---\n"
fence = "yaml"
Attestation fields
| option | accepts | required | description | example |
|---|---|---|---|---|
schema_version | string | yes | Must be poq.attestation/v1 for the current signer. | "poq.attestation/v1" |
signing_key_id | string | yes | Matches the server-configured signing key id (e.g. sapien-prod-ed25519-v1). | "poq-prod-2024" |
payload | table | no | Nested table for payload options (see below). | [attestation.payload] |
metadata | array | no | Extra signed report header fields (see below). | [[attestation.metadata]] |
output | table | no | Download formatting and emit strategy (see below). | [attestation.output] |
The [attestation.payload] block
| option | accepts | required | description | example |
|---|---|---|---|---|
include_per_validator_votes | bool | no | When true, the signed YAML includes each validator's specific answer for every rubric dimension. | true |
include_rationales_inline | bool | no | When false, rationales use opaque references instead of inline text. | false |
include_datapoint_id | bool | no | Tri-state (unset/true/false). When true, each finding in the signed payload carries its datapoint id. | true |
outputs_alias | string | no | Names the main findings array in the YAML. Use "findings" for security audits; defaults to "sub_reports". | "findings" |
The [attestation.payload.outputs] block
Maps attestation fields to canonical field names defined in [ingestion.fields].
| option | accepts | required | description | example |
|---|---|---|---|---|
finding_id | string | no | Field holding the stable per-finding identifier in the report. | "finding_id" |
report_hash | string | no | Field holding the hash of the original input document. | "audit_report_hash" |
severity_in_report | string | no | Field holding the original tool-reported severity. | "proposed_severity" |
repo_url | string | no | Field holding the repository URL (emitted in audit_target). | "repository" |
commit_hash | string | no | Field holding the pinned commit SHA (emitted in audit_target). | "commit_sha" |
The [[attestation.metadata]] block
Used for literal top-level YAML metadata blocks.
| option | accepts | required | description | example |
|---|---|---|---|---|
field_name | string | yes | The top-level YAML key name (e.g. report_source). | "report_source" |
| (others) | any | no | Any other keys in the table are emitted as key-value pairs under field_name. | channel = "portal" |
The [attestation.output] block
| option | accepts | required | description | example |
|---|---|---|---|---|
strategy | enum | no | How the attestation is emitted: aggregated (one signed report) or in_place (appended to each input). Omit to use the server default. | "aggregated" |
delimiter | string | no | String inserted between the original document and the attestation in in_place mode. | "\n\n---\n" |
fence | enum | no | Optional markdown fence type. Only "yaml" is supported today (wraps the attestation in yaml ... ). | "yaml" |