helpers

func AppendSignature ¶

func AppendSignature(ctx context.Context, req *http.Request, body []byte, signer Signer, opts SignOptions) error

AppendSignature chains a new signature onto req WITHOUT disturbing any existing one (forwarding chain). It preserves an existing Content-Digest (only setting it when missing), binds Authorization, finds the next label sig(N+1) and predecessor sigN, builds the chain-linked covered set (the FORA base plus "signature";key="sigN" so sig(N+1) commits to its predecessor), asks the Signer to sign, and APPENDS to the Signature-Input / Signature headers. Appending to a request with no existing signatures produces a sig1 byte-for-byte identical to SignRequest — single-sig is the N=1 case.

func ApplyScopes ¶

func ApplyScopes(r *forav1.Requester, scopes ...string)

ApplyScopes sets the requester's held scopes (normalized). It is how the caller supplies the entitlements it holds for a discover/resolve call.

func CanonicalAcceptanceBytes ¶

func CanonicalAcceptanceBytes(offer *forav1.Offer, requester *forav1.Requester, idempotencyKey string) ([]byte, error)

CanonicalAcceptanceBytes returns the exact canonical byte sequence an agent's offer acceptance covers: the accepted Offer.signature (which transitively binds the offer's pricing, terms, expiry, and issuing Exchange), plus the requester identity and idempotency key of the ENCLOSING execute request — in batch mode both come from the TransactionRequest, never from the per-item TransactionItem, which carries neither. The returned bytes are byte-identical to what SignOfferAcceptance signs and VerifyOfferAcceptance verifies over — persist them to re-verify an acceptance verbatim, independent of how the canonical form later evolves.

Re-verification also needs the persisted AgentAcceptance.signature and the signer's trusted public key: these bytes are the signed message, necessary but not by themselves sufficient. A passing signature proves only that the key holder signed THESE bytes, so a caller weighing them as evidence must also parse them and match their content against the transaction in question.

The canonical form is RFC 8785 JCS over canonical proto-JSON — JCS(protojson(AgentAcceptancePayload)) — the same definition the offer signature uses, stated normatively on Offer.signature in fora.proto: snake_case proto field names, enums as name strings, unpopulated fields omitted. AgentAcceptancePayload carries no signature fields, so the clear-then-render step reduces to a plain render. Any language (Go/TS/Python) reproduces the exact bytes from that definition, without a protobuf binary codec.

The payload is built here from the four scalars rather than taken from the caller, so it cannot carry the unknown fields CanonicalOfferBytes has to refuse; only the values read off the offer and requester reach the signed bytes.

Unpopulated fields are OMITTED before JCS — EVERY empty string field, not just the domain: the bytes for an empty requester id are not the bytes for any populated one. A port that assembles this object by hand instead of rendering the proto must reproduce that omission per field, or it signs bytes this function never produces.

Fails closed on a nil offer, a nil requester, or an unsigned offer (empty Offer.signature) — an empty anchor would let the acceptance float free of any concrete offer.

func CanonicalOfferBytes ¶

func CanonicalOfferBytes(offer *forav1.Offer) ([]byte, error)

CanonicalOfferBytes returns the exact canonical byte sequence an Offer's signature is computed over: the ENTIRE Offer (pricing, terms, expires_at, …) with ONLY the signature and signature_algorithm fields cleared, per fora.proto Offer.signature. The returned bytes are byte-identical to what SignOffer signs and VerifyOffer verifies over — persist them to re-verify an Offer signature verbatim, independent of how the canonical form, or the Offer message, later evolves.

Re-verification also needs the persisted Offer.signature and the signer's trusted public key: these bytes are the signed message, necessary but not by themselves sufficient. A passing signature proves only that the key holder signed THESE bytes, so a caller weighing them as evidence must also parse them and match their content against the transaction in question.

The canonical form is RFC 8785 JCS over canonical proto-JSON — JCS(protojson(offer with sig cleared)) — rendered under the option set the Offer.signature comment in fora.proto defines normatively: snake_case proto field names, enums as name strings, unpopulated fields omitted. That definition, not this implementation, is what lets any language (Go/TS/Python) reproduce the exact signed bytes without a protobuf binary codec.

