conformance

README

qurl-conformance

The single public source of truth for the qURL cross-language conformance vectors: the language-agnostic wire-truth that every qURL verifier re-runs against its own implementation. Separate artifact ids keep the qURL v2 verify path, Noise-handshake packets, agent registration, NHP assignment/completion, registered-agent knock application bodies, registered-agent session control, control-plane API-key IDs, private Connector Authority invocations, private Connector Hub replay identifiers, Hub LST return-routability cookies, and same-agent device-credential recovery decoupled by layer.

The verify-path vectors are behavioral. Each class names the verifier operation it targets and the input shape it consumes; a consumer feeds that input through its real parser/validator and asserts the declared accept/reject outcome (and, where the class is about the distinction, the reject_class). A verifier that drifts from the contract fails its own run — there are no stored booleans to trust.

Layout

Path	What it is
vectors/qv2_conformance_vectors.json	the conformance classes: claims/secret parse, strict base64url, fragment shape, relay allowlist, server-id, and the composed signature class
vectors/issuer_signature_vectors.json	the issuer-signature golden vectors (P-256 raw r||s low-S) the signature class composes by reference
vectors/relay_knock_golden.json	the relay/NHP-handshake golden packets (X25519 / AES-256-GCM / BLAKE2s): a deterministic knock packet plus a frozen, server-sealed ack reply (see Scope)
vectors/agent_registration_golden.json	the NHP agent-registration golden packets (X25519 / AES-256-GCM / BLAKE2s): deterministic OTP/REG requests plus frozen, server-sealed RAK replies (see Scope)
vectors/agent_assignment_golden.json	deterministic hub LST/LRT assignment, account-only assigned-cell OTP, REG/RAK activation, completion LST/LRT packets, strict request/binding/size/result rejects, and the producer-pinned closed error-body taxonomy (see Scope)
vectors/agent_knock_application_vectors.json	registered-agent KNK body and RunID request-policy cases plus already-decrypted ACK/COK dispositions; no Noise packet duplication
vectors/README_agent_knock_application_vectors.md	application-vector schema, outcome/reject vocabulary, and consumer algorithm
vectors/agent_session_control_vectors.json	deterministic full-packet KNK/COK/RKN/ACK overload recovery and EXT/ACK clean exit, strict cookie parsing, authentication, and closed flow rejects
vectors/README_agent_session_control_vectors.md	session-control wire contract, correlation rules, digest formula, reject vocabulary, and consumer algorithm
vectors/agent_api_key_id_vectors.json	issuer and strict-consumer fixtures for agent registration key_id / device_api_key_id
vectors/README_agent_api_key_id_vectors.md	API-key ID grammar, fixture roles, reject classes, and lockstep rule
vectors/assignment_ticket_v1_vectors.json	standalone qat1 claims/signature golden bytes, three exact fences, and strict reject suites
vectors/README_assignment_ticket_v1_vectors.md	qat1 wire, signing, fence, size-budget, and reject-consumer contract
vectors/connector_authority_lambda_v1_vectors.json	strict private request/result/error bodies for the five separately permissioned Connector Authority Lambda operations plus NHP public mappings
vectors/README_connector_authority_lambda_v1_vectors.md	private schema, closed errors, reject vocabulary, mapping provenance, and consumer algorithm
vectors/connector_hub_request_id_v1_vectors.json	private Hub replay-key framing over environment, operation, authenticated peer, and client logical-request nonce
vectors/README_connector_hub_request_id_v1_vectors.md	request-nonce lifetime, exact derivation, excluded packet inputs, and consumer boundaries
vectors/connector_hub_lst_cookie_v1_vectors.json	Hub LST/COK/LST return-routability derivation, closed initial/refresh flows, allowlisted additive profiles, amplification bounds, and rejects
vectors/README_connector_hub_lst_cookie_v1_vectors.md	cookie framing, proof flag/digest placement, replay boundaries, and consumer algorithm
vectors/agent_credential_recovery_v1_vectors.json	UDP-only same-agent device-credential recovery public/private bodies, grant bindings, exact replay, recovery horizon, and closed errors
vectors/README_agent_credential_recovery_v1_vectors.md	recovery trust boundary, no-takeover rule, Hub/cell flow, crash/time semantics, and consumer algorithm
vectors/README_qv2_conformance_vectors.md	the schema, reject_class vocabulary, class-to-entry-point map, and the derived tamper case
schema.go, embed.go	a stdlib-only Go module that embeds the artifacts and exposes strict, typed loaders

Using it from Go

import conformance "github.com/layervai/qurl-conformance"

cf, err := conformance.ConformanceVectors()        // strict-parsed conformance artifact
vf, err := conformance.SignatureVectors()          // strict-parsed issuer-signature vectors
rk, err := conformance.RelayKnockGolden()          // strict-parsed relay-knock golden packets
ar, err := conformance.AgentRegistrationGolden()   // strict-parsed agent-registration golden packets
aa, err := conformance.AgentAssignmentGolden()     // strict-parsed assignment/REG/completion packets + errors
ka, err := conformance.AgentKnockApplication()      // strict-parsed agent KNK/ACK application vectors
sc, err := conformance.AgentSessionControl()        // strict-parsed RKN/EXT full-packet vectors
ki, err := conformance.AgentAPIKeyIDs()             // strict-parsed agent API-key ID vectors
at, err := conformance.AssignmentTicket()           // strict-parsed qat1 cryptographic/fence artifact
ca, err := conformance.ConnectorAuthorityLambda()   // strict-parsed private authority invocation artifact
hi, err := conformance.ConnectorHubRequestID()       // strict-parsed private Hub request-ID KATs
hc, err := conformance.ConnectorHubLSTCookie()       // strict-parsed Hub LST return-routability contract
cr, err := conformance.AgentCredentialRecovery()      // strict-parsed UDP credential-recovery contract
raw := conformance.QV2Vectors()                    // raw bytes, if you drive your own parser

The loaders fail (never return an empty document) on a malformed or unexpected artifact, so the contract can never silently drop out of a test suite.

Using it from another language

Copy the artifact your implementation consumes (and, for qURL v2, qv2_conformance_vectors.json and issuer_signature_vectors.json) verbatim (same bytes, no reformatting), load them with a strict JSON reader that rejects duplicate keys and unknown fields, route each class's input to your real entry point, and assert the declared outcome. Treat a missing fixture as a hard failure, not a skip. See vectors/README_qv2_conformance_vectors.md for the full schema and vocabulary.

Scope

This module hosts twelve artifact families, each under its own artifact id:

• qURL v2 verify path (qurl-v2-conformance-vectors, composing the issuer-signature golden bytes) — the claims/secret/base64/fragment/relay/ server-id classes described above.
• Relay/NHP handshake (qurl-relay-knock-golden-vectors, relay_knock_golden.json) — the Noise-handshake golden packets, kept in a separate artifact because the qURL verify path does not import the handshake layer. The knock packet is deterministic: a conformant initiator must reproduce its packet_hex byte-for-byte from the listed inputs. The ack reply is sealed at origin with a random server ephemeral key, so it is not reproducible by a client — consumers can only decrypt it and assert the recovered fields. It is re-hosted here verbatim as a frozen golden value. These packets originate from the NHP cross-language handshake fixtures and are pinned here.
• NHP agent registration (qurl-agent-registration-golden-vectors, agent_registration_golden.json) — the OTP/REG/RAK Noise-handshake golden packets for agent enrollment, again a separate artifact from the verify path. The otp, reg_emailed, and reg_preissued requests are deterministic: a conformant initiator must reproduce each packet_hex byte-for-byte. The REG body is {usrId, devId, aspId, otp, usrData} with usrData = {hostname, version, takeover} (fields omitted when empty/false), matching the live agent implementations byte-for-byte. The two REG packets differ in the body otp value (an emailed code vs a pre-issued key secret) and in usrData.takeover (omitted vs true); the framing is identical. The rak_success / rak_error replies are sealed at origin with a random server ephemeral, so they are frozen decrypt-only, mirroring the relay-knock ack. The RAK cases echo reg_emailed's counter, so a consumer can validate the RAK-must-echo-its-REG counter contract against a positive fixture. All keys/ids/secrets are synthetic.
• NHP agent assignment and completion (qurl-agent-assignment-golden-vectors, agent_assignment_golden.json) — complete deterministic NHP_LST (type 5) / NHP_LRT (type 6) exchanges for initial hub assignment, registered-agent assignment refresh, and assigned-cell registration completion, plus the intervening assigned-cell NHP_REG (type 13) / NHP_RAK (type 14) activation. Every result echoes its request counter. Initial and refresh packets authenticate the hub; REG and completion authenticate the distinct cell public key returned by assignment. The initial and refresh LST bodies are strictly parsed and require a canonical, CSPRNG-generated 32-byte request_nonce. An SDK mints it once per logical assignment operation and reuses the exact body through every nested retry, while a later operation mints a fresh nonce. It is never echoed in LRT and never exposes the Hub's private replay key. The separate Hub request-ID artifact freezes that private derivation. The opaque ticket returned by initial assignment appears byte-for-byte in REG usrData and is consumed there. Ordinary refresh returns only the current assignment binding and never issues a registration ticket, while completion deliberately carries no ticket. Public initial-assignment registration.key_kind is closed to bootstrap, connector_bootstrap, account, or agent; tunnel_bootstrap remains a private control-plane key_type and is rejected if it crosses the LRT wire. The account_credential_otp section freezes the exact one-way NHP_OTP (type 12) request bytes sent to the assigned cell: {usrId,devId,aspId,pass,usrData:{query,version,assignment_ticket}}. Its secret-bearing decrypted body must be consumed from the exact RawBody; the Noise-authenticated peer key is a separate trusted input, and no public key or placement field is allowed in the body. Only key_kind=account uses OTP. The bootstrap, connector_bootstrap, and agent paths are explicitly OTP-free and proceed directly to one REG. Binding cases isolate the exact ticket token, peer key, devId, credential id/hash/fence/kind, environment, cell, expiry, inclusive 630-second lifetime boundary, and 629-second reject. The challenge-store metadata freezes ticket_jti as its lookup key and binds that ticket to the authenticated peer key, devId, credential id, environment, and cell, with an exact one-field mismatch suite. recomputed_credential_fence_b64 is the frozen expected result of the qat1/authority-owned strong-row derivation; this artifact freezes its compare inputs and mismatch outcome rather than locally reimplementing that derivation. Binding and challenge cases are declarative mutation recipes that authority consumers must execute against their own implementation. Packet-size cases drive the producer at the exact 3,840-byte plaintext / 4,096-byte packet limit and max+1. This remains contract data: it does not implement ticket verification, OTP state, rate limiting, email delivery, SDK callbacks, or a plugin. Schema v3 introduced the required assignment request nonce; schema v4 adds the 52205 case's exact accepted request phases. Each is a deliberate breaking shape for strict consumers, which must update their typed loader before adopting the corresponding release. The completion request carries the synthetic SDK-generated device-key candidate that must be persisted before send; its result list contains exactly query, version, and device_api_key_id—no agent metadata, secret, secret-derived hash, or candidate commitment. The artifact also carries the closed 522xx/523xx LRT and ticket/quota 521xx RAK error taxonomy, including retry-delay rules and malformed-body rejects. The assignment-family 52205 response is explicitly accepted for both initial and refresh requests so a Hub can reject a malformed, unidentifiable mode without guessing the intended exchange. Its compact authenticated request/result case sets separately pin duplicate-aware JSON parsing, exact case-sensitive keys, unknown-field rejection, phase semantics, secret non-disclosure, and the rule that clients cannot supply owner identity or cell placement. The artifact notes define the consumer-neutral reject vocabulary so non-Go consumers do not need to infer meanings from Go constants. The loader verifies canonical lowercase hex, positive decimal transaction fields, canonical padded base64 endpoint keys, and each static X25519 keypair. The assignment wire verifier pins merged qurl-go packet-codec revision 8a69642957030b9ce0a1b8b356246d265a9f577d and rebuilds and opens all nine deterministic packets through its exported low-level codec. That revision pin does not claim the higher-level qurl-go assignment request builder already supports the current artifact schema; the conformance artifact intentionally lands first. The error taxonomy is pinned to merged NHP revision 9653fcb185c77629b787ad046c13c760baba88f4, which reserves 52110-52112 and the 522xx/523xx ranges and adds list-result retryAfterSeconds. Exact OTP RawBody preservation and the authenticated-peer plugin boundary are pinned separately to merged NHP revision 2072546e1fc76eb76bd7e5c22d37856019ba33e7. All packets, identities, credentials, tickets, hosts, timestamps, and error messages are synthetic conformance values.
• Registered-agent knock application contract (qurl-agent-knock-application-vectors, agent_knock_application_vectors.json) — the exact compact six-field KNK body, authenticated RunID request-policy cases, and synthetic, already-decrypted reply dispositions for ACK success, authenticated deny, cookie challenge, wrong resource, malformed/missing maps, the complete current ACK producer envelope, required pre-access actions, and reply counter/type mismatch. Generic protocol parsing keeps RunID optional, while the native qURL Connector gate requires one canonical 16-character lowercase-hex value. Standard success includes exact-resource preActions: null; any non-null action requires NHP_ACC and fails closed until that phase is implemented. Optional aspToken / redirectUrl metadata never replaces the requested resource's acTokens / resHost authorization result. It contains no Noise packets or key material; consumers compose it with their real body serializer, request-policy gates, reply parser, and transport correlation gates. Its resId semantic is the placement-neutral NHP knock_resource_id, not the public-key management resource_id. See vectors/README_agent_knock_application_vectors.md.
• Registered-agent session control (qurl-agent-session-control-vectors, agent_session_control_vectors.json) — deterministic full packets for the overload path KNK -> COK -> RKN -> ACK and clean exit EXT -> ACK, pinned to merged producer revision 2a2a3d91adcf5a7930050db3561c8e00b8340a39. The COK wire counter is deliberately unconstrained; its authenticated body trxId must equal the originating KNK counter. RKN authenticates a canonical padded standard-base64 32-byte cookie by extending the header digest with the raw cookie bytes. ACK counters echo RKN or EXT. EXT never accepts a cookie challenge. The artifact freezes both static X25519 identities, every deterministic ephemeral key, body byte, header digest, and packet byte, plus closed cookie and flow reject suites. Consumers must rebuild initiator packets, authenticate replies against the assigned cell key, and enforce the application-body and correlation gates after decryption. See vectors/README_agent_session_control_vectors.md.
• Agent API-key ID contract (qurl-agent-api-key-id-vectors, agent_api_key_id_vectors.json) — deterministic issuer suffix fixtures, direct string validation cases, and raw response-field cases for registration-info.key_id and completion device_api_key_id. It freezes the exact key_ plus 12 ASCII-alphanumeric grammar without reinterpreting the synthetic NHP registration packet usrId. See vectors/README_agent_api_key_id_vectors.md.
• Assignment ticket v1 (qurl-assignment-ticket-v1-vectors, assignment_ticket_v1_vectors.json) — exact qat1 claims bytes, signing digest, synthetic KMS DER-to-raw-low-S conversion, complete ticket, credential/cell/ existing-assignment fences, NHP size budget, and closed reject suites. NHP carries this ticket opaquely. See vectors/README_assignment_ticket_v1_vectors.md.
• Private Connector Authority Lambda v1 (qurl-connector-authority-lambda-v1-vectors, connector_authority_lambda_v1_vectors.json) — five distinct strict request schemas for IssueAssignment, RefreshAssignment, IssueRegistrationOTP, ActivateRegistration, and CompleteRegistration. There is no generic operation selector and callers cannot supply environment, cell, owner, or assignment generation. Each global IssueAssignment and RefreshAssignment request carries a required lowercase SHA-256 hex hub_request_id. The authenticated Hub worker uses domain-separated framing over its environment, the Hub-selected exact operation, authenticated initiator public key, and the raw 32-byte request_nonce from the strict authenticated LST. NHP timestamp, transaction id, source address, and body digest are deliberately excluded so fresh-packet retries retain one logical ID. This gives the private authority a cross-worker replay key without making it caller authority: a successful Issue/Refresh domain result is cached for 15 minutes and the same id plus request fingerprint reuses it, while the same id plus a different semantic request fingerprint fails closed. Malformed, rejected-credential or identity, pre-invoke/rate-limited, and transient-unavailable outcomes are not cached. A later top-level assignment operation has a newly generated request nonce and therefore a new id. Cell operations reject the field, and it never appears in a public NHP body or authority response. Each response is exactly {version,result} or {version,error} under a 4,096-byte cap; only OTP rate_limited may carry a positive retry_after_seconds. Private-to-NHP cases freeze whether the worker emits LRT, emits RAK, follows OTP's normal no-application-reply protocol, or deliberately drops an activation reply. In particular, activation unavailable is deliberately silent so the SDK's bounded exact-pending-activation transport recovery owns ambiguity; it is never translated to 52107. Initial-enrollment 52107 and Issue/Refresh assignment-admission 52204 are explicitly NHP pre-invoke outcomes, not authority errors. Public 52203 remains reserved by the public assignment artifact but is intentionally not produced here: the Issue and Refresh domain operations do not mutate assignments, although their private adapter writes the 15-minute replay envelope; activation atomically enforces owner quota as RAK 52112. See vectors/README_connector_authority_lambda_v1_vectors.md.
• Private Connector Hub request-ID v1 (qurl-connector-hub-request-id-v1-vectors, connector_hub_request_id_v1_vectors.json) — exact tagged framing and KATs for the Hub-derived replay key. It also freezes the canonical public request_nonce encoding and the rule that same-nonce changed semantics must reach the Authority under the same operation-scoped ID and fail its semantic fingerprint check. See vectors/README_connector_hub_request_id_v1_vectors.md.
• Connector Hub LST return-routability cookie v1 (qurl-connector-hub-lst-cookie-v1-vectors, connector_hub_lst_cookie_v1_vectors.json) — exact stateless HMAC framing, the Hub-LST-only 0x0004 proof flag and digest input, initial and refresh flows, strict zero-flag COK parsing (including terminal compressed and unknown-flag rejects), dynamic no-amplification bounds, and silent pre-Authority rejects. It neither changes nor reuses the existing overload KNK/RKN cookie domain. See vectors/README_connector_hub_lst_cookie_v1_vectors.md.
• Agent credential recovery v1 (qurl-agent-credential-recovery-v1-vectors, agent_credential_recovery_v1_vectors.json) — strict UDP-only public Hub and assigned-cell bodies, operation-specific private Authority bodies, recovery error mappings, additive Hub-cookie proof/size cases, replay fingerprints, grant bindings, no-takeover/no-placement-hint policy, exact-candidate replay, per-episode immutable 90-day horizon, and closed 524xx outcomes. See vectors/README_agent_credential_recovery_v1_vectors.md.

