@tnldotdev/tnl 0.1.0-rc.15 → 0.1.0-rc.20

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type ProjectMetadata } from "./internal/runtime.js";
+/** Augmented by the `.tnl/project.d.ts` file generated by the tnl client. */
+export interface TnlProjectMetadata {
+}
+type RegisteredTnlProject = keyof TnlProjectMetadata extends never ? ProjectMetadata : Readonly<TnlProjectMetadata>;
+type TnlProject = RegisteredTnlProject & {
+    readonly runningUnderTnlDev: boolean;
+};
+/** Validated project metadata injected by a tnl framework integration during development. */
+export declare const tnl: TnlProject | undefined;
+export {};

package/dist/index.js

@@ -0,0 +1,4 @@
+import { parseRuntimePayload } from "./internal/runtime.js";
+const serializedRuntime = typeof process === "undefined" ? undefined : process.env?.TNL_PROJECT_RUNTIME;
+/** Validated project metadata injected by a tnl framework integration during development. */
+export const tnl = parseRuntimePayload(serializedRuntime);

package/dist/internal/dev.d.ts

@@ -0,0 +1,41 @@
+import { type ProjectMetadata, type ProjectRuntime } from "./runtime.js";
+export type TnlDevEnvironment = Readonly<Record<string, string | undefined>>;
+export interface TnlDevBootstrap {
+    readonly port?: number;
+    readonly socket: string;
+}
+export interface ProjectDocument extends ProjectMetadata {
+    readonly projectRoot: string;
+    readonly runningUnderTnlDev: boolean;
+    readonly serviceDirectories: Readonly<Record<string, string>>;
+    readonly version: 1;
+}
+export interface ProjectDiscovery {
+    readonly document: ProjectDocument;
+    readonly file: string;
+    readonly project: ProjectMetadata;
+    readonly service: string | null;
+}
+export interface DevelopmentContext {
+    readonly bootstrap: TnlDevBootstrap | null;
+    readonly localProject: ProjectMetadata | null;
+}
+export interface TnlTunnelAssignment extends TnlDevBootstrap {
+    readonly framework: string;
+    readonly hostname: string;
+    readonly memberNamespace: string;
+    readonly project: ProjectRuntime;
+    readonly publicURL: `https://${string}`;
+    readonly service: string | null;
+    readonly tunnelID: `tunnel_${string}`;
+}
+export type CanonicalLoopbackTarget = `http://${string}`;
+export declare function readDevelopmentContext(environment?: TnlDevEnvironment, cwd?: string): DevelopmentContext;
+export declare function requestTunnelAssignment(framework: string, bootstrap: TnlDevBootstrap): Promise<TnlTunnelAssignment>;
+export declare function canonicalLoopbackTarget(host: string, port: number): CanonicalLoopbackTarget;
+export declare function registerLocalTarget(assignment: TnlTunnelAssignment, target: CanonicalLoopbackTarget): Promise<void>;
+export declare function runtimePayload(project: ProjectMetadata, runningUnderTnlDev: boolean): string;
+export declare function discoverProject(cwd: string): ProjectDiscovery | null;
+export declare function socketIdentity(projectRoot: string, service: string | null): string;
+/** Parses digit-only listener ports in [1, 65535], preserving source-specific diagnostics. */
+export declare function parseListenerPort(value: string, source: string): number;

package/dist/internal/dev.js