expires_at is covered (only signature/signature_algorithm are cleared), so a relaying Broker cannot extend or shorten a signed offer's TTL under an otherwise-valid signature.

An Offer carrying UNKNOWN fields at ANY depth is REFUSED (ErrUnknownFields) rather than rendered — proto-JSON emits only what the schema defines, so those bytes would silently drop the unknown content. The rule, and the depths it reaches, are stated once in the fora.proto Offer.signature comment; it is not restated here. VerifyOffer surfaces the refusal wrapped in ErrOfferSignatureInvalid, since a message that arrived carrying extra bytes is a tampered Offer, not an internal fault.

func CanonicalRequestAcceptanceBytes ¶

func CanonicalRequestAcceptanceBytes(payload *forav1.AgentRequestAcceptancePayload) ([]byte, error)

CanonicalRequestAcceptanceBytes returns the exact JCS(protojson(...)) bytes covered by an AgentRequestAcceptance signature.

func CanonicalRestrictionToken ¶

func CanonicalRestrictionToken(kind forav1.RestrictionKind, token string) string

CanonicalRestrictionToken returns the canonical form of a restriction token on an axis: RFC 8259 whitespace trimmed, ASCII case folded (lower for FUNCTION and USER_TYPE, upper for GEOGRAPHY) and, where the axis authors aliases, the alias resolved to its registered token. OTHER and any unknown axis carry custom, registry-less tokens and are returned unchanged. Applying it twice is a fixed point, which is what makes NormalizeLicenseTerm idempotent.

func CanonicalizeMoney ¶

func CanonicalizeMoney(s string) (string, error)

CanonicalizeMoney normalizes a wire decimal string to its canonical form (parse then format). It is the convenience used when echoing a money value back onto the wire without doing arithmetic.

func CatalogRejectionDetail ¶

func CatalogRejectionDetail(domain, message string, reason forav1.CatalogRejectionReason) *forav1.ErrorDetail

CatalogRejectionDetail builds an ErrorDetail carrying a typed CatalogRejectionReason.

func CheckWellKnownManifestVersion ¶

func CheckWellKnownManifestVersion(ver string) error

CheckWellKnownManifestVersion applies the receive-side rule for WellKnownManifest.ver. It accepts a version whose MAJOR equals the major of WellKnownManifestVersion, whatever the MINOR — a minor revision of the manifest is additive by definition, so a reader ignores members it does not know and keeps reading. It refuses an unrecognised major, a value that is not of the form MAJOR.MINOR (two runs of ASCII digits joined by one dot), and the empty string, which is how an absent field arrives.

Absent is refused rather than tolerated: the field is required by the wire shape, and a document with no version is one whose layout the reader cannot classify. Why the gate runs before any other member is read, and fails closed, is stated once on WellKnownManifest.ver in the proto.

The returned error wraps ErrManifestVersionRefused and names the value found, so an operator can tell a version mismatch from a network failure. The echo is clipped to maxEchoedVer bytes: the document body is read up to 1 MiB and a refusal is never cached, so an unclipped echo would let a hostile origin size every error a resolve produces. The function is pure: the same input always yields the same verdict, and the three SDK languages pin that verdict to a shared corpus.

func CompileRegistrationSchema ¶

func CompileRegistrationSchema(raw []byte) (*RegistrationSchema, SchemaVerdict)

CompileRegistrationSchema checks a published data_schema against every rule above and compiles it.

raw is the schema AS SERVED — the exact UTF-8 bytes of the data_schema member in fora.json — because MaxRegistrationSchemaBytes is defined over those bytes.

The schema is non-nil only on SchemaAccepted. There is no error return: every way this can fail is a property of the schema, and both callers need to know WHICH, not merely that something went wrong. They read the same refusal differently, and that difference is the contract:

A CLIENT pre-checking a payload treats any non-accepted verdict as "do not
pre-check" and sends anyway. The field's contract says so for an oversized
schema, and it generalises: a local check that cannot run must not become a
local veto, because the Exchange's own enforcement is the deciding one and a
client that refused here would block a payload the Exchange would have taken.

