@hilbras/keystone 1.1.0

package/src/services/organizations.ts

@@ -0,0 +1,171 @@
+import { eq, and, sql } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { organizations, orgMemberships, users, type Organization, type OrgMembership } from "../db/schema.js";
+
+export type OrgRole = "owner" | "admin" | "member";
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+}
+
+export async function createOrganization(input: {
+  name: string;
+  slug?: string;
+  plan?: string;
+}): Promise<Organization> {
+  const baseSlug = input.slug || slugify(input.name);
+  const slug = await ensureUniqueSlug(baseSlug);
+
+  const [org] = await db
+    .insert(organizations)
+    .values({
+      name: input.name,
+      slug,
+      plan: input.plan || "free",
+    })
+    .returning();
+  return org;
+}
+
+export async function findOrganizationById(id: string): Promise<Organization | undefined> {
+  const [org] = await db.select().from(organizations).where(eq(organizations.id, id)).limit(1);
+  return org;
+}
+
+export async function findOrganizationBySlug(slug: string): Promise<Organization | undefined> {
+  const [org] = await db.select().from(organizations).where(eq(organizations.slug, slug)).limit(1);
+  return org;
+}
+
+export async function findOrganizationsByUserId(userId: string): Promise<Organization[]> {
+  const rows = await db
+    .select({ org: organizations })
+    .from(orgMemberships)
+    .where(eq(orgMemberships.userId, userId))
+    .innerJoin(organizations, eq(orgMemberships.orgId, organizations.id));
+  return rows.map((r) => r.org);
+}
+
+export async function addOrgMembership(input: {
+  orgId: string;
+  userId: string;
+  role: OrgRole;
+}): Promise<OrgMembership> {
+  const [membership] = await db
+    .insert(orgMemberships)
+    .values({
+      orgId: input.orgId,
+      userId: input.userId,
+      role: input.role,
+    })
+    .onConflictDoNothing({ target: [orgMemberships.orgId, orgMemberships.userId] })
+    .returning();
+
+  if (membership) return membership;
+
+  const [existing] = await db
+    .select()
+    .from(orgMemberships)
+    .where(and(eq(orgMemberships.orgId, input.orgId), eq(orgMemberships.userId, input.userId)))
+    .limit(1);
+  return existing;
+}
+
+export async function findMembership(
+  orgId: string,
+  userId: string
+): Promise<OrgMembership | undefined> {
+  const [membership] = await db
+    .select()
+    .from(orgMemberships)
+    .where(and(eq(orgMemberships.orgId, orgId), eq(orgMemberships.userId, userId)))
+    .limit(1);
+  return membership;
+}
+
+export async function updateMembershipRole(
+  orgId: string,
+  userId: string,
+  role: OrgRole
+): Promise<OrgMembership | undefined> {
+  const [updated] = await db
+    .update(orgMemberships)
+    .set({ role, updatedAt: sql`now()` })
+    .where(and(eq(orgMemberships.orgId, orgId), eq(orgMemberships.userId, userId)))
+    .returning();
+  return updated;
+}
+
+export async function removeMembership(orgId: string, userId: string): Promise<boolean> {
+  const deleted = await db
+    .delete(orgMemberships)
+    .where(and(eq(orgMemberships.orgId, orgId), eq(orgMemberships.userId, userId)))
+    .returning();
+  return deleted.length > 0;
+}
+
+export async function countOwners(orgId: string): Promise<number> {
+  const rows = await db
+    .select({ count: sql<number>`count(*)`.mapWith(Number) })
+    .from(orgMemberships)
+    .where(and(eq(orgMemberships.orgId, orgId), eq(orgMemberships.role, "owner")));
+  return rows[0]?.count ?? 0;
+}
+
+export async function requireOrgRole(
+  userId: string,
+  orgId: string,
+  allowedRoles: OrgRole[]
+): Promise<OrgMembership> {
+  const membership = await findMembership(orgId, userId);
+  if (!membership) {
+    const error = new Error("Not a member of this organization") as Error & { statusCode: number };
+    error.statusCode = 403;
+    throw error;
+  }
+  if (!allowedRoles.includes(membership.role as OrgRole)) {
+    const error = new Error("Insufficient organization permissions") as Error & {
+      statusCode: number;
+    };
+    error.statusCode = 403;
+    throw error;
+  }
+  return membership;
+}
+
+export async function listOrgMembers(orgId: string) {
+  return db
+    .select({
+      membership: orgMemberships,
+      user: {
+        id: users.id,
+        email: users.email,
+        username: users.username,
+        name: users.name,
+        avatarUrl: users.avatarUrl,
+      },
+    })
+    .from(orgMemberships)
+    .where(eq(orgMemberships.orgId, orgId))
+    .innerJoin(users, eq(orgMemberships.userId, users.id));
+}
+
+async function ensureUniqueSlug(base: string): Promise<string> {
+  let slug = base || "org";
+  let counter = 2;
+  while (true) {
+    const existing = await db
+      .select({ id: organizations.id })
+      .from(organizations)
+      .where(eq(organizations.slug, slug))
+      .limit(1);
+    if (existing.length === 0) return slug;
+    slug = `${base}-${counter}`;
+    counter++;
+  }
+}