This module is intentionally dependency-free (stdlib only). The generator that produces the verify-path vectors lives at tools/gen and is run via make gen-vectors once per issuer-key rotation; it is never run in CI (the accept signature uses a random nonce, so it is not reproducible). The committed JSON is the artifact. Vectors are edited under vectors/.

Releases

Versioning is automated with Release Please in manifest mode: the Go module, the npm package, and the Python package are released together under one linked version (see release-please-config.json). Merging the release PR tags the repo, which is what releases the Go module.

npm and PyPI registry publishing on release is a token-gated follow-up (it needs NPM_TOKEN / PyPI trusted publishing wired up); for now Release Please only automates the version-bump PRs and the Go tag.

License

MIT — see LICENSE.

Documentation

Overview

Package conformance is the single public source of truth for the qURL cross-language conformance vectors. It embeds the JSON artifacts under vectors/ and exposes strict, typed loaders so any consumer — in any language that can call this Go module, or that copies the JSON directly — can re-run the same wire-truth against its own implementation.

Twelve families live here, each under its own artifact id so they stay decoupled by layer:

• The qURL v2 verify-path vectors (qv2_conformance_vectors.json composing issuer_signature_vectors.json): the claims/secret/base64/fragment/relay/ server-id classes and the issuer-signature golden bytes.
• The relay/NHP-handshake golden packets (relay_knock_golden.json): the deterministic relay-knock packet plus a frozen, server-sealed ack reply for the Noise handshake layer, which the qURL verify path does not import.
• The NHP agent-registration golden packets (agent_registration_golden.json): deterministic OTP/REG requests plus frozen RAK replies.
• The NHP agent-assignment golden packets (agent_assignment_golden.json): deterministic LST/LRT assignment and completion, account-only assigned-cell OTP, REG/RAK activation, and strict request/binding/size/error cases.
• The registered-agent knock application contract (agent_knock_application_vectors.json): exact KNK JSON, RunID request policy, and already-decrypted ACK/COK disposition vectors, with no duplicate packet bytes.
• The registered-agent session-control contract (agent_session_control_vectors.json): deterministic KNK/COK/RKN/ACK and EXT/ACK packets, strict cookie handling, and closed flow negatives.
• The agent API-key ID contract (agent_api_key_id_vectors.json): issuer construction and strict consumer cases for registration-info key_id and completion device_api_key_id.
• The assignment-ticket v1 artifact (assignment_ticket_v1_vectors.json): exact qat1 claims/signature bytes, optimistic fences, and reject suites.
• The private Connector Authority Lambda contract (connector_authority_lambda_v1_vectors.json): five operation-specific request/result envelopes, strict rejects, and private-to-NHP mappings.
• The private Connector Hub request-ID contract (connector_hub_request_id_v1_vectors.json): byte-exact replay-key KATs over environment, authority operation, authenticated peer, and the client logical-request nonce.
• The Connector Hub LST return-routability cookie contract (connector_hub_lst_cookie_v1_vectors.json): stateless challenge/proof framing and amplification gates before Authority invocation.
• The agent credential recovery contract (agent_credential_recovery_v1_vectors.json): UDP-only same-agent device credential replacement bodies, grant fences, horizon, and outcomes.

The verify-path artifact is BEHAVIORAL: a consumer feeds each class's input through its real parser/validator and asserts the declared accept/reject outcome (and, where the class is about the distinction, the reject_class), rather than trusting a stored boolean. A verifier that drifts from the contract fails its own run.

This module is stdlib-only and has no build-time dependencies; the generator that produces the vectors is intentionally not part of it.

Index

• Constants
• Variables
• func AgentAPIKeyIDVectors() []byte
• func AgentAssignmentVectors() []byte
• func AgentCredentialRecoveryVectors() []byte
• func AgentKnockApplicationVectors() []byte
• func AgentRegistrationVectors() []byte
• func AgentSessionControlVectors() []byte
• func AssignmentTicketVectors() []byte
• func ConnectorAuthorityLambdaVectors() []byte
• func ConnectorHubLSTChallengeBody(transactionID uint64, cookie []byte) (string, error)
• func ConnectorHubLSTCookieVectors() []byte
• func ConnectorHubRequestIDVectors() []byte
• func DecodeConnectorHubRequestNonce(value string) ([]byte, error)
• func DeriveConnectorHubLSTCookie(signingKey []byte, sourceIP string, authenticatedPeerPublicKey []byte, ...) ([]byte, error)
• func DeriveConnectorHubRequestID(environment, operation string, authenticatedPeerPublicKey, requestNonce []byte) (string, error)
• func IssuerSignatureVectors() []byte
• func Open(name string) ([]byte, error)
• func QV2Vectors() []byte
• func RelayKnockVectors() []byte
• type AgentAPIKeyIDContract
• type AgentAPIKeyIDFile
  • func AgentAPIKeyIDs() (*AgentAPIKeyIDFile, error)
  • func ParseAgentAPIKeyIDFile(data []byte) (*AgentAPIKeyIDFile, error)
• type AgentAPIKeyIDProducerCase
• type AgentAPIKeyIDResponseCase
• type AgentAPIKeyIDSurface
• type AgentAPIKeyIDValueCase
• type AgentAssignmentCase
• type AgentAssignmentErrorCase
  • func (c *AgentAssignmentErrorCase) UnmarshalJSON(data []byte) error
• type AgentAssignmentErrorContract
• type AgentAssignmentErrorRules
• type AgentAssignmentExchange
• type AgentAssignmentFile
  • func AgentAssignmentGolden() (*AgentAssignmentFile, error)
  • func ParseAgentAssignmentFile(data []byte) (*AgentAssignmentFile, error)
• type AgentAssignmentKey
• type AgentAssignmentKeys
• type AgentAssignmentMalformedCase
• type AgentAssignmentOTPBindingCase
• type AgentAssignmentOTPChallengeBinding
• type AgentAssignmentOTPContract
• type AgentAssignmentOTPEnrollmentBinding
• type AgentAssignmentOTPPacketSizeCase
• type AgentAssignmentOTPPacketSizeContract
• type AgentAssignmentPacket
• type AgentAssignmentRequestCase
• type AgentAssignmentResultCase
• type AgentCredentialRecoveryBindingCase
• type AgentCredentialRecoveryBodyCase
• type AgentCredentialRecoveryErrorCase
• type AgentCredentialRecoveryExchange
• type AgentCredentialRecoveryFile
  • func AgentCredentialRecovery() (*AgentCredentialRecoveryFile, error)
  • func ParseAgentCredentialRecoveryFile(data []byte) (*AgentCredentialRecoveryFile, error)
• type AgentCredentialRecoveryFixtures
• type AgentCredentialRecoveryHubCookieComposition
• type AgentCredentialRecoveryOperation
• type AgentCredentialRecoveryPrivateErrorCase
• type AgentCredentialRecoveryProtocol
  • func (protocol *AgentCredentialRecoveryProtocol) UnmarshalJSON(data []byte) error
• type AgentCredentialRecoveryPublicMapping
• type AgentKnockApplicationFile
  • func AgentKnockApplication() (*AgentKnockApplicationFile, error)
  • func ParseAgentKnockApplicationFile(data []byte) (*AgentKnockApplicationFile, error)
• type AgentKnockApplicationRequest
• type AgentKnockApplicationRequestFields
• type AgentKnockReplyCase
• type AgentKnockRequestCase
• type AgentKnockRequestExpectation
• type AgentRegistrationCase
• type AgentRegistrationFile
  • func AgentRegistrationGolden() (*AgentRegistrationFile, error)
  • func ParseAgentRegistrationFile(data []byte) (*AgentRegistrationFile, error)
• type AgentSessionCleanExit
• type AgentSessionControlFile
  • func AgentSessionControl() (*AgentSessionControlFile, error)
  • func ParseAgentSessionControlFile(data []byte) (*AgentSessionControlFile, error)
• type AgentSessionCookieBodyCase
• type AgentSessionFlowCase
• type AgentSessionKey
• type AgentSessionKeys
• type AgentSessionOverloadReknock
• type AgentSessionPacket
• type AgentSessionProtocol
• type AssignmentTicketClaimsReject
  • func (c AssignmentTicketClaimsReject) ResolveClaims() (string, error)
• type AssignmentTicketContract
• type AssignmentTicketDERCase
• type AssignmentTicketFencePart
• type AssignmentTicketFenceReject
• type AssignmentTicketFenceVector
• type AssignmentTicketFile
  • func AssignmentTicket() (*AssignmentTicketFile, error)
  • func ParseAssignmentTicketFile(data []byte) (*AssignmentTicketFile, error)
• type AssignmentTicketGolden
• type AssignmentTicketJWK
• type AssignmentTicketRepeatDerivation
• type AssignmentTicketSyntheticKey
• type AssignmentTicketTrustReject
• type AssignmentTicketVerifyReject
  • func (c AssignmentTicketVerifyReject) ResolveToken(g AssignmentTicketGolden) (string, error)
• type ConformanceClass
• type ConformanceFile
  • func ConformanceVectors() (*ConformanceFile, error)
  • func ParseConformanceFile(data []byte) (*ConformanceFile, error)
• type ConformanceSignatureClass
• type ConformanceTamperDerivation
• type ConformanceVector
• type ConnectorAuthorityActivateRegistrationRequest
• type ConnectorAuthorityAssignmentResult
• type ConnectorAuthorityCompleteRegistrationRequest
• type ConnectorAuthorityCompleteRegistrationResult
• type ConnectorAuthorityIssueAssignmentRequest
• type ConnectorAuthorityIssueAssignmentResult
• type ConnectorAuthorityIssueRegistrationOTPRequest
• type ConnectorAuthorityLambdaBodyCase
• type ConnectorAuthorityLambdaErrorCase
• type ConnectorAuthorityLambdaFile
  • func ConnectorAuthorityLambda() (*ConnectorAuthorityLambdaFile, error)
  • func ParseConnectorAuthorityLambdaFile(data []byte) (*ConnectorAuthorityLambdaFile, error)
• type ConnectorAuthorityLambdaFixtures
• type ConnectorAuthorityLambdaOperation
• type ConnectorAuthorityLambdaProtocol
• type ConnectorAuthorityLambdaRejectCase
• type ConnectorAuthorityNHPUDPEndpoint
• type ConnectorAuthorityPublicMapping
• type ConnectorAuthorityRefreshAssignmentRequest
• type ConnectorAuthorityRefreshAssignmentResult
• type ConnectorAuthorityRegistrationResult
• type ConnectorHubAssignmentSuccessSize
• type ConnectorHubLSTChallengeBodyCase
• type ConnectorHubLSTCookieContract
• type ConnectorHubLSTCookieFile
  • func ConnectorHubLSTCookie() (*ConnectorHubLSTCookieFile, error)
  • func ParseConnectorHubLSTCookieFile(data []byte) (*ConnectorHubLSTCookieFile, error)
• type ConnectorHubLSTCookieFlow
• type ConnectorHubLSTCookieKAT
• type ConnectorHubLSTCookieKeyCase
• type ConnectorHubLSTCookieRejectCase
• type ConnectorHubLSTCookieSizeCase
• type ConnectorHubLSTProofDigestKAT
• type ConnectorHubRequestIDCase
• type ConnectorHubRequestIDContract
• type ConnectorHubRequestIDFile
  • func ConnectorHubRequestID() (*ConnectorHubRequestIDFile, error)
  • func ParseConnectorHubRequestIDFile(data []byte) (*ConnectorHubRequestIDFile, error)
• type ECPublicJWK
• type IssuerKeyMaterial
• type RelayKnockCase
• type RelayKnockFile
  • func ParseRelayKnockFile(data []byte) (*RelayKnockFile, error)
  • func RelayKnockGolden() (*RelayKnockFile, error)
• type SignatureVector
• type VectorFile
  • func ParseVectorFile(data []byte) (*VectorFile, error)
  • func SignatureVectors() (*VectorFile, error)

Constants

const (
	// AgentAPIKeyIDArtifactID identifies the control-plane API-key ID artifact.
	AgentAPIKeyIDArtifactID = "qurl-agent-api-key-id-vectors"
	// AgentAPIKeyIDSchemaVersion is the only schema accepted by this release.
	AgentAPIKeyIDSchemaVersion = 1

	AgentAPIKeyIDPrefix         = "key_"
	AgentAPIKeyIDSuffixLength   = 12
	AgentAPIKeyIDTotalLength    = len(AgentAPIKeyIDPrefix) + AgentAPIKeyIDSuffixLength
	AgentAPIKeyIDSuffixAlphabet = "ASCII_ALPHANUMERIC"
	AgentAPIKeyIDPattern        = "^key_[A-Za-z0-9]{12}$"

	AgentAPIKeyIDSurfaceRegistrationInfo = "registration_info"
	AgentAPIKeyIDSurfaceCompletion       = "completion"

	AgentAPIKeyIDRejectInvalidID = "invalid_id"
	AgentAPIKeyIDRejectBodyParse = "body_parse"
)

const (
	AgentCredentialRecoveryArtifactID           = "qurl-agent-credential-recovery-v1-vectors"
	AgentCredentialRecoveryHubCookieProfile     = AgentCredentialRecoveryArtifactID + "/hub_cookie_composition"
	AgentCredentialRecoverySchemaVersion        = 1
	AgentCredentialRecoveryRequestHeader        = "NHP_LST"
	AgentCredentialRecoveryRequestType          = 5
	AgentCredentialRecoveryResultHeader         = "NHP_LRT"
	AgentCredentialRecoveryResultType           = 6
	AgentCredentialRecoveryGrantPrefix          = "qrg1."
	AgentCredentialRecoveryMaxGrantBytes        = 2304
	AgentCredentialRecoveryGrantLifetimeSeconds = 900
	AgentCredentialRecoveryHorizonSeconds       = 90 * 24 * 60 * 60
	AgentCredentialRecoveryPacketOverheadBytes  = ConnectorHubLSTCookiePacketOverhead
	AgentCredentialRecoveryMaxBodyBytes         = 3840
	AgentCredentialRecoveryMaxPacketBytes       = 4096

	AgentCredentialRecoveryHubPhase  = "hub_issue_recovery"
	AgentCredentialRecoveryCellPhase = "assigned_cell_complete_recovery"

	AgentCredentialRecoveryIssueOperation    = "IssueCredentialRecovery"
	AgentCredentialRecoveryCompleteOperation = "CompleteCredentialRecovery"
)

const (
	// AgentSessionControlArtifactID identifies the registered-agent overload
	// re-knock and clean-exit packet artifact.
	AgentSessionControlArtifactID = "qurl-agent-session-control-vectors"
	// AgentSessionControlProducerRevision is the exact merged NHP producer
	// revision used to seal the golden packets.
	AgentSessionControlProducerRevision = "2a2a3d91adcf5a7930050db3561c8e00b8340a39"

	AgentSessionHeaderKNK = 1
	AgentSessionHeaderACK = 2
	AgentSessionHeaderCOK = 7
	AgentSessionHeaderRKN = 8
	AgentSessionHeaderEXT = 16

	AgentSessionCookieSize     = 32
	AgentSessionHeaderSize     = 240
	AgentSessionTagSize        = 16
	AgentSessionPacketMaxBytes = 4096
)

const (
	AgentSessionOutcomeAccept = "accept"
	AgentSessionOutcomeReject = "reject"

	AgentSessionRejectBodyParse          = "body_parse"
	AgentSessionRejectCookieEncoding     = "cookie_encoding"
	AgentSessionRejectCookieLength       = "cookie_length"
	AgentSessionRejectCookieCanonical    = "cookie_canonical"
	AgentSessionRejectCounter            = "counter"
	AgentSessionRejectHeaderType         = "header_type"
	AgentSessionRejectReplyType          = "reply_type"
	AgentSessionRejectHeaderDigest       = "header_digest"
	AgentSessionRejectApplicationBody    = "application_body"
	AgentSessionRejectPeerAuthentication = "peer_authentication"
)

const (
	// AssignmentTicketArtifactID identifies the standalone qat1 artifact.
	AssignmentTicketArtifactID = "qurl-assignment-ticket-v1-vectors"
	// AssignmentTicketSchemaVersion is the only schema accepted by this release.
	AssignmentTicketSchemaVersion = 1

	AssignmentTicketPrefix        = "qat1"
	AssignmentTicketSigningDomain = "qurl-agent-assignment-ticket-v1"

	// AssignmentTicketSyntheticCredentialBytes is the byte length of the fixed
	// ASCII test credential committed in the golden artifact.
	AssignmentTicketSyntheticCredentialBytes = 51
)

const (
	// ConnectorAuthorityLambdaArtifactID identifies the private NHP-to-authority
	// invocation contract. It is deliberately separate from the public UDP
	// agent-assignment artifact.
	ConnectorAuthorityLambdaArtifactID = "qurl-connector-authority-lambda-v1-vectors"
	// ConnectorAuthorityLambdaSchemaVersion is the only artifact schema accepted
	// by this release.
	ConnectorAuthorityLambdaSchemaVersion = 1

	ConnectorAuthorityLambdaRequestVersion   = 1
	ConnectorAuthorityLambdaMaxRequestBytes  = 4096
	ConnectorAuthorityLambdaMaxResponseBytes = 4096
	// ConnectorAuthorityLambdaMaxAssignmentTicketASCIIBytes is shared with
	// assignmentticket v1 so this adapter accepts every valid qat1 token that
	// still fits inside the operation's 4096-byte request envelope.
	ConnectorAuthorityLambdaMaxAssignmentTicketASCIIBytes = 2304
	ConnectorAuthorityLambdaTimestampFormat               = "RFC3339_UTC_WHOLE_SECONDS"
	ConnectorAuthorityLambdaHubRequestIDFormat            = "lowercase_sha256_hex"
	ConnectorAuthorityLambdaResponseRule                  = "exactly_one_of_result_or_error"

	ConnectorAuthorityOperationIssueAssignment      = "IssueAssignment"
	ConnectorAuthorityOperationRefreshAssignment    = "RefreshAssignment"
	ConnectorAuthorityOperationIssueRegistrationOTP = "IssueRegistrationOTP"
	ConnectorAuthorityOperationActivateRegistration = "ActivateRegistration"
	ConnectorAuthorityOperationCompleteRegistration = "CompleteRegistration"

	ConnectorAuthorityMappingSourceResponse  = "authority_response"
	ConnectorAuthorityMappingSourcePreInvoke = "nhp_preinvoke"
	ConnectorAuthorityNHPActionEmitLRT       = "emit_lrt"
	ConnectorAuthorityNHPActionEmitRAK       = "emit_rak"
	ConnectorAuthorityNHPActionNoReply       = "no_application_reply"
	ConnectorAuthorityNHPActionDropNoReply   = "drop_no_reply"
	ConnectorAuthorityRecoveryNone           = "none"
	ConnectorAuthorityRecoveryPendingExact   = "bounded_exact_pending_activation_transport_retry"
)

