Globus-action-provider-tools

===================

Breaking changes
----------------

* Remove the ``globus_action_provider_tools.flask.api_helpers`` module,
and the helpers it provided.

If possible, it is recommended to immediately migrate Action Providers
off of the code in the Flask API helpers module.

If this cannot be done immediately, it is recommended to pin
the Action Provider Tools dependency to ``0.19.1``.

Deprecations
------------

* The ``required_authorizer_expiration_time`` parameter to ``get_authorizer_for_scope`` is deprecated.

Given token expiration and caching lifetimes,
it was not possible for this parameter to have any effect based on its prior documented usage.

Bugfixes
--------

* Action Provider Tools no longer requests Dependent Refresh Tokens
if Access Tokens are sufficient. As a result of this fix,
the AuthState dependent token cache will never contain dependent refresh tokens.

Changes
-------

* ``AuthState.introspect_token()`` will no longer return ``None``
if the token is not active.

Instead, a new exception, ``InactiveTokenError``, will be raised.
``InactiveTokenError`` is a subclass of ``ValueError``.

Code that calls ``AuthState.introspect_token()`` no longer returns ``None``, either,
but will instead raise ``ValueError`` (or a subclass) or a ``globus_sdk.GlobusAPIError``:

* ``AuthState.get_authorizer_for_scope``
* ``AuthState.effective_identity``
* ``AuthState.identities``

* Group caching behavior in the ``AuthState`` class has been improved
to ensure that the cache is checked before any external operations
(e.g., dependent token callouts) are required.
The cache now uses the token hash as its key, rather than a dependent token.

Documentation
-------------

* Remove examples from documentation which relied upon the ``api_helpers`` module.

Development
-----------

* Introduce new scriv categories to better communicate how the project evolves.

The categories are also re-ordered,
which defines how fragments will be ordered in the CHANGELOG.

* Add a changelog fragment template.

.. _changelog-0.19.1:

===================

Bugfixes
--------

- When introspecting tokens, allow the introspected scopes to be a superset of required scopes.

A bug in the scope comparison code flipped the logic;
if a user consented to scopes A and B and the action provider required only scope A,
the comparison would fail *as if A and B were required but only A had been consented to*.

This is now fixed.

.. _changelog-0.19.0:

===================

**YANKED**

Features
--------

- The token introspect checking and caching performed in ``AuthState`` has
been improved.

- The cache is keyed off of token hashes, rather than raw token strings.

- The ``exp`` and ``nbf`` values are no longer verified, removing the
possibility of incorrect treatment of valid tokens as invalid due to clock
drift.

- Introspect response caching caches the raw response even for invalid
tokens, meaning that Action Providers will no longer repeatedly introspect
a token once it is known to be invalid.

- Scope validation raises a new, dedicated error class,
``globus_action_provider_tools.authentication.InvalidTokenScopesError``, on
failure.

Changes
-------

- The ``TokenChecker`` class has been removed and replaced in all cases with an
``AuthStateBuilder`` which better matches the purpose of this class.

- The ``check_token`` flask-specific helper has been replaced with a
``FlaskAuthStateBuilder`` which subclasses ``AuthStateBuilder`` and
specializes it to handle a ``flask.Request`` object.

- The ``aud`` field of token introspect responses is no longer validated and
fields associated with it have been removed. This includes changes to
function and class initializer signatures.

- The ``expected_audience`` field is no longer supported in ``AuthState`` and
``TokenChecker``. It has been removed from the initializers for these
classes.

- ``globus_auth_client_name`` has been removed from ``ActionProviderBlueprint``.

- ``client_name`` has been removed from ``add_action_routes_to_blueprint``.

Development
-----------

- Move to `src/` tree layout

- Refactor ``AuthState.get_authorizer_for_scope`` without changing its
primary outward semantics. The ``bypass_dependent_token_cache`` argument
has been removed from its interface, as it is not necessary to expose
with the improved implementation.

Removed
-------

- ``globus_action_provider_tools.testing`` has been removed. Users who were
relying on these components should make use of their own fixtures and mocks.

.. _changelog-0.18.0:

===================

Features
--------

- Added a new configuration class ``ActionProviderConfig`` with the initial option to
``scrub_validation_errors`` (default: True).

- If disabled, user-provided data may be included in library raised validation errors.

Changes
-------

- Use UUIDs as action IDs.

- Scrubbed and non-scrubbed jsonschema errors have been enhanced. They now follow
the format

.. code-block:: text

Field '<jsonpath>' (category: '<error_category>'): Input failed schema validation

Sample:

.. code-block:: text

Field 'data.attributes.name' (category: 'required'): Input failed schema validation

- Pydantic errors will similarly include a category in their error messages.

Dependencies
------------

- Remove ``pybase62`` as a project dependency.

.. _changelog-0.17.0:

===================

Bugfixes
--------

- Allow package consumers to run with Python optimizations enabled.

This is supported by replacing ``assert`` statements with ``raise AssertionError``.

Changes
-------

- Remove references to web browsers from HTTP 401 Unauthorized responses.

- Reduce I/O with Globus Auth when possible.

* If the action provider is visible to ``"public"``,
introspection requests are allowed without checking tokens.
* If the bearer token is missing, malformed, or is too short or long,
the incoming request is summarily rejected with HTTP 401
without introspecting the token.

.. _changelog-0.16.0:

===================

Features
--------

* Support CORS requests to introspection routes.

Bugfixes
--------

* Prevent ``TypeError``\s from occurring during pydantic error formatting.

This was caused by integer list indexes in pydantic error locations.

Documentation
-------------

* Fix failing documentation builds (locally, and in Read the Docs).
* Enforce reproducible documentation builds using full dependency locking.
* Bump the OpenAPI documentation version and build the documentation.

Development
-----------

* Test documentation builds in GitHub CI.

* Update ``make install`` so it can get developers up and running.
* Document that ``make install`` can get developers up and running.

Dependencies
------------

* Manage test, mypy, and doc dependencies using a consistent framework.
* Introduce a standard command, ``tox run -m update``, that can update dependencies.

.. _changelog-0.15.0: