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, assignment tickets, Hub LST return-routability cookies, Connector resource discovery, CRID v1 resource identifiers, qURL Connector target paths, and private upload application signatures decoupled by layer.

Everything here is a contract a third-party SDK implements. Platform-internal contracts between the NHP runtime, the Connector Hub, and the Connector Authority live in a private conformance module and are not published here.

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: share-safe qv2t1 outer transport, claims/secret parse, strict base64url, canonical 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 exact-session EXT/ACK retirement, strict receipt/denial 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_resource_lst_v1_vectors.json	registered-agent connector_resource v1 NHP_LST/NHP_LRT application bodies, continuity/replay rules, strict errors, and conservative unfragmented size fixtures
vectors/README_connector_resource_lst_v1_vectors.md	public request/result schema, identity binding, the shared request_nonce gate, retry grammar, size boundary, and consumer algorithm
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/crid_v1_vectors.json	CRID v1 derivation goldens from DER public keys, the local validation gate, the version-byte registry, and delivered-key match binding
vectors/README_crid_v1_vectors.md	CRID v1 derivation, version registry, closed reject vocabulary, forwarding rule, and key-match/lockstep rules
vectors/target_path_v1_vectors.json	shared canonical qURL Connector target-path request grammar and exact wire values
vectors/README_target_path_v1_vectors.md	target-path security boundary, reject classes, consumer algorithm, and SDK lockstep rule
vectors/private_upload_v1_vectors.json	private upload and refresh application-signing contract with byte-exact goldens and rejects
vectors/README_private_upload_v1_vectors.md	protected-authority binding, framing, canonical signatures, 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
rr, err := conformance.ConnectorResourceLSTV1()      // strict-parsed Connector resource LST/LRT artifact
hc, err := conformance.ConnectorHubLSTCookie()       // strict-parsed Hub LST return-routability contract
cd, err := conformance.CRIDV1()                       // strict-parsed CRID v1 derivation/validation vectors
tp, err := conformance.TargetPathV1()                 // strict-parsed Connector target-path vectors
pu, err := conformance.PrivateUploadV1()              // strict-parsed private upload/refresh signature vectors
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. For target-path validation, consume target_path_v1_vectors.json through the real SDK option gate; do not copy its rules into a private fixture. qURL v2 schema version 2 is a deliberate breaking shape: typed consumers must update their loader for transport_contract and the transport class before adopting this release. Private upload clients consume private_upload_v1_vectors.json through their real request signer and run each mutation against the same preflight used in production.

Scope

This module hosts thirteen artifacts across twelve protocol families. Each artifact has its own artifact id:

• qURL v2 read path (qurl-v2-conformance-vectors, composing the issuer-signature golden bytes) — the share-safe qv2t1 outer transport and the claims/secret/base64/canonical-fragment/relay/server-id classes described above. The outer transport splits every data component at 240 characters and reconstructs the exact unchanged qv2 security fragment before parsing and verification. Legacy qv2 is not an accepted outer URL format.
• 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 private Hub request-ID artifact freezes that derivation outside this module. 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 artifact pins layervai/qurl-go packet-codec revision c4729832bf29b0f356964035864707f6904b1982, which built and opened all nine deterministic packets through its 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. ACK consumers inspect present raw sessId occurrences before generic body decoding: shape, type, range, and duplicate violations are session_id and take precedence over an independent body_parse defect. A well-formed successful ACK that omits sessId is also session_id; an ordinary structural defect that prevents establishing a successful ACK remains body_parse, as do duplicates of other fields. 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, schema version 4) — deterministic full packets for the overload path KNK -> COK -> RKN -> ACK and exact-session EXT -> ACK, pinned to layervai/qurl-go producer revision b962ee4aa82f643d507ddf75adc3c110df8dff9d. This is the signed commit on qurl-go main whose deterministic regeneration gate reproduces the committed artifact. 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. KNK and RKN carry one canonical RunID and positive uint64 runAttempt. The RKN ACK counter echoes RKN and the successful ACK carries the exact immutable cellId, nonzero uint64 sessId, positive sessIssuedAtMillis, runId, and runAttempt receipt. Its raw JSON sessId number can exceed JavaScript's safe-integer range, so JavaScript consumers must parse it losslessly into BigInt rather than pass it through an ordinary JSON.parse number. EXT carries that exact receipt and receives a dedicated counter-echoing ACK that repeats it and adds a canonical closeEventId plus closing or closed state. Denials omit every receipt and close-event field. Resource-scoped and bodyless/global exit shapes are rejected. 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.
• Connector resource discovery LST/LRT v1 (qurl-connector-resource-lst-v1-vectors, connector_resource_lst_v1_vectors.json) — a dedicated post-registration connector_resource v1 exchange over standard NHP_LST/NHP_LRT. The authenticated peer binds exact usrId=devId=agent_id; owner and entitlement remain server-side. One request resolves one connector and returns exact resource, routing, knock, optional CRID, and found_existing values. The optional expected_resource_id is read-only fail-closed continuity: only the same active resource succeeds; absent, revoked, tombstoned, or different state returns terminal 52503 without creating or reclaiming a replacement. Replay preserves the byte-identical first result, while a fresh nonce reauthorizes. The artifact freezes strict 52500-52506 errors and conservative pre-seal size budgets; the NHP reference integration owns the real sealed 1,232-byte proof. No HTTP fallback or hostname-derived placement is allowed. See vectors/README_connector_resource_lst_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.
• CRID v1 (qurl-crid-v1-vectors, crid_v1_vectors.json) — exact derivation of the Cryptographic Resource ID from a DER SubjectPublicKeyInfo (domain-separated SHA-256, big-endian CRC32C, lowercase unpadded RFC 4648 base32), the closed version-byte registry with its environment bit, the local validation gate with its five-class reject vocabulary, and the delivered-key match rule. The gate is local-only: accept means forward to the authoritative validator, unknown version bytes are forwarded rather than rejected, and a delivered public key is used only when its re-derived CRID equals the held CRID. This family is fully stdlib-derivable, so the strict Go loader re-derives every golden from the DER key bytes. See vectors/README_crid_v1_vectors.md.
• qURL Connector target path (qurl-target-path-v1-vectors, target_path_v1_vectors.json) — the shared local preflight and service input grammar for the optional per-qURL path and query on a tunnel resource. The vectors keep omission distinct from explicit empty, cover the exact 2,048-byte boundary and all closed rejection classes, reject non-canonical path escapes and segments before dispatch, and preserve accepted bytes without decoding or normalization. Schema version 2 removes apostrophe from the whole-value alphabet and adds the path-only forbidden_path_ascii set. Every accepted value is safe to open. See vectors/README_target_path_v1_vectors.md.
• Private upload application signing v1 (qurl-private-upload-v1-vectors, private_upload_v1_vectors.json) — exact POST and PATCH application signatures for the private upload path reached after an authenticated NHP 1.1 ACK. The signature binds the protected ACK URL authority, exact method and path, body digest and length, caller key, and request ID. Upload also binds the audience key, media type, filename, and authority horizon. The artifact publishes strict request construction rules, byte-exact goldens, stable request digests, canonical low-S DER signatures, and executable HTTP and client-preflight rejects. It adds no NHP packet format and defines no CLI or OAuth credential path. See vectors/README_private_upload_v1_vectors.md.

This module is intentionally dependency-free (stdlib only). The generator for key-dependent vectors lives at tools/gen; run make gen-vectors once when its key-dependent artifact must change. It never runs in CI because ECDSA signatures use random nonces and are not reproducible. The committed JSON is the artifact. Vectors are edited under vectors/.

NHP protocol version

