/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.rest.server.auth.oauth;

import static org.apache.juneau.commons.utils.Shorts.*;

import java.io.*;
import java.net.*;
import java.security.*;
import java.time.*;
import java.util.*;
import java.util.function.*;
import java.util.stream.*;

import org.apache.juneau.commons.utils.*;
import org.apache.juneau.rest.server.auth.*;

import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.auth.*;
import com.nimbusds.oauth2.sdk.http.*;
import com.nimbusds.oauth2.sdk.id.*;
import com.nimbusds.oauth2.sdk.token.*;

/**
 * {@link TokenValidator} that validates opaque OAuth 2.0 access tokens via the
 * <a class="doclink" href="https://datatracker.ietf.org/doc/html/rfc7662">RFC 7662</a> Token Introspection
 * endpoint.
 *
 * <p>
 * Wraps Nimbus's {@code TokenIntrospectionRequest} / {@code TokenIntrospectionResponse} for the HTTP
 * round-trip and the JSON parsing.  A {@link TokenCache} (default: bounded LRU cache) short-circuits
 * the round-trip on repeated lookups within the configured TTL window.
 *
 * <h5 class='topic'>Usage</h5>
 *
 * <p class='bjava'>
 *    <jk>var</jk> validator = OAuthIntrospectionValidator.<jsm>create</jsm>()
 *       .introspectionEndpoint(URI.<jsm>create</jsm>(<js>"https://idp.example.com/oauth2/introspect"</js>))
 *       .clientId(<js>"api-server"</js>)
 *       .clientSecret(<js>"..."</js>)
 *       .requiredScopes(<js>"read:orders"</js>)
 *       .build();
 * </p>
 *
 * <h5 class='topic'>Defaults</h5>
 * <ul>
 *    <li>Cache TTL: 5 minutes, capped at 1 hour.
 *    <li>Cache size: 1000 entries.
 *    <li>Required scopes: none (scope enforcement lives on the validator, not the filter).
 * </ul>
 *
 * <h5 class='section'>See Also:</h5>
 * <ul>
 *    <li class='jc'>{@link OAuthFilter}
 *    <li class='jc'>{@link TokenValidator}
 *    <li class='link'><a class="doclink" href="https://datatracker.ietf.org/doc/html/rfc7662">RFC 7662 &mdash; OAuth 2.0 Token Introspection</a>
 * </ul>
 *
 * @since 10.0.0
 */
@SuppressWarnings({
   "java:S1192" // Duplicate string literals are OAuth introspection response field names; intentional
})
public class OAuthIntrospectionValidator implements TokenValidator {

   /** Default cache TTL. */
   public static final Duration DEFAULT_CACHE_TTL = Duration.ofMinutes(5);

   /** Maximum cache TTL. */
   public static final Duration MAX_CACHE_TTL = Duration.ofHours(1);

   /**
    * Static creator.
    *
    * @return A new builder.
    */
   public static Builder create() {
      return new Builder();
   }

   /**
    * Builder for {@link OAuthIntrospectionValidator}.
    */
   public static class Builder {
      private URI introspectionEndpoint;
      private String clientId;
      private Supplier<String> clientSecretSupplier;
      private TokenCache tokenCache;
      private Duration cacheTtl = DEFAULT_CACHE_TTL;
      private final Set<String> requiredScopes = st();
      private final Set<String> expectedAudiences = st();
      private Clock clock = Clock.systemUTC();
      private Consumer<HTTPRequest> httpRequestConfigurator;

      /** Constructor. */
      protected Builder() {}

      /**
       * Sets the introspection endpoint URL.  Required.
       *
       * <p>
       * Each introspection call transmits the client secret (HTTP Basic) and the access token under
       * validation to this endpoint, so the URL must use <js>"https"</js> or target a loopback host; a
       * plaintext transport to a non-loopback host is rejected.
       *
       * @param value The endpoint URL.  Must not be <jk>null</jk> and must use HTTPS or target a loopback host.
       * @return This object.
       */
      public Builder introspectionEndpoint(URI value) {
         introspectionEndpoint = UriUtils.assertSecureOrLoopback(reqnn("value", value));
         return this;
      }

