Przejdź do treści

Node Address Attestation v1

Source schema: doc/schemas/node-address-attestation.v1.schema.json

Fallback signed-evidence artifact for a single normalized Node address claim. Seed Directory remains the trusted primary source for node address resolution; this artifact carries bounded evidence that may help a receiver make a local degraded-mode dial decision when Seed Directory is unavailable. It belongs to the broader Orbiplex signed-credential/passport family but is intentionally not encoded as capability-passport.v1: capability passports grant authority, while address attestations carry freshness-bound evidence about observed reachability. The signed address claim is the deterministic canonical JSON of {target/node-id, endpoint}; evidence signatures bind to claim/digest and their own freshness metadata.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: node-address-attestation.v1 Schema discriminator. MUST be exactly node-address-attestation.v1.
attestation/id yes string Stable identifier for this assembled evidence packet. Recommended construction: attestation:node-address:<claim-digest-suffix>:<unix-nanos-or-random>.
target/node-id yes string Node whose endpoint is being attested. MUST match the node id in the embedded or referenced node-advertisement.v1 when that advertisement is available.
endpoint yes ref: #/$defs/normalizedEndpoint Normalized endpoint claim being attested. The claim digest is computed from canonical JSON containing only target/node-id and this normalized endpoint object. Receivers MUST normalize before digest comparison; raw endpoint URLs from advertisements are not authoritative for digesting.
claim/digest yes ref: #/$defs/sha256Digest Digest of the normalized address claim: sha256:<base64url-no-pad> over canonical JSON { "target/node-id": ..., "endpoint": ... }. Every evidence entry MUST repeat this same digest.
node-advertisement no object Optional full node-advertisement.v1 payload for the target node. Its own signature remains governed by node-advertisement.v1; this attestation does not reinterpret that signature.
node-advertisement/ref no string Optional content-addressed reference to the target node advertisement when the full advertisement is not embedded.
advertisement/digest yes ref: #/$defs/sha256Digest Digest of the target node-advertisement.v1 payload or referenced blob. Used for deduplication and for checking that peer evidence refers to the same signed advertisement.
observed/at yes string Timestamp at which the assembler most recently observed or accepted any evidence in this packet. Informational for ordering; freshness is enforced from each evidence entry and the envelope expires/at.
expires/at yes string Timestamp after which this assembled packet MUST be treated as expired. It SHOULD NOT exceed the earliest authoritative expiry among the evidence entries that make the packet useful under local policy.
evidence yes array Signed evidence entries for this address claim. Unknown evidence kinds are not allowed in v1; new authority-bearing evidence classes require a new schema version or a formally registered extension.
assembler/node-id no string Optional node that assembled the evidence packet. The assembler is a courier/curator, not an authority, unless it also appears as a valid evidence signer.
signature no ref: #/$defs/ed25519Signature Optional envelope signature by assembler/node-id over the deterministic canonical JSON of the attestation with signature omitted. This proves packet assembly integrity, not address authority. Receivers MUST evaluate evidence[] independently.
policy_annotations no object Optional local or federation-local annotations. MUST NOT alter core evidence semantics.

Definitions

Definition Shape Description
sha256Digest string sha256: followed by unpadded base64url-encoded SHA-256 bytes.
normalizedEndpoint object Canonical endpoint descriptor used for address-claim hashing. It intentionally avoids storing a raw URL as the semantic claim because equivalent URLs can differ textually.
evidenceEntry object Signed evidence statement for one normalized address claim. The signature covers the evidence statement without the signature field and binds the signer, claim digest, evidence kind, freshness window, and any endpoint certificate observation. signed/at MUST be less than or equal to expires/at. When endpoint/certificate is present, endpoint/certificate.verified/at MUST fall inside the evidence freshness window with at most 16 seconds of clock-skew tolerance.
endpointCertificateEvidence object
ed25519Signature object Ed25519 signature object used by envelope and evidence signatures.

Conditional Rules

Rule 1

Constraint:

