Access Control

// convex/schema.ts
import { defineSchema } from "convex/server";
import { createVextroSchema } from "vextro/convex/schema";
import { posts, pages, media } from "./collections";

const vextro = createVextroSchema({
  collections: [posts, pages, media],
  globals: [],
  // accessControl is omitted — tables auto-generated with defaults
});

export { vextro };

export default defineSchema({
  ...vextro.tables,
  // Your own non-admin tables here
});

// convex/admin.ts
import { query, mutation } from "./_generated/server";
import { components } from "./_generated/api";
import { createVextroAdminModule } from "vextro/convex/admin";
import { vextro } from "./schema";

const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  globalDefinitions: vextro.globalDefinitions,
  // accessControl is omitted — default permissions/roles auto-injected
});

export const {
  listCollections,
  getCollectionBySlug,
  seedAdminMetadata,
  // ... all other exports including access control functions
  listRoles,
  listPermissions,
  listUsers,
  me,
  createRole,
  assignRoleToUser,
  syncAccessControl,
} = admin;

// convex/admin.ts
import { createVextroAdminModule } from "vextro/convex/admin";
import { defaultPermissions, defaultRoles } from "vextro/convex/accessControl";

const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  accessControl: {
    permissions: [
      ...defaultPermissions,
      { slug: "orders:read", description: "View orders" },
      { slug: "orders:manage", description: "Create, update, delete orders" },
      { slug: "reports:view", description: "View analytics reports" },
    ],
    roles: [
      ...defaultRoles,
      {
        slug: "sales-rep",
        name: "Sales Representative",
        description: "Order management and reporting",
        permissions: ["cms:read", "orders:read", "orders:manage", "reports:view"],
      },
      {
        slug: "analyst",
        name: "Analyst",
        description: "Read-only access with reports",
        permissions: ["cms:read", "reports:view"],
      },
    ],
  },
});

import { defineVextroAuth, okta, google } from "vextro/convex/authProviders";

export const authConfig = defineVextroAuth({
  appName: "My Admin",
  providers: [
    okta({ issuer: process.env.OKTA_ISSUER!, clientId: process.env.OKTA_CLIENT_ID!, clientSecret: process.env.OKTA_CLIENT_SECRET! }),
    google({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET! }),
  ],
});

// In schema.ts — provider fields auto-injected
import { createVextroSchema } from "vextro/convex/schema";

const vextro = createVextroSchema({
  collections: allCollections,
  globals: [],
  accessControl: {
    userFields: authConfig.providerMeta.userFields,
    userIndexes: authConfig.providerMeta.userIndexes,
  },
});

import { v } from "convex/values";
import { defineProvider } from "vextro/convex/authProviders";

const saml = defineProvider({
  id: "saml",
  userFields: { samlNameId: v.optional(v.string()) },
  userIndexes: [{ name: "by_samlNameId", fields: ["samlNameId"] }],
});

// convex/schema.ts
import { v } from "convex/values";
import { createVextroSchema } from "vextro/convex/schema";

const vextro = createVextroSchema({
  collections: [posts, pages, media],
  globals: [],
  accessControl: {
    userFields: {
      phone: v.optional(v.string()),
      department: v.optional(v.string()),
      hireDate: v.optional(v.number()),
      externalId: v.optional(v.string()),
    },
    userIndexes: [
      { name: "by_department", fields: ["department"] },
      { name: "by_externalId", fields: ["externalId"] },
    ],
  },
});

export default defineSchema({ ...vextro.tables });

// convex/schema.ts
const vextro = createVextroSchema({
  collections: [posts, pages, media],
  globals: [],
  accessControl: {
    tables: {
      users: "app_users",
      roles: "app_roles",
      permissions: "app_permissions",
      userRoles: "user_role_assignments",
      rolePermissions: "role_permission_grants",
      userScopes: "user_scope_assignments",
    },
  },
});

// convex/admin.ts
const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  accessControl: {
    permissions: [...defaultPermissions],
    roles: [...defaultRoles],
    tables: {
      users: "app_users",
      roles: "app_roles",
      permissions: "app_permissions",
      userRoles: "user_role_assignments",
      rolePermissions: "role_permission_grants",
      userScopes: "user_scope_assignments",
    },
  },
});

import { defineVextroCollection, f } from "vextro";

export const products = defineVextroCollection({
  label: "Products",
  collectionType: "content",
  tableName: "products",
  access: {
    read: "cms:read",
    create: "cms:edit",
    update: "cms:edit",
    delete: "cms:admin",
  },
  fields: {
    name: f.text({ required: true }),
    price: f.number({ required: true }),
    category: f.select({
      options: ["electronics", "clothing", "food"],
      required: true,
    }),
  },
});

access: {
  // Anyone with admin access can read
  // Only content-editors can create and update
  create: "cms:edit",
  update: "cms:edit",
  // Only admins can delete
  delete: "cms:admin",
},

