@vibecodiq/cli 0.5.0 → 0.6.0

package/dist/foundation/admin_basic/manifest.json

@@ -0,0 +1,37 @@
+{
+  "name": "admin-basic",
+  "version": "1.0.0",
+  "description": "Admin control surface for SaaS apps — RBAC, audit log, user management, safe impersonation",
+  "min_cli_version": "2.0.0",
+  "stack": "asa-native-v1",
+  "dependencies": ["db-basic", "auth-basic"],
+  "package_dependencies": {},
+  "package_dev_dependencies": {},
+  "slices": [
+    { "domain": "admin", "name": "dashboard", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "admin", "name": "users", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "admin", "name": "roles", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "admin", "name": "impersonation", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "admin", "name": "audit-log", "type": "route", "has_ui": true, "has_repository": true }
+  ],
+  "shared": [
+    { "src": "shared/permissions.ts", "dest": "shared/admin/permissions.ts", "overwrite": false },
+    { "src": "shared/roles.ts", "dest": "shared/admin/roles.ts", "overwrite": false },
+    { "src": "shared/guards.ts", "dest": "shared/admin/guards.ts", "overwrite": false },
+    { "src": "shared/audit.ts", "dest": "shared/admin/audit.ts", "overwrite": false },
+    { "src": "shared/impersonation.ts", "dest": "shared/admin/impersonation.ts", "overwrite": false }
+  ],
+  "migrations": [
+    { "src": "migrations/004_user_roles.sql", "dest": "shared/db/migrations/004_user_roles.sql" },
+    { "src": "migrations/005_audit_log.sql", "dest": "shared/db/migrations/005_audit_log.sql" },
+    { "src": "migrations/006_impersonation_sessions.sql", "dest": "shared/db/migrations/006_impersonation_sessions.sql" }
+  ],
+  "env_vars": [],
+  "post_install_notes": [
+    "Run migration: Apply shared/db/migrations/004_user_roles.sql in Supabase SQL Editor",
+    "Run migration: Apply shared/db/migrations/005_audit_log.sql in Supabase SQL Editor",
+    "Run migration: Apply shared/db/migrations/006_impersonation_sessions.sql in Supabase SQL Editor",
+    "Set up Supabase Custom Access Token Hook for RBAC claims (see shared/admin/roles.ts)",
+    "Assign 'owner' role to your first admin user"
+  ]
+}

package/dist/foundation/admin_basic/migrations/004_user_roles.sql

