@happyvertical/smrt-users 0.30.0

package/dist/models/Tenant.d.ts

@@ -0,0 +1,138 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { Tenant as TenantContract } from '@happyvertical/smrt-types';
+import { TenantStatus } from '../types/index.js';
+/**
+ * Maximum allowed depth for tenant hierarchy.
+ * Prevents excessively deep trees that could cause performance issues.
+ */
+export declare const MAX_TENANT_HIERARCHY_DEPTH = 10;
+/**
+ * Tenant represents an organizational boundary in the multi-tenant system.
+ *
+ * Supports hierarchical organization with parent-child relationships.
+ * Users can belong to multiple tenants through Memberships.
+ * Each tenant can have custom roles in addition to system defaults.
+ *
+ * ## Hierarchical Tenants
+ *
+ * Tenants can be organized in a tree structure where child tenants
+ * can optionally inherit permissions from their parent tenants.
+ *
+ * ### Cascade Control
+ *
+ * Two flags control permission inheritance:
+ * - `cascadePermissions`: If true, this tenant pushes its permissions to children
+ * - `inheritPermissions`: If true, this tenant accepts permissions from parent
+ *
+ * Both must be true for inheritance to flow from parent to child.
+ *
+ * @example
+ * ```typescript
+ * // Create root tenant
+ * const corp = await tenants.create({
+ *   name: 'Acme Corporation',
+ *   slug: 'acme-corp',
+ *   cascadePermissions: true,  // Push permissions to children
+ * });
+ * await corp.save();
+ *
+ * // Create child tenant that inherits
+ * const division = await tenants.create({
+ *   name: 'Acme West Division',
+ *   slug: 'acme-west',
+ *   parentTenantId: corp.id,
+ *   inheritPermissions: true,  // Accept parent permissions
+ * });
+ * await division.save();
+ *
+ * // Create independent child (breaks inheritance chain)
+ * const independent = await tenants.create({
+ *   name: 'Acme Labs',
+ *   slug: 'acme-labs',
+ *   parentTenantId: corp.id,
+ *   inheritPermissions: false,  // Does NOT inherit from parent
+ * });
+ * await independent.save();
+ * ```
+ */
+export declare class Tenant extends SmrtObject implements TenantContract {
+    /**
+     * Display name for the tenant
+     */
+    name: string;
+    /**
+     * Tenant status
+     */
+    status: TenantStatus;
+    /**
+     * Optional description
+     */
+    description: string;
+    /**
+     * Parent tenant ID for hierarchical organization.
+     * Null for root-level tenants.
+     */
+    parentTenantId?: string | null;
+    /**
+     * Depth in the hierarchy tree (0 = root, 1 = first level child, etc.)
+     * Automatically managed by TenantCollection methods.
+     */
+    hierarchyLevel: number;
+    /**
+     * Materialized path for efficient tree traversal.
+     * Format: "ancestor-id/parent-id" (path to parent; does not include this tenant's id)
+     * Empty string for root tenants.
+     * Automatically managed by TenantCollection methods.
+     */
+    hierarchyPath: string;
+    /**
+     * If true, this tenant's permissions cascade DOWN to child tenants.
+     * Children can still opt-out by setting inheritPermissions: false.
+     * Default: true
+     */
+    cascadePermissions: boolean;
+    /**
+     * If true, this tenant ACCEPTS permissions from its parent tenant.
+     * Parent must also have cascadePermissions: true for inheritance to work.
+     * Default: true
+     */
+    inheritPermissions: boolean;
+    constructor(options?: any);
+    /**
+     * Check if tenant is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if tenant is suspended
+     */
+    isSuspended(): boolean;
+    /**
+     * Check if this is a root-level tenant (no parent)
+     */
+    isRoot(): boolean;
+    /**
+     * Check if this tenant is configured to cascade permissions to children.
+     *
+     * Note: This does NOT indicate whether any child tenants actually exist.
+     * Use TenantCollection.findChildren() for accurate child lookup.
+     */
+    canCascadeToChildren(): boolean;
+    /**
+     * Check if permission inheritance is active for this tenant.
+     * Inheritance is active if:
+     * - This tenant has a parent AND
+     * - This tenant has inheritPermissions: true
+     *
+     * Note: The parent must also have cascadePermissions: true
+     * for actual inheritance to occur. Use PermissionResolver
+     * for accurate permission calculation.
+     */
+    acceptsInheritance(): boolean;
+    /**
+     * Get ancestor IDs from the hierarchy path.
+     * Returns an array of tenant IDs from root to immediate parent.
+     * Empty array for root tenants.
+     */
+    getAncestorIds(): string[];
+}
+//# sourceMappingURL=Tenant.d.ts.map

