@adminforge/core 0.3.1

package/src/api/security/agent-auth.ts

@@ -0,0 +1,134 @@
+import jwt from "jsonwebtoken";
+import crypto from "crypto";
+
+/**
+ * --- Security Model Definitions ---
+ */
+
+export type Action = "create" | "read" | "update" | "delete";
+
+export type AgentTokenPayload = {
+  sub: string;        // userId
+  role: string;
+  scope: string[];    // format: "collection:action"
+  iat: number;
+  exp: number;
+  iss: "adminforge";
+  aud: "agent";
+  sessionId: string;
+};
+
+export type AgentSession = AgentTokenPayload;
+
+export type SecurityContext = {
+  user?: any; // Replace with User type from your auth package
+  agent?: AgentSession;
+  source: "user" | "agent";
+};
+
+function getSecret(): string {
+  const secret = process.env.ADMINFORGE_SECRET;
+  if (!secret) {
+    throw new Error("ADMINFORGE_SECRET env var is required. Generate one with: openssl rand -hex 32");
+  }
+  return secret;
+}
+
+/**
+ * --- Utilities ---
+ */
+
+function normalizeScope(scope: string): string {
+  const normalized = scope.trim().toLowerCase();
+  if (!/^[a-z0-9_-]+:[a-z]+$/.test(normalized)) {
+    throw new Error(`Malformed scope format: ${scope}`);
+  }
+  return normalized;
+}
+
+function assertValidAction(action: string): Action {
+  const validActions: Action[] = ["create", "read", "update", "delete"];
+  if (!validActions.includes(action as Action)) {
+    throw new Error(`Invalid action: ${action}`);
+  }
+  return action as Action;
+}
+
+function assertValidCollection(collection: string): string {
+  if (!/^[a-z0-9_-]+$/.test(collection)) {
+    throw new Error(`Invalid collection name: ${collection}`);
+  }
+  return collection;
+}
+
+/**
+ * --- Token Lifecycle ---
+ */
+
+export function generateAgentToken(
+  userId: string,
+  role: string,
+  scopes: string[],
+  expiresInSeconds: number = 600
+): string {
+  const normalizedScopes = scopes.map(normalizeScope);
+
+  return jwt.sign(
+    {
+      sub: userId,
+      role,
+      scope: normalizedScopes,
+      sessionId: crypto.randomUUID(),
+    },
+    getSecret(),
+    {
+      expiresIn: expiresInSeconds,
+      issuer: "adminforge",
+      audience: "agent",
+    }
+  );
+}
+
+/**
+ * --- Verification & Enforcement ---
+ */
+
+// Stub for revocation capability
+function isRevoked(sessionId: string): boolean {
+  // In V1, we return false. V2 will check against a Redis/DB blacklist.
+  return false;
+}
+
+export function verifyAgentToken(token: string): AgentTokenPayload {
+  try {
+    const payload = jwt.verify(token, getSecret(), {
+      issuer: "adminforge",
+      audience: "agent",
+    }) as unknown as AgentTokenPayload;
+
+    if (!payload.sub) throw new Error("Missing userId (sub)");
+    if (!payload.role) throw new Error("Missing role");
+    if (!Array.isArray(payload.scope)) throw new Error("Invalid scope format");
+
+    if (isRevoked(payload.sessionId)) {
+      throw new Error("Session revoked");
+    }
+
+    // Semantic normalization
+    payload.scope = payload.scope.map(normalizeScope);
+
+    return payload;
+  } catch (error: any) {
+    throw new Error(`Unauthorized: ${error.message}`);
+  }
+}
+
+export function assertScope(agent: AgentSession, collection: string, action: Action): void {
+  const validColl = assertValidCollection(collection);
+  const validAction = assertValidAction(action);
+  const key = `${validColl}:${validAction}`.toLowerCase();
+
+  if (!agent.scope.includes(key)) {
+    throw new Error(`Forbidden: Missing scope ${key}`);
+  }
+}

package/src/auth/config.ts

@@ -0,0 +1,20 @@
+interface AuthConfigOptions {
+  enabled: boolean;
+  secret?: string;
+}
+
+export function createAuthConfig(options: AuthConfigOptions) {
+  return {
+    ...options,
+    providers: ["credentials"] as const,
+  };
+}
+
+export const auth = {
+  providers: {
+    credentials: {
+      id: "credentials",
+      name: "Credentials",
+    },
+  },
+} as const;

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export { createAuthConfig, auth } from "./config.js";
+export { adminMiddleware } from "./middleware.js";
+

package/src/auth/middleware.ts