const (
	// ConnectorHubLSTCookieArtifactID identifies the Hub assignment
	// return-routability challenge contract.
	ConnectorHubLSTCookieArtifactID = "qurl-connector-hub-lst-cookie-v1-vectors"
	// ConnectorHubLSTCookieSchemaVersion is the only schema accepted by this
	// release.
	ConnectorHubLSTCookieSchemaVersion = 1

	ConnectorHubLSTCookieAlgorithm       = "HMAC-SHA-256"
	ConnectorHubLSTCookieDomain          = "nhp-connector-hub-lst-cookie-v1"
	ConnectorHubLSTCookieDomainSuffixHex = "00"
	ConnectorHubLSTCookieInputFraming    = "domain_then_00_then_u8_ip_family_then_u32be_length_framed_raw_ip_and_peer_then_u64be_window"
	ConnectorHubLSTCookieSigningKeyBytes = 32
	ConnectorHubLSTCookieBytes           = 32
	ConnectorHubLSTCookieEncoding        = "base64_std_padded_canonical"
	ConnectorHubLSTCookiePeerBytes       = 32
	ConnectorHubLSTCookieWindowSeconds   = 30

	ConnectorHubLSTCookieProofFlagName     = "NHP_FLAG_HUB_LST_COOKIE_PROOF"
	ConnectorHubLSTCookieProofFlagHex      = "0004"
	ConnectorHubLSTCookieProofFlag         = uint16(0x0004)
	ConnectorHubLSTCookieChallengeFlagsHex = "0000"
	ConnectorHubLSTProofKATPurpose         = "digest_primitive_with_fresh_proof_header_not_complete_encrypted_packet"

	ConnectorHubLSTCookieHeaderBytes       = 240
	ConnectorHubLSTCookieBodyAEADTagBytes  = 16
	ConnectorHubLSTCookiePacketMaxBytes    = 4096
	ConnectorHubLSTCookiePacketOverhead    = ConnectorHubLSTCookieHeaderBytes + ConnectorHubLSTCookieBodyAEADTagBytes
	ConnectorHubLSTCookiePlaintextMaxBytes = ConnectorHubLSTCookiePacketMaxBytes - ConnectorHubLSTCookiePacketOverhead

	ConnectorHubLSTCookieOutcomeAccept  = "accept"
	ConnectorHubLSTCookieOutcomeReject  = "reject"
	ConnectorHubLSTCookieActionDrop     = "drop_silently"
	ConnectorHubLSTCookieActionSizeSafe = "challenge_size_eligible"
	ConnectorHubLSTCookieActionContinue = "continue_strict_request_validation"
	ConnectorHubLSTCookieClientProof    = "send_one_fresh_proof_lst"
	ConnectorHubLSTCookieClientStop     = "stop_without_third_lst_or_fallback"
)

const (
	// ConnectorHubRequestIDArtifactID identifies the byte-level private replay
	// key contract used by every Connector Hub worker.
	ConnectorHubRequestIDArtifactID = "qurl-connector-hub-request-id-v1-vectors"
	// ConnectorHubRequestIDSchemaVersion is the only artifact schema accepted by
	// this release.
	ConnectorHubRequestIDSchemaVersion = 1

	ConnectorHubRequestIDDigest          = "SHA-256"
	ConnectorHubRequestIDOutputEncoding  = "lowercase_hex"
	ConnectorHubRequestIDDomain          = "layerv:qurl:connector-hub-request-id:v1"
	ConnectorHubRequestIDDomainSuffixHex = "00"
	ConnectorHubRequestIDFrameEncoding   = "u8_field_tag_then_u16be_byte_length_then_value"

	ConnectorHubRequestIDEnvironmentTagHex = "01"
	ConnectorHubRequestIDOperationTagHex   = "02"
	ConnectorHubRequestIDPeerTagHex        = "03"
	ConnectorHubRequestIDNonceTagHex       = "04"

	ConnectorHubRequestIDOperationIssue   = "IssueAssignment"
	ConnectorHubRequestIDOperationRefresh = "RefreshAssignment"
	ConnectorHubRequestIDOperationRecover = "IssueCredentialRecovery"

	ConnectorHubRequestIDEnvironmentNormalization = "none"
	ConnectorHubRequestIDPeerFixtureEncoding      = "canonical_base64_std_padded"
	ConnectorHubRequestIDPeerHashEncoding         = "raw_32_bytes"
	ConnectorHubRequestIDNonceFixtureEncoding     = "canonical_base64url_unpadded"
	ConnectorHubRequestIDNonceHashEncoding        = "raw_32_bytes"

	ConnectorHubRequestIDMinEnvironmentBytes = 1
	ConnectorHubRequestIDMaxEnvironmentBytes = 32
	ConnectorHubRequestIDPeerBytes           = 32
	ConnectorHubRequestIDNonceBytes          = 32
)

const (
	ExpectAccept = "accept"
	ExpectReject = "reject"
)

Expectation constants for accept/reject vector fields across artifacts.

const (
	// RejectClassParse is the coarse class for a JSON-schema violation (duplicate
	// key, unknown field, null, wrong type, missing required, out-of-range/ordering).
	RejectClassParse = "parse"
	// RejectClassEncoding is a base64url encoding-layer rejection.
	RejectClassEncoding = "encoding"
	// RejectClassKeyLength is a decoded-key wrong-length rejection.
	RejectClassKeyLength = "key_length"
	// RejectClassFragment is a fragment wire-shape rejection.
	RejectClassFragment = "fragment"
	// RejectClassRelayURL is a relay_url HTTPS/allowlist rejection.
	RejectClassRelayURL = "relay_url"
	// RejectClassTamper is the signature-class payload-tamper rejection: a valid
	// signature verified against a flipped claims input (derived, not stored).
	RejectClassTamper = "tamper"
	// RejectClassHighS is a signature that is not low-S normalized.
	RejectClassHighS = "high_s"
	// RejectClassWrongLength is a signature that is not exactly 64 bytes (raw r||s).
	RejectClassWrongLength = "wrong_length"
)

reject_class vocabulary. These constants are the fixed cross-language vocabulary the README pins, so every consumer can switch on a closed, known set. They are pinned precisely only where the class is about the distinction (signature high_s vs wrong_length; encoding; key_length); JSON-schema faults use the coarse "parse" because a conformant verifier may surface any of several internal sentinels for them.

const (
	// TamperDeriveFromAccept is the only supported derive_from: start from the
	// composed file's accept vector.
	TamperDeriveFromAccept = "accept_vector"
	// TamperTransformFlipFirstB64 flips the FIRST base64url character of the accept
	// vector's claims_b64 between 'A' and 'B' ('A'->'B', any other char->'A'). The
	// first symbol encodes the top 6 bits of decoded byte 0, so this changes the
	// DECODED claims (not just don't-care tail bits) AND keeps the string canonical
	// base64url. That makes the derived tamper identical for every consumer
	// regardless of whether it hashes the base64 string, decodes-then-hashes, or
	// strict-decodes before verifying.
	TamperTransformFlipFirstB64 = "flip_first_base64url_char_A_B"
)

Signature-class tamper derivation identifiers. These pin the artifact's language-agnostic derivation so a consumer applies exactly what the JSON specifies rather than a hardcoded rule.

const (
	AgentAssignmentRequestHeaderName = "NHP_LST"
	AgentAssignmentRequestHeaderType = 5
	AgentAssignmentResultHeaderName  = "NHP_LRT"
	AgentAssignmentResultHeaderType  = 6
	// REG/RAK are shared NHP wire identities; these constants describe the
	// assigned-cell activation step, not a second registration wire format.
	AgentAssignmentRegistrationRequestHeaderName = "NHP_REG"
	AgentAssignmentRegistrationRequestHeaderType = 13
	AgentAssignmentRegistrationResultHeaderName  = "NHP_RAK"
	AgentAssignmentRegistrationResultHeaderType  = 14
	// OTP is the one-way, account-credential-only assigned-cell step. It has no
	// result header: the operator receives the code out of band and presents it
	// in the subsequent REG request.
	AgentAssignmentOTPRequestHeaderName = "NHP_OTP"
	AgentAssignmentOTPRequestHeaderType = 12
)

The exact NHP header values used for list request/result exchanges. Results echo their request's counter and never use the overload-cookie reply type.

const (
	AgentAssignmentErrorOutcomeReject         = "reject"
	AgentAssignmentRejectBodyParse            = "body_parse"
	AgentAssignmentRejectUnknownField         = "unknown_field"
	AgentAssignmentRejectMissingField         = "missing_field"
	AgentAssignmentRejectWrongType            = "wrong_type"
	AgentAssignmentRejectListOnError          = "list_on_error"
	AgentAssignmentRejectRetryAfterMissing    = "retry_after_missing"
	AgentAssignmentRejectRetryAfterInvalid    = "retry_after_invalid"
	AgentAssignmentRejectRetryAfterUnexpected = "retry_after_unexpected"
	AgentAssignmentRejectSemantic             = "semantic"
	AgentAssignmentRejectUnknownErrorCode     = "unknown_error_code"
	AgentAssignmentRejectWrongPhase           = "wrong_phase"
	AgentAssignmentRejectTicketBinding        = "ticket_binding"
	AgentAssignmentRejectTicketExpired        = "ticket_expired"
	AgentAssignmentRejectTicketLifetime       = "ticket_lifetime"
	AgentAssignmentRejectPeerBinding          = "peer_binding"
	AgentAssignmentRejectAgentBinding         = "agent_binding"
	AgentAssignmentRejectCredentialBinding    = "credential_binding"
	AgentAssignmentRejectEnvironmentBinding   = "environment_binding"
	AgentAssignmentRejectCellBinding          = "cell_binding"
	AgentAssignmentRejectChallengeBinding     = "challenge_binding"
	AgentAssignmentRejectPacketSize           = "packet_size"
)

Agent-assignment reject outcome and class vocabulary.

const (
	// AgentAssignmentQURLGoProducerRevision is the merged qurl-go packet-codec
	// revision used to build and authenticate-open every assignment lifecycle
	// packet from the artifact's exact application body. It does not claim that
	// the revision's higher-level assignment request builder knows the current
	// artifact schema; consumers add that support conformance-first.
	AgentAssignmentQURLGoProducerRevision = "8a69642957030b9ce0a1b8b356246d265a9f577d"
	// AgentAssignmentNHPProducerRevision is the merged NHP revision that owns
	// the closed assignment and registration error-code taxonomy.
	AgentAssignmentNHPProducerRevision = "9653fcb185c77629b787ad046c13c760baba88f4"
	// AgentAssignmentOTPProducerRevision is the merged NHP revision that
	// preserves the exact decrypted OTP RawBody alongside the independently
	// authenticated initiator public key at the plugin boundary.
	AgentAssignmentOTPProducerRevision = "2072546e1fc76eb76bd7e5c22d37856019ba33e7"
)

Producer revisions for the deterministic wire and error contracts.

const (

	// AgentAssignmentBootstrapCredentialFixture is the exact synthetic,
	// production-shaped credential fixture. Secret scanners must allow only
	// this value, never an lv_live_conformance_* wildcard.
	AgentAssignmentBootstrapCredentialFixture = "lv_live_conformance_bootstrap_secret_0001"
	// AgentAssignmentDeviceAPIKeyFixture is the exact synthetic,
	// production-shaped device-key fixture. Its body is canonical unpadded
	// base64url for the deterministic 32-byte sequence 0x00..0x1f. Secret
	// scanners must allow only this exact value, never an lv_live_* wildcard.
	AgentAssignmentDeviceAPIKeyFixture = "lv_live_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
	// AgentAssignmentAccountCredentialFixture is the exact synthetic account
	// credential carried only by the optional account OTP packet.
	AgentAssignmentAccountCredentialFixture = "lv_live_conformance_account_secret_0001"
	// AgentAssignmentInitialRequestNonceFixture is canonical unpadded base64url
	// for the deterministic 32-byte sequence 0xa0..0xbf.
	AgentAssignmentInitialRequestNonceFixture = "oKGio6SlpqeoqaqrrK2ur7CxsrO0tba3uLm6u7y9vr8"
	// AgentAssignmentRefreshRequestNonceFixture is canonical unpadded base64url
	// for the deterministic 32-byte sequence 0xc0..0xdf.
	AgentAssignmentRefreshRequestNonceFixture = "wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t8"
)

Exact synthetic production-shaped fixture values.

const (
	AgentKnockOutcomeSuccess = "success"
	AgentKnockOutcomeDeny    = "deny"
	AgentKnockOutcomeRetry   = "retry"
	AgentKnockOutcomeReject  = "reject"
)

Agent-knock application outcomes. A consumer drives each reply through its real reply interpreter and derives one of these outcomes; it must not trust the stored label without exercising the application parser and correlation gates.

const (
	AgentKnockRejectServerDeny           = "server_deny"
	AgentKnockRejectServerBusy           = "server_busy"
	AgentKnockRejectWrongResource        = "wrong_resource"
	AgentKnockRejectMissingToken         = "missing_token"
	AgentKnockRejectMissingHost          = "missing_host"
	AgentKnockRejectBodyParse            = "body_parse"
	AgentKnockRejectUnsupportedPreAccess = "unsupported_pre_access"
	AgentKnockRejectCounter              = "counter"
	AgentKnockRejectReplyType            = "reply_type"
)

Agent-knock application reject classes form a closed, consumer-neutral vocabulary. ServerDeny and ServerBusy are authenticated platform outcomes; the other classes are fail-closed client dispositions: validation failures plus the unsupported pre-access feature gate.

const (
	AgentKnockRejectMissingRunID = "missing_run_id"
	AgentKnockRejectInvalidRunID = "invalid_run_id"
)

Agent-knock request reject classes distinguish strict JSON-shape failures from RunID policy failures. MissingRunID is specific to the native Connector entry point; the generic protocol parser intentionally accepts an omitted or empty RunID while rejecting every malformed non-empty value.

const AgentAssignmentArtifactID = "qurl-agent-assignment-golden-vectors"

AgentAssignmentArtifactID is the fixed identity of the NHP assignment, assigned-cell activation, and registration-completion golden artifact.

const AgentKnockApplicationArtifactID = "qurl-agent-knock-application-vectors"

AgentKnockApplicationArtifactID is the fixed identity of the registered-agent knock application-body artifact. It is deliberately separate from RelayKnockArtifactID: this document starts after Noise decryption and carries no packet bytes, private keys, nonces, or ciphertext.

const AgentKnockRunIDLength = 16

AgentKnockRunIDLength is the exact lowercase-hex length of a canonical native-UDP-SDK-generated knock cycle identifier (8 random bytes).

const AgentRegistrationArtifactID = "qurl-agent-registration-golden-vectors"

AgentRegistrationArtifactID is the fixed identity string the agent-registration artifact's top-level "artifact" field must carry. The loader enforces it so a consumer that relies on "the loader rejects malformed files" cannot silently load a DIFFERENT document into these structs. A consumer in another language should assert the same id.

const ConformanceArtifactID = "qurl-v2-conformance-vectors"

ConformanceArtifactID is the fixed identity string the top-level "artifact" field must carry. The loader enforces it so a consumer that relies on "the loader rejects malformed files" cannot silently load a DIFFERENT document into these structs. A consumer in another language should assert the same id.

const RelayKnockArtifactID = "qurl-relay-knock-golden-vectors"

RelayKnockArtifactID is the fixed identity string the relay-knock artifact's top-level "artifact" field must carry. The loader enforces it so a consumer that relies on "the loader rejects malformed files" cannot silently load a DIFFERENT document into these structs. A consumer in another language should assert the same id.

Variables

var (

	// ErrConnectorHubRequestIDEnvironment identifies an invalid immutable Hub
	// environment. It never includes the rejected value.
	ErrConnectorHubRequestIDEnvironment = errors.New("conformance: invalid Connector Hub request-ID environment")
	// ErrConnectorHubRequestIDOperation identifies a value outside the closed
	// separately permissioned Hub authority operations.
	ErrConnectorHubRequestIDOperation = errors.New("conformance: invalid Connector Hub request-ID operation")
	// ErrConnectorHubRequestIDPeer identifies a peer key that is not exactly one
	// raw X25519 public-key width.
	ErrConnectorHubRequestIDPeer = errors.New("conformance: invalid Connector Hub request-ID peer key")
	// ErrConnectorHubRequestIDNonce identifies a logical-request nonce that is
	// not exactly 32 decoded bytes.
	ErrConnectorHubRequestIDNonce = errors.New("conformance: invalid Connector Hub request-ID nonce")
)

Functions

func AgentAPIKeyIDVectors

func AgentAPIKeyIDVectors() []byte

AgentAPIKeyIDVectors returns the raw bytes of the control-plane API-key ID producer and consumer vectors used by agent registration.

func AgentAssignmentVectors

func AgentAssignmentVectors() []byte

AgentAssignmentVectors returns the raw bytes of the deterministic NHP LST/LRT assignment and registration-completion packets plus the account-only OTP request contract.

func AgentCredentialRecoveryVectors

func AgentCredentialRecoveryVectors() []byte

AgentCredentialRecoveryVectors returns the UDP-only same-agent device- credential recovery contract shared by the Hub, assigned cell, Authority, and native SDK.