@@ -0,0 +1,387 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import { isIP } from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { exactKeys, parseProjectMetadata, parseProjectRuntime, record, requiredHostname, serializeRuntimePayload, validServiceName, } from "./runtime.js";
+const protocolVersion = "1";
+const maximumDocumentBytes = 64 * 1024;
+const maximumResponseBytes = 64 * 1024;
+const registrationTimeoutMilliseconds = 10 * 60 * 1000;
+export function readDevelopmentContext(environment = process.env, cwd = process.cwd()) {
+    const protocol = environment.TNL_DEV_PROTOCOL;
+    if (protocol !== undefined) {
+        if (protocol !== protocolVersion) {
+            throw new Error(`unsupported tnl dev protocol ${JSON.stringify(protocol)}; upgrade tnl and its framework integrations`);
+        }
+        return Object.freeze({
+            bootstrap: parseBootstrapEnvironment(environment),
+            localProject: null,
+        });
+    }
+    if (environment.TNL_DEV_SOCKET !== undefined || environment.TNL_DEV_PORT !== undefined) {
+        throw new Error(`TNL_DEV_PROTOCOL=${protocolVersion} is required with tnl dev bootstrap values`);
+    }
+    const discovery = discoverProject(cwd);
+    if (discovery === null) {
+        return Object.freeze({ bootstrap: null, localProject: null });
+    }
+    const socket = discoverDevSocket(discovery, environment);
+    return Object.freeze({
+        bootstrap: socket === null ? null : Object.freeze({ socket }),
+        localProject: discovery.project,
+    });
+}
+export async function requestTunnelAssignment(framework, bootstrap) {
+    if (!/^[a-z]{1,32}$/.test(framework)) {
+        throw new Error("tnl framework name is invalid");
+    }
+    const body = JSON.stringify({ protocol: 1, framework });
+    const response = await sendRequest(bootstrap, framework, "/v1/configure", body, 200);
+    return parseAssignment(response, bootstrap, framework);
+}
+export function canonicalLoopbackTarget(host, port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("tnl listener port must be between 1 and 65535");
+    }
+    const hostname = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    const lowerHostname = hostname.toLowerCase();
+    if (lowerHostname === "localhost" || hostname === "0.0.0.0") {
+        return `http://127.0.0.1:${port}`;
+    }
+    if (hostname === "::") {
+        return `http://[::1]:${port}`;
+    }
+    if (isIP(hostname) === 4 && hostname.startsWith("127.")) {
+        return `http://${hostname}:${port}`;
+    }
+    if (hostname === "::1") {
+        return `http://[::1]:${port}`;
+    }
+    throw new Error("tnl development target must use a loopback listener");
+}
+export async function registerLocalTarget(assignment, target) {
+    const body = JSON.stringify({ protocol: 1, framework: assignment.framework, target });
+    await sendRequest(assignment, assignment.framework, "/v1/target", body, 204);
+}
+export function runtimePayload(project, runningUnderTnlDev) {
+    return serializeRuntimePayload(project, runningUnderTnlDev);
+}
+export function discoverProject(cwd) {
+    let directory = absoluteNormalizedPath(cwd, "working directory");
+    for (;;) {
+        const file = path.join(directory, ".tnl", "project.json");
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile()) {
+                throw new Error(`${file} must be a regular file`);
+            }
+            const document = parseProjectDocument(readBoundedFile(file), file, directory);
+            const service = selectService(document, cwd);
+            return Object.freeze({
+                document,
+                file,
+                project: projectMetadata(document),
+                service,
+            });
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                throw error;
+            }
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return null;
+        }
+        directory = parent;
+    }
+}
+export function socketIdentity(projectRoot, service) {
+    return createHash("sha256")
+        .update(`${projectRoot}\0${service ?? ""}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+function parseBootstrapEnvironment(environment) {
+    const socket = environment.TNL_DEV_SOCKET;
+    if (socket === undefined || socket === "") {
+        throw new Error(`TNL_DEV_SOCKET is required by tnl dev protocol ${protocolVersion}`);
+    }
+    const rawPort = environment.TNL_DEV_PORT;
+    const port = rawPort === undefined ? undefined : parseListenerPort(rawPort, "TNL_DEV_PORT");
+    return Object.freeze({ port, socket });
+}
+function discoverDevSocket(discovery, environment) {
+    const getuid = process.getuid;
+    if (getuid === undefined) {
+        return null;
+    }
+    const base = environment.XDG_RUNTIME_DIR || os.tmpdir();
+    const directory = path.join(base, `tnl-${getuid()}`);
+    const socket = path.join(directory, `dev-${socketIdentity(discovery.document.projectRoot, discovery.service)}.sock`);
+    let directoryStat;
+    let socketStat;
+    try {
+        directoryStat = fs.lstatSync(directory);
+        socketStat = fs.lstatSync(socket);
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return null;
+        }
+        throw error;
+    }
+    if (!directoryStat.isDirectory() ||
+        directoryStat.uid !== getuid() ||
+        (directoryStat.mode & 0o777) !== 0o700 ||
+        !socketStat.isSocket() ||
+        socketStat.uid !== getuid() ||
+        (socketStat.mode & 0o777) !== 0o600) {
+        throw new Error("tnl dev runtime directory or socket has unsafe ownership or permissions");
+    }
+    return socket;
+}
+function parseAssignment(value, bootstrap, framework) {
+    const object = record(value, "tnl dev response");
+    exactKeys(object, ["hostname", "memberNamespace", "project", "protocol", "publicURL", "service", "tunnelID"], "tnl dev response");
+    if (object.protocol !== 1) {
+        throw new Error("tnl dev returned an inconsistent tunnel assignment");
+    }
+    if (typeof object.tunnelID !== "string" || !/^tunnel_[a-f0-9]{32}$/.test(object.tunnelID)) {
+        throw new Error("tnl dev returned an invalid tunnel ID");
+    }
+    if (object.service !== null && !validServiceName(object.service)) {
+        throw new Error("tnl dev returned an invalid service");
+    }
+    const memberNamespace = requiredHostname(object.memberNamespace, "tnl dev returned member namespace");
+    const hostname = requiredHostname(object.hostname, "tnl dev returned public hostname");
+    if (object.publicURL !== `https://${hostname}`) {
+        throw new Error("tnl dev returned an invalid public URL");
+    }
+    const project = parseProjectRuntime(object.project, "tnl dev project metadata");
+    if (!project.runningUnderTnlDev) {
+        throw new Error("tnl dev returned project metadata outside tnl dev");
+    }
+    const assignmentNamespace = object.service === null
+        ? project.memberNamespace
+        : project.services[object.service]?.memberNamespace;
+    if (assignmentNamespace !== memberNamespace) {
+        throw new Error("tnl dev returned inconsistent project metadata");
+    }
+    if (object.service !== null && project.services[object.service] === undefined) {
+        throw new Error("tnl dev returned inconsistent project metadata");
+    }
+    if (object.service !== null && project.services[object.service]?.hostname !== hostname) {
+        throw new Error("tnl dev returned inconsistent project metadata");
+    }
+    return Object.freeze({
+        ...bootstrap,
+        framework,
+        hostname,
+        memberNamespace,
+        project,
+        publicURL: object.publicURL,
+        service: object.service,
+        tunnelID: object.tunnelID,
+    });
+}
+function parseProjectDocument(serialized, description, projectRoot) {
+    let value;
+    try {
+        value = JSON.parse(serialized);
+    }
+    catch (error) {
+        throw new Error(`${description} is not valid JSON`, { cause: error });
+    }
+    return parseProjectDocumentValue(value, description, projectRoot);
+}
+function parseProjectDocumentValue(value, description, projectRoot) {
+    const object = record(value, description);
+    exactKeys(object, ["memberNamespace", "runningUnderTnlDev", "serviceDirectories", "services", "version"], description);
+    if (object.version !== 1) {
+        throw new Error(`${description} has an unsupported version`);
+    }
+    if (typeof object.runningUnderTnlDev !== "boolean") {
+        throw new Error(`${description} has an invalid runningUnderTnlDev value`);
+    }
+    if (object.runningUnderTnlDev) {
+        throw new Error(`${description} cannot be marked as running under tnl dev`);
+    }
+    const project = parseProjectMetadata({ memberNamespace: object.memberNamespace, services: object.services }, description);
+    const directoryValues = record(object.serviceDirectories, `${description} service directories`);
+    const names = Object.keys(project.services);
+    if (Object.keys(directoryValues).length !== names.length ||
+        names.some((name) => !Object.hasOwn(directoryValues, name))) {
+        throw new Error(`${description} requires one directory for every service`);
+    }
+    const serviceDirectories = {};
+    for (const name of names) {
+        serviceDirectories[name] = relativeDirectory(directoryValues[name], `${description} service ${JSON.stringify(name)} directory`);
+    }
+    return Object.freeze({
+        ...project,
+        projectRoot,
+        runningUnderTnlDev: object.runningUnderTnlDev,
+        serviceDirectories: Object.freeze(serviceDirectories),
+        version: 1,
+    });
+}
+function projectMetadata(document) {
+    return Object.freeze({ memberNamespace: document.memberNamespace, services: document.services });
+}
+function selectService(document, cwd) {
+    const absoluteCwd = absoluteNormalizedPath(cwd, "working directory");
+    const canonicalCwd = fs.realpathSync.native(absoluteCwd);
+    const canonicalRoot = fs.realpathSync.native(document.projectRoot);
+    if (!pathWithin(canonicalCwd, canonicalRoot)) {
+        throw new Error("working directory is outside the discovered tnl project");
+    }
+    const matches = Object.entries(document.serviceDirectories)
+        .map(([name, directory]) => [name, canonicalPath(path.join(document.projectRoot, directory))])
+        .filter(([, directory]) => pathWithin(canonicalCwd, directory))
+        .sort((left, right) => right[1].length - left[1].length);
+    if (matches.length > 1 && matches[0]?.[1].length === matches[1]?.[1].length) {
+        throw new Error("working directory matches multiple tnl service directories");
+    }
+    return matches[0]?.[0] ?? null;
+}
+function relativeDirectory(value, description) {
+    if (typeof value !== "string" || value === "" || value.includes("\0") || path.isAbsolute(value)) {
+        throw new Error(`${description} must be a non-empty relative path`);
+    }
+    const normalized = path.normalize(value);
+    if (normalized === ".." ||
+        normalized.startsWith(`..${path.sep}`) ||
+        normalized.split(path.sep).join("/") !== value) {
+        throw new Error(`${description} must be a clean relative path`);
+    }
+    return value;
+}
+function sendRequest(bootstrap, framework, requestPath, body, expectedStatus) {
+    return new Promise((resolve, reject) => {
+        const request = http.request({
+            socketPath: bootstrap.socket,
+            path: requestPath,
+            method: "POST",
+            headers: {
+                "Content-Length": Buffer.byteLength(body),
+                "Content-Type": "application/json",
+            },
+        }, (response) => {
+            response.on("error", reject);
+            const declaredLength = Number(response.headers["content-length"]);
+            if (Number.isFinite(declaredLength) && declaredLength > maximumResponseBytes) {
+                response.destroy(new Error("tnl dev returned an oversized response"));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > maximumResponseBytes) {
+                    response.destroy(new Error("tnl dev returned an oversized response"));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on("end", () => {
+                const data = Buffer.concat(chunks).toString("utf8").trim();
+                if (response.statusCode !== expectedStatus) {
+                    reject(new Error(`tnl dev rejected the ${framework} request with status ${response.statusCode}${data ? `: ${data}` : ""}`));
+                    return;
+                }
+                if (expectedStatus === 204) {
+                    if (data !== "") {
+                        reject(new Error("tnl dev returned an unexpected target response"));
+                        return;
+                    }
+                    resolve(undefined);
+                    return;
+                }
+                if (response.headers["content-type"]?.split(";", 1)[0]?.trim() !== "application/json") {
+                    reject(new Error("tnl dev returned a non-JSON configuration"));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (error) {
+                    reject(new Error("tnl dev returned an invalid configuration", { cause: error }));
+                }
+            });
+        });
+        request.setTimeout(registrationTimeoutMilliseconds, () => {
+            request.destroy(new Error("timed out configuring the target with tnl dev"));
+        });
+        request.on("error", reject);
+        request.end(body);
+    });
+}
+function readBoundedFile(file) {
+    const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
+    const descriptor = fs.openSync(file, flags);
+    try {
+        const stat = fs.fstatSync(descriptor);
+        if (!stat.isFile()) {
+            throw new Error(`${file} must be a regular file`);
+        }
+        const buffer = Buffer.allocUnsafe(maximumDocumentBytes + 1);
+        let length = 0;
+        for (;;) {
+            const read = fs.readSync(descriptor, buffer, length, buffer.length - length, null);
+            length += read;
+            if (read === 0 || length === buffer.length) {
+                break;
+            }
+        }
+        if (length > maximumDocumentBytes) {
+            throw new Error(`${file} exceeds ${maximumDocumentBytes} bytes`);
+        }
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length));
+        }
+        catch (error) {
+            throw new Error(`${file} is not valid UTF-8`, { cause: error });
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function absoluteNormalizedPath(value, description) {
+    if (typeof value !== "string" ||
+        value === "" ||
+        !path.isAbsolute(value) ||
+        path.normalize(value) !== value) {
+        throw new Error(`${description} must be an absolute normalized path`);
+    }
+    return value;
+}
+/** Parses digit-only listener ports in [1, 65535], preserving source-specific diagnostics. */
+export function parseListenerPort(value, source) {
+    if (!/^[0-9]+$/.test(value)) {
+        throw new Error(`${source} must be a port between 1 and 65535`);
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${source} must be a port between 1 and 65535`);
+    }
+    return port;
+}
+function pathWithin(value, root) {
+    const relative = path.relative(root, value);
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+function canonicalPath(value) {
+    try {
+        return fs.realpathSync.native(value);
+    }
+    catch {
+        return value;
+    }
+}
+function isMissing(error) {
+    return error.code === "ENOENT";
+}

package/dist/internal/runtime.d.ts

@@ -0,0 +1,22 @@
+export interface ProjectServiceMetadata {
+    readonly memberNamespace: string;
+    readonly hostname: string;
+    readonly url: `https://${string}`;
+}
+export interface ProjectMetadata {
+    readonly memberNamespace: string;
+    readonly services: Readonly<Record<string, ProjectServiceMetadata>>;
+}
+export interface ProjectRuntime extends ProjectMetadata {
+    readonly runningUnderTnlDev: boolean;
+}
+/** Validates and deep-freezes public metadata, excluding runtime flags and Node-only discovery fields. */
+export declare function parseProjectMetadata(value: unknown, description: string): ProjectMetadata;
+/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+export declare function validServiceName(value: unknown): value is string;
+export declare function parseRuntimePayload(serialized: string | undefined): ProjectRuntime | undefined;
+export declare function parseProjectRuntime(value: unknown, description: string): ProjectRuntime;
+export declare function serializeRuntimePayload(project: ProjectMetadata, runningUnderTnlDev: boolean): string;
+export declare function requiredHostname(value: unknown, description: string): string;
+export declare function exactKeys(object: Record<string, unknown>, expected: readonly string[], description: string): void;
+export declare function record(value: unknown, description: string): Record<string, unknown>;

package/dist/internal/runtime.js

@@ -0,0 +1,118 @@
+const maximumRuntimeBytes = 64 * 1024;
+const maximumServices = 32;
+const serviceNamePattern = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+/** Validates and deep-freezes public metadata, excluding runtime flags and Node-only discovery fields. */
+export function parseProjectMetadata(value, description) {
+    const object = record(value, description);
+    exactKeys(object, ["memberNamespace", "services"], description);
+    const memberNamespace = requiredHostname(object.memberNamespace, `${description} member namespace`);
+    const servicesObject = record(object.services, `${description} services`);
+    const entries = Object.entries(servicesObject);
+    if (entries.length > maximumServices) {
+        throw new Error(`${description} may contain at most ${maximumServices} services`);
+    }
+    const services = {};
+    const hostnames = new Set();
+    for (const [name, value] of entries) {
+        if (!validServiceName(name)) {
+            throw new Error(`${description} contains an invalid service name ${JSON.stringify(name)}`);
+        }
+        const service = record(value, `${description} service ${JSON.stringify(name)}`);
+        exactKeys(service, ["hostname", "memberNamespace", "url"], `${description} service ${JSON.stringify(name)}`);
+        const serviceMemberNamespace = requiredHostname(service.memberNamespace, `${description} service ${JSON.stringify(name)} member namespace`);
+        const hostname = requiredHostname(service.hostname, `${description} service ${JSON.stringify(name)} hostname`);
+        if (service.url !== `https://${hostname}`) {
+            throw new Error(`${description} service ${JSON.stringify(name)} has an invalid URL`);
+        }
+        if (hostnames.has(hostname)) {
+            throw new Error(`${description} contains duplicate service hostname ${hostname}`);
+        }
+        hostnames.add(hostname);
+        services[name] = Object.freeze({
+            memberNamespace: serviceMemberNamespace,
+            hostname,
+            url: service.url,
+        });
+    }
+    return Object.freeze({
+        memberNamespace,
+        services: Object.freeze(services),
+    });
+}
+/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+export function validServiceName(value) {
+    return typeof value === "string" && serviceNamePattern.test(value);
+}
+export function parseRuntimePayload(serialized) {
+    if (serialized === undefined) {
+        return undefined;
+    }
+    if (byteLength(serialized) > maximumRuntimeBytes) {
+        throw new Error(`tnl runtime payload exceeds ${maximumRuntimeBytes} bytes`);
+    }
+    let value;
+    try {
+        value = JSON.parse(serialized);
+    }
+    catch (error) {
+        throw new Error("tnl runtime payload is not valid JSON", { cause: error });
+    }
+    return parseProjectRuntime(value, "tnl runtime payload");
+}
+export function parseProjectRuntime(value, description) {
+    const object = record(value, description);
+    exactKeys(object, ["memberNamespace", "runningUnderTnlDev", "services"], description);
+    if (typeof object.runningUnderTnlDev !== "boolean") {
+        throw new Error(`${description} has an invalid runningUnderTnlDev value`);
+    }
+    const project = parseProjectMetadata({ memberNamespace: object.memberNamespace, services: object.services }, description);
+    return Object.freeze({
+        ...project,
+        runningUnderTnlDev: object.runningUnderTnlDev,
+    });
+}
+export function serializeRuntimePayload(project, runningUnderTnlDev) {
+    const serialized = JSON.stringify({
+        memberNamespace: project.memberNamespace,
+        runningUnderTnlDev,
+        services: project.services,
+    });
+    if (byteLength(serialized) > maximumRuntimeBytes) {
+        throw new Error(`tnl runtime payload exceeds ${maximumRuntimeBytes} bytes`);
+    }
+    return serialized;
+}
+export function requiredHostname(value, description) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 253) {
+        throw new Error(`${description} is invalid`);
+    }
+    if (value !== value.toLowerCase() || value.endsWith(".")) {
+        throw new Error(`${description} is invalid`);
+    }
+    const labels = value.split(".");
+    if (labels.some((label) => label.length === 0 || label.length > 63 || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label))) {
+        throw new Error(`${description} is invalid`);
+    }
+    if (labels.length === 4 &&
+        labels.every((label) => /^[0-9]+$/.test(label) && Number(label) <= 255)) {
+        throw new Error(`${description} is invalid`);
+    }
+    return value;
+}
+export function exactKeys(object, expected, description) {
+    const keys = Object.keys(object).sort();
+    const sortedExpected = [...expected].sort();
+    if (keys.length !== sortedExpected.length ||
+        keys.some((key, index) => key !== sortedExpected[index])) {
+        throw new Error(`${description} has an invalid shape`);
+    }
+}
+export function record(value, description) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${description} must be an object`);
+    }
+    return value;
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}

package/dist/next.d.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from "next";
+export interface NextConfigContext {
+    /** The default Next.js configuration. */
+    readonly defaultConfig: NextConfig;
+}
+/** A function that returns Next.js configuration. */
+export type NextConfigFactory = (phase: string, context: NextConfigContext) => NextConfig | Promise<NextConfig>;
+export type NextConfigInput = NextConfig | Promise<NextConfig> | NextConfigFactory;
+/** Adds tnl project metadata and safe `tnl dev` routing to a Next.js development server. */
+export declare function withTnl(config?: NextConfigInput, ...extra: never[]): NextConfigFactory;

package/dist/next.js

@@ -0,0 +1,75 @@
+import { canonicalLoopbackTarget, parseListenerPort, readDevelopmentContext, registerLocalTarget, requestTunnelAssignment, runtimePayload, } from "./internal/dev.js";
+const developmentServerPhase = "phase-development-server";
+const runtimeEnvironmentName = "TNL_PROJECT_RUNTIME";
+/** Adds tnl project metadata and safe `tnl dev` routing to a Next.js development server. */
+export function withTnl(config = {}, ...extra) {
+    if (extra.length !== 0) {
+        throw new Error("withTnl() does not accept tunnel options; use project configuration");
+    }
+    return async function tnlNextConfig(phase, context) {
+        const resolved = typeof config === "function" ? await config(phase, context) : await config;
+        const nextConfig = resolved ?? {};
+        if (phase !== developmentServerPhase) {
+            return nextConfig;
+        }
+        const development = readDevelopmentContext();
+        if (development.bootstrap === null) {
+            if (development.localProject === null) {
+                return nextConfig;
+            }
+            return injectRuntime(nextConfig, runtimePayload(development.localProject, false));
+        }
+        const allowedDevOrigins = nextConfig.allowedDevOrigins ?? [];
+        if (!Array.isArray(allowedDevOrigins)) {
+            throw new Error("Next.js allowedDevOrigins must be an array when used with tnl");
+        }
+        const target = nextTarget(process.env);
+        const assignment = await requestTunnelAssignment("next", development.bootstrap);
+        await registerLocalTarget(assignment, target);
+        return injectRuntime({
+            ...nextConfig,
+            allowedDevOrigins: unique([...allowedDevOrigins, assignment.hostname]),
+        }, runtimePayload(assignment.project, true));
+    };
+}
+function injectRuntime(config, payload) {
+    return {
+        ...config,
+        env: {
+            ...config.env,
+            [runtimeEnvironmentName]: payload,
+        },
+    };
+}
+function nextTarget(environment) {
+    // Next 16.3.4 binds and sets this origin before loading next.config, so it is authoritative.
+    const value = environment.__NEXT_PRIVATE_ORIGIN;
+    if (value === undefined) {
+        throw new Error("Next.js did not report its bound development listener to tnl dev");
+    }
+    let origin;
+    try {
+        origin = new URL(value);
+        if (origin.protocol !== "http:" ||
+            origin.username !== "" ||
+            origin.password !== "" ||
+            origin.pathname !== "/" ||
+            origin.search !== "" ||
+            origin.hash !== "" ||
+            origin.port === "") {
+            throw new Error("invalid origin");
+        }
+    }
+    catch (error) {
+        throw new Error("Next.js reported an invalid development listener", { cause: error });
+    }
+    const port = parseListenerPort(origin.port, "Next.js listener");
+    const reportedPort = environment.PORT;
+    if (reportedPort !== undefined && parseListenerPort(reportedPort, "PORT") !== port) {
+        throw new Error("Next.js reported inconsistent development listener ports");
+    }
+    return canonicalLoopbackTarget(origin.hostname, port);
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/vite.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "vite";
+/** Adds tnl project metadata and safe `tnl dev` routing to a Vite development server. */
+export default function tnl(...arguments_: never[]): Plugin;