@rovela-ai/sdk 0.2.0 → 0.3.0

package/dist/admin/permissions.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @rovela/sdk/admin/permissions
+ *
+ * Role-based permission matrix for store admins.
+ *
+ * # Four-role hierarchy (strict)
+ *
+ *   owner          (rank 0) can do everything, including managing other owners.
+ *                           Subject to "at least one active owner always exists".
+ *   administrator  (rank 1) can do everything except manage owners or other administrators.
+ *                           Prevents lateral privilege escalation.
+ *   manager        (rank 2) full day-to-day operational access (products, orders, customers,
+ *                           returns, refunds). Cannot touch settings, billing, or users.
+ *   user           (rank 3) read-only on most resources + write access to orders only
+ *                           (for warehouse/fulfillment staff updating tracking).
+ *
+ * # Legacy 'admin' role
+ *
+ * Stores created before the four-role system shipped have rows with role='admin'.
+ * We never rewrite those rows (Postgres enums can't remove values anyway). The
+ * permission map treats 'admin' as an alias for 'administrator' — same exact
+ * permission set, same `canManageUser` behavior.
+ *
+ * # Client vs server
+ *
+ * All checks in this file are pure functions over static data. They are safe to
+ * import from both server and client code. The server uses them as the source
+ * of truth for authorization; the client uses them for UX gating (hide/disable
+ * buttons). The client is always advisory — the server is the gate.
+ */
+import type { AdminRole } from '../core/types';
+/**
+ * Every action an admin can perform, grouped by resource. Adding a new
+ * permission here means:
+ *   1. Add it to this type union
+ *   2. Assign it to one or more roles in the PERMISSIONS map below
+ *   3. Reference it via `hasPermission(role, 'foo.bar')` at the relevant API handler
+ */
+export type Permission = 'products.read' | 'products.write' | 'products.delete' | 'orders.read' | 'orders.write' | 'orders.refund' | 'returns.approve' | 'returns.reject' | 'customers.read' | 'customers.write' | 'customers.delete' | 'settings.read' | 'settings.write' | 'billing.read' | 'billing.write' | 'users.read' | 'users.write' | 'users.delete';
+/**
+ * Returns true if `actorRole` is at least as powerful as `minRole`.
+ *
+ * @example
+ * meetsMinRole('owner', 'manager')  // true
+ * meetsMinRole('user', 'manager')   // false
+ */
+export declare function meetsMinRole(actorRole: AdminRole | null | undefined, minRole: AdminRole): boolean;
+/**
+ * Does this role have a specific permission?
+ *
+ * Safe to call with `undefined` / `null` actor — returns `false`, which is what
+ * unauthenticated requests want.
+ *
+ * @example
+ * hasPermission('owner', 'users.delete')          // true
+ * hasPermission('administrator', 'users.delete')  // false
+ * hasPermission(undefined, 'products.read')       // false
+ */
+export declare function hasPermission(role: AdminRole | null | undefined, permission: Permission): boolean;
+/**
+ * Can `actor` modify `target` as a user-management action?
+ *
+ * Rules:
+ *   - Owners can manage anyone, including other owners. The "at least one
+ *     active owner must remain" invariant is enforced separately at the
+ *     service layer, not here — this helper only answers "does the actor
+ *     have the authority in principle?"
+ *   - Administrators can manage managers and users only. They cannot touch
+ *     owners or other administrators. (Prevents lateral escalation.)
+ *   - Managers and users cannot manage anyone.
+ *   - Actor cannot manage themselves via this helper. Self-actions (password
+ *     change, profile update) go through /api/admin/me/* endpoints and have
+ *     their own rules.
+ */
+export declare function canManageUser(actor: {
+    id: string;
+    role: AdminRole;
+}, target: {
+    id: string;
+    role: AdminRole;
+}): boolean;
+/**
+ * Human-readable label for a role. Maps the legacy 'admin' to
+ * 'Administrator' so UI never leaks the old value.
+ */
+export declare function roleLabel(role: AdminRole): string;
+/**
+ * Canonical role for a given stored value. Collapses 'admin' → 'administrator'
+ * so callers don't need to think about the legacy alias.
+ */
+export declare function canonicalRole(role: AdminRole): Exclude<AdminRole, 'admin'>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/admin/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/admin/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAM9C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAElB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GAEjB,aAAa,GACb,cAAc,GACd,eAAe,GAEf,iBAAiB,GACjB,gBAAgB,GAEhB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAElB,eAAe,GACf,gBAAgB,GAEhB,cAAc,GACd,eAAe,GAEf,YAAY,GACZ,aAAa,GACb,cAAc,CAAA;AAmBlB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EACvC,OAAO,EAAE,SAAS,GACjB,OAAO,CAGT;AAoFD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EAClC,UAAU,EAAE,UAAU,GACrB,OAAO,CAIT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,EACtC,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACtC,OAAO,CAaT;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAYjD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAE1E"}

package/dist/admin/permissions.js

@@ -0,0 +1,201 @@
+/**
+ * @rovela/sdk/admin/permissions
+ *
+ * Role-based permission matrix for store admins.
+ *
+ * # Four-role hierarchy (strict)
+ *
+ *   owner          (rank 0) can do everything, including managing other owners.
+ *                           Subject to "at least one active owner always exists".
+ *   administrator  (rank 1) can do everything except manage owners or other administrators.
+ *                           Prevents lateral privilege escalation.
+ *   manager        (rank 2) full day-to-day operational access (products, orders, customers,
+ *                           returns, refunds). Cannot touch settings, billing, or users.
+ *   user           (rank 3) read-only on most resources + write access to orders only
+ *                           (for warehouse/fulfillment staff updating tracking).
+ *
+ * # Legacy 'admin' role
+ *
+ * Stores created before the four-role system shipped have rows with role='admin'.
+ * We never rewrite those rows (Postgres enums can't remove values anyway). The
+ * permission map treats 'admin' as an alias for 'administrator' — same exact
+ * permission set, same `canManageUser` behavior.
+ *
+ * # Client vs server
+ *
+ * All checks in this file are pure functions over static data. They are safe to
+ * import from both server and client code. The server uses them as the source
+ * of truth for authorization; the client uses them for UX gating (hide/disable
+ * buttons). The client is always advisory — the server is the gate.
+ */
+// =============================================================================
+// Role ranks + hierarchy helpers
+// =============================================================================
+/**
+ * Lower number = higher power. Used by `meetsMinRole` to enforce "must be at
+ * least an administrator" style checks. 'admin' is explicitly an alias for
+ * 'administrator' at rank 1.
+ */
+const ROLE_RANK = {
+    owner: 0,
+    administrator: 1,
+    admin: 1, // legacy alias — identical to 'administrator'
+    manager: 2,
+    user: 3,
+};
+/**
+ * Returns true if `actorRole` is at least as powerful as `minRole`.
+ *
+ * @example
+ * meetsMinRole('owner', 'manager')  // true
+ * meetsMinRole('user', 'manager')   // false
+ */
+export function meetsMinRole(actorRole, minRole) {
+    if (!actorRole)
+        return false;
+    return ROLE_RANK[actorRole] <= ROLE_RANK[minRole];
+}
+// =============================================================================
+// Permission matrix
+// =============================================================================
+const OWNER_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'products.delete',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'customers.delete',
+    'settings.read',
+    'settings.write',
+    'billing.read',
+    'billing.write',
+    'users.read',
+    'users.write',
+    'users.delete',
+];
+const ADMINISTRATOR_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'products.delete',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'customers.delete',
+    'settings.read',
+    'settings.write',
+    'billing.read',
+    'billing.write',
+    'users.read',
+    'users.write',
+    // NOTE: 'users.delete' is intentionally owner-only. Administrators can
+    // deactivate (via users.write + canManageUser) but not hard-delete.
+];
+const MANAGER_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'settings.read',
+];
+const USER_PERMISSIONS = [
+    'products.read',
+    'orders.read',
+    'orders.write', // fulfillment staff update tracking/status
+];
+/**
+ * The canonical permission map. Each role points at a Set<Permission> for O(1)
+ * membership checks. 'admin' shares the administrator set (legacy alias).
+ */
+const PERMISSIONS = {
+    owner: new Set(OWNER_PERMISSIONS),
+    administrator: new Set(ADMINISTRATOR_PERMISSIONS),
+    admin: new Set(ADMINISTRATOR_PERMISSIONS), // legacy alias
+    manager: new Set(MANAGER_PERMISSIONS),
+    user: new Set(USER_PERMISSIONS),
+};
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Does this role have a specific permission?
+ *
+ * Safe to call with `undefined` / `null` actor — returns `false`, which is what
+ * unauthenticated requests want.
+ *
+ * @example
+ * hasPermission('owner', 'users.delete')          // true
+ * hasPermission('administrator', 'users.delete')  // false
+ * hasPermission(undefined, 'products.read')       // false
+ */
+export function hasPermission(role, permission) {
+    if (!role)
+        return false;
+    const perms = PERMISSIONS[role];
+    return perms ? perms.has(permission) : false;
+}
+/**
+ * Can `actor` modify `target` as a user-management action?
+ *
+ * Rules:
+ *   - Owners can manage anyone, including other owners. The "at least one
+ *     active owner must remain" invariant is enforced separately at the
+ *     service layer, not here — this helper only answers "does the actor
+ *     have the authority in principle?"
+ *   - Administrators can manage managers and users only. They cannot touch
+ *     owners or other administrators. (Prevents lateral escalation.)
+ *   - Managers and users cannot manage anyone.
+ *   - Actor cannot manage themselves via this helper. Self-actions (password
+ *     change, profile update) go through /api/admin/me/* endpoints and have
+ *     their own rules.
+ */
+export function canManageUser(actor, target) {
+    // No self-management through this helper.
+    if (actor.id === target.id)
+        return false;
+    if (actor.role === 'owner') {
+        return true;
+    }
+    if (actor.role === 'administrator' || actor.role === 'admin') {
+        return target.role === 'manager' || target.role === 'user';
+    }
+    return false;
+}
+/**
+ * Human-readable label for a role. Maps the legacy 'admin' to
+ * 'Administrator' so UI never leaks the old value.
+ */
+export function roleLabel(role) {
+    switch (role) {
+        case 'owner':
+            return 'Owner';
+        case 'admin':
+        case 'administrator':
+            return 'Administrator';
+        case 'manager':
+            return 'Manager';
+        case 'user':
+            return 'User';
+    }
+}
+/**
+ * Canonical role for a given stored value. Collapses 'admin' → 'administrator'
+ * so callers don't need to think about the legacy alias.
+ */
+export function canonicalRole(role) {
+    return role === 'admin' ? 'administrator' : role;
+}
+//# sourceMappingURL=permissions.js.map

