@storyteq/authnz-sdk 1.0.0

package/README.md

@@ -0,0 +1,220 @@
+# @storyteq/authnz-sdk
+
+Backend SDK for Keycloak authentication and Access API authorization.
+
+## Installation
+
+```bash
+pnpm add @storyteq/authnz-sdk @keycloak/keycloak-admin-client
+```
+
+## Usage
+
+### Service Token Provider (Machine-to-Machine)
+
+Use this for backend services that need to authenticate as a service account:
+
+```typescript
+import {
+  createServiceTokenProvider,
+  KEYCLOAK_URLS,
+  ACCESS_API_URLS,
+  REALMS,
+} from "@storyteq/authnz-sdk"
+
+const provider = createServiceTokenProvider({
+  keycloakBaseUrl: KEYCLOAK_URLS.production["europe-west1"],
+  keycloakRealm: REALMS.production,
+  accessApiBaseUrl: ACCESS_API_URLS.production["europe-west1"],
+  clientId: process.env.KEYCLOAK_CLIENT_ID,
+  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+  // Optional: set defaults for RPT requests
+  defaultPermissions: ["workspace:*"],
+  defaultAudience: ["platform"],
+})
+
+// Get a Keycloak service account token
+const kcToken = await provider.keycloak()
+console.log(kcToken.accessToken)
+
+// Get an RPT (Resource Permission Token) from Access API
+const rptToken = await provider.rpt({
+  permissions: ["workspace:123"],
+  audience: ["platform"],
+})
+console.log(rptToken.accessToken)
+```
+
+### User Token Provider (On-Behalf-Of)
+
+Use this when you have a user's Keycloak JWT and need to exchange it for an RPT:
+
+```typescript
+import { createUserTokenProvider, ACCESS_API_URLS } from "@storyteq/authnz-sdk"
+
+const provider = createUserTokenProvider({
+  accessApiBaseUrl: ACCESS_API_URLS.production["europe-west1"],
+})
+
+// Exchange user's Keycloak JWT for RPT
+const rptToken = await provider.rpt({
+  keycloakJwt: userKeycloakToken,
+  permissions: ["workspace:123"],
+  audience: ["platform"],
+})
+
+// Or exchange a static API token
+const rptFromApiToken = await provider.rpt({
+  apiToken: userApiToken,
+  permissions: ["workspace:123"],
+})
+```
+
+## API Reference
+
+### Types
+
+#### TokenResult
+
+```typescript
+interface TokenResult {
+  accessToken: string
+  expiresAt: Date
+  expiresIn: number
+}
+```
+
+#### ServiceTokenProviderConfig
+
+```typescript
+interface ServiceTokenProviderConfig {
+  keycloakBaseUrl: string
+  keycloakRealm: string
+  accessApiBaseUrl: string
+  clientId: string
+  clientSecret: string
+  defaultPermissions?: string[]
+  defaultAudience?: string[]
+  logger?: Logger
+}
+```
+
+#### UserTokenProviderConfig
+
+```typescript
+interface UserTokenProviderConfig {
+  accessApiBaseUrl: string
+  logger?: Logger
+}
+```
+
+### Constants
+
+- `KEYCLOAK_URLS` - Keycloak URLs by environment and region
+- `ACCESS_API_URLS` - Access API URLs by environment and region
+- `REALMS` - Keycloak realm names by environment
+
+### Error Handling
+
+All errors are thrown as `AuthNZError` with specific error codes:
+
+```typescript
+import { AuthNZError, ErrorCode } from "@storyteq/authnz-sdk"
+
+try {
+  const token = await provider.rpt()
+} catch (error) {
+  if (error instanceof AuthNZError) {
+    switch (error.code) {
+      case ErrorCode.KEYCLOAK_AUTH_FAILED:
+        // Handle Keycloak authentication failure
+        break
+      case ErrorCode.ACCESS_API_INVALID_TOKEN:
+        // Handle invalid token
+        break
+      case ErrorCode.ACCESS_API_USER_NOT_FOUND:
+        // Handle user not found
+        break
+    }
+  }
+}
+```
+
+### Logging
+
+Pass a logger to the provider configuration to enable debug logging:
+
+```typescript
+const provider = createServiceTokenProvider({
+  // ... config
+  logger: {
+    debug: (msg, ctx) => console.debug(msg, ctx),
+    info: (msg, ctx) => console.info(msg, ctx),
+    warn: (msg, ctx) => console.warn(msg, ctx),
+    error: (msg, ctx) => console.error(msg, ctx),
+  },
+})
+```
+
+## Caching Behavior
+
+### Service Token Provider
+
+- Keycloak tokens are cached and reused until 15 seconds before expiry
+- RPT tokens are cached per unique combination of permissions and audience
+- On 401 errors, the cache is cleared and tokens are refreshed automatically
+
+### User Token Provider
+
+- User tokens are NOT cached (each call makes a fresh request)
+- This is intentional for security - user context should not be cached
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm type-check
+
+# Build
+pnpm build
+
+# Lint
+pnpm lint
+```
+
+## CI/CD
+
+### Static Checks
+
+On every MR and push to main, the CI runs:
+
+- `pnpm lint` - ESLint checks
+- `pnpm type-check` - TypeScript type checking
+- `pnpm build` - Build verification
+- `pnpm test` - Unit tests
+
+### Publishing to NPM
+
+To publish a new version to NPM:
+
+1. Update the version in `package.json`
+2. Commit and merge to `main`
+3. Create a git tag from a commit on main:
+   ```bash
+   git tag authnz-sdk/1.0.0
+   ```
+4. Push the tag:
+   ```bash
+   git push origin authnz-sdk/1.0.0
+   ```
+
+The CI will automatically:
+
+- Build the package
+- Publish to NPM

package/dist/cache/token-cache.d.ts

@@ -0,0 +1,15 @@
+import type { TokenResult } from "../types.js";
+export declare class TokenCache {
+    private keycloakToken;
+    private rptTokens;
+    private isTokenValid;
+    setKeycloakToken(token: TokenResult): void;
+    getKeycloakToken(bufferSeconds: number): TokenResult | null;
+    clearKeycloakToken(): void;
+    setRptToken(key: string, token: TokenResult): void;
+    getRptToken(key: string, bufferSeconds: number): TokenResult | null;
+    clearRptToken(key: string): void;
+    clearAllRptTokens(): void;
+    clearAll(): void;
+}
+//# sourceMappingURL=token-cache.d.ts.map

package/dist/cache/token-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.d.ts","sourceRoot":"","sources":["../../src/cache/token-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,qBAAa,UAAU;IACrB,OAAO,CAAC,aAAa,CAA2B;IAChD,OAAO,CAAC,SAAS,CAAiC;IAElD,OAAO,CAAC,YAAY;IAKpB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAI1C,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAU3D,kBAAkB,IAAI,IAAI;IAI1B,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAIlD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAWnE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,iBAAiB,IAAI,IAAI;IAIzB,QAAQ,IAAI,IAAI;CAIjB"}

package/dist/cache/token-cache.js

@@ -0,0 +1,48 @@
+export class TokenCache {
+    constructor() {
+        this.keycloakToken = null;
+        this.rptTokens = new Map();
+    }
+    isTokenValid(token, bufferSeconds) {
+        const bufferMs = bufferSeconds * 1000;
+        return Date.now() < token.expiresAt.getTime() - bufferMs;
+    }
+    setKeycloakToken(token) {
+        this.keycloakToken = token;
+    }
+    getKeycloakToken(bufferSeconds) {
+        if (!this.keycloakToken) {
+            return null;
+        }
+        if (!this.isTokenValid(this.keycloakToken, bufferSeconds)) {
+            return null;
+        }
+        return this.keycloakToken;
+    }
+    clearKeycloakToken() {
+        this.keycloakToken = null;
+    }
+    setRptToken(key, token) {
+        this.rptTokens.set(key, token);
+    }
+    getRptToken(key, bufferSeconds) {
+        const token = this.rptTokens.get(key);
+        if (!token) {
+            return null;
+        }
+        if (!this.isTokenValid(token, bufferSeconds)) {
+            return null;
+        }
+        return token;
+    }
+    clearRptToken(key) {
+        this.rptTokens.delete(key);
+    }
+    clearAllRptTokens() {
+        this.rptTokens.clear();
+    }
+    clearAll() {
+        this.keycloakToken = null;
+        this.rptTokens.clear();
+    }
+}

package/dist/clients/access-api-client.d.ts

@@ -0,0 +1,18 @@
+import type { Logger, RptRequestOptions, TokenResult } from "../types.js";
+export interface AccessApiClientConfig {
+    baseUrl: string;
+    logger?: Logger | undefined;
+}
+export interface ExchangeOptions extends RptRequestOptions {
+    keycloakJwt?: string | undefined;
+    apiToken?: string | undefined;
+}
+export declare class AccessApiClient {
+    private readonly config;
+    constructor(config: AccessApiClientConfig);
+    exchangeForRpt(options: ExchangeOptions): Promise<TokenResult>;
+    getRptFromKeycloakToken(keycloakToken: string, options?: RptRequestOptions): Promise<TokenResult>;
+    private doRequest;
+    private mapStatusToErrorCode;
+}
+//# sourceMappingURL=access-api-client.d.ts.map

package/dist/clients/access-api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-api-client.d.ts","sourceRoot":"","sources":["../../src/clients/access-api-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGzE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;gBAElC,MAAM,EAAE,qBAAqB;IAInC,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAqC9D,uBAAuB,CAC3B,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,WAAW,CAAC;YAyBT,SAAS;IAiEvB,OAAO,CAAC,oBAAoB;CAa7B"}

package/dist/clients/access-api-client.js

@@ -0,0 +1,108 @@
+import { AuthNZError, ErrorCode } from "../errors.js";
+import { getTokenExpiry } from "../utils/jwt.js";
+export class AccessApiClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async exchangeForRpt(options) {
+        if (!options.keycloakJwt && !options.apiToken) {
+            throw new AuthNZError(ErrorCode.INVALID_CONFIG, "Either keycloakJwt or apiToken must be provided");
+        }
+        const body = new URLSearchParams();
+        if (options.keycloakJwt) {
+            body.append("jwt_keycloak_token", options.keycloakJwt);
+        }
+        else if (options.apiToken) {
+            body.append("api_token", options.apiToken);
+        }
+        if (options.permissions) {
+            for (const perm of options.permissions) {
+                body.append("permission", perm);
+            }
+        }
+        if (options.audience) {
+            for (const aud of options.audience) {
+                body.append("audience", aud);
+            }
+        }
+        return this.doRequest(`${this.config.baseUrl}/exchange`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: body.toString(),
+        });
+    }
+    async getRptFromKeycloakToken(keycloakToken, options) {
+        const body = new URLSearchParams();
+        if (options === null || options === void 0 ? void 0 : options.permissions) {
+            for (const perm of options.permissions) {
+                body.append("permission", perm);
+            }
+        }
+        if (options === null || options === void 0 ? void 0 : options.audience) {
+            for (const aud of options.audience) {
+                body.append("audience", aud);
+            }
+        }
+        return this.doRequest(`${this.config.baseUrl}/token`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Authorization: `Bearer ${keycloakToken}`,
+            },
+            body: body.toString(),
+        });
+    }
+    async doRequest(url, init) {
+        var _a, _b, _c, _d, _e;
+        (_a = this.config.logger) === null || _a === void 0 ? void 0 : _a.debug("Calling Access API", { url });
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (error) {
+            (_b = this.config.logger) === null || _b === void 0 ? void 0 : _b.error("Access API unreachable", {
+                url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw new AuthNZError(ErrorCode.ACCESS_API_UNREACHABLE, "Failed to reach Access API", {
+                cause: error instanceof Error ? error : new Error(String(error)),
+                context: { url },
+            });
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            (_c = this.config.logger) === null || _c === void 0 ? void 0 : _c.error("Access API request failed", {
+                url,
+                status: response.status,
+                error: errorText,
+            });
+            const errorCode = this.mapStatusToErrorCode(response.status);
+            throw new AuthNZError(errorCode, `Access API returned ${response.status}: ${errorText}`, { context: { url, status: response.status } });
+        }
+        const data = (await response.json());
+        const expiresAt = (_d = getTokenExpiry(data.access_token)) !== null && _d !== void 0 ? _d : new Date(Date.now() + data.expires_in * 1000);
+        (_e = this.config.logger) === null || _e === void 0 ? void 0 : _e.info("Access API token obtained", {
+            expiresIn: data.expires_in,
+        });
+        return {
+            accessToken: data.access_token,
+            expiresAt,
+            expiresIn: data.expires_in,
+        };
+    }
+    mapStatusToErrorCode(status) {
+        switch (status) {
+            case 400:
+            case 401:
+                return ErrorCode.ACCESS_API_INVALID_TOKEN;
+            case 404:
+                return ErrorCode.ACCESS_API_USER_NOT_FOUND;
+            case 422:
+                return ErrorCode.ACCESS_API_VALIDATION_ERROR;
+            default:
+                return ErrorCode.ACCESS_API_UNREACHABLE;
+        }
+    }
+}

package/dist/clients/keycloak-client.d.ts

@@ -0,0 +1,15 @@
+import type { Logger, TokenResult } from "../types.js";
+export interface KeycloakClientConfig {
+    baseUrl: string;
+    realm: string;
+    clientId: string;
+    clientSecret: string;
+    logger?: Logger | undefined;
+}
+export declare class KeycloakClient {
+    private readonly kcClient;
+    private readonly config;
+    constructor(config: KeycloakClientConfig);
+    getToken(): Promise<TokenResult>;
+}
+//# sourceMappingURL=keycloak-client.d.ts.map

package/dist/clients/keycloak-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak-client.d.ts","sourceRoot":"","sources":["../../src/clients/keycloak-client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGtD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAEjC,MAAM,EAAE,oBAAoB;IAQlC,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;CAgEvC"}

package/dist/clients/keycloak-client.js

@@ -0,0 +1,60 @@
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import { AuthNZError, ErrorCode } from "../errors.js";
+import { getTokenExpiry } from "../utils/jwt.js";
+const DEFAULT_TOKEN_LIFETIME_SECONDS = 300;
+export class KeycloakClient {
+    constructor(config) {
+        this.config = config;
+        this.kcClient = new KcAdminClient({
+            baseUrl: config.baseUrl,
+            realmName: config.realm,
+        });
+    }
+    async getToken() {
+        var _a, _b, _c, _d;
+        const credentials = {
+            grantType: "client_credentials",
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+        };
+        try {
+            (_a = this.config.logger) === null || _a === void 0 ? void 0 : _a.debug("Authenticating with Keycloak", {
+                baseUrl: this.config.baseUrl,
+                realm: this.config.realm,
+                clientId: this.config.clientId,
+            });
+            await this.kcClient.auth(credentials);
+            const accessToken = await this.kcClient.getAccessToken();
+            if (!accessToken) {
+                throw new AuthNZError(ErrorCode.KEYCLOAK_AUTH_FAILED, "No access token returned from Keycloak");
+            }
+            const expiresAt = (_b = getTokenExpiry(accessToken)) !== null && _b !== void 0 ? _b : new Date(Date.now() + DEFAULT_TOKEN_LIFETIME_SECONDS * 1000);
+            const expiresIn = Math.floor((expiresAt.getTime() - Date.now()) / 1000);
+            (_c = this.config.logger) === null || _c === void 0 ? void 0 : _c.info("Keycloak token obtained", {
+                expiresIn,
+                expiresAt: expiresAt.toISOString(),
+            });
+            return {
+                accessToken,
+                expiresAt,
+                expiresIn,
+            };
+        }
+        catch (error) {
+            if (error instanceof AuthNZError) {
+                throw error;
+            }
+            (_d = this.config.logger) === null || _d === void 0 ? void 0 : _d.error("Keycloak authentication failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw new AuthNZError(ErrorCode.KEYCLOAK_AUTH_FAILED, "Failed to authenticate with Keycloak", {
+                cause: error instanceof Error ? error : new Error(String(error)),
+                context: {
+                    baseUrl: this.config.baseUrl,
+                    realm: this.config.realm,
+                    clientId: this.config.clientId,
+                },
+            });
+        }
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+import type { Environment, Region } from "./types.js";
+export declare const KEYCLOAK_URLS: Record<Environment, Record<Region, string>>;
+export declare const ACCESS_API_URLS: Record<Environment, Record<Region, string>>;
+export declare const REALMS: Record<Environment, string>;
+export declare const TOKEN_REFRESH_BUFFER_SECONDS = 15;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAErD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASrE,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAG9C,CAAA;AAED,eAAO,MAAM,4BAA4B,KAAK,CAAA"}

package/dist/constants.js

@@ -0,0 +1,25 @@
+export const KEYCLOAK_URLS = {
+    staging: {
+        "europe-west1": "https://staging.auth.europe-west1.storyteq.work",
+        "us-east4": "https://staging.auth.us-east4.storyteq.work",
+    },
+    production: {
+        "europe-west1": "https://auth.storyteq.com",
+        "us-east4": "https://auth.us-east4.storyteq.com",
+    },
+};
+export const ACCESS_API_URLS = {
+    staging: {
+        "europe-west1": "https://access.storyteq.work",
+        "us-east4": "https://access.us-east4.storyteq.work",
+    },
+    production: {
+        "europe-west1": "https://access.storyteq.com",
+        "us-east4": "https://access.us-east4.storyteq.com",
+    },
+};
+export const REALMS = {
+    staging: "storyteq.work",
+    production: "storyteq.com",
+};
+export const TOKEN_REFRESH_BUFFER_SECONDS = 15;

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+export declare enum ErrorCode {
+    KEYCLOAK_AUTH_FAILED = "KEYCLOAK_AUTH_FAILED",
+    KEYCLOAK_UNREACHABLE = "KEYCLOAK_UNREACHABLE",
+    ACCESS_API_UNREACHABLE = "ACCESS_API_UNREACHABLE",
+    ACCESS_API_INVALID_TOKEN = "ACCESS_API_INVALID_TOKEN",
+    ACCESS_API_USER_NOT_FOUND = "ACCESS_API_USER_NOT_FOUND",
+    ACCESS_API_VALIDATION_ERROR = "ACCESS_API_VALIDATION_ERROR",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    TOKEN_REFRESH_FAILED = "TOKEN_REFRESH_FAILED"
+}
+export interface AuthNZErrorOptions {
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+export declare class AuthNZError extends Error {
+    readonly code: ErrorCode;
+    readonly context: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, options?: AuthNZErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,oBAAoB,yBAAyB;IAC7C,oBAAoB,yBAAyB;IAC7C,sBAAsB,2BAA2B;IACjD,wBAAwB,6BAA6B;IACrD,yBAAyB,8BAA8B;IACvD,2BAA2B,gCAAgC;IAC3D,cAAc,mBAAmB;IACjC,oBAAoB,yBAAyB;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAEzC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB;CAM3E"}

package/dist/errors.js

@@ -0,0 +1,19 @@
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["KEYCLOAK_AUTH_FAILED"] = "KEYCLOAK_AUTH_FAILED";
+    ErrorCode["KEYCLOAK_UNREACHABLE"] = "KEYCLOAK_UNREACHABLE";
+    ErrorCode["ACCESS_API_UNREACHABLE"] = "ACCESS_API_UNREACHABLE";
+    ErrorCode["ACCESS_API_INVALID_TOKEN"] = "ACCESS_API_INVALID_TOKEN";
+    ErrorCode["ACCESS_API_USER_NOT_FOUND"] = "ACCESS_API_USER_NOT_FOUND";
+    ErrorCode["ACCESS_API_VALIDATION_ERROR"] = "ACCESS_API_VALIDATION_ERROR";
+    ErrorCode["INVALID_CONFIG"] = "INVALID_CONFIG";
+    ErrorCode["TOKEN_REFRESH_FAILED"] = "TOKEN_REFRESH_FAILED";
+})(ErrorCode || (ErrorCode = {}));
+export class AuthNZError extends Error {
+    constructor(code, message, options) {
+        super(message, { cause: options === null || options === void 0 ? void 0 : options.cause });
+        this.name = "AuthNZError";
+        this.code = code;
+        this.context = options === null || options === void 0 ? void 0 : options.context;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const VERSION = "1.0.0";
+export type { Environment, Logger, Region, RptRequestOptions, ServiceTokenProvider, ServiceTokenProviderConfig, TokenResult, UserTokenExchangeOptions, UserTokenProvider, UserTokenProviderConfig, } from "./types.js";
+export { ACCESS_API_URLS, KEYCLOAK_URLS, REALMS, TOKEN_REFRESH_BUFFER_SECONDS, } from "./constants.js";
+export type { AuthNZErrorOptions } from "./errors.js";
+export { AuthNZError, ErrorCode } from "./errors.js";
+export { createServiceTokenProvider } from "./providers/service-token-provider.js";
+export { createUserTokenProvider } from "./providers/user-token-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,UAAU,CAAA;AAG9B,YAAY,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,WAAW,EACX,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,eAAe,EACf,aAAa,EACb,MAAM,EACN,4BAA4B,GAC7B,MAAM,gBAAgB,CAAA;AAGvB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAA;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @storyteq/authnz-sdk
+// Unified authentication and authorization SDK
+export const VERSION = "1.0.0";
+// Constants
+export { ACCESS_API_URLS, KEYCLOAK_URLS, REALMS, TOKEN_REFRESH_BUFFER_SECONDS, } from "./constants.js";
+export { AuthNZError, ErrorCode } from "./errors.js";
+// Providers
+export { createServiceTokenProvider } from "./providers/service-token-provider.js";
+export { createUserTokenProvider } from "./providers/user-token-provider.js";

package/dist/providers/service-token-provider.d.ts

@@ -0,0 +1,3 @@
+import type { ServiceTokenProvider, ServiceTokenProviderConfig } from "../types.js";
+export declare function createServiceTokenProvider(config: ServiceTokenProviderConfig): ServiceTokenProvider;
+//# sourceMappingURL=service-token-provider.d.ts.map

package/dist/providers/service-token-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-token-provider.d.ts","sourceRoot":"","sources":["../../src/providers/service-token-provider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,oBAAoB,EACpB,0BAA0B,EAE3B,MAAM,aAAa,CAAA;AAGpB,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CA6EtB"}

package/dist/providers/service-token-provider.js

@@ -0,0 +1,64 @@
+import { TokenCache } from "../cache/token-cache.js";
+import { AccessApiClient } from "../clients/access-api-client.js";
+import { KeycloakClient } from "../clients/keycloak-client.js";
+import { TOKEN_REFRESH_BUFFER_SECONDS } from "../constants.js";
+import { AuthNZError, ErrorCode } from "../errors.js";
+import { generateCacheKey } from "../utils/hash.js";
+export function createServiceTokenProvider(config) {
+    const keycloakClient = new KeycloakClient({
+        baseUrl: config.keycloakBaseUrl,
+        realm: config.keycloakRealm,
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        logger: config.logger,
+    });
+    const accessApiClient = new AccessApiClient({
+        baseUrl: config.accessApiBaseUrl,
+        logger: config.logger,
+    });
+    const cache = new TokenCache();
+    async function keycloak() {
+        var _a, _b;
+        const cached = cache.getKeycloakToken(TOKEN_REFRESH_BUFFER_SECONDS);
+        if (cached) {
+            (_a = config.logger) === null || _a === void 0 ? void 0 : _a.debug("Using cached Keycloak token");
+            return cached;
+        }
+        (_b = config.logger) === null || _b === void 0 ? void 0 : _b.debug("Fetching new Keycloak token");
+        const token = await keycloakClient.getToken();
+        cache.setKeycloakToken(token);
+        return token;
+    }
+    async function rpt(options) {
+        var _a, _b, _c, _d;
+        const permissions = (_a = options === null || options === void 0 ? void 0 : options.permissions) !== null && _a !== void 0 ? _a : config.defaultPermissions;
+        const audience = (_b = options === null || options === void 0 ? void 0 : options.audience) !== null && _b !== void 0 ? _b : config.defaultAudience;
+        const cacheKey = generateCacheKey(permissions, audience);
+        const cachedRpt = cache.getRptToken(cacheKey, TOKEN_REFRESH_BUFFER_SECONDS);
+        if (cachedRpt) {
+            (_c = config.logger) === null || _c === void 0 ? void 0 : _c.debug("Using cached RPT token", { cacheKey });
+            return cachedRpt;
+        }
+        const kcToken = await keycloak();
+        try {
+            const rptToken = await accessApiClient.getRptFromKeycloakToken(kcToken.accessToken, { permissions, audience });
+            cache.setRptToken(cacheKey, rptToken);
+            return rptToken;
+        }
+        catch (error) {
+            // Retry on 401 with fresh keycloak token
+            if (error instanceof AuthNZError &&
+                error.code === ErrorCode.ACCESS_API_INVALID_TOKEN) {
+                (_d = config.logger) === null || _d === void 0 ? void 0 : _d.info("RPT request failed with 401, retrying with fresh Keycloak token");
+                cache.clearKeycloakToken();
+                const freshKcToken = await keycloakClient.getToken();
+                cache.setKeycloakToken(freshKcToken);
+                const rptToken = await accessApiClient.getRptFromKeycloakToken(freshKcToken.accessToken, { permissions, audience });
+                cache.setRptToken(cacheKey, rptToken);
+                return rptToken;
+            }
+            throw error;
+        }
+    }
+    return { keycloak, rpt };
+}

package/dist/providers/user-token-provider.d.ts

@@ -0,0 +1,3 @@
+import type { UserTokenProvider, UserTokenProviderConfig } from "../types.js";
+export declare function createUserTokenProvider(config: UserTokenProviderConfig): UserTokenProvider;
+//# sourceMappingURL=user-token-provider.d.ts.map

package/dist/providers/user-token-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-token-provider.d.ts","sourceRoot":"","sources":["../../src/providers/user-token-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,aAAa,CAAA;AAEpB,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,iBAAiB,CAuBnB"}

package/dist/providers/user-token-provider.js

@@ -0,0 +1,23 @@
+import { AccessApiClient } from "../clients/access-api-client.js";
+export function createUserTokenProvider(config) {
+    const accessApiClient = new AccessApiClient({
+        baseUrl: config.accessApiBaseUrl,
+        logger: config.logger,
+    });
+    async function rpt(options) {
+        var _a;
+        (_a = config.logger) === null || _a === void 0 ? void 0 : _a.debug("Exchanging user token for RPT", {
+            hasKeycloakJwt: !!options.keycloakJwt,
+            hasApiToken: !!options.apiToken,
+            permissions: options.permissions,
+            audience: options.audience,
+        });
+        return accessApiClient.exchangeForRpt({
+            keycloakJwt: options.keycloakJwt,
+            apiToken: options.apiToken,
+            permissions: options.permissions,
+            audience: options.audience,
+        });
+    }
+    return { rpt };
+}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export type Environment = "staging" | "production";
+export type Region = "europe-west1" | "us-east4";
+export interface TokenResult {
+    accessToken: string;
+    expiresAt: Date;
+    expiresIn: number;
+}
+export interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+export interface ServiceTokenProviderConfig {
+    keycloakBaseUrl: string;
+    keycloakRealm: string;
+    accessApiBaseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    defaultPermissions?: string[] | undefined;
+    defaultAudience?: string[] | undefined;
+    logger?: Logger | undefined;
+}
+export interface UserTokenProviderConfig {
+    accessApiBaseUrl: string;
+    logger?: Logger | undefined;
+}
+export interface RptRequestOptions {
+    permissions?: string[] | undefined;
+    audience?: string[] | undefined;
+}
+export interface UserTokenExchangeOptions extends RptRequestOptions {
+    keycloakJwt?: string | undefined;
+    apiToken?: string | undefined;
+}
+export interface ServiceTokenProvider {
+    keycloak(): Promise<TokenResult>;
+    rpt(options?: RptRequestOptions): Promise<TokenResult>;
+}
+export interface UserTokenProvider {
+    rpt(options: UserTokenExchangeOptions): Promise<TokenResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,YAAY,CAAA;AAClD,MAAM,MAAM,MAAM,GAAG,cAAc,GAAG,UAAU,CAAA;AAEhD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAChE;AAED,MAAM,WAAW,0BAA0B;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAChC;AAED,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAChC,GAAG,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACvD;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAC7D"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function generateCacheKey(permissions?: string[], audience?: string[]): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAC9B,WAAW,CAAC,EAAE,MAAM,EAAE,EACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,CAQR"}

package/dist/utils/hash.js

@@ -0,0 +1,8 @@
+export function generateCacheKey(permissions, audience) {
+    const sortedPermissions = [...(permissions !== null && permissions !== void 0 ? permissions : [])].sort();
+    const sortedAudience = [...(audience !== null && audience !== void 0 ? audience : [])].sort();
+    return JSON.stringify({
+        permissions: sortedPermissions,
+        audience: sortedAudience,
+    });
+}

package/dist/utils/jwt.d.ts

@@ -0,0 +1,11 @@
+interface TokenPayload {
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    [key: string]: unknown;
+}
+export declare function decodeToken(token: string): TokenPayload | null;
+export declare function getTokenExpiry(token: string): Date | null;
+export declare function isTokenExpired(token: string, bufferSeconds: number): boolean;
+export {};
+//# sourceMappingURL=jwt.d.ts.map

package/dist/utils/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/utils/jwt.ts"],"names":[],"mappings":"AAEA,UAAU,YAAY;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAO9D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMzD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAO5E"}

package/dist/utils/jwt.js

@@ -0,0 +1,25 @@
+import jwt from "jsonwebtoken";
+export function decodeToken(token) {
+    try {
+        const decoded = jwt.decode(token, { json: true });
+        return decoded;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+export function getTokenExpiry(token) {
+    const decoded = decodeToken(token);
+    if (!(decoded === null || decoded === void 0 ? void 0 : decoded.exp)) {
+        return null;
+    }
+    return new Date(decoded.exp * 1000);
+}
+export function isTokenExpired(token, bufferSeconds) {
+    const expiry = getTokenExpiry(token);
+    if (!expiry) {
+        return true;
+    }
+    const bufferMs = bufferSeconds * 1000;
+    return Date.now() >= expiry.getTime() - bufferMs;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@storyteq/authnz-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Backend SDK for Keycloak authentication and Access API authorization",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": "^18.0.0 || ^22.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@keycloak/keycloak-admin-client": ">=26.0.0"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@keycloak/keycloak-admin-client": "^26.0.7",
+    "@tsconfig/node-lts": "^22.0.1",
+    "@tsconfig/strictest": "^2.0.5",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/node": "^22.15.21",
+    "eslint": "^9.21.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.26.0",
+    "vitest": "^3.1.4",
+    "@storyteq/prettier-config": "1.0.0"
+  },
+  "prettier": "@storyteq/prettier-config",
+  "scripts": {
+    "build": "tsc -p ./tsconfig.dist.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write ."
+  }
+}