/*
 * 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
 *
 *      https://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.commons.xml.secure;

import java.lang.invoke.MethodHandle;
import java.util.Objects;

import javax.xml.XMLConstants;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathFactory;
import javax.xml.xpath.XPathFactoryConfigurationException;
import javax.xml.xpath.XPathFunctionResolver;
import javax.xml.xpath.XPathVariableResolver;

/**
 * Creates new, secure {@link XPathFactory} instances.
 * <p>
 * Beyond the three universal guarantees on {@link org.apache.commons.xml.secure}, URI-fetching XPath 3.1+ functions ({@code doc()}, {@code collection()},
 * {@code unparsed-text()}) are not resolved.
 * </p>
 * <p>
 * The guarantees also cover the document parse behind {@code XPath.evaluate(String, InputSource)} and {@code XPathExpression.evaluate(InputSource)}: the input
 * document is built through a secure, namespace-aware {@link javax.xml.parsers.DocumentBuilder} instead of the engine's internal parser.
 * </p>
 * <p>
 * This class is not itself a {@link XPathFactory}, so it inherits none of the static JAXP factory methods. A caller therefore cannot obtain an unsecured
 * factory through this class by calling a method such as {@code newDefaultInstance()}. The secure factories are instances of a nested, non-public wrapper
 * class.
 * </p>
 *
 * @see org.apache.commons.xml.secure
 */
public final class SecureXPathFactory {

    /**
     * {@link XPathFactory} wrapper that returns a {@link SecureXPath} from {@link #newXPath()}.
     * <p>
     * Required because {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} on the factory governs only the XPath engine: the stock JDK and Apache Xalan
     * implement the {@link org.xml.sax.InputSource}-taking {@code evaluate} entry points by provisioning an internal document parser the feature does not
     * reach. The wrapper performs that document build itself through a secure parser instead; see {@link SecureXPath}.
     * </p>
     */
    private static final class Wrapper extends XPathFactory {

        private final XPathFactory delegate;

        /**
         * Constructs a new instance.
         *
         * @param delegate The delegate to wrap; must not be {@code null}.
         * @throws NullPointerException Thrown if {@code delegate} is {@code null}.
         */
        private Wrapper(final XPathFactory delegate) {
            this.delegate = Objects.requireNonNull(delegate, "delegate");
        }

        @Override
        public boolean getFeature(final String name) throws XPathFactoryConfigurationException {
            return delegate.getFeature(name);
        }

        /**
         * Reports a property of the delegate, the Java 18 {@code XPathFactory.getProperty(String)}.
         * <p>
         * Not marked {@code @Override}: this library compiles against the Java 8 API, where {@link XPathFactory} declares no such method, so the annotation
         * would not compile. At run time on Java 18 or later it overrides the inherited method, which would otherwise answer for the wrapper and hide the
         * delegate's own limits ({@code jdk.xml.xpath*}) behind an {@code UnsupportedOperationException}.
         * </p>
         *
         * @param name The property name.
         * @return the delegate's value for the property.
         */
        public String getProperty(final String name) {
            if (MH_getProperty == null) {
                throw new UnsupportedOperationException("XPathFactory.getProperty(String) requires Java 18 or later");
            }
            return MethodHandleFactory.invokeExact(() -> (String) MH_getProperty.invokeExact(delegate, name), RuntimeException.class);
        }

        @Override
        public boolean isObjectModelSupported(final String objectModel) {
            return delegate.isObjectModelSupported(objectModel);
        }

        @Override
        public XPath newXPath() {
            // newXPath() should never return null for a specification-compliant factory.
            final XPath xpath = delegate.newXPath();
            return xpath == null ? null : new SecureXPath(xpath, overrideDefaultParser());
        }

        /**
         * Tests whether parsers should be instantiated via {@code newInstance()} instead of {@code newDefaultInstance()}.
         * <p>
         * The JDK implementation of {@link XPathFactory} uses the JDK parsers while {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} is unset or
         * {@code false}.
         * </p>
         *
         * @return {@code true} if parsers should be created via {@code newInstance()}.
         */
        private boolean overrideDefaultParser() {
            try {
                return delegate.getFeature(SecureSAXParserFactory.OVERRIDE_DEFAULT_PARSER);
            } catch (final XPathFactoryConfigurationException e) {
                return true;
            }
        }