Every NHP packet in this repository — relay-knock, agent-registration, agent-assignment, and agent-session — carries protocol 1.1 in HeaderCommon[8:10] (01 01), exposed as NHPProtocolVersionMajor / NHPProtocolVersionMinor. All four families moved from 1.0 together and the loaders assert the bytes.

1.1 folds the 24-byte serialized HeaderCommon into the chain hash and uses it as the body-seal AAD, so editing any header field breaks the body open. Under 1.0 the flag word, header type and declared payload size rode outside every AEAD, covered only by the unkeyed BLAKE2s header digest that anyone holding the peer's static public key can recompute — so those fields were forgeable. Chain-key derivation, the body key, the nonce, and the header-digest input are unchanged.

A 1.1 receiver rejects a 1.0 sender by design, so senders must never lead receivers on a rollout. Reject a lower minor on the version byte rather than on an AEAD tag, so the failure is explicit; admit a higher minor so a later compatible release cannot strand deployed clients.

Who authenticates these bytes

This repository publishes wire truth. The module is stdlib-only by rule (go.mod carries no require), so no BLAKE2s or AEAD primitive exists here and no in-repo check can recompute an NHP packet, a header digest, or the Hub proof digest. Those in-repo gates are structural: framing, lengths, canonical hex/base64, key roles, counter and version bytes, and cross-field correlation. A transcription error inside an otherwise well-formed regenerated packet_hex would pass CI here.

Cryptographic verification belongs to the consumers, which rebuild and open these exact bytes against their real codecs in their own CI. Regenerating any packet family therefore hands verification to a release gate, not to this repository's tests — see RELEASE_CHECKLIST.md.

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 share-safe outer transport, claims/secret/base64/canonical-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 an exact-receipt EXT/ACK retirement exchange, strict cookie and denial 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 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 Connector resource discovery contract (connector_resource_lst_v1_vectors.json): strict native LST/LRT resource lookup, continuity, replay, and error cases.
• The CRID v1 contract (crid_v1_vectors.json): public-key derivation, validation, version registry, and delivered-key matching.
• The qURL Connector target-path contract (target_path_v1_vectors.json): shared local input validation, exact wire preservation, and canonical open-safe paths.
• The private upload application-signing contract (private_upload_v1_vectors.json): byte-exact POST and refresh framing, canonical low-S P-256 signatures, and fail-closed mutation cases.

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 AgentKnockApplicationVectors() []byte
• func AgentRegistrationVectors() []byte
• func AgentSessionControlVectors() []byte
• func AssignmentTicketVectors() []byte
• func CRIDV1KeyMatchExpectation(crid, derSPKIB64URL string) (string, error)
• func CRIDV1Vectors() []byte
• func ConnectorHubLSTChallengeBody(transactionID uint64, cookie []byte) (string, error)
• func ConnectorHubLSTCookieVectors() []byte
• func ConnectorResourceLSTV1Vectors() []byte
• func DecodeRequestNonce(value string) ([]byte, error)
• func DeriveConnectorHubLSTCookie(signingKey []byte, sourceIP string, authenticatedPeerPublicKey []byte, ...) ([]byte, error)
• func IssuerSignatureVectors() []byte
• func Open(name string) ([]byte, error)
• func PrivateUploadV1RefreshCanonicalBytes(g PrivateUploadV1RefreshGolden) ([]byte, error)
• func PrivateUploadV1UploadCanonicalBytes(g PrivateUploadV1UploadGolden) ([]byte, error)
• func PrivateUploadV1Vectors() []byte
• func QV2Vectors() []byte
• func RelayKnockVectors() []byte
• func TargetPathV1Vectors() []byte
• func ValidateConnectorResourceLSTV1AgentID(value string) bool
• func ValidateConnectorResourceLSTV1ConnectorID(value string) bool
• func ValidateConnectorResourceLSTV1Environment(value string) error
• func ValidateConnectorResourceLSTV1KnockResourceID(value string) error
• func ValidateConnectorResourceLSTV1Nonce(value string) error
• func ValidateConnectorResourceLSTV1ResourceID(value string) error
• func ValidateConnectorResourceLSTV1RoutingID(value string) error
• 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 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 AgentSessionControlFile
  • func AgentSessionControl() (*AgentSessionControlFile, error)
  • func ParseAgentSessionControlFile(data []byte) (*AgentSessionControlFile, error)
• type AgentSessionCookieBodyCase
• type AgentSessionDenialACKs
• type AgentSessionExactSessionExit
• 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 CRIDV1Contract
• type CRIDV1File
  • func CRIDV1() (*CRIDV1File, error)
  • func ParseCRIDV1File(data []byte) (*CRIDV1File, error)
• type CRIDV1KeyMatchCase
• type CRIDV1ProducerCase
• type CRIDV1ValueCase
• type CRIDV1Version
• type CRIDV1VersionCase
• type ConformanceClass
• type ConformanceFile
  • func ConformanceVectors() (*ConformanceFile, error)
  • func ParseConformanceFile(data []byte) (*ConformanceFile, error)
• type ConformanceSignatureClass
• type ConformanceTamperDerivation
• type ConformanceTransportContract
• type ConformanceTransportField
• type ConformanceTransportFields
• type ConformanceVector
• 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 ConnectorResourceLSTV1Body
• type ConnectorResourceLSTV1BodyCase
• type ConnectorResourceLSTV1Contract
  • func (contract *ConnectorResourceLSTV1Contract) UnmarshalJSON(data []byte) error
• type ConnectorResourceLSTV1ErrorCase
• type ConnectorResourceLSTV1Exchange
• type ConnectorResourceLSTV1File
  • func ConnectorResourceLSTV1() (*ConnectorResourceLSTV1File, error)
  • func ParseConnectorResourceLSTV1File(data []byte) (*ConnectorResourceLSTV1File, error)
• type ConnectorResourceLSTV1Fixtures
• type ConnectorResourceLSTV1ReplayCase
• type ConnectorResourceLSTV1Request
  • func ParseConnectorResourceLSTV1RequestBody(body []byte, authenticatedAgentID string) (*ConnectorResourceLSTV1Request, error)
• type ConnectorResourceLSTV1RequestUserData
• type ConnectorResourceLSTV1Resource
• type ConnectorResourceLSTV1Result
  • func ParseConnectorResourceLSTV1ResultBody(body []byte, request *ConnectorResourceLSTV1Request) (*ConnectorResourceLSTV1Result, error)
• type ConnectorResourceLSTV1SizeCase
• type ConnectorResourceLSTV1ValidationError
  • func (e *ConnectorResourceLSTV1ValidationError) Error() string
  • func (e *ConnectorResourceLSTV1ValidationError) Unwrap() error
• type ECPublicJWK
• type IssuerKeyMaterial
• type PrivateUploadV1ConstructionRejectCase
• type PrivateUploadV1Contract
• type PrivateUploadV1File
  • func ParsePrivateUploadV1File(data []byte) (*PrivateUploadV1File, error)
  • func PrivateUploadV1() (*PrivateUploadV1File, error)
• type PrivateUploadV1FixtureKey
• type PrivateUploadV1OperationContract
• type PrivateUploadV1RefreshGolden
• type PrivateUploadV1RejectCase
• type PrivateUploadV1RejectMutation
• type PrivateUploadV1UploadGolden
• type RelayKnockCase
• type RelayKnockFile
  • func ParseRelayKnockFile(data []byte) (*RelayKnockFile, error)
  • func RelayKnockGolden() (*RelayKnockFile, error)
• type SignatureVector
• type TargetPathCase
  • func (c *TargetPathCase) UnmarshalJSON(data []byte) error
• type TargetPathContract
• type TargetPathV1File
  • func ParseTargetPathV1File(data []byte) (*TargetPathV1File, error)
  • func TargetPathV1() (*TargetPathV1File, error)