func AgentKnockApplicationVectors

func AgentKnockApplicationVectors() []byte

AgentKnockApplicationVectors returns the raw bytes of the registered-agent knock application-body vectors. Unlike RelayKnockVectors, this artifact starts after Noise decryption and contains no packet bytes.

func AgentRegistrationVectors

func AgentRegistrationVectors() []byte

AgentRegistrationVectors returns the raw bytes of the embedded NHP agent-registration golden packets (agent_registration_golden.json): the OTP/REG requests and the RAK replies. The bytes are the canonical wire-truth; a consumer that prefers to drive its own strict parser can feed these directly.

func AgentSessionControlVectors

func AgentSessionControlVectors() []byte

AgentSessionControlVectors returns the deterministic native-UDP overload re-knock and clean-exit packet artifact.

func AssignmentTicketVectors

func AssignmentTicketVectors() []byte

AssignmentTicketVectors returns the raw bytes of the standalone qat1 cryptographic and fence artifact.

func ConnectorAuthorityLambdaVectors

func ConnectorAuthorityLambdaVectors() []byte

ConnectorAuthorityLambdaVectors returns the raw bytes of the private, operation-specific NHP-to-authority invocation artifact.

func ConnectorHubLSTChallengeBody

func ConnectorHubLSTChallengeBody(transactionID uint64, cookie []byte) (string, error)

ConnectorHubLSTChallengeBody returns the exact compact COK JSON envelope.

func ConnectorHubLSTCookieVectors

func ConnectorHubLSTCookieVectors() []byte

ConnectorHubLSTCookieVectors returns the Hub assignment return-routability challenge and proof contract.

func ConnectorHubRequestIDVectors

func ConnectorHubRequestIDVectors() []byte

ConnectorHubRequestIDVectors returns the private Hub replay-key derivation KAT shared by Hub worker implementations.

func DecodeConnectorHubRequestNonce

func DecodeConnectorHubRequestNonce(value string) ([]byte, error)

DecodeConnectorHubRequestNonce strictly decodes the public LST request_nonce grammar shared by SDKs and the Hub. The returned raw bytes are suitable for DeriveConnectorHubRequestID.

func DeriveConnectorHubLSTCookie

func DeriveConnectorHubLSTCookie(signingKey []byte, sourceIP string, authenticatedPeerPublicKey []byte, windowIndex uint64) ([]byte, error)

DeriveConnectorHubLSTCookie derives the opaque stateless Hub-LST cookie from a canonical source IP, authenticated initiator key, and rolling window.

func DeriveConnectorHubRequestID

func DeriveConnectorHubRequestID(environment, operation string, authenticatedPeerPublicKey, requestNonce []byte) (string, error)

DeriveConnectorHubRequestID computes the canonical private replay identifier from immutable deployment scope and authenticated logical-request inputs. operation must be the Hub-selected authority operation after strict LST mode validation; authenticatedPeerPublicKey and requestNonce are raw decoded bytes. NHP timestamp and application-body bytes are deliberately absent: a fresh packet retry changes the timestamp, while Authority's existing operation-specific request fingerprint rejects nonce reuse with changed semantics.

func IssuerSignatureVectors

func IssuerSignatureVectors() []byte

IssuerSignatureVectors returns the raw bytes of the embedded issuer-signature golden vectors (issuer_signature_vectors.json), which the signature class composes by reference.

func Open

func Open(name string) ([]byte, error)

Open returns the raw bytes of an embedded vectors file by its base name (for example "qv2_conformance_vectors.json" or "issuer_signature_vectors.json"), or by its full "vectors/..." path. It returns an error for any other name.

func QV2Vectors

func QV2Vectors() []byte

QV2Vectors returns the raw bytes of the embedded qURL v2 conformance vectors (qv2_conformance_vectors.json). The bytes are the canonical wire-truth; a consumer that prefers to drive its own strict parser can feed these directly.

func RelayKnockVectors

func RelayKnockVectors() []byte

RelayKnockVectors returns the raw bytes of the embedded relay/NHP-handshake golden packets (relay_knock_golden.json). The bytes are the canonical wire-truth; a consumer that prefers to drive its own strict parser can feed these directly.

Types

type AgentAPIKeyIDContract

type AgentAPIKeyIDContract struct {
	Prefix         string `json:"prefix"`
	SuffixLength   int    `json:"suffix_length"`
	TotalLength    int    `json:"total_length"`
	SuffixAlphabet string `json:"suffix_alphabet"`
	Pattern        string `json:"pattern"`
}

AgentAPIKeyIDContract is the language-neutral public grammar.

type AgentAPIKeyIDFile

type AgentAPIKeyIDFile struct {
	Artifact              string                      `json:"artifact"`
	SchemaVersion         int                         `json:"schema_version"`
	Description           string                      `json:"description"`
	Contract              AgentAPIKeyIDContract       `json:"contract"`
	Surfaces              []AgentAPIKeyIDSurface      `json:"surfaces"`
	ProducerCases         []AgentAPIKeyIDProducerCase `json:"producer_cases"`
	ConsumerValueCases    []AgentAPIKeyIDValueCase    `json:"consumer_value_cases"`
	ConsumerResponseCases []AgentAPIKeyIDResponseCase `json:"consumer_response_cases"`
}

AgentAPIKeyIDFile freezes producer construction and consumer parsing for the two control-plane fields that carry an API-key identifier during enrollment.

func AgentAPIKeyIDs

func AgentAPIKeyIDs() (*AgentAPIKeyIDFile, error)

AgentAPIKeyIDs strictly parses the embedded agent API-key ID artifact.

func ParseAgentAPIKeyIDFile

func ParseAgentAPIKeyIDFile(data []byte) (*AgentAPIKeyIDFile, error)

ParseAgentAPIKeyIDFile strictly parses the API-key identifier artifact and independently derives every declared producer and consumer expectation.

type AgentAPIKeyIDProducerCase

type AgentAPIKeyIDProducerCase struct {
	Name       string `json:"name"`
	Suffix     string `json:"suffix"`
	ExpectedID string `json:"expected_id"`
}

AgentAPIKeyIDProducerCase lets an issuer drive its production constructor with a deterministic suffix and compare the exact public ID.

type AgentAPIKeyIDResponseCase

type AgentAPIKeyIDResponseCase struct {
	Name        string `json:"name"`
	Surface     string `json:"surface"`
	BodyJSON    string `json:"body_json"`
	Outcome     string `json:"outcome"`
	ExpectedID  string `json:"expected_id,omitempty"`
	RejectClass string `json:"reject_class,omitempty"`
}

AgentAPIKeyIDResponseCase preserves raw JSON so companion fields, duplicate keys, wrong scalar types, and trailing values reach a consumer's response parser without lossy re-serialization.

type AgentAPIKeyIDSurface

type AgentAPIKeyIDSurface struct {
	Name      string `json:"name"`
	WireField string `json:"wire_field"`
}

AgentAPIKeyIDSurface names one public response field that carries the ID.

type AgentAPIKeyIDValueCase

type AgentAPIKeyIDValueCase struct {
	Name        string `json:"name"`
	Value       string `json:"value"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class,omitempty"`
}

AgentAPIKeyIDValueCase is one direct validator input.

type AgentAssignmentCase

type AgentAssignmentCase struct {
	Name        string `json:"name"`
	Phase       string `json:"phase"`
	HeaderName  string `json:"header_name"`
	HeaderType  int    `json:"header_type"`
	BodyJSON    string `json:"body_json"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class"`
}

AgentAssignmentCase is an authenticated application request or result that a producer/consumer must reject. BodyJSON stays raw so duplicate keys and trailing JSON survive artifact parsing.

type AgentAssignmentErrorCase

type AgentAssignmentErrorCase struct {
	Name  string `json:"name"`
	Phase string `json:"phase"`
	// AcceptedPhases names concrete request exchanges when this error is valid
	// before the producer can identify a single mode. It is otherwise omitted.
	AcceptedPhases    []string `json:"accepted_phases,omitempty"`
	HeaderName        string   `json:"header_name"`
	HeaderType        int      `json:"header_type"`
	BodyJSON          string   `json:"body_json"`
	ErrCode           string   `json:"err_code"`
	Outcome           string   `json:"outcome"`
	RetryAfterSeconds *int     `json:"retry_after_seconds,omitempty"`
	// contains filtered or unexported fields
}

func (*AgentAssignmentErrorCase) UnmarshalJSON

func (c *AgentAssignmentErrorCase) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves whether accepted_phases was present so strict validation can distinguish the canonical omission from [] or null. A slice alone cannot represent that wire distinction.

type AgentAssignmentErrorContract

type AgentAssignmentErrorContract struct {
	Status                 string                         `json:"status"`
	ProducerRevision       string                         `json:"producer_revision"`
	Rules                  AgentAssignmentErrorRules      `json:"rules"`
	AssignmentCases        []AgentAssignmentErrorCase     `json:"assignment_cases"`
	InitialCredentialCases []AgentAssignmentErrorCase     `json:"initial_credential_cases"`
	CompletionCases        []AgentAssignmentErrorCase     `json:"completion_cases"`
	RegistrationCases      []AgentAssignmentErrorCase     `json:"registration_cases"`
	MalformedCases         []AgentAssignmentMalformedCase `json:"malformed_cases"`
}

AgentAssignmentErrorContract is the closed v1 authenticated error taxonomy. Valid cases drive production parsers/classifiers; malformed cases drive their strict reject paths. Error bodies are strings so duplicate keys and trailing JSON reach the consumer unchanged.

type AgentAssignmentErrorRules

type AgentAssignmentErrorRules struct {
	ListErrorHeaderName              string   `json:"list_error_header_name"`
	ListErrorHeaderType              int      `json:"list_error_header_type"`
	RegistrationErrorHeaderName      string   `json:"registration_error_header_name"`
	RegistrationErrorHeaderType      int      `json:"registration_error_header_type"`
	ListOmittedOnError               bool     `json:"list_omitted_on_error"`
	CookieChallengeAllowed           bool     `json:"cookie_challenge_allowed"`
	RetryAfterSecondsPermittedCodes  []string `json:"retry_after_seconds_permitted_codes"`
	RetryAfterSecondsRequiredCodes   []string `json:"retry_after_seconds_required_codes"`
	RetryAfterSecondsPositiveInteger bool     `json:"retry_after_seconds_positive_integer"`
	ErrMsgControlsPolicy             bool     `json:"err_msg_controls_policy"`
}

type AgentAssignmentExchange

type AgentAssignmentExchange struct {
	Request AgentAssignmentPacket `json:"request"`
	Result  AgentAssignmentPacket `json:"result"`
}

type AgentAssignmentFile

type AgentAssignmentFile struct {
	Artifact                   string                       `json:"artifact"`
	SchemaVersion              int                          `json:"schema_version"`
	Description                string                       `json:"description"`
	SourceOfTruth              string                       `json:"source_of_truth"`
	Notes                      []string                     `json:"notes"`
	PublicRegistrationKeyKinds []string                     `json:"public_registration_key_kinds"`
	Keys                       AgentAssignmentKeys          `json:"keys"`
	InitialAssignment          AgentAssignmentExchange      `json:"initial_assignment"`
	RefreshAssignment          AgentAssignmentExchange      `json:"refresh_assignment"`
	AssignedCellRegistration   AgentAssignmentExchange      `json:"assigned_cell_registration"`
	RegistrationCompletion     AgentAssignmentExchange      `json:"registration_completion"`
	AccountCredentialOTP       AgentAssignmentOTPContract   `json:"account_credential_otp"`
	RequestCases               []AgentAssignmentRequestCase `json:"request_cases"`
	SuccessResultCases         []AgentAssignmentResultCase  `json:"success_result_cases"`
	ErrorContract              AgentAssignmentErrorContract `json:"error_contract"`
}

AgentAssignmentFile pins four complete deterministic NHP exchanges plus the one-way account-only OTP packet: initial assignment and refresh against the bootstrap hub, optional assigned-cell OTP, assigned-cell registration with the assignment ticket, and registration completion against that cell. ErrorContract is application-layer behavioral data for the same lifecycle.

func AgentAssignmentGolden

func AgentAssignmentGolden() (*AgentAssignmentFile, error)

AgentAssignmentGolden strictly parses the embedded deterministic NHP LST/LRT assignment and registration-completion artifact plus account-only OTP.

func ParseAgentAssignmentFile

func ParseAgentAssignmentFile(data []byte) (*AgentAssignmentFile, error)

ParseAgentAssignmentFile strictly parses and validates the deterministic assignment artifact. It fails closed on schema drift, missing crypto inputs, body byte drift, semantic envelope drift, type/role mix-ups, unmatched counters, or an incomplete/malformed error taxonomy.

type AgentAssignmentKey

type AgentAssignmentKey struct {
	StaticPrivHex string `json:"static_priv_hex"`
	StaticPubHex  string `json:"static_pub_hex"`
}

type AgentAssignmentKeys

type AgentAssignmentKeys struct {
	Hub          AgentAssignmentKey `json:"hub"`
	AssignedCell AgentAssignmentKey `json:"assigned_cell"`
	Agent        AgentAssignmentKey `json:"agent"`
}

AgentAssignmentKeys names the three synthetic static X25519 identities used by the exchanges. Keeping keys at the top level makes the hub/cell trust boundary explicit without repeating private material in every packet case.

type AgentAssignmentMalformedCase

type AgentAssignmentMalformedCase struct {
	Name        string `json:"name"`
	Phase       string `json:"phase"`
	HeaderName  string `json:"header_name"`
	HeaderType  int    `json:"header_type"`
	BodyJSON    string `json:"body_json"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class"`
}

type AgentAssignmentOTPBindingCase

type AgentAssignmentOTPBindingCase struct {
	Name          string `json:"name"`
	MutationField string `json:"mutation_field"`
	MutationValue string `json:"mutation_value"`
	Outcome       string `json:"outcome"`
	RejectClass   string `json:"reject_class,omitempty"`
}

AgentAssignmentOTPBindingCase applies one typed mutation to the exact enrollment baseline. "none" is the positive boundary case; all other mutations isolate one trust fence without duplicating the credential-bearing baseline across the artifact.

type AgentAssignmentOTPChallengeBinding

type AgentAssignmentOTPChallengeBinding struct {
	LookupKeyField                string   `json:"lookup_key_field"`
	RequiredMatchFields           []string `json:"required_match_fields"`
	TicketJTI                     string   `json:"ticket_jti"`
	AuthenticatedPeerPublicKeyB64 string   `json:"authenticated_peer_public_key_b64"`
	DevID                         string   `json:"dev_id"`
	CredentialKeyID               string   `json:"credential_key_id"`
	EnvironmentID                 string   `json:"environment_id"`
	CellID                        string   `json:"cell_id"`
}

AgentAssignmentOTPChallengeBinding freezes the exact challenge-store tuple. TicketJTI is both the lookup key and a required stored value; every other field must match the authenticated OTP request and verified ticket before a later REG code can be accepted. This is metadata, not a storage implementation.

type AgentAssignmentOTPContract

type AgentAssignmentOTPContract struct {
	ProducerRevision                   string                               `json:"producer_revision"`
	RawBodyRequired                    bool                                 `json:"raw_body_required"`
	AuthenticatedPeerPublicKeyRequired bool                                 `json:"authenticated_peer_public_key_required"`
	OTPRegistrationKeyKinds            []string                             `json:"otp_registration_key_kinds"`
	OTPFreeRegistrationKeyKinds        []string                             `json:"otp_free_registration_key_kinds"`
	EnrollmentBinding                  AgentAssignmentOTPEnrollmentBinding  `json:"enrollment_binding"`
	ChallengeBinding                   AgentAssignmentOTPChallengeBinding   `json:"challenge_binding"`
	Request                            AgentAssignmentPacket                `json:"request"`
	RequestCases                       []AgentAssignmentRequestCase         `json:"request_cases"`
	BindingCases                       []AgentAssignmentOTPBindingCase      `json:"binding_cases"`
	ChallengeBindingCases              []AgentAssignmentOTPBindingCase      `json:"challenge_binding_cases"`
	PacketSizeContract                 AgentAssignmentOTPPacketSizeContract `json:"packet_size_contract"`
}

AgentAssignmentOTPContract is the optional assigned-cell OTP request for an account credential. It is deliberately a contract artifact, not an SDK or authority implementation: the deterministic packet freezes the authenticated wire bytes, request cases freeze strict RawBody parsing, binding cases freeze the inputs an authority must compare, and packet-size cases drive the real producer codec from the verifier module.

type AgentAssignmentOTPEnrollmentBinding

