portal-mojo 0.1.0

package/src/client/markdown.ts

@@ -0,0 +1,122 @@
+// Markdown rendering, the platform way: django-mojo owns the renderer, so the
+// portal asks it instead of shipping a second one that drifts.
+//
+// Wire contract — mojo/apps/docit/rest/render.py, verified against the source:
+//   POST /api/docit/render   {markdown: string}     (@requires_auth)
+//   → the handler returns a bare dict, so mojo/decorators/http.py wraps it:
+//     {status: true, code: 200, data: {html: string}}
+//   → errors: 400 `markdown field is required`, 405 non-POST,
+//     413 over MAX_MARKDOWN_BYTES.
+// Unwrapped at the ONE boundary (mojoCall) like every other endpoint — no
+// `resp.data.data.html || resp.data.html` sniffing, which is what web-mojo's
+// three copies of this call did (do-not-recreate list).
+//
+// What this module guarantees to its callers:
+//   · The string it resolves is SANITIZED (markdown-sanitize.ts). Unsanitized
+//     server HTML never leaves this file, so there is no way to hold it.
+//   · A failure REJECTS. The fallback decision belongs to the component,
+//     because the fallback path renders React ELEMENTS, not a string —
+//     "resolve the fallback as success" would hand back a string that no
+//     longer says which renderer produced it.
+//   · Identical sources are rendered once: an in-memory cache plus in-flight
+//     de-duplication, so a chat feed re-rendering 50 messages is 0 requests
+//     and two mounts of the same message are 1.
+import { mojoCall } from './client';
+import { MojoError } from './errors';
+import { sanitizeMarkdownHtml } from './markdown-sanitize';
+
+export { sanitizeMarkdownHtml, safeLinkUrl, safeImgUrl, type SanitizeDrop } from './markdown-sanitize';
+export { MarkdownFallback, markdownToNodes } from './markdown-fallback';
+export { markdownToHtml, parseMarkdown, type MdBlock, type MdInline } from './markdown-parse';
+
+export const MARKDOWN_RENDER_ENDPOINT = '/api/docit/render';
+/** The server's own cap (rest/render.py) — over it, skip a guaranteed 413. */
+export const MAX_MARKDOWN_BYTES = 400_000;
+/** Enough for a long chat scrollback; oldest entries fall off the end. */
+const CACHE_LIMIT = 200;
+
+interface CacheEntry { source: string; html: string }
+
+const cache = new Map<string, CacheEntry>();
+const inflight = new Map<string, { source: string; p: Promise<string> }>();
+
+/**
+ * FNV-1a over the source, suffixed with its length. The key is only an index:
+ * every entry stores its source and is verified on hit, so a hash collision
+ * costs a re-render, never a wrong document.
+ */
+function cacheKey(source: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < source.length; i++) {
+        h ^= source.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return `${(h >>> 0).toString(36)}:${source.length}`;
+}
+
+function remember(key: string, source: string, html: string): void {
+    if (cache.size >= CACHE_LIMIT) {
+        const oldest = cache.keys().next();
+        if (!oldest.done) cache.delete(oldest.value);
+    }
+    cache.set(key, { source, html });
+}
+
+function utf8Bytes(source: string): number {
+    // UTF-8 is at most 4 bytes per UTF-16 code unit — skip the encode when the
+    // answer cannot possibly exceed the cap.
+    if (source.length * 4 <= MAX_MARKDOWN_BYTES) return source.length;
+    return new TextEncoder().encode(source).length;
+}
+
+/** Sanitized HTML for this source if it has already been rendered — else null. */
+export function peekMarkdown(source: string): string | null {
+    if (!source) return null;
+    const hit = cache.get(cacheKey(source));
+    return hit && hit.source === source ? hit.html : null;
+}
+
+/** Drop the memo (demos, tests, a backend swap mid-session). */
+export function clearMarkdownCache(): void {
+    cache.clear();
+}
+
+/**
+ * Render markdown on the server and sanitize the result.
+ *
+ * REJECTS on any failure (endpoint missing, offline, 401, oversized body, a
+ * response without `html`, or no DOM to sanitize with). Callers render
+ * `<MarkdownFallback source>` instead — see ui/MarkdownView.tsx.
+ */
+export function renderMarkdown(source: string): Promise<string> {
+    if (!source.trim()) return Promise.resolve('');
+
+    const key = cacheKey(source);
+    const hit = cache.get(key);
+    if (hit && hit.source === source) return Promise.resolve(hit.html);
+
+    const pending = inflight.get(key);
+    if (pending && pending.source === source) return pending.p;
+
+    if (utf8Bytes(source) > MAX_MARKDOWN_BYTES) {
+        return Promise.reject(new MojoError('markdown input too large', 413));
+    }
+
+    const p = (async () => {
+        const body = await mojoCall(MARKDOWN_RENDER_ENDPOINT, { method: 'POST', body: { markdown: source } });
+        const html = (body.data as { html?: unknown } | undefined)?.html;
+        if (typeof html !== 'string') throw new MojoError('docit/render returned no html', 0);
+        const safe = sanitizeMarkdownHtml(html);
+        remember(key, source, safe);
+        return safe;
+    })();
+
+    // Only the registered promise clears the slot — a colliding key that was
+    // never registered must not evict someone else's in-flight render.
+    const slot = { source, p };
+    inflight.set(key, slot);
+    void p.catch(() => undefined).then(() => {
+        if (inflight.get(key) === slot) inflight.delete(key);
+    });
+    return p;
+}

