docs: logto tunnel cli

docs/docs/recipes/customize-sie/bring-your-ui.md

@@ -0,0 +1,64 @@
+---
+sidebar_label: Bring your UI
+sidebar_position: 6
+---
+
+import Availability from '@components/Availability';
+
+# Bring your own sign-in experience UI
+
+<Availability cloud oss={false} />
+
+In addition to all the customization methods we introduced above, you can deeply customize your sign-in experience by bringing your own UI to completely replace the built-in Logto sign-in interface. This feature enables you to upload a zip file containing your custom UI assets (HTML, CSS, JavaScript, images, etc.), have it hosted on Logto Cloud servers, and use it as the sign-in experience for your tenant users.
+
+:::note
+
+Please note that this feature requires your custom UI to be Single Page Application (SPA) compatible, and it's recommended to always use a production build for optimal performance.
+
+:::
+
+## Upload your custom UI assets
+
+:::note
+
+Proceed with caution when using this feature in production, since it will immediately affect your users' sign-in experience.
+
+:::
+
+Navigate to "Sign-in experience > Branding > Custom UI > Bring your UI" in the Logto Console.
+
+Click to select or drag and drop your zip file containing your custom UI assets, and the upload process will start automatically. Once the upload is complete, save the changes, and your custom UI will be served immediately.
+
+The "Sign-in preview" window will be disabled when you use your custom sign-in UI. However, you can still click the "Live preview" button to test your custom sign-in page in a new opened browser tab.
+
+### Custom UI assets requirements
+
+- The upload assets should be packed as a single zip file.
+- The zip file should contain an `index.html` file in the root directory.
+- The zip file should not exceed 20MB in size.
+- The zip file should not contain any file that exceeds 10MB in size.
+- The zip file should not contain more than 200 files in total.
+
+### Tips to quickly get started
+
+At this point, the fastest way to initiate a custom sign-in UI is to clone the [Logto experience project](https://github.com/logto-io/logto/tree/master/packages/experience). This is the built-in Logto sign-in experience UI that covers all features and Logto's best practices. You can customize it to fit your needs.
+
+After checking out the code, just simply run:
+
+```
+pnpm install && pnpm start
+```
+
+Note: The whole Logto project is a [pnpm monorepo](https://pnpm.io/workspaces), and you can find workspace protocol dependencies in package.json. Replace it with regular semver if you are not using pnpm, and want to run it as a standalone project.
+
+Moreover, we are working on providing more simplified and scenario-based sample projects to cover the most common use cases. Stay tuned for our future updates!
+
+## Interact with Logto experience API
+
+When developing your custom UI pages, you can interact with Logto's experience API to perform various actions such as sign-in, sign-up, password reset, binding social accounts, enabling MFA, and more. Refer to [Logto experience API documentation](https://openapi.logto.io/group/endpoint-interaction) for more details.
+
+Other sign-in experience configurations, such as branding colors, company logo, favicon, password policy, localized language phrases, even custom CSS, can still be fetched from the [sign-in experience API endpoint](https://openapi.logto.io/operation/operation-getsigninexperienceconfig).
+
+## Restore to Logto built-in sign-in experience
+
+If you wish to restore to Logto's built-in sign-in experience, simply click the delete button on the custom UI card. After saving the changes, the sign-in experience UI will be reverted back to Logto's default.

docs/docs/recipes/customize-sie/check-out-the-live-preview.md

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Check out the live preview
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Check out the live preview

docs/docs/recipes/customize-sie/custom-css.md

@@ -9,7 +9,7 @@ Logto continually enhances the user sign-in experience and has added a brand col
 
 ## Custom CSS in Logto Console
 
-Go to "Sign-in Experience > Branding > Custom CSS" in the Logto Console.
+Go to "Sign-in Experience > Branding > Custom UI > Custom CSS" in the Logto Console.
 
 Editing CSS code in the left editor, it will render lively in the right preview modal immediately. Please note, the code editor only supports the CSS code so far. Not HTML or Javascript.
 

docs/docs/references/using-cli/tunnel.mdx

@@ -0,0 +1,159 @@
+import Availability from '@components/Availability';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+# Set up a local tunnel for custom UI development
+
+<Availability cloud oss={{ major: 1, minor: 20 }} />
+
+For Logto Cloud users, We've made it easy to let you "Bring your own UI" to Logto. Cloud users can now upload a zip file containing the custom UI assets in Logto Console -> Sign-in experience -> Custom UI. (Check out the [Bring your UI](/docs/recipes/customize-sie/bring-your-ui) page for more details.)
+
+However, when developing such custom UI pages, users want to test and debug the code locally, before uploading to Logto Cloud. This CLI command helps you set up a local tunnel and connect the following 3 entities together:
+your Logto cloud auth endpoint, your application, and your custom sign-in UI.
+
+## Why do I need this?
+
+By default, when you click the "sign-in" button in your application, you will be navigated to the sign-in page configured at Logto endpoint. A successful sign-in flow can be illustrated as follows:
+
+```mermaid
+sequenceDiagram
+    box Local machine
+    participant A as Your application
+    end
+    box Logto Cloud
+    participant B as Logto Cloud auth endpoint
+    participant C as Logto sign-in page
+    end
+    A ->> B: User initiates "sign-in" action and request auth
+    B -->> A: Return auth response and tell the client<br/>to redirect to the Logto sign-in page
+    A ->> C: Redirect to the Logto sign-in page
+    C ->> B: Submit the sign-in form and<br/>request experience API to authenticate
+    B -->> C: Respond the sign-in request and<br/>tell the client to redirect to your application
+    C -->> A: Redirect to your application
+    A --> A: Handle the sign-in callback and<br/>the user is now authenticated
+```
+
+But now since you are developing your own custom sign-in UI, you need a way to navigate to the custom sign-in UI pages running on your local machine instead.
+This requires a local tunnel service to intercept the outgoing requests from your application and redirect them to your custom sign-in UI pages.
+
+Additionally, you need to interact with Logto's experience API to authenticate users and manage sessions.
+This service will also help forward these experience API requests to Logto Cloud in order to avoid CORS issues.
+
+The sequence diagram below illustrates how a successful "sign-in" flow works with your custom UI and the tunnel service in place:
+
+```mermaid
+sequenceDiagram
+    box Local machine
+    participant A as Your application
+    participant B as Your custom sign-in UI
+    participant C as Tunnel
+    end
+    box Logto Cloud
+    participant D as Logto Cloud auth endpoint
+    participant E as Logto sign-in page
+    end
+    A ->> C: User initiates "sign-in" action and request auth
+    C ->> D: Forward auth request to Logto Cloud endpoint
+    D -->> C: Return auth response and tell the client<br/>to redirect to the Logto sign-in page
+    C ->> B: Intercept the redirect and<br/>redirect to your custom sign-in page
+    B ->> C: Submit the sign-in form and<br/>request experience API to authenticate
+    C ->> D: Forward the experience API requests to Logto Cloud
+    D -->> C: Authenticate sign-in request and<br/>tell the client to redirect to your application
+    C -->> A: Redirect to your application
+    A --> A: Handle the sign-in callback and<br/>the user is now authenticated
+```
+
+With the tunnel service in place, you can now develop and test your custom sign-in UI locally, without needing to upload the assets to Logto Cloud every time you make a change.
+
+## Instructions
+
+### Step 1: Execute the command
+
+Assuming your Cloud tenant ID is `foobar`, and you have a custom sign-in page running on your local dev server at `http://localhost:4000`, then you can execute the command this way:
+
+<Tabs groupId="cmd">
+
+  <TabItem value="cli" label="CLI">
+
+```bash
+logto tunnel -p 9000 --experience-uri http://localhost:4000/ --endpoint https://foobar.logto.app/
+```
+
+  </TabItem>
+  <TabItem value="npx" label="npx">
+
+```bash
+npx @logto/cli tunnel -p 9000 --experience-uri http://localhost:4000/ --endpoint https://foobar.logto.app/
+```
+
+  </TabItem>
+
+</Tabs>
+
+It also works if you have custom domain configured in Logto:
+
+<Tabs groupId="cmd">
+
+  <TabItem value="cli" label="CLI">
+
+```bash
+logto tunnel -p 9000 --experience-uri http://localhost:4000/ --endpoint https://your.custom.domain/
+```
+
+  </TabItem>
+  <TabItem value="npx" label="npx">
+
+```bash
+npx @logto/cli tunnel -p 9000 --experience-uri http://localhost:4000/ --endpoint https://your.custom.domain/
+```
+
+  </TabItem>
+
+</Tabs>
+
+Alternatively, the command also supports static html assets without needing to run it first on a dev server. Just make sure there's a `index.html` in the path you specified.
+
+<Tabs groupId="cmd">
+
+  <TabItem value="cli" label="CLI">
+
+```bash
+logto tunnel -p 9000 --experience-path /path/to/your/static/files --endpoint https://foobar.logto.app/
+```
+
+  </TabItem>
+  <TabItem value="npx" label="npx">
+
+```bash
+npx @logto/cli tunnel -p 9000 --experience-path /path/to/your/static/files --endpoint https://foobar.logto.app/
+```
+
+  </TabItem>
+
+</Tabs>
+
+### Step 2: Update endpoint URI in your application
+
+Finally, run your application and set its Logto endpoint to the tunnel service address `http://localhost:9000/` instead.
+
+Let's take a React application as an example:
+
+```tsx title=App.tsx
+import { LogtoProvider, LogtoConfig } from '@logto/react';
+
+const config: LogtoConfig = {
+  // endpoint: 'https://foobar.logto.app/', // original Logto Cloud endpoint
+  endpoint: 'http://localhost:9000/', // tunnel service address
+  appId: '<your-application-id>',
+};
+
+const App = () => (
+  <LogtoProvider config={config}>
+    <YourAppContent />
+  </LogtoProvider>
+);
+```
+
+If all set up correctly, when you click the "sign-in" button in your application, you should be navigated to your custom sign-in page instead of Logto's built-in UI, along with valid session (cookies) that allows you to further interact with Logto experience API.
+
+Happy coding!

src/scss/custom.scss

@@ -301,3 +301,9 @@ hr {
 code {
   tab-size: 4;
 }
+
+svg[id^='mermaid-'] {
+  rect[class='rect'] {
+    stroke: var(--logto-border);
+  }
+}