• 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 (
	// AgentSessionControlArtifactID identifies the registered-agent overload
	// re-knock and exact-session retirement packet artifact.
	AgentSessionControlArtifactID = "qurl-agent-session-control-vectors"
	// AgentSessionControlSchemaVersion identifies the exact immutable session
	// receipt carried by successful KNK/RKN ACKs and the strict EXT/ACK retirement
	// exchange. Earlier resource-scoped and bodyless/global EXT contracts are not
	// accepted on the current NHP 1.1 envelope.
	AgentSessionControlSchemaVersion = 4
	// AgentSessionControlProducerRevision is the exact producer revision that
	// deterministically reproduces the golden packets and contains the strict
	// exact-session receipt and EXT/ACK retirement contract in layervai/qurl-go.
	// This signed qurl-go main commit contains the deterministic regeneration
	// gate that reproduces every committed body and packet byte.
	AgentSessionControlProducerRevision = "b962ee4aa82f643d507ddf75adc3c110df8dff9d"

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

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

	// AgentSessionProtocolVersionMajor / Minor are retained names for the
	// repo-wide NHPProtocolVersion pair. Session-control packets carry the same
	// HeaderCommon[8:10] bytes as every other NHP family, so the literals live in
	// one place; these aliases exist only for consumers already referencing them.
	AgentSessionProtocolVersionMajor = NHPProtocolVersionMajor
	AgentSessionProtocolVersionMinor = NHPProtocolVersionMinor
)

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"
	AgentSessionRejectSessionReceipt     = "session_receipt"
	AgentSessionRejectDenialReceipt      = "denial_receipt"
	AgentSessionRejectCloseEvent         = "close_event"
	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 (
	// 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 (
	// ConnectorResourceLSTV1ArtifactID identifies the registered-agent
	// NHP_LST/NHP_LRT Connector resource-discovery contract.
	ConnectorResourceLSTV1ArtifactID = "qurl-connector-resource-lst-v1-vectors"
	// ConnectorResourceLSTV1SchemaVersion is the only artifact schema accepted
	// by this release.
	ConnectorResourceLSTV1SchemaVersion = 1

	ConnectorResourceLSTV1Query   = "connector_resource"
	ConnectorResourceLSTV1Version = 1
	ConnectorResourceLSTV1AspID   = "agent"

	ConnectorResourceLSTV1RequestHeaderName = "NHP_LST"
	ConnectorResourceLSTV1RequestHeaderType = 5
	ConnectorResourceLSTV1ResultHeaderName  = "NHP_LRT"
	ConnectorResourceLSTV1ResultHeaderType  = 6

	ConnectorResourceLSTV1NonceBytes         = RequestNonceBytes
	ConnectorResourceLSTV1ResourceIDBytes    = 91
	ConnectorResourceLSTV1ResourceIDChars    = 122
	ConnectorResourceLSTV1RoutingDigestBytes = 32
	ConnectorResourceLSTV1RoutingIDPrefix    = "c-"
	ConnectorResourceLSTV1RoutingIDChars     = 54
	// ConnectorResourceLSTV1KnockResourceIDMax is deliberately 64 bytes: even
	// when every byte expands to a six-byte JSON escape, the maximal success
	// object remains inside ConnectorResourceLSTV1MaxPlaintextBodyBytes.
	ConnectorResourceLSTV1KnockResourceIDMax          = 64
	ConnectorResourceLSTV1ConservativeSealBudgetBytes = 256
	ConnectorResourceLSTV1MaxPacketBytes              = 1232
	ConnectorResourceLSTV1MaxPlaintextBodyBytes       = ConnectorResourceLSTV1MaxPacketBytes - ConnectorResourceLSTV1ConservativeSealBudgetBytes
	ConnectorResourceLSTV1MaxRetryAfterSeconds        = 3600

	ConnectorResourceLSTV1OutcomeAccept = "accept"
	ConnectorResourceLSTV1OutcomeReject = "reject"
	ConnectorResourceLSTV1OutcomeError  = "error"

	ConnectorResourceLSTV1RejectBodyParse       = "body_parse"
	ConnectorResourceLSTV1RejectUnknownField    = "unknown_field"
	ConnectorResourceLSTV1RejectMissingField    = "missing_field"
	ConnectorResourceLSTV1RejectWrongType       = "wrong_type"
	ConnectorResourceLSTV1RejectSemantic        = "semantic"
	ConnectorResourceLSTV1RejectAgentBinding    = "agent_binding"
	ConnectorResourceLSTV1RejectRequestBinding  = "request_binding"
	ConnectorResourceLSTV1RejectResourceBinding = "resource_binding"
	ConnectorResourceLSTV1RejectCRIDBinding     = "crid_binding"
	ConnectorResourceLSTV1RejectListOnError     = "list_on_error"
	ConnectorResourceLSTV1RejectRetryMissing    = "retry_after_missing"
	ConnectorResourceLSTV1RejectRetryInvalid    = "retry_after_invalid"
	ConnectorResourceLSTV1RejectRetryUnexpected = "retry_after_unexpected"
	ConnectorResourceLSTV1RejectUnknownError    = "unknown_error_code"
	ConnectorResourceLSTV1RejectPacketSize      = "packet_size"

	ConnectorResourceLSTV1ErrorUnavailable      = "52500"
	ConnectorResourceLSTV1ErrorIdentityRejected = "52501"
	ConnectorResourceLSTV1ErrorEntitlement      = "52502"
	ConnectorResourceLSTV1ErrorIdentityConflict = "52503"
	ConnectorResourceLSTV1ErrorQuota            = "52504"
	ConnectorResourceLSTV1ErrorRateLimited      = "52505"
	ConnectorResourceLSTV1ErrorInvalidRequest   = "52506"
)

const (
	// CRIDV1ArtifactID identifies the CRID v1 derivation and validation artifact.
	CRIDV1ArtifactID = "qurl-crid-v1-vectors"
	// CRIDV1SchemaVersion is the only schema accepted by this release.
	CRIDV1SchemaVersion = 1

	// CRIDV1DomainSeparationPrefix starts every digest input, followed by one
	// 0x00 separator byte and the DER SubjectPublicKeyInfo bytes.
	CRIDV1DomainSeparationPrefix = "NHP-QURL-CRID-V1"
	// CRIDV1DomainSeparator is the single byte between the prefix and the key.
	CRIDV1DomainSeparator = byte(0x00)
	// CRIDV1ChecksumLength is the byte length of the big-endian CRC32C
	// (Castagnoli, polynomial 0x1edc6f41) appended after the payload.
	CRIDV1ChecksumLength = 4
	// CRIDV1ChecksumPolynomialHex is the Castagnoli polynomial in normal
	// (non-reflected) form; Go's crc32.Castagnoli table constant is its
	// bit-reversed representation.
	CRIDV1ChecksumPolynomialHex = "1edc6f41"
	// CRIDV1Alphabet is the RFC 4648 base32 alphabet in lowercase; encoding is
	// unpadded.
	CRIDV1Alphabet = "abcdefghijklmnopqrstuvwxyz234567"
	// CRIDV1EnvironmentBit distinguishes non-production version bytes.
	CRIDV1EnvironmentBit = byte(0x80)
	// CRIDV1ForbiddenVersion is permanently invalid and must reject locally.
	CRIDV1ForbiddenVersion = byte(0x00)

	CRIDV1FullDigestLength      = 32
	CRIDV1FullCRIDLength        = 60
	CRIDV1TruncatedDigestLength = 24
	CRIDV1TruncatedCRIDLength   = 47

	CRIDV1EnvironmentProduction = "production"
	CRIDV1EnvironmentTest       = "test"
	// CRIDV1EnvironmentUnknown is reported for structurally valid CRIDs whose
	// version byte is not in the registry; such values are forwarded, not
	// rejected.
	CRIDV1EnvironmentUnknown = "unknown"

	CRIDV1StatusActive   = "active"
	CRIDV1StatusReserved = "reserved"

	CRIDV1OutcomeMatch    = "match"
	CRIDV1OutcomeMismatch = "mismatch"

	// The closed local reject_class vocabulary. Adding a class is a breaking
	// change that requires a schema_version bump.
	CRIDV1RejectLength       = "length"
	CRIDV1RejectCharset      = "charset"
	CRIDV1RejectChecksum     = "checksum"
	CRIDV1RejectNonCanonical = "non_canonical"
	CRIDV1RejectVersion      = "version"
)

