@caido/server-auth 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Caido Labs Inc.
+
+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,51 @@
+<div align="center">
+  <img width="1000" alt="image" src="https://user-images.githubusercontent.com/6225588/211916659-567751d1-0225-402b-9141-4145c18b0834.png">
+
+  <br />
+  <br />
+  <a href="https://caido.io/">Website</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://dashboard.caido.io/">Dashboard</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://docs.caido.io/" target="_blank">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/roadmap">Roadmap</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://github.com/caido/caido/tree/main/brand">Branding</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/www-discord" target="_blank">Discord</a>
+  <br />
+  <hr />
+</div>
+
+## 👋 Server Auth
+
+[![NPM Version](https://img.shields.io/npm/v/@caido/server-auth?style=for-the-badge)](https://www.npmjs.com/package/@caido/server-auth)
+
+Authenticate with a Caido instance using device code flow.
+
+```typescript
+import { CaidoAuth, BrowserApprover } from "@caido/server-auth";
+
+const auth = new CaidoAuth(
+  "http://localhost:8080",
+  new BrowserApprover((request) => {
+    console.log(`Visit ${request.verificationUrl}`);
+    console.log(`Enter code: ${request.userCode}`);
+  })
+);
+
+const token = await auth.startAuthenticationFlow();
+console.log("Access token:", token.accessToken);
+```
+
+## Examples
+
+See the [examples](./examples/) directory for complete working examples:
+
+- [Browser Authentication](./examples/browser/) - Manual approval via browser
+- [PAT Authentication](./examples/pat/) - Automated approval using Personal Access Token
+
+## 💚 Community
+
+Come join our [Discord](https://links.caido.io/www-discord) community and connect with other Caido users! We'd love to have you as part of the conversation and help with any questions you may have.

package/dist/index.cjs

@@ -1,4 +1,5 @@
 let _urql_core = require("@urql/core");
+let graphql = require("graphql");
 let graphql_ws = require("graphql-ws");
 let graphql_tag = require("graphql-tag");
 
@@ -13,51 +14,42 @@ var AuthenticationError = class extends Error {
 	}
 };
 /**
-* Error thrown when the authentication flow fails to start.
+* Error thrown for errors coming from the Caido cloud API.
+* Used for device approval and device information operations.
 */
-var AuthenticationFlowError = class extends AuthenticationError {
-	/** Error code from the API */
-	code;
-	constructor(code, message) {
-		super(`${code}: ${message}`);
-		this.name = "AuthenticationFlowError";
-		this.code = code;
-	}
-};
-/**
-* Error thrown when token refresh fails.
-*/
-var TokenRefreshError = class extends AuthenticationError {
-	/** Error code from the API */
-	code;
-	constructor(code, message) {
-		super(`${code}: ${message}`);
-		this.name = "TokenRefreshError";
-		this.code = code;
-	}
-};
-/**
-* Error thrown when device approval fails.
-*/
-var DeviceApprovalError = class extends AuthenticationError {
+var CloudError = class extends AuthenticationError {
 	/** HTTP status code if available */
 	statusCode;
-	constructor(message, statusCode) {
+	/** Error code from the API if available */
+	code;
+	/** Reason for the error if available */
+	reason;
+	constructor(message, options) {
 		super(message);
-		this.name = "DeviceApprovalError";
-		this.statusCode = statusCode;
+		this.name = "CloudError";
+		this.statusCode = options?.statusCode;
+		this.code = options?.code;
+		this.reason = options?.reason;
 	}
 };
 /**
-* Error thrown when fetching device information fails.
+* Error thrown for errors coming from the Caido instance.
+* Used for authentication flow and token refresh operations.
 */
-var DeviceInformationError = class extends AuthenticationError {
-	/** HTTP status code if available */
-	statusCode;
-	constructor(message, statusCode) {
+var InstanceError = class extends AuthenticationError {
+	/** Error code from the API */
+	code;
+	/** Reason for the error if available */
+	reason;
+	/** Error message if available */
+	errorMessage;
+	constructor(code, options) {
+		const message = options?.reason ?? options?.message ?? code;
 		super(message);
-		this.name = "DeviceInformationError";
-		this.statusCode = statusCode;
+		this.name = "InstanceError";
+		this.code = code;
+		this.reason = options?.reason;
+		this.errorMessage = options?.message;
 	}
 };
 
@@ -73,8 +65,21 @@ const START_AUTHENTICATION_FLOW = graphql_tag.gql`
         expiresAt
       }
       error {
-        code
-        message
+        ... on AuthenticationUserError {
+          code
+          reason
+        }
+        ... on CloudUserError {
+          code
+          reason
+        }
+        ... on InternalUserError {
+          code
+          message
+        }
+        ... on OtherUserError {
+          code
+        }
       }
     }
   }
@@ -84,27 +89,51 @@ const CREATED_AUTHENTICATION_TOKEN = graphql_tag.gql`
     createdAuthenticationToken(requestId: $requestId) {
       token {
         accessToken
-        refreshToken
         expiresAt
+        refreshToken
+        scopes
       }
       error {
-        code
-        message
+        ... on AuthenticationUserError {
+          code
+          reason
+        }
+        ... on InternalUserError {
+          code
+          message
+        }
+        ... on OtherUserError {
+          code
+        }
       }
     }
   }
 `;
 const REFRESH_AUTHENTICATION_TOKEN = graphql_tag.gql`
-  mutation RefreshAuthenticationToken($refreshToken: String!) {
+  mutation RefreshAuthenticationToken($refreshToken: Token!) {
     refreshAuthenticationToken(refreshToken: $refreshToken) {
       token {
         accessToken
-        refreshToken
         expiresAt
+        refreshToken
+        scopes
       }
       error {
-        code
-        message
+        ... on AuthenticationUserError {
+          code
+          reason
+        }
+        ... on CloudUserError {
+          code
+          reason
+        }
+        ... on InternalUserError {
+          code
+          message
+        }
+        ... on OtherUserError {
+          code
+        }
       }
     }
   }
@@ -117,48 +146,54 @@ const REFRESH_AUTHENTICATION_TOKEN = graphql_tag.gql`
 *
 * @example
 * ```typescript
-* import { CaidoAuth, BrowserApprover } from "@caido/auth";
+* import { AuthClient, BrowserApprover } from "@caido/auth";
 *
-* const auth = new CaidoAuth(
-*   "http://localhost:8080",
-*   new BrowserApprover((request) => {
+* const auth = new AuthClient({
+*   instanceUrl: "http://localhost:8080",
+*   approver: new BrowserApprover((request) => {
 *     console.log(`Visit ${request.verificationUrl}`);
 *   })
-* );
+* });
 *
 * const token = await auth.startAuthenticationFlow();
 * console.log("Access token:", token.accessToken);
 * ```
 */
-var CaidoAuth = class {
+var AuthClient = class {
 	instanceUrl;
 	graphqlUrl;
 	websocketUrl;
 	approver;
 	client;
-	/**
-	* Create a new CaidoAuth client.
-	*
-	* @param instanceUrl - Base URL of the Caido instance (e.g., "http://localhost:8080")
-	* @param approver - The approver to use for the authentication flow
-	*/
-	constructor(instanceUrl, approver) {
-		this.instanceUrl = instanceUrl.replace(/\/$/, "");
+	fetchFn;
+	timeout;
+	constructor(options) {
+		this.instanceUrl = options.instanceUrl.replace(/\/$/, "");
 		this.graphqlUrl = `${this.instanceUrl}/graphql`;
 		this.websocketUrl = this.getWebsocketUrl();
-		this.approver = approver;
+		this.approver = options.approver;
+		this.fetchFn = options.fetch;
+		this.timeout = options.timeout;
 		this.client = new _urql_core.Client({
 			url: this.graphqlUrl,
-			exchanges: [_urql_core.fetchExchange]
+			exchanges: [_urql_core.fetchExchange],
+			fetchOptions: () => {
+				const fetchOptions = {};
+				if (this.timeout !== void 0) fetchOptions.signal = AbortSignal.timeout(this.timeout);
+				return fetchOptions;
+			},
+			fetch: this.fetchFn
 		});
 	}
-	/**
-	* Convert HTTP(S) URL to WS(S) URL for subscriptions.
-	*/
 	getWebsocketUrl() {
 		const url = new URL(this.graphqlUrl);
 		return `${url.protocol === "https:" ? "wss:" : "ws:"}//${url.host}/ws/graphql`;
 	}
+	extractErrorDetails(error) {
+		if ("reason" in error) return { reason: error.reason };
+		if ("message" in error) return { message: error.message };
+		return {};
+	}
 	/**
 	* Start the device code authentication flow.
 	*
@@ -169,16 +204,19 @@ var CaidoAuth = class {
 	* 4. Returns the authentication token once approved
 	*
 	* @returns The authentication token
-	* @throws {AuthenticationFlowError} If the flow fails to start
+	* @throws {InstanceError} If the flow fails to start
 	* @throws {AuthenticationError} If token retrieval fails
 	*/
 	async startAuthenticationFlow() {
 		const result = await this.client.mutation(START_AUTHENTICATION_FLOW, {}).toPromise();
-		if (result.error) throw new AuthenticationFlowError("GRAPHQL_ERROR", result.error.message);
+		if (result.error) throw new InstanceError("GRAPHQL_ERROR", { message: result.error.message });
 		const payload = result.data?.startAuthenticationFlow;
-		if (!payload) throw new AuthenticationFlowError("NO_RESPONSE", "No response from startAuthenticationFlow");
-		if (payload.error) throw new AuthenticationFlowError(payload.error.code, payload.error.message);
-		if (!payload.request) throw new AuthenticationFlowError("NO_REQUEST", "No authentication request returned");
+		if (!payload) throw new InstanceError("NO_RESPONSE", { message: "No response from startAuthenticationFlow" });
+		if (payload.error) {
+			const details = this.extractErrorDetails(payload.error);
+			throw new InstanceError(payload.error.code, details);
+		}
+		if (!payload.request) throw new InstanceError("NO_REQUEST", { message: "No authentication request returned" });
 		const authRequest = {
 			id: payload.request.id,
 			userCode: payload.request.userCode,
@@ -188,23 +226,11 @@ var CaidoAuth = class {
 		await this.approver.approve(authRequest);
 		return await this.waitForToken(authRequest.id);
 	}
-	/**
-	* Subscribe and wait for the authentication token.
-	*
-	* @param requestId - The authentication request ID
-	* @returns The authentication token once the user authorizes
-	* @throws {AuthenticationError} If subscription fails or returns an error
-	*/
 	async waitForToken(requestId) {
 		return new Promise((resolve, reject) => {
 			const wsClient = (0, graphql_ws.createClient)({ url: this.websocketUrl });
 			const unsubscribe = wsClient.subscribe({
-				query: CREATED_AUTHENTICATION_TOKEN.loc?.source.body ?? `subscription CreatedAuthenticationToken($requestId: ID!) {
-              createdAuthenticationToken(requestId: $requestId) {
-                token { accessToken refreshToken expiresAt }
-                error { code message }
-              }
-            }`,
+				query: (0, graphql.print)(CREATED_AUTHENTICATION_TOKEN),
 				variables: { requestId }
 			}, {
 				next: (result) => {
@@ -212,7 +238,8 @@ var CaidoAuth = class {
 					if (payload?.error) {
 						unsubscribe();
 						wsClient.dispose();
-						reject(new AuthenticationError(`${payload.error.code}: ${payload.error.message}`));
+						const details = this.extractErrorDetails(payload.error);
+						reject(new InstanceError(payload.error.code, details));
 						return;
 					}
 					if (payload?.token) {
@@ -221,17 +248,18 @@ var CaidoAuth = class {
 						resolve({
 							accessToken: payload.token.accessToken,
 							refreshToken: payload.token.refreshToken,
-							expiresAt: new Date(payload.token.expiresAt)
+							expiresAt: new Date(payload.token.expiresAt),
+							scopes: payload.token.scopes
 						});
 					}
 				},
 				error: (error) => {
 					wsClient.dispose();
-					reject(new AuthenticationError(error instanceof Error ? error.message : String(error)));
+					reject(new InstanceError("SUBSCRIPTION_ERROR", { message: error instanceof Error ? error.message : String(error) }));
 				},
 				complete: () => {
 					wsClient.dispose();
-					reject(new AuthenticationError("Subscription ended without receiving token"));
+					reject(new InstanceError("SUBSCRIPTION_COMPLETE", { message: "Subscription ended without receiving token" }));
 				}
 			});
 		});
@@ -241,19 +269,23 @@ var CaidoAuth = class {
 	*
 	* @param refreshToken - The refresh token from a previous authentication
 	* @returns New authentication token with updated access and refresh tokens
-	* @throws {TokenRefreshError} If the refresh fails
+	* @throws {InstanceError} If the refresh fails
 	*/
 	async refreshToken(refreshToken) {
 		const result = await this.client.mutation(REFRESH_AUTHENTICATION_TOKEN, { refreshToken }).toPromise();
-		if (result.error) throw new TokenRefreshError("GRAPHQL_ERROR", result.error.message);
+		if (result.error) throw new InstanceError("GRAPHQL_ERROR", { message: result.error.message });
 		const payload = result.data?.refreshAuthenticationToken;
-		if (!payload) throw new TokenRefreshError("NO_RESPONSE", "No response from refreshAuthenticationToken");
-		if (payload.error) throw new TokenRefreshError(payload.error.code, payload.error.message);
-		if (!payload.token) throw new TokenRefreshError("NO_TOKEN", "No token returned from refresh");
+		if (!payload) throw new InstanceError("NO_RESPONSE", { message: "No response from refreshAuthenticationToken" });
+		if (payload.error) {
+			const details = this.extractErrorDetails(payload.error);
+			throw new InstanceError(payload.error.code, details);
+		}
+		if (!payload.token) throw new InstanceError("NO_TOKEN", { message: "No token returned from refresh" });
 		return {
 			accessToken: payload.token.accessToken,
 			refreshToken: payload.token.refreshToken,
-			expiresAt: new Date(payload.token.expiresAt)
+			expiresAt: new Date(payload.token.expiresAt),
+			scopes: payload.token.scopes
 		};
 	}
 };
@@ -316,15 +348,14 @@ var PATApprover = class {
 	pat;
 	allowedScopes;
 	apiUrl;
-	/**
-	* Create a new PATApprover.
-	*
-	* @param options - Configuration options for the approver
-	*/
+	fetchFn;
+	timeout;
 	constructor(options) {
 		this.pat = options.pat;
 		this.allowedScopes = options.allowedScopes;
 		this.apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.timeout = options.timeout;
 	}
 	/**
 	* Approve the authentication request using the PAT.
@@ -333,50 +364,71 @@ var PATApprover = class {
 	* and finally approves the device.
 	*
 	* @param request - The authentication request
-	* @throws {DeviceInformationError} If fetching device information fails
-	* @throws {DeviceApprovalError} If approving the device fails
+	* @throws {CloudError} If fetching device information or approving the device fails
 	*/
 	async approve(request) {
 		let scopesToApprove = (await this.getDeviceInformation(request.userCode)).scopes.map((s) => s.name);
 		if (this.allowedScopes) scopesToApprove = scopesToApprove.filter((scope) => this.allowedScopes.includes(scope));
 		await this.approveDevice(request.userCode, scopesToApprove);
 	}
-	/**
-	* Fetch device information from the API.
-	*
-	* @param userCode - The user code from the authentication request
-	* @returns The device information including available scopes
-	* @throws {DeviceInformationError} If the request fails
-	*/
+	async sendRequest(url, options) {
+		const fetchOptions = {
+			method: options.method,
+			headers: options.headers
+		};
+		if (this.timeout !== void 0) fetchOptions.signal = AbortSignal.timeout(this.timeout);
+		return this.fetchFn(url, fetchOptions);
+	}
+	async parseOAuth2Error(response) {
+		let errorText;
+		let errorCode;
+		let errorDescription;
+		try {
+			const errorData = await response.json();
+			if (typeof errorData === "string") errorText = errorData;
+			else {
+				errorCode = errorData.error;
+				errorDescription = errorData.error_description;
+				errorText = errorDescription ?? errorCode ?? "Unknown error";
+			}
+		} catch {
+			errorText = await response.text().catch(() => "Unknown error");
+		}
+		return {
+			errorText,
+			errorCode,
+			errorDescription
+		};
+	}
 	async getDeviceInformation(userCode) {
 		const params = new URLSearchParams();
 		params.append("user_code", userCode);
 		const url = new URL(`${this.apiUrl}/oauth2/device/information`);
 		url.search = params.toString();
-		const response = await fetch(url, {
+		const response = await this.sendRequest(url, {
 			method: "GET",
 			headers: {
 				Authorization: `Bearer ${this.pat}`,
 				Accept: "application/json"
 			}
 		});
-		if (!response.ok) throw new DeviceInformationError(`Failed to get device information: ${await response.text().catch(() => "Unknown error")}`, response.status);
+		if (!response.ok) {
+			const { errorText, errorCode, errorDescription } = await this.parseOAuth2Error(response);
+			throw new CloudError(`Failed to get device information: ${errorText}`, {
+				statusCode: response.status,
+				code: errorCode,
+				reason: errorDescription
+			});
+		}
 		return await response.json();
 	}
-	/**
-	* Approve the device with the specified scopes.
-	*
-	* @param userCode - The user code from the authentication request
-	* @param scopes - The scopes to approve
-	* @throws {DeviceApprovalError} If the request fails
-	*/
 	async approveDevice(userCode, scopes) {
 		const params = new URLSearchParams();
 		params.append("user_code", userCode);
 		params.append("scope", scopes.join(","));
 		const url = new URL(`${this.apiUrl}/oauth2/device/approve`);
 		url.search = params.toString();
-		const response = await fetch(url, {
+		const response = await this.sendRequest(url, {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${this.pat}`,
@@ -384,17 +436,22 @@ var PATApprover = class {
 				Accept: "application/json"
 			}
 		});
-		if (!response.ok) throw new DeviceApprovalError(`Failed to approve device: ${await response.text().catch(() => "Unknown error")}`, response.status);
+		if (!response.ok) {
+			const { errorText, errorCode, errorDescription } = await this.parseOAuth2Error(response);
+			throw new CloudError(`Failed to approve device: ${errorText}`, {
+				statusCode: response.status,
+				code: errorCode,
+				reason: errorDescription
+			});
+		}
 	}
 };
 
 //#endregion
+exports.AuthClient = AuthClient;
 exports.AuthenticationError = AuthenticationError;
-exports.AuthenticationFlowError = AuthenticationFlowError;
 exports.BrowserApprover = BrowserApprover;
-exports.CaidoAuth = CaidoAuth;
-exports.DeviceApprovalError = DeviceApprovalError;
-exports.DeviceInformationError = DeviceInformationError;
+exports.CloudError = CloudError;
+exports.InstanceError = InstanceError;
 exports.PATApprover = PATApprover;
-exports.TokenRefreshError = TokenRefreshError;
 //# sourceMappingURL=index.cjs.map