@mastra/auth-supabase 1.1.6 → 1.2.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/_types/{@internal_auth/dist/_types/@internal_core → @internal_auth@0.0.36/dist/_types/@internal_core@0.1.4}/dist/base/index.d.ts +1 -1
  2. package/dist/_types/{@internal_auth/dist/_types/@internal_core/dist/index-TNVgGNjs.d.ts → @internal_auth@0.0.36/dist/_types/@internal_core@0.1.4/dist/index-Diz1p9N7.d.ts} +3 -2
  3. package/dist/_types/@internal_auth@0.0.36/dist/ee/capabilities.d.ts +142 -0
  4. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/index.d.ts +8 -0
  5. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/rbac/index.d.ts +7 -0
  6. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/rbac/static.d.ts +106 -0
  7. package/dist/_types/@internal_auth@0.0.36/dist/ee/defaults/roles.d.ts +92 -0
  8. package/dist/_types/@internal_auth@0.0.36/dist/ee/fga-check.d.ts +59 -0
  9. package/dist/_types/@internal_auth@0.0.36/dist/ee/index.d.ts +15 -0
  10. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/acl.d.ts +140 -0
  11. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/fga.d.ts +408 -0
  12. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/index.d.ts +15 -0
  13. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/permissions.generated.d.ts +551 -0
  14. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/rbac.d.ts +207 -0
  15. package/dist/_types/@internal_auth@0.0.36/dist/ee/interfaces/user.d.ts +18 -0
  16. package/dist/_types/@internal_auth@0.0.36/dist/ee/license.d.ts +171 -0
  17. package/dist/_types/@internal_auth@0.0.36/dist/index.d.ts +358 -0
  18. package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/dist/provider/index.d.ts +74 -2
  19. package/dist/_types/@internal_auth@0.0.36/dist/session/cookie.d.ts +82 -0
  20. package/dist/_types/@internal_auth@0.0.36/dist/session/index.d.ts +39 -0
  21. package/dist/_types/@internal_auth@0.0.36/dist/session/memory.d.ts +60 -0
  22. package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/dist/types/index.d.ts +7 -0
  23. package/dist/index.cjs +73 -0
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.ts +13 -2
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +73 -0
  28. package/dist/index.js.map +1 -1
  29. package/package.json +7 -7
  30. package/LICENSE.md +0 -32
  31. /package/dist/_types/{@internal_auth → @internal_auth@0.0.36}/package.json +0 -0
