gate-the-dashboard

Skill: gate-the-dashboard

Invoked by: any agent building or securing an analytics dashboard or embedded BI feature; ravenclaude-core/security-reviewer for any embed-auth or dashboard-access change.

When to invoke: adding authentication to the analytics dashboard or any embedded BI component; designing the access-control handoff between the identity layer and the data isolation layer; auditing an existing dashboard that may be accessible without authentication.

Output: dashboard login gate implemented + server-side session check + embed JWT issuance endpoint created + data-platform RLS seam documented + cross-boundary isolation verified.

---

Two-layer contract (this skill's core job)

[User] -- Google SSO --> [auth-identity: authenticated session + auth.uid()]
                                    |
                           Dashboard access gate
                           (this skill: is user logged in? do they have dashboard role?)
                                    |
                           [App shell renders dashboard page]
                                    |
                           [Server issues short-lived embed JWT]
                           (tenant_id from authenticated session — NOT from URL)
                                    |
                           [data-platform: embed verifies JWT, RLS scopes rows]
                           (rls-policy-authoring + jwt-embed-issuance skills)

Layer 1 (this skill): prove who the person is and whether they can see the dashboard at all. Layer 2 (data-platform): prove which data rows that person is allowed to see.

Do not duplicate the Layer 2 mechanics here. Reference them. They are owned by:

• data-platform/skills/jwt-embed-issuance/SKILL.md — short-lived embed JWT with tenant_id
• data-platform/skills/rls-policy-authoring/SKILL.md — Postgres RLS scoping
• data-platform/best-practices/issue-short-lived-jwts-for-embeds.md — embed JWT absolute rule
• data-platform/best-practices/embed-never-ship-the-service-key.md — secret handling rule

---

Step 1 — Protect the dashboard route

The dashboard page must check authentication server-side before rendering any content or loading any embed:

// app/dashboard/page.tsx (Next.js App Router server component)
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const cookieStore = cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } },
  );

  // Server-side validation — not trusting the cookie without verification
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) redirect("/login?next=/dashboard");

  // Optional: role check for dashboard-specific access
  const role = user.app_metadata?.role ?? "viewer";
  if (!["viewer", "editor", "admin"].includes(role)) {
    redirect("/unauthorized");
  }

  // Pass user identity to the dashboard shell — no raw tokens
  return <DashboardShell userId={user.id} userEmail={user.email} />;
}

If using Next.js middleware (recommended), the middleware already redirects unauthenticated users before the page renders. The Server Component check is defense-in-depth.

---

Step 2 — Issue the embed JWT server-side

The dashboard embed requires a short-lived JWT with the user's tenant_id to scope data. This token is issued by a server-side API route after authentication is verified. The signing secret never leaves the server.

// app/api/embed-token/route.ts — conceptual; security-review before production
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import { SignJWT } from "jose";

export async function POST(request: Request) {
  const cookieStore = cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } },
  );

  const { data: { user }, error } = await supabase.auth.getUser();
  if (!user || error) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Resolve tenant_id from the authenticated session — NOT from the request body
  const { data: membership } = await supabase
    .from("tenant_memberships")
    .select("tenant_id")
    .eq("user_id", user.id)
    .single();

  if (!membership?.tenant_id) {
    return NextResponse.json({ error: "No tenant" }, { status: 403 });
  }

  // Issue short-lived JWT — 10 min, server-signed, tenant-scoped
  // signing secret from env var — never hard-coded, never NEXT_PUBLIC_
  const secret = new TextEncoder().encode(process.env.EMBED_JWT_SECRET!);
  const token = await new SignJWT({
    sub: user.id,
    tenant_id: membership.tenant_id,
    iss: "app.example.com",
    aud: "cube", // or "superset" / "metabase" — the embed tool
  })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime("10m") // 5-15 min per data-platform embed JWT rule
    .sign(secret);

  return NextResponse.json({ token });
}

Mandatory: route this code to ravenclaude-core/security-reviewer before production. The data-platform/skills/jwt-embed-issuance/SKILL.md owns the full claim-shape specification (required: sub, tenant_id, iat, exp, iss, aud; recommended: nonce, allowed_dashboards).

