Documentation
¶
Overview ¶
Package auth is a pluggable provider of the two private keys any-sync needs: the account key (identity, signing, encryption) and the device key (per-installation peer identity). How the keys are obtained (mnemonic derivation, server-side auth, hardware token) is the provider's concern; the rest of the SDK only consumes the resulting Ed25519 keys.
Ships a built-in mnemonic provider (BIP-39 / SLIP-10 at m/44'/2046'/[index]'). Key persistence is the caller's responsibility — the SDK does not store keys or mnemonics. See docs/auth-module.md.
Index ¶
Constants ¶
const DefaultAccountIndex uint32 = 1
DefaultAccountIndex is the account derivation index for `any` accounts. Index 0 is anytype's, so one seed phrase yields a distinct account per product. Callers restoring an anytype-derived (or pre-index-1 `any`) account pass 0 explicitly.
Variables ¶
var ErrInvalidMnemonic = errors.New("invalid mnemonic")
ErrInvalidMnemonic wraps BIP-39 validation failures of a supplied mnemonic phrase.
var ErrMnemonicMismatch = errors.New("wallet exists with a different mnemonic")
ErrMnemonicMismatch is returned when FileProviderConfig.Mnemonic is set but an existing wallet file stores a different phrase — or the same phrase at a different derivation index.
var ErrPasskeyRequired = errors.New("wallet is encrypted but no passkey provided")
ErrPasskeyRequired is returned when the wallet file is encrypted but no passkey was supplied.
var ErrWrongPasskey = errors.New("decrypt wallet: wrong passkey or corrupted file")
ErrWrongPasskey is returned when the supplied passkey fails to decrypt the wallet (or the file is corrupted).
Functions ¶
func AccountId ¶
AccountId derives the StrKey-encoded account address ("A…") for a mnemonic + account index without touching disk or booting the SDK. It is the same string SDK.Account().Id() reports after opening with the matching wallet — callers use it to address per-account storage before a wallet file exists.
func GenerateDeviceKey ¶
GenerateDeviceKey returns a fresh Ed25519 device-key in raw form (64 bytes). Callers store the result in their secure storage and pass it back via MnemonicConfig.DeviceKey on every init.
func GenerateMnemonic ¶
GenerateMnemonic returns a fresh 12-word BIP-39 mnemonic.
Types ¶
type FileProvider ¶
type FileProvider struct {
// contains filtered or unexported fields
}
FileProvider is a Provider backed by a JSON wallet file on disk. Generated on first use, loaded on subsequent launches. Exposes Mnemonic so the caller can display it once on first generation for the user to back up.
func NewFileProvider ¶
func NewFileProvider(cfg FileProviderConfig) (*FileProvider, error)
NewFileProvider returns the default provider. On first use it generates a fresh mnemonic (or adopts cfg.Mnemonic when set) plus a fresh device key, writes them to Path, and marks Created() true. On subsequent runs it loads the existing wallet; Created() returns false, and a set cfg.Mnemonic must match the stored phrase.
func (*FileProvider) AccountIndex ¶
func (p *FileProvider) AccountIndex() uint32
AccountIndex returns the derivation index pinned in the wallet file.
func (*FileProvider) AccountKey ¶
func (p *FileProvider) AccountKey(_ context.Context) ([]byte, error)
AccountKey derives and returns the account private key.
func (*FileProvider) Created ¶
func (p *FileProvider) Created() bool
Created reports whether the wallet was freshly generated on this call to NewFileProvider. Callers typically use it to display the mnemonic to the user once ("write this down") the first time the SDK is initialized.
func (*FileProvider) DeviceKey ¶
func (p *FileProvider) DeviceKey(_ context.Context) ([]byte, error)
DeviceKey returns the stored device private key (raw Ed25519).
func (*FileProvider) Mnemonic ¶
func (p *FileProvider) Mnemonic() string
Mnemonic returns the BIP-39 phrase backing this wallet. Sensitive — only surface to the user on first launch.
func (*FileProvider) Path ¶
func (p *FileProvider) Path() string
Path returns the resolved wallet-file path.
type FileProviderConfig ¶
type FileProviderConfig struct {
// Path to the wallet file. Required.
Path string
// Passkey, when non-empty, encrypts the wallet at rest with
// AES-256-GCM keyed by PBKDF2-HMAC-SHA256 (600k iterations,
// 16-byte salt). Leave empty for a plain-text wallet.
Passkey string
// Mnemonic, when non-empty, seeds wallet creation with an existing
// BIP-39 phrase instead of generating a fresh one — the restore /
// second-device path (the device key is still freshly generated).
// When the wallet file already exists the stored phrase must match,
// otherwise NewFileProvider returns ErrMnemonicMismatch.
Mnemonic string
// Index is the account derivation index applied when the wallet is
// created — both for a supplied Mnemonic and for a freshly
// generated one. Ignored when the wallet file already exists (the
// stored index wins). Zero means index 0, the anytype-compatible
// account; `any` accounts use DefaultAccountIndex.
Index uint32
}
FileProviderConfig configures the default file-backed Provider.
type MnemonicConfig ¶
type MnemonicConfig struct {
// Mnemonic is the BIP-39 phrase (typically 12 or 24 words).
Mnemonic string
// Index is the account index. Defaults to 0.
Index uint32
// DeviceKey is the persisted device private key in raw Ed25519
// form (64 bytes). Callers own device-key lifecycle: generate on
// first run with GenerateDeviceKey, store securely, pass back
// every init.
DeviceKey []byte
}
MnemonicConfig builds a Provider from a BIP-39 mnemonic using the SLIP-10 path m/44'/2046'/[Index]' for the account identity.
type Provider ¶
type Provider interface {
AccountKey(ctx context.Context) ([]byte, error)
DeviceKey(ctx context.Context) ([]byte, error)
}
Provider yields the two private keys any-sync needs to operate: the account key (identity, signing, encryption) and the device key (per-installation peer identity). How the keys are obtained (mnemonic derivation, server-side auth, hardware token) is the implementation's concern. The SDK does not persist keys — callers are responsible for secure storage.
Both keys are Ed25519. The SDK treats the byte slices as opaque Ed25519 private-key seeds (the 32-byte secret form any-sync derives everything else from). Wrappers that carry more than a seed should return only the seed here.
func NewMnemonicProvider ¶
func NewMnemonicProvider(cfg MnemonicConfig) (Provider, error)
NewMnemonicProvider validates the mnemonic and returns a Provider that derives the account key on demand.