How it works

packshell is a client-side encryption system with a thin sync server. Understanding the flow makes the security guarantees obvious.

The push path

When you run packshell push, the CLI does the following entirely on your machine:

1. Reads your local .env file.
2. Encrypts the contents with the project key using AES-256-GCM, producing a cipher blob tagged with the aes-256-gcm: envelope prefix.
3. Computes a SHA-256 checksum and a count of how many keys are present.
4. Uploads only the cipher blob, checksum, and key count as a new immutable version.

The server stores the version but has no way to read it — it never receives the project key or the plaintext.

The pull path

packshell pull reverses it: the CLI downloads the latest cipher blob for the environment, decrypts it locally with the project key it already holds, and writes the resulting .env to disk.

local .env  ──AES-256-GCM(projectKey)──▶  aes-256-gcm:<cipher blob>  ──▶  serverserver  ──▶  aes-256-gcm:<cipher blob>  ──AES-256-GCM-decrypt(projectKey)──▶  local .env

How teammates get the key

The project key never travels in the clear. Each member has a personal RSA-4096 keypair; the private half stays on their machine. To grant access, the project key is wrapped(encrypted) with the recipient's public key using RSA-OAEP, and only that wrapped key is stored on the server under the rsa-oaep: envelope. The recipient unwraps it locally with their private key.

This is why invite and share are CLI actions: the wrapping happens on your machine where the project key lives. The server only ever holds wrapped keys it cannot open.

What the dashboard shows

The web dashboard reads the metadata the server can see: companies, projects, environments, version checksums and timestamps, who has access, and the audit log. It deliberately cannot show secret values, because those values never reach it. Operations that require the project key — creating a project, pushing, pulling, sharing — live in the CLI.