      /**
       * Sets the OAuth client ID used for HTTP Basic auth against the introspection endpoint.
       *
       * @param value The client ID.  Must not be <jk>null</jk> or blank.
       * @return This object.
       */
      public Builder clientId(String value) {
         clientId = reqnb("value", value);
         return this;
      }

      /**
       * Sets the OAuth client secret as a literal string.
       *
       * <p>
       * Mutually exclusive with {@link #clientSecretSupplier(Supplier)}.
       *
       * @param value The client secret.  Must not be <jk>null</jk> or blank.
       * @return This object.
       */
      public Builder clientSecret(String value) {
         reqnb("value", value);
         clientSecretSupplier = () -> value;
         return this;
      }

      /**
       * Sets the OAuth client secret via a supplier (useful for rotating secrets).
       *
       * @param value The supplier.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder clientSecretSupplier(Supplier<String> value) {
         clientSecretSupplier = reqnn("value", value);
         return this;
      }

      /**
       * Sets a custom token cache.  Defaults to a {@link BoundedLruTokenCache} with 1000 entries.
       *
       * @param value The cache.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder tokenCache(TokenCache value) {
         tokenCache = reqnn("value", value);
         return this;
      }

      /**
       * Sets the cache TTL.  Defaults to {@link #DEFAULT_CACHE_TTL 5 minutes}; capped at
       * {@link #MAX_CACHE_TTL 1 hour}.  Capped by the token's own {@code exp} when shorter.
       *
       * @param value The TTL.  Must be positive and not exceed 1 hour.
       * @return This object.
       */
      public Builder cacheTtl(Duration value) {
         reqnn("value", value);
         if (value.isZero() || value.isNegative())
            throw iaex("cacheTtl must be positive");
         if (value.compareTo(MAX_CACHE_TTL) > 0)
            throw iaex("cacheTtl must not exceed 1 hour (was %s)", value);
         cacheTtl = value;
         return this;
      }

      /**
       * Adds required scopes (scope enforcement lives on the validator, not the filter).
       *
       * <p>
       * If any required scope is missing from the introspection response's {@code scope} claim, the
       * validator throws {@link AuthenticationException} with
       * {@code WWW-Authenticate: Bearer error="insufficient_scope"}.
       *
       * @param scopes The required scopes.  Must contain at least one non-blank entry.
       * @return This object.
       */
      public Builder requiredScopes(String... scopes) {
         reqnn("scopes", scopes);
         for (var s : scopes) {
            reqnb("scope", s);
            requiredScopes.add(s);
         }
         return this;
      }

      /**
       * Adds expected audience values (RFC 7662 {@code aud}) that a token must carry to be accepted.
       *
       * <p>
       * When at least one value is configured here (via this method or {@link #resource(String...)}), the
       * introspection response's {@code aud} claim must contain <b>at least one</b> matching value, or the
       * token is rejected as {@code invalid_token} &mdash; even when {@code active=true} and required scopes
       * match.  This binds the token to the resource server it was minted for, so a token issued for a
       * different API cannot be replayed against this one.
       *
       * <p>
       * When left unset (the default), no audience/resource check is performed: today's
       * {@code active} + optional-required-scopes behavior is preserved unchanged.
       *
       * @param values The expected audience values.  Must contain at least one non-blank entry.
       * @return This object.
       */
      public Builder audience(String... values) {
         reqnn("values", values);
         for (var v : values) {
            reqnb("audience", v);
            expectedAudiences.add(v);
         }
         return this;
      }

      /**
       * Adds expected resource-indicator values (RFC 8707).
       *
       * <p>
       * Alias for {@link #audience(String...)}: RFC 8707 resource indicators are echoed back by
       * conformant authorization servers in the same introspection {@code aud} claim as RFC 7662
       * audiences, so both methods add to the same expected-value set.
       *
       * @param values The expected resource values.  Must contain at least one non-blank entry.
       * @return This object.
       */
      public Builder resource(String... values) {
         return audience(values);
      }

