@takodotid/azure-rest 0.1.0

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./AzureClient.js";
+export * from "./lib/AzureCliCredential.js";
+export * from "./lib/AzureCredential.js";
+export * from "./lib/DefaultChainedCredential.js";
+export * from "./lib/ManagedIdentityCredential.js";
+export * from "./lib/ServicePrincipalCredential.js";
+export * from "./lib/WorkloadIdentityCredential.js";

package/src/lib/AzureCliCredential.ts

@@ -0,0 +1,135 @@
+import { execFile } from "node:child_process";
+import process from "node:process";
+import type { AzureCredential } from "./AzureCredential.js";
+
+/**
+ * The raw response returned by Azure CLI when requesting an access token.
+ *
+ * @property accessToken - The access token string
+ * @property expiresOn - Expiry date in RFC3339 format (legacy)
+ * @property expires_on - Expiry as seconds since epoch (preferred)
+ * @property subscription - (Optional) Subscription ID, may not be present
+ * @property tenant - Tenant ID
+ * @property tokenType - Token type (usually 'Bearer')
+ */
+export type CLITokenResponse = {
+	accessToken: string;
+	expiresOn: string;
+	expires_on: string;
+	subscription?: string;
+	tenant: string;
+	tokenType: string;
+};
+
+/**
+ * Options for AzureCliCredential.
+ *
+ * @property tenantId - The Azure tenant ID to use for authentication
+ */
+export type AzureCLICredentialOptions = {
+	tenantId: string;
+};
+
+export class AzureCliCredential implements AzureCredential {
+	public constructor(public options: AzureCLICredentialOptions) {}
+
+	/**
+	 * Gets an Azure access token using the Azure CLI.
+	 * @param scope The resource scope for the token
+	 * @returns An object with token and expiresAt
+	 * @throws If CLI is not installed or not logged in
+	 */
+	public async getToken(scope: string) {
+		try {
+			const result = await this.getCliToken(scope);
+
+			const specificScope = result.stderr.match("(.*)az login --scope(.*)");
+			const isLoginError = result.stderr.match("(.*)az login(.*)") && !specificScope;
+			const isNotInstallError = result.stderr.match("az:(.*)not found") ?? result.stderr.startsWith("'az' is not recognized");
+
+			if (isNotInstallError) {
+				throw new Error("Azure CLI not found. Please install");
+			}
+			if (isLoginError) {
+				throw new Error("Please login to Azure CLI");
+			}
+
+			return this.parseRawOutput(result.stdout);
+		} catch (error) {
+			throw new Error(`Failed to get token: ${(error as Error).stack}`);
+		}
+	}
+
+	/**
+	 * Runs the Azure CLI to get an access token for the given scope.
+	 * @param scope The resource scope
+	 * @returns Promise resolving to CLI stdout and stderr
+	 * @private
+	 */
+	private async getCliToken(scope: string) {
+		return new Promise<{ stderr: string; stdout: string }>((resolve, reject) => {
+			try {
+				execFile(
+					"az",
+					["account", "get-access-token", "--output", "json", "--resource", scope.replace(".default", ""), "--tenant", this.options.tenantId],
+					{ cwd: process.cwd(), shell: true, timeout: 30_000 },
+					(error, stdout, stderr) => {
+						if (error) {
+							reject(new Error(`Failed to get token: ${error.stack}`));
+							return;
+						}
+
+						resolve({ stdout, stderr });
+					}
+				);
+			} catch (error) {
+				reject(error as Error);
+			}
+		});
+	}
+
+	/**
+	 * Parses the raw CLI output and returns a token + expiry object.
+	 * @param output The stdout from Azure CLI
+	 * @returns An object with token and expiresAt
+	 * @private
+	 */
+	private parseRawOutput(output: string) {
+		const response = JSON.parse(output) as CLITokenResponse;
+		const token = response.accessToken;
+
+		// if available, expires_on will be a number representing seconds since epoch.
+		// ensure it's a number or NaN
+		const expiresOnTimestamp = Number.parseInt(response.expires_on, 10) * 1_000;
+		if (!Number.isNaN(expiresOnTimestamp)) {
+			return {
+				accessToken: token,
+				expiresAt: new Date(expiresOnTimestamp),
+				tokenType: response.tokenType
+			};
+		}
+
+		// fallback to the older expiresOn - an RFC3339 date string
+		return {
+			accessToken: token,
+			expiresAt: new Date(response.expiresOn),
+			tokenType: response.tokenType
+		};
+	}
+
+	/**
+	 * Instantiates AzureCliCredential using the AZURE_TENANT_ID environment variable.
+	 * @returns AzureCliCredential instance
+	 */
+	public static fromEnv() {
+		return new AzureCliCredential({ tenantId: process.env.AZURE_TENANT_ID });
+	}
+}
+
+declare global {
+	namespace NodeJS {
+		interface ProcessEnv {
+			AZURE_TENANT_ID: string;
+		}
+	}
+}