const (
	PrivateUploadV1ArtifactID    = "qurl-private-upload-v1-vectors"
	PrivateUploadV1SchemaVersion = 1
	PrivateUploadV1Description   = "" /* 266-byte string literal not displayed */

	PrivateUploadV1NHPVersion           = "1.1"
	PrivateUploadV1Path                 = "/internal/v1/uploads"
	PrivateUploadV1UploadMethod         = "POST"
	PrivateUploadV1RefreshMethod        = "PATCH"
	PrivateUploadV1UploadAuthDomain     = "LV-QURL-UPLOAD-AUTH-V1"
	PrivateUploadV1UploadRequestDomain  = "LV-QURL-UPLOAD-REQUEST-V1"
	PrivateUploadV1RefreshAuthDomain    = "LV-QURL-UPLOAD-REFRESH-AUTH-V1"
	PrivateUploadV1RefreshRequestDomain = "LV-QURL-UPLOAD-REFRESH-REQUEST-V1"
	PrivateUploadV1FrameEncoding        = "u32be_byte_length_then_exact_utf8_bytes"
	PrivateUploadV1SignatureAlgorithm   = "ECDSA_P-256_SHA-256"
	PrivateUploadV1SignatureEncoding    = "canonical_der_base64url_unpadded_low_s"
	PrivateUploadV1PrivateKeyEncoding   = "pkcs8_der_base64url_unpadded"
	PrivateUploadV1PublicKeyEncoding    = "der_spki_base64url_unpadded"
	PrivateUploadV1ContentDigest        = "sha-256=:canonical_standard_base64_sha256:"
	PrivateUploadV1AudienceKeyIDRule    = "regex:^key_[A-Za-z0-9]{12}$"
	PrivateUploadV1ClientIDRule         = "regex:^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
	PrivateUploadV1KeyIDRule            = "regex:^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
	PrivateUploadV1UploadRequestIDRule  = "regex:^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
	PrivateUploadV1UploadHandleRule     = "regex:^upl_[A-Za-z0-9_-]{43}$"
	PrivateUploadV1AuthorityExpiryRule  = "rfc3339_utc_whole_seconds_uppercase_z"
	PrivateUploadV1BodyLengthRule       = "positive_canonical_decimal_equal_to_exact_body_byte_length"
	PrivateUploadV1MediaTypeRule        = "regex:^[!#$%&'*+.^_`|~0-9a-z-]+/[!#$%&'*+.^_`|~0-9a-z-]+$"
	PrivateUploadV1MediaTypeSubtypeRule = "not_exactly_star"
	PrivateUploadV1FilenameEncoding     = "utf8_then_base64url_unpadded"
	PrivateUploadV1DisplayFilenameRule  = "" /* 139-byte string literal not displayed */
	PrivateUploadV1AuthFailureStatus    = 401
	PrivateUploadV1AuthFailureCode      = "invalid_upload_auth"
)

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"
	// RejectClassTransport is a qv2t1 outer transport framing rejection.
	RejectClassTransport = "transport"
	// 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 (transport; 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 (
	NHPProtocolVersionMajor = 1
	NHPProtocolVersionMinor = 1
)

NHPProtocolVersionMajor / Minor are the HeaderCommon[8:10] bytes every NHP golden packet in this repository carries, across all four packet families: relay-knock, agent-registration, agent-assignment and agent-session. The version is a repo-wide fact, not a per-family one, so a family must never restate the literals.

Minor 1 is the transcript that folds the 24-byte serialized HeaderCommon into the body-seal AAD. Under 1.0 the flag word, header type and declared size rode outside every AEAD and were forgeable by anyone holding the peer's static public key. Consumers must reject a packet below this minor on the version rather than on an AEAD tag.

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 layervai/qurl-go packet-codec
	// revision that built and authenticate-opened 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.
	//
	// It names the protocol-1.1 codec commit on branch
	// justin/feat/authenticate-nhp-header-aad, which is pushed and immutable but
	// NOT yet merged. A pre-merge pin is the only value that is true today; a
	// squash-merge will mint a different SHA, so re-pinning to the merged commit
	// is a release-checklist item (see RELEASE_CHECKLIST.md).
	AgentAssignmentQURLGoProducerRevision = "c4729832bf29b0f356964035864707f6904b1982"
	// 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"
	AgentKnockRejectSessionID            = "session_id"
	AgentKnockRejectSessionLifetime      = "session_lifetime"
	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 (
	// TargetPathArtifactID identifies the shared Connector target-path input contract.
	TargetPathArtifactID = "qurl-target-path-v1-vectors"
	// TargetPathSchemaVersion is the only schema accepted by this release.
	TargetPathSchemaVersion = 2
	// TargetPathMaxBytes is the complete target_path wire-value limit.
	TargetPathMaxBytes = 2048

	// TargetPathReject* constants are the closed v1 local reject vocabulary.
	TargetPathRejectEmpty            = "empty"
	TargetPathRejectTooLong          = "too_long"
	TargetPathRejectNotAbsolute      = "not_absolute"
	TargetPathRejectAuthority        = "authority"
	TargetPathRejectInvalidCharacter = "invalid_character"
	TargetPathRejectDotSegment       = "dot_segment"
	TargetPathRejectPercentEncoding  = "percent_encoding"

	// TargetPathAllowedASCII is the complete raw ASCII alphabet accepted by
	// the whole-value character gate. Later ordered gates further restrict
	// characters and percent escapes in the path component.
	TargetPathAllowedASCII = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._~!$&()*+,;=:@%/?-"
	// TargetPathForbiddenPathASCII is the complete set of raw ASCII characters
	// accepted in the query but rejected in the path component.
	TargetPathForbiddenPathASCII = "!()*;"
)

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 ConformanceSchemaVersion = 2

ConformanceSchemaVersion is the exact qURL v2 artifact schema understood by this package. Version 2 adds the mandatory qv2t1 outer transport contract and its behavioral vector class.

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.

const RequestNonceBytes = 32

RequestNonceBytes is the exact decoded length of the public LST request_nonce that a registered agent mints per logical request.

Variables

var ErrRequestNonce = errors.New("conformance: invalid request nonce")

ErrRequestNonce identifies a logical-request nonce that is not exactly RequestNonceBytes of canonical unpadded base64url.

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 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 exact-session retirement packet artifact.

func AssignmentTicketVectors

func AssignmentTicketVectors() []byte

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

func CRIDV1KeyMatchExpectation

func CRIDV1KeyMatchExpectation(crid, derSPKIB64URL string) (string, error)

CRIDV1KeyMatchExpectation re-derives a CRID from the delivered key under the held CRID's version byte and digest length and reports whether a consumer may use the key.

func CRIDV1Vectors

func CRIDV1Vectors() []byte

CRIDV1Vectors returns the raw bytes of the CRID v1 derivation and validation vectors shared by every producer and consumer of the cryptographic resource identifier.

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 ConnectorResourceLSTV1Vectors

func ConnectorResourceLSTV1Vectors() []byte

ConnectorResourceLSTV1Vectors returns the exact registered-agent NHP_LST and NHP_LRT application bodies for resolving one Connector resource.

func DecodeRequestNonce

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

