content

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 26, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// BlockSize 是一个完整内容块的字节数(256 KiB)。
	BlockSize uint64 = masterseed.BlockSize
	// DigestSize 是 seed 摘要的字节宽度。
	DigestSize = masterseed.DigestSize
)

BlockSize 与 DigestSize 是 MasterSeed 依赖库拥有的协议常量;本包仅按 协议引用它们。

View Source
const MaxContentBatchItems = 64

MaxContentBatchItems 是一条 003 授权或一个 004 交付包允许携带的内容条目数。

该上限是协议真值:content_hashes 与 content_payloads 子 CBOR 数组长度必须 在 1 到 64 之间。超过 64 个内容时,调用方必须拆成多个连续付款序号的 003 批次;SDK 不做自动拆分、截断或去重。

View Source
const MaxContentPayloadsCBORBytes = MaxContentBatchItems*(int(masterseed.BlockSize)+9) + 9

MaxContentPayloadsCBORBytes 是 004 中 content_payloads_cbor 子文档的最大字节数。

公式为 MaxContentBatchItems*(masterseed.BlockSize+9)+9:每个最大长度的 bstr 条目占用 BlockSize 字节加最多 9 字节的 CBOR 头部,外加最多 9 字节的 数组头部。在解码子数组之前先按该上限拒绝超长输入,防止单个恶意 bstr 绕过 数组数量限制。它是 SDK 的协议上限,不是部署层的 HTTP body 或消息配额; 应用仍必须设置不高于自身可承受能力的资源上限。

View Source
const MaxQuoteFileSize uint64 = MaxQuoteSeedBlocks * BlockSize

MaxQuoteFileSize is the largest file a quote can describe while the seed is delivered in one BitFS payload.

MaxQuoteSeedBlocks is the greatest block count whose seed fits the BitFS payload limit. A seed contains one 32-byte hash for each block.

Variables

This section is empty.

Functions

func CheckContentRequestTiming

func CheckContentRequestTiming(authorization *PaymentAuthorization, quoteTerms *FileQuoteTerms, at time.Time) error

CheckContentRequestTiming 应用 003 请求的两项显式时间比较:报价过期与交付 截止。at 是调用方显式传入的本操作唯一时间事实。

func ContentHashesPriceSatoshis

func ContentHashesPriceSatoshis(ctx context.Context, terms *FileQuoteTerms, contentHashes [][]byte, seed []byte) (uint64, error)

ContentHashesPriceSatoshis derives the aggregate buyer-signed amount for an ordered batch of content hashes against the verified quote. Each hash equal to the quote SeedHash is priced at SeedPriceSatoshis; every other hash must be found in the verified seed and is priced at its position's protocol expected length (full blocks at FullBlockPriceSatoshis, tail blocks with the proportional round-up and the specified 10% seller allowance). Duplicate block positions behind one hash are charged once; matches with conflicting expected lengths reject the batch. The total is accumulated with checked addition so any overflow fails before signing instead of wrapping.

func DecodeContentDeliveryDocument

func DecodeContentDeliveryDocument(data []byte) (protocol.PaymentAuthorizationID, error)

DecodeContentDeliveryDocument strictly decodes a content_delivery_cbor and returns the payment authorization ID it commits to.

func DecodeContentHashes

func DecodeContentHashes(raw []byte) ([][]byte, error)

DecodeContentHashes strictly decodes the content_hashes child document. It rejects indefinite lengths, tags, trailing data, non-canonical encodings, wrong counts, wrong hash widths, duplicates, and reordering attempts by requiring byte equality with the deterministic re-encoding. The returned slices are deep copies owned by the caller.

func DecodeContentPayloads

func DecodeContentPayloads(raw []byte) ([][]byte, error)

DecodeContentPayloads strictly decodes the content_payloads child document with the same canonicality rules as DecodeContentHashes, plus per-item non-empty and maximum-length checks. Inputs above MaxContentPayloadsCBORBytes are rejected before decoding so a hostile length cannot bypass the item count limit. The returned slices are deep copies owned by the caller.

func DecodeSupportedArbiterPublicKeys

func DecodeSupportedArbiterPublicKeys(data []byte) ([][]byte, error)