@@ -0,0 +1,358 @@
1
+ /**
2
+ * User provider interface for authentication.
3
+ * Enables user awareness in Studio.
4
+ */
5
+ /**
6
+ * Base user type for authentication.
7
+ */
8
+ export interface User {
9
+ /** Unique user identifier */
10
+ id: string;
11
+ /** User email address */
12
+ email?: string;
13
+ /** Display name */
14
+ name?: string;
15
+ /** Avatar URL */
16
+ avatarUrl?: string;
17
+ /**
18
+ * Primary role, when the auth provider or a configured RBAC provider
19
+ * supplies one. `undefined` means the auth setup has no role concept —
20
+ * not that the user lacks permissions.
21
+ */
22
+ role?: string;
23
+ }
24
+ /**
25
+ * Authenticated end user, normalized to a stable shape.
26
+ *
27
+ * Produced by `MastraAuthProvider.toMastraUser()` at authentication time and
28
+ * surfaced to `DynamicArgument` callbacks as the optional `user` argument.
29
+ * The raw provider-specific user object remains available on the request
30
+ * context under the `mastra__user` key.
31
+ */
32
+ export type MastraUser = User;
33
+ /**
34
+ * Provider interface for user awareness in Studio.
35
+ *
36
+ * Implement this interface to enable:
37
+ * - Current user display in header
38
+ * - User menu with profile info
39
+ * - User context in API calls
40
+ *
41
+ * @example
42
+ * ```typescript
43
+ * class MyUserProvider implements IUserProvider {
44
+ * async getCurrentUser(request: Request) {
45
+ * const session = await this.getSession(request);
46
+ * if (!session) return null;
47
+ * return this.db.getUser(session.userId);
48
+ * }
49
+ *
50
+ * async getUser(userId: string) {
51
+ * return this.db.getUser(userId);
52
+ * }
53
+ * }
54
+ * ```
55
+ */
56
+ export interface IUserProvider<TUser extends User = User> {
57
+ /**
58
+ * Get current user from request (session cookie, token, etc.)
59
+ *
60
+ * @param request - Incoming HTTP request
61
+ * @returns User object or null if not authenticated
62
+ */
63
+ getCurrentUser(request: Request): Promise<TUser | null>;
64
+ /**
65
+ * Get user by ID.
66
+ *
67
+ * @param userId - User identifier
68
+ * @returns User object or null if not found
69
+ */
70
+ getUser(userId: string): Promise<TUser | null>;
71
+ /**
72
+ * Optional: Get multiple users by ID.
73
+ * Implement for efficient batch loading in user enrichment flows.
74
+ *
75
+ * @param userIds - User identifiers
76
+ * @returns User objects for the requested IDs (null for missing users, order preserved)
77
+ */
78
+ getUsers?(userIds: string[]): Promise<Array<TUser | null>>;
79
+ /**
80
+ * Optional: Get URL to user's profile page.
81
+ *
82
+ * @param user - User object
83
+ * @returns URL string to profile
84
+ */
85
+ getUserProfileUrl?(user: TUser): string;
86
+ }
87
+ /**
88
+ * SSO provider interface for EE authentication.
89
+ * Enables single sign-on flows in Studio.
90
+ */
91
+ /**
92
+ * Configuration for rendering a login button.
93
+ */
94
+ export interface SSOLoginConfig {
95
+ /** Provider identifier (e.g., 'mastra', 'auth0', 'okta') */
96
+ provider: string;
97
+ /** Button text (e.g., 'Sign in with Mastra') */
98
+ text: string;
99
+ /** Optional icon URL */
100
+ icon?: string;
101
+ /** Optional description explaining the auth requirement and what credentials to use */
102
+ description?: string;
103
+ }
104
+ /**
105
+ * Result of an SSO callback exchange.
106
+ */
107
+ export interface SSOCallbackResult<TUser> {
108
+ /** Authenticated user */
109
+ user: TUser;
110
+ /** OAuth tokens */
111
+ tokens: {
112
+ /** Access token for API calls */
113
+ accessToken: string;
114
+ /** Refresh token for token renewal */
115
+ refreshToken?: string;
116
+ /** ID token with user claims */
117
+ idToken?: string;
118
+ /** Token expiration time */
119
+ expiresAt?: Date;
120
+ };
121
+ /**
122
+ * Session cookies to set in the response.
123
+ * Providers using encrypted cookie sessions (like AuthKit) should populate this.
124
+ */
125
+ cookies?: string[];
126
+ }
127
+ /**
128
+ * Provider interface for SSO authentication.
129
+ *
130
+ * Implement this interface to enable:
131
+ * - SSO login button in Studio
132
+ * - OAuth/OIDC redirect flows
133
+ * - Token exchange on callback
134
+ *
135
+ * @example
136
+ * ```typescript
137
+ * class Auth0SSOProvider implements ISSOProvider {
138
+ * getLoginUrl(redirectUri: string, state: string) {
139
+ * const params = new URLSearchParams({
140
+ * client_id: this.clientId,
141
+ * redirect_uri: redirectUri,
142
+ * response_type: 'code',
143
+ * scope: 'openid profile email',
144
+ * state,
145
+ * });
146
+ * return `https://${this.domain}/authorize?${params}`;
147
+ * }
148
+ *
149
+ * async handleCallback(code: string, state: string) {
150
+ * const tokens = await this.exchangeCode(code);
151
+ * const user = await this.getUserInfo(tokens.accessToken);
152
+ * return { user, tokens };
153
+ * }
154
+ *
155
+ * getLoginButtonConfig() {
156
+ * return { provider: 'auth0', text: 'Sign in with Auth0' };
157
+ * }
158
+ * }
159
+ * ```
160
+ */
161
+ export interface ISSOProvider<TUser = unknown> {
162
+ /**
163
+ * Get URL to redirect user to for login.
164
+ *
165
+ * @param redirectUri - Callback URL after authentication
166
+ * @param state - CSRF protection state parameter
167
+ * @returns Full URL to redirect user to
168
+ */
169
+ getLoginUrl(redirectUri: string, state: string): string | Promise<string>;
170
+ /**
171
+ * Handle OAuth callback, exchange code for tokens and user.
172
+ *
173
+ * @param code - Authorization code from callback
174
+ * @param state - State parameter for CSRF validation
175
+ * @returns User and tokens
176
+ */
177
+ handleCallback(code: string, state: string): Promise<SSOCallbackResult<TUser>>;
178
+ /**
179
+ * Optional: Get logout URL if provider supports it.
180
+ *
181
+ * @param redirectUri - URL to redirect to after logout
182
+ * @param request - Optional request to extract session info (e.g., for WorkOS sid)
183
+ * @returns Logout URL, null if no active session, or undefined if not implemented
184
+ */
185
+ getLogoutUrl?(redirectUri: string, request?: Request): string | null | Promise<string | null>;
186
+ /**
187
+ * Get configuration for rendering login button in UI.
188
+ *
189
+ * @returns Login button configuration
190
+ */
191
+ getLoginButtonConfig(): SSOLoginConfig;
192
+ /**
193
+ * Optional: Get cookies to set during login redirect.
194
+ * Used by PKCE-enabled providers to store code verifier.
195
+ *
196
+ * @param redirectUri - OAuth callback URL
197
+ * @param state - State parameter
198
+ * @returns Array of Set-Cookie header values, or undefined
199
+ */
200
+ getLoginCookies?(redirectUri: string, state: string): string[] | undefined;
201
+ }
202
+ /**
203
+ * Credentials provider interface for authentication.
204
+ * Enables email/password sign-in and sign-up in Studio.
205
+ */
206
+ /**
207
+ * Result of a successful credentials operation.
208
+ */
209
+ export interface CredentialsResult<TUser = User> {
210
+ /** The authenticated user */
211
+ user: TUser;
212
+ /** Optional session token */
213
+ token?: string;
214
+ /** Optional cookies to set on the response (e.g., session cookies) */
215
+ cookies?: string[];
216
+ }
217
+ /**
218
+ * Provider interface for credentials-based authentication in Studio.
219
+ *
220
+ * Implement this interface to enable:
221
+ * - Email/password sign-in
222
+ * - Email/password sign-up
223
+ * - Password reset (optional)
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * class MyCredentialsProvider implements ICredentialsProvider {
228
+ * async signIn(email: string, password: string, request: Request) {
229
+ * const user = await this.validateCredentials(email, password);
230
+ * if (!user) throw new Error('Invalid credentials');
231
+ * return { user };
232
+ * }
233
+ *
234
+ * async signUp(email: string, password: string, name: string | undefined, request: Request) {
235
+ * const user = await this.createUser({ email, password, name });
236
+ * return { user };
237
+ * }
238
+ * }
239
+ * ```
240
+ */
241
+ export interface ICredentialsProvider<TUser extends User = User> {
242
+ /**
243
+ * Sign in with email and password.
244
+ *
245
+ * @param email - User email
246
+ * @param password - User password
247
+ * @param request - Incoming HTTP request (for setting cookies, etc.)
248
+ * @returns Result with user and optional token
249
+ * @throws Error if credentials are invalid
250
+ */
251
+ signIn(email: string, password: string, request: Request): Promise<CredentialsResult<TUser>>;
252
+ /**
253
+ * Sign up with email and password.
254
+ *
255
+ * @param email - User email
256
+ * @param password - User password
257
+ * @param name - Optional display name
258
+ * @param request - Incoming HTTP request (for setting cookies, etc.)
259
+ * @returns Result with new user and optional token
260
+ * @throws Error if sign up fails (e.g., email already exists)
261
+ */
262
+ signUp(email: string, password: string, name: string | undefined, request: Request): Promise<CredentialsResult<TUser>>;
263
+ /**
264
+ * Optional: Request password reset.
265
+ *
266
+ * @param email - User email
267
+ * @returns Promise that resolves when reset email is sent
268
+ */
269
+ requestPasswordReset?(email: string): Promise<void>;
270
+ /**
271
+ * Optional: Reset password with token.
272
+ *
273
+ * @param token - Reset token from email
274
+ * @param newPassword - New password
275
+ * @returns Promise that resolves when password is reset
276
+ */
277
+ resetPassword?(token: string, newPassword: string): Promise<void>;
278
+ /**
279
+ * Optional: Check if sign-up is enabled.
280
+ * Defaults to true if not implemented.
281
+ *
282
+ * Use this to disable public registration while still allowing sign-in.
283
+ *
284
+ * @returns Whether sign-up is enabled
285
+ */
286
+ isSignUpEnabled?(): boolean;
287
+ }
288
+ /**
289
+ * Provider interface for organization membership management.
290
+ *
291
+ * Implement this interface to enable multi-tenant hosts (e.g. the Mastra Code
292
+ * web factory) to bootstrap a personal organization for new users and to
293
+ * authorize organization-level administrative mutations.
294
+ */
295
+ export interface IOrganizationsProvider {
296
+ /**
297
+ * Ensure the user belongs to an organization, bootstrapping a personal org
298
+ * on first use when they have none. Must be idempotent under
299
+ * concurrent/retried first logins.
300
+ *
301
+ * @param userId - Stable provider user id
302
+ * @returns The organization id, or `undefined` when the user genuinely
303
+ * stays no-org (bootstrap is best-effort)
304
+ */
305
+ ensureOrganization(userId: string): Promise<string | undefined>;
306
+ /**
307
+ * Whether the user holds an admin-equivalent role in the organization.
308
+ * Provider errors should resolve to `false` rather than throw.
309
+ *
310
+ * @param organizationId - Organization id
311
+ * @param userId - Stable provider user id
312
+ */
313
+ isOrganizationAdmin(organizationId: string, userId: string): Promise<boolean>;
314
+ }
315
+ /**
316
+ * Host-level context handed to {@link IAuthInit.init} once during server
317
+ * preparation. Storage-agnostic: hosts pass whatever database handle their
318
+ * storage backend exposes.
319
+ */
320
+ export interface AuthInitContext {
321
+ /**
322
+ * Database handle for providers that persist their own auth tables
323
+ * (e.g. better-auth). Shape is provider-defined; hosts pass their storage
324
+ * backend's auth database as-is.
325
+ */
326
+ database?: unknown;
327
+ /** Browser-facing origin (no trailing slash), e.g. `https://factory.acme.com`. */
328
+ publicUrl?: string;
329
+ /**
330
+ * Extra browser origins allowed to talk to the API (cross-origin SPA
331
+ * deploys). Providers that enforce their own origin allow-list (e.g.
332
+ * better-auth `trustedOrigins`) must honor these.
333
+ */
334
+ allowedOrigins?: string[];
335
+ }
336
+ /**
337
+ * Optional one-time initialization hook for auth providers. Hosts call
338
+ * `init()` once during preparation with host-level context (database, public
339
+ * origin) so providers can consume it without the deploy entry passing it
340
+ * twice. Providers should fail fast here for requirements only satisfiable at
341
+ * prepare time.
342
+ */
343
+ export interface IAuthInit {
344
+ init(ctx: AuthInitContext): Promise<void>;
345
+ }
346
+ /**
347
+ * Provider interface for handling raw auth HTTP requests. Providers that ship
348
+ * their own HTTP API surface (e.g. better-auth's `/api/auth/*` handler)
349
+ * implement this so hosts can mount it (typically under `/auth/api/*`).
350
+ */
351
+ export interface IAuthHttpHandler {
352
+ handleAuthRequest(request: Request): Promise<Response>;
353
+ }
354
+ export * from './session/index.js';
355
+ export * from './provider/index.js';
356
+ export * from './types/index.js';
357
+ export * from './ee/index.js';
358
+ //# sourceMappingURL=index.d.ts.map
@@ -1,6 +1,18 @@
1
- import { MastraBase } from '../_types/@internal_core/dist/base/index.js';
2
- import type { CredentialsResult, IAuthHttpHandler, IAuthInit, ICredentialsProvider, IOrganizationsProvider, ISSOProvider, ISessionProvider, IUserProvider, Session, SSOCallbackResult, SSOLoginConfig, User } from '..';
1
+ import { MastraBase } from '../_types/@internal_core@0.1.4/dist/base/index.js';
2
+ import type { CredentialsResult, IAuthHttpHandler, IAuthInit, ICredentialsProvider, IOrganizationsProvider, ISSOProvider, ISessionProvider, IUserProvider, MastraUser, Session, SSOCallbackResult, SSOLoginConfig, User } from '..';
3
3
  import type { AuthorizeUserFn, MastraAuthConfig, MastraAuthRequest } from '../types/index.js';