import { defineVextroGlobal, f } from "vextro";

export const siteSettings = defineVextroGlobal({
  slug: "site-settings",
  label: "Site Settings",
  tableName: "site_settings",
  access: {
    read: "cms:read",
    update: "cms:admin",
  },
  fields: {
    siteName: f.text({ required: true }),
    maintenanceMode: f.checkbox(),
  },
});

fields: {
  name: f.text({ required: true }),
  salary: f.number({
    config: {
      readRoles: ["admin", "hr-manager"],
      writeRoles: ["admin"],
      hidden: true,
    },
  }),
  internalNotes: f.textarea({
    config: {
      writeRoles: ["admin", "editor"],
    },
  }),
}

// convex/lib/policy.ts
import { createPolicyHelpers } from "vextro/convex/policy";

export const {
  getCurrentUser,
  attachRolesAndPermissions,
  requireAuth,
  requireActiveUser,
  hasRole,
  hasAnyRole,
  hasAllRoles,
  requireRole,
  requireAnyRole,
  hasPermission,
  hasAnyPermission,
  hasAllPermissions,
  requirePermission,
  requireAnyPermission,
  AuthorizationError,
} = createPolicyHelpers();

const policy = createPolicyHelpers({
  usersTable: "app_users",
  rolesTable: "app_roles",
  permissionsTable: "app_permissions",
  userRolesTable: "user_role_assignments",
  rolePermissionsTable: "role_permission_grants",
});

// convex/myFunctions.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import {
  requirePermission,
  requireAnyRole,
  getCurrentUser,
  hasPermission,
} from "./lib/policy";

// Guard an entire function
export const deleteOrder = mutation({
  args: { orderId: v.id("orders") },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Throws AuthorizationError if user lacks permission
    await requirePermission(ctx, "orders:manage");
    await ctx.db.delete(args.orderId);
    return null;
  },
});

// Conditional logic based on permissions
export const getOrderDetails = query({
  args: { orderId: v.id("orders") },
  returns: v.any(),
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    if (!user) return null;

    const order = await ctx.db.get(args.orderId);
    if (!order) return null;

    // Strip sensitive fields for non-admins
    if (!hasPermission(user, "orders:manage")) {
      const { internalCost, supplierNotes, ...publicFields } = order;
      return publicFields;
    }

    return order;
  },
});

// convex/admin.ts
import { createVextroAdminModule } from "vextro/convex/admin";
import {
  getCurrentUser,
  requireAnyPermission,
  requirePermission,
} from "./lib/policy";

const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  getCurrentUser,
  requireAdminRead: async (ctx) => {
    await requireAnyPermission(ctx, ["cms:read", "cms:admin"]);
  },
  requireAdminWrite: async (ctx) => {
    await requirePermission(ctx, "cms:admin");
  },
  getUserRoles: async (ctx) => {
    const user = await getCurrentUser(ctx);
    if (!user) return [];
    // Return both role slugs and permission strings
    return [
      ...user.roles.map((r) => r.slug),
      ...user.permissions,
    ];
  },
});

// convex/schema.ts
const vextro = createVextroSchema({
  collections: [posts, pages, media],
  globals: [],
  accessControl: {
    enabled: false,
  },
});

// convex/admin.ts
const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  getCurrentUser: async (ctx) => {
    // Your own user lookup logic
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return null;
    return await ctx.db
      .query("members")
      .withIndex("by_authId", (q) => q.eq("authId", identity.subject))
      .unique();
  },
  getUserRoles: async (ctx) => {
    const user = await getCurrentUser(ctx);
    if (!user) return [];
    // Return role slugs from your own tables
    return user.roleSlugs;
  },
  accessControl: {
    permissions: [
      { slug: "cms:read", description: "View content" },
      { slug: "cms:write", description: "Edit content" },
    ],
    roles: [
      {
        slug: "admin",
        name: "Admin",
        permissions: ["cms:read", "cms:write"],
      },
    ],
    tables: {
      users: "members",
      roles: "member_roles",
      permissions: "member_permissions",
      userRoles: "member_role_assignments",
      rolePermissions: "member_role_permissions",
      userScopes: "member_scopes",
    },
  },
});

const admin = createVextroAdminModule({
  // ...
  requireAdminRead: async (ctx) => {
    await requireAnyPermission(ctx, ["cms:read", "cms:admin"]);
  },
  requireAdminWrite: async (ctx) => {
    await requirePermission(ctx, "cms:edit");
  },
  // Stricter guards for access control pages
  requireAccessControlRead: async (ctx) => {
    await requireAnyPermission(ctx, ["users:read", "roles:read", "cms:admin"]);
  },
  requireAccessControlWrite: async (ctx) => {
    await requireAnyPermission(ctx, ["users:manage", "roles:manage"]);
  },
});

