diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e50e0b..1326881 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,10 @@ takes it when asked for: `shopify_api = "=1.0.0-rc.1"`. A rewrite around operations checked at compile time. See [MIGRATION.md](MIGRATION.md). +### Since 1.0.0-rc.3 + +- Added: an admin origin, for a local stand-in of Shopify (local-storefront's `http://localhost:9292`), a mock server or a proxy: `ShopifyBuilder::admin_origin` and `ShopifyApp::with_admin_origin` send the requests built from the shop's domain (GraphQL, the client credentials grant, refresh tokens, the code and token exchanges) and the install link of `authorization_url` to that origin instead of `https://{shop}`. Only the scheme, the host and the port change: the paths are Shopify's, and the shop stays the identity of the session tokens, the tokens and the errors. The requests sent there name the shop in `X-Forwarded-Host`, and the install link in a last `shop` parameter. `ShopifyApp::builder` and `ShopifyApp::client` pass the origin on to their clients; `Shopify::admin_origin` and `ShopifyApp::admin_origin` read it. `AdminOrigin` checks it: an absolute `https://` URL, or `http://` to `localhost`, `127.0.0.1` or `[::1]` only, with no path (a trailing `/` aside), query string, fragment or user; anything else is an `Error::Config` that does not show what was given. Without it, nothing changes. + ### Since 1.0.0-rc.2 - Changed: `graphql!` downloads a schema file only with the new `schema-download` feature (in `full` too), off by default. Without it the macro has no HTTP client (28 crates in its build instead of 55) and a build never uses the network: a file of the version the crate asks for is read as it is, and a missing or outdated one is a compile error that names `shopify-api schema download`. With it, `CARGO_NET_OFFLINE=true` also keeps the build offline. diff --git a/README.md b/README.md index dc0627a..0ae3a2e 100644 --- a/README.md +++ b/README.md @@ -376,6 +376,43 @@ assert_eq!(my_code_under_test(&shopify).await?, "Test shop"); assert_eq!(mock.graphql_requests()[0].operation_name.as_deref(), Some("Shop")); ``` +## A local Shopify: `admin_origin` + +`admin_origin` sends the requests built from the shop's domain to another +origin than `https://{shop}`: a local stand-in of Shopify such as +[local-storefront](https://github.com/0xtlt/local-storefront), a mock server, +or a proxy. Only the scheme, the host and the port change: the paths are +Shopify's, and the shop stays the shop (the session tokens verified, the +tokens obtained, the errors). + +```rust,ignore +use shopify_api::Shopify; +use shopify_api::oauth::ShopifyApp; + +// A client: its GraphQL requests, and those of its client credentials or refresh token. +let shopify = Shopify::builder("local-supply-co.myshopify.com") + .admin_origin("http://localhost:9292") + .access_token(token) + .build()?; + +// An app (feature `oauth`): its code and token exchanges, its install links, +// and every client its `builder` and `client` make. +let mut app = ShopifyApp::new(client_id, client_secret); +if let Ok(origin) = std::env::var("LSF_URL") { + app = app.with_admin_origin(origin)?; +} +``` + +The origin is `https://host[:port]`, or `http://` to `localhost`, `127.0.0.1` +or `[::1]` only, so that an access token never leaves the machine in clear +text; it has no path (a trailing `/` aside), query string, fragment or user. +`build` and `with_admin_origin` refuse anything else with `Error::Config`, +which does not show what was given. The requests sent to the origin name the +shop in `X-Forwarded-Host`, and the install link in a last `shop` parameter, +so that one origin can serve several shops. The addresses an answer gives (a +bulk operation's results, a staged upload's target) are used as they come. +Without `admin_origin`, nothing changes. + ## Features | Feature | | diff --git a/crates/shopify_api/src/auth.rs b/crates/shopify_api/src/auth.rs index df8e56f..1889517 100644 --- a/crates/shopify_api/src/auth.rs +++ b/crates/shopify_api/src/auth.rs @@ -9,8 +9,9 @@ use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; use tokio::sync::{Mutex, OwnedMutexGuard}; +use crate::origin::admin_url; use crate::transport::{BoxFuture, HttpRequest, Method, Transport}; -use crate::{Error, OAuthErrorCode, Result, ShopDomain}; +use crate::{AdminOrigin, Error, OAuthErrorCode, Result, ShopDomain}; /// How a [`Shopify`](crate::Shopify) client gets its access token. /// @@ -317,8 +318,22 @@ impl TokenResponse { } } -fn token_url(shop: &ShopDomain) -> String { - format!("https://{shop}/admin/oauth/access_token") +/// The token endpoint of `shop`, at `origin` when there is one. +fn token_url(shop: &ShopDomain, origin: Option<&AdminOrigin>) -> String { + admin_url(shop, origin, "/admin/oauth/access_token") +} + +/// `request`, saying which shop it is for when it goes to an admin origin +/// instead of the shop's own host: one origin may serve several shops. +pub(crate) fn for_shop( + request: HttpRequest, + shop: &ShopDomain, + origin: Option<&AdminOrigin>, +) -> HttpRequest { + match origin { + Some(_) => request.with_header("X-Forwarded-Host", shop.as_str()), + None => request, + } } /// How the fields of a token request travel. @@ -330,20 +345,22 @@ pub(crate) enum Encoding { Json, } -/// Asks the token endpoint of `shop` for a token. A refusal says what -/// Shopify answered, never what was sent. +/// Asks the token endpoint of `shop` for a token, at `origin` when there is +/// one. A refusal says what Shopify answered, never what was sent. pub(crate) async fn request_token( transport: &dyn Transport, shop: &ShopDomain, + origin: Option<&AdminOrigin>, user_agent: &str, encoding: Encoding, fields: &[(&str, &str)], ) -> Result { - let url = token_url(shop); + let url = token_url(shop, origin); let request = HttpRequest::new(Method::Post, &url) .with_header("Accept", "application/json") .with_header("User-Agent", user_agent) .with_timeout(Duration::from_secs(30)); + let request = for_shop(request, shop, origin); let request = match encoding { Encoding::Form => request.with_form(fields), Encoding::Json => { @@ -413,6 +430,8 @@ const FAILURE_HOLD: Duration = Duration::from_secs(5); pub(crate) struct Endpoint { pub transport: Arc, pub shop: ShopDomain, + /// Where the requests built from `shop` go instead of `https://{shop}`. + pub admin_origin: Option, pub user_agent: String, } @@ -643,6 +662,7 @@ async fn obtain(kind: &Kind, state: &State, endpoint: &Endpoint) -> Result Result) -> ShopifyBuilder { ShopifyBuilder { shop: shop.as_ref().to_string(), + admin_origin: None, auth: None, api_version: None, transport: None, @@ -76,6 +79,12 @@ impl Shopify { &self.shared.endpoint.shop } + /// The origin requests go to instead of `https://{shop}`, when + /// [`ShopifyBuilder::admin_origin`] set one. + pub fn admin_origin(&self) -> Option<&AdminOrigin> { + self.shared.endpoint.admin_origin.as_ref() + } + /// The version requests go to: the one pinned with /// [`ShopifyBuilder::api_version`], else [`ApiVersion::DEFAULT`]. /// @@ -106,11 +115,14 @@ impl Shopify { } } - /// `https://{shop}/admin/api/{version}/graphql.json`. + /// `https://{shop}/admin/api/{version}/graphql.json`, or the same path at + /// the [admin origin](ShopifyBuilder::admin_origin) when there is one. pub fn graphql_url(&self, version: ApiVersion) -> String { - format!( - "https://{}/admin/api/{version}/graphql.json", - self.shared.endpoint.shop + let endpoint = &self.shared.endpoint; + admin_url( + &endpoint.shop, + endpoint.admin_origin.as_ref(), + &format!("/admin/api/{version}/graphql.json"), ) } @@ -320,6 +332,9 @@ fn jitter_fraction() -> f64 { #[must_use] pub struct ShopifyBuilder { shop: String, + /// Checked when it is given, refused by `build`. Set by + /// `ShopifyApp::builder` too, with the app's. + pub(crate) admin_origin: Option>, auth: Option, api_version: Option, /// Set by `ShopifyApp::builder` too, with the app's. @@ -335,6 +350,7 @@ impl std::fmt::Debug for ShopifyBuilder { formatter .debug_struct("ShopifyBuilder") .field("shop", &self.shop) + .field("admin_origin", &self.admin_origin) .field("auth", &self.auth) .field("api_version", &self.api_version) .field("retry", &self.retry) @@ -376,6 +392,51 @@ impl ShopifyBuilder { self } + /// Sends the requests built from the shop's domain to `origin` instead of + /// `https://{shop}`: the GraphQL requests, and the token requests of the + /// client credentials grant and of refresh tokens. Only the scheme, the + /// host and the port change; the shop stays the shop, and each request + /// names it in `X-Forwarded-Host`. For a local stand-in of Shopify, such + /// as [local-storefront](https://github.com/0xtlt/local-storefront), or a + /// proxy. + /// + /// `origin` is an [`AdminOrigin`]: `https://host[:port]`, or `http://` + /// to `localhost`, `127.0.0.1` or `[::1]` only. [`build`](Self::build) + /// fails with [`Error::Config`] when it is not one. Without it, the + /// requests go to `https://{shop}`. + /// + /// ``` + /// # #[cfg(any(feature = "rustls", feature = "native-tls"))] + /// # { + /// use shopify_api::{ApiVersion, Shopify}; + /// + /// // The Admin API of local-storefront: the token picks the shop. + /// let shopify = Shopify::builder("local-supply-co.myshopify.com") + /// .admin_origin("http://localhost:9292") + /// .access_token("shpat_…") + /// .build()?; + /// assert_eq!( + /// shopify.graphql_url(ApiVersion::V2026_10), + /// "http://localhost:9292/admin/api/2026-10/graphql.json" + /// ); + /// assert_eq!(shopify.shop().as_str(), "local-supply-co.myshopify.com"); + /// + /// // Not in clear text off this machine. + /// assert!( + /// Shopify::builder("my-shop") + /// .admin_origin("http://lsf.example.com") + /// .access_token("shpat_…") + /// .build() + /// .is_err() + /// ); + /// # } + /// # Ok::<(), shopify_api::Error>(()) + /// ``` + pub fn admin_origin(mut self, origin: impl AsRef) -> Self { + self.admin_origin = Some(AdminOrigin::new(origin.as_ref())); + self + } + pub fn retry(mut self, retry: RetryPolicy) -> Self { self.retry = retry; self @@ -401,6 +462,7 @@ impl ShopifyBuilder { pub fn build(self) -> Result { let shop = ShopDomain::new(&self.shop)?; + let admin_origin = self.admin_origin.transpose()?; let auth = self.auth.ok_or_else(|| { Error::auth("no credentials: call `access_token`, `client_credentials` or `auth`") })?; @@ -413,6 +475,7 @@ impl ShopifyBuilder { endpoint: Arc::new(Endpoint { transport, shop, + admin_origin, user_agent: self.user_agent, }), tokens: Tokens::new(auth, self.token_store, self.refresh_leeway), @@ -512,6 +575,58 @@ mod tests { ); } + #[cfg(feature = "testing")] + #[test] + fn an_admin_origin_moves_the_graphql_url_only() { + let shopify = Shopify::builder("my-shop") + .admin_origin("http://localhost:9292/") + .access_token("t") + .transport(crate::testing::MockTransport::new()) + .build() + .unwrap(); + assert_eq!( + shopify.graphql_url(ApiVersion::V2026_10), + "http://localhost:9292/admin/api/2026-10/graphql.json" + ); + assert_eq!(shopify.shop().as_str(), "my-shop.myshopify.com"); + assert_eq!( + shopify.admin_origin().map(AdminOrigin::as_str), + Some("http://localhost:9292") + ); + assert!(format!("{shopify:?}").contains("http://localhost:9292")); + + let without = Shopify::builder("my-shop") + .access_token("t") + .transport(crate::testing::MockTransport::new()) + .build() + .unwrap(); + assert_eq!(without.admin_origin(), None); + assert_eq!( + without.graphql_url(ApiVersion::V2026_10), + "https://my-shop.myshopify.com/admin/api/2026-10/graphql.json" + ); + } + + #[cfg(feature = "testing")] + #[test] + fn building_refuses_an_invalid_admin_origin() { + for origin in [ + "http://lsf.example.com", + "http://localhost:9292/admin", + "localhost:9292", + "http://user:shpat_secret@localhost:9292", + ] { + let builder = Shopify::builder("my-shop") + .admin_origin(origin) + .access_token("t") + .transport(crate::testing::MockTransport::new()); + assert!(!format!("{builder:?}").contains("shpat_secret")); + let error = builder.build().unwrap_err(); + assert!(matches!(error, Error::Config(_)), "{origin}: {error:?}"); + assert!(!error.to_string().contains("shpat_secret")); + } + } + #[test] fn building_needs_a_shop_and_credentials() { assert!(matches!( diff --git a/crates/shopify_api/src/error.rs b/crates/shopify_api/src/error.rs index ba7a0ab..be4f7c3 100644 --- a/crates/shopify_api/src/error.rs +++ b/crates/shopify_api/src/error.rs @@ -951,8 +951,14 @@ mod tests { fn token_endpoint(status: u16, body: String) -> Error { let shop = crate::ShopDomain::new("a-shop").unwrap(); let transport = Answer(status, body); - let future = - crate::auth::request_token(&transport, &shop, "test", crate::auth::Encoding::Form, &[]); + let future = crate::auth::request_token( + &transport, + &shop, + None, + "test", + crate::auth::Encoding::Form, + &[], + ); tokio::runtime::Builder::new_current_thread() .build() .unwrap() @@ -1172,6 +1178,15 @@ mod tests { "Config", Error::Config("the HTTP client does not start".to_string()), )); + for origin in [ + format!("http://me:{TOKEN}@localhost:9292"), + format!("http://localhost:9292/?token={TOKEN}"), + format!("http://{TOKEN}.example.com"), + TOKEN.to_string(), + SIGNED_URL.to_string(), + ] { + errors.push(("Config", crate::AdminOrigin::new(&origin).unwrap_err())); + } #[cfg(feature = "webhooks")] { use base64::Engine; diff --git a/crates/shopify_api/src/graphql.rs b/crates/shopify_api/src/graphql.rs index 15755f7..3217008 100644 --- a/crates/shopify_api/src/graphql.rs +++ b/crates/shopify_api/src/graphql.rs @@ -142,6 +142,8 @@ impl Shopify { .with_header("User-Agent", &self.shared.endpoint.user_agent) .with_header("X-Shopify-Access-Token", &token) .with_body(body.clone()); + let request = + crate::auth::for_shop(request, &endpoint.shop, endpoint.admin_origin.as_ref()); let may_retry = retries < self.retry.max_retries(); let response = match self.shared.endpoint.transport.send(request).await { Ok(response) => response, diff --git a/crates/shopify_api/src/lib.rs b/crates/shopify_api/src/lib.rs index 61bc13b..1005158 100644 --- a/crates/shopify_api/src/lib.rs +++ b/crates/shopify_api/src/lib.rs @@ -67,6 +67,7 @@ mod client; mod decode; mod error; mod graphql; +mod origin; mod pagination; pub mod schema; mod shop; @@ -90,6 +91,7 @@ pub use graphql::{ Cost, GraphqlError, InputObject, IntoVariable, InvalidValueReason, Location, Maybe, Operation, OperationKind, RawResponse, Response, ThrottleStatus, UserError, VariableType, }; +pub use origin::AdminOrigin; pub use pagination::Page; pub use shop::ShopDomain; pub use version::ApiVersion; diff --git a/crates/shopify_api/src/oauth.rs b/crates/shopify_api/src/oauth.rs index 6251ce4..b5f98a3 100644 --- a/crates/shopify_api/src/oauth.rs +++ b/crates/shopify_api/src/oauth.rs @@ -59,9 +59,11 @@ use serde_json::Value; use sha2::Sha256; use crate::auth::{Encoding, request_token}; +use crate::origin::admin_url; use crate::transport::{Transport, default_transport}; use crate::{ - Auth, Error, Result, ShopDomain, Shopify, ShopifyBuilder, TokenData, TokenStore, USER_AGENT, + AdminOrigin, Auth, Error, Result, ShopDomain, Shopify, ShopifyBuilder, TokenData, TokenStore, + USER_AGENT, }; /// How far the `timestamp` of a signed query may be from now, as Shopify's libraries allow. @@ -98,6 +100,7 @@ pub struct ShopifyApp { transport: Option>, token_store: Option>, user_agent: String, + admin_origin: Option, } impl std::fmt::Debug for ShopifyApp { @@ -106,6 +109,7 @@ impl std::fmt::Debug for ShopifyApp { .debug_struct("ShopifyApp") .field("client_id", &self.client_id) .field("token_store", &self.token_store.is_some()) + .field("admin_origin", &self.admin_origin) .finish_non_exhaustive() } } @@ -365,6 +369,7 @@ impl ShopifyApp { transport: default_transport().ok(), token_store: None, user_agent: USER_AGENT.to_string(), + admin_origin: None, } } @@ -388,6 +393,43 @@ impl ShopifyApp { self } + /// Sends the requests built from a shop's domain to `origin` instead of + /// `https://{shop}`: the token requests of the code and token exchanges, + /// the install link of [`authorization_url`](Self::authorization_url), and + /// every request of the clients it [builds](Self::builder) (see + /// [`ShopifyBuilder::admin_origin`]). The shop stays the shop: the session + /// tokens it verifies are still those of `https://{shop}`. + /// + /// Fails with [`Error::Config`] when `origin` is not an [`AdminOrigin`]: + /// `https://host[:port]`, or `http://` to `localhost`, `127.0.0.1` or + /// `[::1]` only. + /// + /// ``` + /// use shopify_api::ShopDomain; + /// use shopify_api::oauth::{AuthorizationRequest, ShopifyApp}; + /// + /// // local-storefront's admin, OAuth and token exchange. + /// let app = ShopifyApp::new("client-id", "client-secret") + /// .with_admin_origin("http://localhost:9292")?; + /// let shop = ShopDomain::new("local-supply-co")?; + /// let link = app.authorization_url( + /// &shop, + /// &AuthorizationRequest::new("http://localhost:3000/auth/callback", "state"), + /// ); + /// assert!(link.starts_with("http://localhost:9292/admin/oauth/authorize?client_id=client-id&")); + /// assert!(link.ends_with("&shop=local-supply-co.myshopify.com")); + /// # Ok::<(), shopify_api::Error>(()) + /// ``` + pub fn with_admin_origin(mut self, origin: impl AsRef) -> Result { + self.admin_origin = Some(AdminOrigin::new(origin.as_ref())?); + Ok(self) + } + + /// The origin set with [`with_admin_origin`](Self::with_admin_origin), if any. + pub fn admin_origin(&self) -> Option<&AdminOrigin> { + self.admin_origin.as_ref() + } + pub fn client_id(&self) -> &str { &self.client_id } @@ -408,12 +450,13 @@ impl ShopifyApp { // ─── Clients ───────────────────────────────────────────────────── - /// A builder of a client of `shop` that uses the app's transport and - /// token store. + /// A builder of a client of `shop` that uses the app's transport, token + /// store and admin origin. pub fn builder(&self, shop: &ShopDomain) -> ShopifyBuilder { let mut builder = Shopify::builder(shop).user_agent(&self.user_agent); builder.transport.clone_from(&self.transport); builder.token_store.clone_from(&self.token_store); + builder.admin_origin = self.admin_origin.clone().map(Ok); builder } @@ -432,6 +475,10 @@ impl ShopifyApp { // ─── Install link and callback ─────────────────────────────────── /// The address that asks the merchant to install the app. + /// + /// With an [admin origin](Self::with_admin_origin), it is at that origin, + /// the browser's way to the stand-in of Shopify, and names the shop in a + /// last `shop` parameter, which the host no longer says. pub fn authorization_url(&self, shop: &ShopDomain, request: &AuthorizationRequest) -> String { let scope = request.scopes.join(","); let mut params = vec![ @@ -443,10 +490,14 @@ impl ShopifyApp { if request.online { params.push(("grant_options[]", "per-user")); } + if self.admin_origin.is_some() { + params.push(("shop", shop.as_str())); + } let query = serde_urlencoded::to_string(¶ms) .unwrap_or_default() .replace('+', "%20"); - format!("https://{shop}/admin/oauth/authorize?{query}") + let path = format!("/admin/oauth/authorize?{query}"); + admin_url(shop, self.admin_origin.as_ref(), &path) } /// Exchanges the `code` of a verified callback for a token. @@ -483,6 +534,7 @@ impl ShopifyApp { request_token( self.transport()?, shop, + self.admin_origin.as_ref(), &self.user_agent, Encoding::Json, &fields, @@ -766,6 +818,7 @@ impl ShopifyApp { request_token( self.transport()?, session.shop(), + self.admin_origin.as_ref(), &self.user_agent, Encoding::Json, &fields, @@ -1303,4 +1356,65 @@ mod tests { &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback&state=nonce%201&grant_options%5B%5D=per-user" ); } + + #[test] + fn an_admin_origin_moves_the_install_link_and_names_the_shop() { + let shop = ShopDomain::new("my-shop").unwrap(); + let app = app().with_admin_origin("http://localhost:9292/").unwrap(); + assert_eq!( + app.admin_origin().map(AdminOrigin::as_str), + Some("http://localhost:9292") + ); + let link = app.authorization_url( + &shop, + &AuthorizationRequest::new("http://localhost:3000/auth/callback", "s") + .scopes(["read_products"]) + .online(), + ); + assert_eq!( + link, + "http://localhost:9292/admin/oauth/authorize?client_id=client-id&scope=read_products\ + &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback&state=s&grant_options%5B%5D=per-user\ + &shop=my-shop.myshopify.com" + ); + // The clients it builds go there too, for the same shop. + struct Unused; + impl Transport for Unused { + fn send( + &self, + _: crate::transport::HttpRequest, + ) -> crate::transport::BoxFuture< + '_, + std::result::Result< + crate::transport::HttpResponse, + crate::transport::TransportError, + >, + > { + Box::pin(async { Err(crate::transport::TransportError::new("not sent")) }) + } + } + let client = app + .clone() + .with_transport(Unused) + .builder(&shop) + .access_token("t") + .build() + .unwrap(); + assert_eq!(client.admin_origin(), app.admin_origin()); + assert_eq!(client.shop(), &shop); + // A session token is still that of the shop's own admin. + let now = 1_800_000_000; + let token = app.sign_session_token(&claims(now)); + assert_eq!( + app.verify_session_token_at(&token, at(now)).unwrap().shop(), + &shop + ); + + for invalid in ["http://lsf.example.com", "http://localhost:9292/admin"] { + assert!(matches!( + ShopifyApp::new("client-id", "client-secret").with_admin_origin(invalid), + Err(Error::Config(_)) + )); + } + } } diff --git a/crates/shopify_api/src/origin.rs b/crates/shopify_api/src/origin.rs new file mode 100644 index 0000000..3ec9b04 --- /dev/null +++ b/crates/shopify_api/src/origin.rs @@ -0,0 +1,339 @@ +//! Where the admin of a shop is reached: `https://{shop}`, or another origin +//! that stands in for it, such as a local fake of Shopify. + +use std::fmt; +use std::net::{Ipv4Addr, Ipv6Addr}; +use std::str::FromStr; + +use crate::{Error, ShopDomain}; + +/// The scheme, host and port that the addresses built from a shop's domain go +/// to instead of `https://{shop}`: a local stand-in of Shopify, such as +/// [local-storefront](https://github.com/0xtlt/local-storefront), a mock +/// server, or a proxy. +/// +/// Only the origin changes. The paths stay Shopify's +/// (`/admin/api/{version}/graphql.json`, `/admin/oauth/access_token`, +/// `/admin/oauth/authorize`), and the shop stays the shop: the session tokens +/// verified, the tokens obtained and the errors are still those of +/// `{shop}.myshopify.com`. The requests sent to the origin say which shop they +/// are for in `X-Forwarded-Host`, and the install link in its `shop` +/// parameter, so that one origin can serve several shops. +/// +/// It is an absolute `https://` or `http://` URL: a host and an optional port, +/// no path (a trailing `/` aside), no query string, fragment, user or +/// password. `http://` is taken for a loopback host only, `localhost`, +/// `127.0.0.1` or `[::1]`, so that an access token never travels in clear +/// text off the machine. +/// +/// ``` +/// use shopify_api::AdminOrigin; +/// +/// assert_eq!(AdminOrigin::new("http://localhost:9292/")?.as_str(), "http://localhost:9292"); +/// assert!(AdminOrigin::new("https://shopify-proxy.example.com").is_ok()); +/// // In clear text, only to this machine. +/// assert!(AdminOrigin::new("http://shopify-proxy.example.com").is_err()); +/// // The origin only: the paths are Shopify's. +/// assert!(AdminOrigin::new("http://localhost:9292/admin").is_err()); +/// # Ok::<(), shopify_api::Error>(()) +/// ``` +/// +/// Give it to [`ShopifyBuilder::admin_origin`](crate::ShopifyBuilder::admin_origin), +/// or to `ShopifyApp::with_admin_origin` (feature `oauth`) for the token +/// requests of an app and the clients it builds. +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +pub struct AdminOrigin(String); + +impl AdminOrigin { + /// Checks `origin` and writes it as `scheme://host[:port]`, in lower + /// case, without a trailing `/`. An error does not show `origin`, which + /// may hold a password. + pub fn new(origin: &str) -> Result { + let (scheme, rest) = origin + .trim() + .split_once("://") + .ok_or_else(|| invalid("not an absolute `http://` or `https://` URL"))?; + let secure = if scheme.eq_ignore_ascii_case("https") { + true + } else if scheme.eq_ignore_ascii_case("http") { + false + } else { + return Err(invalid("the scheme is not `http` or `https`")); + }; + if rest.contains(['?', '#']) { + return Err(invalid("it has a query string or a fragment")); + } + let authority = rest.strip_suffix('/').unwrap_or(rest); + if authority.contains('/') { + return Err(invalid( + "it has a path: give the scheme, the host and the port only", + )); + } + if authority.contains('@') { + return Err(invalid("it has a user or a password")); + } + let (host, port) = split_port(authority)?; + let (host, loopback) = host_of(host)?; + if !secure && !loopback { + return Err(invalid( + "`http://` is taken for `localhost`, `127.0.0.1` or `[::1]` only: use `https://`", + )); + } + let scheme = if secure { "https" } else { "http" }; + Ok(Self(match port { + Some(port) => format!("{scheme}://{host}:{port}"), + None => format!("{scheme}://{host}"), + })) + } + + /// `http://localhost:9292`: no trailing `/`. + pub fn as_str(&self) -> &str { + &self.0 + } + + /// The address of `path` (from its `/`) at this origin. + pub(crate) fn url(&self, path: &str) -> String { + format!("{}{path}", self.0) + } +} + +/// The address of `path` (from its `/`) in the admin of `shop`: at `origin` +/// when there is one, else at `https://{shop}`. +pub(crate) fn admin_url(shop: &ShopDomain, origin: Option<&AdminOrigin>, path: &str) -> String { + match origin { + Some(origin) => origin.url(path), + None => format!("{}{path}", shop.origin()), + } +} + +fn invalid(reason: &str) -> Error { + Error::Config(format!( + "invalid admin origin, expected `https://host[:port]` (or `http://` to localhost): {reason}" + )) +} + +/// The host and the port of `authority`: `[::1]:9292`, `localhost`. +fn split_port(authority: &str) -> Result<(&str, Option), Error> { + let (host, port) = if authority.starts_with('[') { + let end = authority + .find(']') + .ok_or_else(|| invalid("an IPv6 address without its closing `]`"))?; + let (host, after) = authority.split_at(end + 1); + match after.strip_prefix(':') { + Some(port) => (host, Some(port)), + None if after.is_empty() => (host, None), + None => return Err(invalid("text after the IPv6 address")), + } + } else { + match authority.split_once(':') { + Some((host, port)) => (host, Some(port)), + None => (authority, None), + } + }; + let port = port + .map(|port| { + port.bytes() + .all(|byte| byte.is_ascii_digit()) + .then(|| port.parse::().ok()) + .flatten() + .filter(|port| *port != 0) + .ok_or_else(|| invalid("the port is not a number from 1 to 65535")) + }) + .transpose()?; + Ok((host, port)) +} + +/// The host as it is written in the origin, and whether it is a loopback +/// host `http://` may go to. +fn host_of(host: &str) -> Result<(String, bool), Error> { + if let Some(inner) = host.strip_prefix('[') { + let inner = inner.strip_suffix(']').unwrap_or(inner); + let address = Ipv6Addr::from_str(inner) + .map_err(|_| invalid("the host is not a valid IPv6 address"))?; + return Ok((format!("[{address}]"), address == Ipv6Addr::LOCALHOST)); + } + let host = host.to_ascii_lowercase(); + let label = |label: &str| { + (1..=63).contains(&label.len()) + && label + .bytes() + .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-') + && !label.starts_with('-') + && !label.ends_with('-') + }; + if host.len() > 253 || !host.split('.').all(label) { + return Err(invalid("the host is not a domain name or an IP address")); + } + // A name whose last label is a number is read as an IPv4 address by + // URL parsers: it must be one, written in the usual way. + if host + .rsplit('.') + .next() + .is_some_and(|last| last.bytes().all(|byte| byte.is_ascii_digit())) + { + let address = Ipv4Addr::from_str(&host) + .map_err(|_| invalid("the host is not a valid IPv4 address"))?; + return Ok((address.to_string(), address == Ipv4Addr::LOCALHOST)); + } + let loopback = host == "localhost"; + Ok((host, loopback)) +} + +impl fmt::Display for AdminOrigin { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(&self.0) + } +} + +impl AsRef for AdminOrigin { + fn as_ref(&self) -> &str { + &self.0 + } +} + +impl FromStr for AdminOrigin { + type Err = Error; + + fn from_str(origin: &str) -> Result { + Self::new(origin) + } +} + +impl TryFrom<&str> for AdminOrigin { + type Error = Error; + + fn try_from(origin: &str) -> Result { + Self::new(origin) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn writes_the_origin_without_a_trailing_slash() { + for (input, expected) in [ + ("http://localhost:9292", "http://localhost:9292"), + ("http://localhost:9292/", "http://localhost:9292"), + (" HTTP://LocalHost:9292 ", "http://localhost:9292"), + ("http://localhost", "http://localhost"), + ("http://127.0.0.1:9292", "http://127.0.0.1:9292"), + ("http://[::1]:9292", "http://[::1]:9292"), + ("http://[0:0:0:0:0:0:0:1]/", "http://[::1]"), + ("https://lsf.example.com", "https://lsf.example.com"), + ( + "https://Proxy.Example.com:8443/", + "https://proxy.example.com:8443", + ), + ("https://10.0.0.5:9292", "https://10.0.0.5:9292"), + ("https://[2001:db8::1]:443", "https://[2001:db8::1]:443"), + ("https://localhost:09292", "https://localhost:9292"), + ] { + let origin = AdminOrigin::new(input).unwrap_or_else(|error| panic!("{input}: {error}")); + assert_eq!(origin.as_str(), expected, "{input}"); + assert_eq!(input.parse::().unwrap(), origin); + } + } + + #[test] + fn refuses_what_is_not_an_origin() { + for input in [ + "", + "localhost:9292", + "//localhost:9292", + "ftp://localhost", + "ws://localhost:9292", + "https://", + "http://:9292", + "http://localhost:9292/admin", + "http://localhost:9292//", + "http://localhost:9292/?", + "http://localhost:9292?shop=x", + "http://localhost:9292#x", + "http://user:secret@localhost:9292", + "http://user@localhost:9292", + "http://localhost:", + "http://localhost:0", + "http://localhost:65536", + "http://localhost:92a", + "http://localhost:+92", + "http://localhost:9292:1", + "http://::1", + "http://[::1", + "http://[::1]x", + "http://[fe80::1%25en0]", + "http://[not-an-address]", + "https://exa mple.com", + "https://-bad.example.com", + "https://bad-.example.com", + "https://a..b", + "https://example.com.", + "https://under_score.example.com", + "https://999.1.1.1", + "https://127.000.000.001", + "https://1.2.3", + "https://exam\\ple.com", + ] { + assert!( + matches!(AdminOrigin::new(input), Err(Error::Config(_))), + "{input}" + ); + } + } + + #[test] + fn takes_http_for_a_loopback_host_only() { + for input in [ + "http://example.com", + "http://lsf.example.com:9292", + "http://localhost.example.com", + "http://app.localhost", + "http://127.0.0.2:9292", + "http://10.0.0.5:9292", + "http://0.0.0.0:9292", + "http://[::ffff:127.0.0.1]:9292", + "http://[::]:9292", + "http://2130706433", + ] { + let error = AdminOrigin::new(input).unwrap_err(); + assert!(matches!(error, Error::Config(_)), "{input}"); + assert!( + error.to_string().contains("use `https://`") || error.to_string().contains("IPv4"), + "{input}: {error}" + ); + let secure = input.replacen("http://", "https://", 1); + if input != "http://2130706433" { + assert!(AdminOrigin::new(&secure).is_ok(), "{secure}"); + } + } + } + + #[test] + fn an_error_does_not_show_the_origin() { + for input in [ + "http://user:shpat_secret@localhost:9292", + "http://localhost:9292/?token=shpat_secret", + "http://shpat_secret.example.com", + "shpat_secret", + ] { + let error = AdminOrigin::new(input).unwrap_err(); + let shown = format!("{error} {error:?}"); + assert!(!shown.contains("shpat_secret"), "{shown}"); + } + } + + #[test] + fn builds_the_addresses_of_the_admin() { + let shop = ShopDomain::new("my-shop").unwrap(); + assert_eq!( + admin_url(&shop, None, "/admin/oauth/access_token"), + "https://my-shop.myshopify.com/admin/oauth/access_token" + ); + let origin = AdminOrigin::new("http://localhost:9292/").unwrap(); + assert_eq!( + admin_url(&shop, Some(&origin), "/admin/oauth/access_token"), + "http://localhost:9292/admin/oauth/access_token" + ); + } +} diff --git a/crates/shopify_api/tests/admin_origin.rs b/crates/shopify_api/tests/admin_origin.rs new file mode 100644 index 0000000..b88665b --- /dev/null +++ b/crates/shopify_api/tests/admin_origin.rs @@ -0,0 +1,335 @@ +//! An admin origin: the requests built from the shop's domain go to a local +//! stand-in of Shopify, over the default transport, and nothing else changes. +#![cfg(all( + feature = "oauth", + feature = "testing", + any(feature = "rustls", feature = "native-tls") +))] + +use std::sync::{Arc, Mutex}; + +use serde_json::{Value, json}; +use shopify_api::oauth::{RequestedToken, ShopifyApp}; +use shopify_api::testing::MockTransport; +use shopify_api::{ApiVersion, RetryPolicy, Shopify}; +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::{TcpListener, TcpStream}; + +/// A request the local server received. +#[derive(Debug, Clone)] +struct Received { + method: String, + path: String, + headers: Vec<(String, String)>, + body: Vec, +} + +impl Received { + fn header(&self, name: &str) -> Option<&str> { + self.headers + .iter() + .find(|(key, _)| key.eq_ignore_ascii_case(name)) + .map(|(_, value)| value.as_str()) + } +} + +type Log = Arc>>; + +/// A local stand-in of Shopify's admin on a port of its own: its token +/// endpoint, the GraphQL Admin API and a bulk operation's file. Returns its +/// origin, on `localhost`, and what it receives. +async fn start() -> (String, Log) { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let port = listener.local_addr().unwrap().port(); + let log = Log::default(); + let received = log.clone(); + tokio::spawn(async move { + loop { + let (socket, _) = listener.accept().await.unwrap(); + tokio::spawn(answer(socket, received.clone())); + } + }); + (format!("http://localhost:{port}"), log) +} + +async fn answer(mut socket: TcpStream, log: Log) { + let request = read_request(&mut socket).await; + let (status, body) = respond(&request); + log.lock().unwrap().push(request); + let head = format!( + "HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n", + body.len() + ); + socket.write_all(head.as_bytes()).await.unwrap(); + socket.write_all(&body).await.unwrap(); + socket.shutdown().await.ok(); +} + +async fn read_request(socket: &mut TcpStream) -> Received { + let mut bytes = Vec::new(); + let mut buffer = [0; 4096]; + let end = loop { + if let Some(end) = bytes.windows(4).position(|window| window == b"\r\n\r\n") { + break end; + } + let read = socket.read(&mut buffer).await.unwrap(); + assert!(read > 0, "the connection closed before the headers ended"); + bytes.extend_from_slice(&buffer[..read]); + }; + let head = String::from_utf8(bytes[..end].to_vec()).unwrap(); + let mut lines = head.split("\r\n"); + let mut start = lines.next().unwrap().split(' '); + let method = start.next().unwrap().to_string(); + let path = start.next().unwrap().to_string(); + let headers: Vec<(String, String)> = lines + .filter_map(|line| line.split_once(':')) + .map(|(name, value)| (name.trim().to_ascii_lowercase(), value.trim().to_string())) + .collect(); + let length: usize = headers + .iter() + .find(|(name, _)| name == "content-length") + .map_or(0, |(_, value)| value.parse().unwrap()); + let mut body = bytes[end + 4..].to_vec(); + while body.len() < length { + let read = socket.read(&mut buffer).await.unwrap(); + assert!(read > 0, "the connection closed before the body ended"); + body.extend_from_slice(&buffer[..read]); + } + Received { + method, + path, + headers, + body, + } +} + +fn respond(request: &Received) -> (&'static str, Vec) { + let json = |value: Value| value.to_string().into_bytes(); + match (request.method.as_str(), request.path.as_str()) { + ("POST", "/admin/oauth/access_token") => { + let exchanged = serde_json::from_slice::(&request.body).is_ok_and(|body| { + body["grant_type"] == "urn:ietf:params:oauth:grant-type:token-exchange" + }); + let granted = + String::from_utf8_lossy(&request.body).contains("grant_type=client_credentials"); + match (exchanged, granted) { + (true, _) => ( + "200 OK", + json(json!({ "access_token": "shpat_exchanged", "scope": "read_products" })), + ), + (_, true) => ( + "200 OK", + json( + json!({ "access_token": "shpat_granted", "scope": "read_products", "expires_in": 86_399 }), + ), + ), + _ => ( + "400 Bad Request", + json(json!({ "error": "unsupported_grant_type" })), + ), + } + } + ("POST", "/admin/api/2026-10/graphql.json") => { + match request.header("x-shopify-access-token") { + Some("shpat_exchanged" | "shpat_granted") => ( + "200 OK", + json(json!({ "data": { "shop": { "name": "Local Supply Co" } } })), + ), + _ => ( + "401 Unauthorized", + json(json!({ "errors": "[API] Invalid API key or access token" })), + ), + } + } + ("GET", "/__lsf/admin/bulk/my-shop.myshopify.com/1.jsonl") => ( + "200 OK", + b"{\"id\":\"gid://shopify/Product/1\"}\n{\"id\":\"gid://shopify/Product/2\"}\n" + .to_vec(), + ), + _ => ("404 Not Found", json(json!({ "errors": "Not Found" }))), + } +} + +fn session_claims() -> Value { + let now = chrono::Utc::now().timestamp(); + json!({ + "iss": "https://my-shop.myshopify.com/admin", + "dest": "https://my-shop.myshopify.com", + "aud": "client-id", + "sub": "1", + "exp": now + 60, + "nbf": now - 1, + "iat": now - 1, + "jti": "a5f0c3e2-7d4b-4f7e-9a51-0c2d6b1e8f30", + "sid": "local-session", + }) +} + +#[tokio::test] +async fn a_token_exchange_and_a_query_go_to_the_admin_origin() { + let (origin, log) = start().await; + let app = ShopifyApp::new("client-id", "client-secret") + .with_admin_origin(&origin) + .unwrap(); + + let bearer = app.sign_session_token(&session_claims()); + let session = app.verify_session_token(&bearer).unwrap(); + let token = app + .exchange_session_token(&session, RequestedToken::Offline) + .await + .unwrap(); + assert_eq!(token.access_token, "shpat_exchanged"); + + let shopify = app + .client(session.shop(), token) + .unwrap() + .with_api_version(ApiVersion::V2026_10); + assert_eq!(shopify.shop().as_str(), "my-shop.myshopify.com"); + let data = shopify.graphql("{ shop { name } }", ()).await.unwrap(); + assert_eq!(data["shop"]["name"], "Local Supply Co"); + + let received = log.lock().unwrap().clone(); + assert_eq!(received.len(), 2, "{received:#?}"); + let exchange = &received[0]; + assert_eq!( + (exchange.method.as_str(), exchange.path.as_str()), + ("POST", "/admin/oauth/access_token") + ); + assert_eq!( + exchange.header("x-forwarded-host"), + Some("my-shop.myshopify.com") + ); + let fields: Value = serde_json::from_slice(&exchange.body).unwrap(); + assert_eq!(fields["subject_token"], bearer.as_str()); + assert_eq!(fields["client_id"], "client-id"); + + let query = &received[1]; + assert_eq!( + (query.method.as_str(), query.path.as_str()), + ("POST", "/admin/api/2026-10/graphql.json") + ); + assert_eq!( + query.header("x-shopify-access-token"), + Some("shpat_exchanged") + ); + assert_eq!( + query.header("x-forwarded-host"), + Some("my-shop.myshopify.com") + ); +} + +#[tokio::test] +async fn the_client_credentials_grant_goes_to_the_admin_origin() { + let (origin, log) = start().await; + let shopify = Shopify::builder("my-shop") + .admin_origin(format!("{origin}/")) + .client_credentials("client-id", "client-secret") + .api_version(ApiVersion::V2026_10) + .retry(RetryPolicy::none()) + .build() + .unwrap(); + + let data = shopify.graphql("{ shop { name } }", ()).await.unwrap(); + assert_eq!(data["shop"]["name"], "Local Supply Co"); + + let received = log.lock().unwrap().clone(); + let paths: Vec<&str> = received + .iter() + .map(|request| request.path.as_str()) + .collect(); + assert_eq!( + paths, + [ + "/admin/oauth/access_token", + "/admin/api/2026-10/graphql.json" + ] + ); + assert!(String::from_utf8_lossy(&received[0].body).contains("grant_type=client_credentials")); + assert!( + received + .iter() + .all(|request| request.header("x-forwarded-host") == Some("my-shop.myshopify.com")) + ); +} + +#[tokio::test] +async fn bulk_results_download_from_the_admin_origin() { + let (origin, log) = start().await; + let shopify = Shopify::builder("my-shop") + .admin_origin(&origin) + .access_token("shpat_exchanged") + .build() + .unwrap(); + + // The address a bulk operation of local-storefront answers. + let url = format!("{origin}/__lsf/admin/bulk/my-shop.myshopify.com/1.jsonl"); + let rows: Vec = shopify.download_bulk_results(&url).await.unwrap(); + assert_eq!(rows.len(), 2); + assert_eq!(rows[1]["id"], "gid://shopify/Product/2"); + + // As from Shopify's storage: no token, and nothing added. + let received = log.lock().unwrap().clone(); + assert_eq!(received.len(), 1); + assert_eq!(received[0].header("x-shopify-access-token"), None); + assert_eq!(received[0].header("x-forwarded-host"), None); +} + +#[tokio::test] +async fn without_an_admin_origin_nothing_changes() { + let mock = MockTransport::new(); + mock.push_json(json!({ "access_token": "shpat_exchanged", "scope": "read_products" })); + mock.push_data(json!({ "shop": { "name": "x" } })); + let app = ShopifyApp::new("client-id", "client-secret").with_transport(mock.clone()); + assert_eq!(app.admin_origin(), None); + + let session = app + .verify_session_token(&app.sign_session_token(&session_claims())) + .unwrap(); + let token = app + .exchange_session_token(&session, RequestedToken::Offline) + .await + .unwrap(); + let shopify = app + .client(session.shop(), token) + .unwrap() + .with_api_version(ApiVersion::V2026_10); + assert_eq!(shopify.admin_origin(), None); + shopify.graphql("{ shop { name } }", ()).await.unwrap(); + + let sent = mock.requests(); + assert_eq!( + sent[0].url, + "https://my-shop.myshopify.com/admin/oauth/access_token" + ); + assert_eq!( + sent[1].url, + "https://my-shop.myshopify.com/admin/api/2026-10/graphql.json" + ); + assert!( + sent.iter() + .all(|request| request.header("X-Forwarded-Host").is_none()) + ); +} + +#[tokio::test] +async fn the_admin_origin_goes_through_a_mock_transport_too() { + let mock = MockTransport::new(); + mock.push_data(json!({ "shop": { "name": "x" } })); + let shopify = Shopify::builder("my-shop") + .admin_origin("http://127.0.0.1:9292") + .access_token("t") + .api_version(ApiVersion::V2026_10) + .transport(mock.clone()) + .build() + .unwrap(); + shopify.graphql("{ shop { name } }", ()).await.unwrap(); + let sent = mock.last_request().unwrap(); + assert_eq!( + sent.url, + "http://127.0.0.1:9292/admin/api/2026-10/graphql.json" + ); + assert_eq!( + sent.header("X-Forwarded-Host"), + Some("my-shop.myshopify.com") + ); +}