1 package com.atlassian.plugins.rest.common.security.descriptor;
2
3 import java.util.Set;
4
5 /**
6 * Defaults to apply for Cross-Origin Resource Sharing when the
7 * {@link com.atlassian.plugins.rest.common.security.AllowCors}
8 * annotation is used.
9 *
10 * @since 2.6
11 */
12 public interface CorsDefaults
13 {
14 /**
15 * Given an origin which has already passed an {@link #allowsOrigin(String)} check, tests that origin to determine
16 * if it is whitelisted for making a <i>credentialed</i> CORS request, on behalf of a specific user.
17 *
18 * @param uri The origin that has already been allowed. Will never be null
19 * @return True if the origin allows origin requests that contain credentials such as cookies or HTTP auth
20 * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
21 */
22 boolean allowsCredentials(String uri) throws IllegalArgumentException;
23
24 /**
25 * Tests the provided origin to determine if it is whitelisted for making <i>non-credentialed</i> CORS requests.
26 *
27 * @param uri The origin. Will never be null
28 * @return True if the origin provided matches any values in the whitelist
29 * @throws IllegalArgumentException Thrown if the uri is not a valid URL or is null.
30 */
31 boolean allowsOrigin(String uri) throws IllegalArgumentException;
32
33 /**
34 * For the provided origin, returns a set of HTTP headers which the browser may include when making a request.
35 * These headers are only relevant for a CORS preflight check, which is made for non-simple HTTP requests.
36 *
37 * @param uri the origin that has already been allowed. Will never be null
38 * @return set of allowed non-simple (see spec) HTTP headers. Must not be null
39 * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
40 * @see com.atlassian.plugins.rest.common.security.CorsHeaders#ACCESS_CONTROL_ALLOW_HEADERS
41 */
42 Set<String> getAllowedRequestHeaders(String uri) throws IllegalArgumentException;
43
44 /**
45 * For the provided origin, returns a set of HTTP headers which the browser's CORS support can forward on to the
46 * underlying request. For resources accessed via CORS which have non-simple headers they return, only those
47 * headers which are allowed this set will actually be exposed by the browser after the request completes. These
48 * headers are only relevant for simple HTTP requests, which do not require a CORS preflight check.
49 *
50 * @param uri the origin that has already been allowed. Will never be null
51 * @return set of allowed simple (see spec) HTTP headers. Must not be null
52 * @throws IllegalArgumentException Thrown if the uri is not a valid origin or is null.
53 * @see com.atlassian.plugins.rest.common.security.CorsHeaders#ACCESS_CONTROL_EXPOSE_HEADERS
54 */
55 Set<String> getAllowedResponseHeaders(String uri) throws IllegalArgumentException;
56 }