package/src/services/permissions.ts

@@ -0,0 +1,146 @@
+import { eq, and, inArray } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { permissions, rolePermissions, type Permission } from "../db/schema.js";
+
+export type PermissionInput = {
+  resource: string;
+  action: string;
+};
+
+export const DEFAULT_PERMISSIONS: PermissionInput[] = [
+  { resource: "organization", action: "read" },
+  { resource: "organization", action: "update" },
+  { resource: "organization", action: "delete" },
+  { resource: "organization", action: "invite" },
+  { resource: "organization", action: "manage_members" },
+  { resource: "application", action: "read" },
+  { resource: "application", action: "create" },
+  { resource: "application", action: "update" },
+  { resource: "application", action: "delete" },
+  { resource: "service_account", action: "read" },
+  { resource: "service_account", action: "create" },
+  { resource: "service_account", action: "update" },
+  { resource: "service_account", action: "delete" },
+  { resource: "api_key", action: "read" },
+  { resource: "api_key", action: "create" },
+  { resource: "api_key", action: "revoke" },
+  { resource: "audit_log", action: "read" },
+];
+
+export const DEFAULT_ROLE_PERMISSIONS: Record<string, string[]> = {
+  owner: DEFAULT_PERMISSIONS.map((p) => `${p.resource}:${p.action}`),
+  admin: [
+    "organization:read",
+    "organization:update",
+    "organization:invite",
+    "organization:manage_members",
+    "application:read",
+    "application:create",
+    "application:update",
+    "service_account:read",
+    "service_account:create",
+    "service_account:update",
+    "api_key:read",
+    "api_key:create",
+    "api_key:revoke",
+    "audit_log:read",
+  ],
+  member: [
+    "organization:read",
+    "application:read",
+    "service_account:read",
+    "api_key:read",
+  ],
+  viewer: ["organization:read", "application:read", "audit_log:read"],
+};
+
+export function permissionKey(resource: string, action: string): string {
+  return `${resource}:${action}`;
+}
+
+export async function ensurePermissionsSeeded(): Promise<void> {
+  const existing = await db.select().from(permissions);
+  const existingKeys = new Set(existing.map((p) => permissionKey(p.resource, p.action)));
+
+  const toInsert = DEFAULT_PERMISSIONS.filter(
+    (p) => !existingKeys.has(permissionKey(p.resource, p.action))
+  );
+
+  if (toInsert.length > 0) {
+    await db.insert(permissions).values(toInsert);
+  }
+}
+
+export async function ensureRolePermissionsSeeded(): Promise<void> {
+  await ensurePermissionsSeeded();
+  const allPermissions = await db.select().from(permissions);
+  const permissionByKey = new Map(allPermissions.map((p) => [permissionKey(p.resource, p.action), p.id]));
+
+  for (const [role, perms] of Object.entries(DEFAULT_ROLE_PERMISSIONS)) {
+    const permissionIds = perms
+      .map((key) => permissionByKey.get(key))
+      .filter((id): id is string => Boolean(id));
+
+    for (const permissionId of permissionIds) {
+      await db
+        .insert(rolePermissions)
+        .values({ role, permissionId })
+        .onConflictDoNothing({ target: [rolePermissions.role, rolePermissions.permissionId] });
+    }
+  }
+}
+
+export async function listPermissions(): Promise<Permission[]> {
+  return db.select().from(permissions).orderBy(permissions.resource, permissions.action);
+}
+
+export async function listPermissionsForRole(role: string): Promise<Permission[]> {
+  const rows = await db
+    .select({ permission: permissions })
+    .from(rolePermissions)
+    .where(eq(rolePermissions.role, role))
+    .innerJoin(permissions, eq(rolePermissions.permissionId, permissions.id));
+  return rows.map((r) => r.permission);
+}
+
+export async function listPermissionKeysForRole(role: string): Promise<Set<string>> {
+  const perms = await listPermissionsForRole(role);
+  return new Set(perms.map((p) => permissionKey(p.resource, p.action)));
+}
+
+export async function assignPermissionToRole(role: string, permissionId: string): Promise<void> {
+  await db
+    .insert(rolePermissions)
+    .values({ role, permissionId })
+    .onConflictDoNothing({ target: [rolePermissions.role, rolePermissions.permissionId] });
+}
+
+export async function removePermissionFromRole(role: string, permissionId: string): Promise<void> {
+  await db
+    .delete(rolePermissions)
+    .where(and(eq(rolePermissions.role, role), eq(rolePermissions.permissionId, permissionId)));
+}
+
+export async function hasPermission(role: string, resource: string, action: string): Promise<boolean> {
+  const key = permissionKey(resource, action);
+  const keys = await listPermissionKeysForRole(role);
+  return keys.has(key);
+}
+
+export async function hasAnyPermission(role: string, required: PermissionInput[]): Promise<boolean> {
+  const keys = await listPermissionKeysForRole(role);
+  return required.some((p) => keys.has(permissionKey(p.resource, p.action)));
+}
+
+export async function requirePermission(
+  role: string,
+  resource: string,
+  action: string
+): Promise<void> {
+  const allowed = await hasPermission(role, resource, action);
+  if (!allowed) {
+    const error = new Error(`Missing permission ${resource}:${action}`) as Error & { statusCode: number };
+    error.statusCode = 403;
+    throw error;
+  }
+}

