@tsg-dsp/tsg-sdk 0.0.0-stage → 0.20.1

package/dist/auth/auth.provider.d.ts

@@ -0,0 +1,45 @@
+import type { TsgSdkAuthConfig } from "../config/sdk.config.js";
+/**
+ * Handles OAuth 2.0 token acquisition, caching, and automatic refresh
+ * for all SDK HTTP clients.
+ *
+ * Supports three authentication strategies:
+ * - `client_secret_post` — client credentials with a shared secret.
+ * - `private_key_jwt` — client credentials with a signed JWT assertion.
+ * - `access_token` — static pre-obtained bearer token (no refresh).
+ *
+ * Tokens are cached and automatically re-acquired when they expire
+ * (with a 10-second safety buffer). OpenID Connect discovery is used
+ * to locate the token endpoint.
+ */
+export declare class AuthProvider {
+    private readonly authConfig;
+    private readonly ssoBridgeBaseUrl;
+    private cachedToken?;
+    private tokenExpiresAt;
+    private openIdConfig?;
+    constructor(authConfig: TsgSdkAuthConfig | undefined, ssoBridgeBaseUrl: string | undefined);
+    /**
+     * Get a valid access token, acquiring or refreshing one if necessary.
+     *
+     * - Returns `undefined` when no auth config is set (unauthenticated mode).
+     * - Returns the static token for `access_token` auth.
+     * - For other methods, returns a cached token or acquires a new one.
+     * @returns The access token string, or `undefined` if auth is not configured.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if token acquisition fails.
+     */
+    getAccessToken(): Promise<string | undefined>;
+    /**
+     * Build an HTTP headers object containing the `Authorization` header.
+     *
+     * Returns an empty object when auth is not configured, allowing
+     * unauthenticated requests to pass through.
+     * @returns A headers record, e.g. `{ Authorization: "Bearer <token>" }`.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    private acquireToken;
+    private getOpenIdConfiguration;
+    private createClientAssertion;
+    private resolveAlgorithm;
+}
+//# sourceMappingURL=auth.provider.d.ts.map

package/dist/auth/auth.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.provider.d.ts","sourceRoot":"","sources":["../../src/auth/auth.provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAWhE;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IAMrB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IANnC,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAsB;gBAGxB,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS;IAGvD;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAiBnD;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAQzC,YAAY;YA4DZ,sBAAsB;YAwCtB,qBAAqB;IAmBnC,OAAO,CAAC,gBAAgB;CAazB"}

package/dist/auth/auth.provider.js

@@ -0,0 +1,158 @@
+import { importJWK, SignJWT } from "jose";
+import { SdkError, SdkErrorCode } from "../utils/errors.js";
+/**
+ * Buffer (in milliseconds) subtracted from the token expiry time to ensure
+ * tokens are refreshed before they actually expire.
+ * @internal
+ */
+const TOKEN_EXPIRY_BUFFER_MS = 10_000;
+/**
+ * Handles OAuth 2.0 token acquisition, caching, and automatic refresh
+ * for all SDK HTTP clients.
+ *
+ * Supports three authentication strategies:
+ * - `client_secret_post` — client credentials with a shared secret.
+ * - `private_key_jwt` — client credentials with a signed JWT assertion.
+ * - `access_token` — static pre-obtained bearer token (no refresh).
+ *
+ * Tokens are cached and automatically re-acquired when they expire
+ * (with a 10-second safety buffer). OpenID Connect discovery is used
+ * to locate the token endpoint.
+ */
+export class AuthProvider {
+    authConfig;
+    ssoBridgeBaseUrl;
+    cachedToken;
+    tokenExpiresAt = 0;
+    openIdConfig;
+    constructor(authConfig, ssoBridgeBaseUrl) {
+        this.authConfig = authConfig;
+        this.ssoBridgeBaseUrl = ssoBridgeBaseUrl;
+    }
+    /**
+     * Get a valid access token, acquiring or refreshing one if necessary.
+     *
+     * - Returns `undefined` when no auth config is set (unauthenticated mode).
+     * - Returns the static token for `access_token` auth.
+     * - For other methods, returns a cached token or acquires a new one.
+     * @returns The access token string, or `undefined` if auth is not configured.
+     * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.AUTH_FAILED} if token acquisition fails.
+     */
+    async getAccessToken() {
+        if (!this.authConfig) {
+            return undefined;
+        }
+        if (this.authConfig.method === "access_token") {
+            return this.authConfig.accessToken;
+        }
+        if (this.cachedToken && Date.now() < this.tokenExpiresAt) {
+            return this.cachedToken;
+        }
+        const token = await this.acquireToken();
+        return token;
+    }
+    /**
+     * Build an HTTP headers object containing the `Authorization` header.
+     *
+     * Returns an empty object when auth is not configured, allowing
+     * unauthenticated requests to pass through.
+     * @returns A headers record, e.g. `{ Authorization: "Bearer <token>" }`.
+     */
+    async getAuthHeaders() {
+        const token = await this.getAccessToken();
+        if (!token) {
+            return {};
+        }
+        return { Authorization: `Bearer ${token}` };
+    }
+    async acquireToken() {
+        const config = this.authConfig;
+        if (!config || config.method === "access_token") {
+            throw new SdkError("Cannot acquire token with access_token method", SdkErrorCode.AUTH_FAILED);
+        }
+        const openIdConfig = await this.getOpenIdConfiguration();
+        const tokenEndpoint = openIdConfig.token_endpoint;
+        const params = new URLSearchParams();
+        params.set("grant_type", "client_credentials");
+        params.set("client_id", config.clientId);
+        if (config.method === "client_secret_post") {
+            params.set("client_secret", config.clientSecret);
+        }
+        else if (config.method === "private_key_jwt") {
+            const assertion = await this.createClientAssertion(config.clientId, config.privateKeyJwk, tokenEndpoint);
+            params.set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer");
+            params.set("client_assertion", assertion);
+        }
+        const response = await fetch(tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString()
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new SdkError(`Token acquisition failed (${response.status}): ${body}`, SdkErrorCode.AUTH_FAILED, response.status);
+        }
+        const tokenResponse = await response.json();
+        this.cachedToken = tokenResponse.access_token;
+        if (tokenResponse.expires_in) {
+            this.tokenExpiresAt =
+                Date.now() + tokenResponse.expires_in * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+        }
+        else {
+            // Default to 5 minutes if no expiry given
+            this.tokenExpiresAt = Date.now() + 5 * 60 * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+        }
+        return this.cachedToken;
+    }
+    async getOpenIdConfiguration() {
+        if (this.openIdConfig) {
+            return this.openIdConfig;
+        }
+        const config = this.authConfig;
+        if (!config || config.method === "access_token") {
+            throw new SdkError("No OpenID configuration available", SdkErrorCode.AUTH_FAILED);
+        }
+        const url = config.openIdConfigurationUrl ??
+            (this.ssoBridgeBaseUrl
+                ? new URL("/.well-known/openid-configuration", this.ssoBridgeBaseUrl)
+                    .href
+                : undefined);
+        if (!url) {
+            throw new SdkError("Cannot determine OpenID configuration URL. Provide openIdConfigurationUrl or ssoBridgeBaseUrl.", SdkErrorCode.INVALID_CONFIG);
+        }
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new SdkError(`Failed to fetch OpenID configuration from ${url} (${response.status})`, SdkErrorCode.AUTH_FAILED, response.status);
+        }
+        this.openIdConfig = await response.json();
+        return this.openIdConfig;
+    }
+    async createClientAssertion(clientId, privateKeyJwk, audience) {
+        const key = await importJWK(privateKeyJwk);
+        const alg = this.resolveAlgorithm(privateKeyJwk);
+        return new SignJWT({})
+            .setProtectedHeader({ alg, typ: "JWT" })
+            .setIssuer(clientId)
+            .setSubject(clientId)
+            .setAudience(audience)
+            .setIssuedAt()
+            .setExpirationTime("5m")
+            .setJti(crypto.randomUUID())
+            .sign(key);
+    }
+    resolveAlgorithm(jwk) {
+        if (jwk.alg)
+            return jwk.alg;
+        switch (jwk.kty) {
+            case "EC":
+                return jwk.crv === "P-384" ? "ES384" : "ES256";
+            case "OKP":
+                return "EdDSA";
+            case "RSA":
+                return "RS256";
+            default:
+                return "ES256";
+        }
+    }
+}
+//# sourceMappingURL=auth.provider.js.map