DecodeSupportedArbiterPublicKeys validates and decodes a canonical supported-arbiter child structure.

func EncodeContentDeliveryDocument

func EncodeContentDeliveryDocument(paymentAuthorizationID protocol.PaymentAuthorizationID) ([]byte, error)

EncodeContentDeliveryDocument returns the exact canonical one-element content_delivery_cbor authentication document: [payment_authorization_id].

func EncodeContentHashes

func EncodeContentHashes(hashes [][]byte) ([]byte, error)

EncodeContentHashes returns the sole canonical representation of the 003 content_hashes child document: an array of 1..MaxContentBatchItems unique, ordered 32-byte hashes encoded as a deterministic CBOR byte string.

func EncodeContentPayloads

func EncodeContentPayloads(payloads [][]byte) ([]byte, error)

EncodeContentPayloads returns the sole canonical representation of the 004 content_payloads child document: an array of 1..MaxContentBatchItems non-empty payloads, each at most masterseed.BlockSize bytes.

func EncodeFileQuoteTerms

func EncodeFileQuoteTerms(terms *FileQuoteTerms) ([]byte, error)

EncodeFileQuoteTerms returns the exact canonical CBOR bytes signed by a seller. The authenticated document contains business fields only; version and kind live exclusively in the outer [1, 1, ...] wire message.

func EncodePaymentAuthorization

func EncodePaymentAuthorization(authorization *PaymentAuthorization) ([]byte, error)

EncodePaymentAuthorization returns the exact deterministic CBOR bytes signed by the buyer for a Kind 5 request: the six-element business-field array.

func EncodeSignedContentDelivery

func EncodeSignedContentDelivery(delivery *SignedContentDelivery) ([]byte, error)

EncodeSignedContentDelivery encodes the complete Kind 6 wire message: [1, 6, content_delivery_cbor, seller_content_delivery_signature, content_payloads_cbor].

func EncodeSignedContentRequest

func EncodeSignedContentRequest(request *SignedContentRequest) ([]byte, error)

EncodeSignedContentRequest encodes the complete Kind 5 wire message: [1, 5, payment_authorization_cbor, buyer_payment_authorization_signature].

func EncodeSignedFileQuote

func EncodeSignedFileQuote(quote *SignedFileQuote) ([]byte, error)

EncodeSignedFileQuote returns the complete Kind 1 wire message: [1, 1, terms_cbor, seller_public_key, seller_file_quote_terms_signature].

func EncodeSupportedArbiterPublicKeys

func EncodeSupportedArbiterPublicKeys(publicKeys [][]byte) ([]byte, error)

EncodeSupportedArbiterPublicKeys returns the sole allowed representation of the supported-arbiter child structure.

func FileQuoteTermsID

func FileQuoteTermsID(termsCBOR []byte) (protocol.FileQuoteTermsID, error)

FileQuoteTermsID returns SHA-256 over the exact canonical quote terms. It lives in the Kind 1 document ID namespace and anchors every later payment authorization to one quote.

func PaymentAuthorizationID

func PaymentAuthorizationID(paymentAuthorizationCBOR []byte) (protocol.PaymentAuthorizationID, error)

PaymentAuthorizationID validates canonical payment authorization CBOR and returns its SHA-256 digest. It is defined exclusively over the exact payment_authorization_cbor and shares its namespace with that document.

func SanitizeRecommendedFilename

func SanitizeRecommendedFilename(name string) string

SanitizeRecommendedFilename converts the seller-supplied display name into a safe single filename. Sellers must apply it before encoding and signing the terms; receivers use the identical rule to reject any field that was not sanitized upstream instead of silently rewriting signed bytes.

func ValidateFileQuoteTerms

func ValidateFileQuoteTerms(terms *FileQuoteTerms) error

ValidateFileQuoteTerms validates quote terms without considering time or a seller signature. The recommended filename must already satisfy the single sanitize rule: sellers sanitize before encoding and signing, buyers only verify that the received field obeys the same rule and never rewrite it. 所有导出失败分支都返回结构化 invalid_evidence/malformed_wire 分类错误, 调用方可用 protocol.CodeOf 稳定分支。

func ValidatePaymentAuthorization