{
  "description": "The attestation must carry either a full target node advertisement or a content-addressed reference to one.",
  "oneOf": [
    {
      "required": [
        "node-advertisement"
      ]
    },
    {
      "required": [
        "node-advertisement/ref"
      ]
    }
  ]
}

Field Semantics

schema

  • Required: yes
  • Shape: const: node-address-attestation.v1

Schema discriminator. MUST be exactly node-address-attestation.v1.

attestation/id

  • Required: yes
  • Shape: string

Stable identifier for this assembled evidence packet. Recommended construction: attestation:node-address:<claim-digest-suffix>:<unix-nanos-or-random>.

target/node-id

  • Required: yes
  • Shape: string

Node whose endpoint is being attested. MUST match the node id in the embedded or referenced node-advertisement.v1 when that advertisement is available.

endpoint

  • Required: yes
  • Shape: ref: #/$defs/normalizedEndpoint

Normalized endpoint claim being attested. The claim digest is computed from canonical JSON containing only target/node-id and this normalized endpoint object. Receivers MUST normalize before digest comparison; raw endpoint URLs from advertisements are not authoritative for digesting.

claim/digest

  • Required: yes
  • Shape: ref: #/$defs/sha256Digest

Digest of the normalized address claim: sha256:<base64url-no-pad> over canonical JSON { "target/node-id": ..., "endpoint": ... }. Every evidence entry MUST repeat this same digest.

node-advertisement

  • Required: no
  • Shape: object

Optional full node-advertisement.v1 payload for the target node. Its own signature remains governed by node-advertisement.v1; this attestation does not reinterpret that signature.

node-advertisement/ref

  • Required: no
  • Shape: string

Optional content-addressed reference to the target node advertisement when the full advertisement is not embedded.

advertisement/digest

  • Required: yes
  • Shape: ref: #/$defs/sha256Digest

Digest of the target node-advertisement.v1 payload or referenced blob. Used for deduplication and for checking that peer evidence refers to the same signed advertisement.

observed/at

  • Required: yes
  • Shape: string

Timestamp at which the assembler most recently observed or accepted any evidence in this packet. Informational for ordering; freshness is enforced from each evidence entry and the envelope expires/at.

expires/at

  • Required: yes
  • Shape: string

Timestamp after which this assembled packet MUST be treated as expired. It SHOULD NOT exceed the earliest authoritative expiry among the evidence entries that make the packet useful under local policy.

evidence

  • Required: yes
  • Shape: array

Signed evidence entries for this address claim. Unknown evidence kinds are not allowed in v1; new authority-bearing evidence classes require a new schema version or a formally registered extension.

assembler/node-id

  • Required: no
  • Shape: string

Optional node that assembled the evidence packet. The assembler is a courier/curator, not an authority, unless it also appears as a valid evidence signer.

signature

  • Required: no
  • Shape: ref: #/$defs/ed25519Signature

Optional envelope signature by assembler/node-id over the deterministic canonical JSON of the attestation with signature omitted. This proves packet assembly integrity, not address authority. Receivers MUST evaluate evidence[] independently.

policy_annotations

  • Required: no
  • Shape: object

Optional local or federation-local annotations. MUST NOT alter core evidence semantics.

Definition Semantics

$defs.sha256Digest

  • Shape: string

sha256: followed by unpadded base64url-encoded SHA-256 bytes.

$defs.normalizedEndpoint

  • Shape: object

Canonical endpoint descriptor used for address-claim hashing. It intentionally avoids storing a raw URL as the semantic claim because equivalent URLs can differ textually.

$defs.evidenceEntry

  • Shape: object

Signed evidence statement for one normalized address claim. The signature covers the evidence statement without the signature field and binds the signer, claim digest, evidence kind, freshness window, and any endpoint certificate observation. signed/at MUST be less than or equal to expires/at. When endpoint/certificate is present, endpoint/certificate.verified/at MUST fall inside the evidence freshness window with at most 16 seconds of clock-skew tolerance.

$defs.endpointCertificateEvidence

  • Shape: object

$defs.ed25519Signature

  • Shape: object

Ed25519 signature object used by envelope and evidence signatures.