package/src/services/plugins/registry.ts

@@ -0,0 +1,242 @@
+import type {
+  KeystonePlugin,
+  PluginMetadata,
+  WorkflowStepExecutor,
+  AuthenticationMethod,
+  AnalyticsProvider,
+  BillingProvider,
+  AuthorizationPolicy,
+  RegisteredPluginSummary,
+  ExtensionPointSummary,
+} from "./types.js";
+import type { IdentityConnector } from "../connectors/types.js";
+import type { EmailProvider } from "../email.js";
+import type { SmsProvider } from "../sms.js";
+
+const plugins: KeystonePlugin[] = [];
+const connectorFactories = new Map<string, (config?: Record<string, unknown>) => IdentityConnector>();
+const workflowStepExecutors = new Map<string, WorkflowStepExecutor>();
+const authenticationMethodFactories = new Map<string, (config?: Record<string, unknown>) => AuthenticationMethod>();
+const analyticsProviderFactories = new Map<string, (config?: Record<string, unknown>) => AnalyticsProvider>();
+const billingProviderFactories = new Map<string, (config?: Record<string, unknown>) => BillingProvider>();
+const authorizationPolicyFactories = new Map<string, (config?: Record<string, unknown>) => AuthorizationPolicy>();
+let emailProvider: EmailProvider | undefined;
+let smsProvider: SmsProvider | undefined;
+
+function collectExtensionPoints(plugin: KeystonePlugin): string[] {
+  const points: string[] = [];
+  if (plugin.connectors) points.push("connectors");
+  if (plugin.emailProvider) points.push("emailProvider");
+  if (plugin.smsProvider) points.push("smsProvider");
+  if (plugin.workflowSteps) points.push("workflowSteps");
+  if (plugin.authenticationMethods) points.push("authenticationMethods");
+  if (plugin.analyticsProviders) points.push("analyticsProviders");
+  if (plugin.billingProviders) points.push("billingProviders");
+  if (plugin.authorizationPolicies) points.push("authorizationPolicies");
+  return points;
+}
+
+export function registerPlugin(plugin: KeystonePlugin): void {
+  plugins.push(plugin);
+
+  if (plugin.connectors) {
+    for (const [type, factory] of Object.entries(plugin.connectors)) {
+      connectorFactories.set(type, factory);
+    }
+  }
+
+  if (plugin.emailProvider) {
+    emailProvider = plugin.emailProvider;
+  }
+
+  if (plugin.smsProvider) {
+    smsProvider = plugin.smsProvider;
+  }
+
+  if (plugin.workflowSteps) {
+    for (const [type, executor] of Object.entries(plugin.workflowSteps)) {
+      workflowStepExecutors.set(type, executor);
+    }
+  }
+
+  if (plugin.authenticationMethods) {
+    for (const [type, factory] of Object.entries(plugin.authenticationMethods)) {
+      authenticationMethodFactories.set(type, factory);
+    }
+  }
+
+  if (plugin.analyticsProviders) {
+    for (const [type, factory] of Object.entries(plugin.analyticsProviders)) {
+      analyticsProviderFactories.set(type, factory);
+    }
+  }
+
+  if (plugin.billingProviders) {
+    for (const [type, factory] of Object.entries(plugin.billingProviders)) {
+      billingProviderFactories.set(type, factory);
+    }
+  }
+
+  if (plugin.authorizationPolicies) {
+    for (const [type, factory] of Object.entries(plugin.authorizationPolicies)) {
+      authorizationPolicyFactories.set(type, factory);
+    }
+  }
+
+  if (plugin.onRegister) {
+    Promise.resolve(plugin.onRegister()).catch((err) => {
+      console.error(`Plugin ${plugin.metadata.name} onRegister failed:`, err);
+    });
+  }
+}
+
+export function unregisterPlugin(name: string): boolean {
+  const index = plugins.findIndex((p) => p.metadata.name === name);
+  if (index === -1) return false;
+
+  const [plugin] = plugins.splice(index, 1);
+
+  if (plugin.connectors) {
+    for (const type of Object.keys(plugin.connectors)) {
+      connectorFactories.delete(type);
+    }
+  }
+
+  if (plugin.workflowSteps) {
+    for (const type of Object.keys(plugin.workflowSteps)) {
+      workflowStepExecutors.delete(type);
+    }
+  }
+
+  if (plugin.authenticationMethods) {
+    for (const type of Object.keys(plugin.authenticationMethods)) {
+      authenticationMethodFactories.delete(type);
+    }
+  }
+
+  if (plugin.analyticsProviders) {
+    for (const type of Object.keys(plugin.analyticsProviders)) {
+      analyticsProviderFactories.delete(type);
+    }
+  }
+
+  if (plugin.billingProviders) {
+    for (const type of Object.keys(plugin.billingProviders)) {
+      billingProviderFactories.delete(type);
+    }
+  }
+
+  if (plugin.authorizationPolicies) {
+    for (const type of Object.keys(plugin.authorizationPolicies)) {
+      authorizationPolicyFactories.delete(type);
+    }
+  }
+
+  if (plugin.emailProvider && emailProvider === plugin.emailProvider) {
+    emailProvider = undefined;
+  }
+
+  if (plugin.smsProvider && smsProvider === plugin.smsProvider) {
+    smsProvider = undefined;
+  }
+
+  if (plugin.onUnregister) {
+    Promise.resolve(plugin.onUnregister()).catch((err) => {
+      console.error(`Plugin ${plugin.metadata.name} onUnregister failed:`, err);
+    });
+  }
+
+  return true;
+}
+
+export function getConnectorFactory(type: string): ((config?: Record<string, unknown>) => IdentityConnector) | undefined {
+  return connectorFactories.get(type);
+}
+
+export function getPluginEmailProvider(): EmailProvider | undefined {
+  return emailProvider;
+}
+
+export function getPluginSmsProvider(): SmsProvider | undefined {
+  return smsProvider;
+}
+
+export function getPluginWorkflowStep(type: string): WorkflowStepExecutor | undefined {
+  return workflowStepExecutors.get(type);
+}
+
+export function getAuthenticationMethodFactory(
+  type: string
+): ((config?: Record<string, unknown>) => AuthenticationMethod) | undefined {
+  return authenticationMethodFactories.get(type);
+}
+
+export function getAnalyticsProviderFactory(
+  type: string
+): ((config?: Record<string, unknown>) => AnalyticsProvider) | undefined {
+  return analyticsProviderFactories.get(type);
+}
+
+export function getBillingProviderFactory(
+  type: string
+): ((config?: Record<string, unknown>) => BillingProvider) | undefined {
+  return billingProviderFactories.get(type);
+}
+
+export function getAuthorizationPolicyFactory(
+  type: string
+): ((config?: Record<string, unknown>) => AuthorizationPolicy) | undefined {
+  return authorizationPolicyFactories.get(type);
+}
+
+export function listRegisteredPlugins(): RegisteredPluginSummary[] {
+  return plugins.map((p) => ({
+    metadata: p.metadata,
+    extensionPoints: collectExtensionPoints(p),
+  }));
+}
+
+export function listExtensionPoints(): ExtensionPointSummary[] {
+  return [
+    {
+      name: "connectors",
+      description: "Identity provider adapters (OAuth2/OIDC/SAML).",
+      registered: Array.from(connectorFactories.keys()),
+    },
+    {
+      name: "emailProvider",
+      description: "Transactional email delivery backend.",
+      registered: emailProvider?.name ? [emailProvider.name] : [],
+    },
+    {
+      name: "smsProvider",
+      description: "SMS delivery backend.",
+      registered: smsProvider?.name ? [smsProvider.name] : [],
+    },
+    {
+      name: "workflowSteps",
+      description: "Reusable steps for automation workflows.",
+      registered: Array.from(workflowStepExecutors.keys()),
+    },
+    {
+      name: "authenticationMethods",
+      description: "Alternative authentication mechanisms.",
+      registered: Array.from(authenticationMethodFactories.keys()),
+    },
+    {
+      name: "analyticsProviders",
+      description: "Analytics and event tracking backends.",
+      registered: Array.from(analyticsProviderFactories.keys()),
+    },
+    {
+      name: "billingProviders",
+      description: "Subscription and billing integrations.",
+      registered: Array.from(billingProviderFactories.keys()),
+    },
+    {
+      name: "authorizationPolicies",
+      description: "Custom authorization policy engines.",
+      registered: Array.from(authorizationPolicyFactories.keys()),
+    },
+  ];
+}