package/src/lib/AzureCredential.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents an Azure access token and its expiration.
+ */
+export type Credential = { accessToken: string; clientId?: string; expiresAt: Date; tokenType: string };
+
+/**
+ * Abstract credential class for acquiring Azure tokens.
+ * Implement this to provide custom authentication logic.
+ */
+export abstract class AzureCredential {
+	/**
+	 * Gets an Azure access token for the given scope.
+	 * @param scope The resource or scope for which the token is requested
+	 * @returns A promise resolving to an AzureToken
+	 */
+	public abstract getToken(scope: string): Promise<Credential>;
+}

package/src/lib/DefaultChainedCredential.ts

@@ -0,0 +1,34 @@
+import { AzureCliCredential } from "./AzureCliCredential.js";
+import type { AzureCredential } from "./AzureCredential.js";
+import { ManagedIdentityCredential } from "./ManagedIdentityCredential.js";
+import { ServicePrincipalCredential } from "./ServicePrincipalCredential.js";
+import { WorkloadIdentityCredential } from "./WorkloadIdentityCredential.js";
+
+const credentialChain = [WorkloadIdentityCredential, ManagedIdentityCredential, ServicePrincipalCredential, AzureCliCredential];
+
+/**
+ * DefaultChainedCredential tries multiple credential providers in order until one succeeds.
+ *
+ * The chain is: WorkloadIdentityCredential → ManagedIdentityCredential → ServicePrincipalCredential → AzureCliCredential.
+ * Useful for local dev, CI, and cloud environments with minimal config.
+ */
+export class DefaultChainedCredential implements AzureCredential {
+	/**
+	 * Attempts to get an Azure access token using the first available credential in the chain.
+	 * @param scope The resource scope for the token
+	 * @returns An object with token and expiresAt
+	 * @throws If all credential providers fail
+	 */
+	public async getToken(scope: string) {
+		const errors: { name: string; error: Error }[] = [];
+		for (const Credential of credentialChain) {
+			try {
+				return await Credential.fromEnv().getToken(scope);
+			} catch (error) {
+				errors.push({ error: error as Error, name: Credential.name });
+			}
+		}
+
+		throw new Error(`Failed to get token, errors:\n${errors.map(err => `[${err.name}] ${err.error.message}`).join("\n")}`);
+	}
+}

package/src/lib/ManagedIdentityCredential.ts

@@ -0,0 +1,75 @@
+import type { AzureCredential } from "./AzureCredential.js";
+import type { OAuth2TokenResponse } from "./ServicePrincipalCredential.js";
+
+/**
+ * Options for configuring ManagedIdentityCredential.
+ *
+ * @property clientId - (Optional) The user-assigned managed identity client ID
+ */
+export type ManagedIdentityCredentialOptions = {
+	clientId?: string;
+};
+
+/**
+ * AzureCredential implementation for Azure Managed Identity (MSI).
+ *
+ * Supports both system-assigned and user-assigned managed identities.
+ * Works on Azure VM, App Service, Container Apps, etc.
+ */
+export class ManagedIdentityCredential implements AzureCredential {
+	/**
+	 * @param options Managed identity credential options
+	 */
+	public constructor(public options: ManagedIdentityCredentialOptions = {}) {}
+
+	/**
+	 * Gets an Azure access token using the managed identity endpoint.
+	 * @param scope The resource scope for the token
+	 * @returns An object with token and expiresAt
+	 * @throws If the endpoint is unavailable or token request fails
+	 */
+	public async getToken(scope: string) {
+		const endpoint = process.env.AZURE_MANAGED_IDENTITY_ENDPOINT || process.env.IDENTITY_ENDPOINT || "http://169.254.169.254/metadata/identity/oauth2/token";
+		const apiVersion = "2018-02-01";
+		const params = new URLSearchParams({
+			resource: scope.replace(".default", ""),
+			apiVersion
+		});
+		if (this.options.clientId) {
+			params.set("client_id", this.options.clientId);
+		}
+
+		const url = `${endpoint}?${params.toString()}`;
+		const headers = { Metadata: "true" };
+
+		const response = await fetch(url, { headers });
+		if (!response.ok) {
+			throw new Error(`ManagedIdentityCredential: Failed to get token: ${await response.text()}`);
+		}
+
+		const data = (await response.json()) as OAuth2TokenResponse;
+		return {
+			accessToken: data.access_token,
+			clientId: data.client_id,
+			expiresAt: new Date(data.expires_on ? Number(data.expires_on) * 1000 : Date.now() + 60 * 60 * 1000), // fallback 1h
+			tokenType: data.token_type
+		};
+	}
+
+	/**
+	 * Instantiates ManagedIdentityCredential using environment variables.
+	 * @returns ManagedIdentityCredential instance
+	 */
+	public static fromEnv() {
+		return new ManagedIdentityCredential({ clientId: process.env.AZURE_CLIENT_ID });
+	}
+}
+
+declare global {
+	namespace NodeJS {
+		interface ProcessEnv {
+			AZURE_MANAGED_IDENTITY_ENDPOINT?: string;
+			IDENTITY_ENDPOINT?: string;
+		}
+	}
+}

