=pod

=encoding utf-8

=head1 NAME

Noise - Pure Perl implementation of the Noise Protocol Framework

=head1 SYNOPSIS

    use Noise;

    # Initialize state for Noise_XX_25519_ChaChaPoly_SHA256
    my $alice = Noise->new( );
    $alice->initialize_state( );

    # Handshake Pattern: XX

    # Msg 1: Alice -> Bob (e)
    my $msg1 = $alice->write_message( 'e', '' ); # payload is optional

    # Msg 2: Bob -> Alice (e, ee, s, es)
    my ( $payload, $error ) = $alice->read_message( 'e, ee, s, es', $msg2 );

    # ... after handshake ...
    my ( $send_key, $recv_key ) = $alice->split_for_transport( );

=head1 DESCRIPTION

C<Noise> implements the Noise Protocol Framework, a modern cryptographic construction for building high-performance,
secure  communications protocols.

This implementation provides the foundational SymmetricState and CipherState logic, as well as helper methods for
executing handshake  patterns like XX.

=head1 Architecture

=head2 SymmetricState

Manages the chaining key (C<ck>) and the handshake hash (C<h>). It ensures that every message sent or received
contributes to the overall  cryptographic transcript.

=head2 CipherState

Handles the symmetric encryption (ChaCha20-Poly1305) and nonce management. Nonces are automatically incremented and
reset according to the spec.

=head1 METHODS

=head2 C<new(%params )>

Constructor.

Expected parameter:

=over

=item C<prologue>: Optional initial data to be hashed into the state.

=back

=head2 C<initialize_state( $protocol_name )>

Sets up the state machine for a specific protocol. Defaults to C<Noise_XX_25519_ChaChaPoly_SHA256>.

=head2 C<mix_hash( $data )>

Incorporates C<$data> into the handshake hash.

=head2 C<mix_key( $ikm )>

Derives a new chaining key and symmetric key from the provided input keying material (typically a DH shared secret).

=head2 C<encrypt_and_hash( $plaintext )>

Writes a payload to the handshake state. This method encrypts the plaintext using the current symmetric key and
incorporates the resulting ciphertext into the handshake hash. This ensures that the transcript is kept in
synchronization between parties.

=head2 C<decrypt_and_hash( $ciphertext )>

Reads a payload from the handshake state. This method decrypts the ciphertext, verifies the MAC tag, and incorporates
the ciphertext into the handshake hash. Dies if decryption fails.

=head2 C<split_for_transport( )>

Finalizes the handshake and returns two 32-byte keys for secure communication.

=head1 Handshake Patterns

While this module provides low-level primitives, it is recommended to use higher-level wrappers (like
L<Net::Libp2p::Noise>) for specific application integrations.

=head1 SEE ALSO

L<Noise::Stream>, L<https://noiseprotocol.org/>

L<Crypt::Noise> is an earlier implementation.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut
