Unified Access Control & Admin Panel
Development Specification

One Admin Panel. All Access Decisions.

Today, access to gated Salud Capital content is managed in two disconnected ways: research document HTML files contain hardcoded SHA-256 password hashes and manually maintained email lists, and the website has no centralized user management. This creates operational drag — adding an investor means editing code — and no audit trail of who accessed what.

The target state is a single Salud Capital Admin Panel where any authorized administrator can provision, modify, and revoke access for employees, investors, and research readers across every gated surface of the SaludCap platform — website sections, investor portals, and individual research documents — from one interface.

Three Tiers, Four Surfaces, One Source of Truth

Access Tiers

Gated Surfaces & Tier Requirements

★ Investors get Vault Appendix access only if the "Vault Appendix" permission toggle is individually enabled for their account in the admin panel. Default = off for investors.

Per-User Permission Flags

Beyond tier, each user account carries a set of boolean permission flags that admin can toggle independently. This allows granular control — e.g. an investor who gets all research but not the Vault Appendix, or a research partner who gets one specific report but not the investor portal.

How the Pieces Connect

Authentication Flow

Migration: Hardcoded SHA-256 → Centralized Auth

// ❌ Old approach — hardcoded in each HTML file
const PASS_HASH = '98364381a28f...';
const AUTHORIZED = ['@saludcap.com', '@saludwireless.com'];
async function vaultAuth() { /* SHA-256 check */ }

// ✅ New approach — research HTML calls auth service
async function initResearchDoc() {
  const token = localStorage.getItem('sc_auth_token');
  if (!token) { showLoginPrompt(); return; }

  const res = await fetch('https://auth.saludcap.com/api/verify-token', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  if (!res.ok) { showLoginPrompt(); return; }

  const { permissions, email } = await res.json();
  // permissions = { can_gated_research, can_vault_appendix, ... }

  if (permissions.can_vault_appendix) {
    document.getElementById('vault-appendix').classList.add('unlocked');
  }
  logAccess(token, 'digital_payments_research_v1'); // audit event
}

Data Model — Postgres (Supabase Recommended)

-- Users table
CREATE TABLE users (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email         TEXT UNIQUE NOT NULL,
  password_hash TEXT,                    -- bcrypt; null if magic-link-only
  tier          TEXT NOT NULL DEFAULT 'investor',  -- admin | employee | investor | public
  display_name  TEXT,
  company       TEXT,
  created_at    TIMESTAMPTZ DEFAULT now(),
  last_login_at TIMESTAMPTZ,
  expires_at    TIMESTAMPTZ,             -- null = no expiry; set for time-boxed investors
  is_active     BOOLEAN DEFAULT true,
  invited_by    UUID REFERENCES users(id)
);

-- Permission flags (one row per user, all flags)
CREATE TABLE user_permissions (
  user_id               UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
  can_investor_portal   BOOLEAN DEFAULT false,
  can_gated_research    BOOLEAN DEFAULT false,
  can_vault_appendix    BOOLEAN DEFAULT false,   -- Salud Vault confidential appendix
  can_employee_sections BOOLEAN DEFAULT false,
  report_allowlist      TEXT[] DEFAULT '{}',      -- array of report slugs
  updated_at            TIMESTAMPTZ DEFAULT now(),
  updated_by            UUID REFERENCES users(id)
);

-- Authorized email domains (auto-grants EMPLOYEE tier)
CREATE TABLE authorized_domains (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  domain     TEXT UNIQUE NOT NULL,   -- e.g. 'saludwireless.com'
  auto_tier  TEXT DEFAULT 'employee',
  added_by   UUID REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Invite tokens (for investor onboarding)
CREATE TABLE invite_tokens (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  token       TEXT UNIQUE NOT NULL DEFAULT gen_random_uuid()::text,
  email       TEXT NOT NULL,
  tier        TEXT NOT NULL DEFAULT 'investor',
  permissions JSONB,                  -- pre-set permission flags for this invite
  expires_at  TIMESTAMPTZ NOT NULL,   -- invite link expiry (typically 7 days)
  used_at     TIMESTAMPTZ,
  created_by  UUID REFERENCES users(id)
);

-- Audit log
CREATE TABLE access_log (
  id          BIGSERIAL PRIMARY KEY,
  user_id     UUID REFERENCES users(id),
  email       TEXT,                   -- denormalized for easy log reading
  event_type  TEXT NOT NULL,          -- login | view_research | unlock_vault | invite_sent | access_revoked
  resource_id TEXT,                   -- report slug, page path, etc.
  ip_address  INET,
  user_agent  TEXT,
  metadata    JSONB,
  created_at  TIMESTAMPTZ DEFAULT now()
);

-- Default permissions by tier (for new user initialization)
-- Employee: all internal flags on. Investor: portal + research on; vault off.
CREATE VIEW default_permissions AS
SELECT 'employee' AS tier, true AS can_investor_portal, true AS can_gated_research,
       true AS can_vault_appendix, true AS can_employee_sections
UNION ALL
SELECT 'investor', true, true, false, false;

Recommended Stack

Admin Panel — Screen-by-Screen

The admin panel lives at /admin and is accessible only to accounts with tier = 'admin'. It is the single interface for all access management across the SaludCap platform.

Panel Wireframe — Users Screen

Admin Panel — All Screens

Invite Flow — Investor Onboarding

Auth Service API — Required Endpoints

All endpoints hosted under https://auth.saludcap.com/api/ (Vercel Edge Function or Next.js API route). All authenticated endpoints require Authorization: Bearer <jwt>.

// GET /api/verify-token
// Response 200:
{
  "valid": true,
  "user_id": "uuid-...",
  "email": "investor@example.com",
  "tier": "investor",
  "display_name": "J. Smith",
  "permissions": {
    "can_investor_portal": true,
    "can_gated_research": true,
    "can_vault_appendix": false,   // ← controls Vault appendix visibility
    "can_employee_sections": false,
    "report_allowlist": ["genius_act_research", "crypto_policy_trump_biden"]
  },
  "expires_at": "2026-07-01T00:00:00Z"
}

// Response 401 (expired or invalid token):
{ "valid": false, "error": "token_expired" }

// Drop-in script for every gated research HTML file
// Replaces the current hardcoded SHA-256 auth block entirely

(async function saludAuth() {
  const token = localStorage.getItem('sc_auth_token');
  const loginUrl = 'https://saludcap.github.io/salud/login?return='
                 + encodeURIComponent(location.href);

  // No token → redirect to login
  if (!token) { location.href = loginUrl; return; }

  try {
    const res = await fetch('https://auth.saludcap.com/api/verify-token', {
      headers: { Authorization: 'Bearer ' + token }
    });
    if (!res.ok) { location.href = loginUrl; return; }

    const { permissions, email, tier } = await res.json();

    // Gate: gated research requires can_gated_research
    if (!permissions.can_gated_research) {
      document.getElementById('gated-gate').style.display = 'block';
      return;
    }

    // Vault Appendix: controlled by can_vault_appendix flag
    if (permissions.can_vault_appendix) {
      const vault = document.getElementById('vault-appendix');
      if (vault) vault.classList.add('unlocked');
    }

    // Show user identity in nav
    document.getElementById('user-email').textContent = email;

    // Log access event
    fetch('https://auth.saludcap.com/api/log-access', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + token,
                 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event_type: 'view_research',
        resource_id: document.documentElement.dataset.reportSlug
      })
    });

  } catch (e) {
    console.error('Auth check failed', e);
    // Fail open on network error for offline access — or fail closed:
    // location.href = loginUrl;
  }
})();

Mapping Research Files to Access Rules

Every gated research document should be registered in the admin panel's Research Docs screen. This allows access rules to be changed without touching the HTML files, and gives the audit log meaningful resource identifiers.

<!-- Add to <html> tag of each research document -->
<html lang="en"
  data-report-slug="digital_payments_v1"
  data-report-title="Digital Payments, Tokens, Smart Contracts & Secure Identity"
  data-vault-appendix="true">

Security Architecture & Compliance Notes

Build Sequence for Website Dev Team

Phase 1 — Foundation (Week 1–2)

• Supabase project setup: Create project, run schema migrations from Section 04, configure Row Level Security policies
• Auth service scaffolding: Next.js API routes for login, verify-token, logout. JWT signing with RS256. Deploy to Vercel.
• Authorized domains seeded: Insert saludcap.com and saludwireless.com into authorized_domains table
• Admin account seeded: Create initial admin account via DB seed script. Enable TOTP.
• Login page built: /login — email + password form, magic link option. Branded with SaludCap design tokens. Returns JWT to localStorage on success.

Phase 2 — Admin Panel (Week 3–4)

• Admin panel layout: /admin protected route (admin tier only). Sidebar navigation. Dashboard with summary stats.
• Users list screen: Table with inline permission toggles. Filter by tier. Search by email.
• User detail screen: Full permissions editor, expiry date picker, access history, revoke sessions.
• Invite flow: Invite form → token generation → Resend email send → accept-invite page → account creation.
• Domain management screen: Add/remove domains, set auto-tier per domain.
• Research docs registry screen: CRUD for report slugs, access rules, Vault appendix flag.
• Audit log screen: Paginated table, filters, CSV export.

Phase 3 — Research Doc Integration (Week 5)

• Auth script extracted to CDN: Host salud-auth.js on Vercel (or GitHub Pages). All research docs load it via <script> tag instead of inline JS.
• Research HTML files updated: Remove hardcoded SHA-256 blocks. Add data-report-slug attribute. Add <script src="salud-auth.js"></script>.
• Login redirect flow: Unauthenticated research doc visitors → /login?return=[doc-url] → after login, redirect back to doc. JWT stored in localStorage, persists across tabs.
• Vault appendix integration: Auth script checks permissions.can_vault_appendix; reveals #vault-appendix div if true. Remove current client-side gate.
• Access logging tested: Confirm every doc open and Vault unlock writes to access_log and appears in admin audit screen.

Phase 4 — Polish & Hardening (Week 6)

• Investor portal protected: Next.js middleware checks JWT for can_investor_portal on all /investor/* routes.
• Employee sections protected: Middleware checks can_employee_sections on internal pages.
• Account expiry cron job: Vercel cron or Supabase scheduled function deactivates expired accounts nightly.
• Rate limiting deployed: Upstash Redis rate limiter on login and magic-link endpoints.
• TOTP 2FA for admin accounts: QR code enrollment flow; TOTP required on every admin login.
• End-to-end test: Invite investor → investor logs in → can see research → cannot see Vault appendix → admin enables Vault → investor sees Vault → admin revokes → investor locked out.

What to Tell the Dev Team About Existing Files

Recommended Reading for Dev Team