@@ -0,0 +1,15 @@
+export function adminMiddleware(handler: (request: Request) => Promise<Response>) {
+  return async (request: Request): Promise<Response> => {
+    const sessionCookie = request.headers.get("cookie") ?? "";
+    const hasSession = sessionCookie.includes("next-auth.session-token");
+
+    if (!hasSession) {
+      return new Response(JSON.stringify({ error: "Unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    return handler(request);
+  };
+}

package/src/auth/provider.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+interface AdminSession {
+  user: { id: string; email: string; role?: string } | null;
+  role?: string;
+}
+
+const AdminSessionContext = createContext<AdminSession | null>(null);
+
+export function AuthProvider({
+  children,
+  session,
+}: {
+  children: React.ReactNode;
+  session: AdminSession | null;
+}) {
+  return (
+    <AdminSessionContext.Provider value={session}>
+      {children}
+    </AdminSessionContext.Provider>
+  );
+}
+
+export function useAdminSession(): AdminSession | null {
+  return useContext(AdminSessionContext);
+}

package/src/core/fields/index.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type {
+  FieldDefinition,
+  FieldMeta,
+  FieldOptions,
+  TextOptions,
+  BooleanOptions,
+  RichTextOptions,
+  SlugOptions,
+  RelationOptions,
+  DateOptions,
+  ImageOptions,
+} from "../types/index.js";
+
+function fieldMeta(options: FieldOptions = {}): FieldMeta {
+  return {
+    required: Boolean(options.required),
+    unique: Boolean(options.unique),
+    default: options.default,
+    label: options.label,
+    hidden: options.hidden,
+    readOnly: options.readOnly,
+    description: options.description,
+  };
+}
+
+function text(options: TextOptions = {}): FieldDefinition {
+  return {
+    type: "text",
+    db: { type: "String", nullable: !options.required, unique: options.unique, default: options.default },
+    access: options.access,
+    ui: { component: "text", props: { label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: options.required ? z.string().min(1) : z.string().optional(),
+    meta: fieldMeta(options),
+  };
+}
+
+function boolean(options: BooleanOptions = {}): FieldDefinition {
+  return {
+    type: "boolean",
+    db: { type: "Boolean", nullable: !options.required, default: options.default ?? false },
+    access: options.access,
+    ui: { component: "boolean", props: { label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: options.required ? z.boolean() : z.boolean().optional(),
+    meta: fieldMeta(options),
+  };
+}
+
+function richText(options: RichTextOptions = {}): FieldDefinition {
+  return {
+    type: "richText",
+    db: { type: "String", nullable: !options.required },
+    access: options.access,
+    ui: { component: "richText", props: { label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: options.required ? z.string().min(1) : z.string().optional(),
+    meta: fieldMeta(options),
+  };
+}
+
+function slug(options: SlugOptions): FieldDefinition {
+  return {
+    type: "slug",
+    db: { type: "String", nullable: !options.required, unique: options.unique ?? true },
+    access: options.access,
+    ui: { component: "slug", props: { from: options.from, label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: options.required
+      ? z.string().regex(/^[a-z0-9-]+$/)
+      : z.string().regex(/^[a-z0-9-]+$/).optional(),
+    hooks: { beforeSave: (value: unknown) => {
+      if (typeof value === "string") return value.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+      return value;
+    }},
+    meta: { ...fieldMeta(options), unique: options.unique ?? true },
+  };
+}
+
+function relation(options: RelationOptions): FieldDefinition {
+  const isMulti = options.type === "many-to-many" || options.type === "one-to-many";
+  return {
+    type: "relation",
+    db: { type: "String", nullable: !options.required, references: { model: options.to, field: "id" }, relationType: options.type },
+    access: options.access,
+    ui: { component: "relation", props: { to: options.to, relationType: options.type, label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: isMulti
+      ? (options.required ? z.array(z.string()).min(1) : z.array(z.string()).optional())
+      : (options.required ? z.string().min(1) : z.string().optional()),
+    meta: fieldMeta(options),
+  };
+}
+
+function date(options: DateOptions = {}): FieldDefinition {
+  return {
+    type: "date",
+    db: { type: "DateTime", nullable: !options.required },
+    access: options.access,
+    ui: { component: "date", props: { label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: options.required ? z.string().datetime() : z.string().datetime().optional(),
+    hooks: { beforeSave: (value: unknown) => {
+      if (options.autoCreate && !value) return new Date().toISOString();
+      return value;
+    }},
+    meta: fieldMeta(options),
+  };
+}
+
+function image(options: ImageOptions = {}): FieldDefinition {
+  return {
+    type: "image",
+    db: { type: "String", nullable: true },
+    access: options.access,
+    ui: { component: "image", props: { label: options.label, hidden: options.hidden, readOnly: options.readOnly } },
+    validation: z.string().optional(),
+    meta: fieldMeta(options),
+  };
+}
+
+export const fields = {
+  text, boolean, richText, slug, relation, date, image,
+} as const;

package/src/core/hooks/index.ts

@@ -0,0 +1,60 @@
+import type { CollectionHooks } from "../types/index.js";
+
+export async function executeBeforeCreate(
+  hooks: CollectionHooks | undefined,
+  data: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  if (hooks?.beforeCreate) {
+    return await hooks.beforeCreate({ data });
+  }
+  return data;
+}
+
+export async function executeAfterCreate(
+  hooks: CollectionHooks | undefined,
+  data: Record<string, unknown>,
+  id: string
+): Promise<void> {
+  if (hooks?.afterCreate) {
+    await hooks.afterCreate({ data, id });
+  }
+}
+
+export async function executeBeforeUpdate(
+  hooks: CollectionHooks | undefined,
+  data: Record<string, unknown>,
+  id: string
+): Promise<Record<string, unknown>> {
+  if (hooks?.beforeUpdate) {
+    return await hooks.beforeUpdate({ data, id });
+  }
+  return data;
+}
+
+export async function executeAfterUpdate(
+  hooks: CollectionHooks | undefined,
+  data: Record<string, unknown>,
+  id: string
+): Promise<void> {
+  if (hooks?.afterUpdate) {
+    await hooks.afterUpdate({ data, id });
+  }
+}
+
+export async function executeBeforeDelete(
+  hooks: CollectionHooks | undefined,
+  id: string
+): Promise<void> {
+  if (hooks?.beforeDelete) {
+    await hooks.beforeDelete({ id });
+  }
+}
+
+export async function executeAfterDelete(
+  hooks: CollectionHooks | undefined,
+  id: string
+): Promise<void> {
+  if (hooks?.afterDelete) {
+    await hooks.afterDelete({ id });
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,43 @@
+export { defineConfig } from "./schema/config.js";
+export { collection } from "./schema/collection.js";
+export { normalize, serializeConfig } from "./schema/normalize.js";
+export type { NormalizedSchema } from "./schema/normalize.js";
+export { fields } from "./fields/index.js";
+export { registerField, getField, getRegisteredFields, clearRegistry } from "./registry/index.js";
+export {
+  executeBeforeCreate,
+  executeAfterCreate,
+  executeBeforeUpdate,
+  executeAfterUpdate,
+  executeBeforeDelete,
+  executeAfterDelete,
+} from "./hooks/index.js";
+export type {
+  FieldDefinition,
+  FieldDBMapping,
+  FieldUI,
+  FieldHooks,
+  FieldMeta,
+  CollectionDefinition,
+  CollectionHooks,
+  AdminForgeConfig,
+  AuthConfig,
+  AccessConfig,
+  RelationType,
+  TextOptions,
+  BooleanOptions,
+  RichTextOptions,
+  SlugOptions,
+  RelationOptions,
+  DateOptions,
+  ImageOptions,
+} from "./types/index.js";
+
+/**
+ * Utility type to infer the record structure from a CollectionDefinition.
+ */
+export type InferRecord<T extends { fields: Record<string, any> }> = {
+  id: string;
+} & {
+  [K in keyof T["fields"]]: any; // We'll refine this in the future with proper field-to-type mapping
+};

package/src/core/registry/index.ts

@@ -0,0 +1,22 @@
+import type { FieldDefinition } from "../types/index.js";
+
+const fieldRegistry = new Map<string, FieldDefinition>();
+
+export function registerField(name: string, definition: FieldDefinition): void {
+  if (fieldRegistry.has(name)) {
+    throw new Error(`Field "${name}" is already registered`);
+  }
+  fieldRegistry.set(name, definition);
+}
+
+export function getField(name: string): FieldDefinition | undefined {
+  return fieldRegistry.get(name);
+}
+
+export function getRegisteredFields(): Map<string, FieldDefinition> {
+  return new Map(fieldRegistry);
+}
+
+export function clearRegistry(): void {
+  fieldRegistry.clear();
+}

package/src/core/schema/collection.ts

@@ -0,0 +1,12 @@
+import type { CollectionDefinition, CollectionInput } from "../types/index.js";
+
+export function collection(input: CollectionInput): CollectionDefinition {
+  return {
+    name: input.name,
+    label: input.label ?? input.name.charAt(0).toUpperCase() + input.name.slice(1),
+    icon: input.icon,
+    fields: input.fields,
+    hooks: input.hooks,
+    access: input.access,
+  };
+}

package/src/core/schema/config.ts

@@ -0,0 +1,11 @@
+import type { AdminForgeConfig, CollectionDefinition, AuthConfig } from "../types/index.js";
+
+export function defineConfig(config: {
+  collections: CollectionDefinition[];
+  auth?: AuthConfig;
+}): AdminForgeConfig {
+  return {
+    collections: config.collections,
+    auth: config.auth ?? { enabled: false },
+  };
+}

package/src/core/schema/normalize.ts

@@ -0,0 +1,32 @@
+import type { AdminForgeConfig } from "../types/index.js";
+
+export type NormalizedSchema = AdminForgeConfig;
+
+export function normalize(config: AdminForgeConfig): NormalizedSchema {
+  return {
+    collections: config.collections.map((c) => ({
+      ...c,
+      label: c.label ?? c.name.charAt(0).toUpperCase() + c.name.slice(1),
+    })),
+    auth: config.auth ?? { enabled: false },
+  };
+}
+
+/**
+ * Removes non-serializable parts of the config (like Zod schemas)
+ * so it can be passed from Server Components to Client Components.
+ */
+export function serializeConfig(config: AdminForgeConfig): any {
+  return {
+    ...config,
+    collections: config.collections.map((c) => ({
+      ...c,
+      fields: Object.fromEntries(
+        Object.entries(c.fields).map(([name, field]) => {
+          const { validation, ...rest } = field;
+          return [name, rest];
+        })
+      ),
+    })),
+  };
+}

package/src/core/types/index.ts

@@ -0,0 +1,114 @@
+import type { ZodSchema } from "zod";
+
+export type RelationType = "many-to-one" | "one-to-many" | "many-to-many";
+
+export interface FieldDBMapping {
+  type: string;
+  nullable?: boolean;
+  unique?: boolean;
+  default?: unknown;
+  references?: { model: string; field: string };
+  relationType?: RelationType;
+}
+
+export interface FieldUI {
+  component: string;
+  props?: Record<string, unknown>;
+}
+
+export interface FieldHooks {
+  beforeValidate?: (value: unknown) => unknown;
+  beforeSave?: (value: unknown) => unknown;
+}
+
+export interface FieldDefinition {
+  type: string;
+  db: FieldDBMapping;
+  ui: FieldUI;
+  validation: ZodSchema;
+  meta?: FieldMeta;
+  hooks?: FieldHooks;
+  access?: AccessConfig;
+}
+
+export interface FieldOptions {
+  required?: boolean;
+  default?: unknown;
+  unique?: boolean;
+  label?: string;
+  hidden?: boolean;
+  readOnly?: boolean;
+  description?: string;
+  access?: AccessConfig;
+}
+
+export interface FieldMeta {
+  required: boolean;
+  unique: boolean;
+  default?: unknown;
+  label?: string;
+  hidden?: boolean;
+  readOnly?: boolean;
+  description?: string;
+}
+
+export interface TextOptions extends FieldOptions {}
+export interface BooleanOptions extends FieldOptions {}
+export interface RichTextOptions extends FieldOptions {}
+
+export interface SlugOptions extends FieldOptions {
+  from: string;
+}
+
+export interface RelationOptions extends FieldOptions {
+  to: string;
+  type: RelationType;
+}
+
+export interface DateOptions extends FieldOptions {
+  autoCreate?: boolean;
+  autoUpdate?: boolean;
+}
+
+export interface ImageOptions extends FieldOptions {}
+
+export interface AccessConfig {
+  read?: string[];
+  create?: string[];
+  update?: string[];
+  delete?: string[];
+}
+
+export interface CollectionHooks {
+  beforeCreate?: (ctx: { data: Record<string, unknown> }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  afterCreate?: (ctx: { data: Record<string, unknown>; id: string }) => void | Promise<void>;
+  beforeUpdate?: (ctx: { data: Record<string, unknown>; id: string }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  afterUpdate?: (ctx: { data: Record<string, unknown>; id: string }) => void | Promise<void>;
+  beforeDelete?: (ctx: { id: string }) => void | Promise<void>;
+  afterDelete?: (ctx: { id: string }) => void | Promise<void>;
+}
+
+export interface CollectionDefinition {
+  name: string;
+  label: string;
+  icon?: string;
+  fields: Record<string, FieldDefinition>;
+  hooks?: CollectionHooks;
+  access?: AccessConfig;
+}
+
+export interface AuthConfig {
+  enabled: boolean;
+  provider?: "credentials";
+  roles?: Record<string, { label?: string; parent?: string }>;
+}
+
+export interface AdminForgeConfig {
+  collections: CollectionDefinition[];
+  auth?: AuthConfig;
+}
+
+export type CollectionInput = Omit<CollectionDefinition, "fields"> & {
+  fields: Record<string, FieldDefinition>;
+  hooks?: CollectionHooks;
+};