type AgentAssignmentOTPEnrollmentBinding struct {
	RequestAssignmentTicket       string `json:"request_assignment_ticket"`
	VerifiedAssignmentTicket      string `json:"verified_assignment_ticket"`
	RequestAgentID                string `json:"request_agent_id"`
	TicketAgentID                 string `json:"ticket_agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	TicketAgentPublicKeyB64       string `json:"ticket_agent_public_key_b64"`
	RequestRegistrationKeyID      string `json:"request_registration_key_id"`
	TicketCredentialKeyID         string `json:"ticket_credential_key_id"`
	TicketCredentialKind          string `json:"ticket_credential_kind"`
	RequestCredential             string `json:"request_credential"`
	RequestCredentialHashB64      string `json:"request_credential_hash_b64"`
	TicketCredentialKeyHashB64    string `json:"ticket_credential_key_hash_b64"`
	RecomputedCredentialFenceB64  string `json:"recomputed_credential_fence_b64"`
	TicketCredentialFenceB64      string `json:"ticket_credential_fence_b64"`
	TicketJTI                     string `json:"ticket_jti"`
	LocalEnvironmentID            string `json:"local_environment_id"`
	TicketEnvironmentID           string `json:"ticket_environment_id"`
	LocalCellID                   string `json:"local_cell_id"`
	TicketCellID                  string `json:"ticket_cell_id"`
	EvaluatedAtUnix               int64  `json:"evaluated_at_unix"`
	TicketExpiresAtUnix           int64  `json:"ticket_expires_at_unix"`
	MinimumTicketRemainingSeconds int64  `json:"minimum_ticket_remaining_seconds"`
}

AgentAssignmentOTPEnrollmentBinding is the trusted baseline from which each binding case starts. Request* values come from the authenticated RawBody; Ticket* values come from verified ticket claims; AuthenticatedPeerPublicKeyB64 comes from the Noise transaction; Local* values come from server configuration.

type AgentAssignmentOTPPacketSizeCase

type AgentAssignmentOTPPacketSizeCase struct {
	Name                string `json:"name"`
	BodyBytes           int    `json:"body_bytes"`
	ExpectedPacketBytes int    `json:"expected_packet_bytes,omitempty"`
	Outcome             string `json:"outcome"`
	RejectClass         string `json:"reject_class,omitempty"`
}

type AgentAssignmentOTPPacketSizeContract

type AgentAssignmentOTPPacketSizeContract struct {
	HeaderBytes           int                                `json:"header_bytes"`
	BodyAEADTagBytes      int                                `json:"body_aead_tag_bytes"`
	MaxPlaintextBodyBytes int                                `json:"max_plaintext_body_bytes"`
	MaxPacketBytes        int                                `json:"max_packet_bytes"`
	BodyFillByteHex       string                             `json:"body_fill_byte_hex"`
	Cases                 []AgentAssignmentOTPPacketSizeCase `json:"cases"`
}

type AgentAssignmentPacket

type AgentAssignmentPacket struct {
	HeaderName       string `json:"header_name"`
	HeaderType       int    `json:"header_type"`
	SenderKey        string `json:"sender_key"`
	ReceiverKey      string `json:"receiver_key"`
	EphemeralPrivHex string `json:"ephemeral_priv_hex"`
	TimestampNanos   string `json:"timestamp_nanos"`
	Counter          string `json:"counter"`
	PreambleHex      string `json:"preamble_hex"`
	BodyJSON         string `json:"body_json"`
	BodyHex          string `json:"body_hex"`
	PacketHex        string `json:"packet_hex"`
}

AgentAssignmentPacket is one deterministic LST, LRT, REG, or RAK packet. body_json is a string, rather than an embedded object, because its exact UTF-8 bytes and field order are cryptographic input; body_hex must encode those same bytes.

type AgentAssignmentRequestCase

type AgentAssignmentRequestCase AgentAssignmentCase

AgentAssignmentRequestCase is an authenticated application request reject. It is intentionally distinct from AgentAssignmentResultCase so callers cannot interchange request and result cases at compile time.

type AgentAssignmentResultCase

type AgentAssignmentResultCase AgentAssignmentCase

AgentAssignmentResultCase is an authenticated success-envelope reject. It is intentionally distinct from AgentAssignmentRequestCase so callers cannot interchange request and result cases at compile time.

type AgentCredentialRecoveryBindingCase

type AgentCredentialRecoveryBindingCase struct {
	Name        string `json:"name"`
	Mutation    string `json:"mutation"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class,omitempty"`
}

type AgentCredentialRecoveryBodyCase

type AgentCredentialRecoveryBodyCase struct {
	Name        string `json:"name"`
	Phase       string `json:"phase"`
	BodyJSON    string `json:"body_json"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class"`
}

type AgentCredentialRecoveryErrorCase

type AgentCredentialRecoveryErrorCase struct {
	Name              string `json:"name"`
	Phase             string `json:"phase"`
	BodyJSON          string `json:"body_json"`
	ErrCode           string `json:"err_code"`
	Outcome           string `json:"outcome"`
	RetryAfterSeconds int64  `json:"retry_after_seconds,omitempty"`
}

type AgentCredentialRecoveryExchange

type AgentCredentialRecoveryExchange struct {
	Phase           string `json:"phase"`
	RequestBodyJSON string `json:"request_body_json"`
	SuccessBodyJSON string `json:"success_body_json"`
}

type AgentCredentialRecoveryFile

type AgentCredentialRecoveryFile struct {
	Artifact          string                                      `json:"artifact"`
	SchemaVersion     int                                         `json:"schema_version"`
	Description       string                                      `json:"description"`
	Protocol          AgentCredentialRecoveryProtocol             `json:"protocol"`
	Fixtures          AgentCredentialRecoveryFixtures             `json:"fixtures"`
	HubCookie         AgentCredentialRecoveryHubCookieComposition `json:"hub_cookie_composition"`
	PublicExchanges   map[string]AgentCredentialRecoveryExchange  `json:"public_exchanges"`
	PrivateOperations map[string]AgentCredentialRecoveryOperation `json:"private_operations"`
	RequestRejects    []AgentCredentialRecoveryBodyCase           `json:"request_rejects"`
	ResultRejects     []AgentCredentialRecoveryBodyCase           `json:"result_rejects"`
	ErrorCases        []AgentCredentialRecoveryErrorCase          `json:"error_cases"`
	IssueReplayCases  []AgentCredentialRecoveryBindingCase        `json:"issue_replay_cases"`
	GrantBindingCases []AgentCredentialRecoveryBindingCase        `json:"grant_binding_cases"`
	FlowCases         []AgentCredentialRecoveryBindingCase        `json:"flow_cases"`
}

AgentCredentialRecoveryFile freezes the public UDP bodies, private operation-specific authority bodies, binding mutations, and closed result taxonomy for explicit same-agent device-credential recovery.

func AgentCredentialRecovery

func AgentCredentialRecovery() (*AgentCredentialRecoveryFile, error)

AgentCredentialRecovery strictly parses the UDP-only same-agent device- credential recovery artifact.

func ParseAgentCredentialRecoveryFile

func ParseAgentCredentialRecoveryFile(data []byte) (*AgentCredentialRecoveryFile, error)

type AgentCredentialRecoveryFixtures

type AgentCredentialRecoveryFixtures struct {
	Environment                   string `json:"environment"`
	AgentID                       string `json:"agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	RequestNonce                  string `json:"request_nonce"`
	RecoveryCredential            string `json:"recovery_credential"`
	HubRequestID                  string `json:"hub_request_id"`
	RecoveryGrant                 string `json:"recovery_grant"`
	RecoveryGrantIssuedAt         string `json:"recovery_grant_issued_at"`
	RecoveryGrantExpiresAt        string `json:"recovery_grant_expires_at"`
	DeviceAPIKeyCandidate         string `json:"device_api_key_candidate"`
	DeviceAPIKeyID                string `json:"device_api_key_id"`
	CellID                        string `json:"cell_id"`
	AssignmentGeneration          int64  `json:"assignment_generation"`
	EndpointRevision              int64  `json:"endpoint_revision"`
	LeaseExpiresAt                string `json:"lease_expires_at"`
	NHPHost                       string `json:"nhp_host"`
	NHPPort                       int    `json:"nhp_port"`
	ServerPublicKeyB64            string `json:"server_public_key_b64"`
}

type AgentCredentialRecoveryHubCookieComposition

type AgentCredentialRecoveryHubCookieComposition struct {
	BaseContractArtifact            string                               `json:"base_contract_artifact"`
	Phase                           string                               `json:"phase"`
	UnprovenCounter                 string                               `json:"unproven_counter"`
	ProofCounter                    string                               `json:"proof_counter"`
	UnprovenBodyJSON                string                               `json:"unproven_body_json"`
	ProofBodyJSON                   string                               `json:"proof_body_json"`
	RequestNonce                    string                               `json:"request_nonce"`
	UnprovenHeaderFlagsHex          string                               `json:"unproven_header_flags_hex"`
	ProofHeaderFlagsHex             string                               `json:"proof_header_flags_hex"`
	UnprovenRequestBodyBytes        int                                  `json:"unproven_request_body_bytes"`
	UnprovenRequestPacketBytes      int                                  `json:"unproven_request_packet_bytes"`
	ChallengeBodyJSON               string                               `json:"challenge_body_json"`
	ChallengeBodyBytes              int                                  `json:"challenge_body_bytes"`
	ChallengePacketBytes            int                                  `json:"challenge_packet_bytes"`
	ProofRequestPacketBytes         int                                  `json:"proof_request_packet_bytes"`
	SuccessBodyBytes                int                                  `json:"success_body_bytes"`
	SuccessPacketBytes              int                                  `json:"success_packet_bytes"`
	MaximumGrantSuccessBodyBytes    int                                  `json:"maximum_grant_success_body_bytes"`
	MaximumGrantSuccessPacketBytes  int                                  `json:"maximum_grant_success_packet_bytes"`
	AuthorityInvocationsBeforeProof int                                  `json:"authority_invocations_before_proof"`
	AuthorityInvocationsAfterProof  int                                  `json:"authority_invocations_after_proof"`
	Cases                           []AgentCredentialRecoveryBindingCase `json:"cases"`
}

type AgentCredentialRecoveryOperation

type AgentCredentialRecoveryOperation struct {
	RequestBodyJSON string                                    `json:"request_body_json"`
	SuccessBodyJSON string                                    `json:"success_body_json"`
	SemanticErrors  []AgentCredentialRecoveryPrivateErrorCase `json:"semantic_errors"`
	PublicMappings  []AgentCredentialRecoveryPublicMapping    `json:"public_mapping_cases"`
}

type AgentCredentialRecoveryPrivateErrorCase

type AgentCredentialRecoveryPrivateErrorCase struct {
	Code     string `json:"code"`
	BodyJSON string `json:"body_json"`
}

type AgentCredentialRecoveryProtocol

type AgentCredentialRecoveryProtocol struct {
	Transport                                string   `json:"transport"`
	RequestHeaderName                        string   `json:"request_header_name"`
	RequestHeaderType                        int      `json:"request_header_type"`
	ResultHeaderName                         string   `json:"result_header_name"`
	ResultHeaderType                         int      `json:"result_header_type"`
	ResultCounterRule                        string   `json:"result_counter_rule"`
	HubQuery                                 string   `json:"hub_query"`
	HubMode                                  string   `json:"hub_mode"`
	CellQuery                                string   `json:"cell_query"`
	AuthenticatedIdentityProof               string   `json:"authenticated_identity_proof"`
	TakeoverPolicy                           string   `json:"takeover_policy"`
	RecoveryCredentialKind                   string   `json:"recovery_credential_kind"`
	RecoveryCredentialScope                  string   `json:"recovery_credential_scope"`
	MalformedRecoveryCredentialOutcome       string   `json:"malformed_recovery_credential_outcome"`
	CanonicalRecoveryCredentialRejectOutcome string   `json:"canonical_recovery_credential_reject_outcome"`
	HubRequestIDOperation                    string   `json:"hub_request_id_operation"`
	IssueSemanticFingerprintFields           []string `json:"issue_semantic_fingerprint_fields"`
	IssueReplayRule                          string   `json:"issue_replay_rule"`
	HubCookieContract                        string   `json:"hub_cookie_contract"`
	MaxRecoveryGrantASCIIBytes               int      `json:"max_recovery_grant_ascii_bytes"`
	RecoveryGrantLifetimeSeconds             int64    `json:"recovery_grant_lifetime_seconds"`
	NonemptyPacketOverheadBytes              int      `json:"nonempty_packet_overhead_bytes"`
	RecoveryHorizonSeconds                   int64    `json:"recovery_horizon_seconds"`
	RecoveryHorizonAnchor                    string   `json:"recovery_horizon_anchor"`
	RecoveryEpisodeIdentity                  string   `json:"recovery_episode_identity"`
	NewRecoveryEpisodeRule                   string   `json:"new_recovery_episode_rule"`
	RecoveryDeadlineRule                     string   `json:"recovery_deadline_rule"`
	LaterGrantOrLocalClockExtensionAllowed   bool     `json:"later_grant_or_local_clock_extension_allowed"`
	MaxPlaintextBodyBytes                    int      `json:"max_plaintext_body_bytes"`
	MaxPacketBytes                           int      `json:"max_packet_bytes"`
	RetryRule                                string   `json:"retry_rule"`
	HTTPFallbackAllowed                      bool     `json:"http_fallback_allowed"`
	RelayFallbackAllowed                     bool     `json:"relay_fallback_allowed"`
	ClientCellSelectionAllowed               bool     `json:"client_cell_selection_allowed"`
}

func (*AgentCredentialRecoveryProtocol) UnmarshalJSON

func (protocol *AgentCredentialRecoveryProtocol) UnmarshalJSON(data []byte) error

UnmarshalJSON requires every false-valued security decision to be present; a missing key must not silently inherit Go's false zero value.

type AgentCredentialRecoveryPublicMapping

type AgentCredentialRecoveryPublicMapping struct {
	Name                    string `json:"name"`
	MappingSource           string `json:"mapping_source"`
	PrivateOutcome          string `json:"private_outcome"`
	PrivateResponseBodyJSON string `json:"private_response_body_json"`
	NHPAction               string `json:"nhp_action"`
	NHPBodyJSON             string `json:"nhp_body_json"`
	RetryDisposition        string `json:"retry_disposition"`
}

type AgentKnockApplicationFile

type AgentKnockApplicationFile struct {
	Artifact      string                       `json:"artifact"`
	SchemaVersion int                          `json:"schema_version"`
	Description   string                       `json:"description"`
	SourceOfTruth string                       `json:"source_of_truth"`
	Notes         []string                     `json:"notes"`
	Request       AgentKnockApplicationRequest `json:"request"`
	RequestCases  []AgentKnockRequestCase      `json:"request_cases"`
	ReplyCases    []AgentKnockReplyCase        `json:"reply_cases"`
}

AgentKnockApplicationFile is the versioned application-layer contract for a registered-agent NHP knock. Request carries one deterministic body golden; RequestCases pin generic-parser versus native-Connector RunID policy; and ReplyCases cover the complete current ACK producer envelope, success result values, authenticated deny, overload, unsupported pre-access, and fail-closed application/correlation negatives without duplicating Noise packet vectors.

func AgentKnockApplication

func AgentKnockApplication() (*AgentKnockApplicationFile, error)

AgentKnockApplication strictly parses the embedded registered-agent knock application-body artifact into a typed document.

func ParseAgentKnockApplicationFile

func ParseAgentKnockApplicationFile(data []byte) (*AgentKnockApplicationFile, error)

ParseAgentKnockApplicationFile strictly parses and validates the application-body artifact. It rejects duplicate/unknown/trailing outer fields, stale schema versions, missing or unknown cases, invalid enums/counters, duplicate case names, and a request golden that does not exactly match its semantic fields. It independently derives both declared request-parser outcomes and cross-checks success result labels against the requested resource's raw body maps so labels cannot drift, and rejects a declared success that carries any non-null preActions value. Remaining reply semantics stay the consumer's job: those bodies include intentional wrong-map shapes and trailing data that must reach the production parser. Invalid raw JSON is allowed only for an explicit body_parse reject.

type AgentKnockApplicationRequest

type AgentKnockApplicationRequest struct {
	WireType int                                `json:"wire_type"`
	Fields   AgentKnockApplicationRequestFields `json:"fields"`
	BodyJSON string                             `json:"body_json"`
}

AgentKnockApplicationRequest pins the outer NHP type, semantic synthetic inputs, and exact compact JSON body. Keeping the semantic inputs beside the golden prevents a consumer from merely copying BodyJSON: it must construct the body through its production serializer and compare the resulting bytes.

type AgentKnockApplicationRequestFields

type AgentKnockApplicationRequestFields struct {
	HeaderType      int    `json:"header_type"`
	UserID          string `json:"user_id"`
	DeviceID        string `json:"device_id"`
	AuthServiceID   string `json:"auth_service_id"`
	KnockResourceID string `json:"knock_resource_id"`
	RunID           string `json:"run_id"`
}

AgentKnockApplicationRequestFields names the six load-bearing registered- agent fields without importing any producer implementation type.

type AgentKnockReplyCase

type AgentKnockReplyCase struct {
	Name                 string `json:"name"`
	ReplyType            int    `json:"reply_type"`
	RequestCounter       string `json:"request_counter"`
	ReplyCounter         string `json:"reply_counter"`
	BodyJSON             string `json:"body_json"`
	Outcome              string `json:"outcome"`
	RejectClass          string `json:"reject_class,omitempty"`
	ExpectedACToken      string `json:"expected_ac_token,omitempty"`
	ExpectedResourceHost string `json:"expected_resource_host,omitempty"`
}

AgentKnockReplyCase is one already-decrypted reply disposition. Counter values are decimal strings so JavaScript consumers never lose uint64 precision. BodyJSON stays raw so malformed application shapes, including deliberate trailing data, survive the artifact and reach the consumer's real parser. ExpectedACToken and ExpectedResourceHost are present only on success and pin the exact requested-resource map values a conforming interpreter must return; optional ACK metadata cannot substitute for either.

type AgentKnockRequestCase

type AgentKnockRequestCase struct {
	Name            string                       `json:"name"`
	BodyJSON        string                       `json:"body_json"`
	GenericParser   AgentKnockRequestExpectation `json:"generic_parser"`
	NativeConnector AgentKnockRequestExpectation `json:"native_connector"`
}

AgentKnockRequestCase is one authenticated KNK JSON-body input evaluated at both protocol entry points. BodyJSON remains raw so duplicate keys and alias spellings reach each consumer's real strict parser.

type AgentKnockRequestExpectation

type AgentKnockRequestExpectation struct {
	Outcome     string  `json:"outcome"`
	ParsedRunID *string `json:"parsed_run_id,omitempty"`
	RejectClass string  `json:"reject_class,omitempty"`
}

AgentKnockRequestExpectation is the declared result at one request parser. ParsedRunID is required on accept (including the accepted empty generic value) and absent on reject; RejectClass follows the inverse rule.

type AgentRegistrationCase

type AgentRegistrationCase struct {
	// ServerStaticPrivHex / ServerStaticPubHex are the server static X25519 key.
	// Deterministic cases carry both; frozen (RAK) cases carry only the public half.
	ServerStaticPrivHex string `json:"server_static_priv_hex,omitempty"`
	ServerStaticPubHex  string `json:"server_static_pub_hex"`
	// DeviceStaticPrivHex / DeviceStaticPubHex are the initiator (agent/device)
	// static X25519 key, used by the deterministic OTP/REG cases.
	DeviceStaticPrivHex string `json:"device_static_priv_hex,omitempty"`
	DeviceStaticPubHex  string `json:"device_static_pub_hex,omitempty"`
	// AgentStaticPrivHex is the agent (responder-side decryptor) static private
	// X25519 key, used by the frozen RAK cases to open the reply. It is the same
	// key as the deterministic cases' device_static_priv_hex.
	AgentStaticPrivHex string `json:"agent_static_priv_hex,omitempty"`
	// EphemeralPrivHex is the fixed initiator ephemeral private key the
	// deterministic cases seal under (so the packet is reproducible).
	EphemeralPrivHex string `json:"ephemeral_priv_hex,omitempty"`
	// TimestampNanos is the handshake timestamp, decimal string (exceeds 2^53).
	TimestampNanos string `json:"timestamp_nanos"`
	// Counter is the deterministic-case counter as a decimal string.
	Counter string `json:"counter,omitempty"`
	// CounterHex is the frozen RAK counter as a hex string (no 0x prefix, no
	// padding). It echoes reg_emailed's counter for the matched pair.
	CounterHex string `json:"counter_hex,omitempty"`
	// PreambleHex is the 32-bit HeaderCommon preamble as a hex string
	// (deterministic cases).
	PreambleHex string `json:"preamble_hex,omitempty"`
	// BodyHex is the plaintext registration body the case carries, hex-encoded
	// (AgentOTPMsg / AgentRegisterMsg / ServerRegisterAckMsg JSON).
	BodyHex string `json:"body_hex"`
	// PacketHex is the full wire packet, hex-encoded: for a deterministic case,
	// the value a conformant builder must reproduce; for a frozen RAK case, the
	// value a conformant decryptor must open.
	PacketHex string `json:"packet_hex"`
}

AgentRegistrationCase is one golden packet: an OTP/REG initiator request or a RAK reply. Every value is the exact hex (or, for the numeric fields, the stringified value) the case uses; only the fields relevant to a given case are populated. All fields are strings — including timestamp_nanos, which exceeds 2^53 and so is carried as a decimal string rather than a JSON number.

Deterministic cases (otp, reg_emailed, reg_preissued) carry the same fields as relay_knock's knock: the server/device static keypairs, the fixed initiator ephemeral, the timestamp/counter/preamble, the plaintext body, and the full packet a conformant builder must reproduce. Frozen cases (rak_success, rak_error) carry the ack-style fields: the server static PUBLIC key, the agent (responder-side decryptor) static PRIVATE key, the counter as hex, the body, and the frozen packet a conformant decryptor must open.

type AgentRegistrationFile

type AgentRegistrationFile struct {
	Artifact      string                `json:"artifact"`
	SchemaVersion int                   `json:"schema_version"`
	Description   string                `json:"description"`
	SourceOfTruth string                `json:"source_of_truth"`
	Notes         []string              `json:"notes"`
	OTP           AgentRegistrationCase `json:"otp"`
	RegEmailed    AgentRegistrationCase `json:"reg_emailed"`
	RegPreissued  AgentRegistrationCase `json:"reg_preissued"`
	RakSuccess    AgentRegistrationCase `json:"rak_success"`
	RakError      AgentRegistrationCase `json:"rak_error"`
}

AgentRegistrationFile is the top-level NHP agent-registration golden artifact: the OTP request, the emailed-code and pre-issued-key REG requests (all three DETERMINISTIC — a conformant initiator must reproduce packet_hex byte-for-byte), and the server register-ack (RAK) success/error replies (FROZEN, sealed at origin with a random server ephemeral, so NOT reproducible by a client — only decryptable). Every case decodes into the same AgentRegistrationCase, which carries the UNION of the fields the deterministic and frozen cases use.

The reg_emailed → rak pair is counter-matched (rak_success/rak_error echo reg_emailed's counter), so a consumer can validate the RAK-must-echo-its-REG counter contract (conformance#19) against a positive fixture.

func AgentRegistrationGolden

func AgentRegistrationGolden() (*AgentRegistrationFile, error)

AgentRegistrationGolden strictly parses the embedded NHP agent-registration golden artifact into a typed document, returning an error if it is malformed or is not the expected artifact.

func ParseAgentRegistrationFile

func ParseAgentRegistrationFile(data []byte) (*AgentRegistrationFile, error)

ParseAgentRegistrationFile strictly parses the agent-registration golden artifact from raw bytes. It returns an error (never an empty/zero document) when the bytes are malformed or are not the agent-registration artifact, so a consumer test FAILS rather than silently skipping or misreading the contract. DisallowUnknownFields keeps a typo'd or stale schema field from being ignored.

type AgentSessionCleanExit

type AgentSessionCleanExit struct {
	Request AgentSessionPacket `json:"request"`
	ACK     AgentSessionPacket `json:"ack"`
}

type AgentSessionControlFile

type AgentSessionControlFile struct {
	Artifact         string                       `json:"artifact"`
	SchemaVersion    int                          `json:"schema_version"`
	Description      string                       `json:"description"`
	SourceOfTruth    string                       `json:"source_of_truth"`
	ProducerRevision string                       `json:"producer_revision"`
	Notes            []string                     `json:"notes"`
	Protocol         AgentSessionProtocol         `json:"protocol"`
	Keys             AgentSessionKeys             `json:"keys"`
	OverloadReknock  AgentSessionOverloadReknock  `json:"overload_reknock"`
	CleanExit        AgentSessionCleanExit        `json:"clean_exit"`
	CookieBodyCases  []AgentSessionCookieBodyCase `json:"cookie_body_cases"`
	// FlowCases is a closed, consumer-driven expectation table. Each consumer
	// synthesizes the named mutations against its real session implementation.
	FlowCases []AgentSessionFlowCase `json:"flow_cases"`
}

AgentSessionControlFile is the complete packet and negative-case contract for one overload KNK/COK/RKN/ACK sequence and one clean EXT/ACK sequence.

func AgentSessionControl

func AgentSessionControl() (*AgentSessionControlFile, error)

AgentSessionControl strictly parses the native-UDP overload re-knock and clean-exit packet artifact.

func ParseAgentSessionControlFile

func ParseAgentSessionControlFile(data []byte) (*AgentSessionControlFile, error)

ParseAgentSessionControlFile strictly parses and semantically validates the registered-agent RKN/EXT artifact. It never accepts a partial fixture.

type AgentSessionCookieBodyCase

type AgentSessionCookieBodyCase struct {
	Name        string `json:"name"`
	BodyJSON    string `json:"body_json"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class,omitempty"`
}

