/** * Creates a {@link SafeUrlProto} wrapping the given {@code string}. No validation is performed. * * <p>If possible please use the production API in * {@link com.google.common.html.types.SafeUrls} * instead. */ public static SafeUrlProto newSafeUrlProtoForTest(String string) { return SafeUrls.toProto(newSafeUrlForTest(string)); }
/** * Creates a SafeUrl object from the given {@code url}, validating that the input string matches * a pattern of commonly used safe URLs. If {@code url} fails validation, this method returns a * SafeUrl, {@link SafeUrl#INNOCUOUS}, which contains an innocuous string, * {@link SafeUrl#INNOCUOUS_STRING}. * * <p>{@code url} is sanitized as in {@link #sanitize(String)}, additionally permitting the * custom schemes listed in {@code extraAllowedSchemes}. */ public static SafeUrl sanitize(String url, Set<CustomSafeUrlScheme> extraAllowedSchemes) { if (!isSafeUrl(url, extraAllowedSchemes)) { return SafeUrl.INNOCUOUS; } return create(url); }
/** * Creates a SafeUrl object from the given {@code url}, validating that the input string matches * a pattern of commonly used safe URLs. If {@code url} fails validation, this method returns a * SafeUrl, {@link SafeUrl#INNOCUOUS}, which contains an innocuous string, * {@link SafeUrl#INNOCUOUS_STRING}. * * <p>Specifically, {@code url} may be a URL with any of the default safe schemes (http, https, * ftp, mailto), or a relative URL (i.e., a URL without a scheme; specifically, a scheme-relative, * absolute-path-relative, or path-relative URL). * * @see http://url.spec.whatwg.org/#concept-relative-url */ public static SafeUrl sanitize(String url) { return sanitize(url, EMPTY_CUSTOM_SCHEMES); }
/** * Creates a SafeUrl from the given compile-time constant string {@code url}. * * <p>No runtime validation or sanitization is performed on {@code url}; being under application * control, it is simply assumed to comply with the SafeUrl contract. */ public static SafeUrl fromConstant(@CompileTimeConstant final String url) { return create(url); }
/** Converts a {@link SafeUrlProto} into a Soy {@link SanitizedContent} of kind URI. */ public static SanitizedContent fromSafeUrlProto(SafeUrlProto url) { return SanitizedContent.create(SafeUrls.fromProto(url).getSafeUrlString(), ContentKind.URI); }
/** * Sanitizes the given {@code url}, validating that the input string matches a pattern of commonly * used safe URLs. If {@code url} fails validation, this method returns * {@code about:invalid#identifier}, with the given {@code identifier}. The identifier allows * users to trace a sanitized value to the library that performed the sanitization and hence * should be a unique string like "zLibraryNamez". * * <p>Specifically, {@code url} may be a URL with any of the default safe schemes (http, https, * ftp, mailto), or a relative URL (i.e., a URL without a scheme; specifically, a scheme-relative, * absolute-path-relative, or path-relative URL). * * @see http://url.spec.whatwg.org/#concept-relative-url */ public static String sanitizeAsString(String url, @CompileTimeConstant final String identifier) { if (!isSafeUrl(url, EMPTY_CUSTOM_SCHEMES)) { return "about:invalid#" + identifier; } return url; }
/** * Deserializes a SafeUrlProto into a SafeUrl instance. * * <p>Protocol-message forms are intended to be opaque. The fields of the protocol message should * be considered encapsulated and are not intended for direct inspection or manipulation. Protocol * message forms of this type should be produced by {@link #toProto(SafeUrl)} or its * equivalent in other implementation languages. * * <p><b>Important:</b> It is unsafe to invoke this method on a protocol message that has been * received from an entity outside the application's trust domain. Data coming from the browser * is outside the application's trust domain. */ public static SafeUrl fromProto(SafeUrlProto proto) { return create(proto.getPrivateDoNotAccessOrElseSafeUrlWrappedValue()); }
/** Converts a {@link SafeUrlProto} into a Soy {@link SanitizedContent} of kind URI. */ public static SanitizedContent fromSafeUrlProto(SafeUrlProto url) { return SanitizedContent.create(SafeUrls.fromProto(url).getSafeUrlString(), ContentKind.URI); }
/** * Converts a Soy {@link SanitizedContent} of kind URI into a {@link SafeUrlProto}. * * @throws IllegalStateException if this SanitizedContent's content kind is not {@link * ContentKind#URI}. */ public SafeUrlProto toSafeUrlProto() { Preconditions.checkState( getContentKind() == ContentKind.URI, "toSafeUrlProto() only valid for SanitizedContent of kind URI, is: %s", getContentKind()); return SafeUrls.toProto( UncheckedConversions.safeUrlFromStringKnownToSatisfyTypeContract(getContent())); }
/** * Creates a {@code data:text/html} URL whose content is populated from the given * {@code SafeHtml} object. * * <p>The resulting {@code data}-scheme URL's content is UTF-8-encoded, and further encoded using * base-64 transfer encoding. * * @see http://tools.ietf.org/html/rfc2397 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/data_URIs */ public static SafeUrl createHtmlDataUrlBase64(SafeHtml html) { try { String dataUrl = "data:text/html;charset=UTF-8;base64," + BaseEncoding.base64().encode(html.getSafeHtmlString().getBytes("UTF-8")); return create(dataUrl); } catch (UnsupportedEncodingException e) { // Should never happen. We use getBytes(String) instead of getBytes(CharSet) because // there's no java.nio.charset.StandardCharsets in older Android SDKs. throw new RuntimeException(e); } }
/** * Appends a {@code url} value to the {@code background-image} property, if necessary inserting * a leading comma. The {@code url} value will be inserted inside a {@code url} function call. * * <p>The {@code url} is validated as safe, as determined by {@link SafeUrls#sanitize(String)}. * It also percent-encoded to prevent it from interefering with the structure of the surrounding * CSS. * * <p>TODO(mlourenco): The right thing to do would be to CSS-escape but percent-encoding is * easier for now because we don't have a CSS-escaper. As URLs in CSS are likely to point to * domains we control it seems extremely unlikely that this will break anything. * * @see "http://dev.w3.org/csswg/css-backgrounds/#background-image" */ public SafeStyleBuilder backgroundImageAppendUrl(String url) { url = SafeUrls.sanitize(url).getSafeUrlString(); try { url = ESCAPER_BACKGROUND_IMAGE.escape(url); } catch (IllegalArgumentException e) { // Happens if url contains invalid surrogate sequences. url = INNOCUOUS_PROPERTY_STRING; } String urlValue = "url(" + url + ")"; appendToProperty("background-image", urlValue); return this; }
/** * Converts a Soy {@link SanitizedContent} of kind URI into a {@link SafeUrlProto}. * * @throws IllegalStateException if this SanitizedContent's content kind is not {@link * ContentKind#URI}. */ public SafeUrlProto toSafeUrlProto() { Preconditions.checkState( getContentKind() == ContentKind.URI, "toSafeUrlProto() only valid for SanitizedContent of kind URI, is: %s", getContentKind()); return SafeUrls.toProto( UncheckedConversions.safeUrlFromStringKnownToSatisfyTypeContract(getContent())); }
/** * Creates a {@code data:text/html} URL whose content is populated from the given * {@code SafeHtml} object. * * <p>The resulting {@code data}-scheme URL's content is UTF-8-encoded, but the * encoding of non-ASCII characters is done using the standard %xx hex encoding. * * @see http://tools.ietf.org/html/rfc2397 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/data_URIs */ public static SafeUrl createHtmlDataUrl(SafeHtml html) { // Use urlPathSegmentEscaper because all other Escapers convert spaces to "+" instead of "%20", // which are rendered as normal "+"s in the browser instead of being rendered as spaces. String dataUrl = "data:text/html;charset=UTF-8," + UrlEscapers.urlPathSegmentEscaper().escape(html.getSafeHtmlString()); return create(dataUrl); }