Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Security boundaries

This page describes the current implementation in packages/. It separates authentication from confidentiality so the guarantee stays precise.

Account root

Account creation generates an Ed25519 root key. The private key is encoded as the gsr_ recovery key and shown to the user. The control plane receives the public key.
The root key signs browser authority. An account-wide delegating browser can approve a machine grant without copying the root key to that machine. Possession of the recovery key is account-root authority.
GitSpace does not store the recovery key and cannot restore it. Keep it outside source control, chat, workspace notes, and browser screenshots.

Machine identity

gitspace machine setup --pair <token> creates separate Ed25519 signing and X25519 key-exchange keys on the computer. It proves possession of the signing key before the browser can approve the request.
The browser signs a grant naming the account, machine, public keys, generation, allowed capabilities, and approving device. The grant carries the root/device proof chain. Verification also checks the canonical issuer's revocation and expiry state. Revoking that authority can invalidate a dependent machine grant.
Pairing tokens expire after ten minutes and cannot bind a second set of machine keys. A claimed machine can retry retrieval with a fresh signature until the original expiry. The machine receives only its own enrollment configuration, not the account root private key.

Browser identity

Account creation or recovery in the web page creates a short-lived signed browser invitation. The browser creates a non-extractable Ed25519 key in IndexedDB and redeems the invitation for a device grant. The account root key is not persisted in browser storage.
Browser RPC requests are signed. Verification binds a request to the enrolled device and detects changes to the signed request.

Encrypted data

Current package code encrypts these data classes:
  • Artifact and checkpoint blobs use AES-GCM with an account-scoped key supplied to authorized machines. The managed credential vault is part of this trust boundary.
  • Machine credential envelopes use ephemeral X25519 key agreement, HKDF-SHA256 key derivation, and AES-GCM authenticated encryption.
These are scoped guarantees. They do not imply that every request or terminal byte uses the same encryption boundary.

Relay and Worker visibility

The production browser transport signs RPC requests, but it does not currently encrypt every RPC body end to end between the browser and machine. The account Worker and relay terminate or route production requests and may observe data needed by that path.
A full encrypted RPC transport exists in package library and test code, but it is not wired into the production browser transport. Treat the account Worker and relay as part of the trusted routing path, not as zero-knowledge infrastructure.

Operational responsibilities

  • Protect the gsr_ recovery key as the account root secret.
  • Use separate machine and browser enrollments instead of copying device private keys.
  • Revoke devices that should no longer have access.
  • Treat machine hosts as trusted for the repositories, agents, services, and decrypted workspace data placed on them.
  • Review device grants and capability changes as security-sensitive operations.

Algorithms in current package code

PurposeAlgorithm
Account, machine, and browser signingEd25519
Machine credential key agreementX25519
Key derivation for sealed credentialsHKDF-SHA256
Artifact, checkpoint, and credential encryptionAES-GCM