Globus-action-provider-tools

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

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

* The ``now_isoformat`` and ``principal_urn_regex`` names are no longer
publicly exported by the library.

* The ``AuthState`` object now introspects its token when initialized. This
results in more eager error behaviors, as a failed introspect will now
raise an error immediately, rather than on the first usage which triggers
an implicit introspect.

Callers who are explicitly handling invalid token errors, like
``InactiveTokenError``, should put their handling around ``AuthState``
construction rather than around ``AuthState`` attribute and method usage.

* The provided ``FlaskAuthStateBuilder`` used by the provided flask blueprint
now handles ``InactiveTokenError`` and ``InvalidTokenScopesError`` and will
raise an ``AuthenticationError`` if these are encountered.
The error handler in the provided blueprint translates these into
``UnauthorizedRequest`` exceptions, which render as HTTP 401 Unauthorized
responses.

* The ``required_authorizer_expiration_time`` parameter for
``AuthState.get_authorizer_for_scope`` has been removed. In recent
releases it had no effect and emitted deprecation warnings.

.. _changelog-0.20.1:

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

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

* ``AuthState.get_dependent_tokens`` is now deprecated. It will be removed in
a future release.

Features
--------

* A new component, ``ClientFactory`` is now exposed in
``globus_action_provider_tools.client_factory``. This allows users to
customize the transport-layer settings used for Auth and Groups clients which
are constructed by the Action Provider Tools library, and sets initial
parameters for this tuning.

* The number of retries for both client types is reduced to 1 (from an
SDK-default of 5).
* The HTTP timeout is reduced to 30 seconds (from an SDK default of 60s).
* The max sleep duration is reduced to 5 seconds (from an SDK default of
10s).
* ActionProviderConfig, AuthStateBuilder, and AuthState are all customized to
accept a ClientFactory, and to use the client factory for any client
building operations.

.. _changelog-0.20.0:

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

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: