@407dev/cms-astro 0.1.0

package/src/dev/token.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import { signDevToken, validateDevToken } from './token';
+
+function createMockJwt(payload: Record<string, unknown>): string {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const encode = (obj: unknown) =>
+    Buffer.from(JSON.stringify(obj))
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+  return `${encode(header)}.${encode(payload)}.mocksignature`;
+}
+
+describe('validateDevToken credential gate', () => {
+  it('refuses empty, null, or non-string tokens', () => {
+    expect(validateDevToken('')).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN is missing or empty',
+    });
+    expect(validateDevToken(null)).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN is missing or empty',
+    });
+    expect(validateDevToken(undefined)).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN is missing or empty',
+    });
+  });
+
+  it('refuses invalid JWT formats', () => {
+    expect(validateDevToken('not-a-jwt')).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN is not a valid 3-part JWT',
+    });
+    expect(validateDevToken('header.payload')).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN is not a valid 3-part JWT',
+    });
+    expect(validateDevToken('header.%%%badbase64%%%.sig')).toEqual({
+      ok: false,
+      reason: 'CMS_DEV_TOKEN payload is not decodable',
+    });
+  });
+
+  it('refuses service_role tokens', () => {
+    const serviceToken = createMockJwt({
+      role: 'service_role',
+      sub: 'service-key-id',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    const result = validateDevToken(serviceToken);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain('service_role');
+    }
+  });
+
+  it('refuses anonymous or publishable tokens', () => {
+    const anonToken = createMockJwt({
+      role: 'anon',
+      sub: 'anon-key-id',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    const result = validateDevToken(anonToken);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain("invalid role 'anon'");
+    }
+  });
+
+  it('refuses expired authenticated tokens', () => {
+    const expiredToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'user-expired',
+      exp: Math.floor(Date.now() / 1000) - 600,
+    });
+    const result = validateDevToken(expiredToken);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain('expired');
+    }
+  });
+
+  it('accepts valid authenticated JWT and extracts identity', () => {
+    const validExp = Math.floor(Date.now() / 1000) + 7200;
+    const validToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-12345',
+      email: 'builder@example.com',
+      exp: validExp,
+      app_metadata: {
+        workspace_id: 'ws-1',
+        role: 'member',
+      },
+    });
+
+    const result = validateDevToken(validToken);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.sub).toBe('usr-12345');
+      expect(result.identity.email).toBe('builder@example.com');
+      expect(result.identity.exp).toBe(validExp);
+      expect(result.identity.workspaceRole).toBe('member');
+    }
+  });
+
+  it('refuses tokens with workspace owner scope without allowElevated', () => {
+    const ownerToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-owner',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspace_id: 'ws-1',
+        role: 'owner',
+      },
+    });
+
+    const result = validateDevToken(ownerToken);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain("workspace 'owner' scope");
+    }
+
+    const explicitFalseResult = validateDevToken(ownerToken, { allowElevated: false });
+    expect(explicitFalseResult.ok).toBe(false);
+  });
+
+  it('accepts tokens with workspace owner scope when allowElevated is true', () => {
+    const ownerToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-owner',
+      email: 'owner@example.com',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspace_id: 'ws-1',
+        role: 'owner',
+      },
+    });
+
+    const result = validateDevToken(ownerToken, { allowElevated: true });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.sub).toBe('usr-owner');
+      expect(result.identity.email).toBe('owner@example.com');
+      expect(result.identity.workspaceRole).toBe('owner');
+    }
+
+    // Also supports boolean parameter
+    const boolResult = validateDevToken(ownerToken, true);
+    expect(boolResult.ok).toBe(true);
+  });
+
+  it('refuses tokens with workspace editor scope in the per-workspace claim map without allowElevated', () => {
+    const editorToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-editor',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspaces: {
+          'ws-1': { role: 'viewer' },
+          'ws-2': { role: 'editor' },
+        },
+      },
+    });
+
+    const result = validateDevToken(editorToken);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toContain("workspace 'editor' scope");
+    }
+  });
+
+  it('accepts tokens with workspace editor scope when allowElevated is true', () => {
+    const editorToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-editor',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspaces: {
+          'ws-1': { role: 'editor' },
+        },
+      },
+    });
+
+    const result = validateDevToken(editorToken, { allowElevated: true });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.workspaceRole).toBe('editor');
+    }
+  });
+
+  it('does not treat retired admin or developer roles as elevated', () => {
+    const retiredAdminToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-admin',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspace_id: 'ws-1',
+        role: 'admin',
+      },
+    });
+
+    const resultAdmin = validateDevToken(retiredAdminToken);
+    expect(resultAdmin.ok).toBe(true);
+
+    const retiredDevToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-dev',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspaces: {
+          'ws-1': { role: 'developer' },
+        },
+      },
+    });
+
+    const resultDev = validateDevToken(retiredDevToken);
+    expect(resultDev.ok).toBe(true);
+  });
+
+  it('accepts a workspace-viewer-scoped token via the per-workspace claim map', () => {
+    const viewerToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-viewer',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspaces: {
+          'ws-1': { role: 'viewer' },
+        },
+      },
+    });
+
+    const result = validateDevToken(viewerToken);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.workspaceRole).toBe('viewer');
+    }
+  });
+
+  it('accepts a workspace-member-scoped token via the per-workspace claim map', () => {
+    const memberToken = createMockJwt({
+      role: 'authenticated',
+      sub: 'usr-member',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      app_metadata: {
+        workspaces: {
+          'ws-1': { role: 'member' },
+        },
+      },
+    });
+
+    const result = validateDevToken(memberToken);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.identity.workspaceRole).toBe('member');
+    }
+  });
+
+  describe('signDevToken', () => {
+    it('generates a valid, signed 3-part JWT acceptable by validateDevToken', () => {
+      const secret = 'super-secret-jwt-token-with-at-least-32-characters-long';
+      const token = signDevToken(secret, {
+        siteId: 'site-custom',
+        workspaceId: 'ws-custom',
+        userId: 'usr-custom',
+      });
+      expect(typeof token).toBe('string');
+      expect(token.split('.').length).toBe(3);
+
+      const result = validateDevToken(token);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.identity.sub).toBe('usr-custom');
+        expect(result.identity.email).toBe('dev@example.com');
+        expect(result.identity.workspaceRole).toBe('viewer');
+      }
+    });
+  });
+});

