@logto/tunnel 0.1.0 → 0.2.0

package/lib/commands/deploy/index.d.ts

@@ -0,0 +1,4 @@
+import type { CommandModule } from 'yargs';
+import { type DeployCommandArgs } from './types.js';
+declare const tunnel: CommandModule<unknown, DeployCommandArgs>;
+export default tunnel;

package/lib/commands/deploy/index.js

@@ -0,0 +1,77 @@
+import { isValidUrl } from '@logto/core-kit';
+import chalk from 'chalk';
+import ora from 'ora';
+import { consoleLog } from '../../utils.js';
+import { checkExperienceAndZipPathInputs, deployToLogtoCloud } from './utils.js';
+const tunnel = {
+    command: ['deploy'],
+    describe: 'Deploy your custom UI assets to Logto Cloud',
+    builder: (yargs) => yargs
+        .options({
+        auth: {
+            describe: 'Auth credentials of your Logto M2M application. E.g.: <app-id>:<app-secret> (Docs: https://docs.logto.io/docs/recipes/interact-with-management-api/#create-an-m2m-app)',
+            type: 'string',
+        },
+        endpoint: {
+            describe: 'Logto endpoint URI that points to your Logto Cloud instance. E.g.: https://<tenant-id>.logto.app/',
+            type: 'string',
+        },
+        path: {
+            alias: ['experience-path'],
+            describe: 'The local folder path of your custom sign-in experience assets.',
+            type: 'string',
+        },
+        resource: {
+            alias: ['management-api-resource'],
+            describe: 'Logto Management API resource indicator. Required if using custom domain.',
+            type: 'string',
+        },
+        verbose: {
+            describe: 'Show verbose output.',
+            type: 'boolean',
+            default: false,
+        },
+        zip: {
+            alias: ['zip-path'],
+            describe: 'The local folder path of your existing zip package.',
+            type: 'string',
+        },
+    })
+        .epilog(`Refer to our documentation for more details:\n${chalk.blue('https://docs.logto.io/docs/references/tunnel-cli/deploy')}`),
+    handler: async (options) => {
+        const { auth, endpoint, path: experiencePath, resource: managementApiResource, verbose, zip: zipPath, } = options;
+        if (!auth) {
+            consoleLog.fatal('Must provide valid Machine-to-Machine (M2M) authentication credentials. E.g. `--auth <app-id>:<app-secret>` or add `LOGTO_AUTH` to your environment variables.');
+        }
+        if (!endpoint || !isValidUrl(endpoint)) {
+            consoleLog.fatal('A valid Logto endpoint URI must be provided. E.g. `--endpoint https://<tenant-id>.logto.app/` or add `LOGTO_ENDPOINT` to your environment variables.');
+        }
+        await checkExperienceAndZipPathInputs(experiencePath, zipPath);
+        const spinner = ora();
+        if (verbose) {
+            consoleLog.plain(`${chalk.bold('Starting deployment...')} ${chalk.gray('(with verbose output)')}`);
+        }
+        else {
+            spinner.start('Deploying your custom UI assets to Logto Cloud...');
+        }
+        await deployToLogtoCloud({
+            auth,
+            endpoint,
+            experiencePath,
+            managementApiResource,
+            verbose,
+            zipPath,
+        });
+        if (!verbose) {
+            spinner.succeed('Deploying your custom UI assets to Logto Cloud... Done.');
+        }
+        const endpointUrl = new URL(endpoint);
+        spinner.succeed(`🎉 ${chalk.bold(chalk.green('Deployment successful!'))}`);
+        consoleLog.plain(`${chalk.green('➜')} You can try your own sign-in UI on Logto Cloud now.`);
+        consoleLog.plain(`${chalk.green('➜')} Make sure the Logto endpoint URI in your app is set to:`);
+        consoleLog.plain(`  ${chalk.blue(chalk.bold(endpointUrl.href))}`);
+        consoleLog.plain(`${chalk.green('➜')} If you are using social sign-in, make sure the social redirect URI is set to:`);
+        consoleLog.plain(`  ${chalk.blue(chalk.bold(`${endpointUrl.href}callback/<connector-id>`))}`);
+    },
+};
+export default tunnel;

package/lib/commands/deploy/types.d.ts

@@ -0,0 +1,8 @@
+export type DeployCommandArgs = {
+    auth?: string;
+    endpoint?: string;
+    path?: string;
+    zip?: string;
+    resource?: string;
+    verbose: boolean;
+};

package/lib/commands/deploy/utils.d.ts

