From f57c76f0fc7152c792a659215fb08a8bb630967b Mon Sep 17 00:00:00 2001 From: Anders Alm Date: Thu, 19 Nov 2026 12:47:39 -0500 Subject: [PATCH 1/4] docs: explain storage model and current disk protection Built-by: Codex --- SECURITY.md | 73 ++++++++-- docs/GLOSSARY.md | 54 +++---- docs/INSTALL.md | 8 +- docs/STORAGE_AND_ACCESS.md | 189 +++++++++++++------------ scripts/storage-documentation.test.mjs | 75 ++++++++++ 5 files changed, 255 insertions(+), 144 deletions(-) create mode 100644 scripts/storage-documentation.test.mjs diff --git a/SECURITY.md b/SECURITY.md index 87a1e858e..5f3f5f568 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -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 each recovery export contains. The [isolation plan](https://github.com/elastos/elastos-runtime/issues/173) records the remaining gates. Source checks describe this source tree. Accepted @@ -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; `` 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 and retains a Recovery Kit during Profile +setup. The Kit's recovery phrase protects that key. Runtime keeps the Kit, +including that 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. + +In the last column, **key only** means the export restores the data key; you +still need a separate copy of the files. The full bundle includes a Recovery Kit, +plus the built-in Wallet keys and People identity/contacts present at export. + +| Data and storage path | Encrypted on disk? | Key location | Recovery Kit / full bundle | +|---|---|---|---| +| Assistant conversations and drafts: `Users//.AppData/ElastOS/Assistant/workspace-v2.json` | Yes; answer copies also appear in model run records | Person's data key, archived above | Key only / key only | +| Direct messages: `Users//.AppData/ElastOS/Chat/direct-messages.json` | Yes | Person's data key | Key only / key only | +| Community history: `collaboration/default-conversation/history-v1.json` | No | None | Omitted / omitted | +| Contacts and Profile: `Users//.AppData/ElastOS/People`, `Users//.AppData/ElastOS/Profile` | Yes | Person's data key; Profile signing key inside the protected file | Key only / identity and contacts | +| Documents: `Users//Documents`; titles and file names in `ElastOS/Documents//document.json`; published copies in `ipfs-repo` | Bodies when protection exists; metadata and published bytes are plain | Person's data key for bodies | Key only / key only | +| Library files and records under `Users/`; 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 | Key only / key only | +| Notifications: `Local/Shared/System/Notifications` | No | None | Omitted / 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 | Omitted / built-in Wallet keys | +| Browser profile: `Users//BrowserProfiles/default/profile.ext4` | No | None | Omitted / omitted | +| Model run records: `providers/model-provider/journal` | No; retains answers, events, and a hash of the input under its retention policy | None | Omitted / omitted | +| Model provider credentials: `providers/model-provider/secrets` | No; files restricted to the host account | None | Omitted / omitted | +| Home settings: `Users//.AppData/ElastOS/Home` | When protection exists; browser preferences are separate | Person's data key | Key only / key only | + +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 and keys 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, your Recovery Kit, and your full bundle as secrets. The full +bundle offers optional password protection. 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. + +If the disk is lost, a Kit alone cannot restore files or histories. A full bundle +also restores its included Wallet keys and People identity/contacts; it leaves +out the other bytes listed above, including the Browser profile and model +credentials. Keep separate backups of those bytes. Neither export is a whole-Home +backup. [Backup and recovery (#567)](https://github.com/elastos/elastos-runtime/issues/567) +and [copies 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 copies. ## Open Findings diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index c9b33cc39..a44899918 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -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 @@ -317,15 +295,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, copy + +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 copy is a revision kept elsewhere under the owner's +storage policy. ## Service Offer diff --git a/docs/INSTALL.md b/docs/INSTALL.md index da4fd10c8..20c35eb7b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -528,14 +528,18 @@ 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 full recovery bundle first for built-in Wallet keys and People +identity/contacts. A Recovery Kit alone restores the data key. ## 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. +material; keep it under your own control. A Kit restores a data key; the full +bundle adds built-in Wallet keys and People identity/contacts. Both leave ordinary +files and histories for a separate backup. See the dated +[storage table](../SECURITY.md#stored-keys-and-recovery) for exact coverage. Use hosted accounts only for public demos. Keep wallets, private data and recovery material on your own device until diff --git a/docs/STORAGE_AND_ACCESS.md b/docs/STORAGE_AND_ACCESS.md index 95f5b3746..a65143f79 100644 --- a/docs/STORAGE_AND_ACCESS.md +++ b/docs/STORAGE_AND_ACCESS.md @@ -2,24 +2,33 @@ Status: target architecture and product contract. This document records the storage direction. Product support requires implementation and acceptance. -Current verified behavior and open work belong in -[GitHub issues](https://github.com/elastos/elastos-runtime/issues). The -[implementation guide](OBJECT_PROTECTION_IMPLEMENTATION.md) defines the staged -provider boundary and acceptance tests. - -## The product people should experience - -ElastOS gives people familiar files and folders whose ownership and permissions -continue to work across devices, apps, groups, and services. A person can save a -document, share it, remove access, and recover it after losing a device. The -system handles encryption, location, and delivery. +For what is stored and protected today, read +[Security: stored keys and recovery](../SECURITY.md#stored-keys-and-recovery). +The gaps belong to [backup and recovery (#567)](https://github.com/elastos/elastos-runtime/issues/567), +[key custody (#210)](https://github.com/elastos/elastos-runtime/issues/210), +[host protection (#209)](https://github.com/elastos/elastos-runtime/issues/209), +[copies on your own devices (#498)](https://github.com/elastos/elastos-runtime/issues/498), +and [isolation (#173)](https://github.com/elastos/elastos-runtime/issues/173). + +## Two kinds of data + +Finished things stay fixed: a photo, a saved document revision, or an app package. +Living things keep changing: a conversation, a Browser profile, or a game in progress. +A content fingerprint (CID) names a saved revision or published content, never a +store that is still changing. This target model uses five building blocks: + +| Building block | Meaning | +|---|---| +| Working copy | A file or database where an app makes frequent local writes. | +| Revision | A fixed save of the working copy, named by its CID. | +| Head | A signed pointer that selects the current revision (the signed mutable head). | +| Key | A secret that encrypts private data and lets an authorised reader open it. | +| Copy | A revision kept in another place under the owner's storage policy. | -User-controlled encrypted storage is the default for private objects. The owner -chooses where data is kept, how access is granted, and how recovery works. -Protected sharing grants specific uses; export and redistribution require -separate permission. Open publishing and permanent transfers remain deliberate -owner choices. Users should see ordinary actions such as Open, Share, Manage -access, Export, and Restore. +The owner should choose where data stays and who can use it; Runtime should +handle encryption, permission checks, and delivery. Protected sharing +should grant specific uses, with separate permission for export or redistribution. +Open publishing and permanent transfers should remain deliberate owner choices. ## One object model, four responsibilities @@ -31,33 +40,22 @@ access, Export, and Restore. | Availability | Storage, retrieval, retention, replication, and repair | Content and availability providers under the owner's storage agreement | Runtime owns permission checks, provider selection, lifecycle, and audit. -Providers implement their protocols. Carrier handles Runtime-selected peer -communication. These roles follow [PRINCIPLES.md](../PRINCIPLES.md) and the +Providers implement their protocols; Carrier handles Runtime-selected peer communication. These roles follow [PRINCIPLES.md](../PRINCIPLES.md) and the [content-provider contract](CONTENT_AVAILABILITY.md). -```mermaid -flowchart TD - A[Person, app, or agent] --> B[Runtime: object, action, authority, lifecycle] - B --> C[Protection and permitted-use providers] - B --> D[Content provider: store, fetch, retain, repair] - E[Owner, group, or license authority] --> B - C --> F[Encrypted object and bound access session] - D --> F -``` - A provider that stores encrypted blocks gains storage responsibility, not permission to read them. A valid grant establishes authority, not availability. A content hash verifies bytes, not the latest ownership or permission state. ## What an object contains -An object has a stable identity and immutable revisions. A signed mutable head -selects the current revision. Names and folders resolve that identity; moving -an object between storage providers should preserve its identity and rights. +In this model, an object keeps a stable identity across revisions. Names and +folders resolve that identity. Moving an object between storage providers should +preserve its identity and rights. Moving it into another workspace is an authority change that needs an explicit audience and history decision. -The object model binds its encrypted content, integrity information, protection +The target object model binds its encrypted content, integrity information, protection format, and authority reference. Private metadata includes names, thumbnails, search indexes, and other revealing details. Keep that metadata encrypted or inside an explicitly trusted execution boundary. Public distribution exposes @@ -71,54 +69,59 @@ inside their private boundaries rather than public manifests. ## Shared application state -Browser profiles, game saves, Assistant conversations, Builder work and logs use -the same object ownership, protection, revision, availability and recovery -mechanics. Their mutable state stays separate from executable capsules, model -packages and service offers. Updating a capsule preserves the identity and -permissions of the user's state. - -Each payload keeps its own format and save boundary. Chromium needs a consistent -profile checkpoint; a game supplies save bytes; conversations preserve drafts -and message history; run journals preserve ordered events and durable operation -identities. Reuse existing protected storage, content and authority mechanisms -with narrow payload adapters. A common contract does not require one file layout -or a new storage service. - -A successful save is acknowledged by the selected durable store after it commits -a usable revision. Interrupted writes, exhausted -storage and failed migration preserve the previous committed revision and report -unsaved work. Local commit and confirmed remote retention are separate outcomes. -Copying an actively mounted Browser disk is not a consistent checkpoint. One -Runtime holds writable ownership of a Browser profile; transfer fences that -writer before another begins. Other payloads declare merge or conflict behavior. - -Durable storage placement is separate from execution placement. With a remote -Browser Engine and local storage, the consumer's store retains the canonical -checkpoint and the Engine receives an authorised working copy. Checkpoints -return through the common protected-state and content path. A remote working -copy alone cannot satisfy a local-save claim. Host failure preserves the last -acknowledged checkpoint; pending edits and unresolved writer ownership remain -explicit. Availability peers retain only the objects selected by the owner's -storage and access policy. - -Recovery restores the selected revision and usable keys under fresh authority on -a compatible Runtime. Restored conversations and logs retain operation identity -without replaying inference, tools, payments or approvals. Active authentication -sessions and stale grants are not recovered as authority. A storage replica holds -protected bytes; an execution provider separately needs permission to use -readable state within an accepted execution boundary. - -Logs share storage and protection mechanics while retaining their own semantics. -User history, provider settlement journals and Runtime audit records each have -an explicit owner, integrity rule and bounded retention policy. Secret redaction, -pruned-history reporting and pending replica cleanup are part of that policy. -User-facing log controls confer only the rights granted over those records. - -The release plan's Required SA1-SA6 criteria qualify this contract for each -shipped payload. Reuse common mechanism tests, then prove actual payload saves, -restore and failure handling. Existing game-save checks cover the shipped GBA -surface; this contract adds no separate emulator product. Current implementation -and acceptance limits remain in the owning GitHub issue. +Frequent writes belong in the working copy. In this target contract, each kind +of data defines when to save a fixed revision: + +- A person saves or publishes finished content through its app; an app that + saves automatically declares that boundary. +- The Browser Engine makes a consistent profile save; copying a mounted disk + while it changes cannot produce that save. +- A game supplies its save bytes at its own save boundary. +- A conversation app saves drafts and message history at its declared boundaries. +- A run journal saves ordered events and durable operation identities. + +The selected durable store should acknowledge a save only after it commits a +usable revision. Interrupted writes, full storage, and failed migration should +preserve the previous revision and report unsaved work. Local save and confirmed +remote retention are separate outcomes. + +State should stay separate from executable capsules, model packages, and service +offers, so an update preserves the identity and permissions of the user's state. +Narrow adapters should connect each file layout to the same protection, content, +and authority contracts. + +Storage placement should be separate from execution placement. For a remote +Browser Engine with local storage, the consumer's store should keep the current +revision and give the Engine an authorised working copy. Saves should return +through the common protected-state and content path; a remote working copy alone +cannot satisfy a local-save claim. One Runtime should own the writable profile, +and transfer should stop that writer before another starts. Other payloads +should declare their merge or conflict rules. Host failure should preserve the +last acknowledged revision and report pending edits and unresolved writer ownership. + +Recovery should restore a revision and usable keys under fresh authority on a +compatible Runtime. Restored conversations and logs should keep operation +identity without replaying inference, tools, payments, or approvals. Active +sessions and stale grants should gain no authority from recovery. Storage peers +should keep only the protected revisions selected by the owner's policy; +execution providers should separately need permission to use readable state. + +User history, provider settlement journals, and Runtime audit records should each +have an owner, integrity rule, and bounded retention policy for secret redaction, +removed history, and pending copy cleanup. Log controls should grant only the +permitted rights. Acceptance must meet the release plan's required criteria and +prove each payload's saves, restore, and failure handling. Game-save checks cover the shipped GBA +surface; this contract adds no separate emulator product. + +## Encryption and isolation + +Private data and metadata should use encryption by default, with usable keys +outside the data folder. Encryption protects against a reader who lacks the key; +key custody determines whether the storage host can read it. Isolation should +limit a running app to its permitted data and services through a sandbox or +virtual machine. A virtual machine supplies an execution boundary; stored data +still needs encryption and separate key custody. The [current boundaries](../SECURITY.md#current-isolation-and-target-boundary) and +[stored-key limits](../SECURITY.md#stored-keys-and-recovery) are recorded in Security. ## The everyday object journey @@ -138,18 +141,18 @@ and acceptance limits remain in the owning GitHub issue. Apps, games, models, and media use the same content foundation. Installing or executing an app is a separate permission from storing its signed package. Permission to use a model through an approved inference provider is separate -from permission to export its weights. Marketplace licensing adds rights and -payment evidence to this object journey. +from permission to export its weights. Marketplace licensing should add rights +and payment evidence to this object journey. ## Copying storage and granting a copy are different actions -ElastOS copies encrypted blocks for delivery, caching, backup, and repair under -the storage policy. These copies can retain the object's protection and +Runtime should copy encrypted blocks for delivery, caching, backup, and repair +under the storage policy. These copies can retain the object's protection and authority requirements. An independently usable export, redistribution to a new audience, or release of reusable decryption material is a separate action. -An owner's private files remain under that owner's control. Protected sharing -can grant View or Use while retaining separate rights for Edit, Export, and +In this target, private files should remain under their owner's control. +Protected sharing should grant View or Use while retaining separate rights for Edit, Export, and Manage access. These are product meanings, not a requirement to add a separate public API or capability token type for every button. @@ -184,11 +187,11 @@ recordings. Ordinary export paths still require full permission enforcement. Availability is specific to an operation. Data, keys, a permitted execution provider, and sufficiently current authority may be available locally, through -nearby peers, or through remote services. Runtime hides routing details while -reporting useful states: Ready, Retrieving content, Permission check +nearby peers, or through remote services. Runtime should hide routing details and +report useful states: Ready, Retrieving content, Permission check unavailable, Access removed, or Required protection unavailable. -The owner's own files remain usable when their local content, keys, and +The owner's own files should remain usable when their local content, keys, and authority suffice. A recipient's saved permission proves a grant at a point in time. It cannot reveal a later revocation that has not reached that recipient. Shared access therefore needs a policy for freshness: check authority for each @@ -220,14 +223,14 @@ policy and enter shared history only after current write authority is checked. ## Groups, devices, and recovery -A workspace can belong to a group with an explicit management policy. Its +A group workspace should have an explicit management policy. Its continuity should survive the departure of the person who created it. Joining and leaving affect membership, devices, delegated grants, and future keys. Define whether new members receive old revisions; possession of an old group key must not grant access to future protected revisions after removal. -Each device has revocable credentials and the minimum key material required for -its authorised work. Keep a recovery root separate from routine device use. +Each device should have revocable credentials and only the key material needed +for its authorised work. Keep a recovery root separate from routine device use. Loss of a device is different from compromise of a root or recovery authority: the latter can require wider credential and data-key changes. Identity recovery alone is insufficient when object keys or encrypted data are missing. diff --git a/scripts/storage-documentation.test.mjs b/scripts/storage-documentation.test.mjs new file mode 100644 index 000000000..53d9f01dd --- /dev/null +++ b/scripts/storage-documentation.test.mjs @@ -0,0 +1,75 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import test from "node:test"; + +const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), "utf8"); +const security = read("SECURITY.md"); +const browser = read("elastos/crates/elastos-server/src/api/gateway_browser.rs"); + +test("each Security storage row names path parts present in its storage source", () => { + const server = "elastos/crates/elastos-server/src/"; + const sources = [ + ["Assistant conversations", "api/gateway_assistant_workspace_v2.rs"], + ["Direct messages", "collaboration_direct_messages.rs"], + ["Community history", "collaboration_core.rs"], + ["Contacts and Profile", "collaboration_contact_store.rs", "collaboration_profile_authority.rs"], + ["Documents:", "documents.rs", "../../../../capsules/ipfs-provider/src/main.rs"], + ["Library files", "library.rs", "../../../../capsules/ipfs-provider/src/main.rs"], + ["Notifications:", "notifications.rs"], + ["Built-in Wallet", "../../../../capsules/wallet-provider/src/main.rs"], + ["Browser profile", "api/gateway_browser.rs"], + ["Model run records", "api/model_provider_config.rs"], + ["Model provider credentials", "api/model_provider_config.rs"], + ["Home settings", "api/gateway_home_system.rs"], + ]; + const table = security.split("| Data and storage path |", 2)[1].split("\n\n", 1)[0]; + const rows = table.split("\n").filter((line) => /^\| [A-Z]/.test(line)); + assert.equal(rows.length, sources.length, "cover each storage row"); + for (const [name, ...paths] of sources) { + const row = rows.find((line) => line.startsWith(`| ${name}`)); + assert.ok(row, `find the ${name} row`); + const literals = [...paths, "auth.rs"].flatMap((path) => [...read(server + path).matchAll(/"([^"\n]+)"/g)] + .map((match) => match[1])); + for (const [, path] of row.split("|")[1].matchAll(/`([^`]+)`/g)) { + // Variable person/document parts are explained above the table. + // This checks fixed path parts, not assembly or write-time protection. + for (const part of path.split("/")) { + if (/^<.*>$/.test(part)) continue; + const pattern = new RegExp(`(?:^|/)${part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")}(?:/|$)`); + assert.ok(literals.some((literal) => pattern.test(literal)), `${name}: source names ${part}`); + } + } + } +}); + +// Source contract only: this does not prove installed encryption or recovery. +function checkBrowserRow(document) { + const row = document.split("\n").find((line) => line.startsWith("| Browser profile:")); + assert.ok(row, "Security must describe Browser profile storage"); + const [, data, encrypted, key, recovery] = row.split("|").map((cell) => cell.trim()); + const profilePath = browser.match(/let profile_uri = format!\("\{principal_root\}([^"\n]+)"\)/)?.[1]; + assert.ok(profilePath, "find the Browser profile path in its launch descriptor"); + assert.ok(data.includes(`\`Users/${profilePath}\``), "document the path used by Browser launch"); + for (const flag of ["encrypted", "recoverable"]) { + assert.match(browser, new RegExp(`\\b${flag}: false,`), + `Browser ${flag} changed; review the storage table`); + } + assert.equal(encrypted, "No", "match the Browser encrypted flag"); + assert.equal(key, "None", "the unencrypted Browser disk has no storage key"); + assert.equal(recovery, "Omitted / omitted", "match Browser recovery and bundle exclusion"); + assert.match(read("elastos/crates/elastos-server/src/api/auth_gateway.rs"), + /BrowserProfiles are VM lifecycle artifacts[\s\S]*?Neither is a principal-root protected object/); +} + +test("Security Browser storage row matches the source descriptor", () => checkBrowserRow(security)); + +test("the storage check rejects false Browser path, encryption, and recovery claims", () => { + const row = security.split("\n").find((line) => line.startsWith("| Browser profile:")); + for (const falseRow of [ + row.replace("profile.ext4", "missing.ext4"), + row.replace("| No |", "| Yes |"), + row.replace("Omitted / omitted", "Key only / key only"), + ]) { + assert.throws(() => checkBrowserRow(security.replace(row, falseRow))); + } +}); From 175fc46de05497606029db3f87146971bc78eaca Mon Sep 17 00:00:00 2001 From: Anders Alm Date: Thu, 19 Nov 2026 13:31:21 -0500 Subject: [PATCH 2/4] docs: use one Recovery Kit name and preserve storage limits Built-by: Codex --- SECURITY.md | 54 +++++++++++++------------- docs/GLOSSARY.md | 15 +++++-- docs/INSTALL.md | 17 ++++---- docs/STORAGE_AND_ACCESS.md | 17 ++++---- scripts/storage-documentation.test.mjs | 50 ++++++++++++++++++++++-- 5 files changed, 102 insertions(+), 51 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 5f3f5f568..19a4e5670 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -71,37 +71,39 @@ Disk storage checked on 19 November 2026. Paths below are relative to the Home data folder; `` 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 and retains a Recovery Kit during Profile -setup. The Kit's recovery phrase protects that key. Runtime keeps the Kit, -including that phrase, encrypted in `ElastOS/System/Auth/auth-state.json`; the unencrypted +Runtime creates a person's data key during Profile setup. Its 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. -In the last column, **key only** means the export restores the data key; you -still need a separate copy of the files. The full bundle includes a Recovery Kit, -plus the built-in Wallet keys and People identity/contacts present at export. +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 / full bundle | +| Data and storage path | Encrypted on disk? | Key location | Recovery Kit restores | |---|---|---|---| -| Assistant conversations and drafts: `Users//.AppData/ElastOS/Assistant/workspace-v2.json` | Yes; answer copies also appear in model run records | Person's data key, archived above | Key only / key only | -| Direct messages: `Users//.AppData/ElastOS/Chat/direct-messages.json` | Yes | Person's data key | Key only / key only | -| Community history: `collaboration/default-conversation/history-v1.json` | No | None | Omitted / omitted | -| Contacts and Profile: `Users//.AppData/ElastOS/People`, `Users//.AppData/ElastOS/Profile` | Yes | Person's data key; Profile signing key inside the protected file | Key only / identity and contacts | -| Documents: `Users//Documents`; titles and file names in `ElastOS/Documents//document.json`; published copies in `ipfs-repo` | Bodies when protection exists; metadata and published bytes are plain | Person's data key for bodies | Key only / key only | -| Library files and records under `Users/`; 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 | Key only / key only | -| Notifications: `Local/Shared/System/Notifications` | No | None | Omitted / 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 | Omitted / built-in Wallet keys | -| Browser profile: `Users//BrowserProfiles/default/profile.ext4` | No | None | Omitted / omitted | -| Model run records: `providers/model-provider/journal` | No; retains answers, events, and a hash of the input under its retention policy | None | Omitted / omitted | -| Model provider credentials: `providers/model-provider/secrets` | No; files restricted to the host account | None | Omitted / omitted | -| Home settings: `Users//.AppData/ElastOS/Home` | When protection exists; browser preferences are separate | Person's data key | Key only / key only | +| 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 | +| Assistant conversations and drafts: `Users//.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//.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//.AppData/ElastOS/People`, `Users//.AppData/ElastOS/Profile` | Yes | Person's data key; Profile signing key inside the protected file | Profile identity and contacts present at export | +| Documents: `Users//Documents`; titles and file names in `ElastOS/Documents//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/`; 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//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//.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 and keys while Home is locked. +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); @@ -110,20 +112,16 @@ belongs to [locked Home protection (#210)](https://github.com/elastos/elastos-ru 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, your Recovery Kit, and your full bundle as secrets. The full -bundle offers optional password protection. Use hosted accounts only for public +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. -If the disk is lost, a Kit alone cannot restore files or histories. A full bundle -also restores its included Wallet keys and People identity/contacts; it leaves -out the other bytes listed above, including the Browser profile and model -credentials. Keep separate backups of those bytes. Neither export is a whole-Home -backup. [Backup and recovery (#567)](https://github.com/elastos/elastos-runtime/issues/567) +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) and [copies 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 copies. +working copies, revisions, heads, keys, and replicas. ## Open Findings diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index a44899918..451497063 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -49,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. @@ -302,13 +309,13 @@ 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, copy +## 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 copy is a revision kept elsewhere under the owner's +authorised reader open it. A replica is a revision kept elsewhere under the owner's storage policy. ## Service Offer diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 20c35eb7b..6175c0f2f 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -528,18 +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 full recovery bundle first for built-in Wallet keys and People -identity/contacts. A Recovery Kit alone restores the data key. +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. A Kit restores a data key; the full -bundle adds built-in Wallet keys and People identity/contacts. Both leave ordinary -files and histories for a separate backup. See the dated -[storage table](../SECURITY.md#stored-keys-and-recovery) for exact coverage. +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 @@ -554,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 diff --git a/docs/STORAGE_AND_ACCESS.md b/docs/STORAGE_AND_ACCESS.md index a65143f79..ffaf316d9 100644 --- a/docs/STORAGE_AND_ACCESS.md +++ b/docs/STORAGE_AND_ACCESS.md @@ -23,12 +23,13 @@ store that is still changing. This target model uses five building blocks: | Revision | A fixed save of the working copy, named by its CID. | | Head | A signed pointer that selects the current revision (the signed mutable head). | | Key | A secret that encrypts private data and lets an authorised reader open it. | -| Copy | A revision kept in another place under the owner's storage policy. | +| Replica | A revision kept in another place under the owner's storage policy. | The owner should choose where data stays and who can use it; Runtime should handle encryption, permission checks, and delivery. Protected sharing should grant specific uses, with separate permission for export or redistribution. Open publishing and permanent transfers should remain deliberate owner choices. +People should see familiar actions: Open, Share, Manage access, Export, and Restore. ## One object model, four responsibilities @@ -78,6 +79,7 @@ of data defines when to save a fixed revision: while it changes cannot produce that save. - A game supplies its save bytes at its own save boundary. - A conversation app saves drafts and message history at its declared boundaries. +- Builder work uses the same ownership, protection, revision, availability, and recovery rules. - A run journal saves ordered events and durable operation identities. The selected durable store should acknowledge a save only after it commits a @@ -88,7 +90,8 @@ remote retention are separate outcomes. State should stay separate from executable capsules, model packages, and service offers, so an update preserves the identity and permissions of the user's state. Narrow adapters should connect each file layout to the same protection, content, -and authority contracts. +and authority contracts. This common contract does not require one file layout +or a new storage service. Storage placement should be separate from execution placement. For a remote Browser Engine with local storage, the consumer's store should keep the current @@ -108,8 +111,8 @@ execution providers should separately need permission to use readable state. User history, provider settlement journals, and Runtime audit records should each have an owner, integrity rule, and bounded retention policy for secret redaction, -removed history, and pending copy cleanup. Log controls should grant only the -permitted rights. Acceptance must meet the release plan's required criteria and +removed history, and pending replica cleanup. Log controls should grant only the +permitted rights. Acceptance must meet the release plan's Required SA1-SA6 criteria and prove each payload's saves, restore, and failure handling. Game-save checks cover the shipped GBA surface; this contract adds no separate emulator product. @@ -144,10 +147,10 @@ Permission to use a model through an approved inference provider is separate from permission to export its weights. Marketplace licensing should add rights and payment evidence to this object journey. -## Copying storage and granting a copy are different actions +## Storage replicas and exports are different actions -Runtime should copy encrypted blocks for delivery, caching, backup, and repair -under the storage policy. These copies can retain the object's protection and +Runtime should replicate encrypted blocks for delivery, caching, backup, and repair +under the storage policy. These replicas can retain the object's protection and authority requirements. An independently usable export, redistribution to a new audience, or release of reusable decryption material is a separate action. diff --git a/scripts/storage-documentation.test.mjs b/scripts/storage-documentation.test.mjs index 53d9f01dd..f44435f40 100644 --- a/scripts/storage-documentation.test.mjs +++ b/scripts/storage-documentation.test.mjs @@ -6,9 +6,12 @@ const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), "utf const security = read("SECURITY.md"); const browser = read("elastos/crates/elastos-server/src/api/gateway_browser.rs"); -test("each Security storage row names path parts present in its storage source", () => { +// Path-name and source-descriptor checks only. These do not prove write-time +// encryption for every row, successful import, or installed behavior. +test("Security storage path parts occur in source literals (not a write or encryption check)", () => { const server = "elastos/crates/elastos-server/src/"; const sources = [ + ["Home recovery authority", "auth.rs"], ["Assistant conversations", "api/gateway_assistant_workspace_v2.rs"], ["Direct messages", "collaboration_direct_messages.rs"], ["Community history", "collaboration_core.rs"], @@ -56,7 +59,7 @@ function checkBrowserRow(document) { } assert.equal(encrypted, "No", "match the Browser encrypted flag"); assert.equal(key, "None", "the unencrypted Browser disk has no storage key"); - assert.equal(recovery, "Omitted / omitted", "match Browser recovery and bundle exclusion"); + assert.equal(recovery, "Omitted", "match Browser recovery exclusion"); assert.match(read("elastos/crates/elastos-server/src/api/auth_gateway.rs"), /BrowserProfiles are VM lifecycle artifacts[\s\S]*?Neither is a principal-root protected object/); } @@ -68,8 +71,49 @@ test("the storage check rejects false Browser path, encryption, and recovery cla for (const falseRow of [ row.replace("profile.ext4", "missing.ext4"), row.replace("| No |", "| Yes |"), - row.replace("Omitted / omitted", "Key only / key only"), + row.replace("Omitted", "Data key; files separate"), ]) { assert.throws(() => checkBrowserRow(security.replace(row, falseRow))); } }); + +function checkRecoveryCoverage(document) { + const table = document.split("| Data and storage path |", 2)[1].split("\n\n", 1)[0]; + assert.match(table, /\| Recovery Kit restores \|/); + for (const [name, coverage] of [ + ["Home recovery authority", "Home recovery authority and data key"], + ["Contacts and Profile", "Profile identity and contacts present at export"], + ["Built-in Wallet", "Built-in Wallet keys present at export"], + ]) { + const row = table.split("\n").find((line) => line.startsWith(`| ${name}`)); + assert.ok(row, `find the ${name} row`); + assert.equal(row.split("|")[4].trim(), coverage, `${name}: single-file export coverage`); + } +} + +test("Security Recovery Kit coverage matches System's single-file export and product name", () => { + const system = read("capsules/system/browser/system.js"); + const gateway = read("elastos/crates/elastos-server/src/api/gateway.rs"); + const auth = read("elastos/crates/elastos-server/src/api/auth_gateway.rs"); + assert.match(system, /setRecoveryButton\("Download Recovery Kit", false\)/); + assert.match(system, /fetchJson\("\/api\/auth\/recovery\/full-export"/); + for (const schema of ["elastos.full-recovery-bundle/v1", "elastos.full-recovery-bundle.package/v1"]) { + assert.ok(system.includes(`importedSchema === "${schema}"`), `System imports ${schema}`); + } + assert.deepEqual([...gateway.matchAll(/"\/api\/auth\/recovery\/([^"\n]+)"/g)].map((match) => match[1]), + ["status", "full-export", "full-import"]); + assert.match(auth, /"data_kit": kit,/); + assert.match(auth, /"wallet_recovery_keys": wallet_recovery_keys,/); + assert.match(auth, /\.insert\("people_identity"\.to_string\(\), people_identity\)/); + checkRecoveryCoverage(security); + for (const path of ["SECURITY.md", "docs/INSTALL.md", "docs/GLOSSARY.md", "docs/STORAGE_AND_ACCESS.md"]) { + assert.doesNotMatch(read(path), /full (?:recovery )?bundle/i, + `${path}: use System's Recovery Kit name for the recovery file`); + } +}); + +test("the recovery coverage check rejects the internal-record-only description", () => { + assert.throws(() => checkRecoveryCoverage(security.replace( + "Profile identity and contacts present at export", "Data key; files separate", + ))); +}); From 2abac4f8e0bb2270036555fbea38130c007c20f1 Mon Sep 17 00:00:00 2001 From: Anders Alm Date: Thu, 19 Nov 2026 13:38:39 -0500 Subject: [PATCH 3/4] docs: clarify recovery coverage and storage replicas Built-by: Codex --- SECURITY.md | 20 +++++++++++--------- docs/STORAGE_AND_ACCESS.md | 5 +++-- scripts/storage-documentation.test.mjs | 8 +++++++- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 19a4e5670..b38ce0a84 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -28,7 +28,7 @@ host developer mode and closed guest registration are required to enable it. An enabled Terminal runs commands with the host user's rights. Stored data has a separate boundary. [Stored keys and recovery](#stored-keys-and-recovery) -explains host access while Home is locked and what each recovery export contains. +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 @@ -71,8 +71,9 @@ Disk storage checked on 19 November 2026. Paths below are relative to the Home data folder; `` 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. Its recovery phrase -protects that key. Runtime keeps an internal recovery record, including the +Runtime creates a person's data key during Profile setup or Recovery Kit export +if the key is missing. 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 @@ -84,7 +85,7 @@ protect, in the same Home data folder; the person's data key is in the Auth arch | 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 | +| 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//.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//.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 | @@ -118,8 +119,9 @@ 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) -and [copies on your own devices (#498)](https://github.com/elastos/elastos-runtime/issues/498) +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. @@ -166,9 +168,9 @@ Over HTTP, an ordinary Home's raw CID routes (`/content/`, `/ipfs/`, 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, diff --git a/docs/STORAGE_AND_ACCESS.md b/docs/STORAGE_AND_ACCESS.md index ffaf316d9..8bc4ff48a 100644 --- a/docs/STORAGE_AND_ACCESS.md +++ b/docs/STORAGE_AND_ACCESS.md @@ -5,9 +5,10 @@ storage direction. Product support requires implementation and acceptance. For what is stored and protected today, read [Security: stored keys and recovery](../SECURITY.md#stored-keys-and-recovery). The gaps belong to [backup and recovery (#567)](https://github.com/elastos/elastos-runtime/issues/567), +[file backup (#603)](https://github.com/elastos/elastos-runtime/issues/603), [key custody (#210)](https://github.com/elastos/elastos-runtime/issues/210), [host protection (#209)](https://github.com/elastos/elastos-runtime/issues/209), -[copies on your own devices (#498)](https://github.com/elastos/elastos-runtime/issues/498), +[replicas on your own devices (#498)](https://github.com/elastos/elastos-runtime/issues/498), and [isolation (#173)](https://github.com/elastos/elastos-runtime/issues/173). ## Two kinds of data @@ -181,7 +182,7 @@ require protection against host tampering need a supported execution boundary and evidence for it. The recipient can choose a compatible environment; a provider's unsupported claim is insufficient to satisfy the policy. -Runtime should prevent unauthorised copies inside the enforced boundary. The +Runtime should prevent unauthorised replicas inside the enforced boundary. The limit is information that has already escaped that boundary or was deliberately exported. Removing a grant cannot recover such information, including external recordings. Ordinary export paths still require full permission enforcement. diff --git a/scripts/storage-documentation.test.mjs b/scripts/storage-documentation.test.mjs index f44435f40..a0d83e2d4 100644 --- a/scripts/storage-documentation.test.mjs +++ b/scripts/storage-documentation.test.mjs @@ -87,7 +87,13 @@ function checkRecoveryCoverage(document) { ]) { const row = table.split("\n").find((line) => line.startsWith(`| ${name}`)); assert.ok(row, `find the ${name} row`); - assert.equal(row.split("|")[4].trim(), coverage, `${name}: single-file export coverage`); + const actual = row.split("|")[4].trim(); + if (name === "Home recovery authority") { + assert.ok(actual.includes(coverage), `${name}: single-file export coverage`); + assert.match(actual, /\bnot passkeys or sessions\b/i, "exclude sign-in state from recovery"); + } else { + assert.equal(actual, coverage, `${name}: single-file export coverage`); + } } } From ce19e3546d0db12585bfb8fc8c5fa1f3a4fbb123 Mon Sep 17 00:00:00 2001 From: Anders Alm Date: Thu, 19 Nov 2026 13:42:06 -0500 Subject: [PATCH 4/4] docs: restore copies wording and clarify recovery key creation Built-by: Codex --- SECURITY.md | 4 ++-- docs/STORAGE_AND_ACCESS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b38ce0a84..ca8234fed 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -71,8 +71,8 @@ Disk storage checked on 19 November 2026. Paths below are relative to the Home data folder; `` 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 Recovery Kit export -if the key is missing. The person's recovery phrase protects that key. +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, diff --git a/docs/STORAGE_AND_ACCESS.md b/docs/STORAGE_AND_ACCESS.md index 8bc4ff48a..520afb3bb 100644 --- a/docs/STORAGE_AND_ACCESS.md +++ b/docs/STORAGE_AND_ACCESS.md @@ -182,7 +182,7 @@ require protection against host tampering need a supported execution boundary and evidence for it. The recipient can choose a compatible environment; a provider's unsupported claim is insufficient to satisfy the policy. -Runtime should prevent unauthorised replicas inside the enforced boundary. The +Runtime should prevent unauthorised copies inside the enforced boundary. The limit is information that has already escaped that boundary or was deliberately exported. Removing a grant cannot recover such information, including external recordings. Ordinary export paths still require full permission enforcement.