        @Override
        public void setFeature(final String name, final boolean value) throws XPathFactoryConfigurationException {
            delegate.setFeature(name, value);
        }

        /**
         * Sets a property on the delegate, the Java 18 {@code XPathFactory.setProperty(String, String)}; see {@link #getProperty(String)} for why it carries no
         * {@code @Override}. The {@code jdk.xml.xpath*} limits reached this way are processing limits like any other: an operator may tighten them, and
         * loosening one is reconfiguration.
         *
         * @param name  The property name.
         * @param value The value to set.
         */
        public void setProperty(final String name, final String value) {
            if (MH_setProperty == null) {
                throw new UnsupportedOperationException("XPathFactory.setProperty(String, String) requires Java 18 or later");
            }
            MethodHandleFactory.invokeExact(() -> {
                MH_setProperty.invokeExact(delegate, name, value);
                return null;
            }, RuntimeException.class);
        }

        @Override
        public void setXPathFunctionResolver(final XPathFunctionResolver resolver) {
            delegate.setXPathFunctionResolver(resolver);
        }

        @Override
        public void setXPathVariableResolver(final XPathVariableResolver resolver) {
            delegate.setXPathVariableResolver(resolver);
        }
    }

    /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */
    private static final String JDK_XPATH_FACTORY = "com.sun.org.apache.xpath.internal.jaxp.XPathFactoryImpl";

    private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(XPathFactory.class, "newDefaultInstance");

    /** {@code XPathFactory.getProperty(String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist. */
    private static final MethodHandle MH_getProperty = MethodHandleFactory.findVirtual(XPathFactory.class, "getProperty", String.class, String.class);

    /** {@code XPathFactory.setProperty(String, String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist. */
    private static final MethodHandle MH_setProperty =
            MethodHandleFactory.findVirtual(XPathFactory.class, "setProperty", void.class, String.class, String.class);

    /**
     * Returns a new, secure {@link XPathFactory} of the system-default implementation, supporting the default XPath object model.
     * <p>
     * Obtained from {@code XPathFactory.newDefaultInstance()} where the platform provides it (Java 9 or later), and by instantiating the JDK's built-in
     * implementation directly on Java 8.
     * </p>
     *
     * @return A secure factory.
     * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation.
     * @throws RuntimeException      Thrown if the running platform provides neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for
     *                               example Android).
     */
    public static XPathFactory newDefaultInstance() {
        if (MH_newDefaultInstance != null) {
            return secure(MethodHandleFactory.invokeExact(() -> (XPathFactory) MH_newDefaultInstance.invokeExact(), RuntimeException.class));
        }
        try {
            // Java 8: the method does not exist; instantiate the JDK's built-in default by its class name instead.
            return newInstance(XPathFactory.DEFAULT_OBJECT_MODEL_URI, JDK_XPATH_FACTORY, null);
        } catch (final XPathFactoryConfigurationException e) {
            // newDefaultInstance declares no checked exception; mirror XPathFactory.newInstance(), which reports a default-model miss as a RuntimeException.
            throw new RuntimeException("Neither XPathFactory.newDefaultInstance() nor " + JDK_XPATH_FACTORY + " is available", e);
        }
    }

    /**
     * Returns a new, secure {@link XPathFactory} for the default XPath object model.
     *
     * @return A secure factory.
     * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation.
     * @throws RuntimeException      Thrown if there is a failure in creating an {@link XPathFactory} for the default object model.
     */
    public static XPathFactory newInstance() {
        return secure(XPathFactory.newInstance());
    }

    /**
     * Returns a new, secure {@link XPathFactory} for the given object model.
     *
     * @param uri The underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)}.
     * @return A secure factory.
     * @throws IllegalStateException              Thrown if a required secure setting cannot be applied to the underlying implementation.
     * @throws XPathFactoryConfigurationException Thrown if no implementation of the object model is available.
     * @throws NullPointerException               Thrown if {@code uri} is {@code null}.
     * @throws IllegalArgumentException           Thrown if {@code uri} is empty.
     */
    public static XPathFactory newInstance(final String uri) throws XPathFactoryConfigurationException {
        return secure(XPathFactory.newInstance(uri));
    }