DecodeRequestNonce strictly decodes the public LST request_nonce grammar: an SDK mints it once per logical request and the platform consumes it as exactly RequestNonceBytes of canonical unpadded base64url. Strict raw-url decoding rejects padding, out-of-alphabet bytes, and non-zero trailing bits, but Go's decoder still skips embedded CR and LF, so the re-encode comparison is what pins one wire string per nonce. The returned raw bytes are what the Hub binds its private replay identifier to.

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 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 PrivateUploadV1RefreshCanonicalBytes

func PrivateUploadV1RefreshCanonicalBytes(g PrivateUploadV1RefreshGolden) ([]byte, error)

func PrivateUploadV1UploadCanonicalBytes

func PrivateUploadV1UploadCanonicalBytes(g PrivateUploadV1UploadGolden) ([]byte, error)

func PrivateUploadV1Vectors

func PrivateUploadV1Vectors() []byte

PrivateUploadV1Vectors returns the private upload and refresh application- signing contract and its byte-exact golden requests.

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.

func TargetPathV1Vectors

func TargetPathV1Vectors() []byte

TargetPathV1Vectors returns the raw bytes of the canonical target_path request contract shared by the service and SDKs.

func ValidateConnectorResourceLSTV1AgentID

func ValidateConnectorResourceLSTV1AgentID(value string) bool

func ValidateConnectorResourceLSTV1ConnectorID

func ValidateConnectorResourceLSTV1ConnectorID(value string) bool

func ValidateConnectorResourceLSTV1Environment

func ValidateConnectorResourceLSTV1Environment(value string) error

ValidateConnectorResourceLSTV1Environment rejects a value that is not a canonical Connector environment label: lowercase, starting with a letter, at most 32 bytes, with no leading or trailing hyphen. Private contracts that compose this artifact validate their environment field through this exact gate rather than a copied pattern.

func ValidateConnectorResourceLSTV1KnockResourceID

func ValidateConnectorResourceLSTV1KnockResourceID(value string) error

func ValidateConnectorResourceLSTV1Nonce

func ValidateConnectorResourceLSTV1Nonce(value string) error

ValidateConnectorResourceLSTV1Nonce applies the one shared request_nonce grammar (DecodeRequestNonce) to a Connector resource request.

func ValidateConnectorResourceLSTV1ResourceID

func ValidateConnectorResourceLSTV1ResourceID(value string) error

func ValidateConnectorResourceLSTV1RoutingID

func ValidateConnectorResourceLSTV1RoutingID(value string) error

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 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"`
	ExpectedSessionID    string `json:"expected_session_id,omitempty"`
	ExpectedOpenTime     uint32 `json:"expected_open_time,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, ExpectedResourceHost, ExpectedSessionID, and ExpectedOpenTime are present only on success and pin the exact values a conforming interpreter must return; optional ACK metadata cannot substitute for them. Session ID remains a decimal string outside BodyJSON so JavaScript consumers can compare every uint64 value without losing precision.

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 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"`
	ExactSessionExit AgentSessionExactSessionExit `json:"exact_session_exit"`
	DenialACKs       AgentSessionDenialACKs       `json:"denial_acks"`
	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 exact-session EXT/ACK.

func AgentSessionControl

func AgentSessionControl() (*AgentSessionControlFile, error)

AgentSessionControl strictly parses the native-UDP overload re-knock and exact-session retirement 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 AgentSessionDenialACKs

type AgentSessionDenialACKs struct {
	Knock AgentSessionPacket `json:"knock"`
	Exit  AgentSessionPacket `json:"exit"`
}

type AgentSessionExactSessionExit

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

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"`
	KnockRunAttempt               string `json:"knock_run_attempt"`
	SuccessACKReceipt             string `json:"success_ack_receipt"`
	ExitBody                      string `json:"exit_body"`
	ExitResponse                  string `json:"exit_response"`
	DenialReceiptFields           string `json:"denial_receipt_fields"`
	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 CRIDV1Contract

type CRIDV1Contract struct {
	DomainSeparationPrefix string `json:"domain_separation_prefix"`
	DomainSeparatorHex     string `json:"domain_separator_hex"`
	Digest                 string `json:"digest"`
	Checksum               string `json:"checksum"`
	ChecksumPolynomialHex  string `json:"checksum_polynomial_hex"`
	ChecksumByteOrder      string `json:"checksum_byte_order"`
	ChecksumLength         int    `json:"checksum_length"`
	Encoding               string `json:"encoding"`
	Alphabet               string `json:"alphabet"`
	EnvironmentBitHex      string `json:"environment_bit_hex"`
	ForbiddenVersionHex    string `json:"forbidden_version_hex"`
	FullDigestLength       int    `json:"full_digest_length"`
	FullCRIDLength         int    `json:"full_crid_length"`
	TruncatedDigestLength  int    `json:"truncated_digest_length"`
	TruncatedCRIDLength    int    `json:"truncated_crid_length"`
}

CRIDV1Contract is the language-neutral public derivation grammar.

type CRIDV1File

type CRIDV1File struct {
	Artifact           string               `json:"artifact"`
	SchemaVersion      int                  `json:"schema_version"`
	Description        string               `json:"description"`
	Contract           CRIDV1Contract       `json:"contract"`
	Versions           []CRIDV1Version      `json:"versions"`
	ProducerCases      []CRIDV1ProducerCase `json:"producer_cases"`
	ConsumerValueCases []CRIDV1ValueCase    `json:"consumer_value_cases"`
	VersionCases       []CRIDV1VersionCase  `json:"version_cases"`
	KeyMatchCases      []CRIDV1KeyMatchCase `json:"key_match_cases"`
}

CRIDV1File freezes the CRID v1 derivation, the local validation gate, the version-byte registry, and the delivered-key match rule.

func CRIDV1

func CRIDV1() (*CRIDV1File, error)

CRIDV1 strictly parses the embedded CRID v1 derivation and validation artifact.

func ParseCRIDV1File

func ParseCRIDV1File(data []byte) (*CRIDV1File, error)

ParseCRIDV1File strictly parses the CRID v1 artifact and independently re-derives every declared expectation: producer digests, checksums and CRIDs from the DER key bytes, consumer outcomes from the reference local gate, version-case fields from the registry, and key-match outcomes from the derivation itself.

type CRIDV1KeyMatchCase

type CRIDV1KeyMatchCase struct {
	Name          string `json:"name"`
	CRID          string `json:"crid"`
	DERSPKIB64URL string `json:"der_spki_b64url"`
	Outcome       string `json:"outcome"`
}

CRIDV1KeyMatchCase pins the consumer rule that a delivered public key is used only when its derived CRID equals the CRID the consumer already holds.

type CRIDV1ProducerCase

type CRIDV1ProducerCase struct {
	Name          string `json:"name"`
	DERSPKIB64URL string `json:"der_spki_b64url"`
	VersionByte   string `json:"version_byte"`
	Environment   string `json:"environment"`
	DigestHex     string `json:"digest_hex"`
	PayloadHex    string `json:"payload_hex"`
	CRCHex        string `json:"crc_hex"`
	ExpectedCRID  string `json:"expected_crid"`
}

CRIDV1ProducerCase lets a producer drive its real derivation with a frozen DER SubjectPublicKeyInfo and version byte and compare every intermediate. PayloadHex is the complete pre-encoding byte string version_byte || digest[:digest_length] || crc; CRCHex is its final four bytes, computed over everything before them.

type CRIDV1ValueCase

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

CRIDV1ValueCase is one direct input to the local validation gate.

type CRIDV1Version

type CRIDV1Version struct {
	VersionHex   string `json:"version_hex"`
	DigestLength int    `json:"digest_length"`
	Environment  string `json:"environment"`
	Status       string `json:"status"`
}

CRIDV1Version is one row of the closed version-byte registry.

