secret/pkg/agehd/README.md

# agehd - Deterministic Age Identities from BIP85

The `agehd` package derives deterministic X25519 age identities using BIP85
entropy derivation and a deterministic random number generator (DRNG). This
package only supports proper BIP85 sources: BIP39 mnemonics and extended private
keys (xprv).

## Features

- **Deterministic key generation**: Same input always produces the same age
  identity
- **BIP85 compliance**: Uses the BIP85 standard for entropy derivation
- **Multiple key support**: Generate multiple keys from the same source using
  different indices
- **Two BIP85 input methods**: Support for BIP39 mnemonics and extended private
  keys (xprv)
- **Vendor/application scoped**: Uses vendor-specific derivation paths to avoid
  conflicts

## Derivation Path

The package uses the following BIP85 derivation path:

```
m/83696968'/592366788'/733482323'/n'
```

Where:

- `83696968'` is the BIP85 root path ("bip" in ASCII)
- `592366788'` is the vendor ID (sha256("berlin.sneak") & 0x7fffffff)
- `733482323'` is the application ID (sha256("secret") & 0x7fffffff)
- `n'` is the sequential index (0, 1, 2, ...)

## Usage

### From BIP39 Mnemonic

```go
package main

import (
    "fmt"
    "log"

    "git.eeqj.de/sneak/secret/pkg/agehd"
)

func main() {
    mnemonic := "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

    // Derive the first identity (index 0)
    identity, err := agehd.DeriveIdentity(mnemonic, 0)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Secret key: %s\n", identity.String())
    fmt.Printf("Public key: %s\n", identity.Recipient().String())
}
```

### From Extended Private Key (XPRV)

```go
package main

import (
    "fmt"
    "log"

    "git.eeqj.de/sneak/secret/pkg/agehd"
)

func main() {
    xprv := "xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb"

    // Derive the first identity (index 0) from the xprv
    identity, err := agehd.DeriveIdentityFromXPRV(xprv, 0)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Secret key: %s\n", identity.String())
    fmt.Printf("Public key: %s\n", identity.Recipient().String())
}
```

### Multiple Identities

```go
package main

import (
    "fmt"
    "log"

    "git.eeqj.de/sneak/secret/pkg/agehd"
)

func main() {
    mnemonic := "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

    // Derive multiple identities with different indices
    for i := uint32(0); i < 3; i++ {
        identity, err := agehd.DeriveIdentity(mnemonic, i)
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("Identity %d: %s\n", i, identity.Recipient().String())
    }
}
```

### From Raw Entropy

```go
package main

import (
    "fmt"
    "log"

    "git.eeqj.de/sneak/secret/pkg/agehd"
)

func main() {
    mnemonic := "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

    // First derive entropy using BIP85
    entropy, err := agehd.DeriveEntropy(mnemonic, 0)
    if err != nil {
        log.Fatal(err)
    }

    // Then create identity from entropy
    identity, err := agehd.IdentityFromEntropy(entropy)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Secret key: %s\n", identity.String())
    fmt.Printf("Public key: %s\n", identity.Recipient().String())
}
```

## API Reference

### Functions

#### `DeriveIdentity(mnemonic string, n uint32) (*age.X25519Identity, error)`

Derives a deterministic age identity from a BIP39 mnemonic and index.

- `mnemonic`: A valid BIP39 mnemonic phrase
- `n`: The derivation index (0, 1, 2, ...)
- Returns: An age X25519 identity or an error

#### `DeriveIdentityFromXPRV(xprv string, n uint32) (*age.X25519Identity, error)`

Derives a deterministic age identity from an extended private key (xprv) and
index.

- `xprv`: A valid extended private key in xprv format
- `n`: The derivation index (0, 1, 2, ...)
- Returns: An age X25519 identity or an error

#### `DeriveEntropy(mnemonic string, n uint32) ([]byte, error)`

Derives 32 bytes of entropy from a BIP39 mnemonic and index using BIP85.

- `mnemonic`: A valid BIP39 mnemonic phrase
- `n`: The derivation index
- Returns: 32 bytes of entropy or an error

#### `DeriveEntropyFromXPRV(xprv string, n uint32) ([]byte, error)`

Derives 32 bytes of entropy from an extended private key (xprv) and index using
BIP85.

- `xprv`: A valid extended private key in xprv format
- `n`: The derivation index
- Returns: 32 bytes of entropy or an error

#### `IdentityFromEntropy(ent []byte) (*age.X25519Identity, error)`

Converts 32 bytes of entropy into an age X25519 identity.

- `ent`: Exactly 32 bytes of entropy
- Returns: An age X25519 identity or an error

## Implementation Details

1. **BIP85 Entropy Derivation**: The package uses the BIP85 standard to derive
   64 bytes of entropy from the input source
2. **DRNG**: A BIP85 DRNG (Deterministic Random Number Generator) using SHAKE256
   is seeded with the 64-byte entropy
3. **Key Generation**: 32 bytes are read from the DRNG to generate the age
   private key
4. **RFC-7748 Clamping**: The private key is clamped according to RFC-7748 for
   X25519
5. **Bech32 Encoding**: The key is encoded using Bech32 with the
   "age-secret-key-" prefix

## Security Considerations

- The same mnemonic/xprv and index will always produce the same identity
- Different indices produce cryptographically independent identities
- The vendor/application scoping prevents conflicts with other BIP85
  applications
- The DRNG ensures high-quality randomness for key generation
- Private keys are properly clamped for X25519 usage
- Only accepts proper BIP85 sources (mnemonics and xprv keys), not arbitrary
  passphrases

## Testing

Run the tests with:

```bash
go test -v ./internal/agehd
```