@objectstack/plugin-auth 4.0.5 → 4.1.0

package/dist/index.d.mts

@@ -3,6 +3,7 @@ import { AuthConfig, OidcProvidersConfig } from '@objectstack/spec/system';
 export { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system';
 import * as better_auth from 'better-auth';
 import { Auth } from 'better-auth';
+import { IEmailService } from '@objectstack/spec/contracts';
 import * as better_auth_adapters from 'better-auth/adapters';
 import { CleanedWhere } from 'better-auth/adapters';
 
@@ -21,6 +22,23 @@ interface AuthPluginOptions extends Partial<AuthConfig> {
      * @default '/api/v1/auth'
      */
     basePath?: string;
+    /**
+     * Override the datasource that owns the identity tables (sys_user,
+     * sys_session, …) when AuthPlugin's manifest is registered.
+     *
+     * Defaults to `'cloud'` (control-plane DB) so the historical
+     * single-tenant control-plane behaviour is preserved. Per-project
+     * kernels in objectos pass `'default'` so identity tables live in the
+     * project's own database — each project owns its own users.
+     */
+    manifestDatasource?: string;
+    /**
+     * Application-specific organization roles to register with Better-Auth's
+     * organization plugin so invitations to those roles aren't rejected with
+     * ROLE_NOT_FOUND. Forwarded as-is to AuthManager. See
+     * {@link AuthManagerOptions.additionalOrgRoles} for details.
+     */
+    additionalOrgRoles?: string[];
 }
 /**
  * Authentication Plugin
@@ -109,6 +127,42 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * Each entry is passed to better-auth's genericOAuth plugin.
      */
     oidcProviders?: OidcProvidersConfig;
+    /**
+     * Application-specific organization roles to register with Better-Auth's
+     * organization plugin. Each name becomes a valid role for invitations and
+     * member assignments without going through Better-Auth's default
+     * `owner|admin|member` whitelist.
+     *
+     * The ObjectStack SecurityPlugin handles real RBAC enforcement by matching
+     * these role names against `permission` metadata (PermissionSets / Profiles),
+     * so Better-Auth only needs to accept them as opaque strings. Each role is
+     * registered with the minimum access-control privileges (equivalent to
+     * Better-Auth's `member` role) so it cannot inadvertently grant org-level
+     * admin capabilities.
+     *
+     * Typical source: the union of `permission` metadata names that have
+     * `isProfile: true`, collected from the loaded stack at CLI boot.
+     *
+     * @example ['sales_rep', 'sales_manager', 'service_agent']
+     */
+    additionalOrgRoles?: string[];
+    /**
+     * Optional outbound email service used by better-auth callbacks
+     * (`sendResetPassword`, `sendVerificationEmail`, `sendInvitationEmail`,
+     * `sendMagicLink`). When omitted, those callbacks degrade to logging
+     * the action URL — keeping flows usable in pilots / local dev — but
+     * production deployments SHOULD wire one via `setEmailService()`.
+     *
+     * Resolved lazily through {@link AuthManager.getEmailService}; safe
+     * to set after construction. AuthPlugin wires this from the kernel
+     * service registry on `kernel:ready`.
+     */
+    emailService?: IEmailService;
+    /**
+     * Display name used by built-in auth email templates (`{{appName}}`
+     * placeholder). Defaults to `'ObjectStack'` when omitted.
+     */
+    appName?: string;
 }
 /**
  * Authentication Manager
@@ -170,6 +224,20 @@ declare class AuthManager {
      * a warning is emitted.
      */
     setRuntimeBaseUrl(url: string): void;
+    /**
+     * Inject (or replace) the outbound email service used by better-auth
+     * callbacks. Safe to call after construction but BEFORE the first
+     * request hits the auth handler — callbacks read this via
+     * {@link getEmailService} when invoked.
+     *
+     * AuthPlugin calls this on `kernel:ready` once `ctx.getService('email')`
+     * resolves. For tests / serverless, callers may invoke directly.
+     */
+    setEmailService(email: IEmailService | undefined): void;
+    /** @internal Used by callback closures. */
+    private getEmailService;
+    /** @internal `{{appName}}` placeholder value for built-in templates. */
+    private getAppName;
     /**
      * Get the underlying better-auth instance
      * Useful for advanced use cases
@@ -544,6 +612,29 @@ declare const AUTH_TWO_FACTOR_SCHEMA: {
 declare const AUTH_TWO_FACTOR_USER_FIELDS: {
     readonly twoFactorEnabled: "two_factor_enabled";
 };
+/**
+ * Admin plugin adds platform-level admin fields to the `user` model.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | banReason               | ban_reason               |
+ * | banExpires              | ban_expires              |
+ *
+ * `role` and `banned` already have matching snake_case names and are
+ * therefore omitted from this mapping (better-auth's database hooks
+ * read them by the auto-derived column names).
+ */
+declare const AUTH_ADMIN_USER_FIELDS: {
+    readonly banReason: "ban_reason";
+    readonly banExpires: "ban_expires";
+};
+/**
+ * Admin plugin adds an `impersonatedBy` field to the session model
+ * recording the operator user id when an admin impersonates someone.
+ */
+declare const AUTH_ADMIN_SESSION_FIELDS: {
+    readonly impersonatedBy: "impersonated_by";
+};
 /**
  * `@better-auth/oauth-provider` plugin `oauthClient` model mapping.
  *
@@ -753,6 +844,26 @@ declare function buildTwoFactorPluginSchema(): {
         };
     };
 };
+/**
+ * Builds the `schema` option for better-auth's `admin()` plugin.
+ *
+ * The admin plugin extends the user model with `role`/`banned`/`banReason`/
+ * `banExpires` and the session model with `impersonatedBy`. Only the
+ * snake_case-differing fields are mapped explicitly.
+ */
+declare function buildAdminPluginSchema(): {
+    user: {
+        fields: {
+            readonly banReason: "ban_reason";
+            readonly banExpires: "ban_expires";
+        };
+    };
+    session: {
+        fields: {
+            readonly impersonatedBy: "impersonated_by";
+        };
+    };
+};
 /**
  * Builds the `schema` option for better-auth's `organization()` plugin.
  *
@@ -952,4 +1063,4 @@ declare function buildDeviceAuthorizationPluginSchema(): {
     };
 };
 
-export { AUTH_ACCOUNT_CONFIG, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SESSION_CONFIG, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName };
+export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SESSION_CONFIG, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { AuthConfig, OidcProvidersConfig } from '@objectstack/spec/system';
 export { AuthConfig, AuthPluginConfig, AuthProviderConfig } from '@objectstack/spec/system';
 import * as better_auth from 'better-auth';
 import { Auth } from 'better-auth';
+import { IEmailService } from '@objectstack/spec/contracts';
 import * as better_auth_adapters from 'better-auth/adapters';
 import { CleanedWhere } from 'better-auth/adapters';
 
@@ -21,6 +22,23 @@ interface AuthPluginOptions extends Partial<AuthConfig> {
      * @default '/api/v1/auth'
      */
     basePath?: string;
+    /**
+     * Override the datasource that owns the identity tables (sys_user,
+     * sys_session, …) when AuthPlugin's manifest is registered.
+     *
+     * Defaults to `'cloud'` (control-plane DB) so the historical
+     * single-tenant control-plane behaviour is preserved. Per-project
+     * kernels in objectos pass `'default'` so identity tables live in the
+     * project's own database — each project owns its own users.
+     */
+    manifestDatasource?: string;
+    /**
+     * Application-specific organization roles to register with Better-Auth's
+     * organization plugin so invitations to those roles aren't rejected with
+     * ROLE_NOT_FOUND. Forwarded as-is to AuthManager. See
+     * {@link AuthManagerOptions.additionalOrgRoles} for details.
+     */
+    additionalOrgRoles?: string[];
 }
 /**
  * Authentication Plugin
@@ -109,6 +127,42 @@ interface AuthManagerOptions extends Partial<AuthConfig> {
      * Each entry is passed to better-auth's genericOAuth plugin.
      */
     oidcProviders?: OidcProvidersConfig;
+    /**
+     * Application-specific organization roles to register with Better-Auth's
+     * organization plugin. Each name becomes a valid role for invitations and
+     * member assignments without going through Better-Auth's default
+     * `owner|admin|member` whitelist.
+     *
+     * The ObjectStack SecurityPlugin handles real RBAC enforcement by matching
+     * these role names against `permission` metadata (PermissionSets / Profiles),
+     * so Better-Auth only needs to accept them as opaque strings. Each role is
+     * registered with the minimum access-control privileges (equivalent to
+     * Better-Auth's `member` role) so it cannot inadvertently grant org-level
+     * admin capabilities.
+     *
+     * Typical source: the union of `permission` metadata names that have
+     * `isProfile: true`, collected from the loaded stack at CLI boot.
+     *
+     * @example ['sales_rep', 'sales_manager', 'service_agent']
+     */
+    additionalOrgRoles?: string[];
+    /**
+     * Optional outbound email service used by better-auth callbacks
+     * (`sendResetPassword`, `sendVerificationEmail`, `sendInvitationEmail`,
+     * `sendMagicLink`). When omitted, those callbacks degrade to logging
+     * the action URL — keeping flows usable in pilots / local dev — but
+     * production deployments SHOULD wire one via `setEmailService()`.
+     *
+     * Resolved lazily through {@link AuthManager.getEmailService}; safe
+     * to set after construction. AuthPlugin wires this from the kernel
+     * service registry on `kernel:ready`.
+     */
+    emailService?: IEmailService;
+    /**
+     * Display name used by built-in auth email templates (`{{appName}}`
+     * placeholder). Defaults to `'ObjectStack'` when omitted.
+     */
+    appName?: string;
 }
 /**
  * Authentication Manager
@@ -170,6 +224,20 @@ declare class AuthManager {
      * a warning is emitted.
      */
     setRuntimeBaseUrl(url: string): void;