type AgentSessionFlowCase

type AgentSessionFlowCase struct {
	Name        string `json:"name"`
	Stage       string `json:"stage"`
	Mutation    string `json:"mutation"`
	Outcome     string `json:"outcome"`
	RejectClass string `json:"reject_class,omitempty"`
}

type AgentSessionKey

type AgentSessionKey struct {
	StaticPrivateHex string `json:"static_private_hex"`
	StaticPublicHex  string `json:"static_public_hex"`
}

type AgentSessionKeys

type AgentSessionKeys struct {
	AssignedCell AgentSessionKey `json:"assigned_cell"`
	Agent        AgentSessionKey `json:"agent"`
}

type AgentSessionOverloadReknock

type AgentSessionOverloadReknock struct {
	CookieHex      string             `json:"cookie_hex"`
	CookieB64      string             `json:"cookie_b64"`
	KnockRequest   AgentSessionPacket `json:"knock_request"`
	CookieReply    AgentSessionPacket `json:"cookie_reply"`
	ReknockRequest AgentSessionPacket `json:"reknock_request"`
	ACK            AgentSessionPacket `json:"ack"`
}

type AgentSessionPacket

type AgentSessionPacket struct {
	HeaderName          string `json:"header_name"`
	HeaderType          int    `json:"header_type"`
	SenderKey           string `json:"sender_key"`
	ReceiverKey         string `json:"receiver_key"`
	EphemeralPrivateHex string `json:"ephemeral_private_hex"`
	TimestampNanos      string `json:"timestamp_nanos"`
	Counter             string `json:"counter"`
	PreambleHex         string `json:"preamble_hex"`
	BodyJSON            string `json:"body_json"`
	BodyHex             string `json:"body_hex"`
	HeaderDigestHex     string `json:"header_digest_hex"`
	PacketHex           string `json:"packet_hex"`
}

AgentSessionPacket carries every deterministic input plus the full packet. Replies are deterministic in this artifact too, so both directions can be authenticated and reproduced independently.

type AgentSessionProtocol

type AgentSessionProtocol struct {
	CookieSizeBytes               int    `json:"cookie_size_bytes"`
	CookieEncoding                string `json:"cookie_encoding"`
	COKWireCounterCorrelation     string `json:"cok_wire_counter_correlation"`
	COKBodyTransactionCorrelation string `json:"cok_body_transaction_correlation"`
	ACKCounterCorrelation         string `json:"ack_counter_correlation"`
	RKNHeaderDigest               string `json:"rkn_header_digest"`
	ExitCookieChallengeAllowed    bool   `json:"exit_cookie_challenge_allowed"`
}

type AssignmentTicketClaimsReject

type AssignmentTicketClaimsReject struct {
	Name        string                            `json:"name"`
	RejectClass string                            `json:"reject_class"`
	Reason      string                            `json:"reason"`
	ClaimsJSON  string                            `json:"claims_json,omitempty"`
	Derivation  *AssignmentTicketRepeatDerivation `json:"derivation,omitempty"`
}

AssignmentTicketClaimsReject drives strict parsing before signing/verification.

func (AssignmentTicketClaimsReject) ResolveClaims

func (c AssignmentTicketClaimsReject) ResolveClaims() (string, error)

ResolveClaims returns the exact strict-parser input for a claims reject.

type AssignmentTicketContract

type AssignmentTicketContract struct {
	TokenPrefix              string   `json:"token_prefix"`
	SigningAlgorithm         string   `json:"signing_algorithm"`
	SigningDomain            string   `json:"signing_domain"`
	SigningSeparatorHex      string   `json:"signing_separator_hex"`
	SignatureEncoding        string   `json:"signature_encoding"`
	KMSMessageType           string   `json:"kms_message_type"`
	KMSOutputEncoding        string   `json:"kms_output_encoding"`
	MaxTicketASCIIBytes      int      `json:"max_ticket_ascii_bytes"`
	MaxClaimsPartCharacters  int      `json:"max_claims_part_characters"`
	MaxClaimsJSONBytes       int      `json:"max_claims_json_bytes"`
	RawSignatureBytes        int      `json:"raw_signature_bytes"`
	SignaturePartCharacters  int      `json:"signature_part_characters"`
	MaxKIDCharacters         int      `json:"max_kid_characters"`
	DigestCharacters         int      `json:"digest_characters"`
	AgentPublicKeyCharacters int      `json:"agent_public_key_characters"`
	MaxLifetimeSeconds       int      `json:"max_lifetime_seconds"`
	NotBeforeOffsetSeconds   int      `json:"not_before_offset_seconds"`
	NHPBodyMaxBytes          int      `json:"nhp_body_max_bytes"`
	NHPPacketMaxBytes        int      `json:"nhp_packet_max_bytes"`
	ClaimOrder               []string `json:"claim_order"`
	CredentialKinds          []string `json:"credential_kinds"`
	PlacementModes           []string `json:"placement_modes"`
}

AssignmentTicketContract is the closed wire and size profile.

type AssignmentTicketDERCase

type AssignmentTicketDERCase struct {
	Name           string `json:"name"`
	Outcome        string `json:"outcome"`
	RejectClass    string `json:"reject_class,omitempty"`
	Reason         string `json:"reason"`
	DERHex         string `json:"der_hex"`
	ExpectedRawHex string `json:"expected_raw_low_s_hex,omitempty"`
}

AssignmentTicketDERCase drives KMS DER-to-raw-low-S normalization.

type AssignmentTicketFencePart

type AssignmentTicketFencePart struct {
	Name     string `json:"name"`
	Encoding string `json:"encoding"`
	Value    string `json:"value"`
	BytesHex string `json:"bytes_hex"`
}

AssignmentTicketFencePart exposes both the semantic input and its exact bytes. Value is always a string; Encoding determines how to interpret it.

type AssignmentTicketFenceReject

type AssignmentTicketFenceReject struct {
	Name        string `json:"name"`
	FenceKind   string `json:"fence_kind"`
	RejectClass string `json:"reject_class"`
	Reason      string `json:"reason"`
	Mutation    string `json:"mutation"`
}

AssignmentTicketFenceReject freezes invalid typed fence input classes.

type AssignmentTicketFenceVector

type AssignmentTicketFenceVector struct {
	Name         string                      `json:"name"`
	Kind         string                      `json:"kind"`
	Domain       string                      `json:"domain"`
	Parts        []AssignmentTicketFencePart `json:"parts"`
	PreimageHex  string                      `json:"preimage_hex"`
	DigestHex    string                      `json:"digest_hex"`
	DigestB64URL string                      `json:"digest_b64url"`
}

AssignmentTicketFenceVector freezes one exact length-framed fence preimage.

type AssignmentTicketFile

type AssignmentTicketFile struct {
	Artifact            string                         `json:"artifact"`
	SchemaVersion       int                            `json:"schema_version"`
	Description         string                         `json:"description"`
	Contract            AssignmentTicketContract       `json:"contract"`
	SyntheticSigningKey AssignmentTicketSyntheticKey   `json:"synthetic_signing_key"`
	FenceVectors        []AssignmentTicketFenceVector  `json:"fence_vectors"`
	Golden              AssignmentTicketGolden         `json:"golden"`
	VerifyRejects       []AssignmentTicketVerifyReject `json:"verify_rejects"`
	ClaimsRejects       []AssignmentTicketClaimsReject `json:"claims_rejects"`
	KMSDERCases         []AssignmentTicketDERCase      `json:"kms_der_cases"`
	FenceRejects        []AssignmentTicketFenceReject  `json:"fence_rejects"`
	TrustKeyRejects     []AssignmentTicketTrustReject  `json:"trust_key_rejects"`
}

AssignmentTicketFile freezes the byte-level qat1 signing profile, the three optimistic fences, and negative inputs for strict producer/verifier tests.

func AssignmentTicket

func AssignmentTicket() (*AssignmentTicketFile, error)

AssignmentTicket strictly parses the embedded standalone qat1 artifact.

func ParseAssignmentTicketFile

func ParseAssignmentTicketFile(data []byte) (*AssignmentTicketFile, error)

ParseAssignmentTicketFile strictly parses and structurally validates the qat1 artifact. Cryptographic byte identity is checked independently by tools/verify-assignment-ticket.

type AssignmentTicketGolden

type AssignmentTicketGolden struct {
	EnvironmentID          string `json:"environment_id"`
	VerifyAtUnix           int64  `json:"verify_at_unix"`
	ClockUnix              int64  `json:"clock_unix"`
	JTIRandomHex           string `json:"jti_random_hex"`
	SyntheticECDSANonceHex string `json:"synthetic_ecdsa_nonce_hex"`
	SyntheticCredential    string `json:"synthetic_presented_credential"`
	ClaimsJSON             string `json:"claims_json"`
	ClaimsUTF8Hex          string `json:"claims_utf8_hex"`
	ClaimsB64URL           string `json:"claims_b64url"`
	SigningPreimageHex     string `json:"signing_preimage_hex"`
	SigningDigestHex       string `json:"signing_digest_hex"`
	KMSSignatureDERHex     string `json:"kms_signature_der_hex"`
	KMSSignatureDERB64     string `json:"kms_signature_der_b64"`
	RawLowSSignatureHex    string `json:"raw_low_s_signature_hex"`
	SignatureB64URL        string `json:"signature_b64url"`
	Token                  string `json:"token"`
	LRTBodyTemplate        string `json:"lrt_body_template"`
	TicketMarker           string `json:"ticket_marker"`
	NHPPacketOverheadBytes int    `json:"nhp_packet_overhead_bytes"`
	LRTBodyBytes           int    `json:"lrt_body_bytes"`
	CompleteNHPPacketBytes int    `json:"complete_nhp_packet_bytes"`
}

AssignmentTicketGolden is the single complete positive cryptographic vector.

type AssignmentTicketJWK

type AssignmentTicketJWK struct {
	Kty string `json:"kty"`
	Crv string `json:"crv"`
	X   string `json:"x"`
	Y   string `json:"y"`
}

AssignmentTicketJWK is the public half of the synthetic P-256 key.

type AssignmentTicketRepeatDerivation

type AssignmentTicketRepeatDerivation struct {
	Target    string `json:"target"`
	ASCIIChar string `json:"ascii_char"`
	Count     int    `json:"count"`
}

AssignmentTicketRepeatDerivation specifies an exact large ASCII input without inflating all three published package copies.

type AssignmentTicketSyntheticKey

type AssignmentTicketSyntheticKey struct {
	KID                 string              `json:"kid"`
	Curve               string              `json:"curve"`
	PrivateScalarHex    string              `json:"private_scalar_hex"`
	PublicKeySPKIDERB64 string              `json:"public_key_spki_der_b64url"`
	JWK                 AssignmentTicketJWK `json:"jwk"`
}

AssignmentTicketSyntheticKey is public test-only signing material. It must never be used outside conformance tests.

type AssignmentTicketTrustReject

type AssignmentTicketTrustReject struct {
	Name                string `json:"name"`
	RejectClass         string `json:"reject_class"`
	Reason              string `json:"reason"`
	PublicKeySPKIDERB64 string `json:"public_key_spki_der_b64url"`
}

AssignmentTicketTrustReject freezes invalid verifier-key inputs.

type AssignmentTicketVerifyReject

type AssignmentTicketVerifyReject struct {
	Name                  string                            `json:"name"`
	RejectClass           string                            `json:"reject_class"`
	Reason                string                            `json:"reason"`
	ClaimsB64URL          string                            `json:"claims_b64url,omitempty"`
	SignatureB64URL       string                            `json:"signature_b64url,omitempty"`
	Token                 string                            `json:"token,omitempty"`
	ExpectedEnvironmentID string                            `json:"expected_environment_id"`
	TrustedKID            string                            `json:"trusted_kid"`
	VerifyAtUnix          int64                             `json:"verify_at_unix"`
	Derivation            *AssignmentTicketRepeatDerivation `json:"derivation,omitempty"`
}

AssignmentTicketVerifyReject drives the complete verifier. Empty source fields inherit the golden claims/signature; explicit fields are used verbatim.

func (AssignmentTicketVerifyReject) ResolveToken

func (c AssignmentTicketVerifyReject) ResolveToken(g AssignmentTicketGolden) (string, error)

ResolveToken returns the exact verifier input for a reject vector.

type ConformanceClass

