Given the current auth projection,
what should the user be able to see, attempt, understand, and recover from?

user.role === "admin"

can("case.approve", caseResource)
can("case.assign", caseResource)
can("case.comment.create", caseResource)
can("case.penalty.edit", caseResource)

Frontend permission logic controls exposure.
Backend authorization controls access.

Can this user do X?

Should the user see X?
If not, should we hide it, disable it, or explain it?
Can the user request access?
Can this denial be remediated?
Is the denial due to role, state, tenant, ownership, policy, expiry, or assurance level?

case.read
case.create
case.assign
case.approve
case.reject
case.penalty.edit
case.evidence.upload
case.evidence.delete
case.audit.view
user.invite
user.role.assign

admin
manager
canClickApproveButton
showAdminPanel
isCaseApprover
level3
superUser

<resource>.<action>
<resource>.<field>.<action>
<resource>.<subresource>.<action>
<domain>.<resource>.<action>

case.read
case.update
case.assign
case.transition.approve
case.transition.reject
case.penalty.read
case.penalty.edit
case.evidence.upload
case.evidence.delete
case.audit.view
org.member.invite
org.member.remove
org.role.assign

button.show
modal.open
tab.visible
link.click

case.approve
case.assign
case.audit.view

const canApprove = can("case.approve", caseResource);

type PermissionDecision =
  | {
      allowed: true;
      reason?: string;
      source: "session" | "resource" | "policy";
      evaluatedAt: string;
    }
  | {
      allowed: false;
      reason: PermissionDenialReason;
      message: string;
      remediable: boolean;
      requestAccess?: {
        workflow: "access-request" | "step-up" | "tenant-switch";
        target: string;
      };
      evaluatedAt: string;
    };

type PermissionDenialReason =
  | "anonymous"
  | "session_expired"
  | "tenant_mismatch"
  | "missing_permission"
  | "resource_state"
  | "ownership_required"
  | "assurance_too_low"
  | "separation_of_duties"
  | "policy_temporarily_unavailable"
  | "unknown";

unknown => do not expose privileged actions
loading => do not expose privileged actions
error => do not expose privileged actions
stale => do not expose privileged actions until revalidated, unless explicitly safe read-only fallback

function isAllowed(decision: PermissionDecision | undefined): boolean {
  return decision?.allowed === true;
}

// Dangerous: undefined becomes allowed.
function isAllowed(decision: PermissionDecision | undefined): boolean {
  return decision?.allowed !== false;
}

{
  "user": {
    "id": "u_123",
    "displayName": "Ari"
  },
  "tenant": {
    "id": "t_001",
    "slug": "acme"
  },
  "permissions": [
    "case.read",
    "case.create",
    "case.assign",
    "case.audit.view"
  ],
  "permissionEpoch": "perm_2026_07_08_001"
}

{
  "id": "case_900",
  "status": "UNDER_REVIEW",
  "assigneeId": "u_123",
  "allowedActions": [
    "case.read",
    "case.comment.create",
    "case.transition.approve",
    "case.transition.reject"
  ]
}

POST /api/authorization/check
Content-Type: application/json

{
  "action": "case.transition.approve",
  "resource": {
    "type": "case",
    "id": "case_900"
  },
  "context": {
    "tenantId": "t_001"
  }
}

{
  "allowed": false,
  "reason": "separation_of_duties",
  "message": "You cannot approve a case you investigated.",
  "remediable": false,
  "evaluatedAt": "2026-07-08T10:00:00+07:00"
}

// Wrong mental model.
const canApproveAnyCase = session.permissions.includes("case.approve");

const canEnterCaseReviewArea = session.permissions.includes("case.review.view");
const canApproveThisCase = case.allowedActions.includes("case.transition.approve");

Can this user generally access this capability area?

Can this user do this action on this specific object now?

type Permission = string;

type AuthProjection = {
  user: {
    id: string;
    displayName: string;
  };
  tenant: {
    id: string;
    slug: string;
  };
  permissions: Permission[];
  permissionEpoch: string;
  sessionEpoch: string;
};

type PermissionStore = {
  status: "unknown" | "loading" | "ready" | "stale" | "error";
  projection?: AuthProjection;
};