func ValidatePaymentAuthorization(authorization *PaymentAuthorization) error

ValidatePaymentAuthorization checks the Kind 5 field widths, pool reference, target payment sequence bounds, canonical content-hash batch, and delivery deadline before signing.

func VerifyContentPayloadsContext

func VerifyContentPayloadsContext(ctx context.Context, quoteTerms *FileQuoteTerms, contentHashes, payloads [][]byte, seed []byte) ([]byte, error)

VerifyContentPayloadsContext 验证交付批次:数量严格等于授权哈希数量、顺序 一一对应、逐项 SHA-256、seed/block 归属与协议期望长度。当批次内携带与报价 SeedHash 对应的 seed payload 时,先完整验证它,再用它做块成员校验;返回值 是实际用于成员校验的 seed 深复制,调用方可用它继续计算聚合价格。ctx 仅用 于可取消的大 payload 计算。

func VerifyContentRequestEvidence

func VerifyContentRequestEvidence(request *SignedContentRequest, quote *SignedFileQuote, opening PoolOpeningEvidence) (*PaymentAuthorization, *FileQuoteTerms, error)

VerifyContentRequestEvidence 是时间无关的 003 完整证据验证:报价证据与 卖方签名、池绑定、买方统一签名、FileQuoteTermsID 比对以及 Buyer/Seller/Arbiter 与开池证据的绑定。它不检查报价过期或交付截止时间; 角色工作流用它保证整个操作只使用调用方显式传入的一份时间事实。

Types

type FileQuoteTerms

type FileQuoteTerms struct {
	// SeedHash 是内容仓库的种子摘要(SHA-256,32 字节):买方据此识别要购买
	// 的 seed;等于该值的哈希按 seed 计价,其余哈希必须能在该 seed 中找到。
	SeedHash []byte
	// BuyerPublicKey 是唯一被允许接受并签署后续 003 请求的买方压缩公钥
	// (33 字节);报价只面向这一个买方。
	BuyerPublicKey []byte
	// SeedPriceSatoshis 是整个 MasterSeed 的绝对单价,单位 satoshi。
	SeedPriceSatoshis uint64
	// FullBlockPriceSatoshis 是一个完整块(256 KiB)的绝对单价,单位
	// satoshi;尾块按实际长度比例计算并享受 10% 卖方让利。
	FullBlockPriceSatoshis uint64
	// FileSizeBytes 是文件总字节数;块数由它派生:0 -> 0 块,正数 ->
	// ceil(file_size_bytes / 262144)。
	FileSizeBytes uint64
	// QuoteExpiresAtUnixSeconds 是报价失效时间(UTC Unix 秒,int64);
	// 到期判断由调用方用自己读取的一次系统时间完成。
	QuoteExpiresAtUnixSeconds int64
	// SupportedArbiterPublicKeysCBOR 是仲裁公钥数组的独立确定性 CBOR 子文档;
	// 可为空数组,但内部公钥不得为空或重复。开池时 Arbiter 公钥必须在其中。
	SupportedArbiterPublicKeysCBOR []byte
	// RecommendedFilename 是经 sanitize 的展示文件名建议:先 sanitize 再编码,
	// 与经济条款一起进入卖方统一签名;不同文件名产生不同 file_quote_terms_id。
	// 它只是展示事实,不是内容/价格/身份的真值。
	RecommendedFilename string
}

FileQuoteTerms is the seller's signed pricing and expiry commitment to one buyer. It is the authenticated Kind 1 document: business fields only, no version and no kind. RecommendedFilename is a sanitized display fact supplied by the seller, so it is signed together with the economic terms; different filenames therefore produce different file_quote_terms_id values.

func DecodeFileQuoteTerms

func DecodeFileQuoteTerms(data []byte) (*FileQuoteTerms, error)

DecodeFileQuoteTerms validates and decodes canonical FileQuoteTerms bytes.

func VerifyFileQuoteEvidence

func VerifyFileQuoteEvidence(quote *SignedFileQuote) (*FileQuoteTerms, error)