An EXCHANGE compiling its OWN configured schema treats the same verdict as an
operator misconfiguration of this deployment. Nothing about a third party is
involved, and serving a manifest advertising a schema it cannot itself enforce
is the one outcome it must not reach.

func ContentDigest ¶

func ContentDigest(body []byte) string

ContentDigest returns the RFC 9530 Content-Digest header value for body: sha-256=:<base64(SHA-256(body))>:.

func DisputeFailureDetail ¶

func DisputeFailureDetail(domain, message string, reason forav1.DisputeFailureReason) *forav1.ErrorDetail

DisputeFailureDetail builds an ErrorDetail carrying a typed DisputeFailureReason.

func DomainVerificationFailureDetail ¶

func DomainVerificationFailureDetail(domain, message string, reason forav1.DomainVerificationFailureReason) *forav1.ErrorDetail

DomainVerificationFailureDetail builds an ErrorDetail carrying a typed DomainVerificationFailureReason.

func FormatMoney ¶

func FormatMoney(d decimal.Decimal) (string, error)

FormatMoney renders an exact decimal as the canonical wire string: no sign, no exponent, and insignificant trailing fractional zeros stripped ("0.050" -> "0.05", "1.00" -> "1", "10" -> "10"). A negative value is rejected — FORA money is non-negative. The result always satisfies the wire pattern.

func HashURL ¶

func HashURL(signed string) []byte

HashURL returns the SHA-256 digest of a signed URL (the transaction_log.signed_url_hash value, 32 bytes).

func HostAnchored ¶

func HostAnchored(anchor, candidate string) (bool, error)

HostAnchored reports whether candidate is anchored to anchor — the same host and port, or a subdomain of that host on that port. Either side may be a bare domain, a host:port pair, or a full URL; a reference that does not parse is returned as an error, which callers treat as "not anchored".

The use is checking a value a remote document supplied against the host that served that document: it may point at itself or at one of its own subdomains, and nothing else. Without it, a host could redirect a signed request — or a revocation poll — to an unrelated third-party address that a dial-time address guard would happily allow, because the address is perfectly public.

The PORT is part of the comparison. What is being anchored is a place a signed call is sent, and a different port is a different service — one the party that published the anchor need not control. An Exchange reachable on a non-default port says so on both sides: the port belongs in the value the offer names as much as in the endpoint the manifest advertises.

A DEFAULT port and its omission are the same port, so https://x, https://x:443 and x all anchor to one another. url.Parse does not materialize an implicit port, and refusing an operator who merely wrote :443 out in full would be a spelling check wearing a security check's clothes.

The SCHEME is still not compared. Whether a leg may run in the clear is the guarded transport's decision, made in one place from one flag. Its only job here is choosing which port counts as the default — and a side that NAMED no scheme borrows the other's for that purpose, rather than being assumed to mean https.

That last part is load-bearing, not a nicety. Both anchors in this SDK arrive schemeless: a WBA directory's authority and an Offer.exchange host are bare host[:port] values. Assuming https for them meant an anchor of "a.example:80" kept its port (80 is not https's default) while the candidate "http://a.example:80" folded it away — the same authority reaching two answers, which silently un-anchored every plaintext directory that spelled :80 in full.

func HostOf ¶

func HostOf(ref string) (string, error)

HostOf extracts the host (including any port) from a bare domain, a host:port pair, or a full URL. A ref with no scheme is parsed as though it carried https, since a bare domain is otherwise indistinguishable from a path.

func IsBareDomain ¶

func IsBareDomain(v string) bool

IsBareDomain reports whether v is a bare domain of the shape the wire admits.

This is NOT IsBareHost, and the two are deliberately kept apart because they answer different questions. IsBareHost asks whether a value is safe to concatenate into a URL — a structural question, answered by round-tripping the value through a URL parse, which accepts anything a host may hold. IsBareDomain asks whether a value is the SHAPE THE CONTRACT ADMITS, which is narrower: a trailing root dot, a leading or trailing hyphen, an underscore and a bracketed IPv6 literal are all usable hosts and none of them is a value the wire rule accepts. A caller vetting a value it is about to dial wants the first; a caller vetting a value that arrived in a message wants this one.