package/src/lib/ServicePrincipalCredential.ts

@@ -0,0 +1,132 @@
+import { URLSearchParams } from "node:url";
+import type { AzureCredential } from "./AzureCredential.js";
+
+/**
+ * The OAuth2 token response returned by Azure AD and Managed Identity endpoints.
+ *
+ * @property access_token - The access token string
+ * @property client_id - The client/application ID (optional, present in MSI)
+ * @property expires_in - Seconds until token expiry
+ * @property expires_on - Expiry time (epoch seconds, as string)
+ * @property ext_expires_in - Extended expiry in seconds
+ * @property not_before - Not before time (epoch seconds, as string)
+ * @property resource - The resource for which the token is issued
+ * @property token_type - The type of token (usually 'Bearer')
+ */
+export type OAuth2TokenResponse = {
+	access_token: string;
+	client_id?: string;
+	expires_in: number;
+	expires_on: string;
+	ext_expires_in: number;
+	not_before: string;
+	resource: string;
+	token_type: string;
+};
+
+/**
+ * Options for configuring ServicePrincipalCredential.
+ *
+ * @property clientId - The Azure AD application (client) ID
+ * @property clientSecret - The client secret or JWT assertion (for federated)
+ * @property tenantId - The Azure AD tenant ID
+ * @property authorityHost - (Optional) The Azure AD authority host
+ * @property federated - Whether to use federated (JWT) auth
+ */
+export type ServicePrincipalCredentialOption = {
+	clientId: string;
+	clientSecret?: string;
+	tenantId: string;
+	authorityHost?: string;
+	federated: boolean;
+};
+
+/**
+ * AzureCredential implementation for authenticating with a Service Principal (client secret or federated/JWT).
+ */
+export class ServicePrincipalCredential implements AzureCredential {
+	/**
+	 * @param options Service principal credential options
+	 */
+	public constructor(public options: ServicePrincipalCredentialOption) {}
+
+	/**
+	 * Gets an Azure access token using the service principal credentials.
+	 * @param scope The resource scope for the token
+	 * @returns An object with token and expiresAt
+	 * @throws If client secret is missing or token request fails
+	 */
+	public async getToken(scope: string) {
+		if (!this.options.clientSecret) throw new Error("ServicePrincipalCredential: The client secret is not provided.");
+
+		// Remove trailing slash from identityAuthorityHost
+		const url = [this.options.authorityHost?.replace(/\/$/, "") ?? "https://login.microsoftonline.com", `${this.options.tenantId}/oauth2/v2.0/token`].join("/");
+
+		try {
+			const searchParams = {
+				client_id: this.options.clientId,
+				grant_type: "client_credentials",
+				scope
+			};
+
+			// If federated, use client_assertion and client_assertion_type
+			// Otherwise, use client_secret
+			if (this.options.federated) {
+				Object.assign(searchParams, {
+					client_assertion: this.options.clientSecret,
+					client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+				});
+			} else {
+				Object.assign(searchParams, {
+					client_secret: this.options.clientSecret
+				});
+			}
+			const response = await fetch(url, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/x-www-form-urlencoded"
+				},
+				body: new URLSearchParams(searchParams)
+			});
+
+			if (!response.ok) {
+				throw new Error(`Failed to get token: ${await response.text()}`);
+			}
+
+			const data = (await response.json()) as OAuth2TokenResponse;
+
+			return {
+				accessToken: data.access_token,
+				clientId: data.client_id ?? this.options.clientId,
+				expiresAt: new Date(Date.now() + data.expires_in * 1_000),
+				tokenType: data.token_type
+			};
+		} catch (error) {
+			throw new Error(`Failed to get token: ${(error as Error).stack}`);
+		}
+	}
+
+	/**
+	 * Instantiates ServicePrincipalCredential using environment variables.
+	 * @returns ServicePrincipalCredential instance
+	 */
+	public static fromEnv() {
+		return new ServicePrincipalCredential({
+			clientId: process.env.AZURE_CLIENT_ID,
+			clientSecret: process.env.AZURE_CLIENT_SECRET,
+			tenantId: process.env.AZURE_TENANT_ID,
+			federated: false
+		});
+	}
+}
+
+declare global {
+	namespace NodeJS {
+		interface ProcessEnv {
+			AZURE_CLIENT_ID: string;
+			AZURE_CLIENT_SECRET: string;
+			AZURE_TENANT_ID: string;
+		}
+	}
+}

