Diff: applications/app-privategit-workbench
From d70ca2d to d70ca2d
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Browser developer workbench" | title: "Browser developer workbench" |
| slug: app-privategit-workbench | slug: app-privategit-workbench |
| category: applications | category: applications |
| type: topic | type: topic |
| quality: in-progress | quality: in-progress |
| status: active | status: active |
| audience: vendor-public | audience: vendor-public |
| bcsc_class: no-disclosure-implication | bcsc_class: no-disclosure-implication |
| language_protocol: PROSE-TOPIC | language_protocol: PROSE-TOPIC |
| last_edited: 2026-05-28 | last_edited: 2026-05-28 |
| editor: jwoodfine | editor: jwoodfine |
| short_description: "app-privategit-workbench is a browser-based file editor included in the os-privategit host operating system, presenting a three-column interface — file tree, viewer, and editor — for working with plain-text and source files across the cluster archive tree without a terminal session." | short_description: "app-privategit-workbench is a browser-based file editor included in the os-privategit host operating system, presenting a three-column interface — file tree, viewer, and editor — for working with plain-text and source files across the cluster archive tree without a terminal session." |
| paired_with: app-privategit-workbench.es.md | paired_with: app-privategit-workbench.es.md |
| cites: [] | cites: [] |
| --- | --- |
| `app-privategit-workbench` is a browser-based file editor included | `app-privategit-workbench` is a browser-based file editor included |
| in the [[os-privategit|`os-privategit`]] host operating system. It presents a local | in the [[os-privategit|`os-privategit`]] host operating system. It presents a local |
| HTTP endpoint that serves a single-page application with a | HTTP endpoint that serves a single-page application with a |
| three-column layout: a file tree sidebar, a content viewer, and a | three-column layout: a file tree sidebar, a content viewer, and a |
| plain-text editor. | plain-text editor. |
| The workbench is the primary authoring and review surface for | The workbench is the primary authoring and review surface for |
| [[totebox-orchestration|Totebox Orchestration]] operators and Community Members who want | [[totebox-orchestration|Totebox Orchestration]] operators and Community Members who want |
| direct browser-based access to their [[totebox-archive|archive tree]] without a terminal | direct browser-based access to their [[totebox-archive|archive tree]] without a terminal |
| session. It is not a publication surface — it writes to the local | session. It is not a publication surface — it writes to the local |
| filesystem and relies on the git-based version-control pipeline | filesystem and relies on the git-based version-control pipeline |
| for history and promotion. | for history and promotion. |
| --- | --- |
| ## Architecture | ## Architecture |
| The workbench is a single Rust crate (`app-privategit-workbench`, | The workbench is a single Rust crate (`app-privategit-workbench`, |
| Apache 2.0) in the `pointsav-monorepo`. It has two components: | Apache 2.0) in the `pointsav-monorepo`. It has two components: |
| **Write-service (Rust/axum):** An HTTP server that handles file reads | **Write-service (Rust/axum):** An HTTP server that handles file reads |
| and writes. It binds to a loopback address and is never exposed | and writes. It binds to a loopback address and is never exposed |
| directly to external networks. The service enforces root containment | directly to external networks. The service enforces root containment |
| (all paths are canonicalized and checked against declared roots), | (all paths are canonicalized and checked against declared roots), |
| an extension allowlist, and mtime-based conflict detection. | an extension allowlist, and mtime-based conflict detection. |
| **Single-page application:** A self-contained HTML file embedded into | **Single-page application:** A self-contained HTML file embedded into |
| the binary at compile time via `include_str!`. The SPA makes API | the binary at compile time via `include_str!`. The SPA makes API |
| calls through an nginx proxy to the write-service for file reads and | calls through an nginx proxy to the write-service for file reads and |
| writes, and to nginx autoindex routes for directory listings. No | writes, and to nginx autoindex routes for directory listings. No |
| external resources are loaded at runtime. | external resources are loaded at runtime. |
| The binary is compiled for the `os-privategit` host and managed by | The binary is compiled for the `os-privategit` host and managed by |
| a systemd unit. The nginx intranet routes `/_api/edit/*` to the | a systemd unit. The nginx intranet routes `/_api/edit/*` to the |
| write-service and serves autoindex JSON at `/_api/command/`, | write-service and serves autoindex JSON at `/_api/command/`, |
| `/_api/clones/`, and per-sandbox prefixes. | `/_api/clones/`, and per-sandbox prefixes. |
| --- | --- |
| ## File tree | ## File tree |
| The sidebar lists the roots declared in `config.toml`. Each root maps | The sidebar lists the roots declared in `config.toml`. Each root maps |
| a URL prefix (for example, `_clones/project-development`) to a | a URL prefix (for example, `_clones/project-development`) to a |
| filesystem path (for example, `/srv/foundry/clones/project-development`). | filesystem path (for example, `/srv/foundry/clones/project-development`). |
| Roots may be writable or read-only. The Command workspace root | Roots may be writable or read-only. The Command workspace root |
| (`/srv/foundry`) is always read-only; archive roots are writable. | (`/srv/foundry`) is always read-only; archive roots are writable. |
| Directory contents are fetched on expand from nginx autoindex JSON. | Directory contents are fetched on expand from nginx autoindex JSON. |
| The tree supports nested expansion to arbitrary depth. | The tree supports nested expansion to arbitrary depth. |
| --- | --- |
| ## Viewer | ## Viewer |
| The centre column renders the selected file according to its extension: | The centre column renders the selected file according to its extension: |
| - **Markdown (`.md`):** Rendered as HTML using a built-in parser. | - **Markdown (`.md`):** Rendered as HTML using a built-in parser. |
| Fenced code blocks, inline code, headings, lists, links, and tables | Fenced code blocks, inline code, headings, lists, links, and tables |
| are supported. Click-to-source from rendered headings and paragraphs | are supported. Click-to-source from rendered headings and paragraphs |
| moves the editor cursor to the corresponding source line. | moves the editor cursor to the corresponding source line. |
| - **HTML (`.html`):** Displayed in a sandboxed iframe. | - **HTML (`.html`):** Displayed in a sandboxed iframe. |
| - **Images:** Displayed inline. | - **Images:** Displayed inline. |
| - **All other types:** Displayed as plain text. | - **All other types:** Displayed as plain text. |
| The viewer and editor operate independently. Opening a read-only file | The viewer and editor operate independently. Opening a read-only file |
| shows the viewer without the editor panel. | shows the viewer without the editor panel. |
| --- | --- |
| ## Editor | ## Editor |
| The right column appears when the open file is in a writable root. The | The right column appears when the open file is in a writable root. The |
| editor is a `<textarea>` with the following features: | editor is a `<textarea>` with the following features: |
| - Line number gutter with active-line highlight | - Line number gutter with active-line highlight |
| - Cursor position indicator (line and column) in the editor bar | - Cursor position indicator (line and column) in the editor bar |
| - Dirty state indicator (orange dot) when unsaved changes are present | - Dirty state indicator (orange dot) when unsaved changes are present |
| - Save: `Cmd+S` or the Save button — writes via `PUT /file` with the | - Save: `Cmd+S` or the Save button — writes via `PUT /file` with the |
| current mtime to detect concurrent edits; shows a conflict dialog on | current mtime to detect concurrent edits; shows a conflict dialog on |
| HTTP 409 | HTTP 409 |
| - Find / Replace bar (`Cmd+F`): incremental match highlighting, previous | - Find / Replace bar (`Cmd+F`): incremental match highlighting, previous |
| / next navigation, Replace and Replace All; preserves native undo stack | / next navigation, Replace and Replace All; preserves native undo stack |
| via `execCommand` | via `execCommand` |
| - Document Outline panel (`Cmd+Shift+O`): lists all markdown headings | - Document Outline panel (`Cmd+Shift+O`): lists all markdown headings |
| (H1–H6) or TOML table headers from the current file; filter by typing; | (H1–H6) or TOML table headers from the current file; filter by typing; |
| click or press Enter to jump the cursor to that symbol | click or press Enter to jump the cursor to that symbol |
| - Toggle line comment button: extension-aware (`//` for Rust/JS/TS, | - Toggle line comment button: extension-aware (`//` for Rust/JS/TS, |
| `#` for TOML/YAML/shell); toggles selected lines | `#` for TOML/YAML/shell); toggles selected lines |
| - Go to line (`Ctrl+G`) | - Go to line (`Ctrl+G`) |
| - Tab inserts two spaces | - Tab inserts two spaces |
| - Bracket auto-close for `{`, `[`, `(` | - Bracket auto-close for `{`, `[`, `(` |
| - Line move up / down (`Alt+↑` / `Alt+↓`) | - Line move up / down (`Alt+↑` / `Alt+↓`) |
| - Line duplicate (`Shift+Alt+↓`) | - Line duplicate (`Shift+Alt+↓`) |
| --- | --- |
| ## Security model | ## Security model |
| The write-service enforces four layers of containment aligned with the [[pre-commit-defense-in-depth|pre-commit defence-in-depth]] approach used across the platform: | The write-service enforces four layers of containment aligned with the [[pre-commit-defense-in-depth|pre-commit defence-in-depth]] approach used across the platform: |
| **Root containment:** Every path is canonicalized with `std::fs::canonicalize` | **Root containment:** Every path is canonicalized with `std::fs::canonicalize` |
| and verified to remain within the declared root's filesystem path. Paths | and verified to remain within the declared root's filesystem path. Paths |
| that resolve outside the root are rejected with HTTP 400. | that resolve outside the root are rejected with HTTP 400. |
| **CSRF guard:** Every `PUT /file` request requires the `X-Foundry-Editor: 1` | **CSRF guard:** Every `PUT /file` request requires the `X-Foundry-Editor: 1` |
| header. The browser's cross-origin policy prevents third-party pages from | header. The browser's cross-origin policy prevents third-party pages from |
| adding this header. | adding this header. |
| **Extension allowlist:** Writes are permitted only for recognized plain-text | **Extension allowlist:** Writes are permitted only for recognized plain-text |
| and source-code extensions. Binary formats and unknown extensions are | and source-code extensions. Binary formats and unknown extensions are |
| read-only through the workbench. | read-only through the workbench. |
| **Writable flag:** The `writable = false` declaration in a root entry causes | **Writable flag:** The `writable = false` declaration in a root entry causes |
| all write attempts to that root to be rejected with HTTP 403, regardless of | all write attempts to that root to be rejected with HTTP 403, regardless of |
| filesystem permissions. | filesystem permissions. |
| The systemd unit runs with `ProtectSystem=strict` and `ReadWritePaths=` | The systemd unit runs with `ProtectSystem=strict` and `ReadWritePaths=` |
| scoped to the declared writable roots. Adding a new writable root requires | scoped to the declared writable roots. Adding a new writable root requires |
| updating both `config.toml` and the systemd service file; missing the | updating both `config.toml` and the systemd service file; missing the |
| service file update causes silent write failures at the filesystem layer. | service file update causes silent write failures at the filesystem layer. |
| --- | --- |
| ## Relationship to os-privategit | ## Relationship to os-privategit |
| `app-privategit-workbench` is included in the [[os-privategit|`os-privategit`]] host | `app-privategit-workbench` is included in the [[os-privategit|`os-privategit`]] host |
| operating system alongside `app-privategit-design-system` and | operating system alongside `app-privategit-design-system` and |
| `service-privategit`. It is the authoring surface for operators who | `service-privategit`. It is the authoring surface for operators who |
| use the privategit tier — a locally-hosted, network-isolated development | use the privategit tier — a locally-hosted, network-isolated development |
| environment for [[totebox-orchestration|Totebox Orchestration]] instances. Access to writable roots is governed by the [[machine-based-auth|machine-based authorization]] model. | environment for [[totebox-orchestration|Totebox Orchestration]] instances. Access to writable roots is governed by the [[machine-based-auth|machine-based authorization]] model. |
| The crate is licensed under the Apache License, Version 2.0 and intended | The crate is licensed under the Apache License, Version 2.0 and intended |
| for downstream deployment in customer-tier instances of `os-privategit`. | for downstream deployment in customer-tier instances of `os-privategit`. |
| An operational setup guide is available in the customer fleet deployment | An operational setup guide is available in the customer fleet deployment |
| catalog. | catalog. |
| --- | --- |
| ## Planned additions | ## Planned additions |
| - **Phase 4 (planned/intended):** CodeMirror 6 integration for syntax | - **Phase 4 (planned/intended):** CodeMirror 6 integration for syntax |
| highlighting; authenticated roots with per-user writable scope. | highlighting; authenticated roots with per-user writable scope. |
| ## See also | ## See also |
| - [[os-privategit]] — the host operating system that includes this workbench | - [[os-privategit]] — the host operating system that includes this workbench |
| - [[totebox-archive]] — the archive tree that operators work with through the workbench | - [[totebox-archive]] — the archive tree that operators work with through the workbench |
| - [[machine-based-auth]] — the authorization model governing writable root access | - [[machine-based-auth]] — the authorization model governing writable root access |
| - [[pre-commit-defense-in-depth]] — the defence-in-depth discipline applied by the write-service | - [[pre-commit-defense-in-depth]] — the defence-in-depth discipline applied by the write-service |