package/dist/auth/auth.provider.js.map

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

package/dist/auth/auth.types.d.ts

@@ -0,0 +1,27 @@
+/** Supported OAuth 2.0 / authentication methods for the SDK. */
+export type AuthMethod = "client_secret_post" | "private_key_jwt" | "access_token";
+/** Response from an OAuth 2.0 token endpoint. */
+export interface TokenResponse {
+    /** The issued access token. */
+    access_token: string;
+    /** Token type, typically `"Bearer"`. */
+    token_type: string;
+    /** Number of seconds until the token expires. */
+    expires_in?: number;
+    /** Space-delimited list of granted scopes. */
+    scope?: string;
+}
+/** Subset of an OpenID Connect discovery document used by the SDK. */
+export interface OpenIDConfiguration {
+    /** The issuer identifier of the OpenID provider. */
+    issuer: string;
+    /** URL of the token endpoint. */
+    token_endpoint: string;
+    /** URL of the authorization endpoint. */
+    authorization_endpoint?: string;
+    /** URL of the JSON Web Key Set document. */
+    jwks_uri: string;
+    /** Additional OpenID configuration fields. */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=auth.types.d.ts.map

package/dist/auth/auth.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.d.ts","sourceRoot":"","sources":["../../src/auth/auth.types.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,MAAM,UAAU,GACpB,oBAAoB,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAE5D,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/auth/auth.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.types.js.map

package/dist/auth/auth.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.js","sourceRoot":"","sources":["../../src/auth/auth.types.ts"],"names":[],"mappings":""}

package/dist/auth/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./auth.provider.js";
+export * from "./auth.types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,3 @@
+export * from "./auth.provider.js";
+export * from "./auth.types.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}