package/src/dev/token.ts

@@ -0,0 +1,201 @@
+import crypto from 'node:crypto';
+
+export interface DevTokenIdentity {
+  sub: string;
+  email?: string;
+  exp?: number;
+  workspaceRole?: string;
+}
+
+export type ValidateDevTokenResult =
+  | { ok: true; identity: DevTokenIdentity }
+  | { ok: false; reason: string };
+
+// Matches is_workspace_admin_or_dev()'s RLS bypass roles (owner | editor); CMS_DEV_TOKEN must not carry them.
+const WORKSPACE_ELEVATED_ROLES = new Set(['owner', 'editor']);
+
+// Reads both claim shapes RLS accepts: the flat single-workspace shortcut (app_metadata.workspace_id + app_metadata.role) and the per-workspace map (app_metadata.workspaces[id].role).
+function collectWorkspaceRoles(payload: Record<string, unknown>): string[] {
+  const appMetadata = payload.app_metadata as Record<string, unknown> | undefined;
+  if (!appMetadata || typeof appMetadata !== 'object') return [];
+
+  const roles: string[] = [];
+
+  if (typeof appMetadata.workspace_id === 'string' && typeof appMetadata.role === 'string') {
+    roles.push(appMetadata.role);
+  }
+
+  const workspaces = appMetadata.workspaces;
+  if (workspaces && typeof workspaces === 'object') {
+    for (const entry of Object.values(workspaces as Record<string, unknown>)) {
+      const role = (entry as Record<string, unknown> | null)?.role;
+      if (typeof role === 'string') roles.push(role);
+    }
+  }
+
+  return roles;
+}
+
+function base64UrlDecode(str: string): string {
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64.length % 4 !== 0) {
+    base64 += '=';
+  }
+  return Buffer.from(base64, 'base64').toString('utf-8');
+}
+
+export interface ValidateDevTokenOptions {
+  allowElevated?: boolean;
+}
+
+/**
+ * Decodes and validates a developer user JWT for the dev toolbar.
+ * Rejects non-JWTs, service-role keys, anon keys, and expired tokens.
+ */
+export function validateDevToken(
+  token: string | null | undefined,
+  options?: ValidateDevTokenOptions | boolean,
+): ValidateDevTokenResult {
+  const allowElevated = typeof options === 'boolean' ? options : Boolean(options?.allowElevated);
+
+  if (!token || typeof token !== 'string' || !token.trim()) {
+    return { ok: false, reason: 'CMS_DEV_TOKEN is missing or empty' };
+  }
+
+  const parts = token.trim().split('.');
+  if (parts.length !== 3) {
+    return { ok: false, reason: 'CMS_DEV_TOKEN is not a valid 3-part JWT' };
+  }
+
+  let payload: Record<string, unknown>;
+  try {
+    const decoded = base64UrlDecode(parts[1]);
+    payload = JSON.parse(decoded);
+    if (!payload || typeof payload !== 'object') {
+      return { ok: false, reason: 'CMS_DEV_TOKEN payload is not a valid JSON object' };
+    }
+  } catch {
+    return { ok: false, reason: 'CMS_DEV_TOKEN payload is not decodable' };
+  }
+
+  // 1. Refuse service_role
+  if (payload.role === 'service_role') {
+    return {
+      ok: false,
+      reason: 'CMS_DEV_TOKEN must not be a service_role key; authenticated user JWT required',
+    };
+  }
+
+  // 2. Refuse non-authenticated (e.g. anon / publishable)
+  if (payload.role !== 'authenticated') {
+    return {
+      ok: false,
+      reason: `CMS_DEV_TOKEN has invalid role '${String(payload.role || 'none')}'; expected 'authenticated'`,
+    };
+  }
+
+  // 3. Refuse expired
+  if (typeof payload.exp === 'number' && payload.exp * 1000 <= Date.now()) {
+    return { ok: false, reason: 'CMS_DEV_TOKEN has expired' };
+  }
+
+  // 4. Refuse workspace scope above 'viewer'/'member' unless explicitly allowed (e.g. CLI session)
+  const workspaceRoles = collectWorkspaceRoles(payload);
+  if (!allowElevated) {
+    const elevatedRole = workspaceRoles.find((role) => WORKSPACE_ELEVATED_ROLES.has(role));
+    if (elevatedRole) {
+      return {
+        ok: false,
+        reason: `CMS_DEV_TOKEN grants workspace '${elevatedRole}' scope; only workspace-member tokens are permitted`,
+      };
+    }
+  }
+
+  const sub = typeof payload.sub === 'string' ? payload.sub : '';
+  if (!sub) {
+    return { ok: false, reason: 'CMS_DEV_TOKEN is missing sub claim' };
+  }
+
+  const email =
+    typeof payload.email === 'string'
+      ? payload.email
+      : typeof (payload.user_metadata as Record<string, unknown> | undefined)?.email === 'string'
+        ? ((payload.user_metadata as Record<string, unknown>).email as string)
+        : undefined;
+
+  const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
+
+  const workspaceRole = workspaceRoles[0];
+
+  return {
+    ok: true,
+    identity: {
+      sub,
+      email,
+      exp,
+      workspaceRole,
+    },
+  };
+}
+
+export interface SignDevTokenOptions {
+  siteId?: string;
+  workspaceId?: string;
+  userId?: string;
+}
+
+/**
+ * Signs a developer user JWT (with workspace viewer & site editor roles) for local development against local Supabase/CMS API.
+ */
+export function signDevToken(
+  secret: string,
+  siteIdOrOptions?: string | SignDevTokenOptions,
+  workspaceIdParam?: string,
+  userIdParam?: string,
+): string {
+  let siteId = '00000000-0000-0000-0000-000000000002';
+  let workspaceId = '00000000-0000-0000-0000-000000000001';
+  let userId = '00000000-0000-0000-0000-000000000003';
+
+  if (typeof siteIdOrOptions === 'object' && siteIdOrOptions !== null) {
+    if (siteIdOrOptions.siteId) siteId = siteIdOrOptions.siteId;
+    if (siteIdOrOptions.workspaceId) workspaceId = siteIdOrOptions.workspaceId;
+    if (siteIdOrOptions.userId) userId = siteIdOrOptions.userId;
+  } else {
+    if (typeof siteIdOrOptions === 'string') siteId = siteIdOrOptions;
+    if (typeof workspaceIdParam === 'string') workspaceId = workspaceIdParam;
+    if (typeof userIdParam === 'string') userId = userIdParam;
+  }
+
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const payload = {
+    aud: 'authenticated',
+    role: 'authenticated',
+    sub: userId,
+    email: 'dev@example.com',
+    app_metadata: {
+      workspace_id: workspaceId,
+      site_id: siteId,
+      role: 'viewer',
+      workspaces: {
+        [workspaceId]: { role: 'viewer' },
+      },
+      sites: {
+        [siteId]: { role: 'editor', workspace_id: workspaceId },
+      },
+      site_roles: {
+        [siteId]: 'editor',
+      },
+    },
+    user_metadata: { role: 'viewer' },
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 3600 * 24 * 365,
+  };
+
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const data = `${encodedHeader}.${encodedPayload}`;
+  const signature = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+
+  return `${data}.${signature}`;
+}

package/src/dev/verifier.test.ts

@@ -0,0 +1,63 @@
+import * as cliModule from '@407dev/cli';
+import { describe, expect, it, vi } from 'vitest';
+import { createVerifier } from './verifier';
+
+describe('createVerifier service', () => {
+  it('clears error cache when a subsequent run produces zero diagnostics', async () => {
+    let mockDiagnostics: cliModule.ExtractionDiagnostic[] = [
+      {
+        type: 'error',
+        message: 'Dynamic template key not extractable',
+        file: 'src/pages/index.astro',
+        line: 10,
+        column: 5,
+      },
+    ];
+
+    const extractSpy = vi.spyOn(cliModule, 'extractProject').mockImplementation(async () => {
+      const errors = mockDiagnostics.filter((d) => d.type === 'error');
+      const warnings = mockDiagnostics.filter((d) => d.type === 'warning');
+      return {
+        manifest: {
+          manifestVersion: 1,
+          fields: {},
+          collections: {},
+          routes: [],
+        },
+        diagnostics: mockDiagnostics,
+        errors,
+        warnings,
+        merged: {
+          fields: {},
+          scopes: {},
+          collections: {},
+          routes: [],
+          diagnostics: [],
+        },
+      };
+    });
+
+    const verifier = await createVerifier({
+      siteDir: '/mock/site',
+      siteId: 'site-123',
+    });
+
+    // 1. Initial run with errors
+    const state1 = await verifier.run();
+    expect(state1.errors.length).toBe(1);
+    expect(state1.errors[0].message).toBe('Dynamic template key not extractable');
+
+    // 2. User fixes the error in template; next run has 0 diagnostics
+    mockDiagnostics = [];
+    const state2 = await verifier.run();
+
+    // Prior error cache must be completely replaced
+    expect(state2.errors.length).toBe(0);
+    expect(state2.warnings.length).toBe(0);
+
+    const currentCached = await verifier.getDiagnostics();
+    expect(currentCached.errors.length).toBe(0);
+
+    extractSpy.mockRestore();
+  });
+});