VerifyFileQuoteEvidence 验证时间无关的报价证据:结构、CBOR、压缩公钥与 统一 SignWireDocument(1, 1, ...) 卖方签名。它不检查当前是否过期;过期判断 由调用方用返回 terms 的 QuoteExpiresAtUnixSeconds 与显式传入的时间事实完成。

func VerifySignedFileQuote

func VerifySignedFileQuote(quote *SignedFileQuote, at time.Time) (*FileQuoteTerms, error)

VerifySignedFileQuote verifies structural validity, quote expiry at the caller-supplied time fact, and the seller signature. It never reads a clock: at 必须由调用方作为本操作唯一时间事实传入。

type PaymentAuthorization

type PaymentAuthorization struct {
	// FileQuoteTermsID 选择本授权购买的报价(SHA-256(exact
	// file_quote_terms_cbor),32 字节);全零哨兵不得上线。
	FileQuoteTermsID protocol.FileQuoteTermsID
	// RefundTemplateTxID 选择费用池并经其不可变的 OpeningProof 唯一确定
	// 买/卖/仲裁三方角色与费率(32 字节,按交易 TxID 算法派生)。
	RefundTemplateTxID []byte
	// PaymentSequence 是本次授权的目标付款状态序号;接收方验证它恰好等于
	// previous + 1,范围 1..4294967294。
	PaymentSequence uint32
	// SellerAmountAfterSatoshis 是批次付款后卖方的绝对累计金额(单位
	// satoshi),绝不是本批增量。
	SellerAmountAfterSatoshis uint64
	// ContentHashesCBOR 是确定性 CBOR 子文档:1..64 个有序且不重复的
	// 32 字节内容哈希,与 payload 批次顺序一一对应。
	ContentHashesCBOR []byte
	// DeliveryDeadlineUnixSeconds 是交付截止时间(UTC Unix 秒,int64);
	// 必须为正数且不超过报价有效期。
	DeliveryDeadlineUnixSeconds int64
}

PaymentAuthorization is the unsigned, signed-bytes portion of the canonical Kind 5 ContentRequest: the buyer's final payment authorization. It carries no public keys or fee rates: those are uniquely determined by RefundTemplateTxID's OpeningProof, and the quote is selected by FileQuoteTermsID alone.

func DecodePaymentAuthorization

func DecodePaymentAuthorization(data []byte) (*PaymentAuthorization, error)

DecodePaymentAuthorization accepts only canonical six-element Kind 5 authentication documents. Legacy versions, inner kinds, single-hash requests, missing or extra fields, and non-canonical encodings all return a structured malformed_wire/non_canonical/invalid_evidence error.

func VerifySignedContentRequestForOpening

func VerifySignedContentRequestForOpening(request *SignedContentRequest, opening PoolOpeningEvidence) (*PaymentAuthorization, error)

VerifySignedContentRequestForOpening verifies the pool binding and buyer signature of a Kind 5 against caller-supplied local opening evidence. A seller may use it while forming the Kind 8 Claim, but the OpeningProof is not part of the Kind 8 wire request. It derives the RefundTemplateTxID from the supplied opening, requires an exact match, and verifies the buyer signature through VerifyWireDocument(1, 5, ...) against the opening's buyer key. Quote, content, and timing facts are intentionally out of scope here.

type PoolOpeningEvidence

type PoolOpeningEvidence interface {
	OpeningBuyerPublicKey() []byte
	OpeningSellerPublicKey() []byte
	OpeningArbiterPublicKey() []byte
	OpeningRefundTemplateTxID() []byte
}

PoolOpeningEvidence is the minimal opening-proof view needed to bind a 003 to its fee pool without importing the pool package. *pool.OpeningProof implements it with exported helper methods.

type SignedContentDelivery

type SignedContentDelivery struct {
	// ContentDeliveryCBOR 是确定性 CBOR 认证文档 [payment_authorization_id],
	// 把交付钉死到一次授权;它也是应用路由 004 到本地原始 003 的索引来源。
	ContentDeliveryCBOR []byte
	// SellerContentDeliverySignature 是卖方对精确 content_delivery_cbor 的
	// 统一普通消息签名(SignWireDocument(1, 6, ...))。它不覆盖 payload。
	SellerContentDeliverySignature []byte
	// ContentPayloadsCBOR 是确定性 CBOR 子文档,按顺序承载与 003 哈希一一对应
	// 的 payload 数组;作为 attachment 不进入签名预映像。
	ContentPayloadsCBOR []byte
}

