Package co.ankatech.ankasecure.sdk.auth

Interface TokenSource

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CachingTokenSource, FederatedAssertionTokenSource, NativeSecretTokenSource, PrivateKeyJwtTokenSource, SuppliedTokenSource
public interface TokenSource extends AutoCloseable
The one seam between "how this workload proves who it is" and "everything the SDK does".

Every operations group depends on this interface rather than on the transport, so no part of the SDK above this line knows - or can branch on - which credential kind produced the token. That is the property the whole design exists to buy: a workload authenticating through Auth0 and one authenticating with an ANKASecure client secret run identical code above this interface.

Binding is a side effect of minting, and that is deliberate

accessToken() does not merely return a value: minting a token also binds it to the transport this source was built against. Callers that need a live token on the wire therefore call accessToken() for its effect and may ignore the return. The alternative - handing the transport a supplier that mints lazily inside request construction - was rejected because a minting failure would then surface from the middle of an HTTP call as a transport error, and an operator reading "connection failed" would go and check the network rather than their credential.

Lifetime

A source that can re-mint must retain whatever it re-mints from, so an implementation may hold a credential for its lifetime. close() releases it. Implementations zeroize what the JVM lets them zeroize and never log, persist or place a credential in an exception message.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    accessToken()
    Returns a token that is valid now, minting one if none is cached or the cached one is inside the refresh window, and binding whatever it returns to the transport.
    void
    close()
    Releases any credential this source retains for re-minting, and discards the cached token.
    default Instant
    currentTokenExpiry()
    When the token currently in force expires, if this source knows.
    void
    invalidate()
    Discards the cached token and unbinds it from the transport, so the next accessToken() mints a fresh one.
    AuthMechanism
    mechanism()
    Names the credential kind this source presents.

  • Method Details

    • accessToken

      String accessToken() throws AnkaSecureSdkException
      Returns a token that is valid now, minting one if none is cached or the cached one is inside the refresh window, and binding whatever it returns to the transport.

      Concurrent callers of a stale source do not stampede the token endpoint: exactly one mints and the rest observe its result.

      Returns:
      the ANKASecure access token; never null and never blank
      Throws:
      AnkaSecureSdkException - if a token cannot be obtained. A failure leaves any previously cached token untouched rather than poisoning the cache with the failure.

    • invalidate

      void invalidate()
      Discards the cached token and unbinds it from the transport, so the next accessToken() mints a fresh one.

      This is what a caller does on a 401 it did not expect. A token can be refused while still unexpired locally - revoked at logout, superseded by a revocation epoch, or invalidated by a role change - and the local exp claim cannot see any of that.

      Idempotent, and safe to call on a source that has never minted.

    • mechanism

      AuthMechanism mechanism()
      Names the credential kind this source presents. Diagnostic only; nothing branches on it.
      Returns:
      the mechanism; never null

    • currentTokenExpiry

      default Instant currentTokenExpiry()
      When the token currently in force expires, if this source knows.

      Known for any source that minted its own token, because the issuer states the lifetime in the same response that carried it. Absent for a token the caller supplied from elsewhere - that one arrived with no accompanying statement, and this SDK does not read a token's claims to find out.

      Returns:
      the expiry, or null when nothing is cached or the lifetime is not known

    • close

      void close()
      Releases any credential this source retains for re-minting, and discards the cached token.

      Idempotent. Overridden to drop the checked exception AutoCloseable declares, so a try-with-resources over a token source needs no catch clause.

      Specified by:
      close in interface AutoCloseable