---

Step 3 — Client fetches the embed token and passes it to the embed

// components/DashboardEmbed.tsx — client component
"use client";
import { useEffect, useState } from "react";

export function DashboardEmbed() {
  const [embedToken, setEmbedToken] = useState<string | null>(null);

  useEffect(() => {
    // Fetch the embed token from our server — it does NOT leave in the HTML
    fetch("/api/embed-token", { method: "POST" })
      .then((r) => r.json())
      .then(({ token }) => setEmbedToken(token));
  }, []);

  if (!embedToken) return <div>Loading dashboard…</div>;

  // Pass to your embed component (Cube SDK, Superset SDK, iframe URL param, etc.)
  // The token is short-lived and tenant-scoped — safe to pass to the embed
  return <YourEmbedComponent apiToken={embedToken} />;
  // ❌ NEVER: pass process.env.EMBED_JWT_SECRET or any signing secret here
}

---

Step 4 — Data isolation (data-platform's responsibility)

Once the embed token is in the embed component, data isolation is enforced by the data-platform plugin:

• The embed tool (Cube, Superset, Metabase) verifies the JWT signature.
• It extracts tenant_id from the verified JWT.
• Postgres RLS policies or Cube securityContext rules scope all queries to that tenant_id.

The auth-identity plugin's job ends at Step 3. Do not implement RLS policies or Cube securityContext rules here. Refer to:

• data-platform/skills/rls-policy-authoring/SKILL.md
• data-platform/skills/jwt-embed-issuance/SKILL.md
• data-platform/skills/cube-schema-scaffolding/SKILL.md

---

The generated dashboard.html (marketplace analytics dashboard)

For the RavenClaude marketplace's own analytics dashboard (dashboard.html), the same two-layer pattern applies:

1. The dashboard shell is only rendered after a successful Supabase Auth session check.
2. Any BI embed within dashboard.html receives a short-lived server-issued JWT scoped to the authenticated user's context.
3. The embed's data queries are gated by Postgres RLS — the user only sees their own data.

---

Anti-patterns this skill flags

• Dashboard page renders without server-side authentication check (relying only on client-side redirect)
• Embed JWT issued without verifying the user's session first
• tenant_id in the embed JWT derived from the URL or request body (not from the authenticated session)
• Signing secret for embed JWT in a NEXT_PUBLIC_ env var or in the client bundle
• Embed JWT with exp > 30 minutes (absolute rule — see data-platform embed JWT best-practice)
• Skipping the data-platform RLS layer and relying on app-code row filtering as the data isolation control
• Dashboard accessible without authentication in any environment (including staging and preview)
• No cross-boundary denial test — required before shipping (see data-platform's rls-cross-tenant-test.sql template)

---

Verification checklist

• Dashboard route redirects to login when session is absent (server-side check)
• Embed token API route verifies session before issuing token
• tenant_id in embed JWT comes from server-side session, not from URL/request body
• EMBED_JWT_SECRET is in a server-side env var, not NEXT_PUBLIC_
• Embed JWT exp is 5-15 minutes
• data-platform's rls-policy-authoring skill has been applied (denial test passing)
• Cross-boundary denial test: user A cannot see user B's data
• Security review completed for embed token issuance code

---

See also

• Skill: ../protect-spa-and-api/SKILL.md — the underlying route-guard mechanics
• Skill: ../authorization-rbac/SKILL.md — dashboard role check
• Best-practice: ../../best-practices/authenticate-the-person-authorize-the-data-separately.md
• data-platform: ../../../data-platform/skills/jwt-embed-issuance/SKILL.md — the canonical JWT claim shape and verification pattern for embeds
• data-platform: ../../../data-platform/skills/rls-policy-authoring/SKILL.md — data-row scoping after the embed JWT is validated
• data-platform: ../../../data-platform/best-practices/issue-short-lived-jwts-for-embeds.md — the absolute rule this skill enforces
• data-platform: ../../../data-platform/best-practices/embed-never-ship-the-service-key.md — secret handling
• Security escalation: ../../../ravenclaude-core/agents/security-reviewer.md