@elf5/periscope 1.0.64

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Elf Industries, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# Periscope
+
+Secure tunnels from localhost to the internet — [hosted by Elf 5](https://elf5.com) or self-hosted on your own infrastructure.
+
+## Install
+
+```bash
+npm install -g @elf5/periscope
+```
+
+## Quick Start
+
+```bash
+periscope connect my-app --target http://localhost:3000
+```
+
+The CLI opens a browser to authenticate on first run, then prints your public tunnel URL.
+
+## Commands
+
+```bash
+periscope connect <name> --target <url>   # Create a tunnel
+periscope auth login                      # Authenticate
+periscope auth logout                     # Sign out
+periscope config set --server <url>       # Set server URL
+periscope config show                     # Show configuration
+periscope status                          # Check connection and auth status
+periscope feedback "<message>"            # Send feedback to Elf 5
+```
+
+## Beta
+
+Periscope is currently in free beta — no credit card required, limited to 100 users. [Get started at elf5.com](https://elf5.com/getting-started).
+
+## Support
+
+Email [support@elf5.com](mailto:support@elf5.com) or run `periscope feedback "your message"`.
+
+## License
+
+MIT

package/dist/__tests__/e2e/cli-test-utils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared CLI Test Utilities
+ *
+ * Common helpers for CLI E2E tests to keep tests DRY.
+ */
+import { ChildProcess } from 'child_process';
+import * as http from 'http';
+export declare const CLI_PATH: string;
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ExecOptions {
+    env?: Record<string, string>;
+    timeout?: number;
+    input?: string;
+}
+export interface CliTestContext {
+    tempConfigDir: string;
+    cleanup: () => void;
+}
+/**
+ * Verify CLI binary exists, throw if not
+ */
+export declare function ensureCliBinaryExists(): void;
+/**
+ * Create isolated test context with temp directory
+ */
+export declare function createCliTestContext(prefix: string): CliTestContext;
+/**
+ * Create an execCli function bound to a specific config directory and base env
+ */
+export declare function createExecCli(tempConfigDir: string, baseEnv?: Record<string, string>): (args: string[], options?: ExecOptions) => Promise<ExecResult>;
+/**
+ * Spawn a long-running CLI process with output capture
+ */
+export declare function spawnCliProcess(args: string[], tempConfigDir: string, extraEnv?: Record<string, string>, timeoutMs?: number): {
+    child: ChildProcess;
+    getOutput: () => {
+        stdout: string;
+        stderr: string;
+    };
+};
+/**
+ * Wait for a condition in process output or timeout
+ */
+export declare function waitForOutput(getOutput: () => {
+    stdout: string;
+    stderr: string;
+}, condition: (output: {
+    stdout: string;
+    stderr: string;
+}) => boolean, timeoutMs?: number): Promise<void>;
+/**
+ * Kill process and wait for exit
+ */
+export declare function killAndWait(child: ChildProcess, signal?: NodeJS.Signals): Promise<void>;
+/**
+ * Extract the remote URL from CLI connect output
+ */
+export declare function extractRemoteUrl(output: string): string | null;
+/**
+ * Extract hostname from a URL
+ */
+export declare function extractHostname(url: string): string | null;
+/**
+ * Make an HTTP request with a custom Host header.
+ *
+ * Node.js fetch() doesn't allow overriding the Host header for security reasons
+ * (see https://github.com/nodejs/node/issues/50305).
+ * We need to use http.request() directly to set custom Host headers.
+ */
+export declare function httpRequestWithHost(url: string, hostHeader: string, timeoutMs?: number): Promise<{
+    status: number;
+    body: string;
+    headers: http.IncomingHttpHeaders;
+}>;
+//# sourceMappingURL=cli-test-utils.d.ts.map

package/dist/__tests__/e2e/cli-test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-test-utils.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/cli-test-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAS,YAAY,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAY7B,eAAO,MAAM,QAAQ,QAA+C,CAAC;AAMrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAM5C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAanE;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,IAGlC,MAAM,MAAM,EAAE,EACd,UAAS,WAAgB,KACxB,OAAO,CAAC,UAAU,CAAC,CAuCvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACrC,SAAS,GAAE,MAAc,GACxB;IACD,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CA0BA;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACnD,SAAS,EAAE,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,EAClE,SAAS,GAAE,MAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,YAAY,EACnB,MAAM,GAAE,MAAM,CAAC,OAAmB,GACjC,OAAO,CAAC,IAAI,CAAC,CAMf;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAc,GACxB,OAAO,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;CACnC,CAAC,CAiCD"}

package/dist/__tests__/e2e/mock-server.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mock Server Responses for Dual-Mode Testing
+ *
+ * When the real server is not available, these mocks are used.
+ * This allows tests to run locally without a server while still
+ * exercising the same code paths.
+ */
+/**
+ * Mock MSAL configuration matching real server response structure.
+ */
+export declare const MOCK_MSAL_CONFIG: {
+    clientId: string;
+    authority: string;
+    scopes: string[];
+};
+export declare const MOCK_OPENAPI_SPEC: {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    paths: {
+        '/api/user': {};
+        '/api/user/tunnel': {};
+    };
+};
+export declare const MOCK_SWAGGER_HTML = "\n<!DOCTYPE html>\n<html>\n<head><title>Swagger UI</title></head>\n<body>Swagger UI mock</body>\n</html>\n";
+/**
+ * Mock fetch that returns canned responses for known endpoints.
+ * Used when the real server is not available.
+ */
+export declare function createMockFetch(baseUrl: string): (input: string | URL | Request, _init?: RequestInit) => Promise<Response>;
+/**
+ * Install mock fetch globally.
+ * Call in beforeAll/beforeEach when server is not available.
+ */
+export declare function installMockFetch(baseUrl: string): void;
+/**
+ * Restore original fetch.
+ * Call in afterAll/afterEach to clean up.
+ */
+export declare function restoreFetch(): void;
+//# sourceMappingURL=mock-server.d.ts.map

package/dist/__tests__/e2e/mock-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-server.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/mock-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;CAI5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;CAU7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,+GAM7B,CAAC;AAMF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,IAE3C,OAAO,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,QAAQ,WAAW,KAClB,OAAO,CAAC,QAAQ,CAAC,CAoCrB;AAQD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAKnC"}

package/dist/__tests__/e2e/test-server.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Test Server for E2E Testing
+ *
+ * A simple HTTP server that can be:
+ * 1. Controlled programmatically in tests (start/stop/restart)
+ * 2. Run standalone via: npx tsx src/__tests__/e2e/test-server.ts
+ *
+ * The server returns HTML that includes the request path, which tests
+ * can verify to confirm traffic is flowing through the tunnel.
+ */
+export interface TestServerOptions {
+    port?: number;
+    host?: string;
+}
+export declare class TestServer {
+    private server;
+    private port;
+    private host;
+    constructor(options?: TestServerOptions);
+    /**
+     * Start the test server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the test server
+     */
+    stop(): Promise<void>;
+    /**
+     * Restart the test server
+     */
+    restart(): Promise<void>;
+    /**
+     * Check if server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the server URL
+     */
+    getUrl(): string;
+    /**
+     * Get the port
+     */
+    getPort(): number;
+    private handleRequest;
+}
+//# sourceMappingURL=test-server.d.ts.map

package/dist/__tests__/e2e/test-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/test-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,OAAO,GAAE,iBAAsB;IAK3C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB,OAAO,CAAC,aAAa;CA+JtB"}

package/dist/__tests__/e2e/test-utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared E2E Test Utilities
+ *
+ * Provides common configuration and helpers for all E2E tests.
+ */
+/**
+ * Server URL for E2E tests - requires a TEST server (not dev server)
+ *
+ * The test server must be running with ASPNETCORE_ENVIRONMENT=Test
+ * which enables TestAuthHandler for X-Test-User header authentication.
+ *
+ * Priority:
+ * 1. PERISCOPE_TEST_SERVER_URL (explicit test server)
+ * 2. PERISCOPE_SERVER_URL (used by CI workflows)
+ * 3. In CI: fallback to http://localhost:8080
+ * 4. Otherwise: empty string (tests will skip)
+ *
+ * NOTE: The dev server at periscope-server:8080 is NOT suitable for
+ * E2E tests as it uses real Azure AD authentication.
+ */
+export declare const TEST_SERVER_URL: string;
+export declare const TEST_USER_HEADER = "X-Test-User";
+export declare const DEFAULT_TEST_USER = "test@example.com";
+/**
+ * Check if test server is available
+ */
+export declare function checkTestServer(): Promise<boolean>;
+/**
+ * Initialize test server availability check (call in beforeAll)
+ * Returns true if server is available, false otherwise
+ */
+export declare function initTestServer(): Promise<boolean>;
+/**
+ * Get current server availability status
+ */
+export declare function isServerAvailable(): boolean;
+/**
+ * Skip helper - returns true if test should be skipped
+ * Use: if (skipIfNoServer()) return;
+ */
+export declare function skipIfNoServer(): boolean;
+/**
+ * Generate unique name for test resources to avoid conflicts
+ */
+export declare const uniqueName: (prefix: string) => string;
+/**
+ * Set up test authentication for CLI commands.
+ *
+ * This writes a fake token to the token cache that the CLI will read
+ * and send as a Bearer token. The test server's TestAuthHandler will
+ * extract the email from the token format: "test-token-{email}"
+ *
+ * @param email - Test user email (default: test@example.com)
+ * @param homeDir - Custom home directory (default: os.homedir())
+ */
+export declare function setupTestAuth(email?: string, homeDir?: string): void;
+/**
+ * Clear test authentication.
+ *
+ * Removes the cached token to simulate logged-out state.
+ *
+ * @param homeDir - Custom home directory (default: os.homedir())
+ */
+export declare function clearTestAuth(homeDir?: string): void;
+/**
+ * Get the path to the token cache file.
+ *
+ * @param homeDir - Custom home directory (default: os.homedir())
+ */
+export declare function getTokenCachePath(homeDir?: string): string;
+/**
+ * Generate and register an SSH key pair for e2e tests that create tunnels.
+ *
+ * With ELF-184, SSH keys are client-side. setupTestAuth() only writes the MSAL
+ * token; this function generates a key and registers the public key with the
+ * server so tunnel SSH authentication succeeds.
+ *
+ * Must be called after setupTestAuth() and only when the server is available.
+ *
+ * @param homeDir - Temp config dir used as HOME for the CLI process
+ * @param email   - Test user email passed as PERISCOPE_TEST_USER
+ */
+export declare function setupTestSshKey(homeDir: string, email?: string): void;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/__tests__/e2e/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/__tests__/e2e/test-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,QAGqB,CAAC;AAElD,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAC9C,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAQpD;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAaxD;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CA8BvD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAMxC;AAMD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,MACyB,CAAC;AAkBtE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,GAAE,MAA0B,EACjC,OAAO,GAAE,MAAqB,GAC7B,IAAI,CAsBN;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,MAAqB,GAAG,IAAI,CAmBlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAqB,GAAG,MAAM,CAExE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAA0B,GAChC,IAAI,CAkBN"}

package/dist/__tests__/helpers/assertions.d.ts

@@ -0,0 +1,5 @@
+export declare function assertTunnelValid(tunnel: any): void;
+export declare function assertConfigValid(config: any): void;
+export declare function assertAuthValid(auth: any): void;
+export declare function assertMSALConfigValid(msalConfig: any): void;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/__tests__/helpers/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/assertions.ts"],"names":[],"mappings":"AAKA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,QAM5C;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,QAe5C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,GAAG,QAKxC;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,GAAG,QAMpD"}

package/dist/__tests__/helpers/mock-factory.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Mock factory functions for creating test data
+ */
+export declare const mockConfig: (overrides?: {}) => {
+    serverUrl: string;
+    logLevel: string;
+    allowUntrustedCerts: boolean;
+};
+export declare const mockTunnel: (overrides?: {}) => {
+    id: string;
+    name: string;
+    clientPort: number;
+    sshTunnelPort: number;
+    remoteURL: string;
+    status: string;
+    createdAt: string;
+};
+export declare const mockMSALConfig: (overrides?: {}) => {
+    clientId: string;
+    authority: string;
+    scopes: string[];
+};
+export declare const mockAuthToken: (overrides?: {}) => {
+    accessToken: string;
+    expiresOn: Date;
+    account: {
+        username: string;
+        name: string;
+    };
+};
+//# sourceMappingURL=mock-factory.d.ts.map

package/dist/__tests__/helpers/mock-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-factory.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/mock-factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,UAAU,GAAI,cAAc;;;;CAKvC,CAAC;AAEH,eAAO,MAAM,UAAU,GAAI,cAAc;;;;;;;;CASvC,CAAC;AAEH,eAAO,MAAM,cAAc,GAAI,cAAc;;;;CAK3C,CAAC;AAEH,eAAO,MAAM,aAAa,GAAI,cAAc;;;;;;;CAQ1C,CAAC"}

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":""}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}