package/dist/models/Tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tenant.d.ts","sourceRoot":"","sources":["../../src/models/Tenant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBASa,MAAO,SAAQ,UAAW,YAAW,cAAc;IAC9D;;OAEG;IACH,IAAI,EAAE,MAAM,CAAM;IAElB;;OAEG;IAEH,MAAM,EAAE,YAAY,CAAuB;IAE3C;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAIzB;;;OAGG;IAEH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAK;IAE3B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAM;IAI3B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAQ;IAEnC;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAQ;gBAEvB,OAAO,GAAE,GAAQ;IAkB7B;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;OAKG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;;;;;;;;OASG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;;;OAIG;IACH,cAAc,IAAI,MAAM,EAAE;CAI3B"}

package/dist/models/TenantPermissionOverride.d.ts

@@ -0,0 +1,74 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { TenantPermissionEffect } from '../types/index.js';
+/**
+ * TenantPermissionOverride allows setting explicit permission values at the tenant level.
+ *
+ * This is used in hierarchical tenant structures to control permission inheritance.
+ * Each override specifies whether a permission is:
+ * - INHERIT: Use the parent tenant's value (default behavior)
+ * - GRANT: Explicitly grant at this tenant level
+ * - DENY: Explicitly deny at this tenant level (blocks inheritance)
+ *
+ * ## Resolution Order
+ *
+ * When resolving effective tenant permissions:
+ * 1. Walk down the tenant hierarchy from root to target, accumulating permissions
+ * 2. Apply each tenant's overrides (DENY blocks, GRANT adds)
+ * 3. INHERIT means "use whatever the parent resolved to"
+ *
+ * @example
+ * ```typescript
+ * // Explicitly grant a permission at this tenant level
+ * const override = await tenantPermissionOverrides.create({
+ *   tenantId: tenant.id,
+ *   permissionId: specialPermission.id,
+ *   effect: TenantPermissionEffect.GRANT
+ * });
+ *
+ * // Block a permission from being inherited (even if parent grants it)
+ * const block = await tenantPermissionOverrides.create({
+ *   tenantId: tenant.id,
+ *   permissionId: dangerousPermission.id,
+ *   effect: TenantPermissionEffect.DENY
+ * });
+ *
+ * // Explicitly inherit (same as not having an override, but documents intent)
+ * const inherit = await tenantPermissionOverrides.create({
+ *   tenantId: tenant.id,
+ *   permissionId: standardPermission.id,
+ *   effect: TenantPermissionEffect.INHERIT
+ * });
+ * ```
+ */
+export declare class TenantPermissionOverride extends SmrtObject {
+    /**
+     * Foreign key to Tenant
+     */
+    tenantId?: string;
+    /**
+     * Foreign key to Permission
+     */
+    permissionId?: string;
+    /**
+     * Effect of the override: inherit, grant, or deny
+     */
+    effect: TenantPermissionEffect;
+    constructor(options?: any);
+    /**
+     * Check if this override inherits from parent
+     */
+    isInherit(): boolean;
+    /**
+     * Check if this override grants the permission
+     */
+    isGrant(): boolean;
+    /**
+     * Check if this override denies the permission
+     */
+    isDeny(): boolean;
+    /**
+     * Check if this override has an explicit effect (not inherit)
+     */
+    hasExplicitEffect(): boolean;
+}
+//# sourceMappingURL=TenantPermissionOverride.d.ts.map

package/dist/models/TenantPermissionOverride.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantPermissionOverride.d.ts","sourceRoot":"","sources":["../../src/models/TenantPermissionOverride.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAQa,wBAAyB,SAAQ,UAAU;IACtD;;OAEG;IAEH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IAEH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IAEH,MAAM,EAAE,sBAAsB,CAAkC;gBAEpD,OAAO,GAAE,GAAQ;IAQ7B;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,iBAAiB,IAAI,OAAO;CAG7B"}

package/dist/models/User.d.ts