The length is checked FIRST, so the work stays bounded on hostile input. This is insurance rather than a fix for a known blowup: the pattern is unambiguous — every repetition is anchored by a literal dot no label class can consume — so it cannot backtrack catastrophically, and the cost of matching it is linear in all three languages. Bounding that cost is still worth the one comparison it takes, since the Python and TypeScript ports run it on backtracking engines where linear work on an unbounded string is a caller's choice to make, not ours. Doing it in this order costs nothing in agreement, even though the three languages count length in different units — a value whose byte, code-point and UTF-16 counts disagree contains something outside ASCII, and the pattern refuses it whichever check runs first.

func IsBareHost ¶

func IsBareHost(ref string) (bool, error)

IsBareHost reports whether ref is EXACTLY a host — nothing a URL could carry besides the authority. It answers false for a ref with a scheme, userinfo, a path, a query, or a fragment, because HostOf had to strip something to reach the host. A port is NOT a strip: "exchange.example:8443" is a bare host, and the well-known resolver concatenates host-with-port unchanged.

It exists for the callers that hand a network-supplied domain to code which builds a URL by concatenation. There, narrowing a rich reference to its host is the wrong repair: the value was never a domain, and accepting it silently means the far side chose the path that gets fetched, not just the host it is fetched from. Comparing against the extracted host is what makes the rejection structural, rather than a blocklist of the separators anyone thought to name.

func IsSafeSchemaPattern ¶

func IsSafeSchemaPattern(p string) bool

IsSafeSchemaPattern reports whether a `pattern` uses only constructs all three SDK languages express identically.

Draft 2020-12 patterns are ECMA-262, and the three SDKs run three different engines over them: Go's RE2, JavaScript's RegExp, and Python's re. The three intersect on far less than any one of them accepts, and BOTH directions of the gap are a bug this face exists to close. Lookaround, atomic groups and backreferences are legal ECMA and refused by RE2, so a schema using them compiles in two SDKs and fails in the third. Inline flags, Unicode property classes, text anchors and POSIX bracket names run the other way — RE2 (or Python) takes them and JavaScript does not, or takes them to mean something else. The second kind is the more dangerous, because nothing errors: two SDKs both compile the pattern and then disagree about which payloads match it.

So the admitted alphabet is the intersection, expressed as six rules:

1. an escape names a portable class, control character, \xHH, or a metacharacter standing for itself — see portableEscapes, an ALLOWLIST;
2. a group opens with `(` or `(?:` and nothing else;
3. `[:` does not appear inside a bracket expression, at any position — it is a POSIX class name to RE2 and the literal characters to JavaScript;
4. a bracket expression closes, and does not open with `]`;
5. a counted repeat does not exceed maxPortableRepeat;
6. no quantified group has a body that can itself repeat or branch.

Rule 6 is aimed at catastrophic backtracking SEPARATELY and deliberately, because nothing in rules 1-5 covers it: `(a+)+` needs neither lookaround nor a backreference and sits comfortably inside the alphabet. See hasNestedQuantifier.

The scan is syntactic and deliberately a little conservative. It tracks escaping, so a literal `\(` is not read as a group, and it tracks bracket-expression interiors, because the constructs above mean different things inside a class than outside one. Over-refusing costs an author a rewrite; under-refusing costs the SDKs the agreement they exist to provide.

func KnownRestrictionToken ¶

func KnownRestrictionToken(kind forav1.RestrictionKind, token string) bool

KnownRestrictionToken reports whether an already-canonical token is registered on its axis. GEOGRAPHY registers only the non-ISO specials and admits any two-uppercase-letter ISO 3166-1 alpha-2 code structurally; OTHER and any unknown axis carry no registry and are never known.

func NewContext ¶

func NewContext(ctx context.Context, v *VerifiedRequest) context.Context

NewContext returns a copy of ctx carrying v under the single verified-request slot. Production code MUST NOT call this outside the verifying transport.

func NewIdempotencyKey ¶

func NewIdempotencyKey() (string, error)

NewIdempotencyKey returns a fresh cryptographically-random, URL-safe idempotency key. Use it once per logical operation; reuse a stored key only to deliberately replay.

func NewMultisigContext ¶

func NewMultisigContext(ctx context.Context, sigs []VerifiedRequest) context.Context