type CRIDV1VersionCase

type CRIDV1VersionCase struct {
	Name         string `json:"name"`
	Value        string `json:"value"`
	VersionHex   string `json:"version_hex"`
	Known        bool   `json:"known"`
	Environment  string `json:"environment"`
	DigestLength int    `json:"digest_length"`
}

CRIDV1VersionCase pins what a consumer reports for the version byte of a locally valid CRID.

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"`
	TransportContract ConformanceTransportContract `json:"transport_contract"`
	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 ConformanceTransportContract

type ConformanceTransportContract struct {
	Prefix             string                     `json:"prefix"`
	CanonicalPrefix    string                     `json:"canonical_prefix"`
	ComponentMax       int                        `json:"component_max"`
	MaxTransportLength int                        `json:"max_transport_length"`
	Fields             ConformanceTransportFields `json:"fields"`
}

ConformanceTransportContract pins the non-cryptographic qv2t1 envelope used in URL fragments. It chunks the three exact qv2 base64url fields so no URL dot-component exceeds ComponentMax, then reconstructs the byte-identical qv2 canonical fragment before the existing security parser runs.

type ConformanceTransportField

type ConformanceTransportField struct {
	MaxEncodedLength int `json:"max_encoded_length"`
	MaxChunks        int `json:"max_chunks"`
}

ConformanceTransportField is one reconstructed qv2 base64url field's bound.

type ConformanceTransportFields

type ConformanceTransportFields struct {
	Claims    ConformanceTransportField `json:"claims"`
	Secret    ConformanceTransportField `json:"secret"`
	Signature ConformanceTransportField `json:"signature"`
}

ConformanceTransportFields records the fixed field order and independent encoded-size/count bounds. Struct fields keep this closed under strict JSON parsing; consumers must not accept a fourth field or reorder these three.

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"`

	// transport: a qv2t1 outer fragment body and, on accept vectors, the exact
	// canonical qv2 fragment body it must reconstruct. Reject vectors omit the
	// canonical output.
	TransportFragment string `json:"transport_fragment"`
	CanonicalFragment string `json:"canonical_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 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 ConnectorResourceLSTV1Body

type ConnectorResourceLSTV1Body struct {
	HeaderName      string `json:"header_name"`
	HeaderType      int    `json:"header_type"`
	BodyJSON        string `json:"body_json"`
	BodyBytes       int    `json:"body_bytes"`
	SizeBudgetBytes int    `json:"size_budget_bytes"`
}

type ConnectorResourceLSTV1BodyCase

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

type ConnectorResourceLSTV1Contract

type ConnectorResourceLSTV1Contract struct {
	Query                         string   `json:"query"`
	Version                       int      `json:"version"`
	RequestHeaderName             string   `json:"request_header_name"`
	RequestHeaderType             int      `json:"request_header_type"`
	ResultHeaderName              string   `json:"result_header_name"`
	ResultHeaderType              int      `json:"result_header_type"`
	AspID                         string   `json:"asp_id"`
	RequestOuterFields            []string `json:"request_outer_fields"`
	RequestUserDataRequiredFields []string `json:"request_user_data_required_fields"`
	RequestUserDataOptionalFields []string `json:"request_user_data_optional_fields"`
	SuccessOuterFields            []string `json:"success_outer_fields"`
	SuccessListRequiredFields     []string `json:"success_list_required_fields"`
	SuccessListOptionalFields     []string `json:"success_list_optional_fields"`
	ErrorRequiredFields           []string `json:"error_required_fields"`
	ErrorOptionalFields           []string `json:"error_optional_fields"`
	NonceEncoding                 string   `json:"nonce_encoding"`
	NonceDecodedBytes             int      `json:"nonce_decoded_bytes"`
	AgentIDPattern                string   `json:"agent_id_pattern"`
	ConnectorIDPattern            string   `json:"connector_id_pattern"`
	ResourceIDEncoding            string   `json:"resource_id_encoding"`
	ResourceIDDecodedBytes        int      `json:"resource_id_decoded_bytes"`
	ResourceIDEncodedChars        int      `json:"resource_id_encoded_chars"`
	ConnectorRoutingIDPattern     string   `json:"connector_routing_id_pattern"`
	KnockResourceIDMaxBytes       int      `json:"knock_resource_id_max_bytes"`
	CRIDProfile                   string   `json:"crid_profile"`
	IdentitySource                string   `json:"identity_source"`
	EntitlementSource             string   `json:"entitlement_source"`
	OneResourcePerExchange        bool     `json:"one_resource_per_exchange"`
	HTTPFallbackAllowed           bool     `json:"http_fallback_allowed"`
	ExpectedResourceIDRule        string   `json:"expected_resource_id_rule"`
	ExactReplayRule               string   `json:"exact_replay_rule"`
	ChangedReplayRule             string   `json:"changed_replay_rule"`
	LaterRequestRule              string   `json:"later_request_rule"`
	FoundExistingRule             string   `json:"found_existing_rule"`
	AuthorizationFreshnessRule    string   `json:"authorization_freshness_rule"`
	ConservativeOverheadBytes     int      `json:"conservative_overhead_bytes"`
	SizeAccountingRule            string   `json:"size_accounting_rule"`
	RealSealProofOwner            string   `json:"real_seal_proof_owner"`
	MaxPlaintextBodyBytes         int      `json:"max_plaintext_body_bytes"`
	MaxPacketBytes                int      `json:"max_packet_bytes"`
	MaxRetryAfterSeconds          int      `json:"max_retry_after_seconds"`
	RejectClasses                 []string `json:"reject_classes"`
	ErrorCodes                    []string `json:"error_codes"`
}

ConnectorResourceLSTV1Contract is the complete consumer-neutral wire and trust-boundary profile.

func (*ConnectorResourceLSTV1Contract) UnmarshalJSON

func (contract *ConnectorResourceLSTV1Contract) UnmarshalJSON(data []byte) error

UnmarshalJSON requires security-sensitive false decisions to be explicit.

type ConnectorResourceLSTV1ErrorCase

type ConnectorResourceLSTV1ErrorCase struct {
	Name              string `json:"name"`
	BodyJSON          string `json:"body_json"`
	ErrorCode         string `json:"error_code"`
	Retryable         bool   `json:"retryable"`
	RetryAfterSeconds int    `json:"retry_after_seconds,omitempty"`
}

type ConnectorResourceLSTV1Exchange

type ConnectorResourceLSTV1Exchange struct {
	Name                  string                     `json:"name"`
	Request               ConnectorResourceLSTV1Body `json:"request"`
	Result                ConnectorResourceLSTV1Body `json:"result"`
	ExpectedFoundExisting bool                       `json:"expected_found_existing"`
}

type ConnectorResourceLSTV1File

type ConnectorResourceLSTV1File struct {
	Artifact          string                             `json:"artifact"`
	SchemaVersion     int                                `json:"schema_version"`
	Description       string                             `json:"description"`
	Notes             []string                           `json:"notes"`
	Contract          ConnectorResourceLSTV1Contract     `json:"contract"`
	Fixtures          ConnectorResourceLSTV1Fixtures     `json:"fixtures"`
	SuccessExchanges  []ConnectorResourceLSTV1Exchange   `json:"success_exchanges"`
	ReplayCases       []ConnectorResourceLSTV1ReplayCase `json:"replay_cases"`
	RequestCases      []ConnectorResourceLSTV1BodyCase   `json:"request_cases"`
	ResultRejectCases []ConnectorResourceLSTV1BodyCase   `json:"result_reject_cases"`
	ErrorCases        []ConnectorResourceLSTV1ErrorCase  `json:"error_cases"`
	ErrorRejectCases  []ConnectorResourceLSTV1BodyCase   `json:"error_reject_cases"`
	SizeCases         []ConnectorResourceLSTV1SizeCase   `json:"size_cases"`
}

ConnectorResourceLSTV1File freezes the public application bodies, replay behavior, closed error grammar, and operational unfragmented size bound. It deliberately contains no encrypted packets: consumers compose these exact bodies with their own NHP 1.1 codec and pinned assigned-cell key.

func ConnectorResourceLSTV1

func ConnectorResourceLSTV1() (*ConnectorResourceLSTV1File, error)

ConnectorResourceLSTV1 strictly parses the registered-agent Connector resource-discovery application contract.

func ParseConnectorResourceLSTV1File

func ParseConnectorResourceLSTV1File(data []byte) (*ConnectorResourceLSTV1File, error)

ParseConnectorResourceLSTV1File strictly parses the embedded Connector resource discovery artifact and reclassifies every body through the reference application parser.

type ConnectorResourceLSTV1Fixtures

type ConnectorResourceLSTV1Fixtures struct {
	AgentID                       string `json:"agent_id"`
	AuthenticatedPeerPublicKeyB64 string `json:"authenticated_peer_public_key_b64"`
	ConnectorID                   string `json:"connector_id"`
	ResourceID                    string `json:"resource_id"`
	ConnectorRoutingID            string `json:"connector_routing_id"`
	KnockResourceID               string `json:"knock_resource_id"`
	CRID                          string `json:"crid"`
	CreateRequestNonce            string `json:"create_request_nonce"`
	ExistingRequestNonce          string `json:"existing_request_nonce"`
	NoCRIDRequestNonce            string `json:"no_crid_request_nonce"`
}

type ConnectorResourceLSTV1ReplayCase

type ConnectorResourceLSTV1ReplayCase struct {
	Name                    string `json:"name"`
	FirstExchange           string `json:"first_exchange"`
	ReplayRequestBodyJSON   string `json:"replay_request_body_json"`
	ChangedRequestBodyJSON  string `json:"changed_request_body_json,omitempty"`
	ExpectedOutcome         string `json:"expected_outcome"`
	ExpectedResultBodyJSON  string `json:"expected_result_body_json,omitempty"`
	ExpectedErrorCode       string `json:"expected_error_code,omitempty"`
	MutationAllowed         bool   `json:"mutation_allowed"`
	FoundExistingOnResponse *bool  `json:"found_existing_on_response,omitempty"`
}

type ConnectorResourceLSTV1Request

type ConnectorResourceLSTV1Request = connectorResourceLSTV1RequestWire

Exported aliases are the exact public application-body types. Callers should use the parsing functions below so duplicate keys, null optionals, request binding, CRID binding, and closed error grammar remain enforced.

func ParseConnectorResourceLSTV1RequestBody

func ParseConnectorResourceLSTV1RequestBody(body []byte, authenticatedAgentID string) (*ConnectorResourceLSTV1Request, error)

ParseConnectorResourceLSTV1RequestBody validates one already-decrypted LST body against the agent id independently established by the authenticated NHP peer mapping.

type ConnectorResourceLSTV1RequestUserData

type ConnectorResourceLSTV1RequestUserData = connectorResourceLSTV1RequestUserDataWire

type ConnectorResourceLSTV1Resource

type ConnectorResourceLSTV1Resource = connectorResourceLSTV1SuccessListWire

type ConnectorResourceLSTV1Result

type ConnectorResourceLSTV1Result = connectorResourceLSTV1ResultWire

func ParseConnectorResourceLSTV1ResultBody

func ParseConnectorResourceLSTV1ResultBody(body []byte, request *ConnectorResourceLSTV1Request) (*ConnectorResourceLSTV1Result, error)

ParseConnectorResourceLSTV1ResultBody validates an already-decrypted LRT body. request may be nil only when parsing an error result; a success without its originating request is rejected by higher-level transaction correlation.

type ConnectorResourceLSTV1SizeCase

type ConnectorResourceLSTV1SizeCase struct {
	Name            string `json:"name"`
	Direction       string `json:"direction"`
	BodyJSON        string `json:"body_json,omitempty"`
	BodyFillByteHex string `json:"body_fill_byte_hex,omitempty"`
	BodyBytes       int    `json:"body_bytes"`
	SizeBudgetBytes int    `json:"size_budget_bytes"`
	Outcome         string `json:"outcome"`
}

type ConnectorResourceLSTV1ValidationError

type ConnectorResourceLSTV1ValidationError struct {
	RejectClass string
	// contains filtered or unexported fields
}

ConnectorResourceLSTV1ValidationError carries the stable consumer-neutral reject class without exposing rejected values in a sentinel error.

func (*ConnectorResourceLSTV1ValidationError) Error

func (e *ConnectorResourceLSTV1ValidationError) Error() string

func (*ConnectorResourceLSTV1ValidationError) Unwrap

func (e *ConnectorResourceLSTV1ValidationError) Unwrap() error

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 PrivateUploadV1ConstructionRejectCase

type PrivateUploadV1ConstructionRejectCase struct {
	Name       string `json:"name"`
	Base       string `json:"base"`
	Field      string `json:"field"`
	Value      string `json:"value"`
	RejectRule string `json:"reject_rule"`
	Outcome    string `json:"outcome"`
}

type PrivateUploadV1Contract

type PrivateUploadV1Contract struct {
	NHPProtocolVersion      string                           `json:"nhp_protocol_version"`
	TransportScope          string                           `json:"transport_scope"`
	FreshnessReplayScope    string                           `json:"freshness_replay_scope"`
	Path                    string                           `json:"path"`
	AuthorityRule           string                           `json:"authority_rule"`
	AudienceKeyIDRule       string                           `json:"audience_key_id_rule"`
	ClientIDRule            string                           `json:"client_id_rule"`
	KeyIDRule               string                           `json:"key_id_rule"`
	UploadRequestIDRule     string                           `json:"upload_request_id_rule"`
	UploadHandleRule        string                           `json:"upload_handle_rule"`
	AuthorityExpiresAtRule  string                           `json:"authority_expires_at_rule"`
	BodyLengthRule          string                           `json:"body_length_rule"`
	FrameEncoding           string                           `json:"frame_encoding"`
	SignatureAlgorithm      string                           `json:"signature_algorithm"`
	SignatureEncoding       string                           `json:"signature_encoding"`
	PrivateKeyEncoding      string                           `json:"private_key_encoding"`
	PublicKeyEncoding       string                           `json:"public_key_encoding"`
	ContentDigestEncoding   string                           `json:"content_digest_encoding"`
	NonceEncoding           string                           `json:"nonce_encoding"`
	NonceDecodedBytes       int                              `json:"nonce_decoded_bytes"`
	TimestampMaxSkewSeconds int                              `json:"timestamp_max_skew_seconds"`
	Upload                  PrivateUploadV1OperationContract `json:"upload"`
	Refresh                 PrivateUploadV1OperationContract `json:"refresh"`
	RejectClasses           []string                         `json:"reject_classes"`
	RejectClassPrecedence   []string                         `json:"reject_class_precedence"`
}

type PrivateUploadV1File

type PrivateUploadV1File struct {
	Artifact                string                                  `json:"artifact"`
	SchemaVersion           int                                     `json:"schema_version"`
	Description             string                                  `json:"description"`
	Contract                PrivateUploadV1Contract                 `json:"contract"`
	FixtureKey              PrivateUploadV1FixtureKey               `json:"fixture_key"`
	UploadGolden            PrivateUploadV1UploadGolden             `json:"upload_golden"`
	RefreshGolden           PrivateUploadV1RefreshGolden            `json:"refresh_golden"`
	RejectCases             []PrivateUploadV1RejectCase             `json:"reject_cases"`
	ConstructionRejectCases []PrivateUploadV1ConstructionRejectCase `json:"construction_reject_cases"`
}

func ParsePrivateUploadV1File

func ParsePrivateUploadV1File(data []byte) (*PrivateUploadV1File, error)

func PrivateUploadV1

func PrivateUploadV1() (*PrivateUploadV1File, error)

PrivateUploadV1 strictly parses and verifies the private upload and refresh application-signing artifact.

type PrivateUploadV1FixtureKey

type PrivateUploadV1FixtureKey struct {
	Warning                  string `json:"warning"`
	PrivateKeyPKCS8DERB64URL string `json:"private_key_pkcs8_der_b64url"`
	PublicKeyDERB64URL       string `json:"public_key_der_b64url"`
}

type PrivateUploadV1OperationContract

type PrivateUploadV1OperationContract struct {
	Method                   string   `json:"method"`
	SigningDomainASCII       string   `json:"signing_domain_ascii"`
	SigningDomainSeparator   string   `json:"signing_domain_separator_hex"`
	FieldOrder               []string `json:"field_order"`
	StableRequestDomainASCII string   `json:"stable_request_domain_ascii"`
	StableRequestFieldOrder  []string `json:"stable_request_field_order"`
	BodyEncoding             string   `json:"body_encoding"`
	BodyKeyOrder             []string `json:"body_key_order,omitempty"`
	BodyWhitespaceRule       string   `json:"body_whitespace_rule,omitempty"`
	BodyStringEscapingRule   string   `json:"body_string_escaping_rule,omitempty"`
	MediaTypeRule            string   `json:"media_type_rule,omitempty"`
	MediaTypeSubtypeRule     string   `json:"media_type_subtype_rule,omitempty"`
	FilenameEncoding         string   `json:"filename_encoding,omitempty"`
	DisplayFilenameRule      string   `json:"display_filename_rule,omitempty"`
	ContentTypeRule          string   `json:"content_type_rule"`
	RequiredHeaders          []string `json:"required_headers"`
	ForbiddenHeaders         []string `json:"forbidden_headers"`
}

type PrivateUploadV1RefreshGolden

type PrivateUploadV1RefreshGolden struct {
	Method                    string `json:"method"`
	Authority                 string `json:"authority"`
	Path                      string `json:"path"`
	TimestampUnixDecimal      string `json:"timestamp_unix_decimal"`
	Nonce                     string `json:"nonce"`
	ClientID                  string `json:"client_id"`
	KeyID                     string `json:"key_id"`
	BodyHex                   string `json:"body_hex"`
	BodySHA256Hex             string `json:"body_sha256_hex"`
	BodyLengthDecimal         string `json:"body_length_decimal"`
	ContentDigestHeader       string `json:"content_digest_header"`
	ContentType               string `json:"content_type"`
	UploadHandle              string `json:"upload_handle"`
	MaxBatchSizeDecimal       string `json:"max_batch_size_decimal"`
	MaxLinkTTLSecondsDecimal  string `json:"max_link_ttl_seconds_decimal"`
	AuthorityExpiresAt        string `json:"authority_expires_at"`
	UploadRequestID           string `json:"upload_request_id"`
	CanonicalHex              string `json:"canonical_hex"`
	SigningDigestHex          string `json:"signing_digest_hex"`
	SignatureDERB64URL        string `json:"signature_der_b64url"`
	StableRequestCanonicalHex string `json:"stable_request_canonical_hex"`
	StableRequestDigestHex    string `json:"stable_request_digest_hex"`
}

type PrivateUploadV1RejectCase

type PrivateUploadV1RejectCase struct {
	Name        string                          `json:"name"`
	Base        string                          `json:"base"`
	Mutations   []PrivateUploadV1RejectMutation `json:"mutations"`
	Outcome     string                          `json:"outcome"`
	RejectClass string                          `json:"reject_class"`
	Status      int                             `json:"status"`
	ErrorCode   string                          `json:"error_code"`
}

type PrivateUploadV1RejectMutation

type PrivateUploadV1RejectMutation struct {
	Target string `json:"target"`
	Field  string `json:"field"`
	Value  string `json:"value"`
}

type PrivateUploadV1UploadGolden

type PrivateUploadV1UploadGolden struct {
	Method                    string `json:"method"`
	Authority                 string `json:"authority"`
	Path                      string `json:"path"`
	TimestampUnixDecimal      string `json:"timestamp_unix_decimal"`
	Nonce                     string `json:"nonce"`
	ClientID                  string `json:"client_id"`
	KeyID                     string `json:"key_id"`
	AudienceKeyID             string `json:"audience_key_id"`
	BodyHex                   string `json:"body_hex"`
	BodySHA256Hex             string `json:"body_sha256_hex"`
	BodyLengthDecimal         string `json:"body_length_decimal"`
	ContentDigestHeader       string `json:"content_digest_header"`
	MediaType                 string `json:"media_type"`
	ContentType               string `json:"content_type"`
	DisplayFilenameUTF8       string `json:"display_filename_utf8"`
	FilenameB64URL            string `json:"filename_b64url"`
	AuthorityExpiresAt        string `json:"authority_expires_at"`
	UploadRequestID           string `json:"upload_request_id"`
	CanonicalHex              string `json:"canonical_hex"`
	SigningDigestHex          string `json:"signing_digest_hex"`
	SignatureDERB64URL        string `json:"signature_der_b64url"`
	StableRequestCanonicalHex string `json:"stable_request_canonical_hex"`
	StableRequestDigestHex    string `json:"stable_request_digest_hex"`
}

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 TargetPathCase

type TargetPathCase struct {
	Name          string  `json:"name"`
	Present       bool    `json:"present"`
	Value         *string `json:"value,omitempty"`
	Outcome       string  `json:"outcome"`
	RejectClass   string  `json:"reject_class,omitempty"`
	OpenSupported *bool   `json:"open_supported,omitempty"`
	// contains filtered or unexported fields
}

TargetPathCase is one direct public-SDK option input. Present distinguishes omission from an explicit empty string. OpenSupported is required only for accepted cases. Every accepted canonical value is safe to open.

func (*TargetPathCase) UnmarshalJSON

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

UnmarshalJSON retains optional-field presence and requires present itself. This keeps omission different from explicit null, empty, and false values.

type TargetPathContract

type TargetPathContract struct {
	WireField               string   `json:"wire_field"`
	MaxBytes                int      `json:"max_bytes"`
	OmittedSemantics        string   `json:"omitted_semantics"`
	ExplicitEmptySemantics  string   `json:"explicit_empty_semantics"`
	AcceptedCharacterSet    string   `json:"accepted_character_set"`
	AllowedASCII            string   `json:"allowed_ascii"`
	ForbiddenPathASCII      string   `json:"forbidden_path_ascii"`
	QueryDelimiter          string   `json:"query_delimiter"`
	ValidationOrder         []string `json:"validation_order"`
	AcceptedValueHandling   string   `json:"accepted_value_handling"`
	PercentEncodingHandling string   `json:"percent_encoding_handling"`
}

TargetPathContract freezes the stable wire and runtime rules that every consumer must apply without normalization.

type TargetPathV1File

type TargetPathV1File struct {
	Artifact      string             `json:"artifact"`
	SchemaVersion int                `json:"schema_version"`
	Description   string             `json:"description"`
	Contract      TargetPathContract `json:"contract"`
	Cases         []TargetPathCase   `json:"cases"`
}

TargetPathV1File is the language-neutral target_path mint contract shared by service and SDK consumers.

func ParseTargetPathV1File

func ParseTargetPathV1File(data []byte) (*TargetPathV1File, error)

ParseTargetPathV1File strictly parses and independently re-derives every case.

func TargetPathV1

func TargetPathV1() (*TargetPathV1File, error)

TargetPathV1 strictly parses the embedded target_path contract artifact.

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.