@percepta/create 3.1.5 → 3.3.0

package/templates/webapp/scripts/seed.ts

@@ -2,7 +2,7 @@
 
 /**
  * Development seed script.
- * Creates a default admin user for local development.
+ * Creates shared auth users and local access grants for development.
  *
  * Usage: pnpm db:seed
  */
@@ -10,52 +10,103 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { loadEnvConfig } from "@next/env";
 
-const DEFAULT_USER = {
-  email: "admin@example.com",
-  password: "password",
-  name: "Admin User",
-};
+const SEEDED_USERS = [
+  {
+    access: "owner",
+    appRole: "admin",
+    email: "admin@example.com",
+    name: "Admin User",
+    password: "password",
+    role: "admin",
+  },
+  {
+    access: "member",
+    email: "user@example.com",
+    name: "Regular User",
+    password: "password",
+    role: "user",
+  },
+] as const;
 
 async function main(): Promise<void> {
   loadEnvConfig(process.cwd());
   // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
   (globalThis as any).AsyncLocalStorage = AsyncLocalStorage;
 
-  const { auth } = await import("../src/lib/auth");
-  const { db } = await import("../src/drizzle/db");
-  const { users } = await import("../src/drizzle/schema/auth/users");
+  const { auth } = await import("@__REPO_NAME__/auth");
+  const { db: authDb } = await import("@__REPO_NAME__/auth/db");
+  const { users } = await import("@__REPO_NAME__/auth/schema");
+  const { getAccessControl, toUserSubject } =
+    await import("../src/services/access/AppAccessControl");
+  const { createCustomerAccessControl } =
+    await import("@percepta/access-control");
   const { eq, sql } = await import("drizzle-orm");
 
-  // Check if user already exists
-  const [existing] = await db
-    .select({ id: users.id })
-    .from(users)
-    .where(eq(sql`lower(${users.email})`, sql`lower(${DEFAULT_USER.email})`))
-    .limit(1);
-
-  if (existing != null) {
-    await db
-      .update(users)
-      .set({ role: "admin" })
-      .where(eq(users.id, existing.id));
-    console.log(
-      `Seed user "${DEFAULT_USER.email}" already exists (id: ${existing.id}). Ensured admin role.`,
-    );
-    process.exit(0);
-  }
-
-  // Use Better Auth's signUpEmail API to create the user with a hashed password
-  const res = await auth.api.signUpEmail({
-    body: DEFAULT_USER,
+  const access = getAccessControl();
+  const customerAccess = createCustomerAccessControl({
+    applications: [{ appNamespace: access.manifest.appNamespace }],
+    client: access.client,
   });
 
-  await db
-    .update(users)
-    .set({ role: "admin" })
-    .where(eq(users.id, res.user.id));
+  for (const seededUser of SEEDED_USERS) {
+    // Check if user already exists
+    const [existing] = await authDb
+      .select({ id: users.id })
+      .from(users)
+      .where(eq(sql`lower(${users.email})`, sql`lower(${seededUser.email})`))
+      .limit(1);
+
+    let userId: string;
+    if (existing != null) {
+      await authDb
+        .update(users)
+        .set({ role: seededUser.role })
+        .where(eq(users.id, existing.id));
+      userId = existing.id;
+      console.log(
+        `Seed user "${seededUser.email}" already exists (id: ${existing.id}). Ensured ${seededUser.role} role.`,
+      );
+    } else {
+      // Use Better Auth's signUpEmail API to create the user with a hashed password
+      const res = await auth.api.signUpEmail({
+        body: {
+          email: seededUser.email,
+          name: seededUser.name,
+          password: seededUser.password,
+        },
+      });
+
+      await authDb
+        .update(users)
+        .set({ role: seededUser.role })
+        .where(eq(users.id, res.user.id));
+
+      userId = res.user.id;
+      console.log(
+        `Seed user created: ${seededUser.email} (id: ${res.user.id})`,
+      );
+      console.log(`  Password: ${seededUser.password}`);
+    }
+
+    const subject = toUserSubject(userId);
+    if (seededUser.access === "owner") {
+      await customerAccess.assignApplicationOwner(
+        access.manifest.appNamespace,
+        subject,
+      );
+    } else {
+      await customerAccess.assignApplicationMember(
+        access.manifest.appNamespace,
+        subject,
+      );
+    }
+
+    if ("appRole" in seededUser) {
+      await access.app.assignAppRole(seededUser.appRole, subject);
+    }
+  }
 
-  console.log(`Seed user created: ${DEFAULT_USER.email} (id: ${res.user.id})`);
-  console.log(`  Password: ${DEFAULT_USER.password}`);
+  console.log("Ensured local app access grants.");
   process.exit(0);
 }
 

package/templates/webapp/scripts/setup-database.ts

@@ -53,7 +53,9 @@ async function main(): Promise<void> {
     if (result.rows.length === 0) {
       console.log(`📦 Creating database: ${database}`);
       // Create the database (note: database names cannot be parameterized)
-      await adminClient.query(`CREATE DATABASE "${database}"`);
+      await adminClient.query(
+        `CREATE DATABASE ${escapePgIdentifier(database)}`,
+      );
       console.log(`✅ Database ${database} created successfully`);
     } else {
       console.log(`✅ Database ${database} already exists`);
@@ -66,6 +68,10 @@ async function main(): Promise<void> {
   }
 }
 
+function escapePgIdentifier(identifier: string): string {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+
 void main().catch((error) => {
   console.error("💥 Database setup failed:", error);
   process.exit(1);

package/templates/webapp/scripts/start.sh

@@ -39,15 +39,6 @@ else
     echo "ℹ️  READONLY_SECRET_NAME not set, skipping readonly user setup"
 fi
 
-if [ -n "$ADMIN_USERNAME" ] && [ -n "$ADMIN_PASSWORD" ] && [ -n "$ADMIN_NAME" ]; then
-    echo "Creating admin user..."
-    if pnpm exec tsx scripts/create-user.ts "$ADMIN_USERNAME" "$ADMIN_PASSWORD" --name "$ADMIN_NAME"; then
-        echo "✅ Admin user created (or already exists)."
-    else
-        echo "⚠️  Failed to create admin user."
-    fi
-fi
-
 # Start the Next.js application
 echo "Starting Next.js server on port ${PORT:-3000}..."
 exec pnpm start

package/templates/webapp/src/access/access.manifest.ts

@@ -0,0 +1,15 @@
+import { defineAccessManifest } from "@percepta/access-control";
+
+export const accessManifest = defineAccessManifest({
+  adminUI: {
+    enabled: true,
+  },
+  appNamespace: "__APP_NAME_SNAKE__",
+  application: {
+    displayName: "__APP_TITLE__",
+    urlEnv: "APP_BASE_URL",
+  },
+  system: {
+    assignableRoles: ["admin"],
+  },
+} as const);

package/templates/webapp/src/access/schema.zed

@@ -0,0 +1,7 @@
+definition __APP_NAME_SNAKE__/system {
+  relation application: core/application
+  relation admin: core/user | core/group#member
+
+  permission access_app = application->access
+  permission manage_roles = access_app & (application->owner + admin)
+}

package/templates/webapp/src/app/(app)/admin/_lib/PrincipalRoleTable.tsx

@@ -0,0 +1,113 @@
+import type { SubjectRef } from "@percepta/access-control";
+import { ShieldCheck, ShieldMinus } from "lucide-react";
+import { type AccessAppRole, assignableRoles } from "./accessAdmin";
+
+type RoleAction = (formData: FormData) => Promise<void>;
+
+export interface PrincipalRoleRow {
+  readonly accessLabel: string;
+  readonly canAssignRoles?: boolean;
+  readonly detail: string;
+  readonly displayName: string;
+  readonly roles: readonly AccessAppRole[];
+  readonly subject: SubjectRef;
+}
+
+export function PrincipalRoleTable({
+  assignAction,
+  principalColumnLabel,
+  revokeAction,
+  rows,
+}: {
+  readonly assignAction: RoleAction;
+  readonly principalColumnLabel: string;
+  readonly revokeAction: RoleAction;
+  readonly rows: readonly PrincipalRoleRow[];
+}) {
+  return (
+    <div className="overflow-x-auto rounded-md border border-border">
+      <table className="w-full text-left text-sm">
+        <thead className="border-b border-border bg-muted/50 text-xs text-muted-foreground uppercase">
+          <tr>
+            <th className="px-4 py-3 font-medium">{principalColumnLabel}</th>
+            <th className="px-4 py-3 font-medium">Application Access</th>
+            <th className="px-4 py-3 font-medium">Roles</th>
+            <th className="px-4 py-3 font-medium">Actions</th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border">
+          {rows.map((principal) => (
+            <tr key={principal.subject} className="align-top">
+              <td className="px-4 py-4">
+                <div className="font-medium text-foreground">
+                  {principal.displayName}
+                </div>
+                <div className="text-muted-foreground">{principal.detail}</div>
+              </td>
+              <td className="px-4 py-4 text-foreground">
+                {principal.accessLabel}
+              </td>
+              <td className="px-4 py-4">
+                {principal.roles.length > 0 ? (
+                  <div className="flex flex-wrap gap-2">
+                    {principal.roles.map((role) => (
+                      <span
+                        key={role}
+                        className="rounded-md border border-border bg-muted px-2 py-1 text-xs font-medium text-foreground"
+                      >
+                        {role}
+                      </span>
+                    ))}
+                  </div>
+                ) : (
+                  <span className="text-muted-foreground">None</span>
+                )}
+              </td>
+              <td className="px-4 py-4">
+                <div className="flex flex-wrap gap-2">
+                  {assignableRoles.map((role) => {
+                    const hasRole = principal.roles.includes(role);
+                    const action = hasRole ? revokeAction : assignAction;
+                    return (
+                      <form action={action} key={role}>
+                        <input
+                          name="subject"
+                          type="hidden"
+                          value={principal.subject}
+                        />
+                        <input name="role" type="hidden" value={role} />
+                        <button
+                          className={
+                            hasRole
+                              ? "inline-flex h-9 items-center gap-2 rounded-md border border-border px-3 text-sm font-medium text-foreground transition-colors hover:bg-muted"
+                              : "inline-flex h-9 items-center gap-2 rounded-md bg-primary px-3 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-50"
+                          }
+                          disabled={
+                            !hasRole && principal.canAssignRoles === false
+                          }
+                          type="submit"
+                        >
+                          {hasRole ? (
+                            <>
+                              <ShieldMinus className="h-4 w-4" />
+                              Revoke {role}
+                            </>
+                          ) : (
+                            <>
+                              <ShieldCheck className="h-4 w-4" />
+                              Assign {role}
+                            </>
+                          )}
+                        </button>
+                      </form>
+                    );
+                  })}
+                </div>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/templates/webapp/src/app/(app)/admin/_lib/accessAdmin.ts

@@ -0,0 +1,85 @@
+import type { AppRole, SubjectRef } from "@percepta/access-control";
+import { revalidatePath } from "next/cache";
+import { notFound, redirect } from "next/navigation";
+import { accessManifest } from "../../../../access/access.manifest";
+import { getServerSession } from "../../../../lib/auth";
+import {
+  getAccessControl,
+  toUserSubject,
+} from "../../../../services/access/AppAccessControl";
+
+export type AccessAppRole = AppRole<typeof accessManifest>;
+
+export const assignableRoles: readonly AccessAppRole[] =
+  accessManifest.system.assignableRoles ?? [];
+
+export async function updatePrincipalRole(
+  formData: FormData,
+  operation: "assign" | "revoke",
+  path: string,
+) {
+  await requireRoleManager();
+  const app = getAccessControl().app;
+  const role = readAssignableRole(formData);
+  const subject = readPrincipalSubject(formData);
+
+  if (operation === "assign") {
+    await app.assignAppRole(role, subject);
+  } else {
+    await app.revokeAppRole(role, subject);
+  }
+
+  revalidatePath(path);
+}
+
+export async function requireRoleManager() {
+  if (!isAdminUiEnabled()) {
+    notFound();
+  }
+
+  const session = await getServerSession();
+
+  if (session?.user == null) {
+    redirect("/auth/signin");
+  }
+
+  const allowed = await getAccessControl().permissions.canStrong({
+    permission: accessManifest.system.manageRolesPermission,
+    resource: accessManifest.system.ref(),
+    subject: toUserSubject(session.user.id),
+  });
+  if (!allowed) {
+    notFound();
+  }
+}
+
+export function readAssignableRole(formData: FormData): AccessAppRole {
+  const role = formData.get("role");
+  if (
+    typeof role !== "string" ||
+    !assignableRoles.includes(role as AccessAppRole)
+  ) {
+    throw new Error("Invalid app role.");
+  }
+
+  return role as AccessAppRole;
+}
+
+function readPrincipalSubject(formData: FormData): SubjectRef {
+  const subject = formData.get("subject");
+  if (
+    typeof subject !== "string" ||
+    (!subject.startsWith("core/user:") &&
+      !/^core\/group:[^#]+#member$/.test(subject))
+  ) {
+    throw new Error("Invalid principal subject.");
+  }
+
+  return subject as SubjectRef;
+}
+
+function isAdminUiEnabled(): boolean {
+  const adminUI: { readonly enabled?: boolean } | undefined =
+    accessManifest.adminUI;
+  return adminUI?.enabled !== false;
+}

package/templates/webapp/src/app/(app)/admin/groups/page.tsx

@@ -0,0 +1,117 @@
+import type { SubjectRef } from "@percepta/access-control";
+import { db as authDb } from "@__REPO_NAME__/auth/db";
+import { groups } from "@__REPO_NAME__/auth/schema";
+import { inArray } from "drizzle-orm";
+import type { Metadata } from "next";
+import { accessManifest } from "../../../../access/access.manifest";
+import { getAccessControl } from "../../../../services/access/AppAccessControl";
+import {
+  type PrincipalRoleRow,
+  PrincipalRoleTable,
+} from "../_lib/PrincipalRoleTable";
+import { requireRoleManager, updatePrincipalRole } from "../_lib/accessAdmin";
+
+export const metadata: Metadata = {
+  title: "Groups - __APP_TITLE__",
+  description: "Groups - __APP_TITLE__",
+};
+
+const GROUP_SUBJECT_PATTERN = /^core\/group:([^#]+)#member$/;
+
+export default async function AdminGroupsPage() {
+  await requireRoleManager();
+
+  const rows = await listApplicationGroups();
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold text-foreground">Groups</h1>
+      </div>
+
+      {rows.length === 0 ? (
+        <div className="rounded-md border border-border bg-card p-8 text-sm text-muted-foreground">
+          <p className="font-medium text-foreground">No groups enrolled.</p>
+          <p className="mt-2">
+            Groups appear here after the customer identity sync projects them
+            into SpiceDB and grants this application access.
+          </p>
+        </div>
+      ) : (
+        <PrincipalRoleTable
+          assignAction={assignGroupRole}
+          principalColumnLabel="Group"
+          revokeAction={revokeGroupRole}
+          rows={rows}
+        />
+      )}
+    </div>
+  );
+}
+
+async function assignGroupRole(formData: FormData) {
+  "use server";
+
+  await updatePrincipalRole(formData, "assign", "/admin/groups");
+}
+
+async function revokeGroupRole(formData: FormData) {
+  "use server";
+
+  await updatePrincipalRole(formData, "revoke", "/admin/groups");
+}
+
+async function listApplicationGroups(): Promise<readonly PrincipalRoleRow[]> {
+  const access = getAccessControl();
+  const subjects = await access.permissions.lookupSubjects({
+    permission: accessManifest.system.accessPermission,
+    resource: accessManifest.system.ref(),
+    subjectRelation: "member",
+    subjectType: "core/group",
+  });
+
+  if (subjects.length === 0) {
+    return [];
+  }
+
+  const groupRefs = subjects.map((subject) => ({
+    id: groupIdFromSubject(subject),
+    subject,
+  }));
+  const groupNames = await listGroupNames(groupRefs.map(({ id }) => id));
+
+  const rows = await Promise.all(
+    groupRefs.map(async ({ id, subject }) => ({
+      accessLabel: "Allowed",
+      detail: subject,
+      displayName: groupNames.get(id) ?? id,
+      roles: await access.app.listAppRoles(subject),
+      subject,
+    })),
+  );
+
+  return rows.sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+
+async function listGroupNames(
+  groupIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  const groupRows = await authDb
+    .select({
+      id: groups.id,
+      name: groups.name,
+    })
+    .from(groups)
+    .where(inArray(groups.id, [...new Set(groupIds)]));
+
+  return new Map(groupRows.map((group) => [group.id, group.name]));
+}
+
+function groupIdFromSubject(subject: SubjectRef): string {
+  const id = GROUP_SUBJECT_PATTERN.exec(subject)?.[1];
+  if (id == null) {
+    throw new Error("Invalid group subject.");
+  }
+
+  return id;
+}

package/templates/webapp/src/app/(app)/admin/users/page.tsx

@@ -0,0 +1,79 @@
+import { db as authDb } from "@__REPO_NAME__/auth/db";
+import { users } from "@__REPO_NAME__/auth/schema";
+import type { Metadata } from "next";
+import { accessManifest } from "../../../../access/access.manifest";
+import {
+  getAccessControl,
+  toUserSubject,
+} from "../../../../services/access/AppAccessControl";
+import { PrincipalRoleTable } from "../_lib/PrincipalRoleTable";
+import { requireRoleManager, updatePrincipalRole } from "../_lib/accessAdmin";
+
+export const metadata: Metadata = {
+  title: "Users - __APP_TITLE__",
+  description: "Users - __APP_TITLE__",
+};
+
+export default async function AdminUsersPage() {
+  await requireRoleManager();
+
+  const access = getAccessControl();
+  const userRows = await authDb
+    .select({
+      email: users.email,
+      id: users.id,
+      name: users.name,
+    })
+    .from(users)
+    .orderBy(users.email);
+
+  const rows = await Promise.all(
+    userRows.map(async (user) => {
+      const subject = toUserSubject(user.id);
+      const [canAccessApp, roles] = await Promise.all([
+        access.permissions.can({
+          permission: accessManifest.system.accessPermission,
+          resource: accessManifest.system.ref(),
+          subject,
+        }),
+        access.app.listAppRoles(subject),
+      ]);
+
+      return {
+        accessLabel: canAccessApp ? "Allowed" : "Not enrolled",
+        canAssignRoles: canAccessApp,
+        detail: user.email,
+        displayName: user.name,
+        roles,
+        subject,
+      };
+    }),
+  );
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold text-foreground">Users</h1>
+      </div>
+
+      <PrincipalRoleTable
+        assignAction={assignUserRole}
+        principalColumnLabel="User"
+        revokeAction={revokeUserRole}
+        rows={rows}
+      />
+    </div>
+  );
+}
+
+async function assignUserRole(formData: FormData) {
+  "use server";
+
+  await updatePrincipalRole(formData, "assign", "/admin/users");
+}
+
+async function revokeUserRole(formData: FormData) {
+  "use server";
+
+  await updatePrincipalRole(formData, "revoke", "/admin/users");
+}

package/templates/webapp/src/app/(app)/layout.tsx

@@ -1,7 +1,21 @@
-import React from "react";
+import { notFound, redirect } from "next/navigation";
+import type { ReactNode } from "react";
 import Header from "../../components/Header";
+import { getServerSession } from "../../lib/auth";
+import { canAccessApplication } from "../../services/access/AppAccessControl";
+
+export default async function AppLayout({ children }: { children: ReactNode }) {
+  const session = await getServerSession();
+
+  if (session?.user == null) {
+    redirect("/auth/signin");
+  }
+
+  const canAccessApp = await canAccessApplication(session.user.id);
+  if (!canAccessApp) {
+    notFound();
+  }
 
-export default function AppLayout({ children }: { children: React.ReactNode }) {
   return (
     <>
       <Header />

package/templates/webapp/src/app/(app)/page.tsx

@@ -1,22 +1,11 @@
 import type { Metadata } from "next";
-import { headers } from "next/headers";
-import { redirect } from "next/navigation";
-import { auth } from "../../lib/auth";
 
 export const metadata: Metadata = {
   title: "__APP_TITLE__",
   description: "__APP_TITLE__",
 };
 
-export default async function HomePage() {
-  const session = await auth.api.getSession({
-    headers: await headers(),
-  });
-
-  if (session?.user == null) {
-    redirect("/auth/signin");
-  }
-
+export default function HomePage() {
   return (
     <div className="space-y-8">
       <h1 className="text-center text-2xl font-bold text-foreground">

package/templates/webapp/src/app/(auth)/auth/signin/page.tsx

@@ -1,8 +1,7 @@
 import type { Metadata } from "next";
-import { headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { Suspense } from "react";
-import { auth } from "../../../../lib/auth";
+import { getServerSession } from "../../../../lib/auth";
 import { CredentialsSignInForm } from "./CredentialsSignInForm";
 
 export const metadata: Metadata = {
@@ -10,9 +9,7 @@ export const metadata: Metadata = {
 };
 
 export default async function SignInPage() {
-  const session = await auth.api.getSession({
-    headers: await headers(),
-  });
+  const session = await getServerSession();
 
   if (session?.user != null) {
     redirect("/");