org.klomp.snark.dht

## Class Token

- java.lang.Object
- - net.i2p.data.ByteArray
  - - org.klomp.snark.dht.Token

- All Implemented Interfaces:
    Serializable, Comparable<ByteArray>

      class Token
      extends ByteArray

  DHT token management for secure peer verification.

  Tokens are used in the BitTorrent DHT protocol to prevent certain types of attacks. When a peer announces itself to a DHT node, it receives a token that must be included in subsequent get_peer requests. This verifies that the requesting peer has previously communicated with the DHT node from the same IP address.

  This class handles both outgoing tokens (generated locally for sending to peers) and incoming tokens (received from remote DHT nodes). Tokens have limited lifetimes and are automatically expired to prevent replay attacks.

  Security considerations:
  - Outgoing tokens are 8 bytes of cryptographically secure random data
  - Incoming tokens may be up to 64 bytes (to accommodate various implementations)
  - Tokens are timestamped for automatic expiration
  - Lookup-only tokens don't store timestamps to save memory

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Token(byte[] data)` Creates a lookup-only token without timestamp.
    `Token(I2PAppContext ctx)` Creates a new outgoing token for sending to remote peers.
    `Token(I2PAppContext ctx, byte[] data)` Creates an incoming token received from a remote DHT node.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `lastSeen()` Returns the timestamp when this token was created or last seen.
    `String` | `toString()` Returns a string representation of the token for debugging and logging.

    - ### Methods inherited from class net.i2p.data.ByteArray

      `compareTo, equals, getData, getOffset, getValid, hashCode, setData, setOffset, setValid, toBase64`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Token

          public Token(byte[] data)

      Creates a lookup-only token without timestamp.

      Creates a token instance for comparison purposes only, without storing a timestamp. This is useful when checking if a received token matches an expected value without needing to track its age for expiration.

      Parameters:
        `data` - the token data to use for lookup comparison

    - #### Token

          public Token(I2PAppContext ctx)

      Creates a new outgoing token for sending to remote peers.

      Generates 8 bytes of cryptographically secure random data that will be used as a token. The token is timestamped for expiration tracking. This constructor is used when we are the DHT node responding to a get_peer request.

      Parameters:
        `ctx` - the I2P application context for random number generation and clock access

    - #### Token

          public Token(I2PAppContext ctx,
                       byte[] data)

      Creates an incoming token received from a remote DHT node.

      Stores a token received from a remote DHT node for later use in announce_peer requests. The token is timestamped for expiration tracking. Tokens longer than 64 bytes are rejected to prevent memory exhaustion attacks.

      Parameters:
        `ctx` - the I2P application context for clock access
        `data` - the token data received from the remote DHT node
      Throws:
        `IllegalArgumentException` - if the token data exceeds 64 bytes

  - ### Method Detail

    - #### lastSeen

          public long lastSeen()

      Returns the timestamp when this token was created or last seen.
      Returns:
        the timestamp in milliseconds since epoch, or 0 for lookup-only tokens

    - #### toString

          public String toString()

      Returns a string representation of the token for debugging and logging.

      Formats the token data as hexadecimal and includes the creation timestamp if available. The format is consistent with other DHT debugging output.

      Overrides:
        `toString` in class `ByteArray`
      Returns:
        a formatted string containing token length, hex data, and creation time