NewMultisigContext returns a copy of ctx carrying all verified signatures (sig1..sigN, in chain order). Production code MUST NOT call this outside the verifying transport.

func NormalizeLicenseTerm ¶

func NormalizeLicenseTerm(term *forav1.LicenseTerm)

NormalizeLicenseTerm rewrites the term's restriction tokens to their canonical form in place, on every axis that carries a canonicalisation rule. It touches nothing else — Pricing.unit and Quota.metric are exact registry values, scopes are matched verbatim — and is nil-safe and idempotent. Run it before ValidateLicenseTerm, whose checks read canonical tokens — all but the disjointness check, which folds what it compares and so reaches the same verdict on either form.

func NormalizeResourceEntry ¶

func NormalizeResourceEntry(entry *forav1.ResourceEntry)

NormalizeResourceEntry applies NormalizeLicenseTerm to every term of the entry, in place. Nil-safe.

func NormalizeScopes ¶

func NormalizeScopes(scopes []string) []string

NormalizeScopes returns scopes with empty entries dropped, duplicates removed, and a stable (sorted) order — so two callers supplying the same set produce identical bytes on the wire.

func ParseMoney ¶

func ParseMoney(s string) (decimal.Decimal, error)

ParseMoney parses a canonical wire decimal string into an exact decimal. It rejects the empty string (ErrEmptyMoney) and any value the wire pattern forbids — signs, exponents, a leading dot — so a value that would fail the server's protovalidate never silently parses here.

func Reason ¶

func Reason(detail *forav1.ErrorDetail) any

Reason returns the active typed reason enum from detail — one of forav1.DenialReason, RetrievalAuthFailureReason, CatalogRejectionReason, RegistrationFailureReason, DisputeFailureReason, DomainVerificationFailureReason, or UsageReportRejectionReason — or nil when no reason is set. Callers type-switch on the result to branch on the failure, never on a string.

func RedactURL ¶

func RedactURL(raw string) string

RedactURL reduces a signed URL to scheme://host/path, for a value headed somewhere more durable than the caller who already holds it — a log line, or an error an operator will read.

url.URL.Redacted() is NOT the tool for this. It masks userinfo passwords, and a delivery URL carries its credential in the QUERY: sig, kid, exp and agent_id. Redacted() would pass the signature through untouched while reading like a redaction, which is worse than not redacting at all.

An unparseable input yields "" rather than the original: a value that could not be sanitized is not one to emit.

func RegistrationFailureDetail ¶

func RegistrationFailureDetail(domain, message string, reason forav1.RegistrationFailureReason, fieldErrors ...*forav1.RegistrationFieldError) *forav1.ErrorDetail

RegistrationFailureDetail builds an ErrorDetail carrying a typed RegistrationFailureReason, plus the offending registration_data members when the reason is REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA.

fieldErrors is variadic rather than a fourth required parameter so the six reasons that carry no per-member detail keep calling this with three arguments. It is the one *Detail builder that reaches past the reason enum: the schema refusal is useless without naming what failed, whereas the sibling detail lists (TransactionDenial.restriction_mismatches, CatalogRejection.rejected_paths) are still caller-set post-construction. Passing field errors with any other reason is a caller error — the field's contract says the list is empty otherwise.

func RequestAcceptancePayload ¶

func RequestAcceptancePayload(req *forav1.TransactionRequest) (*forav1.AgentRequestAcceptancePayload, error)

RequestAcceptancePayload builds the complete ordered request-set payload an agent signs before any Broker fan-out.

func RetrievalAuthFailureDetail ¶

func RetrievalAuthFailureDetail(domain, message string, reason forav1.RetrievalAuthFailureReason) *forav1.ErrorDetail

RetrievalAuthFailureDetail builds an ErrorDetail carrying a typed RetrievalAuthFailureReason.

func RetrievalAuthFailureReasonFromToken ¶

func RetrievalAuthFailureReasonFromToken(token string) (forav1.RetrievalAuthFailureReason, bool)

RetrievalAuthFailureReasonFromToken resolves a delivery edge's refusal token to its typed RetrievalAuthFailureReason. The second result is false for a token this SDK does not recognise or cannot attribute unambiguously — the caller then falls back to its own failure class, which it owns, rather than promoting a value the edge did not actually state.