type ConformanceClass struct {
	EntryPoint string              `json:"entry_point"`
	Input      string              `json:"input"`
	Comment    string              `json:"comment"`
	Vectors    []ConformanceVector `json:"vectors"`
}

ConformanceClass is one named class: an entry-point label, the input field name, an optional human comment, and the ordered vectors.

type ConformanceFile

type ConformanceFile struct {
	Artifact       string                      `json:"artifact"`
	SchemaVersion  int                         `json:"schema_version"`
	Description    string                      `json:"description"`
	SourceOfTruth  string                      `json:"source_of_truth"`
	Notes          []string                    `json:"notes"`
	SignatureClass ConformanceSignatureClass   `json:"signature_class"`
	Classes        map[string]ConformanceClass `json:"classes"`
}

ConformanceFile is the top-level conformance artifact document.

func ConformanceVectors

func ConformanceVectors() (*ConformanceFile, error)

ConformanceVectors strictly parses the embedded qURL v2 conformance artifact into a typed document, returning an error if it is malformed or is not the expected artifact.

func ParseConformanceFile

func ParseConformanceFile(data []byte) (*ConformanceFile, error)

ParseConformanceFile strictly parses the conformance artifact from raw bytes. It returns an error (never an empty/zero document) when the bytes are malformed or are not the qURL v2 conformance artifact, so a consumer test FAILS rather than silently skipping or misreading the contract. DisallowUnknownFields keeps a typo'd or stale schema field from being ignored.

type ConformanceSignatureClass

type ConformanceSignatureClass struct {
	EntryPoint string `json:"entry_point"`
	Composes   string `json:"composes"`
	Comment    string `json:"comment"`
	// TamperDerivation specifies the derived payload-tamper reject. It is optional
	// in the schema's struct but consumers assert it is present and well-formed.
	TamperDerivation *ConformanceTamperDerivation `json:"tamper_derivation,omitempty"`
}

ConformanceSignatureClass records that the signature class is composed from a separate file rather than carrying its own bytes, plus the language-agnostic payload-tamper derivation every consumer synthesizes from the composed file's accept vector (so the tamper negative is portable without a second copy of signature bytes).

type ConformanceTamperDerivation

type ConformanceTamperDerivation struct {
	RejectClass     string `json:"reject_class"`
	Comment         string `json:"comment"`
	DeriveFrom      string `json:"derive_from"`
	ClaimsTransform string `json:"claims_transform"`
}

ConformanceTamperDerivation specifies how a consumer derives the payload-tamper reject from the composed signature file's accept vector. It is a derivation, not stored bytes, so every consumer synthesizes the SAME negative.

• RejectClass: the reject_class label for the derived case ("tamper").
• DeriveFrom: which composed vector to start from ("accept_vector").
• ClaimsTransform: the transform applied to that vector's claims_b64 to make the signature no longer valid over it ("flip_first_base64url_char_A_B": flip the FIRST base64url character between 'A' and 'B'). The signature bytes are reused UNCHANGED, so the case fails only at the curve check.

type ConformanceVector

type ConformanceVector struct {
	Name        string `json:"name"`
	Expect      string `json:"expect"`
	RejectClass string `json:"reject_class"`
	Reason      string `json:"reason"`

	// claims_parse / secret_parse: raw JSON text fed directly to the parser.
	ClaimsJSON string `json:"claims_json"`
	SecretJSON string `json:"secret_json"`

	// strict_base64: the base64url string verbatim.
	ValueB64 string `json:"value_b64"`

	// fragment: a full fragment body.
	Fragment string `json:"fragment"`

	// relay_allowlist: the allowlist entries and the URL to validate.
	Entries []string `json:"entries"`
	URL     string   `json:"url"`

	// server_id: the cell public key (base64url) and its expected routing id.
	CellPublicKeyB64 string `json:"cell_public_key_b64"`
	ServerID         string `json:"server_id"`
}

ConformanceVector is one case. Only the fields relevant to a vector's class are populated; the loader does not interpret them — the consumer routes each class to the matching entry point and reads the fields that class uses.

type ConnectorAuthorityActivateRegistrationRequest

type ConnectorAuthorityActivateRegistrationRequest struct {
	Version                       int    `json:"version"`
	AssignmentTicket              string `json:"assignment_ticket"`
	CredentialKeyID               string `json:"credential_key_id"`
	RegistrationCredential        string `json:"registration_credential"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	AgentID                       string `json:"agent_id"`
	Hostname                      string `json:"hostname"`
	AgentVersion                  string `json:"agent_version"`
}

type ConnectorAuthorityAssignmentResult

type ConnectorAuthorityAssignmentResult struct {
	CellID               string                           `json:"cell_id"`
	AssignmentGeneration int64                            `json:"assignment_generation"`
	EndpointRevision     int64                            `json:"endpoint_revision"`
	LeaseExpiresAt       string                           `json:"lease_expires_at"`
	NHPUDPEndpoint       ConnectorAuthorityNHPUDPEndpoint `json:"nhp_udp_endpoint"`
}

ConnectorAuthorityAssignmentResult is the only placement result shape. The initial operation additionally wraps registration metadata and a ticket; refresh does not.

type ConnectorAuthorityCompleteRegistrationRequest

type ConnectorAuthorityCompleteRegistrationRequest struct {
	Version                       int    `json:"version"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	AgentID                       string `json:"agent_id"`
	DeviceAPIKey                  string `json:"device_api_key"`
}

type ConnectorAuthorityCompleteRegistrationResult

type ConnectorAuthorityCompleteRegistrationResult struct {
	DeviceAPIKeyID string `json:"device_api_key_id"`
}

type ConnectorAuthorityIssueAssignmentRequest

type ConnectorAuthorityIssueAssignmentRequest struct {
	Version                       int    `json:"version"`
	HubRequestID                  string `json:"hub_request_id"`
	AgentID                       string `json:"agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	Credential                    string `json:"credential"`
}

Private request shapes. Environment, cell, owner, assignment generation, and operation selector are absent by construction.

type ConnectorAuthorityIssueAssignmentResult

type ConnectorAuthorityIssueAssignmentResult struct {
	AgentID                   string                               `json:"agent_id"`
	Registration              ConnectorAuthorityRegistrationResult `json:"registration"`
	Assignment                ConnectorAuthorityAssignmentResult   `json:"assignment"`
	AssignmentTicket          string                               `json:"assignment_ticket"`
	AssignmentTicketExpiresAt string                               `json:"assignment_ticket_expires_at"`
}

type ConnectorAuthorityIssueRegistrationOTPRequest

type ConnectorAuthorityIssueRegistrationOTPRequest struct {
	Version                       int    `json:"version"`
	AssignmentTicket              string `json:"assignment_ticket"`
	CredentialKeyID               string `json:"credential_key_id"`
	CredentialSecret              string `json:"credential_secret"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	AgentID                       string `json:"agent_id"`
	ObservedSourceAddress         string `json:"observed_source_address"`
}

type ConnectorAuthorityLambdaBodyCase

type ConnectorAuthorityLambdaBodyCase struct {
	Name     string `json:"name"`
	BodyJSON string `json:"body_json"`
}

ConnectorAuthorityLambdaBodyCase preserves exact raw JSON bytes for a valid request or response.

type ConnectorAuthorityLambdaErrorCase

type ConnectorAuthorityLambdaErrorCase struct {
	Code     string `json:"code"`
	BodyJSON string `json:"body_json"`
}

ConnectorAuthorityLambdaErrorCase freezes one operation-specific semantic error code and its exact private response body.

type ConnectorAuthorityLambdaFile

type ConnectorAuthorityLambdaFile struct {
	Artifact      string                                       `json:"artifact"`
	SchemaVersion int                                          `json:"schema_version"`
	Description   string                                       `json:"description"`
	Protocol      ConnectorAuthorityLambdaProtocol             `json:"protocol"`
	Fixtures      ConnectorAuthorityLambdaFixtures             `json:"fixtures"`
	Operations    map[string]ConnectorAuthorityLambdaOperation `json:"operations"`
}

ConnectorAuthorityLambdaFile freezes the private synchronous invocation bodies shared by authority handlers and NHP workers. It does not define a public API or a generic operation-dispatch envelope.

func ConnectorAuthorityLambda

func ConnectorAuthorityLambda() (*ConnectorAuthorityLambdaFile, error)

ConnectorAuthorityLambda strictly parses the embedded private invocation artifact shared by NHP workers and Connector Authority handlers.

func ParseConnectorAuthorityLambdaFile

func ParseConnectorAuthorityLambdaFile(data []byte) (*ConnectorAuthorityLambdaFile, error)

ParseConnectorAuthorityLambdaFile strictly parses and independently validates the embedded private invocation artifact.

type ConnectorAuthorityLambdaFixtures

type ConnectorAuthorityLambdaFixtures struct {
	AgentID                       string `json:"agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	HubRequestID                  string `json:"hub_request_id"`
	Credential                    string `json:"credential"`
	AssignmentTicket              string `json:"assignment_ticket"`
	CredentialKeyID               string `json:"credential_key_id"`
	RegistrationCredential        string `json:"registration_credential"`
	ObservedSourceAddress         string `json:"observed_source_address"`
	Hostname                      string `json:"hostname"`
	AgentVersion                  string `json:"agent_version"`
	DeviceAPIKey                  string `json:"device_api_key"`
	DeviceAPIKeyID                string `json:"device_api_key_id"`
	RegistrationKeyKind           string `json:"registration_key_kind"`
	CellID                        string `json:"cell_id"`
	AssignmentGeneration          int64  `json:"assignment_generation"`
	EndpointRevision              int64  `json:"endpoint_revision"`
	LeaseExpiresAt                string `json:"lease_expires_at"`
	NHPHost                       string `json:"nhp_host"`
	NHPPort                       int    `json:"nhp_port"`
	ServerPublicKeyB64            string `json:"server_public_key_b64"`
	AssignmentTicketExpiresAt     string `json:"assignment_ticket_expires_at"`
}

ConnectorAuthorityLambdaFixtures are synthetic, non-production values used by every golden and mapping case.

type ConnectorAuthorityLambdaOperation

type ConnectorAuthorityLambdaOperation struct {
	RequestGolden           ConnectorAuthorityLambdaBodyCase     `json:"request_golden"`
	SuccessGolden           ConnectorAuthorityLambdaBodyCase     `json:"success_golden"`
	SemanticErrors          []ConnectorAuthorityLambdaErrorCase  `json:"semantic_errors"`
	RequestRejects          []ConnectorAuthorityLambdaRejectCase `json:"request_rejects"`
	ResponseProducerRejects []ConnectorAuthorityLambdaRejectCase `json:"response_producer_rejects"`
	PublicMappingCases      []ConnectorAuthorityPublicMapping    `json:"public_mapping_cases"`
}

ConnectorAuthorityLambdaOperation is one separately permissioned function's complete request, response, reject, and public-mapping contract.

type ConnectorAuthorityLambdaProtocol

type ConnectorAuthorityLambdaProtocol struct {
	RequestVersion                int    `json:"request_version"`
	MaxRequestBytes               int    `json:"max_request_bytes"`
	MaxResponseBytes              int    `json:"max_response_bytes"`
	MaxAssignmentTicketASCIIBytes int    `json:"max_assignment_ticket_ascii_bytes"`
	TimestampFormat               string `json:"timestamp_format"`
	HubRequestIDFormat            string `json:"hub_request_id_format"`
	ResponseRule                  string `json:"response_rule"`
}

ConnectorAuthorityLambdaProtocol is the closed framing profile applied before operation-specific decoding.

type ConnectorAuthorityLambdaRejectCase

type ConnectorAuthorityLambdaRejectCase struct {
	Name             string `json:"name"`
	BodyJSON         string `json:"body_json,omitempty"`
	BodyFillByteHex  string `json:"body_fill_byte_hex,omitempty"`
	DerivedBodyBytes int    `json:"derived_body_bytes,omitempty"`
	Outcome          string `json:"outcome"`
	RejectClass      string `json:"reject_class"`
}

ConnectorAuthorityLambdaRejectCase preserves raw malformed input. Oversize cases derive an exact byte sequence from the fill byte and length instead of committing thousands of redundant characters.

type ConnectorAuthorityNHPUDPEndpoint

type ConnectorAuthorityNHPUDPEndpoint struct {
	Host               string `json:"host"`
	Port               int    `json:"port"`
	ServerPublicKeyB64 string `json:"server_public_key_b64"`
}

type ConnectorAuthorityPublicMapping

type ConnectorAuthorityPublicMapping struct {
	Name                    string `json:"name"`
	MappingSource           string `json:"mapping_source"`
	PrivateOutcome          string `json:"private_outcome,omitempty"`
	PrivateResponseBodyJSON string `json:"private_response_body_json,omitempty"`
	NHPAction               string `json:"nhp_action"`
	NHPBodyJSON             string `json:"nhp_body_json,omitempty"`
	RecoveryAction          string `json:"recovery_action"`
}

ConnectorAuthorityPublicMapping freezes how an authority outcome, or an NHP pre-invoke gate, becomes a public application reply or deliberate absence of one. PrivateResponseBodyJSON is empty only for pre-invoke cases. NHPBodyJSON is empty when NHPAction is no_application_reply or drop_no_reply.

type ConnectorAuthorityRefreshAssignmentRequest

type ConnectorAuthorityRefreshAssignmentRequest struct {
	Version                       int    `json:"version"`
	HubRequestID                  string `json:"hub_request_id"`
	AgentID                       string `json:"agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
}

type ConnectorAuthorityRefreshAssignmentResult

type ConnectorAuthorityRefreshAssignmentResult struct {
	AgentID    string                             `json:"agent_id"`
	Assignment ConnectorAuthorityAssignmentResult `json:"assignment"`
}

type ConnectorAuthorityRegistrationResult

type ConnectorAuthorityRegistrationResult struct {
	KeyID   string `json:"key_id"`
	KeyKind string `json:"key_kind"`
}

type ConnectorHubAssignmentSuccessSize

type ConnectorHubAssignmentSuccessSize struct {
	Name                               string `json:"name"`
	Phase                              string `json:"phase"`
	Basis                              string `json:"basis"`
	RequestPacketBytes                 int    `json:"request_packet_bytes"`
	ResultBodyBytes                    int    `json:"result_body_bytes"`
	ResultPacketBytes                  int    `json:"result_packet_bytes"`
	AmplificationNumeratorBytes        int    `json:"amplification_numerator_bytes"`
	AmplificationDenominatorBytes      int    `json:"amplification_denominator_bytes"`
	LegacyAssignmentFixturePacketBytes int    `json:"legacy_assignment_fixture_packet_bytes,omitempty"`
}

ConnectorHubAssignmentSuccessSize cross-links the return-routability request to real assignment-success envelopes. Ratios are exact byte fractions rather than rounded decimal claims.

type ConnectorHubLSTChallengeBodyCase

type ConnectorHubLSTChallengeBodyCase struct {
	Name           string `json:"name"`
	Stage          string `json:"stage"`
	Mutation       string `json:"mutation"`
	HeaderFlagsHex string `json:"header_flags_hex"`
	BodyJSON       string `json:"body_json,omitempty"`
	Outcome        string `json:"outcome"`
	ClientAction   string `json:"client_action"`
}

ConnectorHubLSTChallengeBodyCase drives the SDK's strict authenticated COK parser and its one-proof-flight state machine.

type ConnectorHubLSTCookieContract

type ConnectorHubLSTCookieContract struct {
	CookieAlgorithm               string   `json:"cookie_algorithm"`
	CookieDomainASCII             string   `json:"cookie_domain_ascii"`
	CookieDomainSuffixHex         string   `json:"cookie_domain_suffix_hex"`
	CookieInputFraming            string   `json:"cookie_input_framing"`
	SigningKeyBytes               int      `json:"signing_key_bytes"`
	CookieBytes                   int      `json:"cookie_bytes"`
	CookieEncoding                string   `json:"cookie_encoding"`
	SourceIPEncoding              string   `json:"source_ip_encoding"`
	SourcePortBound               bool     `json:"source_port_bound"`
	AuthenticatedPeerBytes        int      `json:"authenticated_peer_bytes"`
	WindowSeconds                 int      `json:"window_seconds"`
	AcceptedWindowOffsets         []int    `json:"accepted_window_offsets"`
	FutureWindowAccepted          bool     `json:"future_window_accepted"`
	SigningKeySlots               int      `json:"signing_key_slots"`
	ActiveSigningKeyRequired      bool     `json:"active_signing_key_required"`
	PreviousSigningKeyOptional    bool     `json:"previous_signing_key_optional"`
	MintKeySlot                   string   `json:"mint_key_slot"`
	VerifyKeyWindowOrder          []string `json:"verify_key_window_order"`
	CookieKeyIDOnWire             bool     `json:"cookie_key_id_on_wire"`
	RequestHeaderName             string   `json:"request_header_name"`
	RequestHeaderType             int      `json:"request_header_type"`
	ChallengeHeaderName           string   `json:"challenge_header_name"`
	ChallengeHeaderType           int      `json:"challenge_header_type"`
	ChallengeCompressed           bool     `json:"challenge_compressed"`
	ChallengeHeaderFlagsHex       string   `json:"challenge_header_flags_hex"`
	ChallengeSizeRule             string   `json:"challenge_size_rule"`
	SuccessHeaderName             string   `json:"success_header_name"`
	SuccessHeaderType             int      `json:"success_header_type"`
	UnprovenHeaderFlagsHex        string   `json:"unproven_header_flags_hex"`
	ProofFlagName                 string   `json:"proof_flag_name"`
	ProofFlagHex                  string   `json:"proof_flag_hex"`
	ProofFlagExclusive            bool     `json:"proof_flag_exclusive"`
	ProofHeaderDigest             string   `json:"proof_header_digest"`
	ProofCookieDigestInput        string   `json:"proof_cookie_digest_input"`
	ProofHeaderFreshnessRule      string   `json:"proof_header_freshness_rule"`
	ProofBodyRule                 string   `json:"proof_body_rule"`
	ProofRequestNonceRule         string   `json:"proof_request_nonce_rule"`
	ProofResendLimit              int      `json:"proof_resend_limit"`
	SecondChallengeAction         string   `json:"second_challenge_action"`
	AuthorityBeforeProofAllowed   bool     `json:"authority_before_proof_allowed"`
	HTTPFallbackAllowed           bool     `json:"http_fallback_allowed"`
	RequestPaddingFallbackAllowed bool     `json:"request_padding_fallback_allowed"`
	AdditiveApplicationProfiles   []string `json:"additive_application_profiles"`
	CurveHeaderBytes              int      `json:"curve_header_bytes"`
	BodyAEADTagBytes              int      `json:"body_aead_tag_bytes"`
	EmptyBodyPacketBytes          int      `json:"empty_body_packet_bytes"`
	NonemptyPacketOverheadBytes   int      `json:"nonempty_packet_overhead_bytes"`
	MaxPlaintextBodyBytes         int      `json:"max_plaintext_body_bytes"`
	MaxPacketBytes                int      `json:"max_packet_bytes"`
	ChallengeMaxTransactionID     string   `json:"challenge_max_transaction_id"`
	ChallengeMaxBodyJSON          string   `json:"challenge_max_body_json"`
	ChallengeMaxBodyBytes         int      `json:"challenge_max_body_bytes"`
	ChallengeMaxPacketBytes       int      `json:"challenge_max_packet_bytes"`
}

