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