@knpkv/atlassian-common 1.5.0 → 1.6.0

package/dist/cli-auth/internal/oauthServer.js

@@ -0,0 +1,94 @@
+/**
+ * Local HTTP callback server for OAuth2 authorization code capture.
+ *
+ * **Mental model**
+ *
+ * - **Scope-owned lifecycle**: {@link startCallbackServer} returns a `codePromise`
+ *   (Deferred). The server validates the CSRF `state` parameter, resolves the
+ *   Deferred with the authorization code, and stops when its enclosing scope closes.
+ * - **Port auto-discovery**: Tries default port 8585, increments on conflict up to 8594.
+ * - **Ready before return**: the handler is installed before the port is handed back,
+ *   so the caller never advertises a callback URL nothing answers.
+ *
+ * @internal
+ */
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import { HttpRouter, HttpServer, HttpServerRequest, HttpServerResponse } from "effect/http";
+import * as Layer from "effect/Layer";
+import { NetAddress } from "effect/net";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import { OAuthError } from "../../auth/OAuthErrors.js";
+const DEFAULT_PORT = 8585;
+const MAX_PORT = 8594;
+export const callbackServerListenOptions = (port) => ({
+    host: "localhost",
+    port
+});
+export const callbackUrl = (port) => `http://localhost:${port}/callback`;
+export class HttpServerFactoryTag extends Context.Service()("@knpkv/atlassian-common/cli-auth/HttpServerFactory") {
+}
+/** Builds a {@link HttpServerFactoryTag} layer from a per-attempt server layer. */
+export const makeHttpServerFactory = (createLayerFn) => Layer.succeed(HttpServerFactoryTag, {
+    createServerLayer: createLayerFn
+});
+const AddressInUseCause = Schema.Struct({
+    code: Schema.Literal("EADDRINUSE")
+});
+const isAddressInUse = (error) => Schema.is(AddressInUseCause)(error.cause);
+const page = (heading, body) => HttpServerResponse.html(`<html><body><h1>${heading}</h1><p>${body}</p></body></html>`);
+/**
+ * Start a local HTTP server to receive the OAuth callback for `expectedState`.
+ *
+ * Fails with one `OAuthError` (step `authorize`) when no port in range can be
+ * bound; the server stops when the enclosing scope closes.
+ */
+export const startCallbackServer = (expectedState) => Effect.gen(function* () {
+    const factory = yield* HttpServerFactoryTag;
+    const deferred = yield* Deferred.make();
+    const scope = yield* Effect.scope;
+    // Map to OAuthError once, outside the retry, so a run of occupied ports
+    // does not nest one OAuthError inside another.
+    const buildServer = (port) => Layer.build(factory.createServerLayer(callbackServerListenOptions(port))).pipe(Scope.provide(scope), Effect.map((context) => Context.get(context, HttpServer.HttpServer)), Effect.catchIf((error) => isAddressInUse(error) && port < MAX_PORT, () => buildServer(port + 1)));
+    const server = yield* buildServer(DEFAULT_PORT).pipe(Effect.mapError((cause) => new OAuthError({ step: "authorize", cause })));
+    if (!NetAddress.isInetAddress(server.address)) {
+        return yield* new OAuthError({ step: "authorize", cause: "OAuth callback server must listen on a TCP port" });
+    }
+    const port = server.address.port;
+    const router = yield* HttpRouter.make;
+    yield* router.add("GET", "/callback", Effect.gen(function* () {
+        const req = yield* HttpServerRequest.HttpServerRequest;
+        const url = new URL(req.url, callbackUrl(port));
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+        const errorDescription = url.searchParams.get("error_description");
+        if (state !== expectedState) {
+            return page("Security Error", "State verification failed.").pipe(HttpServerResponse.setStatus(403));
+        }
+        if (error !== null && error !== "") {
+            // An empty description is no description: report the error code instead.
+            yield* Deferred.fail(deferred, new OAuthError({
+                step: "authorize",
+                cause: errorDescription === null || errorDescription === "" ? error : errorDescription
+            }));
+            return page("Authorization Failed", "You can close this window.");
+        }
+        if (code === null || code === "") {
+            yield* Deferred.fail(deferred, new OAuthError({ step: "authorize", cause: "No authorization code received" }));
+            return page("Error", "No authorization code received.");
+        }
+        yield* Deferred.succeed(deferred, code);
+        return page("Success!", "You can close this window and return to the terminal.");
+    }));
+    // Installs the handler in this scope and returns; a failure to install
+    // surfaces here rather than leaving the caller waiting on a dead server.
+    yield* HttpServer.serveEffect(router.asHttpEffect()).pipe(Effect.provideService(HttpServer.HttpServer, server));
+    return {
+        codePromise: Deferred.await(deferred),
+        port
+    };
+});
+//# sourceMappingURL=oauthServer.js.map

package/dist/cli-auth/internal/oauthServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthServer.js","sourceRoot":"","sources":["../../../src/cli-auth/internal/oauthServer.ts"],"names":[],"mappings":"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"}

package/dist/cli-auth/openBrowser.d.ts

@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import type * as PlatformError from "effect/PlatformError";
+import { ChildProcessSpawner } from "effect/process";
+declare const BrowserOpenError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BrowserOpenError";
+} & Readonly<A>;
+/** A launcher ran but reported failure (for example `xdg-open` with no browser on a headless host). */
+export declare class BrowserOpenError extends BrowserOpenError_base<{
+    readonly command: string;
+    readonly exitCode: number;
+}> {
+}
+/** Open `url` in the user's browser. */
+export declare const openBrowser: (url: string) => Effect.Effect<void, BrowserOpenError | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+export {};
+//# sourceMappingURL=openBrowser.d.ts.map

package/dist/cli-auth/openBrowser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrowser.d.ts","sourceRoot":"","sources":["../../src/cli-auth/openBrowser.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAgB,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;;;;AAElE,uGAAuG;AACvG,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B,CAAC;CAAG;AAoBL,wCAAwC;AACxC,eAAO,MAAM,WAAW,QACjB,MAAM,KACV,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAAC,aAAa,EAAE,mBAAmB,CAAC,mBAAmB,CAI3G,CAAA"}

package/dist/cli-auth/openBrowser.js

@@ -0,0 +1,30 @@
+/**
+ * Cross-platform browser launcher backed by Effect child process services.
+ *
+ * Tries `open`, then `xdg-open`, then `rundll32.exe`, stopping at the first that
+ * exits 0. A launcher that is missing or exits non-zero falls through to the next;
+ * when none succeeds the last failure is reported, typed, so the caller decides
+ * whether a browser that never opened is fatal.
+ *
+ * @module
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+/** A launcher ran but reported failure (for example `xdg-open` with no browser on a headless host). */
+export class BrowserOpenError extends Data.TaggedError("BrowserOpenError") {
+}
+const run = (command, args) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const exitCode = yield* spawner.exitCode(ChildProcess.make(command, args, {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore"
+    }));
+    if (exitCode !== 0) {
+        return yield* new BrowserOpenError({ command, exitCode });
+    }
+});
+/** Open `url` in the user's browser. */
+export const openBrowser = (url) => run("open", [url]).pipe(Effect.catch(() => run("xdg-open", [url])), Effect.catch(() => run("rundll32.exe", ["url.dll,FileProtocolHandler", url])));
+//# sourceMappingURL=openBrowser.js.map

package/dist/cli-auth/openBrowser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openBrowser.js","sourceRoot":"","sources":["../../src/cli-auth/openBrowser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAElE,uGAAuG;AACvG,MAAM,OAAO,gBAAiB,SAAQ,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAGvE;CAAG;AAEL,MAAM,GAAG,GAAG,CACV,OAAe,EACf,IAA2B,EACmF,EAAE,CAChH,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,mBAAmB,CAAC,mBAAmB,CAAA;IAC9D,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,CACtC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;QAC/B,KAAK,EAAE,QAAQ;QACf,MAAM,EAAE,QAAQ;QAChB,MAAM,EAAE,QAAQ;KACjB,CAAC,CACH,CAAA;IACD,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC,CAAC,IAAI,gBAAgB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC3D,CAAC;AACH,CAAC,CAAC,CAAA;AAEJ,wCAAwC;AACxC,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,GAAW,EACmG,EAAE,CAChH,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CACrB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAC1C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC,CAAC,CAC9E,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/atlassian-common",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Shared utilities for Atlassian tools (AST, serializers, auth, config)",
   "license": "MIT",
   "author": "knpkv",
@@ -42,6 +42,10 @@
       "import": "./dist/auth/index.js",
       "types": "./dist/auth/index.d.ts"
     },
+    "./cli-auth": {
+      "import": "./dist/cli-auth/index.js",
+      "types": "./dist/cli-auth/index.d.ts"
+    },
     "./config": {
       "import": "./dist/config/index.js",
       "types": "./dist/config/index.d.ts"