@@ -0,0 +1,117 @@
+-- ASA Foundation: RBAC — user_roles table
+-- Canonical built-in roles: owner, admin, support
+-- Guards check PERMISSIONS, not role strings directly.
+
+-- Role definitions (canonical, versioned with module)
+CREATE TABLE IF NOT EXISTS public.roles (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL,
+  description TEXT,
+  is_builtin BOOLEAN NOT NULL DEFAULT false,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Seed built-in roles
+INSERT INTO public.roles (id, display_name, description, is_builtin) VALUES
+  ('owner', 'Owner', 'Full access. Can manage all users, billing, and settings.', true),
+  ('admin', 'Admin', 'Can manage users and content. Cannot change billing or transfer ownership.', true),
+  ('support', 'Support', 'Can view users and impersonate for debugging. Read-only admin access.', true)
+ON CONFLICT (id) DO NOTHING;
+
+-- Permission definitions
+CREATE TABLE IF NOT EXISTS public.permissions (
+  id TEXT PRIMARY KEY,
+  description TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Seed default permissions
+INSERT INTO public.permissions (id, description) VALUES
+  ('admin.access', 'Access admin panel'),
+  ('admin.users.list', 'View user list'),
+  ('admin.users.edit', 'Edit user details'),
+  ('admin.users.delete', 'Delete users'),
+  ('admin.roles.assign', 'Assign roles to users'),
+  ('admin.impersonate', 'Impersonate users'),
+  ('admin.audit.view', 'View audit log'),
+  ('admin.billing.manage', 'Manage billing and plans'),
+  ('admin.settings.edit', 'Edit application settings')
+ON CONFLICT (id) DO NOTHING;
+
+-- Role-permission mapping
+CREATE TABLE IF NOT EXISTS public.role_permissions (
+  role_id TEXT NOT NULL REFERENCES public.roles(id) ON DELETE CASCADE,
+  permission_id TEXT NOT NULL REFERENCES public.permissions(id) ON DELETE CASCADE,
+  PRIMARY KEY (role_id, permission_id)
+);
+
+-- Seed role-permission mappings
+INSERT INTO public.role_permissions (role_id, permission_id) VALUES
+  -- Owner: everything
+  ('owner', 'admin.access'),
+  ('owner', 'admin.users.list'),
+  ('owner', 'admin.users.edit'),
+  ('owner', 'admin.users.delete'),
+  ('owner', 'admin.roles.assign'),
+  ('owner', 'admin.impersonate'),
+  ('owner', 'admin.audit.view'),
+  ('owner', 'admin.billing.manage'),
+  ('owner', 'admin.settings.edit'),
+  -- Admin: users + content, no billing
+  ('admin', 'admin.access'),
+  ('admin', 'admin.users.list'),
+  ('admin', 'admin.users.edit'),
+  ('admin', 'admin.roles.assign'),
+  ('admin', 'admin.impersonate'),
+  ('admin', 'admin.audit.view'),
+  -- Support: read-only + impersonate
+  ('support', 'admin.access'),
+  ('support', 'admin.users.list'),
+  ('support', 'admin.impersonate'),
+  ('support', 'admin.audit.view')
+ON CONFLICT DO NOTHING;
+
+-- User-role assignment (links profiles to roles)
+CREATE TABLE IF NOT EXISTS public.user_roles (
+  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES public.roles(id) ON DELETE CASCADE,
+  assigned_by UUID REFERENCES auth.users(id),
+  assigned_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (user_id, role_id)
+);
+
+-- Index for quick role lookups
+CREATE INDEX IF NOT EXISTS idx_user_roles_user ON public.user_roles (user_id);
+CREATE INDEX IF NOT EXISTS idx_user_roles_role ON public.user_roles (role_id);
+
+-- RLS
+ALTER TABLE public.roles ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.permissions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.role_permissions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.user_roles ENABLE ROW LEVEL SECURITY;
+
+-- Roles/permissions are readable by authenticated users
+CREATE POLICY "Roles are viewable by authenticated users"
+  ON public.roles FOR SELECT TO authenticated USING (true);
+
+CREATE POLICY "Permissions are viewable by authenticated users"
+  ON public.permissions FOR SELECT TO authenticated USING (true);
+
+CREATE POLICY "Role permissions are viewable by authenticated users"
+  ON public.role_permissions FOR SELECT TO authenticated USING (true);
+
+-- User roles: users can see their own roles, admins can see all
+CREATE POLICY "Users can view own roles"
+  ON public.user_roles FOR SELECT TO authenticated
+  USING (user_id = auth.uid());
+
+-- Add role column to profiles if it doesn't exist (backward compat with auth-basic)
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = 'profiles' AND column_name = 'role'
+  ) THEN
+    ALTER TABLE public.profiles ADD COLUMN role TEXT DEFAULT 'user';
+  END IF;
+END $$;

package/dist/foundation/admin_basic/migrations/005_audit_log.sql

@@ -0,0 +1,34 @@
+-- ASA Foundation: immutable audit log
+-- Append-only, actor/subject aware, reason-aware for impersonation.
+-- No UPDATE or DELETE policies — log entries are permanent.
+
+CREATE TABLE IF NOT EXISTS public.audit_log (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_id UUID NOT NULL,
+  actor_email TEXT,
+  actor_role TEXT,
+  subject_id UUID,
+  subject_email TEXT,
+  action TEXT NOT NULL,
+  resource_type TEXT,
+  resource_id TEXT,
+  details JSONB DEFAULT '{}',
+  reason TEXT,
+  ip_address TEXT,
+  user_agent TEXT,
+  impersonation_session_id UUID,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_audit_log_actor ON public.audit_log (actor_id);
+CREATE INDEX IF NOT EXISTS idx_audit_log_subject ON public.audit_log (subject_id);
+CREATE INDEX IF NOT EXISTS idx_audit_log_action ON public.audit_log (action);
+CREATE INDEX IF NOT EXISTS idx_audit_log_created ON public.audit_log (created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_log_resource ON public.audit_log (resource_type, resource_id);
+
+-- RLS: audit log is append-only via service_role
+ALTER TABLE public.audit_log ENABLE ROW LEVEL SECURITY;
+
+-- Admins can read audit log (via server-side queries with service_role)
+-- No INSERT/UPDATE/DELETE policies for regular users = immutable from app perspective

package/dist/foundation/admin_basic/migrations/006_impersonation_sessions.sql

@@ -0,0 +1,22 @@
+-- ASA Foundation: impersonation sessions (hybrid b+c model)
+-- Admin session stays admin session. Impersonation is app-layer server-side context.
+-- Every impersonated action is audit-logged with actor + subject chain.
+
+CREATE TABLE IF NOT EXISTS public.impersonation_sessions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_admin_id UUID NOT NULL REFERENCES auth.users(id),
+  subject_user_id UUID NOT NULL REFERENCES auth.users(id),
+  reason TEXT NOT NULL,
+  started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  expires_at TIMESTAMPTZ NOT NULL,
+  stopped_at TIMESTAMPTZ,
+  is_active BOOLEAN GENERATED ALWAYS AS (stopped_at IS NULL AND expires_at > now()) STORED,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_impersonation_actor ON public.impersonation_sessions (actor_admin_id);
+CREATE INDEX IF NOT EXISTS idx_impersonation_active ON public.impersonation_sessions (is_active) WHERE is_active = true;
+
+-- RLS: only accessible via service_role (backend)
+ALTER TABLE public.impersonation_sessions ENABLE ROW LEVEL SECURITY;

package/dist/foundation/admin_basic/shared/audit.ts

@@ -0,0 +1,97 @@
+import { createAdminClient } from '@/shared/db/supabase-client';
+
+// --- ASA GENERATED START ---
+// Immutable audit log — append-only, actor/subject aware.
+// All admin actions must be logged via logAuditEvent().
+// No update/delete operations on audit_log table.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export interface AuditEvent {
+  actor_id: string;
+  actor_email?: string;
+  actor_role?: string;
+  subject_id?: string;
+  subject_email?: string;
+  action: string;
+  resource_type?: string;
+  resource_id?: string;
+  details?: Record<string, unknown>;
+  reason?: string;
+  ip_address?: string;
+  user_agent?: string;
+  impersonation_session_id?: string;
+}
+
+/**
+ * Log an audit event. Append-only — entries cannot be modified or deleted.
+ */
+export async function logAuditEvent(event: AuditEvent): Promise<void> {
+  const supabase = createAdminClient();
+
+  const { error } = await supabase.from('audit_log').insert({
+    actor_id: event.actor_id,
+    actor_email: event.actor_email,
+    actor_role: event.actor_role,
+    subject_id: event.subject_id,
+    subject_email: event.subject_email,
+    action: event.action,
+    resource_type: event.resource_type,
+    resource_id: event.resource_id,
+    details: event.details ?? {},
+    reason: event.reason,
+    ip_address: event.ip_address,
+    user_agent: event.user_agent,
+    impersonation_session_id: event.impersonation_session_id,
+  });
+
+  if (error) {
+    // Never throw on audit failure — log to console as fallback
+    console.error('[audit] Failed to write audit log:', error.message, event);
+  }
+}
+
+/**
+ * Query audit log entries with filters.
+ */
+export async function queryAuditLog(options: {
+  actor_id?: string;
+  subject_id?: string;
+  action?: string;
+  resource_type?: string;
+  from_date?: string;
+  to_date?: string;
+  limit?: number;
+  offset?: number;
+}) {
+  const supabase = createAdminClient();
+
+  let query = supabase
+    .from('audit_log')
+    .select('*', { count: 'exact' })
+    .order('created_at', { ascending: false });
+
+  if (options.actor_id) query = query.eq('actor_id', options.actor_id);
+  if (options.subject_id) query = query.eq('subject_id', options.subject_id);
+  if (options.action) query = query.eq('action', options.action);
+  if (options.resource_type) query = query.eq('resource_type', options.resource_type);
+  if (options.from_date) query = query.gte('created_at', options.from_date);
+  if (options.to_date) query = query.lte('created_at', options.to_date);
+
+  query = query.range(
+    options.offset ?? 0,
+    (options.offset ?? 0) + (options.limit ?? 50) - 1,
+  );
+
+  const { data, count, error } = await query;
+
+  if (error) {
+    console.error('[audit] Query failed:', error.message);
+    return { entries: [], total: 0 };
+  }
+
+  return { entries: data ?? [], total: count ?? 0 };
+}
+
+// --- USER CODE END ---

package/dist/foundation/admin_basic/shared/guards.ts

@@ -0,0 +1,58 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth } from '@/shared/auth/guards';
+import { hasPermission } from '@/shared/admin/roles';
+import { logAuditEvent } from '@/shared/admin/audit';
+import type { Permission } from '@/shared/admin/permissions';
+
+// --- ASA GENERATED START ---
+// Admin guards — server-side permission checks for admin route handlers.
+// Every admin endpoint MUST use requirePermission() — never UI-only checks.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+/**
+ * Require a specific permission in an admin route handler.
+ * Verifies auth + checks permission via RBAC engine.
+ * Logs unauthorized access attempts to audit log.
+ *
+ * Usage:
+ * ```ts
+ * const { user, response } = await requirePermission(request, PERMISSIONS.USERS_LIST);
+ * if (response) return response;
+ * ```
+ */
+export async function requirePermission(
+  request: NextRequest,
+  permission: Permission,
+): Promise<{
+  user: { id: string; email: string } | null;
+  response: NextResponse | null;
+}> {
+  const { user, response } = await requireAuth(request);
+  if (response) return { user: null, response };
+
+  const allowed = await hasPermission(user!.id, permission);
+
+  if (!allowed) {
+    // Log unauthorized access attempt
+    await logAuditEvent({
+      actor_id: user!.id,
+      actor_email: user!.email,
+      action: 'admin.access_denied',
+      details: { permission, path: request.nextUrl.pathname },
+    });
+
+    return {
+      user: null,
+      response: NextResponse.json(
+        { error: 'Insufficient permissions' },
+        { status: 403 },
+      ),
+    };
+  }
+
+  return { user, response: null };
+}
+
+// --- USER CODE END ---

package/dist/foundation/admin_basic/shared/impersonation.ts

@@ -0,0 +1,165 @@
+import { cookies } from 'next/headers';
+import { createAdminClient } from '@/shared/db/supabase-client';
+import { logAuditEvent } from '@/shared/admin/audit';
+
+// --- ASA GENERATED START ---
+// Safe impersonation — hybrid b+c model.
+// Admin session stays admin session. Impersonation is server-side context.
+// No fake end-user JWT. All impersonated actions are audit-logged.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+const IMPERSONATION_COOKIE = 'asa-impersonation-session';
+const DEFAULT_TTL_MINUTES = 30;
+
+export interface ImpersonationSession {
+  id: string;
+  actor_admin_id: string;
+  subject_user_id: string;
+  reason: string;
+  started_at: string;
+  expires_at: string;
+  stopped_at: string | null;
+  is_active: boolean;
+}
+
+/**
+ * Start impersonation session.
+ * Creates DB record + sets HttpOnly cookie.
+ */
+export async function startImpersonation(
+  adminId: string,
+  adminEmail: string,
+  subjectUserId: string,
+  reason: string,
+  ttlMinutes: number = DEFAULT_TTL_MINUTES,
+): Promise<{ session: ImpersonationSession | null; error?: string }> {
+  if (!reason || reason.trim().length < 3) {
+    return { session: null, error: 'Reason is required (min 3 characters)' };
+  }
+
+  const supabase = createAdminClient();
+
+  // Check if admin already has an active impersonation
+  const { data: existing } = await supabase
+    .from('impersonation_sessions')
+    .select('id')
+    .eq('actor_admin_id', adminId)
+    .eq('is_active', true)
+    .limit(1);
+
+  if (existing && existing.length > 0) {
+    return { session: null, error: 'You already have an active impersonation session. Stop it first.' };
+  }
+
+  const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000).toISOString();
+
+  const { data, error } = await supabase
+    .from('impersonation_sessions')
+    .insert({
+      actor_admin_id: adminId,
+      subject_user_id: subjectUserId,
+      reason: reason.trim(),
+      expires_at: expiresAt,
+    })
+    .select()
+    .single();
+
+  if (error || !data) {
+    return { session: null, error: error?.message ?? 'Failed to create impersonation session' };
+  }
+
+  // Set HttpOnly cookie with session ID
+  const cookieStore = await cookies();
+  cookieStore.set(IMPERSONATION_COOKIE, data.id, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    maxAge: ttlMinutes * 60,
+    path: '/',
+  });
+
+  // Audit log
+  await logAuditEvent({
+    actor_id: adminId,
+    actor_email: adminEmail,
+    subject_id: subjectUserId,
+    action: 'impersonation.start',
+    reason: reason.trim(),
+    impersonation_session_id: data.id,
+  });
+
+  return { session: data as ImpersonationSession };
+}
+
+/**
+ * Stop impersonation session.
+ */
+export async function stopImpersonation(
+  adminId: string,
+  adminEmail: string,
+): Promise<{ success: boolean; error?: string }> {
+  const supabase = createAdminClient();
+
+  const { data: session } = await supabase
+    .from('impersonation_sessions')
+    .select('id, subject_user_id, reason')
+    .eq('actor_admin_id', adminId)
+    .eq('is_active', true)
+    .single();
+
+  if (!session) {
+    return { success: false, error: 'No active impersonation session found' };
+  }
+
+  await supabase
+    .from('impersonation_sessions')
+    .update({ stopped_at: new Date().toISOString() })
+    .eq('id', session.id);
+
+  // Clear cookie
+  const cookieStore = await cookies();
+  cookieStore.delete(IMPERSONATION_COOKIE);
+
+  // Audit log
+  await logAuditEvent({
+    actor_id: adminId,
+    actor_email: adminEmail,
+    subject_id: session.subject_user_id,
+    action: 'impersonation.stop',
+    reason: session.reason,
+    impersonation_session_id: session.id,
+  });
+
+  return { success: true };
+}
+
+/**
+ * Get current active impersonation session from cookie.
+ * Returns null if no active impersonation.
+ */
+export async function getActiveImpersonation(): Promise<ImpersonationSession | null> {
+  const cookieStore = await cookies();
+  const sessionId = cookieStore.get(IMPERSONATION_COOKIE)?.value;
+
+  if (!sessionId) return null;
+
+  const supabase = createAdminClient();
+  const { data } = await supabase
+    .from('impersonation_sessions')
+    .select('*')
+    .eq('id', sessionId)
+    .eq('is_active', true)
+    .single();
+
+  if (!data) {
+    // Cookie exists but session expired/stopped — clear cookie
+    cookieStore.delete(IMPERSONATION_COOKIE);
+    return null;
+  }
+
+  return data as ImpersonationSession;
+}
+
+// --- USER CODE END ---

package/dist/foundation/admin_basic/shared/permissions.ts

@@ -0,0 +1,27 @@
+// --- ASA GENERATED START ---
+// Permission registry — canonical permissions for admin-basic module.
+// Guards check permissions, NOT role strings.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+/**
+ * Canonical permission IDs.
+ * These match the seeded permissions in 004_user_roles.sql.
+ * Guards should import and use these constants — never raw strings.
+ */
+export const PERMISSIONS = {
+  ADMIN_ACCESS: 'admin.access',
+  USERS_LIST: 'admin.users.list',
+  USERS_EDIT: 'admin.users.edit',
+  USERS_DELETE: 'admin.users.delete',
+  ROLES_ASSIGN: 'admin.roles.assign',
+  IMPERSONATE: 'admin.impersonate',
+  AUDIT_VIEW: 'admin.audit.view',
+  BILLING_MANAGE: 'admin.billing.manage',
+  SETTINGS_EDIT: 'admin.settings.edit',
+} as const;
+
+export type Permission = typeof PERMISSIONS[keyof typeof PERMISSIONS];
+
+// --- USER CODE END ---