Compare commits
No commits in common. "342252efbb1299567322d6948ad7a30a2665b814" and "e23531a0ac5d0222813290217a7e4f479a609593" have entirely different histories.
342252efbb
...
e23531a0ac
8 changed files with 122 additions and 217 deletions
47
README.md
47
README.md
|
|
@ -4,13 +4,35 @@
|
|||
|
||||
Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.
|
||||
|
||||
## System Diagram
|
||||
## Architecture
|
||||
|
||||
This diagram shows how traffic moves through the public internet, the VPS or self-hosted server, the host firewall, the platform router, Myst, Forgejo, and Postgres.
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph VPS["VPS / Self-Hosted"]
|
||||
subgraph Docker["Docker Network"]
|
||||
Forgejo["Forgejo (Git Server)"]
|
||||
Postgres["PostgreSQL (2 Databases)"]
|
||||
Myst["Myst (This Service)"]
|
||||
Traefik["Traefik (Reverse Proxy)"]
|
||||
end
|
||||
Tailscale["Tailscale (Admin Access)"]
|
||||
end
|
||||
|
||||
[](docs/diagrams/system-routing.svg)
|
||||
subgraph External["External"]
|
||||
Owner["Repo Owner"]
|
||||
Viewer["Link Recipient"]
|
||||
end
|
||||
|
||||
Click the diagram to open the full-size SVG.
|
||||
Owner -->|"Login via Forgejo Session"| Myst
|
||||
Owner -->|"Create View Link (PAT)"| Forgejo
|
||||
Myst -->|"Read-only API (PAT)"| Forgejo
|
||||
Myst -->|"Store Grants"| Postgres
|
||||
Forgejo -->|"Sessions"| Postgres
|
||||
Myst -->|"Public Viewer"| Viewer
|
||||
Myst -->|"Admin UI (Protected)"| Owner
|
||||
Tailscale -->|"Private Admin Access"| Myst
|
||||
Traefik -->|"Route HTTPS Traffic"| Myst
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
|
|
@ -34,7 +56,7 @@ Click the diagram to open the full-size SVG.
|
|||
| Purpose | Method |
|
||||
|---------|--------|
|
||||
| User Identity | Forgejo Sessions |
|
||||
| Data Access | Dedicated Forgejo User PAT |
|
||||
| Data Access | Service Account PAT |
|
||||
|
||||
### Tech Stack
|
||||
|
||||
|
|
@ -58,10 +80,10 @@ Prompts for:
|
|||
- Private admin URL (`admin.example.com`)
|
||||
- Forgejo base URL (`git.example.com`)
|
||||
- PostgreSQL connection string
|
||||
- Dedicated Forgejo username and PAT
|
||||
- Forgejo service account username and PAT
|
||||
- Grant token secret
|
||||
|
||||
### 2. Configure Dedicated Forgejo User
|
||||
### 2. Configure Service Account
|
||||
|
||||
Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT:
|
||||
|
||||
|
|
@ -70,12 +92,7 @@ Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT:
|
|||
|
||||
### 3. Deploy
|
||||
|
||||
Deploy Myst anywhere you can run a normal web app beside Forgejo. Phase 1 should explicitly support both of these examples:
|
||||
|
||||
- VPS deployment: Hostinger or another VPS with Dokploy, Traefik, UFW, Myst, Forgejo, and a shared Postgres instance that contains separate `forgejo` and `myst` databases.
|
||||
- Self-hosted server deployment: a home server, mini PC, NAS, or other self-hosted Linux machine running Myst with Docker, Podman, Docker Compose, Coolify, Caddy, Nginx, or another reverse proxy.
|
||||
|
||||
Myst should not assume a VPS-only environment. The requirement is an existing Forgejo instance, Myst's own database, and a way to route the public and admin hostnames to the Myst app.
|
||||
Deploy via Dokploy, Coolify, or your preferred platform.
|
||||
|
||||
## Example Configuration
|
||||
|
||||
|
|
@ -84,7 +101,7 @@ MYST_PUBLIC_URL="https://share.example.com"
|
|||
MYST_ADMIN_URL="https://admin.example.com"
|
||||
DATABASE_URL="postgresql://myst:secret@localhost:5432/myst"
|
||||
FORGEJO_BASE_URL="https://git.example.com"
|
||||
FORGEJO_BOT_USERNAME="myst-bot"
|
||||
FORGEJO_SERVICE_ACCOUNT_USERNAME="myst-bot"
|
||||
FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx"
|
||||
GRANT_TOKEN_SECRET="your-secret-here"
|
||||
```
|
||||
|
|
@ -102,7 +119,7 @@ GRANT_TOKEN_SECRET="your-secret-here"
|
|||
- [ ] Repo ownership verification
|
||||
- [ ] Private link creation (email-verified)
|
||||
- [ ] Public link creation (time-expired)
|
||||
- [ ] Web-based code viewer
|
||||
- [ ] Web-based code viewer (Jinja2 + HTMX)
|
||||
- [ ] User dashboard
|
||||
- [ ] SMTP configuration UI
|
||||
- [ ] Access logs
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 36 KiB |
|
|
@ -47,11 +47,11 @@ Phase 1 does not deliver:
|
|||
|
||||
## Security Baseline
|
||||
|
||||
- dedicated Forgejo user access is restricted to approved repos
|
||||
- service account access is restricted to approved repos
|
||||
- Myst grant checks are enforced on every Forgejo read
|
||||
- grants store `repo_id` and pinned `commit_sha`
|
||||
- viewer requests never choose repo or ref directly
|
||||
- operators create the dedicated Forgejo user and PAT themselves
|
||||
- operators create the Forgejo service account and PAT themselves
|
||||
- Myst stores only its own app config and metadata in its own database
|
||||
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
|
||||
- Myst does not ship built-in admin auth in Phase 1
|
||||
|
|
@ -66,8 +66,8 @@ Myst uses two authentication mechanisms:
|
|||
- Users use their existing Forgejo accounts — no separate Myst login
|
||||
- All Forgejo users with an account are trusted Myst users
|
||||
|
||||
**Data Access (Dedicated Forgejo User PAT)**
|
||||
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
|
||||
**Data Access (Service Account PAT)**
|
||||
- Myst uses an operator-created service account PAT to call the Forgejo API
|
||||
- PAT is used to verify repo ownership and fetch code for viewers
|
||||
- PAT is never used for user identity (that's handled by sessions)
|
||||
|
||||
|
|
@ -76,9 +76,9 @@ Myst uses two authentication mechanisms:
|
|||
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
|
||||
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
|
||||
|
||||
## Dedicated Forgejo User Baseline
|
||||
## Forgejo Service Account Baseline
|
||||
|
||||
- the dedicated Forgejo user is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
||||
- the Forgejo service account is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
||||
- the operator creates this user in Forgejo and grants repo access explicitly
|
||||
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
|
||||
- recommended PAT scopes are `read:user` and `read:repository`
|
||||
|
|
@ -112,7 +112,7 @@ Myst supports two types of view links:
|
|||
|
||||
Only repo owners can create view links for their repos.
|
||||
|
||||
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
|
||||
- Myst verifies ownership via the Forgejo API using the service account PAT
|
||||
- Collaborators or read-access users cannot create view links
|
||||
- Site admins are treated as regular users for this purpose (details to be finalized)
|
||||
|
||||
|
|
@ -124,8 +124,8 @@ Only repo owners can create view links for their repos.
|
|||
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
|
||||
- Forgejo base URL, for example `https://git.example.com`
|
||||
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
|
||||
- Forgejo bot username, for example `myst-bot`
|
||||
- Forgejo PAT for that dedicated Forgejo user
|
||||
- Forgejo service account username, for example `myst-bot`
|
||||
- Forgejo PAT for that service account
|
||||
- grant token secret, with secure auto-generation as the default
|
||||
|
||||
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
|
||||
|
|
@ -139,7 +139,7 @@ Only repo owners can create view links for their repos.
|
|||
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
||||
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
|
||||
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
|
||||
- the PAT should be created for the dedicated Forgejo user
|
||||
- the PAT should be created for the dedicated service account user
|
||||
- the operator can consult Forgejo docs for token creation and scopes if needed
|
||||
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
|
||||
|
||||
|
|
@ -148,7 +148,7 @@ Only repo owners can create view links for their repos.
|
|||
- Forgejo is already deployed and operator-managed
|
||||
- Myst is deployed independently as its own app
|
||||
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
||||
- Myst reaches Forgejo via API using a least-privilege PAT for the dedicated Forgejo user
|
||||
- Myst reaches Forgejo via API using a least-privilege service account token
|
||||
- the CLI validates configuration and connectivity rather than provisioning infrastructure
|
||||
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
|
||||
|
||||
|
|
@ -191,8 +191,8 @@ Minimum v1 data model:
|
|||
`myst forgejo bootstrap` should verify, not provision:
|
||||
|
||||
- Forgejo base URL reachability
|
||||
- dedicated Forgejo user token validity
|
||||
- authenticated user matches the configured Forgejo bot username
|
||||
- service account token validity
|
||||
- authenticated user matches the configured service account username
|
||||
- minimum token scopes are sufficient for Myst's read-only API usage
|
||||
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
||||
- Myst can verify repo ownership for the operator's user account
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"adminUrl": "https://admin.example.com",
|
||||
"forgejoBaseUrl": "https://git.example.com",
|
||||
"forgejoBotUsername": "myst-bot",
|
||||
"forgejoServiceAccountUsername": "myst-bot",
|
||||
"publicUrl": "https://share.example.com"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -172,26 +172,26 @@ export async function initCommand(_args: string[]): Promise<void> {
|
|||
placeholder: "postgresql://myst:password@db.example.com:5432/myst",
|
||||
validate: validatePostgresUrl,
|
||||
}),
|
||||
forgejoBotUsername: () =>
|
||||
forgejoServiceAccountUsername: () =>
|
||||
p.text({
|
||||
message:
|
||||
"What dedicated Forgejo username should Myst use for API access?",
|
||||
"What Forgejo service account username should Myst use for API access?",
|
||||
placeholder: "myst-bot",
|
||||
validate: (v) =>
|
||||
v?.trim() ? undefined : "Dedicated Forgejo username is required",
|
||||
v?.trim()
|
||||
? undefined
|
||||
: "Forgejo service account username is required",
|
||||
}),
|
||||
forgejoPat: () =>
|
||||
p.password({
|
||||
message:
|
||||
"Paste the Forgejo personal access token for that dedicated Forgejo user",
|
||||
mask: "*",
|
||||
"Paste the Forgejo personal access token for that service account",
|
||||
validate: (v) => (v?.trim() ? undefined : "Forgejo PAT is required"),
|
||||
}),
|
||||
grantTokenSecret: () =>
|
||||
p.password({
|
||||
message:
|
||||
"Paste a grant token secret, or press enter to generate one automatically",
|
||||
mask: "*",
|
||||
validate: () => undefined,
|
||||
}),
|
||||
},
|
||||
|
|
@ -204,71 +204,70 @@ export async function initCommand(_args: string[]): Promise<void> {
|
|||
);
|
||||
|
||||
const s = p.spinner();
|
||||
s.start("Generating config files");
|
||||
const publicUrl = normalizeHttpUrl(answers.publicUrl);
|
||||
const adminUrl = normalizeHttpUrl(answers.adminUrl);
|
||||
const forgejoBaseUrl = normalizeHttpUrl(answers.forgejoBaseUrl);
|
||||
const grantTokenSecret = answers.grantTokenSecret?.trim() || generateSecret();
|
||||
const envContent = generateEnvFile({
|
||||
adminUrl,
|
||||
databaseUrl: answers.databaseUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoPat: answers.forgejoPat,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
grantTokenSecret,
|
||||
publicUrl,
|
||||
});
|
||||
const configContent = JSON.stringify(
|
||||
{
|
||||
adminUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
||||
publicUrl,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
|
||||
const outDir = process.cwd();
|
||||
const envPath = path.join(outDir, ".env");
|
||||
const configPath = path.join(outDir, "myst.config.json");
|
||||
|
||||
try {
|
||||
s.start("Generating config files");
|
||||
|
||||
const publicUrl = normalizeHttpUrl(answers.publicUrl);
|
||||
const adminUrl = normalizeHttpUrl(answers.adminUrl);
|
||||
const forgejoBaseUrl = normalizeHttpUrl(answers.forgejoBaseUrl);
|
||||
const grantTokenSecret =
|
||||
answers.grantTokenSecret?.trim() || generateSecret();
|
||||
|
||||
const envContent = generateEnvFile({
|
||||
adminUrl,
|
||||
databaseUrl: answers.databaseUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoBotUsername: answers.forgejoBotUsername,
|
||||
forgejoPat: answers.forgejoPat,
|
||||
grantTokenSecret,
|
||||
publicUrl,
|
||||
});
|
||||
|
||||
const configContent = JSON.stringify(
|
||||
{
|
||||
adminUrl,
|
||||
forgejoBaseUrl,
|
||||
forgejoBotUsername: answers.forgejoBotUsername,
|
||||
publicUrl,
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
|
||||
const outDir = process.cwd();
|
||||
const envPath = path.join(outDir, ".env");
|
||||
const configPath = path.join(outDir, "myst.config.json");
|
||||
|
||||
await preflightWriteTargets([envPath, configPath]);
|
||||
await writePrivateFile(envPath, envContent);
|
||||
await writePrivateFile(configPath, configContent);
|
||||
|
||||
s.stop("Config files generated");
|
||||
p.note(
|
||||
[c.green(".env"), c.green("myst.config.json")].join("\n"),
|
||||
c.yellow("Files written to current directory"),
|
||||
);
|
||||
p.note(
|
||||
[
|
||||
`${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`,
|
||||
`${c.bold("Private admin URL:")} ${c.cyan(adminUrl)}`,
|
||||
`${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
||||
`${c.bold("Forgejo bot username:")} ${c.green(answers.forgejoBotUsername)}`,
|
||||
"",
|
||||
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
||||
].join("\n"),
|
||||
c.yellow("Next steps"),
|
||||
);
|
||||
p.outro(
|
||||
c.green(
|
||||
"Done. Deploy Myst, then run forgejo bootstrap and doctor commands to verify setup.",
|
||||
),
|
||||
);
|
||||
} catch (error) {
|
||||
} catch (e) {
|
||||
s.stop();
|
||||
p.cancel(
|
||||
error instanceof Error ? error.message : "Failed to initialize Myst",
|
||||
e instanceof Error
|
||||
? e.message
|
||||
: `Failed to write config files to ${outDir}`,
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
s.stop("Config files generated");
|
||||
|
||||
p.note(
|
||||
[c.green(".env"), c.green("myst.config.json")].join("\n"),
|
||||
c.yellow("Files written to current directory"),
|
||||
);
|
||||
|
||||
p.note(
|
||||
[
|
||||
`${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`,
|
||||
`${c.bold("Private admin URL:")} ${c.cyan(adminUrl)}`,
|
||||
`${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
||||
`${c.bold("Forgejo service account:")} ${c.green(answers.forgejoServiceAccountUsername)}`,
|
||||
"",
|
||||
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
||||
].join("\n"),
|
||||
c.yellow("Next steps"),
|
||||
);
|
||||
p.outro(
|
||||
c.green(
|
||||
"Done. Deploy Myst, then run forgejo bootstrap and doctor commands to verify setup.",
|
||||
),
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@ interface EnvOptions {
|
|||
adminUrl: string;
|
||||
databaseUrl: string;
|
||||
forgejoBaseUrl: string;
|
||||
forgejoBotUsername: string;
|
||||
forgejoPat: string;
|
||||
forgejoServiceAccountUsername: string;
|
||||
grantTokenSecret: string;
|
||||
publicUrl: string;
|
||||
}
|
||||
|
|
@ -12,8 +12,7 @@ function escapeEnvValue(value: string): string {
|
|||
return `"${value
|
||||
.replace(/\\/g, "\\\\") // Escape backslashes
|
||||
.replace(/"/g, '\\"') // Escape double quotes
|
||||
.replace(/\r?\n/g, "\\n") // Escape newlines
|
||||
.replace(/\$/g, "\\$")}"`; // Escape dollar signs
|
||||
.replace(/\r?\n/g, "\\n")}"`; // Escape newlines
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
@ -31,9 +30,9 @@ MYST_ADMIN_URL=${escapeEnvValue(options.adminUrl)}
|
|||
# Myst's own Postgres database.
|
||||
DATABASE_URL=${escapeEnvValue(options.databaseUrl)}
|
||||
|
||||
# Existing Forgejo instance and operator-created PAT for the dedicated Forgejo user.
|
||||
# Existing Forgejo instance and operator-created service account token.
|
||||
FORGEJO_BASE_URL=${escapeEnvValue(options.forgejoBaseUrl)}
|
||||
FORGEJO_BOT_USERNAME=${escapeEnvValue(options.forgejoBotUsername)}
|
||||
FORGEJO_SERVICE_ACCOUNT_USERNAME=${escapeEnvValue(options.forgejoServiceAccountUsername)}
|
||||
FORGEJO_PAT=${escapeEnvValue(options.forgejoPat)}
|
||||
|
||||
# Secret used to sign or derive grant tokens.
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
export const MYST_DEFAULT_FORGEJO_PORT = 3000;
|
||||
export const MYST_DEFAULT_SERVICE_PORT = 4000;
|
||||
|
||||
export const MYST_VISIBILITY_MODES = {
|
||||
TEAM: "team",
|
||||
ALLOWLIST: "allowlist"
|
||||
} as const;
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
export type VisibilityMode = "team" | "allowlist";
|
||||
|
||||
export interface RepoRef {
|
||||
owner: string;
|
||||
name: string;
|
||||
|
|
@ -8,3 +10,4 @@ export interface GrantSnapshot {
|
|||
sourceBranch: string;
|
||||
commitSha: string;
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue