mygensite 1.1.0 → 1.3.0

package/README.en.md

@@ -154,6 +154,70 @@ await tunnel.updateAccess({ mode: 'ip_only', allowed_ips: ['1.2.3.0/24'] });
 await tunnel.extendTTL(3600);
 ```
 
+## Constraints
+
+### Slug (subdomain)
+
+- 3–63 characters, lowercase letters (`a-z`), numbers (`0-9`), and hyphens (`-`) only
+- Must start and end with a letter or number (not a hyphen)
+- Reserved words cannot be used: `www`, `api`, `dashboard`, `admin`, `mail`, `ftp`, `static`, `docs`, `status`, `health`, `internal`, `tunnel`, `app`, `web`
+- A slug used as a tunnel cannot be reused for static deployment (and vice versa). Delete the existing service first.
+
+```
+OK:  my-app, demo-v2, test-123
+BAD: My-App, -dash, ab, a_b, my--app..com
+```
+
+### File Paths (static deploy)
+
+- Allowed characters per segment: letters, numbers, hyphens (`-`), underscores (`_`), dots (`.`), spaces
+- Forward slashes (`/`) for directory nesting
+- Max total path length: 1024 characters. Max segment length: 255 characters.
+- Path traversal (`..`, `.`) is rejected
+- Hidden files (names starting with `.`) are rejected (e.g. `.env`, `.git`)
+- No leading spaces, backslashes, or control characters
+- Total upload size limit: **50 MB** per deployment
+
+```
+OK:  index.html, assets/style.css, img/logo 2.png, deep/nested/file.js
+BAD: ../secret.txt, .env, file\name.html
+```
+
+### Static File Serving Behavior
+
+- `/` serves `index.html`
+- `/about/` serves `about/index.html`
+- `/about` (no trailing slash) tries the literal file first, then falls back to `about/index.html`
+- Content-Type is determined by file extension (e.g. `.css` → `text/css`, `.js` → `application/javascript`)
+- Responses include `Cache-Control: public, max-age=60`
+
+### TTL
+
+- Minimum: 60 seconds (1 minute)
+- Maximum: 86,400 seconds (24 hours)
+- Default: 3,600 seconds (1 hour)
+- Extending TTL resets the timer (created_at becomes now)
+
+### Client-Side Validation
+
+The library validates inputs before making API calls, throwing an error immediately if values are invalid:
+
+```js
+// Throws at construction time — no API call made
+const tunnel = await mygensite({ port: 3000, subdomain: 'INVALID' });
+// Error: Slug must be lowercase alphanumeric and hyphens...
+
+// Use validators directly for custom checks
+const { validate } = require('mygensite');
+
+validate.validateSlug('my-app');         // { valid: true }
+validate.validateSlug('AB');             // { valid: false, error: 'Slug must be 3-63 characters' }
+validate.validateFilePath('assets/x.js');// { valid: true, cleaned: 'assets/x.js' }
+validate.validateFilePath('../etc');     // { valid: false, error: 'Path traversal...' }
+validate.validateTTL(30);               // { valid: false, error: 'TTL must be...' }
+validate.validateAccessMode('public');   // { valid: true }
+```
+
 ## Error Codes
 
 ### Tunnel creation errors
@@ -237,11 +301,32 @@ const site = await mygensite.deploy({
   access: 'public',
   files: [
     { name: 'index.html', content: '<h1>Hello World</h1>' },
-    { name: 'style.css', content: 'body { font-family: sans-serif; }' },
+    { name: 'assets/style.css', content: 'body { font-family: sans-serif; }' },
   ],
 });
 ```
 
+#### Deploy with curl
+
+Multipart `filename` strips directory paths (e.g. `assets/style.css` becomes `style.css`). Use the `filepaths` JSON field to preserve directory structure:
+
+```bash
+# Flat files (no subdirectories) — filepaths not needed
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F files=@index.html -F files=@style.css
+
+# With subdirectories — filepaths required
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F 'filepaths=["index.html","assets/style.css","assets/js/app.js"]' \
+  -F files=@index.html \
+  -F files=@assets/style.css \
+  -F files=@assets/js/app.js
+```
+
+The `filepaths` field is a JSON array where each element corresponds to the `files` field in order. The server uses these paths instead of the multipart filename.
+
 ### Site instance
 
 The returned object contains the deployment result plus convenience methods:
@@ -265,6 +350,34 @@ The returned object contains the deployment result plus convenience methods:
 | `redeploy(directory)` | directory path (string) | Upload new files, replacing all existing files. Returns a Promise. |
 | `delete(purge?)` | purge (boolean) | Delete the site. `false` = soft delete (files kept), `true` = purge S3 files. Returns a Promise. |
 
+### mygensite.manage(options)
+
+Create a management handle for an existing service when you already have the `slug` and `admin_token` (e.g. saved from a previous deploy). **Do not redeploy just to get a management object** — use this instead.
+
+```js
+const mygensite = require('mygensite');
+
+const site = mygensite.manage({
+  slug: 'demo',
+  admin_token: 'tok_xxx',       // from the original deploy/tunnel response
+  host: 'https://mygen.site',   // optional
+});
+
+// Same methods as deploy result
+await site.updateAccess({ mode: 'public' });
+await site.extendTTL(86400);
+await site.redeploy('./dist-v2');
+await site.delete();
+```
+
+#### Options
+
+| option | type | required | default | description |
+| --- | --- | --- | --- | --- |
+| `slug` | string | yes | — | The service slug |
+| `admin_token` | string | yes | — | The admin token from the original deploy/tunnel response |
+| `host` | string | | `https://mygen.site` | Server URL |
+
 ### Deploy management examples
 
 ```js

package/README.ko.md

@@ -154,6 +154,70 @@ await tunnel.updateAccess({ mode: 'ip_only', allowed_ips: ['1.2.3.0/24'] });
 await tunnel.extendTTL(3600);
 ```
 
+## 제약사항
+
+### Slug (서브도메인)
+
+- 3–63자, 소문자 영문(`a-z`), 숫자(`0-9`), 하이픈(`-`)만 허용
+- 영문자 또는 숫자로 시작/끝나야 함 (하이픈으로 시작/끝 불가)
+- 예약어 사용 불가: `www`, `api`, `dashboard`, `admin`, `mail`, `ftp`, `static`, `docs`, `status`, `health`, `internal`, `tunnel`, `app`, `web`
+- 터널로 사용 중인 slug에 정적 배포 불가 (반대도 동일). 기존 서비스를 먼저 삭제해야 함.
+
+```
+OK:  my-app, demo-v2, test-123
+BAD: My-App, -dash, ab, a_b, my--app..com
+```
+
+### 파일 경로 (정적 배포)
+
+- 세그먼트별 허용 문자: 영문, 숫자, 하이픈(`-`), 밑줄(`_`), 점(`.`), 공백
+- 슬래시(`/`)로 디렉토리 구조 표현
+- 최대 경로 길이: 1024자, 세그먼트 최대: 255자
+- 경로 탈출(`..`, `.`) 거부
+- 숨김 파일(`.`으로 시작하는 이름) 거부 (예: `.env`, `.git`)
+- 선행 공백, 백슬래시, 제어 문자 불가
+- 전체 업로드 크기 제한: **50 MB**
+
+```
+OK:  index.html, assets/style.css, img/logo 2.png, deep/nested/file.js
+BAD: ../secret.txt, .env, file\name.html
+```
+
+### 정적 파일 서빙 동작
+
+- `/` → `index.html` 제공
+- `/about/` → `about/index.html` 제공
+- `/about` (슬래시 없이) → 해당 파일 먼저 시도, 없으면 `about/index.html`로 폴백
+- Content-Type은 확장자로 결정 (`.css` → `text/css`, `.js` → `application/javascript`)
+- 응답에 `Cache-Control: public, max-age=60` 포함
+
+### TTL
+
+- 최소: 60초 (1분)
+- 최대: 86,400초 (24시간)
+- 기본: 3,600초 (1시간)
+- TTL 연장 시 타이머 리셋 (created_at이 현재 시각으로 변경)
+
+### 클라이언트 사전 검증
+
+라이브러리가 API 호출 전에 입력값을 검증하여 잘못된 값은 즉시 에러를 발생시킵니다:
+
+```js
+// 생성 시점에 즉시 에러 — API 호출 없음
+const tunnel = await mygensite({ port: 3000, subdomain: 'INVALID' });
+// Error: Slug must be lowercase alphanumeric and hyphens...
+
+// 검증 함수 직접 사용
+const { validate } = require('mygensite');
+
+validate.validateSlug('my-app');         // { valid: true }
+validate.validateSlug('AB');             // { valid: false, error: 'Slug must be 3-63 characters' }
+validate.validateFilePath('assets/x.js');// { valid: true, cleaned: 'assets/x.js' }
+validate.validateFilePath('../etc');     // { valid: false, error: '경로 탈출 불가...' }
+validate.validateTTL(30);               // { valid: false, error: 'TTL 범위 초과...' }
+validate.validateAccessMode('public');   // { valid: true }
+```
+
 ## 에러 코드
 
 ### 터널 생성 에러
@@ -237,11 +301,32 @@ const site = await mygensite.deploy({
   access: 'public',
   files: [
     { name: 'index.html', content: '<h1>Hello World</h1>' },
-    { name: 'style.css', content: 'body { font-family: sans-serif; }' },
+    { name: 'assets/style.css', content: 'body { font-family: sans-serif; }' },
   ],
 });
 ```
 
+#### curl로 배포
+
+Multipart의 `filename`은 디렉토리 경로를 제거합니다 (예: `assets/style.css` &rarr; `style.css`). 서브디렉토리가 있으면 `filepaths` JSON 필드를 사용하세요:
+
+```bash
+# 플랫 파일 (서브디렉토리 없음) - filepaths 불필요
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F files=@index.html -F files=@style.css
+
+# 서브디렉토리 있음 - filepaths 필수
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F 'filepaths=["index.html","assets/style.css","assets/js/app.js"]' \
+  -F files=@index.html \
+  -F files=@assets/style.css \
+  -F files=@assets/js/app.js
+```
+
+`filepaths`는 JSON 배열로, 각 원소가 `files` 필드와 순서대로 대응됩니다. 서버는 multipart filename 대신 이 경로를 사용합니다.
+
 ### Site 인스턴스
 
 반환 객체에 배포 결과와 편의 메서드가 포함됩니다:
@@ -265,6 +350,35 @@ const site = await mygensite.deploy({
 | `redeploy(directory)` | 디렉토리 경로 (string) | 새 파일로 교체 업로드. Promise 반환. |
 | `delete(purge?)` | purge (boolean) | 사이트 삭제. `false` = 소프트 삭제 (파일 유지), `true` = S3 파일까지 삭제. Promise 반환. |
 
+### mygensite.manage(options)
+
+기존 서비스의 `slug`과 `admin_token`이 있을 때 관리 핸들을 생성합니다 (예: 이전 배포에서 저장해둔 값).
+**관리 객체를 얻기 위해 재배포하지 마세요** — 이 함수를 사용하세요.
+
+```js
+const mygensite = require('mygensite');
+
+const site = mygensite.manage({
+  slug: 'demo',
+  admin_token: 'tok_xxx',       // 원래 배포/터널 생성 시 반환된 값
+  host: 'https://mygen.site',   // 선택
+});
+
+// deploy 결과와 동일한 메서드 사용 가능
+await site.updateAccess({ mode: 'public' });
+await site.extendTTL(86400);
+await site.redeploy('./dist-v2');
+await site.delete();
+```
+
+#### 옵션
+
+| 옵션 | 타입 | 필수 | 기본값 | 설명 |
+| --- | --- | --- | --- | --- |
+| `slug` | string | 예 | — | 서비스 slug |
+| `admin_token` | string | 예 | — | 원래 배포/터널 생성 시 반환된 admin token |
+| `host` | string | | `https://mygen.site` | 서버 URL |
+
 ### 배포 관리 예제
 
 ```js

package/README.md

@@ -66,6 +66,27 @@ await site.delete();                // soft delete
 await site.delete(true);            // purge (delete S3 files too)
 ```
 
+## Manage (existing service)
+
+Use `manage()` when you already have the `slug` and `admin_token` from a previous deploy or tunnel.
+**Do not redeploy just to get a management object** — use this instead.
+
+```js
+const mygensite = require('mygensite');
+
+const site = mygensite.manage({
+  slug: 'demo',
+  admin_token: 'tok_xxx',       // from the original deploy response
+  host: 'https://mygen.site',   // optional
+});
+
+// Same methods as deploy result
+await site.updateAccess({ mode: 'public' });
+await site.extendTTL(86400);
+await site.redeploy('./dist-v2');
+await site.delete();
+```
+
 ## Access Modes
 
 | mode | behavior |
@@ -75,6 +96,48 @@ await site.delete(true);            // purge (delete S3 files too)
 | `ip_only` | allowed_ips only |
 | `both` | allowed_ips + password (default) |
 
+## Constraints
+
+### Slug (subdomain)
+
+- 3–63 characters, lowercase letters, numbers, and hyphens only
+- Must start and end with a letter or number (not a hyphen)
+- Reserved: `www`, `api`, `dashboard`, `admin`, `docs`, `status`, `health`, etc.
+- A slug used as a tunnel cannot be reused for static deploy (and vice versa)
+
+### File Paths (static deploy)
+
+- Allowed: letters, numbers, `-`, `_`, `.`, spaces, `/` for directories
+- Max path: 1024 chars, max segment: 255 chars
+- No `..`, no hidden files (`.env`), no backslashes
+- Total upload limit: **50 MB**
+
+### Static File Serving
+
+- `/` → `index.html`
+- `/about/` → `about/index.html`
+- `/about` (no slash) → falls back to `about/index.html`
+- Content-Type set by extension (`.css` → `text/css`, `.js` → `application/javascript`)
+
+### Client-Side Validation
+
+The library validates slug, file paths, TTL, and access mode before making API calls:
+
+```js
+const mygensite = require('mygensite');
+
+// Throws immediately if slug is invalid
+const tunnel = await mygensite({ port: 3000, subdomain: 'INVALID' });
+// Error: Slug must be lowercase alphanumeric and hyphens...
+
+// Use validators directly
+const { validate } = mygensite;
+validate.validateSlug('my-app');       // { valid: true }
+validate.validateSlug('AB');           // { valid: false, error: '...' }
+validate.validateFilePath('../etc');   // { valid: false, error: '...' }
+validate.validateTTL(30);             // { valid: false, error: '...' }
+```
+
 ## Error Codes
 
 | status | error | when | fix |
@@ -93,9 +156,69 @@ await site.delete(true);            // purge (delete S3 files too)
 
 ```bash
 # Tunnel
-mygensite --port 3000 --subdomain my-app --access password --password secret --ttl 7200
+mygensite --port 3000 --subdomain my-app --access password --password 'secret' --ttl 7200
 
-# Deploy (coming soon)
+# Deploy
+mygensite deploy --directory ./dist --subdomain demo --access public --ttl 86400
+
+# Deploy with password
+mygensite deploy -d ./dist -s private-demo --access password --password 'mypass'
+
+# Redeploy (reuse admin_token)
+mygensite deploy -d ./dist-v2 -s demo --admin-token tok_xxx
+```
+
+## curl Deploy
+
+```bash
+# Simple (flat files)
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F files=@index.html -F files=@style.css
+
+# With subdirectories — use filepaths to preserve directory structure
+curl -X POST https://mygen.site/api/deploy \
+  -F slug=demo -F access='{"mode":"public"}' \
+  -F 'filepaths=["index.html","assets/style.css","assets/js/app.js"]' \
+  -F files=@index.html \
+  -F files=@assets/style.css \
+  -F files=@assets/js/app.js
+```
+
+> **Note:** Multipart `filename` strips directory paths. The `filepaths` JSON field tells the server the correct path for each file, in order.
+
+## Passwords with Special Characters
+
+When using the CLI or curl, passwords with special characters (like `!`, `$`, `&`, `\`) may be modified by your shell before reaching the program.
+
+**Use single quotes** to prevent shell interpretation:
+
+```bash
+# CORRECT — single quotes preserve special characters
+mygensite --port 3000 --password 'my!p@ss$word'
+
+# WRONG — double quotes: bash expands ! and $
+mygensite --port 3000 --password "my!p@ss$word"
+
+# WRONG — unquoted: shell interprets special chars
+mygensite --port 3000 --password my!p@ss$word
+```
+
+When using curl:
+
+```bash
+# CORRECT
+curl 'http://mygen.site/api/tunnels/my-app?password=my!pass'
+
+# WRONG — double quotes let bash expand !
+curl "http://mygen.site/api/tunnels/my-app?password=my!pass"
+```
+
+When using the **Node.js API**, no escaping is needed — JavaScript string literals preserve all characters:
+
+```js
+const tunnel = await mygensite({ port: 3000, password: 'my!p@ss$word' });
+// password is stored and returned exactly as provided
 ```
 
 ## Documentation

package/bin/lt.js

@@ -5,125 +5,184 @@ const openurl = require('openurl');
 const yargs = require('yargs');
 
 const localtunnel = require('../localtunnel');
+const deploy = require('../lib/deploy');
 const { version } = require('../package');
 
-const { argv } = yargs
-  .usage('Usage: mygensite --port [num] <options>')
+yargs
+  .usage('Usage: mygensite <command> [options]')
   .env(true)
-  .option('p', {
-    alias: 'port',
-    describe: 'Internal HTTP server port',
-  })
-  .option('h', {
-    alias: 'host',
-    describe: 'Upstream server providing forwarding',
-    default: 'https://mygen.site',
-  })
-  .option('s', {
-    alias: 'subdomain',
-    describe: 'Request this subdomain',
-  })
-  .option('l', {
-    alias: 'local-host',
-    describe: 'Tunnel traffic to this host instead of localhost, override Host header to this host',
-  })
-  .option('local-https', {
-    describe: 'Tunnel traffic to a local HTTPS server',
-  })
-  .option('local-cert', {
-    describe: 'Path to certificate PEM file for local HTTPS server',
-  })
-  .option('local-key', {
-    describe: 'Path to certificate key file for local HTTPS server',
-  })
-  .option('local-ca', {
-    describe: 'Path to certificate authority file for self-signed certificates',
-  })
-  .option('allow-invalid-cert', {
-    describe: 'Disable certificate checks for your local HTTPS server (ignore cert/key/ca options)',
-  })
-  .options('o', {
-    alias: 'open',
-    describe: 'Opens the tunnel URL in your browser',
-  })
-  .option('print-requests', {
-    describe: 'Print basic request info',
-  })
-  .option('access', {
-    describe: 'Access control mode: public, password, ip_only, both',
-  })
-  .option('password', {
-    describe: 'Password for access control',
-  })
-  .option('owner-email', {
-    describe: 'Owner email for dashboard management',
-  })
-  .option('ttl', {
-    describe: 'Tunnel TTL in seconds (60-86400)',
-    type: 'number',
-  })
-  .require('port')
-  .boolean('local-https')
-  .boolean('allow-invalid-cert')
-  .boolean('print-requests')
-  .help('help', 'Show this help and exit')
-  .version(version);
+  .command('deploy', 'Deploy a static site', (y) => {
+    return y
+      .option('directory', {
+        alias: 'd',
+        describe: 'Directory to deploy',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('host', {
+        alias: 'h',
+        describe: 'Server host',
+        default: 'https://mygen.site',
+      })
+      .option('subdomain', {
+        alias: 's',
+        describe: 'Subdomain (slug)',
+      })
+      .option('access', {
+        describe: 'Access mode: public, password, ip_only, both',
+      })
+      .option('password', {
+        describe: 'Password for access control',
+      })
+      .option('owner-email', {
+        describe: 'Owner email for dashboard',
+      })
+      .option('ttl', {
+        describe: 'TTL in seconds (60-86400)',
+        type: 'number',
+      })
+      .option('admin-token', {
+        describe: 'Admin token for redeployment',
+      });
+  }, async (argv) => {
+    try {
+      const result = await deploy({
+        host: argv.host,
+        subdomain: argv.subdomain,
+        directory: argv.directory,
+        access: argv.access,
+        password: argv.password,
+        owner_email: argv.ownerEmail,
+        ttl: argv.ttl,
+        admin_token: argv.adminToken,
+      });
 
-if (typeof argv.port !== 'number') {
-  yargs.showHelp();
-  console.error('\nInvalid argument: `port` must be a number');
-  process.exit(1);
-}
+      console.log('your url is: %s', result.url);
+      console.log('your slug is: %s', result.slug);
+      if (result.admin_token) {
+        console.log('your admin_token is: %s', result.admin_token);
+      }
+      if (result.password) {
+        console.log('your password is: %s', result.password);
+      }
+      if (result.expires_at) {
+        console.log('expires at: %s', result.expires_at);
+      }
+    } catch (err) {
+      console.error('deploy failed: %s', err.message);
+      process.exit(1);
+    }
+  })
+  .command('$0', 'Create a tunnel (default)', (y) => {
+    return y
+      .option('p', {
+        alias: 'port',
+        describe: 'Internal HTTP server port',
+      })
+      .option('h', {
+        alias: 'host',
+        describe: 'Upstream server providing forwarding',
+        default: 'https://mygen.site',
+      })
+      .option('s', {
+        alias: 'subdomain',
+        describe: 'Request this subdomain',
+      })
+      .option('l', {
+        alias: 'local-host',
+        describe: 'Tunnel traffic to this host instead of localhost, override Host header to this host',
+      })
+      .option('local-https', {
+        describe: 'Tunnel traffic to a local HTTPS server',
+      })
+      .option('local-cert', {
+        describe: 'Path to certificate PEM file for local HTTPS server',
+      })
+      .option('local-key', {
+        describe: 'Path to certificate key file for local HTTPS server',
+      })
+      .option('local-ca', {
+        describe: 'Path to certificate authority file for self-signed certificates',
+      })
+      .option('allow-invalid-cert', {
+        describe: 'Disable certificate checks for your local HTTPS server (ignore cert/key/ca options)',
+      })
+      .options('o', {
+        alias: 'open',
+        describe: 'Opens the tunnel URL in your browser',
+      })
+      .option('print-requests', {
+        describe: 'Print basic request info',
+      })
+      .option('access', {
+        describe: 'Access control mode: public, password, ip_only, both',
+      })
+      .option('password', {
+        describe: 'Password for access control',
+      })
+      .option('owner-email', {
+        describe: 'Owner email for dashboard management',
+      })
+      .option('ttl', {
+        describe: 'Tunnel TTL in seconds (60-86400)',
+        type: 'number',
+      })
+      .boolean('local-https')
+      .boolean('allow-invalid-cert')
+      .boolean('print-requests');
+  }, async (argv) => {
+    if (typeof argv.port !== 'number') {
+      yargs.showHelp();
+      console.error('\nInvalid argument: `port` must be a number');
+      process.exit(1);
+    }
 
-(async () => {
-  const tunnel = await localtunnel({
-    port: argv.port,
-    host: argv.host,
-    subdomain: argv.subdomain,
-    local_host: argv.localHost,
-    local_https: argv.localHttps,
-    local_cert: argv.localCert,
-    local_key: argv.localKey,
-    local_ca: argv.localCa,
-    allow_invalid_cert: argv.allowInvalidCert,
-    access: argv.access,
-    password: argv.password,
-    owner_email: argv.ownerEmail,
-    ttl: argv.ttl,
-  }).catch(err => {
-    throw err;
-  });
+    const tunnel = await localtunnel({
+      port: argv.port,
+      host: argv.host,
+      subdomain: argv.subdomain,
+      local_host: argv.localHost,
+      local_https: argv.localHttps,
+      local_cert: argv.localCert,
+      local_key: argv.localKey,
+      local_ca: argv.localCa,
+      allow_invalid_cert: argv.allowInvalidCert,
+      access: argv.access,
+      password: argv.password,
+      owner_email: argv.ownerEmail,
+      ttl: argv.ttl,
+    }).catch(err => {
+      throw err;
+    });
 
-  tunnel.on('error', err => {
-    throw err;
-  });
+    tunnel.on('error', err => {
+      throw err;
+    });
 
-  console.log('your url is: %s', tunnel.url);
+    console.log('your url is: %s', tunnel.url);
 
-  if (tunnel.password) {
-    console.log('your password is: %s', tunnel.password);
-  }
+    if (tunnel.password) {
+      console.log('your password is: %s', tunnel.password);
+    }
 
-  if (tunnel.admin_token) {
-    console.log('your admin_token is: %s', tunnel.admin_token);
-  }
+    if (tunnel.admin_token) {
+      console.log('your admin_token is: %s', tunnel.admin_token);
+    }
 
-  /**
-   * `cachedUrl` is set when using a proxy server that support resource caching.
-   * This URL generally remains available after the tunnel itself has closed.
-   * @see https://github.com/localtunnel/localtunnel/pull/319#discussion_r319846289
-   */
-  if (tunnel.cachedUrl) {
-    console.log('your cachedUrl is: %s', tunnel.cachedUrl);
-  }
+    if (tunnel.cachedUrl) {
+      console.log('your cachedUrl is: %s', tunnel.cachedUrl);
+    }
 
-  if (argv.open) {
-    openurl.open(tunnel.url);
-  }
+    if (argv.open) {
+      openurl.open(tunnel.url);
+    }
 
-  if (argv['print-requests']) {
-    tunnel.on('request', info => {
-      console.log(new Date().toString(), info.method, info.path);
-    });
-  }
-})();
+    if (argv['print-requests']) {
+      tunnel.on('request', info => {
+        console.log(new Date().toString(), info.method, info.path);
+      });
+    }
+  })
+  .help('help', 'Show this help and exit')
+  .version(version)
+  .parse();

package/lib/Tunnel.js

@@ -6,6 +6,7 @@ const axios = require('axios');
 const debug = require('debug')('localtunnel:client');
 
 const TunnelCluster = require('./TunnelCluster');
+const { validateSlug, validateTTL, validateAccessMode } = require('./validate');
 
 module.exports = class Tunnel extends EventEmitter {
   constructor(opts = {}) {
@@ -15,6 +16,26 @@ module.exports = class Tunnel extends EventEmitter {
     if (!this.opts.host) {
       this.opts.host = 'https://mygen.site';
     }
+
+    // Client-side validation — fail fast before API call
+    if (opts.subdomain) {
+      const slugCheck = validateSlug(opts.subdomain);
+      if (!slugCheck.valid) {
+        throw new Error(slugCheck.error);
+      }
+    }
+    if (opts.ttl != null) {
+      const ttlCheck = validateTTL(Number(opts.ttl));
+      if (!ttlCheck.valid) {
+        throw new Error(ttlCheck.error);
+      }
+    }
+    if (opts.access) {
+      const accessCheck = validateAccessMode(opts.access);
+      if (!accessCheck.valid) {
+        throw new Error(accessCheck.error);
+      }
+    }
   }
 
   _getInfo(body) {

package/lib/deploy.js

@@ -3,6 +3,7 @@ const path = require('path');
 const axios = require('axios');
 const FormData = require('form-data');
 const debug = require('debug')('mygensite:deploy');
+const { validateSlug, validateFilePath, validateTTL, validateAccessMode } = require('./validate');
 
 const DEFAULT_HOST = 'https://mygen.site';
 
@@ -94,6 +95,29 @@ async function deploy(options) {
     admin_token,
   } = options;
 
+  // Client-side validation — fail fast before API call
+  if (subdomain) {
+    const slugCheck = validateSlug(subdomain);
+    if (!slugCheck.valid) {
+      throw new Error(slugCheck.error);
+    }
+  }
+  if (ttl != null) {
+    const ttlCheck = validateTTL(Number(ttl));
+    if (!ttlCheck.valid) {
+      throw new Error(ttlCheck.error);
+    }
+  }
+  if (access) {
+    const mode = typeof access === 'string' ? access : access.mode;
+    if (mode) {
+      const accessCheck = validateAccessMode(mode);
+      if (!accessCheck.valid) {
+        throw new Error(accessCheck.error);
+      }
+    }
+  }
+
   // Build file list
   let fileList;
   if (directory) {
@@ -116,6 +140,15 @@ async function deploy(options) {
     throw new Error('No files found to deploy');
   }
 
+  // Validate all file paths before uploading
+  for (const file of fileList) {
+    const pathCheck = validateFilePath(file.name);
+    if (!pathCheck.valid) {
+      throw new Error(`Invalid file path "${file.name}": ${pathCheck.error}`);
+    }
+    file.name = pathCheck.cleaned;
+  }
+
   debug('deploying %d files to %s', fileList.length, host);
 
   // Build multipart form
@@ -137,9 +170,12 @@ async function deploy(options) {
   }
   form.append('access', JSON.stringify(accessObj));
 
+  // Send file paths as separate JSON field (busboy strips directories from filename)
+  form.append('filepaths', JSON.stringify(fileList.map(f => f.name)));
+
   for (const file of fileList) {
     form.append('files', file.content, {
-      filename: file.name,
+      filepath: file.name,
       contentType: file.contentType,
     });
   }
@@ -169,4 +205,36 @@ async function deploy(options) {
   return data;
 }
 
+/**
+ * Create a management handle for an existing service.
+ * Use this when you already have the slug and admin_token (e.g. from a previous deploy).
+ *
+ * @param {object} options
+ * @param {string} options.slug - The service slug
+ * @param {string} options.admin_token - The admin token from the original deploy
+ * @param {string} [options.host] - API host (default: https://mygen.site)
+ * @returns {object} Management object with updateAccess, extendTTL, redeploy, delete methods
+ */
+function manage(options) {
+  const {
+    slug,
+    admin_token,
+    host = DEFAULT_HOST,
+  } = options;
+
+  if (!slug) throw new Error('slug is required');
+  if (!admin_token) throw new Error('admin_token is required');
+
+  return {
+    slug,
+    admin_token,
+    url: `https://${slug}.${host.replace(/^https?:\/\//, '')}`,
+    updateAccess: (access) => patchService(host, slug, admin_token, { access }),
+    extendTTL: (ttl) => patchService(host, slug, admin_token, { ttl }),
+    redeploy: (dir) => deploy({ host, subdomain: slug, directory: dir, admin_token }),
+    delete: (purge) => deleteService(host, slug, admin_token, purge),
+  };
+}
+
 module.exports = deploy;
+module.exports.manage = manage;

package/lib/validate.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Validation helpers for mygensite.
+ *
+ * These mirror the server-side rules so you can catch errors locally
+ * before making an API call.
+ */
+
+// Must match: server/src/api/routes/tunnels.ts SLUG_REGEX
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/;
+
+const RESERVED_SLUGS = new Set([
+  'www', 'api', 'dashboard', 'admin', 'mail',
+  'ftp', 'static', 'docs', 'status', 'health',
+  'internal', 'tunnel', 'app', 'web',
+]);
+
+// Must match: server/src/api/routes/deploy.ts SAFE_PATH_SEGMENT
+const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9_\-. ]+$/;
+
+const VALID_ACCESS_MODES = ['public', 'password', 'ip_only', 'both'];
+
+/**
+ * Validate a slug (subdomain) name.
+ * @param {string} slug
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateSlug(slug) {
+  if (!slug || typeof slug !== 'string') {
+    return { valid: false, error: 'Slug is required' };
+  }
+  if (slug.length < 3 || slug.length > 63) {
+    return { valid: false, error: 'Slug must be 3-63 characters' };
+  }
+  if (!SLUG_REGEX.test(slug)) {
+    return { valid: false, error: 'Slug must be lowercase alphanumeric and hyphens, starting and ending with alphanumeric' };
+  }
+  if (RESERVED_SLUGS.has(slug)) {
+    return { valid: false, error: `"${slug}" is a reserved slug` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate a file path for static deployment.
+ * @param {string} name - File path (e.g. "index.html", "assets/style.css")
+ * @returns {{ valid: boolean, cleaned?: string, error?: string }}
+ */
+function validateFilePath(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, error: 'File path is required' };
+  }
+  if (name.length > 1024) {
+    return { valid: false, error: 'File path must not exceed 1024 characters' };
+  }
+
+  const cleaned = name.replace(/^\/+/, '');
+  if (!cleaned) {
+    return { valid: false, error: 'File path is empty after cleaning' };
+  }
+
+  const segments = cleaned.split('/');
+  for (const seg of segments) {
+    if (!seg) {
+      return { valid: false, error: 'File path contains empty segments (double slash)' };
+    }
+    if (seg === '.' || seg === '..') {
+      return { valid: false, error: 'Path traversal ("." or "..") is not allowed' };
+    }
+    if (seg.length > 255) {
+      return { valid: false, error: `Segment "${seg.slice(0, 20)}..." exceeds 255 characters` };
+    }
+    if (seg.startsWith('.')) {
+      return { valid: false, error: `Hidden files (starting with ".") are not allowed: "${seg}"` };
+    }
+    if (seg.startsWith(' ')) {
+      return { valid: false, error: 'File names must not start with a space' };
+    }
+    if (!SAFE_PATH_SEGMENT.test(seg)) {
+      return { valid: false, error: `Invalid characters in "${seg}". Allowed: letters, numbers, hyphens, underscores, dots, spaces` };
+    }
+  }
+
+  return { valid: true, cleaned: segments.join('/') };
+}
+
+/**
+ * Validate TTL value.
+ * @param {number} ttl - TTL in seconds
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateTTL(ttl) {
+  if (typeof ttl !== 'number' || !Number.isFinite(ttl)) {
+    return { valid: false, error: 'TTL must be a number' };
+  }
+  if (ttl < 60 || ttl > 86400) {
+    return { valid: false, error: 'TTL must be between 60 and 86400 seconds (1 min to 24 hours)' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate access mode.
+ * @param {string} mode
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateAccessMode(mode) {
+  if (!VALID_ACCESS_MODES.includes(mode)) {
+    return { valid: false, error: `Access mode must be one of: ${VALID_ACCESS_MODES.join(', ')}` };
+  }
+  return { valid: true };
+}
+
+module.exports = {
+  validateSlug,
+  validateFilePath,
+  validateTTL,
+  validateAccessMode,
+  SLUG_REGEX,
+  RESERVED_SLUGS,
+  VALID_ACCESS_MODES,
+};

package/localtunnel.js

@@ -1,5 +1,6 @@
 const Tunnel = require('./lib/Tunnel');
 const deploy = require('./lib/deploy');
+const validate = require('./lib/validate');
 
 function localtunnel(arg1, arg2, arg3) {
   const options = typeof arg1 === 'object' ? arg1 : { ...arg2, port: arg1 };
@@ -15,5 +16,7 @@ function localtunnel(arg1, arg2, arg3) {
 }
 
 localtunnel.deploy = deploy;
+localtunnel.manage = deploy.manage;
+localtunnel.validate = validate;
 
 module.exports = localtunnel;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mygensite",
   "description": "Expose your localhost to mygen.site with access control",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",