// Package geduldh stores immutable, content-addressed Document payloads. // Authorization and reference/retention decisions belong to the application, // not to a storage backend. A hash or storage key is never an access token. package geduldh import ( "context" "crypto/sha256" "encoding/hex" "errors" "io" "strings" ) const Component = "geduldh" var ( ErrInvalidHash = errors.New("invalid Document SHA-256") ErrHashMismatch = errors.New("Document payload does not match SHA-256") ErrSizeMismatch = errors.New("Document payload does not match declared size") ) type Info struct { Hash string Size int64 } // Reader supports bounded and seekable access, including HTTP Range and ZIP. // A remote backend must not download the entire object merely to open it. type Reader interface { io.ReadSeekCloser io.ReaderAt } // Store is the immutable payload boundary, not a filesystem abstraction. // PutIfAbsent must verify the size and SHA-256 before publishing a complete // object, never replace an existing object, and reject corrupt existing bytes. // A successful write must precede the metadata transaction which references it. // Delete is deliberately absent: GC requires reference and retention protection. type Store interface { Stat(context.Context, string) (Info, error) Open(context.Context, string) (Reader, error) PutIfAbsent(context.Context, string, int64, io.Reader) error Verify(context.Context, string) error } // Key preserves the existing on-disk layout and is also suitable for S3 keys. // Backend placement never changes Page/Revision identity or public URLs. func Key(hash string) (string, error) { hash = strings.ToLower(strings.TrimSpace(hash)) if len(hash) != sha256.Size*2 { return "", ErrInvalidHash } if _, err := hex.DecodeString(hash); err != nil { return "", ErrInvalidHash } return "sha256/" + hash[:2] + "/" + hash, nil }