SignedContentDelivery is the complete Kind 6 ContentDelivery wire message. The seller signature covers exactly content_delivery_cbor through the unified SignWireDocument(1, 6, ...) helper; payloads are bound indirectly via the hashes committed in the referenced payment authorization and are carried as the trailing attachment.

func CloneSignedContentDelivery

func CloneSignedContentDelivery(delivery *SignedContentDelivery) *SignedContentDelivery

CloneSignedContentDelivery returns a deep copy of a 004 credential, including independent terms, public-key, payload, and signature byte slices.

func DecodeSignedContentDelivery

func DecodeSignedContentDelivery(data []byte) (*SignedContentDelivery, error)

DecodeSignedContentDelivery decodes canonical Kind 6 wire message bytes.

func NewSignedContentDelivery

func NewSignedContentDelivery(ctx context.Context, paymentAuthorizationID protocol.PaymentAuthorizationID, payloads [][]byte, signer protocol.Signer) (*SignedContentDelivery, error)

NewSignedContentDelivery builds the one-element content_delivery_cbor over the referenced payment authorization ID, signs it through the unified SignWireDocument(1, 6, ...) helper, and attaches the canonically encoded payload batch. Callers must fully verify the referenced 003, the quote, the opening proof, and every payload before invoking this constructor.

type SignedContentRequest

type SignedContentRequest struct {
	// PaymentAuthorizationCBOR 是 exact 规范付款授权字节(确定性 CBOR),
	// 也是 payment_authorization_id = SHA-256(...) 的计算来源。
	PaymentAuthorizationCBOR []byte
	// BuyerPaymentAuthorizationSignature 是买方对 WireSignatureInput(1, 5,
	// payment_authorization_cbor) 的 low-S DER 统一消息签名。
	BuyerPaymentAuthorizationSignature []byte
}

SignedContentRequest is the complete Kind 5 ContentRequest wire message: the canonical payment_authorization_cbor plus the buyer signature over WireSignatureInput(1, 5, payment_authorization_cbor).

func CloneSignedContentRequest

func CloneSignedContentRequest(request *SignedContentRequest) *SignedContentRequest

CloneSignedContentRequest returns a deep copy of a 003 credential, including independent terms, public-key, and signature byte slices.

func DecodeSignedContentRequest

func DecodeSignedContentRequest(data []byte) (*SignedContentRequest, error)

DecodeSignedContentRequest decodes a canonical Kind 5 wire message and rejects malformed array shapes, outer version/kind pairs, and byte fields before returning a copy.

func NewSignedContentRequest

func NewSignedContentRequest(ctx context.Context, authorization *PaymentAuthorization, signer protocol.Signer) (*SignedContentRequest, error)

NewSignedContentRequest deterministically encodes the payment authorization and signs those exact bytes through the unified SignWireDocument(1, 5, ...) helper with the supplied constrained Signer. The signature is immediately self-verified against the Signer's fixed public key; the private key never enters any wire message, local result, log, or persisted structure.

type SignedFileQuote

type SignedFileQuote struct {
	// FileQuoteTermsCBOR 是 exact 规范条款字节(确定性 CBOR),也是
	// file_quote_terms_id = SHA-256(...) 的计算来源;验证后绝不重编码。
	FileQuoteTermsCBOR []byte
	// SellerPublicKey 是卖方压缩公钥(33 字节),用于恢复并验证条款统一签名。
	SellerPublicKey []byte
	// SellerFileQuoteTermsSignature 是卖方对 WireSignatureInput(1, 1,
	// file_quote_terms_cbor) 的 low-S DER 统一消息签名。
	SellerFileQuoteTermsSignature []byte
}

SignedFileQuote is the complete Kind 1 FileQuote wire message payload: canonical quote terms, the seller identity key, and the seller signature over WireSignatureInput(1, 1, terms_cbor).

func CloneSignedFileQuote

func CloneSignedFileQuote(quote *SignedFileQuote) *SignedFileQuote

