Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 62 additions & 17 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,8 @@ also runs as a native host process. The web Terminal is disabled by default;
host developer mode and closed guest registration are required to enable it.
An enabled Terminal runs commands with the host user's rights.

The seed operator can read hosted data, wallet keys and recovery material.
Passkeys control sign-in; stored data and keys remain accessible to the Runtime
account and root while Home is locked. Protection against hosted operators and
root, and against other software or OS users while a self-hosted Home is locked,
is the target of [hosted protection](https://github.com/elastos/elastos-runtime/issues/209)
and [locked Home protection](https://github.com/elastos/elastos-runtime/issues/210).
An unlocked self-hosted Home trusts its owner and their host software. Recovery
from a stolen device or profile key requires a new identity.
Stored data has a separate boundary. [Stored keys and recovery](#stored-keys-and-recovery)
explains host access while Home is locked and what the Recovery Kit contains.

The [isolation plan](https://github.com/elastos/elastos-runtime/issues/173)
records the remaining gates. Source checks describe this source tree. Accepted
Expand Down Expand Up @@ -73,12 +67,63 @@ is a trusted display that binds what the person sees to the approved effect.

## Stored keys and recovery

Keys are stored next to the data they protect. Full data-home backups include
all keys. Protect those backups and your Recovery Kit as secrets. Encryption
with keys stored on the same host leaves those secrets accessible to its
operator. Use hosted accounts only for public demos; keep wallets, private data
and recovery material on your own device until hosted protection passes its
acceptance gate. Independent review and installed proof remain security gates.
Disk storage checked on 19 November 2026. Paths below are relative to the Home
data folder; `<person>` is that person's folder name. The table describes
application encryption; file names and filesystem metadata stay readable.

Runtime creates a person's data key during Profile setup or, if the key is missing,
during Recovery Kit export. The person's recovery phrase protects that key.
Runtime keeps an internal recovery record, including the
phrase, encrypted in `ElastOS/System/Auth/auth-state.json`; the unencrypted
archive key is in `recovery-archive.key` beside it. Before that protection exists,
Assistant, direct messages, and People refuse saves. Documents, Library, and
Home settings can instead write plain data.

System's **Download Recovery Kit** saves one recovery file, with optional password
protection. Its coverage is listed below. Keys are stored next to the data they
protect, in the same Home data folder; the person's data key is in the Auth archive above.

| Data and storage path | Encrypted on disk? | Key location | Recovery Kit restores |
|---|---|---|---|
| Home recovery authority: `ElastOS/System/Auth/auth-state.json` | Recovery material only; other auth state is plain | `recovery-archive.key` in the same Auth folder | Home recovery authority and data key (not passkeys or sessions) |
| Assistant conversations and drafts: `Users/<person>/.AppData/ElastOS/Assistant/workspace-v2.json` | Yes; answers also appear in model run records | Person's data key | Data key; files separate |
| Direct messages: `Users/<person>/.AppData/ElastOS/Chat/direct-messages.json` | Yes | Person's data key | Data key; files separate |
| Community history: `collaboration/default-conversation/history-v1.json` | No | None | Omitted |
| Contacts and Profile: `Users/<person>/.AppData/ElastOS/People`, `Users/<person>/.AppData/ElastOS/Profile` | Yes | Person's data key; Profile signing key inside the protected file | Profile identity and contacts present at export |
| Documents: `Users/<person>/Documents`; titles and file names in `ElastOS/Documents/<document>/document.json`; published bytes in `ipfs-repo` | Bodies when protection exists; metadata and published bytes are plain | Person's data key for bodies | Data key; files separate |
| Library files and records under `Users/<person>`; publication index under `ElastOS/SystemServices/Library`; published bytes in `ipfs-repo` | Private files/records when protection exists; published bytes and shared index are plain | Person's data key for private files/records | Data key; files separate |
| Notifications: `Local/Shared/System/Notifications` | No | None | Omitted |
| Built-in Wallet: `ElastOS/SystemServices/Wallet/wallet-state.json` | Signing keys only; account and approval records are plain | Derived from nearby `wallet-key.hex` and the person's account ID | Built-in Wallet keys present at export |
| Browser profile: `Users/<person>/BrowserProfiles/default/profile.ext4` | No | None | Omitted |
| Model run records: `providers/model-provider/journal` | No; retains answers, events, and a hash of the input under its retention policy | None | Omitted |
| Model provider credentials: `providers/model-provider/secrets` | No; files restricted to the host account | None | Omitted |
| Home settings: `Users/<person>/.AppData/ElastOS/Home` | When protection exists; browser preferences are separate | Person's data key | Data key; files separate |

Community history, notifications, document metadata, and the Wallet file are
shared Home files, outside each person's private folder.

The Runtime account, software running as that host account, root, and the
hosting operator can read stored data, Wallet keys, and recovery material at any
time, including while Home is locked.
Passkeys control sign-in. An unlocked self-hosted Home trusts its owner and
their host software. Protection against
hosted operators and root belongs to [hosted protection (#209)](https://github.com/elastos/elastos-runtime/issues/209);
protection against other software or OS users while a self-hosted Home is locked
belongs to [locked Home protection (#210)](https://github.com/elastos/elastos-runtime/issues/210).
Recovery from a stolen device or Profile key requires a new identity.

A complete data-folder copy contains the keys needed to read the protected data.
Protect that backup and your Recovery Kit as secrets. Use hosted accounts only for public
demos; keep wallets, private data, and recovery material on your own device until
hosted protection passes its acceptance gate. Independent review and installed
proof remain security gates.

The Recovery Kit is not a whole-Home backup. Keep separate backups as listed in
the table before the disk is lost. [Backup and recovery (#567)](https://github.com/elastos/elastos-runtime/issues/567),
[file backup (#603)](https://github.com/elastos/elastos-runtime/issues/603),
and [replicas on your own devices (#498)](https://github.com/elastos/elastos-runtime/issues/498)
own that work. The [target storage model](docs/STORAGE_AND_ACCESS.md) explains
working copies, revisions, heads, keys, and replicas.

## Open Findings

Expand Down Expand Up @@ -123,9 +168,9 @@ Over HTTP, an ordinary Home's raw CID routes (`/content/<cid>`, `/ipfs/<cid>`,
CID gateway.
Only a node that serves publisher content (a seed) answers the raw
`content_fetch` byte operation or serves without these checks. In this
release a seed accepts no new copies from other Homes; copies it already holds
stay. A Home accepts a new copy from a peer only if the owner gave that peer
the `content.replica` permission; copies it already holds stay. The owner
release a seed accepts no new replicas from other Homes; replicas it already holds
stay. A Home accepts a new replica from a peer only if the owner gave that peer
the `content.replica` permission; replicas it already holds stay. The owner
trusts such a peer like an own device: it can ask the Home to pin content,
import complete content and read storage status. An import pins only the CID
it was asked for and never removes an existing pin. No peer can publish,
Expand Down
65 changes: 28 additions & 37 deletions docs/GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,32 +12,10 @@ Key terms used in the ElastOS codebase and documentation.

## Current isolation and target boundary

First-party apps run as web projections in the browser's opaque sandboxed
frames. Runtime checks each app's signed launch token and actor before it performs an effect.
Home can currently obtain every app's capability, so a compromised Home can
reach those apps' authority. The target limits Home to delegation and gives each
app a separate, revocable capability. The WASM Component authoring path runs in
Wasmtime with memory and fuel limits and Runtime Bus hostcalls.

Providers run as native operating-system processes with the Runtime user's
rights. Only the model provider is partly confined. The trusted shell helper
also runs as a native host process. The web Terminal is disabled by default;
host developer mode and closed guest registration are required to enable it.
An enabled Terminal runs commands with the host user's rights.

The seed operator can read hosted data, wallet keys and recovery material.
Passkeys control sign-in; stored data and keys remain accessible to the Runtime
account and root while Home is locked. Protection against hosted operators and
root, and against other software or OS users while a self-hosted Home is locked,
is the target of [hosted protection](https://github.com/elastos/elastos-runtime/issues/209)
and [locked Home protection](https://github.com/elastos/elastos-runtime/issues/210).
An unlocked self-hosted Home trusts its owner and their host software. Recovery
from a stolen device or profile key requires a new identity.

The [isolation plan](https://github.com/elastos/elastos-runtime/issues/173)
records the remaining gates. Source checks describe this source tree. Accepted
installed proof binds the exact Runtime, components and app assets to the
journeys tested on that device.
[Security](../SECURITY.md#current-isolation-and-target-boundary) owns the current
app, provider, Home, and host boundaries and their limitations. Its
[storage table](../SECURITY.md#stored-keys-and-recovery) describes disk encryption,
key custody, and recovery coverage.

## ElastOS Four Quadrants

Expand Down Expand Up @@ -71,13 +49,20 @@ The default human proof for Home. A passkey proves control of a local account to
the runtime and unlocks short-lived sessions. It is not a wallet, not a DID, and
normally does not expose raw key material for encryption.

## Recovery Kit

The recovery file saved by System's **Download Recovery Kit**. Keep it private,
with its optional password. The [storage table](../SECURITY.md#stored-keys-and-recovery)
defines its contents and the data that needs separate backups.

## Profile DID

The stable person/contact identity used by signed People, discovery, accepted
contacts, and direct-conversation identity. A Profile DID belongs to a
principal-owned signed Profile document and can remain stable across device
replacement or revocation when a valid Recovery Kit restores it. A stolen
profile key requires a new identity. It is not the passkey and not the local principal
replacement or revocation; see the
[recovery coverage](../SECURITY.md#stored-keys-and-recovery). A stolen profile key
requires a new identity. It is not the passkey and not the local principal
identifier. It represents the person in collaboration, but the signed Profile
document is not the human actor or the delivery device.

Expand Down Expand Up @@ -317,15 +302,21 @@ access-control system.

## CID (Content ID)

A content-addressed identifier (hash of the content). Used for capsule identity, IPFS references, and the `elastos://` namespace. The identity is the content, not the location.

CID is not an availability guarantee. A CID says what bytes or graph root are
being referenced; availability receipts say which provider accepted or verified
responsibility to keep that content reachable.

A CID is also not a person, device, account, or global name claim. A stable
object may later have a signed head or object DID that points to changing CID
revisions, but each CID already identifies one immutable byte graph.
A content fingerprint that names fixed bytes or a fixed graph of content, such
as a saved revision or published package. A CID names content rather than its
location; a changing working copy needs a new revision before it can have a CID.
Availability receipts separately state which provider accepted or verified a
responsibility to keep those bytes reachable. A CID grants no permission and
makes no person, device, account, or global name claim.

## Working copy, revision, head, key, replica

In the [target storage model](STORAGE_AND_ACCESS.md#two-kinds-of-data), a working
copy is a file or database for frequent writes. A revision is a fixed save named
by its CID. A head is the signed pointer that selects the current revision,
also called a signed mutable head. A key encrypts private data and lets an
authorised reader open it. A replica is a revision kept elsewhere under the owner's
storage policy.

## Service Offer

Expand Down
13 changes: 8 additions & 5 deletions docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -528,14 +528,17 @@ curl -fsSL https://elastos.elacitylabs.com/install.sh | bash -s -- --uninstall -
```

This deletes your identity, wallets and recovery material on this computer.
Keep your Recovery Kit first: it is the only way to restore that identity.
Keep your Recovery Kit and separate data backups first; check the
[storage table](../SECURITY.md#stored-keys-and-recovery) for coverage.

## Data, keys and backups

Runtime stores keys next to the data they protect in its data home. A full
backup of that home contains all keys, including wallet keys. Protect the backup
with the same care as the running Home. A Recovery Kit is sensitive recovery
material; keep it under your own control.
with the same care as the running Home. System's **Download Recovery Kit** saves
one recovery file. Keep it under your own control, with its optional password.
The [storage table](../SECURITY.md#stored-keys-and-recovery) lists its contents
and the data that needs separate backups.

Use hosted accounts only for public demos. Keep wallets, private data and
recovery material on your own device until
Expand All @@ -550,8 +553,8 @@ operators and root, and other software or OS users while a self-hosted Home is
locked. An unlocked self-hosted Home trusts its owner and their host software.
A stolen device or profile key requires a new identity.

Lost every passkey? Your Recovery Kit brings your account back on the same
Home, even when guest accounts are off:
If you lose every passkey, use your Recovery Kit on the same Home, even when guest
accounts are off:

1. On the computer that runs Home, as the user who installed it, run
the command shown on the sign-in screen, for example
Expand Down
Loading
Loading