@@ -0,0 +1,72 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { User as UserContract } from '@happyvertical/smrt-types';
+import { UserStatus } from '../types/index.js';
+/**
+ * Validate email format.
+ * @param email - Email address to validate
+ * @returns true if email format is valid
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Normalize email address (lowercase and trim).
+ * @param email - Email address to normalize
+ * @returns Normalized email
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * User represents an authenticated identity in the system.
+ *
+ * Users are linked to Profiles from smrt-profiles via profileId.
+ * A User can have multiple Memberships across different Tenants.
+ *
+ * @example
+ * ```typescript
+ * const user = await users.create({
+ *   profileId: 'profile-uuid',
+ *   email: 'user@example.com',
+ *   status: UserStatus.ACTIVE
+ * });
+ * await user.save();
+ * ```
+ */
+export declare class User extends SmrtObject implements UserContract {
+    /**
+     * Foreign key to smrt-profiles Profile (cross-package)
+     */
+    profileId: string;
+    /**
+     * User's email address (unique, used for lookup)
+     */
+    email: string;
+    /**
+     * User account status
+     */
+    status: UserStatus;
+    /**
+     * Last login timestamp
+     */
+    lastLoginAt: Date | null;
+    constructor(options?: any);
+    /**
+     * Validate the user's email format.
+     * @returns true if email is valid
+     */
+    hasValidEmail(): boolean;
+    /**
+     * Check if user is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if user is suspended
+     */
+    isSuspended(): boolean;
+    /**
+     * Check if user is pending verification
+     */
+    isPending(): boolean;
+    /**
+     * Record a login event
+     */
+    recordLogin(): void;
+}
+//# sourceMappingURL=User.d.ts.map

package/dist/models/User.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"User.d.ts","sourceRoot":"","sources":["../../src/models/User.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAQ/C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAOa,IAAK,SAAQ,UAAW,YAAW,YAAY;IAC1D;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;IAEnB;;OAEG;IAEH,MAAM,EAAE,UAAU,CAAqB;IAEvC;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;gBAEpB,OAAO,GAAE,GAAQ;IAS7B;;;OAGG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,IAAI,IAAI;CAGpB"}

package/dist/models/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model exports for smrt-users
+ * @packageDocumentation
+ */
+export { CliAuthRequest, type CliAuthRequestStatus, UsersCliAuthRequest, } from './CliAuthRequest.js';
+export { Group } from './Group.js';
+export { GroupMember } from './GroupMember.js';
+export { GroupRole } from './GroupRole.js';
+export { DEFAULT_TOKEN_EXPIRY_SECONDS, MagicLinkToken, UsersMagicLinkToken, } from './MagicLinkToken.js';
+export { Membership } from './Membership.js';
+export { MembershipOverride } from './MembershipOverride.js';
+export { isValidPermissionSlug, type ParsedPermissionSlug, Permission, parsePermissionSlug, } from './Permission.js';
+export { Role } from './Role.js';
+export { RolePermission } from './RolePermission.js';
+export { DEFAULT_SESSION_TTL, generateSessionId, Session, } from './Session.js';
+export { MAX_TENANT_HIERARCHY_DEPTH, Tenant } from './Tenant.js';
+export { TenantPermissionOverride } from './TenantPermissionOverride.js';
+export { isValidEmail, normalizeEmail, User } from './User.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EACL,4BAA4B,EAC5B,cAAc,EACd,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,UAAU,EACV,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,0BAA0B,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}

package/dist/playground.d.ts

@@ -0,0 +1,2 @@
+export { default } from './svelte/playground.js';
+//# sourceMappingURL=playground.d.ts.map

package/dist/playground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/playground.js