+    /**
+     * Inject (or replace) the outbound email service used by better-auth
+     * callbacks. Safe to call after construction but BEFORE the first
+     * request hits the auth handler — callbacks read this via
+     * {@link getEmailService} when invoked.
+     *
+     * AuthPlugin calls this on `kernel:ready` once `ctx.getService('email')`
+     * resolves. For tests / serverless, callers may invoke directly.
+     */
+    setEmailService(email: IEmailService | undefined): void;
+    /** @internal Used by callback closures. */
+    private getEmailService;
+    /** @internal `{{appName}}` placeholder value for built-in templates. */
+    private getAppName;
     /**
      * Get the underlying better-auth instance
      * Useful for advanced use cases
@@ -544,6 +612,29 @@ declare const AUTH_TWO_FACTOR_SCHEMA: {
 declare const AUTH_TWO_FACTOR_USER_FIELDS: {
     readonly twoFactorEnabled: "two_factor_enabled";
 };
+/**
+ * Admin plugin adds platform-level admin fields to the `user` model.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | banReason               | ban_reason               |
+ * | banExpires              | ban_expires              |
+ *
+ * `role` and `banned` already have matching snake_case names and are
+ * therefore omitted from this mapping (better-auth's database hooks
+ * read them by the auto-derived column names).
+ */
+declare const AUTH_ADMIN_USER_FIELDS: {
+    readonly banReason: "ban_reason";
+    readonly banExpires: "ban_expires";
+};
+/**
+ * Admin plugin adds an `impersonatedBy` field to the session model
+ * recording the operator user id when an admin impersonates someone.
+ */
+declare const AUTH_ADMIN_SESSION_FIELDS: {
+    readonly impersonatedBy: "impersonated_by";
+};
 /**
  * `@better-auth/oauth-provider` plugin `oauthClient` model mapping.
  *
@@ -753,6 +844,26 @@ declare function buildTwoFactorPluginSchema(): {
         };
     };
 };
+/**
+ * Builds the `schema` option for better-auth's `admin()` plugin.
+ *
+ * The admin plugin extends the user model with `role`/`banned`/`banReason`/
+ * `banExpires` and the session model with `impersonatedBy`. Only the
+ * snake_case-differing fields are mapped explicitly.
+ */
+declare function buildAdminPluginSchema(): {
+    user: {
+        fields: {
+            readonly banReason: "ban_reason";
+            readonly banExpires: "ban_expires";
+        };
+    };
+    session: {
+        fields: {
+            readonly impersonatedBy: "impersonated_by";
+        };
+    };
+};
 /**
  * Builds the `schema` option for better-auth's `organization()` plugin.
  *
@@ -952,4 +1063,4 @@ declare function buildDeviceAuthorizationPluginSchema(): {
     };
 };
 
-export { AUTH_ACCOUNT_CONFIG, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SESSION_CONFIG, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName };
+export { AUTH_ACCOUNT_CONFIG, AUTH_ADMIN_SESSION_FIELDS, AUTH_ADMIN_USER_FIELDS, AUTH_DEVICE_CODE_SCHEMA, AUTH_INVITATION_SCHEMA, AUTH_JWKS_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_MODEL_TO_PROTOCOL, AUTH_OAUTH_ACCESS_TOKEN_SCHEMA, AUTH_OAUTH_APPLICATION_SCHEMA, AUTH_OAUTH_CLIENT_SCHEMA, AUTH_OAUTH_CONSENT_SCHEMA, AUTH_OAUTH_REFRESH_TOKEN_SCHEMA, AUTH_ORGANIZATION_SCHEMA, AUTH_ORG_SESSION_FIELDS, AUTH_SESSION_CONFIG, AUTH_TEAM_MEMBER_SCHEMA, AUTH_TEAM_SCHEMA, AUTH_TWO_FACTOR_SCHEMA, AUTH_TWO_FACTOR_USER_FIELDS, AUTH_USER_CONFIG, AUTH_VERIFICATION_CONFIG, AuthManager, type AuthManagerOptions, AuthPlugin, type AuthPluginOptions, buildAdminPluginSchema, buildDeviceAuthorizationPluginSchema, buildJwtPluginSchema, buildOauthProviderPluginSchema, buildOidcProviderPluginSchema, buildOrganizationPluginSchema, buildTwoFactorPluginSchema, createObjectQLAdapter, createObjectQLAdapterFactory, resolveProtocolName };