package/src/dev/verifier.ts

@@ -0,0 +1,161 @@
+import path from 'node:path';
+import { hashSchema } from '@407dev/blocks';
+import type { ViteDevServer } from 'vite';
+
+export interface VerifierDiagnostic {
+  type: 'error' | 'warning';
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  code?: string;
+}
+
+export interface VerifierState {
+  available: boolean;
+  errors: VerifierDiagnostic[];
+  warnings: VerifierDiagnostic[];
+  localHash: string | null;
+  pushedHash: string | null;
+  fresh: boolean;
+}
+
+export interface VerifierInstance {
+  getDiagnostics: () => Promise<VerifierState>;
+  run: () => Promise<VerifierState>;
+  attachServer: (server: ViteDevServer) => void;
+}
+
+export interface CreateVerifierOptions {
+  siteDir: string;
+  siteId: string;
+}
+
+/**
+ * Creates a diagnostics verifier that extracts AST diagnostics from templates via @407dev/cli,
+ * tracks manifest freshness against .cms/state.json, and streams updates via Vite HMR.
+ */
+export async function createVerifier(options: CreateVerifierOptions): Promise<VerifierInstance> {
+  const { siteDir, siteId } = options;
+
+  let cliModule: typeof import('@407dev/cli') | null = null;
+  try {
+    const cliPkg = '@407dev/cli';
+    cliModule = await import(/* @vite-ignore */ cliPkg);
+  } catch {
+    cliModule = null;
+  }
+
+  let cachedState: VerifierState = {
+    available: Boolean(cliModule),
+    errors: [],
+    warnings: [],
+    localHash: null,
+    pushedHash: null,
+    fresh: true,
+  };
+
+  let activeServer: ViteDevServer | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async function run(): Promise<VerifierState> {
+    if (!cliModule) {
+      cachedState = {
+        available: false,
+        errors: [],
+        warnings: [],
+        localHash: null,
+        pushedHash: null,
+        fresh: true,
+      };
+      return cachedState;
+    }
+
+    try {
+      const extractResult = await cliModule.extractProject(siteDir, { noSync: true });
+      const localHash = hashSchema(extractResult.manifest);
+
+      const stateStorePath = path.join(siteDir, '.cms', 'state.json');
+      const store = new cliModule.StateStore(stateStorePath);
+      const pushedHash = store.getSiteManifestHash(siteId);
+
+      const fresh = Boolean(localHash && pushedHash && localHash === pushedHash);
+
+      const errors: VerifierDiagnostic[] = (extractResult.errors || []).map((e) => ({
+        type: 'error',
+        message: e.message,
+        file: e.file,
+        line: e.line,
+        column: e.column,
+        code: e.code,
+      }));
+
+      const warnings: VerifierDiagnostic[] = (extractResult.warnings || []).map((w) => ({
+        type: 'warning',
+        message: w.message,
+        file: w.file,
+        line: w.line,
+        column: w.column,
+        code: w.code,
+      }));
+
+      // A run replaces the cache, ensuring warnings clear on fix
+      cachedState = {
+        available: true,
+        errors,
+        warnings,
+        localHash,
+        pushedHash,
+        fresh,
+      };
+
+      if (activeServer?.hot) {
+        activeServer.hot.send({
+          type: 'custom',
+          event: 'cms:diagnostics',
+          data: cachedState,
+        });
+      }
+
+      return cachedState;
+    } catch (_err) {
+      return cachedState;
+    }
+  }
+
+  function handleFileEvent(filePath: string) {
+    const normalized = filePath.replace(/\\/g, '/');
+    if (
+      normalized.includes('/src/') &&
+      /\.(astro|ts|tsx|js|mjs)$/.test(normalized) &&
+      !normalized.endsWith('.d.ts')
+    ) {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+      }
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        run();
+      }, 300);
+    }
+  }
+
+  function attachServer(server: ViteDevServer) {
+    activeServer = server;
+
+    server.watcher.on('change', handleFileEvent);
+    server.watcher.on('add', handleFileEvent);
+    server.watcher.on('unlink', handleFileEvent);
+  }
+
+  // Initial execution
+  if (cliModule) {
+    await run();
+  }
+
+  return {
+    getDiagnostics: async () => cachedState,
+    run,
+    attachServer,
+  };
+}