package/src/client/me.ts

@@ -0,0 +1,188 @@
+// Me + permissions — the CHECK side of web-mojo's permission model, ported
+// from User.hasPermission (src/core/models/User.js:13-61) and
+// Member.hasPermission (Member.js:15-28). UX gating only: the client may err
+// permissive (category rollups), the server stays authoritative on every
+// request.
+//
+// Semantics, in check order:
+//   1. `is_superuser` passes everything.
+//   2. An array means ANY-of.
+//   3. A `sys.` prefix pins the check to system-level (user) permissions —
+//      group/member permissions are never consulted for sys.* checks.
+//   4. Direct grant, or a category grant covering the granular name
+//      (CATEGORY_GRANULAR_MAP rollup).
+//   5. System-level `admin` is the permission-driven equivalent of
+//      is_superuser — passes every gate.
+//   6. Otherwise the active-group member: direct grant, or the member
+//      `admin` wildcard (full access within the group — never sys.*).
+import { useQuery } from '@tanstack/react-query';
+import { useContext, useSyncExternalStore } from 'react';
+import { mojoGet } from './client';
+import { getAuthSnapshot, subscribeAuth, type AuthSnapshot } from './auth';
+import { GroupContext } from './group-context';
+import { sanitizeAvatarRelation } from './types';
+
+/** Server permission dicts use true AND 1 as granted (web-mojo checked `== true`). */
+export type PermissionsDict = Record<string, unknown>;
+
+export interface Me {
+    id: number;
+    display_name?: string;
+    email?: string;
+    is_superuser?: boolean;
+    permissions?: PermissionsDict | null;
+    avatar?: { id: number } | null;
+    [field: string]: unknown;
+}
+
+/** `me` has its own query key and therefore its own mandatory sanitizer. */
+export function sanitizeMe(row: Me): Me {
+    return { ...row, avatar: sanitizeAvatarRelation(row.avatar) };
+}
+
+/** Active-group membership context — provided by the A3 GroupProvider. */
+export interface MemberLike {
+    permissions?: PermissionsDict | null;
+}
+
+// ── Category → granular rollup map ────────────────────────────────────
+// A category grant implicitly grants every granular permission it covers.
+// Ported verbatim from User.CATEGORY_GRANULAR_MAP (incl. the dnsman note:
+// `security` maps view_dns/manage_dns because dnsman's RestMeta accepts
+// `security` for both VIEW_PERMS and SAVE_PERMS — mirroring, not over-granting).
+
+const BASE_CATEGORY_GRANULAR_MAP: Record<string, string[]> = {
+    security: ['view_security', 'manage_security', 'view_dns', 'manage_dns'],
+    users: ['view_users', 'manage_users', 'view_members'],
+    groups: ['view_groups', 'manage_groups', 'manage_group'],
+    comms: ['manage_chat', 'manage_aws', 'view_notifications', 'manage_notifications', 'send_notifications',
+        'view_devices', 'manage_devices', 'manage_push_config',
+        'view_phone_numbers', 'manage_phone_numbers', 'manage_phone_config',
+        'view_sms', 'manage_sms', 'send_sms'],
+    jobs: ['view_jobs', 'manage_jobs'],
+    metrics: ['view_metrics', 'manage_metrics', 'write_metrics'],
+    files: ['view_fileman', 'manage_files', 'view_vault', 'manage_vault'],
+};
+
+let categoryGranularMap: Record<string, string[]> = { ...BASE_CATEGORY_GRANULAR_MAP };
+let granularToCategory: Record<string, string> = invertMap(categoryGranularMap);
+
+function invertMap(map: Record<string, string[]>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [category, granulars] of Object.entries(map)) {
+        for (const g of granulars) out[g] = category;
+    }
+    return out;
+}
+
+/**
+ * App extension point: add category → granular coverage (web-mojo's
+ * APP_CATEGORY_PERMISSIONS + rebuildPermissions, as a registry call instead
+ * of live-mutated arrays). Existing categories are extended, not replaced.
+ */
+export function registerPermissionCategories(extra: Record<string, string[]>): void {
+    for (const [category, granulars] of Object.entries(extra)) {
+        const current = categoryGranularMap[category] ?? [];
+        categoryGranularMap[category] = [...new Set([...current, ...granulars])];
+    }
+    granularToCategory = invertMap(categoryGranularMap);
+}
+
+export function getCategoryGranularMap(): Readonly<Record<string, readonly string[]>> {
+    return categoryGranularMap;
+}
+
+// ── The check ─────────────────────────────────────────────────────────
+
+/** The backend stores grants as true or 1 (web-mojo's loose `== true`). */
+function granted(dict: PermissionsDict | null | undefined, name: string): boolean {
+    const v = dict?.[name];
+    return v === true || v === 1;
+}
+
+/** Direct grant or category rollup on one permissions dict (User._hasPermission). */
+function dictHasPermission(dict: PermissionsDict | null | undefined, name: string): boolean {
+    if (!dict) return false;
+    if (granted(dict, name)) return true;
+    const category = granularToCategory[name];
+    return category != null && granted(dict, category);
+}
+
+/** Member.hasPermission: direct grant, or the group `admin` wildcard (never sys.*). */
+export function memberHasPermission(member: MemberLike | null | undefined, permission: string | string[]): boolean {
+    if (!member) return false;
+    if (Array.isArray(permission)) return permission.some((p) => memberHasPermission(member, p));
+    // A member dictionary is never a system authority. Fail before the direct
+    // lookup too: malformed/stale rows containing a literal `sys.*` key must
+    // not satisfy an Admin gate. User.hasPermission still resolves sys.* from
+    // the user's global dictionary in hasPermission() below.
+    if (permission.startsWith('sys.')) return false;
+    const dict = member.permissions;
+    if (!dict) return false;
+    if (granted(dict, permission)) return true;
+    return granted(dict, 'admin');
+}
+
+/** User.hasPermission, full semantics. `member` is the active-group membership. */
+export function hasPermission(
+    me: Me | null | undefined,
+    permission: string | string[],
+    member?: MemberLike | null,
+): boolean {
+    if (!me) return false;
+    if (me.is_superuser) return true;
+    if (Array.isArray(permission)) return permission.some((p) => hasPermission(me, p, member));
+
+    const isSys = permission.startsWith('sys.');
+    const name = isSys ? permission.slice(4) : permission;
+
+    if (dictHasPermission(me.permissions, name)) return true;
+    // System-level `admin` is a full-access grant — the permission-driven
+    // equivalent of is_superuser.
+    if (dictHasPermission(me.permissions, 'admin')) return true;
+    // Member permissions are only consulted for non-sys checks.
+    if (!isSys && member && memberHasPermission(member, permission)) return true;
+    return false;
+}
+
+// ── Hooks ─────────────────────────────────────────────────────────────
+
+/** Live auth-session snapshot (re-renders on login/logout, incl. cross-tab). */
+export function useAuthSnapshot(): AuthSnapshot {
+    return useSyncExternalStore(subscribeAuth, getAuthSnapshot, getAuthSnapshot);
+}
+
+/**
+ * The signed-in user. Disabled (no fetch, no data) while anonymous; keyed by
+ * uid so a login/logout/login sequence never bleeds one identity's data into
+ * the next.
+ */
+export function useMe() {
+    const auth = useAuthSnapshot();
+    return useQuery<Me>({
+        queryKey: ['me', auth.uid],
+        queryFn: async () => sanitizeMe(await mojoGet<Me>('/api/user', 'me')),
+        enabled: auth.authenticated,
+        staleTime: 5 * 60_000,
+    });
+}
+
+export interface CanResult {
+    can: boolean;
+    /** True only during the first `me` fetch — anonymous is NOT loading. */
+    isLoading: boolean;
+    me: Me | null;
+}
+
+/**
+ * Permission check against the signed-in user PLUS the active-group member
+ * when a <GroupProvider> is mounted (member `admin` grants everything in the
+ * group; sys.* checks never consult it). Resolves false while loading or
+ * anonymous (fail-closed rendering).
+ */
+export function useCan(permission: string | string[]): CanResult {
+    const { data, isLoading } = useMe();
+    const groupCtx = useContext(GroupContext);
+    const me = data ?? null;
+    return { can: hasPermission(me, permission, groupCtx?.member ?? null), isLoading, me };
+}