@mastra/auth-cloud 0.0.1 → 1.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# @mastra/auth-cloud
+
+## 1.1.0-alpha.0
+
+### Minor Changes
+
+- Added `@mastra/auth-cloud` — a new auth provider for Mastra Cloud with PKCE OAuth flow, session management, and role-based access control. ([#13163](https://github.com/mastra-ai/mastra/pull/13163))
+
+  ```ts
+  import { MastraCloudAuthProvider, MastraRBACCloud } from '@mastra/auth-cloud';
+
+  const mastra = new Mastra({
+    server: {
+      auth: new MastraCloudAuthProvider({
+        appId: process.env.MASTRA_APP_ID!,
+        apiKey: process.env.MASTRA_API_KEY!,
+      }),
+      rbac: new MastraRBACCloud({
+        appId: process.env.MASTRA_APP_ID!,
+        apiKey: process.env.MASTRA_API_KEY!,
+      }),
+    },
+  });
+  ```
+
+  Handles the full OAuth lifecycle including login URL generation, PKCE challenge/verification, callback handling, and session cookie management.
+
+### Patch Changes
+
+- Updated dependencies [[`504fc8b`](https://github.com/mastra-ai/mastra/commit/504fc8b9d0ddab717577ad3bf9c95ea4bd5377bd), [`f9c150b`](https://github.com/mastra-ai/mastra/commit/f9c150b7595ad05ad9cc9a11098e2944361e8c22), [`88de7e8`](https://github.com/mastra-ai/mastra/commit/88de7e8dfe4b7e1951a9e441bb33136e705ce24e), [`edee4b3`](https://github.com/mastra-ai/mastra/commit/edee4b37dff0af515fc7cc0e8d71ee39e6a762f0), [`3790c75`](https://github.com/mastra-ai/mastra/commit/3790c7578cc6a47d854eb12d89e6b1912867fe29), [`e7a235b`](https://github.com/mastra-ai/mastra/commit/e7a235be6472e0c870ed6c791ddb17c492dc188b), [`d51d298`](https://github.com/mastra-ai/mastra/commit/d51d298953967aab1f58ec965b644d109214f085), [`6dbeeb9`](https://github.com/mastra-ai/mastra/commit/6dbeeb94a8b1eebb727300d1a98961f882180794), [`d5f0d8d`](https://github.com/mastra-ai/mastra/commit/d5f0d8d6a03e515ddaa9b5da19b7e44b8357b07b), [`09c3b18`](https://github.com/mastra-ai/mastra/commit/09c3b1802ff14e243a8a8baea327440bc8cc2e32), [`b896379`](https://github.com/mastra-ai/mastra/commit/b8963791c6afa79484645fcec596a201f936b9a2), [`85c84eb`](https://github.com/mastra-ai/mastra/commit/85c84ebb78aebfcba9d209c8e152b16d7a00cb71), [`a89272a`](https://github.com/mastra-ai/mastra/commit/a89272a5d71939b9fcd284e6a6dc1dd091a6bdcf), [`ee9c8df`](https://github.com/mastra-ai/mastra/commit/ee9c8df644f19d055af5f496bf4942705f5a47b7), [`77b4a25`](https://github.com/mastra-ai/mastra/commit/77b4a254e51907f8ff3a3ba95596a18e93ae4b35), [`276246e`](https://github.com/mastra-ai/mastra/commit/276246e0b9066a1ea48bbc70df84dbe528daaf99), [`08ecfdb`](https://github.com/mastra-ai/mastra/commit/08ecfdbdad6fb8285deef86a034bdf4a6047cfca), [`d5f628c`](https://github.com/mastra-ai/mastra/commit/d5f628ca86c6f6f3ff1035d52f635df32dd81cab), [`524c0f3`](https://github.com/mastra-ai/mastra/commit/524c0f3c434c3d9d18f66338dcef383d6161b59c), [`c18a0e9`](https://github.com/mastra-ai/mastra/commit/c18a0e9cef1e4ca004b2963d35e4cfc031971eac), [`4bd21ea`](https://github.com/mastra-ai/mastra/commit/4bd21ea43d44d0a0427414fc047577f9f0aa3bec), [`115a7a4`](https://github.com/mastra-ai/mastra/commit/115a7a47db5e9896fec12ae6507501adb9ec89bf), [`22a48ae`](https://github.com/mastra-ai/mastra/commit/22a48ae2513eb54d8d79dad361fddbca97a155e8), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9311c17`](https://github.com/mastra-ai/mastra/commit/9311c17d7a0640d9c4da2e71b814dc67c57c6369), [`7edf78f`](https://github.com/mastra-ai/mastra/commit/7edf78f80422c43e84585f08ba11df0d4d0b73c5), [`1c4221c`](https://github.com/mastra-ai/mastra/commit/1c4221cf6032ec98d0e094d4ee11da3e48490d96), [`d25b9ea`](https://github.com/mastra-ai/mastra/commit/d25b9eabd400167255a97b690ffbc4ee4097ded5), [`fe1ce5c`](https://github.com/mastra-ai/mastra/commit/fe1ce5c9211c03d561606fda95cbfe7df1d9a9b5), [`b03c0e0`](https://github.com/mastra-ai/mastra/commit/b03c0e0389a799523929a458b0509c9e4244d562), [`0a8366b`](https://github.com/mastra-ai/mastra/commit/0a8366b0a692fcdde56c4d526e4cf03c502ae4ac), [`85664e9`](https://github.com/mastra-ai/mastra/commit/85664e9fd857320fbc245e301f764f45f66f32a3), [`bc79650`](https://github.com/mastra-ai/mastra/commit/bc796500c6e0334faa158a96077e3fb332274869), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`3a3a59e`](https://github.com/mastra-ai/mastra/commit/3a3a59e8ffaa6a985fe3d9a126a3f5ade11a6724), [`3108d4e`](https://github.com/mastra-ai/mastra/commit/3108d4e649c9fddbf03253a6feeb388a5fa9fa5a), [`0c33b2c`](https://github.com/mastra-ai/mastra/commit/0c33b2c9db537f815e1c59e2c898ffce2e395a79), [`191e5bd`](https://github.com/mastra-ai/mastra/commit/191e5bd29b82f5bda35243945790da7bc7b695c2), [`f77cd94`](https://github.com/mastra-ai/mastra/commit/f77cd94c44eabed490384e7d19232a865e13214c), [`e8135c7`](https://github.com/mastra-ai/mastra/commit/e8135c7e300dac5040670eec7eab896ac6092e30), [`daca48f`](https://github.com/mastra-ai/mastra/commit/daca48f0fb17b7ae0b62a2ac40cf0e491b2fd0b7), [`257d14f`](https://github.com/mastra-ai/mastra/commit/257d14faca5931f2e4186fc165b6f0b1f915deee), [`352f25d`](https://github.com/mastra-ai/mastra/commit/352f25da316b24cdd5b410fd8dddf6a8b763da2a), [`93477d0`](https://github.com/mastra-ai/mastra/commit/93477d0769b8a13ea5ed73d508d967fb23eaeed9), [`31c78b3`](https://github.com/mastra-ai/mastra/commit/31c78b3eb28f58a8017f1dcc795c33214d87feac), [`0bc0720`](https://github.com/mastra-ai/mastra/commit/0bc07201095791858087cc56f353fcd65e87ab54), [`36516ac`](https://github.com/mastra-ai/mastra/commit/36516aca1021cbeb42e74751b46a2614101f37c8), [`e947652`](https://github.com/mastra-ai/mastra/commit/e9476527fdecb4449e54570e80dfaf8466901254), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`ec248f6`](https://github.com/mastra-ai/mastra/commit/ec248f6b56e8a037c066c49b2178e2507471d988)]:
+  - @mastra/core@1.9.0-alpha.0
+  - @mastra/auth@1.0.0

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,67 @@
 # @mastra/auth-cloud
 
-Mastra Cloud Auth integration. Coming soon.
+Mastra Cloud authentication provider with PKCE OAuth flow.
+
+## Installation
+
+```bash
+pnpm add @mastra/auth-cloud
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { MastraCloudAuth } from '@mastra/auth-cloud';
+
+const auth = new MastraCloudAuth({
+  projectId: process.env.MASTRA_PROJECT_ID!,
+  // Optional: defaults to https://cloud.mastra.ai
+  baseUrl: process.env.MASTRA_CLOUD_URL,
+  // Optional: defaults to /auth/callback
+  redirectPath: '/auth/callback',
+});
+
+const mastra = new Mastra({
+  server: {
+    auth,
+  },
+});
+```
+
+## Configuration
+
+| Option         | Required | Default                   | Description                     |
+| -------------- | -------- | ------------------------- | ------------------------------- |
+| `projectId`    | Yes      | -                         | Project ID from cloud.mastra.ai |
+| `baseUrl`      | No       | `https://cloud.mastra.ai` | Mastra Cloud base URL           |
+| `redirectPath` | No       | `/auth/callback`          | OAuth callback path             |
+| `cookieName`   | No       | `mastra_session`          | Session cookie name             |
+
+## Authentication Flow
+
+This package implements PKCE OAuth flow with Mastra Cloud:
+
+1. User clicks login, redirected to Mastra Cloud with code challenge
+2. User authenticates via Mastra Cloud (GitHub OAuth)
+3. Mastra Cloud redirects back with authorization code
+4. Package exchanges code + verifier for session token
+5. Session token stored in HttpOnly cookie
+
+## API
+
+### `MastraCloudAuth`
+
+The main authentication provider class implementing `MastraAuthProvider`.
+
+### Methods
+
+- `getLoginUrl(state?)` - Get OAuth login URL with PKCE
+- `handleCallback(code, verifier)` - Exchange code for session
+- `verifyToken(token)` - Verify session and get user with role
+- `refreshSession(token)` - Refresh expiring session
+- `logout(token)` - Invalidate session
+
+## License
+
+Apache-2.0

package/dist/auth-provider.d.ts

@@ -0,0 +1,198 @@
+/**
+ * MastraCloudAuthProvider - Server integration for Mastra Cloud authentication.
+ *
+ * Extends MastraAuthProvider and implements ISSOProvider, ISessionProvider,
+ * and IUserProvider interfaces to integrate with Mastra server middleware.
+ *
+ * @packageDocumentation
+ */
+import type { IUserProvider, ISSOProvider, ISessionProvider, Session, SSOCallbackResult, SSOLoginConfig } from '@mastra/core/auth';
+import type { EEUser } from '@mastra/core/auth/ee';
+import type { MastraAuthProviderOptions } from '@mastra/core/server';
+import { MastraAuthProvider } from '@mastra/core/server';
+import type { HonoRequest } from 'hono';
+import type { CloudUser } from './types.js';
+/**
+ * Configuration options for MastraCloudAuthProvider.
+ */
+export interface MastraCloudAuthProviderOptions extends MastraAuthProviderOptions<CloudUser> {
+    /** Mastra Cloud project ID */
+    projectId: string;
+    /** Base URL of Mastra Cloud API (e.g., https://cloud.mastra.ai) */
+    cloudBaseUrl: string;
+    /** OAuth callback URL for your application */
+    callbackUrl: string;
+    /** Whether running in production (adds Secure flag to cookies) */
+    isProduction?: boolean;
+}
+/**
+ * Mastra Cloud authentication provider for server integration.
+ *
+ * Wraps the MastraCloudAuth client and implements the required interfaces
+ * for Mastra server middleware. Provides SSO login, session management,
+ * and user awareness.
+ *
+ * @example
+ * ```typescript
+ * import { MastraCloudAuthProvider } from '@mastra/auth-cloud';
+ *
+ * const auth = new MastraCloudAuthProvider({
+ *   cloudBaseUrl: 'https://cloud.mastra.ai',
+ *   callbackUrl: 'https://myapp.com/auth/callback',
+ * });
+ *
+ * const mastra = new Mastra({
+ *   auth,
+ *   // ...
+ * });
+ * ```
+ */
+export declare class MastraCloudAuthProvider extends MastraAuthProvider<CloudUser> implements IUserProvider<EEUser>, ISSOProvider<EEUser>, ISessionProvider<Session> {
+    private client;
+    /** Marker for EE license exemption - MastraCloudAuth is exempt */
+    readonly isMastraCloudAuth = true;
+    /**
+     * Cookie header for handleCallback PKCE validation.
+     * Set via setCallbackCookieHeader() before handleCallback() is called.
+     * @internal
+     */
+    private _lastCallbackCookieHeader;
+    constructor(options: MastraCloudAuthProviderOptions);
+    /**
+     * Set cookie header for handleCallback PKCE validation.
+     * Must be called before handleCallback() to pass cookie header.
+     *
+     * @param cookieHeader - Cookie header from original request
+     */
+    setCallbackCookieHeader(cookieHeader: string | null): void;
+    /**
+     * Authenticate a bearer token or session cookie.
+     *
+     * Checks session cookie first, falls back to bearer token for API clients.
+     *
+     * @param token - Bearer token (from Authorization header)
+     * @param request - Hono or raw Request
+     * @returns Authenticated user with role, or null if invalid
+     */
+    authenticateToken(token: string, request: HonoRequest | Request): Promise<CloudUser | null>;
+    /**
+     * Authorize a user for access.
+     *
+     * Simple validation - detailed permission checking happens in server
+     * middleware via checkRoutePermission(), not authorizeUser().
+     *
+     * @param user - Authenticated user
+     * @returns True if user has valid id
+     */
+    authorizeUser(user: CloudUser): boolean;
+    /**
+     * Cached login result for getLoginCookies() to retrieve cookies.
+     * @internal
+     */
+    private _lastLoginResult;
+    /**
+     * Get URL to redirect user to for SSO login.
+     *
+     * @param redirectUri - Callback URL after authentication
+     * @param state - State parameter (format: uuid|encodedPostLoginRedirect)
+     * @returns Full authorization URL
+     */
+    getLoginUrl(redirectUri: string, state: string): string;
+    /**
+     * Get cookies to set during login redirect (PKCE verifier).
+     * Must be called after getLoginUrl() in same request.
+     *
+     * @returns Array of Set-Cookie header values
+     */
+    getLoginCookies(): string[] | undefined;
+    /**
+     * Handle OAuth callback, exchange code for tokens and user.
+     *
+     * @param code - Authorization code from callback
+     * @param state - State parameter for CSRF validation
+     * @returns User, tokens, and session cookies
+     */
+    handleCallback(code: string, state: string): Promise<SSOCallbackResult<EEUser>>;
+    /**
+     * Get configuration for rendering login button in UI.
+     *
+     * @returns Login button configuration
+     */
+    getLoginButtonConfig(): SSOLoginConfig;
+    /**
+     * Get logout URL for client-side redirect.
+     * Requires the request to extract the session token for id_token_hint.
+     *
+     * @param redirectUri - URL to redirect to after logout
+     * @param request - Request to extract session token from
+     * @returns Logout URL with redirect and token parameters, or null if no session
+     */
+    getLogoutUrl(redirectUri: string, request?: Request): string | null;
+    /**
+     * Create a new session for a user.
+     *
+     * For Cloud auth, sessions are created via handleCallback.
+     * This method builds a Session object for interface compatibility.
+     *
+     * @param userId - User to create session for
+     * @param metadata - Optional metadata (accessToken can be passed here)
+     * @returns Session object
+     */
+    createSession(userId: string, metadata?: Record<string, unknown>): Promise<Session>;
+    /**
+     * Validate a session and return it if valid.
+     *
+     * @param sessionId - Session token to validate
+     * @returns Session object or null if invalid/expired
+     */
+    validateSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Destroy a session (logout).
+     *
+     * @param sessionId - Session token to destroy
+     */
+    destroySession(sessionId: string): Promise<void>;
+    /**
+     * Refresh a session, extending its expiry.
+     * Cloud handles refresh internally, so just validate.
+     *
+     * @param sessionId - Session token to refresh
+     * @returns Session object or null if invalid
+     */
+    refreshSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Extract session ID from an incoming request.
+     *
+     * @param request - Incoming HTTP request
+     * @returns Session token or null if not present
+     */
+    getSessionIdFromRequest(request: Request): string | null;
+    /**
+     * Create response headers to set session cookie.
+     *
+     * @param session - Session to encode (id is the access token)
+     * @returns Headers object with Set-Cookie
+     */
+    getSessionHeaders(session: Session): Record<string, string>;
+    /**
+     * Create response headers to clear session (for logout).
+     *
+     * @returns Headers object to clear session cookie
+     */
+    getClearSessionHeaders(): Record<string, string>;
+    /**
+     * Get current user from request (session cookie).
+     *
+     * @param request - Incoming HTTP request
+     * @returns User with role or null if not authenticated
+     */
+    getCurrentUser(request: Request): Promise<CloudUser | null>;
+    /**
+     * Get user by ID.
+     * Cloud API doesn't have a /users/:id endpoint.
+     *
+     * @returns Always null (not supported)
+     */
+    getUser(_userId: string): Promise<CloudUser | null>;
+}
+//# sourceMappingURL=auth-provider.d.ts.map

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

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

package/dist/client.d.ts

@@ -0,0 +1,110 @@
+/**
+ * MastraCloudAuth client class.
+ * Facade composing OAuth and session modules into unified API.
+ */
+import type { LoginUrlResult, CallbackResult, VerifyResponse, CloudSession } from './types.js';
+/**
+ * Configuration for MastraCloudAuth client.
+ */
+export interface MastraCloudAuthConfig {
+    /** Mastra Cloud project ID */
+    projectId: string;
+    /** Base URL of the Cloud API (e.g., https://cloud.mastra.ai) */
+    cloudBaseUrl: string;
+    /** OAuth callback URL for your application */
+    callbackUrl: string;
+    /** Whether running in production (adds Secure flag to cookies) */
+    isProduction?: boolean;
+}
+/**
+ * Mastra Cloud authentication client.
+ *
+ * Provides unified API for OAuth flow and session management.
+ *
+ * @example
+ * ```typescript
+ * const auth = new MastraCloudAuth({
+ *   cloudBaseUrl: 'https://cloud.mastra.ai',
+ *   callbackUrl: 'https://myapp.com/auth/callback',
+ * });
+ *
+ * // Start login flow
+ * const { url, cookies } = auth.getLoginUrl({
+ *   requestOrigin: 'https://myapp.com',
+ * });
+ *
+ * // After callback
+ * const result = await auth.handleCallback({
+ *   code: 'auth_code',
+ *   state: 'state_param',
+ *   cookieHeader: request.headers.get('cookie'),
+ * });
+ * ```
+ */
+export declare class MastraCloudAuth {
+    private readonly config;
+    constructor(config: MastraCloudAuthConfig);
+    /**
+     * Generate login URL for OAuth authorization.
+     *
+     * @param options - Login options
+     * @returns URL to redirect to and cookies to set
+     */
+    getLoginUrl(options: {
+        returnTo?: string;
+        requestOrigin: string;
+    }): LoginUrlResult;
+    /**
+     * Handle OAuth callback after authorization.
+     *
+     * @param options - Callback parameters
+     * @returns User info, tokens, and redirect URL
+     */
+    handleCallback(options: {
+        code: string;
+        state: string;
+        cookieHeader: string | null;
+    }): Promise<CallbackResult>;
+    /**
+     * Verify an access token.
+     *
+     * @param token - Access token to verify
+     * @returns User and role information
+     */
+    verifyToken(token: string): Promise<VerifyResponse>;
+    /**
+     * Validate an existing session.
+     *
+     * @param sessionToken - Session token to validate
+     * @returns Session data if valid, null otherwise
+     */
+    validateSession(sessionToken: string): Promise<CloudSession | null>;
+    /**
+     * Destroy a session (server-side logout).
+     *
+     * @param sessionToken - Session token to destroy
+     */
+    destroySession(sessionToken: string): Promise<void>;
+    /**
+     * Get the logout URL for client-side redirect.
+     *
+     * @param postLogoutRedirectUri - URL to redirect to after logout
+     * @param idTokenHint - The access token
+     * @returns Full logout URL with redirect and token parameters
+     */
+    getLogoutUrl(postLogoutRedirectUri: string, idTokenHint: string): string;
+    /**
+     * Create Set-Cookie header value for session token.
+     *
+     * @param token - Session token to store
+     * @returns Set-Cookie header value
+     */
+    setSessionCookie(token: string): string;
+    /**
+     * Create Set-Cookie header value to clear session cookie.
+     *
+     * @returns Set-Cookie header value
+     */
+    clearSessionCookie(): string;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5F;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAEnC,MAAM,EAAE,qBAAqB;IAIzC;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc;IAWlF;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAS9G;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAInD;;;;;OAKG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAInE;;;;OAIG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;;;;;OAMG;IACH,YAAY,CAAC,qBAAqB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAIxE;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIvC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;CAG7B"}

package/dist/error.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Auth error types and error class.
+ *
+ * Provides typed error handling for OAuth flow and session management.
+ */
+/**
+ * Error codes for authentication-related failures.
+ */
+export type AuthErrorCode = 'invalid_state' | 'state_mismatch' | 'missing_code' | 'token_exchange_failed' | 'verification_failed' | 'session_invalid' | 'session_expired' | 'network_error' | 'cloud_api_error';
+/**
+ * Options for AuthError constructor.
+ */
+export interface AuthErrorOptions {
+    cause?: Error;
+    cloudCode?: string;
+    cloudMessage?: string;
+}
+/**
+ * Error class for authentication-related failures.
+ * Uses a code discriminator for programmatic error handling.
+ */
+export declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly cause?: Error;
+    readonly cloudCode?: string;
+    readonly cloudMessage?: string;
+    constructor(code: AuthErrorCode, message: string, options?: AuthErrorOptions);
+    /**
+     * Factory: OAuth state parameter is invalid or malformed.
+     */
+    static invalidState(): AuthError;
+    /**
+     * Factory: OAuth state parameter does not match expected value.
+     */
+    static stateMismatch(): AuthError;
+    /**
+     * Factory: Authorization code is missing from callback.
+     */
+    static missingCode(): AuthError;
+    /**
+     * Factory: Token exchange with Cloud API failed.
+     */
+    static tokenExchangeFailed(options?: AuthErrorOptions): AuthError;
+    /**
+     * Factory: Token verification failed.
+     */
+    static verificationFailed(): AuthError;
+    /**
+     * Factory: Session is invalid.
+     */
+    static sessionInvalid(): AuthError;
+    /**
+     * Factory: Session has expired.
+     */
+    static sessionExpired(): AuthError;
+    /**
+     * Factory: Network error during API call.
+     */
+    static networkError(cause?: Error): AuthError;
+    /**
+     * Factory: Cloud API returned an error.
+     */
+    static cloudApiError(options?: AuthErrorOptions): AuthError;
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,uBAAuB,GACvB,qBAAqB,GACrB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,SAAkB,KAAK,CAAC,EAAE,KAAK,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAW5E;;OAEG;IACH,MAAM,CAAC,YAAY,IAAI,SAAS;IAIhC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,SAAS;IAIjC;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,SAAS;IAI/B;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS;IAIjE;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,SAAS;IAItC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,SAAS;IAIlC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,SAAS;IAIlC;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS;IAI7C;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS;CAI5D"}