      /**
       * Overrides the {@link Clock} used for cache expiry.  Useful in tests.
       *
       * @param value The clock.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder clock(Clock value) {
         clock = reqnn("value", value);
         return this;
      }

      /**
       * Sets a callback that customizes the Nimbus {@link HTTPRequest} before it is sent.
       *
       * <p>
       * This is the escape hatch for custom HTTP behavior (proxies, TLS overrides,
       * timeouts).  The callback is invoked on every introspection call.
       *
       * @param value The configurator callback.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder httpRequestConfigurator(Consumer<HTTPRequest> value) {
         httpRequestConfigurator = reqnn("value", value);
         return this;
      }

      /**
       * Builds the validator.
       *
       * @return A new {@link OAuthIntrospectionValidator}.
       */
      public OAuthIntrospectionValidator build() {
         if (introspectionEndpoint == null)
            throw new IllegalStateException("OAuthIntrospectionValidator requires introspectionEndpoint(...)");
         if (clientId == null)
            throw new IllegalStateException("OAuthIntrospectionValidator requires clientId(...)");
         if (clientSecretSupplier == null)
            throw new IllegalStateException("OAuthIntrospectionValidator requires clientSecret(...) or clientSecretSupplier(...)");
         if (tokenCache == null)
            tokenCache = BoundedLruTokenCache.create();
         return new OAuthIntrospectionValidator(this);
      }
   }

   private final URI introspectionEndpoint;
   private final String clientId;
   private final Supplier<String> clientSecretSupplier;
   private final TokenCache tokenCache;
   private final Duration cacheTtl;
   private final Set<String> requiredScopes;
   private final Set<String> expectedAudiences;
   private final Clock clock;
   private final Consumer<HTTPRequest> httpRequestConfigurator;

   /**
    * Constructor.
    *
    * @param b The builder.
    */
   protected OAuthIntrospectionValidator(Builder b) {
      this.introspectionEndpoint = b.introspectionEndpoint;
      this.clientId = b.clientId;
      this.clientSecretSupplier = b.clientSecretSupplier;
      this.tokenCache = b.tokenCache;
      this.cacheTtl = b.cacheTtl;
      this.requiredScopes = u(cp(b.requiredScopes));
      this.expectedAudiences = u(cp(b.expectedAudiences));
      this.clock = b.clock;
      this.httpRequestConfigurator = b.httpRequestConfigurator;
   }

   /**
    * Returns the configured introspection endpoint URL.
    *
    * @return The endpoint.
    */
   public URI getIntrospectionEndpoint() {
      return introspectionEndpoint;
   }

   /**
    * Returns the configured OAuth client ID.
    *
    * @return The client ID.
    */
   public String getClientId() {
      return clientId;
   }

   /**
    * Returns the cache TTL.
    *
    * @return The TTL.
    */
   public Duration getCacheTtl() {
      return cacheTtl;
   }

   /**
    * Returns the required-scope set.
    *
    * @return An unmodifiable view.
    */
   public Set<String> getRequiredScopes() {
      return requiredScopes;
   }

   /**
    * Returns the configured expected audience / resource-indicator set.
    *
    * @return An unmodifiable view.  Empty when no audience/resource binding is configured (default).
    */
   public Set<String> getExpectedAudiences() {
      return expectedAudiences;
   }

   /**
    * Returns the underlying token cache.
    *
    * @return The token cache.
    */
   public TokenCache getTokenCache() {
      return tokenCache;
   }

   @Override /* Overridden from TokenValidator */
   public Principal validate(String token) throws AuthenticationException {
      reqnb("token", token);
      var cached = tokenCache.getPrincipal(token);
      if (cached.isPresent())
         return cached.get();
      return introspect(token);
   }