package/src/lib/WorkloadIdentityCredential.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { AzureCredential } from "./AzureCredential.js";
+import { ServicePrincipalCredential } from "./ServicePrincipalCredential.js";
+
+/**
+ * Options for configuring WorkloadIdentityCredential.
+ *
+ * @property clientId - The Azure AD application (client) ID
+ * @property federatedTokenFile - Path to the federated token file (OIDC/JWT)
+ * @property tenantId - The Azure AD tenant ID
+ * @property authorityHost - (Optional) The Azure AD authority host
+ */
+export type WorkloadIdentityCredentialOption = {
+	clientId: string;
+	federatedTokenFile: string;
+	tenantId: string;
+	authorityHost?: string;
+};
+
+/**
+ * AzureCredential implementation for Azure Workload Identity (OIDC federated token).
+ *
+ * Reads a federated token from file and authenticates as a service principal using JWT assertion.
+ */
+export class WorkloadIdentityCredential implements AzureCredential {
+	/**
+	 * @param options Workload identity credential options
+	 */
+	public constructor(public options: WorkloadIdentityCredentialOption) {}
+
+	/**
+	 * Gets an Azure access token using the federated token file.
+	 * @param scope The resource scope for the token
+	 * @returns An object with token and expiresAt
+	 * @throws If the federated token file does not exist
+	 */
+	public async getToken(scope: string) {
+		if (!existsSync(this.options.federatedTokenFile)) {
+			throw new Error("WorkloadIdentityCredential: The federated token file does not exist.");
+		}
+
+		const token = readFileSync(this.options.federatedTokenFile, "utf-8");
+		const servicePrincipal = new ServicePrincipalCredential({ ...this.options, clientSecret: token, federated: true });
+
+		return servicePrincipal.getToken(scope);
+	}
+
+	/**
+	 * Instantiates WorkloadIdentityCredential using environment variables.
+	 * @returns WorkloadIdentityCredential instance
+	 */
+	public static fromEnv() {
+		return new WorkloadIdentityCredential({
+			authorityHost: process.env.AZURE_AUTHORITY_HOST,
+			clientId: process.env.AZURE_CLIENT_ID,
+			federatedTokenFile: process.env.AZURE_FEDERATED_TOKEN_FILE,
+			tenantId: process.env.AZURE_TENANT_ID
+		});
+	}
+}
+
+declare global {
+	namespace NodeJS {
+		interface ProcessEnv {
+			AZURE_AUTHORITY_HOST: string;
+			AZURE_CLIENT_ID: string;
+			AZURE_FEDERATED_TOKEN_FILE: string;
+			AZURE_TENANT_ID: string;
+		}
+	}
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"baseUrl": ".",
+		"lib": ["ES2022"],
+		"module": "node18",
+		"moduleResolution": "nodenext",
+		"target": "es2022",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"declaration": true,
+		"noEmit": true
+	},
+	"include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+	entry: ["src/index.ts"],
+	format: ["esm", "cjs"],
+	dts: true,
+	platform: "node",
+	target: "es2022",
+	sourcemap: true
+});