dsh-github-app 0.0.0-stage → 0.0.1

package/declaration.d.ts

@@ -0,0 +1,4 @@
+interface ImportMeta {
+  readonly env: Record<string, string>;
+  readonly require: (src?: string) => any
+}

package/fence.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const PAYLOAD_TOO_LARGE: unique symbol;
+export declare function parseAuthority(authority: unknown): URL | undefined;
+export declare function isLoopbackHostname(hostname: unknown): boolean;
+export declare function canonicalAuthority(authority: string): string | undefined;
+export declare function buildTrustedHosts(entries: unknown, warn?: (message: string) => void): string[];
+export declare function isTrustedApiRequest(req: unknown, trustedHosts?: string[]): boolean;
+/**
+ * Whether a request targets a loopback authority.
+ *
+ * @param req incoming request carrying a Host header.
+ * @returns true for localhost, ::1 and 127.0.0.0/8 authorities.
+ */
+export declare function isLoopbackRequest(req: unknown): boolean;
+export declare function readJsonBody(req: IncomingMessage, maxBytes?: number): Promise<unknown>;
+export declare function writeJson(res: ServerResponse, status: number, value: unknown): void;

package/fence.mjs

@@ -0,0 +1,136 @@
+import { MAX_BODY_BYTES } from "./constants.mjs";
+// src/fence.ts
+const PAYLOAD_TOO_LARGE = Symbol("payload-too-large");
+function parseAuthority(authority) {
+	if (typeof authority !== "string") return void 0;
+	const value = authority.trim();
+	if (value === "" || /[/?#@\\\s]/.test(value)) return void 0;
+	try {
+		const url = new URL(`http://${value}`);
+		if (url.username !== "" || url.password !== "" || url.pathname !== "/") return void 0;
+		return url;
+	} catch {
+		return;
+	}
+}
+function isLoopbackHostname(hostname) {
+	if (typeof hostname !== "string" || hostname === "") return false;
+	let name = hostname.toLowerCase();
+	if (name.startsWith("[") && name.endsWith("]")) name = name.slice(1, -1);
+	if (name === "localhost" || name === "::1") return true;
+	const parts = (name.startsWith("::ffff:") ? name.slice(7) : name).split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+function canonicalFrom(url, authority) {
+	const explicitPort = /:(\d+)$/.exec(authority.trim());
+	return explicitPort === null ? url.hostname : `${url.hostname}:${explicitPort[1]}`;
+}
+function canonicalAuthority(authority) {
+	const url = parseAuthority(authority);
+	return url === void 0 ? void 0 : canonicalFrom(url, authority);
+}
+function isTrustedAuthority(authority, hostUrl, trustedHosts) {
+	const requestAuthority = canonicalAuthority(authority) || hostUrl.hostname;
+	return trustedHosts.some((entry) => {
+		const url = parseAuthority(entry);
+		if (url === void 0) return false;
+		const canonical = canonicalFrom(url, entry);
+		return canonical !== url.hostname ? canonical === requestAuthority : url.hostname === hostUrl.hostname;
+	});
+}
+function buildTrustedHosts(entries, warn) {
+	const trusted = [];
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		if (typeof entry !== "string") {
+			if (warn) warn("trusted host entry is not a string");
+			continue;
+		}
+		const canonical = canonicalAuthority(entry);
+		if (canonical === void 0 || canonical !== entry.trim().toLowerCase()) {
+			if (warn) warn(`entry ${JSON.stringify(entry)} is not a bare host[:port] authority`);
+			continue;
+		}
+		trusted.push(entry.trim());
+	}
+	return trusted;
+}
+function headersOf(req) {
+	return req !== null && typeof req === "object" && "headers" in req && req.headers !== null && typeof req.headers === "object" ? req.headers : {};
+}
+function isTrustedApiRequest(req, trustedHosts = []) {
+	if (req === null || typeof req !== "object") return false;
+	const headers = headersOf(req);
+	const host = typeof headers.host === "string" ? headers.host : void 0;
+	if (host === void 0) return false;
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === void 0) return false;
+	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(host, hostUrl, trustedHosts)) return false;
+	const site = headers["sec-fetch-site"];
+	if (typeof site === "string" && site.toLowerCase() === "cross-site") return false;
+	const origin = headers.origin;
+	if (origin === void 0 || origin === "") return true;
+	if (typeof origin !== "string") return false;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether a request targets a loopback authority.
+*
+* @param req incoming request carrying a Host header.
+* @returns true for localhost, ::1 and 127.0.0.0/8 authorities.
+*/
+function isLoopbackRequest(req) {
+	if (req === null || typeof req !== "object") return false;
+	const headers = headersOf(req);
+	const host = typeof headers.host === "string" ? headers.host : void 0;
+	if (host === void 0) return false;
+	const authority = parseAuthority(host);
+	return authority !== void 0 && isLoopbackHostname(authority.hostname);
+}
+function readJsonBody(req, maxBytes = MAX_BODY_BYTES) {
+	return new Promise((resolve) => {
+		const chunks = [];
+		let size = 0;
+		let settled = false;
+		req.on("data", (chunk) => {
+			if (settled) return;
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+			size += buffer.length;
+			if (size > maxBytes) {
+				settled = true;
+				req.pause();
+				resolve(PAYLOAD_TOO_LARGE);
+				return;
+			}
+			chunks.push(buffer);
+		});
+		req.on("end", () => {
+			if (settled) return;
+			settled = true;
+			try {
+				const raw = Buffer.concat(chunks).toString("utf8").trim();
+				resolve(raw === "" ? null : JSON.parse(raw));
+			} catch {
+				resolve(null);
+			}
+		});
+		req.on("error", () => {
+			if (settled) return;
+			settled = true;
+			resolve(null);
+		});
+	});
+}
+function writeJson(res, status, value) {
+	if (!res || res.writableEnded || res.destroyed) return;
+	const body = JSON.stringify(value);
+	res.writeHead(status, {
+		"content-type": "application/json",
+		"cache-control": "no-store"
+	});
+	res.end(body);
+}
+export { PAYLOAD_TOO_LARGE, buildTrustedHosts, canonicalAuthority, isLoopbackHostname, isLoopbackRequest, isTrustedApiRequest, parseAuthority, readJsonBody, writeJson };

package/github.d.ts

@@ -0,0 +1,117 @@
+import type { GitIdentity, ToolStatus } from './contracts';
+import type { GithubSettings } from './settings';
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Variables to drop from the inherited environment before spawning. */
+    unset?: string[];
+    timeout?: number;
+    input?: string;
+}
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    error: Error | null;
+}
+export interface InstallResult {
+    ok: boolean;
+    version?: string | null;
+    skipped?: boolean;
+    error?: string;
+}
+export interface InstallGhResult extends InstallResult {
+    gh: InstallResult;
+    git: InstallResult;
+}
+export interface AuthStatus {
+    loggedIn: boolean;
+    gitConfigured: boolean;
+    hostname: string;
+    output?: string;
+    error?: string;
+}
+export interface ConnectResult {
+    ok: boolean;
+    error?: string;
+    auth?: AuthStatus;
+}
+export declare function getGhInfo(): Promise<ToolStatus>;
+export declare function getGitInfo(): Promise<ToolStatus>;
+/**
+ * Decide whether `gh auth status` output describes a usable authentication.
+ *
+ * `gh` exits 0 as soon as *one* configured account is usable, so judging the
+ * merged output as a whole reports a false "disconnected" whenever an unusable
+ * entry sits next to a working one. The entry marked `Active account: true` —
+ * the credential `gh` and git operations actually use — decides the verdict.
+ * Other entries are only consulted when no such marker is present; when the
+ * marker is present but its status line is unrecognisable (a future `gh`
+ * re-wording), the verdict stays `false` instead of falling back to another
+ * account, so an unknown format can never claim "Connected".
+ *
+ * @param output merged stdout+stderr of `gh auth status`.
+ * @returns true when the active (or only) account is authenticated.
+ */
+export declare function isLoggedInOutput(output: unknown): boolean;
+export declare function getAuthStatus(hostname?: string): Promise<AuthStatus>;
+/** Tool the settings section can install automatically. */
+export type InstallableTool = 'gh' | 'git';
+/**
+ * One supported package manager and the commands that install a tool with it.
+ *
+ * `install` is a prefix: the resolved package name is appended as the last
+ * argument, so managers that put the name after flags (`winget --id`) can use
+ * the same shape.
+ */
+export interface PackageManager {
+    /** Executable to spawn. */
+    command: string;
+    /** Arguments that exit 0 when the manager is usable. */
+    probe: string[];
+    /** Arguments that refresh the package index, or null when not needed. */
+    update: string[] | null;
+    /** Arguments to install a package (package name appended). */
+    install: string[];
+    /** Package name when it differs from the tool name. */
+    packageName?: Partial<Record<InstallableTool, string>>;
+}
+/**
+ * Package managers available for a platform, in probe order.
+ *
+ * @param platform target platform; defaults to the host.
+ * @returns the manager list, empty when the platform has no installer.
+ */
+export declare function packageManagers(platform?: NodeJS.Platform): PackageManager[];
+/**
+ * Commands needed to install one tool with a known package manager.
+ *
+ * @param manager manager to use.
+ * @param tool tool to install.
+ * @returns ordered commands; an install failure aborts the sequence.
+ */
+export declare function installCommands(manager: PackageManager, tool: InstallableTool): Array<{
+    command: string;
+    args: string[];
+}>;
+export declare function installGit(): Promise<InstallResult>;
+export declare function installGh(): Promise<InstallGhResult>;
+/**
+ * Exchange the GitHub App private key for an installation token.
+ *
+ * The key file is encrypted at rest, so the passphrase is required on every
+ * call: the decrypted PEM lives only for the duration of this operation and is
+ * never cached in the server process.
+ *
+ * @param settings persisted App ID, installation ID and key location.
+ * @param passphrase passphrase protecting the key file.
+ * @returns the connection outcome and refreshed auth status.
+ */
+export declare function connect(settings?: Partial<GithubSettings> | null, passphrase?: unknown): Promise<ConnectResult>;
+export interface DisconnectResult {
+    ok: boolean;
+    error?: string;
+}
+export declare function disconnect(): Promise<DisconnectResult>;
+export declare function getGitIdentity(): Promise<GitIdentity>;
+export declare function setGitIdentity(name: unknown, email: unknown): Promise<GitIdentity>;