CloneSignedFileQuote returns an independent copy for API and storage boundaries.

func DecodeSignedFileQuote

func DecodeSignedFileQuote(data []byte) (*SignedFileQuote, error)

DecodeSignedFileQuote decodes one canonical Kind 1 wire message. Signature and expiry verification is intentionally separate so callers verify through the fixed evidence path with their own explicit time facts.

func NewSignedFileQuote

func NewSignedFileQuote(ctx context.Context, terms *FileQuoteTerms, signer protocol.Signer) (*SignedFileQuote, error)

NewSignedFileQuote validates quote terms, encodes the canonical FileQuoteTermsCBOR, signs those exact bytes through the unified SignWireDocument(1, 1, ...) helper with the supplied constrained Signer, and fixedly re-verifies the signature with the Signer's public key before returning a portable Kind 1 credential. The recommended filename lives inside the draft terms as their single source: callers sanitize it first; the private key never enters any wire message, local result, log, or persisted structure.

type UnixSeconds

type UnixSeconds int64

UnixSeconds is the protocol's UTC Unix-seconds representation.

type VerifiedQuote

type VerifiedQuote struct {
	// contains filtered or unexported fields
}

VerifiedQuote 是字段私有、访问器防御性复制的已验证报价:它证明卖方签名、 条款结构与其绑定关系全部正确(Verified),并携带买方做后续时间判断所需的 最终规范化 terms。它不拥有存储或网络行为;应用自行保存 exact Kind 1 bytes。

func VerifyQuoteForBuyer

func VerifyQuoteForBuyer(quote *SignedFileQuote, facts protocol.Facts, buyerPublicKey []byte) (*VerifiedQuote, error)

VerifyQuoteForBuyer 是获得 VerifiedQuote 的唯一公开路径:执行时间无关证据 验证(结构与卖方统一签名)、显式时间过期判断与买方归属绑定,全部通过后才 返回不可变 verified value。伪造、他人报价或已过期报价都会被拒绝。 时间事实经 protocol.Facts.RequireNow 获取:零值时间直接拒绝,绝不回退 系统时钟,也绝不可能用零值绕过过期门禁。

func (*VerifiedQuote) AllowsArbiter

func (v *VerifiedQuote) AllowsArbiter(publicKey []byte) bool

AllowsArbiter 报告指定仲裁公钥是否在报价允许列表内。

func (*VerifiedQuote) BuyerPublicKey

func (v *VerifiedQuote) BuyerPublicKey() []byte

BuyerPublicKey 返回唯一被授权买方的压缩公钥副本。

func (*VerifiedQuote) EqualTermsID

func (v *VerifiedQuote) EqualTermsID(other protocol.FileQuoteTermsID) bool

EqualTermsID 比较给定 ID 是否等于本报价的 typed ID。

func (*VerifiedQuote) ExpiresAt

func (v *VerifiedQuote) ExpiresAt() time.Time

ExpiresAt 返回报价失效时间(UTC Unix 秒);过期判断由调用方用自己的显式 时间事实完成,SDK 不读钟。

func (*VerifiedQuote) ID

ID 返回 file_quote_terms_id = SHA-256(exact file_quote_terms_cbor)。

func (*VerifiedQuote) Quote

func (v *VerifiedQuote) Quote() *SignedFileQuote

Quote 返回深拷贝的完整已签报价凭证(含 exact terms CBOR 与卖方签名)。

func (*VerifiedQuote) SeedHash

func (v *VerifiedQuote) SeedHash() []byte

SeedHash 返回报价种子摘要的副本。

func (*VerifiedQuote) SellerPublicKey

func (v *VerifiedQuote) SellerPublicKey() []byte

SellerPublicKey 返回卖方压缩公钥副本。

func (*VerifiedQuote) SupportedArbiterPublicKeys

func (v *VerifiedQuote) SupportedArbiterPublicKeys() [][]byte

SupportedArbiterPublicKeys 解码并返回受支持仲裁公钥的深拷贝列表。

func (*VerifiedQuote) Terms

func (v *VerifiedQuote) Terms() *FileQuoteTerms

Terms 返回深拷贝的已解码条款;RecommendedFilename 是实际签署的单一来源值。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL