Metadata-Version: 2.1
Name: indieauth-helpers
Version: 1.0.0
Summary: IndieAuth authorization and callback helpers.
Home-page: https://github.com/capjamesg/python-indieauth-helpers
Author: capjamesg
Author-email: jamesg@jamesg.blog
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/capjamesg/python-indieauth-helpers/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.md

# Python IndieAuth Helpers

This package contains helper scripts for implementing an IndieAuth-compliant authentication flow.

## Installation

To install this package, run the following command:

    pip install indieauth_helpers

You can import the package using the following line of code:

    import indieauth_helpers

## Usage

This project creates two handler functions that you can use in your programs:

- A `discover_endpoints` function to find specified IndieWeb endpoints (i.e. `authorization_server`)
- A `indieauth_callback_handler` function to handle a response from an IndieAuth server after a visitor has authorized access to an account.

### discover_endpoints

    discover_endpoints(domain, headers_to_find)

To use this function, specify:

- The domain on which endpoint discovery should take place.
- A list of headers that should be returned by the server.

You can use this script to find any header in a HTTP Header tag or a HTML <link> tag.

The values that you are most likely going to use this function for are:

- authorization_endpoint
- token_endpoint
- micropub
- microsub

The function returns a dictionary of values depending on what endpoints you want to find

Here is an example of the `discover_endpoints` function in use:

    import indieauth_helpers

    domain = "https://jamesg.blog"

    headers_to_find = ["authorization_endpoint", "token_endpoint"]

    endpoints = indieauth_helpers.discover_endpoint(domain, headers_to_find)

    print(endpoints)

This code returns the following:

    {
        'authorization_endpoint': 'https://auth.jamesg.blog/auth',
        'token_endpoint': 'https://auth.jamesg.blog/token'
    }

### indieauth_callback_handler

    message, response = indieauth_callback_handler(
        code, # The code that was returned by the IndieAuth server
        state, # The state that was returned by the IndieAuth server
        token_endpoint, # The token endpoint to which the callback POST request should be sent
        code_verifier, # The code verifier that was used to generate the code
        session_state, # The session state that was generated by the client
        me, # The URL of the user's profile
        callback_url, # The URL to which the user should be redirected if authentication is successful
        client_id, # The URL of the page that identifies the client
        required_scopes # The scopes that the client needs
    )

This function verifies that an authorization server has returned a valid response and redeems a token.

This function will return a message and a None value for response if there was an error. The message value tells you what went wrong during the token verification process.

You can leave the "me" value equal to None if any URL should be able to access your service. Otherwise, set "me" to the URL of the profile that should be able to access your service. Setting a me value other than None may be useful if you are building personal services that nobody else should be able to access.

If successful, this function will return the JSON object returned by an IndieAuth authorization server.

Here is an example of the function in action:

    import indieauth_helpers

    message, response = indieauth_callback_handler(
        "CODE_FROM_AUTHORIZATION_SERVER",
        "STATE_FROM_AUTHORIZATION_SERVER",
        "https://auth.jamesg.blog/token",
        "CODE_VERIFIER_FROM_CLIENT",
        "STATE_IN_SESSION",
        "jamesg.blog",
        "https://app.jamesg.blog/callback",
        "https://jamesg.blog/callback",
        ["read", "write]
    )

    print(response)

When successful, this code returns the following:

    {
        "me": "https://jamesg.blog/",
        "access_token": "ACCESS_TOKEN",
        "scope": "SCOPE_LIST"
    }

## License

This project is licensed under the [MIT license](LICENSE).

## Contributors

- capjamesg