Fail-closed by construction: the token arrives in a body written by the host the fetch just went to, so an unrecognised value is never surfaced as a typed protocol reason.

func ScopesSubset ¶

func ScopesSubset(sub, super []string) bool

ScopesSubset reports whether every scope in sub is present in super. It is the delegation-attenuation rule (Delegation.scopes MUST be a subset of the principal's granted scopes): use it to validate a delegation before relying on it, so an over-broad delegation is caught at the SDK boundary.

func SharedValidator ¶

func SharedValidator() (protovalidate.Validator, error)

SharedValidator returns the process-wide protovalidate.Validator that Validate wraps — built once and reused (compiling its CEL is expensive). The L2 validate interceptor injects it into connectrpc.com/validate so the interceptor and the L1 client-side pre-check share one engine, giving zero rule drift by construction.

func SignOffer ¶

func SignOffer(priv ed25519.PrivateKey, offer *forav1.Offer) (string, error)

SignOffer signs the canonical serialization of offer with priv and returns the hex-encoded Ed25519 signature for the Offer.signature field.

func SignOfferAcceptance ¶

func SignOfferAcceptance(priv ed25519.PrivateKey, offer *forav1.Offer, requester *forav1.Requester, idempotencyKey string) (string, error)

SignOfferAcceptance signs the canonical acceptance payload for the accepted offer with priv and returns the hex-encoded Ed25519 signature for the AgentAcceptance.signature field. requester and idempotencyKey come from the enclosing execute request.

func SignOfferAcceptanceWith ¶

func SignOfferAcceptanceWith(ctx context.Context, signer Signer, offer *forav1.Offer, requester *forav1.Requester, idempotencyKey string) (string, error)

SignOfferAcceptanceWith signs the canonical acceptance payload through an injected Signer, so an application whose key lives in a KMS or an HSM can produce an acceptance without ever handing the key over. It is the form the SDK's own client uses; SignOfferAcceptance above is the direct-key form for a caller that already holds the bytes. Both cover the identical payload from CanonicalAcceptanceBytes, so the two are interchangeable on the wire.

The acceptance is signed with the same key that signs the caller's requests: its thumbprint becomes the delivery URL's agent_id, which is what the edge later requires proof of possession of.

func SignRequest ¶

func SignRequest(ctx context.Context, req *http.Request, body []byte, signer Signer, opts SignOptions) error

SignRequest signs req with the FORA covered-component set and mutates it in place: it sets Content-Digest over body, binds the Authorization header (even when empty, so a later token injection is detected), builds the RFC 9421 signature base, asks the Signer to sign it, and writes the Signature-Input and Signature headers. body must be the exact bytes that will be transmitted.

func SignRequestAcceptance ¶

func SignRequestAcceptance(priv ed25519.PrivateKey, req *forav1.TransactionRequest) (*forav1.AgentRequestAcceptance, error)

SignRequestAcceptance signs req's complete ordered request set with priv.

func SignRequestAcceptanceWith ¶

func SignRequestAcceptanceWith(ctx context.Context, signer Signer, req *forav1.TransactionRequest) (*forav1.AgentRequestAcceptance, error)

SignRequestAcceptanceWith is SignRequestAcceptance for a KMS/HSM-backed Signer.

func SignatureAgentFromContext ¶

func SignatureAgentFromContext(ctx context.Context) string

SignatureAgentFromContext returns the Signature-Agent value threaded by the resolved verify entrypoints, or "" when none was set.

func Thumbprint ¶

func Thumbprint(pub ed25519.PublicKey) (string, error)

Thumbprint returns the RFC 7638 JWK Thumbprint of pub as a base64url-no-pad string. It returns ErrInvalidKeyLength when pub is not a 32-byte Ed25519 public key.

func ThumbprintBytes ¶

func ThumbprintBytes(pub ed25519.PublicKey) ([32]byte, error)

ThumbprintBytes returns the raw 32-byte SHA-256 digest underlying the thumbprint. The digest is what the transaction_log.agent_identity_hash BYTEA column stores (ADR-013 17.6); base64url-no-pad of it is the wire form.

func TransactionDenialDetail ¶

func TransactionDenialDetail(domain, message string, reason forav1.DenialReason) *forav1.ErrorDetail

TransactionDenialDetail builds an ErrorDetail carrying a typed DenialReason.

func UsageReportRejectionDetail ¶

func UsageReportRejectionDetail(domain, message string, reason forav1.UsageReportRejectionReason) *forav1.ErrorDetail

UsageReportRejectionDetail builds an ErrorDetail carrying a typed UsageReportRejectionReason.

func Validate ¶

func Validate(msg proto.Message) error

Validate checks msg against its protovalidate rules. It returns nil when msg is valid and a *protovalidate.ValidationError (carrying the violated rule ids) otherwise. The validator is built once and reused (compiling its CEL is expensive); it is safe for concurrent use.

func ValidateIdempotencyKey ¶

func ValidateIdempotencyKey(key string) error

ValidateIdempotencyKey enforces the protocol's min_len=1 constraint, so the SDK rejects an empty key before the server does.

func ValidationRuleIDs ¶

func ValidationRuleIDs(err error) []string

ValidationRuleIDs extracts the violated protovalidate rule ids from an error returned by Validate (nil/empty when err is not a validation error). Callers use it to branch on or log which constraint failed.

func VerifyOffer ¶

func VerifyOffer(offer *forav1.Offer, signatureHex string, pub ed25519.PublicKey) error

VerifyOffer verifies signatureHex against offer using pub. It checks signature integrity only; the expires-at-in-the-past policy ("MUST reject an offer whose expires_at is in the past") is enforced by the caller's {verified, rejected} selection layer, not here.

func VerifyOfferAcceptance ¶

func VerifyOfferAcceptance(offer *forav1.Offer, requester *forav1.Requester, idempotencyKey, signatureHex string, pub ed25519.PublicKey) error

VerifyOfferAcceptance verifies signatureHex (an AgentAcceptance.signature) against the canonical acceptance payload for the offer, using pub. It returns ErrAcceptanceSignatureInvalid on any mismatch (wrong key or tampered binding).

func VerifyPresentedOffer ¶

func VerifyPresentedOffer(offer *forav1.Offer, exchangePub ed25519.PublicKey, now time.Time) error

VerifyPresentedOffer is the stateless {verified, rejected} primitive for a reflected Offer: the agent presents the WHOLE signed Offer and the verifier checks it against its own key over the exact presented bytes — no reconstruct-from-catalog. It returns nil only when BOTH hold, in this order:

1. offer.signature is a valid Ed25519 signature over the canonical Offer (expires_at included) under exchangePub — else ErrOfferSignatureInvalid.
2. the signed expires_at is at or after now — else ErrOfferExpired.

Signature is checked first so freshness never leaks for a tampered offer. Freshness uses the injected now (never the wall clock); expires_at is inclusive, so now == expires_at is still valid. An offer with NO expires_at is rejected fail-closed: FORA offers are minted at discovery as now+TTL, so a missing expiry is a forever-token and unsafe to honor.

func VerifyRequestAcceptance ¶

func VerifyRequestAcceptance(req *forav1.TransactionRequest, acceptance *forav1.AgentRequestAcceptance, pub ed25519.PublicKey) ([]byte, error)

VerifyRequestAcceptance verifies the signature and the shared request envelope fields. It deliberately does not apply a fan-out projection rule; an Exchange must call VerifyRequestAcceptanceProjection instead.

func VerifyRequestAcceptanceProjection ¶

func VerifyRequestAcceptanceProjection(req *forav1.TransactionRequest, acceptance *forav1.AgentRequestAcceptance, exchange string, pub ed25519.PublicKey) ([]byte, error)

VerifyRequestAcceptanceProjection additionally proves that req.items is the complete ordered projection of the signed original set addressed to exchange.

func WithSignatureAgent ¶

func WithSignatureAgent(ctx context.Context, dir string) context.Context

WithSignatureAgent returns a copy of ctx carrying the request's Signature-Agent value (the signer's WBA key-directory URL). The resolved verify entrypoints thread it before per-signature resolution so a KeyResolver can fetch keys from the directory the signature commits to.