Skip to content

Commit 70e22ea

Browse files
committed
build: add Arch Linux package recipe
- Ensure secure handling of sessions and credentials with appropriate error handling and validation.
1 parent e229799 commit 70e22ea

19 files changed

Lines changed: 980 additions & 18 deletions

‎AGENTS.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,11 @@ Project-owned type declarations belong in `.ts` files. `.d.ts` is reserved for a
143143

144144
### Client and transport boundary
145145

146-
The shared React renderer is being prepared for desktop and browser clients. New renderer code must obtain privileged operations through the typed CrewCode client boundary in `src/renderer/src/runtime/crewcode-client.ts`; do not introduce transport-specific HTTP/WebSocket calls in components. Electron currently installs `window.electronAPI` as that client. The future web adapter will implement the same contract over authenticated, versioned HTTP/WebSocket RPC. Protocol envelopes live in `src/shared/remote-access-types.ts`; see `docs/web-remote-access.md`.
146+
The shared React renderer supports desktop and direct browser clients. New renderer code must obtain privileged operations through the typed CrewCode client boundary in `src/renderer/src/runtime/crewcode-client.ts`; do not introduce transport-specific HTTP/WebSocket calls in components. Electron installs `window.electronAPI`; the web adapter implements the same contract over authenticated, versioned HTTP/WebSocket RPC. Protocol envelopes live in `src/shared/remote-access-types.ts`; see `docs/web-remote-access.md`.
147+
148+
Remote-access credentials are authority boundaries. Pairing tokens must remain short-lived, memory-only, and single-use. Persist only device-session digests in owner-only atomic stores; enforce expiry and revocation. Browser HTTP/WebSocket origins must match exactly or be explicitly configured—never reflect arbitrary `Origin`/forwarded headers. Keep authentication limiters bounded, and do not hardcode CJ's `crewcode.logixhub.icu` deployment as a default Hub URL.
149+
150+
The self-hosted Hub is a separate `crewcode hub` process, not Electron renderer state. Keep its SQLite store owner-only and server-side; persist WebAuthn public credentials and only digests of browser/CSRF secrets. Bootstrap credentials and WebAuthn challenges stay short-lived and memory-only. Require user verification, exact configured RP origin/id, one-use challenges, secure HttpOnly SameSite cookies, and CSRF checks for mutations. Do not let Hub identity imply brain execution authority: enrollment, tickets, relay, and brain-side authorization remain separate gates.
147151

148152
### Path alias
149153

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,52 @@ CrewCode is strongest today for:
195195
4. watch output in chat, terminal panes, and Mission Control
196196
5. inspect diffs, commit changes, open or merge PRs, or discard work
197197

198+
## Install on Linux
199+
200+
The installer detects Arch-based and Debian-based distributions and uses their
201+
native package manager. Other x86_64 Linux distributions receive a user-local
202+
AppImage installation.
203+
204+
Download and review the installer before running it:
205+
206+
```bash
207+
curl --proto '=https' --tlsv1.2 -fsSLo install-crewcode.sh \
208+
https://crewcode.logixhub.icu/install
209+
less install-crewcode.sh
210+
sh install-crewcode.sh
211+
```
212+
213+
Or use the convenience one-liner after reviewing the
214+
[installer source](./scripts/install-linux.sh):
215+
216+
```bash
217+
curl --proto '=https' --tlsv1.2 -fsSL \
218+
https://crewcode.logixhub.icu/install | sh
219+
```
220+
221+
The installer verifies the selected `v0.2.1` release artifact with SHA-256 and
222+
prompts before invoking a package manager or writing user-local application
223+
files. It refuses to run as root. Use `sh install-crewcode.sh --dry-run` to see
224+
the selected method without changing files.
225+
226+
### Manual Arch Linux package
227+
228+
Until `crewcode-bin` is available in the AUR, Arch users can instead build and
229+
install the pacman-managed package directly from this repository:
230+
231+
```bash
232+
sudo pacman -S --needed base-devel git
233+
git clone https://github.com/OnPoint-Dev-Tools/crewcode.git
234+
cd crewcode/packaging/arch
235+
less PKGBUILD # review the package recipe before building
236+
makepkg -si
237+
```
238+
239+
The PKGBUILD downloads CrewCode's official x86_64 release artifact, verifies its
240+
SHA-256 checksum, and repackages it for pacman. Arch does not install the Debian
241+
package directly. See the [Arch Linux package guide](./docs/arch-linux-package.md)
242+
for upgrade, uninstall, and maintainer instructions.
243+
198244
## Development
199245