export const {
  // Collection functions
  listCollections,
  getCollectionBySlug,
  seedAdminMetadata,
  // ... other collection functions

  // Access control functions
  listRoles,
  getRoleBySlug,
  getRoleById,
  getUsersForRole,
  listRolesWithCounts,
  listPermissions,
  me,
  getUserById,
  listUsers,
  listUsersWithRoles,
  getUserRolesForUser,
  listUserScopes,
  createRole,
  updateRole,
  deleteRole,
  addPermissionToRole,
  removePermissionFromRole,
  updateUserProfile,
  updateUserStatus,
  assignRoleToUser,
  removeRoleFromUser,
  assignUserScope,
  removeUserScope,
  syncAccessControl,
} = admin;

const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  onUserStatusChange: async (ctx, { userId, previousStatus, newStatus }) => {
    if (newStatus === "inactive") {
      // Delete all sessions for the deactivated user
      const sessions = await ctx.db
        .query("sessions")
        .withIndex("by_userId", (q) => q.eq("userId", userId))
        .collect();
      await Promise.all(sessions.map((s) => ctx.db.delete(s._id)));
    }
  },
});

// In your Vextro config
const config = {
  locale: {
    sidebar: {
      accessControl: "Team Management",
      users: "Members",
      roles: "Groups",
      permissions: "Capabilities",
    },
  },
};

// Auth user table is auto-generated by createVextroSchema

// Domain-specific profile as a regular collection
export const employeeProfiles = defineVextroCollection({
  label: "Employee Profiles",
  collectionType: "config",
  tableName: "employee_profiles",
  useAsTitle: "fullName",
  access: {
    read: "users:read",
    create: "users:manage",
    update: "users:manage",
    delete: "users:manage",
  },
  fields: {
    userId: f.relationship("users", { required: true }),
    fullName: f.text({ required: true }),
    jobTitle: f.text(),
    department: f.select({
      options: ["engineering", "marketing", "sales", "operations"],
      required: true,
    }),
    manager: f.relationship("employee_profiles"),
    startDate: f.date({ required: true }),
    bio: f.richText(),
  },
});

// Collection with scope filtering
export const storeProducts = defineVextroCollection({
  label: "Store Products",
  collectionType: "content",
  tableName: "store_products",
  scope: {
    field: "regionId",
    type: "region",
  },
  access: {
    read: "cms:read",
    create: "cms:edit",
    update: "cms:edit",
    delete: "cms:admin",
  },
  fields: {
    name: f.text({ required: true }),
    regionId: f.text({ required: true }),
    price: f.number({ required: true }),
    status: f.select({
      options: ["draft", "published", "scheduled", "trashed"],
      required: true,
    }),
  },
});

const admin = createVextroAdminModule({
  query,
  mutation,
  components,
  collectionDefinitions: vextro.collectionDefinitions,
  // ... auth callbacks
  getUserScopes: async (ctx, scopeType) => {
    if (scopeType !== "region") return null; // unrestricted
    const user = await getCurrentUser(ctx);
    if (!user) return [];
    // Admins see all regions
    if (hasPermission(user, "cms:admin")) return null;
    // Others see only their assigned regions
    const scopes = await ctx.db
      .query("userScopes")
      .withIndex("by_userId_and_scopeType", (q) =>
        q.eq("userId", user._id).eq("scopeType", "region")
      )
      .collect();
    return scopes.map((s) => s.scopeValue);
  },
  canAccessScope: async (ctx, scopeType, scopeValue) => {
    if (scopeType !== "region") return true;
    const user = await getCurrentUser(ctx);
    if (!user) return false;
    if (hasPermission(user, "cms:admin")) return true;
    const scope = await ctx.db
      .query("userScopes")
      .withIndex("by_userId_and_scopeType", (q) =>
        q.eq("userId", user._id).eq("scopeType", "region")
      )
      .collect();
    return scope.some((s) => s.scopeValue === scopeValue);
  },
  listScopeOptions: async (ctx, scopeType) => {
    if (scopeType !== "region") return [];
    const regions = await ctx.db.query("regions").collect();
    return regions.map((r) => ({
      id: String(r._id),
      label: r.name,
    }));
  },
});

export const invoices = defineVextroCollection({
  label: "Invoices",
  collectionType: "content",
  tableName: "invoices",
  hooks: {
    beforeChange: [
      async ({ data, ctx }) => {
        // Prevent editing finalized invoices
        if (data.status === "finalized") {
          throw new Error("Cannot edit a finalized invoice");
        }
      },
    ],
    beforeDelete: [
      async ({ doc }) => {
        // Only draft invoices can be deleted
        if (doc.status !== "draft") {
          throw new Error("Only draft invoices can be deleted");
        }
      },
    ],
  },
  fields: {
    amount: f.number({ required: true }),
    recipient: f.text({ required: true }),
    status: f.select({
      options: ["draft", "sent", "finalized"],
      required: true,
    }),
  },
});