    /**
     * Returns a new, secure {@link XPathFactory} of the given implementation class.
     *
     * @param uri              The underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)}.
     * @param factoryClassName The fully qualified class name of the {@link XPathFactory} implementation.
     * @param classLoader      The class loader used to load the factory class; {@code null} means the current thread's context class loader.
     * @return A secure factory.
     * @throws IllegalStateException              Thrown if a required secure setting cannot be applied to the underlying implementation.
     * @throws XPathFactoryConfigurationException Thrown if {@code factoryClassName} is {@code null}, or if the factory class cannot be loaded or
     *                                            instantiated, or does not support {@code uri}.
     * @throws NullPointerException               Thrown if {@code uri} is {@code null}.
     * @throws IllegalArgumentException           Thrown if {@code uri} is empty.
     */
    public static XPathFactory newInstance(final String uri, final String factoryClassName, final ClassLoader classLoader)
            throws XPathFactoryConfigurationException {
        return secure(XPathFactory.newInstance(uri, factoryClassName, classLoader));
    }

    /**
     * Capability-driven securing for any {@link XPathFactory} on the classpath.
     *
     * <p>The XPath object model mirrors TrAX: the stock JDK and Apache Xalan ship an XPath 1.0 engine with no URI-fetching functions, while Saxon adds the XPath 3.1
     * {@code fn:doc}, {@code fn:collection} and {@code fn:unparsed-text} functions that can reach external resources. Rather than branching on the implementation
     * class, this method probes what the factory supports and adapts:</p>
     * <ul>
     *     <li><strong>Saxon</strong> ({@code net.sf.saxon}): recognized by package prefix and handed to {@link SaxonProvider#configure(XPathFactory)}, so any public
     *         subclass routes to the same recipe as the registered factory. Its URI-fetching
     *         functions and reflection-based extension calls are reachable only through a locked-down Saxon {@code Configuration}, not the standard JAXP knobs; this
     *         is the XPath counterpart of the Saxon exception in {@link SecureTransformerFactory#secure(javax.xml.transform.TransformerFactory)}, kept as a
     *         documented package-prefix exception because the required securing surface is reachable only through a vendor API.</li>
     *     <li><strong>FSP</strong> ({@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING}): required. It is the only knob both the stock JDK and Xalan XPath
     *         engines expose, and switches on their secure-processing limits. {@link XPathFactory} has no attribute API for finer control.</li>
     *     <li><strong>The nested wrapper</strong>: required. FSP governs only the engine, not the parser it provisions internally for the
     *         {@link org.xml.sax.InputSource}-taking {@code evaluate} entry points; the wrapper performs that document build with a secure parser instead, so
     *         the engine never parses.</li>
     * </ul>
     *
     * @param factory The factory to secure.
     * @return A new secure factory or the original factory, as-is, if it is a known Saxon factory.
     * @throws SecureException Thrown if this {@link XPathFactory} or the {@code XPath}s it creates cannot support this feature.
     */
    static XPathFactory secure(final XPathFactory factory) {
        if (SaxonProvider.isSaxon(factory.getClass())) {
            // Saxon: only a locked-down Configuration can close its URI-fetching functions and extension-function surface.
            return SaxonProvider.configure(factory);
        }
        // Required: enables the engine's secure-processing limits; XPathFactory has no attribute API for finer control.
        setFeature(factory, XMLConstants.FEATURE_SECURE_PROCESSING, true);
        // Required: FSP does not reach the parser the engine provisions for InputSource-taking evaluate calls; the wrapper parses those itself.
        return new Wrapper(factory);
    }

    /**
     * Sets a feature on the given factory, throwing a {@link SecureException} if the implementation does not recognize it.
     *
     * @param factory The factory to secure.
     * @param feature The feature to set.
     * @param value   The value to set.
     * @throws SecureException Thrown if this {@link XPathFactory} or the {@code XPath}s it creates cannot support this feature or if {@code feature} is
     *                            {@code null}.
     */
    private static void setFeature(final XPathFactory factory, final String feature, final boolean value) {
        try {
            factory.setFeature(feature, value);
        } catch (final XPathFactoryConfigurationException e) {
            throw SecureException.featureFailed(feature, factory, e);
        }
    }

    private SecureXPathFactory() {
        // static only
    }
}