core/go-io
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

docs(ax): align sigil references with current surfaces
Some checks failed
CI / test (push) Failing after 2s
Details
CI / auto-fix (push) Failing after 0s
Details
CI / auto-merge (push) Failing after 0s
Details

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Virgil 2026-03-31 07:24:17 +00:00
parent 48b777675e
commit 378fc7c0de
3 changed files with 20 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CLAUDE.md
View file

@ -128,7 +128,7 @@ Backend packages use `var _ io.Medium = (*Medium)(nil)` to verify interface comp
### Sentinel Errors ### Sentinel Errors
Sentinel errors (`var ErrNotFound`, `var ErrInvalidKey`, etc.) use standard `errors.New()` — this is correct Go convention. Only inline error returns in functions should use `coreerr.E()`. Sentinel errors (`var NotFoundError`, `var InvalidKeyError`, etc.) use standard `errors.New()` — this is correct Go convention. Only inline error returns in functions should use `coreerr.E()`.
## Testing ## Testing

44
docs/RFC.md
View file

@ -2341,45 +2341,45 @@ Example:
s, _ := sigil.NewSigil("hex") s, _ := sigil.NewSigil("hex")
``` ```
### ErrInvalidKey ### InvalidKeyError
Returned when an encryption key is not 32 bytes. Returned when an encryption key is not 32 bytes.
Example: Example:
```go ```go
_, err := sigil.NewChaChaPolySigil([]byte("short")) _, err := sigil.NewChaChaPolySigil([]byte("short"), nil)
if errors.Is(err, sigil.ErrInvalidKey) { if errors.Is(err, sigil.InvalidKeyError) {
// handle invalid key // handle invalid key
} }
``` ```
### ErrCiphertextTooShort ### CiphertextTooShortError
Returned when ciphertext is too short to decrypt. Returned when ciphertext is too short to decrypt.
Example: Example:
```go ```go
_, err := sigil.GetNonceFromCiphertext([]byte("short")) _, err := sigil.GetNonceFromCiphertext([]byte("short"))
if errors.Is(err, sigil.ErrCiphertextTooShort) { if errors.Is(err, sigil.CiphertextTooShortError) {
// handle truncated payload // handle truncated payload
} }
``` ```
### ErrDecryptionFailed ### DecryptionFailedError
Returned when decryption or authentication fails. Returned when decryption or authentication fails.
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
_, err := s.Out([]byte("tampered")) _, err := s.Out([]byte("tampered"))
if errors.Is(err, sigil.ErrDecryptionFailed) { if errors.Is(err, sigil.DecryptionFailedError) {
// handle failed decrypt // handle failed decrypt
} }
``` ```
### ErrNoKeyConfigured ### NoKeyConfiguredError
Returned when a `ChaChaPolySigil` has no key. Returned when a `ChaChaPolySigil` has no key.
@ -2387,7 +2387,7 @@ Example:
```go ```go
s := &sigil.ChaChaPolySigil{} s := &sigil.ChaChaPolySigil{}
_, err := s.In([]byte("data")) _, err := s.In([]byte("data"))
if errors.Is(err, sigil.ErrNoKeyConfigured) { if errors.Is(err, sigil.NoKeyConfiguredError) {
// handle missing key // handle missing key
} }
``` ```
@ -2472,14 +2472,14 @@ XChaCha20-Poly1305 encryption sigil with optional pre-obfuscation.
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
``` ```
**In(data []byte) ([]byte, error)** **In(data []byte) ([]byte, error)**
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
ciphertext, _ := s.In([]byte("hello")) ciphertext, _ := s.In([]byte("hello"))
``` ```
@ -2487,30 +2487,20 @@ ciphertext, _ := s.In([]byte("hello"))
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
ciphertext, _ := s.In([]byte("hello")) ciphertext, _ := s.In([]byte("hello"))
plain, _ := s.Out(ciphertext) plain, _ := s.Out(ciphertext)
``` ```
### NewChaChaPolySigil(key []byte) (*ChaChaPolySigil, error) ### NewChaChaPolySigil(key []byte, obfuscator PreObfuscator) (*ChaChaPolySigil, error)
Creates an encryption sigil with the default XOR obfuscator. Creates an encryption sigil with an optional pre-obfuscator. Pass `nil` to use the default XOR obfuscator.
Example:
```go
key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key)
```
### NewChaChaPolySigilWithObfuscator(key []byte, obfuscator PreObfuscator) (*ChaChaPolySigil, error)
Creates an encryption sigil with a custom obfuscator.
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
ob := &sigil.ShuffleMaskObfuscator{} ob := &sigil.ShuffleMaskObfuscator{}
s, _ := sigil.NewChaChaPolySigilWithObfuscator(key, ob) s, _ := sigil.NewChaChaPolySigil(key, ob)
``` ```
### GetNonceFromCiphertext(ciphertext []byte) ([]byte, error) ### GetNonceFromCiphertext(ciphertext []byte) ([]byte, error)
@ -2520,7 +2510,7 @@ Extracts the XChaCha20 nonce from encrypted output.
Example: Example:
```go ```go
key := make([]byte, 32) key := make([]byte, 32)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
ciphertext, _ := s.In([]byte("hello")) ciphertext, _ := s.In([]byte("hello"))
nonce, _ := sigil.GetNonceFromCiphertext(ciphertext) nonce, _ := sigil.GetNonceFromCiphertext(ciphertext)
``` ```

4
docs/architecture.md
View file

@ -230,12 +230,12 @@ The pre-obfuscation layer ensures that raw plaintext patterns are never sent dir
key := make([]byte, 32) key := make([]byte, 32)
rand.Read(key) rand.Read(key)
s, _ := sigil.NewChaChaPolySigil(key) s, _ := sigil.NewChaChaPolySigil(key, nil)
ciphertext, _ := s.In([]byte("secret")) ciphertext, _ := s.In([]byte("secret"))
plaintext, _ := s.Out(ciphertext) plaintext, _ := s.Out(ciphertext)
// With stronger obfuscation: // With stronger obfuscation:
s2, _ := sigil.NewChaChaPolySigilWithObfuscator(key, &sigil.ShuffleMaskObfuscator{}) s2, _ := sigil.NewChaChaPolySigil(key, &sigil.ShuffleMaskObfuscator{})
``` ```
Each call to `In` generates a fresh random nonce, so encrypting the same plaintext twice produces different ciphertexts. Each call to `In` generates a fresh random nonce, so encrypting the same plaintext twice produces different ciphertexts.