function createPermissionSet(projection: AuthProjection | undefined): ReadonlySet<Permission> {
  return new Set(projection?.permissions ?? []);
}

function hasPermission(
  projection: AuthProjection | undefined,
  permission: Permission
): boolean {
  if (!projection) return false;
  return projection.permissions.includes(permission);
}

type ResourceLike = {
  type: string;
  id?: string;
  tenantId?: string;
  allowedActions?: string[];
};

type CanInput = {
  action: string;
  resource?: ResourceLike;
};

type CanResult = {
  allowed: boolean;
  source: "session" | "resource" | "none";
  reason?: string;
};

function can(
  projection: AuthProjection | undefined,
  input: CanInput
): CanResult {
  if (!projection) {
    return {
      allowed: false,
      source: "none",
      reason: "permission_projection_missing",
    };
  }

  if (input.resource?.tenantId && input.resource.tenantId !== projection.tenant.id) {
    return {
      allowed: false,
      source: "none",
      reason: "tenant_mismatch",
    };
  }

  if (input.resource?.allowedActions) {
    return {
      allowed: input.resource.allowedActions.includes(input.action),
      source: "resource",
      reason: input.resource.allowedActions.includes(input.action)
        ? undefined
        : "resource_action_not_allowed",
    };
  }

  return {
    allowed: projection.permissions.includes(input.action),
    source: "session",
    reason: projection.permissions.includes(input.action)
      ? undefined
      : "session_permission_missing",
  };
}

function useCan(action: string, resource?: ResourceLike): CanResult {
  const projection = useAuthProjection();

  return useMemo(
    () => can(projection, { action, resource }),
    [projection?.permissionEpoch, projection?.tenant.id, action, resource?.id, resource?.allowedActions]
  );
}

const canApprove = useCanApproveCase(caseId);

const canApprove = useCan("case.transition.approve", case);

function useCanApproveCase(caseRecord: CaseSummary) {
  return useCan("case.transition.approve", caseRecord);
}

type CanProps = {
  action: string;
  resource?: ResourceLike;
  children: React.ReactNode;
  fallback?: React.ReactNode;
};

export function Can({ action, resource, children, fallback = null }: CanProps) {
  const decision = useCan(action, resource);

  if (!decision.allowed) return <>{fallback}</>;

  return <>{children}</>;
}

<Can action="case.transition.approve" resource={caseRecord}>
  <ApproveCaseButton caseId={caseRecord.id} />
</Can>

Hide “Delete tenant” from regular users.
Disable “Approve” on a closed case with reason “Closed cases cannot be approved.”
Show “Request access” for a report the user may legitimately need.
Trigger step-up auth for changing payout bank details.
Return 404-like not-found for objects whose existence must not be disclosed.

type AuthorizedButtonProps = {
  action: string;
  resource?: ResourceLike;
  children: React.ReactNode;
  onClick: () => void;
  denialMode?: "hide" | "disable" | "explain";
};

function AuthorizedButton({
  action,
  resource,
  children,
  onClick,
  denialMode = "disable",
}: AuthorizedButtonProps) {
  const decision = useCan(action, resource);

  if (!decision.allowed && denialMode === "hide") {
    return null;
  }

  if (!decision.allowed && denialMode === "explain") {
    return (
      <div>
        <button type="button" disabled>
          {children}
        </button>
        <p role="note">You do not have access to perform this action.</p>
      </div>
    );
  }

  return (
    <button type="button" disabled={!decision.allowed} onClick={onClick}>
      {children}
    </button>
  );
}

const menu = [
  { label: "Dashboard", href: "/dashboard" },
  { label: "Users", href: "/admin/users", role: "admin" },
  { label: "Audit", href: "/audit", role: "admin" },
];

type MenuItem = {
  label: string;
  href: string;
  permission?: string;
  children?: MenuItem[];
};

const menu: MenuItem[] = [
  { label: "Dashboard", href: "/dashboard" },
  { label: "Cases", href: "/cases", permission: "case.read" },
  { label: "Users", href: "/admin/users", permission: "user.manage" },
  { label: "Audit", href: "/audit", permission: "audit.view" },
];