@@ -0,0 +1,11 @@
+type DeployArgs = {
+    auth: string;
+    endpoint: string;
+    experiencePath?: string;
+    zipPath?: string;
+    managementApiResource?: string;
+    verbose: boolean;
+};
+export declare const checkExperienceAndZipPathInputs: (experiencePath?: string, zipPath?: string) => Promise<void>;
+export declare const deployToLogtoCloud: ({ auth, endpoint, experiencePath, managementApiResource, verbose, zipPath, }: DeployArgs) => Promise<void>;
+export {};

package/lib/commands/deploy/utils.js

@@ -0,0 +1,159 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { appendPath } from '@silverhand/essentials';
+import AdmZip from 'adm-zip';
+import chalk from 'chalk';
+import ora from 'ora';
+import { consoleLog } from '../../utils.js';
+export const checkExperienceAndZipPathInputs = async (experiencePath, zipPath) => {
+    if (zipPath && experiencePath) {
+        consoleLog.fatal('You can only specify either `--zip-path` or `--experience-path`. Please check your input and environment variables.');
+    }
+    if (!zipPath && !experiencePath) {
+        consoleLog.fatal('A valid path to your experience asset folder or zip package must be provided. You can specify either `--zip-path` or `--experience-path` options or corresponding environment variables.');
+    }
+    if (zipPath) {
+        if (!existsSync(zipPath)) {
+            consoleLog.fatal(`The specified zip file does not exist: ${zipPath}`);
+        }
+        const zipFile = new AdmZip(zipPath);
+        const zipEntries = zipFile.getEntries();
+        const hasIndexHtmlInRoot = zipEntries.some(({ entryName }) => {
+            const parts = entryName.split('/');
+            return parts.length <= 2 && parts.at(-1) === 'index.html';
+        });
+        if (!hasIndexHtmlInRoot) {
+            consoleLog.fatal('The provided zip must contain an "index.html" file in the root directory.');
+        }
+    }
+    if (experiencePath && !existsSync(path.join(experiencePath, 'index.html'))) {
+        consoleLog.fatal(`The provided experience path must contain an "index.html" file.`);
+    }
+};
+export const deployToLogtoCloud = async ({ auth, endpoint, experiencePath, managementApiResource, verbose, zipPath, }) => {
+    const spinner = ora();
+    if (verbose) {
+        spinner.start(`[1/4] ${zipPath ? 'Reading zip' : 'Zipping'} files...`);
+    }
+    const zipBuffer = await getZipBuffer(experiencePath, zipPath);
+    if (verbose) {
+        spinner.succeed(`[1/4] ${zipPath ? 'Reading zip' : 'Zipping'} files... Done.`);
+    }
+    try {
+        if (verbose) {
+            spinner.start('[2/4] Exchanging access token...');
+        }
+        const endpointUrl = new URL(endpoint);
+        const tokenResponse = await getAccessToken(auth, endpointUrl, managementApiResource);
+        if (verbose) {
+            spinner.succeed('[2/4] Exchanging access token... Done.');
+            spinner.succeed(`Token exchange response:\n${chalk.gray(JSON.stringify(tokenResponse, undefined, 2))}`);
+            spinner.start('[3/4] Uploading zip...');
+        }
+        const accessToken = tokenResponse.access_token;
+        const uploadResult = await uploadCustomUiAssets(accessToken, endpointUrl, zipBuffer);
+        if (verbose) {
+            spinner.succeed('[3/4] Uploading zip... Done.');
+            spinner.succeed(`Received response:\n${chalk.gray(JSON.stringify(uploadResult, undefined, 2))}`);
+            spinner.start('[4/4] Saving changes to your tenant...');
+        }
+        await saveChangesToSie(accessToken, endpointUrl, uploadResult.customUiAssetId);
+        if (verbose) {
+            spinner.succeed('[4/4] Saving changes to your tenant... Done.');
+        }
+    }
+    catch (error) {
+        spinner.fail();
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        consoleLog.fatal(chalk.red(errorMessage));
+    }
+};
+const getZipBuffer = async (experiencePath, zipPath) => {
+    if (!experiencePath && !zipPath) {
+        consoleLog.fatal('Must specify either `--experience-path` or `--zip-path`.');
+    }
+    if (zipPath) {
+        return readFile(zipPath);
+    }
+    if (!experiencePath) {
+        consoleLog.fatal('Invalid experience path input.');
+    }
+    const zip = new AdmZip();
+    await zip.addLocalFolderPromise(experiencePath, {
+        filter: (filename) => !isHiddenEntry(filename),
+    });
+    return zip.toBuffer();
+};
+const getAccessToken = async (auth, endpoint, managementApiResource) => {
+    const tokenEndpoint = appendPath(endpoint, '/oidc/token').href;
+    const resource = managementApiResource ?? getManagementApiResourceFromEndpointUri(endpoint);
+    const response = await fetch(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Authorization: `Basic ${Buffer.from(auth).toString('base64')}`,
+        },
+        body: new URLSearchParams({
+            grant_type: 'client_credentials',
+            resource,
+            scope: 'all',
+        }).toString(),
+    });
+    if (!response.ok) {
+        await throwRequestError(response);
+    }
+    return response.json();
+};
+const uploadCustomUiAssets = async (accessToken, endpoint, zipBuffer) => {
+    const form = new FormData();
+    const blob = new Blob([zipBuffer], { type: 'application/zip' });
+    const timestamp = Math.floor(Date.now() / 1000);
+    form.append('file', blob, `custom-ui-${timestamp}.zip`);
+    const response = await fetch(appendPath(endpoint, '/api/sign-in-exp/default/custom-ui-assets'), {
+        method: 'POST',
+        body: form,
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        await throwRequestError(response);
+    }
+    return response.json();
+};
+const saveChangesToSie = async (accessToken, endpointUrl, customUiAssetId) => {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const response = await fetch(appendPath(endpointUrl, '/api/sign-in-exp'), {
+        method: 'PATCH',
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            customUiAssets: { id: customUiAssetId, createdAt: timestamp },
+        }),
+    });
+    if (!response.ok) {
+        await throwRequestError(response);
+    }
+    return response.json();
+};
+const throwRequestError = async (response) => {
+    const errorDetails = await response.text();
+    throw new Error(`[${response.status}] ${errorDetails}`);
+};
+const getTenantIdFromEndpointUri = (endpoint) => {
+    const splitted = endpoint.hostname.split('.');
+    return splitted.length > 2 ? splitted[0] : 'default';
+};
+const getManagementApiResourceFromEndpointUri = (endpoint) => {
+    const tenantId = getTenantIdFromEndpointUri(endpoint);
+    // This resource domain is fixed to `logto.app` for all environments (prod, staging, and dev)
+    return `https://${tenantId}.logto.app/api`;
+};
+const isHiddenEntry = (entryName) => {
+    return entryName.split('/').some((part) => part.startsWith('.'));
+};

