verifyaname 0.2.1
Aname verification library
License: Apache 2.0
Requires Python: >=3.8,<3.12

## Token generation
Below is the example how to generate verification token for your domain:

```python
from verifyaname.verification_token import VerificationTokenData

domain = 'fetch-ai.com'
owner_wallet_address = 'fetch176kwvxr6u9v4axkfe2pzzzn87p4qssu9rn09kn'

vtd = VerificationTokenData(domain=domain, owner_address=owner_wallet_address)

# *Raw* Value of the verification token is `vtd.token`:
print(f'Raw token value: {vtd.token_raw}')

# *DNS TXT* value of the verification token is `vtd.token_b64` (it is URL-Safe-Base64 encoded raw value):
print(f'DNS TXT token value: "{vtd.token}"')
```

Execution of the code examples above gives the following output:
```text
Raw token value: b'j7\xe5\xb4\x88T\x97\xde7\x98-\xde\x1b\x90n\n\x08\xe2\xdf=\x03S\x7f\x1f\x1f%n\xf7S?|\xe4'
DNS TXT token value: "ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ"
```

> NOTE: Value returned by the `vtd.token` property (see the code above) needs to be stored in domain's
> DNS TXT configuration under the `fetch-aname-token=` key - see the [DNS TXT record](#dns-txt-record) below.

## DNS TXT record
The whole DNS TXT record can be simply generated by calling the `create_dns_txt_record()` method.

```python
from verifyaname.verification_token import VerificationTokenData

domain = 'fetch-ai.com'
owner_wallet_address = 'fetch176kwvxr6u9v4axkfe2pzzzn87p4qssu9rn09kn'

vtd = VerificationTokenData(domain=domain, owner_address=owner_wallet_address)

dns_record = vtd.create_dns_txt_record()
print("Below is the *whole* DNS TXT record:")
print(dns_record)
```

Execution of the code above gives the following output, please notice the very last line starting with
the `fetch-aname-token=` text - **WHOLE** that line represents the whole DNS TXT record line:
```text
Below is the *whole* DNS TXT record:
fetch-aname-token=ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ
```
> NOTE: This dns txt record **MUST** be then added as the **whole** line to the DNS TXT configuration of the domain in
> question(the `fetch-ai.com` in this particular case).


# Verifying DNS TXT record

In order to verify validity of the DNS TXT record (queried from the DNS TXT configuration of the domain) use the
following static method:

```python
from verifyaname.verification_token import VerificationTokenData

# Value acquired from the DNS TXT domain configuration of the 'fetch-ai.com' domain:
dns_txt_record = 'fetch-aname-token=ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ'

# We expect following domain & owner wallet address:
domain = 'fetch-ai.com'
expected_owner_wallet_address = 'fetch176kwvxr6u9v4axkfe2pzzzn87p4qssu9rn09kn'

expected_vtd = VerificationTokenData(domain=domain, owner_address=expected_owner_wallet_address)

print(f'Is token valid: {expected_vtd.verify_dns_txt_record(dns_txt_record)}')
```

Execution of the code examples above gives the following output:
```text
Is token valid: True
```

## Extracting token from a DNS TXT record

```python
from verifyaname.verification_token import VerificationTokenData

# Value acquired from the DNS TXT domain configuration of the 'fetch-ai.com' domain:
dns_txt_record = 'fetch-aname-token=ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ'
token = VerificationTokenData.extract_token_from_dns_txt_record(dns_txt_record)
print(f'[Valid record]     Extracted token: {token}')

# Malformed DNS TXT record (the record does *NOT* start with expected `fetch-aname-token=` prefix,
# in which case, the `VerificationTokenData.extract_token_from_dns_txt_record(...)` returns `None`.
malformed_dns_txt_record = 'MAFLFORMED_PREFIX=ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ'
token2 = VerificationTokenData.extract_token_from_dns_txt_record(malformed_dns_txt_record)
print(f'[Malformed record] Extracted token: {token2}')
```

Execution of the code examples above gives the following output:
```text
[Valid record]     Extracted token: ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ
[Malformed record] Extracted token: None
```

### Retrospective postprocessing of *Multiple* DNS TXT records

Using this approach makes sense more-or-less only if there is necessary to do some post-processing
of **multiple** DNS TXT records - e.g. do their verification retrospectively for some reason.

HOWEVER, normally, there is no reason to do verification retrospectively, and it is better, and way more readable 
to perform verification in immediate fashion using the `VerificationTokenData.verify_dns_txt_record(...)` method.

```python
from verifyaname.verification_token import VerificationTokenData

# NOTE: In this example we are going to use just *single* domain in order to simplify.
# However, in general, the algorithm below can be extended to multiple domains if necessary. 
domain = 'fetch-ai.com'

# Values acquired from the DNS TXT configuration of the 'fetch-ai.com' domain:
dns_txt_records = [
    'fetch-aname-token=ajfltIhUl943mC3eG5BuCgji3z0DU38fHyVu91M_fOQ',
    'fetch-aname-token=0OSUJZkcHtGMzEYivudG2DtBIq0M7pC9rWS3WXRhUac',
    'fetch-aname-token=J7RRL7jHyZ0LqUsrtDEODWOAb54XUlHT3laCUG9di8k',
    'fetch-aname-token=Cb09i2l-_WDHrY5tjOhZzbNbAWGiPSijMdiRAWgywtA'
]

tokens = set()
for record in dns_txt_records:
    tokens.add(VerificationTokenData.extract_token_from_dns_txt_record(record))

# For the domain `fetch-ai.com` we are expecting 4 owners:

expected_owners = {
    'fetch176kwvxr6u9v4axkfe2pzzzn87p4qssu9rn09kn',
    'fetch1mlhdzzrmcrmmzfjg4tg8runfmu7d0nvlmmttdv',
    'fetch104376kh6sevxel6xy4qdragnyvvczcfqje5urg',
    'fetch1pws7ernn93pd8ht2w4zu08mqgznpz3qu7xs709',
}

# Verify all owners for the domain:
failed_owners = set()
for owner in expected_owners:
    vtd = VerificationTokenData(domain=domain, owner_address=owner)

    # Using the `vtd.token` property to verify the token:
    if vtd.token in tokens:
        print(f'SUCCESS: [{owner}] has been VERIFIED as owner of the "{domain}" domain')
    else:
        failed_owners.add(owner)
        print(f'FAILURE: [{owner}] failed to verify as an owner of the "{domain}" domain')

if len(failed_owners) > 0:
    print(
        f'Verification of ownership for the "{domain}" domain FAILED for {len(failed_owners)} from {len(expected_owners)} owner(s)')
else:
    print(f'ALL owners have been verified')
```

Execution of the code examples above gives the following output:
```text
SUCCESS: [fetch176kwvxr6u9v4axkfe2pzzzn87p4qssu9rn09kn] has been VERIFIED as owner of the "fetch-ai.com" domain
SUCCESS: [fetch1mlhdzzrmcrmmzfjg4tg8runfmu7d0nvlmmttdv] has been VERIFIED as owner of the "fetch-ai.com" domain
SUCCESS: [fetch104376kh6sevxel6xy4qdragnyvvczcfqje5urg] has been VERIFIED as owner of the "fetch-ai.com" domain
FAILURE: [fetch1pws7ernn93pd8ht2w4zu08mqgznpz3qu7xs709] failed to verify as an owner of the "fetch-ai.com" domain
Verification of ownership for the "fetch-ai.com" domain FAILED for 1 from 4 owner(s)
```