ConnectorHubLSTCookieContract is the closed protocol and size profile.

type ConnectorHubLSTCookieFile

type ConnectorHubLSTCookieFile struct {
	Artifact       string                              `json:"artifact"`
	SchemaVersion  int                                 `json:"schema_version"`
	Description    string                              `json:"description"`
	SourceOfTruth  string                              `json:"source_of_truth"`
	Contract       ConnectorHubLSTCookieContract       `json:"contract"`
	CookieKATs     []ConnectorHubLSTCookieKAT          `json:"cookie_kats"`
	ProofDigestKAT ConnectorHubLSTProofDigestKAT       `json:"proof_digest_kat"`
	Flows          []ConnectorHubLSTCookieFlow         `json:"flows"`
	SizeCases      []ConnectorHubLSTCookieSizeCase     `json:"size_cases"`
	SuccessSizes   []ConnectorHubAssignmentSuccessSize `json:"assignment_success_sizes"`
	KeyCases       []ConnectorHubLSTCookieKeyCase      `json:"key_cases"`
	RejectCases    []ConnectorHubLSTCookieRejectCase   `json:"reject_cases"`
	ChallengeCases []ConnectorHubLSTChallengeBodyCase  `json:"challenge_cases"`
}

ConnectorHubLSTCookieFile freezes the strict challenge/proof contract that must complete before a public Hub invokes Connector Authority.

func ConnectorHubLSTCookie

func ConnectorHubLSTCookie() (*ConnectorHubLSTCookieFile, error)

ConnectorHubLSTCookie strictly parses the Hub assignment return-routability challenge artifact.

func ParseConnectorHubLSTCookieFile

func ParseConnectorHubLSTCookieFile(data []byte) (*ConnectorHubLSTCookieFile, error)

ParseConnectorHubLSTCookieFile strictly parses and independently validates every derivation, size bound, assignment linkage, and closed disposition.

type ConnectorHubLSTCookieFlow

type ConnectorHubLSTCookieFlow struct {
	Phase                                    string `json:"phase"`
	UnprovenCounter                          string `json:"unproven_counter"`
	ProofCounter                             string `json:"proof_counter"`
	UnprovenBodyJSON                         string `json:"unproven_body_json"`
	ProofBodyJSON                            string `json:"proof_body_json"`
	RequestNonce                             string `json:"request_nonce"`
	UnprovenHeaderFlagsHex                   string `json:"unproven_header_flags_hex"`
	ProofHeaderFlagsHex                      string `json:"proof_header_flags_hex"`
	UnprovenRequestPacketBytes               int    `json:"unproven_request_packet_bytes"`
	ChallengeBodyJSON                        string `json:"challenge_body_json"`
	ChallengeBodyBytes                       int    `json:"challenge_body_bytes"`
	ChallengePacketBytes                     int    `json:"challenge_packet_bytes"`
	ProofRequestPacketBytes                  int    `json:"proof_request_packet_bytes"`
	LegacyAssignmentFixtureResultPacketBytes int    `json:"legacy_assignment_fixture_result_packet_bytes"`
	AuthorityInvocationsBeforeProof          int    `json:"authority_invocations_before_proof"`
	AuthorityInvocationsAfterProof           int    `json:"authority_invocations_after_proof"`
}

ConnectorHubLSTCookieFlow freezes one initial or refresh LST/COK/LST/LRT sequence. The proof body is duplicated intentionally so a consumer can compare the exact authenticated bytes, not reconstructed JSON.

type ConnectorHubLSTCookieKAT

type ConnectorHubLSTCookieKAT struct {
	Name                          string `json:"name"`
	SigningKeyHex                 string `json:"signing_key_hex"`
	SourceIP                      string `json:"source_ip"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	WindowIndex                   string `json:"window_index"`
	PreimageHex                   string `json:"preimage_hex"`
	CookieHex                     string `json:"cookie_hex"`
	CookieB64                     string `json:"cookie_b64"`
	EqualTo                       string `json:"equal_to,omitempty"`
}

ConnectorHubLSTCookieKAT is one exact HMAC derivation. The signing key is synthetic and exists only to make the contract independently executable.

type ConnectorHubLSTCookieKeyCase

type ConnectorHubLSTCookieKeyCase struct {
	Name               string `json:"name"`
	ActiveKeyPresent   bool   `json:"active_key_present"`
	PreviousKeyPresent bool   `json:"previous_key_present"`
	CookieKeySlot      string `json:"cookie_key_slot"`
	WindowOffset       int    `json:"window_offset"`
	Outcome            string `json:"outcome"`
	ServerAction       string `json:"server_action"`
}

ConnectorHubLSTCookieKeyCase freezes rolling-key overlap without exposing a key identifier on the public wire.

type ConnectorHubLSTCookieRejectCase

type ConnectorHubLSTCookieRejectCase struct {
	Name                 string `json:"name"`
	Stage                string `json:"stage"`
	Mutation             string `json:"mutation"`
	Outcome              string `json:"outcome"`
	ServerAction         string `json:"server_action"`
	AuthorityInvocations int    `json:"authority_invocations"`
}

ConnectorHubLSTCookieRejectCase is a server-side fail-closed mutation. All cases are deliberately silent and stop before Connector Authority.

type ConnectorHubLSTCookieSizeCase

type ConnectorHubLSTCookieSizeCase struct {
	Name                      string `json:"name"`
	CryptoValidNHPFraming     bool   `json:"crypto_valid_nhp_framing"`
	ApplicationBodyClass      string `json:"application_body_class"`
	ChallengeTransactionID    string `json:"challenge_transaction_id"`
	RequestPlaintextBodyBytes int    `json:"request_plaintext_body_bytes"`
	ReceivedLSTPacketBytes    int    `json:"received_lst_packet_bytes"`
	CandidateCOKPacketBytes   int    `json:"candidate_cok_packet_bytes"`
	SizeGateAction            string `json:"size_gate_action"`
}

ConnectorHubLSTCookieSizeCase drives the pre-challenge amplification gate with cryptographically valid NHP framing. The application body remains opaque until cookie proof succeeds; passing this gate only permits COK.

type ConnectorHubLSTProofDigestKAT

type ConnectorHubLSTProofDigestKAT struct {
	Purpose                     string `json:"purpose"`
	InitialHashHex              string `json:"initial_hash_hex"`
	HubServerStaticPublicKeyHex string `json:"hub_server_static_public_key_hex"`
	HeaderPrefixHex             string `json:"header_prefix_hex"`
	HeaderType                  int    `json:"header_type"`
	HeaderFlagsHex              string `json:"header_flags_hex"`
	Counter                     string `json:"counter"`
	TimestampNanos              string `json:"timestamp_nanos"`
	EphemeralPublicKeyHex       string `json:"ephemeral_public_key_hex"`
	RawCookieHex                string `json:"raw_cookie_hex"`
	ExpectedDigestHex           string `json:"expected_digest_hex"`
}

ConnectorHubLSTProofDigestKAT freezes an executable digest over a fresh deterministic Curve header prefix and the opaque Hub cookie. It is a digest primitive, not a complete encrypted packet; flow fixtures separately pin the byte-identical body and request nonce. Cryptographic consumers recompute ExpectedDigestHex with BLAKE2s-256.

type ConnectorHubRequestIDCase

type ConnectorHubRequestIDCase struct {
	Name                          string `json:"name"`
	Environment                   string `json:"environment"`
	Operation                     string `json:"operation"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	RequestNonce                  string `json:"request_nonce"`
	PreimageHex                   string `json:"preimage_hex"`
	HubRequestID                  string `json:"hub_request_id"`
	MutatedField                  string `json:"mutated_field,omitempty"`
	NotEqualTo                    string `json:"not_equal_to,omitempty"`
}

ConnectorHubRequestIDCase is one exact byte KAT. Substitution cases change exactly the named input from NotEqualTo and must derive a distinct ID.

type ConnectorHubRequestIDContract

type ConnectorHubRequestIDContract struct {
	Digest                   string   `json:"digest"`
	OutputEncoding           string   `json:"output_encoding"`
	DomainASCII              string   `json:"domain_ascii"`
	DomainSuffixHex          string   `json:"domain_suffix_hex"`
	FrameEncoding            string   `json:"frame_encoding"`
	EnvironmentTagHex        string   `json:"environment_tag_hex"`
	OperationTagHex          string   `json:"operation_tag_hex"`
	PeerTagHex               string   `json:"peer_tag_hex"`
	NonceTagHex              string   `json:"nonce_tag_hex"`
	FieldOrder               []string `json:"field_order"`
	EnvironmentPattern       string   `json:"environment_pattern"`
	EnvironmentMinBytes      int      `json:"environment_min_bytes"`
	EnvironmentMaxBytes      int      `json:"environment_max_bytes"`
	EnvironmentNormalization string   `json:"environment_normalization"`
	Operations               []string `json:"operations"`
	PeerDecodedBytes         int      `json:"peer_decoded_bytes"`
	PeerFixtureEncoding      string   `json:"peer_fixture_encoding"`
	PeerHashEncoding         string   `json:"peer_hash_encoding"`
	NonceDecodedBytes        int      `json:"nonce_decoded_bytes"`
	NonceFixtureEncoding     string   `json:"nonce_fixture_encoding"`
	NonceHashEncoding        string   `json:"nonce_hash_encoding"`
	ExcludedInputs           []string `json:"excluded_inputs"`
}

ConnectorHubRequestIDContract is the complete consumer-neutral byte profile.

type ConnectorHubRequestIDFile

type ConnectorHubRequestIDFile struct {
	Artifact      string                        `json:"artifact"`
	SchemaVersion int                           `json:"schema_version"`
	Description   string                        `json:"description"`
	Contract      ConnectorHubRequestIDContract `json:"contract"`
	Cases         []ConnectorHubRequestIDCase   `json:"cases"`
}

ConnectorHubRequestIDFile freezes the only request-ID preimage used by the public-UDP Connector Hub. It is separate from both the public LST and private Lambda schemas: the SDK supplies only request_nonce, and the authority treats the resulting hub_request_id as opaque.

func ConnectorHubRequestID

func ConnectorHubRequestID() (*ConnectorHubRequestIDFile, error)

ConnectorHubRequestID strictly parses the embedded private Hub replay-key derivation artifact.

func ParseConnectorHubRequestIDFile

func ParseConnectorHubRequestIDFile(data []byte) (*ConnectorHubRequestIDFile, error)

ParseConnectorHubRequestIDFile strictly parses and independently recomputes every embedded preimage and substitution result.

type ECPublicJWK

type ECPublicJWK struct {
	Kty string `json:"kty"`
	Crv string `json:"crv"`
	X   string `json:"x"`
	Y   string `json:"y"`
}

ECPublicJWK is a minimal P-256 public-key JWK. x and y are fixed-width 32-byte base64url (leading zeros preserved) so a strict importer accepts them.

type IssuerKeyMaterial

type IssuerKeyMaterial struct {
	KID string `json:"kid"`
	// SPKIDERB64 is the DER SPKI public key, base64url.
	SPKIDERB64 string `json:"spki_der_b64"`
	// JWK is the same public key as a P-256 JWK (crv/x/y), for WebCrypto "jwk".
	JWK ECPublicJWK `json:"jwk"`
}

IssuerKeyMaterial is the issuer public key in both import forms.

type RelayKnockCase

type RelayKnockCase struct {
	// ServerStaticPrivHex / ServerStaticPubHex are the server static X25519 key.
	// The knock case carries both; the ack case carries only the public half.
	ServerStaticPrivHex string `json:"server_static_priv_hex,omitempty"`
	ServerStaticPubHex  string `json:"server_static_pub_hex"`
	// DeviceStaticPrivHex / DeviceStaticPubHex are the initiator (device) static
	// X25519 key, used by the knock case.
	DeviceStaticPrivHex string `json:"device_static_priv_hex,omitempty"`
	DeviceStaticPubHex  string `json:"device_static_pub_hex,omitempty"`
	// AgentStaticPrivHex is the agent (responder-side decryptor) static private
	// X25519 key, used by the ack case to open the reply. It is the same key as the
	// knock case's device_static_priv_hex.
	AgentStaticPrivHex string `json:"agent_static_priv_hex,omitempty"`
	// EphemeralPrivHex is the fixed initiator ephemeral private key the knock case
	// seals under (so the knock packet is deterministic).
	EphemeralPrivHex string `json:"ephemeral_priv_hex,omitempty"`
	// TimestampNanos is the handshake timestamp, decimal string (exceeds 2^53).
	TimestampNanos string `json:"timestamp_nanos"`
	// Counter is the knock counter as a decimal string.
	Counter string `json:"counter,omitempty"`
	// CounterHex is the ack counter as a hex string (no 0x prefix, no padding).
	CounterHex string `json:"counter_hex,omitempty"`
	// PreambleHex is the 32-bit knock preamble as a hex string.
	PreambleHex string `json:"preamble_hex,omitempty"`
	// BodyHex is the plaintext body the case carries, hex-encoded.
	BodyHex string `json:"body_hex"`
	// PacketHex is the full wire packet, hex-encoded: for knock, the value a
	// conformant BuildKnock must reproduce; for ack, the frozen value a conformant
	// DecryptReply must open.
	PacketHex string `json:"packet_hex"`
}

RelayKnockCase is one golden packet (knock or ack). Every value is the exact hex (or, for the numeric fields, the stringified value) the case uses; only the fields relevant to a given case are populated. All fields are strings — including timestamp_nanos, which exceeds 2^53 and so is carried as a decimal string rather than a JSON number.

type RelayKnockFile

type RelayKnockFile struct {
	Artifact      string         `json:"artifact"`
	SchemaVersion int            `json:"schema_version"`
	Description   string         `json:"description"`
	SourceOfTruth string         `json:"source_of_truth"`
	Notes         []string       `json:"notes"`
	Knock         RelayKnockCase `json:"knock"`
	Ack           RelayKnockCase `json:"ack"`
}

RelayKnockFile is the top-level relay/NHP-handshake golden artifact: a deterministic knock packet a conformant initiator must reproduce byte-for-byte, plus a frozen ack reply (sealed at origin with a random server ephemeral, so it is NOT reproducible by a client — only decryptable). Both cases decode into the same RelayKnockCase, which carries the UNION of the fields either case uses.

func ParseRelayKnockFile

func ParseRelayKnockFile(data []byte) (*RelayKnockFile, error)

ParseRelayKnockFile strictly parses the relay-knock golden artifact from raw bytes. It returns an error (never an empty/zero document) when the bytes are malformed or are not the relay-knock artifact, so a consumer test FAILS rather than silently skipping or misreading the contract. DisallowUnknownFields keeps a typo'd or stale schema field from being ignored.

func RelayKnockGolden

func RelayKnockGolden() (*RelayKnockFile, error)

RelayKnockGolden strictly parses the embedded relay/NHP-handshake golden artifact into a typed document, returning an error if it is malformed or is not the expected artifact.

type SignatureVector

type SignatureVector struct {
	Name string `json:"name"`
	// Expect is "accept" or "reject".
	Expect string `json:"expect"`
	// RejectClass is the machine-readable rejection class. It is present on reject
	// vectors and absent on accept vectors.
	RejectClass string `json:"reject_class,omitempty"`
	// Reason documents why in human-readable prose.
	Reason string `json:"reason"`
	// ClaimsB64 is the exact base64url claims string (primary verify input).
	ClaimsB64 string `json:"claims_b64"`
	// SigB64Raw is the signature as base64url. For accept/high-S it is 64-byte
	// raw r||s; for the wrong-length case it is the DER form (the realistic
	// "passed signer output straight through" mistake).
	SigB64Raw string `json:"sig_b64"`
	// SigEncoding documents the signature's byte form ("raw_r_s" or "der").
	SigEncoding string `json:"sig_encoding"`
	// SigningInputB64 is a cross-check value a verifier reconstructs itself as
	// prefix + 0x00 + claims_b64; it is not the data fed to the verifier.
	SigningInputB64 string `json:"signing_input_b64"`
}

SignatureVector is one accept-or-reject case.

type VectorFile

type VectorFile struct {
	// Description documents the contract for a human reader of the JSON.
	Description string `json:"description"`
	// Algorithm pins the signing profile (informational; verifiers do not
	// negotiate).
	Algorithm string `json:"algorithm"`
	// DomainSeparationPrefix is the ASCII prefix; the 0x00 separator follows it.
	DomainSeparationPrefix string `json:"domain_separation_prefix"`
	// Issuer is the shared issuer key all vectors are signed/verified under.
	Issuer IssuerKeyMaterial `json:"issuer"`
	// Vectors is the ordered list of accept/reject cases.
	Vectors []SignatureVector `json:"vectors"`
}

VectorFile is the top-level committed issuer-signature fixture document. The signature class of the conformance artifact composes this file by reference.

func ParseVectorFile

func ParseVectorFile(data []byte) (*VectorFile, error)

ParseVectorFile strictly parses an issuer-signature vector file from raw bytes. It returns an error (never an empty/zero document) if the bytes are malformed, so a consumer test FAILS rather than silently skipping the contract.

func SignatureVectors

func SignatureVectors() (*VectorFile, error)

SignatureVectors strictly parses the embedded issuer-signature vector file into a typed document, returning an error if it is malformed.