package/lib/commands/{index.js → tunnel/index.js}

@@ -2,7 +2,7 @@ import http from 'node:http';
 import { isValidUrl } from '@logto/core-kit';
 import { conditional } from '@silverhand/essentials';
 import chalk from 'chalk';
-import { consoleLog } from '../utils.js';
+import { consoleLog } from '../../utils.js';
 import { checkExperienceInput, createLogtoResponseHandler, createProxy, createStaticFileProxy, isLogtoRequestPath, } from './utils.js';
 const tunnel = {
     command: ['$0'],
@@ -19,7 +19,7 @@ const tunnel = {
             type: 'string',
         },
         endpoint: {
-            describe: 'Logto endpoint URI that points to your Logto Cloud instance. E.g.: https://<tenant-id>.logto.app/',
+            describe: `Logto endpoint URI that points to your Logto Cloud instance. E.g.: https://<tenant-id>.logto.app/`,
             type: 'string',
         },
         port: {
@@ -34,10 +34,10 @@ const tunnel = {
             default: false,
         },
     }),
-    handler: async ({ 'experience-uri': url, 'experience-path': path, endpoint, port, verbose }) => {
-        checkExperienceInput(url, path);
+    handler: async ({ 'experience-uri': uri, 'experience-path': path, endpoint, port, verbose }) => {
+        checkExperienceInput(uri, path);
         if (!endpoint || !isValidUrl(endpoint)) {
-            consoleLog.fatal('A valid Logto endpoint URI must be provided.');
+            consoleLog.fatal('A valid Logto endpoint URI must be provided. E.g. `--endpoint https://<tenant-id>.logto.app/` or add `LOGTO_ENDPOINT` to your environment variables.');
         }
         const logtoEndpointUrl = new URL(endpoint);
         const startServer = (port) => {
@@ -50,7 +50,7 @@ const tunnel = {
                 tunnelServiceUrl,
                 verbose,
             }));
-            const proxyExperienceServerRequest = conditional(url && createProxy(url));
+            const proxyExperienceServerRequest = conditional(uri && createProxy(uri));
             const proxyExperienceStaticFileRequest = conditional(path && createStaticFileProxy(path));
             const server = http.createServer((request, response) => {
                 consoleLog.info(`[${chalk.green(request.method)}] ${request.url}`);
@@ -69,21 +69,16 @@ const tunnel = {
             });
             server.listen(port, () => {
                 const serviceUrl = new URL(`http://localhost:${port}`);
-                consoleLog.info(`🎉 Logto tunnel service is running!
-  ${chalk.green('➜')} Your custom sign-in UI is hosted on: ${chalk.blue(serviceUrl.href)}
-
-  ${chalk.green('➜')} Don't forget to update Logto endpoint URI in your app:
-
-      ${chalk.gray('From:')} ${chalk.bold(endpoint)}
-      ${chalk.gray('To:')}   ${chalk.bold(serviceUrl.href)}
-
-  ${chalk.green('➜')} If you are using social sign-in, make sure the social redirect URI is also set to:
-
-      ${chalk.bold(`${serviceUrl.href}callback/<connector-id>`)}
-
-  ${chalk.green('➜')} ${chalk.gray(`Press ${chalk.white('Ctrl+C')} to stop the tunnel service.`)}
-  ${chalk.green('➜')} ${chalk.gray(`Use ${chalk.white('--verbose')} to print verbose output.`)}
-          `);
+                consoleLog.plain(`${chalk.green('✔')} 🎉 Logto tunnel service is running!`);
+                consoleLog.plain(`${chalk.green('➜')} Your custom sign-in UI is hosted on:`);
+                consoleLog.plain(`  ${chalk.blue(chalk.bold(serviceUrl.href))}`);
+                consoleLog.plain(`${chalk.green('➜')} Remember to update Logto endpoint URI in your app:`);
+                consoleLog.plain(`  ${chalk.gray('From:')} ${chalk.blue(chalk.bold(endpoint))}`);
+                consoleLog.plain(`  ${chalk.gray('To:')}   ${chalk.blue(chalk.bold(serviceUrl.href))}`);
+                consoleLog.plain(`${chalk.green('➜')} If you are using social sign-in, make sure the social redirect URI is also set to:`);
+                consoleLog.plain(`  ${chalk.blue(chalk.bold(`${serviceUrl.href}callback/<connector-id>`))}\n`);
+                consoleLog.plain(`${chalk.green('➜')} ${chalk.gray(`Press ${chalk.white('Ctrl+C')} to stop the tunnel service.`)}`);
+                consoleLog.plain(`${chalk.green('➜')} ${chalk.gray(`Use ${chalk.white('--verbose')} to print verbose output.`)}`);
             });
             server.on('error', (error) => {
                 if ('code' in error && error.code === 'EADDRINUSE') {

package/lib/commands/{utils.js → tunnel/utils.js}

@@ -6,7 +6,7 @@ import { conditional, trySafe } from '@silverhand/essentials';
 import chalk from 'chalk';
 import { createProxyMiddleware, responseInterceptor } from 'http-proxy-middleware';
 import mime from 'mime';
-import { consoleLog } from '../utils.js';
+import { consoleLog } from '../../utils.js';
 export const createProxy = (targetUrl, onProxyResponse) => {
     const hasResponseHandler = Boolean(onProxyResponse);
     return createProxyMiddleware({
@@ -97,13 +97,15 @@ export const checkExperienceInput = (url, staticPath) => {
         consoleLog.fatal('Only one of the experience URI or path can be provided.');
     }
     if (!staticPath && !url) {
-        consoleLog.fatal('Either a sign-in experience URI or local path must be provided.');
+        consoleLog.fatal(`Either a sign-in experience URI or local path must be provided.
+      
+Specify --help for available options`);
     }
     if (url && !isValidUrl(url)) {
-        consoleLog.fatal('A valid sign-in experience URI must be provided. E.g.: http://localhost:4000');
+        consoleLog.fatal('A valid sign-in experience URI must be provided. E.g. `--experience-uri http://localhost:4000` or add `LOGTO_EXPERIENCE_URI` to your environment variables.');
     }
     if (staticPath && !existsSync(path.join(staticPath, index))) {
-        consoleLog.fatal('The provided path does not contain a valid index.html file.');
+        consoleLog.fatal('The provided path must contain a valid index.html file.');
     }
 };
 /**

package/lib/commands/tunnel/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.js

@@ -1,24 +1,20 @@
 import chalk from 'chalk';
 import dotenv from 'dotenv';
+import { findUp } from 'find-up';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import tunnel from './commands/index.js';
+import deploy from './commands/deploy/index.js';
+import tunnel from './commands/tunnel/index.js';
 import { packageJson } from './package-json.js';
 import { consoleLog } from './utils.js';
+dotenv.config({ path: await findUp('.env', {}) });
 void yargs(hideBin(process.argv))
     .version(false)
-    .option('env', {
-    alias: ['e', 'env-file'],
-    describe: 'The path to your `.env` file',
-    type: 'string',
-})
+    .env('LOGTO')
     .option('version', {
     alias: 'v',
     describe: 'Print CLI version',
     type: 'boolean',
-})
-    .middleware(({ env }) => {
-    dotenv.config({ path: env });
 })
     .middleware(({ version }) => {
     if (version) {
@@ -28,9 +24,11 @@ void yargs(hideBin(process.argv))
     }
 }, true)
     .command(tunnel)
+    .command(deploy)
     .showHelpOnFail(false, `Specify ${chalk.green('--help')} for available options`)
-    .strict()
+    .strictCommands()
     .parserConfiguration({
     'dot-notation': false,
 })
+    .epilog(`Refer to our documentation for more details:\n${chalk.blue('https://docs.logto.io/docs/references/tunnel-cli')}`)
     .parse();

package/lib/package-json.d.ts

@@ -41,16 +41,20 @@ export declare const packageJson: {
         "@logto/core-kit": string;
         "@logto/shared": string;
         "@silverhand/essentials": string;
+        "adm-zip": string;
         chalk: string;
         dotenv: string;
+        "find-up": string;
         "http-proxy-middleware": string;
         mime: string;
+        ora: string;
         yargs: string;
         zod: string;
     };
     devDependencies: {
         "@silverhand/eslint-config": string;
         "@silverhand/ts-config": string;
+        "@types/adm-zip": string;
         "@types/node": string;
         "@types/yargs": string;
         "@vitest/coverage-v8": string;

package/lib/package-json.js

@@ -1,6 +1,6 @@
 export const packageJson = {
     "name": "@logto/tunnel",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "A CLI tool that creates tunnel service to Logto Cloud for local development.",
     "author": "Silverhand Inc. <contact@silverhand.io>",
     "homepage": "https://github.com/logto-io/logto#readme",
@@ -44,16 +44,20 @@ export const packageJson = {
         "@logto/core-kit": "workspace:^",
         "@logto/shared": "workspace:^",
         "@silverhand/essentials": "^2.9.1",
+        "adm-zip": "^0.5.14",
         "chalk": "^5.3.0",
         "dotenv": "^16.4.5",
+        "find-up": "^7.0.0",
         "http-proxy-middleware": "^3.0.0",
         "mime": "^4.0.4",
+        "ora": "^8.0.1",
         "yargs": "^17.6.0",
         "zod": "^3.23.8"
     },
     "devDependencies": {
         "@silverhand/eslint-config": "6.0.1",
         "@silverhand/ts-config": "6.0.0",
+        "@types/adm-zip": "^0.5.5",
         "@types/node": "^20.9.5",
         "@types/yargs": "^17.0.13",
         "@vitest/coverage-v8": "^2.0.0",

package/lib/utils.js

@@ -1,12 +1,2 @@
 import { ConsoleLog } from '@logto/shared';
-// The explicit type annotation is required to make `.fatal()`
-// works correctly without `return`:
-//
-// ```ts
-// const foo: number | undefined;
-// consoleLog.fatal();
-// typeof foo // Still `number | undefined` without explicit type annotation
-// ```
-//
-// For now I have no idea why.
 export const consoleLog = new ConsoleLog();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/tunnel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A CLI tool that creates tunnel service to Logto Cloud for local development.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",
@@ -29,18 +29,22 @@
   },
   "dependencies": {
     "@silverhand/essentials": "^2.9.1",
+    "adm-zip": "^0.5.14",
     "chalk": "^5.3.0",
     "dotenv": "^16.4.5",
+    "find-up": "^7.0.0",
     "http-proxy-middleware": "^3.0.0",
     "mime": "^4.0.4",
+    "ora": "^8.0.1",
     "yargs": "^17.6.0",
     "zod": "^3.23.8",
-    "@logto/shared": "^3.1.1",
-    "@logto/core-kit": "^2.5.0"
+    "@logto/core-kit": "^2.5.0",
+    "@logto/shared": "^3.1.1"
   },
   "devDependencies": {
     "@silverhand/eslint-config": "6.0.1",
     "@silverhand/ts-config": "6.0.0",
+    "@types/adm-zip": "^0.5.5",
     "@types/node": "^20.9.5",
     "@types/yargs": "^17.0.13",
     "@vitest/coverage-v8": "^2.0.0",