200246
```bash

‎docs/README.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ internal references).
1010

1111
| Doc | What it covers |
1212
| --- | --- |
13-
| [getting-started.md](./getting-started.md) | Install (download placeholder + build from source), providers, first run |
13+
| [getting-started.md](./getting-started.md) | Install from a release or source, providers, first run |
14+
| [arch-linux-package.md](./arch-linux-package.md) | Build, upgrade, and uninstall the temporary manual Arch Linux package |
1415
| [keybindings.md](./keybindings.md) | Every shortcut, defaults per group, and the editable `~/.crewcode/keys.json` override file |
1516
| [tweaks-panel.md](./tweaks-panel.md) | The floating Layout panel: density and workspace dock presentation controls |
1617
| [system-monitor.md](./system-monitor.md) | CPU/memory pill and panel: per-workspace process usage, jump-to and kill controls |
@@ -59,8 +60,6 @@ internal references).
5960

6061
## Content gaps for the site
6162

62-
- **Install links** — `getting-started.md` has a placeholder; swap in real
63-
download links when installers are published.
6463
- **Notifications** — `notifications.md` is a developer API reference; if the
6564
notification bar needs user documentation, it's a couple of paragraphs, not
6665
that file.

‎docs/arch-linux-package.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Arch Linux package
2+
3+
Until CrewCode can be listed in the Arch User Repository (AUR), this repository
4+
ships a manual `crewcode-bin` PKGBUILD in [`packaging/arch`](../packaging/arch/).
5+
It downloads the official x86_64 Debian release artifact, verifies its SHA-256
6+
checksum, and repackages its files as a native package managed by pacman. Arch
7+
does not install the Debian package directly.
8+
9+
Only x86_64 is currently supported because CrewCode does not yet publish a Linux
10+
ARM64 artifact.
11+
12+
## Install
13+
14+
Install Arch's standard package-building tools if needed:
15+
16+
```bash
17+
sudo pacman -S --needed base-devel git
18+
```
19+
20+
Clone CrewCode, inspect the package recipe, then build and install it:
21+
22+
```bash
23+
git clone https://github.com/OnPoint-Dev-Tools/crewcode.git
24+
cd crewcode/packaging/arch
25+
less PKGBUILD
26+
makepkg -si
27+
```
28+
29+
`makepkg` downloads the pinned CrewCode release and refuses to build if its
30+
checksum does not match. `pacman` installs the resulting `crewcode-bin` package.
31+
Launch CrewCode from the desktop application menu or run:
32+
33+
```bash
34+
crewcode
35+
```
36+
37+
Optional integrations such as an AI agent CLI must still be installed and
38+
authenticated separately.
39+
40+
## Upgrade
41+
42+
Pull a repository revision containing an updated PKGBUILD and rebuild it:
43+
44+
```bash
45+
cd crewcode
46+
git pull --ff-only
47+
cd packaging/arch
48+
makepkg -si
49+
```
50+
51+
Until the package reaches AUR, AUR helpers cannot discover upgrades
52+
automatically.
53+
54+
## Uninstall
55+
56+
```bash
57+
sudo pacman -Rns crewcode-bin
58+
```
59+
60+
This removes application files managed by pacman. It does not remove the user's
61+
CrewCode configuration and data.
62+
63+
## Maintainer release update
64+
65+
After publishing a stable GitHub release with a matching
66+
`CrewCode-<version>-amd64.deb` artifact:
67+
68+
1. Set `pkgver` to the release version and reset `pkgrel` to `1`.
69+
2. Replace `sha256sums_x86_64` with the artifact's SHA-256 checksum. Never use
70+
`SKIP` for a release binary.
71+
3. Regenerate metadata from `packaging/arch`:
72+
73+
```bash
74+
makepkg --printsrcinfo > .SRCINFO
75+
```
76+
77+
4. Run `makepkg --cleanbuild`, install the result, and verify both the desktop
78+
launcher and `crewcode` command.
79+
5. If available, run `namcap PKGBUILD` and `namcap crewcode-bin-*.pkg.tar.zst`
80+
and review its findings before committing.
81+
82+
When AUR account registration becomes available, the contents of
83+
`packaging/arch` can be pushed to the separate AUR Git repository for
84+
`crewcode-bin`.

‎docs/getting-started.md‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,36 @@ chat, terminals, a code editor, and git review in one window.
66

77
## Install
88

9-
<!-- TODO(release): replace this section with download links once installers are published. -->
9+
Download the latest stable Linux, macOS, or Windows artifact from
10+
[GitHub Releases](https://github.com/OnPoint-Dev-Tools/crewcode/releases/latest).
1011

11-
> [!NOTE]
12-
> Official installers for **Linux (AppImage/deb), macOS (dmg), and Windows**
13-
> are coming soon — download links will appear here.
12+
On x86_64 Linux, download and review the universal installer before running it:
13+
14+
```bash
15+
curl --proto '=https' --tlsv1.2 -fsSLo install-crewcode.sh \
16+
https://crewcode.logixhub.icu/install
17+
less install-crewcode.sh
18+
sh install-crewcode.sh
19+
```
20+
21+
The installer uses pacman on Arch-based systems, apt on Debian-based systems,
22+
and a user-local AppImage elsewhere. It verifies the pinned release checksum,
23+
refuses root execution, and prompts before installation. The convenience form
24+
is:
25+
26+
```bash
27+
curl --proto '=https' --tlsv1.2 -fsSL \
28+
https://crewcode.logixhub.icu/install | sh
29+
```
30+
31+
Arch Linux users can alternatively build a pacman-managed `crewcode-bin` package
32+
using the [manual Arch package instructions](./arch-linux-package.md). The recipe
33+
verifies and repackages CrewCode's official release artifact; it does not install
34+
a Debian package directly.
1435

1536
### Build from source (contributors)
1637

17-
Requirements: Node.js 20+, git.
38+
Requirements: Node.js 22.16 or newer, git.
1839

1940
```bash
2041
git clone https://github.com/OnPoint-Dev-Tools/crewcode.git