4
+ /**
5
+ * Normalize an arbitrary provider-specific user object to the stable
6
+ * {@link MastraUser} shape surfaced to `DynamicArgument` callbacks.
7
+ *
8
+ * Picks `id` from `id`/`sub`/`userId` (numeric ids are stringified),
9
+ * `avatarUrl` from `avatarUrl`/`picture`, and passes `name`/`email`/`role`
10
+ * through when they are non-empty strings.
11
+ *
12
+ * @throws when no id can be derived — override `toMastraUser()` on the auth
13
+ * provider for user shapes this default cannot handle.
14
+ */
15
+ export declare function normalizeMastraUser(user: unknown): MastraUser;
4
16
  export interface MastraAuthProviderOptions<TUser = unknown> {
5
17
  name?: string;
6
18
  authorizeUser?: AuthorizeUserFn<TUser>;
@@ -50,6 +62,11 @@ export interface IMastraAuthProvider<TUser = unknown> {
50
62
  * Map an authenticated user to a memory resource id
51
63
  */
52
64
  mapUserToResourceId?(user: TUser): string | undefined | null;
65
+ /**
66
+ * Normalize the authenticated provider-specific user to the stable
67
+ * `MastraUser` shape surfaced to `DynamicArgument` callbacks.
68
+ */
69
+ toMastraUser?(user: TUser): MastraUser;
53
70
  /**
54
71
  * Return response headers (typically `Set-Cookie` for a rotated session)
55
72
  * that the provider accumulated while handling this request and clear them
@@ -58,7 +75,32 @@ export interface IMastraAuthProvider<TUser = unknown> {
58
75
  * reach the browser.
59
76
  */
60
77
  consumePendingResponseHeaders?(request: MastraAuthRequest): Record<string, string> | undefined;
78
+ /**
79
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728) hints, used by the built-in MCP server's
80
+ * `/.well-known/oauth-protected-resource` endpoint when `server.mcp.oauth` does not set them.
81
+ */
82
+ getOAuthMetadata?(): MastraAuthOAuthMetadata | undefined;
83
+ /**
84
+ * Whether the token that authenticated `user` was issued for `audience` (its `aud` claim includes it).
85
+ * `user` is the value returned by `authenticateToken`. Called by the built-in MCP server when
86
+ * `server.mcp.oauth.resource` is set.
87
+ */
88
+ verifyAudience?(user: TUser, audience: string): boolean | Promise<boolean>;
89
+ }
90
+ /** Authorization server hints for MCP clients (RFC 9728). */
91
+ export interface MastraAuthOAuthMetadata {
92
+ /** Issuer URLs of the authorization servers that issue tokens accepted by this provider. */
93
+ authorizationServers?: string[];
94
+ /** OAuth scopes the provider understands. */
95
+ scopesSupported?: string[];
61
96
  }
97
+ /** Whether a JWT `aud` claim (string or array) includes `audience`. */
98
+ export declare function jwtAudienceIncludes(aud: unknown, audience: string): boolean;
99
+ /**
100
+ * JWT claims as the authenticated user. OIDC tokens name the user in `sub`, while RBAC and FGA look the user up
101
+ * by `id`, so `id` is filled from `sub` when the token has no `id` claim of its own.
102
+ */
103
+ export declare function withSubjectAsId<T extends object>(claims: T): T;
62
104
  export declare abstract class MastraAuthProvider<TUser = unknown> extends MastraBase implements IMastraAuthProvider<TUser> {
63
105
  protected?: MastraAuthConfig['protected'];
64
106
  public?: MastraAuthConfig['public'];
@@ -78,6 +120,16 @@ export declare abstract class MastraAuthProvider<TUser = unknown> extends Mastra
78
120
  * @returns The authorization result
79
121
  */
80
122
  abstract authorizeUser(user: TUser, request: MastraAuthRequest): Promise<boolean> | boolean;
123
+ /**
124
+ * Normalize the authenticated provider-specific user to the stable
125
+ * {@link MastraUser} shape surfaced to `DynamicArgument` callbacks as the
126
+ * optional `user` argument.
127
+ *
128
+ * The default implementation handles common user shapes (see
129
+ * {@link normalizeMastraUser}); override it when your provider's user type
130
+ * needs custom mapping.
131
+ */
132
+ toMastraUser(user: TUser): MastraUser;
81
133
  protected registerOptions(opts?: MastraAuthProviderOptions<TUser>): void;
82
134
  }
83
135
  export declare function isSSOProvider(p: unknown): p is ISSOProvider;
@@ -95,6 +147,13 @@ export declare class CompositeAuth extends MastraAuthProvider implements ISSOPro
95
147
  private findProvider;
96
148
  private rememberAuthenticatedProvider;
97
149
  private takeAuthenticatedProvider;
150
+ private peekAuthenticatedProvider;
151
+ /**
152
+ * Delegate normalization to the provider that authenticated this user.
153
+ * Falls back to the default normalization when the winning provider is
154
+ * unknown or predates `toMastraUser`.
155
+ */
156
+ toMastraUser(user: unknown): MastraUser;
98
157
  private mapAuthenticatedUserToResourceId;
99
158
  /**
100
159
  * True if any provider is MastraCloudAuth (exempt from license requirement).
@@ -106,6 +165,19 @@ export declare class CompositeAuth extends MastraAuthProvider implements ISSOPro
106
165
  get isSimpleAuth(): boolean;
107
166
  authenticateToken(token: string, request: MastraAuthRequest): Promise<unknown | null>;
108
167
  consumePendingResponseHeaders(request: MastraAuthRequest): Record<string, string> | undefined;
168
+ /** The wrapped provider that authenticated `user`, or undefined when it can't be determined. */
169
+ getAuthenticatedProvider(user: unknown): IMastraAuthProvider | undefined;
170
+ /** The wrapped providers, in the order they are tried. */
171
+ getProviders(): readonly IMastraAuthProvider[];
172
+ /** Union of the wrapped providers' OAuth metadata. */
173
+ getOAuthMetadata(): MastraAuthOAuthMetadata | undefined;
174
+ /**
175
+ * Delegates to the provider that authenticated `user`. Returns true (audience not enforced) when that
176
+ * provider has no `verifyAudience`. When the authenticating provider can't be determined (for example the
177
+ * user object was replaced after authentication), returns false if any wrapped provider could check the
178
+ * audience, so the check fails closed.
179
+ */
180
+ verifyAudience(user: unknown, audience: string): Promise<boolean>;
109
181
  authorizeUser(user: unknown, request: MastraAuthRequest): Promise<boolean>;
110
182
  /**
111
183
  * Forward cookie header to SSO provider for PKCE validation.
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Signed cookie session provider.
3
+ *
4
+ * Stores session data in signed cookies. No server-side storage required.
5
+ */
6
+ import type { Session, ISessionProvider } from '..';
7
+ /**
8
+ * Options for CookieSessionProvider.
9
+ */
10
+ export interface CookieSessionProviderOptions {
11
+ /** Secret for signing cookies (required) */
12
+ secret: string;
13
+ /** Session TTL in milliseconds (default: 7 days) */
14
+ ttl?: number;
15
+ /** Cookie name (default: 'mastra_session') */
16
+ cookieName?: string;
17
+ /** Cookie path (default: '/') */
18
+ cookiePath?: string;
19
+ /** Cookie domain */
20
+ cookieDomain?: string;
21
+ /** Use secure cookies (default: true in production) */
22
+ secure?: boolean;
23
+ }
24
+ /**
25
+ * Signed cookie session provider.
26
+ *
27
+ * Stores session data in signed cookies. The session is validated
28
+ * by verifying the signature on each request.
29
+ *
30
+ * @example
31
+ * ```typescript
32
+ * const sessionProvider = new CookieSessionProvider({
33
+ * secret: process.env.SESSION_SECRET!,
34
+ * ttl: 7 * 24 * 60 * 60 * 1000, // 7 days
35
+ * });
36
+ * ```
37
+ */
38
+ export declare class CookieSessionProvider implements ISessionProvider {
39
+ private secret;
40
+ private ttl;
41
+ private cookieName;
42
+ private cookiePath;
43
+ private cookieDomain?;
44
+ private secure;
45
+ constructor(options: CookieSessionProviderOptions);
46
+ createSession(userId: string, metadata?: Record<string, unknown>): Promise<Session>;
47
+ validateSession(_sessionId: string): Promise<Session | null>;
48
+ destroySession(_sessionId: string): Promise<void>;
49
+ refreshSession(_sessionId: string): Promise<Session | null>;
50
+ getSessionIdFromRequest(request: Request): string | null;
51
+ /**
52
+ * Get full session from cookie.
53
+ */
54
+ getSessionFromCookie(request: Request): Session | null;
55
+ getSessionHeaders(session: Session): Record<string, string>;
56
+ getClearSessionHeaders(): Record<string, string>;
57
+ /**
58
+ * Sign and encode session data.
59
+ */
60
+ private signAndEncode;
61
+ /**
62
+ * Decode and verify session cookie.
63
+ */
64
+ private decodeAndVerify;
65
+ /**
66
+ * Create HMAC-SHA256 signature.
67
+ */
68
+ private sign;
69
+ /**
70
+ * Base64 encode (consistent across Node.js and browser runtimes).
71
+ */
72
+ private base64Encode;
73
+ /**
74
+ * Base64 decode (consistent across Node.js and browser runtimes).
75
+ */
76
+ private base64Decode;
77
+ /**
78
+ * Constant-time string comparison.
79
+ */
80
+ private secureCompare;
81
+ }
82
+ //# sourceMappingURL=cookie.d.ts.map
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Session object representing an authenticated session.
3
+ */
4
+ export interface Session {
5
+ /** Unique session identifier */
6
+ id: string;
7
+ /** User ID this session belongs to */
8
+ userId: string;
9
+ /** When the session expires */
10
+ expiresAt: Date;
11
+ /** When the session was created */
12
+ createdAt: Date;
13
+ /** Additional session metadata */
14
+ metadata?: Record<string, unknown>;
15
+ }
16
+ /**
17
+ * Provider interface for session management.
18
+ */
19
+ export interface ISessionProvider<TSession extends Session = Session> {
20
+ createSession(userId: string, metadata?: Record<string, unknown>): Promise<TSession>;
21
+ validateSession(sessionId: string): Promise<TSession | null>;
22
+ destroySession(sessionId: string): Promise<void>;
23
+ refreshSession(sessionId: string): Promise<TSession | null>;
24
+ getSessionIdFromRequest(request: Request): string | null;
25
+ getSessionHeaders(session: TSession): Record<string, string>;
26
+ getClearSessionHeaders(): Record<string, string>;
27
+ /**
28
+ * Optional: `Set-Cookie` values expiring legacy copies of the session cookie
29
+ * (for example one an earlier release scoped to a shared parent `Domain`).
30
+ * A browser only deletes a cookie whose exact `(name, Domain, Path)` match,
31
+ * so servers append these to every response that sets or clears the session
32
+ * cookie; otherwise a stale shared-domain copy keeps being sent to every
33
+ * sibling host until it expires.
34
+ */
35
+ getLegacySessionClearCookies?(): string[];
36
+ }
37
+ export { MemorySessionProvider, type MemorySessionProviderOptions } from './memory.js';
38
+ export { CookieSessionProvider, type CookieSessionProviderOptions } from './cookie.js';
39
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,60 @@
1
+ /**
2
+ * In-memory session provider for development.
3
+ *
4
+ * WARNING: Sessions are lost on server restart. Not for production use.
5
+ */
6
+ import type { Session, ISessionProvider } from '..';
7
+ /**
8
+ * Options for MemorySessionProvider.
9
+ */
10
+ export interface MemorySessionProviderOptions {
11
+ /** Session TTL in milliseconds (default: 7 days) */
12
+ ttl?: number;
13
+ /** Cookie name (default: 'mastra_session') */
14
+ cookieName?: string;
15
+ /** Cookie path (default: '/') */
16
+ cookiePath?: string;
17
+ /** Cleanup interval in milliseconds (default: 60000) */
18
+ cleanupInterval?: number;
19
+ }
20
+ /**
21
+ * In-memory session provider.
22
+ *
23
+ * Stores sessions in a Map. Useful for development but not suitable
24
+ * for production as sessions are lost on restart.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * const sessionProvider = new MemorySessionProvider({
29
+ * ttl: 24 * 60 * 60 * 1000, // 24 hours
30
+ * });
31
+ * ```
32
+ */
33
+ export declare class MemorySessionProvider implements ISessionProvider {
34
+ private sessions;
35
+ private ttl;
36
+ private cookieName;
37
+ private cookiePath;
38
+ private cleanupTimer;
39
+ constructor(options?: MemorySessionProviderOptions);
40
+ createSession(userId: string, metadata?: Record<string, unknown>): Promise<Session>;
41
+ validateSession(sessionId: string): Promise<Session | null>;
42
+ destroySession(sessionId: string): Promise<void>;
43
+ refreshSession(sessionId: string): Promise<Session | null>;
44
+ getSessionIdFromRequest(request: Request): string | null;
45
+ getSessionHeaders(session: Session): Record<string, string>;
46
+ getClearSessionHeaders(): Record<string, string>;
47
+ /**
48
+ * Clean up expired sessions.
49
+ */
50
+ private cleanup;
51
+ /**
52
+ * Stop the cleanup timer.
53
+ */
54
+ dispose(): void;
55
+ /**
56
+ * Get the number of active sessions (for debugging).
57
+ */
58
+ getSessionCount(): number;
59
+ }
60
+ //# sourceMappingURL=memory.d.ts.map
@@ -1,3 +1,4 @@
1
+ import type { User } from '../index.js';
1
2
  export interface HonoRequestLike {
2
3
  raw?: Request;
3
4
  headers?: Headers | Record<string, string | string[] | undefined>;
@@ -34,6 +35,12 @@ export type MastraAuthConfig<TUser = unknown, TContext = unknown> = {
34
35
  * Maps the authenticated user to a resource ID for memory/thread scoping.
35
36
  */
36
37
  mapUserToResourceId?(user: TUser): string | undefined | null;
38
+ /**
39
+ * Normalizes the authenticated user to the `MastraUser` shape passed to
40
+ * dynamic configuration callbacks as `user`. Defaults to the shared
41
+ * normalization (`id`/`sub`/`userId`, `name`, `email`, `avatarUrl`/`picture`, `role`).
42
+ */
43
+ toMastraUser?(user: TUser): User;
37
44
  /**
38
45
  * Authorization function for the server.
39
46
  */