@@ -0,0 +1,139 @@
+import { USERS_MODULE_META } from "./ui.js";
+const noop = () => {
+};
+const sampleTenant = {
+  id: "tenant-riverstone",
+  name: "Riverstone Newsroom",
+  slug: "riverstone-newsroom",
+  status: "active"
+};
+const sampleRoles = [
+  {
+    id: "role-member",
+    slug: "member",
+    name: "Member",
+    description: "Can collaborate on editorial work."
+  },
+  {
+    id: "role-editor",
+    slug: "editor",
+    name: "Editor",
+    description: "Can approve and publish content."
+  }
+];
+const sampleUsers = [
+  {
+    user: {
+      id: "user-taylor",
+      email: "taylor@example.com",
+      status: "active"
+    },
+    profile: {
+      id: "profile-taylor",
+      name: "Taylor Rowan",
+      email: "taylor@example.com"
+    },
+    role: "Editor"
+  },
+  {
+    user: {
+      id: "user-jordan",
+      email: "jordan@example.com",
+      status: "pending"
+    },
+    profile: {
+      id: "profile-jordan",
+      name: "Jordan Lee",
+      email: "jordan@example.com"
+    },
+    role: "Contributor"
+  }
+];
+const loadInviteUserModal = () => import("./svelte/components/InviteUserModal.svelte");
+const loadUserForm = () => import("./svelte/components/UserForm.svelte");
+const loadUserList = () => import("./svelte/components/UserList.svelte");
+const loadUserMenu = () => import("./svelte/components/UserMenu.svelte");
+const playground = {
+  packageName: "@happyvertical/smrt-users",
+  displayName: USERS_MODULE_META.displayName,
+  description: USERS_MODULE_META.description,
+  moduleMeta: USERS_MODULE_META,
+  entries: [
+    {
+      id: "user-list",
+      title: "User List",
+      description: "Role-aware list of users with selection and profile display.",
+      loadComponent: loadUserList,
+      order: 1,
+      props: {
+        users: sampleUsers,
+        selectedId: "user-taylor",
+        onselect: noop
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    },
+    {
+      id: "user-form",
+      title: "User Form",
+      description: "Create and edit form for user records and account status.",
+      loadComponent: loadUserForm,
+      order: 2,
+      props: {
+        user: sampleUsers[0].user,
+        profile: sampleUsers[0].profile,
+        onsubmit: noop,
+        oncancel: noop
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    },
+    {
+      id: "invite-user-modal",
+      title: "Invite User Modal",
+      description: "Invitation flow for adding a tenant member with a role assignment.",
+      loadComponent: loadInviteUserModal,
+      order: 3,
+      props: {
+        open: false,
+        tenant: sampleTenant,
+        roles: sampleRoles,
+        onsubmit: noop,
+        onclose: noop
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    },
+    {
+      id: "user-menu",
+      title: "User Menu",
+      description: "Authenticated account menu for profile, settings, and sign-out actions.",
+      loadComponent: loadUserMenu,
+      order: 4,
+      props: {
+        profile: sampleUsers[0].profile,
+        profileUrl: "/settings/profile",
+        settingsUrl: "/settings",
+        signoutUrl: "/auth/signout"
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    }
+  ]
+};
+export {
+  playground as default
+};
+//# sourceMappingURL=playground.js.map

package/dist/playground.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.js","sources":["../src/svelte/playground.ts"],"sourcesContent":["import { USERS_MODULE_META } from '../ui.js';\n\nconst noop = () => {};\n\nconst sampleTenant = {\n  id: 'tenant-riverstone',\n  name: 'Riverstone Newsroom',\n  slug: 'riverstone-newsroom',\n  status: 'active',\n};\n\nconst sampleRoles = [\n  {\n    id: 'role-member',\n    slug: 'member',\n    name: 'Member',\n    description: 'Can collaborate on editorial work.',\n  },\n  {\n    id: 'role-editor',\n    slug: 'editor',\n    name: 'Editor',\n    description: 'Can approve and publish content.',\n  },\n];\n\nconst sampleUsers = [\n  {\n    user: {\n      id: 'user-taylor',\n      email: 'taylor@example.com',\n      status: 'active',\n    },\n    profile: {\n      id: 'profile-taylor',\n      name: 'Taylor Rowan',\n      email: 'taylor@example.com',\n    },\n    role: 'Editor',\n  },\n  {\n    user: {\n      id: 'user-jordan',\n      email: 'jordan@example.com',\n      status: 'pending',\n    },\n    profile: {\n      id: 'profile-jordan',\n      name: 'Jordan Lee',\n      email: 'jordan@example.com',\n    },\n    role: 'Contributor',\n  },\n];\n\nconst loadInviteUserModal = () => import('./components/InviteUserModal.svelte');\nconst loadUserForm = () => import('./components/UserForm.svelte');\nconst loadUserList = () => import('./components/UserList.svelte');\nconst loadUserMenu = () => import('./components/UserMenu.svelte');\n\nexport default {\n  packageName: '@happyvertical/smrt-users',\n  displayName: USERS_MODULE_META.displayName,\n  description: USERS_MODULE_META.description,\n  moduleMeta: USERS_MODULE_META,\n  entries: [\n    {\n      id: 'user-list',\n      title: 'User List',\n      description:\n        'Role-aware list of users with selection and profile display.',\n      loadComponent: loadUserList,\n      order: 1,\n      props: {\n        users: sampleUsers,\n        selectedId: 'user-taylor',\n        onselect: noop,\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'user-form',\n      title: 'User Form',\n      description: 'Create and edit form for user records and account status.',\n      loadComponent: loadUserForm,\n      order: 2,\n      props: {\n        user: sampleUsers[0].user,\n        profile: sampleUsers[0].profile,\n        onsubmit: noop,\n        oncancel: noop,\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'invite-user-modal',\n      title: 'Invite User Modal',\n      description:\n        'Invitation flow for adding a tenant member with a role assignment.',\n      loadComponent: loadInviteUserModal,\n      order: 3,\n      props: {\n        open: false,\n        tenant: sampleTenant,\n        roles: sampleRoles,\n        onsubmit: noop,\n        onclose: noop,\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'user-menu',\n      title: 'User Menu',\n      description:\n        'Authenticated account menu for profile, settings, and sign-out actions.',\n      loadComponent: loadUserMenu,\n      order: 4,\n      props: {\n        profile: sampleUsers[0].profile,\n        profileUrl: '/settings/profile',\n        settingsUrl: '/settings',\n        signoutUrl: '/auth/signout',\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n  ],\n};\n"],"names":[],"mappings":";AAEA,MAAM,OAAO,MAAM;AAAC;AAEpB,MAAM,eAAe;AAAA,EACnB,IAAI;AAAA,EACJ,MAAM;AAAA,EACN,MAAM;AAAA,EACN,QAAQ;AACV;AAEA,MAAM,cAAc;AAAA,EAClB;AAAA,IACE,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,IACN,aAAa;AAAA,EAAA;AAAA,EAEf;AAAA,IACE,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,IACN,aAAa;AAAA,EAAA;AAEjB;AAEA,MAAM,cAAc;AAAA,EAClB;AAAA,IACE,MAAM;AAAA,MACJ,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,QAAQ;AAAA,IAAA;AAAA,IAEV,SAAS;AAAA,MACP,IAAI;AAAA,MACJ,MAAM;AAAA,MACN,OAAO;AAAA,IAAA;AAAA,IAET,MAAM;AAAA,EAAA;AAAA,EAER;AAAA,IACE,MAAM;AAAA,MACJ,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,QAAQ;AAAA,IAAA;AAAA,IAEV,SAAS;AAAA,MACP,IAAI;AAAA,MACJ,MAAM;AAAA,MACN,OAAO;AAAA,IAAA;AAAA,IAET,MAAM;AAAA,EAAA;AAEV;AAEA,MAAM,sBAAsB,MAAM,OAAO,4CAAqC;AAC9E,MAAM,eAAe,MAAM,OAAO,qCAA8B;AAChE,MAAM,eAAe,MAAM,OAAO,qCAA8B;AAChE,MAAM,eAAe,MAAM,OAAO,qCAA8B;AAEhE,MAAA,aAAe;AAAA,EACb,aAAa;AAAA,EACb,aAAa,kBAAkB;AAAA,EAC/B,aAAa,kBAAkB;AAAA,EAC/B,YAAY;AAAA,EACZ,SAAS;AAAA,IACP;AAAA,MACE,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,aACE;AAAA,MACF,eAAe;AAAA,MACf,OAAO;AAAA,MACP,OAAO;AAAA,QACL,OAAO;AAAA,QACP,YAAY;AAAA,QACZ,UAAU;AAAA,MAAA;AAAA,MAEZ,OAAO;AAAA,QACL,MAAM;AAAA,UACJ,OAAO;AAAA,QAAA;AAAA,MACT;AAAA,IACF;AAAA,IAEF;AAAA,MACE,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,aAAa;AAAA,MACb,eAAe;AAAA,MACf,OAAO;AAAA,MACP,OAAO;AAAA,QACL,MAAM,YAAY,CAAC,EAAE;AAAA,QACrB,SAAS,YAAY,CAAC,EAAE;AAAA,QACxB,UAAU;AAAA,QACV,UAAU;AAAA,MAAA;AAAA,MAEZ,OAAO;AAAA,QACL,MAAM;AAAA,UACJ,OAAO;AAAA,QAAA;AAAA,MACT;AAAA,IACF;AAAA,IAEF;AAAA,MACE,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,aACE;AAAA,MACF,eAAe;AAAA,MACf,OAAO;AAAA,MACP,OAAO;AAAA,QACL,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,OAAO;AAAA,QACP,UAAU;AAAA,QACV,SAAS;AAAA,MAAA;AAAA,MAEX,OAAO;AAAA,QACL,MAAM;AAAA,UACJ,OAAO;AAAA,QAAA;AAAA,MACT;AAAA,IACF;AAAA,IAEF;AAAA,MACE,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,aACE;AAAA,MACF,eAAe;AAAA,MACf,OAAO;AAAA,MACP,OAAO;AAAA,QACL,SAAS,YAAY,CAAC,EAAE;AAAA,QACxB,YAAY;AAAA,QACZ,aAAa;AAAA,QACb,YAAY;AAAA,MAAA;AAAA,MAEd,OAAO;AAAA,QACL,MAAM;AAAA,UACJ,OAAO;AAAA,QAAA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AAEJ;"}

package/dist/services/MagicLinkService.d.ts

@@ -0,0 +1,84 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+/**
+ * Options for MagicLinkService
+ */
+export interface MagicLinkServiceOptions extends SmrtClassOptions {
+    /** Secret used to derive the HMAC signing key (required) */
+    secret: string;
+    /** Token expiry in seconds (default: 10 minutes) */
+    tokenExpiry?: number;
+    /** JWT issuer claim (default: 'smrt:magiclink') */
+    issuer?: string;
+}
+/**
+ * Result of generating a magic link token
+ */
+export interface MagicLinkResult {
+    /** The signed JWT token */
+    token: string;
+    /** When the token expires */
+    expiresAt: Date;
+}
+/**
+ * Result of verifying a magic link token
+ */
+export interface MagicLinkVerifyResult {
+    /** The email address from the token */
+    email: string;
+    /** The nonce (for correlation/logging) */
+    nonce: string;
+}
+/**
+ * Error class for magic link authentication failures
+ */
+export declare class MagicLinkError extends Error {
+    constructor(message: string);
+}
+/**
+ * MagicLinkService provides passwordless authentication via email magic links.
+ *
+ * Tokens are HMAC-signed JWTs with embedded nonces for replay protection.
+ * The service is framework-agnostic — it does not send emails or set cookies.
+ */
+export declare class MagicLinkService {
+    private tokenCollection;
+    private signingKey;
+    private readonly secret;
+    private readonly tokenExpiry;
+    private readonly issuer;
+    private readonly options;
+    constructor(options: MagicLinkServiceOptions);
+    /**
+     * Initialize collections
+     */
+    initialize(): Promise<void>;
+    /**
+     * Derive the HMAC signing key from the secret
+     */
+    private getSigningKey;
+    /**
+     * Generate a magic link token for the given email.
+     *
+     * Stores a nonce in the database for replay protection.
+     * The caller is responsible for emailing the token to the user.
+     */
+    generate(email: string): Promise<MagicLinkResult>;
+    /**
+     * Verify a magic link token.
+     *
+     * Checks JWT signature, expiry, and that the nonce hasn't been used.
+     * Marks the nonce as used on success (single-use enforcement).
+     *
+     * @throws {MagicLinkError} If the token is invalid, expired, or already used
+     */
+    verify(token: string): Promise<MagicLinkVerifyResult>;
+    /**
+     * Clean up expired tokens (run periodically)
+     */
+    cleanupExpiredTokens(): Promise<number>;
+    /**
+     * Static factory method
+     */
+    static create(options: MagicLinkServiceOptions): Promise<MagicLinkService>;
+}
+//# sourceMappingURL=MagicLinkService.d.ts.map

package/dist/services/MagicLinkService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MagicLinkService.d.ts","sourceRoot":"","sources":["../../src/services/MagicLinkService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKjE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,OAAO,EAAE,uBAAuB;IAU5C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;YACW,aAAa;IAW3B;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAoCvD;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAuC3D;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7C;;OAEG;WACU,MAAM,CACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC;CAK7B"}