   private Principal introspect(String token) throws AuthenticationException {
      var clientAuth = new ClientSecretBasic(new ClientID(clientId),
         new com.nimbusds.oauth2.sdk.auth.Secret(clientSecretSupplier.get()));
      AccessToken accessToken = new BearerAccessToken(token);
      var req = new TokenIntrospectionRequest(introspectionEndpoint, clientAuth, accessToken);
      var http = req.toHTTPRequest();
      if (httpRequestConfigurator != null)
         httpRequestConfigurator.accept(http);

      com.nimbusds.oauth2.sdk.http.HTTPResponse httpResp;
      try {
         httpResp = http.send();
      } catch (IOException e) {
         throw new AuthenticationException(e, "OAuth introspection HTTP call failed")
            .wwwAuthenticate(bearerError("invalid_token", "introspection unreachable"));
      }
      TokenIntrospectionResponse resp;
      try {
         resp = TokenIntrospectionResponse.parse(httpResp);
      } catch (ParseException e) {
         throw new AuthenticationException(e, "OAuth introspection response could not be parsed")
            .wwwAuthenticate(bearerError("invalid_token", "introspection parse failed"));
      }
      if (!resp.indicatesSuccess())
         throw new AuthenticationException("OAuth introspection error: " + resp.toErrorResponse().getErrorObject().getCode())
            .wwwAuthenticate(bearerError("invalid_token", resp.toErrorResponse().getErrorObject().getCode()));
      var success = resp.toSuccessResponse();
      if (!success.isActive())
         throw new AuthenticationException("OAuth token inactive")
            .wwwAuthenticate(bearerError("invalid_token", "token inactive"));
      enforceAudience(success);
      var scopes = extractScopes(success);
      enforceRequiredScopes(scopes);
      var claims = buildClaims(success, scopes);
      var subject = success.getSubject() != null ? success.getSubject().getValue() : "<no-sub>";
      var principal = new ClaimsPrincipal(subject, claims);
      var ttl = resolveTtl(success);
      tokenCache.putPrincipal(token, principal, ttl);
      return principal;
   }

   private Set<String> extractScopes(TokenIntrospectionSuccessResponse success) {
      var s = success.getScope();
      if (s == null)
         return Collections.emptySet();
      return s.toStringList().stream()
         .filter(v -> v != null && !v.isBlank()) // HTT: v==null branch unreachable; Nimbus Scope.toStringList() never returns null entries
         .collect(Collectors.toCollection(LinkedHashSet::new));
   }

   /**
    * Rejects the token when an expected audience/resource set is configured and the introspection
    * response's {@code aud} claim contains none of the expected values.  No-op when
    * {@link #expectedAudiences} is empty (no bind configured).
    */
   private void enforceAudience(TokenIntrospectionSuccessResponse success) throws AuthenticationException {
      if (expectedAudiences.isEmpty())
         return;
      var tokenAudiences = success.getAudience();
      var matched = tokenAudiences != null && tokenAudiences.stream()
         .map(Audience::getValue)
         .anyMatch(expectedAudiences::contains);
      if (!matched)
         throw new AuthenticationException("OAuth token audience/resource mismatch")
            .wwwAuthenticate(bearerError("invalid_token", "audience mismatch"));
   }

   private void enforceRequiredScopes(Set<String> tokenScopes) throws AuthenticationException {
      for (var req : requiredScopes) {
         if (!tokenScopes.contains(req))
            throw new AuthenticationException("Required scope missing: " + req)
               .wwwAuthenticate(bearerError("insufficient_scope", "scope " + req + " missing"));
      }
   }

   private Map<String,Object> buildClaims(TokenIntrospectionSuccessResponse success, Set<String> scopes) {
      var claims = new LinkedHashMap<String,Object>(success.toJSONObject());
      if (!scopes.isEmpty())
         claims.put("scope", new ArrayList<>(scopes));
      return claims;
   }

   private Duration resolveTtl(TokenIntrospectionSuccessResponse success) {
      var ttl = cacheTtl;
      var exp = success.getExpirationTime();
      if (exp != null) {
         var until = Duration.between(clock.instant(), exp.toInstant());
         if (until.isNegative() || until.isZero())
            until = Duration.ofSeconds(1);
         if (until.compareTo(ttl) < 0)
            ttl = until;
      }
      return ttl;
   }

   private static String bearerError(String code, String description) {
      return "Bearer error=\"" + code + "\", error_description=\"" + description.replace('"', ' ') + "\"";
   }
}