function filterMenu(items: MenuItem[], projection: AuthProjection | undefined): MenuItem[] {
  return items
    .map((item) => {
      const children = item.children
        ? filterMenu(item.children, projection)
        : undefined;

      const allowed = !item.permission || hasPermission(projection, item.permission);

      if (!allowed && (!children || children.length === 0)) {
        return null;
      }

      return { ...item, children };
    })
    .filter((item): item is MenuItem => item !== null);
}

Menu visibility must not be the only route protection.

export const handle = {
  auth: {
    required: true,
    permission: "case.read",
  },
};

type RouteAuthHandle = {
  auth?: {
    required?: boolean;
    permission?: string;
  };
};

Can the user enter this area?

Can the user approve this case?
Can the user edit this field?
Can the user delete this evidence file?

{cases.map((caseRecord) => (
  <tr key={caseRecord.id}>
    <td>{caseRecord.reference}</td>
    <td>
      <ApproveButton caseId={caseRecord.id} />
      <RejectButton caseId={caseRecord.id} />
    </td>
  </tr>
))}

{cases.map((caseRecord) => {
  const canApprove = can(projection, {
    action: "case.transition.approve",
    resource: caseRecord,
  });

  const canReject = can(projection, {
    action: "case.transition.reject",
    resource: caseRecord,
  });

  return (
    <tr key={caseRecord.id}>
      <td>{caseRecord.reference}</td>
      <td>{caseRecord.status}</td>
      <td>
        <button disabled={!canApprove.allowed}>Approve</button>
        <button disabled={!canReject.allowed}>Reject</button>
      </td>
    </tr>
  );
})}

type CaseRow = {
  id: string;
  reference: string;
  status: "DRAFT" | "UNDER_REVIEW" | "APPROVED" | "REJECTED";
  tenantId: string;
  allowedActions: string[];
};

none eligible
some eligible
all eligible
unknown

type BulkEligibility = {
  eligibleIds: string[];
  ineligibleIds: string[];
  unknownIds: string[];
};

function computeBulkEligibility(
  selected: CaseRow[],
  action: string,
  projection: AuthProjection | undefined
): BulkEligibility {
  const result: BulkEligibility = {
    eligibleIds: [],
    ineligibleIds: [],
    unknownIds: [],
  };

  for (const item of selected) {
    if (!item.allowedActions) {
      result.unknownIds.push(item.id);
      continue;
    }

    const decision = can(projection, { action, resource: item });

    if (decision.allowed) result.eligibleIds.push(item.id);
    else result.ineligibleIds.push(item.id);
  }

  return result;
}

{
  "id": "case_900",
  "reference": "CASE-2026-000900",
  "status": "UNDER_REVIEW",
  "fields": {
    "penaltyAmount": {
      "value": 5000000,
      "access": "read-write"
    },
    "internalNotes": {
      "access": "redacted",
      "reason": "internal_notes_permission_missing"
    }
  }
}

Server filters sensitive data.
React renders the filtered projection.

<button disabled={!isAdmin}>Delete</button>

Can this subject delete this exact resource under this context?

type AuthProjection = {
  sessionEpoch: string;
  permissionEpoch: string;
  tenantEpoch: string;
  policyEpoch?: string;
};

const queryKey = [
  "case",
  caseId,
  auth.tenant.id,
  auth.permissionEpoch,
  auth.policyEpoch,
];

queryClient.invalidateQueries({ queryKey: ["case"] });
queryClient.invalidateQueries({ queryKey: ["case-list"] });
queryClient.invalidateQueries({ queryKey: ["navigation"] });

queryClient.clear();

export const Permissions = {
  CaseRead: "case.read",
  CaseCreate: "case.create",
  CaseApprove: "case.transition.approve",
  CaseReject: "case.transition.reject",
  CasePenaltyEdit: "case.penalty.edit",
} as const;

export type Permission = (typeof Permissions)[keyof typeof Permissions];

case.approve

case.transition.approve_low_value
case.transition.approve_high_value

{
  "permissionContractVersion": "2026-07-01",
  "permissions": [
    "case.transition.approve_low_value",
    "case.transition.approve_high_value"
  ],
  "deprecatedPermissions": [
    "case.approve"
  ]
}

const canReadAudit = useCan("case.audit.view", caseRecord);

