sealkeep 0.5.0

package/ARCHITECTURE.md

@@ -0,0 +1,201 @@
+# Sealkeep Architecture and Contracts
+
+## 1. Trust boundaries
+
+```text
+Agent transcript -> local adapter -> local queue -> crypto boundary
+                                              | plaintext ends here
+                                              v
+                               ciphertext + opaque metadata
+                                              |
+                         control plane -> scoped provider lease
+                                              |
+                                     S3 / R2 / GCS / managed store
+```
+
+The client is trusted to handle plaintext. The control plane and object store are untrusted for confidentiality. The MCP server is local but model-invoked, so tools must minimize disclosure and mark destructive actions clearly.
+
+## 2. Client modules
+
+- `adapters`: discover roots, consume hook payloads, preserve raw files.
+- `queue`: durable jobs, retries, backoff, idempotency.
+- `crypto`: versioned envelope, key generation/wrapping, integrity.
+- `providers`: lease client, multipart/resumable upload, plain object verbs, remote checksum.
+- `chunk-store`: remote layout v2 — one archive as one folder of sealed chunks, path
+  segments hashed under a storage-scoped key, readable identity in a sealed sidecar.
+- `index-sync`: the sealed content index, pulled and pushed as ciphertext so every
+  machine of the vault searches the whole history.
+- `retention`: active-session detection, policy evaluation, grace/trash staging.
+- `restore`: integrity checks, atomic output, native adapter mapping; `rehydrate`
+  restores an archived transcript before an agent's resume reads it.
+- `local-api`: loopback API shared by CLI/TUI/desktop/MCP.
+
+Implemented as: `src/adapters.ts`, `src/watcher.ts`, `src/queue.ts`, `src/worker.ts`,
+`packages/vaultline-crypto/`, `src/providers/`, `src/secrets.ts`, `src/upload.ts`,
+`src/chunk-store.ts`, `src/index-sync.ts`, `src/stream-to-cloud.ts`,
+`src/retention.ts` with `src/activity.ts` and `src/trash.ts`, `src/restore.ts` with
+`src/rehydrate.ts`, `src/share.ts`, `src/rotate.ts`,
+`src/local-api.ts` with `web/` and `src/tui.ts`, `src/daemon.ts`, `src/search.ts`,
+`src/audit.ts`, `src/migrate.ts`, `src/doctor.ts`, `src/mcp.ts` with
+`src/mcp-install.ts`, and
+`src/control-plane/`. `src/errors.ts` holds the shared failure codes every surface reports.
+
+## 2.1 Queue and idempotency
+
+A job is one atomically created file named by a content-addressed id derived from
+`agent + resolved source path + byte length + mtime`. Two consequences follow:
+
+- Repeated lifecycle events for an unchanged transcript collapse to one job, so a
+  `PostCompact` immediately followed by a `SessionEnd` archives once.
+- Concurrent hook processes cannot create duplicates: creation uses `link(2)`,
+  which fails atomically when the id already exists.
+
+Work is handed out under a time-boxed lease. An expired lease is reclaimed on the
+next claim, which is how an interrupted worker recovers. Completion requires a
+matching unexpired lease; a stale worker cannot mark a job done. Failure applies
+exponential backoff and dead-letters after `maxAttempts`, and a dead-lettered job
+only returns to `ready` through an explicit `queue retry`.
+
+Archiving is separately idempotent: `archiveFile` returns the existing record when
+the same source path already has an archive with the same plaintext SHA-256. A
+worker that dies between encrypting and completing therefore never writes a second
+archive on retry.
+
+## 2.2 Hook boundary
+
+Hook commands hold no secret. They parse the lifecycle payload for a transcript
+path (`transcript_path`, `rollout_path`, and camelCase spellings), verify it is
+readable, enqueue, and exit. Unknown vendor fields are ignored rather than parsed,
+so a schema change cannot break preservation. Encryption happens later in
+`sealkeep queue run`, which is the only process that sees the recovery phrase.
+
+## 3. Archive envelope (implemented, format v2)
+
+```json
+{
+  "version": 2,
+  "archiveId": "uuid",
+  "suite": "chacha20-poly1305",
+  "chunkBytes": 4194304,
+  "chunks": [{ "index": 0, "plaintextBytes": 0, "storedBytes": 16, "sha256": "...", "nonce": "...", "final": true }],
+  "manifest": { "plaintextSha256": "...", "plaintextBytes": 0, "createdAt": "...", "adapter": { "agent": "codex", "version": "1" } },
+  "wrappedKeys": [{ "type": "phrase", "id": "...", "kdf": {}, "nonce": "...", "ciphertext": "..." }]
+}
+```
+
+Each chunk is authenticated with associated data covering format version, suite, archive
+id, chunk index, total chunk count, plaintext length, and a final-chunk flag. Wrapped keys
+are separately bound to archive id and suite, so tampering with either is caught at unwrap
+time before any chunk is touched. An archive is durable only after the provider confirms
+the byte count and checksum the client computed; `remote.verifiedAt` records that, and
+retention reads it.
+
+Full specification, test vectors, and tamper coverage: `packages/vaultline-crypto/`.
+
+## 4. Control-plane API v1
+
+Authentication is on by default. `VAULTLINE_CONTROL_PLANE_DEV=1` disables device signatures
+and keeps state in memory for local interface work; `/health` reports
+`mode: development-interface` so a misconfigured deployment is visible in one request.
+
+All non-enrollment endpoints require an Ed25519 device signature over
+`vaultline-request:v1\n<METHOD>\n<path>\n<timestamp>\n<nonce>\n<sha256(body)>`, presented in
+`x-vaultline-device`, `-timestamp`, `-nonce`, and `-signature`. Timestamps outside a
+five-minute window are refused, and a nonce cache rejects verbatim replays.
+
+### `POST /v1/accounts` and `POST /v1/devices`
+
+Account creation returns an enrollment token exactly once; only its hash is stored. Device
+enrollment presents that token plus a raw Ed25519 public key. These two endpoints cannot be
+device-signed because they are what establish a device.
+
+### `POST /v1/storage-configs`
+
+Request: `{ provider, bucket, prefix, region?, credentialMode }`. Response: opaque config ID. Never accept secrets in this payload.
+
+### `POST /v1/archives/leases`
+
+Request: `{ storageConfigId, archiveId, ciphertextSha256, bytes, partCount }`. Response: `{ leaseId, objectKey, expiresAt, method, requiredHeaders, parts|resumableInit, status }`. Object key is server-generated; the client cannot choose it.
+
+### `POST /v1/archives/:id/complete`
+
+Request: provider object checksum, byte count, lease ID, manifest hash. Server performs provider HEAD/checksum validation before marking durable.
+
+### `PUT /v1/archives/:id/manifest`
+
+Stores opaque encrypted manifest plus safe operational metadata. Never accepts source transcript content.
+
+### Device endpoints
+
+`GET /v1/devices`, `POST /v1/devices/:id/revoke`. Revocation blocks new leases and never
+deletes an archive; the response reports how many archives were retained. Revocation is not
+retroactive for ciphertext an attacker already holds — the client-side counterpart is
+`sealkeep recipients remove` followed by `sealkeep rewrap`.
+
+### `GET /v1/audit`
+
+Account-scoped audit events: action, outcome, identifiers, and counts. No content.
+
+## 4.1 Local API v1 (loopback)
+
+`sealkeep api` binds `127.0.0.1` only. Every state endpoint requires
+`Authorization: Bearer <token>` compared in constant time; the token is minted once
+into `<data-dir>/local-api-token` at mode `600` and is never logged or returned.
+Non-loopback peers and unexpected `Host` headers are rejected with `forbidden`, so a
+browsed page cannot reach the API by DNS rebinding.
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /health` | Unauthenticated readiness; returns no vault state |
+| `GET /v1/status` | Vault identity, archive counts, queue stats |
+| `GET /v1/agents` | Detected agent installs |
+| `GET /v1/archives` | Archive metadata; wrapped key material is omitted |
+| `GET /v1/queue` | Job list |
+| `POST /v1/queue` | Enqueue `{ sourcePath, agent, event?, sessionId? }` |
+| `GET /v1/retention` | Policy evaluation with every blocker per candidate |
+| `POST /v1/retention/preview` | Read-only reclamation preview |
+| `POST /v1/retention/apply` | Reclaims only when `confirm: true`; dry run otherwise |
+| `POST /v1/upload` | Uploads pending archives (no phrase: the ciphertext already exists) |
+| `GET /v1/doctor` | Environment report |
+| `GET /v1/recipients` | Registered X25519 recipients |
+| `GET /` and static assets | The dashboard shell, served before authentication because it holds no data |
+
+The API deliberately cannot decrypt. No endpoint accepts a recovery phrase, and
+`/v1/recover` answers `403 forbidden` pointing at the local `sealkeep recover`
+command. Bodies are capped at 1 MB, validated with strict schemas, and rejected as
+`invalid_argument`.
+
+## 5. Local MCP contract
+
+MCP tools call local APIs, not provider SDKs directly. `vaultline_create_upload` returns a lease object; it must never receive a cloud secret. Search defaults to metadata. Recover and archive require explicit local authorization/recovery secret.
+
+## 6. Failure behavior
+
+- Offline: retain encrypted job and retry with exponential backoff.
+- Expired lease: request a new lease; never reuse a bearer URL.
+- Hash mismatch: quarantine object/job, do not reclaim source, surface high-priority error.
+- Hook timeout: hook exits quickly; daemon continues independently.
+- Provider unavailable: local state remains recoverable.
+- Interrupted restore: temporary file is removed or retained as a clearly named partial artifact; destination is never half-overwritten.
+
+## 7. Current boundary
+
+Implemented and tested end to end: capture (hooks, watcher, durable queue), encryption
+(format v2 with vectors and a tamper suite), provider clients (SigV4 verified against AWS's
+published example; multipart, GCS resumable, and the plain object verbs exercised against
+in-process emulators), verified upload, the chunk-folder remote layout with hashed naming
+and sealed identity, retention with trash staging, restore including native adapter paths
+and rehydrate-on-resume, the sealed index sync, the loopback API behind the dashboard and
+TUI, the MCP server and its installer, the control plane with device auth and audit,
+search, and the local audit log.
+
+Four gates remain open, none closable by writing more code in this repository:
+
+1. **Independent cryptographic audit.** Required before any end-to-end-encryption claim.
+2. **A live cloud drill for the bring-your-own providers.** GCS carries production
+   traffic through the managed tier; S3, R2, and Drive have not yet been driven
+   against a real account.
+3. **OS code-signing certificates.** Releases carry npm provenance and an Ed25519-signed manifest only.
+4. **Browser and accessibility QA** of the dashboard.
+
+Uploads remain off unless `VAULTLINE_ENABLE_SIGNER=1` is set explicitly.

package/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+Notable changes, by published version. Sealkeep is pre-1.0: minor versions
+may change behavior, and say so here when they do.
+
+## 0.5.0 — 2026-08-18
+
+**Vaultline is now Sealkeep** (by SPALA AI) — the old name is used by several
+unrelated companies, and this one says what the product does: seal it, keep it.
+
+Nothing breaks:
+- the `vaultline` command still works (aliased to `sealkeep`)
+- existing `~/.vaultline` vaults keep working forever; new vaults use `~/.sealkeep`
+- `VAULTLINE_*` environment variables are unchanged
+- every file format, keystore entry, and cloud object stays exactly as it was
+
+Install as `npm install -g sealkeep`; the `vaultline` npm package is deprecated
+and points here.
+
+## 0.4.0 — 2026-08-18
+
+Several storages, one vault — proven live against a real Google Drive.
+
+- **Storage targets**: keep the managed cloud AND your own Drive (or bucket)
+  connected at once, with rules — a byte cap per target ("Drive holds at
+  most 50 GB"), projects pinned to a target, priority ordering in which the
+  managed cloud wins by default. `sealkeep storage targets [add|remove]`,
+  `archive --target <id>`. Reads never consult the rules: every archive's
+  record routes its own restore.
+- **The rules live on your account.** Every machine of the vault syncs the
+  same routing rules down (and caches them for offline), so a cap set on
+  one laptop holds on the next.
+- **Connecting Drive is one click.** Consent runs on the account's shared
+  Google client through a remote callback: the browser approves, the server
+  exchanges the code with its own secret, and the machine claims its tokens
+  once — nothing Google-related ships in this package, and the flow works
+  even for headless machines whose browser lives elsewhere. `drive.file`
+  scope only: Sealkeep sees nothing in a Drive but its own sealed files.
+- **Drive reads back.** Offload's stale gate thought Drive was write-only;
+  the live drill sealed a 58.8 MB session to a real Drive, freed the local
+  copy only after downloading and hash-proving the Drive copy, and restored
+  it byte-identical from cold.
+
+## 0.3.5 — 2026-08-18
+
+Proven on two live machines sharing one storage: knowledge really is
+collective now.
+
+- **A second machine sees everything.** A hit whose archive this machine
+  never made is reconstructed from the cloud alone — the envelope sidecar
+  opens with the phrase, the sealed identity restores agent and path, and
+  snippets fetch like any cold archive. A fresh vault signed into the
+  account searched a 1.67 GB session it had no record of, with snippets,
+  in 12 seconds; the first machine found the second machine's session in
+  under 5.
+- **Snippet fetches are bounded and parallel**: one small window per tagged
+  chunk instead of a single window spanning between tags (two far tags used
+  to fetch 349 chunks of a cold archive). Multi-term search dropped from
+  153 s to 5.5 s; single-term from 60 s to 5.7 s.
+- **Compounds index by their segments** — "chunk-store.ts" answers for
+  "store", and an over-long hyphenated identifier is findable through every
+  piece of itself; query terms the index could never hold are not required.
+
+## 0.3.4 — 2026-08-18
+
+Search quality, earned the hard way: a real 1.67 GB session was archived,
+searched, and every miss chased to its cause.
+
+- **The token budget scales with the archive** (72 tokens/MB, capped at
+  120k). A flat 4000 starved everything past the first chunks of a big seal
+  — "retention" was findable, "chunk" (141 honest mentions) was not.
+- **Every chunk gets a fair seat**: per-chunk vocabularies merge round-robin
+  instead of first-chunks-win, so a word living only in chunk 350 is as
+  findable as one from chunk 0.
+- **Junk never takes a slot**: hex digests, base64 runs, and over-long
+  identifiers are filtered before they can crowd out words.
+- **Prefix search**: "chunk" also finds "chunks" and "chunkbytes".
+- **Fixed prototype pollution via transcripts**: a session containing the
+  word "constructor" crashed indexing — token maps are own-property-safe
+  everywhere now.
+- **The index actually syncs**: the managed index slot refused every blob
+  PUT (the signed x-goog-if-generation-match header was never forwarded, and
+  the slot was signed create-only). The plane now returns the signer's own
+  headers and signs with overwrite — pushes verified live, twice.
+- `archive --stream --json` reports `indexed`.
+
+## 0.3.3 — 2026-08-18
+
+- **You can always see what search covers.** `sealkeep index status` (and a
+  `search-index` doctor check) reports how many archives are searchable,
+  names the ones that are not yet indexed, and needs no phrase to answer —
+  coverage lives in an unsealed sidecar of archive ids only, while every
+  token stays sealed. New seals index themselves; `index build` adds the
+  rest whenever you choose.
+
+## 0.3.2 — 2026-08-18
+
+Found by running the real loop — archive a quarter-gigabyte production
+session, index it, search it, restore it — and fixing what it hit.
+
+- **Sessions are searchable the moment they seal.** The seal already holds
+  every plaintext slice, so tokens are collected during sealing and merged
+  into the content index (and synced to the vault's slot) as the seal
+  returns. The old way uploaded an archive and then downloaded it back just
+  to read it.
+- **Chunks upload four at a time.** The seal loop stays sequential; the wire
+  no longer is. A 282 MB session that took 5 minutes uploads in a fraction.
+- **`index build` survives the real world**: offloaded archives are fetched
+  from the cloud instead of ENOENT-ing on the reclaimed local blob; archives
+  past Node's ~512 MB string ceiling are scanned in windows; a version-1
+  index merges instead of crashing (unusable entries re-index once); one
+  flaky download skips one archive with a report instead of killing the
+  build; token collection is capped so hex-noise transcripts cannot balloon
+  memory.
+
+## 0.3.1 — 2026-08-18
+
+- **Fixed: a real managed vault could not stream.** Enrolled vaults carry a
+  cloud token and no `remoteStorage` entry; 0.3.0's chunk paths (and index
+  sync) gated on the entry alone, so streaming answered "no remote target
+  configured" on exactly the vaults the feature was for. Managed-ness now
+  follows the same rule everywhere: an own bucket wins when configured,
+  otherwise the signed-in account is the target. Found by a live drill on a
+  production vault; covered by a token-only regression test.
+
+## 0.3.0 — 2026-08-18
+
+The chunk-folder layout is now the whole product's answer, not a CLI flag.
+
+- **Managed vaults stream into chunk folders** — no new control-plane
+  capability: the client already chunks, so each sealed chunk is delivered as
+  an ordinary file through the ordinary upload lease (`<archiveId>.chunk-NNNNNN`
+  plus an `<archiveId>.envelope.vlmeta` sidecar). Resume probes storage, not
+  metering rows; restore, search, check-copy, listings, and delete all treat
+  the family as one archive.
+- **The background worker streams under pressure.** A transcript the disk
+  cannot hold a sealed copy of no longer waits in the queue for a reclaim:
+  the worker seals it straight into a chunk folder — peak local cost is one
+  chunk — and the archive is born offloaded and verified. The ordinary path
+  (local seal, delta chains, offline archiving) is untouched.
+- **Google Drive is single-object by design.** Chunk folders need an object
+  store; Drive archives keep the whole-object path and say so.
+- **Fixed: restoring a chunk-folder archive refused good bytes.** 0.2.0
+  recorded a double-hashed whole-ciphertext digest for `--stream` chunk-folder
+  seals (own-bucket only), so sealing verified but every restore failed its
+  integrity check. Records sealed with 0.2.0's `--stream` carry the bad
+  digest and need a fresh seal; per-chunk hashes were always correct.
+
+## 0.2.0 — 2026-08-18
+
+Everything since the first publish. Version 0.1.1 was packed for internal
+smoke tests and never reached the registry; its work is listed here.
+
+### The vault runs itself
+- `sealkeep autopilot`: one command installs the login service that catches,
+  seals, uploads, verifies, and reclaims on a loop, with a heartbeat that
+  `status`, the dashboard, and the local API all read.
+- Sessions seal in parallel behind a disk-space reservation; repeat archives
+  of a growing session are deltas, not re-archives.
+- Retention finishes the job: archives the bucket verifiably holds can be
+  offloaded locally, and the disk reserve scales with the disk.
+
+### What the bucket sees became a design surface
+- Remote layout v2: one archive is one folder of sealed chunks plus a small
+  envelope. Uploads are plain known-length PUTs, resume is deterministic,
+  delete is the folder.
+- Path segments (project, date, session) are hashed under a storage-scoped
+  key by default; a sealed sidecar carries the readable identity, so the
+  phrase rebuilds the friendly view and the provider gets noise.
+  `remoteNaming: "readable"` opts out.
+- `sealkeep archive --stream` seals straight to the bucket — the ciphertext
+  never touches the disk — resumable mid-object, with journaling ordered so
+  an encryption nonce is never reused across a crash.
+
+### Search that travels
+- The content index is sealed with the archive machinery and synced beside
+  the data (own bucket or the managed tier), so every machine of the vault
+  searches the whole history without rebuilding it.
+- Index builds are incremental and merging; `search --content` answers with
+  ranged chunk fetches, not bulk restores.
+
+### Agents are first-class users
+- `sealkeep mcp` is a local MCP server (status, search, archive, recover,
+  upload leases, retention preview); `sealkeep mcp install` registers it
+  with Claude Code and Codex, with a byte-identical backup of any file it
+  touches.
+- Rehydrate-on-resume: a `SessionStart` hook restores an archived transcript
+  to its exact path before the agent reads it. Resuming a session Sealkeep
+  reclaimed is no longer a failure mode — and the hook can never break a
+  session start.
+- `sealkeep recover <filename>` accepts the filename from an agent's error
+  message; `sealkeep doctor` warns when a resumable session's file is gone
+  and names the command that puts it back.
+
+### Keys, phrases, sharing
+- Phrase rotation and password change re-key every archive by re-wrapping —
+  nothing is re-encrypted.
+- `sealkeep share <id>` seals one archive into a `.vlshare` bundle under a
+  one-time passcode; the vault phrase deliberately does not open it.
+- Escrow blobs can carry more than one way in.
+
+### Storage and accounts
+- Google Drive joins S3, R2, GCS, and S3-compatibles as a first-class home.
+- Managed tier: accounts, device auth, quotas, upload leases, and returning
+  machines joining an account — with the control plane never receiving
+  content, keys, or the phrase.
+- A secrets leak-scan runs before anything leaves the machine.
+
+### The panel is one product
+- One SPA: sessions, retention rules, memory pool, and the vault merged into
+  a single navigable dashboard; every archive's verbs live on its row; bulk
+  actions state what they will remove before they act.
+
+## 0.1.0 — 2026-08-16
+
+First publish: encrypted session vault core — capture hooks, durable queue,
+envelope format v2 (vectors and tamper suite), verified upload, trash-staged
+retention, byte-identical restore.

package/CONTROL_PLANE.md

@@ -0,0 +1,86 @@
+# Sealkeep control-plane contract
+
+The control plane stores device identities, encrypted manifests, and provider configuration. It never accepts transcript plaintext.
+
+## Running it
+
+```sh
+npm run control-plane                       # authenticated, durable
+VAULTLINE_CONTROL_PLANE_DEV=1 npm run control-plane   # unauthenticated, in memory
+docker build -t vaultline-control-plane . && docker run -p 8787:8787 -v vaultline-data:/data vaultline-control-plane
+```
+
+Endpoints:
+
+- `GET /health` — reports `mode: control-plane` or `development-interface`
+- `POST /v1/accounts` — returns an enrollment token once; only its hash is stored
+- `POST /v1/devices` — enrols an Ed25519 device key using that token
+- `GET /v1/devices`, `POST /v1/devices/:id/revoke`
+- `POST /v1/storage-configs`, `GET /v1/storage-configs/:id`
+- `POST /v1/archives/leases`, `POST /v1/archives/:id/complete`
+- `PUT /v1/archives/:id/manifest`, `GET /v1/archives`
+- `GET /v1/audit`
+
+## Authentication
+
+Every endpoint except account creation and device enrollment requires an Ed25519 signature
+over:
+
+```text
+vaultline-request:v1\n<METHOD>\n<path>\n<timestamp>\n<nonce>\n<sha256(body)>
+```
+
+presented in `x-vaultline-device`, `x-vaultline-timestamp`, `x-vaultline-nonce`, and
+`x-vaultline-signature`. A timestamp more than five minutes from the server's clock is
+refused, and a nonce cache rejects verbatim replays. Binding method, path, and body hash
+into the signature means a captured signature cannot be redirected to another endpoint.
+
+`VAULTLINE_CONTROL_PLANE_DEV=1` disables this and keeps state in memory. It exists for
+local interface development. If `/health` reports `development-interface` on anything you
+deployed, stop it.
+
+## Provider configuration
+
+```json
+{
+  "provider": "s3 | r2 | gcs | vaultline",
+  "bucket": "vaultline-archives",
+  "region": "us-east-1",
+  "prefix": "v1/accounts/<account-id>",
+  "credentialMode": "server-managed | byo-role | byo-service-account"
+}
+```
+
+Provider credentials live only in the control plane's secret manager. BYO S3/R2 configurations use a prefix-restricted role/token; GCS uses a service account restricted to the archive prefix.
+
+## Lease endpoint
+
+`POST /v1/archives/leases`
+
+Input is ciphertext-only metadata: archive ID, encrypted byte length, SHA-256 of ciphertext, and desired part count. The response includes a short-lived, single-object upload lease. Leases are bearer capabilities; default expiry is 15 minutes and every issued lease is audit logged.
+
+Every lease carries `status` and `uploadable`. In this build they are always `pending-signer` and `false`. `assertLeaseUsable` is the single gate an upload path must pass: it checks expiry first, so a replayed lease is refused as `lease_expired` rather than as an unsigned one, and it then refuses anything that is not an `active` uploadable lease with `signer_not_configured`.
+
+`VAULTLINE_ENABLE_SIGNER=1` permits registering a `ProviderUploadClient`, but no implementation ships. With the flag off, registration and lookup both fail; turning it off again immediately withdraws every registered client.
+
+For S3/R2 the response contains `createMultipart`, per-part presigned PUT URLs, and a completion endpoint. For GCS it contains a signed initiation URL plus the resumable session URI returned to the local agent. The client validates the remote checksum and then calls `POST /v1/archives/complete`.
+
+## Manifest endpoint
+
+`PUT /v1/archives/:id/manifest` stores an opaque encrypted manifest. It may contain encrypted source path, agent adapter version, chunk object keys, and wrapped archive keys. The server only indexes account, device, timestamps, byte counts, and object status unless private-metadata mode is disabled.
+
+## Required security checks
+
+- The lease object key is allocated by the server, never accepted from the client. *(Implemented: the key is derived from the account's configured prefix and the archive id.)*
+- Content length, checksum, content type, and upload method are signed/restricted. *(Implemented client-side: the SHA-256 header is signed, which pins the bytes. `content-length` is a forbidden header for `fetch` and cannot be sent verbatim, so it is not signed.)*
+- Completion verifies the reported byte count against the lease before marking an archive durable, and the client independently verifies the provider's checksum before writing `remote.verifiedAt`. *(A server-side provider HEAD is still to do; it needs the signer service.)*
+- Device revocation prevents new leases but does not destroy user archives. *(Implemented and tested.)*
+- Leases are single use: completing one marks it consumed, and a replay is refused with `lease_replayed`. *(Implemented and tested.)*
+- Quotas are checked before a lease is issued. *(Implemented and tested.)*
+- Archive deletion has no endpoint. Removing an account is a deliberate manual operation; see `docs/RUNBOOK.md` §8.
+
+## Storage limits
+
+State is one JSON document rewritten atomically per mutation — appropriate for a
+team-sized deployment, not a large multi-tenant service. Replace `ControlPlaneStore` with a
+database before that point; nothing above it depends on the file layout.

package/LICENSE

@@ -0,0 +1,34 @@
+Vaultline Software License
+
+Copyright (c) Spala.
+All rights reserved.
+
+Permission is granted to install, copy, and run this package to archive,
+encrypt, verify, and restore your own coding-agent session data, on machines
+you own or control, including for commercial purposes. No fee is charged for
+use with storage you provide yourself. Use of the managed storage service
+operated by Spala is charged separately and is governed by the managed-service
+terms in force at the time of purchase.
+
+You may not sell, relicense, redistribute this package as a standalone or
+competing product, or use it to provide an archiving service to third parties
+without prior written permission from Spala.
+
+Your data is encrypted on your machine before it is written or transmitted.
+Spala does not receive, and cannot decrypt, the contents of your archives —
+including archives stored in the managed service. You are solely responsible
+for the recovery phrase this software generates: Spala cannot recover it,
+cannot reset it, and cannot decrypt your archives without it. Losing the
+recovery phrase means losing access to your archives permanently. This is a
+deliberate property of the design, not a defect.
+
+This package includes third-party open-source components, each governed by its
+own licence; see THIRD_PARTY.md.
+
+This package is provided "as is", without warranty of any kind, express or
+implied, including but not limited to warranties of merchantability, fitness
+for a particular purpose, and noninfringement. Spala is not liable for any
+claim, damages, or other liability — including loss of data — arising from use
+of this package, except liability that cannot lawfully be excluded.
+
+Questions: paul@spala.ai