package/dist/admin/permissions.js.map

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

package/dist/admin/server/admin-invite.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @rovela/sdk/admin/server/admin-invite
+ *
+ * Admin invite token lifecycle: validation, acceptance, and housekeeping.
+ *
+ * Paired with `user-management.ts::inviteAdmin` which creates the token +
+ * sends the email. This file handles the INVITEE's side of the flow: they
+ * click the email link, land on `/admin/accept-invite?token=X`, and this
+ * module validates + consumes the token.
+ *
+ * # Failure modes (all graceful — no exceptions leak out)
+ *
+ *   - Token unknown            → `{valid: false}` / `INVALID_TOKEN`
+ *   - Token expired            → delete row, return `{valid: false}` with "expired"
+ *   - Admin deleted            → cascaded delete already removed the token;
+ *                                caller will see `{valid: false}`
+ *   - Admin already accepted   → `{valid: false}` with "already accepted"
+ *                                (protects against double-clicks)
+ *   - Admin was deactivated    → same as "already accepted" from UX point of view
+ *   - Concurrent acceptance    → atomic UPDATE returns 0 rows → `INVALID_STATE`
+ *
+ * # Design notes
+ *
+ * The structure mirrors `admin-password-reset.ts` from Phase 1 exactly:
+ *   1. `validate*` is non-destructive (opportunistically cleans up expired
+ *      tokens but doesn't touch the admin row).
+ *   2. `accept*` is destructive — it updates the password, flips status,
+ *      and deletes ALL tokens for the admin (both invite + reset tokens,
+ *      so a stale reset link can't resurrect access).
+ *   3. `delete*ForAdmin` helper used by `cancelInvite` / `resendInvite` to
+ *      wipe stale tokens before issuing a new one.
+ *   4. `cleanupExpired` is an optional cron hook.
+ */
+import type { AdminRole } from '../../core/types';
+/**
+ * Invite token lifetime: 72 hours. Matches industry standard
+ * (Google Workspace, GitHub, Shopify).
+ */
+export declare const INVITE_EXPIRY_MS: number;
+/** Token length — nanoid(32) = ~192 bits of entropy, URL-safe. */
+export declare const INVITE_TOKEN_LENGTH = 32;
+/** Display string for the expiry duration. */
+export declare const INVITE_EXPIRY_HOURS = "72";
+export interface AdminInviteSnapshot {
+    id: string;
+    email: string;
+    name: string;
+    role: AdminRole;
+}
+export interface ValidateInviteResult {
+    valid: boolean;
+    error?: string;
+    admin?: AdminInviteSnapshot;
+}
+export interface AcceptInviteResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Create a new invite token for an existing `invited` admin row.
+ *
+ * The caller is responsible for:
+ *   - Validating the admin exists and is in `invited` status
+ *   - Deleting any existing invite tokens for this admin (via
+ *     `deleteAdminInviteTokens`) before calling this to keep "one active
+ *     token" semantics
+ *
+ * @returns The plain-text token that should be embedded in the email link.
+ */
+export declare function createInviteToken(params: {
+    adminId: string;
+    invitedBy: string;
+}): Promise<{
+    token: string;
+    expires: Date;
+}>;
+/**
+ * Validate an invite token without consuming it.
+ *
+ * Used by the accept-invite page on mount to decide between rendering the
+ * password form or an "invalid/expired" error view.
+ *
+ * Side effect: expired tokens are opportunistically deleted as part of the
+ * check. All other failure modes leave the DB untouched.
+ */
+export declare function validateInviteToken(token: string): Promise<ValidateInviteResult>;
+/**
+ * Consume an invite token and activate the invited admin.
+ *
+ * Atomically:
+ *   1. Validates the token + admin row.
+ *   2. Hashes + stores the new password via the existing
+ *      `updateAdminPassword` helper.
+ *   3. Flips status from 'invited' → 'active' via an atomic guarded UPDATE
+ *      (if two clicks race, the second one fails with INVALID_STATE).
+ *   4. Deletes all invite tokens for this admin (single-use batch).
+ *   5. Defensively deletes any stale password reset tokens too — a
+ *      previously abandoned reset flow shouldn't grant access after the
+ *      user has taken ownership of the account via accept-invite.
+ */
+export declare function acceptAdminInvite(token: string, newPassword: string): Promise<AcceptInviteResult>;
+/**
+ * Delete all invite tokens for a specific admin.
+ *
+ * Called from:
+ *   - `user-management.ts::inviteAdmin` — not called; the admin is newly
+ *     created so there are no tokens to delete
+ *   - `user-management.ts::resendAdminInvite` — clear stale tokens before
+ *     creating a new one
+ *   - `acceptAdminInvite` above — invalidate the used batch
+ *   - `user-management.ts::cancelAdminInvite` — cascade handles this
+ *     automatically via FK, but we call explicitly for clarity
+ */
+export declare function deleteAdminInviteTokens(adminId: string): Promise<void>;
+/**
+ * Delete all expired invite tokens. Optional hook for a periodic cleanup
+ * job. Safe to call anytime — no-op if nothing is expired.
+ *
+ * @returns Number of tokens deleted
+ */
+export declare function cleanupExpiredInviteTokens(): Promise<number>;
+//# sourceMappingURL=admin-invite.d.ts.map

package/dist/admin/server/admin-invite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-invite.d.ts","sourceRoot":"","sources":["../../../src/admin/server/admin-invite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAMjD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAsB,CAAA;AAEnD,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,OAAO,CAAA;AAMvC,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAa5C;AAMD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,CAAC,CA+D/B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CA8C7B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5E;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAOlE"}

package/dist/admin/server/admin-invite.js

@@ -0,0 +1,235 @@
+/**
+ * @rovela/sdk/admin/server/admin-invite
+ *
+ * Admin invite token lifecycle: validation, acceptance, and housekeeping.
+ *
+ * Paired with `user-management.ts::inviteAdmin` which creates the token +
+ * sends the email. This file handles the INVITEE's side of the flow: they
+ * click the email link, land on `/admin/accept-invite?token=X`, and this
+ * module validates + consumes the token.
+ *
+ * # Failure modes (all graceful — no exceptions leak out)
+ *
+ *   - Token unknown            → `{valid: false}` / `INVALID_TOKEN`
+ *   - Token expired            → delete row, return `{valid: false}` with "expired"
+ *   - Admin deleted            → cascaded delete already removed the token;
+ *                                caller will see `{valid: false}`
+ *   - Admin already accepted   → `{valid: false}` with "already accepted"
+ *                                (protects against double-clicks)
+ *   - Admin was deactivated    → same as "already accepted" from UX point of view
+ *   - Concurrent acceptance    → atomic UPDATE returns 0 rows → `INVALID_STATE`
+ *
+ * # Design notes
+ *
+ * The structure mirrors `admin-password-reset.ts` from Phase 1 exactly:
+ *   1. `validate*` is non-destructive (opportunistically cleans up expired
+ *      tokens but doesn't touch the admin row).
+ *   2. `accept*` is destructive — it updates the password, flips status,
+ *      and deletes ALL tokens for the admin (both invite + reset tokens,
+ *      so a stale reset link can't resurrect access).
+ *   3. `delete*ForAdmin` helper used by `cancelInvite` / `resendInvite` to
+ *      wipe stale tokens before issuing a new one.
+ *   4. `cleanupExpired` is an optional cron hook.
+ */
+import { eq, lt } from 'drizzle-orm';
+import { nanoid } from 'nanoid';
+import { getDb } from '../../core/db/client';
+import * as schema from '../../core/db/schema';
+import { findAdminById, updateAdminPassword } from './admin-service';
+import { deleteAdminPasswordResetTokens } from './admin-password-reset';
+import { validatePassword } from '../../auth/server/password';
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Invite token lifetime: 72 hours. Matches industry standard
+ * (Google Workspace, GitHub, Shopify).
+ */
+export const INVITE_EXPIRY_MS = 72 * 60 * 60 * 1000;
+/** Token length — nanoid(32) = ~192 bits of entropy, URL-safe. */
+export const INVITE_TOKEN_LENGTH = 32;
+/** Display string for the expiry duration. */
+export const INVITE_EXPIRY_HOURS = '72';
+// =============================================================================
+// Token creation (used by inviteAdmin + resendAdminInvite in user-management.ts)
+// =============================================================================
+/**
+ * Create a new invite token for an existing `invited` admin row.
+ *
+ * The caller is responsible for:
+ *   - Validating the admin exists and is in `invited` status
+ *   - Deleting any existing invite tokens for this admin (via
+ *     `deleteAdminInviteTokens`) before calling this to keep "one active
+ *     token" semantics
+ *
+ * @returns The plain-text token that should be embedded in the email link.
+ */
+export async function createInviteToken(params) {
+    const db = getDb();
+    const token = nanoid(INVITE_TOKEN_LENGTH);
+    const expires = new Date(Date.now() + INVITE_EXPIRY_MS);
+    await db.insert(schema.adminInviteTokens).values({
+        adminId: params.adminId,
+        token,
+        expires,
+        invitedBy: params.invitedBy,
+    });
+    return { token, expires };
+}
+// =============================================================================
+// Validate (non-destructive)
+// =============================================================================
+/**
+ * Validate an invite token without consuming it.
+ *
+ * Used by the accept-invite page on mount to decide between rendering the
+ * password form or an "invalid/expired" error view.
+ *
+ * Side effect: expired tokens are opportunistically deleted as part of the
+ * check. All other failure modes leave the DB untouched.
+ */
+export async function validateInviteToken(token) {
+    if (!token) {
+        return {
+            valid: false,
+            error: 'Invite link is missing a token. Please request a new invite.',
+        };
+    }
+    const db = getDb();
+    const [record] = await db
+        .select()
+        .from(schema.adminInviteTokens)
+        .where(eq(schema.adminInviteTokens.token, token))
+        .limit(1);
+    if (!record) {
+        return {
+            valid: false,
+            error: 'Invalid or expired invite link. Please request a new one.',
+        };
+    }
+    if (new Date() > record.expires) {
+        // Opportunistic cleanup
+        await db
+            .delete(schema.adminInviteTokens)
+            .where(eq(schema.adminInviteTokens.id, record.id));
+        return {
+            valid: false,
+            error: 'Invite link has expired. Please request a new one.',
+        };
+    }
+    const admin = await findAdminById(record.adminId);
+    if (!admin) {
+        // Cascaded delete should have prevented this — defensive
+        return {
+            valid: false,
+            error: 'Invalid or expired invite link. Please request a new one.',
+        };
+    }
+    if (admin.status !== 'invited') {
+        return {
+            valid: false,
+            error: admin.status === 'active'
+                ? 'This invite has already been accepted. Please sign in with your password.'
+                : 'This invite is no longer valid.',
+        };
+    }
+    return {
+        valid: true,
+        admin: {
+            id: admin.id,
+            email: admin.email,
+            name: admin.name,
+            role: admin.role,
+        },
+    };
+}
+// =============================================================================
+// Accept (destructive — consumes token, activates admin)
+// =============================================================================
+/**
+ * Consume an invite token and activate the invited admin.
+ *
+ * Atomically:
+ *   1. Validates the token + admin row.
+ *   2. Hashes + stores the new password via the existing
+ *      `updateAdminPassword` helper.
+ *   3. Flips status from 'invited' → 'active' via an atomic guarded UPDATE
+ *      (if two clicks race, the second one fails with INVALID_STATE).
+ *   4. Deletes all invite tokens for this admin (single-use batch).
+ *   5. Defensively deletes any stale password reset tokens too — a
+ *      previously abandoned reset flow shouldn't grant access after the
+ *      user has taken ownership of the account via accept-invite.
+ */
+export async function acceptAdminInvite(token, newPassword) {
+    // 1. Re-validate (fresh read — the validate* function is idempotent)
+    const validation = await validateInviteToken(token);
+    if (!validation.valid || !validation.admin) {
+        return {
+            success: false,
+            error: validation.error || 'Invalid or expired invite link.',
+        };
+    }
+    const adminId = validation.admin.id;
+    // 2. Password strength check
+    const passwordCheck = validatePassword(newPassword);
+    if (!passwordCheck.valid) {
+        return { success: false, error: passwordCheck.error };
+    }
+    const db = getDb();
+    // 3. Hash + store password (updateAdminPassword handles hashing internally)
+    await updateAdminPassword(adminId, newPassword);
+    // 4. Flip status — guarded so a concurrent accept gets rejected cleanly
+    const statusUpdate = await db
+        .update(schema.storeAdmins)
+        .set({ status: 'active' })
+        .where(eq(schema.storeAdmins.id, adminId))
+        .returning({ id: schema.storeAdmins.id, status: schema.storeAdmins.status });
+    if (statusUpdate.length === 0) {
+        // Target was deleted between validate and update — race condition
+        return {
+            success: false,
+            error: 'Admin state changed while accepting invite. Please try again.',
+        };
+    }
+    // 5. Wipe all invite tokens for this admin (single-use batch)
+    await deleteAdminInviteTokens(adminId);
+    // 6. Defensive: wipe any stale password reset tokens too
+    await deleteAdminPasswordResetTokens(adminId);
+    return { success: true };
+}
+// =============================================================================
+// Housekeeping
+// =============================================================================
+/**
+ * Delete all invite tokens for a specific admin.
+ *
+ * Called from:
+ *   - `user-management.ts::inviteAdmin` — not called; the admin is newly
+ *     created so there are no tokens to delete
+ *   - `user-management.ts::resendAdminInvite` — clear stale tokens before
+ *     creating a new one
+ *   - `acceptAdminInvite` above — invalidate the used batch
+ *   - `user-management.ts::cancelAdminInvite` — cascade handles this
+ *     automatically via FK, but we call explicitly for clarity
+ */
+export async function deleteAdminInviteTokens(adminId) {
+    const db = getDb();
+    await db
+        .delete(schema.adminInviteTokens)
+        .where(eq(schema.adminInviteTokens.adminId, adminId));
+}
+/**
+ * Delete all expired invite tokens. Optional hook for a periodic cleanup
+ * job. Safe to call anytime — no-op if nothing is expired.
+ *
+ * @returns Number of tokens deleted
+ */
+export async function cleanupExpiredInviteTokens() {
+    const db = getDb();
+    const result = await db
+        .delete(schema.adminInviteTokens)
+        .where(lt(schema.adminInviteTokens.expires, new Date()))
+        .returning({ id: schema.adminInviteTokens.id });
+    return result.length;
+}
+//# sourceMappingURL=admin-invite.js.map

package/dist/admin/server/admin-invite.js.map

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