The Four Enforcement Points Every Application Surface Needs

// app/(portal)/docs/[id]/page.tsx
import { alfiz } from "@/lib/alfiz";
import { getSession } from "@/lib/session";
import { DocumentEditor } from "./DocumentEditor";

export default async function DocPage({ params }: { params: { id: string } }) {
  const session = await getSession();
  const scope = `docs.doc:${params.id}` as const;

  // Point 1: gate the page
  const snap = await alfiz.snapshot(
    { userId: session.userId },
    { scopes: [scope] },
  );
  snap.require("docs.files.read", scope);

  const doc = await db.docs.findUniqueOrThrow({ where: { id: params.id } });

  // Point 4: conditional UI resolved from the snapshot
  const canEdit   = snap.can("docs.files.update_file", scope);
  const canDelete = snap.can("docs.files.delete", scope);

  return (
    <DocumentEditor
      doc={doc}
      canEdit={canEdit}
      canDelete={canDelete}
    />
  );
}

// app/(portal)/layout.tsx
import { alfiz } from "@/lib/alfiz";
import { getSession } from "@/lib/session";
import { NavLink } from "@/components/NavLink";

export default async function PortalLayout({ children }) {
  const session = await getSession();
  const principal = { userId: session.userId };

  // Point 2: navigation visibility
  const showDocs    = await alfiz.canAny(principal, "docs.*");
  const showAdmin   = await alfiz.canAny(principal, "admin.*");

  return (
    <div>
      <nav>
        {showDocs  && <NavLink href="/docs">Documents</NavLink>}
        {showAdmin && <NavLink href="/admin">Admin</NavLink>}
      </nav>
      {children}
    </div>
  );
}

// app/actions/documents.ts
"use server";

import { alfiz } from "@/lib/alfiz";
import { getSession } from "@/lib/session";
import { AccessDeniedError } from "@alfiz/core";

export async function saveDocument(docId: string, data: { title: string; body: string }) {
  const session = await getSession();
  const scope = `docs.doc:${docId}` as const;

  // Point 3: gate the action before any work
  await alfiz.require(
    { userId: session.userId },
    "docs.files.update_file",
    scope,
  );

  return db.docs.update({ where: { id: docId }, data });
}

export async function deleteDocument(docId: string) {
  const session = await getSession();
  const scope = `docs.doc:${docId}` as const;

  // Point 3: destructive: bypass caches
  if (!(await alfiz.can.fresh({ userId: session.userId }, "docs.files.delete", scope))) {
    throw new AccessDeniedError({ reason: "forbidden", permission: "docs.files.delete", scope });
  }

  return db.docs.delete({ where: { id: docId } });
}

// app/(portal)/docs/[id]/DocumentEditor.tsx
import { SaveButton } from "@/components/SaveButton";
import { DeleteButton } from "@/components/DeleteButton";

interface Props {
  doc: Doc;
  canEdit: boolean;
  canDelete: boolean;
}

export function DocumentEditor({ doc, canEdit, canDelete }: Props) {
  return (
    <article>
      <h1>{doc.title}</h1>
      <div>{doc.body}</div>
      <footer>
        {/* Point 4: render controls only when the check passed */}
        {canEdit   && <SaveButton docId={doc.id} />}
        {canDelete && <DeleteButton docId={doc.id} />}
      </footer>
    </article>
  );
}