mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 22:41:09 +02:00
142a65a22f
Five documentation surfaces gained encryption awareness in this
sweep. Before this commit, the only place anyone could learn about
the at-rest encryption layer or the zero-knowledge opt-in was the
internal DATA_LAYER_AUDIT.md. New contributors and self-hosters
would never discover one of the most important features of the
product just by reading the standard onboarding docs.
apps/docs/src/content/docs/architecture/security.mdx (NEW)
----------------------------------------------------------
First-class user-facing security page in the Starlight site,
slotted into the Architecture sidebar between Authentication and
Backend.
Sections:
- What's encrypted (overview table of 27 modules + the
intentional plaintext carve-outs)
- Standard mode flow with ASCII diagram
- "What Mana CAN see" trust statements per mode
- Zero-knowledge mode setup walkthrough (Steps component)
- Unlock flow on a new device
- Recovery code rotation
- Deployment requirements (the loud MANA_AUTH_KEK warning)
- Audit trail action vocabulary
- Threat model summary table
- Implementation file references with paths
services/mana-auth/CLAUDE.md
----------------------------
New "Encryption Vault" section under Key Endpoints, listing all 7
routes (status, init, key, rotate, recovery-wrap GET+DELETE,
zero-knowledge) with their HTTP method, path, error codes, and a
description. Mentions the three CHECK constraints + RLS + audit
table. Points readers at DATA_LAYER_AUDIT.md and the new
security.mdx for the deep dive.
Environment Variables block gains MANA_AUTH_KEK with a multi-line
comment explaining the openssl rand command + dev fallback warning.
apps/mana/CLAUDE.md
-------------------
Full rewrite. The existing file was from the Supabase era and
described things like @supabase/ssr, safeGetSession(), and a
five-table schema with users + organizations + teams that doesn't
exist any more. Replaced with the unified-app architecture:
- Module system layout (collections.ts / queries.ts / stores/)
- Mana Auth (Better Auth + EdDSA JWT) instead of Supabase
- Local-first data layer with the full pipeline diagram
- At-rest encryption section with the "when writing module code
that touches sensitive fields" 4-step guide
- Updated routing structure (no more separate /organizations,
/teams routes)
- Module store pattern code example
- Reference document table at the bottom pointing at the audit,
the new security.mdx, and the auth doc
Root CLAUDE.md
--------------
New "At-Rest Encryption (Phase 1–9)" subsection under the
Local-First Architecture section. Two-mode trust summary table,
production requirement for MANA_AUTH_KEK with the openssl command,
the "when writing module code" 4-step guide, and a reference
table. New contributors reading the root CLAUDE.md from top to
bottom now hit encryption naturally as part of the data layer
discussion.
.env.macmini.example
--------------------
MANA_AUTH_KEK was missing from the production env example
entirely — the macmini deployment would silently boot on the
32-zero-byte dev fallback if you copied this file. Added with a
multi-paragraph comment covering: how to generate, why it's
required, how to store securely (Docker secrets / KMS / Vault),
and the rotation caveat.
apps/docs/src/content/docs/deployment/self-hosting.mdx
------------------------------------------------------
Two changes:
1. Added MANA_AUTH_KEK to the mana-auth service block in the
Compose example with an inline comment pointing at the new
section below.
2. New "Encryption Vault Setup" H2 section with subsections:
- Generating a KEK (with a fake example value labelled DO NOT
USE — generate your own)
- Securing the KEK (Docker secrets, KMS, systemd
LoadCredential, anti-patterns)
- "What if I lose the KEK?" — explains the data is
unrecoverable by design and mitigation via zero-knowledge
mode opt-in
- KEK rotation — calls out the missing background re-wrap
job as a known limitation
apps/docs/astro.config.mjs
--------------------------
Added "Security & Encryption" entry to the Architecture sidebar
between Authentication and Backend so the new page is reachable
from the docs nav.
Astro check: 0 errors, 0 warnings, 0 hints across 4 .astro files.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
115 lines
3.5 KiB
JavaScript
115 lines
3.5 KiB
JavaScript
import { defineConfig } from 'astro/config';
|
|
import starlight from '@astrojs/starlight';
|
|
import tailwind from '@astrojs/tailwind';
|
|
import sitemap from '@astrojs/sitemap';
|
|
|
|
export default defineConfig({
|
|
site: 'https://docs.mana.how',
|
|
integrations: [
|
|
starlight({
|
|
title: 'Mana Docs',
|
|
description:
|
|
'Documentation for the Mana ecosystem - a multi-app platform with shared infrastructure.',
|
|
logo: {
|
|
light: './src/assets/logo-light.svg',
|
|
dark: './src/assets/logo-dark.svg',
|
|
replacesTitle: false,
|
|
},
|
|
social: {
|
|
github: 'https://github.com/mana/mana-monorepo',
|
|
},
|
|
editLink: {
|
|
baseUrl: 'https://github.com/mana/mana-monorepo/edit/main/apps/docs/',
|
|
},
|
|
customCss: ['./src/styles/custom.css'],
|
|
sidebar: [
|
|
{
|
|
label: 'Getting Started',
|
|
items: [
|
|
{ label: 'Introduction', slug: 'getting-started/introduction' },
|
|
{ label: 'Quick Start', slug: 'getting-started/quick-start' },
|
|
{ label: 'Project Structure', slug: 'getting-started/project-structure' },
|
|
],
|
|
},
|
|
{
|
|
label: 'Development',
|
|
items: [
|
|
{ label: 'Local Development', slug: 'development/local-development' },
|
|
{ label: 'Environment Variables', slug: 'development/environment-variables' },
|
|
{ label: 'Docker Setup', slug: 'development/docker' },
|
|
{ label: 'Database Migrations', slug: 'development/database-migrations' },
|
|
{ label: 'Testing', slug: 'development/testing' },
|
|
],
|
|
},
|
|
{
|
|
label: 'Architecture',
|
|
items: [
|
|
{ label: 'Overview', slug: 'architecture/overview' },
|
|
{ label: 'Authentication', slug: 'architecture/authentication' },
|
|
{ label: 'Security & Encryption', slug: 'architecture/security' },
|
|
{ label: 'Backend (NestJS)', slug: 'architecture/backend' },
|
|
{ label: 'Web (SvelteKit)', slug: 'architecture/web' },
|
|
{ label: 'Mobile (Expo)', slug: 'architecture/mobile' },
|
|
{ label: 'Search Service', slug: 'architecture/search' },
|
|
{ label: 'Storage', slug: 'architecture/storage' },
|
|
],
|
|
},
|
|
{
|
|
label: 'Guidelines',
|
|
items: [
|
|
{ label: 'Code Style', slug: 'guidelines/code-style' },
|
|
{ label: 'Error Handling', slug: 'guidelines/error-handling' },
|
|
{ label: 'Database Patterns', slug: 'guidelines/database' },
|
|
{ label: 'Design & UX', slug: 'guidelines/design-ux' },
|
|
],
|
|
},
|
|
{
|
|
label: 'Deployment',
|
|
items: [
|
|
{ label: 'Overview', slug: 'deployment/overview' },
|
|
{ label: 'Cloudflare Pages', slug: 'deployment/cloudflare-pages' },
|
|
{ label: 'Mac Mini Server', slug: 'deployment/mac-mini-server' },
|
|
{ label: 'Self-Hosting', slug: 'deployment/self-hosting' },
|
|
],
|
|
},
|
|
{
|
|
label: 'Projects',
|
|
collapsed: true,
|
|
items: [
|
|
{ label: 'Overview', slug: 'projects' },
|
|
{ label: 'Chat', slug: 'projects/chat' },
|
|
],
|
|
},
|
|
{
|
|
label: 'API Reference',
|
|
collapsed: true,
|
|
items: [{ label: 'Overview', slug: 'api' }],
|
|
},
|
|
],
|
|
head: [
|
|
{
|
|
tag: 'meta',
|
|
attrs: {
|
|
property: 'og:image',
|
|
content: 'https://docs.mana.how/og-image.png',
|
|
},
|
|
},
|
|
{
|
|
tag: 'script',
|
|
content: `
|
|
// Set dark mode as default
|
|
(function() {
|
|
const stored = localStorage.getItem('starlight-theme');
|
|
if (!stored) {
|
|
document.documentElement.dataset.theme = 'dark';
|
|
localStorage.setItem('starlight-theme', 'dark');
|
|
}
|
|
})();
|
|
`,
|
|
},
|
|
],
|
|
}),
|
|
tailwind({ applyBaseStyles: false }),
|
|
sitemap(),
|
|
],
|
|
});
|