‎docs/releasing.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,29 @@ gh release list
6464
gh release edit v0.1.1 --draft=false
6565
```
6666

67+
## Updating the Linux web installer
68+
69+
The universal Linux installer is pinned to one stable release instead of trusting
70+
a mutable `latest` download. After publishing a new stable release:
71+
72+
1. Update the version, Debian SHA-256, and AppImage SHA-256 in
73+
`scripts/install-linux.sh`. Obtain digests from the published GitHub assets,
74+
not from a local build with the same filename.
75+
2. Update `packaging/arch/PKGBUILD` and regenerate its `.SRCINFO`.
76+
3. Run the installer's `--dry-run` checks and isolated Arch, Debian, and AppImage
77+
method tests.
78+
4. Copy the verified script byte-for-byte to `public/install` in the separate
79+
`CjLogic/crewcode-website` repository, build that site, and verify
80+
`dist/install` still matches.
81+
5. Deploy the website and confirm
82+
`https://crewcode.logixhub.icu/install` starts with `#!/bin/sh` and does not
83+
return the SPA HTML fallback.
84+
85+
The public installer refuses root execution, prompts before installation, and
86+
uses native packages on Arch/Debian with a user-local AppImage fallback. Do not
87+
replace the pinned checksums with `SKIP` or runtime parsing of an unsigned
88+
`latest` response.
89+
6790
## Release channels
6891

6992
Two trains, and the distinction is **prerelease vs not** — not electron-builder

‎docs/security-model.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,31 @@ re-decided at each hop's gate, not carried forward as context.
3434
- Production renderer CSP locks `default-src 'self'`, `connect-src 'self' data: blob:`
3535
(`src/main/index.ts:89`), so a compromised renderer cannot open arbitrary sockets.
3636

37+
## Remote browser -> headless brain boundary
38+
39+
**Boundary:** a network browser must not acquire privileged RPC authority through a
40+
replayed pairing link, stolen persisted file, cross-origin request, or unbounded
41+
credential guessing.
42+
43+
**Enforcement:** `RemoteAccessAuth` keeps pairing credentials memory-only,
44+
short-lived, and single-use. Device session files contain SHA-256 digests rather than
45+
bearer tokens, are written atomically with owner-only permissions, survive restart,
46+
and enforce 30-day absolute plus 7-day idle expiry. Authenticated `auth.sessions` and
47+
`auth.revoke` RPC expose only sanitized metadata. HTTP and WebSocket browser requests
48+
must match the request's exact origin or a CLI-configured `--public-origin`.
49+
Pairing and failed-session attempts use bounded per-peer fixed-window limits. The
50+
brain still revalidates registered workspace roots for filesystem, Git, PTY, and
51+
agent operations; transport authentication does not widen filesystem scope.
52+
53+
**Tests:** `remote-access-auth.test.ts`, `remote-access-security.test.ts`, and
54+
`remote-access-server.test.ts` cover persistence/restart, expiry, revocation,
55+
corrupt-store refusal, origin rejection, rate limiting, and workspace denial.
56+
57+
**Residual limitation:** the direct server does not yet have a general
58+
per-authenticated-session RPC bandwidth/request budget, remote execution custody is
59+
not fully persisted, and public deployment still depends on correctly configured
60+
TLS/reverse-proxy infrastructure. Prefer loopback or a trusted tailnet.
61+
3762
## Hop 1 — untrusted content -> agent
3863

3964
**Boundary:** injected instructions in scraped/file/MCP content must not gain

‎electron.vite.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ export default defineConfig({
2323
input: {
2424
index: resolve('src/main/index.ts'),
2525
headless: resolve('src/main/headless.ts'),
26+
hub: resolve('src/main/hub.ts'),
2627
},
2728
},
2829
}

0 commit comments

Comments
 (0)