const auditQuery = useQuery({
  queryKey: ["case-audit", caseRecord.id, auth.permissionEpoch],
  queryFn: () => fetchCaseAudit(caseRecord.id),
  enabled: canReadAudit.allowed,
});

async function fetchCaseAudit(caseId: string) {
  const response = await fetch(`/api/cases/${caseId}/audit`);

  if (response.status === 403) {
    throw new AuthzError("case.audit.view denied");
  }

  if (!response.ok) throw new Error("Failed to load audit");

  return response.json();
}

{
  "allowed": false,
  "reason": "missing_permission",
  "message": "You need Case Reviewer access to approve this case.",
  "remediable": true,
  "requestAccess": {
    "workflow": "access-request",
    "target": "case.transition.approve",
    "resourceId": "case_900"
  }
}

if (!decision.allowed && decision.requestAccess) {
  return (
    <AccessDeniedPanel
      message={decision.message}
      onRequestAccess={() => openAccessRequest(decision.requestAccess)}
    />
  );
}

{
  "allowed": false,
  "reason": "assurance_too_low",
  "message": "Please verify your identity again to continue.",
  "remediable": true,
  "requestAccess": {
    "workflow": "step-up",
    "target": "case.penalty.edit"
  }
}

show action -> on click -> start step-up -> return to intended action -> re-check -> execute

if (flags.newAdminPanel) {
  showAdminPanel();
}

if (flags.newAdminPanel && can("admin.console.view").allowed) {
  showAdminPanel();
}

type Command = {
  id: string;
  label: string;
  run: () => void;
  permission?: string;
};

function filterCommands(commands: Command[], projection: AuthProjection | undefined) {
  return commands.filter((command) => {
    if (!command.permission) return true;
    return hasPermission(projection, command.permission);
  });
}

function runCommand(command: Command) {
  if (command.permission && !hasPermission(auth.projection, command.permission)) {
    throw new Error("Command denied");
  }

  command.run();
}

No cases found.

if (!canReadCases.allowed) {
  return <NoAccess message="You do not have access to view cases." />;
}

if (query.isLoading) {
  return <CasesSkeleton />;
}

if (query.data.items.length === 0) {
  return <EmptyCases />;
}

Case not found or you do not have access.

analytics.track("Permission denied", {
  userId,
  action: "case.audit.view",
  caseId,
  reason: "high_value_case_restricted_by_investigation_unit",
});

internalTelemetry.record("authz.ui_denied", {
  action: "case.audit.view",
  resourceType: "case",
  reasonClass: "missing_permission",
  tenantId,
  correlationId,
});

it("does not render approve button while permission projection is unknown", () => {
  render(
    <AuthProjectionProvider value={{ status: "unknown" }}>
      <CaseToolbar caseRecord={caseUnderReview} />
    </AuthProjectionProvider>
  );

  expect(screen.queryByRole("button", { name: /approve/i })).not.toBeInTheDocument();
});

it("uses resource allowedActions over broad session permission", () => {
  const projection = makeProjection({ permissions: ["case.transition.approve"] });
  const closedCase = makeCase({
    status: "APPROVED",
    allowedActions: ["case.read"],
  });

  render(
    <AuthProjectionProvider value={{ status: "ready", projection }}>
      <CaseToolbar caseRecord={closedCase} />
    </AuthProjectionProvider>
  );

  expect(screen.getByRole("button", { name: /approve/i })).toBeDisabled();
});

{
  "scenario": "reviewer_can_approve_case_under_review",
  "subject": "u_reviewer",
  "tenant": "t_001",
  "resource": "case_under_review_assigned_to_other_investigator",
  "expectedAllowedActions": [
    "case.read",
    "case.transition.approve",
    "case.transition.reject"
  ]
}

Backend policy changed.
Frontend assumption did not.

{user.role === "admin" && <DeleteUserButton />}

<Can action="user.delete" resource={targetUser}>
  <DeleteUserButton />
</Can>

User cannot see menu item, so route must be safe.

const canEdit = caseRecord.createdBy === user.id;

// User requested access, so show button immediately.
setCanApprove(true);

.secret {
  display: none;
}

Backend policy decides.
API projects safe permission facts.
React renders based on those facts.
Every mutation is still checked server-side.
Every stale projection is treated as suspicious.
Every denial has a typed recovery path.