package/src/services/plugins/types.ts

@@ -0,0 +1,98 @@
+import type { IdentityConnector } from "../connectors/types.js";
+import type { EmailProvider } from "../email.js";
+import type { SmsProvider } from "../sms.js";
+import type { WorkflowStep, StepContext, StepResult } from "../workflows/steps.js";
+import type { Result, KeystoneError } from "../../lib/result.js";
+
+export type WorkflowStepExecutor = (step: WorkflowStep, context: StepContext) => Promise<StepResult> | StepResult;
+
+export interface PluginMetadata {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  homepage?: string;
+}
+
+export interface AuthenticatedUser {
+  id: string;
+  email: string;
+  emailVerified?: boolean;
+  name?: string;
+  picture?: string;
+  username?: string;
+  roles?: string[];
+}
+
+export interface AuthenticationMethodContext {
+  body: Record<string, unknown>;
+  ip: string;
+  userAgent?: string;
+}
+
+export interface AuthenticationMethod {
+  id: string;
+  name: string;
+  description?: string;
+  authenticate(ctx: AuthenticationMethodContext): Promise<Result<AuthenticatedUser>>;
+}
+
+export interface AnalyticsEvent {
+  type: string;
+  timestamp: Date;
+  payload: Record<string, unknown>;
+}
+
+export interface AnalyticsProvider {
+  id: string;
+  name: string;
+  track(event: AnalyticsEvent): Promise<void>;
+  identify?(userId: string, traits?: Record<string, unknown>): Promise<void>;
+  page?(name: string, properties?: Record<string, unknown>): Promise<void>;
+}
+
+export interface BillingProvider {
+  id: string;
+  name?: string;
+  createCustomer(tenantId: string, email: string): Promise<Record<string, unknown>>;
+  subscribe(tenantId: string, planId: string): Promise<Record<string, unknown>>;
+  getSubscription(tenantId: string): Promise<Record<string, unknown> | null>;
+}
+
+export interface AuthorizationPolicyContext {
+  subjectId: string;
+  action: string;
+  resource: string;
+  context?: Record<string, unknown>;
+}
+
+export interface AuthorizationPolicy {
+  id: string;
+  name: string;
+  evaluate(ctx: AuthorizationPolicyContext): Promise<Result<boolean>> | Result<boolean>;
+}
+
+export interface KeystonePlugin {
+  metadata: PluginMetadata;
+  connectors?: Record<string, (config?: Record<string, unknown>) => IdentityConnector>;
+  emailProvider?: EmailProvider;
+  smsProvider?: SmsProvider;
+  workflowSteps?: Record<string, WorkflowStepExecutor>;
+  authenticationMethods?: Record<string, (config?: Record<string, unknown>) => AuthenticationMethod>;
+  analyticsProviders?: Record<string, (config?: Record<string, unknown>) => AnalyticsProvider>;
+  billingProviders?: Record<string, (config?: Record<string, unknown>) => BillingProvider>;
+  authorizationPolicies?: Record<string, (config?: Record<string, unknown>) => AuthorizationPolicy>;
+  onRegister?(): Promise<void> | void;
+  onUnregister?(): Promise<void> | void;
+}
+
+export interface RegisteredPluginSummary {
+  metadata: PluginMetadata;
+  extensionPoints: string[];
+}
+
+export interface ExtensionPointSummary {
+  name: string;
+  description: string;
+  registered: string[];
+}