001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.mcp.v20260728;
018
019import java.util.*;
020
021/**
022 * Resolves the set of scopes required to invoke a specific MCP operation (SEP-2350 per-operation step-up enforcement).
023 *
024 * <p>
025 * The {@code 2026-07-28} resource server enforces per-operation scopes at the POST-parse dispatch point (where the
026 * JSON-RPC method is known); a resolver returning a non-empty set that the caller's granted scopes do not satisfy causes
027 * a {@code 403 insufficient_scope} step-up challenge naming the required scopes.
028 *
029 * <p>
030 * The default resolver is a <b>static per-operation map</b> populated via
031 * {@link McpResourceServerConfig#addOperationScope(String, String, String...)} &mdash; sufficient for 10.0.
032 * This interface is the seam a future <em>dynamic</em> resolver (e.g. one inspecting
033 * {@link McpOperationContext#params() params}) could plug into via
034 * {@link McpResourceServerConfig#setOperationScopeResolver(McpOperationScopeResolver)}; that dynamic capability is
035 * deliberately not built for 10.0.
036 *
037 * @since 10.0.0
038 */
039@FunctionalInterface
040public interface McpOperationScopeResolver {
041
042   /**
043    * Returns the scopes required to invoke the given operation.
044    *
045    * @param ctx The resolved operation (method, name, raw JSON-RPC params).  Never {@code null}.
046    * @return The required scopes.  An empty or {@code null} return means "no per-operation requirement beyond the
047    *    endpoint-wide baseline".
048    */
049   Set<String> requiredScopesFor(McpOperationContext ctx);
050}